diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 4b2433ea4..a27d3f5ef 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -11,10 +11,10 @@ cache:
- _ccache/
variables:
- FEDORA_IMAGE: "registry.gitlab.gnome.org/gnome/glib/fedora:v20"
+ FEDORA_IMAGE: "registry.gitlab.gnome.org/gnome/glib/fedora:v21"
COVERITY_IMAGE: "registry.gitlab.gnome.org/gnome/glib/coverity:v7"
- DEBIAN_IMAGE: "registry.gitlab.gnome.org/gnome/glib/debian-stable:v14"
- MINGW_IMAGE: "registry.gitlab.gnome.org/gnome/glib/mingw:v10"
+ DEBIAN_IMAGE: "registry.gitlab.gnome.org/gnome/glib/debian-stable:v15"
+ MINGW_IMAGE: "registry.gitlab.gnome.org/gnome/glib/mingw:v11"
MESON_TEST_TIMEOUT_MULTIPLIER: 4
G_MESSAGES_DEBUG: all
MESON_COMMON_OPTIONS: "--buildtype debug --wrap-mode=nodownload --fatal-meson-warnings"
diff --git a/.gitlab-ci/debian-stable.Dockerfile b/.gitlab-ci/debian-stable.Dockerfile
index a3a0e75b2..e6a2c7188 100644
--- a/.gitlab-ci/debian-stable.Dockerfile
+++ b/.gitlab-ci/debian-stable.Dockerfile
@@ -16,6 +16,7 @@ RUN apt-get update -qq && apt-get install --no-install-recommends -qq -y \
gdb \
g++ \
gettext \
+ gi-docgen \
git \
libc6-dev \
gtk-doc-tools \
diff --git a/.gitlab-ci/fedora.Dockerfile b/.gitlab-ci/fedora.Dockerfile
index d6d6da7ce..e95ef6859 100644
--- a/.gitlab-ci/fedora.Dockerfile
+++ b/.gitlab-ci/fedora.Dockerfile
@@ -15,6 +15,7 @@ RUN dnf -y update \
gcc-c++ \
gdb \
gettext \
+ gi-docgen \
git \
glibc-devel \
glibc-headers \
diff --git a/docs/reference/gio/Gio-2.0.gir b/docs/reference/gio/Gio-2.0.gir
new file mode 100644
index 000000000..8f8bd17af
--- /dev/null
+++ b/docs/reference/gio/Gio-2.0.gir
@@ -0,0 +1,136814 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #GAction represents a single named action.
+
+The main interface to an action is that it can be activated with
+g_action_activate(). This results in the 'activate' signal being
+emitted. An activation has a #GVariant parameter (which may be
+%NULL). The correct type for the parameter is determined by a static
+parameter type (which is given at construction time).
+
+An action may optionally have a state, in which case the state may be
+set with g_action_change_state(). This call takes a #GVariant. The
+correct type for the state is determined by a static state type
+(which is given at construction time).
+
+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.
+
+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 is responsible for filtering
+calls to g_action_activate() and g_action_change_state() for type
+safety and for the state being enabled.
+
+Probably the only useful thing to do with a #GAction is to put it
+inside of a #GSimpleActionGroup.
+
+
+ Checks if @action_name is valid.
+
+@action_name is valid if it consists only of alphanumeric characters,
+plus '-' and '.'. The empty string is not a valid action name.
+
+It is an error to call this function with a non-utf8 @action_name.
+@action_name must not be %NULL.
+
+
+ %TRUE if @action_name is valid
+
+
+
+
+ a potential action name
+
+
+
+
+
+ Parses a detailed action name into its separate name and target
+components.
+
+Detailed action names can have three formats.
+
+The first format is used to represent an action name with no target
+value and consists of just an action name containing no whitespace
+nor the characters `:`, `(` or `)`. For example: `app.action`.
+
+The second format is used to represent an action with a target value
+that is a non-empty string consisting only of alphanumerics, plus `-`
+and `.`. In that case, the action name and target value are
+separated by a double colon (`::`). For example:
+`app.action::target`.
+
+The third format is used to represent an action with any type of
+target value, including strings. The target value follows the action
+name, surrounded in parens. For example: `app.action(42)`. The
+target value is parsed using g_variant_parse(). If a tuple-typed
+value is desired, it must be specified in the same way, resulting in
+two sets of parens, for example: `app.action((1,2,3))`. A string
+target can be specified this way as well: `app.action('target')`.
+For strings, this third format must be used if target value is
+empty or contains characters other than alphanumerics, `-` and `.`.
+
+If this function returns %TRUE, a non-%NULL value is guaranteed to be returned
+in @action_name (if a pointer is passed in). A %NULL value may still be
+returned in @target_value, as the @detailed_name may not contain a target.
+
+If returned, the #GVariant in @target_value is guaranteed to not be floating.
+
+
+ %TRUE if successful, else %FALSE with @error set
+
+
+
+
+ a detailed action name
+
+
+
+ the action name
+
+
+
+ the target value,
+ or %NULL for no target
+
+
+
+
+
+ Formats a detailed action name from @action_name and @target_value.
+
+It is an error to call this function with an invalid action name.
+
+This function is the opposite of g_action_parse_detailed_name().
+It will produce a string that can be parsed back to the @action_name
+and @target_value by that function.
+
+See that function for the types of strings that will be printed by
+this function.
+
+
+ a detailed format string
+
+
+
+
+ a valid action name
+
+
+
+ a #GVariant target value, or %NULL
+
+
+
+
+
+ Activates the action.
+
+@parameter must be the correct type of parameter for the action (ie:
+the parameter type given at construction time). If the parameter
+type was %NULL then @parameter must also be %NULL.
+
+If the @parameter GVariant is floating, it is consumed.
+
+
+
+
+
+
+ a #GAction
+
+
+
+ the parameter to the activation
+
+
+
+
+
+ Request for the state of @action to be changed to @value.
+
+The action must be stateful and @value must be of the correct type.
+See g_action_get_state_type().
+
+This call merely requests a change. The action may refuse to change
+its state or may change its state to something other than @value.
+See g_action_get_state_hint().
+
+If the @value GVariant is floating, it is consumed.
+
+
+
+
+
+
+ a #GAction
+
+
+
+ the new state
+
+
+
+
+
+ Checks if @action is currently enabled.
+
+An action must be enabled in order to be activated or in order to
+have its state changed from outside callers.
+
+
+ whether the action is enabled
+
+
+
+
+ a #GAction
+
+
+
+
+
+ Queries the name of @action.
+
+
+ the name of the action
+
+
+
+
+ a #GAction
+
+
+
+
+
+ Queries the type of the parameter that must be given when activating
+@action.
+
+When activating the action using g_action_activate(), the #GVariant
+given to that function must be of the type returned by this function.
+
+In the case that this function returns %NULL, you must not give any
+#GVariant, but %NULL instead.
+
+
+ the parameter type
+
+
+
+
+ a #GAction
+
+
+
+
+
+ Queries the current state of @action.
+
+If the action is not stateful then %NULL will be returned. If the
+action is stateful then the type of the return value is the type
+given by g_action_get_state_type().
+
+The return value (if non-%NULL) should be freed with
+g_variant_unref() when it is no longer required.
+
+
+ the current state of the action
+
+
+
+
+ a #GAction
+
+
+
+
+
+ Requests a hint about the valid range of values for the state of
+@action.
+
+If %NULL is returned it either means that the action is not stateful
+or that there is no hint about the valid range of values for the
+state of the action.
+
+If a #GVariant array is returned then each item in the array is a
+possible value for the state. If a #GVariant pair (ie: two-tuple) is
+returned then the tuple specifies the inclusive lower and upper bound
+of valid values for the state.
+
+In any case, the information is merely a hint. It may be possible to
+have a state value outside of the hinted range and setting a value
+within the range may fail.
+
+The return value (if non-%NULL) should be freed with
+g_variant_unref() when it is no longer required.
+
+
+ the state range hint
+
+
+
+
+ a #GAction
+
+
+
+
+
+ Queries the type of the state of @action.
+
+If the action is stateful (e.g. created with
+g_simple_action_new_stateful()) then this function returns the
+#GVariantType of the state. This is the type of the initial value
+given as the state. All calls to g_action_change_state() must give a
+#GVariant of this type and g_action_get_state() will return a
+#GVariant of the same type.
+
+If the action is not stateful (e.g. created with g_simple_action_new())
+then this function will return %NULL. In that case, g_action_get_state()
+will return %NULL and you must not call g_action_change_state().
+
+
+ the state type, if the action is stateful
+
+
+
+
+ a #GAction
+
+
+
+
+
+ Activates the action.
+
+@parameter must be the correct type of parameter for the action (ie:
+the parameter type given at construction time). If the parameter
+type was %NULL then @parameter must also be %NULL.
+
+If the @parameter GVariant is floating, it is consumed.
+
+
+
+
+
+
+ a #GAction
+
+
+
+ the parameter to the activation
+
+
+
+
+
+ Request for the state of @action to be changed to @value.
+
+The action must be stateful and @value must be of the correct type.
+See g_action_get_state_type().
+
+This call merely requests a change. The action may refuse to change
+its state or may change its state to something other than @value.
+See g_action_get_state_hint().
+
+If the @value GVariant is floating, it is consumed.
+
+
+
+
+
+
+ a #GAction
+
+
+
+ the new state
+
+
+
+
+
+ Checks if @action is currently enabled.
+
+An action must be enabled in order to be activated or in order to
+have its state changed from outside callers.
+
+
+ whether the action is enabled
+
+
+
+
+ a #GAction
+
+
+
+
+
+ Queries the name of @action.
+
+
+ the name of the action
+
+
+
+
+ a #GAction
+
+
+
+
+
+ Queries the type of the parameter that must be given when activating
+@action.
+
+When activating the action using g_action_activate(), the #GVariant
+given to that function must be of the type returned by this function.
+
+In the case that this function returns %NULL, you must not give any
+#GVariant, but %NULL instead.
+
+
+ the parameter type
+
+
+
+
+ a #GAction
+
+
+
+
+
+ Queries the current state of @action.
+
+If the action is not stateful then %NULL will be returned. If the
+action is stateful then the type of the return value is the type
+given by g_action_get_state_type().
+
+The return value (if non-%NULL) should be freed with
+g_variant_unref() when it is no longer required.
+
+
+ the current state of the action
+
+
+
+
+ a #GAction
+
+
+
+
+
+ Requests a hint about the valid range of values for the state of
+@action.
+
+If %NULL is returned it either means that the action is not stateful
+or that there is no hint about the valid range of values for the
+state of the action.
+
+If a #GVariant array is returned then each item in the array is a
+possible value for the state. If a #GVariant pair (ie: two-tuple) is
+returned then the tuple specifies the inclusive lower and upper bound
+of valid values for the state.
+
+In any case, the information is merely a hint. It may be possible to
+have a state value outside of the hinted range and setting a value
+within the range may fail.
+
+The return value (if non-%NULL) should be freed with
+g_variant_unref() when it is no longer required.
+
+
+ the state range hint
+
+
+
+
+ a #GAction
+
+
+
+
+
+ Queries the type of the state of @action.
+
+If the action is stateful (e.g. created with
+g_simple_action_new_stateful()) then this function returns the
+#GVariantType of the state. This is the type of the initial value
+given as the state. All calls to g_action_change_state() must give a
+#GVariant of this type and g_action_get_state() will return a
+#GVariant of the same type.
+
+If the action is not stateful (e.g. created with g_simple_action_new())
+then this function will return %NULL. In that case, g_action_get_state()
+will return %NULL and you must not call g_action_change_state().
+
+
+ the state type, if the action is stateful
+
+
+
+
+ a #GAction
+
+
+
+
+
+ If @action is currently enabled.
+
+If the action is disabled then calls to g_action_activate() and
+g_action_change_state() have no effect.
+
+
+
+ The name of the action. This is mostly meaningful for identifying
+the action once it has been added to a #GActionGroup. It is immutable.
+
+
+
+ The type of the parameter that must be given when activating the
+action. This is immutable, and may be %NULL if no parameter is needed when
+activating the action.
+
+
+
+ The state of the action, or %NULL if the action is stateless.
+
+
+
+ The #GVariantType of the state that the action has, or %NULL if the
+action is stateless. This is immutable.
+
+
+
+
+ This struct defines a single action. It is for use with
+g_action_map_add_action_entries().
+
+The order of the items in the structure are intended to reflect
+frequency of use. It is permissible to use an incomplete initialiser
+in order to leave some of the later values as %NULL. All values
+after @name are optional. Additional optional fields may be added in
+the future.
+
+See g_action_map_add_action_entries() for an example.
+
+
+ the name of the action
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ the type of the parameter that must be passed to the
+ activate function for this action, given as a single
+ GVariant type string (or %NULL for no parameter)
+
+
+
+ the initial state for this action, given in
+ [GVariant text format][gvariant-text]. The state is parsed
+ with no extra type information, so type tags must be added to
+ the string if they are necessary. Stateless actions should
+ give %NULL here.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #GActionGroup represents a group of actions. Actions can be used to
+expose functionality in a structured way, either from one part of a
+program to another, or to the outside world. Action groups are often
+used together with a #GMenuModel that provides additional
+representation data for displaying the actions to the user, e.g. in
+a menu.
+
+The main way to interact with the actions in a GActionGroup is to
+activate them with g_action_group_activate_action(). Activating an
+action may require a #GVariant parameter. The required type of the
+parameter can be inquired with g_action_group_get_action_parameter_type().
+Actions may be disabled, see g_action_group_get_action_enabled().
+Activating a disabled action has no effect.
+
+Actions may optionally have a state in the form of a #GVariant. The
+current state of an action can be inquired with
+g_action_group_get_action_state(). Activating a stateful action may
+change its state, but it is also possible to set the state by calling
+g_action_group_change_action_state().
+
+As typical example, consider a text editing application which has an
+option to change the current font to 'bold'. A good way to represent
+this would be a stateful action, with a boolean state. Activating the
+action would toggle the state.
+
+Each action in the group has a unique name (which is a string). All
+method calls, except g_action_group_list_actions() take the name of
+an action as an argument.
+
+The #GActionGroup API is meant to be the 'public' API to the action
+group. The calls here are exactly the interaction that 'external
+forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have
+with actions. 'Internal' APIs (ie: ones meant only to be accessed by
+the action group implementation) are found on subclasses. This is
+why you will find - for example - g_action_group_get_action_enabled()
+but not an equivalent set() call.
+
+Signals are emitted on the action group in response to state changes
+on individual actions.
+
+Implementations of #GActionGroup should provide implementations for
+the virtual functions g_action_group_list_actions() and
+g_action_group_query_action(). The other virtual functions should
+not be implemented - their "wrappers" are actually implemented with
+calls to g_action_group_query_action().
+
+
+ Emits the #GActionGroup::action-added signal on @action_group.
+
+This function should only be called by #GActionGroup implementations.
+
+
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of an action in the group
+
+
+
+
+
+ Emits the #GActionGroup::action-enabled-changed signal on @action_group.
+
+This function should only be called by #GActionGroup implementations.
+
+
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of an action in the group
+
+
+
+ whether or not the action is now enabled
+
+
+
+
+
+ Emits the #GActionGroup::action-removed signal on @action_group.
+
+This function should only be called by #GActionGroup implementations.
+
+
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of an action in the group
+
+
+
+
+
+ Emits the #GActionGroup::action-state-changed signal on @action_group.
+
+This function should only be called by #GActionGroup implementations.
+
+
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of an action in the group
+
+
+
+ the new state of the named action
+
+
+
+
+
+ Activate the named action within @action_group.
+
+If the action is expecting a parameter, then the correct type of
+parameter must be given as @parameter. If the action is expecting no
+parameters then @parameter must be %NULL. See
+g_action_group_get_action_parameter_type().
+
+If the #GActionGroup implementation supports asynchronous remote
+activation over D-Bus, this call may return before the relevant
+D-Bus traffic has been sent, or any replies have been received. In
+order to block on such asynchronous activation calls,
+g_dbus_connection_flush() should be called prior to the code, which
+depends on the result of the action activation. Without flushing
+the D-Bus connection, there is no guarantee that the action would
+have been activated.
+
+The following code which runs in a remote app instance, shows an
+example of a "quit" action being activated on the primary app
+instance over D-Bus. Here g_dbus_connection_flush() is called
+before `exit()`. Without g_dbus_connection_flush(), the "quit" action
+may fail to be activated on the primary instance.
+
+|[<!-- language="C" -->
+// call "quit" action on primary instance
+g_action_group_activate_action (G_ACTION_GROUP (app), "quit", NULL);
+
+// make sure the action is activated now
+g_dbus_connection_flush (...);
+
+g_debug ("application has been terminated. exiting.");
+
+exit (0);
+]|
+
+
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of the action to activate
+
+
+
+ parameters to the activation
+
+
+
+
+
+ Request for the state of the named action within @action_group to be
+changed to @value.
+
+The action must be stateful and @value must be of the correct type.
+See g_action_group_get_action_state_type().
+
+This call merely requests a change. The action may refuse to change
+its state or may change its state to something other than @value.
+See g_action_group_get_action_state_hint().
+
+If the @value GVariant is floating, it is consumed.
+
+
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of the action to request the change on
+
+
+
+ the new state
+
+
+
+
+
+ Checks if the named action within @action_group is currently enabled.
+
+An action must be enabled in order to be activated or in order to
+have its state changed from outside callers.
+
+
+ whether or not the action is currently enabled
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of the action to query
+
+
+
+
+
+ Queries the type of the parameter that must be given when activating
+the named action within @action_group.
+
+When activating the action using g_action_group_activate_action(),
+the #GVariant given to that function must be of the type returned
+by this function.
+
+In the case that this function returns %NULL, you must not give any
+#GVariant, but %NULL instead.
+
+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.
+
+
+ the parameter type
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of the action to query
+
+
+
+
+
+ Queries the current state of the named action within @action_group.
+
+If the action is not stateful then %NULL will be returned. If the
+action is stateful then the type of the return value is the type
+given by g_action_group_get_action_state_type().
+
+The return value (if non-%NULL) should be freed with
+g_variant_unref() when it is no longer required.
+
+
+ the current state of the action
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of the action to query
+
+
+
+
+
+ Requests a hint about the valid range of values for the state of the
+named action within @action_group.
+
+If %NULL is returned it either means that the action is not stateful
+or that there is no hint about the valid range of values for the
+state of the action.
+
+If a #GVariant array is returned then each item in the array is a
+possible value for the state. If a #GVariant pair (ie: two-tuple) is
+returned then the tuple specifies the inclusive lower and upper bound
+of valid values for the state.
+
+In any case, the information is merely a hint. It may be possible to
+have a state value outside of the hinted range and setting a value
+within the range may fail.
+
+The return value (if non-%NULL) should be freed with
+g_variant_unref() when it is no longer required.
+
+
+ the state range hint
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of the action to query
+
+
+
+
+
+ Queries the type of the state of the named action within
+@action_group.
+
+If the action is stateful then this function returns the
+#GVariantType of the state. All calls to
+g_action_group_change_action_state() must give a #GVariant of this
+type and g_action_group_get_action_state() will return a #GVariant
+of the same type.
+
+If the action is not stateful then this function will return %NULL.
+In that case, g_action_group_get_action_state() will return %NULL
+and you must not call g_action_group_change_action_state().
+
+The state type of a particular action will never change but it is
+possible for an action to be removed and for a new action to be added
+with the same name but a different state type.
+
+
+ the state type, if the action is stateful
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of the action to query
+
+
+
+
+
+ Checks if the named action exists within @action_group.
+
+
+ whether the named action exists
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of the action to check for
+
+
+
+
+
+ Lists the actions contained within @action_group.
+
+The caller is responsible for freeing the list with g_strfreev() when
+it is no longer required.
+
+
+ a %NULL-terminated array of the names of the
+actions in the group
+
+
+
+
+
+
+ a #GActionGroup
+
+
+
+
+
+ Queries all aspects of the named action within an @action_group.
+
+This function acquires the information available from
+g_action_group_has_action(), g_action_group_get_action_enabled(),
+g_action_group_get_action_parameter_type(),
+g_action_group_get_action_state_type(),
+g_action_group_get_action_state_hint() and
+g_action_group_get_action_state() with a single function call.
+
+This provides two main benefits.
+
+The first is the improvement in efficiency that comes with not having
+to perform repeated lookups of the action in order to discover
+different things about it. The second is that implementing
+#GActionGroup can now be done by only overriding this one virtual
+function.
+
+The interface provides a default implementation of this function that
+calls the individual functions, as required, to fetch the
+information. The interface also provides default implementations of
+those functions that call this function. All implementations,
+therefore, must override either this function or all of the others.
+
+If the action exists, %TRUE is returned and any of the requested
+fields (as indicated by having a non-%NULL reference passed in) are
+filled. If the action doesn't exist, %FALSE is returned and the
+fields may or may not have been modified.
+
+
+ %TRUE if the action exists, else %FALSE
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of an action in the group
+
+
+
+ if the action is presently enabled
+
+
+
+ the parameter type, or %NULL if none needed
+
+
+
+ the state type, or %NULL if stateless
+
+
+
+ the state hint, or %NULL if none
+
+
+
+ the current state, or %NULL if stateless
+
+
+
+
+
+ Emits the #GActionGroup::action-added signal on @action_group.
+
+This function should only be called by #GActionGroup implementations.
+
+
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of an action in the group
+
+
+
+
+
+ Emits the #GActionGroup::action-enabled-changed signal on @action_group.
+
+This function should only be called by #GActionGroup implementations.
+
+
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of an action in the group
+
+
+
+ whether or not the action is now enabled
+
+
+
+
+
+ Emits the #GActionGroup::action-removed signal on @action_group.
+
+This function should only be called by #GActionGroup implementations.
+
+
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of an action in the group
+
+
+
+
+
+ Emits the #GActionGroup::action-state-changed signal on @action_group.
+
+This function should only be called by #GActionGroup implementations.
+
+
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of an action in the group
+
+
+
+ the new state of the named action
+
+
+
+
+
+ Activate the named action within @action_group.
+
+If the action is expecting a parameter, then the correct type of
+parameter must be given as @parameter. If the action is expecting no
+parameters then @parameter must be %NULL. See
+g_action_group_get_action_parameter_type().
+
+If the #GActionGroup implementation supports asynchronous remote
+activation over D-Bus, this call may return before the relevant
+D-Bus traffic has been sent, or any replies have been received. In
+order to block on such asynchronous activation calls,
+g_dbus_connection_flush() should be called prior to the code, which
+depends on the result of the action activation. Without flushing
+the D-Bus connection, there is no guarantee that the action would
+have been activated.
+
+The following code which runs in a remote app instance, shows an
+example of a "quit" action being activated on the primary app
+instance over D-Bus. Here g_dbus_connection_flush() is called
+before `exit()`. Without g_dbus_connection_flush(), the "quit" action
+may fail to be activated on the primary instance.
+
+|[<!-- language="C" -->
+// call "quit" action on primary instance
+g_action_group_activate_action (G_ACTION_GROUP (app), "quit", NULL);
+
+// make sure the action is activated now
+g_dbus_connection_flush (...);
+
+g_debug ("application has been terminated. exiting.");
+
+exit (0);
+]|
+
+
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of the action to activate
+
+
+
+ parameters to the activation
+
+
+
+
+
+ Request for the state of the named action within @action_group to be
+changed to @value.
+
+The action must be stateful and @value must be of the correct type.
+See g_action_group_get_action_state_type().
+
+This call merely requests a change. The action may refuse to change
+its state or may change its state to something other than @value.
+See g_action_group_get_action_state_hint().
+
+If the @value GVariant is floating, it is consumed.
+
+
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of the action to request the change on
+
+
+
+ the new state
+
+
+
+
+
+ Checks if the named action within @action_group is currently enabled.
+
+An action must be enabled in order to be activated or in order to
+have its state changed from outside callers.
+
+
+ whether or not the action is currently enabled
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of the action to query
+
+
+
+
+
+ Queries the type of the parameter that must be given when activating
+the named action within @action_group.
+
+When activating the action using g_action_group_activate_action(),
+the #GVariant given to that function must be of the type returned
+by this function.
+
+In the case that this function returns %NULL, you must not give any
+#GVariant, but %NULL instead.
+
+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.
+
+
+ the parameter type
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of the action to query
+
+
+
+
+
+ Queries the current state of the named action within @action_group.
+
+If the action is not stateful then %NULL will be returned. If the
+action is stateful then the type of the return value is the type
+given by g_action_group_get_action_state_type().
+
+The return value (if non-%NULL) should be freed with
+g_variant_unref() when it is no longer required.
+
+
+ the current state of the action
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of the action to query
+
+
+
+
+
+ Requests a hint about the valid range of values for the state of the
+named action within @action_group.
+
+If %NULL is returned it either means that the action is not stateful
+or that there is no hint about the valid range of values for the
+state of the action.
+
+If a #GVariant array is returned then each item in the array is a
+possible value for the state. If a #GVariant pair (ie: two-tuple) is
+returned then the tuple specifies the inclusive lower and upper bound
+of valid values for the state.
+
+In any case, the information is merely a hint. It may be possible to
+have a state value outside of the hinted range and setting a value
+within the range may fail.
+
+The return value (if non-%NULL) should be freed with
+g_variant_unref() when it is no longer required.
+
+
+ the state range hint
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of the action to query
+
+
+
+
+
+ Queries the type of the state of the named action within
+@action_group.
+
+If the action is stateful then this function returns the
+#GVariantType of the state. All calls to
+g_action_group_change_action_state() must give a #GVariant of this
+type and g_action_group_get_action_state() will return a #GVariant
+of the same type.
+
+If the action is not stateful then this function will return %NULL.
+In that case, g_action_group_get_action_state() will return %NULL
+and you must not call g_action_group_change_action_state().
+
+The state type of a particular action will never change but it is
+possible for an action to be removed and for a new action to be added
+with the same name but a different state type.
+
+
+ the state type, if the action is stateful
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of the action to query
+
+
+
+
+
+ Checks if the named action exists within @action_group.
+
+
+ whether the named action exists
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of the action to check for
+
+
+
+
+
+ Lists the actions contained within @action_group.
+
+The caller is responsible for freeing the list with g_strfreev() when
+it is no longer required.
+
+
+ a %NULL-terminated array of the names of the
+actions in the group
+
+
+
+
+
+
+ a #GActionGroup
+
+
+
+
+
+ Queries all aspects of the named action within an @action_group.
+
+This function acquires the information available from
+g_action_group_has_action(), g_action_group_get_action_enabled(),
+g_action_group_get_action_parameter_type(),
+g_action_group_get_action_state_type(),
+g_action_group_get_action_state_hint() and
+g_action_group_get_action_state() with a single function call.
+
+This provides two main benefits.
+
+The first is the improvement in efficiency that comes with not having
+to perform repeated lookups of the action in order to discover
+different things about it. The second is that implementing
+#GActionGroup can now be done by only overriding this one virtual
+function.
+
+The interface provides a default implementation of this function that
+calls the individual functions, as required, to fetch the
+information. The interface also provides default implementations of
+those functions that call this function. All implementations,
+therefore, must override either this function or all of the others.
+
+If the action exists, %TRUE is returned and any of the requested
+fields (as indicated by having a non-%NULL reference passed in) are
+filled. If the action doesn't exist, %FALSE is returned and the
+fields may or may not have been modified.
+
+
+ %TRUE if the action exists, else %FALSE
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of an action in the group
+
+
+
+ if the action is presently enabled
+
+
+
+ the parameter type, or %NULL if none needed
+
+
+
+ the state type, or %NULL if stateless
+
+
+
+ the state hint, or %NULL if none
+
+
+
+ the current state, or %NULL if stateless
+
+
+
+
+
+ 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.
+
+
+
+
+
+ the name of the action in @action_group
+
+
+
+
+
+ Signals that the enabled status of the named action has changed.
+
+
+
+
+
+ the name of the action in @action_group
+
+
+
+ whether the action is enabled or not
+
+
+
+
+
+ Signals that an action is just about to be removed from the group.
+This signal is emitted before the action is removed, so the action
+is still visible and can be queried from the signal handler.
+
+
+
+
+
+ the name of the action in @action_group
+
+
+
+
+
+ Signals that the state of the named action has changed.
+
+
+
+
+
+ the name of the action in @action_group
+
+
+
+ the new value of the state
+
+
+
+
+
+
+ The virtual function table for #GActionGroup.
+
+
+
+
+
+
+
+
+ whether the named action exists
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of the action to check for
+
+
+
+
+
+
+
+
+
+ a %NULL-terminated array of the names of the
+actions in the group
+
+
+
+
+
+
+ a #GActionGroup
+
+
+
+
+
+
+
+
+
+ whether or not the action is currently enabled
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of the action to query
+
+
+
+
+
+
+
+
+
+ the parameter type
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of the action to query
+
+
+
+
+
+
+
+
+
+ the state type, if the action is stateful
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of the action to query
+
+
+
+
+
+
+
+
+
+ the state range hint
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of the action to query
+
+
+
+
+
+
+
+
+
+ the current state of the action
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of the action to query
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of the action to request the change on
+
+
+
+ the new state
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of the action to activate
+
+
+
+ parameters to the activation
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of an action in the group
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of an action in the group
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of an action in the group
+
+
+
+ whether or not the action is now enabled
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of an action in the group
+
+
+
+ the new state of the named action
+
+
+
+
+
+
+
+
+
+ %TRUE if the action exists, else %FALSE
+
+
+
+
+ a #GActionGroup
+
+
+
+ the name of an action in the group
+
+
+
+ if the action is presently enabled
+
+
+
+ the parameter type, or %NULL if none needed
+
+
+
+ the state type, or %NULL if stateless
+
+
+
+ the state hint, or %NULL if none
+
+
+
+ the current state, or %NULL if stateless
+
+
+
+
+
+
+
+ The virtual function table for #GAction.
+
+
+
+
+
+
+
+
+ the name of the action
+
+
+
+
+ a #GAction
+
+
+
+
+
+
+
+
+
+ the parameter type
+
+
+
+
+ a #GAction
+
+
+
+
+
+
+
+
+
+ the state type, if the action is stateful
+
+
+
+
+ a #GAction
+
+
+
+
+
+
+
+
+
+ the state range hint
+
+
+
+
+ a #GAction
+
+
+
+
+
+
+
+
+
+ whether the action is enabled
+
+
+
+
+ a #GAction
+
+
+
+
+
+
+
+
+
+ the current state of the action
+
+
+
+
+ a #GAction
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GAction
+
+
+
+ the new state
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GAction
+
+
+
+ the parameter to the activation
+
+
+
+
+
+
+
+ The GActionMap interface is implemented by #GActionGroup
+implementations that operate by containing a number of
+named #GAction instances, such as #GSimpleActionGroup.
+
+One useful application of this interface is to map the
+names of actions from various action groups to unique,
+prefixed names (e.g. by prepending "app." or "win.").
+This is the motivation for the 'Map' part of the interface
+name.
+
+
+ Adds an action to the @action_map.
+
+If the action map already contains an action with the same name
+as @action then the old action is dropped from the action map.
+
+The action map takes its own reference on @action.
+
+
+
+
+
+
+ a #GActionMap
+
+
+
+ a #GAction
+
+
+
+
+
+ Looks up the action with the name @action_name in @action_map.
+
+If no such action exists, returns %NULL.
+
+
+ a #GAction, or %NULL
+
+
+
+
+ a #GActionMap
+
+
+
+ the name of an action
+
+
+
+
+
+ Removes the named action from the action map.
+
+If no action of this name is in the map then nothing happens.
+
+
+
+
+
+
+ a #GActionMap
+
+
+
+ the name of the action
+
+
+
+
+
+ Adds an action to the @action_map.
+
+If the action map already contains an action with the same name
+as @action then the old action is dropped from the action map.
+
+The action map takes its own reference on @action.
+
+
+
+
+
+
+ a #GActionMap
+
+
+
+ a #GAction
+
+
+
+
+
+ A convenience function for creating multiple #GSimpleAction instances
+and adding them to a #GActionMap.
+
+Each action is constructed as per one #GActionEntry.
+
+|[<!-- language="C" -->
+static void
+activate_quit (GSimpleAction *simple,
+ GVariant *parameter,
+ gpointer user_data)
+{
+ exit (0);
+}
+
+static void
+activate_print_string (GSimpleAction *simple,
+ GVariant *parameter,
+ gpointer user_data)
+{
+ g_print ("%s\n", g_variant_get_string (parameter, NULL));
+}
+
+static GActionGroup *
+create_action_group (void)
+{
+ const GActionEntry entries[] = {
+ { "quit", activate_quit },
+ { "print-string", activate_print_string, "s" }
+ };
+ GSimpleActionGroup *group;
+
+ group = g_simple_action_group_new ();
+ g_action_map_add_action_entries (G_ACTION_MAP (group), entries, G_N_ELEMENTS (entries), NULL);
+
+ return G_ACTION_GROUP (group);
+}
+]|
+
+
+
+
+
+
+ a #GActionMap
+
+
+
+ a pointer to
+ the first item in an array of #GActionEntry structs
+
+
+
+
+
+ the length of @entries, or -1 if @entries is %NULL-terminated
+
+
+
+ the user data for signal connections
+
+
+
+
+
+ Looks up the action with the name @action_name in @action_map.
+
+If no such action exists, returns %NULL.
+
+
+ a #GAction, or %NULL
+
+
+
+
+ a #GActionMap
+
+
+
+ the name of an action
+
+
+
+
+
+ Removes the named action from the action map.
+
+If no action of this name is in the map then nothing happens.
+
+
+
+
+
+
+ a #GActionMap
+
+
+
+ the name of the action
+
+
+
+
+
+
+ The virtual function table for #GActionMap.
+
+
+
+
+
+
+
+
+ a #GAction, or %NULL
+
+
+
+
+ a #GActionMap
+
+
+
+ the name of an action
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GActionMap
+
+
+
+ a #GAction
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GActionMap
+
+
+
+ the name of the action
+
+
+
+
+
+
+
+ #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 a desktop-file based application with Exec key `totem
+%U` and a single URI, `sftp://foo/file.avi`, then
+`/home/user/.gvfs/sftp on foo/file.avi` will be passed. This will
+only work if a set of suitable GIO extensions (such as gvfs 2.26
+compiled with FUSE support), is available and operational; if this
+is not the case, the URI will be passed unmodified to the application.
+Some URIs, such as `mailto:`, of course cannot be mapped to a POSIX
+path (in gvfs there's no FUSE mount for it); such URIs will be
+passed unmodified to the application.
+
+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:
+
+|[
+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;
+g_free (uri);
+
+if (g_file_has_uri_scheme (file, "cdda"))
+ {
+ // do something special with uri
+ }
+g_object_unref (file);
+]|
+
+This code will work when both `cdda://sr0/Track 1.wav` and
+`/home/user/.gvfs/cdda on sr0/Track 1.wav` is passed to the
+application. It should be noted that it's generally not safe
+for applications to rely on the format of a particular URIs.
+Different launcher applications (e.g. file managers) may have
+different ideas of what a given URI means.
+
+
+ Creates a new #GAppInfo from the given information.
+
+Note that for @commandline, the quoting rules of the Exec key of the
+[freedesktop.org Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec)
+are applied. For example, if the @commandline contains
+percent-encoded URIs, the percent-character must be doubled in order to prevent it from
+being swallowed by Exec key unquoting. See the specification for exact quoting rules.
+
+
+ new #GAppInfo for given command.
+
+
+
+
+ the commandline to use
+
+
+
+ the application name, or %NULL to use @commandline
+
+
+
+ flags that can specify details of the created #GAppInfo
+
+
+
+
+
+ Gets a list of all of the applications currently registered
+on this system.
+
+For desktop files, this includes applications that have
+`NoDisplay=true` set or are excluded from display by means
+of `OnlyShowIn` or `NotShowIn`. See g_app_info_should_show().
+The returned list does not include applications which have
+the `Hidden` key set.
+
+
+ a newly allocated #GList of references to #GAppInfos.
+
+
+
+
+
+
+ Gets a list of all #GAppInfos for a given content type,
+including the recommended and fallback #GAppInfos. See
+g_app_info_get_recommended_for_type() and
+g_app_info_get_fallback_for_type().
+
+
+ #GList of #GAppInfos
+ for given @content_type or %NULL on error.
+
+
+
+
+
+
+ the content type to find a #GAppInfo for
+
+
+
+
+
+ Gets the default #GAppInfo for a given content type.
+
+
+ #GAppInfo for given @content_type or
+ %NULL on error.
+
+
+
+
+ the content type to find a #GAppInfo for
+
+
+
+ if %TRUE, the #GAppInfo is expected to
+ support URIs
+
+
+
+
+
+ Asynchronously gets the default #GAppInfo for a given content type.
+
+
+
+
+
+
+ the content type to find a #GAppInfo for
+
+
+
+ if %TRUE, the #GAppInfo is expected to
+ support URIs
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call when the request is done
+
+
+
+ data to pass to @callback
+
+
+
+
+
+ Finishes a default #GAppInfo lookup started by
+g_app_info_get_default_for_type_async().
+
+If no #GAppInfo is found, then @error will be set to %G_IO_ERROR_NOT_FOUND.
+
+
+ #GAppInfo for given @content_type or
+ %NULL on error.
+
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Gets the default application for handling URIs with
+the given URI scheme. A URI scheme is the initial part
+of the URI, up to but not including the ':', e.g. "http",
+"ftp" or "sip".
+
+
+ #GAppInfo for given @uri_scheme or
+ %NULL on error.
+
+
+
+
+ a string containing a URI scheme.
+
+
+
+
+
+ Asynchronously gets the default application for handling URIs with
+the given URI scheme. A URI scheme is the initial part
+of the URI, up to but not including the ':', e.g. "http",
+"ftp" or "sip".
+
+
+
+
+
+
+ a string containing a URI scheme.
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call when the request is done
+
+
+
+ data to pass to @callback
+
+
+
+
+
+ Finishes a default #GAppInfo lookup started by
+g_app_info_get_default_for_uri_scheme_async().
+
+If no #GAppInfo is found, then @error will be set to %G_IO_ERROR_NOT_FOUND.
+
+
+ #GAppInfo for given @uri_scheme or
+ %NULL on error.
+
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ 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.
+
+
+ #GList of #GAppInfos
+ for given @content_type or %NULL on error.
+
+
+
+
+
+
+ the content type to find a #GAppInfo for
+
+
+
+
+
+ Gets a list of recommended #GAppInfos for a given content type, i.e.
+those applications which claim to support the given content type exactly,
+and not by MIME type subclassing.
+Note that the first application of the list is the last used one, i.e.
+the last one for which g_app_info_set_as_last_used_for_type() has been
+called.
+
+
+ #GList of #GAppInfos
+ for given @content_type or %NULL on error.
+
+
+
+
+
+
+ the content type to find a #GAppInfo for
+
+
+
+
+
+ Utility function that launches the default application
+registered to handle the specified uri. Synchronous I/O
+is done on the uri to detect the type of the file if
+required.
+
+The D-Bus–activated applications don't have to be started if your application
+terminates too soon after this function. To prevent this, use
+g_app_info_launch_default_for_uri_async() instead.
+
+
+ %TRUE on success, %FALSE on error.
+
+
+
+
+ the uri to show
+
+
+
+ an optional #GAppLaunchContext
+
+
+
+
+
+ Async version of g_app_info_launch_default_for_uri().
+
+This version is useful if you are interested in receiving
+error information in the case where the application is
+sandboxed and the portal may present an application chooser
+dialog to the user.
+
+This is also useful if you want to be sure that the D-Bus–activated
+applications are really started before termination and if you are interested
+in receiving error information from their activation.
+
+
+
+
+
+
+ the uri to show
+
+
+
+ an optional #GAppLaunchContext
+
+
+
+ a #GCancellable
+
+
+
+ a #GAsyncReadyCallback to call when the request is done
+
+
+
+ data to pass to @callback
+
+
+
+
+
+ Finishes an asynchronous launch-default-for-uri operation.
+
+
+ %TRUE if the launch was successful, %FALSE if @error is set
+
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ 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().
+
+
+
+
+
+
+ a content type
+
+
+
+
+
+ Adds a content type to the application information to indicate the
+application is capable of opening files with the given content type.
+
+
+ %TRUE on success, %FALSE on error.
+
+
+
+
+ a #GAppInfo.
+
+
+
+ a string.
+
+
+
+
+
+ Obtains the information whether the #GAppInfo can be deleted.
+See g_app_info_delete().
+
+
+ %TRUE if @appinfo can be deleted
+
+
+
+
+ a #GAppInfo
+
+
+
+
+
+ Checks if a supported content type can be removed from an application.
+
+
+ %TRUE if it is possible to remove supported
+ content types from a given @appinfo, %FALSE if not.
+
+
+
+
+ a #GAppInfo.
+
+
+
+
+
+ Tries to delete a #GAppInfo.
+
+On some platforms, there may be a difference between user-defined
+#GAppInfos which can be deleted, and system-wide ones which cannot.
+See g_app_info_can_delete().
+
+
+ %TRUE if @appinfo has been deleted
+
+
+
+
+ a #GAppInfo
+
+
+
+
+
+ Creates a duplicate of a #GAppInfo.
+
+
+ a duplicate of @appinfo.
+
+
+
+
+ a #GAppInfo.
+
+
+
+
+
+ Checks if two #GAppInfos are equal.
+
+Note that the check *may not* compare each individual
+field, and only does an identity check. In case detecting changes in the
+contents is needed, program code must additionally compare relevant fields.
+
+
+ %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise.
+
+
+
+
+ the first #GAppInfo.
+
+
+
+ the second #GAppInfo.
+
+
+
+
+
+ Gets the commandline with which the application will be
+started.
+
+
+ a string containing the @appinfo's commandline,
+ or %NULL if this information is not available
+
+
+
+
+ a #GAppInfo
+
+
+
+
+
+ Gets a human-readable description of an installed application.
+
+
+ a string containing a description of the
+application @appinfo, or %NULL if none.
+
+
+
+
+ a #GAppInfo.
+
+
+
+
+
+ Gets the display name of the application. The display name is often more
+descriptive to the user than the name itself.
+
+
+ the display name of the application for @appinfo, or the name if
+no display name is available.
+
+
+
+
+ a #GAppInfo.
+
+
+
+
+
+ Gets the executable's name for the installed application.
+
+This is intended to be used for debugging or labelling what program is going
+to be run. To launch the executable, use g_app_info_launch() and related
+functions, rather than spawning the return value from this function.
+
+
+ a string containing the @appinfo's application
+binaries name
+
+
+
+
+ a #GAppInfo
+
+
+
+
+
+ Gets the icon for the application.
+
+
+ the default #GIcon for @appinfo or %NULL
+if there is no default icon.
+
+
+
+
+ a #GAppInfo.
+
+
+
+
+
+ Gets the ID of an application. An id is a string that
+identifies the application. The exact format of the id is
+platform dependent. For instance, on Unix this is the
+desktop file id from the xdg menu specification.
+
+Note that the returned ID may be %NULL, depending on how
+the @appinfo has been constructed.
+
+
+ a string containing the application's ID.
+
+
+
+
+ a #GAppInfo.
+
+
+
+
+
+ Gets the installed name of the application.
+
+
+ the name of the application for @appinfo.
+
+
+
+
+ a #GAppInfo.
+
+
+
+
+
+ Retrieves the list of content types that @app_info claims to support.
+If this information is not provided by the environment, this function
+will return %NULL.
+This function does not take in consideration associations added with
+g_app_info_add_supports_type(), but only those exported directly by
+the application.
+
+
+
+ a list of content types.
+
+
+
+
+
+
+ a #GAppInfo that can handle files
+
+
+
+
+
+ Launches the application. Passes @files to the launched application
+as arguments, using the optional @context to get information
+about the details of the launcher (like what screen it is on).
+On error, @error will be set accordingly.
+
+To launch the application without arguments pass a %NULL @files list.
+
+Note that even if the launch is successful the application launched
+can fail to start if it runs into problems during startup. There is
+no way to detect this.
+
+Some URIs can be changed when passed through a GFile (for instance
+unsupported URIs with strange formats like mailto:), so if you have
+a textual URI you want to pass in as argument, consider using
+g_app_info_launch_uris() instead.
+
+The launched application inherits the environment of the launching
+process, but it can be modified with g_app_launch_context_setenv()
+and g_app_launch_context_unsetenv().
+
+On UNIX, this function sets the `GIO_LAUNCHED_DESKTOP_FILE`
+environment variable with the path of the launched desktop file and
+`GIO_LAUNCHED_DESKTOP_FILE_PID` to the process id of the launched
+process. This can be used to ignore `GIO_LAUNCHED_DESKTOP_FILE`,
+should it be inherited by further processes. The `DISPLAY`,
+`XDG_ACTIVATION_TOKEN` and `DESKTOP_STARTUP_ID` environment
+variables are also set, based on information provided in @context.
+
+
+ %TRUE on successful launch, %FALSE otherwise.
+
+
+
+
+ a #GAppInfo
+
+
+
+ a #GList of #GFile objects
+
+
+
+
+
+ a #GAppLaunchContext or %NULL
+
+
+
+
+
+ Launches the application. This passes the @uris to the launched application
+as arguments, using the optional @context to get information
+about the details of the launcher (like what screen it is on).
+On error, @error will be set accordingly. If the application only supports
+one URI per invocation as part of their command-line, multiple instances
+of the application will be spawned.
+
+To launch the application without arguments pass a %NULL @uris list.
+
+Note that even if the launch is successful the application launched
+can fail to start if it runs into problems during startup. There is
+no way to detect this.
+
+
+ %TRUE on successful launch, %FALSE otherwise.
+
+
+
+
+ a #GAppInfo
+
+
+
+ a #GList containing URIs to launch.
+
+
+
+
+
+ a #GAppLaunchContext or %NULL
+
+
+
+
+
+ Async version of g_app_info_launch_uris().
+
+The @callback is invoked immediately after the application launch, but it
+waits for activation in case of D-Bus–activated applications and also provides
+extended error information for sandboxed applications, see notes for
+g_app_info_launch_default_for_uri_async().
+
+
+
+
+
+
+ a #GAppInfo
+
+
+
+ a #GList containing URIs to launch.
+
+
+
+
+
+ a #GAppLaunchContext or %NULL
+
+
+
+ a #GCancellable
+
+
+
+ a #GAsyncReadyCallback to call when the request is done
+
+
+
+ data to pass to @callback
+
+
+
+
+
+ Finishes a g_app_info_launch_uris_async() operation.
+
+
+ %TRUE on successful launch, %FALSE otherwise.
+
+
+
+
+ a #GAppInfo
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Removes a supported type from an application, if possible.
+
+
+ %TRUE on success, %FALSE on error.
+
+
+
+
+ a #GAppInfo.
+
+
+
+ a string.
+
+
+
+
+
+ Sets the application as the default handler for the given file extension.
+
+
+ %TRUE on success, %FALSE on error.
+
+
+
+
+ a #GAppInfo.
+
+
+
+ a string containing the file extension
+ (without the dot).
+
+
+
+
+
+ Sets the application as the default handler for a given type.
+
+
+ %TRUE on success, %FALSE on error.
+
+
+
+
+ a #GAppInfo.
+
+
+
+ the content type.
+
+
+
+
+
+ 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.
+
+
+ %TRUE on success, %FALSE on error.
+
+
+
+
+ a #GAppInfo.
+
+
+
+ the content type.
+
+
+
+
+
+ Checks if the application info should be shown in menus that
+list available applications.
+
+
+ %TRUE if the @appinfo should be shown, %FALSE otherwise.
+
+
+
+
+ a #GAppInfo.
+
+
+
+
+
+ Checks if the application accepts files as arguments.
+
+
+ %TRUE if the @appinfo supports files.
+
+
+
+
+ a #GAppInfo.
+
+
+
+
+
+ Checks if the application supports reading files and directories from URIs.
+
+
+ %TRUE if the @appinfo supports URIs.
+
+
+
+
+ a #GAppInfo.
+
+
+
+
+
+ Adds a content type to the application information to indicate the
+application is capable of opening files with the given content type.
+
+
+ %TRUE on success, %FALSE on error.
+
+
+
+
+ a #GAppInfo.
+
+
+
+ a string.
+
+
+
+
+
+ Obtains the information whether the #GAppInfo can be deleted.
+See g_app_info_delete().
+
+
+ %TRUE if @appinfo can be deleted
+
+
+
+
+ a #GAppInfo
+
+
+
+
+
+ Checks if a supported content type can be removed from an application.
+
+
+ %TRUE if it is possible to remove supported
+ content types from a given @appinfo, %FALSE if not.
+
+
+
+
+ a #GAppInfo.
+
+
+
+
+
+ Tries to delete a #GAppInfo.
+
+On some platforms, there may be a difference between user-defined
+#GAppInfos which can be deleted, and system-wide ones which cannot.
+See g_app_info_can_delete().
+
+
+ %TRUE if @appinfo has been deleted
+
+
+
+
+ a #GAppInfo
+
+
+
+
+
+ Creates a duplicate of a #GAppInfo.
+
+
+ a duplicate of @appinfo.
+
+
+
+
+ a #GAppInfo.
+
+
+
+
+
+ Checks if two #GAppInfos are equal.
+
+Note that the check *may not* compare each individual
+field, and only does an identity check. In case detecting changes in the
+contents is needed, program code must additionally compare relevant fields.
+
+
+ %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise.
+
+
+
+
+ the first #GAppInfo.
+
+
+
+ the second #GAppInfo.
+
+
+
+
+
+ Gets the commandline with which the application will be
+started.
+
+
+ a string containing the @appinfo's commandline,
+ or %NULL if this information is not available
+
+
+
+
+ a #GAppInfo
+
+
+
+
+
+ Gets a human-readable description of an installed application.
+
+
+ a string containing a description of the
+application @appinfo, or %NULL if none.
+
+
+
+
+ a #GAppInfo.
+
+
+
+
+
+ Gets the display name of the application. The display name is often more
+descriptive to the user than the name itself.
+
+
+ the display name of the application for @appinfo, or the name if
+no display name is available.
+
+
+
+
+ a #GAppInfo.
+
+
+
+
+
+ Gets the executable's name for the installed application.
+
+This is intended to be used for debugging or labelling what program is going
+to be run. To launch the executable, use g_app_info_launch() and related
+functions, rather than spawning the return value from this function.
+
+
+ a string containing the @appinfo's application
+binaries name
+
+
+
+
+ a #GAppInfo
+
+
+
+
+
+ Gets the icon for the application.
+
+
+ the default #GIcon for @appinfo or %NULL
+if there is no default icon.
+
+
+
+
+ a #GAppInfo.
+
+
+
+
+
+ Gets the ID of an application. An id is a string that
+identifies the application. The exact format of the id is
+platform dependent. For instance, on Unix this is the
+desktop file id from the xdg menu specification.
+
+Note that the returned ID may be %NULL, depending on how
+the @appinfo has been constructed.
+
+
+ a string containing the application's ID.
+
+
+
+
+ a #GAppInfo.
+
+
+
+
+
+ Gets the installed name of the application.
+
+
+ the name of the application for @appinfo.
+
+
+
+
+ a #GAppInfo.
+
+
+
+
+
+ Retrieves the list of content types that @app_info claims to support.
+If this information is not provided by the environment, this function
+will return %NULL.
+This function does not take in consideration associations added with
+g_app_info_add_supports_type(), but only those exported directly by
+the application.
+
+
+
+ a list of content types.
+
+
+
+
+
+
+ a #GAppInfo that can handle files
+
+
+
+
+
+ Launches the application. Passes @files to the launched application
+as arguments, using the optional @context to get information
+about the details of the launcher (like what screen it is on).
+On error, @error will be set accordingly.
+
+To launch the application without arguments pass a %NULL @files list.
+
+Note that even if the launch is successful the application launched
+can fail to start if it runs into problems during startup. There is
+no way to detect this.
+
+Some URIs can be changed when passed through a GFile (for instance
+unsupported URIs with strange formats like mailto:), so if you have
+a textual URI you want to pass in as argument, consider using
+g_app_info_launch_uris() instead.
+
+The launched application inherits the environment of the launching
+process, but it can be modified with g_app_launch_context_setenv()
+and g_app_launch_context_unsetenv().
+
+On UNIX, this function sets the `GIO_LAUNCHED_DESKTOP_FILE`
+environment variable with the path of the launched desktop file and
+`GIO_LAUNCHED_DESKTOP_FILE_PID` to the process id of the launched
+process. This can be used to ignore `GIO_LAUNCHED_DESKTOP_FILE`,
+should it be inherited by further processes. The `DISPLAY`,
+`XDG_ACTIVATION_TOKEN` and `DESKTOP_STARTUP_ID` environment
+variables are also set, based on information provided in @context.
+
+
+ %TRUE on successful launch, %FALSE otherwise.
+
+
+
+
+ a #GAppInfo
+
+
+
+ a #GList of #GFile objects
+
+
+
+
+
+ a #GAppLaunchContext or %NULL
+
+
+
+
+
+ Launches the application. This passes the @uris to the launched application
+as arguments, using the optional @context to get information
+about the details of the launcher (like what screen it is on).
+On error, @error will be set accordingly. If the application only supports
+one URI per invocation as part of their command-line, multiple instances
+of the application will be spawned.
+
+To launch the application without arguments pass a %NULL @uris list.
+
+Note that even if the launch is successful the application launched
+can fail to start if it runs into problems during startup. There is
+no way to detect this.
+
+
+ %TRUE on successful launch, %FALSE otherwise.
+
+
+
+
+ a #GAppInfo
+
+
+
+ a #GList containing URIs to launch.
+
+
+
+
+
+ a #GAppLaunchContext or %NULL
+
+
+
+
+
+ Async version of g_app_info_launch_uris().
+
+The @callback is invoked immediately after the application launch, but it
+waits for activation in case of D-Bus–activated applications and also provides
+extended error information for sandboxed applications, see notes for
+g_app_info_launch_default_for_uri_async().
+
+
+
+
+
+
+ a #GAppInfo
+
+
+
+ a #GList containing URIs to launch.
+
+
+
+
+
+ a #GAppLaunchContext or %NULL
+
+
+
+ a #GCancellable
+
+
+
+ a #GAsyncReadyCallback to call when the request is done
+
+
+
+ data to pass to @callback
+
+
+
+
+
+ Finishes a g_app_info_launch_uris_async() operation.
+
+
+ %TRUE on successful launch, %FALSE otherwise.
+
+
+
+
+ a #GAppInfo
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Removes a supported type from an application, if possible.
+
+
+ %TRUE on success, %FALSE on error.
+
+
+
+
+ a #GAppInfo.
+
+
+
+ a string.
+
+
+
+
+
+ Sets the application as the default handler for the given file extension.
+
+
+ %TRUE on success, %FALSE on error.
+
+
+
+
+ a #GAppInfo.
+
+
+
+ a string containing the file extension
+ (without the dot).
+
+
+
+
+
+ Sets the application as the default handler for a given type.
+
+
+ %TRUE on success, %FALSE on error.
+
+
+
+
+ a #GAppInfo.
+
+
+
+ the content type.
+
+
+
+
+
+ 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.
+
+
+ %TRUE on success, %FALSE on error.
+
+
+
+
+ a #GAppInfo.
+
+
+
+ the content type.
+
+
+
+
+
+ Checks if the application info should be shown in menus that
+list available applications.
+
+
+ %TRUE if the @appinfo should be shown, %FALSE otherwise.
+
+
+
+
+ a #GAppInfo.
+
+
+
+
+
+ Checks if the application accepts files as arguments.
+
+
+ %TRUE if the @appinfo supports files.
+
+
+
+
+ a #GAppInfo.
+
+
+
+
+
+ Checks if the application supports reading files and directories from URIs.
+
+
+ %TRUE if the @appinfo supports URIs.
+
+
+
+
+ a #GAppInfo.
+
+
+
+
+
+
+ Flags used when creating a #GAppInfo.
+
+ No flags.
+
+
+ Application opens in a terminal window.
+
+
+ Application supports URI arguments.
+
+
+ Application supports startup notification. Since 2.26
+
+
+
+ Application Information interface, for operating system portability.
+
+
+ The parent interface.
+
+
+
+
+
+
+ a duplicate of @appinfo.
+
+
+
+
+ a #GAppInfo.
+
+
+
+
+
+
+
+
+
+ %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise.
+
+
+
+
+ the first #GAppInfo.
+
+
+
+ the second #GAppInfo.
+
+
+
+
+
+
+
+
+
+ a string containing the application's ID.
+
+
+
+
+ a #GAppInfo.
+
+
+
+
+
+
+
+
+
+ the name of the application for @appinfo.
+
+
+
+
+ a #GAppInfo.
+
+
+
+
+
+
+
+
+
+ a string containing a description of the
+application @appinfo, or %NULL if none.
+
+
+
+
+ a #GAppInfo.
+
+
+
+
+
+
+
+
+
+ a string containing the @appinfo's application
+binaries name
+
+
+
+
+ a #GAppInfo
+
+
+
+
+
+
+
+
+
+ the default #GIcon for @appinfo or %NULL
+if there is no default icon.
+
+
+
+
+ a #GAppInfo.
+
+
+
+
+
+
+
+
+
+ %TRUE on successful launch, %FALSE otherwise.
+
+
+
+
+ a #GAppInfo
+
+
+
+ a #GList of #GFile objects
+
+
+
+
+
+ a #GAppLaunchContext or %NULL
+
+
+
+
+
+
+
+
+
+ %TRUE if the @appinfo supports URIs.
+
+
+
+
+ a #GAppInfo.
+
+
+
+
+
+
+
+
+
+ %TRUE if the @appinfo supports files.
+
+
+
+
+ a #GAppInfo.
+
+
+
+
+
+
+
+
+
+ %TRUE on successful launch, %FALSE otherwise.
+
+
+
+
+ a #GAppInfo
+
+
+
+ a #GList containing URIs to launch.
+
+
+
+
+
+ a #GAppLaunchContext or %NULL
+
+
+
+
+
+
+
+
+
+ %TRUE if the @appinfo should be shown, %FALSE otherwise.
+
+
+
+
+ a #GAppInfo.
+
+
+
+
+
+
+
+
+
+ %TRUE on success, %FALSE on error.
+
+
+
+
+ a #GAppInfo.
+
+
+
+ the content type.
+
+
+
+
+
+
+
+
+
+ %TRUE on success, %FALSE on error.
+
+
+
+
+ a #GAppInfo.
+
+
+
+ a string containing the file extension
+ (without the dot).
+
+
+
+
+
+
+
+
+
+ %TRUE on success, %FALSE on error.
+
+
+
+
+ a #GAppInfo.
+
+
+
+ a string.
+
+
+
+
+
+
+
+
+
+ %TRUE if it is possible to remove supported
+ content types from a given @appinfo, %FALSE if not.
+
+
+
+
+ a #GAppInfo.
+
+
+
+
+
+
+
+
+
+ %TRUE on success, %FALSE on error.
+
+
+
+
+ a #GAppInfo.
+
+
+
+ a string.
+
+
+
+
+
+
+
+
+
+ %TRUE if @appinfo can be deleted
+
+
+
+
+ a #GAppInfo
+
+
+
+
+
+
+
+
+
+ %TRUE if @appinfo has been deleted
+
+
+
+
+ a #GAppInfo
+
+
+
+
+
+
+
+
+
+ a string containing the @appinfo's commandline,
+ or %NULL if this information is not available
+
+
+
+
+ a #GAppInfo
+
+
+
+
+
+
+
+
+
+ the display name of the application for @appinfo, or the name if
+no display name is available.
+
+
+
+
+ a #GAppInfo.
+
+
+
+
+
+
+
+
+
+ %TRUE on success, %FALSE on error.
+
+
+
+
+ a #GAppInfo.
+
+
+
+ the content type.
+
+
+
+
+
+
+
+
+
+
+ a list of content types.
+
+
+
+
+
+
+ a #GAppInfo that can handle files
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GAppInfo
+
+
+
+ a #GList containing URIs to launch.
+
+
+
+
+
+ a #GAppLaunchContext or %NULL
+
+
+
+ a #GCancellable
+
+
+
+ a #GAsyncReadyCallback to call when the request is done
+
+
+
+ data to pass to @callback
+
+
+
+
+
+
+
+
+
+ %TRUE on successful launch, %FALSE otherwise.
+
+
+
+
+ a #GAppInfo
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+ #GAppInfoMonitor is a very simple object used for monitoring the app
+info database for changes (ie: newly installed or removed
+applications).
+
+Call g_app_info_monitor_get() to get a #GAppInfoMonitor and connect
+to the "changed" signal.
+
+In the usual case, applications should try to make note of the change
+(doing things like invalidating caches) but not act on it. In
+particular, applications should avoid making calls to #GAppInfo APIs
+in response to the change signal, deferring these until the time that
+the data is actually required. The exception to this case is when
+application information is actually being displayed on the screen
+(eg: during a search or when the list of all applications is shown).
+The reason for this is that changes to the list of installed
+applications often come in groups (like during system updates) and
+rescanning the list on every change is pointless and expensive.
+
+ Gets the #GAppInfoMonitor for the current thread-default main
+context.
+
+The #GAppInfoMonitor will emit a "changed" signal in the
+thread-default main context whenever the list of installed
+applications (as reported by g_app_info_get_all()) may have changed.
+
+You must only call g_object_unref() on the return value from under
+the same main context as you created it.
+
+
+ a reference to a #GAppInfoMonitor
+
+
+
+
+ Signal emitted when the app info database for changes (ie: newly installed
+or removed applications).
+
+
+
+
+
+
+ Integrating the launch with the launching application. This is used to
+handle for instance startup notification and launching the new application
+on the same screen as the launching window.
+
+
+ Creates a new application launch context. This is not normally used,
+instead you instantiate a subclass of this, such as #GdkAppLaunchContext.
+
+
+ a #GAppLaunchContext.
+
+
+
+
+ Gets the display string for the @context. This is used to ensure new
+applications are started on the same display as the launching
+application, by setting the `DISPLAY` environment variable.
+
+
+ a display string for the display.
+
+
+
+
+ a #GAppLaunchContext
+
+
+
+ a #GAppInfo
+
+
+
+ a #GList of #GFile objects
+
+
+
+
+
+
+
+ Initiates startup notification for the application and returns the
+`XDG_ACTIVATION_TOKEN` or `DESKTOP_STARTUP_ID` for the launched operation,
+if supported.
+
+The returned token may be referred to equivalently as an ‘activation token’
+(using Wayland terminology) or a ‘startup sequence ID’ (using X11 terminology).
+The two [are interoperable](https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/staging/xdg-activation/x11-interoperation.rst).
+
+Activation tokens are defined in the [XDG Activation Protocol](https://wayland.app/protocols/xdg-activation-v1),
+and startup notification IDs are defined in the
+[freedesktop.org Startup Notification Protocol](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt).
+
+Support for the XDG Activation Protocol was added in GLib 2.76.
+
+
+ a startup notification ID for the application, or %NULL if
+ not supported.
+
+
+
+
+ a #GAppLaunchContext
+
+
+
+ a #GAppInfo
+
+
+
+ a #GList of of #GFile objects
+
+
+
+
+
+
+
+ Called when an application has failed to launch, so that it can cancel
+the application startup notification started in g_app_launch_context_get_startup_notify_id().
+
+
+
+
+
+
+ a #GAppLaunchContext.
+
+
+
+ the startup notification id that was returned by g_app_launch_context_get_startup_notify_id().
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Gets the display string for the @context. This is used to ensure new
+applications are started on the same display as the launching
+application, by setting the `DISPLAY` environment variable.
+
+
+ a display string for the display.
+
+
+
+
+ a #GAppLaunchContext
+
+
+
+ a #GAppInfo
+
+
+
+ a #GList of #GFile objects
+
+
+
+
+
+
+
+ Gets the complete environment variable list to be passed to
+the child process when @context is used to launch an application.
+This is a %NULL-terminated array of strings, where each string has
+the form `KEY=VALUE`.
+
+
+
+ the child's environment
+
+
+
+
+
+
+ a #GAppLaunchContext
+
+
+
+
+
+ Initiates startup notification for the application and returns the
+`XDG_ACTIVATION_TOKEN` or `DESKTOP_STARTUP_ID` for the launched operation,
+if supported.
+
+The returned token may be referred to equivalently as an ‘activation token’
+(using Wayland terminology) or a ‘startup sequence ID’ (using X11 terminology).
+The two [are interoperable](https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/staging/xdg-activation/x11-interoperation.rst).
+
+Activation tokens are defined in the [XDG Activation Protocol](https://wayland.app/protocols/xdg-activation-v1),
+and startup notification IDs are defined in the
+[freedesktop.org Startup Notification Protocol](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt).
+
+Support for the XDG Activation Protocol was added in GLib 2.76.
+
+
+ a startup notification ID for the application, or %NULL if
+ not supported.
+
+
+
+
+ a #GAppLaunchContext
+
+
+
+ a #GAppInfo
+
+
+
+ a #GList of of #GFile objects
+
+
+
+
+
+
+
+ Called when an application has failed to launch, so that it can cancel
+the application startup notification started in g_app_launch_context_get_startup_notify_id().
+
+
+
+
+
+
+ a #GAppLaunchContext.
+
+
+
+ the startup notification id that was returned by g_app_launch_context_get_startup_notify_id().
+
+
+
+
+
+ Arranges for @variable to be set to @value in the child's
+environment when @context is used to launch an application.
+
+
+
+
+
+
+ a #GAppLaunchContext
+
+
+
+ the environment variable to set
+
+
+
+ the value for to set the variable to.
+
+
+
+
+
+ Arranges for @variable to be unset in the child's environment
+when @context is used to launch an application.
+
+
+
+
+
+
+ a #GAppLaunchContext
+
+
+
+ the environment variable to remove
+
+
+
+
+
+
+
+
+
+
+
+ The #GAppLaunchContext::launch-failed signal is emitted when a #GAppInfo launch
+fails. The startup notification id is provided, so that the launcher
+can cancel the startup notification.
+
+Because a launch operation may involve spawning multiple instances of the
+target application, you should expect this signal to be emitted multiple
+times, one for each spawned instance.
+
+
+
+
+
+ the startup notification id for the failed launch
+
+
+
+
+
+ The #GAppLaunchContext::launch-started signal is emitted when a #GAppInfo is
+about to be launched. If non-null the @platform_data is an
+GVariant dictionary mapping strings to variants (ie `a{sv}`), which
+contains additional, platform-specific data about this launch. On
+UNIX, at least the `startup-notification-id` keys will be
+present.
+
+The value of the `startup-notification-id` key (type `s`) is a startup
+notification ID corresponding to the format from the [startup-notification
+specification](https://specifications.freedesktop.org/startup-notification-spec/startup-notification-0.1.txt).
+It allows tracking the progress of the launchee through startup.
+
+It is guaranteed that this signal is followed by either a #GAppLaunchContext::launched or
+#GAppLaunchContext::launch-failed signal.
+
+Because a launch operation may involve spawning multiple instances of the
+target application, you should expect this signal to be emitted multiple
+times, one for each spawned instance.
+
+
+
+
+
+ the #GAppInfo that is about to be launched
+
+
+
+ additional platform-specific data for this launch
+
+
+
+
+
+ The #GAppLaunchContext::launched signal is emitted when a #GAppInfo is successfully
+launched.
+
+Because a launch operation may involve spawning multiple instances of the
+target application, you should expect this signal to be emitted multiple
+times, one time for each spawned instance.
+
+The @platform_data is an GVariant dictionary mapping
+strings to variants (ie `a{sv}`), which contains additional,
+platform-specific data about this launch. On UNIX, at least the
+`pid` and `startup-notification-id` keys will be present.
+
+Since 2.72 the `pid` may be 0 if the process id wasn't known (for
+example if the process was launched via D-Bus). The `pid` may not be
+set at all in subsequent releases.
+
+On Windows, `pid` is guaranteed to be valid only for the duration of the
+#GAppLaunchContext::launched signal emission; after the signal is emitted,
+GLib will call g_spawn_close_pid(). If you need to keep the #GPid after the
+signal has been emitted, then you can duplicate `pid` using `DuplicateHandle()`.
+
+
+
+
+
+ the #GAppInfo that was just launched
+
+
+
+ additional platform-specific data for this launch
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a display string for the display.
+
+
+
+
+ a #GAppLaunchContext
+
+
+
+ a #GAppInfo
+
+
+
+ a #GList of #GFile objects
+
+
+
+
+
+
+
+
+
+
+
+ a startup notification ID for the application, or %NULL if
+ not supported.
+
+
+
+
+ a #GAppLaunchContext
+
+
+
+ a #GAppInfo
+
+
+
+ a #GList of of #GFile objects
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GAppLaunchContext.
+
+
+
+ the startup notification id that was returned by g_app_launch_context_get_startup_notify_id().
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ A #GApplication is the foundation of an application. It wraps some
+low-level platform-specific services and is intended to act as the
+foundation for higher-level application classes such as
+#GtkApplication or #MxApplication. In general, you should not use
+this class outside of a higher level framework.
+
+GApplication provides convenient life cycle management by maintaining
+a "use count" for the primary application instance. The use count can
+be changed using g_application_hold() and g_application_release(). If
+it drops to zero, the application exits. Higher-level classes such as
+#GtkApplication employ the use count to ensure that the application
+stays alive as long as it has any opened windows.
+
+Another feature that GApplication (optionally) provides is process
+uniqueness. Applications can make use of this functionality by
+providing a unique application ID. If given, only one application
+with this ID can be running at a time per session. The session
+concept is platform-dependent, but corresponds roughly to a graphical
+desktop login. When your application is launched again, its
+arguments are passed through platform communication to the already
+running program. The already running instance of the program is
+called the "primary instance"; for non-unique applications this is
+always the current instance. On Linux, the D-Bus session bus
+is used for communication.
+
+The use of #GApplication differs from some other commonly-used
+uniqueness libraries (such as libunique) in important ways. The
+application is not expected to manually register itself and check
+if it is the primary instance. Instead, the main() function of a
+#GApplication should do very little more than instantiating the
+application instance, possibly connecting signal handlers, then
+calling g_application_run(). All checks for uniqueness are done
+internally. If the application is the primary instance then the
+startup signal is emitted and the mainloop runs. If the application
+is not the primary instance then a signal is sent to the primary
+instance and g_application_run() promptly returns. See the code
+examples below.
+
+If used, the expected form of an application identifier is the same as
+that of of a
+[D-Bus well-known bus name](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus).
+Examples include: `com.example.MyApp`, `org.example.internal_apps.Calculator`,
+`org._7_zip.Archiver`.
+For details on valid application identifiers, see g_application_id_is_valid().
+
+On Linux, the application identifier is claimed as a well-known bus name
+on the user's session bus. This means that the uniqueness of your
+application is scoped to the current session. It also means that your
+application may provide additional services (through registration of other
+object paths) at that bus name. The registration of these object paths
+should be done with the shared GDBus session bus. Note that due to the
+internal architecture of GDBus, method calls can be dispatched at any time
+(even if a main loop is not running). For this reason, you must ensure that
+any object paths that you wish to register are registered before #GApplication
+attempts to acquire the bus name of your application (which happens in
+g_application_register()). Unfortunately, this means that you cannot use
+g_application_get_is_remote() to decide if you want to register object paths.
+
+GApplication also implements the #GActionGroup and #GActionMap
+interfaces and lets you easily export actions by adding them with
+g_action_map_add_action(). When invoking an action by calling
+g_action_group_activate_action() on the application, it is always
+invoked in the primary instance. The actions are also exported on
+the session bus, and GIO provides the #GDBusActionGroup wrapper to
+conveniently access them remotely. GIO provides a #GDBusMenuModel wrapper
+for remote access to exported #GMenuModels.
+
+There is a number of different entry points into a GApplication:
+
+- via 'Activate' (i.e. just starting the application)
+
+- via 'Open' (i.e. opening some files)
+
+- by handling a command-line
+
+- via activating an action
+
+The #GApplication::startup signal lets you handle the application
+initialization for all of these in a single place.
+
+Regardless of which of these entry points is used to start the
+application, GApplication passes some ‘platform data’ from the
+launching instance to the primary instance, in the form of a
+#GVariant dictionary mapping strings to variants. To use platform
+data, override the @before_emit or @after_emit virtual functions
+in your #GApplication subclass. When dealing with
+#GApplicationCommandLine objects, the platform data is
+directly available via g_application_command_line_get_cwd(),
+g_application_command_line_get_environ() and
+g_application_command_line_get_platform_data().
+
+As the name indicates, the platform data may vary depending on the
+operating system, but it always includes the current directory (key
+"cwd"), and optionally the environment (ie the set of environment
+variables and their values) of the calling process (key "environ").
+The environment is only added to the platform data if the
+%G_APPLICATION_SEND_ENVIRONMENT flag is set. #GApplication subclasses
+can add their own platform data by overriding the @add_platform_data
+virtual function. For instance, #GtkApplication adds startup notification
+data in this way.
+
+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.
+
+For an example of opening files with a GApplication, see
+[gapplication-example-open.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-open.c).
+
+For an example of using actions with GApplication, see
+[gapplication-example-actions.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-actions.c).
+
+For an example of using extra D-Bus hooks with GApplication, see
+[gapplication-example-dbushooks.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-dbushooks.c).
+
+
+
+
+ Creates a new #GApplication instance.
+
+If non-%NULL, the application id must be valid. See
+g_application_id_is_valid().
+
+If no application ID is given then some features of #GApplication
+(most notably application uniqueness) will be disabled.
+
+
+ a new #GApplication instance
+
+
+
+
+ the application id
+
+
+
+ the application flags
+
+
+
+
+
+ Returns the default #GApplication instance for this process.
+
+Normally there is only one #GApplication per process and it becomes
+the default when it is created. You can exercise more control over
+this by using g_application_set_default().
+
+If there is no default application then %NULL is returned.
+
+
+ the default application for this process, 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().
+
+Application identifiers follow the same format as
+[D-Bus well-known bus names](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus).
+For convenience, the restrictions on application identifiers are
+reproduced here:
+
+- Application identifiers are composed of 1 or more elements separated by a
+ period (`.`) character. All elements must contain at least one character.
+
+- Each element must only contain the ASCII characters `[A-Z][a-z][0-9]_-`,
+ with `-` discouraged in new application identifiers. Each element must not
+ begin with a digit.
+
+- Application identifiers must contain at least one `.` (period) character
+ (and thus at least two elements).
+
+- Application identifiers must not begin with a `.` (period) character.
+
+- Application identifiers must not exceed 255 characters.
+
+Note that the hyphen (`-`) character is allowed in application identifiers,
+but is problematic or not allowed in various specifications and APIs that
+refer to D-Bus, such as
+[Flatpak application IDs](http://docs.flatpak.org/en/latest/introduction.html#identifiers),
+the
+[`DBusActivatable` interface in the Desktop Entry Specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#dbus),
+and the convention that an application's "main" interface and object path
+resemble its application identifier and bus name. To avoid situations that
+require special-case handling, it is recommended that new application
+identifiers consistently replace hyphens with underscores.
+
+Like D-Bus interface names, application identifiers should start with the
+reversed DNS domain name of the author of the interface (in lower-case), and
+it is conventional for the rest of the application identifier to consist of
+words run together, with initial capital letters.
+
+As with D-Bus interface names, if the author's DNS domain name contains
+hyphen/minus characters they should be replaced by underscores, and if it
+contains leading digits they should be escaped by prepending an underscore.
+For example, if the owner of 7-zip.org used an application identifier for an
+archiving application, it might be named `org._7_zip.Archiver`.
+
+
+ %TRUE if @application_id is valid
+
+
+
+
+ a potential application identifier
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+ a #GApplication
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This virtual function is always invoked in the local instance. It
+gets passed a pointer to a %NULL-terminated copy of @argv and is
+expected to remove arguments that it handled (shifting up remaining
+arguments).
+
+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().
+
+See g_application_run() for more details on #GApplication startup.
+
+
+ %TRUE if the commandline has been completely handled
+
+
+
+
+ a #GApplication
+
+
+
+ array of command line arguments
+
+
+
+
+
+ exit status to fill after processing the command line.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Opens the given files.
+
+In essence, this results in the #GApplication::open signal being emitted
+in the primary instance.
+
+@n_files must be greater than zero.
+
+@hint is simply passed through to the ::open signal. It is
+intended to be used by applications that have multiple modes for
+opening files (eg: "view" vs "edit", etc). Unless you have a need
+for this functionality, you should use "".
+
+The application must be registered before calling this function
+and it must have the %G_APPLICATION_HANDLES_OPEN flag set.
+
+
+
+
+
+
+ a #GApplication
+
+
+
+ an array of #GFiles to open
+
+
+
+
+
+ the length of the @files array
+
+
+
+ a hint (or ""), but never %NULL
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+ a #GApplication
+
+
+
+
+
+ Add an option to be handled by @application.
+
+Calling this function is the equivalent of calling
+g_application_add_main_option_entries() with a single #GOptionEntry
+that has its arg_data member set to %NULL.
+
+The parsed arguments will be packed into a #GVariantDict which
+is passed to #GApplication::handle-local-options. If
+%G_APPLICATION_HANDLES_COMMAND_LINE is set, then it will also
+be sent to the primary instance. See
+g_application_add_main_option_entries() for more details.
+
+See #GOptionEntry for more documentation of the arguments.
+
+
+
+
+
+
+ the #GApplication
+
+
+
+ the long name of an option used to specify it in a commandline
+
+
+
+ the short name of an option
+
+
+
+ flags from #GOptionFlags
+
+
+
+ the type of the option, as a #GOptionArg
+
+
+
+ the description for the option in `--help` output
+
+
+
+ the placeholder to use for the extra argument
+ parsed by the option in `--help` output
+
+
+
+
+
+ Adds main option entries to be handled by @application.
+
+This function is comparable to g_option_context_add_main_entries().
+
+After the commandline arguments are parsed, the
+#GApplication::handle-local-options signal will be emitted. At this
+point, the application can inspect the values pointed to by @arg_data
+in the given #GOptionEntrys.
+
+Unlike #GOptionContext, #GApplication supports giving a %NULL
+@arg_data for a non-callback #GOptionEntry. This results in the
+argument in question being packed into a #GVariantDict which is also
+passed to #GApplication::handle-local-options, where it can be
+inspected and modified. If %G_APPLICATION_HANDLES_COMMAND_LINE is
+set, then the resulting dictionary is sent to the primary instance,
+where g_application_command_line_get_options_dict() will return it.
+As it has been passed outside the process at this point, the types of all
+values in the options dict must be checked before being used.
+This "packing" is done according to the type of the argument --
+booleans for normal flags, strings for strings, bytestrings for
+filenames, etc. The packing only occurs if the flag is given (ie: we
+do not pack a "false" #GVariant in the case that a flag is missing).
+
+In general, it is recommended that all commandline arguments are
+parsed locally. The options dictionary should then be used to
+transmit the result of the parsing to the primary instance, where
+g_variant_dict_lookup() can be used. For local options, it is
+possible to either use @arg_data in the usual way, or to consult (and
+potentially remove) the option from the options dictionary.
+
+This function is new in GLib 2.40. Before then, the only real choice
+was to send all of the commandline arguments (options and all) to the
+primary instance for handling. #GApplication ignored them completely
+on the local side. Calling this function "opts in" to the new
+behaviour, and in particular, means that unrecognised options will be
+treated as errors. Unrecognised options have never been ignored when
+%G_APPLICATION_HANDLES_COMMAND_LINE is unset.
+
+If #GApplication::handle-local-options needs to see the list of
+filenames, then the use of %G_OPTION_REMAINING is recommended. If
+@arg_data is %NULL then %G_OPTION_REMAINING can be used as a key into
+the options dictionary. If you do use %G_OPTION_REMAINING then you
+need to handle these arguments for yourself because once they are
+consumed, they will no longer be visible to the default handling
+(which treats them as filenames to be opened).
+
+It is important to use the proper GVariant format when retrieving
+the options with g_variant_dict_lookup():
+- for %G_OPTION_ARG_NONE, use `b`
+- for %G_OPTION_ARG_STRING, use `&s`
+- for %G_OPTION_ARG_INT, use `i`
+- for %G_OPTION_ARG_INT64, use `x`
+- for %G_OPTION_ARG_DOUBLE, use `d`
+- for %G_OPTION_ARG_FILENAME, use `^&ay`
+- for %G_OPTION_ARG_STRING_ARRAY, use `^a&s`
+- for %G_OPTION_ARG_FILENAME_ARRAY, use `^a&ay`
+
+
+
+
+
+
+ a #GApplication
+
+
+
+ a
+ %NULL-terminated list of #GOptionEntrys
+
+
+
+
+
+
+
+ Adds a #GOptionGroup to the commandline handling of @application.
+
+This function is comparable to g_option_context_add_group().
+
+Unlike g_application_add_main_option_entries(), this function does
+not deal with %NULL @arg_data and never transmits options to the
+primary instance.
+
+The reason for that is because, by the time the options arrive at the
+primary instance, it is typically too late to do anything with them.
+Taking the GTK option group as an example: GTK will already have been
+initialised by the time the #GApplication::command-line handler runs.
+In the case that this is not the first-running instance of the
+application, the existing instance may already have been running for
+a very long time.
+
+This means that the options from #GOptionGroup are only really usable
+in the case that the instance of the application being run is the
+first instance. Passing options like `--display=` or `--gdk-debug=`
+on future runs will have no effect on the existing primary instance.
+
+Calling this function will cause the options in the supplied option
+group to be parsed, but it does not cause you to be "opted in" to the
+new functionality whereby unrecognised options are rejected even if
+%G_APPLICATION_HANDLES_COMMAND_LINE was given.
+
+
+
+
+
+
+ the #GApplication
+
+
+
+ a #GOptionGroup
+
+
+
+
+
+ Marks @application as busy (see g_application_mark_busy()) while
+@property on @object is %TRUE.
+
+The binding holds a reference to @application while it is active, but
+not to @object. Instead, the binding is destroyed when @object is
+finalized.
+
+
+
+
+
+
+ a #GApplication
+
+
+
+ a #GObject
+
+
+
+ the name of a boolean property of @object
+
+
+
+
+
+ Gets the unique identifier for @application.
+
+
+ the identifier for @application, owned by @application
+
+
+
+
+ a #GApplication
+
+
+
+
+
+ Gets the #GDBusConnection being used by the application, or %NULL.
+
+If #GApplication is using its D-Bus backend then this function will
+return the #GDBusConnection being used for uniqueness and
+communication with the desktop environment and other instances of the
+application.
+
+If #GApplication is not using D-Bus then this function will return
+%NULL. This includes the situation where the D-Bus backend would
+normally be in use but we were unable to connect to the bus.
+
+This function must not be called before the application has been
+registered. See g_application_get_is_registered().
+
+
+ a #GDBusConnection, or %NULL
+
+
+
+
+ a #GApplication
+
+
+
+
+
+ Gets the D-Bus object path being used by the application, or %NULL.
+
+If #GApplication is using its D-Bus backend then this function will
+return the D-Bus object path that #GApplication is using. If the
+application is the primary instance then there is an object published
+at this path. If the application is not the primary instance then
+the result of this function is undefined.
+
+If #GApplication is not using D-Bus then this function will return
+%NULL. This includes the situation where the D-Bus backend would
+normally be in use but we were unable to connect to the bus.
+
+This function must not be called before the application has been
+registered. See g_application_get_is_registered().
+
+
+ the object path, or %NULL
+
+
+
+
+ a #GApplication
+
+
+
+
+
+ Gets the flags for @application.
+
+See #GApplicationFlags.
+
+
+ the flags for @application
+
+
+
+
+ a #GApplication
+
+
+
+
+
+ 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.
+
+
+ the timeout, in milliseconds
+
+
+
+
+ a #GApplication
+
+
+
+
+
+ Gets the application's current busy state, as set through
+g_application_mark_busy() or g_application_bind_busy_property().
+
+
+ %TRUE if @application is currently marked as busy
+
+
+
+
+ a #GApplication
+
+
+
+
+
+ Checks if @application is registered.
+
+An application is registered if g_application_register() has been
+successfully called.
+
+
+ %TRUE if @application is registered
+
+
+
+
+ a #GApplication
+
+
+
+
+
+ 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().
+
+
+ %TRUE if @application is remote
+
+
+
+
+ a #GApplication
+
+
+
+
+
+ Gets the resource base path of @application.
+
+See g_application_set_resource_base_path() for more information.
+
+
+ the base resource path, if one is set
+
+
+
+
+ a #GApplication
+
+
+
+
+
+ Increases the use count of @application.
+
+Use this function to indicate that the application has a reason to
+continue to run. For example, g_application_hold() is called by GTK+
+when a toplevel window is on the screen.
+
+To cancel the hold, call g_application_release().
+
+
+
+
+
+
+ a #GApplication
+
+
+
+
+
+ Increases the busy count of @application.
+
+Use this function to indicate that the application is busy, for instance
+while a long running operation is pending.
+
+The busy state will be exposed to other processes, so a session shell will
+use that information to indicate the state to the user (e.g. with a
+spinner).
+
+To cancel the busy indication, use g_application_unmark_busy().
+
+The application must be registered before calling this function.
+
+
+
+
+
+
+ a #GApplication
+
+
+
+
+
+ Opens the given files.
+
+In essence, this results in the #GApplication::open signal being emitted
+in the primary instance.
+
+@n_files must be greater than zero.
+
+@hint is simply passed through to the ::open signal. It is
+intended to be used by applications that have multiple modes for
+opening files (eg: "view" vs "edit", etc). Unless you have a need
+for this functionality, you should use "".
+
+The application must be registered before calling this function
+and it must have the %G_APPLICATION_HANDLES_OPEN flag set.
+
+
+
+
+
+
+ a #GApplication
+
+
+
+ an array of #GFiles to open
+
+
+
+
+
+ the length of the @files array
+
+
+
+ a hint (or ""), but never %NULL
+
+
+
+
+
+ Immediately quits the application.
+
+Upon return to the mainloop, g_application_run() will return,
+calling only the 'shutdown' function before doing so.
+
+The hold count is ignored.
+Take care if your code has called g_application_hold() on the application and
+is therefore still expecting it to exist.
+(Note that you may have called g_application_hold() indirectly, for example
+through gtk_application_add_window().)
+
+The result of calling g_application_run() again after it returns is
+unspecified.
+
+
+
+
+
+
+ a #GApplication
+
+
+
+
+
+ Attempts registration of the application.
+
+This is the point at which the application discovers if it is the
+primary instance or merely acting as a remote for an already-existing
+primary instance. This is implemented by attempting to acquire the
+application identifier as a unique bus name on the session bus using
+GDBus.
+
+If there is no application ID or if %G_APPLICATION_NON_UNIQUE was
+given, then this process will always become the primary instance.
+
+Due to the internal architecture of GDBus, method calls can be
+dispatched at any time (even if a main loop is not running). For
+this reason, you must ensure that any object paths that you wish to
+register are registered before calling this function.
+
+If the application has already been registered then %TRUE is
+returned with no work performed.
+
+The #GApplication::startup signal is emitted if registration succeeds
+and @application is the primary instance (including the non-unique
+case).
+
+In the event of an error (such as @cancellable being cancelled, or a
+failure to connect to the session bus), %FALSE is returned and @error
+is set appropriately.
+
+Note: the return value of this function is not an indicator that this
+instance is or is not the primary instance of the application. See
+g_application_get_is_remote() for that.
+
+
+ %TRUE if registration succeeded
+
+
+
+
+ a #GApplication
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Decrease the use count of @application.
+
+When the use count reaches zero, the application will stop running.
+
+Never call this function except to cancel the effect of a previous
+call to g_application_hold().
+
+
+
+
+
+
+ a #GApplication
+
+
+
+
+
+ Runs the application.
+
+This function is intended to be run from main() and its return value
+is intended to be returned by main(). Although you are expected to pass
+the @argc, @argv parameters from main() to this function, it is possible
+to pass %NULL if @argv is not available or commandline handling is not
+required. Note that on Windows, @argc and @argv are ignored, and
+g_win32_get_command_line() is called internally (for proper support
+of Unicode commandline arguments).
+
+#GApplication will attempt to parse the commandline arguments. You
+can add commandline flags to the list of recognised options by way of
+g_application_add_main_option_entries(). After this, the
+#GApplication::handle-local-options signal is emitted, from which the
+application can inspect the values of its #GOptionEntrys.
+
+#GApplication::handle-local-options is a good place to handle options
+such as `--version`, where an immediate reply from the local process is
+desired (instead of communicating with an already-running instance).
+A #GApplication::handle-local-options handler can stop further processing
+by returning a non-negative value, which then becomes the exit status of
+the process.
+
+What happens next depends on the flags: if
+%G_APPLICATION_HANDLES_COMMAND_LINE was specified then the remaining
+commandline arguments are sent to the primary instance, where a
+#GApplication::command-line signal is emitted. Otherwise, the
+remaining commandline arguments are assumed to be a list of files.
+If there are no files listed, the application is activated via the
+#GApplication::activate signal. If there are one or more files, and
+%G_APPLICATION_HANDLES_OPEN was specified then the files are opened
+via the #GApplication::open signal.
+
+If you are interested in doing more complicated local handling of the
+commandline then you should implement your own #GApplication subclass
+and override local_command_line(). In this case, you most likely want
+to return %TRUE from your local_command_line() implementation to
+suppress the default handling. See
+[gapplication-example-cmdline2.c][https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline2.c]
+for an example.
+
+If, after the above is done, the use count of the application is zero
+then the exit status is returned immediately. If the use count is
+non-zero then the default main context is iterated until the use count
+falls to zero, at which point 0 is returned.
+
+If the %G_APPLICATION_IS_SERVICE flag is set, then the service will
+run for as much as 10 seconds with a use count of zero while waiting
+for the message that caused the activation to arrive. After that,
+if the use count falls to zero the application will exit immediately,
+except in the case that g_application_set_inactivity_timeout() is in
+use.
+
+This function sets the prgname (g_set_prgname()), if not already set,
+to the basename of argv[0].
+
+Much like g_main_loop_run(), this function will acquire the main context
+for the duration that the application is running.
+
+Since 2.40, applications that are not explicitly flagged as services
+or launchers (ie: neither %G_APPLICATION_IS_SERVICE or
+%G_APPLICATION_IS_LAUNCHER are given as flags) will check (from the
+default handler for local_command_line) if "--gapplication-service"
+was given in the command line. If this flag is present then normal
+commandline processing is interrupted and the
+%G_APPLICATION_IS_SERVICE flag is set. This provides a "compromise"
+solution whereby running an application directly from the commandline
+will invoke it in the normal way (which can be useful for debugging)
+while still allowing applications to be D-Bus activated in service
+mode. The D-Bus service file should invoke the executable with
+"--gapplication-service" as the sole commandline argument. This
+approach is suitable for use by most graphical applications but
+should not be used from applications like editors that need precise
+control over when processes invoked via the commandline will exit and
+what their exit status will be.
+
+
+ the exit status
+
+
+
+
+ a #GApplication
+
+
+
+ the argc from main() (or 0 if @argv is %NULL)
+
+
+
+
+ the argv from main(), or %NULL
+
+
+
+
+
+
+
+ Sends a notification on behalf of @application to the desktop shell.
+There is no guarantee that the notification is displayed immediately,
+or even at all.
+
+Notifications may persist after the application exits. It will be
+D-Bus-activated when the notification or one of its actions is
+activated.
+
+Modifying @notification after this call has no effect. However, the
+object can be reused for a later call to this function.
+
+@id may be any string that uniquely identifies the event for the
+application. It does not need to be in any special format. For
+example, "new-message" might be appropriate for a notification about
+new messages.
+
+If a previous notification was sent with the same @id, it will be
+replaced with @notification and shown again as if it was a new
+notification. This works even for notifications sent from a previous
+execution of the application, as long as @id is the same string.
+
+@id may be %NULL, but it is impossible to replace or withdraw
+notifications without an id.
+
+If @notification is no longer relevant, it can be withdrawn with
+g_application_withdraw_notification().
+
+
+
+
+
+
+ a #GApplication
+
+
+
+ id of the notification, or %NULL
+
+
+
+ the #GNotification to send
+
+
+
+
+
+ This used to be how actions were associated with a #GApplication.
+Now there is #GActionMap for that.
+ Use the #GActionMap interface instead. Never ever
+mix use of this API with use of #GActionMap on the same @application
+or things will go very badly wrong. This function is known to
+introduce buggy behaviour (ie: signals not emitted on changes to the
+action group), so you should really use #GActionMap instead.
+
+
+
+
+
+
+ a #GApplication
+
+
+
+ a #GActionGroup, or %NULL
+
+
+
+
+
+ Sets the unique identifier for @application.
+
+The application id can only be modified if @application has not yet
+been registered.
+
+If non-%NULL, the application id must be valid. See
+g_application_id_is_valid().
+
+
+
+
+
+
+ a #GApplication
+
+
+
+ the identifier for @application
+
+
+
+
+
+ Sets or unsets the default application for the process, as returned
+by g_application_get_default().
+
+This function does not take its own reference on @application. If
+@application is destroyed then the default application will revert
+back to %NULL.
+
+
+
+
+
+
+ the application to set as default, or %NULL
+
+
+
+
+
+ Sets the flags for @application.
+
+The flags can only be modified if @application has not yet been
+registered.
+
+See #GApplicationFlags.
+
+
+
+
+
+
+ a #GApplication
+
+
+
+ the flags for @application
+
+
+
+
+
+ Sets the current inactivity timeout for the application.
+
+This is the amount of time (in milliseconds) after the last call to
+g_application_release() before the application stops running.
+
+This call has no side effects of its own. The value set here is only
+used for next time g_application_release() drops the use count to
+zero. Any timeouts currently in progress are not impacted.
+
+
+
+
+
+
+ a #GApplication
+
+
+
+ the timeout, in milliseconds
+
+
+
+
+
+ Adds a description to the @application option context.
+
+See g_option_context_set_description() for more information.
+
+
+
+
+
+
+ the #GApplication
+
+
+
+ a string to be shown in `--help` output
+ after the list of options, or %NULL
+
+
+
+
+
+ Sets the parameter string to be used by the commandline handling of @application.
+
+This function registers the argument to be passed to g_option_context_new()
+when the internal #GOptionContext of @application is created.
+
+See g_option_context_new() for more information about @parameter_string.
+
+
+
+
+
+
+ the #GApplication
+
+
+
+ a string which is displayed
+ in the first line of `--help` output, after the usage summary `programname [OPTION...]`.
+
+
+
+
+
+ Adds a summary to the @application option context.
+
+See g_option_context_set_summary() for more information.
+
+
+
+
+
+
+ the #GApplication
+
+
+
+ a string to be shown in `--help` output
+ before the list of options, or %NULL
+
+
+
+
+
+ Sets (or unsets) the base resource path of @application.
+
+The path is used to automatically load various [application
+resources][gresource] such as menu layouts and action descriptions.
+The various types of resources will be found at fixed names relative
+to the given base path.
+
+By default, the resource base path is determined from the application
+ID by prefixing '/' and replacing each '.' with '/'. This is done at
+the time that the #GApplication object is constructed. Changes to
+the application ID after that point will not have an impact on the
+resource base path.
+
+As an example, if the application has an ID of "org.example.app" then
+the default resource base path will be "/org/example/app". If this
+is a #GtkApplication (and you have not manually changed the path)
+then Gtk will then search for the menus of the application at
+"/org/example/app/gtk/menus.ui".
+
+See #GResource for more information about adding resources to your
+application.
+
+You can disable automatic resource loading functionality by setting
+the path to %NULL.
+
+Changing the resource base path once the application is running is
+not recommended. The point at which the resource path is consulted
+for forming paths for various purposes is unspecified. When writing
+a sub-class of #GApplication you should either set the
+#GApplication:resource-base-path property at construction time, or call
+this function during the instance initialization. Alternatively, you
+can call this function in the #GApplicationClass.startup virtual function,
+before chaining up to the parent implementation.
+
+
+
+
+
+
+ a #GApplication
+
+
+
+ the resource path to use
+
+
+
+
+
+ Destroys a binding between @property and the busy state of
+@application that was previously created with
+g_application_bind_busy_property().
+
+
+
+
+
+
+ a #GApplication
+
+
+
+ a #GObject
+
+
+
+ the name of a boolean property of @object
+
+
+
+
+
+ Decreases the busy count of @application.
+
+When the busy count reaches zero, the new state will be propagated
+to other processes.
+
+This function must only be called to cancel the effect of a previous
+call to g_application_mark_busy().
+
+
+
+
+
+
+ a #GApplication
+
+
+
+
+
+ Withdraws a notification that was sent with
+g_application_send_notification().
+
+This call does nothing if a notification with @id doesn't exist or
+the notification was never sent.
+
+This function works even for notifications sent in previous
+executions of this application, as long @id is the same as it was for
+the sent notification.
+
+Note that notifications are dismissed when the user clicks on one
+of the buttons in a notification or triggers its default action, so
+there is no need to explicitly withdraw the notification in that case.
+
+
+
+
+
+
+ a #GApplication
+
+
+
+ id of a previously sent notification
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Whether the application is currently marked as busy through
+g_application_mark_busy() or g_application_bind_busy_property().
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The ::activate signal is emitted on the primary instance when an
+activation occurs. See g_application_activate().
+
+
+
+
+
+ The ::command-line signal is emitted on the primary instance when
+a commandline is not handled locally. See g_application_run() and
+the #GApplicationCommandLine documentation for more information.
+
+ An integer that is set as the exit status for the calling
+ process. See g_application_command_line_set_exit_status().
+
+
+
+
+ a #GApplicationCommandLine representing the
+ passed commandline
+
+
+
+
+
+ The ::handle-local-options signal is emitted on the local instance
+after the parsing of the commandline options has occurred.
+
+You can add options to be recognised during commandline option
+parsing using g_application_add_main_option_entries() and
+g_application_add_option_group().
+
+Signal handlers can inspect @options (along with values pointed to
+from the @arg_data of an installed #GOptionEntrys) in order to
+decide to perform certain actions, including direct local handling
+(which may be useful for options like --version).
+
+In the event that the application is marked
+%G_APPLICATION_HANDLES_COMMAND_LINE the "normal processing" will
+send the @options dictionary to the primary instance where it can be
+read with g_application_command_line_get_options_dict(). The signal
+handler can modify the dictionary before returning, and the
+modified dictionary will be sent.
+
+In the event that %G_APPLICATION_HANDLES_COMMAND_LINE is not set,
+"normal processing" will treat the remaining uncollected command
+line arguments as filenames or URIs. If there are no arguments,
+the application is activated by g_application_activate(). One or
+more arguments results in a call to g_application_open().
+
+If you want to handle the local commandline arguments for yourself
+by converting them to calls to g_application_open() or
+g_action_group_activate_action() then you must be sure to register
+the application first. You should probably not call
+g_application_activate() for yourself, however: just return -1 and
+allow the default handler to do it for you. This will ensure that
+the `--gapplication-service` switch works properly (i.e. no activation
+in that case).
+
+Note that this signal is emitted from the default implementation of
+local_command_line(). If you override that function and don't
+chain up then this signal will never be emitted.
+
+You can override local_command_line() if you need more powerful
+capabilities than what is provided here, but this should not
+normally be required.
+
+ an exit code. If you have handled your options and want
+to exit the process, return a non-negative option, 0 for success,
+and a positive value for failure. To continue, return -1 to let
+the default option processing continue.
+
+
+
+
+ the options dictionary
+
+
+
+
+
+ The ::name-lost signal is emitted only on the registered primary instance
+when a new instance has taken over. This can only happen if the application
+is using the %G_APPLICATION_ALLOW_REPLACEMENT flag.
+
+The default handler for this signal calls g_application_quit().
+
+ %TRUE if the signal has been handled
+
+
+
+
+ The ::open signal is emitted on the primary instance when there are
+files to open. See g_application_open() for more information.
+
+
+
+
+
+ an array of #GFiles
+
+
+
+
+
+ the length of @files
+
+
+
+ a hint provided by the calling instance
+
+
+
+
+
+ The ::shutdown signal is emitted only on the registered primary instance
+immediately after the main loop terminates.
+
+
+
+
+
+ The ::startup signal is emitted on the primary instance immediately
+after registration. See g_application_register().
+
+
+
+
+
+
+ Virtual function table for #GApplication.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GApplication
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GApplication
+
+
+
+ an array of #GFiles to open
+
+
+
+
+
+ the length of the @files array
+
+
+
+ a hint (or ""), but never %NULL
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ %TRUE if the commandline has been completely handled
+
+
+
+
+ a #GApplication
+
+
+
+ array of command line arguments
+
+
+
+
+
+ exit status to fill after processing the command line.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #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
+local (ie: the current process is running in direct response to the
+invocation) or remote (ie: some other process forwarded the
+commandline to this process).
+
+The GApplicationCommandLine object can provide the @argc and @argv
+parameters for use with the #GOptionContext command-line parsing API,
+with the g_application_command_line_get_arguments() function. See
+[gapplication-example-cmdline3.c][gapplication-example-cmdline3]
+for an example.
+
+The exit status of the originally-invoked process may be set and
+messages can be printed to stdout or stderr of that process. The
+lifecycle of the originally-invoked process is tied to the lifecycle
+of this object (ie: the process exits when the last reference is
+dropped).
+
+The main use for #GApplicationCommandLine (and the
+#GApplication::command-line signal) is 'Emacs server' like use cases:
+You can set the `EDITOR` environment variable to have e.g. git use
+your favourite editor to edit commit messages, and if you already
+have an instance of the editor running, the editing will happen
+in the running instance, instead of opening a new one. An important
+aspect of this use case is that the process that gets started by git
+does not return until the editing is done.
+
+Normally, the commandline is completely handled in the
+#GApplication::command-line handler. The launching instance exits
+once the signal handler in the primary instance has returned, and
+the return value of the signal handler becomes the exit status
+of the launching instance.
+|[<!-- language="C" -->
+static int
+command_line (GApplication *application,
+ GApplicationCommandLine *cmdline)
+{
+ gchar **argv;
+ gint argc;
+ gint i;
+
+ argv = g_application_command_line_get_arguments (cmdline, &argc);
+
+ g_application_command_line_print (cmdline,
+ "This text is written back\n"
+ "to stdout of the caller\n");
+
+ for (i = 0; i < argc; i++)
+ g_print ("argument %d: %s\n", i, argv[i]);
+
+ g_strfreev (argv);
+
+ return 0;
+}
+]|
+The complete example can be found here:
+[gapplication-example-cmdline.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline.c)
+
+In more complicated cases, the handling of the commandline can be
+split between the launcher and the primary instance.
+|[<!-- language="C" -->
+static gboolean
+ test_local_cmdline (GApplication *application,
+ gchar ***arguments,
+ gint *exit_status)
+{
+ gint i, j;
+ gchar **argv;
+
+ argv = *arguments;
+
+ if (argv[0] == NULL)
+ {
+ *exit_status = 0;
+ return FALSE;
+ }
+
+ i = 1;
+ while (argv[i])
+ {
+ if (g_str_has_prefix (argv[i], "--local-"))
+ {
+ g_print ("handling argument %s locally\n", argv[i]);
+ g_free (argv[i]);
+ for (j = i; argv[j]; j++)
+ argv[j] = argv[j + 1];
+ }
+ else
+ {
+ g_print ("not handling argument %s locally\n", argv[i]);
+ i++;
+ }
+ }
+
+ *exit_status = 0;
+
+ return FALSE;
+}
+
+static void
+test_application_class_init (TestApplicationClass *class)
+{
+ G_APPLICATION_CLASS (class)->local_command_line = test_local_cmdline;
+
+ ...
+}
+]|
+In this example of split commandline handling, options that start
+with `--local-` are handled locally, all other options are passed
+to the #GApplication::command-line handler which runs in the primary
+instance.
+
+The complete example can be found here:
+[gapplication-example-cmdline2.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline2.c)
+
+If handling the commandline requires a lot of work, it may
+be better to defer it.
+|[<!-- language="C" -->
+static gboolean
+my_cmdline_handler (gpointer data)
+{
+ GApplicationCommandLine *cmdline = data;
+
+ // do the heavy lifting in an idle
+
+ g_application_command_line_set_exit_status (cmdline, 0);
+ g_object_unref (cmdline); // this releases the application
+
+ return G_SOURCE_REMOVE;
+}
+
+static int
+command_line (GApplication *application,
+ GApplicationCommandLine *cmdline)
+{
+ // keep the application running until we are done with this commandline
+ g_application_hold (application);
+
+ g_object_set_data_full (G_OBJECT (cmdline),
+ "application", application,
+ (GDestroyNotify)g_application_release);
+
+ g_object_ref (cmdline);
+ g_idle_add (my_cmdline_handler, cmdline);
+
+ return 0;
+}
+]|
+In this example the commandline is not completely handled before
+the #GApplication::command-line handler returns. Instead, we keep
+a reference to the #GApplicationCommandLine object and handle it
+later (in this example, in an idle). Note that it is necessary to
+hold the application until you are done with the commandline.
+
+The complete example can be found here:
+[gapplication-example-cmdline3.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline3.c)
+
+
+ Gets the stdin of the invoking process.
+
+The #GInputStream can be used to read data passed to the standard
+input of the invoking process.
+This doesn't work on all platforms. Presently, it is only available
+on UNIX when using a D-Bus daemon capable of passing file descriptors.
+If stdin is not available then %NULL will be returned. In the
+future, support may be expanded to other platforms.
+
+You must only call this function once per commandline invocation.
+
+
+ a #GInputStream for stdin
+
+
+
+
+ a #GApplicationCommandLine
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Creates a #GFile corresponding to a filename that was given as part
+of the invocation of @cmdline.
+
+This differs from g_file_new_for_commandline_arg() in that it
+resolves relative pathnames using the current working directory of
+the invoking process rather than the local process.
+
+
+ a new #GFile
+
+
+
+
+ a #GApplicationCommandLine
+
+
+
+ an argument from @cmdline
+
+
+
+
+
+ Gets the list of arguments that was passed on the command line.
+
+The strings in the array may contain non-UTF-8 data on UNIX (such as
+filenames or arguments given in the system locale) but are always in
+UTF-8 on Windows.
+
+If you wish to use the return value with #GOptionContext, you must
+use g_option_context_parse_strv().
+
+The return value is %NULL-terminated and should be freed using
+g_strfreev().
+
+
+
+ the string array containing the arguments (the argv)
+
+
+
+
+
+
+ a #GApplicationCommandLine
+
+
+
+ the length of the arguments array, or %NULL
+
+
+
+
+
+ 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.
+
+
+ the current directory, or %NULL
+
+
+
+
+ a #GApplicationCommandLine
+
+
+
+
+
+ Gets the contents of the 'environ' variable of the command line
+invocation, as would be returned by g_get_environ(), ie as a
+%NULL-terminated list of strings in the form 'NAME=VALUE'.
+The strings may contain non-utf8 data.
+
+The remote application usually does not send an environment. Use
+%G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag
+set it is possible that the environment is still not available (due
+to invocation messages from other applications).
+
+The return value should not be modified or freed and is valid for as
+long as @cmdline exists.
+
+See g_application_command_line_getenv() if you are only interested
+in the value of a single environment variable.
+
+
+
+ the environment strings, or %NULL if they were not sent
+
+
+
+
+
+
+ a #GApplicationCommandLine
+
+
+
+
+
+ Gets the exit status of @cmdline. See
+g_application_command_line_set_exit_status() for more information.
+
+
+ the exit status
+
+
+
+
+ a #GApplicationCommandLine
+
+
+
+
+
+ Determines if @cmdline represents a remote invocation.
+
+
+ %TRUE if the invocation was remote
+
+
+
+
+ a #GApplicationCommandLine
+
+
+
+
+
+ Gets the options that were passed to g_application_command_line().
+
+If you did not override local_command_line() then these are the same
+options that were parsed according to the #GOptionEntrys added to the
+application with g_application_add_main_option_entries() and possibly
+modified from your GApplication::handle-local-options handler.
+
+If no options were sent then an empty dictionary is returned so that
+you don't need to check for %NULL.
+
+The data has been passed via an untrusted external process, so the types of
+all values must be checked before being used.
+
+
+ a #GVariantDict with the options
+
+
+
+
+ a #GApplicationCommandLine
+
+
+
+
+
+ Gets the platform data associated with the invocation of @cmdline.
+
+This is a #GVariant dictionary containing information about the
+context in which the invocation occurred. It typically contains
+information like the current working directory and the startup
+notification ID.
+
+It comes from an untrusted external process and hence the types of all
+values must be validated before being used.
+
+For local invocation, it will be %NULL.
+
+
+ the platform data, or %NULL
+
+
+
+
+ #GApplicationCommandLine
+
+
+
+
+
+ Gets the stdin of the invoking process.
+
+The #GInputStream can be used to read data passed to the standard
+input of the invoking process.
+This doesn't work on all platforms. Presently, it is only available
+on UNIX when using a D-Bus daemon capable of passing file descriptors.
+If stdin is not available then %NULL will be returned. In the
+future, support may be expanded to other platforms.
+
+You must only call this function once per commandline invocation.
+
+
+ a #GInputStream for stdin
+
+
+
+
+ a #GApplicationCommandLine
+
+
+
+
+
+ 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.
+
+
+ the value of the variable, or %NULL if unset or unsent
+
+
+
+
+ a #GApplicationCommandLine
+
+
+
+ the environment variable to get
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+ a #GApplicationCommandLine
+
+
+
+ a printf-style format string
+
+
+
+ arguments, as per @format
+
+
+
+
+
+ Formats a message and prints it using the stderr print handler in the
+invoking process.
+
+If @cmdline is a local invocation then this is exactly equivalent to
+g_printerr(). If @cmdline is remote then this is equivalent to
+calling g_printerr() in the invoking process.
+
+
+
+
+
+
+ a #GApplicationCommandLine
+
+
+
+ a printf-style format string
+
+
+
+ arguments, as per @format
+
+
+
+
+
+ Sets the exit status that will be used when the invoking process
+exits.
+
+The return value of the #GApplication::command-line signal is
+passed to this function when the handler returns. This is the usual
+way of setting the exit status.
+
+In the event that you want the remote invocation to continue running
+and want to decide on the exit status in the future, you can use this
+call. For the case of a remote invocation, the remote process will
+typically exit when the last reference is dropped on @cmdline. The
+exit status of the remote process will be equal to the last value
+that was set with this function.
+
+In the case that the commandline invocation is local, the situation
+is slightly more complicated. If the commandline invocation results
+in the mainloop running (ie: because the use-count of the application
+increased to a non-zero value) then the application is considered to
+have been 'successful' in a certain sense, and the exit status is
+always zero. If the application use count is zero, though, the exit
+status of the local #GApplicationCommandLine is used.
+
+
+
+
+
+
+ a #GApplicationCommandLine
+
+
+
+ the exit status
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The #GApplicationCommandLineClass-struct
+contains private data only.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GInputStream for stdin
+
+
+
+
+ a #GApplicationCommandLine
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Flags used to define the behaviour of a #GApplication.
+
+ Default. Deprecated in 2.74, use
+ %G_APPLICATION_DEFAULT_FLAGS instead
+
+
+ Default flags. Since: 2.74
+
+
+ Run as a service. In this mode, registration
+ fails if the service is already running, and the application
+ will initially wait up to 10 seconds for an initial activation
+ message to arrive.
+
+
+ Don't try to become the primary instance.
+
+
+ This application handles opening files (in
+ the primary instance). Note that this flag only affects the default
+ implementation of local_command_line(), and has no effect if
+ %G_APPLICATION_HANDLES_COMMAND_LINE is given.
+ See g_application_run() for details.
+
+
+ This application handles command line
+ arguments (in the primary instance). Note that this flag only affect
+ the default implementation of local_command_line().
+ See g_application_run() for details.
+
+
+ Send the environment of the
+ launching process to the primary instance. Set this flag if your
+ application is expected to behave differently depending on certain
+ environment variables. For instance, an editor might be expected
+ to use the `GIT_COMMITTER_NAME` environment variable
+ when editing a git commit message. The environment is available
+ to the #GApplication::command-line signal handler, via
+ g_application_command_line_getenv().
+
+
+ Make no attempts to do any of the typical
+ single-instance application negotiation, even if the application
+ ID is given. The application neither attempts to become the
+ owner of the application ID nor does it check if an existing
+ owner already exists. Everything occurs in the local process.
+ Since: 2.30.
+
+
+ Allow users to override the
+ application ID from the command line with `--gapplication-app-id`.
+ Since: 2.48
+
+
+ Allow another instance to take over
+ the bus name. Since: 2.60
+
+
+ Take over from another instance. This flag is
+ usually set by passing `--gapplication-replace` on the commandline.
+ Since: 2.60
+
+
+
+
+
+
+ #GAskPasswordFlags are used to request specific information from the
+user, or to notify the user of their choices in an authentication
+situation.
+
+ operation requires a password.
+
+
+ operation requires a username.
+
+
+ operation requires a domain.
+
+
+ operation supports saving settings.
+
+
+ operation supports anonymous users.
+
+
+ operation takes TCRYPT parameters (Since: 2.58)
+
+
+
+ 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:
+
+|[<!-- language="C" -->
+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)
+ {
+ GTask *task = l->data;
+
+ if (self->priv->success)
+ g_task_return_boolean (task, TRUE);
+ else
+ g_task_return_new_error (task, ...);
+ g_object_unref (task);
+ }
+
+ g_list_free (self->priv->init_results);
+ 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);
+ GTask *task;
+
+ task = g_task_new (initable, cancellable, callback, user_data);
+ g_task_set_name (task, G_STRFUNC);
+
+ switch (self->priv->state)
+ {
+ case NOT_INITIALIZED:
+ _foo_get_ready (self);
+ self->priv->init_results = g_list_append (self->priv->init_results,
+ task);
+ self->priv->state = INITIALIZING;
+ break;
+ case INITIALIZING:
+ self->priv->init_results = g_list_append (self->priv->init_results,
+ task);
+ break;
+ case INITIALIZED:
+ if (!self->priv->success)
+ g_task_return_new_error (task, ...);
+ else
+ g_task_return_boolean (task, TRUE);
+ g_object_unref (task);
+ break;
+ }
+}
+
+static gboolean
+foo_init_finish (GAsyncInitable *initable,
+ GAsyncResult *result,
+ GError **error)
+{
+ g_return_val_if_fail (g_task_is_valid (result, initable), FALSE);
+
+ return g_task_propagate_boolean (G_TASK (result), error);
+}
+
+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;
+}
+]|
+
+
+ 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.
+
+
+
+
+
+
+ a #GType supporting #GAsyncInitable.
+
+
+
+ the [I/O priority][io-priority] of the operation
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback to call when the initialization is
+ finished
+
+
+
+ the data to pass to callback function
+
+
+
+ the name of the first property, or %NULL if no
+ properties
+
+
+
+ the value of the first property, followed by other property
+ value pairs, and ended by %NULL.
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+ a #GType supporting #GAsyncInitable.
+
+
+
+ the name of the first property, followed by
+the value, and other property value pairs, and ended by %NULL.
+
+
+
+ The var args list generated from @first_property_name.
+
+
+
+ the [I/O priority][io-priority] of the operation
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback to call when the initialization is
+ finished
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Helper function for constructing #GAsyncInitable object. This is
+similar to g_object_newv() but also initializes the object asynchronously.
+
+When the initialization is finished, @callback will be called. You can
+then call g_async_initable_new_finish() to get the new object and check
+for any errors.
+ Use g_object_new_with_properties() and
+g_async_initable_init_async() instead. See #GParameter for more information.
+
+
+
+
+
+
+ a #GType supporting #GAsyncInitable.
+
+
+
+ the number of parameters in @parameters
+
+
+
+ the parameters to use to construct the object
+
+
+
+ the [I/O priority][io-priority] of the operation
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback to call when the initialization is
+ finished
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Starts asynchronous initialization of the object implementing the
+interface. This must be done before any real use of the object after
+initial construction. If the object also implements #GInitable you can
+optionally call g_initable_init() instead.
+
+This method is intended for language bindings. If writing in C,
+g_async_initable_new_async() should typically be used instead.
+
+When the initialization is finished, @callback will be called. You can
+then call g_async_initable_init_finish() to get the result of the
+initialization.
+
+Implementations may also support cancellation. If @cancellable is not
+%NULL, then initialization can be cancelled by triggering the cancellable
+object from another thread. If the operation was cancelled, the error
+%G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL, and
+the object doesn't support cancellable initialization, the error
+%G_IO_ERROR_NOT_SUPPORTED will be returned.
+
+As with #GInitable, if the object is not initialized, or initialization
+returns with an error, then all operations on the object except
+g_object_ref() and g_object_unref() are considered to be invalid, and
+have undefined behaviour. They will often fail with g_critical() or
+g_warning(), but this must not be relied on.
+
+Callers should not assume that a class which implements #GAsyncInitable can
+be initialized multiple times; for more information, see g_initable_init().
+If a class explicitly supports being initialized multiple times,
+implementation requires yielding all subsequent calls to init_async() on the
+results of the first call.
+
+For classes that also support the #GInitable interface, the default
+implementation of this method will run the g_initable_init() function
+in a thread, so if you want to support asynchronous initialization via
+threads, just implement the #GAsyncInitable interface without overriding
+any interface methods.
+
+
+
+
+
+
+ a #GAsyncInitable.
+
+
+
+ the [I/O priority][io-priority] of the operation
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes asynchronous initialization and returns the result.
+See g_async_initable_init_async().
+
+
+ %TRUE if successful. If an error has occurred, this function
+will return %FALSE and set @error appropriately if present.
+
+
+
+
+ a #GAsyncInitable.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Starts asynchronous initialization of the object implementing the
+interface. This must be done before any real use of the object after
+initial construction. If the object also implements #GInitable you can
+optionally call g_initable_init() instead.
+
+This method is intended for language bindings. If writing in C,
+g_async_initable_new_async() should typically be used instead.
+
+When the initialization is finished, @callback will be called. You can
+then call g_async_initable_init_finish() to get the result of the
+initialization.
+
+Implementations may also support cancellation. If @cancellable is not
+%NULL, then initialization can be cancelled by triggering the cancellable
+object from another thread. If the operation was cancelled, the error
+%G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL, and
+the object doesn't support cancellable initialization, the error
+%G_IO_ERROR_NOT_SUPPORTED will be returned.
+
+As with #GInitable, if the object is not initialized, or initialization
+returns with an error, then all operations on the object except
+g_object_ref() and g_object_unref() are considered to be invalid, and
+have undefined behaviour. They will often fail with g_critical() or
+g_warning(), but this must not be relied on.
+
+Callers should not assume that a class which implements #GAsyncInitable can
+be initialized multiple times; for more information, see g_initable_init().
+If a class explicitly supports being initialized multiple times,
+implementation requires yielding all subsequent calls to init_async() on the
+results of the first call.
+
+For classes that also support the #GInitable interface, the default
+implementation of this method will run the g_initable_init() function
+in a thread, so if you want to support asynchronous initialization via
+threads, just implement the #GAsyncInitable interface without overriding
+any interface methods.
+
+
+
+
+
+
+ a #GAsyncInitable.
+
+
+
+ the [I/O priority][io-priority] of the operation
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes asynchronous initialization and returns the result.
+See g_async_initable_init_async().
+
+
+ %TRUE if successful. If an error has occurred, this function
+will return %FALSE and set @error appropriately if present.
+
+
+
+
+ a #GAsyncInitable.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Finishes the async construction for the various g_async_initable_new
+calls, returning the created object or %NULL on error.
+
+
+ a newly created #GObject,
+ or %NULL on error. Free with g_object_unref().
+
+
+
+
+ the #GAsyncInitable from the callback
+
+
+
+ the #GAsyncResult from the callback
+
+
+
+
+
+
+ Provides an interface for asynchronous initializing object such that
+initialization may fail.
+
+
+ The parent interface.
+
+
+
+
+
+
+
+
+
+
+ a #GAsyncInitable.
+
+
+
+ the [I/O priority][io-priority] of the operation
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ %TRUE if successful. If an error has occurred, this function
+will return %FALSE and set @error appropriately if present.
+
+
+
+
+ a #GAsyncInitable.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+ Type definition for a function that will be called back when an asynchronous
+operation within GIO has been completed. #GAsyncReadyCallback
+callbacks from #GTask are guaranteed to be invoked in a later
+iteration of the
+[thread-default main context][g-main-context-push-thread-default]
+where the #GTask was created. All other users of
+#GAsyncReadyCallback must likewise call it asynchronously in a
+later iteration of the main context.
+
+The asynchronous operation is guaranteed to have held a reference to
+@source_object from the time when the `*_async()` function was called, until
+after this callback returns.
+
+
+
+
+
+
+ the object the asynchronous operation was started with.
+
+
+
+ a #GAsyncResult.
+
+
+
+ user data passed to the callback.
+
+
+
+
+
+ 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 must be run in a later iteration of
+the [thread-default main context][g-main-context-push-thread-default]
+from where the operation was initiated. It 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. You can pass
+%NULL for the #GAsyncReadyCallback if you don't need to take any
+action at all after the operation completes. Applications may also
+take a reference to the #GAsyncResult and call "_finish()" later;
+however, the "_finish()" function may be called at most once.
+
+Example of a typical asynchronous operation flow:
+|[<!-- language="C" -->
+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.
+
+## I/O Priority # {#io-priority}
+
+Many I/O-related asynchronous operations have a priority parameter,
+which is used in certain cases to determine the order in which
+operations are executed. They are not used to determine system-wide
+I/O scheduling. Priorities are integers, with lower numbers indicating
+higher priority. It is recommended to choose priorities between
+%G_PRIORITY_LOW and %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT
+as a default.
+
+
+ Gets the source object from a #GAsyncResult.
+
+
+ a new reference to the source
+ object for the @res, or %NULL if there is none.
+
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Gets the user data from a #GAsyncResult.
+
+
+ the user data for @res.
+
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Checks if @res has the given @source_tag (generally a function
+pointer indicating the function @res was created by).
+
+
+ %TRUE if @res has the indicated @source_tag, %FALSE if
+ not.
+
+
+
+
+ a #GAsyncResult
+
+
+
+ an application-defined tag
+
+
+
+
+
+ Gets the source object from a #GAsyncResult.
+
+
+ a new reference to the source
+ object for the @res, or %NULL if there is none.
+
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Gets the user data from a #GAsyncResult.
+
+
+ the user data for @res.
+
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Checks if @res has the given @source_tag (generally a function
+pointer indicating the function @res was created by).
+
+
+ %TRUE if @res has the indicated @source_tag, %FALSE if
+ not.
+
+
+
+
+ a #GAsyncResult
+
+
+
+ an application-defined tag
+
+
+
+
+
+ If @res is a #GSimpleAsyncResult, this is equivalent to
+g_simple_async_result_propagate_error(). Otherwise it returns
+%FALSE.
+
+This can be used for legacy error handling in async *_finish()
+wrapper functions that traditionally handled #GSimpleAsyncResult
+error returns themselves rather than calling into the virtual method.
+This should not be used in new code; #GAsyncResult errors that are
+set by virtual methods should also be extracted by virtual methods,
+to enable subclasses to chain up correctly.
+
+
+ %TRUE if @error is has been filled in with an error from
+ @res, %FALSE if not.
+
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+ Interface definition for #GAsyncResult.
+
+
+ The parent interface.
+
+
+
+
+
+
+ the user data for @res.
+
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+ a new reference to the source
+ object for the @res, or %NULL if there is none.
+
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+ %TRUE if @res has the indicated @source_tag, %FALSE if
+ not.
+
+
+
+
+ a #GAsyncResult
+
+
+
+ an application-defined tag
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+
+
+ Creates a new #GInputStream from the given @base_stream, with
+a buffer set to the default size (4 kilobytes).
+
+
+ a #GInputStream for the given @base_stream.
+
+
+
+
+ a #GInputStream
+
+
+
+
+
+ Creates a new #GBufferedInputStream from the given @base_stream,
+with a buffer set to @size.
+
+
+ a #GInputStream.
+
+
+
+
+ a #GInputStream
+
+
+
+ a #gsize
+
+
+
+
+
+ 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().
+
+
+ the number of bytes read into @stream's buffer, up to @count,
+ or -1 on error.
+
+
+
+
+ a #GBufferedInputStream
+
+
+
+ the number of bytes that will be read from the stream
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+
+
+ Reads data into @stream's buffer asynchronously, up to @count size.
+@io_priority can be used to prioritize reads. For the synchronous
+version of this function, see g_buffered_input_stream_fill().
+
+If @count is -1 then the attempted read size is equal to the number
+of bytes that are required to fill the buffer.
+
+
+
+
+
+
+ a #GBufferedInputStream
+
+
+
+ the number of bytes that will be read from the stream
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object
+
+
+
+ a #GAsyncReadyCallback
+
+
+
+ a #gpointer
+
+
+
+
+
+ Finishes an asynchronous read.
+
+
+ a #gssize of the read stream, or `-1` on an error.
+
+
+
+
+ a #GBufferedInputStream
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ 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().
+
+
+ the number of bytes read into @stream's buffer, up to @count,
+ or -1 on error.
+
+
+
+
+ a #GBufferedInputStream
+
+
+
+ the number of bytes that will be read from the stream
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+
+
+ Reads data into @stream's buffer asynchronously, up to @count size.
+@io_priority can be used to prioritize reads. For the synchronous
+version of this function, see g_buffered_input_stream_fill().
+
+If @count is -1 then the attempted read size is equal to the number
+of bytes that are required to fill the buffer.
+
+
+
+
+
+
+ a #GBufferedInputStream
+
+
+
+ the number of bytes that will be read from the stream
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object
+
+
+
+ a #GAsyncReadyCallback
+
+
+
+ a #gpointer
+
+
+
+
+
+ Finishes an asynchronous read.
+
+
+ a #gssize of the read stream, or `-1` on an error.
+
+
+
+
+ a #GBufferedInputStream
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Gets the size of the available data within the stream.
+
+
+ size of the available stream.
+
+
+
+
+ #GBufferedInputStream
+
+
+
+
+
+ Gets the size of the input buffer.
+
+
+ the current buffer size.
+
+
+
+
+ a #GBufferedInputStream
+
+
+
+
+
+ Peeks in the buffer, copying data of size @count into @buffer,
+offset @offset bytes.
+
+
+ a #gsize of the number of bytes peeked, or -1 on error.
+
+
+
+
+ a #GBufferedInputStream
+
+
+
+ a pointer to
+ an allocated chunk of memory
+
+
+
+
+
+ a #gsize
+
+
+
+ a #gsize
+
+
+
+
+
+ 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
+
+
+
+
+
+
+ a #GBufferedInputStream
+
+
+
+ a #gsize to get the number of bytes available in the buffer
+
+
+
+
+
+ Tries to read a single byte from the stream or the buffer. Will block
+during this read.
+
+On success, the byte read from the stream is returned. On end of stream
+-1 is returned but it's not an exceptional error and @error is not set.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
+operation was partially finished when the operation was cancelled the
+partial result will be returned, without an error.
+
+On error -1 is returned and @error is set accordingly.
+
+
+ the byte read from the @stream, or -1 on end of stream or error.
+
+
+
+
+ a #GBufferedInputStream
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+
+
+ Sets the size of the internal buffer of @stream to @size, or to the
+size of the contents of the buffer. The buffer can never be resized
+smaller than its current contents.
+
+
+
+
+
+
+ a #GBufferedInputStream
+
+
+
+ a #gsize
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ the number of bytes read into @stream's buffer, up to @count,
+ or -1 on error.
+
+
+
+
+ a #GBufferedInputStream
+
+
+
+ the number of bytes that will be read from the stream
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GBufferedInputStream
+
+
+
+ the number of bytes that will be read from the stream
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object
+
+
+
+ a #GAsyncReadyCallback
+
+
+
+ a #gpointer
+
+
+
+
+
+
+
+
+
+ a #gssize of the read stream, or `-1` on an error.
+
+
+
+
+ a #GBufferedInputStream
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+
+
+ Creates a new buffered output stream for a base stream.
+
+
+ a #GOutputStream for the given @base_stream.
+
+
+
+
+ a #GOutputStream.
+
+
+
+
+
+ Creates a new buffered output stream with a given buffer size.
+
+
+ a #GOutputStream with an internal buffer set to @size.
+
+
+
+
+ a #GOutputStream.
+
+
+
+ a #gsize.
+
+
+
+
+
+ Checks if the buffer automatically grows as data is added.
+
+
+ %TRUE if the @stream's buffer automatically grows,
+%FALSE otherwise.
+
+
+
+
+ a #GBufferedOutputStream.
+
+
+
+
+
+ Gets the size of the buffer in the @stream.
+
+
+ the current size of the buffer.
+
+
+
+
+ a #GBufferedOutputStream.
+
+
+
+
+
+ Sets whether or not the @stream's buffer should automatically grow.
+If @auto_grow is true, then each write will just make the buffer
+larger, and you must manually flush the buffer to actually write out
+the data to the underlying stream.
+
+
+
+
+
+
+ a #GBufferedOutputStream.
+
+
+
+ a #gboolean.
+
+
+
+
+
+ Sets the size of the internal buffer to @size.
+
+
+
+
+
+
+ a #GBufferedOutputStream.
+
+
+
+ a #gsize.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Invoked when a connection to a message bus has been obtained.
+
+
+
+
+
+
+ The #GDBusConnection to a message bus.
+
+
+
+ The name that is requested to be owned.
+
+
+
+ User data passed to g_bus_own_name().
+
+
+
+
+
+ Invoked when the name is acquired.
+
+
+
+
+
+
+ The #GDBusConnection on which to acquired the name.
+
+
+
+ The name being owned.
+
+
+
+ User data passed to g_bus_own_name() or g_bus_own_name_on_connection().
+
+
+
+
+
+ Invoked when the name being watched is known to have to have an owner.
+
+
+
+
+
+
+ The #GDBusConnection the name is being watched on.
+
+
+
+ The name being watched.
+
+
+
+ Unique name of the owner of the name being watched.
+
+
+
+ User data passed to g_bus_watch_name().
+
+
+
+
+
+ Invoked when the name is lost or @connection has been closed.
+
+
+
+
+
+
+ The #GDBusConnection on which to acquire the name or %NULL if
+the connection was disconnected.
+
+
+
+ The name being owned.
+
+
+
+ User data passed to g_bus_own_name() or g_bus_own_name_on_connection().
+
+
+
+
+
+ Flags used in g_bus_own_name().
+
+ No flags set.
+
+
+ Allow another message bus connection to claim the name.
+
+
+ If another message bus connection owns the name and have
+specified %G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT, then take the name from the other connection.
+
+
+ If another message bus connection owns the name, immediately
+return an error from g_bus_own_name() rather than entering the waiting queue for that name. (Since 2.54)
+
+
+
+ Invoked when the name being watched is known not to have to have an owner.
+
+This is also invoked when the #GDBusConnection on which the watch was
+established has been closed. In that case, @connection will be
+%NULL.
+
+
+
+
+
+
+ The #GDBusConnection the name is being watched on, or
+ %NULL.
+
+
+
+ The name being watched.
+
+
+
+ User data passed to g_bus_watch_name().
+
+
+
+
+
+ Flags used in g_bus_watch_name().
+
+ No flags set.
+
+
+ If no-one owns the name when
+beginning to watch the name, ask the bus to launch an owner for the
+name.
+
+
+
+ An enumeration for well-known message buses.
+
+ An alias for the message bus that activated the process, if any.
+
+
+ Not a message bus.
+
+
+ The system-wide message bus.
+
+
+ The login session message bus.
+
+
+
+ #GBytesIcon specifies an image held in memory in a common format (usually
+png) to be used as icon.
+
+
+
+ Creates a new icon for a bytes.
+
+This cannot fail, but loading and interpreting the bytes may fail later on
+(for example, if g_loadable_icon_load() is called) if the image is invalid.
+
+
+ a #GIcon for the given
+ @bytes.
+
+
+
+
+ a #GBytes.
+
+
+
+
+
+ Gets the #GBytes associated with the given @icon.
+
+
+ a #GBytes.
+
+
+
+
+ a #GIcon.
+
+
+
+
+
+ The bytes containing the icon.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ GCancellable is a thread-safe operation cancellation stack used
+throughout GIO to allow for cancellation of synchronous and
+asynchronous operations.
+
+
+ Creates a new #GCancellable object.
+
+Applications that want to start one or more operations
+that should be cancellable should create a #GCancellable
+and pass it to the operations.
+
+One #GCancellable can be used in multiple consecutive
+operations or in multiple concurrent operations.
+
+
+ a #GCancellable.
+
+
+
+
+ Gets the top cancellable from the stack.
+
+
+ a #GCancellable from the top
+of the stack, or %NULL if the stack is empty.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Will set @cancellable to cancelled, and will emit the
+#GCancellable::cancelled signal. (However, see the warning about
+race conditions in the documentation for that signal if you are
+planning to connect to it.)
+
+This function is thread-safe. In other words, you can safely call
+it from a thread other than the one running the operation that was
+passed the @cancellable.
+
+If @cancellable is %NULL, this function returns immediately for convenience.
+
+The convention within GIO is that cancelling an asynchronous
+operation causes it to complete asynchronously. That is, if you
+cancel the operation from the same thread in which it is running,
+then the operation's #GAsyncReadyCallback will not be invoked until
+the application returns to the main loop.
+
+
+
+
+
+
+ a #GCancellable object.
+
+
+
+
+
+ Convenience function to connect to the #GCancellable::cancelled
+signal. Also handles the race condition that may happen
+if the cancellable is cancelled right before connecting.
+
+@callback is called at most once, either directly at the
+time of the connect if @cancellable is already cancelled,
+or when @cancellable is cancelled in some thread.
+
+@data_destroy_func will be called when the handler is
+disconnected, or immediately if the cancellable is already
+cancelled.
+
+See #GCancellable::cancelled for details on how to use this.
+
+Since GLib 2.40, the lock protecting @cancellable is not held when
+@callback is invoked. This lifts a restriction in place for
+earlier GLib versions which now makes it easier to write cleanup
+code that unconditionally invokes e.g. g_cancellable_cancel().
+
+
+ The id of the signal handler or 0 if @cancellable has already
+ been cancelled.
+
+
+
+
+ A #GCancellable.
+
+
+
+ The #GCallback to connect.
+
+
+
+ Data to pass to @callback.
+
+
+
+ Free function for @data or %NULL.
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+ A #GCancellable or %NULL.
+
+
+
+ Handler id of the handler to be disconnected, or `0`.
+
+
+
+
+
+ Gets the file descriptor for a cancellable job. This can be used to
+implement cancellable operations on Unix systems. The returned fd will
+turn readable when @cancellable is cancelled.
+
+You are not supposed to read from the fd yourself, just check for
+readable status. Reading to unset the readable status is done
+with g_cancellable_reset().
+
+After a successful return from this function, you should use
+g_cancellable_release_fd() to free up resources allocated for
+the returned file descriptor.
+
+See also g_cancellable_make_pollfd().
+
+
+ A valid file descriptor. `-1` if the file descriptor
+is not supported, or on errors.
+
+
+
+
+ a #GCancellable.
+
+
+
+
+
+ Checks if a cancellable job has been cancelled.
+
+
+ %TRUE if @cancellable is cancelled,
+FALSE if called with %NULL or if item is not cancelled.
+
+
+
+
+ a #GCancellable or %NULL
+
+
+
+
+
+ Creates a #GPollFD corresponding to @cancellable; this can be passed
+to g_poll() and used to poll for cancellation. This is useful both
+for unix systems without a native poll and for portability to
+windows.
+
+When this function returns %TRUE, you should use
+g_cancellable_release_fd() to free up resources allocated for the
+@pollfd. After a %FALSE return, do not call g_cancellable_release_fd().
+
+If this function returns %FALSE, either no @cancellable was given or
+resource limits prevent this function from allocating the necessary
+structures for polling. (On Linux, you will likely have reached
+the maximum number of file descriptors.) The suggested way to handle
+these cases is to ignore the @cancellable.
+
+You are not supposed to read from the fd yourself, just check for
+readable status. Reading to unset the readable status is done
+with g_cancellable_reset().
+
+
+ %TRUE if @pollfd was successfully initialized, %FALSE on
+ failure to prepare the cancellable.
+
+
+
+
+ a #GCancellable or %NULL
+
+
+
+ a pointer to a #GPollFD
+
+
+
+
+
+ Pops @cancellable off the cancellable stack (verifying that @cancellable
+is on the top of the stack).
+
+
+
+
+
+
+ a #GCancellable object
+
+
+
+
+
+ Pushes @cancellable onto the cancellable stack. The current
+cancellable can then be received using g_cancellable_get_current().
+
+This is useful when implementing cancellable operations in
+code that does not allow you to pass down the cancellable object.
+
+This is typically called automatically by e.g. #GFile operations,
+so you rarely have to call this yourself.
+
+
+
+
+
+
+ a #GCancellable object
+
+
+
+
+
+ Releases a resources previously allocated by g_cancellable_get_fd()
+or g_cancellable_make_pollfd().
+
+For compatibility reasons with older releases, calling this function
+is not strictly required, the resources will be automatically freed
+when the @cancellable is finalized. However, the @cancellable will
+block scarce file descriptors until it is finalized if this function
+is not called. This can cause the application to run out of file
+descriptors when many #GCancellables are used at the same time.
+
+
+
+
+
+
+ a #GCancellable
+
+
+
+
+
+ Resets @cancellable to its uncancelled state.
+
+If cancellable is currently in use by any cancellable operation
+then the behavior of this function is undefined.
+
+Note that it is generally not a good idea to reuse an existing
+cancellable for more operations after it has been cancelled once,
+as this function might tempt you to do. The recommended practice
+is to drop the reference to a cancellable after cancelling it,
+and let it die with the outstanding async operations. You should
+create a fresh cancellable for further async operations.
+
+
+
+
+
+
+ a #GCancellable object.
+
+
+
+
+
+ If the @cancellable is cancelled, sets the error to notify
+that the operation was cancelled.
+
+
+ %TRUE if @cancellable was cancelled, %FALSE if it was not
+
+
+
+
+ a #GCancellable or %NULL
+
+
+
+
+
+ Creates a source that triggers if @cancellable is cancelled and
+calls its callback of type #GCancellableSourceFunc. This is
+primarily useful for attaching to another (non-cancellable) source
+with g_source_add_child_source() to add cancellability to it.
+
+For convenience, you can call this with a %NULL #GCancellable,
+in which case the source will never trigger.
+
+The new #GSource will hold a reference to the #GCancellable.
+
+
+ the new #GSource.
+
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+
+
+
+
+
+
+ Emitted when the operation has been cancelled.
+
+Can be used by implementations of cancellable operations. If the
+operation is cancelled from another thread, the signal will be
+emitted in the thread that cancelled the operation, not the
+thread that is running the operation.
+
+Note that disconnecting from this signal (or any signal) in a
+multi-threaded program is prone to race conditions. For instance
+it is possible that a signal handler may be invoked even after
+a call to g_signal_handler_disconnect() for that handler has
+already returned.
+
+There is also a problem when cancellation happens right before
+connecting to the signal. If this happens the signal will
+unexpectedly not be emitted, and checking before connecting to
+the signal leaves a race condition where this is still happening.
+
+In order to make it safe and easy to connect handlers there
+are two helper functions: g_cancellable_connect() and
+g_cancellable_disconnect() which protect against problems
+like this.
+
+An example of how to us this:
+|[<!-- language="C" -->
+ // Make sure we don't do unnecessary work if already cancelled
+ if (g_cancellable_set_error_if_cancelled (cancellable, error))
+ return;
+
+ // Set up all the data needed to be able to handle cancellation
+ // of the operation
+ my_data = my_data_new (...);
+
+ id = 0;
+ if (cancellable)
+ id = g_cancellable_connect (cancellable,
+ G_CALLBACK (cancelled_handler)
+ data, NULL);
+
+ // cancellable operation here...
+
+ g_cancellable_disconnect (cancellable, id);
+
+ // cancelled_handler is never called after this, it is now safe
+ // to free the data
+ my_data_free (my_data);
+]|
+
+Note that the cancelled signal is emitted in the thread that
+the user cancelled from, which may be the main thread. So, the
+cancellable signal should not do something that can block.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This is the function type of the callback used for the #GSource
+returned by g_cancellable_source_new().
+
+
+ it should return %FALSE if the source should be removed.
+
+
+
+
+ the #GCancellable
+
+
+
+ data passed in by the user.
+
+
+
+
+
+ #GCharsetConverter is an implementation of #GConverter based on
+GIConv.
+
+
+
+
+ Creates a new #GCharsetConverter.
+
+
+ a new #GCharsetConverter or %NULL on error.
+
+
+
+
+ destination charset
+
+
+
+ source charset
+
+
+
+
+
+ Gets the number of fallbacks that @converter has applied so far.
+
+
+ the number of fallbacks that @converter has applied
+
+
+
+
+ a #GCharsetConverter
+
+
+
+
+
+ Gets the #GCharsetConverter:use-fallback property.
+
+
+ %TRUE if fallbacks are used by @converter
+
+
+
+
+ a #GCharsetConverter
+
+
+
+
+
+ Sets the #GCharsetConverter:use-fallback property.
+
+
+
+
+
+
+ a #GCharsetConverter
+
+
+
+ %TRUE to use fallbacks
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #GConverter is implemented by objects that convert
+binary data in various ways. The conversion can be
+stateful and may fail at any place.
+
+Some example conversions are: character set conversion,
+compression, decompression and regular expression
+replace.
+
+
+ This is the main operation used when converting data. It is to be called
+multiple times in a loop, and each time it will do some work, i.e.
+producing some output (in @outbuf) or consuming some input (from @inbuf) or
+both. If its not possible to do any work an error is returned.
+
+Note that a single call may not consume all input (or any input at all).
+Also a call may produce output even if given no input, due to state stored
+in the converter producing output.
+
+If any data was either produced or consumed, and then an error happens, then
+only the successful conversion is reported and the error is returned on the
+next call.
+
+A full conversion loop involves calling this method repeatedly, each time
+giving it new input and space output space. When there is no more input
+data after the data in @inbuf, the flag %G_CONVERTER_INPUT_AT_END must be set.
+The loop will be (unless some error happens) returning %G_CONVERTER_CONVERTED
+each time until all data is consumed and all output is produced, then
+%G_CONVERTER_FINISHED is returned instead. Note, that %G_CONVERTER_FINISHED
+may be returned even if %G_CONVERTER_INPUT_AT_END is not set, for instance
+in a decompression converter where the end of data is detectable from the
+data (and there might even be other data after the end of the compressed data).
+
+When some data has successfully been converted @bytes_read and is set to
+the number of bytes read from @inbuf, and @bytes_written is set to indicate
+how many bytes was written to @outbuf. If there are more data to output
+or consume (i.e. unless the %G_CONVERTER_INPUT_AT_END is specified) then
+%G_CONVERTER_CONVERTED is returned, and if no more data is to be output
+then %G_CONVERTER_FINISHED is returned.
+
+On error %G_CONVERTER_ERROR is returned and @error is set accordingly.
+Some errors need special handling:
+
+%G_IO_ERROR_NO_SPACE is returned if there is not enough space
+to write the resulting converted data, the application should
+call the function again with a larger @outbuf to continue.
+
+%G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough
+input to fully determine what the conversion should produce,
+and the %G_CONVERTER_INPUT_AT_END flag is not set. This happens for
+example with an incomplete multibyte sequence when converting text,
+or when a regexp matches up to the end of the input (and may match
+further input). It may also happen when @inbuf_size is zero and
+there is no more data to produce.
+
+When this happens the application should read more input and then
+call the function again. If further input shows that there is no
+more data call the function again with the same data but with
+the %G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion
+to finish as e.g. in the regexp match case (or, to fail again with
+%G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the
+input is actually partial).
+
+After g_converter_convert() has returned %G_CONVERTER_FINISHED the
+converter object is in an invalid state where its not allowed
+to call g_converter_convert() anymore. At this time you can only
+free the object or call g_converter_reset() to reset it to the
+initial state.
+
+If the flag %G_CONVERTER_FLUSH is set then conversion is modified
+to try to write out all internal state to the output. The application
+has to call the function multiple times with the flag set, and when
+the available input has been consumed and all internal state has
+been produced then %G_CONVERTER_FLUSHED (or %G_CONVERTER_FINISHED if
+really at the end) is returned instead of %G_CONVERTER_CONVERTED.
+This is somewhat similar to what happens at the end of the input stream,
+but done in the middle of the data.
+
+This has different meanings for different conversions. For instance
+in a compression converter it would mean that we flush all the
+compression state into output such that if you uncompress the
+compressed data you get back all the input data. Doing this may
+make the final file larger due to padding though. Another example
+is a regexp conversion, where if you at the end of the flushed data
+have a match, but there is also a potential longer match. In the
+non-flushed case we would ask for more input, but when flushing we
+treat this as the end of input and do the match.
+
+Flushing is not always possible (like if a charset converter flushes
+at a partial multibyte sequence). Converters are supposed to try
+to produce as much output as possible and then return an error
+(typically %G_IO_ERROR_PARTIAL_INPUT).
+
+
+ a #GConverterResult, %G_CONVERTER_ERROR on error.
+
+
+
+
+ a #GConverter.
+
+
+
+ the buffer
+ containing the data to convert.
+
+
+
+
+
+ the number of bytes in @inbuf
+
+
+
+ a
+ buffer to write converted data in.
+
+
+
+
+
+ the number of bytes in @outbuf, must be at least one
+
+
+
+ a #GConverterFlags controlling the conversion details
+
+
+
+ will be set to the number of bytes read
+ from @inbuf on success
+
+
+
+ will be set to the number of bytes
+ written to @outbuf on success
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+ a #GConverter.
+
+
+
+
+
+ This is the main operation used when converting data. It is to be called
+multiple times in a loop, and each time it will do some work, i.e.
+producing some output (in @outbuf) or consuming some input (from @inbuf) or
+both. If its not possible to do any work an error is returned.
+
+Note that a single call may not consume all input (or any input at all).
+Also a call may produce output even if given no input, due to state stored
+in the converter producing output.
+
+If any data was either produced or consumed, and then an error happens, then
+only the successful conversion is reported and the error is returned on the
+next call.
+
+A full conversion loop involves calling this method repeatedly, each time
+giving it new input and space output space. When there is no more input
+data after the data in @inbuf, the flag %G_CONVERTER_INPUT_AT_END must be set.
+The loop will be (unless some error happens) returning %G_CONVERTER_CONVERTED
+each time until all data is consumed and all output is produced, then
+%G_CONVERTER_FINISHED is returned instead. Note, that %G_CONVERTER_FINISHED
+may be returned even if %G_CONVERTER_INPUT_AT_END is not set, for instance
+in a decompression converter where the end of data is detectable from the
+data (and there might even be other data after the end of the compressed data).
+
+When some data has successfully been converted @bytes_read and is set to
+the number of bytes read from @inbuf, and @bytes_written is set to indicate
+how many bytes was written to @outbuf. If there are more data to output
+or consume (i.e. unless the %G_CONVERTER_INPUT_AT_END is specified) then
+%G_CONVERTER_CONVERTED is returned, and if no more data is to be output
+then %G_CONVERTER_FINISHED is returned.
+
+On error %G_CONVERTER_ERROR is returned and @error is set accordingly.
+Some errors need special handling:
+
+%G_IO_ERROR_NO_SPACE is returned if there is not enough space
+to write the resulting converted data, the application should
+call the function again with a larger @outbuf to continue.
+
+%G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough
+input to fully determine what the conversion should produce,
+and the %G_CONVERTER_INPUT_AT_END flag is not set. This happens for
+example with an incomplete multibyte sequence when converting text,
+or when a regexp matches up to the end of the input (and may match
+further input). It may also happen when @inbuf_size is zero and
+there is no more data to produce.
+
+When this happens the application should read more input and then
+call the function again. If further input shows that there is no
+more data call the function again with the same data but with
+the %G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion
+to finish as e.g. in the regexp match case (or, to fail again with
+%G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the
+input is actually partial).
+
+After g_converter_convert() has returned %G_CONVERTER_FINISHED the
+converter object is in an invalid state where its not allowed
+to call g_converter_convert() anymore. At this time you can only
+free the object or call g_converter_reset() to reset it to the
+initial state.
+
+If the flag %G_CONVERTER_FLUSH is set then conversion is modified
+to try to write out all internal state to the output. The application
+has to call the function multiple times with the flag set, and when
+the available input has been consumed and all internal state has
+been produced then %G_CONVERTER_FLUSHED (or %G_CONVERTER_FINISHED if
+really at the end) is returned instead of %G_CONVERTER_CONVERTED.
+This is somewhat similar to what happens at the end of the input stream,
+but done in the middle of the data.
+
+This has different meanings for different conversions. For instance
+in a compression converter it would mean that we flush all the
+compression state into output such that if you uncompress the
+compressed data you get back all the input data. Doing this may
+make the final file larger due to padding though. Another example
+is a regexp conversion, where if you at the end of the flushed data
+have a match, but there is also a potential longer match. In the
+non-flushed case we would ask for more input, but when flushing we
+treat this as the end of input and do the match.
+
+Flushing is not always possible (like if a charset converter flushes
+at a partial multibyte sequence). Converters are supposed to try
+to produce as much output as possible and then return an error
+(typically %G_IO_ERROR_PARTIAL_INPUT).
+
+
+ a #GConverterResult, %G_CONVERTER_ERROR on error.
+
+
+
+
+ a #GConverter.
+
+
+
+ the buffer
+ containing the data to convert.
+
+
+
+
+
+ the number of bytes in @inbuf
+
+
+
+ a
+ buffer to write converted data in.
+
+
+
+
+
+ the number of bytes in @outbuf, must be at least one
+
+
+
+ a #GConverterFlags controlling the conversion details
+
+
+
+ will be set to the number of bytes read
+ from @inbuf on success
+
+
+
+ will be set to the number of bytes
+ written to @outbuf on success
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+ a #GConverter.
+
+
+
+
+
+
+ Flags used when calling a g_converter_convert().
+
+ No flags.
+
+
+ At end of input data
+
+
+ Flush data
+
+
+
+ Provides an interface for converting data from one type
+to another type. The conversion can be stateful
+and may fail at any place.
+
+
+ The parent interface.
+
+
+
+
+
+
+ a #GConverterResult, %G_CONVERTER_ERROR on error.
+
+
+
+
+ a #GConverter.
+
+
+
+ the buffer
+ containing the data to convert.
+
+
+
+
+
+ the number of bytes in @inbuf
+
+
+
+ a
+ buffer to write converted data in.
+
+
+
+
+
+ the number of bytes in @outbuf, must be at least one
+
+
+
+ a #GConverterFlags controlling the conversion details
+
+
+
+ will be set to the number of bytes read
+ from @inbuf on success
+
+
+
+ will be set to the number of bytes
+ written to @outbuf on success
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GConverter.
+
+
+
+
+
+
+
+ Converter input stream implements #GInputStream and allows
+conversion of data of various types during reading.
+
+As of GLib 2.34, #GConverterInputStream implements
+#GPollableInputStream.
+
+
+
+ Creates a new converter input stream for the @base_stream.
+
+
+ a new #GInputStream.
+
+
+
+
+ a #GInputStream
+
+
+
+ a #GConverter
+
+
+
+
+
+ Gets the #GConverter that is used by @converter_stream.
+
+
+ the converter of the converter input stream
+
+
+
+
+ a #GConverterInputStream
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Converter output stream implements #GOutputStream and allows
+conversion of data of various types during reading.
+
+As of GLib 2.34, #GConverterOutputStream implements
+#GPollableOutputStream.
+
+
+
+ Creates a new converter output stream for the @base_stream.
+
+
+ a new #GOutputStream.
+
+
+
+
+ a #GOutputStream
+
+
+
+ a #GConverter
+
+
+
+
+
+ Gets the #GConverter that is used by @converter_stream.
+
+
+ the converter of the converter output stream
+
+
+
+
+ a #GConverterOutputStream
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Results returned from g_converter_convert().
+
+ There was an error during conversion.
+
+
+ Some data was consumed or produced
+
+
+ The conversion is finished
+
+
+ Flushing is finished
+
+
+
+ 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 `struct ucred` - see the
+unix(7) man page for details. This corresponds to
+%G_CREDENTIALS_TYPE_LINUX_UCRED.
+
+On Apple operating systems (including iOS, tvOS, and macOS),
+the native credential type is a `struct xucred`.
+This corresponds to %G_CREDENTIALS_TYPE_APPLE_XUCRED.
+
+On FreeBSD, Debian GNU/kFreeBSD, and GNU/Hurd, the native
+credential type is a `struct cmsgcred`. This corresponds
+to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED.
+
+On NetBSD, the native credential type is a `struct unpcbid`.
+This corresponds to %G_CREDENTIALS_TYPE_NETBSD_UNPCBID.
+
+On OpenBSD, the native credential type is a `struct sockpeercred`.
+This corresponds to %G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED.
+
+On Solaris (including OpenSolaris and its derivatives), the native
+credential type is a `ucred_t`. This corresponds to
+%G_CREDENTIALS_TYPE_SOLARIS_UCRED.
+
+Since GLib 2.72, on Windows, the native credentials may contain the PID of a
+process. This corresponds to %G_CREDENTIALS_TYPE_WIN32_PID.
+
+
+ Creates a new #GCredentials object with credentials matching the
+the current process.
+
+
+ A #GCredentials. Free with g_object_unref().
+
+
+
+
+ Gets a pointer to native credentials of type @native_type from
+@credentials.
+
+It is a programming error (which will cause a warning to be
+logged) to use this method if there is no #GCredentials support for
+the OS or if @native_type isn't supported by the OS.
+
+
+ The pointer to native credentials or
+ %NULL if there is no #GCredentials support for the OS or if @native_type
+ isn't supported by the OS. Do not free the returned data, it is owned
+ by @credentials.
+
+
+
+
+ A #GCredentials.
+
+
+
+ The type of native credentials to get.
+
+
+
+
+
+ Tries to get the UNIX process identifier from @credentials. This
+method is only available on UNIX platforms.
+
+This operation can fail if #GCredentials is not supported on the
+OS or if the native credentials type does not contain information
+about the UNIX process ID.
+
+
+ The UNIX process ID, or `-1` if @error is set.
+
+
+
+
+ A #GCredentials
+
+
+
+
+
+ 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.
+
+
+ The UNIX user identifier or `-1` if @error is set.
+
+
+
+
+ A #GCredentials
+
+
+
+
+
+ Checks if @credentials and @other_credentials is the same user.
+
+This operation can fail if #GCredentials is not supported on the
+the OS.
+
+
+ %TRUE if @credentials and @other_credentials has the same
+user, %FALSE otherwise or if @error is set.
+
+
+
+
+ A #GCredentials.
+
+
+
+ A #GCredentials.
+
+
+
+
+
+ Copies the native credentials of type @native_type from @native
+into @credentials.
+
+It is a programming error (which will cause a warning to be
+logged) to use this method if there is no #GCredentials support for
+the OS or if @native_type isn't supported by the OS.
+
+
+
+
+
+
+ A #GCredentials.
+
+
+
+ The type of native credentials to set.
+
+
+
+ A pointer to native credentials.
+
+
+
+
+
+ Tries to set the UNIX user identifier on @credentials. This method
+is only available on UNIX platforms.
+
+This operation can fail if #GCredentials is not supported on the
+OS or if the native credentials type does not contain information
+about the UNIX user. It can also fail if the OS does not allow the
+use of "spoofed" credentials.
+
+
+ %TRUE if @uid was set, %FALSE if error is set.
+
+
+
+
+ A #GCredentials.
+
+
+
+ The UNIX user identifier to set.
+
+
+
+
+
+ Creates a human-readable textual representation of @credentials
+that can be used in logging and debug messages. The format of the
+returned string may change in future GLib release.
+
+
+ A string that should be freed with g_free().
+
+
+
+
+ A #GCredentials object.
+
+
+
+
+
+
+ Class structure for #GCredentials.
+
+
+
+ Enumeration describing different kinds of native credential types.
+
+ Indicates an invalid native credential type.
+
+
+ The native credentials type is a `struct ucred`.
+
+
+ The native credentials type is a `struct cmsgcred`.
+
+
+ The native credentials type is a `struct sockpeercred`. Added in 2.30.
+
+
+ The native credentials type is a `ucred_t`. Added in 2.40.
+
+
+ The native credentials type is a `struct unpcbid`. Added in 2.42.
+
+
+ The native credentials type is a `struct xucred`. Added in 2.66.
+
+
+ The native credentials type is a PID `DWORD`. Added in 2.72.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The value returned by handlers of the signals generated by
+the `gdbus-codegen` tool to indicate that a method call has been
+handled by an implementation. It is equal to %TRUE, but using
+this macro is sometimes more readable.
+
+In code that needs to be backwards-compatible with older GLib,
+use %TRUE instead, often written like this:
+
+|[
+ g_dbus_method_invocation_return_error (invocation, ...);
+ return TRUE; // handled
+]|
+
+
+
+
+ The value returned by handlers of the signals generated by
+the `gdbus-codegen` tool to indicate that a method call has not been
+handled by an implementation. It is equal to %FALSE, but using
+this macro is sometimes more readable.
+
+In code that needs to be backwards-compatible with older GLib,
+use %FALSE instead.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #GDBusActionGroup is an implementation of the #GActionGroup
+interface that can be used as a proxy for an action group
+that is exported over D-Bus with g_dbus_connection_export_action_group().
+
+
+
+ Obtains a #GDBusActionGroup for the action group which is exported at
+the given @bus_name and @object_path.
+
+The thread default main context is taken at the time of this call.
+All signals on the menu model (and any linked models) are reported
+with respect to this context. All calls on the returned menu model
+(and linked models) must also originate from this same context, with
+the thread default main context unchanged.
+
+This call is non-blocking. The returned action group may or may not
+already be filled in. The correct thing to do is connect the signals
+for the action group to monitor for changes and then to call
+g_action_group_list_actions() to get the initial list.
+
+
+ a #GDBusActionGroup
+
+
+
+
+ A #GDBusConnection
+
+
+
+ the bus name which exports the action
+ group or %NULL if @connection is not a message bus connection
+
+
+
+ the object path at which the action group is exported
+
+
+
+
+
+
+ Information about an annotation.
+
+
+ The reference count or -1 if statically allocated.
+
+
+
+ The name of the annotation, e.g. "org.freedesktop.DBus.Deprecated".
+
+
+
+ The value of the annotation.
+
+
+
+ A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
+
+
+
+
+
+ If @info is statically allocated does nothing. Otherwise increases
+the reference count.
+
+
+ The same @info.
+
+
+
+
+ A #GDBusNodeInfo
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+ A #GDBusAnnotationInfo.
+
+
+
+
+
+ Looks up the value of an annotation.
+
+The cost of this function is O(n) in number of annotations.
+
+
+ The value or %NULL if not found. Do not free, it is owned by @annotations.
+
+
+
+
+ A %NULL-terminated array of annotations or %NULL.
+
+
+
+
+
+ The name of the annotation to look up.
+
+
+
+
+
+
+ Information about an argument for a method or a signal.
+
+
+ The reference count or -1 if statically allocated.
+
+
+
+ Name of the argument, e.g. @unix_user_id.
+
+
+
+ D-Bus signature of the argument (a single complete type).
+
+
+
+ A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
+
+
+
+
+
+ If @info is statically allocated does nothing. Otherwise increases
+the reference count.
+
+
+ The same @info.
+
+
+
+
+ A #GDBusArgInfo
+
+
+
+
+
+ If @info is statically allocated, does nothing. Otherwise decreases
+the reference count of @info. When its reference count drops to 0,
+the memory used is freed.
+
+
+
+
+
+
+ A #GDBusArgInfo.
+
+
+
+
+
+
+ The #GDBusAuthObserver type provides a mechanism for participating
+in how a #GDBusServer (or a #GDBusConnection) authenticates remote
+peers. Simply instantiate a #GDBusAuthObserver and connect to the
+signals you are interested in. Note that new signals may be added
+in the future
+
+## Controlling Authentication Mechanisms
+
+By default, a #GDBusServer or server-side #GDBusConnection will allow
+any authentication mechanism to be used. If you only
+want to allow D-Bus connections with the `EXTERNAL` mechanism,
+which makes use of credentials passing and is the recommended
+mechanism for modern Unix platforms such as Linux and the BSD family,
+you would use a signal handler like this:
+
+|[<!-- language="C" -->
+static gboolean
+on_allow_mechanism (GDBusAuthObserver *observer,
+ const gchar *mechanism,
+ gpointer user_data)
+{
+ if (g_strcmp0 (mechanism, "EXTERNAL") == 0)
+ {
+ return TRUE;
+ }
+
+ return FALSE;
+}
+]|
+
+## Controlling Authorization # {#auth-observer}
+
+By default, a #GDBusServer or server-side #GDBusConnection will accept
+connections from any successfully authenticated user (but not from
+anonymous connections using the `ANONYMOUS` mechanism). If you only
+want to allow D-Bus connections from processes owned by the same uid
+as the server, since GLib 2.68, you should use the
+%G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flag. It’s equivalent
+to the following signal handler:
+
+|[<!-- language="C" -->
+static gboolean
+on_authorize_authenticated_peer (GDBusAuthObserver *observer,
+ GIOStream *stream,
+ GCredentials *credentials,
+ gpointer user_data)
+{
+ gboolean authorized;
+
+ authorized = FALSE;
+ if (credentials != NULL)
+ {
+ GCredentials *own_credentials;
+ own_credentials = g_credentials_new ();
+ if (g_credentials_is_same_user (credentials, own_credentials, NULL))
+ authorized = TRUE;
+ g_object_unref (own_credentials);
+ }
+
+ return authorized;
+}
+]|
+
+ Creates a new #GDBusAuthObserver object.
+
+
+ A #GDBusAuthObserver. Free with g_object_unref().
+
+
+
+
+ Emits the #GDBusAuthObserver::allow-mechanism signal on @observer.
+
+
+ %TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not.
+
+
+
+
+ A #GDBusAuthObserver.
+
+
+
+ The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`.
+
+
+
+
+
+ Emits the #GDBusAuthObserver::authorize-authenticated-peer signal on @observer.
+
+
+ %TRUE if the peer is authorized, %FALSE if not.
+
+
+
+
+ A #GDBusAuthObserver.
+
+
+
+ A #GIOStream for the #GDBusConnection.
+
+
+
+ Credentials received from the peer or %NULL.
+
+
+
+
+
+ Emitted to check if @mechanism is allowed to be used.
+
+ %TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not.
+
+
+
+
+ The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`.
+
+
+
+
+
+ Emitted to check if a peer that is successfully authenticated
+is authorized.
+
+ %TRUE if the peer is authorized, %FALSE if not.
+
+
+
+
+ A #GIOStream for the #GDBusConnection.
+
+
+
+ Credentials received from the peer or %NULL.
+
+
+
+
+
+
+ Flags used in g_dbus_connection_call() and similar APIs.
+
+ No flags set.
+
+
+ The bus must not launch
+an owner for the destination name in response to this method
+invocation.
+
+
+ the caller is prepared to
+wait for interactive authorization. Since 2.46.
+
+
+
+ Capabilities negotiated with the remote peer.
+
+ No flags set.
+
+
+ The connection
+supports exchanging UNIX file descriptors with the remote peer.
+
+
+
+ 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 a #GIOStream.
+
+This class is rarely used directly in D-Bus clients. If you are writing
+a D-Bus client, it is often easier to use the g_bus_own_name(),
+g_bus_watch_name() or g_dbus_proxy_new_for_bus() APIs.
+
+As an exception to the usual GLib rule that a particular object must not
+be used by two threads at the same time, #GDBusConnection's methods may be
+called from any thread. This is so that g_bus_get() and g_bus_get_sync()
+can safely return the same #GDBusConnection when called from any thread.
+
+Most of the ways to obtain a #GDBusConnection automatically initialize it
+(i.e. connect to D-Bus): for instance, g_dbus_connection_new() and
+g_bus_get(), and the synchronous versions of those methods, give you an
+initialized connection. Language bindings for GIO should use
+g_initable_new() or g_async_initable_new_async(), which also initialize the
+connection.
+
+If you construct an uninitialized #GDBusConnection, such as via
+g_object_new(), you must initialize it via g_initable_init() or
+g_async_initable_init_async() before using its methods or properties.
+Calling methods or accessing properties on a #GDBusConnection that has not
+completed initialization successfully is considered to be invalid, and leads
+to undefined behaviour. In particular, if initialization fails with a
+#GError, the only valid thing you can do with that #GDBusConnection is to
+free it with g_object_unref().
+
+## An example D-Bus server # {#gdbus-server}
+
+Here is an example for a D-Bus server:
+[gdbus-example-server.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-server.c)
+
+## An example for exporting a subtree # {#gdbus-subtree-server}
+
+Here is an example for exporting a subtree:
+[gdbus-example-subtree.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-subtree.c)
+
+## An example for file descriptor passing # {#gdbus-unix-fd-client}
+
+Here is an example for passing UNIX file descriptors:
+[gdbus-unix-fd-client.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-unix-fd-client.c)
+
+## An example for exporting a GObject # {#gdbus-export}
+
+Here is an example for exporting a #GObject:
+[gdbus-example-export.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-export.c)
+
+
+
+ Finishes an operation started with g_dbus_connection_new().
+
+
+ a #GDBusConnection or %NULL if @error is set. Free
+ with g_object_unref().
+
+
+
+
+ a #GAsyncResult obtained from the #GAsyncReadyCallback
+ passed to g_dbus_connection_new().
+
+
+
+
+
+ Finishes an operation started with g_dbus_connection_new_for_address().
+
+
+ a #GDBusConnection or %NULL if @error is set.
+ Free with g_object_unref().
+
+
+
+
+ a #GAsyncResult obtained from the #GAsyncReadyCallback passed
+ to g_dbus_connection_new()
+
+
+
+
+
+ Synchronously connects and sets up a D-Bus client connection for
+exchanging D-Bus messages with an endpoint specified by @address
+which must be in the
+[D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
+
+This constructor can only be used to initiate client-side
+connections - use g_dbus_connection_new_sync() if you need to act
+as the server. In particular, @flags cannot contain the
+%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER,
+%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS or
+%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flags.
+
+This is a synchronous failable constructor. See
+g_dbus_connection_new_for_address() for the asynchronous version.
+
+If @observer is not %NULL it may be used to control the
+authentication process.
+
+
+ a #GDBusConnection or %NULL if @error is set.
+ Free with g_object_unref().
+
+
+
+
+ a D-Bus address
+
+
+
+ flags describing how to make the connection
+
+
+
+ a #GDBusAuthObserver or %NULL
+
+
+
+ a #GCancellable or %NULL
+
+
+
+
+
+ Synchronously sets up a D-Bus connection for exchanging D-Bus messages
+with the end represented by @stream.
+
+If @stream is a #GSocketConnection, then the corresponding #GSocket
+will be put into non-blocking mode.
+
+The D-Bus connection will interact with @stream from a worker thread.
+As a result, the caller should not interact with @stream after this
+method has been called, except by calling g_object_unref() on it.
+
+If @observer is not %NULL it may be used to control the
+authentication process.
+
+This is a synchronous failable constructor. See
+g_dbus_connection_new() for the asynchronous version.
+
+
+ a #GDBusConnection or %NULL if @error is set.
+ Free with g_object_unref().
+
+
+
+
+ a #GIOStream
+
+
+
+ the GUID to use if authenticating as a server or %NULL
+
+
+
+ flags describing how to make the connection
+
+
+
+ a #GDBusAuthObserver or %NULL
+
+
+
+ a #GCancellable or %NULL
+
+
+
+
+
+ Asynchronously sets up a D-Bus connection for exchanging D-Bus messages
+with the end represented by @stream.
+
+If @stream is a #GSocketConnection, then the corresponding #GSocket
+will be put into non-blocking mode.
+
+The D-Bus connection will interact with @stream from a worker thread.
+As a result, the caller should not interact with @stream after this
+method has been called, except by calling g_object_unref() on it.
+
+If @observer is not %NULL it may be used to control the
+authentication process.
+
+When the operation is finished, @callback will be invoked. You can
+then call g_dbus_connection_new_finish() to get the result of the
+operation.
+
+This is an asynchronous failable constructor. See
+g_dbus_connection_new_sync() for the synchronous
+version.
+
+
+
+
+
+
+ a #GIOStream
+
+
+
+ the GUID to use if authenticating as a server or %NULL
+
+
+
+ flags describing how to make the connection
+
+
+
+ a #GDBusAuthObserver or %NULL
+
+
+
+ a #GCancellable or %NULL
+
+
+
+ a #GAsyncReadyCallback to call when the request is satisfied
+
+
+
+ the data to pass to @callback
+
+
+
+
+
+ Asynchronously connects and sets up a D-Bus client connection for
+exchanging D-Bus messages with an endpoint specified by @address
+which must be in the
+[D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
+
+This constructor can only be used to initiate client-side
+connections - use g_dbus_connection_new() if you need to act as the
+server. In particular, @flags cannot contain the
+%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER,
+%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS or
+%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flags.
+
+When the operation is finished, @callback will be invoked. You can
+then call g_dbus_connection_new_for_address_finish() to get the result of
+the operation.
+
+If @observer is not %NULL it may be used to control the
+authentication process.
+
+This is an asynchronous failable constructor. See
+g_dbus_connection_new_for_address_sync() for the synchronous
+version.
+
+
+
+
+
+
+ a D-Bus address
+
+
+
+ flags describing how to make the connection
+
+
+
+ a #GDBusAuthObserver or %NULL
+
+
+
+ a #GCancellable or %NULL
+
+
+
+ a #GAsyncReadyCallback to call when the request is satisfied
+
+
+
+ the data to pass to @callback
+
+
+
+
+
+ Adds a message filter. Filters are handlers that are run on all
+incoming and outgoing messages, prior to standard dispatch. Filters
+are run in the order that they were added. The same handler can be
+added as a filter more than once, in which case it will be run more
+than once. Filters added during a filter callback won't be run on
+the message being processed. Filter functions are allowed to modify
+and even drop messages.
+
+Note that filters are run in a dedicated message handling thread so
+they can't block and, generally, can't do anything but signal a
+worker thread. Also note that filters are rarely needed - use API
+such as g_dbus_connection_send_message_with_reply(),
+g_dbus_connection_signal_subscribe() or g_dbus_connection_call() instead.
+
+If a filter consumes an incoming message the message is not
+dispatched anywhere else - not even the standard dispatch machinery
+(that API such as g_dbus_connection_signal_subscribe() and
+g_dbus_connection_send_message_with_reply() relies on) will see the
+message. Similarly, if a filter consumes an outgoing message, the
+message will not be sent to the other peer.
+
+If @user_data_free_func is non-%NULL, it will be called (in the
+thread-default main context of the thread you are calling this
+method from) at some point after @user_data is no longer
+needed. (It is not guaranteed to be called synchronously when the
+filter is removed, and may be called after @connection has been
+destroyed.)
+
+
+ a filter identifier that can be used with
+ g_dbus_connection_remove_filter()
+
+
+
+
+ a #GDBusConnection
+
+
+
+ a filter function
+
+
+
+ user data to pass to @filter_function
+
+
+
+ function to free @user_data with when filter
+ is removed or %NULL
+
+
+
+
+
+ Asynchronously invokes the @method_name method on the
+@interface_name D-Bus interface on the remote object at
+@object_path owned by @bus_name.
+
+If @connection is closed then the operation will fail with
+%G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
+fail with %G_IO_ERROR_CANCELLED. If @parameters contains a value
+not compatible with the D-Bus protocol, the operation fails with
+%G_IO_ERROR_INVALID_ARGUMENT.
+
+If @reply_type is non-%NULL then the reply will be checked for having this type and an
+error will be raised if it does not match. Said another way, if you give a @reply_type
+then any non-%NULL return value will be of this type. Unless it’s
+%G_VARIANT_TYPE_UNIT, the @reply_type will be a tuple containing one or more
+values.
+
+If the @parameters #GVariant is floating, it is consumed. This allows
+convenient 'inline' use of g_variant_new(), e.g.:
+|[<!-- language="C" -->
+ g_dbus_connection_call (connection,
+ "org.freedesktop.StringThings",
+ "/org/freedesktop/StringThings",
+ "org.freedesktop.StringThings",
+ "TwoStrings",
+ g_variant_new ("(ss)",
+ "Thing One",
+ "Thing Two"),
+ NULL,
+ G_DBUS_CALL_FLAGS_NONE,
+ -1,
+ NULL,
+ (GAsyncReadyCallback) two_strings_done,
+ NULL);
+]|
+
+This is an asynchronous method. When the operation is finished,
+@callback will be invoked in the
+[thread-default main context][g-main-context-push-thread-default]
+of the thread you are calling this method from. You can then call
+g_dbus_connection_call_finish() to get the result of the operation.
+See g_dbus_connection_call_sync() for the synchronous version of this
+function.
+
+If @callback is %NULL then the D-Bus method call message will be sent with
+the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set.
+
+
+
+
+
+
+ a #GDBusConnection
+
+
+
+ a unique or well-known bus name or %NULL if
+ @connection is not a message bus connection
+
+
+
+ path of remote object
+
+
+
+ D-Bus interface to invoke method on
+
+
+
+ the name of the method to invoke
+
+
+
+ a #GVariant tuple with parameters for the method
+ or %NULL if not passing parameters
+
+
+
+ the expected type of the reply (which will be a
+ tuple), or %NULL
+
+
+
+ flags from the #GDBusCallFlags enumeration
+
+
+
+ the timeout in milliseconds, -1 to use the default
+ timeout or %G_MAXINT for no timeout
+
+
+
+ a #GCancellable or %NULL
+
+
+
+ a #GAsyncReadyCallback to call when the request
+ is satisfied or %NULL if you don't care about the result of the
+ method invocation
+
+
+
+ the data to pass to @callback
+
+
+
+
+
+ Finishes an operation started with g_dbus_connection_call().
+
+
+ %NULL if @error is set. Otherwise a non-floating
+ #GVariant tuple with return values. Free with g_variant_unref().
+
+
+
+
+ a #GDBusConnection
+
+
+
+ a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call()
+
+
+
+
+
+ Synchronously invokes the @method_name method on the
+@interface_name D-Bus interface on the remote object at
+@object_path owned by @bus_name.
+
+If @connection is closed then the operation will fail with
+%G_IO_ERROR_CLOSED. If @cancellable is canceled, the
+operation will fail with %G_IO_ERROR_CANCELLED. If @parameters
+contains a value not compatible with the D-Bus protocol, the operation
+fails with %G_IO_ERROR_INVALID_ARGUMENT.
+
+If @reply_type is non-%NULL then the reply will be checked for having
+this type and an error will be raised if it does not match. Said
+another way, if you give a @reply_type then any non-%NULL return
+value will be of this type.
+
+If the @parameters #GVariant is floating, it is consumed.
+This allows convenient 'inline' use of g_variant_new(), e.g.:
+|[<!-- language="C" -->
+ g_dbus_connection_call_sync (connection,
+ "org.freedesktop.StringThings",
+ "/org/freedesktop/StringThings",
+ "org.freedesktop.StringThings",
+ "TwoStrings",
+ g_variant_new ("(ss)",
+ "Thing One",
+ "Thing Two"),
+ NULL,
+ G_DBUS_CALL_FLAGS_NONE,
+ -1,
+ NULL,
+ &error);
+]|
+
+The calling thread is blocked until a reply is received. See
+g_dbus_connection_call() for the asynchronous version of
+this method.
+
+
+ %NULL if @error is set. Otherwise a non-floating
+ #GVariant tuple with return values. Free with g_variant_unref().
+
+
+
+
+ a #GDBusConnection
+
+
+
+ a unique or well-known bus name or %NULL if
+ @connection is not a message bus connection
+
+
+
+ path of remote object
+
+
+
+ D-Bus interface to invoke method on
+
+
+
+ the name of the method to invoke
+
+
+
+ a #GVariant tuple with parameters for the method
+ or %NULL if not passing parameters
+
+
+
+ the expected type of the reply, or %NULL
+
+
+
+ flags from the #GDBusCallFlags enumeration
+
+
+
+ the timeout in milliseconds, -1 to use the default
+ timeout or %G_MAXINT for no timeout
+
+
+
+ a #GCancellable or %NULL
+
+
+
+
+
+ Like g_dbus_connection_call() but also takes a #GUnixFDList object.
+
+The file descriptors normally correspond to %G_VARIANT_TYPE_HANDLE
+values in the body of the message. For example, if a message contains
+two file descriptors, @fd_list would have length 2, and
+`g_variant_new_handle (0)` and `g_variant_new_handle (1)` would appear
+somewhere in the body of the message (not necessarily in that order!)
+to represent the file descriptors at indexes 0 and 1 respectively.
+
+When designing D-Bus APIs that are intended to be interoperable,
+please note that non-GDBus implementations of D-Bus can usually only
+access file descriptors if they are referenced in this way by a
+value of type %G_VARIANT_TYPE_HANDLE in the body of the message.
+
+This method is only available on UNIX.
+
+
+
+
+
+
+ a #GDBusConnection
+
+
+
+ a unique or well-known bus name or %NULL if
+ @connection is not a message bus connection
+
+
+
+ path of remote object
+
+
+
+ D-Bus interface to invoke method on
+
+
+
+ the name of the method to invoke
+
+
+
+ a #GVariant tuple with parameters for the method
+ or %NULL if not passing parameters
+
+
+
+ the expected type of the reply, or %NULL
+
+
+
+ flags from the #GDBusCallFlags enumeration
+
+
+
+ the timeout in milliseconds, -1 to use the default
+ timeout or %G_MAXINT for no timeout
+
+
+
+ a #GUnixFDList or %NULL
+
+
+
+ a #GCancellable or %NULL
+
+
+
+ a #GAsyncReadyCallback to call when the request is
+ satisfied or %NULL if you don't * care about the result of the
+ method invocation
+
+
+
+ The data to pass to @callback.
+
+
+
+
+
+ Finishes an operation started with g_dbus_connection_call_with_unix_fd_list().
+
+The file descriptors normally correspond to %G_VARIANT_TYPE_HANDLE
+values in the body of the message. For example,
+if g_variant_get_handle() returns 5, that is intended to be a reference
+to the file descriptor that can be accessed by
+`g_unix_fd_list_get (*out_fd_list, 5, ...)`.
+
+When designing D-Bus APIs that are intended to be interoperable,
+please note that non-GDBus implementations of D-Bus can usually only
+access file descriptors if they are referenced in this way by a
+value of type %G_VARIANT_TYPE_HANDLE in the body of the message.
+
+
+ %NULL if @error is set. Otherwise a non-floating
+ #GVariant tuple with return values. Free with g_variant_unref().
+
+
+
+
+ a #GDBusConnection
+
+
+
+ return location for a #GUnixFDList or %NULL
+
+
+
+ a #GAsyncResult obtained from the #GAsyncReadyCallback passed to
+ g_dbus_connection_call_with_unix_fd_list()
+
+
+
+
+
+ Like g_dbus_connection_call_sync() but also takes and returns #GUnixFDList objects.
+See g_dbus_connection_call_with_unix_fd_list() and
+g_dbus_connection_call_with_unix_fd_list_finish() for more details.
+
+This method is only available on UNIX.
+
+
+ %NULL if @error is set. Otherwise a non-floating
+ #GVariant tuple with return values. Free with g_variant_unref().
+
+
+
+
+ a #GDBusConnection
+
+
+
+ a unique or well-known bus name or %NULL
+ if @connection is not a message bus connection
+
+
+
+ path of remote object
+
+
+
+ D-Bus interface to invoke method on
+
+
+
+ the name of the method to invoke
+
+
+
+ a #GVariant tuple with parameters for
+ the method or %NULL if not passing parameters
+
+
+
+ the expected type of the reply, or %NULL
+
+
+
+ flags from the #GDBusCallFlags enumeration
+
+
+
+ the timeout in milliseconds, -1 to use the default
+ timeout or %G_MAXINT for no timeout
+
+
+
+ a #GUnixFDList or %NULL
+
+
+
+ return location for a #GUnixFDList or %NULL
+
+
+
+ a #GCancellable or %NULL
+
+
+
+
+
+ Closes @connection. Note that this never causes the process to
+exit (this might only happen if the other end of a shared message
+bus connection disconnects, see #GDBusConnection:exit-on-close).
+
+Once the connection is closed, operations such as sending a message
+will return with the error %G_IO_ERROR_CLOSED. Closing a connection
+will not automatically flush the connection so queued messages may
+be lost. Use g_dbus_connection_flush() if you need such guarantees.
+
+If @connection is already closed, this method fails with
+%G_IO_ERROR_CLOSED.
+
+When @connection has been closed, the #GDBusConnection::closed
+signal is emitted in the
+[thread-default main context][g-main-context-push-thread-default]
+of the thread that @connection was constructed in.
+
+This is an asynchronous method. When the operation is finished,
+@callback will be invoked in the
+[thread-default main context][g-main-context-push-thread-default]
+of the thread you are calling this method from. You can
+then call g_dbus_connection_close_finish() to get the result of the
+operation. See g_dbus_connection_close_sync() for the synchronous
+version.
+
+
+
+
+
+
+ a #GDBusConnection
+
+
+
+ a #GCancellable or %NULL
+
+
+
+ a #GAsyncReadyCallback to call when the request is
+ satisfied or %NULL if you don't care about the result
+
+
+
+ The data to pass to @callback
+
+
+
+
+
+ Finishes an operation started with g_dbus_connection_close().
+
+
+ %TRUE if the operation succeeded, %FALSE if @error is set
+
+
+
+
+ a #GDBusConnection
+
+
+
+ a #GAsyncResult obtained from the #GAsyncReadyCallback passed
+ to g_dbus_connection_close()
+
+
+
+
+
+ Synchronously closes @connection. The calling thread is blocked
+until this is done. See g_dbus_connection_close() for the
+asynchronous version of this method and more details about what it
+does.
+
+
+ %TRUE if the operation succeeded, %FALSE if @error is set
+
+
+
+
+ a #GDBusConnection
+
+
+
+ a #GCancellable or %NULL
+
+
+
+
+
+ Emits a signal.
+
+If the parameters GVariant is floating, it is consumed.
+
+This can only fail if @parameters is not compatible with the D-Bus protocol
+(%G_IO_ERROR_INVALID_ARGUMENT), or if @connection has been closed
+(%G_IO_ERROR_CLOSED).
+
+
+ %TRUE unless @error is set
+
+
+
+
+ a #GDBusConnection
+
+
+
+ the unique bus name for the destination
+ for the signal or %NULL to emit to all listeners
+
+
+
+ path of remote object
+
+
+
+ D-Bus interface to emit a signal on
+
+
+
+ the name of the signal to emit
+
+
+
+ a #GVariant tuple with parameters for the signal
+ or %NULL if not passing parameters
+
+
+
+
+
+ Exports @action_group on @connection at @object_path.
+
+The implemented D-Bus API should be considered private. It is
+subject to change in the future.
+
+A given object path can only have one action group exported on it.
+If this constraint is violated, the export will fail and 0 will be
+returned (with @error set accordingly).
+
+You can unexport the action group using
+g_dbus_connection_unexport_action_group() with the return value of
+this function.
+
+The thread default main context is taken at the time of this call.
+All incoming action activations and state change requests are
+reported from this context. Any changes on the action group that
+cause it to emit signals must also come from this same context.
+Since incoming action activations and state change requests are
+rather likely to cause changes on the action group, this effectively
+limits a given action group to being exported from only one main
+context.
+
+
+ the ID of the export (never zero), or 0 in case of failure
+
+
+
+
+ a #GDBusConnection
+
+
+
+ a D-Bus object path
+
+
+
+ a #GActionGroup
+
+
+
+
+
+ Exports @menu on @connection at @object_path.
+
+The implemented D-Bus API should be considered private.
+It is subject to change in the future.
+
+An object path can only have one menu model exported on it. If this
+constraint is violated, the export will fail and 0 will be
+returned (with @error set accordingly).
+
+Exporting menus with sections containing more than
+%G_MENU_EXPORTER_MAX_SECTION_SIZE items is not supported and results in
+undefined behavior.
+
+You can unexport the menu model using
+g_dbus_connection_unexport_menu_model() with the return value of
+this function.
+
+
+ the ID of the export (never zero), or 0 in case of failure
+
+
+
+
+ a #GDBusConnection
+
+
+
+ a D-Bus object path
+
+
+
+ a #GMenuModel
+
+
+
+
+
+ Asynchronously flushes @connection, that is, writes all queued
+outgoing message to the transport and then flushes the transport
+(using g_output_stream_flush_async()). This is useful in programs
+that wants to emit a D-Bus signal and then exit immediately. Without
+flushing the connection, there is no guaranteed that the message has
+been sent to the networking buffers in the OS kernel.
+
+This is an asynchronous method. When the operation is finished,
+@callback will be invoked in the
+[thread-default main context][g-main-context-push-thread-default]
+of the thread you are calling this method from. You can
+then call g_dbus_connection_flush_finish() to get the result of the
+operation. See g_dbus_connection_flush_sync() for the synchronous
+version.
+
+
+
+
+
+
+ a #GDBusConnection
+
+
+
+ a #GCancellable or %NULL
+
+
+
+ a #GAsyncReadyCallback to call when the
+ request is satisfied or %NULL if you don't care about the result
+
+
+
+ The data to pass to @callback
+
+
+
+
+
+ Finishes an operation started with g_dbus_connection_flush().
+
+
+ %TRUE if the operation succeeded, %FALSE if @error is set
+
+
+
+
+ a #GDBusConnection
+
+
+
+ a #GAsyncResult obtained from the #GAsyncReadyCallback passed
+ to g_dbus_connection_flush()
+
+
+
+
+
+ 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.
+
+
+ %TRUE if the operation succeeded, %FALSE if @error is set
+
+
+
+
+ a #GDBusConnection
+
+
+
+ a #GCancellable or %NULL
+
+
+
+
+
+ Gets the capabilities negotiated with the remote peer
+
+
+ zero or more flags from the #GDBusCapabilityFlags enumeration
+
+
+
+
+ a #GDBusConnection
+
+
+
+
+
+ Gets whether the process is terminated when @connection is
+closed by the remote peer. See
+#GDBusConnection:exit-on-close for more details.
+
+
+ whether the process is terminated when @connection is
+ closed by the remote peer
+
+
+
+
+ a #GDBusConnection
+
+
+
+
+
+ Gets the flags used to construct this connection
+
+
+ zero or more flags from the #GDBusConnectionFlags enumeration
+
+
+
+
+ a #GDBusConnection
+
+
+
+
+
+ The GUID of the peer performing the role of server when
+authenticating. See #GDBusConnection:guid for more details.
+
+
+ The GUID. Do not free this string, it is owned by
+ @connection.
+
+
+
+
+ a #GDBusConnection
+
+
+
+
+
+ Retrieves the last serial number assigned to a #GDBusMessage on
+the current thread. This includes messages sent via both low-level
+API such as g_dbus_connection_send_message() as well as
+high-level API such as g_dbus_connection_emit_signal(),
+g_dbus_connection_call() or g_dbus_proxy_call().
+
+
+ the last used serial or zero when no message has been sent
+ within the current thread
+
+
+
+
+ a #GDBusConnection
+
+
+
+
+
+ Gets the credentials of the authenticated peer. This will always
+return %NULL unless @connection acted as a server
+(e.g. %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER was passed)
+when set up and the client passed credentials as part of the
+authentication process.
+
+In a message bus setup, the message bus is always the server and
+each application is a client. So this method will always return
+%NULL for message bus clients.
+
+
+ a #GCredentials or %NULL if not
+ available. Do not free this object, it is owned by @connection.
+
+
+
+
+ a #GDBusConnection
+
+
+
+
+
+ Gets the underlying stream used for IO.
+
+While the #GDBusConnection is active, it will interact with this
+stream from a worker thread, so it is not safe to interact with
+the stream directly.
+
+
+ the stream used for IO
+
+
+
+
+ a #GDBusConnection
+
+
+
+
+
+ Gets the unique name of @connection as assigned by the message
+bus. This can also be used to figure out if @connection is a
+message bus connection.
+
+
+ the unique name or %NULL if @connection is not a message
+ bus connection. Do not free this string, it is owned by
+ @connection.
+
+
+
+
+ a #GDBusConnection
+
+
+
+
+
+ Gets whether @connection is closed.
+
+
+ %TRUE if the connection is closed, %FALSE otherwise
+
+
+
+
+ a #GDBusConnection
+
+
+
+
+
+ Registers callbacks for exported objects at @object_path with the
+D-Bus interface that is described in @interface_info.
+
+Calls to functions in @vtable (and @user_data_free_func) will happen
+in the
+[thread-default main context][g-main-context-push-thread-default]
+of the thread you are calling this method from.
+
+Note that all #GVariant values passed to functions in @vtable will match
+the signature given in @interface_info - if a remote caller passes
+incorrect values, the `org.freedesktop.DBus.Error.InvalidArgs`
+is returned to the remote caller.
+
+Additionally, if the remote caller attempts to invoke methods or
+access properties not mentioned in @interface_info the
+`org.freedesktop.DBus.Error.UnknownMethod` resp.
+`org.freedesktop.DBus.Error.InvalidArgs` errors
+are returned to the caller.
+
+It is considered a programming error if the
+#GDBusInterfaceGetPropertyFunc function in @vtable returns a
+#GVariant of incorrect type.
+
+If an existing callback is already registered at @object_path and
+@interface_name, then @error is set to %G_IO_ERROR_EXISTS.
+
+GDBus automatically implements the standard D-Bus interfaces
+org.freedesktop.DBus.Properties, org.freedesktop.DBus.Introspectable
+and org.freedesktop.Peer, so you don't have to implement those for the
+objects you export. You can implement org.freedesktop.DBus.Properties
+yourself, e.g. to handle getting and setting of properties asynchronously.
+
+Note that the reference count on @interface_info will be
+incremented by 1 (unless allocated statically, e.g. if the
+reference count is -1, see g_dbus_interface_info_ref()) for as long
+as the object is exported. Also note that @vtable will be copied.
+
+See this [server][gdbus-server] for an example of how to use this method.
+
+
+ 0 if @error is set, otherwise a registration id (never 0)
+ that can be used with g_dbus_connection_unregister_object()
+
+
+
+
+ a #GDBusConnection
+
+
+
+ the object path to register at
+
+
+
+ introspection data for the interface
+
+
+
+ a #GDBusInterfaceVTable to call into or %NULL
+
+
+
+ data to pass to functions in @vtable
+
+
+
+ function to call when the object path is unregistered
+
+
+
+
+
+ Version of g_dbus_connection_register_object() using closures instead of a
+#GDBusInterfaceVTable for easier binding in other languages.
+
+
+ 0 if @error is set, otherwise a registration ID (never 0)
+that can be used with g_dbus_connection_unregister_object() .
+
+
+
+
+ A #GDBusConnection.
+
+
+
+ The object path to register at.
+
+
+
+ Introspection data for the interface.
+
+
+
+ #GClosure for handling incoming method calls.
+
+
+
+ #GClosure for getting a property.
+
+
+
+ #GClosure for setting a property.
+
+
+
+
+
+ Registers a whole subtree of dynamic objects.
+
+The @enumerate and @introspection functions in @vtable are used to
+convey, to remote callers, what nodes exist in the subtree rooted
+by @object_path.
+
+When handling remote calls into any node in the subtree, first the
+@enumerate function is used to check if the node exists. If the node exists
+or the %G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is set
+the @introspection function is used to check if the node supports the
+requested method. If so, the @dispatch function is used to determine
+where to dispatch the call. The collected #GDBusInterfaceVTable and
+#gpointer will be used to call into the interface vtable for processing
+the request.
+
+All calls into user-provided code will be invoked in the
+[thread-default main context][g-main-context-push-thread-default]
+of the thread you are calling this method from.
+
+If an existing subtree is already registered at @object_path or
+then @error is set to %G_IO_ERROR_EXISTS.
+
+Note that it is valid to register regular objects (using
+g_dbus_connection_register_object()) in a subtree registered with
+g_dbus_connection_register_subtree() - if so, the subtree handler
+is tried as the last resort. One way to think about a subtree
+handler is to consider it a fallback handler for object paths not
+registered via g_dbus_connection_register_object() or other bindings.
+
+Note that @vtable will be copied so you cannot change it after
+registration.
+
+See this [server][gdbus-subtree-server] for an example of how to use
+this method.
+
+
+ 0 if @error is set, otherwise a subtree registration ID (never 0)
+that can be used with g_dbus_connection_unregister_subtree()
+
+
+
+
+ a #GDBusConnection
+
+
+
+ the object path to register the subtree at
+
+
+
+ a #GDBusSubtreeVTable to enumerate, introspect and
+ dispatch nodes in the subtree
+
+
+
+ flags used to fine tune the behavior of the subtree
+
+
+
+ data to pass to functions in @vtable
+
+
+
+ function to call when the subtree is unregistered
+
+
+
+
+
+ Removes a filter.
+
+Note that since filters run in a different thread, there is a race
+condition where it is possible that the filter will be running even
+after calling g_dbus_connection_remove_filter(), so you cannot just
+free data that the filter might be using. Instead, you should pass
+a #GDestroyNotify to g_dbus_connection_add_filter(), which will be
+called when it is guaranteed that the data is no longer needed.
+
+
+
+
+
+
+ a #GDBusConnection
+
+
+
+ an identifier obtained from g_dbus_connection_add_filter()
+
+
+
+
+
+ Asynchronously sends @message to the peer represented by @connection.
+
+Unless @flags contain the
+%G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
+will be assigned by @connection and set on @message via
+g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
+serial number used will be written to this location prior to
+submitting the message to the underlying transport. While it has a `volatile`
+qualifier, this is a historical artifact and the argument passed to it should
+not be `volatile`.
+
+If @connection is closed then the operation will fail with
+%G_IO_ERROR_CLOSED. If @message is not well-formed,
+the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
+
+See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
+for an example of how to use this low-level API to send and receive
+UNIX file descriptors.
+
+Note that @message must be unlocked, unless @flags contain the
+%G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
+
+
+ %TRUE if the message was well-formed and queued for
+ transmission, %FALSE if @error is set
+
+
+
+
+ a #GDBusConnection
+
+
+
+ a #GDBusMessage
+
+
+
+ flags affecting how the message is sent
+
+
+
+ return location for serial number assigned
+ to @message when sending it or %NULL
+
+
+
+
+
+ Asynchronously sends @message to the peer represented by @connection.
+
+Unless @flags contain the
+%G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
+will be assigned by @connection and set on @message via
+g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
+serial number used will be written to this location prior to
+submitting the message to the underlying transport. While it has a `volatile`
+qualifier, this is a historical artifact and the argument passed to it should
+not be `volatile`.
+
+If @connection is closed then the operation will fail with
+%G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
+fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed,
+the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
+
+This is an asynchronous method. When the operation is finished, @callback
+will be invoked in the
+[thread-default main context][g-main-context-push-thread-default]
+of the thread you are calling this method from. You can then call
+g_dbus_connection_send_message_with_reply_finish() to get the result of the operation.
+See g_dbus_connection_send_message_with_reply_sync() for the synchronous version.
+
+Note that @message must be unlocked, unless @flags contain the
+%G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
+
+See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
+for an example of how to use this low-level API to send and receive
+UNIX file descriptors.
+
+
+
+
+
+
+ a #GDBusConnection
+
+
+
+ a #GDBusMessage
+
+
+
+ flags affecting how the message is sent
+
+
+
+ the timeout in milliseconds, -1 to use the default
+ timeout or %G_MAXINT for no timeout
+
+
+
+ return location for serial number assigned
+ to @message when sending it or %NULL
+
+
+
+ a #GCancellable or %NULL
+
+
+
+ a #GAsyncReadyCallback to call when the request
+ is satisfied or %NULL if you don't care about the result
+
+
+
+ The data to pass to @callback
+
+
+
+
+
+ Finishes an operation started with g_dbus_connection_send_message_with_reply().
+
+Note that @error is only set if a local in-process error
+occurred. That is to say that the returned #GDBusMessage object may
+be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use
+g_dbus_message_to_gerror() to transcode this to a #GError.
+
+See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
+for an example of how to use this low-level API to send and receive
+UNIX file descriptors.
+
+
+ a locked #GDBusMessage or %NULL if @error is set
+
+
+
+
+ a #GDBusConnection
+
+
+
+ a #GAsyncResult obtained from the #GAsyncReadyCallback passed to
+ g_dbus_connection_send_message_with_reply()
+
+
+
+
+
+ Synchronously sends @message to the peer represented by @connection
+and blocks the calling thread until a reply is received or the
+timeout is reached. See g_dbus_connection_send_message_with_reply()
+for the asynchronous version of this method.
+
+Unless @flags contain the
+%G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
+will be assigned by @connection and set on @message via
+g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
+serial number used will be written to this location prior to
+submitting the message to the underlying transport. While it has a `volatile`
+qualifier, this is a historical artifact and the argument passed to it should
+not be `volatile`.
+
+If @connection is closed then the operation will fail with
+%G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
+fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed,
+the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
+
+Note that @error is only set if a local in-process error
+occurred. That is to say that the returned #GDBusMessage object may
+be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use
+g_dbus_message_to_gerror() to transcode this to a #GError.
+
+See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
+for an example of how to use this low-level API to send and receive
+UNIX file descriptors.
+
+Note that @message must be unlocked, unless @flags contain the
+%G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
+
+
+ a locked #GDBusMessage that is the reply
+ to @message or %NULL if @error is set
+
+
+
+
+ a #GDBusConnection
+
+
+
+ a #GDBusMessage
+
+
+
+ flags affecting how the message is sent.
+
+
+
+ the timeout in milliseconds, -1 to use the default
+ timeout or %G_MAXINT for no timeout
+
+
+
+ return location for serial number
+ assigned to @message when sending it or %NULL
+
+
+
+ a #GCancellable or %NULL
+
+
+
+
+
+ Sets whether the process should be terminated when @connection is
+closed by the remote peer. See #GDBusConnection:exit-on-close for
+more details.
+
+Note that this function should be used with care. Most modern UNIX
+desktops tie the notion of a user session with the session bus, and expect
+all of a user's applications to quit when their bus connection goes away.
+If you are setting @exit_on_close to %FALSE for the shared session
+bus connection, you should make sure that your application exits
+when the user session ends.
+
+
+
+
+
+
+ a #GDBusConnection
+
+
+
+ whether the process should be terminated
+ when @connection is closed by the remote peer
+
+
+
+
+
+ Subscribes to signals on @connection and invokes @callback whenever
+the signal is received. Note that @callback will be invoked in the
+[thread-default main context][g-main-context-push-thread-default]
+of the thread you are calling this method from.
+
+If @connection is not a message bus connection, @sender must be
+%NULL.
+
+If @sender is a well-known name note that @callback is invoked with
+the unique name for the owner of @sender, not the well-known name
+as one would expect. This is because the message bus rewrites the
+name. As such, to avoid certain race conditions, users should be
+tracking the name owner of the well-known name and use that when
+processing the received signal.
+
+If one of %G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_NAMESPACE or
+%G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_PATH are given, @arg0 is
+interpreted as part of a namespace or path. The first argument
+of a signal is matched against that part as specified by D-Bus.
+
+If @user_data_free_func is non-%NULL, it will be called (in the
+thread-default main context of the thread you are calling this
+method from) at some point after @user_data is no longer
+needed. (It is not guaranteed to be called synchronously when the
+signal is unsubscribed from, and may be called after @connection
+has been destroyed.)
+
+As @callback is potentially invoked in a different thread from where it’s
+emitted, it’s possible for this to happen after
+g_dbus_connection_signal_unsubscribe() has been called in another thread.
+Due to this, @user_data should have a strong reference which is freed with
+@user_data_free_func, rather than pointing to data whose lifecycle is tied
+to the signal subscription. For example, if a #GObject is used to store the
+subscription ID from g_dbus_connection_signal_subscribe(), a strong reference
+to that #GObject must be passed to @user_data, and g_object_unref() passed to
+@user_data_free_func. You are responsible for breaking the resulting
+reference count cycle by explicitly unsubscribing from the signal when
+dropping the last external reference to the #GObject. Alternatively, a weak
+reference may be used.
+
+It is guaranteed that if you unsubscribe from a signal using
+g_dbus_connection_signal_unsubscribe() from the same thread which made the
+corresponding g_dbus_connection_signal_subscribe() call, @callback will not
+be invoked after g_dbus_connection_signal_unsubscribe() returns.
+
+The returned subscription identifier is an opaque value which is guaranteed
+to never be zero.
+
+This function can never fail.
+
+
+ a subscription identifier that can be used with g_dbus_connection_signal_unsubscribe()
+
+
+
+
+ a #GDBusConnection
+
+
+
+ sender name to match on (unique or well-known name)
+ or %NULL to listen from all senders
+
+
+
+ D-Bus interface name to match on or %NULL to
+ match on all interfaces
+
+
+
+ D-Bus signal name to match on or %NULL to match on
+ all signals
+
+
+
+ object path to match on or %NULL to match on
+ all object paths
+
+
+
+ contents of first string argument to match on or %NULL
+ to match on all kinds of arguments
+
+
+
+ #GDBusSignalFlags describing how arg0 is used in subscribing to the
+ signal
+
+
+
+ callback to invoke when there is a signal matching the requested data
+
+
+
+ user data to pass to @callback
+
+
+
+ function to free @user_data with when
+ subscription is removed or %NULL
+
+
+
+
+
+ Unsubscribes from signals.
+
+Note that there may still be D-Bus traffic to process (relating to this
+signal subscription) in the current thread-default #GMainContext after this
+function has returned. You should continue to iterate the #GMainContext
+until the #GDestroyNotify function passed to
+g_dbus_connection_signal_subscribe() is called, in order to avoid memory
+leaks through callbacks queued on the #GMainContext after it’s stopped being
+iterated.
+Alternatively, any idle source with a priority lower than %G_PRIORITY_DEFAULT
+that was scheduled after unsubscription, also indicates that all resources
+of this subscription are released.
+
+
+
+
+
+
+ a #GDBusConnection
+
+
+
+ a subscription id obtained from
+ g_dbus_connection_signal_subscribe()
+
+
+
+
+
+ If @connection was created with
+%G_DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING, this method
+starts processing messages. Does nothing on if @connection wasn't
+created with this flag or if the method has already been called.
+
+
+
+
+
+
+ a #GDBusConnection
+
+
+
+
+
+ Reverses the effect of a previous call to
+g_dbus_connection_export_action_group().
+
+It is an error to call this function with an ID that wasn't returned
+from g_dbus_connection_export_action_group() or to call it with the
+same ID more than once.
+
+
+
+
+
+
+ a #GDBusConnection
+
+
+
+ the ID from g_dbus_connection_export_action_group()
+
+
+
+
+
+ Reverses the effect of a previous call to
+g_dbus_connection_export_menu_model().
+
+It is an error to call this function with an ID that wasn't returned
+from g_dbus_connection_export_menu_model() or to call it with the
+same ID more than once.
+
+
+
+
+
+
+ a #GDBusConnection
+
+
+
+ the ID from g_dbus_connection_export_menu_model()
+
+
+
+
+
+ Unregisters an object.
+
+
+ %TRUE if the object was unregistered, %FALSE otherwise
+
+
+
+
+ a #GDBusConnection
+
+
+
+ a registration id obtained from
+ g_dbus_connection_register_object()
+
+
+
+
+
+ Unregisters a subtree.
+
+
+ %TRUE if the subtree was unregistered, %FALSE otherwise
+
+
+
+
+ a #GDBusConnection
+
+
+
+ a subtree registration id obtained from
+ g_dbus_connection_register_subtree()
+
+
+
+
+
+ A D-Bus address specifying potential endpoints that can be used
+when establishing the connection.
+
+
+
+ A #GDBusAuthObserver object to assist in the authentication process or %NULL.
+
+
+
+ Flags from the #GDBusCapabilityFlags enumeration
+representing connection features negotiated with the other peer.
+
+
+
+ A boolean specifying whether the connection has been closed.
+
+
+
+ A boolean specifying whether the process will be terminated (by
+calling `raise(SIGTERM)`) if the connection is closed by the
+remote peer.
+
+Note that #GDBusConnection objects returned by g_bus_get_finish()
+and g_bus_get_sync() will (usually) have this property set to %TRUE.
+
+
+
+ Flags from the #GDBusConnectionFlags enumeration.
+
+
+
+ The GUID of the peer performing the role of server when
+authenticating.
+
+If you are constructing a #GDBusConnection and pass
+%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER in the
+#GDBusConnection:flags property then you **must** also set this
+property to a valid guid.
+
+If you are constructing a #GDBusConnection and pass
+%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT in the
+#GDBusConnection:flags property you will be able to read the GUID
+of the other peer here after the connection has been successfully
+initialized.
+
+Note that the
+[D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses)
+uses the term ‘UUID’ to refer to this, whereas GLib consistently uses the
+term ‘GUID’ for historical reasons.
+
+Despite its name, the format of #GDBusConnection:guid does not follow
+[RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122) or the Microsoft
+GUID format.
+
+
+
+ The underlying #GIOStream used for I/O.
+
+If this is passed on construction and is a #GSocketConnection,
+then the corresponding #GSocket will be put into non-blocking mode.
+
+While the #GDBusConnection is active, it will interact with this
+stream from a worker thread, so it is not safe to interact with
+the stream directly.
+
+
+
+ The unique name as assigned by the message bus or %NULL if the
+connection is not open or not a message bus connection.
+
+
+
+ Emitted when the connection is closed.
+
+The cause of this event can be
+
+- If g_dbus_connection_close() is called. In this case
+ @remote_peer_vanished is set to %FALSE and @error is %NULL.
+
+- If the remote peer closes the connection. In this case
+ @remote_peer_vanished is set to %TRUE and @error is set.
+
+- If the remote peer sends invalid or malformed data. In this
+ case @remote_peer_vanished is set to %FALSE and @error is set.
+
+Upon receiving this signal, you should give up your reference to
+@connection. You are guaranteed that this signal is emitted only
+once.
+
+
+
+
+
+ %TRUE if @connection is closed because the
+ remote peer closed its end of the connection
+
+
+
+ a #GError with more details about the event or %NULL
+
+
+
+
+
+
+ Flags used when creating a new #GDBusConnection.
+
+ No flags set.
+
+
+ Perform authentication against server.
+
+
+ Perform authentication against client.
+
+
+ When
+authenticating as a server, allow the anonymous authentication
+method.
+
+
+ Pass this flag if connecting to a peer that is a
+message bus. This means that the Hello() method will be invoked as part of the connection setup.
+
+
+ If set, processing of D-Bus messages is
+delayed until g_dbus_connection_start_message_processing() is called.
+
+
+ When authenticating
+as a server, require the UID of the peer to be the same as the UID of the server. (Since: 2.68)
+
+
+ When authenticating, try to use
+ protocols that work across a Linux user namespace boundary, even if this
+ reduces interoperability with older D-Bus implementations. This currently
+ affects client-side `EXTERNAL` authentication, for which this flag makes
+ connections to a server in another user namespace succeed, but causes
+ a deadlock when connecting to a GDBus server older than 2.73.3. Since: 2.74
+
+
+
+ Error codes for the %G_DBUS_ERROR error domain.
+
+ A generic error; "something went wrong" - see the error message for
+more.
+
+
+ There was not enough memory to complete an operation.
+
+
+ The bus doesn't know how to launch a service to supply the bus name
+you wanted.
+
+
+ The bus name you referenced doesn't exist (i.e. no application owns
+it).
+
+
+ No reply to a message expecting one, usually means a timeout occurred.
+
+
+ Something went wrong reading or writing to a socket, for example.
+
+
+ A D-Bus bus address was malformed.
+
+
+ Requested operation isn't supported (like ENOSYS on UNIX).
+
+
+ Some limited resource is exhausted.
+
+
+ Security restrictions don't allow doing what you're trying to do.
+
+
+ Authentication didn't work.
+
+
+ Unable to connect to server (probably caused by ECONNREFUSED on a
+socket).
+
+
+ Certain timeout errors, possibly ETIMEDOUT on a socket. Note that
+%G_DBUS_ERROR_NO_REPLY is used for message reply timeouts. Warning:
+this is confusingly-named given that %G_DBUS_ERROR_TIMED_OUT also
+exists. We can't fix it for compatibility reasons so just be
+careful.
+
+
+ No network access (probably ENETUNREACH on a socket).
+
+
+ Can't bind a socket since its address is in use (i.e. EADDRINUSE).
+
+
+ The connection is disconnected and you're trying to use it.
+
+
+ Invalid arguments passed to a method call.
+
+
+ Missing file.
+
+
+ Existing file and the operation you're using does not silently overwrite.
+
+
+ Method name you invoked isn't known by the object you invoked it on.
+
+
+ Certain timeout errors, e.g. while starting a service. Warning: this is
+confusingly-named given that %G_DBUS_ERROR_TIMEOUT also exists. We
+can't fix it for compatibility reasons so just be careful.
+
+
+ Tried to remove or modify a match rule that didn't exist.
+
+
+ The match rule isn't syntactically valid.
+
+
+ While starting a new process, the exec() call failed.
+
+
+ While starting a new process, the fork() call failed.
+
+
+ While starting a new process, the child exited with a status code.
+
+
+ While starting a new process, the child exited on a signal.
+
+
+ While starting a new process, something went wrong.
+
+
+ We failed to setup the environment correctly.
+
+
+ We failed to setup the config parser correctly.
+
+
+ Bus name was not valid.
+
+
+ Service file not found in system-services directory.
+
+
+ Permissions are incorrect on the setuid helper.
+
+
+ Service file invalid (Name, User or Exec missing).
+
+
+ Tried to get a UNIX process ID and it wasn't available.
+
+
+ Tried to get a UNIX process ID and it wasn't available.
+
+
+ A type signature is not valid.
+
+
+ A file contains invalid syntax or is otherwise broken.
+
+
+ Asked for SELinux security context and it wasn't available.
+
+
+ Asked for ADT audit data and it wasn't available.
+
+
+ There's already an object with the requested object path.
+
+
+ Object you invoked a method on isn't known. Since 2.42
+
+
+ Interface you invoked a method on isn't known by the object. Since 2.42
+
+
+ Property you tried to access isn't known by the object. Since 2.42
+
+
+ Property you tried to set is read-only. Since 2.42
+
+
+ Creates a D-Bus error name to use for @error. If @error matches
+a registered error (cf. g_dbus_error_register_error()), the corresponding
+D-Bus error name will be returned.
+
+Otherwise the a name of the form
+`org.gtk.GDBus.UnmappedGError.Quark._ESCAPED_QUARK_NAME.Code_ERROR_CODE`
+will be used. This allows other GDBus applications to map the error
+on the wire back to a #GError using g_dbus_error_new_for_dbus_error().
+
+This function is typically only used in object mappings to put a
+#GError on the wire. Regular applications should not use it.
+
+
+ A D-Bus error name (never %NULL).
+ Free with g_free().
+
+
+
+
+ A #GError.
+
+
+
+
+
+ Gets the D-Bus error name used for @error, if any.
+
+This function is guaranteed to return a D-Bus error name for all
+#GErrors returned from functions handling remote method calls
+(e.g. g_dbus_connection_call_finish()) unless
+g_dbus_error_strip_remote_error() has been used on @error.
+
+
+ an allocated string or %NULL if the
+ D-Bus error name could not be found. Free with g_free().
+
+
+
+
+ a #GError
+
+
+
+
+
+ Checks if @error represents an error received via D-Bus from a remote peer. If so,
+use g_dbus_error_get_remote_error() to get the name of the error.
+
+
+ %TRUE if @error represents an error from a remote peer,
+%FALSE otherwise.
+
+
+
+
+ A #GError.
+
+
+
+
+
+ Creates a #GError based on the contents of @dbus_error_name and
+@dbus_error_message.
+
+Errors registered with g_dbus_error_register_error() will be looked
+up using @dbus_error_name and if a match is found, the error domain
+and code is used. Applications can use g_dbus_error_get_remote_error()
+to recover @dbus_error_name.
+
+If a match against a registered error is not found and the D-Bus
+error name is in a form as returned by g_dbus_error_encode_gerror()
+the error domain and code encoded in the name is used to
+create the #GError. Also, @dbus_error_name is added to the error message
+such that it can be recovered with g_dbus_error_get_remote_error().
+
+Otherwise, a #GError with the error code %G_IO_ERROR_DBUS_ERROR
+in the %G_IO_ERROR error domain is returned. Also, @dbus_error_name is
+added to the error message such that it can be recovered with
+g_dbus_error_get_remote_error().
+
+In all three cases, @dbus_error_name can always be recovered from the
+returned #GError using the g_dbus_error_get_remote_error() function
+(unless g_dbus_error_strip_remote_error() hasn't been used on the returned error).
+
+This function is typically only used in object mappings to prepare
+#GError instances for applications. Regular applications should not use
+it.
+
+
+ An allocated #GError. Free with g_error_free().
+
+
+
+
+ D-Bus error name.
+
+
+
+ D-Bus error message.
+
+
+
+
+
+
+
+
+
+
+ Creates an association to map between @dbus_error_name and
+#GErrors specified by @error_domain and @error_code.
+
+This is typically done in the routine that returns the #GQuark for
+an error domain.
+
+
+ %TRUE if the association was created, %FALSE if it already
+exists.
+
+
+
+
+ A #GQuark for an error domain.
+
+
+
+ An error code.
+
+
+
+ A D-Bus error name.
+
+
+
+
+
+ Helper function for associating a #GError error domain with D-Bus error names.
+
+While @quark_volatile has a `volatile` qualifier, this is a historical
+artifact and the argument passed to it should not be `volatile`.
+
+
+
+
+
+
+ The error domain name.
+
+
+
+ A pointer where to store the #GQuark.
+
+
+
+ A pointer to @num_entries #GDBusErrorEntry struct items.
+
+
+
+
+
+ Number of items to register.
+
+
+
+
+
+ Does nothing if @error is %NULL. Otherwise sets *@error to
+a new #GError created with g_dbus_error_new_for_dbus_error()
+with @dbus_error_message prepend with @format (unless %NULL).
+
+
+
+
+
+
+ A pointer to a #GError or %NULL.
+
+
+
+ D-Bus error name.
+
+
+
+ D-Bus error message.
+
+
+
+ printf()-style format to prepend to @dbus_error_message or %NULL.
+
+
+
+ Arguments for @format.
+
+
+
+
+
+ Like g_dbus_error_set_dbus_error() but intended for language bindings.
+
+
+
+
+
+
+ A pointer to a #GError or %NULL.
+
+
+
+ D-Bus error name.
+
+
+
+ D-Bus error message.
+
+
+
+ printf()-style format to prepend to @dbus_error_message or %NULL.
+
+
+
+ Arguments for @format.
+
+
+
+
+
+ Looks for extra information in the error message used to recover
+the D-Bus error name and strips it if found. If stripped, the
+message field in @error will correspond exactly to what was
+received on the wire.
+
+This is typically used when presenting errors to the end user.
+
+
+ %TRUE if information was stripped, %FALSE otherwise.
+
+
+
+
+ A #GError.
+
+
+
+
+
+ Destroys an association previously set up with g_dbus_error_register_error().
+
+
+ %TRUE if the association was destroyed, %FALSE if it wasn't found.
+
+
+
+
+ A #GQuark for an error domain.
+
+
+
+ An error code.
+
+
+
+ A D-Bus error name.
+
+
+
+
+
+
+ Struct used in g_dbus_error_register_error_domain().
+
+
+ An error code.
+
+
+
+ The D-Bus error name to associate with @error_code.
+
+
+
+
+ The #GDBusInterface type is the base type for D-Bus interfaces both
+on the service side (see #GDBusInterfaceSkeleton) and client side
+(see #GDBusProxy).
+
+
+ Gets the #GDBusObject that @interface_ belongs to, if any.
+
+
+ A #GDBusObject or %NULL. The returned
+reference should be freed with g_object_unref().
+
+
+
+
+ An exported D-Bus interface.
+
+
+
+
+
+ Gets D-Bus introspection information for the D-Bus interface
+implemented by @interface_.
+
+
+ A #GDBusInterfaceInfo. Do not free.
+
+
+
+
+ An exported D-Bus interface.
+
+
+
+
+
+ Gets the #GDBusObject that @interface_ belongs to, if any.
+
+It is not safe to use the returned object if @interface_ or
+the returned object is being used from other threads. See
+g_dbus_interface_dup_object() for a thread-safe alternative.
+
+
+ A #GDBusObject or %NULL. The returned
+ reference belongs to @interface_ and should not be freed.
+
+
+
+
+ An exported D-Bus interface
+
+
+
+
+
+ Sets the #GDBusObject for @interface_ to @object.
+
+Note that @interface_ will hold a weak reference to @object.
+
+
+
+
+
+
+ An exported D-Bus interface.
+
+
+
+ A #GDBusObject or %NULL.
+
+
+
+
+
+ Gets the #GDBusObject that @interface_ belongs to, if any.
+
+
+ A #GDBusObject or %NULL. The returned
+reference should be freed with g_object_unref().
+
+
+
+
+ An exported D-Bus interface.
+
+
+
+
+
+ Gets D-Bus introspection information for the D-Bus interface
+implemented by @interface_.
+
+
+ A #GDBusInterfaceInfo. Do not free.
+
+
+
+
+ An exported D-Bus interface.
+
+
+
+
+
+ Gets the #GDBusObject that @interface_ belongs to, if any.
+
+It is not safe to use the returned object if @interface_ or
+the returned object is being used from other threads. See
+g_dbus_interface_dup_object() for a thread-safe alternative.
+
+
+ A #GDBusObject or %NULL. The returned
+ reference belongs to @interface_ and should not be freed.
+
+
+
+
+ An exported D-Bus interface
+
+
+
+
+
+ Sets the #GDBusObject for @interface_ to @object.
+
+Note that @interface_ will hold a weak reference to @object.
+
+
+
+
+
+
+ An exported D-Bus interface.
+
+
+
+ A #GDBusObject or %NULL.
+
+
+
+
+
+
+ The type of the @get_property function in #GDBusInterfaceVTable.
+
+
+ A #GVariant with the value for @property_name or %NULL if
+ @error is set. If the returned #GVariant is floating, it is
+ consumed - otherwise its reference count is decreased by one.
+
+
+
+
+ A #GDBusConnection.
+
+
+
+ The unique bus name of the remote caller.
+
+
+
+ The object path that the method was invoked on.
+
+
+
+ The D-Bus interface name for the property.
+
+
+
+ The name of the property to get the value of.
+
+
+
+ Return location for error.
+
+
+
+ The @user_data #gpointer passed to g_dbus_connection_register_object().
+
+
+
+
+
+ Base type for D-Bus interfaces.
+
+
+ The parent interface.
+
+
+
+
+
+
+ A #GDBusInterfaceInfo. Do not free.
+
+
+
+
+ An exported D-Bus interface.
+
+
+
+
+
+
+
+
+
+ A #GDBusObject or %NULL. The returned
+ reference belongs to @interface_ and should not be freed.
+
+
+
+
+ An exported D-Bus interface
+
+
+
+
+
+
+
+
+
+
+
+
+
+ An exported D-Bus interface.
+
+
+
+ A #GDBusObject or %NULL.
+
+
+
+
+
+
+
+
+
+ A #GDBusObject or %NULL. The returned
+reference should be freed with g_object_unref().
+
+
+
+
+ An exported D-Bus interface.
+
+
+
+
+
+
+
+ Information about a D-Bus interface.
+
+
+ The reference count or -1 if statically allocated.
+
+
+
+ The name of the D-Bus interface, e.g. "org.freedesktop.DBus.Properties".
+
+
+
+ A pointer to a %NULL-terminated array of pointers to #GDBusMethodInfo structures or %NULL if there are no methods.
+
+
+
+
+
+ A pointer to a %NULL-terminated array of pointers to #GDBusSignalInfo structures or %NULL if there are no signals.
+
+
+
+
+
+ A pointer to a %NULL-terminated array of pointers to #GDBusPropertyInfo structures or %NULL if there are no properties.
+
+
+
+
+
+ A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+ A GDBusInterfaceInfo
+
+
+
+
+
+ Appends an XML representation of @info (and its children) to @string_builder.
+
+This function is typically used for generating introspection XML
+documents at run-time for handling the
+`org.freedesktop.DBus.Introspectable.Introspect`
+method.
+
+
+
+
+
+
+ A #GDBusNodeInfo
+
+
+
+ Indentation level.
+
+
+
+ A #GString to to append XML data to.
+
+
+
+
+
+ Looks up information about a method.
+
+The cost of this function is O(n) in number of methods unless
+g_dbus_interface_info_cache_build() has been used on @info.
+
+
+ A #GDBusMethodInfo or %NULL if not found. Do not free, it is owned by @info.
+
+
+
+
+ A #GDBusInterfaceInfo.
+
+
+
+ A D-Bus method name (typically in CamelCase)
+
+
+
+
+
+ Looks up information about a property.
+
+The cost of this function is O(n) in number of properties unless
+g_dbus_interface_info_cache_build() has been used on @info.
+
+
+ A #GDBusPropertyInfo or %NULL if not found. Do not free, it is owned by @info.
+
+
+
+
+ A #GDBusInterfaceInfo.
+
+
+
+ A D-Bus property name (typically in CamelCase).
+
+
+
+
+
+ Looks up information about a signal.
+
+The cost of this function is O(n) in number of signals unless
+g_dbus_interface_info_cache_build() has been used on @info.
+
+
+ A #GDBusSignalInfo or %NULL if not found. Do not free, it is owned by @info.
+
+
+
+
+ A #GDBusInterfaceInfo.
+
+
+
+ A D-Bus signal name (typically in CamelCase)
+
+
+
+
+
+ If @info is statically allocated does nothing. Otherwise increases
+the reference count.
+
+
+ The same @info.
+
+
+
+
+ A #GDBusInterfaceInfo
+
+
+
+
+
+ If @info is statically allocated, does nothing. Otherwise decreases
+the reference count of @info. When its reference count drops to 0,
+the memory used is freed.
+
+
+
+
+
+
+ A #GDBusInterfaceInfo.
+
+
+
+
+
+
+ The type of the @method_call function in #GDBusInterfaceVTable.
+
+
+
+
+
+
+ A #GDBusConnection.
+
+
+
+ The unique bus name of the remote caller.
+
+
+
+ The object path that the method was invoked on.
+
+
+
+ The D-Bus interface name the method was invoked on.
+
+
+
+ The name of the method that was invoked.
+
+
+
+ A #GVariant tuple with parameters.
+
+
+
+ A #GDBusMethodInvocation object that must be used to return a value or error.
+
+
+
+ The @user_data #gpointer passed to g_dbus_connection_register_object().
+
+
+
+
+
+ The type of the @set_property function in #GDBusInterfaceVTable.
+
+
+ %TRUE if the property was set to @value, %FALSE if @error is set.
+
+
+
+
+ A #GDBusConnection.
+
+
+
+ The unique bus name of the remote caller.
+
+
+
+ The object path that the method was invoked on.
+
+
+
+ The D-Bus interface name for the property.
+
+
+
+ The name of the property to get the value of.
+
+
+
+ The value to set the property to.
+
+
+
+ Return location for error.
+
+
+
+ The @user_data #gpointer passed to g_dbus_connection_register_object().
+
+
+
+
+
+ Abstract base class for D-Bus interfaces on the service side.
+
+
+
+ If @interface_ has outstanding changes, request for these changes to be
+emitted immediately.
+
+For example, an exported D-Bus interface may queue up property
+changes and emit the
+`org.freedesktop.DBus.Properties.PropertiesChanged`
+signal later (e.g. in an idle handler). This technique is useful
+for collapsing multiple property changes into one.
+
+
+
+
+
+
+ A #GDBusInterfaceSkeleton.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Gets D-Bus introspection information for the D-Bus interface
+implemented by @interface_.
+
+
+ A #GDBusInterfaceInfo (never %NULL). Do not free.
+
+
+
+
+ A #GDBusInterfaceSkeleton.
+
+
+
+
+
+ Gets all D-Bus properties for @interface_.
+
+
+ A #GVariant of type
+['a{sv}'][G-VARIANT-TYPE-VARDICT:CAPS].
+Free with g_variant_unref().
+
+
+
+
+ A #GDBusInterfaceSkeleton.
+
+
+
+
+
+ Gets the interface vtable for the D-Bus interface implemented by
+@interface_. The returned function pointers should expect @interface_
+itself to be passed as @user_data.
+
+
+ A #GDBusInterfaceVTable (never %NULL).
+
+
+
+
+ A #GDBusInterfaceSkeleton.
+
+
+
+
+
+ Exports @interface_ at @object_path on @connection.
+
+This can be called multiple times to export the same @interface_
+onto multiple connections however the @object_path provided must be
+the same for all connections.
+
+Use g_dbus_interface_skeleton_unexport() to unexport the object.
+
+
+ %TRUE if the interface was exported on @connection, otherwise %FALSE with
+@error set.
+
+
+
+
+ The D-Bus interface to export.
+
+
+
+ A #GDBusConnection to export @interface_ on.
+
+
+
+ The path to export the interface at.
+
+
+
+
+
+ If @interface_ has outstanding changes, request for these changes to be
+emitted immediately.
+
+For example, an exported D-Bus interface may queue up property
+changes and emit the
+`org.freedesktop.DBus.Properties.PropertiesChanged`
+signal later (e.g. in an idle handler). This technique is useful
+for collapsing multiple property changes into one.
+
+
+
+
+
+
+ A #GDBusInterfaceSkeleton.
+
+
+
+
+
+ Gets the first connection that @interface_ is exported on, if any.
+
+
+ A #GDBusConnection or %NULL if @interface_ is
+not exported anywhere. Do not free, the object belongs to @interface_.
+
+
+
+
+ A #GDBusInterfaceSkeleton.
+
+
+
+
+
+ Gets a list of the connections that @interface_ is exported on.
+
+
+ A list of
+ all the connections that @interface_ is exported on. The returned
+ list should be freed with g_list_free() after each element has
+ been freed with g_object_unref().
+
+
+
+
+
+
+ A #GDBusInterfaceSkeleton.
+
+
+
+
+
+ Gets the #GDBusInterfaceSkeletonFlags that describes what the behavior
+of @interface_
+
+
+ One or more flags from the #GDBusInterfaceSkeletonFlags enumeration.
+
+
+
+
+ A #GDBusInterfaceSkeleton.
+
+
+
+
+
+ Gets D-Bus introspection information for the D-Bus interface
+implemented by @interface_.
+
+
+ A #GDBusInterfaceInfo (never %NULL). Do not free.
+
+
+
+
+ A #GDBusInterfaceSkeleton.
+
+
+
+
+
+ Gets the object path that @interface_ is exported on, if any.
+
+
+ A string owned by @interface_ or %NULL if @interface_ is not exported
+anywhere. Do not free, the string belongs to @interface_.
+
+
+
+
+ A #GDBusInterfaceSkeleton.
+
+
+
+
+
+ Gets all D-Bus properties for @interface_.
+
+
+ A #GVariant of type
+['a{sv}'][G-VARIANT-TYPE-VARDICT:CAPS].
+Free with g_variant_unref().
+
+
+
+
+ A #GDBusInterfaceSkeleton.
+
+
+
+
+
+ Gets the interface vtable for the D-Bus interface implemented by
+@interface_. The returned function pointers should expect @interface_
+itself to be passed as @user_data.
+
+
+ A #GDBusInterfaceVTable (never %NULL).
+
+
+
+
+ A #GDBusInterfaceSkeleton.
+
+
+
+
+
+ Checks if @interface_ is exported on @connection.
+
+
+ %TRUE if @interface_ is exported on @connection, %FALSE otherwise.
+
+
+
+
+ A #GDBusInterfaceSkeleton.
+
+
+
+ A #GDBusConnection.
+
+
+
+
+
+ Sets flags describing what the behavior of @skeleton should be.
+
+
+
+
+
+
+ A #GDBusInterfaceSkeleton.
+
+
+
+ Flags from the #GDBusInterfaceSkeletonFlags enumeration.
+
+
+
+
+
+ Stops exporting @interface_ on all connections it is exported on.
+
+To unexport @interface_ from only a single connection, use
+g_dbus_interface_skeleton_unexport_from_connection()
+
+
+
+
+
+
+ A #GDBusInterfaceSkeleton.
+
+
+
+
+
+ Stops exporting @interface_ on @connection.
+
+To stop exporting on all connections the interface is exported on,
+use g_dbus_interface_skeleton_unexport().
+
+
+
+
+
+
+ A #GDBusInterfaceSkeleton.
+
+
+
+ A #GDBusConnection.
+
+
+
+
+
+ Flags from the #GDBusInterfaceSkeletonFlags enumeration.
+
+
+
+
+
+
+
+
+
+ Emitted when a method is invoked by a remote caller and used to
+determine if the method call is authorized.
+
+Note that this signal is emitted in a thread dedicated to
+handling the method call so handlers are allowed to perform
+blocking IO. This means that it is appropriate to call e.g.
+[polkit_authority_check_authorization_sync()](http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#polkit-authority-check-authorization-sync)
+with the
+[POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION](http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#POLKIT-CHECK-AUTHORIZATION-FLAGS-ALLOW-USER-INTERACTION:CAPS)
+flag set.
+
+If %FALSE is returned then no further handlers are run and the
+signal handler must take a reference to @invocation and finish
+handling the call (e.g. return an error via
+g_dbus_method_invocation_return_error()).
+
+Otherwise, if %TRUE is returned, signal emission continues. If no
+handlers return %FALSE, then the method is dispatched. If
+@interface has an enclosing #GDBusObjectSkeleton, then the
+#GDBusObjectSkeleton::authorize-method signal handlers run before
+the handlers for this signal.
+
+The default class handler just returns %TRUE.
+
+Please note that the common case is optimized: if no signals
+handlers are connected and the default class handler isn't
+overridden (for both @interface and the enclosing
+#GDBusObjectSkeleton, if any) and #GDBusInterfaceSkeleton:g-flags does
+not have the
+%G_DBUS_INTERFACE_SKELETON_FLAGS_HANDLE_METHOD_INVOCATIONS_IN_THREAD
+flags set, no dedicated thread is ever used and the call will be
+handled in the same thread as the object that @interface belongs
+to was exported in.
+
+ %TRUE if the call is authorized, %FALSE otherwise.
+
+
+
+
+ A #GDBusMethodInvocation.
+
+
+
+
+
+
+ Class structure for #GDBusInterfaceSkeleton.
+
+
+ The parent class.
+
+
+
+
+
+
+ A #GDBusInterfaceInfo (never %NULL). Do not free.
+
+
+
+
+ A #GDBusInterfaceSkeleton.
+
+
+
+
+
+
+
+
+
+ A #GDBusInterfaceVTable (never %NULL).
+
+
+
+
+ A #GDBusInterfaceSkeleton.
+
+
+
+
+
+
+
+
+
+ A #GVariant of type
+['a{sv}'][G-VARIANT-TYPE-VARDICT:CAPS].
+Free with g_variant_unref().
+
+
+
+
+ A #GDBusInterfaceSkeleton.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ A #GDBusInterfaceSkeleton.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Flags describing the behavior of a #GDBusInterfaceSkeleton instance.
+
+ No flags set.
+
+
+ Each method invocation is handled in
+ a thread dedicated to the invocation. This means that the method implementation can use blocking IO
+ without blocking any other part of the process. It also means that the method implementation must
+ use locking to access data structures used by other threads.
+
+
+
+
+
+
+ Virtual table for handling properties and method calls for a D-Bus
+interface.
+
+Since 2.38, if you want to handle getting/setting D-Bus properties
+asynchronously, give %NULL as your get_property() or set_property()
+function. The D-Bus call will be directed to your @method_call function,
+with the provided @interface_name set to "org.freedesktop.DBus.Properties".
+
+Ownership of the #GDBusMethodInvocation object passed to the
+method_call() function is transferred to your handler; you must
+call one of the methods of #GDBusMethodInvocation to return a reply
+(possibly empty), or an error. These functions also take ownership
+of the passed-in invocation object, so unless the invocation
+object has otherwise been referenced, it will be then be freed.
+Calling one of these functions may be done within your
+method_call() implementation but it also can be done at a later
+point to handle the method asynchronously.
+
+The usual checks on the validity of the calls is performed. For
+`Get` calls, an error is automatically returned if the property does
+not exist or the permissions do not allow access. The same checks are
+performed for `Set` calls, and the provided value is also checked for
+being the correct type.
+
+For both `Get` and `Set` calls, the #GDBusMethodInvocation
+passed to the @method_call handler can be queried with
+g_dbus_method_invocation_get_property_info() to get a pointer
+to the #GDBusPropertyInfo of the property.
+
+If you have readable properties specified in your interface info,
+you must ensure that you either provide a non-%NULL @get_property()
+function or provide implementations of both the `Get` and `GetAll`
+methods on org.freedesktop.DBus.Properties interface in your @method_call
+function. Note that the required return type of the `Get` call is
+`(v)`, not the type of the property. `GetAll` expects a return value
+of type `a{sv}`.
+
+If you have writable properties specified in your interface info,
+you must ensure that you either provide a non-%NULL @set_property()
+function or provide an implementation of the `Set` call. If implementing
+the call, you must return the value of type %G_VARIANT_TYPE_UNIT.
+
+
+ Function for handling incoming method calls.
+
+
+
+ Function for getting a property.
+
+
+
+ Function for setting a property.
+
+
+
+
+
+
+
+
+
+ #GDBusMenuModel is an implementation of #GMenuModel that can be used
+as a proxy for a menu model that is exported over D-Bus with
+g_dbus_connection_export_menu_model().
+
+ Obtains a #GDBusMenuModel for the menu model which is exported
+at the given @bus_name and @object_path.
+
+The thread default main context is taken at the time of this call.
+All signals on the menu model (and any linked models) are reported
+with respect to this context. All calls on the returned menu model
+(and linked models) must also originate from this same context, with
+the thread default main context unchanged.
+
+
+ a #GDBusMenuModel object. Free with
+ g_object_unref().
+
+
+
+
+ a #GDBusConnection
+
+
+
+ the bus name which exports the menu model
+ or %NULL if @connection is not a message bus connection
+
+
+
+ the object path at which the menu model is exported
+
+
+
+
+
+
+ A type for representing D-Bus messages that can be sent or received
+on a #GDBusConnection.
+
+ Creates a new empty #GDBusMessage.
+
+
+ A #GDBusMessage. Free with g_object_unref().
+
+
+
+
+ Creates a new #GDBusMessage from the data stored at @blob. The byte
+order that the message was in can be retrieved using
+g_dbus_message_get_byte_order().
+
+If the @blob cannot be parsed, contains invalid fields, or contains invalid
+headers, %G_IO_ERROR_INVALID_ARGUMENT will be returned.
+
+
+ A new #GDBusMessage or %NULL if @error is set. Free with
+g_object_unref().
+
+
+
+
+ A blob representing a binary D-Bus message.
+
+
+
+
+
+ The length of @blob.
+
+
+
+ A #GDBusCapabilityFlags describing what protocol features are supported.
+
+
+
+
+
+ Creates a new #GDBusMessage for a method call.
+
+
+ A #GDBusMessage. Free with g_object_unref().
+
+
+
+
+ A valid D-Bus name or %NULL.
+
+
+
+ A valid object path.
+
+
+
+ A valid D-Bus interface name or %NULL.
+
+
+
+ A valid method name.
+
+
+
+
+
+ Creates a new #GDBusMessage for a signal emission.
+
+
+ A #GDBusMessage. Free with g_object_unref().
+
+
+
+
+ A valid object path.
+
+
+
+ A valid D-Bus interface name.
+
+
+
+ A valid signal name.
+
+
+
+
+
+ Utility function to calculate how many bytes are needed to
+completely deserialize the D-Bus message stored at @blob.
+
+
+ Number of bytes needed or -1 if @error is set (e.g. if
+@blob contains invalid data or not enough data is available to
+determine the size).
+
+
+
+
+ A blob representing a binary D-Bus message.
+
+
+
+
+
+ The length of @blob (must be at least 16).
+
+
+
+
+
+ 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.
+
+
+ A new #GDBusMessage or %NULL if @error is set.
+ Free with g_object_unref().
+
+
+
+
+ A #GDBusMessage.
+
+
+
+
+
+ Convenience to get the first item in the body of @message.
+
+
+ The string item or %NULL if the first item in the body of
+@message is not a string.
+
+
+
+
+ A #GDBusMessage.
+
+
+
+
+
+ Gets the body of a message.
+
+
+ A #GVariant or %NULL if the body is
+empty. Do not free, it is owned by @message.
+
+
+
+
+ A #GDBusMessage.
+
+
+
+
+
+ Gets the byte order of @message.
+
+
+ The byte order.
+
+
+
+
+ A #GDBusMessage.
+
+
+
+
+
+ Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.
+
+
+ The value.
+
+
+
+
+ A #GDBusMessage.
+
+
+
+
+
+ Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.
+
+
+ The value.
+
+
+
+
+ A #GDBusMessage.
+
+
+
+
+
+ Gets the flags for @message.
+
+
+ Flags that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together).
+
+
+
+
+ A #GDBusMessage.
+
+
+
+
+
+ Gets a header field on @message.
+
+The caller is responsible for checking the type of the returned #GVariant
+matches what is expected.
+
+
+ A #GVariant with the value if the header was found, %NULL
+otherwise. Do not free, it is owned by @message.
+
+
+
+
+ A #GDBusMessage.
+
+
+
+ A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration)
+
+
+
+
+
+ Gets an array of all header fields on @message that are set.
+
+
+ An array of header fields
+terminated by %G_DBUS_MESSAGE_HEADER_FIELD_INVALID. Each element
+is a #guchar. Free with g_free().
+
+
+
+
+
+
+ A #GDBusMessage.
+
+
+
+
+
+ Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.
+
+
+ The value.
+
+
+
+
+ A #GDBusMessage.
+
+
+
+
+
+ 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.
+
+
+ %TRUE if @message is locked, %FALSE otherwise.
+
+
+
+
+ A #GDBusMessage.
+
+
+
+
+
+ Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.
+
+
+ The value.
+
+
+
+
+ A #GDBusMessage.
+
+
+
+
+
+ Gets the type of @message.
+
+
+ A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration).
+
+
+
+
+ A #GDBusMessage.
+
+
+
+
+
+ Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.
+
+
+ The value.
+
+
+
+
+ A #GDBusMessage.
+
+
+
+
+
+ Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.
+
+
+ The value.
+
+
+
+
+ A #GDBusMessage.
+
+
+
+
+
+ Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.
+
+
+ The value.
+
+
+
+
+ A #GDBusMessage.
+
+
+
+
+
+ Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.
+
+
+ The value.
+
+
+
+
+ A #GDBusMessage.
+
+
+
+
+
+ Gets the serial for @message.
+
+
+ A #guint32.
+
+
+
+
+ A #GDBusMessage.
+
+
+
+
+
+ Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.
+
+This will always be non-%NULL, but may be an empty string.
+
+
+ The value.
+
+
+
+
+ A #GDBusMessage.
+
+
+
+
+
+ Gets the UNIX file descriptors associated with @message, if any.
+
+This method is only available on UNIX.
+
+The file descriptors normally correspond to %G_VARIANT_TYPE_HANDLE
+values in the body of the message. For example,
+if g_variant_get_handle() returns 5, that is intended to be a reference
+to the file descriptor that can be accessed by
+`g_unix_fd_list_get (list, 5, ...)`.
+
+
+ A #GUnixFDList or %NULL if no file descriptors are
+associated. Do not free, this object is owned by @message.
+
+
+
+
+ A #GDBusMessage.
+
+
+
+
+
+ If @message is locked, does nothing. Otherwise locks the message.
+
+
+
+
+
+
+ A #GDBusMessage.
+
+
+
+
+
+ Creates a new #GDBusMessage that is an error reply to @method_call_message.
+
+
+ A #GDBusMessage. Free with g_object_unref().
+
+
+
+
+ A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to
+create a reply message to.
+
+
+
+ A valid D-Bus error name.
+
+
+
+ The D-Bus error message in a printf() format.
+
+
+
+ Arguments for @error_message_format.
+
+
+
+
+
+ Creates a new #GDBusMessage that is an error reply to @method_call_message.
+
+
+ A #GDBusMessage. Free with g_object_unref().
+
+
+
+
+ A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to
+create a reply message to.
+
+
+
+ A valid D-Bus error name.
+
+
+
+ The D-Bus error message.
+
+
+
+
+
+ Like g_dbus_message_new_method_error() but intended for language bindings.
+
+
+ A #GDBusMessage. Free with g_object_unref().
+
+
+
+
+ A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to
+create a reply message to.
+
+
+
+ A valid D-Bus error name.
+
+
+
+ The D-Bus error message in a printf() format.
+
+
+
+ Arguments for @error_message_format.
+
+
+
+
+
+ Creates a new #GDBusMessage that is a reply to @method_call_message.
+
+
+ #GDBusMessage. Free with g_object_unref().
+
+
+
+
+ A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to
+create a reply message to.
+
+
+
+
+
+ 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:
+|[
+Flags: none
+Version: 0
+Serial: 4
+Headers:
+ path -> objectpath '/org/gtk/GDBus/TestObject'
+ interface -> 'org.gtk.GDBus.TestInterface'
+ member -> 'GimmeStdout'
+ destination -> ':1.146'
+Body: ()
+UNIX File Descriptors:
+ (none)
+]|
+or
+|[
+Flags: no-reply-expected
+Version: 0
+Serial: 477
+Headers:
+ reply-serial -> uint32 4
+ destination -> ':1.159'
+ sender -> ':1.146'
+ num-unix-fds -> uint32 1
+Body: ()
+UNIX File Descriptors:
+ fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635
+]|
+
+
+ A string that should be freed with g_free().
+
+
+
+
+ A #GDBusMessage.
+
+
+
+ Indentation level.
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+ A #GDBusMessage.
+
+
+
+ Either %NULL or a #GVariant that is a tuple.
+
+
+
+
+
+ Sets the byte order of @message.
+
+
+
+
+
+
+ A #GDBusMessage.
+
+
+
+ The byte order.
+
+
+
+
+
+ Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.
+
+
+
+
+
+
+ A #GDBusMessage.
+
+
+
+ The value to set.
+
+
+
+
+
+ Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.
+
+
+
+
+
+
+ A #GDBusMessage.
+
+
+
+ The value to set.
+
+
+
+
+
+ Sets the flags to set on @message.
+
+
+
+
+
+
+ A #GDBusMessage.
+
+
+
+ Flags for @message that are set (typically values from the #GDBusMessageFlags
+enumeration bitwise ORed together).
+
+
+
+
+
+ Sets a header field on @message.
+
+If @value is floating, @message assumes ownership of @value.
+
+
+
+
+
+
+ A #GDBusMessage.
+
+
+
+ A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration)
+
+
+
+ A #GVariant to set the header field or %NULL to clear the header field.
+
+
+
+
+
+ Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.
+
+
+
+
+
+
+ A #GDBusMessage.
+
+
+
+ The value to set.
+
+
+
+
+
+ Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.
+
+
+
+
+
+
+ A #GDBusMessage.
+
+
+
+ The value to set.
+
+
+
+
+
+ Sets @message to be of @type.
+
+
+
+
+
+
+ A #GDBusMessage.
+
+
+
+ A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration).
+
+
+
+
+
+ Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.
+
+
+
+
+
+
+ A #GDBusMessage.
+
+
+
+ The value to set.
+
+
+
+
+
+ Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.
+
+
+
+
+
+
+ A #GDBusMessage.
+
+
+
+ The value to set.
+
+
+
+
+
+ Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.
+
+
+
+
+
+
+ A #GDBusMessage.
+
+
+
+ The value to set.
+
+
+
+
+
+ Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.
+
+
+
+
+
+
+ A #GDBusMessage.
+
+
+
+ The value to set.
+
+
+
+
+
+ Sets the serial for @message.
+
+
+
+
+
+
+ A #GDBusMessage.
+
+
+
+ A #guint32.
+
+
+
+
+
+ Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.
+
+
+
+
+
+
+ A #GDBusMessage.
+
+
+
+ The value to set.
+
+
+
+
+
+ Sets the UNIX file descriptors associated with @message. As a
+side-effect the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header
+field is set to the number of fds in @fd_list (or cleared if
+@fd_list is %NULL).
+
+This method is only available on UNIX.
+
+When designing D-Bus APIs that are intended to be interoperable,
+please note that non-GDBus implementations of D-Bus can usually only
+access file descriptors if they are referenced by a value of type
+%G_VARIANT_TYPE_HANDLE in the body of the message.
+
+
+
+
+
+
+ A #GDBusMessage.
+
+
+
+ A #GUnixFDList or %NULL.
+
+
+
+
+
+ Serializes @message to a blob. The byte order returned by
+g_dbus_message_get_byte_order() will be used.
+
+
+ A pointer to a
+valid binary D-Bus message of @out_size bytes generated by @message
+or %NULL if @error is set. Free with g_free().
+
+
+
+
+
+
+ A #GDBusMessage.
+
+
+
+ Return location for size of generated blob.
+
+
+
+ A #GDBusCapabilityFlags describing what protocol features are supported.
+
+
+
+
+
+ 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.
+
+
+ %TRUE if @error was set, %FALSE otherwise.
+
+
+
+
+ A #GDBusMessage.
+
+
+
+
+
+
+
+
+
+ Enumeration used to describe the byte order of a D-Bus message.
+
+ The byte order is big endian.
+
+
+ The byte order is little endian.
+
+
+
+ Signature for function used in g_dbus_connection_add_filter().
+
+A filter function is passed a #GDBusMessage and expected to return
+a #GDBusMessage too. Passive filter functions that don't modify the
+message can simply return the @message object:
+|[
+static GDBusMessage *
+passive_filter (GDBusConnection *connection
+ GDBusMessage *message,
+ gboolean incoming,
+ gpointer user_data)
+{
+ // inspect @message
+ return message;
+}
+]|
+Filter functions that wants to drop a message can simply return %NULL:
+|[
+static GDBusMessage *
+drop_filter (GDBusConnection *connection
+ GDBusMessage *message,
+ gboolean incoming,
+ gpointer user_data)
+{
+ if (should_drop_message)
+ {
+ g_object_unref (message);
+ message = NULL;
+ }
+ return message;
+}
+]|
+Finally, a filter function may modify a message by copying it:
+|[
+static GDBusMessage *
+modifying_filter (GDBusConnection *connection
+ GDBusMessage *message,
+ gboolean incoming,
+ gpointer user_data)
+{
+ GDBusMessage *copy;
+ GError *error;
+
+ error = NULL;
+ copy = g_dbus_message_copy (message, &error);
+ // handle @error being set
+ g_object_unref (message);
+
+ // modify @copy
+
+ return copy;
+}
+]|
+If the returned #GDBusMessage is different from @message and cannot
+be sent on @connection (it could use features, such as file
+descriptors, not compatible with @connection), then a warning is
+logged to standard error. Applications can
+check this ahead of time using g_dbus_message_to_blob() passing a
+#GDBusCapabilityFlags value obtained from @connection.
+
+
+ A #GDBusMessage that will be freed with
+g_object_unref() or %NULL to drop the message. Passive filter
+functions can simply return the passed @message object.
+
+
+
+
+ A #GDBusConnection.
+
+
+
+ A locked #GDBusMessage that the filter function takes ownership of.
+
+
+
+ %TRUE if it is a message received from the other peer, %FALSE if it is
+a message to be sent to the other peer.
+
+
+
+ User data passed when adding the filter.
+
+
+
+
+
+ Message flags used in #GDBusMessage.
+
+ No flags set.
+
+
+ A reply is not expected.
+
+
+ The bus must not launch an
+owner for the destination name in response to this message.
+
+
+ If set on a method
+call, this flag means that the caller is prepared to wait for interactive
+authorization. Since 2.46.
+
+
+
+ Header fields used in #GDBusMessage.
+
+ Not a valid header field.
+
+
+ The object path.
+
+
+ The interface name.
+
+
+ The method or signal name.
+
+
+ The name of the error that occurred.
+
+
+ The serial number the message is a reply to.
+
+
+ The name the message is intended for.
+
+
+ Unique name of the sender of the message (filled in by the bus).
+
+
+ The signature of the message body.
+
+
+ The number of UNIX file descriptors that accompany the message.
+
+
+
+ Message types used in #GDBusMessage.
+
+ Message is of invalid type.
+
+
+ Method call.
+
+
+ Method reply.
+
+
+ Error reply.
+
+
+ Signal emission.
+
+
+
+ Information about a method on an D-Bus interface.
+
+
+ The reference count or -1 if statically allocated.
+
+
+
+ The name of the D-Bus method, e.g. @RequestName.
+
+
+
+ A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no in arguments.
+
+
+
+
+
+ A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no out arguments.
+
+
+
+
+
+ A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
+
+
+
+
+
+ If @info is statically allocated does nothing. Otherwise increases
+the reference count.
+
+
+ The same @info.
+
+
+
+
+ A #GDBusMethodInfo
+
+
+
+
+
+ If @info is statically allocated, does nothing. Otherwise decreases
+the reference count of @info. When its reference count drops to 0,
+the memory used is freed.
+
+
+
+
+
+
+ A #GDBusMethodInfo.
+
+
+
+
+
+
+ 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().
+
+ Gets the #GDBusConnection the method was invoked on.
+
+
+ A #GDBusConnection. Do not free, it is owned by @invocation.
+
+
+
+
+ A #GDBusMethodInvocation.
+
+
+
+
+
+ Gets the name of the D-Bus interface the method was invoked on.
+
+If this method call is a property Get, Set or GetAll call that has
+been redirected to the method call handler then
+"org.freedesktop.DBus.Properties" will be returned. See
+#GDBusInterfaceVTable for more information.
+
+
+ A string. Do not free, it is owned by @invocation.
+
+
+
+
+ A #GDBusMethodInvocation.
+
+
+
+
+
+ Gets the #GDBusMessage for the method invocation. This is useful if
+you need to use low-level protocol features, such as UNIX file
+descriptor passing, that cannot be properly expressed in the
+#GVariant API.
+
+See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
+for an example of how to use this low-level API to send and receive
+UNIX file descriptors.
+
+
+ #GDBusMessage. Do not free, it is owned by @invocation.
+
+
+
+
+ A #GDBusMethodInvocation.
+
+
+
+
+
+ Gets information about the method call, if any.
+
+If this method invocation is a property Get, Set or GetAll call that
+has been redirected to the method call handler then %NULL will be
+returned. See g_dbus_method_invocation_get_property_info() and
+#GDBusInterfaceVTable for more information.
+
+
+ A #GDBusMethodInfo or %NULL. Do not free, it is owned by @invocation.
+
+
+
+
+ A #GDBusMethodInvocation.
+
+
+
+
+
+ Gets the name of the method that was invoked.
+
+
+ A string. Do not free, it is owned by @invocation.
+
+
+
+
+ A #GDBusMethodInvocation.
+
+
+
+
+
+ Gets the object path the method was invoked on.
+
+
+ A string. Do not free, it is owned by @invocation.
+
+
+
+
+ A #GDBusMethodInvocation.
+
+
+
+
+
+ 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.
+
+
+ A #GVariant tuple. Do not unref this because it is owned by @invocation.
+
+
+
+
+ A #GDBusMethodInvocation.
+
+
+
+
+
+ Gets information about the property that this method call is for, if
+any.
+
+This will only be set in the case of an invocation in response to a
+property Get or Set call that has been directed to the method call
+handler for an object on account of its property_get() or
+property_set() vtable pointers being unset.
+
+See #GDBusInterfaceVTable for more information.
+
+If the call was GetAll, %NULL will be returned.
+
+
+ a #GDBusPropertyInfo or %NULL
+
+
+
+
+ A #GDBusMethodInvocation
+
+
+
+
+
+ Gets the bus name that invoked the method.
+
+
+ A string. Do not free, it is owned by @invocation.
+
+
+
+
+ A #GDBusMethodInvocation.
+
+
+
+
+
+ Gets the @user_data #gpointer passed to g_dbus_connection_register_object().
+
+
+ A #gpointer.
+
+
+
+
+ A #GDBusMethodInvocation.
+
+
+
+
+
+ Finishes handling a D-Bus method call by returning an error.
+
+This method will take ownership of @invocation. See
+#GDBusInterfaceVTable for more information about the ownership of
+@invocation.
+
+
+
+
+
+
+ A #GDBusMethodInvocation.
+
+
+
+ A valid D-Bus error name.
+
+
+
+ A valid D-Bus error message.
+
+
+
+
+
+ Finishes handling a D-Bus method call by returning an error.
+
+See g_dbus_error_encode_gerror() for details about what error name
+will be returned on the wire. In a nutshell, if the given error is
+registered using g_dbus_error_register_error() the name given
+during registration is used. Otherwise, a name of the form
+`org.gtk.GDBus.UnmappedGError.Quark...` is used. This provides
+transparent mapping of #GError between applications using GDBus.
+
+If you are writing an application intended to be portable,
+always register errors with g_dbus_error_register_error()
+or use g_dbus_method_invocation_return_dbus_error().
+
+This method will take ownership of @invocation. See
+#GDBusInterfaceVTable for more information about the ownership of
+@invocation.
+
+Since 2.48, if the method call requested for a reply not to be sent
+then this call will free @invocation but otherwise do nothing (as per
+the recommendations of the D-Bus specification).
+
+
+
+
+
+
+ A #GDBusMethodInvocation.
+
+
+
+ A #GQuark for the #GError error domain.
+
+
+
+ The error code.
+
+
+
+ printf()-style format.
+
+
+
+ Parameters for @format.
+
+
+
+
+
+ Like g_dbus_method_invocation_return_error() but without printf()-style formatting.
+
+This method will take ownership of @invocation. See
+#GDBusInterfaceVTable for more information about the ownership of
+@invocation.
+
+
+
+
+
+
+ A #GDBusMethodInvocation.
+
+
+
+ A #GQuark for the #GError error domain.
+
+
+
+ The error code.
+
+
+
+ The error message.
+
+
+
+
+
+ Like g_dbus_method_invocation_return_error() but intended for
+language bindings.
+
+This method will take ownership of @invocation. See
+#GDBusInterfaceVTable for more information about the ownership of
+@invocation.
+
+
+
+
+
+
+ A #GDBusMethodInvocation.
+
+
+
+ A #GQuark for the #GError error domain.
+
+
+
+ The error code.
+
+
+
+ printf()-style format.
+
+
+
+ #va_list of parameters for @format.
+
+
+
+
+
+ Like g_dbus_method_invocation_return_error() but takes a #GError
+instead of the error domain, error code and message.
+
+This method will take ownership of @invocation. See
+#GDBusInterfaceVTable for more information about the ownership of
+@invocation.
+
+
+
+
+
+
+ A #GDBusMethodInvocation.
+
+
+
+ A #GError.
+
+
+
+
+
+ Finishes handling a D-Bus method call by returning @parameters.
+If the @parameters GVariant is floating, it is consumed.
+
+It is an error if @parameters is not of the right format: it must be a tuple
+containing the out-parameters of the D-Bus method. Even if the method has a
+single out-parameter, it must be contained in a tuple. If the method has no
+out-parameters, @parameters may be %NULL or an empty tuple.
+
+|[<!-- language="C" -->
+GDBusMethodInvocation *invocation = some_invocation;
+g_autofree gchar *result_string = NULL;
+g_autoptr (GError) error = NULL;
+
+result_string = calculate_result (&error);
+
+if (error != NULL)
+ g_dbus_method_invocation_return_gerror (invocation, error);
+else
+ g_dbus_method_invocation_return_value (invocation,
+ g_variant_new ("(s)", result_string));
+
+// Do not free @invocation here; returning a value does that
+]|
+
+This method will take ownership of @invocation. See
+#GDBusInterfaceVTable for more information about the ownership of
+@invocation.
+
+Since 2.48, if the method call requested for a reply not to be sent
+then this call will sink @parameters and free @invocation, but
+otherwise do nothing (as per the recommendations of the D-Bus
+specification).
+
+
+
+
+
+
+ A #GDBusMethodInvocation.
+
+
+
+ A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.
+
+
+
+
+
+ Like g_dbus_method_invocation_return_value() but also takes a #GUnixFDList.
+
+This method is only available on UNIX.
+
+This method will take ownership of @invocation. See
+#GDBusInterfaceVTable for more information about the ownership of
+@invocation.
+
+
+
+
+
+
+ A #GDBusMethodInvocation.
+
+
+
+ A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.
+
+
+
+ A #GUnixFDList or %NULL.
+
+
+
+
+
+ Like g_dbus_method_invocation_return_gerror() but takes ownership
+of @error so the caller does not need to free it.
+
+This method will take ownership of @invocation. See
+#GDBusInterfaceVTable for more information about the ownership of
+@invocation.
+
+
+
+
+
+
+ A #GDBusMethodInvocation.
+
+
+
+ A #GError.
+
+
+
+
+
+
+ Information about nodes in a remote object hierarchy.
+
+
+ The reference count or -1 if statically allocated.
+
+
+
+ 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.
+
+
+
+ A pointer to a %NULL-terminated array of pointers to #GDBusInterfaceInfo structures or %NULL if there are no interfaces.
+
+
+
+
+
+ A pointer to a %NULL-terminated array of pointers to #GDBusNodeInfo structures or %NULL if there are no nodes.
+
+
+
+
+
+ A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
+
+
+
+
+
+ Parses @xml_data and returns a #GDBusNodeInfo representing the data.
+
+The introspection XML must contain exactly one top-level
+<node> element.
+
+Note that this routine is using a
+[GMarkup][glib-Simple-XML-Subset-Parser.description]-based
+parser that only accepts a subset of valid XML documents.
+
+
+ A #GDBusNodeInfo structure or %NULL if @error is set. Free
+with g_dbus_node_info_unref().
+
+
+
+
+ Valid D-Bus introspection XML.
+
+
+
+
+
+ Appends an XML representation of @info (and its children) to @string_builder.
+
+This function is typically used for generating introspection XML documents at run-time for
+handling the `org.freedesktop.DBus.Introspectable.Introspect` method.
+
+
+
+
+
+
+ A #GDBusNodeInfo.
+
+
+
+ Indentation level.
+
+
+
+ A #GString to to append XML data to.
+
+
+
+
+
+ Looks up information about an interface.
+
+The cost of this function is O(n) in number of interfaces.
+
+
+ A #GDBusInterfaceInfo or %NULL if not found. Do not free, it is owned by @info.
+
+
+
+
+ A #GDBusNodeInfo.
+
+
+
+ A D-Bus interface name.
+
+
+
+
+
+ If @info is statically allocated does nothing. Otherwise increases
+the reference count.
+
+
+ The same @info.
+
+
+
+
+ A #GDBusNodeInfo
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+ A #GDBusNodeInfo.
+
+
+
+
+
+
+ The #GDBusObject type is the base type for D-Bus objects on both
+the service side (see #GDBusObjectSkeleton) and the client side
+(see #GDBusObjectProxy). It is essentially just a container of
+interfaces.
+
+
+ Gets the D-Bus interface with name @interface_name associated with
+@object, if any.
+
+
+ %NULL if not found, otherwise a
+ #GDBusInterface that must be freed with g_object_unref().
+
+
+
+
+ A #GDBusObject.
+
+
+
+ A D-Bus interface name.
+
+
+
+
+
+ Gets the D-Bus interfaces associated with @object.
+
+
+ A list of #GDBusInterface instances.
+ The returned list must be freed by g_list_free() after each element has been freed
+ with g_object_unref().
+
+
+
+
+
+
+ A #GDBusObject.
+
+
+
+
+
+ Gets the object path for @object.
+
+
+ A string owned by @object. Do not free.
+
+
+
+
+ A #GDBusObject.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Gets the D-Bus interface with name @interface_name associated with
+@object, if any.
+
+
+ %NULL if not found, otherwise a
+ #GDBusInterface that must be freed with g_object_unref().
+
+
+
+
+ A #GDBusObject.
+
+
+
+ A D-Bus interface name.
+
+
+
+
+
+ Gets the D-Bus interfaces associated with @object.
+
+
+ A list of #GDBusInterface instances.
+ The returned list must be freed by g_list_free() after each element has been freed
+ with g_object_unref().
+
+
+
+
+
+
+ A #GDBusObject.
+
+
+
+
+
+ Gets the object path for @object.
+
+
+ A string owned by @object. Do not free.
+
+
+
+
+ A #GDBusObject.
+
+
+
+
+
+ Emitted when @interface is added to @object.
+
+
+
+
+
+ The #GDBusInterface that was added.
+
+
+
+
+
+ Emitted when @interface is removed from @object.
+
+
+
+
+
+ The #GDBusInterface that was removed.
+
+
+
+
+
+
+ Base object type for D-Bus objects.
+
+
+ The parent interface.
+
+
+
+
+
+
+ A string owned by @object. Do not free.
+
+
+
+
+ A #GDBusObject.
+
+
+
+
+
+
+
+
+
+ A list of #GDBusInterface instances.
+ The returned list must be freed by g_list_free() after each element has been freed
+ with g_object_unref().
+
+
+
+
+
+
+ A #GDBusObject.
+
+
+
+
+
+
+
+
+
+ %NULL if not found, otherwise a
+ #GDBusInterface that must be freed with g_object_unref().
+
+
+
+
+ A #GDBusObject.
+
+
+
+ A D-Bus interface name.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The #GDBusObjectManager type is the base type for service- and
+client-side implementations of the standardized
+[org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager)
+interface.
+
+See #GDBusObjectManagerClient for the client-side implementation
+and #GDBusObjectManagerServer for the service-side implementation.
+
+
+ Gets the interface proxy for @interface_name at @object_path, if
+any.
+
+
+ A #GDBusInterface instance or %NULL. Free
+ with g_object_unref().
+
+
+
+
+ A #GDBusObjectManager.
+
+
+
+ Object path to look up.
+
+
+
+ D-Bus interface name to look up.
+
+
+
+
+
+ Gets the #GDBusObject at @object_path, if any.
+
+
+ A #GDBusObject or %NULL. Free with
+ g_object_unref().
+
+
+
+
+ A #GDBusObjectManager.
+
+
+
+ Object path to look up.
+
+
+
+
+
+ Gets the object path that @manager is for.
+
+
+ A string owned by @manager. Do not free.
+
+
+
+
+ A #GDBusObjectManager.
+
+
+
+
+
+ Gets all #GDBusObject objects known to @manager.
+
+
+ A list of
+ #GDBusObject objects. The returned list should be freed with
+ g_list_free() after each element has been freed with
+ g_object_unref().
+
+
+
+
+
+
+ A #GDBusObjectManager.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Gets the interface proxy for @interface_name at @object_path, if
+any.
+
+
+ A #GDBusInterface instance or %NULL. Free
+ with g_object_unref().
+
+
+
+
+ A #GDBusObjectManager.
+
+
+
+ Object path to look up.
+
+
+
+ D-Bus interface name to look up.
+
+
+
+
+
+ Gets the #GDBusObject at @object_path, if any.
+
+
+ A #GDBusObject or %NULL. Free with
+ g_object_unref().
+
+
+
+
+ A #GDBusObjectManager.
+
+
+
+ Object path to look up.
+
+
+
+
+
+ Gets the object path that @manager is for.
+
+
+ A string owned by @manager. Do not free.
+
+
+
+
+ A #GDBusObjectManager.
+
+
+
+
+
+ Gets all #GDBusObject objects known to @manager.
+
+
+ A list of
+ #GDBusObject objects. The returned list should be freed with
+ g_list_free() after each element has been freed with
+ g_object_unref().
+
+
+
+
+
+
+ A #GDBusObjectManager.
+
+
+
+
+
+ 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.
+
+
+
+
+
+ The #GDBusObject on which an interface was added.
+
+
+
+ The #GDBusInterface that was added.
+
+
+
+
+
+ Emitted when @interface has been removed from @object.
+
+This signal exists purely as a convenience to avoid having to
+connect signals to all objects managed by @manager.
+
+
+
+
+
+ The #GDBusObject on which an interface was removed.
+
+
+
+ The #GDBusInterface that was removed.
+
+
+
+
+
+ Emitted when @object is added to @manager.
+
+
+
+
+
+ The #GDBusObject that was added.
+
+
+
+
+
+ Emitted when @object is removed from @manager.
+
+
+
+
+
+ The #GDBusObject that was removed.
+
+
+
+
+
+
+ #GDBusObjectManagerClient is used to create, monitor and delete object
+proxies for remote objects exported by a #GDBusObjectManagerServer (or any
+code implementing the
+[org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager)
+interface).
+
+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. `:1.42`) and %NULL even in the case where
+the name of interest is atomically replaced
+
+Ultimately, #GDBusObjectManagerClient is used to obtain #GDBusProxy
+instances. All signals (including the
+org.freedesktop.DBus.Properties::PropertiesChanged signal)
+delivered to #GDBusProxy instances are guaranteed to originate
+from the name owner. This guarantee along with the behavior
+described above, means that certain race conditions including the
+"half the proxy is from the old owner and the other half is from
+the new owner" problem cannot happen.
+
+To avoid having the application connect to signals on the returned
+#GDBusObjectProxy and #GDBusProxy objects, the
+#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
+[thread-default main context][g-main-context-push-thread-default]
+that the #GDBusObjectManagerClient object was constructed
+in. Additionally, the #GDBusObjectProxy and #GDBusProxy objects
+originating from the #GDBusObjectManagerClient object will be created in
+the same context and, consequently, will deliver signals in the
+same main loop.
+
+
+
+
+
+ Finishes an operation started with g_dbus_object_manager_client_new().
+
+
+ A
+ #GDBusObjectManagerClient object or %NULL if @error is set. Free
+ with g_object_unref().
+
+
+
+
+ A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new().
+
+
+
+
+
+ Finishes an operation started with g_dbus_object_manager_client_new_for_bus().
+
+
+ A
+ #GDBusObjectManagerClient object or %NULL if @error is set. Free
+ with g_object_unref().
+
+
+
+
+ A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new_for_bus().
+
+
+
+
+
+ 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.
+
+
+ A
+ #GDBusObjectManagerClient object or %NULL if @error is set. Free
+ with g_object_unref().
+
+
+
+
+ A #GBusType.
+
+
+
+ Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
+
+
+
+ The owner of the control object (unique or well-known name).
+
+
+
+ The object path of the control object.
+
+
+
+ A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
+
+
+
+ User data to pass to @get_proxy_type_func.
+
+
+
+ Free function for @get_proxy_type_user_data or %NULL.
+
+
+
+ A #GCancellable or %NULL
+
+
+
+
+
+ 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.
+
+
+ A
+ #GDBusObjectManagerClient object or %NULL if @error is set. Free
+ with g_object_unref().
+
+
+
+
+ A #GDBusConnection.
+
+
+
+ Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
+
+
+
+ The owner of the control object (unique or well-known name), or %NULL when not using a message bus connection.
+
+
+
+ The object path of the control object.
+
+
+
+ A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
+
+
+
+ User data to pass to @get_proxy_type_func.
+
+
+
+ Free function for @get_proxy_type_user_data or %NULL.
+
+
+
+ A #GCancellable or %NULL
+
+
+
+
+
+ Asynchronously creates a new #GDBusObjectManagerClient object.
+
+This is an asynchronous failable constructor. When the result is
+ready, @callback will be invoked in the
+[thread-default main context][g-main-context-push-thread-default]
+of the thread you are calling this method from. You can
+then call g_dbus_object_manager_client_new_finish() to get the result. See
+g_dbus_object_manager_client_new_sync() for the synchronous version.
+
+
+
+
+
+
+ A #GDBusConnection.
+
+
+
+ Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
+
+
+
+ The owner of the control object (unique or well-known name).
+
+
+
+ The object path of the control object.
+
+
+
+ A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
+
+
+
+ User data to pass to @get_proxy_type_func.
+
+
+
+ Free function for @get_proxy_type_user_data or %NULL.
+
+
+
+ A #GCancellable or %NULL
+
+
+
+ A #GAsyncReadyCallback to call when the request is satisfied.
+
+
+
+ The data to pass to @callback.
+
+
+
+
+
+ Like g_dbus_object_manager_client_new() but takes a #GBusType instead of a
+#GDBusConnection.
+
+This is an asynchronous failable constructor. When the result is
+ready, @callback will be invoked in the
+[thread-default main loop][g-main-context-push-thread-default]
+of the thread you are calling this method from. You can
+then call g_dbus_object_manager_client_new_for_bus_finish() to get the result. See
+g_dbus_object_manager_client_new_for_bus_sync() for the synchronous version.
+
+
+
+
+
+
+ A #GBusType.
+
+
+
+ Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
+
+
+
+ The owner of the control object (unique or well-known name).
+
+
+
+ The object path of the control object.
+
+
+
+ A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
+
+
+
+ User data to pass to @get_proxy_type_func.
+
+
+
+ Free function for @get_proxy_type_user_data or %NULL.
+
+
+
+ A #GCancellable or %NULL
+
+
+
+ A #GAsyncReadyCallback to call when the request is satisfied.
+
+
+
+ The data to pass to @callback.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Gets the #GDBusConnection used by @manager.
+
+
+ A #GDBusConnection object. Do not free,
+ the object belongs to @manager.
+
+
+
+
+ A #GDBusObjectManagerClient
+
+
+
+
+
+ Gets the flags that @manager was constructed with.
+
+
+ Zero of more flags from the #GDBusObjectManagerClientFlags
+enumeration.
+
+
+
+
+ A #GDBusObjectManagerClient
+
+
+
+
+
+ Gets the name that @manager is for, or %NULL if not a message bus
+connection.
+
+
+ A unique or well-known name. Do not free, the string
+belongs to @manager.
+
+
+
+
+ A #GDBusObjectManagerClient
+
+
+
+
+
+ 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.
+
+
+ The name owner or %NULL if no name owner
+exists. Free with g_free().
+
+
+
+
+ A #GDBusObjectManagerClient.
+
+
+
+
+
+ If this property is not %G_BUS_TYPE_NONE, then
+#GDBusObjectManagerClient:connection must be %NULL and will be set to the
+#GDBusConnection obtained by calling g_bus_get() with the value
+of this property.
+
+
+
+ The #GDBusConnection to use.
+
+
+
+ Flags from the #GDBusObjectManagerClientFlags enumeration.
+
+
+
+ A #GDestroyNotify for the #gpointer user_data in #GDBusObjectManagerClient:get-proxy-type-user-data.
+
+
+
+ The #GDBusProxyTypeFunc to use when determining what #GType to
+use for interface proxies or %NULL.
+
+
+
+ The #gpointer user_data to pass to #GDBusObjectManagerClient:get-proxy-type-func.
+
+
+
+ The well-known name or unique name that the manager is for.
+
+
+
+ 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.
+
+
+
+ The object path the manager is for.
+
+
+
+
+
+
+
+
+
+ Emitted when one or more D-Bus properties on proxy changes. The
+local cache has already been updated when this signal fires. Note
+that both @changed_properties and @invalidated_properties are
+guaranteed to never be %NULL (either may be empty though).
+
+This signal exists purely as a convenience to avoid having to
+connect signals to all interface proxies managed by @manager.
+
+This signal is emitted in the
+[thread-default main context][g-main-context-push-thread-default]
+that @manager was constructed in.
+
+
+
+
+
+ The #GDBusObjectProxy on which an interface has properties that are changing.
+
+
+
+ The #GDBusProxy that has properties that are changing.
+
+
+
+ A #GVariant containing the properties that changed (type: `a{sv}`).
+
+
+
+ A %NULL terminated
+ array of properties that were invalidated.
+
+
+
+
+
+
+
+ Emitted when a D-Bus signal is received on @interface_proxy.
+
+This signal exists purely as a convenience to avoid having to
+connect signals to all interface proxies managed by @manager.
+
+This signal is emitted in the
+[thread-default main context][g-main-context-push-thread-default]
+that @manager was constructed in.
+
+
+
+
+
+ The #GDBusObjectProxy on which an interface is emitting a D-Bus signal.
+
+
+
+ The #GDBusProxy that is emitting a D-Bus signal.
+
+
+
+ The sender of the signal or NULL if the connection is not a bus connection.
+
+
+
+ The signal name.
+
+
+
+ A #GVariant tuple with parameters for the signal.
+
+
+
+
+
+
+ Class structure for #GDBusObjectManagerClient.
+
+
+ The parent class.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Flags used when constructing a #GDBusObjectManagerClient.
+
+ No flags set.
+
+
+ If not set and the
+ manager is for a well-known name, then request the bus to launch
+ an owner for the name if no-one owns the name. This flag can only
+ be used in managers for well-known names.
+
+
+
+
+
+
+ Base type for D-Bus object managers.
+
+
+ The parent interface.
+
+
+
+
+
+
+ A string owned by @manager. Do not free.
+
+
+
+
+ A #GDBusObjectManager.
+
+
+
+
+
+
+
+
+
+ A list of
+ #GDBusObject objects. The returned list should be freed with
+ g_list_free() after each element has been freed with
+ g_object_unref().
+
+
+
+
+
+
+ A #GDBusObjectManager.
+
+
+
+
+
+
+
+
+
+ A #GDBusObject or %NULL. Free with
+ g_object_unref().
+
+
+
+
+ A #GDBusObjectManager.
+
+
+
+ Object path to look up.
+
+
+
+
+
+
+
+
+
+ A #GDBusInterface instance or %NULL. Free
+ with g_object_unref().
+
+
+
+
+ A #GDBusObjectManager.
+
+
+
+ Object path to look up.
+
+
+
+ D-Bus interface name to look up.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #GDBusObjectManagerServer is used to export #GDBusObject instances using
+the standardized
+[org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager)
+interface. For example, remote D-Bus clients can get all objects
+and properties in a single call. Additionally, any change in the
+object hierarchy is broadcast using signals. This means that D-Bus
+clients can keep caches up to date by only listening to D-Bus
+signals.
+
+The recommended path to export an object manager at is the path form of the
+well-known name of a D-Bus service, or below. For example, if a D-Bus service
+is available at the well-known name `net.example.ExampleService1`, the object
+manager should typically be exported at `/net/example/ExampleService1`, or
+below (to allow for multiple object managers in a service).
+
+It is supported, but not recommended, to export an object manager at the root
+path, `/`.
+
+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.
+
+
+
+ Creates a new #GDBusObjectManagerServer object.
+
+The returned server isn't yet exported on any connection. To do so,
+use g_dbus_object_manager_server_set_connection(). Normally you
+want to export all of your objects before doing so to avoid
+[InterfacesAdded](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager)
+signals being emitted.
+
+
+ A #GDBusObjectManagerServer object. Free with g_object_unref().
+
+
+
+
+ The object path to export the manager object at.
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+ A #GDBusObjectManagerServer.
+
+
+
+ A #GDBusObjectSkeleton.
+
+
+
+
+
+ Like g_dbus_object_manager_server_export() but appends a string of
+the form _N (with N being a natural number) to @object's object path
+if an object with the given path already exists. As such, the
+#GDBusObjectProxy:g-object-path property of @object may be modified.
+
+
+
+
+
+
+ A #GDBusObjectManagerServer.
+
+
+
+ An object.
+
+
+
+
+
+ Gets the #GDBusConnection used by @manager.
+
+
+ A #GDBusConnection object or %NULL if
+ @manager isn't exported on a connection. The returned object should
+ be freed with g_object_unref().
+
+
+
+
+ A #GDBusObjectManagerServer
+
+
+
+
+
+ Returns whether @object is currently exported on @manager.
+
+
+ %TRUE if @object is exported
+
+
+
+
+ A #GDBusObjectManagerServer.
+
+
+
+ An object.
+
+
+
+
+
+ Exports all objects managed by @manager on @connection. If
+@connection is %NULL, stops exporting objects.
+
+
+
+
+
+
+ A #GDBusObjectManagerServer.
+
+
+
+ A #GDBusConnection or %NULL.
+
+
+
+
+
+ If @manager has an object at @path, removes the object. Otherwise
+does nothing.
+
+Note that @object_path must be in the hierarchy rooted by the
+object path for @manager.
+
+
+ %TRUE if object at @object_path was removed, %FALSE otherwise.
+
+
+
+
+ A #GDBusObjectManagerServer.
+
+
+
+ An object path.
+
+
+
+
+
+ The #GDBusConnection to export objects on.
+
+
+
+ The object path to register the manager object at.
+
+
+
+
+
+
+
+
+
+
+ Class structure for #GDBusObjectManagerServer.
+
+
+ The parent class.
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+
+
+ Creates a new #GDBusObjectProxy for the given connection and
+object path.
+
+
+ a new #GDBusObjectProxy
+
+
+
+
+ a #GDBusConnection
+
+
+
+ the object path
+
+
+
+
+
+ Gets the connection that @proxy is for.
+
+
+ A #GDBusConnection. Do not free, the
+ object is owned by @proxy.
+
+
+
+
+ a #GDBusObjectProxy
+
+
+
+
+
+ The connection of the proxy.
+
+
+
+ The object path of the proxy.
+
+
+
+
+
+
+
+
+
+
+ Class structure for #GDBusObjectProxy.
+
+
+ The parent class.
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+
+
+ Creates a new #GDBusObjectSkeleton.
+
+
+ A #GDBusObjectSkeleton. Free with g_object_unref().
+
+
+
+
+ An object path.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+ A #GDBusObjectSkeleton.
+
+
+
+ A #GDBusInterfaceSkeleton.
+
+
+
+
+
+ This method simply calls g_dbus_interface_skeleton_flush() on all
+interfaces belonging to @object. See that method for when flushing
+is useful.
+
+
+
+
+
+
+ A #GDBusObjectSkeleton.
+
+
+
+
+
+ Removes @interface_ from @object.
+
+
+
+
+
+
+ A #GDBusObjectSkeleton.
+
+
+
+ A #GDBusInterfaceSkeleton.
+
+
+
+
+
+ Removes the #GDBusInterface with @interface_name from @object.
+
+If no D-Bus interface of the given interface exists, this function
+does nothing.
+
+
+
+
+
+
+ A #GDBusObjectSkeleton.
+
+
+
+ A D-Bus interface name.
+
+
+
+
+
+ Sets the object path for @object.
+
+
+
+
+
+
+ A #GDBusObjectSkeleton.
+
+
+
+ A valid D-Bus object path.
+
+
+
+
+
+ The object path where the object is exported.
+
+
+
+
+
+
+
+
+
+ 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.
+
+ %TRUE if the call is authorized, %FALSE otherwise.
+
+
+
+
+ The #GDBusInterfaceSkeleton that @invocation is for.
+
+
+
+ A #GDBusMethodInvocation.
+
+
+
+
+
+
+ Class structure for #GDBusObjectSkeleton.
+
+
+ The parent class.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Information about a D-Bus property on a D-Bus interface.
+
+
+ The reference count or -1 if statically allocated.
+
+
+
+ The name of the D-Bus property, e.g. "SupportedFilesystems".
+
+
+
+ The D-Bus signature of the property (a single complete type).
+
+
+
+ Access control flags for the property.
+
+
+
+ A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
+
+
+
+
+
+ If @info is statically allocated does nothing. Otherwise increases
+the reference count.
+
+
+ The same @info.
+
+
+
+
+ A #GDBusPropertyInfo
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+ A #GDBusPropertyInfo.
+
+
+
+
+
+
+ Flags describing the access control of a D-Bus property.
+
+ No flags set.
+
+
+ Property is readable.
+
+
+ Property is writable.
+
+
+
+ #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 get
+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.
+
+The unique name owner of the proxy's 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).
+
+If the proxy is for a stateless D-Bus service, where the name owner may
+be started and stopped between calls, the #GDBusProxy:g-name-owner tracking
+of #GDBusProxy will cause the proxy to drop signal and property changes from
+the service after it has restarted for the first time. When interacting
+with a stateless D-Bus service, do not use #GDBusProxy — use direct D-Bus
+method calls and signal connections.
+
+The generic #GDBusProxy::g-properties-changed and
+#GDBusProxy::g-signal signals are not very convenient to work with.
+Therefore, the recommended way of working with proxies is to subclass
+#GDBusProxy, and have more natural properties and signals in your derived
+class. This [example][gdbus-example-gdbus-codegen] shows how this can
+easily be done using the [gdbus-codegen][gdbus-codegen] tool.
+
+A #GDBusProxy instance can be used from multiple threads but note
+that all signals (e.g. #GDBusProxy::g-signal, #GDBusProxy::g-properties-changed
+and #GObject::notify) are emitted in the
+[thread-default main context][g-main-context-push-thread-default]
+of the thread where the instance was constructed.
+
+An example using a proxy for a well-known name can be found in
+[gdbus-example-watch-proxy.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-watch-proxy.c)
+
+
+
+
+
+ Finishes creating a #GDBusProxy.
+
+
+ A #GDBusProxy or %NULL if @error is set.
+ Free with g_object_unref().
+
+
+
+
+ A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new().
+
+
+
+
+
+ Finishes creating a #GDBusProxy.
+
+
+ A #GDBusProxy or %NULL if @error is set.
+ Free with g_object_unref().
+
+
+
+
+ A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new_for_bus().
+
+
+
+
+
+ Like g_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection.
+
+#GDBusProxy is used in this [example][gdbus-wellknown-proxy].
+
+
+ A #GDBusProxy or %NULL if error is set.
+ Free with g_object_unref().
+
+
+
+
+ A #GBusType.
+
+
+
+ Flags used when constructing the proxy.
+
+
+
+ A #GDBusInterfaceInfo specifying the minimal interface
+ that @proxy conforms to or %NULL.
+
+
+
+ A bus name (well-known or unique).
+
+
+
+ An object path.
+
+
+
+ A D-Bus interface name.
+
+
+
+ A #GCancellable or %NULL.
+
+
+
+
+
+ Creates a proxy for accessing @interface_name on the remote object
+at @object_path owned by @name at @connection and synchronously
+loads D-Bus properties unless the
+%G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used.
+
+If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up
+match rules for signals. Connect to the #GDBusProxy::g-signal signal
+to handle signals from the remote object.
+
+If both %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES and
+%G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS are set, this constructor is
+guaranteed to return immediately without blocking.
+
+If @name is a well-known name and the
+%G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION
+flags aren't set and no name owner currently exists, the message bus
+will be requested to launch a name owner for the name.
+
+This is a synchronous failable constructor. See g_dbus_proxy_new()
+and g_dbus_proxy_new_finish() for the asynchronous version.
+
+#GDBusProxy is used in this [example][gdbus-wellknown-proxy].
+
+
+ A #GDBusProxy or %NULL if error is set.
+ Free with g_object_unref().
+
+
+
+
+ A #GDBusConnection.
+
+
+
+ Flags used when constructing the proxy.
+
+
+
+ A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
+
+
+
+ A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
+
+
+
+ An object path.
+
+
+
+ A D-Bus interface name.
+
+
+
+ A #GCancellable or %NULL.
+
+
+
+
+
+ Creates a proxy for accessing @interface_name on the remote object
+at @object_path owned by @name at @connection and asynchronously
+loads D-Bus properties unless the
+%G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. Connect to
+the #GDBusProxy::g-properties-changed signal to get notified about
+property changes.
+
+If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up
+match rules for signals. Connect to the #GDBusProxy::g-signal signal
+to handle signals from the remote object.
+
+If both %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES and
+%G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS are set, this constructor is
+guaranteed to complete immediately without blocking.
+
+If @name is a well-known name and the
+%G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION
+flags aren't set and no name owner currently exists, the message bus
+will be requested to launch a name owner for the name.
+
+This is a failable asynchronous constructor - when the proxy is
+ready, @callback will be invoked and you can use
+g_dbus_proxy_new_finish() to get the result.
+
+See g_dbus_proxy_new_sync() and for a synchronous version of this constructor.
+
+#GDBusProxy is used in this [example][gdbus-wellknown-proxy].
+
+
+
+
+
+
+ A #GDBusConnection.
+
+
+
+ Flags used when constructing the proxy.
+
+
+
+ A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
+
+
+
+ A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
+
+
+
+ An object path.
+
+
+
+ A D-Bus interface name.
+
+
+
+ A #GCancellable or %NULL.
+
+
+
+ Callback function to invoke when the proxy is ready.
+
+
+
+ User data to pass to @callback.
+
+
+
+
+
+ Like g_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection.
+
+#GDBusProxy is used in this [example][gdbus-wellknown-proxy].
+
+
+
+
+
+
+ A #GBusType.
+
+
+
+ Flags used when constructing the proxy.
+
+
+
+ A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
+
+
+
+ A bus name (well-known or unique).
+
+
+
+ An object path.
+
+
+
+ A D-Bus interface name.
+
+
+
+ A #GCancellable or %NULL.
+
+
+
+ Callback function to invoke when the proxy is ready.
+
+
+
+ User data to pass to @callback.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Asynchronously invokes the @method_name method on @proxy.
+
+If @method_name contains any dots, then @name is split into interface and
+method name parts. This allows using @proxy for invoking methods on
+other interfaces.
+
+If the #GDBusConnection associated with @proxy is closed then
+the operation will fail with %G_IO_ERROR_CLOSED. If
+@cancellable is canceled, the operation will fail with
+%G_IO_ERROR_CANCELLED. If @parameters contains a value not
+compatible with the D-Bus protocol, the operation fails with
+%G_IO_ERROR_INVALID_ARGUMENT.
+
+If the @parameters #GVariant is floating, it is consumed. This allows
+convenient 'inline' use of g_variant_new(), e.g.:
+|[<!-- language="C" -->
+ g_dbus_proxy_call (proxy,
+ "TwoStrings",
+ g_variant_new ("(ss)",
+ "Thing One",
+ "Thing Two"),
+ G_DBUS_CALL_FLAGS_NONE,
+ -1,
+ NULL,
+ (GAsyncReadyCallback) two_strings_done,
+ &data);
+]|
+
+If @proxy has an expected interface (see
+#GDBusProxy:g-interface-info) and @method_name is referenced by it,
+then the return value is checked against the return type.
+
+This is an asynchronous method. When the operation is finished,
+@callback will be invoked in the
+[thread-default main context][g-main-context-push-thread-default]
+of the thread you are calling this method from.
+You can then call g_dbus_proxy_call_finish() to get the result of
+the operation. See g_dbus_proxy_call_sync() for the synchronous
+version of this method.
+
+If @callback is %NULL then the D-Bus method call message will be sent with
+the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set.
+
+
+
+
+
+
+ A #GDBusProxy.
+
+
+
+ Name of method to invoke.
+
+
+
+ A #GVariant tuple with parameters for the signal or %NULL if not passing parameters.
+
+
+
+ Flags from the #GDBusCallFlags enumeration.
+
+
+
+ The timeout in milliseconds (with %G_MAXINT meaning
+ "infinite") or -1 to use the proxy default timeout.
+
+
+
+ A #GCancellable or %NULL.
+
+
+
+ A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't
+care about the result of the method invocation.
+
+
+
+ The data to pass to @callback.
+
+
+
+
+
+ Finishes an operation started with g_dbus_proxy_call().
+
+
+ %NULL if @error is set. Otherwise a #GVariant tuple with
+return values. Free with g_variant_unref().
+
+
+
+
+ A #GDBusProxy.
+
+
+
+ A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call().
+
+
+
+
+
+ Synchronously invokes the @method_name method on @proxy.
+
+If @method_name contains any dots, then @name is split into interface and
+method name parts. This allows using @proxy for invoking methods on
+other interfaces.
+
+If the #GDBusConnection associated with @proxy is disconnected then
+the operation will fail with %G_IO_ERROR_CLOSED. If
+@cancellable is canceled, the operation will fail with
+%G_IO_ERROR_CANCELLED. If @parameters contains a value not
+compatible with the D-Bus protocol, the operation fails with
+%G_IO_ERROR_INVALID_ARGUMENT.
+
+If the @parameters #GVariant is floating, it is consumed. This allows
+convenient 'inline' use of g_variant_new(), e.g.:
+|[<!-- language="C" -->
+ g_dbus_proxy_call_sync (proxy,
+ "TwoStrings",
+ g_variant_new ("(ss)",
+ "Thing One",
+ "Thing Two"),
+ G_DBUS_CALL_FLAGS_NONE,
+ -1,
+ NULL,
+ &error);
+]|
+
+The calling thread is blocked until a reply is received. See
+g_dbus_proxy_call() for the asynchronous version of this
+method.
+
+If @proxy has an expected interface (see
+#GDBusProxy:g-interface-info) and @method_name is referenced by it,
+then the return value is checked against the return type.
+
+
+ %NULL if @error is set. Otherwise a #GVariant tuple with
+return values. Free with g_variant_unref().
+
+
+
+
+ A #GDBusProxy.
+
+
+
+ Name of method to invoke.
+
+
+
+ A #GVariant tuple with parameters for the signal
+ or %NULL if not passing parameters.
+
+
+
+ Flags from the #GDBusCallFlags enumeration.
+
+
+
+ The timeout in milliseconds (with %G_MAXINT meaning
+ "infinite") or -1 to use the proxy default timeout.
+
+
+
+ A #GCancellable or %NULL.
+
+
+
+
+
+ Like g_dbus_proxy_call() but also takes a #GUnixFDList object.
+
+This method is only available on UNIX.
+
+
+
+
+
+
+ A #GDBusProxy.
+
+
+
+ Name of method to invoke.
+
+
+
+ A #GVariant tuple with parameters for the signal or %NULL if not passing parameters.
+
+
+
+ Flags from the #GDBusCallFlags enumeration.
+
+
+
+ The timeout in milliseconds (with %G_MAXINT meaning
+ "infinite") or -1 to use the proxy default timeout.
+
+
+
+ A #GUnixFDList or %NULL.
+
+
+
+ A #GCancellable or %NULL.
+
+
+
+ A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't
+care about the result of the method invocation.
+
+
+
+ The data to pass to @callback.
+
+
+
+
+
+ Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list().
+
+
+ %NULL if @error is set. Otherwise a #GVariant tuple with
+return values. Free with g_variant_unref().
+
+
+
+
+ A #GDBusProxy.
+
+
+
+ Return location for a #GUnixFDList or %NULL.
+
+
+
+ A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call_with_unix_fd_list().
+
+
+
+
+
+ Like g_dbus_proxy_call_sync() but also takes and returns #GUnixFDList objects.
+
+This method is only available on UNIX.
+
+
+ %NULL if @error is set. Otherwise a #GVariant tuple with
+return values. Free with g_variant_unref().
+
+
+
+
+ A #GDBusProxy.
+
+
+
+ Name of method to invoke.
+
+
+
+ A #GVariant tuple with parameters for the signal
+ or %NULL if not passing parameters.
+
+
+
+ Flags from the #GDBusCallFlags enumeration.
+
+
+
+ The timeout in milliseconds (with %G_MAXINT meaning
+ "infinite") or -1 to use the proxy default timeout.
+
+
+
+ A #GUnixFDList or %NULL.
+
+
+
+ Return location for a #GUnixFDList or %NULL.
+
+
+
+ A #GCancellable or %NULL.
+
+
+
+
+
+ Looks up the value for a property from the cache. This call does no
+blocking IO.
+
+If @proxy has an expected interface (see
+#GDBusProxy:g-interface-info) and @property_name is referenced by
+it, then @value is checked against the type of the property.
+
+
+ A reference to the #GVariant instance
+ that holds the value for @property_name or %NULL if the value is not in
+ the cache. The returned reference must be freed with g_variant_unref().
+
+
+
+
+ A #GDBusProxy.
+
+
+
+ Property name.
+
+
+
+
+
+ Gets the names of all cached properties on @proxy.
+
+
+ A
+ %NULL-terminated array of strings or %NULL if
+ @proxy has no cached properties. Free the returned array with
+ g_strfreev().
+
+
+
+
+
+
+ A #GDBusProxy.
+
+
+
+
+
+ Gets the connection @proxy is for.
+
+
+ A #GDBusConnection owned by @proxy. Do not free.
+
+
+
+
+ A #GDBusProxy.
+
+
+
+
+
+ Gets the timeout to use if -1 (specifying default timeout) is
+passed as @timeout_msec in the g_dbus_proxy_call() and
+g_dbus_proxy_call_sync() functions.
+
+See the #GDBusProxy:g-default-timeout property for more details.
+
+
+ Timeout to use for @proxy.
+
+
+
+
+ A #GDBusProxy.
+
+
+
+
+
+ Gets the flags that @proxy was constructed with.
+
+
+ Flags from the #GDBusProxyFlags enumeration.
+
+
+
+
+ A #GDBusProxy.
+
+
+
+
+
+ Returns the #GDBusInterfaceInfo, if any, specifying the interface
+that @proxy conforms to. See the #GDBusProxy:g-interface-info
+property for more details.
+
+
+ A #GDBusInterfaceInfo or %NULL.
+ Do not unref the returned object, it is owned by @proxy.
+
+
+
+
+ A #GDBusProxy
+
+
+
+
+
+ Gets the D-Bus interface name @proxy is for.
+
+
+ A string owned by @proxy. Do not free.
+
+
+
+
+ A #GDBusProxy.
+
+
+
+
+
+ Gets the name that @proxy was constructed for.
+
+When connected to a message bus, this will usually be non-%NULL.
+However, it may be %NULL for a proxy that communicates using a peer-to-peer
+pattern.
+
+
+ A string owned by @proxy. Do not free.
+
+
+
+
+ A #GDBusProxy.
+
+
+
+
+
+ The unique name that owns the name that @proxy is for or %NULL if
+no-one currently owns that name. You may connect to the
+#GObject::notify signal to track changes to the
+#GDBusProxy:g-name-owner property.
+
+
+ The name owner or %NULL if no name
+ owner exists. Free with g_free().
+
+
+
+
+ A #GDBusProxy.
+
+
+
+
+
+ Gets the object path @proxy is for.
+
+
+ A string owned by @proxy. Do not free.
+
+
+
+
+ A #GDBusProxy.
+
+
+
+
+
+ If @value is not %NULL, sets the cached value for the property with
+name @property_name to the value in @value.
+
+If @value is %NULL, then the cached value is removed from the
+property cache.
+
+If @proxy has an expected interface (see
+#GDBusProxy:g-interface-info) and @property_name is referenced by
+it, then @value is checked against the type of the property.
+
+If the @value #GVariant is floating, it is consumed. This allows
+convenient 'inline' use of g_variant_new(), e.g.
+|[<!-- language="C" -->
+ g_dbus_proxy_set_cached_property (proxy,
+ "SomeProperty",
+ g_variant_new ("(si)",
+ "A String",
+ 42));
+]|
+
+Normally you will not need to use this method since @proxy
+is tracking changes using the
+`org.freedesktop.DBus.Properties.PropertiesChanged`
+D-Bus signal. However, for performance reasons an object may
+decide to not use this signal for some properties and instead
+use a proprietary out-of-band mechanism to transmit changes.
+
+As a concrete example, consider an object with a property
+`ChatroomParticipants` which is an array of strings. Instead of
+transmitting the same (long) array every time the property changes,
+it is more efficient to only transmit the delta using e.g. signals
+`ChatroomParticipantJoined(String name)` and
+`ChatroomParticipantParted(String name)`.
+
+
+
+
+
+
+ A #GDBusProxy
+
+
+
+ Property name.
+
+
+
+ Value for the property or %NULL to remove it from the cache.
+
+
+
+
+
+ Sets the timeout to use if -1 (specifying default timeout) is
+passed as @timeout_msec in the g_dbus_proxy_call() and
+g_dbus_proxy_call_sync() functions.
+
+See the #GDBusProxy:g-default-timeout property for more details.
+
+
+
+
+
+
+ A #GDBusProxy.
+
+
+
+ Timeout in milliseconds.
+
+
+
+
+
+ Ensure that interactions with @proxy conform to the given
+interface. See the #GDBusProxy:g-interface-info property for more
+details.
+
+
+
+
+
+
+ A #GDBusProxy
+
+
+
+ Minimum interface this proxy conforms to
+ or %NULL to unset.
+
+
+
+
+
+ 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.
+
+
+
+ The #GDBusConnection the proxy is for.
+
+
+
+ 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.
+
+
+
+ Flags from the #GDBusProxyFlags enumeration.
+
+
+
+ Ensure that interactions with this proxy conform to the given
+interface. This is mainly to ensure that malformed data received
+from the other peer is ignored. The given #GDBusInterfaceInfo is
+said to be the "expected interface".
+
+The checks performed are:
+- When completing a method call, if the type signature of
+ the reply message isn't what's expected, the reply is
+ discarded and the #GError is set to %G_IO_ERROR_INVALID_ARGUMENT.
+
+- Received signals that have a type signature mismatch are dropped and
+ a warning is logged via g_warning().
+
+- Properties received via the initial `GetAll()` call or via the
+ `::PropertiesChanged` signal (on the
+ [org.freedesktop.DBus.Properties](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties)
+ interface) or set using g_dbus_proxy_set_cached_property()
+ with a type signature mismatch are ignored and a warning is
+ logged via g_warning().
+
+Note that these checks are never done on methods, signals and
+properties that are not referenced in the given
+#GDBusInterfaceInfo, since extending a D-Bus interface on the
+service-side is not considered an ABI break.
+
+
+
+ The D-Bus interface name the proxy is for.
+
+
+
+ The well-known or unique name that the proxy is for.
+
+
+
+ The unique name that owns #GDBusProxy:g-name or %NULL if no-one
+currently owns that name. You may connect to #GObject::notify signal to
+track changes to this property.
+
+
+
+ The object path the proxy is for.
+
+
+
+
+
+
+
+
+
+ Emitted when one or more D-Bus properties on @proxy changes. The
+local cache has already been updated when this signal fires. Note
+that both @changed_properties and @invalidated_properties are
+guaranteed to never be %NULL (either may be empty though).
+
+If the proxy has the flag
+%G_DBUS_PROXY_FLAGS_GET_INVALIDATED_PROPERTIES set, then
+@invalidated_properties will always be empty.
+
+This signal corresponds to the
+`PropertiesChanged` D-Bus signal on the
+`org.freedesktop.DBus.Properties` interface.
+
+
+
+
+
+ A #GVariant containing the properties that changed (type: `a{sv}`)
+
+
+
+ A %NULL terminated array of properties that was invalidated
+
+
+
+
+
+
+
+ Emitted when a signal from the remote object and interface that @proxy is for, has been received.
+
+Since 2.72 this signal supports detailed connections. You can connect to
+the detailed signal `g-signal::x` in order to receive callbacks only when
+signal `x` is received from the remote object.
+
+
+
+
+
+ The sender of the signal or %NULL if the connection is not a bus connection.
+
+
+
+ The name of the signal.
+
+
+
+ A #GVariant tuple with parameters for the signal.
+
+
+
+
+
+
+ Class structure for #GDBusProxy.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Flags used when constructing an instance of a #GDBusProxy derived class.
+
+ No flags set.
+
+
+ Don't load properties.
+
+
+ Don't connect to signals on the remote object.
+
+
+ If the proxy is for a well-known name,
+do not ask the bus to launch an owner during proxy initialization or a method call.
+This flag is only meaningful in proxies for well-known names.
+
+
+ If set, the property value for any __invalidated property__ will be (asynchronously) retrieved upon receiving the [`PropertiesChanged`](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties) D-Bus signal and the property will not cause emission of the #GDBusProxy::g-properties-changed signal. When the value is received the #GDBusProxy::g-properties-changed signal is emitted for the property along with the retrieved value. Since 2.32.
+
+
+ If the proxy is for a well-known name,
+do not ask the bus to launch an owner during proxy initialization, but allow it to be
+autostarted by a method call. This flag is only meaningful in proxies for well-known names,
+and only if %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is not also specified.
+
+
+ Don't actually send the AddMatch D-Bus
+ call for this signal subscription. This gives you more control
+ over which match rules you add (but you must add them manually). (Since: 2.72)
+
+
+
+
+
+
+ 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
+[thread-default main loop][g-main-context-push-thread-default]
+that @manager was constructed in.
+
+
+ A #GType to use for the remote object. The returned type
+ must be a #GDBusProxy or #GDBusObjectProxy -derived
+ type.
+
+
+
+
+ A #GDBusObjectManagerClient.
+
+
+
+ The object path of the remote object.
+
+
+
+ The interface name of the remote object or %NULL if a #GDBusObjectProxy #GType is requested.
+
+
+
+ data passed in by the user.
+
+
+
+
+
+ Flags used when sending #GDBusMessages on a #GDBusConnection.
+
+ No flags set.
+
+
+ Do not automatically
+assign a serial number from the #GDBusConnection object when
+sending a message.
+
+
+
+ #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().
+
+An example of peer-to-peer communication with GDBus can be found
+in [gdbus-example-peer.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-peer.c).
+
+Note that a minimal #GDBusServer will accept connections from any
+peer. In many use-cases it will be necessary to add a #GDBusAuthObserver
+that only accepts connections that have successfully authenticated
+as the same user that is running the #GDBusServer. Since GLib 2.68 this can
+be achieved more simply by passing the
+%G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flag to the server.
+
+
+ Creates a new D-Bus server that listens on the first address in
+@address that works.
+
+Once constructed, you can use g_dbus_server_get_client_address() to
+get a D-Bus address string that clients can use to connect.
+
+To have control over the available authentication mechanisms and
+the users that are authorized to connect, it is strongly recommended
+to provide a non-%NULL #GDBusAuthObserver.
+
+Connect to the #GDBusServer::new-connection signal to handle
+incoming connections.
+
+The returned #GDBusServer isn't active - you have to start it with
+g_dbus_server_start().
+
+#GDBusServer is used in this [example][gdbus-peer-to-peer].
+
+This is a synchronous failable constructor. There is currently no
+asynchronous version.
+
+
+ A #GDBusServer or %NULL if @error is set. Free with
+g_object_unref().
+
+
+
+
+ A D-Bus address.
+
+
+
+ Flags from the #GDBusServerFlags enumeration.
+
+
+
+ A D-Bus GUID.
+
+
+
+ A #GDBusAuthObserver or %NULL.
+
+
+
+ A #GCancellable or %NULL.
+
+
+
+
+
+ Gets a
+[D-Bus address](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses)
+string that can be used by clients to connect to @server.
+
+This is valid and non-empty if initializing the #GDBusServer succeeded.
+
+
+ A D-Bus address string. Do not free, the string is owned
+by @server.
+
+
+
+
+ A #GDBusServer.
+
+
+
+
+
+ Gets the flags for @server.
+
+
+ A set of flags from the #GDBusServerFlags enumeration.
+
+
+
+
+ A #GDBusServer.
+
+
+
+
+
+ Gets the GUID for @server, as provided to g_dbus_server_new_sync().
+
+
+ A D-Bus GUID. Do not free this string, it is owned by @server.
+
+
+
+
+ A #GDBusServer.
+
+
+
+
+
+ Gets whether @server is active.
+
+
+ %TRUE if server is active, %FALSE otherwise.
+
+
+
+
+ A #GDBusServer.
+
+
+
+
+
+ Starts @server.
+
+
+
+
+
+
+ A #GDBusServer.
+
+
+
+
+
+ Stops @server.
+
+
+
+
+
+
+ A #GDBusServer.
+
+
+
+
+
+ Whether the server is currently active.
+
+
+
+ The D-Bus address to listen on.
+
+
+
+ A #GDBusAuthObserver object to assist in the authentication process or %NULL.
+
+
+
+ The D-Bus address that clients can use.
+
+
+
+ Flags from the #GDBusServerFlags enumeration.
+
+
+
+ The GUID of the server.
+
+See #GDBusConnection:guid for more details.
+
+
+
+ Emitted when a new authenticated connection has been made. Use
+g_dbus_connection_get_peer_credentials() to figure out what
+identity (if any), was authenticated.
+
+If you want to accept the connection, take a reference to the
+@connection object and return %TRUE. When you are done with the
+connection call g_dbus_connection_close() and give up your
+reference. Note that the other peer may disconnect at any time -
+a typical thing to do when accepting a connection is to listen to
+the #GDBusConnection::closed signal.
+
+If #GDBusServer:flags contains %G_DBUS_SERVER_FLAGS_RUN_IN_THREAD
+then the signal is emitted in a new thread dedicated to the
+connection. Otherwise the signal is emitted in the
+[thread-default main context][g-main-context-push-thread-default]
+of the thread that @server was constructed in.
+
+You are guaranteed that signal handlers for this signal runs
+before incoming messages on @connection are processed. This means
+that it's suitable to call g_dbus_connection_register_object() or
+similar from the signal handler.
+
+ %TRUE to claim @connection, %FALSE to let other handlers
+run.
+
+
+
+
+ A #GDBusConnection for the new connection.
+
+
+
+
+
+
+ Flags used when creating a #GDBusServer.
+
+ No flags set.
+
+
+ All #GDBusServer::new-connection
+signals will run in separated dedicated threads (see signal for
+details).
+
+
+ Allow the anonymous
+authentication method.
+
+
+ Require the UID of the
+peer to be the same as the UID of the server when authenticating. (Since: 2.68)
+
+
+
+ Signature for callback function used in g_dbus_connection_signal_subscribe().
+
+
+
+
+
+
+ A #GDBusConnection.
+
+
+
+ The unique bus name of the sender of the signal,
+ or %NULL on a peer-to-peer D-Bus connection.
+
+
+
+ The object path that the signal was emitted on.
+
+
+
+ The name of the interface.
+
+
+
+ The name of the signal.
+
+
+
+ A #GVariant tuple with parameters for the signal.
+
+
+
+ User data passed when subscribing to the signal.
+
+
+
+
+
+ Flags used when subscribing to signals via g_dbus_connection_signal_subscribe().
+
+ No flags set.
+
+
+ Don't actually send the AddMatch
+D-Bus call for this signal subscription. This gives you more control
+over which match rules you add (but you must add them manually).
+
+
+ Match first arguments that
+contain a bus or interface name with the given namespace.
+
+
+ Match first arguments that
+contain an object path that is either equivalent to the given path,
+or one of the paths is a subpath of the other.
+
+
+
+ Information about a signal on a D-Bus interface.
+
+
+ The reference count or -1 if statically allocated.
+
+
+
+ The name of the D-Bus signal, e.g. "NameOwnerChanged".
+
+
+
+ A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no arguments.
+
+
+
+
+
+ A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
+
+
+
+
+
+ If @info is statically allocated does nothing. Otherwise increases
+the reference count.
+
+
+ The same @info.
+
+
+
+
+ A #GDBusSignalInfo
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+ A #GDBusSignalInfo.
+
+
+
+
+
+
+ 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).
+
+
+ A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods.
+
+
+
+
+ A #GDBusConnection.
+
+
+
+ The unique bus name of the remote caller.
+
+
+
+ The object path that was registered with g_dbus_connection_register_subtree().
+
+
+
+ The D-Bus interface name that the method call or property access is for.
+
+
+
+ A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
+
+
+
+ Return location for user data to pass to functions in the returned #GDBusInterfaceVTable.
+
+
+
+ The @user_data #gpointer passed to g_dbus_connection_register_subtree().
+
+
+
+
+
+ The type of the @enumerate function in #GDBusSubtreeVTable.
+
+This function is called when generating introspection data and also
+when preparing to dispatch incoming messages in the event that the
+%G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is not
+specified (ie: to verify that the object path is valid).
+
+Hierarchies are not supported; the items that you return should not
+contain the `/` character.
+
+The return value will be freed with g_strfreev().
+
+
+ A newly allocated array of strings for node names that are children of @object_path.
+
+
+
+
+
+
+ A #GDBusConnection.
+
+
+
+ The unique bus name of the remote caller.
+
+
+
+ The object path that was registered with g_dbus_connection_register_subtree().
+
+
+
+ The @user_data #gpointer passed to g_dbus_connection_register_subtree().
+
+
+
+
+
+ Flags passed to g_dbus_connection_register_subtree().
+
+ No flags set.
+
+
+ Method calls to objects not in the enumerated range
+ will still be dispatched. This is useful if you want
+ to dynamically spawn objects in the subtree.
+
+
+
+ The type of the @introspect function in #GDBusSubtreeVTable.
+
+Subtrees are flat. @node, if non-%NULL, is always exactly one
+segment of the object path (ie: it never contains a slash).
+
+This function should return %NULL to indicate that there is no object
+at this node.
+
+If this function returns non-%NULL, the return value is expected to
+be a %NULL-terminated array of pointers to #GDBusInterfaceInfo
+structures describing the interfaces implemented by @node. This
+array will have g_dbus_interface_info_unref() called on each item
+before being freed with g_free().
+
+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.
+
+
+ A %NULL-terminated array of pointers to #GDBusInterfaceInfo, or %NULL.
+
+
+
+
+
+
+ A #GDBusConnection.
+
+
+
+ The unique bus name of the remote caller.
+
+
+
+ The object path that was registered with g_dbus_connection_register_subtree().
+
+
+
+ A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
+
+
+
+ The @user_data #gpointer passed to g_dbus_connection_register_subtree().
+
+
+
+
+
+ Virtual table for handling subtrees registered with g_dbus_connection_register_subtree().
+
+
+ Function for enumerating child nodes.
+
+
+
+ Function for introspecting a child node.
+
+
+
+ Function for dispatching a remote call on a child node.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Extension point for debug control functionality.
+See [Extending GIO][extending-gio].
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Extension point for default handler to URI association. See
+[Extending GIO][extending-gio].
+ The #GDesktopAppInfoLookup interface is deprecated and
+ unused by GIO.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The string used to obtain a Unix device path with g_drive_get_identifier().
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Data input stream implements #GInputStream and includes functions for
+reading structured data directly from a binary input stream.
+
+
+
+ Creates a new data input stream for the @base_stream.
+
+
+ a new #GDataInputStream.
+
+
+
+
+ a #GInputStream.
+
+
+
+
+
+ Gets the byte order for the data input stream.
+
+
+ the @stream's current #GDataStreamByteOrder.
+
+
+
+
+ a given #GDataInputStream.
+
+
+
+
+
+ Gets the current newline type for the @stream.
+
+
+ #GDataStreamNewlineType for the given @stream.
+
+
+
+
+ a given #GDataInputStream.
+
+
+
+
+
+ Reads an unsigned 8-bit/1-byte value from @stream.
+
+
+ an unsigned 8-bit/1-byte value read from the @stream or `0`
+if an error occurred.
+
+
+
+
+ a given #GDataInputStream.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Reads a 16-bit/2-byte value from @stream.
+
+In order to get the correct byte order for this read operation,
+see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
+
+
+ a signed 16-bit/2-byte value read from @stream or `0` if
+an error occurred.
+
+
+
+
+ a given #GDataInputStream.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Reads a signed 32-bit/4-byte value from @stream.
+
+In order to get the correct byte order for this read operation,
+see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ a signed 32-bit/4-byte value read from the @stream or `0` if
+an error occurred.
+
+
+
+
+ a given #GDataInputStream.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Reads a 64-bit/8-byte value from @stream.
+
+In order to get the correct byte order for this read operation,
+see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ a signed 64-bit/8-byte value read from @stream or `0` if
+an error occurred.
+
+
+
+
+ a given #GDataInputStream.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Reads a line from the data input stream. Note that no encoding
+checks or conversion is performed; the input is not guaranteed to
+be UTF-8, and may in fact have embedded NUL characters.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+
+ a NUL terminated byte array with the line that was read in
+ (without the newlines). Set @length to a #gsize to get the length
+ of the read line. On an error, it will return %NULL and @error
+ will be set. If there's no content to read, it will still return
+ %NULL, but @error won't be set.
+
+
+
+
+
+
+ a given #GDataInputStream.
+
+
+
+ a #gsize to get the length of the data read in.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+ a given #GDataInputStream.
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ callback to call when the request is satisfied.
+
+
+
+ the data to pass to callback function.
+
+
+
+
+
+ Finish an asynchronous call started by
+g_data_input_stream_read_line_async(). Note the warning about
+string encoding in g_data_input_stream_read_line() applies here as
+well.
+
+
+
+ a NUL-terminated byte array with the line that was read in
+ (without the newlines). Set @length to a #gsize to get the length
+ of the read line. On an error, it will return %NULL and @error
+ will be set. If there's no content to read, it will still return
+ %NULL, but @error won't be set.
+
+
+
+
+
+
+ a given #GDataInputStream.
+
+
+
+ the #GAsyncResult that was provided to the callback.
+
+
+
+ a #gsize to get the length of the data read in.
+
+
+
+
+
+ Finish an asynchronous call started by
+g_data_input_stream_read_line_async().
+
+
+ a string with the line that
+ was read in (without the newlines). Set @length to a #gsize to
+ get the length of the read line. On an error, it will return
+ %NULL and @error will be set. For UTF-8 conversion errors, the set
+ error domain is %G_CONVERT_ERROR. If there's no content to read,
+ it will still return %NULL, but @error won't be set.
+
+
+
+
+ a given #GDataInputStream.
+
+
+
+ the #GAsyncResult that was provided to the callback.
+
+
+
+ a #gsize to get the length of the data read in.
+
+
+
+
+
+ Reads a UTF-8 encoded line from the data input stream.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ a NUL terminated UTF-8 string
+ with the line that was read in (without the newlines). Set
+ @length to a #gsize to get the length of the read line. On an
+ error, it will return %NULL and @error will be set. For UTF-8
+ conversion errors, the set error domain is %G_CONVERT_ERROR. If
+ there's no content to read, it will still return %NULL, but @error
+ won't be set.
+
+
+
+
+ a given #GDataInputStream.
+
+
+
+ a #gsize to get the length of the data read in.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ 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 unsigned 16-bit/2-byte value read from the @stream or `0` if
+an error occurred.
+
+
+
+
+ a given #GDataInputStream.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ 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 unsigned 32-bit/4-byte value read from the @stream or `0` if
+an error occurred.
+
+
+
+
+ a given #GDataInputStream.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ 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 unsigned 64-bit/8-byte read from @stream or `0` if
+an error occurred.
+
+
+
+
+ a given #GDataInputStream.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ 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.
+ Use g_data_input_stream_read_upto() instead, which has more
+ consistent behaviour regarding the stop character.
+
+
+ a string with the data that was read
+ before encountering any of the stop characters. Set @length to
+ a #gsize to get the length of the string. This function will
+ return %NULL on an error.
+
+
+
+
+ a given #GDataInputStream.
+
+
+
+ characters to terminate the read.
+
+
+
+ a #gsize to get the length of the data read in.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ 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.
+ Use g_data_input_stream_read_upto_async() instead, which
+ has more consistent behaviour regarding the stop character.
+
+
+
+
+
+
+ a given #GDataInputStream.
+
+
+
+ characters to terminate the read.
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ callback to call when the request is satisfied.
+
+
+
+ the data to pass to callback function.
+
+
+
+
+
+ Finish an asynchronous call started by
+g_data_input_stream_read_until_async().
+ Use g_data_input_stream_read_upto_finish() instead, which
+ has more consistent behaviour regarding the stop character.
+
+
+ a string with the data that was read
+ before encountering any of the stop characters. Set @length to
+ a #gsize to get the length of the string. This function will
+ return %NULL on an error.
+
+
+
+
+ a given #GDataInputStream.
+
+
+
+ the #GAsyncResult that was provided to the callback.
+
+
+
+ a #gsize to get the length of the data read in.
+
+
+
+
+
+ Reads a string from the data input stream, up to the first
+occurrence of any of the stop characters.
+
+In contrast to g_data_input_stream_read_until(), this function
+does not consume the stop character. You have to use
+g_data_input_stream_read_byte() to get it before calling
+g_data_input_stream_read_upto() again.
+
+Note that @stop_chars may contain '\0' if @stop_chars_len is
+specified.
+
+The returned string will always be nul-terminated on success.
+
+
+ a string with the data that was read
+ before encountering any of the stop characters. Set @length to
+ a #gsize to get the length of the string. This function will
+ return %NULL on an error
+
+
+
+
+ a #GDataInputStream
+
+
+
+ characters to terminate the read
+
+
+
+ length of @stop_chars. May be -1 if @stop_chars is
+ nul-terminated
+
+
+
+ a #gsize to get the length of the data read in
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+
+
+ The asynchronous version of g_data_input_stream_read_upto().
+It is an error to have two outstanding calls to this function.
+
+In contrast to g_data_input_stream_read_until(), this function
+does not consume the stop character. You have to use
+g_data_input_stream_read_byte() to get it before calling
+g_data_input_stream_read_upto() again.
+
+Note that @stop_chars may contain '\0' if @stop_chars_len is
+specified.
+
+When the operation is finished, @callback will be called. You
+can then call g_data_input_stream_read_upto_finish() to get
+the result of the operation.
+
+
+
+
+
+
+ a #GDataInputStream
+
+
+
+ characters to terminate the read
+
+
+
+ length of @stop_chars. May be -1 if @stop_chars is
+ nul-terminated
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finish an asynchronous call started by
+g_data_input_stream_read_upto_async().
+
+Note that this function does not consume the stop character. You
+have to use g_data_input_stream_read_byte() to get it before calling
+g_data_input_stream_read_upto_async() again.
+
+The returned string will always be nul-terminated on success.
+
+
+ a string with the data that was read
+ before encountering any of the stop characters. Set @length to
+ a #gsize to get the length of the string. This function will
+ return %NULL on an error.
+
+
+
+
+ a #GDataInputStream
+
+
+
+ the #GAsyncResult that was provided to the callback
+
+
+
+ a #gsize to get the length of the data read in
+
+
+
+
+
+ This function sets the byte order for the given @stream. All subsequent
+reads from the @stream will be read in the given @order.
+
+
+
+
+
+
+ a given #GDataInputStream.
+
+
+
+ a #GDataStreamByteOrder to set.
+
+
+
+
+
+ Sets the newline type for the @stream.
+
+Note that using G_DATA_STREAM_NEWLINE_TYPE_ANY is slightly unsafe. If a read
+chunk ends in "CR" we must read an additional byte to know if this is "CR" or
+"CR LF", and this might block if there is no more data available.
+
+
+
+
+
+
+ a #GDataInputStream.
+
+
+
+ the type of new line return as #GDataStreamNewlineType.
+
+
+
+
+
+ The :byte-order property determines the byte ordering that
+is used when reading multi-byte entities (such as integers)
+from the stream.
+
+
+
+ The :newline-type property determines what is considered
+as a line ending when reading complete lines from the stream.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Data output stream implements #GOutputStream and includes functions for
+writing data directly to an output stream.
+
+
+
+ Creates a new data output stream for @base_stream.
+
+
+ #GDataOutputStream.
+
+
+
+
+ a #GOutputStream.
+
+
+
+
+
+ Gets the byte order for the stream.
+
+
+ the #GDataStreamByteOrder for the @stream.
+
+
+
+
+ a #GDataOutputStream.
+
+
+
+
+
+ Puts a byte into the output stream.
+
+
+ %TRUE if @data was successfully added to the @stream.
+
+
+
+
+ a #GDataOutputStream.
+
+
+
+ a #guchar.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Puts a signed 16-bit integer into the output stream.
+
+
+ %TRUE if @data was successfully added to the @stream.
+
+
+
+
+ a #GDataOutputStream.
+
+
+
+ a #gint16.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Puts a signed 32-bit integer into the output stream.
+
+
+ %TRUE if @data was successfully added to the @stream.
+
+
+
+
+ a #GDataOutputStream.
+
+
+
+ a #gint32.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Puts a signed 64-bit integer into the stream.
+
+
+ %TRUE if @data was successfully added to the @stream.
+
+
+
+
+ a #GDataOutputStream.
+
+
+
+ a #gint64.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Puts a string into the output stream.
+
+
+ %TRUE if @string was successfully added to the @stream.
+
+
+
+
+ a #GDataOutputStream.
+
+
+
+ a string.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Puts an unsigned 16-bit integer into the output stream.
+
+
+ %TRUE if @data was successfully added to the @stream.
+
+
+
+
+ a #GDataOutputStream.
+
+
+
+ a #guint16.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Puts an unsigned 32-bit integer into the stream.
+
+
+ %TRUE if @data was successfully added to the @stream.
+
+
+
+
+ a #GDataOutputStream.
+
+
+
+ a #guint32.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Puts an unsigned 64-bit integer into the stream.
+
+
+ %TRUE if @data was successfully added to the @stream.
+
+
+
+
+ a #GDataOutputStream.
+
+
+
+ a #guint64.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Sets the byte order of the data output stream to @order.
+
+
+
+
+
+
+ a #GDataOutputStream.
+
+
+
+ a %GDataStreamByteOrder.
+
+
+
+
+
+ Determines the byte ordering that is used when writing
+multi-byte entities (such as integers) to the stream.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #GDataStreamByteOrder is used to ensure proper endianness of streaming data sources
+across various machine architectures.
+
+ Selects Big Endian byte order.
+
+
+ Selects Little Endian byte order.
+
+
+ Selects endianness based on host machine's architecture.
+
+
+
+ #GDataStreamNewlineType is used when checking for or setting the line endings for a given file.
+
+ Selects "LF" line endings, common on most modern UNIX platforms.
+
+
+ Selects "CR" line endings.
+
+
+ Selects "CR, LF" line ending, common on Microsoft Windows.
+
+
+ Automatically try to handle any line ending type.
+
+
+
+ A #GDatagramBased is a networking interface for representing datagram-based
+communications. It is a more or less direct mapping of the core parts of the
+BSD socket API in a portable GObject interface. It is implemented by
+#GSocket, which wraps the UNIX socket API on UNIX and winsock2 on Windows.
+
+#GDatagramBased is entirely platform independent, and is intended to be used
+alongside higher-level networking APIs such as #GIOStream.
+
+It uses vectored scatter/gather I/O by default, allowing for many messages
+to be sent or received in a single call. Where possible, implementations of
+the interface should take advantage of vectored I/O to minimise processing
+or system calls. For example, #GSocket uses recvmmsg() and sendmmsg() where
+possible. Callers should take advantage of scatter/gather I/O (the use of
+multiple buffers per message) to avoid unnecessary copying of data to
+assemble or disassemble a message.
+
+Each #GDatagramBased operation has a timeout parameter which may be negative
+for blocking behaviour, zero for non-blocking behaviour, or positive for
+timeout behaviour. A blocking operation blocks until finished or there is an
+error. A non-blocking operation will return immediately with a
+%G_IO_ERROR_WOULD_BLOCK error if it cannot make progress. A timeout operation
+will block until the operation is complete or the timeout expires; if the
+timeout expires it will return what progress it made, or
+%G_IO_ERROR_TIMED_OUT if no progress was made. To know when a call would
+successfully run you can call g_datagram_based_condition_check() or
+g_datagram_based_condition_wait(). You can also use
+g_datagram_based_create_source() and attach it to a #GMainContext to get
+callbacks when I/O is possible.
+
+When running a non-blocking operation 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.
+
+As with #GSocket, #GDatagramBaseds can be either connection oriented (for
+example, SCTP) or connectionless (for example, UDP). #GDatagramBaseds must be
+datagram-based, not stream-based. The interface does not cover connection
+establishment — use methods on the underlying type to establish a connection
+before sending and receiving data through the #GDatagramBased API. For
+connectionless socket types the target/source address is specified or
+received in each I/O operation.
+
+Like most other APIs in GLib, #GDatagramBased is not inherently thread safe.
+To use a #GDatagramBased concurrently from multiple threads, you must
+implement your own locking.
+
+
+ Checks on the readiness of @datagram_based to perform operations. The
+operations specified in @condition are checked for and masked against the
+currently-satisfied conditions on @datagram_based. The result is returned.
+
+%G_IO_IN will be set in the return value if data is available to read with
+g_datagram_based_receive_messages(), or if the connection is closed remotely
+(EOS); and if the datagram_based has not been closed locally using some
+implementation-specific method (such as g_socket_close() or
+g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket).
+
+If the connection is shut down or closed (by calling g_socket_close() or
+g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for
+example), all calls to this function will return %G_IO_ERROR_CLOSED.
+
+%G_IO_OUT will be set if it is expected that at least one byte can be sent
+using g_datagram_based_send_messages() without blocking. It will not be set
+if the datagram_based has been closed locally.
+
+%G_IO_HUP will be set if the connection has been closed locally.
+
+%G_IO_ERR will be set if there was an asynchronous error in transmitting data
+previously enqueued using g_datagram_based_send_messages().
+
+Note that on Windows, it is possible for an operation to return
+%G_IO_ERROR_WOULD_BLOCK even immediately after
+g_datagram_based_condition_check() has claimed that the #GDatagramBased is
+ready for writing. Rather than calling g_datagram_based_condition_check() and
+then writing to the #GDatagramBased if it succeeds, it is generally better to
+simply try writing right away, and try again later if the initial attempt
+returns %G_IO_ERROR_WOULD_BLOCK.
+
+It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these
+conditions will always be set in the output if they are true. Apart from
+these flags, the output is guaranteed to be masked by @condition.
+
+This call never blocks.
+
+
+ the #GIOCondition mask of the current state
+
+
+
+
+ a #GDatagramBased
+
+
+
+ a #GIOCondition mask to check
+
+
+
+
+
+ Waits for up to @timeout microseconds for condition to become true on
+@datagram_based. If the condition is met, %TRUE is returned.
+
+If @cancellable is cancelled before the condition is met, or if @timeout is
+reached before the condition is met, then %FALSE is returned and @error is
+set appropriately (%G_IO_ERROR_CANCELLED or %G_IO_ERROR_TIMED_OUT).
+
+
+ %TRUE if the condition was met, %FALSE otherwise
+
+
+
+
+ a #GDatagramBased
+
+
+
+ a #GIOCondition mask to wait for
+
+
+
+ the maximum time (in microseconds) to wait, 0 to not block, or -1
+ to block indefinitely
+
+
+
+ a #GCancellable
+
+
+
+
+
+ Creates a #GSource that can be attached to a #GMainContext to monitor for
+the availability of the specified @condition on the #GDatagramBased. The
+#GSource keeps a reference to the @datagram_based.
+
+The callback on the source is of the #GDatagramBasedSourceFunc type.
+
+It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these
+conditions will always be reported in the callback if they are true.
+
+If non-%NULL, @cancellable can be used to cancel the source, which will
+cause the source to trigger, reporting the current condition (which is
+likely 0 unless cancellation happened at the same time as a condition
+change). You can check for this in the callback using
+g_cancellable_is_cancelled().
+
+
+ a newly allocated #GSource
+
+
+
+
+ a #GDatagramBased
+
+
+
+ a #GIOCondition mask to monitor
+
+
+
+ a #GCancellable
+
+
+
+
+
+ Receive one or more data messages from @datagram_based in one go.
+
+@messages must point to an array of #GInputMessage structs and
+@num_messages must be the length of this array. Each #GInputMessage
+contains a pointer to an array of #GInputVector structs describing the
+buffers that the data received in each message will be written to.
+
+@flags modify how all messages are received. The commonly available
+arguments for this are available in the #GSocketMsgFlags enum, but the
+values there are the same as the system values, and the flags
+are passed in as-is, so you can pass in system-specific flags too. These
+flags affect the overall receive operation. Flags affecting individual
+messages are returned in #GInputMessage.flags.
+
+The other members of #GInputMessage are treated as described in its
+documentation.
+
+If @timeout is negative the call will block until @num_messages have been
+received, the connection is closed remotely (EOS), @cancellable is cancelled,
+or an error occurs.
+
+If @timeout is 0 the call will return up to @num_messages without blocking,
+or %G_IO_ERROR_WOULD_BLOCK if no messages are queued in the operating system
+to be received.
+
+If @timeout is positive the call will block on the same conditions as if
+@timeout were negative. If the timeout is reached
+before any messages are received, %G_IO_ERROR_TIMED_OUT is returned,
+otherwise it will return the number of messages received before timing out.
+(Note: This is effectively the behaviour of `MSG_WAITFORONE` with
+recvmmsg().)
+
+To be notified when messages are available, wait for the %G_IO_IN condition.
+Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from
+g_datagram_based_receive_messages() even if you were previously notified of a
+%G_IO_IN condition.
+
+If the remote peer closes the connection, any messages queued in the
+underlying receive buffer will be returned, and subsequent calls to
+g_datagram_based_receive_messages() will return 0 (with no error set).
+
+If the connection is shut down or closed (by calling g_socket_close() or
+g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for
+example), all calls to this function will return %G_IO_ERROR_CLOSED.
+
+On error -1 is returned and @error is set accordingly. An error will only
+be returned if zero messages could be received; otherwise the number of
+messages successfully received before the error will be returned. If
+@cancellable is cancelled, %G_IO_ERROR_CANCELLED is returned as with any
+other error.
+
+
+ number of messages received, or -1 on error. Note that the number
+ of messages received may be smaller than @num_messages if @timeout is
+ zero or positive, if the peer closed the connection, or if @num_messages
+ was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try
+ to receive the remaining messages.
+
+
+
+
+ a #GDatagramBased
+
+
+
+ an array of #GInputMessage structs
+
+
+
+
+
+ the number of elements in @messages
+
+
+
+ an int containing #GSocketMsgFlags flags for the overall operation
+
+
+
+ the maximum time (in microseconds) to wait, 0 to not block, or -1
+ to block indefinitely
+
+
+
+ a %GCancellable
+
+
+
+
+
+ Send one or more data messages from @datagram_based in one go.
+
+@messages must point to an array of #GOutputMessage structs and
+@num_messages must be the length of this array. Each #GOutputMessage
+contains an address to send the data to, and a pointer to an array of
+#GOutputVector structs to describe the buffers that the data to be sent
+for each message will be gathered from.
+
+@flags modify how the message is sent. The commonly available arguments
+for this are available in the #GSocketMsgFlags enum, but the
+values there are the same as the system values, and the flags
+are passed in as-is, so you can pass in system-specific flags too.
+
+The other members of #GOutputMessage are treated as described in its
+documentation.
+
+If @timeout is negative the call will block until @num_messages have been
+sent, @cancellable is cancelled, or an error occurs.
+
+If @timeout is 0 the call will send up to @num_messages without blocking,
+or will return %G_IO_ERROR_WOULD_BLOCK if there is no space to send messages.
+
+If @timeout is positive the call will block on the same conditions as if
+@timeout were negative. If the timeout is reached before any messages are
+sent, %G_IO_ERROR_TIMED_OUT is returned, otherwise it will return the number
+of messages sent before timing out.
+
+To be notified when messages can be sent, wait for the %G_IO_OUT condition.
+Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from
+g_datagram_based_send_messages() even if you were previously notified of a
+%G_IO_OUT condition. (On Windows in particular, this is very common due to
+the way the underlying APIs work.)
+
+If the connection is shut down or closed (by calling g_socket_close() or
+g_socket_shutdown() with @shutdown_write set, if it’s a #GSocket, for
+example), all calls to this function will return %G_IO_ERROR_CLOSED.
+
+On error -1 is returned and @error is set accordingly. An error will only
+be returned if zero messages could be sent; otherwise the number of messages
+successfully sent before the error will be returned. If @cancellable is
+cancelled, %G_IO_ERROR_CANCELLED is returned as with any other error.
+
+
+ number of messages sent, or -1 on error. Note that the number of
+ messages sent may be smaller than @num_messages if @timeout is zero
+ or positive, or if @num_messages was larger than `UIO_MAXIOV` (1024), in
+ which case the caller may re-try to send the remaining messages.
+
+
+
+
+ a #GDatagramBased
+
+
+
+ an array of #GOutputMessage structs
+
+
+
+
+
+ the number of elements in @messages
+
+
+
+ an int containing #GSocketMsgFlags flags
+
+
+
+ the maximum time (in microseconds) to wait, 0 to not block, or -1
+ to block indefinitely
+
+
+
+ a %GCancellable
+
+
+
+
+
+ Checks on the readiness of @datagram_based to perform operations. The
+operations specified in @condition are checked for and masked against the
+currently-satisfied conditions on @datagram_based. The result is returned.
+
+%G_IO_IN will be set in the return value if data is available to read with
+g_datagram_based_receive_messages(), or if the connection is closed remotely
+(EOS); and if the datagram_based has not been closed locally using some
+implementation-specific method (such as g_socket_close() or
+g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket).
+
+If the connection is shut down or closed (by calling g_socket_close() or
+g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for
+example), all calls to this function will return %G_IO_ERROR_CLOSED.
+
+%G_IO_OUT will be set if it is expected that at least one byte can be sent
+using g_datagram_based_send_messages() without blocking. It will not be set
+if the datagram_based has been closed locally.
+
+%G_IO_HUP will be set if the connection has been closed locally.
+
+%G_IO_ERR will be set if there was an asynchronous error in transmitting data
+previously enqueued using g_datagram_based_send_messages().
+
+Note that on Windows, it is possible for an operation to return
+%G_IO_ERROR_WOULD_BLOCK even immediately after
+g_datagram_based_condition_check() has claimed that the #GDatagramBased is
+ready for writing. Rather than calling g_datagram_based_condition_check() and
+then writing to the #GDatagramBased if it succeeds, it is generally better to
+simply try writing right away, and try again later if the initial attempt
+returns %G_IO_ERROR_WOULD_BLOCK.
+
+It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these
+conditions will always be set in the output if they are true. Apart from
+these flags, the output is guaranteed to be masked by @condition.
+
+This call never blocks.
+
+
+ the #GIOCondition mask of the current state
+
+
+
+
+ a #GDatagramBased
+
+
+
+ a #GIOCondition mask to check
+
+
+
+
+
+ Waits for up to @timeout microseconds for condition to become true on
+@datagram_based. If the condition is met, %TRUE is returned.
+
+If @cancellable is cancelled before the condition is met, or if @timeout is
+reached before the condition is met, then %FALSE is returned and @error is
+set appropriately (%G_IO_ERROR_CANCELLED or %G_IO_ERROR_TIMED_OUT).
+
+
+ %TRUE if the condition was met, %FALSE otherwise
+
+
+
+
+ a #GDatagramBased
+
+
+
+ a #GIOCondition mask to wait for
+
+
+
+ the maximum time (in microseconds) to wait, 0 to not block, or -1
+ to block indefinitely
+
+
+
+ a #GCancellable
+
+
+
+
+
+ Creates a #GSource that can be attached to a #GMainContext to monitor for
+the availability of the specified @condition on the #GDatagramBased. The
+#GSource keeps a reference to the @datagram_based.
+
+The callback on the source is of the #GDatagramBasedSourceFunc type.
+
+It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these
+conditions will always be reported in the callback if they are true.
+
+If non-%NULL, @cancellable can be used to cancel the source, which will
+cause the source to trigger, reporting the current condition (which is
+likely 0 unless cancellation happened at the same time as a condition
+change). You can check for this in the callback using
+g_cancellable_is_cancelled().
+
+
+ a newly allocated #GSource
+
+
+
+
+ a #GDatagramBased
+
+
+
+ a #GIOCondition mask to monitor
+
+
+
+ a #GCancellable
+
+
+
+
+
+ Receive one or more data messages from @datagram_based in one go.
+
+@messages must point to an array of #GInputMessage structs and
+@num_messages must be the length of this array. Each #GInputMessage
+contains a pointer to an array of #GInputVector structs describing the
+buffers that the data received in each message will be written to.
+
+@flags modify how all messages are received. The commonly available
+arguments for this are available in the #GSocketMsgFlags enum, but the
+values there are the same as the system values, and the flags
+are passed in as-is, so you can pass in system-specific flags too. These
+flags affect the overall receive operation. Flags affecting individual
+messages are returned in #GInputMessage.flags.
+
+The other members of #GInputMessage are treated as described in its
+documentation.
+
+If @timeout is negative the call will block until @num_messages have been
+received, the connection is closed remotely (EOS), @cancellable is cancelled,
+or an error occurs.
+
+If @timeout is 0 the call will return up to @num_messages without blocking,
+or %G_IO_ERROR_WOULD_BLOCK if no messages are queued in the operating system
+to be received.
+
+If @timeout is positive the call will block on the same conditions as if
+@timeout were negative. If the timeout is reached
+before any messages are received, %G_IO_ERROR_TIMED_OUT is returned,
+otherwise it will return the number of messages received before timing out.
+(Note: This is effectively the behaviour of `MSG_WAITFORONE` with
+recvmmsg().)
+
+To be notified when messages are available, wait for the %G_IO_IN condition.
+Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from
+g_datagram_based_receive_messages() even if you were previously notified of a
+%G_IO_IN condition.
+
+If the remote peer closes the connection, any messages queued in the
+underlying receive buffer will be returned, and subsequent calls to
+g_datagram_based_receive_messages() will return 0 (with no error set).
+
+If the connection is shut down or closed (by calling g_socket_close() or
+g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for
+example), all calls to this function will return %G_IO_ERROR_CLOSED.
+
+On error -1 is returned and @error is set accordingly. An error will only
+be returned if zero messages could be received; otherwise the number of
+messages successfully received before the error will be returned. If
+@cancellable is cancelled, %G_IO_ERROR_CANCELLED is returned as with any
+other error.
+
+
+ number of messages received, or -1 on error. Note that the number
+ of messages received may be smaller than @num_messages if @timeout is
+ zero or positive, if the peer closed the connection, or if @num_messages
+ was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try
+ to receive the remaining messages.
+
+
+
+
+ a #GDatagramBased
+
+
+
+ an array of #GInputMessage structs
+
+
+
+
+
+ the number of elements in @messages
+
+
+
+ an int containing #GSocketMsgFlags flags for the overall operation
+
+
+
+ the maximum time (in microseconds) to wait, 0 to not block, or -1
+ to block indefinitely
+
+
+
+ a %GCancellable
+
+
+
+
+
+ Send one or more data messages from @datagram_based in one go.
+
+@messages must point to an array of #GOutputMessage structs and
+@num_messages must be the length of this array. Each #GOutputMessage
+contains an address to send the data to, and a pointer to an array of
+#GOutputVector structs to describe the buffers that the data to be sent
+for each message will be gathered from.
+
+@flags modify how the message is sent. The commonly available arguments
+for this are available in the #GSocketMsgFlags enum, but the
+values there are the same as the system values, and the flags
+are passed in as-is, so you can pass in system-specific flags too.
+
+The other members of #GOutputMessage are treated as described in its
+documentation.
+
+If @timeout is negative the call will block until @num_messages have been
+sent, @cancellable is cancelled, or an error occurs.
+
+If @timeout is 0 the call will send up to @num_messages without blocking,
+or will return %G_IO_ERROR_WOULD_BLOCK if there is no space to send messages.
+
+If @timeout is positive the call will block on the same conditions as if
+@timeout were negative. If the timeout is reached before any messages are
+sent, %G_IO_ERROR_TIMED_OUT is returned, otherwise it will return the number
+of messages sent before timing out.
+
+To be notified when messages can be sent, wait for the %G_IO_OUT condition.
+Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from
+g_datagram_based_send_messages() even if you were previously notified of a
+%G_IO_OUT condition. (On Windows in particular, this is very common due to
+the way the underlying APIs work.)
+
+If the connection is shut down or closed (by calling g_socket_close() or
+g_socket_shutdown() with @shutdown_write set, if it’s a #GSocket, for
+example), all calls to this function will return %G_IO_ERROR_CLOSED.
+
+On error -1 is returned and @error is set accordingly. An error will only
+be returned if zero messages could be sent; otherwise the number of messages
+successfully sent before the error will be returned. If @cancellable is
+cancelled, %G_IO_ERROR_CANCELLED is returned as with any other error.
+
+
+ number of messages sent, or -1 on error. Note that the number of
+ messages sent may be smaller than @num_messages if @timeout is zero
+ or positive, or if @num_messages was larger than `UIO_MAXIOV` (1024), in
+ which case the caller may re-try to send the remaining messages.
+
+
+
+
+ a #GDatagramBased
+
+
+
+ an array of #GOutputMessage structs
+
+
+
+
+
+ the number of elements in @messages
+
+
+
+ an int containing #GSocketMsgFlags flags
+
+
+
+ the maximum time (in microseconds) to wait, 0 to not block, or -1
+ to block indefinitely
+
+
+
+ a %GCancellable
+
+
+
+
+
+
+ Provides an interface for socket-like objects which have datagram semantics,
+following the Berkeley sockets API. The interface methods are thin wrappers
+around the corresponding virtual methods, and no pre-processing of inputs is
+implemented — so implementations of this API must handle all functionality
+documented in the interface methods.
+
+
+ The parent interface.
+
+
+
+
+
+
+ number of messages received, or -1 on error. Note that the number
+ of messages received may be smaller than @num_messages if @timeout is
+ zero or positive, if the peer closed the connection, or if @num_messages
+ was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try
+ to receive the remaining messages.
+
+
+
+
+ a #GDatagramBased
+
+
+
+ an array of #GInputMessage structs
+
+
+
+
+
+ the number of elements in @messages
+
+
+
+ an int containing #GSocketMsgFlags flags for the overall operation
+
+
+
+ the maximum time (in microseconds) to wait, 0 to not block, or -1
+ to block indefinitely
+
+
+
+ a %GCancellable
+
+
+
+
+
+
+
+
+
+ number of messages sent, or -1 on error. Note that the number of
+ messages sent may be smaller than @num_messages if @timeout is zero
+ or positive, or if @num_messages was larger than `UIO_MAXIOV` (1024), in
+ which case the caller may re-try to send the remaining messages.
+
+
+
+
+ a #GDatagramBased
+
+
+
+ an array of #GOutputMessage structs
+
+
+
+
+
+ the number of elements in @messages
+
+
+
+ an int containing #GSocketMsgFlags flags
+
+
+
+ the maximum time (in microseconds) to wait, 0 to not block, or -1
+ to block indefinitely
+
+
+
+ a %GCancellable
+
+
+
+
+
+
+
+
+
+ a newly allocated #GSource
+
+
+
+
+ a #GDatagramBased
+
+
+
+ a #GIOCondition mask to monitor
+
+
+
+ a #GCancellable
+
+
+
+
+
+
+
+
+
+ the #GIOCondition mask of the current state
+
+
+
+
+ a #GDatagramBased
+
+
+
+ a #GIOCondition mask to check
+
+
+
+
+
+
+
+
+
+ %TRUE if the condition was met, %FALSE otherwise
+
+
+
+
+ a #GDatagramBased
+
+
+
+ a #GIOCondition mask to wait for
+
+
+
+ the maximum time (in microseconds) to wait, 0 to not block, or -1
+ to block indefinitely
+
+
+
+ a #GCancellable
+
+
+
+
+
+
+
+ This is the function type of the callback used for the #GSource
+returned by g_datagram_based_create_source().
+
+
+ %G_SOURCE_REMOVE if the source should be removed,
+ %G_SOURCE_CONTINUE otherwise
+
+
+
+
+ the #GDatagramBased
+
+
+
+ the current condition at the source fired
+
+
+
+ data passed in by the user
+
+
+
+
+
+ #GDebugController is an interface to expose control of debugging features and
+debug output.
+
+It is implemented on Linux using #GDebugControllerDBus, which exposes a D-Bus
+interface to allow authenticated peers to control debug features in this
+process.
+
+Whether debug output is enabled is exposed as
+#GDebugController:debug-enabled. This controls g_log_set_debug_enabled() by
+default. Application code may connect to the #GObject::notify signal for it
+to control other parts of its debug infrastructure as necessary.
+
+If your application or service is using the default GLib log writer function,
+creating one of the built-in implementations of #GDebugController should be
+all that’s needed to dynamically enable or disable debug output.
+
+
+
+ Get the value of #GDebugController:debug-enabled.
+
+
+ %TRUE if debug output should be exposed, %FALSE otherwise
+
+
+
+
+ a #GDebugController
+
+
+
+
+
+ Set the value of #GDebugController:debug-enabled.
+
+
+
+
+
+
+ a #GDebugController
+
+
+
+ %TRUE if debug output should be exposed, %FALSE otherwise
+
+
+
+
+
+ %TRUE if debug output should be exposed (for example by forwarding it to
+the journal), %FALSE otherwise.
+
+
+
+
+ #GDebugControllerDBus is an implementation of #GDebugController which exposes
+debug settings as a D-Bus object.
+
+It is a #GInitable object, and will register an object at
+`/org/gtk/Debugging` on the bus given as
+#GDebugControllerDBus:connection once it’s initialized. The object will be
+unregistered when the last reference to the #GDebugControllerDBus is dropped.
+
+This D-Bus object can be used by remote processes to enable or disable debug
+output in this process. Remote processes calling
+`org.gtk.Debugging.SetDebugEnabled()` will affect the value of
+#GDebugController:debug-enabled and, by default, g_log_get_debug_enabled().
+default.
+
+By default, all processes will be able to call `SetDebugEnabled()`. If this
+process is privileged, or might expose sensitive information in its debug
+output, you may want to restrict the ability to enable debug output to
+privileged users or processes.
+
+One option is to install a D-Bus security policy which restricts access to
+`SetDebugEnabled()`, installing something like the following in
+`$datadir/dbus-1/system.d/`:
+|[<!-- language="XML" -->
+<?xml version="1.0"?> <!--*-nxml-*-->
+<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
+ "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
+<busconfig>
+ <policy user="root">
+ <allow send_destination="com.example.MyService" send_interface="org.gtk.Debugging"/>
+ </policy>
+ <policy context="default">
+ <deny send_destination="com.example.MyService" send_interface="org.gtk.Debugging"/>
+ </policy>
+</busconfig>
+]|
+
+This will prevent the `SetDebugEnabled()` method from being called by all
+except root. It will not prevent the `DebugEnabled` property from being read,
+as it’s accessed through the `org.freedesktop.DBus.Properties` interface.
+
+Another option is to use polkit to allow or deny requests on a case-by-case
+basis, allowing for the possibility of dynamic authorisation. To do this,
+connect to the #GDebugControllerDBus::authorize signal and query polkit in
+it:
+|[<!-- language="C" -->
+ g_autoptr(GError) child_error = NULL;
+ g_autoptr(GDBusConnection) connection = g_bus_get_sync (G_BUS_TYPE_SYSTEM, NULL, NULL);
+ gulong debug_controller_authorize_id = 0;
+
+ // Set up the debug controller.
+ debug_controller = G_DEBUG_CONTROLLER (g_debug_controller_dbus_new (priv->connection, NULL, &child_error));
+ if (debug_controller == NULL)
+ {
+ g_error ("Could not register debug controller on bus: %s"),
+ child_error->message);
+ }
+
+ debug_controller_authorize_id = g_signal_connect (debug_controller,
+ "authorize",
+ G_CALLBACK (debug_controller_authorize_cb),
+ self);
+
+ static gboolean
+ debug_controller_authorize_cb (GDebugControllerDBus *debug_controller,
+ GDBusMethodInvocation *invocation,
+ gpointer user_data)
+ {
+ g_autoptr(PolkitAuthority) authority = NULL;
+ g_autoptr(PolkitSubject) subject = NULL;
+ g_autoptr(PolkitAuthorizationResult) auth_result = NULL;
+ g_autoptr(GError) local_error = NULL;
+ GDBusMessage *message;
+ GDBusMessageFlags message_flags;
+ PolkitCheckAuthorizationFlags flags = POLKIT_CHECK_AUTHORIZATION_FLAGS_NONE;
+
+ message = g_dbus_method_invocation_get_message (invocation);
+ message_flags = g_dbus_message_get_flags (message);
+
+ authority = polkit_authority_get_sync (NULL, &local_error);
+ if (authority == NULL)
+ {
+ g_warning ("Failed to get polkit authority: %s", local_error->message);
+ return FALSE;
+ }
+
+ if (message_flags & G_DBUS_MESSAGE_FLAGS_ALLOW_INTERACTIVE_AUTHORIZATION)
+ flags |= POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION;
+
+ subject = polkit_system_bus_name_new (g_dbus_method_invocation_get_sender (invocation));
+
+ auth_result = polkit_authority_check_authorization_sync (authority,
+ subject,
+ "com.example.MyService.set-debug-enabled",
+ NULL,
+ flags,
+ NULL,
+ &local_error);
+ if (auth_result == NULL)
+ {
+ g_warning ("Failed to get check polkit authorization: %s", local_error->message);
+ return FALSE;
+ }
+
+ return polkit_authorization_result_get_is_authorized (auth_result);
+ }
+]|
+
+
+
+
+ Create a new #GDebugControllerDBus and synchronously initialize it.
+
+Initializing the object will export the debug object on @connection. The
+object will remain registered until the last reference to the
+#GDebugControllerDBus is dropped.
+
+Initialization may fail if registering the object on @connection fails.
+
+
+ a new #GDebugControllerDBus, or %NULL
+ on failure
+
+
+
+
+ a #GDBusConnection to register the debug object on
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Stop the debug controller, unregistering its object from the bus.
+
+Any pending method calls to the object will complete successfully, but new
+ones will return an error. This method will block until all pending
+#GDebugControllerDBus::authorize signals have been handled. This is expected
+to not take long, as it will just be waiting for threads to join. If any
+#GDebugControllerDBus::authorize signal handlers are still executing in other
+threads, this will block until after they have returned.
+
+This method will be called automatically when the final reference to the
+#GDebugControllerDBus is dropped. You may want to call it explicitly to know
+when the controller has been fully removed from the bus, or to break
+reference count cycles.
+
+Calling this method from within a #GDebugControllerDBus::authorize signal
+handler will cause a deadlock and must not be done.
+
+
+
+
+
+
+ a #GDebugControllerDBus
+
+
+
+
+
+ The D-Bus connection to expose the debugging interface on.
+
+Typically this will be the same connection (to the system or session bus)
+which the rest of the application or service’s D-Bus objects are registered
+on.
+
+
+
+
+
+
+ Emitted when a D-Bus peer is trying to change the debug settings and used
+to determine if that is authorized.
+
+This signal is emitted in a dedicated worker thread, so handlers are
+allowed to perform blocking I/O. This means that, for example, it is
+appropriate to call `polkit_authority_check_authorization_sync()` to check
+authorization using polkit.
+
+If %FALSE is returned then no further handlers are run and the request to
+change the debug settings is rejected.
+
+Otherwise, if %TRUE is returned, signal emission continues. If no handlers
+return %FALSE, then the debug settings are allowed to be changed.
+
+Signal handlers must not modify @invocation, or cause it to return a value.
+
+The default class handler just returns %TRUE.
+
+ %TRUE if the call is authorized, %FALSE otherwise.
+
+
+
+
+ A #GDBusMethodInvocation.
+
+
+
+
+
+
+ The virtual function table for #GDebugControllerDBus.
+
+
+ The parent class.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The virtual function table for #GDebugController.
+
+
+ The parent interface.
+
+
+
+
+ #GDesktopAppInfo is an implementation of #GAppInfo based on
+desktop files.
+
+Note that `<gio/gdesktopappinfo.h>` belongs to the UNIX-specific
+GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
+file when using it.
+
+
+
+ Creates a new #GDesktopAppInfo based on a desktop file id.
+
+A desktop file id is the basename of the desktop file, including the
+.desktop extension. GIO is looking for a desktop file with this name
+in the `applications` subdirectories of the XDG
+data directories (i.e. the directories specified in the `XDG_DATA_HOME`
+and `XDG_DATA_DIRS` environment variables). GIO also supports the
+prefix-to-subdirectory mapping that is described in the
+[Menu Spec](http://standards.freedesktop.org/menu-spec/latest/)
+(i.e. a desktop id of kde-foo.desktop will match
+`/usr/share/applications/kde/foo.desktop`).
+
+
+ a new #GDesktopAppInfo, or %NULL if no desktop
+ file with that id exists.
+
+
+
+
+ the desktop file id
+
+
+
+
+
+ Creates a new #GDesktopAppInfo.
+
+
+ a new #GDesktopAppInfo or %NULL on error.
+
+
+
+
+ the path of a desktop file, in the GLib
+ filename encoding
+
+
+
+
+
+ Creates a new #GDesktopAppInfo.
+
+
+ a new #GDesktopAppInfo or %NULL on error.
+
+
+
+
+ an opened #GKeyFile
+
+
+
+
+
+ Gets all applications that implement @interface.
+
+An application implements an interface if that interface is listed in
+the Implements= line of the desktop file of the application.
+
+
+ a list of #GDesktopAppInfo
+objects.
+
+
+
+
+
+
+ the name of the interface
+
+
+
+
+
+ Searches desktop files for ones that match @search_string.
+
+The return value is an array of strvs. Each strv contains a list of
+applications that matched @search_string with an equal score. The
+outer list is sorted by score so that the first strv contains the
+best-matching applications, and so on.
+The algorithm for determining matches is undefined and may change at
+any time.
+
+None of the search results are subjected to the normal validation
+checks performed by g_desktop_app_info_new() (for example, checking that
+the executable referenced by a result exists), and so it is possible for
+g_desktop_app_info_new() to return %NULL when passed an app ID returned by
+this function. It is expected that calling code will do this when
+subsequently creating a #GDesktopAppInfo for each result.
+
+
+ a
+ list of strvs. Free each item with g_strfreev() and free the outer
+ list with g_free().
+
+
+
+
+
+
+
+
+ the search string to use
+
+
+
+
+
+ Sets the name of the desktop that the application is running in.
+This is used by g_app_info_should_show() and
+g_desktop_app_info_get_show_in() to evaluate the
+`OnlyShowIn` and `NotShowIn`
+desktop entry fields.
+
+Should be called only once; subsequent calls are ignored.
+ do not use this API. Since 2.42 the value of the
+`XDG_CURRENT_DESKTOP` environment variable will be used.
+
+
+
+
+
+
+ a string specifying what desktop this is
+
+
+
+
+
+ Gets the user-visible display name of the "additional application
+action" specified by @action_name.
+
+This corresponds to the "Name" key within the keyfile group for the
+action.
+
+
+ the locale-specific action name
+
+
+
+
+ a #GDesktopAppInfo
+
+
+
+ the name of the action as from
+ g_desktop_app_info_list_actions()
+
+
+
+
+
+ Looks up a boolean value in the keyfile backing @info.
+
+The @key is looked up in the "Desktop Entry" group.
+
+
+ the boolean value, or %FALSE if the key
+ is not found
+
+
+
+
+ a #GDesktopAppInfo
+
+
+
+ the key to look up
+
+
+
+
+
+ Gets the categories from the desktop file.
+
+
+ The unparsed Categories key from the desktop file;
+ i.e. no attempt is made to split it by ';' or validate it.
+
+
+
+
+ a #GDesktopAppInfo
+
+
+
+
+
+ When @info was created from a known filename, return it. In some
+situations such as the #GDesktopAppInfo returned from
+g_desktop_app_info_new_from_keyfile(), this function will return %NULL.
+
+
+ The full path to the file for @info,
+ or %NULL if not known.
+
+
+
+
+ a #GDesktopAppInfo
+
+
+
+
+
+ Gets the generic name from the desktop file.
+
+
+ The value of the GenericName key
+
+
+
+
+ a #GDesktopAppInfo
+
+
+
+
+
+ A desktop file is hidden if the Hidden key in it is
+set to True.
+
+
+ %TRUE if hidden, %FALSE otherwise.
+
+
+
+
+ a #GDesktopAppInfo.
+
+
+
+
+
+ Gets the keywords from the desktop file.
+
+
+ The value of the Keywords key
+
+
+
+
+
+
+ a #GDesktopAppInfo
+
+
+
+
+
+ Looks up a localized string value in the keyfile backing @info
+translated to the current locale.
+
+The @key is looked up in the "Desktop Entry" group.
+
+
+ a newly allocated string, or %NULL if the key
+ is not found
+
+
+
+
+ a #GDesktopAppInfo
+
+
+
+ the key to look up
+
+
+
+
+
+ Gets the value of the NoDisplay key, which helps determine if the
+application info should be shown in menus. See
+%G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY and g_app_info_should_show().
+
+
+ The value of the NoDisplay key
+
+
+
+
+ a #GDesktopAppInfo
+
+
+
+
+
+ Checks if the application info should be shown in menus that list available
+applications for a specific name of the desktop, based on the
+`OnlyShowIn` and `NotShowIn` keys.
+
+@desktop_env should typically be given as %NULL, in which case the
+`XDG_CURRENT_DESKTOP` environment variable is consulted. If you want
+to override the default mechanism then you may specify @desktop_env,
+but this is not recommended.
+
+Note that g_app_info_should_show() for @info will include this check (with
+%NULL for @desktop_env) as well as additional checks.
+
+
+ %TRUE if the @info should be shown in @desktop_env according to the
+`OnlyShowIn` and `NotShowIn` keys, %FALSE
+otherwise.
+
+
+
+
+ a #GDesktopAppInfo
+
+
+
+ a string specifying a desktop name
+
+
+
+
+
+ Retrieves the StartupWMClass field from @info. This represents the
+WM_CLASS property of the main window of the application, if launched
+through @info.
+
+
+ the startup WM class, or %NULL if none is set
+in the desktop file.
+
+
+
+
+ a #GDesktopAppInfo that supports startup notify
+
+
+
+
+
+ Looks up a string value in the keyfile backing @info.
+
+The @key is looked up in the "Desktop Entry" group.
+
+
+ a newly allocated string, or %NULL if the key
+ is not found
+
+
+
+
+ a #GDesktopAppInfo
+
+
+
+ the key to look up
+
+
+
+
+
+ Looks up a string list value in the keyfile backing @info.
+
+The @key is looked up in the "Desktop Entry" group.
+
+
+
+ a %NULL-terminated string array or %NULL if the specified
+ key cannot be found. The array should be freed with g_strfreev().
+
+
+
+
+
+
+ a #GDesktopAppInfo
+
+
+
+ the key to look up
+
+
+
+ return location for the number of returned strings, or %NULL
+
+
+
+
+
+ Returns whether @key exists in the "Desktop Entry" group
+of the keyfile backing @info.
+
+
+ %TRUE if the @key exists
+
+
+
+
+ a #GDesktopAppInfo
+
+
+
+ the key to look up
+
+
+
+
+
+ Activates the named application action.
+
+You may only call this function on action names that were
+returned from g_desktop_app_info_list_actions().
+
+Note that if the main entry of the desktop file indicates that the
+application supports startup notification, and @launch_context is
+non-%NULL, then startup notification will be used when activating the
+action (and as such, invocation of the action on the receiving side
+must signal the end of startup notification when it is completed).
+This is the expected behaviour of applications declaring additional
+actions, as per the desktop file specification.
+
+As with g_app_info_launch() there is no way to detect failures that
+occur while using this function.
+
+
+
+
+
+
+ a #GDesktopAppInfo
+
+
+
+ the name of the action as from
+ g_desktop_app_info_list_actions()
+
+
+
+ a #GAppLaunchContext
+
+
+
+
+
+ This function performs the equivalent of g_app_info_launch_uris(),
+but is intended primarily for operating system components that
+launch applications. Ordinary applications should use
+g_app_info_launch_uris().
+
+If the application is launched via GSpawn, then @spawn_flags, @user_setup
+and @user_setup_data are used for the call to g_spawn_async().
+Additionally, @pid_callback (with @pid_callback_data) will be called to
+inform about the PID of the created process. See g_spawn_async_with_pipes()
+for information on certain parameter conditions that can enable an
+optimized posix_spawn() codepath to be used.
+
+If application launching occurs via some other mechanism (eg: D-Bus
+activation) then @spawn_flags, @user_setup, @user_setup_data,
+@pid_callback and @pid_callback_data are ignored.
+
+
+ %TRUE on successful launch, %FALSE otherwise.
+
+
+
+
+ a #GDesktopAppInfo
+
+
+
+ List of URIs
+
+
+
+
+
+ a #GAppLaunchContext
+
+
+
+ #GSpawnFlags, used for each process
+
+
+
+ a #GSpawnChildSetupFunc, used once
+ for each process.
+
+
+
+ User data for @user_setup
+
+
+
+ Callback for child processes
+
+
+
+ User data for @callback
+
+
+
+
+
+ Equivalent to g_desktop_app_info_launch_uris_as_manager() but allows
+you to pass in file descriptors for the stdin, stdout and stderr streams
+of the launched process.
+
+If application launching occurs via some non-spawn mechanism (e.g. D-Bus
+activation) then @stdin_fd, @stdout_fd and @stderr_fd are ignored.
+
+
+ %TRUE on successful launch, %FALSE otherwise.
+
+
+
+
+ a #GDesktopAppInfo
+
+
+
+ List of URIs
+
+
+
+
+
+ a #GAppLaunchContext
+
+
+
+ #GSpawnFlags, used for each process
+
+
+
+ a #GSpawnChildSetupFunc, used once
+ for each process.
+
+
+
+ User data for @user_setup
+
+
+
+ Callback for child processes
+
+
+
+ User data for @callback
+
+
+
+ file descriptor to use for child's stdin, or -1
+
+
+
+ file descriptor to use for child's stdout, or -1
+
+
+
+ file descriptor to use for child's stderr, or -1
+
+
+
+
+
+ Returns the list of "additional application actions" supported on the
+desktop file, as per the desktop file specification.
+
+As per the specification, this is the list of actions that are
+explicitly listed in the "Actions" key of the [Desktop Entry] group.
+
+
+ a list of strings, always non-%NULL
+
+
+
+
+
+
+ a #GDesktopAppInfo
+
+
+
+
+
+ The origin filename of this #GDesktopAppInfo
+
+
+
+
+
+
+
+
+
+
+ #GDesktopAppInfoLookup is an opaque data structure and can only be accessed
+using the following functions.
+ The #GDesktopAppInfoLookup interface is deprecated and
+ unused by GIO.
+
+
+ Gets the default application for launching applications
+using this URI scheme for a particular #GDesktopAppInfoLookup
+implementation.
+
+The #GDesktopAppInfoLookup interface and this function is used
+to implement g_app_info_get_default_for_uri_scheme() backends
+in a GIO module. There is no reason for applications to use it
+directly. Applications should use g_app_info_get_default_for_uri_scheme().
+ The #GDesktopAppInfoLookup interface is deprecated and
+ unused by GIO.
+
+
+ #GAppInfo for given @uri_scheme or
+ %NULL on error.
+
+
+
+
+ a #GDesktopAppInfoLookup
+
+
+
+ a string containing a URI scheme.
+
+
+
+
+
+ Gets the default application for launching applications
+using this URI scheme for a particular #GDesktopAppInfoLookup
+implementation.
+
+The #GDesktopAppInfoLookup interface and this function is used
+to implement g_app_info_get_default_for_uri_scheme() backends
+in a GIO module. There is no reason for applications to use it
+directly. Applications should use g_app_info_get_default_for_uri_scheme().
+ The #GDesktopAppInfoLookup interface is deprecated and
+ unused by GIO.
+
+
+ #GAppInfo for given @uri_scheme or
+ %NULL on error.
+
+
+
+
+ a #GDesktopAppInfoLookup
+
+
+
+ a string containing a URI scheme.
+
+
+
+
+
+
+ Interface that is used by backends to associate default
+handlers with URI schemes.
+
+
+
+
+
+
+
+
+ #GAppInfo for given @uri_scheme or
+ %NULL on error.
+
+
+
+
+ a #GDesktopAppInfoLookup
+
+
+
+ a string containing a URI scheme.
+
+
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+ a #GDesktopAppInfo
+
+
+
+ Process identifier
+
+
+
+ User data
+
+
+
+
+
+ #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, determining 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 potentially 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.
+
+
+ Checks if a drive can be ejected.
+
+
+ %TRUE if the @drive can be ejected, %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+ Checks if a drive can be polled for media changes.
+
+
+ %TRUE if the @drive can be polled for media changes,
+ %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+ Checks if a drive can be started.
+
+
+ %TRUE if the @drive can be started, %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+ Checks if a drive can be started degraded.
+
+
+ %TRUE if the @drive can be started degraded, %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+ Checks if a drive can be stopped.
+
+
+ %TRUE if the @drive can be stopped, %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Asynchronously ejects a drive.
+
+When the operation is finished, @callback will be called.
+You can then call g_drive_eject_finish() to obtain the
+result of the operation.
+ Use g_drive_eject_with_operation() instead.
+
+
+
+
+
+
+ a #GDrive.
+
+
+
+ flags affecting the unmount if required for eject
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback, or %NULL.
+
+
+
+ user data to pass to @callback
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Finishes ejecting a drive.
+ Use g_drive_eject_with_operation_finish() instead.
+
+
+ %TRUE if the drive has been ejected successfully,
+ %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Ejects a drive. This is an asynchronous operation, and is
+finished by calling g_drive_eject_with_operation_finish() with the @drive
+and #GAsyncResult data returned in the @callback.
+
+
+
+
+
+
+ a #GDrive.
+
+
+
+ flags affecting the unmount if required for eject
+
+
+
+ a #GMountOperation or %NULL to avoid
+ user interaction.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback, or %NULL.
+
+
+
+ user data passed to @callback.
+
+
+
+
+
+ Finishes ejecting a drive. If any errors occurred during the operation,
+@error will be set to contain the errors and %FALSE will be returned.
+
+
+ %TRUE if the drive was successfully ejected. %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Gets the kinds of identifiers that @drive has.
+Use g_drive_get_identifier() to obtain the identifiers
+themselves.
+
+
+ a %NULL-terminated
+ array of strings containing kinds of identifiers. Use g_strfreev()
+ to free.
+
+
+
+
+
+
+ a #GDrive
+
+
+
+
+
+ Gets the icon for @drive.
+
+
+ #GIcon for the @drive.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+ Gets the identifier of the given kind for @drive. The only
+identifier currently available is
+%G_DRIVE_IDENTIFIER_KIND_UNIX_DEVICE.
+
+
+ a newly allocated string containing the
+ requested identifier, or %NULL if the #GDrive
+ doesn't have this kind of identifier.
+
+
+
+
+ a #GDrive
+
+
+
+ the kind of identifier to return
+
+
+
+
+
+ Gets the name of @drive.
+
+
+ a string containing @drive's name. The returned
+ string should be freed when no longer needed.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+ Gets the sort key for @drive, if any.
+
+
+ Sorting key for @drive or %NULL if no such key is available.
+
+
+
+
+ A #GDrive.
+
+
+
+
+
+ Gets a hint about how a drive can be started/stopped.
+
+
+ A value from the #GDriveStartStopType enumeration.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+ Gets the icon for @drive.
+
+
+ symbolic #GIcon for the @drive.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+ Get a list of mountable volumes for @drive.
+
+The returned list should be freed with g_list_free(), after
+its elements have been unreffed with g_object_unref().
+
+
+ #GList containing any #GVolume objects on the given @drive.
+
+
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+ Checks if the @drive has media. Note that the OS may not be polling
+the drive for media changes; see g_drive_is_media_check_automatic()
+for more details.
+
+
+ %TRUE if @drive has media, %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+ Check if @drive has any mountable volumes.
+
+
+ %TRUE if the @drive contains volumes, %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+ Checks if @drive is capable of automatically detecting media changes.
+
+
+ %TRUE if the @drive is capable of automatically detecting
+ media changes, %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+ Checks if the @drive supports removable media.
+
+
+ %TRUE if @drive supports removable media, %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+ Checks if the #GDrive and/or its media is considered removable by the user.
+See g_drive_is_media_removable().
+
+
+ %TRUE if @drive and/or its media is considered removable, %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+ Asynchronously polls @drive to see if media has been inserted or removed.
+
+When the operation is finished, @callback will be called.
+You can then call g_drive_poll_for_media_finish() to obtain the
+result of the operation.
+
+
+
+
+
+
+ a #GDrive.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback, or %NULL.
+
+
+
+ user data to pass to @callback
+
+
+
+
+
+ Finishes an operation started with g_drive_poll_for_media() on a drive.
+
+
+ %TRUE if the drive has been poll_for_mediaed successfully,
+ %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Asynchronously starts a drive.
+
+When the operation is finished, @callback will be called.
+You can then call g_drive_start_finish() to obtain the
+result of the operation.
+
+
+
+
+
+
+ a #GDrive.
+
+
+
+ flags affecting the start operation.
+
+
+
+ a #GMountOperation or %NULL to avoid
+ user interaction.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback, or %NULL.
+
+
+
+ user data to pass to @callback
+
+
+
+
+
+ Finishes starting a drive.
+
+
+ %TRUE if the drive has been started successfully,
+ %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Asynchronously stops a drive.
+
+When the operation is finished, @callback will be called.
+You can then call g_drive_stop_finish() to obtain the
+result of the operation.
+
+
+
+
+
+
+ a #GDrive.
+
+
+
+ flags affecting the unmount if required for stopping.
+
+
+
+ a #GMountOperation or %NULL to avoid
+ user interaction.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback, or %NULL.
+
+
+
+ user data to pass to @callback
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Finishes stopping a drive.
+
+
+ %TRUE if the drive has been stopped successfully,
+ %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Checks if a drive can be ejected.
+
+
+ %TRUE if the @drive can be ejected, %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+ Checks if a drive can be polled for media changes.
+
+
+ %TRUE if the @drive can be polled for media changes,
+ %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+ Checks if a drive can be started.
+
+
+ %TRUE if the @drive can be started, %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+ Checks if a drive can be started degraded.
+
+
+ %TRUE if the @drive can be started degraded, %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+ Checks if a drive can be stopped.
+
+
+ %TRUE if the @drive can be stopped, %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+ Asynchronously ejects a drive.
+
+When the operation is finished, @callback will be called.
+You can then call g_drive_eject_finish() to obtain the
+result of the operation.
+ Use g_drive_eject_with_operation() instead.
+
+
+
+
+
+
+ a #GDrive.
+
+
+
+ flags affecting the unmount if required for eject
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback, or %NULL.
+
+
+
+ user data to pass to @callback
+
+
+
+
+
+ Finishes ejecting a drive.
+ Use g_drive_eject_with_operation_finish() instead.
+
+
+ %TRUE if the drive has been ejected successfully,
+ %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Ejects a drive. This is an asynchronous operation, and is
+finished by calling g_drive_eject_with_operation_finish() with the @drive
+and #GAsyncResult data returned in the @callback.
+
+
+
+
+
+
+ a #GDrive.
+
+
+
+ flags affecting the unmount if required for eject
+
+
+
+ a #GMountOperation or %NULL to avoid
+ user interaction.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback, or %NULL.
+
+
+
+ user data passed to @callback.
+
+
+
+
+
+ Finishes ejecting a drive. If any errors occurred during the operation,
+@error will be set to contain the errors and %FALSE will be returned.
+
+
+ %TRUE if the drive was successfully ejected. %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Gets the kinds of identifiers that @drive has.
+Use g_drive_get_identifier() to obtain the identifiers
+themselves.
+
+
+ a %NULL-terminated
+ array of strings containing kinds of identifiers. Use g_strfreev()
+ to free.
+
+
+
+
+
+
+ a #GDrive
+
+
+
+
+
+ Gets the icon for @drive.
+
+
+ #GIcon for the @drive.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+ Gets the identifier of the given kind for @drive. The only
+identifier currently available is
+%G_DRIVE_IDENTIFIER_KIND_UNIX_DEVICE.
+
+
+ a newly allocated string containing the
+ requested identifier, or %NULL if the #GDrive
+ doesn't have this kind of identifier.
+
+
+
+
+ a #GDrive
+
+
+
+ the kind of identifier to return
+
+
+
+
+
+ Gets the name of @drive.
+
+
+ a string containing @drive's name. The returned
+ string should be freed when no longer needed.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+ Gets the sort key for @drive, if any.
+
+
+ Sorting key for @drive or %NULL if no such key is available.
+
+
+
+
+ A #GDrive.
+
+
+
+
+
+ Gets a hint about how a drive can be started/stopped.
+
+
+ A value from the #GDriveStartStopType enumeration.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+ Gets the icon for @drive.
+
+
+ symbolic #GIcon for the @drive.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+ Get a list of mountable volumes for @drive.
+
+The returned list should be freed with g_list_free(), after
+its elements have been unreffed with g_object_unref().
+
+
+ #GList containing any #GVolume objects on the given @drive.
+
+
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+ Checks if the @drive has media. Note that the OS may not be polling
+the drive for media changes; see g_drive_is_media_check_automatic()
+for more details.
+
+
+ %TRUE if @drive has media, %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+ Check if @drive has any mountable volumes.
+
+
+ %TRUE if the @drive contains volumes, %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+ Checks if @drive is capable of automatically detecting media changes.
+
+
+ %TRUE if the @drive is capable of automatically detecting
+ media changes, %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+ Checks if the @drive supports removable media.
+
+
+ %TRUE if @drive supports removable media, %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+ Checks if the #GDrive and/or its media is considered removable by the user.
+See g_drive_is_media_removable().
+
+
+ %TRUE if @drive and/or its media is considered removable, %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+ Asynchronously polls @drive to see if media has been inserted or removed.
+
+When the operation is finished, @callback will be called.
+You can then call g_drive_poll_for_media_finish() to obtain the
+result of the operation.
+
+
+
+
+
+
+ a #GDrive.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback, or %NULL.
+
+
+
+ user data to pass to @callback
+
+
+
+
+
+ Finishes an operation started with g_drive_poll_for_media() on a drive.
+
+
+ %TRUE if the drive has been poll_for_mediaed successfully,
+ %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Asynchronously starts a drive.
+
+When the operation is finished, @callback will be called.
+You can then call g_drive_start_finish() to obtain the
+result of the operation.
+
+
+
+
+
+
+ a #GDrive.
+
+
+
+ flags affecting the start operation.
+
+
+
+ a #GMountOperation or %NULL to avoid
+ user interaction.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback, or %NULL.
+
+
+
+ user data to pass to @callback
+
+
+
+
+
+ Finishes starting a drive.
+
+
+ %TRUE if the drive has been started successfully,
+ %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Asynchronously stops a drive.
+
+When the operation is finished, @callback will be called.
+You can then call g_drive_stop_finish() to obtain the
+result of the operation.
+
+
+
+
+
+
+ a #GDrive.
+
+
+
+ flags affecting the unmount if required for stopping.
+
+
+
+ a #GMountOperation or %NULL to avoid
+ user interaction.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback, or %NULL.
+
+
+
+ user data to pass to @callback
+
+
+
+
+
+ Finishes stopping a drive.
+
+
+ %TRUE if the drive has been stopped successfully,
+ %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Emitted when the drive's state has changed.
+
+
+
+
+
+ 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.
+
+
+
+
+
+ Emitted when the physical eject button (if any) of a drive has
+been pressed.
+
+
+
+
+
+ Emitted when the physical stop button (if any) of a drive has
+been pressed.
+
+
+
+
+
+
+ Interface for creating #GDrive implementations.
+
+
+ The parent interface.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a string containing @drive's name. The returned
+ string should be freed when no longer needed.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+
+
+
+
+ #GIcon for the @drive.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+
+
+
+
+ %TRUE if the @drive contains volumes, %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+
+
+
+
+ #GList containing any #GVolume objects on the given @drive.
+
+
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+
+
+
+
+ %TRUE if @drive supports removable media, %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+
+
+
+
+ %TRUE if @drive has media, %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+
+
+
+
+ %TRUE if the @drive is capable of automatically detecting
+ media changes, %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+
+
+
+
+ %TRUE if the @drive can be ejected, %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+
+
+
+
+ %TRUE if the @drive can be polled for media changes,
+ %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GDrive.
+
+
+
+ flags affecting the unmount if required for eject
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback, or %NULL.
+
+
+
+ user data to pass to @callback
+
+
+
+
+
+
+
+
+
+ %TRUE if the drive has been ejected successfully,
+ %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GDrive.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback, or %NULL.
+
+
+
+ user data to pass to @callback
+
+
+
+
+
+
+
+
+
+ %TRUE if the drive has been poll_for_mediaed successfully,
+ %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+ a newly allocated string containing the
+ requested identifier, or %NULL if the #GDrive
+ doesn't have this kind of identifier.
+
+
+
+
+ a #GDrive
+
+
+
+ the kind of identifier to return
+
+
+
+
+
+
+
+
+
+ a %NULL-terminated
+ array of strings containing kinds of identifiers. Use g_strfreev()
+ to free.
+
+
+
+
+
+
+ a #GDrive
+
+
+
+
+
+
+
+
+
+ A value from the #GDriveStartStopType enumeration.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+
+
+
+
+ %TRUE if the @drive can be started, %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+
+
+
+
+ %TRUE if the @drive can be started degraded, %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GDrive.
+
+
+
+ flags affecting the start operation.
+
+
+
+ a #GMountOperation or %NULL to avoid
+ user interaction.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback, or %NULL.
+
+
+
+ user data to pass to @callback
+
+
+
+
+
+
+
+
+
+ %TRUE if the drive has been started successfully,
+ %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+ %TRUE if the @drive can be stopped, %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GDrive.
+
+
+
+ flags affecting the unmount if required for stopping.
+
+
+
+ a #GMountOperation or %NULL to avoid
+ user interaction.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback, or %NULL.
+
+
+
+ user data to pass to @callback
+
+
+
+
+
+
+
+
+
+ %TRUE if the drive has been stopped successfully,
+ %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GDrive.
+
+
+
+ flags affecting the unmount if required for eject
+
+
+
+ a #GMountOperation or %NULL to avoid
+ user interaction.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback, or %NULL.
+
+
+
+ user data passed to @callback.
+
+
+
+
+
+
+
+
+
+ %TRUE if the drive was successfully ejected. %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+ Sorting key for @drive or %NULL if no such key is available.
+
+
+
+
+ A #GDrive.
+
+
+
+
+
+
+
+
+
+ symbolic #GIcon for the @drive.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+
+
+
+
+ %TRUE if @drive and/or its media is considered removable, %FALSE otherwise.
+
+
+
+
+ a #GDrive.
+
+
+
+
+
+
+
+ Flags used when starting a drive.
+
+ No flags set.
+
+
+
+ Enumeration describing how a drive can be started/stopped.
+
+ Unknown or drive doesn't support
+ start/stop.
+
+
+ The stop method will physically
+ shut down the drive and e.g. power down the port the drive is
+ attached to.
+
+
+ The start/stop methods are used
+ for connecting/disconnect to the drive over the network.
+
+
+ The start/stop methods will
+ assemble/disassemble a virtual drive from several physical
+ drives.
+
+
+ The start/stop methods will
+ unlock/lock the disk (for example using the ATA <quote>SECURITY
+ UNLOCK DEVICE</quote> command)
+
+
+
+ #GDtlsClientConnection is the client-side subclass of
+#GDtlsConnection, representing a client-side DTLS connection.
+
+
+
+
+ Creates a new #GDtlsClientConnection wrapping @base_socket which is
+assumed to communicate with the server identified by @server_identity.
+
+
+ the new
+ #GDtlsClientConnection, or %NULL on error
+
+
+
+
+ the #GDatagramBased to wrap
+
+
+
+ the expected identity of the server
+
+
+
+
+
+ Gets the list of distinguished names of the Certificate Authorities
+that the server will accept certificates from. This will be set
+during the TLS handshake if the server requests a certificate.
+Otherwise, it will be %NULL.
+
+Each item in the list is a #GByteArray which contains the complete
+subject DN of the certificate authority.
+
+
+ the list of
+CA DNs. You should unref each element with g_byte_array_unref() and then
+the free the list with g_list_free().
+
+
+
+
+
+
+
+
+ the #GDtlsClientConnection
+
+
+
+
+
+ Gets @conn's expected server identity
+
+
+ a #GSocketConnectable describing the
+expected server identity, or %NULL if the expected identity is not
+known.
+
+
+
+
+ the #GDtlsClientConnection
+
+
+
+
+
+ Gets @conn's validation flags
+
+This function does not work as originally designed and is impossible
+to use correctly. See #GDtlsClientConnection:validation-flags for more
+information.
+ Do not attempt to ignore validation errors.
+
+
+ the validation flags
+
+
+
+
+ the #GDtlsClientConnection
+
+
+
+
+
+ Sets @conn's expected server identity, which is used both to tell
+servers on virtual hosts which certificate to present, and also
+to let @conn know what name to look for in the certificate when
+performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled.
+
+
+
+
+
+
+ the #GDtlsClientConnection
+
+
+
+ a #GSocketConnectable describing the expected server identity
+
+
+
+
+
+ Sets @conn's validation flags, to override the default set of
+checks performed when validating a server certificate. By default,
+%G_TLS_CERTIFICATE_VALIDATE_ALL is used.
+
+This function does not work as originally designed and is impossible
+to use correctly. See #GDtlsClientConnection:validation-flags for more
+information.
+ Do not attempt to ignore validation errors.
+
+
+
+
+
+
+ the #GDtlsClientConnection
+
+
+
+ the #GTlsCertificateFlags to use
+
+
+
+
+
+ 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.
+
+
+
+
+
+ A #GSocketConnectable describing the identity of the server that
+is expected on the other end of the connection.
+
+If the %G_TLS_CERTIFICATE_BAD_IDENTITY flag is set in
+#GDtlsClientConnection:validation-flags, this object will be used
+to determine the expected identify of the remote end of the
+connection; if #GDtlsClientConnection:server-identity is not set,
+or does not match the identity presented by the server, then the
+%G_TLS_CERTIFICATE_BAD_IDENTITY validation will fail.
+
+In addition to its use in verifying the server certificate,
+this is also used to give a hint to the server about what
+certificate we expect, which is useful for servers that serve
+virtual hosts.
+
+
+
+ What steps to perform when validating a certificate received from
+a server. Server certificates that fail to validate in any of the
+ways indicated here will be rejected unless the application
+overrides the default via #GDtlsConnection::accept-certificate.
+
+GLib guarantees that if certificate verification fails, at least one
+flag will be set, but it does not guarantee that all possible flags
+will be set. Accordingly, you may not safely decide to ignore any
+particular type of error. For example, it would be incorrect to mask
+%G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates,
+because this could potentially be the only error flag set even if
+other problems exist with the certificate. Therefore, there is no
+safe way to use this property. This is not a horrible problem,
+though, because you should not be attempting to ignore validation
+errors anyway. If you really must ignore TLS certificate errors,
+connect to #GDtlsConnection::accept-certificate.
+ Do not attempt to ignore validation errors.
+
+
+
+
+ vtable for a #GDtlsClientConnection implementation.
+
+
+ The parent interface.
+
+
+
+
+ #GDtlsConnection is the base DTLS connection class type, which wraps
+a #GDatagramBased and provides DTLS encryption on top of it. Its
+subclasses, #GDtlsClientConnection and #GDtlsServerConnection,
+implement client-side and server-side DTLS, respectively.
+
+For TLS support, see #GTlsConnection.
+
+As DTLS is datagram based, #GDtlsConnection implements #GDatagramBased,
+presenting a datagram-socket-like API for the encrypted connection. This
+operates over a base datagram connection, which is also a #GDatagramBased
+(#GDtlsConnection:base-socket).
+
+To close a DTLS connection, use g_dtls_connection_close().
+
+Neither #GDtlsServerConnection or #GDtlsClientConnection set the peer address
+on their base #GDatagramBased if it is a #GSocket — it is up to the caller to
+do that if they wish. If they do not, and g_socket_close() is called on the
+base socket, the #GDtlsConnection will not raise a %G_IO_ERROR_NOT_CONNECTED
+error on further I/O.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Gets the name of the application-layer protocol negotiated during
+the handshake.
+
+If the peer did not use the ALPN extension, or did not advertise a
+protocol that matched one of @conn's protocols, or the TLS backend
+does not support ALPN, then this will be %NULL. See
+g_dtls_connection_set_advertised_protocols().
+
+
+ the negotiated protocol, or %NULL
+
+
+
+
+ a #GDtlsConnection
+
+
+
+
+
+ Attempts a TLS handshake on @conn.
+
+On the client side, it is never necessary to call this method;
+although the connection needs to perform a handshake after
+connecting, #GDtlsConnection will handle this for you automatically
+when you try to send or receive data on the connection. You can call
+g_dtls_connection_handshake() manually if you want to know whether
+the initial handshake succeeded or failed (as opposed to just
+immediately trying to use @conn to read or write, in which case,
+if it fails, it may not be possible to tell if it failed before
+or after completing the handshake), but beware that servers may reject
+client authentication after the handshake has completed, so a
+successful handshake does not indicate the connection will be usable.
+
+Likewise, on the server side, although a handshake is necessary at
+the beginning of the communication, you do not need to call this
+function explicitly unless you want clearer error reporting.
+
+Previously, calling g_dtls_connection_handshake() after the initial
+handshake would trigger a rehandshake; however, this usage was
+deprecated in GLib 2.60 because rehandshaking was removed from the
+TLS protocol in TLS 1.3. Since GLib 2.64, calling this function after
+the initial handshake will no longer do anything.
+
+#GDtlsConnection::accept_certificate may be emitted during the
+handshake.
+
+
+ success or failure
+
+
+
+
+ a #GDtlsConnection
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Asynchronously performs a TLS handshake on @conn. See
+g_dtls_connection_handshake() for more information.
+
+
+
+
+
+
+ a #GDtlsConnection
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call when the handshake is complete
+
+
+
+ the data to pass to the callback function
+
+
+
+
+
+ Finish an asynchronous TLS handshake operation. See
+g_dtls_connection_handshake() for more information.
+
+
+ %TRUE on success, %FALSE on failure, in which
+case @error will be set.
+
+
+
+
+ a #GDtlsConnection
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Sets the list of application-layer protocols to advertise that the
+caller is willing to speak on this connection. The
+Application-Layer Protocol Negotiation (ALPN) extension will be
+used to negotiate a compatible protocol with the peer; use
+g_dtls_connection_get_negotiated_protocol() to find the negotiated
+protocol after the handshake. Specifying %NULL for the the value
+of @protocols will disable ALPN negotiation.
+
+See [IANA TLS ALPN Protocol IDs](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids)
+for a list of registered protocol IDs.
+
+
+
+
+
+
+ a #GDtlsConnection
+
+
+
+ a %NULL-terminated
+ array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL
+
+
+
+
+
+
+
+ Shut down part or all of a DTLS connection.
+
+If @shutdown_read is %TRUE then the receiving side of the connection is shut
+down, and further reading is disallowed. Subsequent calls to
+g_datagram_based_receive_messages() will return %G_IO_ERROR_CLOSED.
+
+If @shutdown_write is %TRUE then the sending side of the connection is shut
+down, and further writing is disallowed. Subsequent calls to
+g_datagram_based_send_messages() will return %G_IO_ERROR_CLOSED.
+
+It is allowed for both @shutdown_read and @shutdown_write to be TRUE — this
+is equivalent to calling g_dtls_connection_close().
+
+If @cancellable is cancelled, the #GDtlsConnection may be left
+partially-closed and any pending untransmitted data may be lost. Call
+g_dtls_connection_shutdown() again to complete closing the #GDtlsConnection.
+
+
+ %TRUE on success, %FALSE otherwise
+
+
+
+
+ a #GDtlsConnection
+
+
+
+ %TRUE to stop reception of incoming datagrams
+
+
+
+ %TRUE to stop sending outgoing datagrams
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Asynchronously shut down part or all of the DTLS connection. See
+g_dtls_connection_shutdown() for more information.
+
+
+
+
+
+
+ a #GDtlsConnection
+
+
+
+ %TRUE to stop reception of incoming datagrams
+
+
+
+ %TRUE to stop sending outgoing datagrams
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call when the shutdown operation is complete
+
+
+
+ the data to pass to the callback function
+
+
+
+
+
+ Finish an asynchronous TLS shutdown operation. See
+g_dtls_connection_shutdown() for more information.
+
+
+ %TRUE on success, %FALSE on failure, in which
+case @error will be set
+
+
+
+
+ a #GDtlsConnection
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Close the DTLS connection. This is equivalent to calling
+g_dtls_connection_shutdown() to shut down both sides of the connection.
+
+Closing a #GDtlsConnection waits for all buffered but untransmitted data to
+be sent before it completes. It then sends a `close_notify` DTLS alert to the
+peer and may wait for a `close_notify` to be received from the peer. It does
+not close the underlying #GDtlsConnection:base-socket; that must be closed
+separately.
+
+Once @conn is closed, all other operations will return %G_IO_ERROR_CLOSED.
+Closing a #GDtlsConnection multiple times will not return an error.
+
+#GDtlsConnections will be automatically closed when the last reference is
+dropped, but you might want to call this function to make sure resources are
+released as early as possible.
+
+If @cancellable is cancelled, the #GDtlsConnection may be left
+partially-closed and any pending untransmitted data may be lost. Call
+g_dtls_connection_close() again to complete closing the #GDtlsConnection.
+
+
+ %TRUE on success, %FALSE otherwise
+
+
+
+
+ a #GDtlsConnection
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Asynchronously close the DTLS connection. See g_dtls_connection_close() for
+more information.
+
+
+
+
+
+
+ a #GDtlsConnection
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call when the close operation is complete
+
+
+
+ the data to pass to the callback function
+
+
+
+
+
+ Finish an asynchronous TLS close operation. See g_dtls_connection_close()
+for more information.
+
+
+ %TRUE on success, %FALSE on failure, in which
+case @error will be set
+
+
+
+
+ a #GDtlsConnection
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Used by #GDtlsConnection implementations to emit the
+#GDtlsConnection::accept-certificate signal.
+
+
+ %TRUE if one of the signal handlers has returned
+ %TRUE to accept @peer_cert
+
+
+
+
+ a #GDtlsConnection
+
+
+
+ the peer's #GTlsCertificate
+
+
+
+ the problems with @peer_cert
+
+
+
+
+
+ Gets @conn's certificate, as set by
+g_dtls_connection_set_certificate().
+
+
+ @conn's certificate, or %NULL
+
+
+
+
+ a #GDtlsConnection
+
+
+
+
+
+ Query the TLS backend for TLS channel binding data of @type for @conn.
+
+This call retrieves TLS channel binding data as specified in RFC
+[5056](https://tools.ietf.org/html/rfc5056), RFC
+[5929](https://tools.ietf.org/html/rfc5929), and related RFCs. The
+binding data is returned in @data. The @data is resized by the callee
+using #GByteArray buffer management and will be freed when the @data
+is destroyed by g_byte_array_unref(). If @data is %NULL, it will only
+check whether TLS backend is able to fetch the data (e.g. whether @type
+is supported by the TLS backend). It does not guarantee that the data
+will be available though. That could happen if TLS connection does not
+support @type or the binding data is not available yet due to additional
+negotiation or input required.
+
+
+ %TRUE on success, %FALSE otherwise
+
+
+
+
+ a #GDtlsConnection
+
+
+
+ #GTlsChannelBindingType type of data to fetch
+
+
+
+ #GByteArray is
+ filled with the binding data, or %NULL
+
+
+
+
+
+
+
+ Returns the name of the current DTLS ciphersuite, or %NULL if the
+connection has not handshaked or has been closed. Beware that the TLS
+backend may use any of multiple different naming conventions, because
+OpenSSL and GnuTLS have their own ciphersuite naming conventions that
+are different from each other and different from the standard, IANA-
+registered ciphersuite names. The ciphersuite name is intended to be
+displayed to the user for informative purposes only, and parsing it
+is not recommended.
+
+
+ The name of the current DTLS ciphersuite, or %NULL
+
+
+
+
+ a #GDTlsConnection
+
+
+
+
+
+ Gets the certificate database that @conn uses to verify
+peer certificates. See g_dtls_connection_set_database().
+
+
+ the certificate database that @conn uses or %NULL
+
+
+
+
+ a #GDtlsConnection
+
+
+
+
+
+ Get the object that will be used to interact with the user. It will be used
+for things like prompting the user for passwords. If %NULL is returned, then
+no user interaction will occur for this connection.
+
+
+ The interaction object.
+
+
+
+
+ a connection
+
+
+
+
+
+ Gets the name of the application-layer protocol negotiated during
+the handshake.
+
+If the peer did not use the ALPN extension, or did not advertise a
+protocol that matched one of @conn's protocols, or the TLS backend
+does not support ALPN, then this will be %NULL. See
+g_dtls_connection_set_advertised_protocols().
+
+
+ the negotiated protocol, or %NULL
+
+
+
+
+ a #GDtlsConnection
+
+
+
+
+
+ Gets @conn's peer's certificate after the handshake has completed
+or failed. (It is not set during the emission of
+#GDtlsConnection::accept-certificate.)
+
+
+ @conn's peer's certificate, or %NULL
+
+
+
+
+ a #GDtlsConnection
+
+
+
+
+
+ Gets the errors associated with validating @conn's peer's
+certificate, after the handshake has completed or failed. (It is
+not set during the emission of #GDtlsConnection::accept-certificate.)
+
+
+ @conn's peer's certificate errors
+
+
+
+
+ a #GDtlsConnection
+
+
+
+
+
+ Returns the current DTLS protocol version, which may be
+%G_TLS_PROTOCOL_VERSION_UNKNOWN if the connection has not handshaked, or
+has been closed, or if the TLS backend has implemented a protocol version
+that is not a recognized #GTlsProtocolVersion.
+
+
+ The current DTLS protocol version
+
+
+
+
+ a #GDTlsConnection
+
+
+
+
+
+ Gets @conn rehandshaking mode. See
+g_dtls_connection_set_rehandshake_mode() for details.
+ Changing the rehandshake mode is no longer
+ required for compatibility. Also, rehandshaking has been removed
+ from the TLS protocol in TLS 1.3.
+
+
+ %G_TLS_REHANDSHAKE_SAFELY
+
+
+
+
+ a #GDtlsConnection
+
+
+
+
+
+ Tests whether or not @conn expects a proper TLS close notification
+when the connection is closed. See
+g_dtls_connection_set_require_close_notify() for details.
+
+
+ %TRUE if @conn requires a proper TLS close notification.
+
+
+
+
+ a #GDtlsConnection
+
+
+
+
+
+ Attempts a TLS handshake on @conn.
+
+On the client side, it is never necessary to call this method;
+although the connection needs to perform a handshake after
+connecting, #GDtlsConnection will handle this for you automatically
+when you try to send or receive data on the connection. You can call
+g_dtls_connection_handshake() manually if you want to know whether
+the initial handshake succeeded or failed (as opposed to just
+immediately trying to use @conn to read or write, in which case,
+if it fails, it may not be possible to tell if it failed before
+or after completing the handshake), but beware that servers may reject
+client authentication after the handshake has completed, so a
+successful handshake does not indicate the connection will be usable.
+
+Likewise, on the server side, although a handshake is necessary at
+the beginning of the communication, you do not need to call this
+function explicitly unless you want clearer error reporting.
+
+Previously, calling g_dtls_connection_handshake() after the initial
+handshake would trigger a rehandshake; however, this usage was
+deprecated in GLib 2.60 because rehandshaking was removed from the
+TLS protocol in TLS 1.3. Since GLib 2.64, calling this function after
+the initial handshake will no longer do anything.
+
+#GDtlsConnection::accept_certificate may be emitted during the
+handshake.
+
+
+ success or failure
+
+
+
+
+ a #GDtlsConnection
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Asynchronously performs a TLS handshake on @conn. See
+g_dtls_connection_handshake() for more information.
+
+
+
+
+
+
+ a #GDtlsConnection
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call when the handshake is complete
+
+
+
+ the data to pass to the callback function
+
+
+
+
+
+ Finish an asynchronous TLS handshake operation. See
+g_dtls_connection_handshake() for more information.
+
+
+ %TRUE on success, %FALSE on failure, in which
+case @error will be set.
+
+
+
+
+ a #GDtlsConnection
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Sets the list of application-layer protocols to advertise that the
+caller is willing to speak on this connection. The
+Application-Layer Protocol Negotiation (ALPN) extension will be
+used to negotiate a compatible protocol with the peer; use
+g_dtls_connection_get_negotiated_protocol() to find the negotiated
+protocol after the handshake. Specifying %NULL for the the value
+of @protocols will disable ALPN negotiation.
+
+See [IANA TLS ALPN Protocol IDs](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids)
+for a list of registered protocol IDs.
+
+
+
+
+
+
+ a #GDtlsConnection
+
+
+
+ a %NULL-terminated
+ array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL
+
+
+
+
+
+
+
+ This sets the certificate that @conn will present to its peer
+during the TLS handshake. For a #GDtlsServerConnection, it is
+mandatory to set this, and that will normally be done at construct
+time.
+
+For a #GDtlsClientConnection, this is optional. If a handshake fails
+with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server
+requires a certificate, and if you try connecting again, you should
+call this method first. You can call
+g_dtls_client_connection_get_accepted_cas() on the failed connection
+to get a list of Certificate Authorities that the server will
+accept certificates from.
+
+(It is also possible that a server will allow the connection with
+or without a certificate; in that case, if you don't provide a
+certificate, you can tell that the server requested one by the fact
+that g_dtls_client_connection_get_accepted_cas() will return
+non-%NULL.)
+
+
+
+
+
+
+ a #GDtlsConnection
+
+
+
+ the certificate to use for @conn
+
+
+
+
+
+ Sets the certificate database that is used to verify peer certificates.
+This is set to the default database by default. See
+g_tls_backend_get_default_database(). If set to %NULL, then
+peer certificate validation will always set the
+%G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
+#GDtlsConnection::accept-certificate will always be emitted on
+client-side connections, unless that bit is not set in
+#GDtlsClientConnection:validation-flags).
+
+There are nonintuitive security implications when using a non-default
+database. See #GDtlsConnection:database for details.
+
+
+
+
+
+
+ a #GDtlsConnection
+
+
+
+ a #GTlsDatabase
+
+
+
+
+
+ Set the object that will be used to interact with the user. It will be used
+for things like prompting the user for passwords.
+
+The @interaction argument will normally be a derived subclass of
+#GTlsInteraction. %NULL can also be provided if no user interaction
+should occur for this connection.
+
+
+
+
+
+
+ a connection
+
+
+
+ an interaction object, or %NULL
+
+
+
+
+
+ Since GLib 2.64, changing the rehandshake mode is no longer supported
+and will have no effect. With TLS 1.3, rehandshaking has been removed from
+the TLS protocol, replaced by separate post-handshake authentication and
+rekey operations.
+ Changing the rehandshake mode is no longer
+ required for compatibility. Also, rehandshaking has been removed
+ from the TLS protocol in TLS 1.3.
+
+
+
+
+
+
+ a #GDtlsConnection
+
+
+
+ the rehandshaking mode
+
+
+
+
+
+ Sets whether or not @conn expects a proper TLS close notification
+before the connection is closed. If this is %TRUE (the default),
+then @conn will expect to receive a TLS close notification from its
+peer before the connection is closed, and will return a
+%G_TLS_ERROR_EOF error if the connection is closed without proper
+notification (since this may indicate a network error, or
+man-in-the-middle attack).
+
+In some protocols, the application will know whether or not the
+connection was closed cleanly based on application-level data
+(because the application-level data includes a length field, or is
+somehow self-delimiting); in this case, the close notify is
+redundant and may be omitted. You
+can use g_dtls_connection_set_require_close_notify() to tell @conn
+to allow an "unannounced" connection close, in which case the close
+will show up as a 0-length read, as in a non-TLS
+#GDatagramBased, and it is up to the application to check that
+the data has been fully received.
+
+Note that this only affects the behavior when the peer closes the
+connection; when the application calls g_dtls_connection_close_async() on
+@conn itself, this will send a close notification regardless of the
+setting of this property. If you explicitly want to do an unclean
+close, you can close @conn's #GDtlsConnection:base-socket rather
+than closing @conn itself.
+
+
+
+
+
+
+ a #GDtlsConnection
+
+
+
+ whether or not to require close notification
+
+
+
+
+
+ Shut down part or all of a DTLS connection.
+
+If @shutdown_read is %TRUE then the receiving side of the connection is shut
+down, and further reading is disallowed. Subsequent calls to
+g_datagram_based_receive_messages() will return %G_IO_ERROR_CLOSED.
+
+If @shutdown_write is %TRUE then the sending side of the connection is shut
+down, and further writing is disallowed. Subsequent calls to
+g_datagram_based_send_messages() will return %G_IO_ERROR_CLOSED.
+
+It is allowed for both @shutdown_read and @shutdown_write to be TRUE — this
+is equivalent to calling g_dtls_connection_close().
+
+If @cancellable is cancelled, the #GDtlsConnection may be left
+partially-closed and any pending untransmitted data may be lost. Call
+g_dtls_connection_shutdown() again to complete closing the #GDtlsConnection.
+
+
+ %TRUE on success, %FALSE otherwise
+
+
+
+
+ a #GDtlsConnection
+
+
+
+ %TRUE to stop reception of incoming datagrams
+
+
+
+ %TRUE to stop sending outgoing datagrams
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Asynchronously shut down part or all of the DTLS connection. See
+g_dtls_connection_shutdown() for more information.
+
+
+
+
+
+
+ a #GDtlsConnection
+
+
+
+ %TRUE to stop reception of incoming datagrams
+
+
+
+ %TRUE to stop sending outgoing datagrams
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call when the shutdown operation is complete
+
+
+
+ the data to pass to the callback function
+
+
+
+
+
+ Finish an asynchronous TLS shutdown operation. See
+g_dtls_connection_shutdown() for more information.
+
+
+ %TRUE on success, %FALSE on failure, in which
+case @error will be set
+
+
+
+
+ a #GDtlsConnection
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ The list of application-layer protocols that the connection
+advertises that it is willing to speak. See
+g_dtls_connection_set_advertised_protocols().
+
+
+
+
+
+ The #GDatagramBased that the connection wraps. Note that this may be any
+implementation of #GDatagramBased, not just a #GSocket.
+
+
+
+ The connection's certificate; see
+g_dtls_connection_set_certificate().
+
+
+
+ The name of the DTLS ciphersuite in use. See g_dtls_connection_get_ciphersuite_name().
+
+
+
+ The certificate database to use when verifying this TLS connection.
+If no certificate database is set, then the default database will be
+used. See g_tls_backend_get_default_database().
+
+When using a non-default database, #GDtlsConnection must fall back to using
+the #GTlsDatabase to perform certificate verification using
+g_tls_database_verify_chain(), which means certificate verification will
+not be able to make use of TLS session context. This may be less secure.
+For example, if you create your own #GTlsDatabase that just wraps the
+default #GTlsDatabase, you might expect that you have not changed anything,
+but this is not true because you may have altered the behavior of
+#GDtlsConnection by causing it to use g_tls_database_verify_chain(). See the
+documentation of g_tls_database_verify_chain() for more details on specific
+security checks that may not be performed. Accordingly, setting a
+non-default database is discouraged except for specialty applications with
+unusual security requirements.
+
+
+
+ A #GTlsInteraction object to be used when the connection or certificate
+database need to interact with the user. This will be used to prompt the
+user for passwords where necessary.
+
+
+
+ The application-layer protocol negotiated during the TLS
+handshake. See g_dtls_connection_get_negotiated_protocol().
+
+
+
+ The connection's peer's certificate, after the TLS handshake has
+completed or failed. Note in particular that this is not yet set
+during the emission of #GDtlsConnection::accept-certificate.
+
+(You can watch for a #GObject::notify signal on this property to
+detect when a handshake has occurred.)
+
+
+
+ The errors noticed while verifying
+#GDtlsConnection:peer-certificate. Normally this should be 0, but
+it may not be if #GDtlsClientConnection:validation-flags is not
+%G_TLS_CERTIFICATE_VALIDATE_ALL, or if
+#GDtlsConnection::accept-certificate overrode the default
+behavior.
+
+GLib guarantees that if certificate verification fails, at least
+one error will be set, but it does not guarantee that all possible
+errors will be set. Accordingly, you may not safely decide to
+ignore any particular type of error. For example, it would be
+incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow
+expired certificates, because this could potentially be the only
+error flag set even if other problems exist with the certificate.
+
+
+
+ The DTLS protocol version in use. See g_dtls_connection_get_protocol_version().
+
+
+
+ The rehandshaking mode. See
+g_dtls_connection_set_rehandshake_mode().
+ The rehandshake mode is ignored.
+
+
+
+ Whether or not proper TLS close notification is required.
+See g_dtls_connection_set_require_close_notify().
+
+
+
+ Emitted during the TLS handshake after the peer certificate has
+been received. You can examine @peer_cert's certification path by
+calling g_tls_certificate_get_issuer() on it.
+
+For a client-side connection, @peer_cert is the server's
+certificate, and the signal will only be emitted if the
+certificate was not acceptable according to @conn's
+#GDtlsClientConnection:validation_flags. If you would like the
+certificate to be accepted despite @errors, return %TRUE from the
+signal handler. Otherwise, if no handler accepts the certificate,
+the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE.
+
+GLib guarantees that if certificate verification fails, this signal
+will be emitted with at least one error will be set in @errors, but
+it does not guarantee that all possible errors will be set.
+Accordingly, you may not safely decide to ignore any particular
+type of error. For example, it would be incorrect to ignore
+%G_TLS_CERTIFICATE_EXPIRED if you want to allow expired
+certificates, because this could potentially be the only error flag
+set even if other problems exist with the certificate.
+
+For a server-side connection, @peer_cert is the certificate
+presented by the client, if this was requested via the server's
+#GDtlsServerConnection:authentication_mode. On the server side,
+the signal is always emitted when the client presents a
+certificate, and the certificate will only be accepted if a
+handler returns %TRUE.
+
+Note that if this signal is emitted as part of asynchronous I/O
+in the main thread, then you should not attempt to interact with
+the user before returning from the signal handler. If you want to
+let the user decide whether or not to accept the certificate, you
+would have to return %FALSE from the signal handler on the first
+attempt, and then after the connection attempt returns a
+%G_TLS_ERROR_BAD_CERTIFICATE, you can interact with the user, and
+if the user decides to accept the certificate, remember that fact,
+create a new connection, and return %TRUE from the signal handler
+the next time.
+
+If you are doing I/O in another thread, you do not
+need to worry about this, and can simply block in the signal
+handler until the UI thread returns an answer.
+
+ %TRUE to accept @peer_cert (which will also
+immediately end the signal emission). %FALSE to allow the signal
+emission to continue, which will cause the handshake to fail if
+no one else overrides it.
+
+
+
+
+ the peer's #GTlsCertificate
+
+
+
+ the problems with @peer_cert.
+
+
+
+
+
+
+ Virtual method table for a #GDtlsConnection implementation.
+
+
+ The parent interface.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ success or failure
+
+
+
+
+ a #GDtlsConnection
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GDtlsConnection
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call when the handshake is complete
+
+
+
+ the data to pass to the callback function
+
+
+
+
+
+
+
+
+
+ %TRUE on success, %FALSE on failure, in which
+case @error will be set.
+
+
+
+
+ a #GDtlsConnection
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+ %TRUE on success, %FALSE otherwise
+
+
+
+
+ a #GDtlsConnection
+
+
+
+ %TRUE to stop reception of incoming datagrams
+
+
+
+ %TRUE to stop sending outgoing datagrams
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GDtlsConnection
+
+
+
+ %TRUE to stop reception of incoming datagrams
+
+
+
+ %TRUE to stop sending outgoing datagrams
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call when the shutdown operation is complete
+
+
+
+ the data to pass to the callback function
+
+
+
+
+
+
+
+
+
+ %TRUE on success, %FALSE on failure, in which
+case @error will be set
+
+
+
+
+ a #GDtlsConnection
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GDtlsConnection
+
+
+
+ a %NULL-terminated
+ array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL
+
+
+
+
+
+
+
+
+
+
+
+ the negotiated protocol, or %NULL
+
+
+
+
+ a #GDtlsConnection
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #GDtlsServerConnection is the server-side subclass of #GDtlsConnection,
+representing a server-side DTLS connection.
+
+
+
+
+ Creates a new #GDtlsServerConnection wrapping @base_socket.
+
+
+ the new
+ #GDtlsServerConnection, or %NULL on error
+
+
+
+
+ the #GDatagramBased to wrap
+
+
+
+ the default server certificate, or %NULL
+
+
+
+
+
+ The #GTlsAuthenticationMode for the server. This can be changed
+before calling g_dtls_connection_handshake() if you want to
+rehandshake with a different mode from the initial handshake.
+
+
+
+
+ vtable for a #GDtlsServerConnection implementation.
+
+
+ The parent interface.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #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.
+
+
+
+ Creates a new emblem for @icon.
+
+
+ a new #GEmblem.
+
+
+
+
+ a GIcon containing the icon.
+
+
+
+
+
+ Creates a new emblem for @icon.
+
+
+ a new #GEmblem.
+
+
+
+
+ a GIcon containing the icon.
+
+
+
+ a GEmblemOrigin enum defining the emblem's origin
+
+
+
+
+
+ Gives back the icon from @emblem.
+
+
+ a #GIcon. The returned object belongs to
+ the emblem and should not be modified or freed.
+
+
+
+
+ a #GEmblem from which the icon should be extracted.
+
+
+
+
+
+ Gets the origin of the emblem.
+
+
+ the origin of the emblem
+
+
+
+
+ a #GEmblem
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ GEmblemOrigin is used to add information about the origin of the emblem
+to #GEmblem.
+
+ Emblem of unknown origin
+
+
+ Emblem adds device-specific information
+
+
+ Emblem depicts live metadata, such as "readonly"
+
+
+ Emblem comes from a user-defined tag, e.g. set by nautilus (in the future)
+
+
+
+ #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.
+
+
+
+ Creates a new emblemed icon for @icon with the emblem @emblem.
+
+
+ a new #GIcon
+
+
+
+
+ a #GIcon
+
+
+
+ a #GEmblem, or %NULL
+
+
+
+
+
+ Adds @emblem to the #GList of #GEmblems.
+
+
+
+
+
+
+ a #GEmblemedIcon
+
+
+
+ a #GEmblem
+
+
+
+
+
+ Removes all the emblems from @icon.
+
+
+
+
+
+
+ a #GEmblemedIcon
+
+
+
+
+
+ Gets the list of emblems for the @icon.
+
+
+ a #GList of
+ #GEmblems that is owned by @emblemed
+
+
+
+
+
+
+ a #GEmblemedIcon
+
+
+
+
+
+ Gets the main icon for @emblemed.
+
+
+ a #GIcon that is owned by @emblemed
+
+
+
+
+ a #GEmblemedIcon
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+
+
+
+ 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.
+
+
+
+
+ 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.
+
+
+
+
+ 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.
+
+
+
+
+ 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.
+
+
+
+
+ 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.
+
+
+
+
+ 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.
+
+
+
+
+ A key in the "dos" namespace for checking if the file is a NTFS mount point
+(a volume mount or a junction point).
+
+This attribute is %TRUE if file is a reparse point of type
+[IO_REPARSE_TAG_MOUNT_POINT](https://msdn.microsoft.com/en-us/library/dd541667.aspx).
+
+This attribute is only available for DOS file systems.
+
+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.
+
+
+
+
+ A key in the "dos" namespace for getting the file NTFS reparse tag.
+
+This value is 0 for files that are not reparse points.
+
+See the [Reparse Tags](https://msdn.microsoft.com/en-us/library/dd541667.aspx)
+page for possible reparse tag values.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+
+
+
+
+ A key in the "etag" namespace for getting the value of the file's
+entity tag.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+
+
+
+
+ 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.
+
+
+
+
+ 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.
+
+
+
+
+ A key in the "filesystem" namespace for checking if the file system
+is remote.
+
+Is set to %TRUE if the file system is remote.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+
+
+
+
+ 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.
+
+
+
+
+ A key in the "filesystem" namespace for getting the file system's type.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+
+
+
+
+ A key in the "filesystem" namespace for getting the number of bytes
+used by data on the file system.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
+
+
+
+
+ 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.
+
+
+
+
+ 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 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.
+
+
+
+
+ A key in the "id" namespace for getting the file system identifier.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+
+An example use would be during drag and drop to see if the source
+and target are on the same filesystem (default to move) or not (default
+to copy).
+
+
+
+
+ A key in the "mountable" namespace for checking if a file (of
+type G_FILE_TYPE_MOUNTABLE) can be ejected.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+
+
+
+
+ A 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.
+
+
+
+
+ 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 "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 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 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 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.
+
+
+
+
+ A key in the "mountable" namespace for getting the HAL UDI for the mountable
+file.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+
+
+
+
+ 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 key in the "mountable" namespace for getting the #GDriveStartStopType.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+
+
+
+
+ A key in the "mountable" namespace for getting the unix device.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+
+
+
+
+ A key in the "mountable" namespace for getting the unix device file.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+
+
+
+
+ A key in the "owner" namespace for getting the file owner's group.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+
+
+
+
+ A key in the "owner" namespace for getting the user name of the
+file's owner.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+
+
+
+
+ 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 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.
+
+
+
+
+ A key in the "recent" namespace for getting time, when the metadata for the
+file in `recent:///` was last changed.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_INT64.
+
+
+
+
+ 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.
+
+
+
+
+ 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.
+
+
+
+
+ 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 "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 "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 further 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 "standard" namespace for getting the display name of the file.
+
+A display name is guaranteed to be in UTF-8 and can thus be displayed in
+the UI. It is guaranteed to be set on every file.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+
+
+
+
+ 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 "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 "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 "standard" namespace for checking if a file is a backup file.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+
+
+
+
+ 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 "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.
+
+On Windows NTFS mountpoints are considered to be symlinks as well.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+
+
+
+
+ A key in the "standard" namespace for checking if a file is virtual.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+
+
+
+
+ A key in the "standard" namespace for checking if a file is
+volatile. This is meant for opaque, non-POSIX-like backends to
+indicate that the URI is not persistent. Applications should look
+at %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET for the persistent URI.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+
+
+
+
+ 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. It is guaranteed to be set on
+every file.
+
+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 "standard" namespace for getting the file's size (in bytes).
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
+
+
+
+
+ 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 "standard" namespace for getting the symbolic 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 "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 "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.
+
+
+
+
+ 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 "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 "thumbnail" namespace for checking if thumbnailing failed
+for the large image.
+
+This attribute is %TRUE if thumbnailing failed.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+
+
+
+
+ A key in the "thumbnail" namespace for checking if thumbnailing failed
+for the normal image.
+
+This attribute is %TRUE if thumbnailing failed.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+
+
+
+
+ A key in the "thumbnail" namespace for checking if thumbnailing failed
+for the x-large image.
+
+This attribute is %TRUE if thumbnailing failed.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+
+
+
+
+ A key in the "thumbnail" namespace for checking if thumbnailing failed
+for the xx-large image.
+
+This attribute is %TRUE if thumbnailing failed.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+
+
+
+
+ A key in the "thumbnail" namespace for checking whether the thumbnail is outdated.
+
+This attribute is %TRUE if the thumbnail is up-to-date with the file it represents,
+and %FALSE if the file has been modified since the thumbnail was generated.
+
+If %G_FILE_ATTRIBUTE_THUMBNAILING_FAILED is %TRUE and this attribute is %FALSE,
+it indicates that thumbnailing may be attempted again and may succeed.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+
+
+
+
+ A key in the "thumbnail" namespace for checking whether the large
+thumbnail is outdated.
+
+This attribute is %TRUE if the large thumbnail is up-to-date with the file
+it represents, and %FALSE if the file has been modified since the thumbnail
+was generated.
+
+If %G_FILE_ATTRIBUTE_THUMBNAILING_FAILED_LARGE is %TRUE and this attribute
+is %FALSE, it indicates that thumbnailing may be attempted again and may
+succeed.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+
+
+
+
+ A key in the "thumbnail" namespace for checking whether the normal
+thumbnail is outdated.
+
+This attribute is %TRUE if the normal thumbnail is up-to-date with the file
+it represents, and %FALSE if the file has been modified since the thumbnail
+was generated.
+
+If %G_FILE_ATTRIBUTE_THUMBNAILING_FAILED_NORMAL is %TRUE and this attribute
+is %FALSE, it indicates that thumbnailing may be attempted again and may
+succeed.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+
+
+
+
+ A key in the "thumbnail" namespace for checking whether the x-large
+thumbnail is outdated.
+
+This attribute is %TRUE if the x-large thumbnail is up-to-date with the file
+it represents, and %FALSE if the file has been modified since the thumbnail
+was generated.
+
+If %G_FILE_ATTRIBUTE_THUMBNAILING_FAILED_XLARGE is %TRUE and this attribute
+is %FALSE, it indicates that thumbnailing may be attempted again and may
+succeed.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+
+
+
+
+ A key in the "thumbnail" namespace for checking whether the xx-large
+thumbnail is outdated.
+
+This attribute is %TRUE if the x-large thumbnail is up-to-date with the file
+it represents, and %FALSE if the file has been modified since the thumbnail
+was generated.
+
+If %G_FILE_ATTRIBUTE_THUMBNAILING_FAILED_XXLARGE is %TRUE and this attribute
+is %FALSE, it indicates that thumbnailing may be attempted again and may
+succeed.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+
+
+
+
+ A key in the "thumbnail" namespace for getting the path to the thumbnail
+image with the biggest size available.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.
+
+
+
+
+ A key in the "thumbnail" namespace for getting the path to the large
+thumbnail image.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.
+
+
+
+
+ A key in the "thumbnail" namespace for getting the path to the normal
+thumbnail image.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.
+
+
+
+
+ A key in the "thumbnail" namespace for getting the path to the x-large
+thumbnail image.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.
+
+
+
+
+ A key in the "thumbnail" namespace for getting the path to the xx-large
+thumbnail image.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.
+
+
+
+
+ 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 time since the file was last accessed, in seconds since the
+UNIX epoch.
+
+
+
+
+ A key in the "time" namespace for getting the nanoseconds 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.
+
+
+
+
+ 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.
+
+
+
+
+ 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 time since the file was last changed, in seconds since
+the UNIX epoch.
+
+This corresponds to the traditional UNIX ctime.
+
+
+
+
+ A key in the "time" namespace for getting the nanoseconds 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 "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 "time" namespace for getting the time the file was created.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64,
+and contains the time since the file was created, in seconds since the UNIX
+epoch.
+
+This may correspond to Linux `stx_btime`, FreeBSD `st_birthtim`, NetBSD
+`st_birthtime` or NTFS `ctime`.
+
+
+
+
+ A key in the "time" namespace for getting the nanoseconds 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 "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 "time" namespace for getting the time the file was last
+modified.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, and
+contains the time since the file was modified, in seconds since the UNIX
+epoch.
+
+
+
+
+ A key in the "time" namespace for getting the nanoseconds 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 "time" namespace for getting the microseconds 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 "trash" namespace for getting the deletion date and time
+of a file inside the `trash:///` folder.
+
+The format of the returned string is `YYYY-MM-DDThh:mm:ss`.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+
+
+
+
+ A key in the "trash" namespace for getting the number of (toplevel) items
+that are present in the `trash:///` folder.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+
+
+
+
+ A key in the "trash" namespace for getting the original path of a file
+inside the `trash:///` folder before it was trashed.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.
+
+
+
+
+ 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 "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 "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 "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 "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 "unix" namespace for checking if the file represents a
+UNIX mount point.
+
+This attribute is %TRUE if the file is a UNIX mount point.
+
+Since 2.58, `/` is considered to be a mount point.
+
+This attribute is only available for UNIX file systems.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+
+
+
+
+ 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 the documentation for `lstat()`: this attribute is equivalent to
+the `st_mode` member of `struct stat`, and includes both the file type
+and permissions.
+
+This attribute is only available for UNIX file systems.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+
+
+
+
+ A key in the "unix" namespace for getting the number of hard links
+for a file.
+
+See the documentation for `lstat()`.
+
+This attribute is only available for UNIX file systems.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+
+
+
+
+ A key in the "unix" namespace for getting the device ID for the file
+(if it is a special file).
+
+See the documentation for `lstat()`.
+
+This attribute is only available for UNIX file systems.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+
+
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #GFile is a high level abstraction for manipulating files on a
+virtual file system. #GFiles are lightweight, immutable objects
+that do no I/O upon creation. It is necessary to understand that
+#GFile objects do not represent files, merely an identifier for a
+file. All file content I/O is implemented as streaming operations
+(see #GInputStream and #GOutputStream).
+
+To construct a #GFile, you can use:
+- g_file_new_for_path() if you have a path.
+- g_file_new_for_uri() if you have a URI.
+- g_file_new_for_commandline_arg() for a command line argument.
+- g_file_new_tmp() to create a temporary file from a template.
+- g_file_new_tmp_async() to asynchronously create a temporary file.
+- g_file_new_tmp_dir_async() to asynchronously create a temporary directory.
+- g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name().
+- g_file_new_build_filename() to create a file from path elements.
+
+One way to think of a #GFile is as an abstraction of a pathname. For
+normal files the system pathname is what is stored internally, but as
+#GFiles are extensible it could also be something else that corresponds
+to a pathname in a userspace implementation of a filesystem.
+
+#GFiles make up hierarchies of directories and files that correspond to
+the files on a filesystem. You can move through the file system with
+#GFile using g_file_get_parent() to get an identifier for the parent
+directory, g_file_get_child() to get a child within a directory,
+g_file_resolve_relative_path() to resolve a relative path between two
+#GFiles. There can be multiple hierarchies, so you may not end up at
+the same root if you repeatedly call g_file_get_parent() on two different
+files.
+
+All #GFiles have a basename (get with g_file_get_basename()). These names
+are byte strings that are used to identify the file on the filesystem
+(relative to its parent directory) and there is no guarantees that they
+have any particular charset encoding or even make any sense at all. If
+you want to use filenames in a user interface you should use the display
+name that you can get by requesting the
+%G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info().
+This is guaranteed to be in UTF-8 and can be used in a user interface.
+But always store the real basename or the #GFile to use to actually
+access the file, because there is no way to go from a display name to
+the actual name.
+
+Using #GFile as an identifier has the same weaknesses as using a path
+in that there may be multiple aliases for the same file. For instance,
+hard or soft links may cause two different #GFiles to refer to the same
+file. Other possible causes for aliases are: case insensitive filesystems,
+short and long names on FAT/NTFS, or bind mounts in Linux. If you want to
+check if two #GFiles point to the same file you can query for the
+%G_FILE_ATTRIBUTE_ID_FILE attribute. Note that #GFile does some trivial
+canonicalization of pathnames passed in, so that trivial differences in
+the path string used at creation (duplicated slashes, slash at end of
+path, "." or ".." path segments, etc) does not create different #GFiles.
+
+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.
+
+It is highly recommended to use asynchronous calls when running within a
+shared main loop, such as in the main thread of an application. This avoids
+I/O operations blocking other sources on the main loop from being dispatched.
+Synchronous I/O operations should be performed from worker threads. See the
+[introduction to asynchronous programming section][async-programming] for
+more.
+
+Some #GFile operations almost always take a noticeable amount of time, and
+so do not have synchronous analogs. Notable cases include:
+- g_file_mount_mountable() to mount a mountable file.
+- g_file_unmount_mountable_with_operation() to unmount a mountable file.
+- g_file_eject_mountable_with_operation() to eject a mountable file.
+
+## Entity Tags # {#gfile-etag}
+
+One notable feature of #GFiles are entity tags, or "etags" for
+short. Entity tags are somewhat like a more abstract version of the
+traditional mtime, and can be used to quickly determine if the file
+has been modified from the version on the file system. See the
+HTTP 1.1
+[specification](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)
+for HTTP Etag headers, which are a very similar concept.
+
+
+ Constructs a #GFile from a series of elements using the correct
+separator for filenames.
+
+Using this function is equivalent to calling g_build_filename(),
+followed by g_file_new_for_path() on the result.
+
+
+ a new #GFile
+
+
+
+
+ the first element in the path
+
+
+
+ remaining elements in path, terminated by %NULL
+
+
+
+
+
+ Creates a #GFile with the given argument from the command line.
+The value of @arg can be either a URI, an absolute path or a
+relative path resolved relative to the current working directory.
+This operation never fails, but the returned object might not
+support any I/O operation if @arg points to a malformed path.
+
+Note that on Windows, this function expects its argument to be in
+UTF-8 -- not the system code page. This means that you
+should not use this function with string from argv as it is passed
+to main(). g_win32_get_command_line() will return a UTF-8 version of
+the commandline. #GApplication also uses UTF-8 but
+g_application_command_line_create_file_for_arg() may be more useful
+for you there. It is also always possible to use this function with
+#GOptionContext arguments of type %G_OPTION_ARG_FILENAME.
+
+
+ a new #GFile.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a command line string
+
+
+
+
+
+ Creates a #GFile with the given argument from the command line.
+
+This function is similar to g_file_new_for_commandline_arg() except
+that it allows for passing the current working directory as an
+argument instead of using the current working directory of the
+process.
+
+This is useful if the commandline argument was given in a context
+other than the invocation of the current process.
+
+See also g_application_command_line_create_file_for_arg().
+
+
+ a new #GFile
+
+
+
+
+ a command line string
+
+
+
+ the current working directory of the commandline
+
+
+
+
+
+ Constructs a #GFile for a given path. This operation never
+fails, but the returned object might not support any I/O
+operation if @path is malformed.
+
+
+ a new #GFile for the given @path.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a string containing a relative or absolute path.
+ The string must be encoded in the glib filename encoding.
+
+
+
+
+
+ Constructs a #GFile for a given URI. This operation never
+fails, but the returned object might not support any I/O
+operation if @uri is malformed or if the uri type is
+not supported.
+
+
+ a new #GFile for the given @uri.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a UTF-8 string containing a URI
+
+
+
+
+
+ Opens a file in the preferred directory for temporary files (as
+returned by g_get_tmp_dir()) and returns a #GFile and
+#GFileIOStream pointing to it.
+
+@tmpl should be a string in the GLib file name encoding
+containing a sequence of six 'X' characters, and containing no
+directory components. If it is %NULL, a default template is used.
+
+Unlike the other #GFile constructors, this will return %NULL if
+a temporary file could not be created.
+
+
+ a new #GFile.
+ Free the returned object with g_object_unref().
+
+
+
+
+ Template for the file
+ name, as in g_file_open_tmp(), or %NULL for a default template
+
+
+
+ on return, a #GFileIOStream for the created file
+
+
+
+
+
+ Asynchronously opens a file in the preferred directory for temporary files
+ (as returned by g_get_tmp_dir()) as g_file_new_tmp().
+
+@tmpl should be a string in the GLib file name encoding
+containing a sequence of six 'X' characters, and containing no
+directory components. If it is %NULL, a default template is used.
+
+
+
+
+
+
+ Template for the file
+ name, as in g_file_open_tmp(), or %NULL for a default template
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call when the request is done
+
+
+
+ data to pass to @callback
+
+
+
+
+
+ Asynchronously creates a directory in the preferred directory for
+temporary files (as returned by g_get_tmp_dir()) as g_dir_make_tmp().
+
+@tmpl should be a string in the GLib file name encoding
+containing a sequence of six 'X' characters, and containing no
+directory components. If it is %NULL, a default template is used.
+
+
+
+
+
+
+ Template for the file
+ name, as in g_dir_make_tmp(), or %NULL for a default template
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call when the request is done
+
+
+
+ data to pass to @callback
+
+
+
+
+
+ Finishes a temporary directory creation started by
+g_file_new_tmp_dir_async().
+
+
+ a new #GFile.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Finishes a temporary file creation started by g_file_new_tmp_async().
+
+
+ a new #GFile.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GAsyncResult
+
+
+
+ on return, a #GFileIOStream for the created file
+
+
+
+
+
+ Constructs a #GFile with the given @parse_name (i.e. something
+given by g_file_get_parse_name()). This operation never fails,
+but the returned object might not support any I/O operation if
+the @parse_name cannot be parsed.
+
+
+ a new #GFile.
+
+
+
+
+ a file name or path to be parsed
+
+
+
+
+
+ Gets an output stream for appending data to the file.
+If the file doesn't already exist it is created.
+
+By default files created are generally readable by everyone,
+but if you pass %G_FILE_CREATE_PRIVATE in @flags the file
+will be made readable only to the current user, to the level that
+is supported on the target filesystem.
+
+If @cancellable is not %NULL, then the operation can be cancelled
+by triggering the cancellable object from another thread. If the
+operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
+returned.
+
+Some file systems don't allow all file names, and may return an
+%G_IO_ERROR_INVALID_FILENAME error. If the file is a directory the
+%G_IO_ERROR_IS_DIRECTORY error will be returned. Other errors are
+possible too, and depend on what kind of filesystem the file is on.
+
+
+ a #GFileOutputStream, or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Asynchronously opens @file for appending.
+
+For more details, see g_file_append_to() which is
+the synchronous version of this call.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_append_to_finish() to get the result
+of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous file append operation started with
+g_file_append_to_async().
+
+
+ a valid #GFileOutputStream
+ or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ #GAsyncResult
+
+
+
+
+
+ Copies the file @source to the location specified by @destination.
+Can not handle recursive copies of directories.
+
+If the flag %G_FILE_COPY_OVERWRITE is specified an already
+existing @destination file is overwritten.
+
+If the flag %G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks
+will be copied as symlinks, otherwise the target of the
+@source symlink will be copied.
+
+If the flag %G_FILE_COPY_ALL_METADATA is specified then all the metadata
+that is possible to copy is copied, not just the default subset (which,
+for instance, does not include the owner, see #GFileInfo).
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+If @progress_callback is not %NULL, then the operation can be monitored
+by setting this to a #GFileProgressCallback function.
+@progress_callback_data will be passed to this function. It is guaranteed
+that this callback will be called after all data has been transferred with
+the total number of bytes copied during the operation.
+
+If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND error
+is returned, independent on the status of the @destination.
+
+If %G_FILE_COPY_OVERWRITE is not specified and the target exists, then
+the error %G_IO_ERROR_EXISTS is returned.
+
+If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY
+error is returned. If trying to overwrite a directory with a directory the
+%G_IO_ERROR_WOULD_MERGE error is returned.
+
+If the source is a directory and the target does not exist, or
+%G_FILE_COPY_OVERWRITE is specified and the target is a file, then the
+%G_IO_ERROR_WOULD_RECURSE error is returned.
+
+If you are interested in copying the #GFile object itself (not the on-disk
+file), see g_file_dup().
+
+
+ %TRUE on success, %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ destination #GFile
+
+
+
+ set of #GFileCopyFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ function to callback with
+ progress information, or %NULL if progress information is not needed
+
+
+
+ user data to pass to @progress_callback
+
+
+
+
+
+ Copies the file @source to the location specified by @destination
+asynchronously. For details of the behaviour, see g_file_copy().
+
+If @progress_callback is not %NULL, then that function that will be called
+just like in g_file_copy(). The callback will run in the default main context
+of the thread calling g_file_copy_async() — the same context as @callback is
+run in.
+
+When the operation is finished, @callback will be called. You can then call
+g_file_copy_finish() to get the result of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ destination #GFile
+
+
+
+ set of #GFileCopyFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ function to callback with progress
+ information, or %NULL if progress information is not needed
+
+
+
+ user data to pass to @progress_callback
+
+
+
+ a #GAsyncReadyCallback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes copying the file started with g_file_copy_async().
+
+
+ a %TRUE on success, %FALSE on error.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Creates a new file and returns an output stream for writing to it.
+The file must not already exist.
+
+By default files created are generally readable by everyone,
+but if you pass %G_FILE_CREATE_PRIVATE in @flags the file
+will be made readable only to the current user, to the level
+that is supported on the target filesystem.
+
+If @cancellable is not %NULL, then the operation can be cancelled
+by triggering the cancellable object from another thread. If the
+operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
+returned.
+
+If a file or directory with this name already exists the
+%G_IO_ERROR_EXISTS error will be returned. Some file systems don't
+allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME
+error, and if the name is to long %G_IO_ERROR_FILENAME_TOO_LONG will
+be returned. Other errors are possible too, and depend on what kind
+of filesystem the file is on.
+
+
+ a #GFileOutputStream for the newly created
+ file, or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Asynchronously creates a new file and returns an output stream
+for writing to it. The file must not already exist.
+
+For more details, see g_file_create() which is
+the synchronous version of this call.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_create_finish() to get the result
+of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous file create operation started with
+g_file_create_async().
+
+
+ a #GFileOutputStream or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Creates a new file and returns a stream for reading and
+writing to it. The file must not already exist.
+
+By default files created are generally readable by everyone,
+but if you pass %G_FILE_CREATE_PRIVATE in @flags the file
+will be made readable only to the current user, to the level
+that is supported on the target filesystem.
+
+If @cancellable is not %NULL, then the operation can be cancelled
+by triggering the cancellable object from another thread. If the
+operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
+returned.
+
+If a file or directory with this name already exists, the
+%G_IO_ERROR_EXISTS error will be returned. Some file systems don't
+allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME
+error, and if the name is too long, %G_IO_ERROR_FILENAME_TOO_LONG
+will be returned. Other errors are possible too, and depend on what
+kind of filesystem the file is on.
+
+Note that in many non-local file cases read and write streams are
+not supported, so make sure you really need to do read and write
+streaming, rather than just opening for reading or writing.
+
+
+ a #GFileIOStream for the newly created
+ file, or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GFile
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Asynchronously creates a new file and returns a stream
+for reading and writing to it. The file must not already exist.
+
+For more details, see g_file_create_readwrite() which is
+the synchronous version of this call.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_create_readwrite_finish() to get
+the result of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous file create operation started with
+g_file_create_readwrite_async().
+
+
+ a #GFileIOStream or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Deletes a file. If the @file is a directory, it will only be
+deleted if it is empty. This has the same semantics as g_unlink().
+
+If @file doesn’t exist, %G_IO_ERROR_NOT_FOUND will be returned. This allows
+for deletion to be implemented avoiding
+[time-of-check to time-of-use races](https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use):
+|[
+g_autoptr(GError) local_error = NULL;
+if (!g_file_delete (my_file, my_cancellable, &local_error) &&
+ !g_error_matches (local_error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND))
+ {
+ // deletion failed for some reason other than the file not existing:
+ // so report the error
+ g_warning ("Failed to delete %s: %s",
+ g_file_peek_path (my_file), local_error->message);
+ }
+]|
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ %TRUE if the file was deleted. %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Asynchronously delete a file. If the @file is a directory, it will
+only be deleted if it is empty. This has the same semantics as
+g_unlink().
+
+
+
+
+
+
+ input #GFile
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes deleting a file started with g_file_delete_async().
+
+
+ %TRUE if the file was deleted. %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Duplicates a #GFile handle. This operation does not duplicate
+the actual file or directory represented by the #GFile; see
+g_file_copy() if attempting to copy a file.
+
+g_file_dup() is useful when a second handle is needed to the same underlying
+file, for use in a separate thread (#GFile is not thread-safe). For use
+within the same thread, use g_object_ref() to increment the existing object’s
+reference count.
+
+This call does no blocking I/O.
+
+
+ a new #GFile that is a duplicate
+ of the given #GFile.
+
+
+
+
+ input #GFile
+
+
+
+
+
+ Starts an asynchronous eject on a mountable.
+When this operation has completed, @callback will be called with
+@user_user data, and the operation can be finalized with
+g_file_eject_mountable_finish().
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ Use g_file_eject_mountable_with_operation() instead.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ flags affecting the operation
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied, or %NULL
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous eject operation started by
+g_file_eject_mountable().
+ Use g_file_eject_mountable_with_operation_finish()
+ instead.
+
+
+ %TRUE if the @file was ejected successfully.
+ %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Starts an asynchronous eject on a mountable.
+When this operation has completed, @callback will be called with
+@user_user data, and the operation can be finalized with
+g_file_eject_mountable_with_operation_finish().
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ flags affecting the operation
+
+
+
+ a #GMountOperation,
+ or %NULL to avoid user interaction
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied, or %NULL
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous eject operation started by
+g_file_eject_mountable_with_operation().
+
+
+ %TRUE if the @file was ejected successfully.
+ %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Gets the requested information about the files in a directory.
+The result is a #GFileEnumerator object that will give out
+#GFileInfo objects for all the files in the directory.
+
+The @attributes value is a string that specifies the file
+attributes that should be gathered. It is not an error if
+it's not possible to read a particular requested attribute
+from a file - it just won't be set. @attributes should
+be a comma-separated list of attributes or attribute wildcards.
+The wildcard "*" means all attributes, and a wildcard like
+"standard::*" means all attributes in the standard namespace.
+An example attribute query be "standard::*,owner::user".
+The standard attributes are available as defines, like
+%G_FILE_ATTRIBUTE_STANDARD_NAME. %G_FILE_ATTRIBUTE_STANDARD_NAME should
+always be specified if you plan to call g_file_enumerator_get_child() or
+g_file_enumerator_iterate() on the returned enumerator.
+
+If @cancellable is not %NULL, then the operation can be cancelled
+by triggering the cancellable object from another thread. If the
+operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
+returned.
+
+If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
+be returned. If the file is not a directory, the %G_IO_ERROR_NOT_DIRECTORY
+error will be returned. Other errors are possible too.
+
+
+ A #GFileEnumerator if successful,
+ %NULL on error. Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ an attribute query string
+
+
+
+ a set of #GFileQueryInfoFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Asynchronously gets the requested information about the files
+in a directory. The result is a #GFileEnumerator object that will
+give out #GFileInfo objects for all the files in the directory.
+
+For more details, see g_file_enumerate_children() which is
+the synchronous version of this call.
+
+When the operation is finished, @callback will be called. You can
+then call g_file_enumerate_children_finish() to get the result of
+the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ an attribute query string
+
+
+
+ a set of #GFileQueryInfoFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call when the
+ request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an async enumerate children operation.
+See g_file_enumerate_children_async().
+
+
+ a #GFileEnumerator or %NULL
+ if an error occurred.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Checks if the two given #GFiles refer to the same file.
+
+Note that two #GFiles that differ can still refer to the same
+file on the filesystem due to various forms of filename
+aliasing.
+
+This call does no blocking I/O.
+
+
+ %TRUE if @file1 and @file2 are equal.
+
+
+
+
+ the first #GFile
+
+
+
+ the second #GFile
+
+
+
+
+
+ Gets a #GMount for the #GFile.
+
+#GMount is returned only for user interesting locations, see
+#GVolumeMonitor. If the #GFileIface for @file does not have a #mount,
+@error will be set to %G_IO_ERROR_NOT_FOUND and %NULL #will be returned.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ a #GMount where the @file is located
+ or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Asynchronously gets the mount for the file.
+
+For more details, see g_file_find_enclosing_mount() which is
+the synchronous version of this call.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_find_enclosing_mount_finish() to
+get the result of the operation.
+
+
+
+
+
+
+ a #GFile
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous find mount request.
+See g_file_find_enclosing_mount_async().
+
+
+ #GMount for given @file or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Gets the base name (the last component of the path) for a given #GFile.
+
+If called for the top level of a system (such as the filesystem root
+or a uri like sftp://host/) it will return a single directory separator
+(and on Windows, possibly a drive letter).
+
+The base name is a byte string (not UTF-8). It has no defined encoding
+or rules other than it may not contain zero bytes. If you want to use
+filenames in a user interface you should use the display name that you
+can get by requesting the %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME
+attribute with g_file_query_info().
+
+This call does no blocking I/O.
+
+
+ string containing the #GFile's
+ base name, or %NULL if given #GFile is invalid. The returned string
+ should be freed with g_free() when no longer needed.
+
+
+
+
+ input #GFile
+
+
+
+
+
+ Gets the child of @file for a given @display_name (i.e. a UTF-8
+version of the name). If this function fails, it returns %NULL
+and @error will be set. This is very useful when constructing a
+#GFile for a new file and the user entered the filename in the
+user interface, for instance when you select a directory and
+type a filename in the file selector.
+
+This call does no blocking I/O.
+
+
+ a #GFile to the specified child, or
+ %NULL if the display name couldn't be converted.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ string to a possible child
+
+
+
+
+
+ Gets the parent directory for the @file.
+If the @file represents the root directory of the
+file system, then %NULL will be returned.
+
+This call does no blocking I/O.
+
+
+ a #GFile structure to the
+ parent of the given #GFile or %NULL if there is no parent. Free
+ the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+
+
+ Gets the parse name of the @file.
+A parse name is a UTF-8 string that describes the
+file such that one can get the #GFile back using
+g_file_parse_name().
+
+This is generally used to show the #GFile as a nice
+full-pathname kind of string in a user interface,
+like in a location entry.
+
+For local files with names that can safely be converted
+to UTF-8 the pathname is used, otherwise the IRI is used
+(a form of URI that allows UTF-8 characters unescaped).
+
+This call does no blocking I/O.
+
+
+ a string containing the #GFile's parse name.
+ The returned string should be freed with g_free()
+ when no longer needed.
+
+
+
+
+ input #GFile
+
+
+
+
+
+ Gets the local pathname for #GFile, if one exists. If non-%NULL, this is
+guaranteed to be an absolute, canonical path. It might contain symlinks.
+
+This call does no blocking I/O.
+
+
+ string containing the #GFile's path,
+ or %NULL if no such path exists. The returned string should be freed
+ with g_free() when no longer needed.
+
+
+
+
+ input #GFile
+
+
+
+
+
+ Gets the path for @descendant relative to @parent.
+
+This call does no blocking I/O.
+
+
+ string with the relative path from
+ @descendant to @parent, or %NULL if @descendant doesn't have @parent as
+ prefix. The returned string should be freed with g_free() when
+ no longer needed.
+
+
+
+
+ input #GFile
+
+
+
+ input #GFile
+
+
+
+
+
+ Gets the URI for the @file.
+
+This call does no blocking I/O.
+
+
+ a string containing the #GFile's URI. If the #GFile was constructed
+ with an invalid URI, an invalid URI is returned.
+ The returned string should be freed with g_free()
+ when no longer needed.
+
+
+
+
+ input #GFile
+
+
+
+
+
+ Gets the URI scheme for a #GFile.
+RFC 3986 decodes the scheme as:
+|[
+URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
+]|
+Common schemes include "file", "http", "ftp", etc.
+
+The scheme can be different from the one used to construct the #GFile,
+in that it might be replaced with one that is logically equivalent to the #GFile.
+
+This call does no blocking I/O.
+
+
+ a string containing the URI scheme for the given
+ #GFile or %NULL if the #GFile was constructed with an invalid URI. The
+ returned string should be freed with g_free() when no longer needed.
+
+
+
+
+ input #GFile
+
+
+
+
+
+ Checks to see if a #GFile has a given URI scheme.
+
+This call does no blocking I/O.
+
+
+ %TRUE if #GFile's backend supports the
+ given URI scheme, %FALSE if URI scheme is %NULL,
+ not supported, or #GFile is invalid.
+
+
+
+
+ input #GFile
+
+
+
+ a string containing a URI scheme
+
+
+
+
+
+ Creates a hash value for a #GFile.
+
+This call does no blocking I/O.
+
+
+ 0 if @file is not a valid #GFile, otherwise an
+ integer that can be used as hash value for the #GFile.
+ This function is intended for easily hashing a #GFile to
+ add to a #GHashTable or similar data structure.
+
+
+
+
+ #gconstpointer to a #GFile
+
+
+
+
+
+ Checks to see if a file is native to the platform.
+
+A native file is one expressed in the platform-native filename format,
+e.g. "C:\Windows" or "/usr/bin/". This does not mean the file is local,
+as it might be on a locally mounted remote filesystem.
+
+On some systems non-native files may be available using the native
+filesystem via a userspace filesystem (FUSE), in these cases this call
+will return %FALSE, but g_file_get_path() will still return a native path.
+
+This call does no blocking I/O.
+
+
+ %TRUE if @file is native
+
+
+
+
+ input #GFile
+
+
+
+
+
+ Creates a directory. Note that this will only create a child directory
+of the immediate parent directory of the path or URI given by the #GFile.
+To recursively create directories, see g_file_make_directory_with_parents().
+This function will fail if the parent directory does not exist, setting
+@error to %G_IO_ERROR_NOT_FOUND. If the file system doesn't support
+creating directories, this function will fail, setting @error to
+%G_IO_ERROR_NOT_SUPPORTED.
+
+For a local #GFile the newly created directory will have the default
+(current) ownership and permissions of the current process.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ %TRUE on successful creation, %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Asynchronously creates a directory.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous directory creation, started with
+g_file_make_directory_async().
+
+
+ %TRUE on successful directory creation, %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Creates a symbolic link named @file which contains the string
+@symlink_value.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ %TRUE on the creation of a new symlink, %FALSE otherwise.
+
+
+
+
+ a #GFile with the name of the symlink to create
+
+
+
+ a string with the path for the target
+ of the new symlink
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Asynchronously creates a symbolic link named @file which contains the
+string @symlink_value.
+
+
+
+
+
+
+ a #GFile with the name of the symlink to create
+
+
+
+ a string with the path for the target
+ of the new symlink
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous symbolic link creation, started with
+g_file_make_symbolic_link_async().
+
+
+ %TRUE on successful directory creation, %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Recursively measures the disk usage of @file.
+
+This is essentially an analog of the 'du' command, but it also
+reports the number of directories and non-directory files encountered
+(including things like symbolic links).
+
+By default, errors are only reported against the toplevel file
+itself. Errors found while recursing are silently ignored, unless
+%G_FILE_MEASURE_REPORT_ANY_ERROR is given in @flags.
+
+The returned size, @disk_usage, is in bytes and should be formatted
+with g_format_size() in order to get something reasonable for showing
+in a user interface.
+
+@progress_callback and @progress_data can be given to request
+periodic progress updates while scanning. See the documentation for
+#GFileMeasureProgressCallback for information about when and how the
+callback will be invoked.
+
+
+ %TRUE if successful, with the out parameters set.
+ %FALSE otherwise, with @error set.
+
+
+
+
+ a #GFile
+
+
+
+ #GFileMeasureFlags
+
+
+
+ optional #GCancellable
+
+
+
+ a #GFileMeasureProgressCallback
+
+
+
+ user_data for @progress_callback
+
+
+
+ the number of bytes of disk space used
+
+
+
+ the number of directories encountered
+
+
+
+ the number of non-directories encountered
+
+
+
+
+
+ Recursively measures the disk usage of @file.
+
+This is the asynchronous version of g_file_measure_disk_usage(). See
+there for more information.
+
+
+
+
+
+
+ a #GFile
+
+
+
+ #GFileMeasureFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable
+
+
+
+ a #GFileMeasureProgressCallback
+
+
+
+ user_data for @progress_callback
+
+
+
+ a #GAsyncReadyCallback to call when complete
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Collects the results from an earlier call to
+g_file_measure_disk_usage_async(). See g_file_measure_disk_usage() for
+more information.
+
+
+ %TRUE if successful, with the out parameters set.
+ %FALSE otherwise, with @error set.
+
+
+
+
+ a #GFile
+
+
+
+ the #GAsyncResult passed to your #GAsyncReadyCallback
+
+
+
+ the number of bytes of disk space used
+
+
+
+ the number of directories encountered
+
+
+
+ the number of non-directories encountered
+
+
+
+
+
+ Obtains a directory monitor for the given file.
+This may fail if directory monitoring is not supported.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+It does not make sense for @flags to contain
+%G_FILE_MONITOR_WATCH_HARD_LINKS, since hard links can not be made to
+directories. It is not possible to monitor all the files in a
+directory for changes made via hard links; if you want to do this then
+you must register individual watches with g_file_monitor().
+
+
+ a #GFileMonitor for the given @file,
+ or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a set of #GFileMonitorFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Obtains a file monitor for the given file. If no file notification
+mechanism exists, then regular polling of the file is used.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+If @flags contains %G_FILE_MONITOR_WATCH_HARD_LINKS then the monitor
+will also attempt to report changes made to the file via another
+filename (ie, a hard link). Without this flag, you can only rely on
+changes made through the filename contained in @file to be
+reported. Using this flag may result in an increase in resource
+usage, and may not have any effect depending on the #GFileMonitor
+backend and/or filesystem type.
+
+
+ a #GFileMonitor for the given @file,
+ or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a set of #GFileMonitorFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Starts a @mount_operation, mounting the volume that contains
+the file @location.
+
+When this operation has completed, @callback will be called with
+@user_user data, and the operation can be finalized with
+g_file_mount_enclosing_volume_finish().
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ flags affecting the operation
+
+
+
+ a #GMountOperation
+ or %NULL to avoid user interaction
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied, or %NULL
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes a mount operation started by g_file_mount_enclosing_volume().
+
+
+ %TRUE if successful. If an error has occurred,
+ this function will return %FALSE and set @error
+ appropriately if present.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Mounts a file of type G_FILE_TYPE_MOUNTABLE.
+Using @mount_operation, you can request callbacks when, for instance,
+passwords are needed during authentication.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_mount_mountable_finish() to get
+the result of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ flags affecting the operation
+
+
+
+ a #GMountOperation,
+ or %NULL to avoid user interaction
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied, or %NULL
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes a mount operation. See g_file_mount_mountable() for details.
+
+Finish an asynchronous mount operation that was started
+with g_file_mount_mountable().
+
+
+ a #GFile or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Tries to move the file or directory @source to the location specified
+by @destination. If native move operations are supported then this is
+used, otherwise a copy + delete fallback is used. The native
+implementation may support moving directories (for instance on moves
+inside the same filesystem), but the fallback code does not.
+
+If the flag %G_FILE_COPY_OVERWRITE is specified an already
+existing @destination file is overwritten.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+If @progress_callback is not %NULL, then the operation can be monitored
+by setting this to a #GFileProgressCallback function.
+@progress_callback_data will be passed to this function. It is
+guaranteed that this callback will be called after all data has been
+transferred with the total number of bytes copied during the operation.
+
+If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND
+error is returned, independent on the status of the @destination.
+
+If %G_FILE_COPY_OVERWRITE is not specified and the target exists,
+then the error %G_IO_ERROR_EXISTS is returned.
+
+If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY
+error is returned. If trying to overwrite a directory with a directory the
+%G_IO_ERROR_WOULD_MERGE error is returned.
+
+If the source is a directory and the target does not exist, or
+%G_FILE_COPY_OVERWRITE is specified and the target is a file, then
+the %G_IO_ERROR_WOULD_RECURSE error may be returned (if the native
+move operation isn't available).
+
+
+ %TRUE on successful move, %FALSE otherwise.
+
+
+
+
+ #GFile pointing to the source location
+
+
+
+ #GFile pointing to the destination location
+
+
+
+ set of #GFileCopyFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ #GFileProgressCallback
+ function for updates
+
+
+
+ gpointer to user data for
+ the callback function
+
+
+
+
+
+ Asynchronously moves a file @source to the location of @destination. For details of the behaviour, see g_file_move().
+
+If @progress_callback is not %NULL, then that function that will be called
+just like in g_file_move(). The callback will run in the default main context
+of the thread calling g_file_move_async() — the same context as @callback is
+run in.
+
+When the operation is finished, @callback will be called. You can then call
+g_file_move_finish() to get the result of the operation.
+
+
+
+
+
+
+ #GFile pointing to the source location
+
+
+
+ #GFile pointing to the destination location
+
+
+
+ set of #GFileCopyFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ #GFileProgressCallback
+ function for updates
+
+
+
+ gpointer to user data for
+ the callback function
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous file movement, started with
+g_file_move_async().
+
+
+ %TRUE on successful file move, %FALSE otherwise.
+
+
+
+
+ input source #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Opens an existing file for reading and writing. The result is
+a #GFileIOStream that can be used to read and write the contents
+of the file.
+
+If @cancellable is not %NULL, then the operation can be cancelled
+by triggering the cancellable object from another thread. If the
+operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
+returned.
+
+If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
+be returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY
+error will be returned. Other errors are possible too, and depend on
+what kind of filesystem the file is on. Note that in many non-local
+file cases read and write streams are not supported, so make sure you
+really need to do read and write streaming, rather than just opening
+for reading or writing.
+
+
+ #GFileIOStream or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ #GFile to open
+
+
+
+ a #GCancellable
+
+
+
+
+
+ Asynchronously opens @file for reading and writing.
+
+For more details, see g_file_open_readwrite() which is
+the synchronous version of this call.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_open_readwrite_finish() to get
+the result of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous file read operation started with
+g_file_open_readwrite_async().
+
+
+ a #GFileIOStream or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Polls a file of type %G_FILE_TYPE_MOUNTABLE.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_mount_mountable_finish() to get
+the result of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied, or %NULL
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes a poll operation. See g_file_poll_mountable() for details.
+
+Finish an asynchronous poll operation that was polled
+with g_file_poll_mountable().
+
+
+ %TRUE if the operation finished successfully. %FALSE
+otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Checks whether @file has the prefix specified by @prefix.
+
+In other words, if the names of initial elements of @file's
+pathname match @prefix. Only full pathname elements are matched,
+so a path like /foo is not considered a prefix of /foobar, only
+of /foo/bar.
+
+A #GFile is not a prefix of itself. If you want to check for
+equality, use g_file_equal().
+
+This call does no I/O, as it works purely on names. As such it can
+sometimes return %FALSE even if @file is inside a @prefix (from a
+filesystem point of view), because the prefix of @file is an alias
+of @prefix.
+
+
+ %TRUE if the @file's parent, grandparent, etc is @prefix,
+ %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ input #GFile
+
+
+
+
+
+ Similar to g_file_query_info(), but obtains information
+about the filesystem the @file is on, rather than the file itself.
+For instance the amount of space available and the type of
+the filesystem.
+
+The @attributes value is a string that specifies the attributes
+that should be gathered. It is not an error if it's not possible
+to read a particular requested attribute from a file - it just
+won't be set. @attributes should be a comma-separated list of
+attributes or attribute wildcards. The wildcard "*" means all
+attributes, and a wildcard like "filesystem::*" means all attributes
+in the filesystem namespace. The standard namespace for filesystem
+attributes is "filesystem". Common attributes of interest are
+%G_FILE_ATTRIBUTE_FILESYSTEM_SIZE (the total size of the filesystem
+in bytes), %G_FILE_ATTRIBUTE_FILESYSTEM_FREE (number of bytes available),
+and %G_FILE_ATTRIBUTE_FILESYSTEM_TYPE (type of the filesystem).
+
+If @cancellable is not %NULL, then the operation can be cancelled
+by triggering the cancellable object from another thread. If the
+operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
+returned.
+
+If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
+be returned. Other errors are possible too, and depend on what
+kind of filesystem the file is on.
+
+
+ a #GFileInfo or %NULL if there was an error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ an attribute query string
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Asynchronously gets the requested information about the filesystem
+that the specified @file is on. The result is a #GFileInfo object
+that contains key-value attributes (such as type or size for the
+file).
+
+For more details, see g_file_query_filesystem_info() which is the
+synchronous version of this call.
+
+When the operation is finished, @callback will be called. You can
+then call g_file_query_info_finish() to get the result of the
+operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ an attribute query string
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous filesystem info query.
+See g_file_query_filesystem_info_async().
+
+
+ #GFileInfo for given @file
+ or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Gets the requested information about specified @file.
+The result is a #GFileInfo object that contains key-value
+attributes (such as the type or size of the file).
+
+The @attributes value is a string that specifies the file
+attributes that should be gathered. It is not an error if
+it's not possible to read a particular requested attribute
+from a file - it just won't be set. @attributes should be a
+comma-separated list of attributes or attribute wildcards.
+The wildcard "*" means all attributes, and a wildcard like
+"standard::*" means all attributes in the standard namespace.
+An example attribute query be "standard::*,owner::user".
+The standard attributes are available as defines, like
+%G_FILE_ATTRIBUTE_STANDARD_NAME.
+
+If @cancellable is not %NULL, then the operation can be cancelled
+by triggering the cancellable object from another thread. If the
+operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
+returned.
+
+For symlinks, normally the information about the target of the
+symlink is returned, rather than information about the symlink
+itself. However if you pass %G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS
+in @flags the information about the symlink itself will be returned.
+Also, for symlinks that point to non-existing files the information
+about the symlink itself will be returned.
+
+If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be
+returned. Other errors are possible too, and depend on what kind of
+filesystem the file is on.
+
+
+ a #GFileInfo for the given @file, or %NULL
+ on error. Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ an attribute query string
+
+
+
+ a set of #GFileQueryInfoFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Asynchronously gets the requested information about specified @file.
+The result is a #GFileInfo object that contains key-value attributes
+(such as type or size for the file).
+
+For more details, see g_file_query_info() which is the synchronous
+version of this call.
+
+When the operation is finished, @callback will be called. You can
+then call g_file_query_info_finish() to get the result of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ an attribute query string
+
+
+
+ a set of #GFileQueryInfoFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call when the
+ request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous file info query.
+See g_file_query_info_async().
+
+
+ #GFileInfo for given @file
+ or %NULL on error. Free the returned object with
+ g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Obtain the list of settable attributes for the file.
+
+Returns the type and full attribute name of all the attributes
+that can be set on this file. This doesn't mean setting it will
+always succeed though, you might get an access failure, or some
+specific file may not support a specific attribute.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ a #GFileAttributeInfoList describing the settable attributes.
+ When you are done with it, release it with
+ g_file_attribute_info_list_unref()
+
+
+
+
+ input #GFile
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Obtain the list of attribute namespaces where new attributes
+can be created by a user. An example of this is extended
+attributes (in the "xattr" namespace).
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ a #GFileAttributeInfoList describing the writable namespaces.
+ When you are done with it, release it with
+ g_file_attribute_info_list_unref()
+
+
+
+
+ input #GFile
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Asynchronously opens @file for reading.
+
+For more details, see g_file_read() which is
+the synchronous version of this call.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_read_finish() to get the result
+of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous file read operation started with
+g_file_read_async().
+
+
+ a #GFileInputStream or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Opens a file for reading. The result is a #GFileInputStream that
+can be used to read the contents of the file.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be
+returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY
+error will be returned. Other errors are possible too, and depend
+on what kind of filesystem the file is on.
+
+
+ #GFileInputStream or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ #GFile to read
+
+
+
+ a #GCancellable
+
+
+
+
+
+ Returns an output stream for overwriting the file, possibly
+creating a backup copy of the file first. If the file doesn't exist,
+it will be created.
+
+This will try to replace the file in the safest way possible so
+that any errors during the writing will not affect an already
+existing copy of the file. For instance, for local files it
+may write to a temporary file and then atomically rename over
+the destination when the stream is closed.
+
+By default files created are generally readable by everyone,
+but if you pass %G_FILE_CREATE_PRIVATE in @flags the file
+will be made readable only to the current user, to the level that
+is supported on the target filesystem.
+
+If @cancellable is not %NULL, then the operation can be cancelled
+by triggering the cancellable object from another thread. If the
+operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
+returned.
+
+If you pass in a non-%NULL @etag value and @file already exists, then
+this value is compared to the current entity tag of the file, and if
+they differ an %G_IO_ERROR_WRONG_ETAG error is returned. This
+generally means that the file has been changed since you last read
+it. You can get the new etag from g_file_output_stream_get_etag()
+after you've finished writing and closed the #GFileOutputStream. When
+you load a new file you can use g_file_input_stream_query_info() to
+get the etag of the file.
+
+If @make_backup is %TRUE, this function will attempt to make a
+backup of the current file before overwriting it. If this fails
+a %G_IO_ERROR_CANT_CREATE_BACKUP error will be returned. If you
+want to replace anyway, try again with @make_backup set to %FALSE.
+
+If the file is a directory the %G_IO_ERROR_IS_DIRECTORY error will
+be returned, and if the file is some other form of non-regular file
+then a %G_IO_ERROR_NOT_REGULAR_FILE error will be returned. Some
+file systems don't allow all file names, and may return an
+%G_IO_ERROR_INVALID_FILENAME error, and if the name is to long
+%G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are
+possible too, and depend on what kind of filesystem the file is on.
+
+
+ a #GFileOutputStream or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ an optional [entity tag][gfile-etag]
+ for the current #GFile, or #NULL to ignore
+
+
+
+ %TRUE if a backup should be created
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Asynchronously overwrites the file, replacing the contents,
+possibly creating a backup copy of the file first.
+
+For more details, see g_file_replace() which is
+the synchronous version of this call.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_replace_finish() to get the result
+of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ an [entity tag][gfile-etag] for the current #GFile,
+ or %NULL to ignore
+
+
+
+ %TRUE if a backup should be created
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous file replace operation started with
+g_file_replace_async().
+
+
+ a #GFileOutputStream, or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Returns an output stream for overwriting the file in readwrite mode,
+possibly creating a backup copy of the file first. If the file doesn't
+exist, it will be created.
+
+For details about the behaviour, see g_file_replace() which does the
+same thing but returns an output stream only.
+
+Note that in many non-local file cases read and write streams are not
+supported, so make sure you really need to do read and write streaming,
+rather than just opening for reading or writing.
+
+
+ a #GFileIOStream or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GFile
+
+
+
+ an optional [entity tag][gfile-etag]
+ for the current #GFile, or #NULL to ignore
+
+
+
+ %TRUE if a backup should be created
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Asynchronously overwrites the file in read-write mode,
+replacing the contents, possibly creating a backup copy
+of the file first.
+
+For more details, see g_file_replace_readwrite() which is
+the synchronous version of this call.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_replace_readwrite_finish() to get
+the result of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ an [entity tag][gfile-etag] for the current #GFile,
+ or %NULL to ignore
+
+
+
+ %TRUE if a backup should be created
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous file replace operation started with
+g_file_replace_readwrite_async().
+
+
+ a #GFileIOStream, or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Resolves a relative path for @file to an absolute path.
+
+This call does no blocking I/O.
+
+If the @relative_path is an absolute path name, the resolution
+is done absolutely (without taking @file path as base).
+
+
+ a #GFile for the resolved path.
+
+
+
+
+ input #GFile
+
+
+
+ a given relative path string
+
+
+
+
+
+ Sets an attribute in the file with attribute name @attribute to @value_p.
+
+Some attributes can be unset by setting @type to
+%G_FILE_ATTRIBUTE_TYPE_INVALID and @value_p to %NULL.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ %TRUE if the attribute was set, %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a string containing the attribute's name
+
+
+
+ The type of the attribute
+
+
+
+ a pointer to the value (or the pointer
+ itself if the type is a pointer type)
+
+
+
+ a set of #GFileQueryInfoFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Asynchronously sets the attributes of @file with @info.
+
+For more details, see g_file_set_attributes_from_info(),
+which is the synchronous version of this call.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_set_attributes_finish() to get
+the result of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ a #GFileInfo
+
+
+
+ a #GFileQueryInfoFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback
+
+
+
+ a #gpointer
+
+
+
+
+
+ Finishes setting an attribute started in g_file_set_attributes_async().
+
+
+ %TRUE if the attributes were set correctly, %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+ a #GFileInfo
+
+
+
+
+
+ Tries to set all attributes in the #GFileInfo on the target
+values, not stopping on the first error.
+
+If there is any error during this operation then @error will
+be set to the first error. Error on particular fields are flagged
+by setting the "status" field in the attribute value to
+%G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING, which means you can
+also detect further errors.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ %FALSE if there was any error, %TRUE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GFileInfo
+
+
+
+ #GFileQueryInfoFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Renames @file to the specified display name.
+
+The display name is converted from UTF-8 to the correct encoding
+for the target filesystem if possible and the @file is renamed to this.
+
+If you want to implement a rename operation in the user interface the
+edit name (%G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the
+initial value in the rename widget, and then the result after editing
+should be passed to g_file_set_display_name().
+
+On success the resulting converted filename is returned.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ a #GFile specifying what @file was renamed to,
+ or %NULL if there was an error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a string
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Asynchronously sets the display name for a given #GFile.
+
+For more details, see g_file_set_display_name() which is
+the synchronous version of this call.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_set_display_name_finish() to get
+the result of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ a string
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes setting a display name started with
+g_file_set_display_name_async().
+
+
+ a #GFile or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Starts a file of type %G_FILE_TYPE_MOUNTABLE.
+Using @start_operation, you can request callbacks when, for instance,
+passwords are needed during authentication.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_mount_mountable_finish() to get
+the result of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ flags affecting the operation
+
+
+
+ a #GMountOperation, or %NULL to avoid user interaction
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call when the request is satisfied, or %NULL
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes a start operation. See g_file_start_mountable() for details.
+
+Finish an asynchronous start operation that was started
+with g_file_start_mountable().
+
+
+ %TRUE if the operation finished successfully. %FALSE
+otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Stops a file of type %G_FILE_TYPE_MOUNTABLE.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_stop_mountable_finish() to get
+the result of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ flags affecting the operation
+
+
+
+ a #GMountOperation,
+ or %NULL to avoid user interaction.
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied, or %NULL
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes a stop operation, see g_file_stop_mountable() for details.
+
+Finish an asynchronous stop operation that was started
+with g_file_stop_mountable().
+
+
+ %TRUE if the operation finished successfully.
+ %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Sends @file to the "Trashcan", if possible. This is similar to
+deleting it, but the user can recover it before emptying the trashcan.
+Not all file systems support trashing, so this call can return the
+%G_IO_ERROR_NOT_SUPPORTED error. Since GLib 2.66, the `x-gvfs-notrash` unix
+mount option can be used to disable g_file_trash() support for certain
+mounts, the %G_IO_ERROR_NOT_SUPPORTED error will be returned in that case.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ %TRUE on successful trash, %FALSE otherwise.
+
+
+
+
+ #GFile to send to trash
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Asynchronously sends @file to the Trash location, if possible.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous file trashing operation, started with
+g_file_trash_async().
+
+
+ %TRUE on successful trash, %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Unmounts a file of type G_FILE_TYPE_MOUNTABLE.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_unmount_mountable_finish() to get
+the result of the operation.
+ Use g_file_unmount_mountable_with_operation() instead.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ flags affecting the operation
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied, or %NULL
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an unmount operation, see g_file_unmount_mountable() for details.
+
+Finish an asynchronous unmount operation that was started
+with g_file_unmount_mountable().
+ Use g_file_unmount_mountable_with_operation_finish()
+ instead.
+
+
+ %TRUE if the operation finished successfully.
+ %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Unmounts a file of type %G_FILE_TYPE_MOUNTABLE.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_unmount_mountable_finish() to get
+the result of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ flags affecting the operation
+
+
+
+ a #GMountOperation,
+ or %NULL to avoid user interaction
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied, or %NULL
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an unmount operation,
+see g_file_unmount_mountable_with_operation() for details.
+
+Finish an asynchronous unmount operation that was started
+with g_file_unmount_mountable_with_operation().
+
+
+ %TRUE if the operation finished successfully.
+ %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Gets an output stream for appending data to the file.
+If the file doesn't already exist it is created.
+
+By default files created are generally readable by everyone,
+but if you pass %G_FILE_CREATE_PRIVATE in @flags the file
+will be made readable only to the current user, to the level that
+is supported on the target filesystem.
+
+If @cancellable is not %NULL, then the operation can be cancelled
+by triggering the cancellable object from another thread. If the
+operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
+returned.
+
+Some file systems don't allow all file names, and may return an
+%G_IO_ERROR_INVALID_FILENAME error. If the file is a directory the
+%G_IO_ERROR_IS_DIRECTORY error will be returned. Other errors are
+possible too, and depend on what kind of filesystem the file is on.
+
+
+ a #GFileOutputStream, or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Asynchronously opens @file for appending.
+
+For more details, see g_file_append_to() which is
+the synchronous version of this call.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_append_to_finish() to get the result
+of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous file append operation started with
+g_file_append_to_async().
+
+
+ a valid #GFileOutputStream
+ or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ #GAsyncResult
+
+
+
+
+
+ Prepares the file attribute query string for copying to @file.
+
+This function prepares an attribute query string to be
+passed to g_file_query_info() to get a list of attributes
+normally copied with the file (see g_file_copy_attributes()
+for the detailed description). This function is used by the
+implementation of g_file_copy_attributes() and is useful
+when one needs to query and set the attributes in two
+stages (e.g., for recursive move of a directory).
+
+
+ an attribute query string for g_file_query_info(),
+ or %NULL if an error occurs.
+
+
+
+
+ a #GFile to copy attributes to
+
+
+
+ a set of #GFileCopyFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Copies the file @source to the location specified by @destination.
+Can not handle recursive copies of directories.
+
+If the flag %G_FILE_COPY_OVERWRITE is specified an already
+existing @destination file is overwritten.
+
+If the flag %G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks
+will be copied as symlinks, otherwise the target of the
+@source symlink will be copied.
+
+If the flag %G_FILE_COPY_ALL_METADATA is specified then all the metadata
+that is possible to copy is copied, not just the default subset (which,
+for instance, does not include the owner, see #GFileInfo).
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+If @progress_callback is not %NULL, then the operation can be monitored
+by setting this to a #GFileProgressCallback function.
+@progress_callback_data will be passed to this function. It is guaranteed
+that this callback will be called after all data has been transferred with
+the total number of bytes copied during the operation.
+
+If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND error
+is returned, independent on the status of the @destination.
+
+If %G_FILE_COPY_OVERWRITE is not specified and the target exists, then
+the error %G_IO_ERROR_EXISTS is returned.
+
+If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY
+error is returned. If trying to overwrite a directory with a directory the
+%G_IO_ERROR_WOULD_MERGE error is returned.
+
+If the source is a directory and the target does not exist, or
+%G_FILE_COPY_OVERWRITE is specified and the target is a file, then the
+%G_IO_ERROR_WOULD_RECURSE error is returned.
+
+If you are interested in copying the #GFile object itself (not the on-disk
+file), see g_file_dup().
+
+
+ %TRUE on success, %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ destination #GFile
+
+
+
+ set of #GFileCopyFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ function to callback with
+ progress information, or %NULL if progress information is not needed
+
+
+
+ user data to pass to @progress_callback
+
+
+
+
+
+ Copies the file @source to the location specified by @destination
+asynchronously. For details of the behaviour, see g_file_copy().
+
+If @progress_callback is not %NULL, then that function that will be called
+just like in g_file_copy(). The callback will run in the default main context
+of the thread calling g_file_copy_async() — the same context as @callback is
+run in.
+
+When the operation is finished, @callback will be called. You can then call
+g_file_copy_finish() to get the result of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ destination #GFile
+
+
+
+ set of #GFileCopyFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ function to callback with progress
+ information, or %NULL if progress information is not needed
+
+
+
+ user data to pass to @progress_callback
+
+
+
+ a #GAsyncReadyCallback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Copies the file attributes from @source to @destination.
+
+Normally only a subset of the file attributes are copied,
+those that are copies in a normal file copy operation
+(which for instance does not include e.g. owner). However
+if %G_FILE_COPY_ALL_METADATA is specified in @flags, then
+all the metadata that is possible to copy is copied. This
+is useful when implementing move by copy + delete source.
+
+
+ %TRUE if the attributes were copied successfully,
+ %FALSE otherwise.
+
+
+
+
+ a #GFile with attributes
+
+
+
+ a #GFile to copy attributes to
+
+
+
+ a set of #GFileCopyFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Finishes copying the file started with g_file_copy_async().
+
+
+ a %TRUE on success, %FALSE on error.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Creates a new file and returns an output stream for writing to it.
+The file must not already exist.
+
+By default files created are generally readable by everyone,
+but if you pass %G_FILE_CREATE_PRIVATE in @flags the file
+will be made readable only to the current user, to the level
+that is supported on the target filesystem.
+
+If @cancellable is not %NULL, then the operation can be cancelled
+by triggering the cancellable object from another thread. If the
+operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
+returned.
+
+If a file or directory with this name already exists the
+%G_IO_ERROR_EXISTS error will be returned. Some file systems don't
+allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME
+error, and if the name is to long %G_IO_ERROR_FILENAME_TOO_LONG will
+be returned. Other errors are possible too, and depend on what kind
+of filesystem the file is on.
+
+
+ a #GFileOutputStream for the newly created
+ file, or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Asynchronously creates a new file and returns an output stream
+for writing to it. The file must not already exist.
+
+For more details, see g_file_create() which is
+the synchronous version of this call.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_create_finish() to get the result
+of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous file create operation started with
+g_file_create_async().
+
+
+ a #GFileOutputStream or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Creates a new file and returns a stream for reading and
+writing to it. The file must not already exist.
+
+By default files created are generally readable by everyone,
+but if you pass %G_FILE_CREATE_PRIVATE in @flags the file
+will be made readable only to the current user, to the level
+that is supported on the target filesystem.
+
+If @cancellable is not %NULL, then the operation can be cancelled
+by triggering the cancellable object from another thread. If the
+operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
+returned.
+
+If a file or directory with this name already exists, the
+%G_IO_ERROR_EXISTS error will be returned. Some file systems don't
+allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME
+error, and if the name is too long, %G_IO_ERROR_FILENAME_TOO_LONG
+will be returned. Other errors are possible too, and depend on what
+kind of filesystem the file is on.
+
+Note that in many non-local file cases read and write streams are
+not supported, so make sure you really need to do read and write
+streaming, rather than just opening for reading or writing.
+
+
+ a #GFileIOStream for the newly created
+ file, or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GFile
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Asynchronously creates a new file and returns a stream
+for reading and writing to it. The file must not already exist.
+
+For more details, see g_file_create_readwrite() which is
+the synchronous version of this call.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_create_readwrite_finish() to get
+the result of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous file create operation started with
+g_file_create_readwrite_async().
+
+
+ a #GFileIOStream or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Deletes a file. If the @file is a directory, it will only be
+deleted if it is empty. This has the same semantics as g_unlink().
+
+If @file doesn’t exist, %G_IO_ERROR_NOT_FOUND will be returned. This allows
+for deletion to be implemented avoiding
+[time-of-check to time-of-use races](https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use):
+|[
+g_autoptr(GError) local_error = NULL;
+if (!g_file_delete (my_file, my_cancellable, &local_error) &&
+ !g_error_matches (local_error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND))
+ {
+ // deletion failed for some reason other than the file not existing:
+ // so report the error
+ g_warning ("Failed to delete %s: %s",
+ g_file_peek_path (my_file), local_error->message);
+ }
+]|
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ %TRUE if the file was deleted. %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Asynchronously delete a file. If the @file is a directory, it will
+only be deleted if it is empty. This has the same semantics as
+g_unlink().
+
+
+
+
+
+
+ input #GFile
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes deleting a file started with g_file_delete_async().
+
+
+ %TRUE if the file was deleted. %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Duplicates a #GFile handle. This operation does not duplicate
+the actual file or directory represented by the #GFile; see
+g_file_copy() if attempting to copy a file.
+
+g_file_dup() is useful when a second handle is needed to the same underlying
+file, for use in a separate thread (#GFile is not thread-safe). For use
+within the same thread, use g_object_ref() to increment the existing object’s
+reference count.
+
+This call does no blocking I/O.
+
+
+ a new #GFile that is a duplicate
+ of the given #GFile.
+
+
+
+
+ input #GFile
+
+
+
+
+
+ Starts an asynchronous eject on a mountable.
+When this operation has completed, @callback will be called with
+@user_user data, and the operation can be finalized with
+g_file_eject_mountable_finish().
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ Use g_file_eject_mountable_with_operation() instead.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ flags affecting the operation
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied, or %NULL
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous eject operation started by
+g_file_eject_mountable().
+ Use g_file_eject_mountable_with_operation_finish()
+ instead.
+
+
+ %TRUE if the @file was ejected successfully.
+ %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Starts an asynchronous eject on a mountable.
+When this operation has completed, @callback will be called with
+@user_user data, and the operation can be finalized with
+g_file_eject_mountable_with_operation_finish().
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ flags affecting the operation
+
+
+
+ a #GMountOperation,
+ or %NULL to avoid user interaction
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied, or %NULL
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous eject operation started by
+g_file_eject_mountable_with_operation().
+
+
+ %TRUE if the @file was ejected successfully.
+ %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Gets the requested information about the files in a directory.
+The result is a #GFileEnumerator object that will give out
+#GFileInfo objects for all the files in the directory.
+
+The @attributes value is a string that specifies the file
+attributes that should be gathered. It is not an error if
+it's not possible to read a particular requested attribute
+from a file - it just won't be set. @attributes should
+be a comma-separated list of attributes or attribute wildcards.
+The wildcard "*" means all attributes, and a wildcard like
+"standard::*" means all attributes in the standard namespace.
+An example attribute query be "standard::*,owner::user".
+The standard attributes are available as defines, like
+%G_FILE_ATTRIBUTE_STANDARD_NAME. %G_FILE_ATTRIBUTE_STANDARD_NAME should
+always be specified if you plan to call g_file_enumerator_get_child() or
+g_file_enumerator_iterate() on the returned enumerator.
+
+If @cancellable is not %NULL, then the operation can be cancelled
+by triggering the cancellable object from another thread. If the
+operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
+returned.
+
+If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
+be returned. If the file is not a directory, the %G_IO_ERROR_NOT_DIRECTORY
+error will be returned. Other errors are possible too.
+
+
+ A #GFileEnumerator if successful,
+ %NULL on error. Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ an attribute query string
+
+
+
+ a set of #GFileQueryInfoFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Asynchronously gets the requested information about the files
+in a directory. The result is a #GFileEnumerator object that will
+give out #GFileInfo objects for all the files in the directory.
+
+For more details, see g_file_enumerate_children() which is
+the synchronous version of this call.
+
+When the operation is finished, @callback will be called. You can
+then call g_file_enumerate_children_finish() to get the result of
+the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ an attribute query string
+
+
+
+ a set of #GFileQueryInfoFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call when the
+ request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an async enumerate children operation.
+See g_file_enumerate_children_async().
+
+
+ a #GFileEnumerator or %NULL
+ if an error occurred.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Checks if the two given #GFiles refer to the same file.
+
+Note that two #GFiles that differ can still refer to the same
+file on the filesystem due to various forms of filename
+aliasing.
+
+This call does no blocking I/O.
+
+
+ %TRUE if @file1 and @file2 are equal.
+
+
+
+
+ the first #GFile
+
+
+
+ the second #GFile
+
+
+
+
+
+ Gets a #GMount for the #GFile.
+
+#GMount is returned only for user interesting locations, see
+#GVolumeMonitor. If the #GFileIface for @file does not have a #mount,
+@error will be set to %G_IO_ERROR_NOT_FOUND and %NULL #will be returned.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ a #GMount where the @file is located
+ or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Asynchronously gets the mount for the file.
+
+For more details, see g_file_find_enclosing_mount() which is
+the synchronous version of this call.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_find_enclosing_mount_finish() to
+get the result of the operation.
+
+
+
+
+
+
+ a #GFile
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous find mount request.
+See g_file_find_enclosing_mount_async().
+
+
+ #GMount for given @file or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Gets the base name (the last component of the path) for a given #GFile.
+
+If called for the top level of a system (such as the filesystem root
+or a uri like sftp://host/) it will return a single directory separator
+(and on Windows, possibly a drive letter).
+
+The base name is a byte string (not UTF-8). It has no defined encoding
+or rules other than it may not contain zero bytes. If you want to use
+filenames in a user interface you should use the display name that you
+can get by requesting the %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME
+attribute with g_file_query_info().
+
+This call does no blocking I/O.
+
+
+ string containing the #GFile's
+ base name, or %NULL if given #GFile is invalid. The returned string
+ should be freed with g_free() when no longer needed.
+
+
+
+
+ input #GFile
+
+
+
+
+
+ Gets a child of @file with basename equal to @name.
+
+Note that the file with that specific name might not exist, but
+you can still have a #GFile that points to it. You can use this
+for instance to create that file.
+
+This call does no blocking I/O.
+
+
+ a #GFile to a child specified by @name.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ string containing the child's basename
+
+
+
+
+
+ Gets the child of @file for a given @display_name (i.e. a UTF-8
+version of the name). If this function fails, it returns %NULL
+and @error will be set. This is very useful when constructing a
+#GFile for a new file and the user entered the filename in the
+user interface, for instance when you select a directory and
+type a filename in the file selector.
+
+This call does no blocking I/O.
+
+
+ a #GFile to the specified child, or
+ %NULL if the display name couldn't be converted.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ string to a possible child
+
+
+
+
+
+ Gets the parent directory for the @file.
+If the @file represents the root directory of the
+file system, then %NULL will be returned.
+
+This call does no blocking I/O.
+
+
+ a #GFile structure to the
+ parent of the given #GFile or %NULL if there is no parent. Free
+ the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+
+
+ Gets the parse name of the @file.
+A parse name is a UTF-8 string that describes the
+file such that one can get the #GFile back using
+g_file_parse_name().
+
+This is generally used to show the #GFile as a nice
+full-pathname kind of string in a user interface,
+like in a location entry.
+
+For local files with names that can safely be converted
+to UTF-8 the pathname is used, otherwise the IRI is used
+(a form of URI that allows UTF-8 characters unescaped).
+
+This call does no blocking I/O.
+
+
+ a string containing the #GFile's parse name.
+ The returned string should be freed with g_free()
+ when no longer needed.
+
+
+
+
+ input #GFile
+
+
+
+
+
+ Gets the local pathname for #GFile, if one exists. If non-%NULL, this is
+guaranteed to be an absolute, canonical path. It might contain symlinks.
+
+This call does no blocking I/O.
+
+
+ string containing the #GFile's path,
+ or %NULL if no such path exists. The returned string should be freed
+ with g_free() when no longer needed.
+
+
+
+
+ input #GFile
+
+
+
+
+
+ Gets the path for @descendant relative to @parent.
+
+This call does no blocking I/O.
+
+
+ string with the relative path from
+ @descendant to @parent, or %NULL if @descendant doesn't have @parent as
+ prefix. The returned string should be freed with g_free() when
+ no longer needed.
+
+
+
+
+ input #GFile
+
+
+
+ input #GFile
+
+
+
+
+
+ Gets the URI for the @file.
+
+This call does no blocking I/O.
+
+
+ a string containing the #GFile's URI. If the #GFile was constructed
+ with an invalid URI, an invalid URI is returned.
+ The returned string should be freed with g_free()
+ when no longer needed.
+
+
+
+
+ input #GFile
+
+
+
+
+
+ Gets the URI scheme for a #GFile.
+RFC 3986 decodes the scheme as:
+|[
+URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
+]|
+Common schemes include "file", "http", "ftp", etc.
+
+The scheme can be different from the one used to construct the #GFile,
+in that it might be replaced with one that is logically equivalent to the #GFile.
+
+This call does no blocking I/O.
+
+
+ a string containing the URI scheme for the given
+ #GFile or %NULL if the #GFile was constructed with an invalid URI. The
+ returned string should be freed with g_free() when no longer needed.
+
+
+
+
+ input #GFile
+
+
+
+
+
+ Checks if @file has a parent, and optionally, if it is @parent.
+
+If @parent is %NULL then this function returns %TRUE if @file has any
+parent at all. If @parent is non-%NULL then %TRUE is only returned
+if @file is an immediate child of @parent.
+
+
+ %TRUE if @file is an immediate child of @parent (or any parent in
+ the case that @parent is %NULL).
+
+
+
+
+ input #GFile
+
+
+
+ the parent to check for, or %NULL
+
+
+
+
+
+ Checks whether @file has the prefix specified by @prefix.
+
+In other words, if the names of initial elements of @file's
+pathname match @prefix. Only full pathname elements are matched,
+so a path like /foo is not considered a prefix of /foobar, only
+of /foo/bar.
+
+A #GFile is not a prefix of itself. If you want to check for
+equality, use g_file_equal().
+
+This call does no I/O, as it works purely on names. As such it can
+sometimes return %FALSE even if @file is inside a @prefix (from a
+filesystem point of view), because the prefix of @file is an alias
+of @prefix.
+
+
+ %TRUE if the @file's parent, grandparent, etc is @prefix,
+ %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ input #GFile
+
+
+
+
+
+ Checks to see if a #GFile has a given URI scheme.
+
+This call does no blocking I/O.
+
+
+ %TRUE if #GFile's backend supports the
+ given URI scheme, %FALSE if URI scheme is %NULL,
+ not supported, or #GFile is invalid.
+
+
+
+
+ input #GFile
+
+
+
+ a string containing a URI scheme
+
+
+
+
+
+ Creates a hash value for a #GFile.
+
+This call does no blocking I/O.
+
+
+ 0 if @file is not a valid #GFile, otherwise an
+ integer that can be used as hash value for the #GFile.
+ This function is intended for easily hashing a #GFile to
+ add to a #GHashTable or similar data structure.
+
+
+
+
+ #gconstpointer to a #GFile
+
+
+
+
+
+ Checks to see if a file is native to the platform.
+
+A native file is one expressed in the platform-native filename format,
+e.g. "C:\Windows" or "/usr/bin/". This does not mean the file is local,
+as it might be on a locally mounted remote filesystem.
+
+On some systems non-native files may be available using the native
+filesystem via a userspace filesystem (FUSE), in these cases this call
+will return %FALSE, but g_file_get_path() will still return a native path.
+
+This call does no blocking I/O.
+
+
+ %TRUE if @file is native
+
+
+
+
+ input #GFile
+
+
+
+
+
+ Loads the contents of @file and returns it as #GBytes.
+
+If @file is a resource:// based URI, the resulting bytes will reference the
+embedded resource instead of a copy. Otherwise, this is equivalent to calling
+g_file_load_contents() and g_bytes_new_take().
+
+For resources, @etag_out will be set to %NULL.
+
+The data contained in the resulting #GBytes is always zero-terminated, but
+this is not included in the #GBytes length. The resulting #GBytes should be
+freed with g_bytes_unref() when no longer in use.
+
+
+ a #GBytes or %NULL and @error is set
+
+
+
+
+ a #GFile
+
+
+
+ a #GCancellable or %NULL
+
+
+
+ a location to place the current
+ entity tag for the file, or %NULL if the entity tag is not needed
+
+
+
+
+
+ Asynchronously loads the contents of @file as #GBytes.
+
+If @file is a resource:// based URI, the resulting bytes will reference the
+embedded resource instead of a copy. Otherwise, this is equivalent to calling
+g_file_load_contents_async() and g_bytes_new_take().
+
+@callback should call g_file_load_bytes_finish() to get the result of this
+asynchronous operation.
+
+See g_file_load_bytes() for more information.
+
+
+
+
+
+
+ a #GFile
+
+
+
+ a #GCancellable or %NULL
+
+
+
+ a #GAsyncReadyCallback to call when the
+ request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Completes an asynchronous request to g_file_load_bytes_async().
+
+For resources, @etag_out will be set to %NULL.
+
+The data contained in the resulting #GBytes is always zero-terminated, but
+this is not included in the #GBytes length. The resulting #GBytes should be
+freed with g_bytes_unref() when no longer in use.
+
+See g_file_load_bytes() for more information.
+
+
+ a #GBytes or %NULL and @error is set
+
+
+
+
+ a #GFile
+
+
+
+ a #GAsyncResult provided to the callback
+
+
+
+ a location to place the current
+ entity tag for the file, or %NULL if the entity tag is not needed
+
+
+
+
+
+ Loads the content of the file into memory. The data is always
+zero-terminated, but this is not included in the resultant @length.
+The returned @contents should be freed with g_free() when no longer
+needed.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ %TRUE if the @file's contents were successfully loaded.
+ %FALSE if there were errors.
+
+
+
+
+ input #GFile
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a location to place the contents of the file
+
+
+
+
+
+ a location to place the length of the contents of the file,
+ or %NULL if the length is not needed
+
+
+
+ a location to place the current entity tag for the file,
+ or %NULL if the entity tag is not needed
+
+
+
+
+
+ Starts an asynchronous load of the @file's contents.
+
+For more details, see g_file_load_contents() which is
+the synchronous version of this call.
+
+When the load operation has completed, @callback will be called
+with @user data. To finish the operation, call
+g_file_load_contents_finish() with the #GAsyncResult returned by
+the @callback.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous load of the @file's contents.
+The contents are placed in @contents, and @length is set to the
+size of the @contents string. The @contents should be freed with
+g_free() when no longer needed. If @etag_out is present, it will be
+set to the new entity tag for the @file.
+
+
+ %TRUE if the load was successful. If %FALSE and @error is
+ present, it will be set appropriately.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+ a location to place the contents of the file
+
+
+
+
+
+ a location to place the length of the contents of the file,
+ or %NULL if the length is not needed
+
+
+
+ a location to place the current entity tag for the file,
+ or %NULL if the entity tag is not needed
+
+
+
+
+
+ Reads the partial contents of a file. A #GFileReadMoreCallback should
+be used to stop reading from the file when appropriate, else this
+function will behave exactly as g_file_load_contents_async(). This
+operation can be finished by g_file_load_partial_contents_finish().
+
+Users of this function should be aware that @user_data is passed to
+both the @read_more_callback and the @callback.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a
+ #GFileReadMoreCallback to receive partial data
+ and to specify whether further data should be read
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to the callback functions
+
+
+
+
+
+ Finishes an asynchronous partial load operation that was started
+with g_file_load_partial_contents_async(). The data is always
+zero-terminated, but this is not included in the resultant @length.
+The returned @contents should be freed with g_free() when no longer
+needed.
+
+
+ %TRUE if the load was successful. If %FALSE and @error is
+ present, it will be set appropriately.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+ a location to place the contents of the file
+
+
+
+
+
+ a location to place the length of the contents of the file,
+ or %NULL if the length is not needed
+
+
+
+ a location to place the current entity tag for the file,
+ or %NULL if the entity tag is not needed
+
+
+
+
+
+ Creates a directory. Note that this will only create a child directory
+of the immediate parent directory of the path or URI given by the #GFile.
+To recursively create directories, see g_file_make_directory_with_parents().
+This function will fail if the parent directory does not exist, setting
+@error to %G_IO_ERROR_NOT_FOUND. If the file system doesn't support
+creating directories, this function will fail, setting @error to
+%G_IO_ERROR_NOT_SUPPORTED.
+
+For a local #GFile the newly created directory will have the default
+(current) ownership and permissions of the current process.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ %TRUE on successful creation, %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Asynchronously creates a directory.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous directory creation, started with
+g_file_make_directory_async().
+
+
+ %TRUE on successful directory creation, %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Creates a directory and any parent directories that may not
+exist similar to 'mkdir -p'. If the file system does not support
+creating directories, this function will fail, setting @error to
+%G_IO_ERROR_NOT_SUPPORTED. If the directory itself already exists,
+this function will fail setting @error to %G_IO_ERROR_EXISTS, unlike
+the similar g_mkdir_with_parents().
+
+For a local #GFile the newly created directories will have the default
+(current) ownership and permissions of the current process.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ %TRUE if all directories have been successfully created, %FALSE
+otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Creates a symbolic link named @file which contains the string
+@symlink_value.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ %TRUE on the creation of a new symlink, %FALSE otherwise.
+
+
+
+
+ a #GFile with the name of the symlink to create
+
+
+
+ a string with the path for the target
+ of the new symlink
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Asynchronously creates a symbolic link named @file which contains the
+string @symlink_value.
+
+
+
+
+
+
+ a #GFile with the name of the symlink to create
+
+
+
+ a string with the path for the target
+ of the new symlink
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous symbolic link creation, started with
+g_file_make_symbolic_link_async().
+
+
+ %TRUE on successful directory creation, %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Recursively measures the disk usage of @file.
+
+This is essentially an analog of the 'du' command, but it also
+reports the number of directories and non-directory files encountered
+(including things like symbolic links).
+
+By default, errors are only reported against the toplevel file
+itself. Errors found while recursing are silently ignored, unless
+%G_FILE_MEASURE_REPORT_ANY_ERROR is given in @flags.
+
+The returned size, @disk_usage, is in bytes and should be formatted
+with g_format_size() in order to get something reasonable for showing
+in a user interface.
+
+@progress_callback and @progress_data can be given to request
+periodic progress updates while scanning. See the documentation for
+#GFileMeasureProgressCallback for information about when and how the
+callback will be invoked.
+
+
+ %TRUE if successful, with the out parameters set.
+ %FALSE otherwise, with @error set.
+
+
+
+
+ a #GFile
+
+
+
+ #GFileMeasureFlags
+
+
+
+ optional #GCancellable
+
+
+
+ a #GFileMeasureProgressCallback
+
+
+
+ user_data for @progress_callback
+
+
+
+ the number of bytes of disk space used
+
+
+
+ the number of directories encountered
+
+
+
+ the number of non-directories encountered
+
+
+
+
+
+ Recursively measures the disk usage of @file.
+
+This is the asynchronous version of g_file_measure_disk_usage(). See
+there for more information.
+
+
+
+
+
+
+ a #GFile
+
+
+
+ #GFileMeasureFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable
+
+
+
+ a #GFileMeasureProgressCallback
+
+
+
+ user_data for @progress_callback
+
+
+
+ a #GAsyncReadyCallback to call when complete
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Collects the results from an earlier call to
+g_file_measure_disk_usage_async(). See g_file_measure_disk_usage() for
+more information.
+
+
+ %TRUE if successful, with the out parameters set.
+ %FALSE otherwise, with @error set.
+
+
+
+
+ a #GFile
+
+
+
+ the #GAsyncResult passed to your #GAsyncReadyCallback
+
+
+
+ the number of bytes of disk space used
+
+
+
+ the number of directories encountered
+
+
+
+ the number of non-directories encountered
+
+
+
+
+
+ Obtains a file or directory monitor for the given file,
+depending on the type of the file.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ a #GFileMonitor for the given @file,
+ or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a set of #GFileMonitorFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Obtains a directory monitor for the given file.
+This may fail if directory monitoring is not supported.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+It does not make sense for @flags to contain
+%G_FILE_MONITOR_WATCH_HARD_LINKS, since hard links can not be made to
+directories. It is not possible to monitor all the files in a
+directory for changes made via hard links; if you want to do this then
+you must register individual watches with g_file_monitor().
+
+
+ a #GFileMonitor for the given @file,
+ or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a set of #GFileMonitorFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Obtains a file monitor for the given file. If no file notification
+mechanism exists, then regular polling of the file is used.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+If @flags contains %G_FILE_MONITOR_WATCH_HARD_LINKS then the monitor
+will also attempt to report changes made to the file via another
+filename (ie, a hard link). Without this flag, you can only rely on
+changes made through the filename contained in @file to be
+reported. Using this flag may result in an increase in resource
+usage, and may not have any effect depending on the #GFileMonitor
+backend and/or filesystem type.
+
+
+ a #GFileMonitor for the given @file,
+ or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a set of #GFileMonitorFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Starts a @mount_operation, mounting the volume that contains
+the file @location.
+
+When this operation has completed, @callback will be called with
+@user_user data, and the operation can be finalized with
+g_file_mount_enclosing_volume_finish().
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ flags affecting the operation
+
+
+
+ a #GMountOperation
+ or %NULL to avoid user interaction
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied, or %NULL
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes a mount operation started by g_file_mount_enclosing_volume().
+
+
+ %TRUE if successful. If an error has occurred,
+ this function will return %FALSE and set @error
+ appropriately if present.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Mounts a file of type G_FILE_TYPE_MOUNTABLE.
+Using @mount_operation, you can request callbacks when, for instance,
+passwords are needed during authentication.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_mount_mountable_finish() to get
+the result of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ flags affecting the operation
+
+
+
+ a #GMountOperation,
+ or %NULL to avoid user interaction
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied, or %NULL
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes a mount operation. See g_file_mount_mountable() for details.
+
+Finish an asynchronous mount operation that was started
+with g_file_mount_mountable().
+
+
+ a #GFile or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Tries to move the file or directory @source to the location specified
+by @destination. If native move operations are supported then this is
+used, otherwise a copy + delete fallback is used. The native
+implementation may support moving directories (for instance on moves
+inside the same filesystem), but the fallback code does not.
+
+If the flag %G_FILE_COPY_OVERWRITE is specified an already
+existing @destination file is overwritten.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+If @progress_callback is not %NULL, then the operation can be monitored
+by setting this to a #GFileProgressCallback function.
+@progress_callback_data will be passed to this function. It is
+guaranteed that this callback will be called after all data has been
+transferred with the total number of bytes copied during the operation.
+
+If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND
+error is returned, independent on the status of the @destination.
+
+If %G_FILE_COPY_OVERWRITE is not specified and the target exists,
+then the error %G_IO_ERROR_EXISTS is returned.
+
+If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY
+error is returned. If trying to overwrite a directory with a directory the
+%G_IO_ERROR_WOULD_MERGE error is returned.
+
+If the source is a directory and the target does not exist, or
+%G_FILE_COPY_OVERWRITE is specified and the target is a file, then
+the %G_IO_ERROR_WOULD_RECURSE error may be returned (if the native
+move operation isn't available).
+
+
+ %TRUE on successful move, %FALSE otherwise.
+
+
+
+
+ #GFile pointing to the source location
+
+
+
+ #GFile pointing to the destination location
+
+
+
+ set of #GFileCopyFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ #GFileProgressCallback
+ function for updates
+
+
+
+ gpointer to user data for
+ the callback function
+
+
+
+
+
+ Asynchronously moves a file @source to the location of @destination. For details of the behaviour, see g_file_move().
+
+If @progress_callback is not %NULL, then that function that will be called
+just like in g_file_move(). The callback will run in the default main context
+of the thread calling g_file_move_async() — the same context as @callback is
+run in.
+
+When the operation is finished, @callback will be called. You can then call
+g_file_move_finish() to get the result of the operation.
+
+
+
+
+
+
+ #GFile pointing to the source location
+
+
+
+ #GFile pointing to the destination location
+
+
+
+ set of #GFileCopyFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ #GFileProgressCallback
+ function for updates
+
+
+
+ gpointer to user data for
+ the callback function
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous file movement, started with
+g_file_move_async().
+
+
+ %TRUE on successful file move, %FALSE otherwise.
+
+
+
+
+ input source #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Opens an existing file for reading and writing. The result is
+a #GFileIOStream that can be used to read and write the contents
+of the file.
+
+If @cancellable is not %NULL, then the operation can be cancelled
+by triggering the cancellable object from another thread. If the
+operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
+returned.
+
+If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
+be returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY
+error will be returned. Other errors are possible too, and depend on
+what kind of filesystem the file is on. Note that in many non-local
+file cases read and write streams are not supported, so make sure you
+really need to do read and write streaming, rather than just opening
+for reading or writing.
+
+
+ #GFileIOStream or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ #GFile to open
+
+
+
+ a #GCancellable
+
+
+
+
+
+ Asynchronously opens @file for reading and writing.
+
+For more details, see g_file_open_readwrite() which is
+the synchronous version of this call.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_open_readwrite_finish() to get
+the result of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous file read operation started with
+g_file_open_readwrite_async().
+
+
+ a #GFileIOStream or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Exactly like g_file_get_path(), but caches the result via
+g_object_set_qdata_full(). This is useful for example in C
+applications which mix `g_file_*` APIs with native ones. It
+also avoids an extra duplicated string when possible, so will be
+generally more efficient.
+
+This call does no blocking I/O.
+
+
+ string containing the #GFile's path,
+ or %NULL if no such path exists. The returned string is owned by @file.
+
+
+
+
+ input #GFile
+
+
+
+
+
+ Polls a file of type %G_FILE_TYPE_MOUNTABLE.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_mount_mountable_finish() to get
+the result of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied, or %NULL
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes a poll operation. See g_file_poll_mountable() for details.
+
+Finish an asynchronous poll operation that was polled
+with g_file_poll_mountable().
+
+
+ %TRUE if the operation finished successfully. %FALSE
+otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Returns the #GAppInfo that is registered as the default
+application to handle the file specified by @file.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ a #GAppInfo if the handle was found,
+ %NULL if there were errors.
+ When you are done with it, release it with g_object_unref()
+
+
+
+
+ a #GFile to open
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+
+
+ Async version of g_file_query_default_handler().
+
+
+
+
+
+
+ a #GFile to open
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call when the request is done
+
+
+
+ data to pass to @callback
+
+
+
+
+
+ Finishes a g_file_query_default_handler_async() operation.
+
+
+ a #GAppInfo if the handle was found,
+ %NULL if there were errors.
+ When you are done with it, release it with g_object_unref()
+
+
+
+
+ a #GFile to open
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Utility function to check if a particular file exists. This is
+implemented using g_file_query_info() and as such does blocking I/O.
+
+Note that in many cases it is [racy to first check for file existence](https://en.wikipedia.org/wiki/Time_of_check_to_time_of_use)
+and then execute something based on the outcome of that, because the
+file might have been created or removed in between the operations. The
+general approach to handling that is to not check, but just do the
+operation and handle the errors as they come.
+
+As an example of race-free checking, take the case of reading a file,
+and if it doesn't exist, creating it. There are two racy versions: read
+it, and on error create it; and: check if it exists, if not create it.
+These can both result in two processes creating the file (with perhaps
+a partially written file as the result). The correct approach is to
+always try to create the file with g_file_create() which will either
+atomically create the file or fail with a %G_IO_ERROR_EXISTS error.
+
+However, in many cases an existence check is useful in a user interface,
+for instance to make a menu item sensitive/insensitive, so that you don't
+have to fool users that something is possible and then just show an error
+dialog. If you do this, you should make sure to also handle the errors
+that can happen due to races when you execute the operation.
+
+
+ %TRUE if the file exists (and can be detected without error),
+ %FALSE otherwise (or if cancelled).
+
+
+
+
+ input #GFile
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Utility function to inspect the #GFileType of a file. This is
+implemented using g_file_query_info() and as such does blocking I/O.
+
+The primary use case of this method is to check if a file is
+a regular file, directory, or symlink.
+
+
+ The #GFileType of the file and %G_FILE_TYPE_UNKNOWN
+ if the file does not exist
+
+
+
+
+ input #GFile
+
+
+
+ a set of #GFileQueryInfoFlags passed to g_file_query_info()
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Similar to g_file_query_info(), but obtains information
+about the filesystem the @file is on, rather than the file itself.
+For instance the amount of space available and the type of
+the filesystem.
+
+The @attributes value is a string that specifies the attributes
+that should be gathered. It is not an error if it's not possible
+to read a particular requested attribute from a file - it just
+won't be set. @attributes should be a comma-separated list of
+attributes or attribute wildcards. The wildcard "*" means all
+attributes, and a wildcard like "filesystem::*" means all attributes
+in the filesystem namespace. The standard namespace for filesystem
+attributes is "filesystem". Common attributes of interest are
+%G_FILE_ATTRIBUTE_FILESYSTEM_SIZE (the total size of the filesystem
+in bytes), %G_FILE_ATTRIBUTE_FILESYSTEM_FREE (number of bytes available),
+and %G_FILE_ATTRIBUTE_FILESYSTEM_TYPE (type of the filesystem).
+
+If @cancellable is not %NULL, then the operation can be cancelled
+by triggering the cancellable object from another thread. If the
+operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
+returned.
+
+If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
+be returned. Other errors are possible too, and depend on what
+kind of filesystem the file is on.
+
+
+ a #GFileInfo or %NULL if there was an error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ an attribute query string
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Asynchronously gets the requested information about the filesystem
+that the specified @file is on. The result is a #GFileInfo object
+that contains key-value attributes (such as type or size for the
+file).
+
+For more details, see g_file_query_filesystem_info() which is the
+synchronous version of this call.
+
+When the operation is finished, @callback will be called. You can
+then call g_file_query_info_finish() to get the result of the
+operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ an attribute query string
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous filesystem info query.
+See g_file_query_filesystem_info_async().
+
+
+ #GFileInfo for given @file
+ or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Gets the requested information about specified @file.
+The result is a #GFileInfo object that contains key-value
+attributes (such as the type or size of the file).
+
+The @attributes value is a string that specifies the file
+attributes that should be gathered. It is not an error if
+it's not possible to read a particular requested attribute
+from a file - it just won't be set. @attributes should be a
+comma-separated list of attributes or attribute wildcards.
+The wildcard "*" means all attributes, and a wildcard like
+"standard::*" means all attributes in the standard namespace.
+An example attribute query be "standard::*,owner::user".
+The standard attributes are available as defines, like
+%G_FILE_ATTRIBUTE_STANDARD_NAME.
+
+If @cancellable is not %NULL, then the operation can be cancelled
+by triggering the cancellable object from another thread. If the
+operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
+returned.
+
+For symlinks, normally the information about the target of the
+symlink is returned, rather than information about the symlink
+itself. However if you pass %G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS
+in @flags the information about the symlink itself will be returned.
+Also, for symlinks that point to non-existing files the information
+about the symlink itself will be returned.
+
+If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be
+returned. Other errors are possible too, and depend on what kind of
+filesystem the file is on.
+
+
+ a #GFileInfo for the given @file, or %NULL
+ on error. Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ an attribute query string
+
+
+
+ a set of #GFileQueryInfoFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Asynchronously gets the requested information about specified @file.
+The result is a #GFileInfo object that contains key-value attributes
+(such as type or size for the file).
+
+For more details, see g_file_query_info() which is the synchronous
+version of this call.
+
+When the operation is finished, @callback will be called. You can
+then call g_file_query_info_finish() to get the result of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ an attribute query string
+
+
+
+ a set of #GFileQueryInfoFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call when the
+ request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous file info query.
+See g_file_query_info_async().
+
+
+ #GFileInfo for given @file
+ or %NULL on error. Free the returned object with
+ g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Obtain the list of settable attributes for the file.
+
+Returns the type and full attribute name of all the attributes
+that can be set on this file. This doesn't mean setting it will
+always succeed though, you might get an access failure, or some
+specific file may not support a specific attribute.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ a #GFileAttributeInfoList describing the settable attributes.
+ When you are done with it, release it with
+ g_file_attribute_info_list_unref()
+
+
+
+
+ input #GFile
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Obtain the list of attribute namespaces where new attributes
+can be created by a user. An example of this is extended
+attributes (in the "xattr" namespace).
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ a #GFileAttributeInfoList describing the writable namespaces.
+ When you are done with it, release it with
+ g_file_attribute_info_list_unref()
+
+
+
+
+ input #GFile
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Opens a file for reading. The result is a #GFileInputStream that
+can be used to read the contents of the file.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be
+returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY
+error will be returned. Other errors are possible too, and depend
+on what kind of filesystem the file is on.
+
+
+ #GFileInputStream or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ #GFile to read
+
+
+
+ a #GCancellable
+
+
+
+
+
+ Asynchronously opens @file for reading.
+
+For more details, see g_file_read() which is
+the synchronous version of this call.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_read_finish() to get the result
+of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous file read operation started with
+g_file_read_async().
+
+
+ a #GFileInputStream or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Returns an output stream for overwriting the file, possibly
+creating a backup copy of the file first. If the file doesn't exist,
+it will be created.
+
+This will try to replace the file in the safest way possible so
+that any errors during the writing will not affect an already
+existing copy of the file. For instance, for local files it
+may write to a temporary file and then atomically rename over
+the destination when the stream is closed.
+
+By default files created are generally readable by everyone,
+but if you pass %G_FILE_CREATE_PRIVATE in @flags the file
+will be made readable only to the current user, to the level that
+is supported on the target filesystem.
+
+If @cancellable is not %NULL, then the operation can be cancelled
+by triggering the cancellable object from another thread. If the
+operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
+returned.
+
+If you pass in a non-%NULL @etag value and @file already exists, then
+this value is compared to the current entity tag of the file, and if
+they differ an %G_IO_ERROR_WRONG_ETAG error is returned. This
+generally means that the file has been changed since you last read
+it. You can get the new etag from g_file_output_stream_get_etag()
+after you've finished writing and closed the #GFileOutputStream. When
+you load a new file you can use g_file_input_stream_query_info() to
+get the etag of the file.
+
+If @make_backup is %TRUE, this function will attempt to make a
+backup of the current file before overwriting it. If this fails
+a %G_IO_ERROR_CANT_CREATE_BACKUP error will be returned. If you
+want to replace anyway, try again with @make_backup set to %FALSE.
+
+If the file is a directory the %G_IO_ERROR_IS_DIRECTORY error will
+be returned, and if the file is some other form of non-regular file
+then a %G_IO_ERROR_NOT_REGULAR_FILE error will be returned. Some
+file systems don't allow all file names, and may return an
+%G_IO_ERROR_INVALID_FILENAME error, and if the name is to long
+%G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are
+possible too, and depend on what kind of filesystem the file is on.
+
+
+ a #GFileOutputStream or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ an optional [entity tag][gfile-etag]
+ for the current #GFile, or #NULL to ignore
+
+
+
+ %TRUE if a backup should be created
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Asynchronously overwrites the file, replacing the contents,
+possibly creating a backup copy of the file first.
+
+For more details, see g_file_replace() which is
+the synchronous version of this call.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_replace_finish() to get the result
+of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ an [entity tag][gfile-etag] for the current #GFile,
+ or %NULL to ignore
+
+
+
+ %TRUE if a backup should be created
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Replaces the contents of @file with @contents of @length bytes.
+
+If @etag is specified (not %NULL), any existing file must have that etag,
+or the error %G_IO_ERROR_WRONG_ETAG will be returned.
+
+If @make_backup is %TRUE, this function will attempt to make a backup
+of @file. Internally, it uses g_file_replace(), so will try to replace the
+file contents in the safest way possible. For example, atomic renames are
+used when replacing local files’ contents.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+The returned @new_etag can be used to verify that the file hasn't
+changed the next time it is saved over.
+
+
+ %TRUE if successful. If an error has occurred, this function
+ will return %FALSE and set @error appropriately if present.
+
+
+
+
+ input #GFile
+
+
+
+ a string containing the new contents for @file
+
+
+
+
+
+ the length of @contents in bytes
+
+
+
+ the old [entity-tag][gfile-etag] for the document,
+ or %NULL
+
+
+
+ %TRUE if a backup should be created
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ a location to a new [entity tag][gfile-etag]
+ for the document. This should be freed with g_free() when no longer
+ needed, or %NULL
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+
+
+ Starts an asynchronous replacement of @file with the given
+@contents of @length bytes. @etag will replace the document's
+current entity tag.
+
+When this operation has completed, @callback will be called with
+@user_user data, and the operation can be finalized with
+g_file_replace_contents_finish().
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+If @make_backup is %TRUE, this function will attempt to
+make a backup of @file.
+
+Note that no copy of @contents will be made, so it must stay valid
+until @callback is called. See g_file_replace_contents_bytes_async()
+for a #GBytes version that will automatically hold a reference to the
+contents (without copying) for the duration of the call.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ string of contents to replace the file with
+
+
+
+
+
+ the length of @contents in bytes
+
+
+
+ a new [entity tag][gfile-etag] for the @file, or %NULL
+
+
+
+ %TRUE if a backup should be created
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Same as g_file_replace_contents_async() but takes a #GBytes input instead.
+This function will keep a ref on @contents until the operation is done.
+Unlike g_file_replace_contents_async() this allows forgetting about the
+content without waiting for the callback.
+
+When this operation has completed, @callback will be called with
+@user_user data, and the operation can be finalized with
+g_file_replace_contents_finish().
+
+
+
+
+
+
+ input #GFile
+
+
+
+ a #GBytes
+
+
+
+ a new [entity tag][gfile-etag] for the @file, or %NULL
+
+
+
+ %TRUE if a backup should be created
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous replace of the given @file. See
+g_file_replace_contents_async(). Sets @new_etag to the new entity
+tag for the document, if present.
+
+
+ %TRUE on success, %FALSE on failure.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+ a location of a new [entity tag][gfile-etag]
+ for the document. This should be freed with g_free() when it is no
+ longer needed, or %NULL
+
+
+
+
+
+ Finishes an asynchronous file replace operation started with
+g_file_replace_async().
+
+
+ a #GFileOutputStream, or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Returns an output stream for overwriting the file in readwrite mode,
+possibly creating a backup copy of the file first. If the file doesn't
+exist, it will be created.
+
+For details about the behaviour, see g_file_replace() which does the
+same thing but returns an output stream only.
+
+Note that in many non-local file cases read and write streams are not
+supported, so make sure you really need to do read and write streaming,
+rather than just opening for reading or writing.
+
+
+ a #GFileIOStream or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GFile
+
+
+
+ an optional [entity tag][gfile-etag]
+ for the current #GFile, or #NULL to ignore
+
+
+
+ %TRUE if a backup should be created
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Asynchronously overwrites the file in read-write mode,
+replacing the contents, possibly creating a backup copy
+of the file first.
+
+For more details, see g_file_replace_readwrite() which is
+the synchronous version of this call.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_replace_readwrite_finish() to get
+the result of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ an [entity tag][gfile-etag] for the current #GFile,
+ or %NULL to ignore
+
+
+
+ %TRUE if a backup should be created
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous file replace operation started with
+g_file_replace_readwrite_async().
+
+
+ a #GFileIOStream, or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Resolves a relative path for @file to an absolute path.
+
+This call does no blocking I/O.
+
+If the @relative_path is an absolute path name, the resolution
+is done absolutely (without taking @file path as base).
+
+
+ a #GFile for the resolved path.
+
+
+
+
+ input #GFile
+
+
+
+ a given relative path string
+
+
+
+
+
+ Sets an attribute in the file with attribute name @attribute to @value_p.
+
+Some attributes can be unset by setting @type to
+%G_FILE_ATTRIBUTE_TYPE_INVALID and @value_p to %NULL.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ %TRUE if the attribute was set, %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a string containing the attribute's name
+
+
+
+ The type of the attribute
+
+
+
+ a pointer to the value (or the pointer
+ itself if the type is a pointer type)
+
+
+
+ a set of #GFileQueryInfoFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to @value.
+If @attribute is of a different type, this operation will fail,
+returning %FALSE.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ %TRUE if the @attribute was successfully set to @value
+ in the @file, %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a string containing the attribute's name
+
+
+
+ a string containing the attribute's new value
+
+
+
+ a #GFileQueryInfoFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value.
+If @attribute is of a different type, this operation will fail.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ %TRUE if the @attribute was successfully set to @value
+ in the @file, %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a string containing the attribute's name
+
+
+
+ a #gint32 containing the attribute's new value
+
+
+
+ a #GFileQueryInfoFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 to @value.
+If @attribute is of a different type, this operation will fail.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ %TRUE if the @attribute was successfully set, %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a string containing the attribute's name
+
+
+
+ a #guint64 containing the attribute's new value
+
+
+
+ a #GFileQueryInfoFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value.
+If @attribute is of a different type, this operation will fail.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ %TRUE if the @attribute was successfully set, %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a string containing the attribute's name
+
+
+
+ a string containing the attribute's value
+
+
+
+ #GFileQueryInfoFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value.
+If @attribute is of a different type, this operation will fail.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ %TRUE if the @attribute was successfully set to @value
+ in the @file, %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a string containing the attribute's name
+
+
+
+ a #guint32 containing the attribute's new value
+
+
+
+ a #GFileQueryInfoFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value.
+If @attribute is of a different type, this operation will fail.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ %TRUE if the @attribute was successfully set to @value
+ in the @file, %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a string containing the attribute's name
+
+
+
+ a #guint64 containing the attribute's new value
+
+
+
+ a #GFileQueryInfoFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Asynchronously sets the attributes of @file with @info.
+
+For more details, see g_file_set_attributes_from_info(),
+which is the synchronous version of this call.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_set_attributes_finish() to get
+the result of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ a #GFileInfo
+
+
+
+ a #GFileQueryInfoFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback
+
+
+
+ a #gpointer
+
+
+
+
+
+ Finishes setting an attribute started in g_file_set_attributes_async().
+
+
+ %TRUE if the attributes were set correctly, %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+ a #GFileInfo
+
+
+
+
+
+ Tries to set all attributes in the #GFileInfo on the target
+values, not stopping on the first error.
+
+If there is any error during this operation then @error will
+be set to the first error. Error on particular fields are flagged
+by setting the "status" field in the attribute value to
+%G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING, which means you can
+also detect further errors.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ %FALSE if there was any error, %TRUE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GFileInfo
+
+
+
+ #GFileQueryInfoFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Renames @file to the specified display name.
+
+The display name is converted from UTF-8 to the correct encoding
+for the target filesystem if possible and the @file is renamed to this.
+
+If you want to implement a rename operation in the user interface the
+edit name (%G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the
+initial value in the rename widget, and then the result after editing
+should be passed to g_file_set_display_name().
+
+On success the resulting converted filename is returned.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ a #GFile specifying what @file was renamed to,
+ or %NULL if there was an error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a string
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Asynchronously sets the display name for a given #GFile.
+
+For more details, see g_file_set_display_name() which is
+the synchronous version of this call.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_set_display_name_finish() to get
+the result of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ a string
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes setting a display name started with
+g_file_set_display_name_async().
+
+
+ a #GFile or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Starts a file of type %G_FILE_TYPE_MOUNTABLE.
+Using @start_operation, you can request callbacks when, for instance,
+passwords are needed during authentication.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_mount_mountable_finish() to get
+the result of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ flags affecting the operation
+
+
+
+ a #GMountOperation, or %NULL to avoid user interaction
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call when the request is satisfied, or %NULL
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes a start operation. See g_file_start_mountable() for details.
+
+Finish an asynchronous start operation that was started
+with g_file_start_mountable().
+
+
+ %TRUE if the operation finished successfully. %FALSE
+otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Stops a file of type %G_FILE_TYPE_MOUNTABLE.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_stop_mountable_finish() to get
+the result of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ flags affecting the operation
+
+
+
+ a #GMountOperation,
+ or %NULL to avoid user interaction.
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied, or %NULL
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes a stop operation, see g_file_stop_mountable() for details.
+
+Finish an asynchronous stop operation that was started
+with g_file_stop_mountable().
+
+
+ %TRUE if the operation finished successfully.
+ %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Checks if @file supports
+[thread-default contexts][g-main-context-push-thread-default-context].
+If this returns %FALSE, you cannot perform asynchronous operations on
+@file in a thread that has a thread-default context.
+
+
+ Whether or not @file supports thread-default contexts.
+
+
+
+
+ a #GFile
+
+
+
+
+
+ Sends @file to the "Trashcan", if possible. This is similar to
+deleting it, but the user can recover it before emptying the trashcan.
+Not all file systems support trashing, so this call can return the
+%G_IO_ERROR_NOT_SUPPORTED error. Since GLib 2.66, the `x-gvfs-notrash` unix
+mount option can be used to disable g_file_trash() support for certain
+mounts, the %G_IO_ERROR_NOT_SUPPORTED error will be returned in that case.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ %TRUE on successful trash, %FALSE otherwise.
+
+
+
+
+ #GFile to send to trash
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+ Asynchronously sends @file to the Trash location, if possible.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous file trashing operation, started with
+g_file_trash_async().
+
+
+ %TRUE on successful trash, %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Unmounts a file of type G_FILE_TYPE_MOUNTABLE.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_unmount_mountable_finish() to get
+the result of the operation.
+ Use g_file_unmount_mountable_with_operation() instead.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ flags affecting the operation
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied, or %NULL
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an unmount operation, see g_file_unmount_mountable() for details.
+
+Finish an asynchronous unmount operation that was started
+with g_file_unmount_mountable().
+ Use g_file_unmount_mountable_with_operation_finish()
+ instead.
+
+
+ %TRUE if the operation finished successfully.
+ %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Unmounts a file of type %G_FILE_TYPE_MOUNTABLE.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+When the operation is finished, @callback will be called.
+You can then call g_file_unmount_mountable_finish() to get
+the result of the operation.
+
+
+
+
+
+
+ input #GFile
+
+
+
+ flags affecting the operation
+
+
+
+ a #GMountOperation,
+ or %NULL to avoid user interaction
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied, or %NULL
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an unmount operation,
+see g_file_unmount_mountable_with_operation() for details.
+
+Finish an asynchronous unmount operation that was started
+with g_file_unmount_mountable_with_operation().
+
+
+ %TRUE if the operation finished successfully.
+ %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+ Information about a specific attribute.
+
+
+ the name of the attribute.
+
+
+
+ the #GFileAttributeType type of the attribute.
+
+
+
+ a set of #GFileAttributeInfoFlags.
+
+
+
+
+ Flags specifying the behaviour of an attribute.
+
+ no flags set.
+
+
+ copy the attribute values when the file is copied.
+
+
+ copy the attribute values when the file is moved.
+
+
+
+ Acts as a lightweight registry for possible valid file attributes.
+The registry stores Key-Value pair formats as #GFileAttributeInfos.
+
+
+ an array of #GFileAttributeInfos.
+
+
+
+ the number of values in the array.
+
+
+
+ Creates a new file attribute info list.
+
+
+ a #GFileAttributeInfoList.
+
+
+
+
+ Adds a new attribute with @name to the @list, setting
+its @type and @flags.
+
+
+
+
+
+
+ a #GFileAttributeInfoList.
+
+
+
+ the name of the attribute to add.
+
+
+
+ the #GFileAttributeType for the attribute.
+
+
+
+ #GFileAttributeInfoFlags for the attribute.
+
+
+
+
+
+ Makes a duplicate of a file attribute info list.
+
+
+ a copy of the given @list.
+
+
+
+
+ a #GFileAttributeInfoList to duplicate.
+
+
+
+
+
+ Gets the file attribute with the name @name from @list.
+
+
+ a #GFileAttributeInfo for the @name, or %NULL if an
+attribute isn't found.
+
+
+
+
+ a #GFileAttributeInfoList.
+
+
+
+ the name of the attribute to look up.
+
+
+
+
+
+ References a file attribute info list.
+
+
+ #GFileAttributeInfoList or %NULL on error.
+
+
+
+
+ a #GFileAttributeInfoList to reference.
+
+
+
+
+
+ Removes a reference from the given @list. If the reference count
+falls to zero, the @list is deleted.
+
+
+
+
+
+
+ The #GFileAttributeInfoList to unreference.
+
+
+
+
+
+
+ Determines if a string matches a file attribute.
+
+
+ Creates a new file attribute matcher, which matches attributes
+against a given string. #GFileAttributeMatchers are reference
+counted structures, and are created with a reference count of 1. If
+the number of references falls to 0, the #GFileAttributeMatcher is
+automatically destroyed.
+
+The @attributes string should be formatted with specific keys separated
+from namespaces with a double colon. Several "namespace::key" strings may be
+concatenated with a single comma (e.g. "standard::type,standard::is-hidden").
+The wildcard "*" may be used to match all keys and namespaces, or
+"namespace::*" will match all keys in a given namespace.
+
+## Examples of file attribute matcher strings and results
+
+- `"*"`: matches all attributes.
+- `"standard::is-hidden"`: matches only the key is-hidden in the
+ standard namespace.
+- `"standard::type,unix::*"`: matches the type key in the standard
+ namespace and all keys in the unix namespace.
+
+
+ a #GFileAttributeMatcher
+
+
+
+
+ an attribute string to match.
+
+
+
+
+
+ Checks if the matcher will match all of the keys in a given namespace.
+This will always return %TRUE if a wildcard character is in use (e.g. if
+matcher was created with "standard::*" and @ns is "standard", or if matcher was created
+using "*" and namespace is anything.)
+
+TODO: this is awkwardly worded.
+
+
+ %TRUE if the matcher matches all of the entries
+in the given @ns, %FALSE otherwise.
+
+
+
+
+ a #GFileAttributeMatcher.
+
+
+
+ a string containing a file attribute namespace.
+
+
+
+
+
+ Gets the next matched attribute from a #GFileAttributeMatcher.
+
+
+ a string containing the next attribute or, %NULL if
+no more attribute exist.
+
+
+
+
+ a #GFileAttributeMatcher.
+
+
+
+
+
+ Checks if an attribute will be matched by an attribute matcher. If
+the matcher was created with the "*" matching string, this function
+will always return %TRUE.
+
+
+ %TRUE if @attribute matches @matcher. %FALSE otherwise.
+
+
+
+
+ a #GFileAttributeMatcher.
+
+
+
+ a file attribute key.
+
+
+
+
+
+ Checks if an attribute matcher only matches a given attribute. Always
+returns %FALSE if "*" was used when creating the matcher.
+
+
+ %TRUE if the matcher only matches @attribute. %FALSE otherwise.
+
+
+
+
+ a #GFileAttributeMatcher.
+
+
+
+ a file attribute key.
+
+
+
+
+
+ References a file attribute matcher.
+
+
+ a #GFileAttributeMatcher.
+
+
+
+
+ a #GFileAttributeMatcher.
+
+
+
+
+
+ Subtracts all attributes of @subtract from @matcher and returns
+a matcher that supports those attributes.
+
+Note that currently it is not possible to remove a single
+attribute when the @matcher matches the whole namespace - or remove
+a namespace or attribute when the matcher matches everything. This
+is a limitation of the current implementation, but may be fixed
+in the future.
+
+
+ A file attribute matcher matching all attributes of
+ @matcher that are not matched by @subtract
+
+
+
+
+ Matcher to subtract from
+
+
+
+ The matcher to subtract
+
+
+
+
+
+ Prints what the matcher is matching against. The format will be
+equal to the format passed to g_file_attribute_matcher_new().
+The output however, might not be identical, as the matcher may
+decide to use a different order or omit needless parts.
+
+
+ a string describing the attributes the matcher matches
+ against or %NULL if @matcher was %NULL.
+
+
+
+
+ a #GFileAttributeMatcher.
+
+
+
+
+
+ Unreferences @matcher. If the reference count falls below 1,
+the @matcher is automatically freed.
+
+
+
+
+
+
+ a #GFileAttributeMatcher.
+
+
+
+
+
+
+ Used by g_file_set_attributes_from_info() when setting file attributes.
+
+ Attribute value is unset (empty).
+
+
+ Attribute value is set.
+
+
+ Indicates an error in setting the value.
+
+
+
+ The data types for file attributes.
+
+ indicates an invalid or uninitialized type.
+
+
+ a null terminated UTF8 string.
+
+
+ a zero terminated string of non-zero bytes.
+
+
+ a boolean value.
+
+
+ an unsigned 4-byte/32-bit integer.
+
+
+ a signed 4-byte/32-bit integer.
+
+
+ an unsigned 8-byte/64-bit integer.
+
+
+ a signed 8-byte/64-bit integer.
+
+
+ a #GObject.
+
+
+ a %NULL terminated char **. Since 2.22
+
+
+
+ Flags used when copying or moving files.
+
+ No flags set.
+
+
+ Overwrite any existing files
+
+
+ Make a backup of any existing files.
+
+
+ Don't follow symlinks.
+
+
+ Copy all file metadata instead of just default set used for copy (see #GFileInfo).
+
+
+ Don't use copy and delete fallback if native move not supported.
+
+
+ Leaves target file with default perms, instead of setting the source file perms.
+
+
+
+ Flags used when an operation may create a file.
+
+ No flags set.
+
+
+ Create a file that can only be
+ accessed by the current user.
+
+
+ Replace the destination
+ as if it didn't exist before. Don't try to keep any old
+ permissions, replace instead of following links. This
+ is generally useful if you're doing a "copy over"
+ rather than a "save new version of" replace operation.
+ You can think of it as "unlink destination" before
+ writing to it, although the implementation may not
+ be exactly like that. This flag can only be used with
+ g_file_replace() and its variants, including g_file_replace_contents().
+ Since 2.20
+
+
+
+ #GFileDescriptorBased is implemented by streams (implementations of
+#GInputStream or #GOutputStream) that are based on file descriptors.
+
+Note that `<gio/gfiledescriptorbased.h>` belongs to the UNIX-specific
+GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
+file when using it.
+
+
+ Gets the underlying file descriptor.
+
+
+ The file descriptor
+
+
+
+
+ a #GFileDescriptorBased.
+
+
+
+
+
+ Gets the underlying file descriptor.
+
+
+ The file descriptor
+
+
+
+
+ a #GFileDescriptorBased.
+
+
+
+
+
+
+ An interface for file descriptor based io objects.
+
+
+ The parent interface.
+
+
+
+
+
+
+ The file descriptor
+
+
+
+
+ a #GFileDescriptorBased.
+
+
+
+
+
+
+
+ #GFileEnumerator allows you to operate on a set of #GFiles,
+returning a #GFileInfo structure for each file enumerated (e.g.
+g_file_enumerate_children() will return a #GFileEnumerator for each
+of the children within a directory).
+
+To get the next file's information from a #GFileEnumerator, use
+g_file_enumerator_next_file() or its asynchronous version,
+g_file_enumerator_next_files_async(). Note that the asynchronous
+version will return a list of #GFileInfos, whereas the
+synchronous will only return the next file in the enumerator.
+
+The ordering of returned files is unspecified for non-Unix
+platforms; for more information, see g_dir_read_name(). On Unix,
+when operating on local files, returned files will be sorted by
+inode number. Effectively you can assume that the ordering of
+returned files will be stable between successive calls (and
+applications) assuming the directory is unchanged.
+
+If your application needs a specific ordering, such as by name or
+modification time, you will have to implement that in your
+application code.
+
+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().
+
+
+ Asynchronously closes the file enumerator.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned in
+g_file_enumerator_close_finish().
+
+
+
+
+
+
+ a #GFileEnumerator.
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes closing a file enumerator, started from g_file_enumerator_close_async().
+
+If the file enumerator was already closed when g_file_enumerator_close_async()
+was called, then this function will report %G_IO_ERROR_CLOSED in @error, and
+return %FALSE. If the file enumerator had pending operation when the close
+operation was started, then this function will report %G_IO_ERROR_PENDING, and
+return %FALSE. If @cancellable was not %NULL, then the operation may have been
+cancelled by triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be
+returned.
+
+
+ %TRUE if the close operation has finished successfully.
+
+
+
+
+ a #GFileEnumerator.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Returns information for the next file in the enumerated object.
+Will block until the information is available. The #GFileInfo
+returned from this function will contain attributes that match the
+attribute string that was passed when the #GFileEnumerator was created.
+
+See the documentation of #GFileEnumerator for information about the
+order of returned files.
+
+On error, returns %NULL and sets @error to the error. If the
+enumerator is at the end, %NULL will be returned and @error will
+be unset.
+
+
+ A #GFileInfo or %NULL on error
+ or end of enumerator. Free the returned object with
+ g_object_unref() when no longer needed.
+
+
+
+
+ a #GFileEnumerator.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Request information for a number of files from the enumerator asynchronously.
+When all i/o for the operation is finished the @callback will be called with
+the requested information.
+
+See the documentation of #GFileEnumerator for information about the
+order of returned files.
+
+The callback can be called with less than @num_files files in case of error
+or at the end of the enumerator. In case of a partial error the callback will
+be called with any succeeding items and no error, and on the next request the
+error will be reported. If a request is cancelled the callback will be called
+with %G_IO_ERROR_CANCELLED.
+
+During an async request no other sync and async calls are allowed, and will
+result in %G_IO_ERROR_PENDING errors.
+
+Any outstanding i/o request with higher priority (lower numerical value) will
+be executed before an outstanding request with lower priority. Default
+priority is %G_PRIORITY_DEFAULT.
+
+
+
+
+
+
+ a #GFileEnumerator.
+
+
+
+ the number of file info objects to request
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes the asynchronous operation started with g_file_enumerator_next_files_async().
+
+
+ a #GList of #GFileInfos. You must free the list with
+ g_list_free() and unref the infos with g_object_unref() when you're
+ done with them.
+
+
+
+
+
+
+ a #GFileEnumerator.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Releases all resources used by this enumerator, making the
+enumerator return %G_IO_ERROR_CLOSED on all calls.
+
+This will be automatically called when the last reference
+is dropped, but you might want to call this function to make
+sure resources are released as early as possible.
+
+
+ #TRUE on success or #FALSE on error.
+
+
+
+
+ a #GFileEnumerator.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Asynchronously closes the file enumerator.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned in
+g_file_enumerator_close_finish().
+
+
+
+
+
+
+ a #GFileEnumerator.
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes closing a file enumerator, started from g_file_enumerator_close_async().
+
+If the file enumerator was already closed when g_file_enumerator_close_async()
+was called, then this function will report %G_IO_ERROR_CLOSED in @error, and
+return %FALSE. If the file enumerator had pending operation when the close
+operation was started, then this function will report %G_IO_ERROR_PENDING, and
+return %FALSE. If @cancellable was not %NULL, then the operation may have been
+cancelled by triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be
+returned.
+
+
+ %TRUE if the close operation has finished successfully.
+
+
+
+
+ a #GFileEnumerator.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Return a new #GFile which refers to the file named by @info in the source
+directory of @enumerator. This function is primarily intended to be used
+inside loops with g_file_enumerator_next_file().
+
+To use this, %G_FILE_ATTRIBUTE_STANDARD_NAME must have been listed in the
+attributes list used when creating the #GFileEnumerator.
+
+This is a convenience method that's equivalent to:
+|[<!-- language="C" -->
+ gchar *name = g_file_info_get_name (info);
+ GFile *child = g_file_get_child (g_file_enumerator_get_container (enumr),
+ name);
+]|
+
+
+ a #GFile for the #GFileInfo passed it.
+
+
+
+
+ a #GFileEnumerator
+
+
+
+ a #GFileInfo gotten from g_file_enumerator_next_file()
+ or the async equivalents.
+
+
+
+
+
+ Get the #GFile container which is being enumerated.
+
+
+ the #GFile which is being enumerated.
+
+
+
+
+ a #GFileEnumerator
+
+
+
+
+
+ Checks if the file enumerator has pending operations.
+
+
+ %TRUE if the @enumerator has pending operations.
+
+
+
+
+ a #GFileEnumerator.
+
+
+
+
+
+ Checks if the file enumerator has been closed.
+
+
+ %TRUE if the @enumerator is closed.
+
+
+
+
+ a #GFileEnumerator.
+
+
+
+
+
+ This is a version of g_file_enumerator_next_file() that's easier to
+use correctly from C programs. With g_file_enumerator_next_file(),
+the gboolean return value signifies "end of iteration or error", which
+requires allocation of a temporary #GError.
+
+In contrast, with this function, a %FALSE return from
+g_file_enumerator_iterate() *always* means
+"error". End of iteration is signaled by @out_info or @out_child being %NULL.
+
+Another crucial difference is that the references for @out_info and
+@out_child are owned by @direnum (they are cached as hidden
+properties). You must not unref them in your own code. This makes
+memory management significantly easier for C code in combination
+with loops.
+
+Finally, this function optionally allows retrieving a #GFile as
+well.
+
+You must specify at least one of @out_info or @out_child.
+
+The code pattern for correctly using g_file_enumerator_iterate() from C
+is:
+
+|[
+direnum = g_file_enumerate_children (file, ...);
+while (TRUE)
+ {
+ GFileInfo *info;
+ if (!g_file_enumerator_iterate (direnum, &info, NULL, cancellable, error))
+ goto out;
+ if (!info)
+ break;
+ ... do stuff with "info"; do not unref it! ...
+ }
+
+out:
+ g_object_unref (direnum); // Note: frees the last @info
+]|
+
+
+
+
+
+
+ an open #GFileEnumerator
+
+
+
+ Output location for the next #GFileInfo, or %NULL
+
+
+
+ Output location for the next #GFile, or %NULL
+
+
+
+ a #GCancellable
+
+
+
+
+
+ Returns information for the next file in the enumerated object.
+Will block until the information is available. The #GFileInfo
+returned from this function will contain attributes that match the
+attribute string that was passed when the #GFileEnumerator was created.
+
+See the documentation of #GFileEnumerator for information about the
+order of returned files.
+
+On error, returns %NULL and sets @error to the error. If the
+enumerator is at the end, %NULL will be returned and @error will
+be unset.
+
+
+ A #GFileInfo or %NULL on error
+ or end of enumerator. Free the returned object with
+ g_object_unref() when no longer needed.
+
+
+
+
+ a #GFileEnumerator.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Request information for a number of files from the enumerator asynchronously.
+When all i/o for the operation is finished the @callback will be called with
+the requested information.
+
+See the documentation of #GFileEnumerator for information about the
+order of returned files.
+
+The callback can be called with less than @num_files files in case of error
+or at the end of the enumerator. In case of a partial error the callback will
+be called with any succeeding items and no error, and on the next request the
+error will be reported. If a request is cancelled the callback will be called
+with %G_IO_ERROR_CANCELLED.
+
+During an async request no other sync and async calls are allowed, and will
+result in %G_IO_ERROR_PENDING errors.
+
+Any outstanding i/o request with higher priority (lower numerical value) will
+be executed before an outstanding request with lower priority. Default
+priority is %G_PRIORITY_DEFAULT.
+
+
+
+
+
+
+ a #GFileEnumerator.
+
+
+
+ the number of file info objects to request
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes the asynchronous operation started with g_file_enumerator_next_files_async().
+
+
+ a #GList of #GFileInfos. You must free the list with
+ g_list_free() and unref the infos with g_object_unref() when you're
+ done with them.
+
+
+
+
+
+
+ a #GFileEnumerator.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Sets the file enumerator as having pending operations.
+
+
+
+
+
+
+ a #GFileEnumerator.
+
+
+
+ a boolean value.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ A #GFileInfo or %NULL on error
+ or end of enumerator. Free the returned object with
+ g_object_unref() when no longer needed.
+
+
+
+
+ a #GFileEnumerator.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GFileEnumerator.
+
+
+
+ the number of file info objects to request
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ a #GList of #GFileInfos. You must free the list with
+ g_list_free() and unref the infos with g_object_unref() when you're
+ done with them.
+
+
+
+
+
+
+ a #GFileEnumerator.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GFileEnumerator.
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ %TRUE if the close operation has finished successfully.
+
+
+
+
+ a #GFileEnumerator.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Gets the entity tag for the file when it has been written.
+This must be called after the stream has been written
+and closed, as the etag can change while writing.
+
+
+ the entity tag for the stream.
+
+
+
+
+ a #GFileIOStream.
+
+
+
+
+
+ Queries a file io stream for the given @attributes.
+This function blocks while querying the stream. For the asynchronous
+version of this function, see g_file_io_stream_query_info_async().
+While the stream is blocked, the stream will set the pending flag
+internally, and any other operations on the stream will fail with
+%G_IO_ERROR_PENDING.
+
+Can fail if the stream was already closed (with @error being set to
+%G_IO_ERROR_CLOSED), the stream has pending operations (with @error being
+set to %G_IO_ERROR_PENDING), or if querying info is not supported for
+the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). I
+all cases of failure, %NULL will be returned.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will
+be returned.
+
+
+ a #GFileInfo for the @stream, or %NULL on error.
+
+
+
+
+ a #GFileIOStream.
+
+
+
+ a file attribute query string.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Asynchronously queries the @stream for a #GFileInfo. When completed,
+@callback will be called with a #GAsyncResult which can be used to
+finish the operation with g_file_io_stream_query_info_finish().
+
+For the synchronous version of this function, see
+g_file_io_stream_query_info().
+
+
+
+
+
+
+ a #GFileIOStream.
+
+
+
+ a file attribute query string.
+
+
+
+ the [I/O priority][gio-GIOScheduler] of the request
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finalizes the asynchronous query started
+by g_file_io_stream_query_info_async().
+
+
+ A #GFileInfo for the finished query.
+
+
+
+
+ a #GFileIOStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Gets the entity tag for the file when it has been written.
+This must be called after the stream has been written
+and closed, as the etag can change while writing.
+
+
+ the entity tag for the stream.
+
+
+
+
+ a #GFileIOStream.
+
+
+
+
+
+ Queries a file io stream for the given @attributes.
+This function blocks while querying the stream. For the asynchronous
+version of this function, see g_file_io_stream_query_info_async().
+While the stream is blocked, the stream will set the pending flag
+internally, and any other operations on the stream will fail with
+%G_IO_ERROR_PENDING.
+
+Can fail if the stream was already closed (with @error being set to
+%G_IO_ERROR_CLOSED), the stream has pending operations (with @error being
+set to %G_IO_ERROR_PENDING), or if querying info is not supported for
+the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). I
+all cases of failure, %NULL will be returned.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will
+be returned.
+
+
+ a #GFileInfo for the @stream, or %NULL on error.
+
+
+
+
+ a #GFileIOStream.
+
+
+
+ a file attribute query string.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Asynchronously queries the @stream for a #GFileInfo. When completed,
+@callback will be called with a #GAsyncResult which can be used to
+finish the operation with g_file_io_stream_query_info_finish().
+
+For the synchronous version of this function, see
+g_file_io_stream_query_info().
+
+
+
+
+
+
+ a #GFileIOStream.
+
+
+
+ a file attribute query string.
+
+
+
+ the [I/O priority][gio-GIOScheduler] of the request
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finalizes the asynchronous query started
+by g_file_io_stream_query_info_async().
+
+
+ A #GFileInfo for the finished query.
+
+
+
+
+ a #GFileIOStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GFileInfo for the @stream, or %NULL on error.
+
+
+
+
+ a #GFileIOStream.
+
+
+
+ a file attribute query string.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GFileIOStream.
+
+
+
+ a file attribute query string.
+
+
+
+ the [I/O priority][gio-GIOScheduler] of the request
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ A #GFileInfo for the finished query.
+
+
+
+
+ a #GFileIOStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+ the entity tag for the stream.
+
+
+
+
+ a #GFileIOStream.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #GFileIcon specifies an icon by pointing to an image file
+to be used as icon.
+
+
+
+
+ Creates a new icon for a file.
+
+
+ a #GIcon for the given
+ @file, or %NULL on error.
+
+
+
+
+ a #GFile.
+
+
+
+
+
+ Gets the #GFile associated with the given @icon.
+
+
+ a #GFile.
+
+
+
+
+ a #GIcon.
+
+
+
+
+
+ The file containing the icon.
+
+
+
+
+
+
+
+ An interface for writing VFS file handles.
+
+
+ The parent interface.
+
+
+
+
+
+
+ a new #GFile that is a duplicate
+ of the given #GFile.
+
+
+
+
+ input #GFile
+
+
+
+
+
+
+
+
+
+ 0 if @file is not a valid #GFile, otherwise an
+ integer that can be used as hash value for the #GFile.
+ This function is intended for easily hashing a #GFile to
+ add to a #GHashTable or similar data structure.
+
+
+
+
+ #gconstpointer to a #GFile
+
+
+
+
+
+
+
+
+
+ %TRUE if @file1 and @file2 are equal.
+
+
+
+
+ the first #GFile
+
+
+
+ the second #GFile
+
+
+
+
+
+
+
+
+
+ %TRUE if @file is native
+
+
+
+
+ input #GFile
+
+
+
+
+
+
+
+
+
+ %TRUE if #GFile's backend supports the
+ given URI scheme, %FALSE if URI scheme is %NULL,
+ not supported, or #GFile is invalid.
+
+
+
+
+ input #GFile
+
+
+
+ a string containing a URI scheme
+
+
+
+
+
+
+
+
+
+ a string containing the URI scheme for the given
+ #GFile or %NULL if the #GFile was constructed with an invalid URI. The
+ returned string should be freed with g_free() when no longer needed.
+
+
+
+
+ input #GFile
+
+
+
+
+
+
+
+
+
+ string containing the #GFile's
+ base name, or %NULL if given #GFile is invalid. The returned string
+ should be freed with g_free() when no longer needed.
+
+
+
+
+ input #GFile
+
+
+
+
+
+
+
+
+
+ string containing the #GFile's path,
+ or %NULL if no such path exists. The returned string should be freed
+ with g_free() when no longer needed.
+
+
+
+
+ input #GFile
+
+
+
+
+
+
+
+
+
+ a string containing the #GFile's URI. If the #GFile was constructed
+ with an invalid URI, an invalid URI is returned.
+ The returned string should be freed with g_free()
+ when no longer needed.
+
+
+
+
+ input #GFile
+
+
+
+
+
+
+
+
+
+ a string containing the #GFile's parse name.
+ The returned string should be freed with g_free()
+ when no longer needed.
+
+
+
+
+ input #GFile
+
+
+
+
+
+
+
+
+
+ a #GFile structure to the
+ parent of the given #GFile or %NULL if there is no parent. Free
+ the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+
+
+
+
+
+
+ %TRUE if the @file's parent, grandparent, etc is @prefix,
+ %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ input #GFile
+
+
+
+
+
+
+
+
+
+ string with the relative path from
+ @descendant to @parent, or %NULL if @descendant doesn't have @parent as
+ prefix. The returned string should be freed with g_free() when
+ no longer needed.
+
+
+
+
+ input #GFile
+
+
+
+ input #GFile
+
+
+
+
+
+
+
+
+
+ a #GFile for the resolved path.
+
+
+
+
+ input #GFile
+
+
+
+ a given relative path string
+
+
+
+
+
+
+
+
+
+ a #GFile to the specified child, or
+ %NULL if the display name couldn't be converted.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ string to a possible child
+
+
+
+
+
+
+
+
+
+ A #GFileEnumerator if successful,
+ %NULL on error. Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ an attribute query string
+
+
+
+ a set of #GFileQueryInfoFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+
+
+
+
+
+
+
+
+ input #GFile
+
+
+
+ an attribute query string
+
+
+
+ a set of #GFileQueryInfoFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call when the
+ request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ a #GFileEnumerator or %NULL
+ if an error occurred.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+ a #GFileInfo for the given @file, or %NULL
+ on error. Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ an attribute query string
+
+
+
+ a set of #GFileQueryInfoFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+
+
+
+
+
+
+
+
+ input #GFile
+
+
+
+ an attribute query string
+
+
+
+ a set of #GFileQueryInfoFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call when the
+ request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ #GFileInfo for given @file
+ or %NULL on error. Free the returned object with
+ g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+ a #GFileInfo or %NULL if there was an error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ an attribute query string
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+
+
+
+
+
+
+
+
+ input #GFile
+
+
+
+ an attribute query string
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ #GFileInfo for given @file
+ or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+ a #GMount where the @file is located
+ or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GFile
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ #GMount for given @file or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+ a #GFile specifying what @file was renamed to,
+ or %NULL if there was an error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a string
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+
+
+
+
+
+
+
+
+ input #GFile
+
+
+
+ a string
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ a #GFile or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+ a #GFileAttributeInfoList describing the settable attributes.
+ When you are done with it, release it with
+ g_file_attribute_info_list_unref()
+
+
+
+
+ input #GFile
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GFileAttributeInfoList describing the writable namespaces.
+ When you are done with it, release it with
+ g_file_attribute_info_list_unref()
+
+
+
+
+ input #GFile
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ %TRUE if the attribute was set, %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a string containing the attribute's name
+
+
+
+ The type of the attribute
+
+
+
+ a pointer to the value (or the pointer
+ itself if the type is a pointer type)
+
+
+
+ a set of #GFileQueryInfoFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+
+
+
+
+ %FALSE if there was any error, %TRUE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GFileInfo
+
+
+
+ #GFileQueryInfoFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+
+
+
+
+
+
+
+
+ input #GFile
+
+
+
+ a #GFileInfo
+
+
+
+ a #GFileQueryInfoFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback
+
+
+
+ a #gpointer
+
+
+
+
+
+
+
+
+
+ %TRUE if the attributes were set correctly, %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+ a #GFileInfo
+
+
+
+
+
+
+
+
+
+ #GFileInputStream or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ #GFile to read
+
+
+
+ a #GCancellable
+
+
+
+
+
+
+
+
+
+
+
+
+
+ input #GFile
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ a #GFileInputStream or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+ a #GFileOutputStream, or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+
+
+
+
+
+
+
+
+ input #GFile
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ a valid #GFileOutputStream
+ or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ #GAsyncResult
+
+
+
+
+
+
+
+
+
+ a #GFileOutputStream for the newly created
+ file, or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+
+
+
+
+
+
+
+
+ input #GFile
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ a #GFileOutputStream or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+ a #GFileOutputStream or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ an optional [entity tag][gfile-etag]
+ for the current #GFile, or #NULL to ignore
+
+
+
+ %TRUE if a backup should be created
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+
+
+
+
+
+
+
+
+ input #GFile
+
+
+
+ an [entity tag][gfile-etag] for the current #GFile,
+ or %NULL to ignore
+
+
+
+ %TRUE if a backup should be created
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ a #GFileOutputStream, or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+ %TRUE if the file was deleted. %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+
+
+
+
+
+
+
+
+ input #GFile
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ %TRUE if the file was deleted. %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+ %TRUE on successful trash, %FALSE otherwise.
+
+
+
+
+ #GFile to send to trash
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+
+
+
+
+
+
+
+
+ input #GFile
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ %TRUE on successful trash, %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+ %TRUE on successful creation, %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+
+
+
+
+
+
+
+
+ input #GFile
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ %TRUE on successful directory creation, %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+ %TRUE on the creation of a new symlink, %FALSE otherwise.
+
+
+
+
+ a #GFile with the name of the symlink to create
+
+
+
+ a string with the path for the target
+ of the new symlink
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GFile with the name of the symlink to create
+
+
+
+ a string with the path for the target
+ of the new symlink
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ %TRUE on successful directory creation, %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+ %TRUE on success, %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ destination #GFile
+
+
+
+ set of #GFileCopyFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ function to callback with
+ progress information, or %NULL if progress information is not needed
+
+
+
+ user data to pass to @progress_callback
+
+
+
+
+
+
+
+
+
+
+
+
+
+ input #GFile
+
+
+
+ destination #GFile
+
+
+
+ set of #GFileCopyFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ function to callback with progress
+ information, or %NULL if progress information is not needed
+
+
+
+ user data to pass to @progress_callback
+
+
+
+ a #GAsyncReadyCallback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ a %TRUE on success, %FALSE on error.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+ %TRUE on successful move, %FALSE otherwise.
+
+
+
+
+ #GFile pointing to the source location
+
+
+
+ #GFile pointing to the destination location
+
+
+
+ set of #GFileCopyFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ #GFileProgressCallback
+ function for updates
+
+
+
+ gpointer to user data for
+ the callback function
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #GFile pointing to the source location
+
+
+
+ #GFile pointing to the destination location
+
+
+
+ set of #GFileCopyFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ #GFileProgressCallback
+ function for updates
+
+
+
+ gpointer to user data for
+ the callback function
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ %TRUE on successful file move, %FALSE otherwise.
+
+
+
+
+ input source #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+
+
+
+
+ input #GFile
+
+
+
+ flags affecting the operation
+
+
+
+ a #GMountOperation,
+ or %NULL to avoid user interaction
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied, or %NULL
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ a #GFile or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+
+
+
+
+ input #GFile
+
+
+
+ flags affecting the operation
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied, or %NULL
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ %TRUE if the operation finished successfully.
+ %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+
+
+
+
+ input #GFile
+
+
+
+ flags affecting the operation
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied, or %NULL
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ %TRUE if the @file was ejected successfully.
+ %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+
+
+
+
+ input #GFile
+
+
+
+ flags affecting the operation
+
+
+
+ a #GMountOperation
+ or %NULL to avoid user interaction
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied, or %NULL
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ %TRUE if successful. If an error has occurred,
+ this function will return %FALSE and set @error
+ appropriately if present.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+ a #GFileMonitor for the given @file,
+ or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a set of #GFileMonitorFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+
+
+
+
+ a #GFileMonitor for the given @file,
+ or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a set of #GFileMonitorFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+
+
+
+
+ #GFileIOStream or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ #GFile to open
+
+
+
+ a #GCancellable
+
+
+
+
+
+
+
+
+
+
+
+
+
+ input #GFile
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ a #GFileIOStream or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+ a #GFileIOStream for the newly created
+ file, or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GFile
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+
+
+
+
+
+
+
+
+ input #GFile
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ a #GFileIOStream or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+ a #GFileIOStream or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GFile
+
+
+
+ an optional [entity tag][gfile-etag]
+ for the current #GFile, or #NULL to ignore
+
+
+
+ %TRUE if a backup should be created
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+
+
+
+
+
+
+
+
+
+
+ input #GFile
+
+
+
+ an [entity tag][gfile-etag] for the current #GFile,
+ or %NULL to ignore
+
+
+
+ %TRUE if a backup should be created
+
+
+
+ a set of #GFileCreateFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ a #GFileIOStream, or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+
+
+
+
+ input #GFile
+
+
+
+ flags affecting the operation
+
+
+
+ a #GMountOperation, or %NULL to avoid user interaction
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call when the request is satisfied, or %NULL
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ %TRUE if the operation finished successfully. %FALSE
+otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+
+
+
+
+ input #GFile
+
+
+
+ flags affecting the operation
+
+
+
+ a #GMountOperation,
+ or %NULL to avoid user interaction.
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied, or %NULL
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ %TRUE if the operation finished successfully.
+ %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+ a boolean that indicates whether the #GFile implementation supports thread-default contexts. Since 2.22.
+
+
+
+
+
+
+
+
+
+
+ input #GFile
+
+
+
+ flags affecting the operation
+
+
+
+ a #GMountOperation,
+ or %NULL to avoid user interaction
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied, or %NULL
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ %TRUE if the operation finished successfully.
+ %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+
+
+
+
+ input #GFile
+
+
+
+ flags affecting the operation
+
+
+
+ a #GMountOperation,
+ or %NULL to avoid user interaction
+
+
+
+ optional #GCancellable object,
+ %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied, or %NULL
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ %TRUE if the @file was ejected successfully.
+ %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+
+
+
+
+ input #GFile
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call
+ when the request is satisfied, or %NULL
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ %TRUE if the operation finished successfully. %FALSE
+otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+ %TRUE if successful, with the out parameters set.
+ %FALSE otherwise, with @error set.
+
+
+
+
+ a #GFile
+
+
+
+ #GFileMeasureFlags
+
+
+
+ optional #GCancellable
+
+
+
+ a #GFileMeasureProgressCallback
+
+
+
+ user_data for @progress_callback
+
+
+
+ the number of bytes of disk space used
+
+
+
+ the number of directories encountered
+
+
+
+ the number of non-directories encountered
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GFile
+
+
+
+ #GFileMeasureFlags
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable
+
+
+
+ a #GFileMeasureProgressCallback
+
+
+
+ user_data for @progress_callback
+
+
+
+ a #GAsyncReadyCallback to call when complete
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ %TRUE if successful, with the out parameters set.
+ %FALSE otherwise, with @error set.
+
+
+
+
+ a #GFile
+
+
+
+ the #GAsyncResult passed to your #GAsyncReadyCallback
+
+
+
+ the number of bytes of disk space used
+
+
+
+ the number of directories encountered
+
+
+
+ the number of non-directories encountered
+
+
+
+
+
+
+
+ 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 [GFileAttribute][gio-GFileAttribute] for more information on how
+GIO handles file attributes.
+
+To obtain a #GFileInfo for a #GFile, use g_file_query_info() (or its
+async variant). To obtain a #GFileInfo for a file input or output
+stream, use g_file_input_stream_query_info() or
+g_file_output_stream_query_info() (or their async variants).
+
+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.
+
+The direct accessors, such as g_file_info_get_name(), are slightly more
+optimized than the generic attribute accessors, such as
+g_file_info_get_attribute_byte_string().This optimization will matter
+only if calling the API in a tight loop.
+
+It is an error to call these accessors without specifying their required file
+attributes when creating the #GFileInfo. Use g_file_info_has_attribute() or
+g_file_info_list_attributes() to check what attributes are specified for a
+#GFileInfo.
+
+#GFileAttributeMatcher allows for searching through a #GFileInfo for
+attributes.
+
+
+ Creates a new file info structure.
+
+
+ a #GFileInfo.
+
+
+
+
+ Clears the status information from @info.
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+
+
+ First clears all of the [GFileAttribute][gio-GFileAttribute] of @dest_info,
+and then copies all of the file attributes from @src_info to @dest_info.
+
+
+
+
+
+
+ source to copy attributes from.
+
+
+
+ destination to copy attributes to.
+
+
+
+
+
+ Duplicates a file info structure.
+
+
+ a duplicate #GFileInfo of @other.
+
+
+
+
+ a #GFileInfo.
+
+
+
+
+
+ Gets the access time of the current @info and returns it as a
+#GDateTime.
+
+It is an error to call this if the #GFileInfo does not contain
+%G_FILE_ATTRIBUTE_TIME_ACCESS. If %G_FILE_ATTRIBUTE_TIME_ACCESS_USEC is
+provided, the resulting #GDateTime will additionally have microsecond
+precision.
+
+If nanosecond precision is needed, %G_FILE_ATTRIBUTE_TIME_ACCESS_NSEC must
+be queried separately using g_file_info_get_attribute_uint32().
+
+
+ access time, or %NULL if unknown
+
+
+
+
+ a #GFileInfo.
+
+
+
+
+
+ Gets the value of an attribute, formatted as a string.
+This escapes things as needed to make the string valid
+UTF-8.
+
+
+ a UTF-8 string associated with the given @attribute, or
+ %NULL if the attribute wasn’t set.
+ When you're done with the string it must be freed with g_free().
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a file attribute key.
+
+
+
+
+
+ Gets the value of a boolean attribute. If the attribute does not
+contain a boolean value, %FALSE will be returned.
+
+
+ the boolean value contained within the attribute.
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a file attribute key.
+
+
+
+
+
+ Gets the value of a byte string attribute. If the attribute does
+not contain a byte string, %NULL will be returned.
+
+
+ the contents of the @attribute value as a byte string, or
+%NULL otherwise.
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a file attribute key.
+
+
+
+
+
+ Gets the attribute type, value and status for an attribute key.
+
+
+ %TRUE if @info has an attribute named @attribute,
+ %FALSE otherwise.
+
+
+
+
+ a #GFileInfo
+
+
+
+ a file attribute key
+
+
+
+ return location for the attribute type, or %NULL
+
+
+
+ return location for the
+ attribute value, or %NULL; the attribute value will not be %NULL
+
+
+
+ return location for the attribute status, or %NULL
+
+
+
+
+
+ Gets a signed 32-bit integer contained within the attribute. If the
+attribute does not contain a signed 32-bit integer, or is invalid,
+0 will be returned.
+
+
+ a signed 32-bit integer from the attribute.
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a file attribute key.
+
+
+
+
+
+ Gets a signed 64-bit integer contained within the attribute. If the
+attribute does not contain a signed 64-bit integer, or is invalid,
+0 will be returned.
+
+
+ a signed 64-bit integer from the attribute.
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a file attribute key.
+
+
+
+
+
+ Gets the value of a #GObject attribute. If the attribute does
+not contain a #GObject, %NULL will be returned.
+
+
+ a #GObject associated with the given @attribute,
+or %NULL otherwise.
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a file attribute key.
+
+
+
+
+
+ Gets the attribute status for an attribute key.
+
+
+ a #GFileAttributeStatus for the given @attribute, or
+ %G_FILE_ATTRIBUTE_STATUS_UNSET if the key is invalid.
+
+
+
+
+ a #GFileInfo
+
+
+
+ a file attribute key
+
+
+
+
+
+ Gets the value of a string attribute. If the attribute does
+not contain a string, %NULL will be returned.
+
+
+ the contents of the @attribute value as a UTF-8 string,
+or %NULL otherwise.
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a file attribute key.
+
+
+
+
+
+ Gets the value of a stringv attribute. If the attribute does
+not contain a stringv, %NULL will be returned.
+
+
+ the contents of the @attribute value as a stringv,
+or %NULL otherwise. Do not free. These returned strings are UTF-8.
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a file attribute key.
+
+
+
+
+
+ Gets the attribute type for an attribute key.
+
+
+ a #GFileAttributeType for the given @attribute, or
+%G_FILE_ATTRIBUTE_TYPE_INVALID if the key is not set.
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a file attribute key.
+
+
+
+
+
+ Gets an unsigned 32-bit integer contained within the attribute. If the
+attribute does not contain an unsigned 32-bit integer, or is invalid,
+0 will be returned.
+
+
+ an unsigned 32-bit integer from the attribute.
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a file attribute key.
+
+
+
+
+
+ Gets a unsigned 64-bit integer contained within the attribute. If the
+attribute does not contain an unsigned 64-bit integer, or is invalid,
+0 will be returned.
+
+
+ a unsigned 64-bit integer from the attribute.
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a file attribute key.
+
+
+
+
+
+ Gets the file's content type.
+
+It is an error to call this if the #GFileInfo does not contain
+%G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE.
+
+
+ a string containing the file's content type,
+or %NULL if unknown.
+
+
+
+
+ a #GFileInfo.
+
+
+
+
+
+ Gets the creation time of the current @info and returns it as a
+#GDateTime.
+
+It is an error to call this if the #GFileInfo does not contain
+%G_FILE_ATTRIBUTE_TIME_CREATED. If %G_FILE_ATTRIBUTE_TIME_CREATED_USEC is
+provided, the resulting #GDateTime will additionally have microsecond
+precision.
+
+If nanosecond precision is needed, %G_FILE_ATTRIBUTE_TIME_CREATED_NSEC must
+be queried separately using g_file_info_get_attribute_uint32().
+
+
+ creation time, or %NULL if unknown
+
+
+
+
+ a #GFileInfo.
+
+
+
+
+
+ Returns the #GDateTime representing the deletion date of the file, as
+available in %G_FILE_ATTRIBUTE_TRASH_DELETION_DATE. If the
+%G_FILE_ATTRIBUTE_TRASH_DELETION_DATE attribute is unset, %NULL is returned.
+
+
+ a #GDateTime, or %NULL.
+
+
+
+
+ a #GFileInfo.
+
+
+
+
+
+ Gets a display name for a file. This is guaranteed to always be set.
+
+It is an error to call this if the #GFileInfo does not contain
+%G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME.
+
+
+ a string containing the display name.
+
+
+
+
+ a #GFileInfo.
+
+
+
+
+
+ Gets the edit name for a file.
+
+It is an error to call this if the #GFileInfo does not contain
+%G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME.
+
+
+ a string containing the edit name.
+
+
+
+
+ a #GFileInfo.
+
+
+
+
+
+ Gets the [entity tag][gfile-etag] for a given
+#GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE.
+
+It is an error to call this if the #GFileInfo does not contain
+%G_FILE_ATTRIBUTE_ETAG_VALUE.
+
+
+ a string containing the value of the "etag:value" attribute.
+
+
+
+
+ a #GFileInfo.
+
+
+
+
+
+ Gets a file's type (whether it is a regular file, symlink, etc).
+This is different from the file's content type, see g_file_info_get_content_type().
+
+It is an error to call this if the #GFileInfo does not contain
+%G_FILE_ATTRIBUTE_STANDARD_TYPE.
+
+
+ a #GFileType for the given file.
+
+
+
+
+ a #GFileInfo.
+
+
+
+
+
+ Gets the icon for a file.
+
+It is an error to call this if the #GFileInfo does not contain
+%G_FILE_ATTRIBUTE_STANDARD_ICON.
+
+
+ #GIcon for the given @info.
+
+
+
+
+ a #GFileInfo.
+
+
+
+
+
+ Checks if a file is a backup file.
+
+It is an error to call this if the #GFileInfo does not contain
+%G_FILE_ATTRIBUTE_STANDARD_IS_BACKUP.
+
+
+ %TRUE if file is a backup file, %FALSE otherwise.
+
+
+
+
+ a #GFileInfo.
+
+
+
+
+
+ Checks if a file is hidden.
+
+It is an error to call this if the #GFileInfo does not contain
+%G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN.
+
+
+ %TRUE if the file is a hidden file, %FALSE otherwise.
+
+
+
+
+ a #GFileInfo.
+
+
+
+
+
+ Checks if a file is a symlink.
+
+It is an error to call this if the #GFileInfo does not contain
+%G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK.
+
+
+ %TRUE if the given @info is a symlink.
+
+
+
+
+ a #GFileInfo.
+
+
+
+
+
+ Gets the modification time of the current @info and returns it as a
+#GDateTime.
+
+It is an error to call this if the #GFileInfo does not contain
+%G_FILE_ATTRIBUTE_TIME_MODIFIED. If %G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC is
+provided, the resulting #GDateTime will additionally have microsecond
+precision.
+
+If nanosecond precision is needed, %G_FILE_ATTRIBUTE_TIME_MODIFIED_NSEC must
+be queried separately using g_file_info_get_attribute_uint32().
+
+
+ modification time, or %NULL if unknown
+
+
+
+
+ a #GFileInfo.
+
+
+
+
+
+ Gets the modification time of the current @info and sets it
+in @result.
+
+It is an error to call this if the #GFileInfo does not contain
+%G_FILE_ATTRIBUTE_TIME_MODIFIED. If %G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC is
+provided it will be used too.
+ Use g_file_info_get_modification_date_time() instead, as
+ #GTimeVal is deprecated due to the year 2038 problem.
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a #GTimeVal.
+
+
+
+
+
+ Gets the name for a file. This is guaranteed to always be set.
+
+It is an error to call this if the #GFileInfo does not contain
+%G_FILE_ATTRIBUTE_STANDARD_NAME.
+
+
+ a string containing the file name.
+
+
+
+
+ a #GFileInfo.
+
+
+
+
+
+ Gets the file's size (in bytes). The size is retrieved through the value of
+the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute and is converted
+from #guint64 to #goffset before returning the result.
+
+It is an error to call this if the #GFileInfo does not contain
+%G_FILE_ATTRIBUTE_STANDARD_SIZE.
+
+
+ a #goffset containing the file's size (in bytes).
+
+
+
+
+ a #GFileInfo.
+
+
+
+
+
+ Gets the value of the sort_order attribute from the #GFileInfo.
+See %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER.
+
+It is an error to call this if the #GFileInfo does not contain
+%G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER.
+
+
+ a #gint32 containing the value of the "standard::sort_order" attribute.
+
+
+
+
+ a #GFileInfo.
+
+
+
+
+
+ Gets the symbolic icon for a file.
+
+It is an error to call this if the #GFileInfo does not contain
+%G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON.
+
+
+ #GIcon for the given @info.
+
+
+
+
+ a #GFileInfo.
+
+
+
+
+
+ Gets the symlink target for a given #GFileInfo.
+
+It is an error to call this if the #GFileInfo does not contain
+%G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET.
+
+
+ a string containing the symlink target.
+
+
+
+
+ a #GFileInfo.
+
+
+
+
+
+ Checks if a file info structure has an attribute named @attribute.
+
+
+ %TRUE if @info has an attribute named @attribute,
+ %FALSE otherwise.
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a file attribute key.
+
+
+
+
+
+ Checks if a file info structure has an attribute in the
+specified @name_space.
+
+
+ %TRUE if @info has an attribute in @name_space,
+ %FALSE otherwise.
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a file attribute namespace.
+
+
+
+
+
+ Lists the file info structure's attributes.
+
+
+ a
+null-terminated array of strings of all of the possible attribute
+types for the given @name_space, or %NULL on error.
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a file attribute key's namespace, or %NULL to list
+ all attributes.
+
+
+
+
+
+ Removes all cases of @attribute from @info if it exists.
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a file attribute key.
+
+
+
+
+
+ Sets the %G_FILE_ATTRIBUTE_TIME_ACCESS and
+%G_FILE_ATTRIBUTE_TIME_ACCESS_USEC attributes in the file info to the
+given date/time value.
+
+%G_FILE_ATTRIBUTE_TIME_ACCESS_NSEC will be cleared.
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a #GDateTime.
+
+
+
+
+
+ Sets the @attribute to contain the given value, if possible. To unset the
+attribute, use %G_FILE_ATTRIBUTE_TYPE_INVALID for @type.
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a file attribute key.
+
+
+
+ a #GFileAttributeType
+
+
+
+ pointer to the value
+
+
+
+
+
+ Sets the @attribute to contain the given @attr_value,
+if possible.
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a file attribute key.
+
+
+
+ a boolean value.
+
+
+
+
+
+ Sets the @attribute to contain the given @attr_value,
+if possible.
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a file attribute key.
+
+
+
+ a byte string.
+
+
+
+
+
+ Sets the @attribute to contain the given @attr_value,
+if possible.
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a file attribute key.
+
+
+
+ a signed 32-bit integer
+
+
+
+
+
+ Sets the @attribute to contain the given @attr_value,
+if possible.
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ attribute name to set.
+
+
+
+ int64 value to set attribute to.
+
+
+
+
+
+ Sets @mask on @info to match specific attribute types.
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a #GFileAttributeMatcher.
+
+
+
+
+
+ Sets the @attribute to contain the given @attr_value,
+if possible.
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a file attribute key.
+
+
+
+ a #GObject.
+
+
+
+
+
+ Sets the attribute status for an attribute key. This is only
+needed by external code that implement g_file_set_attributes_from_info()
+or similar functions.
+
+The attribute must exist in @info for this to work. Otherwise %FALSE
+is returned and @info is unchanged.
+
+
+ %TRUE if the status was changed, %FALSE if the key was not set.
+
+
+
+
+ a #GFileInfo
+
+
+
+ a file attribute key
+
+
+
+ a #GFileAttributeStatus
+
+
+
+
+
+ Sets the @attribute to contain the given @attr_value,
+if possible.
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a file attribute key.
+
+
+
+ a UTF-8 string.
+
+
+
+
+
+ Sets the @attribute to contain the given @attr_value,
+if possible.
+
+Sinze: 2.22
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a file attribute key
+
+
+
+ a %NULL
+ terminated array of UTF-8 strings.
+
+
+
+
+
+
+
+ Sets the @attribute to contain the given @attr_value,
+if possible.
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a file attribute key.
+
+
+
+ an unsigned 32-bit integer.
+
+
+
+
+
+ Sets the @attribute to contain the given @attr_value,
+if possible.
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a file attribute key.
+
+
+
+ an unsigned 64-bit integer.
+
+
+
+
+
+ Sets the content type attribute for a given #GFileInfo.
+See %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE.
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a content type. See [GContentType][gio-GContentType]
+
+
+
+
+
+ Sets the %G_FILE_ATTRIBUTE_TIME_CREATED and
+%G_FILE_ATTRIBUTE_TIME_CREATED_USEC attributes in the file info to the
+given date/time value.
+
+%G_FILE_ATTRIBUTE_TIME_CREATED_NSEC will be cleared.
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a #GDateTime.
+
+
+
+
+
+ Sets the display name for the current #GFileInfo.
+See %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME.
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a string containing a display name.
+
+
+
+
+
+ Sets the edit name for the current file.
+See %G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME.
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a string containing an edit name.
+
+
+
+
+
+ Sets the file type in a #GFileInfo to @type.
+See %G_FILE_ATTRIBUTE_STANDARD_TYPE.
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a #GFileType.
+
+
+
+
+
+ Sets the icon for a given #GFileInfo.
+See %G_FILE_ATTRIBUTE_STANDARD_ICON.
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a #GIcon.
+
+
+
+
+
+ Sets the "is_hidden" attribute in a #GFileInfo according to @is_hidden.
+See %G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN.
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a #gboolean.
+
+
+
+
+
+ Sets the "is_symlink" attribute in a #GFileInfo according to @is_symlink.
+See %G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK.
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a #gboolean.
+
+
+
+
+
+ Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED and
+%G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC attributes in the file info to the
+given date/time value.
+
+%G_FILE_ATTRIBUTE_TIME_MODIFIED_NSEC will be cleared.
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a #GDateTime.
+
+
+
+
+
+ Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED and
+%G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC attributes in the file info to the
+given time value.
+
+%G_FILE_ATTRIBUTE_TIME_MODIFIED_NSEC will be cleared.
+ Use g_file_info_set_modification_date_time() instead, as
+ #GTimeVal is deprecated due to the year 2038 problem.
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a #GTimeVal.
+
+
+
+
+
+ Sets the name attribute for the current #GFileInfo.
+See %G_FILE_ATTRIBUTE_STANDARD_NAME.
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a string containing a name.
+
+
+
+
+
+ Sets the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute in the file info
+to the given size.
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a #goffset containing the file's size.
+
+
+
+
+
+ Sets the sort order attribute in the file info structure. See
+%G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER.
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a sort order integer.
+
+
+
+
+
+ Sets the symbolic icon for a given #GFileInfo.
+See %G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON.
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a #GIcon.
+
+
+
+
+
+ Sets the %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET attribute in the file info
+to the given symlink target.
+
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a static string containing a path to a symlink target.
+
+
+
+
+
+ Unsets a mask set by g_file_info_set_attribute_mask(), if one
+is set.
+
+
+
+
+
+
+ #GFileInfo.
+
+
+
+
+
+
+
+
+
+ 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_can_seek().
+To position a file input stream, use g_seekable_seek().
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Queries a file input stream the given @attributes. This function blocks
+while querying the stream. For the asynchronous (non-blocking) version
+of this function, see g_file_input_stream_query_info_async(). While the
+stream is blocked, the stream will set the pending flag internally, and
+any other operations on the stream will fail with %G_IO_ERROR_PENDING.
+
+
+ a #GFileInfo, or %NULL on error.
+
+
+
+
+ a #GFileInputStream.
+
+
+
+ a file attribute query string.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Queries the stream information asynchronously.
+When the operation is finished @callback will be called.
+You can then call g_file_input_stream_query_info_finish()
+to get the result of the operation.
+
+For the synchronous version of this function,
+see g_file_input_stream_query_info().
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be set
+
+
+
+
+
+
+ a #GFileInputStream.
+
+
+
+ a file attribute query string.
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous info query operation.
+
+
+ #GFileInfo.
+
+
+
+
+ a #GFileInputStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Queries a file input stream the given @attributes. This function blocks
+while querying the stream. For the asynchronous (non-blocking) version
+of this function, see g_file_input_stream_query_info_async(). While the
+stream is blocked, the stream will set the pending flag internally, and
+any other operations on the stream will fail with %G_IO_ERROR_PENDING.
+
+
+ a #GFileInfo, or %NULL on error.
+
+
+
+
+ a #GFileInputStream.
+
+
+
+ a file attribute query string.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Queries the stream information asynchronously.
+When the operation is finished @callback will be called.
+You can then call g_file_input_stream_query_info_finish()
+to get the result of the operation.
+
+For the synchronous version of this function,
+see g_file_input_stream_query_info().
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be set
+
+
+
+
+
+
+ a #GFileInputStream.
+
+
+
+ a file attribute query string.
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous info query operation.
+
+
+ #GFileInfo.
+
+
+
+
+ a #GFileInputStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GFileInfo, or %NULL on error.
+
+
+
+
+ a #GFileInputStream.
+
+
+
+ a file attribute query string.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GFileInputStream.
+
+
+
+ a file attribute query string.
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ #GFileInfo.
+
+
+
+
+ a #GFileInputStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Flags that can be used with g_file_measure_disk_usage().
+
+ No flags set.
+
+
+ Report any error encountered
+ while traversing the directory tree. Normally errors are only
+ reported for the toplevel file.
+
+
+ Tally usage based on apparent file
+ sizes. Normally, the block-size is used, if available, as this is a
+ more accurate representation of disk space used.
+ Compare with `du --apparent-size`.
+
+
+ Do not cross mount point boundaries.
+ Compare with `du -x`.
+
+
+
+ This callback type is used by g_file_measure_disk_usage() to make
+periodic progress reports when measuring the amount of disk spaced
+used by a directory.
+
+These calls are made on a best-effort basis and not all types of
+#GFile will support them. At the minimum, however, one call will
+always be made immediately.
+
+In the case that there is no support, @reporting will be set to
+%FALSE (and the other values undefined) and no further calls will be
+made. Otherwise, the @reporting will be %TRUE and the other values
+all-zeros during the first (immediate) call. In this way, you can
+know which type of progress UI to show without a delay.
+
+For g_file_measure_disk_usage() the callback is made directly. For
+g_file_measure_disk_usage_async() the callback is made via the
+default main context of the calling thread (ie: the same way that the
+final async result would be reported).
+
+@current_size is in the same units as requested by the operation (see
+%G_FILE_MEASURE_APPARENT_SIZE).
+
+The frequency of the updates is implementation defined, but is
+ideally about once every 200ms.
+
+The last progress callback may or may not be equal to the final
+result. Always check the async result to get the final value.
+
+
+
+
+
+
+ %TRUE if more reports will come
+
+
+
+ the current cumulative size measurement
+
+
+
+ the number of directories visited so far
+
+
+
+ the number of non-directory files encountered
+
+
+
+ the data passed to the original request for this callback
+
+
+
+
+
+ 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
+[thread-default main context][g-main-context-push-thread-default]
+of the thread that the monitor was created in
+(though if the global default main context is blocked, this may
+cause notifications to be blocked even if the thread-default
+context is still running).
+
+
+ Cancels a file monitor.
+
+
+ always %TRUE
+
+
+
+
+ a #GFileMonitor.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Cancels a file monitor.
+
+
+ always %TRUE
+
+
+
+
+ a #GFileMonitor.
+
+
+
+
+
+ Emits the #GFileMonitor::changed signal if a change
+has taken place. Should be called from file monitor
+implementations only.
+
+Implementations are responsible to call this method from the
+[thread-default main context][g-main-context-push-thread-default] of the
+thread that the monitor was created in.
+
+
+
+
+
+
+ a #GFileMonitor.
+
+
+
+ a #GFile.
+
+
+
+ a #GFile.
+
+
+
+ a set of #GFileMonitorEvent flags.
+
+
+
+
+
+ Returns whether the monitor is canceled.
+
+
+ %TRUE if monitor is canceled. %FALSE otherwise.
+
+
+
+
+ a #GFileMonitor
+
+
+
+
+
+ Sets the rate limit to which the @monitor will report
+consecutive change events to the same file.
+
+
+
+
+
+
+ a #GFileMonitor.
+
+
+
+ a non-negative integer with the limit in milliseconds
+ to poll for changes
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Emitted when @file has been changed.
+
+If using %G_FILE_MONITOR_WATCH_MOVES on a directory monitor, and
+the information is available (and if supported by the backend),
+@event_type may be %G_FILE_MONITOR_EVENT_RENAMED,
+%G_FILE_MONITOR_EVENT_MOVED_IN or %G_FILE_MONITOR_EVENT_MOVED_OUT.
+
+In all cases @file will be a child of the monitored directory. For
+renames, @file will be the old name and @other_file is the new
+name. For "moved in" events, @file is the name of the file that
+appeared and @other_file is the old name that it was moved from (in
+another directory). For "moved out" events, @file is the name of
+the file that used to be in this directory and @other_file is the
+name of the file at its new location.
+
+It makes sense to treat %G_FILE_MONITOR_EVENT_MOVED_IN as
+equivalent to %G_FILE_MONITOR_EVENT_CREATED and
+%G_FILE_MONITOR_EVENT_MOVED_OUT as equivalent to
+%G_FILE_MONITOR_EVENT_DELETED, with extra information.
+%G_FILE_MONITOR_EVENT_RENAMED is equivalent to a delete/create
+pair. This is exactly how the events will be reported in the case
+that the %G_FILE_MONITOR_WATCH_MOVES flag is not in use.
+
+If using the deprecated flag %G_FILE_MONITOR_SEND_MOVED flag and @event_type is
+%G_FILE_MONITOR_EVENT_MOVED, @file will be set to a #GFile containing the
+old path, and @other_file will be set to a #GFile containing the new path.
+
+In all the other cases, @other_file will be set to #NULL.
+
+
+
+
+
+ a #GFile.
+
+
+
+ a #GFile or #NULL.
+
+
+
+ a #GFileMonitorEvent.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ always %TRUE
+
+
+
+
+ a #GFileMonitor.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Specifies what type of event a monitor event is.
+
+ a file changed.
+
+
+ a hint that this was probably the last change in a set of changes.
+
+
+ a file was deleted.
+
+
+ a file was created.
+
+
+ a file attribute was changed.
+
+
+ the file location will soon be unmounted.
+
+
+ the file location was unmounted.
+
+
+ the file was moved -- only sent if the
+ (deprecated) %G_FILE_MONITOR_SEND_MOVED flag is set
+
+
+ the file was renamed within the
+ current directory -- only sent if the %G_FILE_MONITOR_WATCH_MOVES
+ flag is set. Since: 2.46.
+
+
+ the file was moved into the
+ monitored directory from another location -- only sent if the
+ %G_FILE_MONITOR_WATCH_MOVES flag is set. Since: 2.46.
+
+
+ the file was moved out of the
+ monitored directory to another location -- only sent if the
+ %G_FILE_MONITOR_WATCH_MOVES flag is set. Since: 2.46
+
+
+
+ Flags used to set what a #GFileMonitor will watch for.
+
+ No flags set.
+
+
+ Watch for mount events.
+
+
+ Pair DELETED and CREATED events caused
+ by file renames (moves) and send a single G_FILE_MONITOR_EVENT_MOVED
+ event instead (NB: not supported on all backends; the default
+ behaviour -without specifying this flag- is to send single DELETED
+ and CREATED events). Deprecated since 2.46: use
+ %G_FILE_MONITOR_WATCH_MOVES instead.
+
+
+ Watch for changes to the file made
+ via another hard link. Since 2.36.
+
+
+ Watch for rename operations on a
+ monitored directory. This causes %G_FILE_MONITOR_EVENT_RENAMED,
+ %G_FILE_MONITOR_EVENT_MOVED_IN and %G_FILE_MONITOR_EVENT_MOVED_OUT
+ events to be emitted when possible. Since: 2.46.
+
+
+
+
+
+
+ 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().
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Gets the entity tag for the file when it has been written.
+This must be called after the stream has been written
+and closed, as the etag can change while writing.
+
+
+ the entity tag for the stream.
+
+
+
+
+ a #GFileOutputStream.
+
+
+
+
+
+ Queries a file output stream for the given @attributes.
+This function blocks while querying the stream. For the asynchronous
+version of this function, see g_file_output_stream_query_info_async().
+While the stream is blocked, the stream will set the pending flag
+internally, and any other operations on the stream will fail with
+%G_IO_ERROR_PENDING.
+
+Can fail if the stream was already closed (with @error being set to
+%G_IO_ERROR_CLOSED), the stream has pending operations (with @error being
+set to %G_IO_ERROR_PENDING), or if querying info is not supported for
+the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). In
+all cases of failure, %NULL will be returned.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will
+be returned.
+
+
+ a #GFileInfo for the @stream, or %NULL on error.
+
+
+
+
+ a #GFileOutputStream.
+
+
+
+ a file attribute query string.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Asynchronously queries the @stream for a #GFileInfo. When completed,
+@callback will be called with a #GAsyncResult which can be used to
+finish the operation with g_file_output_stream_query_info_finish().
+
+For the synchronous version of this function, see
+g_file_output_stream_query_info().
+
+
+
+
+
+
+ a #GFileOutputStream.
+
+
+
+ a file attribute query string.
+
+
+
+ the [I/O priority][gio-GIOScheduler] of the request
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finalizes the asynchronous query started
+by g_file_output_stream_query_info_async().
+
+
+ A #GFileInfo for the finished query.
+
+
+
+
+ a #GFileOutputStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Gets the entity tag for the file when it has been written.
+This must be called after the stream has been written
+and closed, as the etag can change while writing.
+
+
+ the entity tag for the stream.
+
+
+
+
+ a #GFileOutputStream.
+
+
+
+
+
+ Queries a file output stream for the given @attributes.
+This function blocks while querying the stream. For the asynchronous
+version of this function, see g_file_output_stream_query_info_async().
+While the stream is blocked, the stream will set the pending flag
+internally, and any other operations on the stream will fail with
+%G_IO_ERROR_PENDING.
+
+Can fail if the stream was already closed (with @error being set to
+%G_IO_ERROR_CLOSED), the stream has pending operations (with @error being
+set to %G_IO_ERROR_PENDING), or if querying info is not supported for
+the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). In
+all cases of failure, %NULL will be returned.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will
+be returned.
+
+
+ a #GFileInfo for the @stream, or %NULL on error.
+
+
+
+
+ a #GFileOutputStream.
+
+
+
+ a file attribute query string.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Asynchronously queries the @stream for a #GFileInfo. When completed,
+@callback will be called with a #GAsyncResult which can be used to
+finish the operation with g_file_output_stream_query_info_finish().
+
+For the synchronous version of this function, see
+g_file_output_stream_query_info().
+
+
+
+
+
+
+ a #GFileOutputStream.
+
+
+
+ a file attribute query string.
+
+
+
+ the [I/O priority][gio-GIOScheduler] of the request
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finalizes the asynchronous query started
+by g_file_output_stream_query_info_async().
+
+
+ A #GFileInfo for the finished query.
+
+
+
+
+ a #GFileOutputStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GFileInfo for the @stream, or %NULL on error.
+
+
+
+
+ a #GFileOutputStream.
+
+
+
+ a file attribute query string.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GFileOutputStream.
+
+
+
+ a file attribute query string.
+
+
+
+ the [I/O priority][gio-GIOScheduler] of the request
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ A #GFileInfo for the finished query.
+
+
+
+
+ a #GFileOutputStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+ the entity tag for the stream.
+
+
+
+
+ a #GFileOutputStream.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+ the current number of bytes in the operation.
+
+
+
+ the total number of bytes in the operation.
+
+
+
+ user data passed to the callback.
+
+
+
+
+
+ Flags used when querying a #GFileInfo.
+
+ No flags set.
+
+
+ Don't follow symlinks.
+
+
+
+ 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.
+
+
+ %TRUE if more data should be read back. %FALSE otherwise.
+
+
+
+
+ the data as currently read.
+
+
+
+ the size of the data currently read.
+
+
+
+ data passed to the callback.
+
+
+
+
+
+ Indicates the file's on-disk type.
+
+On Windows systems a file will never have %G_FILE_TYPE_SYMBOLIC_LINK type;
+use #GFileInfo and %G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK to determine
+whether a file is a symlink or not. This is due to the fact that NTFS does
+not have a single filesystem object type for symbolic links - it has
+files that symlink to files, and directories that symlink to directories.
+#GFileType enumeration cannot precisely represent this important distinction,
+which is why all Windows symlinks will continue to be reported as
+%G_FILE_TYPE_REGULAR or %G_FILE_TYPE_DIRECTORY.
+
+ File's type is unknown.
+
+
+ File handle represents a regular file.
+
+
+ File handle represents a directory.
+
+
+ File handle represents a symbolic link
+ (Unix systems).
+
+
+ File is a "special" file, such as a socket, fifo,
+ block device, or character device.
+
+
+ File is a shortcut (Windows systems).
+
+
+ File is a mountable location.
+
+
+
+ Completes partial file and directory names given a partial string by
+looking in the file system for clues. Can return a list of possible
+completion strings for widget implementations.
+
+
+ Creates a new filename completer.
+
+
+ a #GFilenameCompleter.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Obtains a completion for @initial_text from @completer.
+
+
+ a completed string, or %NULL if no
+ completion exists. This string is not owned by GIO, so remember to g_free()
+ it when finished.
+
+
+
+
+ the filename completer.
+
+
+
+ text to be completed.
+
+
+
+
+
+ Gets an array of completion strings for a given initial text.
+
+
+ array of strings with possible completions for @initial_text.
+This array must be freed by g_strfreev() when finished.
+
+
+
+
+
+
+ the filename completer.
+
+
+
+ text to be completed.
+
+
+
+
+
+ If @dirs_only is %TRUE, @completer will only
+complete directory names, and not file names.
+
+
+
+
+
+
+ the filename completer.
+
+
+
+ a #gboolean.
+
+
+
+
+
+ Emitted when the file name completion information comes available.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Indicates a hint from the file system whether files should be
+previewed in a file manager. Returned as the value of the key
+%G_FILE_ATTRIBUTE_FILESYSTEM_USE_PREVIEW.
+
+ Only preview files if user has explicitly requested it.
+
+
+ Preview files if user has requested preview of "local" files.
+
+
+ Never preview files.
+
+
+
+ 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.
+
+
+ Gets the base stream for the filter stream.
+
+
+ a #GInputStream.
+
+
+
+
+ a #GFilterInputStream.
+
+
+
+
+
+ Returns whether the base stream will be closed when @stream is
+closed.
+
+
+ %TRUE if the base stream will be closed.
+
+
+
+
+ a #GFilterInputStream.
+
+
+
+
+
+ Sets whether the base stream will be closed when @stream is closed.
+
+
+
+
+
+
+ a #GFilterInputStream.
+
+
+
+ %TRUE to close the base stream.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+
+ Gets the base stream for the filter stream.
+
+
+ a #GOutputStream.
+
+
+
+
+ a #GFilterOutputStream.
+
+
+
+
+
+ Returns whether the base stream will be closed when @stream is
+closed.
+
+
+ %TRUE if the base stream will be closed.
+
+
+
+
+ a #GFilterOutputStream.
+
+
+
+
+
+ Sets whether the base stream will be closed when @stream is closed.
+
+
+
+
+
+
+ a #GFilterOutputStream.
+
+
+
+ %TRUE to close the base stream.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Error codes returned by GIO functions.
+
+Note that this domain may be extended in future GLib releases. In
+general, new error codes either only apply to new APIs, or else
+replace %G_IO_ERROR_FAILED in cases that were not explicitly
+distinguished before. You should therefore avoid writing code like
+|[<!-- language="C" -->
+if (g_error_matches (error, G_IO_ERROR, G_IO_ERROR_FAILED))
+ {
+ // Assume that this is EPRINTERONFIRE
+ ...
+ }
+]|
+but should instead treat all unrecognized error codes the same as
+%G_IO_ERROR_FAILED.
+
+See also #GPollableReturn for a cheaper way of returning
+%G_IO_ERROR_WOULD_BLOCK to callers without allocating a #GError.
+
+ Generic error condition for when an operation fails
+ and no more specific #GIOErrorEnum value is defined.
+
+
+ File not found.
+
+
+ File already exists.
+
+
+ File is a directory.
+
+
+ File is not a directory.
+
+
+ File is a directory that isn't empty.
+
+
+ File is not a regular file.
+
+
+ File is not a symbolic link.
+
+
+ File cannot be mounted.
+
+
+ Filename is too many characters.
+
+
+ Filename is invalid or contains invalid characters.
+
+
+ File contains too many symbolic links.
+
+
+ No space left on drive.
+
+
+ Invalid argument.
+
+
+ Permission denied.
+
+
+ Operation (or one of its parameters) not supported
+
+
+ File isn't mounted.
+
+
+ File is already mounted.
+
+
+ File was closed.
+
+
+ Operation was cancelled. See #GCancellable.
+
+
+ Operations are still pending.
+
+
+ File is read only.
+
+
+ Backup couldn't be created.
+
+
+ File's Entity Tag was incorrect.
+
+
+ Operation timed out.
+
+
+ Operation would be recursive.
+
+
+ File is busy.
+
+
+ Operation would block.
+
+
+ Host couldn't be found (remote operations).
+
+
+ Operation would merge files.
+
+
+ Operation failed and a helper program has
+ already interacted with the user. Do not display any error dialog.
+
+
+ The current process has too many files
+ open and can't open any more. Duplicate descriptors do count toward
+ this limit. Since 2.20
+
+
+ The object has not been initialized. Since 2.22
+
+
+ The requested address is already in use. Since 2.22
+
+
+ Need more input to finish operation. Since 2.24
+
+
+ The input data was invalid. Since 2.24
+
+
+ A remote object generated an error that
+ doesn't correspond to a locally registered #GError error
+ domain. Use g_dbus_error_get_remote_error() to extract the D-Bus
+ error name and g_dbus_error_strip_remote_error() to fix up the
+ message so it matches what was received on the wire. Since 2.26.
+
+
+ Host unreachable. Since 2.26
+
+
+ Network unreachable. Since 2.26
+
+
+ Connection refused. Since 2.26
+
+
+ Connection to proxy server failed. Since 2.26
+
+
+ Proxy authentication failed. Since 2.26
+
+
+ Proxy server needs authentication. Since 2.26
+
+
+ Proxy connection is not allowed by ruleset.
+ Since 2.26
+
+
+ Broken pipe. Since 2.36
+
+
+ Connection closed by peer. Note that this
+ is the same code as %G_IO_ERROR_BROKEN_PIPE; before 2.44 some
+ "connection closed" errors returned %G_IO_ERROR_BROKEN_PIPE, but others
+ returned %G_IO_ERROR_FAILED. Now they should all return the same
+ value, which has this more logical name. Since 2.44.
+
+
+ Transport endpoint is not connected. Since 2.44
+
+
+ Message too large. Since 2.48.
+
+
+ No such device found. Since 2.74
+
+
+
+ #GIOExtension is an opaque data structure and can only be accessed
+using the following functions.
+
+
+ Gets the name under which @extension was registered.
+
+Note that the same type may be registered as extension
+for multiple extension points, under different names.
+
+
+ the name of @extension.
+
+
+
+
+ a #GIOExtension
+
+
+
+
+
+ Gets the priority with which @extension was registered.
+
+
+ the priority of @extension
+
+
+
+
+ a #GIOExtension
+
+
+
+
+
+ Gets the type associated with @extension.
+
+
+ the type of @extension
+
+
+
+
+ a #GIOExtension
+
+
+
+
+
+ Gets a reference to the class for the type that is
+associated with @extension.
+
+
+ the #GTypeClass for the type of @extension
+
+
+
+
+ a #GIOExtension
+
+
+
+
+
+
+ #GIOExtensionPoint is an opaque data structure and can only be accessed
+using the following functions.
+
+
+ Finds a #GIOExtension for an extension point by name.
+
+
+ the #GIOExtension for @extension_point that has the
+ given name, or %NULL if there is no extension with that name
+
+
+
+
+ a #GIOExtensionPoint
+
+
+
+ the name of the extension to get
+
+
+
+
+
+ Gets a list of all extensions that implement this extension point.
+The list is sorted by priority, beginning with the highest priority.
+
+
+ a #GList of
+ #GIOExtensions. The list is owned by GIO and should not be
+ modified.
+
+
+
+
+
+
+ a #GIOExtensionPoint
+
+
+
+
+
+ Gets the required type for @extension_point.
+
+
+ the #GType that all implementations must have,
+ or %G_TYPE_INVALID if the extension point has no required type
+
+
+
+
+ a #GIOExtensionPoint
+
+
+
+
+
+ Sets the required type for @extension_point to @type.
+All implementations must henceforth have this type.
+
+
+
+
+
+
+ a #GIOExtensionPoint
+
+
+
+ the #GType to require
+
+
+
+
+
+ Registers @type as extension for the extension point with name
+@extension_point_name.
+
+If @type has already been registered as an extension for this
+extension point, the existing #GIOExtension object is returned.
+
+
+ a #GIOExtension object for #GType
+
+
+
+
+ the name of the extension point
+
+
+
+ the #GType to register as extension
+
+
+
+ the name for the extension
+
+
+
+ the priority for the extension
+
+
+
+
+
+ Looks up an existing extension point.
+
+
+ the #GIOExtensionPoint, or %NULL if there
+ is no registered extension point with the given name.
+
+
+
+
+ the name of the extension point
+
+
+
+
+
+ Registers an extension point.
+
+
+ the new #GIOExtensionPoint. This object is
+ owned by GIO and should not be freed.
+
+
+
+
+ The name of the extension point
+
+
+
+
+
+
+ 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.
+
+
+
+ Creates a new GIOModule that will load the specific
+shared library when in use.
+
+
+ a #GIOModule from given @filename,
+or %NULL on error.
+
+
+
+
+ filename of the shared library module.
+
+
+
+
+
+ Optional API for GIO modules to implement.
+
+Should return a list of all the extension points that may be
+implemented in this module.
+
+This method will not be called in normal use, however it may be
+called when probing existing modules and recording which extension
+points that this model is used for. This means we won't have to
+load and initialize this module unless its needed.
+
+If this function is not implemented by the module the module will
+always be loaded, initialized and then unloaded on application
+startup so that it can register its extension points during init.
+
+Note that a module need not actually implement all the extension
+points that g_io_module_query() returns, since the exact list of
+extension may depend on runtime issues. However all extension
+points actually implemented must be returned by g_io_module_query()
+(if defined).
+
+When installing a module that implements g_io_module_query() you must
+run gio-querymodules in order to build the cache files required for
+lazy loading.
+
+Since 2.56, this function should be named `g_io_<modulename>_query`, where
+`modulename` is the plugin’s filename with the `lib` or `libgio` prefix and
+everything after the first dot removed, and with `-` replaced with `_`
+throughout. For example, `libgiognutls-helper.so` becomes `gnutls_helper`.
+Using the new symbol names avoids name clashes when building modules
+statically. The old symbol names continue to be supported, but cannot be used
+for static builds.
+
+
+ A %NULL-terminated array of strings,
+ listing the supported extension points of the module. The array
+ must be suitable for freeing with g_strfreev().
+
+
+
+
+
+
+ Required API for GIO modules to implement.
+
+This function is run after the module has been loaded into GIO,
+to initialize the module. Typically, this function will call
+g_io_extension_point_implement().
+
+Since 2.56, this function should be named `g_io_<modulename>_load`, where
+`modulename` is the plugin’s filename with the `lib` or `libgio` prefix and
+everything after the first dot removed, and with `-` replaced with `_`
+throughout. For example, `libgiognutls-helper.so` becomes `gnutls_helper`.
+Using the new symbol names avoids name clashes when building modules
+statically. The old symbol names continue to be supported, but cannot be used
+for static builds.
+
+
+
+
+
+
+ a #GIOModule.
+
+
+
+
+
+ Required API for GIO modules to implement.
+
+This function is run when the module is being unloaded from GIO,
+to finalize the module.
+
+Since 2.56, this function should be named `g_io_<modulename>_unload`, where
+`modulename` is the plugin’s filename with the `lib` or `libgio` prefix and
+everything after the first dot removed, and with `-` replaced with `_`
+throughout. For example, `libgiognutls-helper.so` becomes `gnutls_helper`.
+Using the new symbol names avoids name clashes when building modules
+statically. The old symbol names continue to be supported, but cannot be used
+for static builds.
+
+
+
+
+
+
+ a #GIOModule.
+
+
+
+
+
+
+
+
+
+ Represents a scope for loading IO modules. A scope can be used for blocking
+duplicate modules, or blocking a module you don't want to load.
+
+The scope can be used with g_io_modules_load_all_in_directory_with_scope()
+or g_io_modules_scan_all_in_directory_with_scope().
+
+
+ Block modules with the given @basename from being loaded when
+this scope is used with g_io_modules_scan_all_in_directory_with_scope()
+or g_io_modules_load_all_in_directory_with_scope().
+
+
+
+
+
+
+ a module loading scope
+
+
+
+ the basename to block
+
+
+
+
+
+ Free a module scope.
+
+
+
+
+
+
+ a module loading scope
+
+
+
+
+
+ Create a new scope for loading of IO modules. A scope can be used for
+blocking duplicate modules, or blocking a module you don't want to load.
+
+Specify the %G_IO_MODULE_SCOPE_BLOCK_DUPLICATES flag to block modules
+which have the same base name as a module that has already been seen
+in this scope.
+
+
+ the new module scope
+
+
+
+
+ flags for the new scope
+
+
+
+
+
+
+ Flags for use with g_io_module_scope_new().
+
+ No module scan flags
+
+
+ When using this scope to load or
+ scan modules, automatically block a modules which has the same base
+ basename as previously loaded module.
+
+
+
+ Opaque class for defining and scheduling IO jobs.
+
+
+ Used from an I/O job to send a callback to be run in the thread
+that the job was started from, waiting for the result (and thus
+blocking the I/O job).
+ Use g_main_context_invoke().
+
+
+ The return value of @func
+
+
+
+
+ a #GIOSchedulerJob
+
+
+
+ a #GSourceFunc callback that will be called in the original thread
+
+
+
+ data to pass to @func
+
+
+
+ a #GDestroyNotify for @user_data, or %NULL
+
+
+
+
+
+ Used from an I/O job to send a callback to be run asynchronously in
+the thread that the job was started from. The callback will be run
+when the main loop is available, but at that time the I/O job might
+have finished. The return value from the callback is ignored.
+
+Note that if you are passing the @user_data from g_io_scheduler_push_job()
+on to this function you have to ensure that it is not freed before
+@func is called, either by passing %NULL as @notify to
+g_io_scheduler_push_job() or by using refcounting for @user_data.
+ Use g_main_context_invoke().
+
+
+
+
+
+
+ a #GIOSchedulerJob
+
+
+
+ a #GSourceFunc callback that will be called in the original thread
+
+
+
+ data to pass to @func
+
+
+
+ a #GDestroyNotify for @user_data, or %NULL
+
+
+
+
+
+
+ I/O Job function.
+
+Long-running jobs should periodically check the @cancellable
+to see if they have been cancelled.
+
+
+ %TRUE if this function should be called again to
+ complete the job, %FALSE if the job is complete (or cancelled)
+
+
+
+
+ a #GIOSchedulerJob.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ data passed to the callback function
+
+
+
+
+
+ GIOStream represents an object that has both read and write streams.
+Generally the two streams act as separate input and output streams,
+but they share some common resources and state. For instance, for
+seekable streams, both streams may use the same position.
+
+Examples of #GIOStream objects are #GSocketConnection, which represents
+a two-way network connection; and #GFileIOStream, which represents 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 substreams, so even if the substreams stay alive they will
+always return %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 but common state in the
+#GIOStream may still be open. However, some streams may support
+"half-closed" states where one direction of the stream is actually shut down.
+
+Operations on #GIOStreams cannot be started while another operation on the
+#GIOStream or its substreams is in progress. Specifically, an application can
+read from the #GInputStream and write to the #GOutputStream simultaneously
+(either in separate threads, or as asynchronous operations in the same
+thread), but an application cannot start any #GIOStream operation while there
+is a #GIOStream, #GInputStream or #GOutputStream operation in progress, and
+an application can’t start any #GInputStream or #GOutputStream operation
+while there is a #GIOStream operation in progress.
+
+This is a product of individual stream operations being associated with a
+given #GMainContext (the thread-default context at the time the operation was
+started), rather than entire streams being associated with a single
+#GMainContext.
+
+GIO may run operations on #GIOStreams from other (worker) threads, and this
+may be exposed to application code in the behaviour of wrapper streams, such
+as #GBufferedInputStream or #GTlsConnection. With such wrapper APIs,
+application code may only run operations on the base (wrapped) stream when
+the wrapper stream is idle. Note that the semantics of such operations may
+not be well-defined due to the state the wrapper stream leaves the base
+stream in (though they are guaranteed not to crash).
+
+
+ Finishes an asynchronous io stream splice operation.
+
+
+ %TRUE on success, %FALSE otherwise.
+
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Requests an asynchronous close of the stream, releasing resources
+related to it. When the operation is finished @callback will be
+called. You can then call g_io_stream_close_finish() to get
+the result of the operation.
+
+For behaviour details see g_io_stream_close().
+
+The asynchronous methods have a default fallback that uses threads
+to implement asynchronicity, so they are optional for inheriting
+classes. However, if you override one you must override all.
+
+
+
+
+
+
+ a #GIOStream
+
+
+
+ the io priority of the request
+
+
+
+ optional cancellable object
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Closes a stream.
+
+
+ %TRUE if stream was successfully closed, %FALSE otherwise.
+
+
+
+
+ a #GIOStream
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Gets the input stream for this object. This is used
+for reading.
+
+
+ a #GInputStream, owned by the #GIOStream.
+Do not free.
+
+
+
+
+ a #GIOStream
+
+
+
+
+
+ Gets the output stream for this object. This is used for
+writing.
+
+
+ a #GOutputStream, owned by the #GIOStream.
+Do not free.
+
+
+
+
+ a #GIOStream
+
+
+
+
+
+ Clears the pending flag on @stream.
+
+
+
+
+
+
+ a #GIOStream
+
+
+
+
+
+ Closes the stream, releasing resources related to it. This will also
+close the individual input and output streams, if they are not already
+closed.
+
+Once the stream is closed, all other operations will return
+%G_IO_ERROR_CLOSED. Closing a stream multiple times will not
+return an error.
+
+Closing a stream will automatically flush any outstanding buffers
+in the stream.
+
+Streams will be automatically closed when the last reference
+is dropped, but you might want to call this function to make sure
+resources are released as early as possible.
+
+Some streams might keep the backing store of the stream (e.g. a file
+descriptor) open after the stream is closed. See the documentation for
+the individual stream for details.
+
+On failure the first error that happened will be reported, but the
+close operation will finish as much as possible. A stream that failed
+to close will still return %G_IO_ERROR_CLOSED for all operations.
+Still, it is important to check and report the error to the user,
+otherwise there might be a loss of data as all data might not be written.
+
+If @cancellable is not NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+Cancelling a close will still leave the stream closed, but some streams
+can use a faster close that doesn't block to e.g. check errors.
+
+The default implementation of this method just calls close on the
+individual input/output streams.
+
+
+ %TRUE on success, %FALSE on failure
+
+
+
+
+ a #GIOStream
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+
+
+ Requests an asynchronous close of the stream, releasing resources
+related to it. When the operation is finished @callback will be
+called. You can then call g_io_stream_close_finish() to get
+the result of the operation.
+
+For behaviour details see g_io_stream_close().
+
+The asynchronous methods have a default fallback that uses threads
+to implement asynchronicity, so they are optional for inheriting
+classes. However, if you override one you must override all.
+
+
+
+
+
+
+ a #GIOStream
+
+
+
+ the io priority of the request
+
+
+
+ optional cancellable object
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Closes a stream.
+
+
+ %TRUE if stream was successfully closed, %FALSE otherwise.
+
+
+
+
+ a #GIOStream
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Gets the input stream for this object. This is used
+for reading.
+
+
+ a #GInputStream, owned by the #GIOStream.
+Do not free.
+
+
+
+
+ a #GIOStream
+
+
+
+
+
+ Gets the output stream for this object. This is used for
+writing.
+
+
+ a #GOutputStream, owned by the #GIOStream.
+Do not free.
+
+
+
+
+ a #GIOStream
+
+
+
+
+
+ Checks if a stream has pending actions.
+
+
+ %TRUE if @stream has pending actions.
+
+
+
+
+ a #GIOStream
+
+
+
+
+
+ Checks if a stream is closed.
+
+
+ %TRUE if the stream is closed.
+
+
+
+
+ a #GIOStream
+
+
+
+
+
+ Sets @stream to have actions pending. If the pending flag is
+already set or @stream is closed, it will return %FALSE and set
+@error.
+
+
+ %TRUE if pending was previously unset and is now set.
+
+
+
+
+ a #GIOStream
+
+
+
+
+
+ Asynchronously splice the output stream of @stream1 to the input stream of
+@stream2, and splice the output stream of @stream2 to the input stream of
+@stream1.
+
+When the operation is finished @callback will be called.
+You can then call g_io_stream_splice_finish() to get the
+result of the operation.
+
+
+
+
+
+
+ a #GIOStream.
+
+
+
+ a #GIOStream.
+
+
+
+ a set of #GIOStreamSpliceFlags.
+
+
+
+ the io priority of the request.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback.
+
+
+
+ user data passed to @callback.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GInputStream, owned by the #GIOStream.
+Do not free.
+
+
+
+
+ a #GIOStream
+
+
+
+
+
+
+
+
+
+ a #GOutputStream, owned by the #GIOStream.
+Do not free.
+
+
+
+
+ a #GIOStream
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GIOStream
+
+
+
+ the io priority of the request
+
+
+
+ optional cancellable object
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ %TRUE if stream was successfully closed, %FALSE otherwise.
+
+
+
+
+ a #GIOStream
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ GIOStreamSpliceFlags determine how streams should be spliced.
+
+ Do not close either stream.
+
+
+ Close the first stream after
+ the splice.
+
+
+ Close the second stream after
+ the splice.
+
+
+ Wait for both splice operations to finish
+ before calling the callback.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #GIcon is a very minimal interface for icons. It provides functions
+for checking the equality of two icons, hashing of icons and
+serializing an icon to and from strings.
+
+#GIcon does not provide the actual pixmap for the icon as this is out
+of GIO's scope, however implementations of #GIcon may contain the name
+of an icon (see #GThemedIcon), or the path to an icon (see #GLoadableIcon).
+
+To obtain a hash of a #GIcon, see g_icon_hash().
+
+To check if two #GIcons are equal, see g_icon_equal().
+
+For serializing a #GIcon, use g_icon_serialize() and
+g_icon_deserialize().
+
+If you want to consume #GIcon (for example, in a toolkit) you must
+be prepared to handle at least the three following cases:
+#GLoadableIcon, #GThemedIcon and #GEmblemedIcon. It may also make
+sense to have fast-paths for other cases (like handling #GdkPixbuf
+directly, for example) but all compliant #GIcon implementations
+outside of GIO must implement #GLoadableIcon.
+
+If your application or library provides one or more #GIcon
+implementations you need to ensure that your new implementation also
+implements #GLoadableIcon. Additionally, you must provide an
+implementation of g_icon_serialize() that gives a result that is
+understood by g_icon_deserialize(), yielding one of the built-in icon
+types.
+
+
+ Deserializes a #GIcon previously serialized using g_icon_serialize().
+
+
+ a #GIcon, or %NULL when deserialization fails.
+
+
+
+
+ a #GVariant created with g_icon_serialize()
+
+
+
+
+
+ Generate a #GIcon instance from @str. This function can fail if
+@str is not valid - see g_icon_to_string() for discussion.
+
+If your application or library provides one or more #GIcon
+implementations you need to ensure that each #GType is registered
+with the type system prior to calling g_icon_new_for_string().
+
+
+ An object implementing the #GIcon
+ interface or %NULL if @error is set.
+
+
+
+
+ A string obtained via g_icon_to_string().
+
+
+
+
+
+ Checks if two icons are equal.
+
+
+ %TRUE if @icon1 is equal to @icon2. %FALSE otherwise.
+
+
+
+
+ pointer to the first #GIcon.
+
+
+
+ pointer to the second #GIcon.
+
+
+
+
+
+ Gets a hash for an icon.
+
+
+ a #guint containing a hash for the @icon, suitable for
+use in a #GHashTable or similar data structure.
+
+
+
+
+ #gconstpointer to an icon object.
+
+
+
+
+
+ Serializes a #GIcon into a #GVariant. An equivalent #GIcon can be retrieved
+back by calling g_icon_deserialize() on the returned value.
+As serialization will avoid using raw icon data when possible, it only
+makes sense to transfer the #GVariant between processes on the same machine,
+(as opposed to over the network), and within the same file system namespace.
+
+
+ a #GVariant, or %NULL when serialization fails. The #GVariant will not be floating.
+
+
+
+
+ a #GIcon
+
+
+
+
+
+ Serializes the @icon into string tokens.
+This is can be invoked when g_icon_new_for_string() is called.
+
+
+ %TRUE if serialization took place, %FALSE otherwise
+
+
+
+
+ The #GIcon
+
+
+
+
+ The array to fill with tokens
+
+
+
+
+
+ version of serialized tokens
+
+
+
+
+
+ Checks if two icons are equal.
+
+
+ %TRUE if @icon1 is equal to @icon2. %FALSE otherwise.
+
+
+
+
+ pointer to the first #GIcon.
+
+
+
+ pointer to the second #GIcon.
+
+
+
+
+
+ Gets a hash for an icon.
+
+
+ a #guint containing a hash for the @icon, suitable for
+use in a #GHashTable or similar data structure.
+
+
+
+
+ #gconstpointer to an icon object.
+
+
+
+
+
+ Serializes a #GIcon into a #GVariant. An equivalent #GIcon can be retrieved
+back by calling g_icon_deserialize() on the returned value.
+As serialization will avoid using raw icon data when possible, it only
+makes sense to transfer the #GVariant between processes on the same machine,
+(as opposed to over the network), and within the same file system namespace.
+
+
+ a #GVariant, or %NULL when serialization fails. The #GVariant will not be floating.
+
+
+
+
+ a #GIcon
+
+
+
+
+
+ Generates a textual representation of @icon that can be used for
+serialization such as when passing @icon to a different process or
+saving it to persistent storage. Use g_icon_new_for_string() to
+get @icon back from the returned string.
+
+The encoding of the returned string is proprietary to #GIcon except
+in the following two cases
+
+- If @icon is a #GFileIcon, the returned string is a native path
+ (such as `/path/to/my icon.png`) without escaping
+ if the #GFile for @icon is a native file. If the file is not
+ native, the returned string is the result of g_file_get_uri()
+ (such as `sftp://path/to/my%20icon.png`).
+
+- If @icon is a #GThemedIcon with exactly one name and no fallbacks,
+ the encoding is simply the name (such as `network-server`).
+
+
+ An allocated NUL-terminated UTF8 string or
+%NULL if @icon can't be serialized. Use g_free() to free.
+
+
+
+
+ a #GIcon.
+
+
+
+
+
+
+ GIconIface is used to implement GIcon types for various
+different systems. See #GThemedIcon and #GLoadableIcon for
+examples of how to implement this interface.
+
+
+ The parent interface.
+
+
+
+
+
+
+ a #guint containing a hash for the @icon, suitable for
+use in a #GHashTable or similar data structure.
+
+
+
+
+ #gconstpointer to an icon object.
+
+
+
+
+
+
+
+
+
+ %TRUE if @icon1 is equal to @icon2. %FALSE otherwise.
+
+
+
+
+ pointer to the first #GIcon.
+
+
+
+ pointer to the second #GIcon.
+
+
+
+
+
+
+
+
+
+ %TRUE if serialization took place, %FALSE otherwise
+
+
+
+
+ The #GIcon
+
+
+
+
+ The array to fill with tokens
+
+
+
+
+
+ version of serialized tokens
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GVariant, or %NULL when serialization fails. The #GVariant will not be floating.
+
+
+
+
+ a #GIcon
+
+
+
+
+
+
+
+ #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).
+
+
+ Creates a #GInetAddress for the "any" address (unassigned/"don't
+care") for @family.
+
+
+ a new #GInetAddress corresponding to the "any" address
+for @family.
+ Free the returned object with g_object_unref().
+
+
+
+
+ the address family
+
+
+
+
+
+ Creates a new #GInetAddress from the given @family and @bytes.
+@bytes should be 4 bytes for %G_SOCKET_FAMILY_IPV4 and 16 bytes for
+%G_SOCKET_FAMILY_IPV6.
+
+
+ a new #GInetAddress corresponding to @family and @bytes.
+ Free the returned object with g_object_unref().
+
+
+
+
+ raw address data
+
+
+
+
+
+ the address family of @bytes
+
+
+
+
+
+ Parses @string as an IP address and creates a new #GInetAddress.
+
+
+ a new #GInetAddress corresponding
+to @string, or %NULL if @string could not be parsed.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a string representation of an IP address
+
+
+
+
+
+ Creates a #GInetAddress for the loopback address for @family.
+
+
+ a new #GInetAddress corresponding to the loopback address
+for @family.
+ Free the returned object with g_object_unref().
+
+
+
+
+ the address family
+
+
+
+
+
+ Gets the raw binary address data from @address.
+
+
+ a pointer to an internal array of the bytes in @address,
+which should not be modified, stored, or freed. The size of this
+array can be gotten with g_inet_address_get_native_size().
+
+
+
+
+ a #GInetAddress
+
+
+
+
+
+ Converts @address to string form.
+
+
+ a representation of @address as a string, which should be
+freed after use.
+
+
+
+
+ a #GInetAddress
+
+
+
+
+
+ Checks if two #GInetAddress instances are equal, e.g. the same address.
+
+
+ %TRUE if @address and @other_address are equal, %FALSE otherwise.
+
+
+
+
+ A #GInetAddress.
+
+
+
+ Another #GInetAddress.
+
+
+
+
+
+ Gets @address's family
+
+
+ @address's family
+
+
+
+
+ a #GInetAddress
+
+
+
+
+
+ Tests whether @address is the "any" address for its family.
+
+
+ %TRUE if @address is the "any" address for its family.
+
+
+
+
+ a #GInetAddress
+
+
+
+
+
+ Tests whether @address is a link-local address (that is, if it
+identifies a host on a local network that is not connected to the
+Internet).
+
+
+ %TRUE if @address is a link-local address.
+
+
+
+
+ a #GInetAddress
+
+
+
+
+
+ Tests whether @address is the loopback address for its family.
+
+
+ %TRUE if @address is the loopback address for its family.
+
+
+
+
+ a #GInetAddress
+
+
+
+
+
+ Tests whether @address is a global multicast address.
+
+
+ %TRUE if @address is a global multicast address.
+
+
+
+
+ a #GInetAddress
+
+
+
+
+
+ Tests whether @address is a link-local multicast address.
+
+
+ %TRUE if @address is a link-local multicast address.
+
+
+
+
+ a #GInetAddress
+
+
+
+
+
+ Tests whether @address is a node-local multicast address.
+
+
+ %TRUE if @address is a node-local multicast address.
+
+
+
+
+ a #GInetAddress
+
+
+
+
+
+ Tests whether @address is an organization-local multicast address.
+
+
+ %TRUE if @address is an organization-local multicast address.
+
+
+
+
+ a #GInetAddress
+
+
+
+
+
+ Tests whether @address is a site-local multicast address.
+
+
+ %TRUE if @address is a site-local multicast address.
+
+
+
+
+ a #GInetAddress
+
+
+
+
+
+ Tests whether @address is a multicast address.
+
+
+ %TRUE if @address is a multicast address.
+
+
+
+
+ a #GInetAddress
+
+
+
+
+
+ Tests whether @address is a site-local address such as 10.0.0.1
+(that is, the address identifies a host on a local network that can
+not be reached directly from the Internet, but which may have
+outgoing Internet connectivity via a NAT or firewall).
+
+
+ %TRUE if @address is a site-local address.
+
+
+
+
+ a #GInetAddress
+
+
+
+
+
+ Gets the size of the native raw binary address for @address. This
+is the size of the data that you get from g_inet_address_to_bytes().
+
+
+ the number of bytes used for the native version of @address.
+
+
+
+
+ a #GInetAddress
+
+
+
+
+
+ Gets the raw binary address data from @address.
+
+
+ a pointer to an internal array of the bytes in @address,
+which should not be modified, stored, or freed. The size of this
+array can be gotten with g_inet_address_get_native_size().
+
+
+
+
+ a #GInetAddress
+
+
+
+
+
+ Converts @address to string form.
+
+
+ a representation of @address as a string, which should be
+freed after use.
+
+
+
+
+ a #GInetAddress
+
+
+
+
+
+
+
+
+
+
+
+ Whether this is the "any" address for its family.
+See g_inet_address_get_is_any().
+
+
+
+ Whether this is a link-local address.
+See g_inet_address_get_is_link_local().
+
+
+
+ Whether this is the loopback address for its family.
+See g_inet_address_get_is_loopback().
+
+
+
+ Whether this is a global multicast address.
+See g_inet_address_get_is_mc_global().
+
+
+
+ Whether this is a link-local multicast address.
+See g_inet_address_get_is_mc_link_local().
+
+
+
+ Whether this is a node-local multicast address.
+See g_inet_address_get_is_mc_node_local().
+
+
+
+ Whether this is an organization-local multicast address.
+See g_inet_address_get_is_mc_org_local().
+
+
+
+ Whether this is a site-local multicast address.
+See g_inet_address_get_is_mc_site_local().
+
+
+
+ Whether this is a multicast address.
+See g_inet_address_get_is_multicast().
+
+
+
+ Whether this is a site-local address.
+See g_inet_address_get_is_loopback().
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a representation of @address as a string, which should be
+freed after use.
+
+
+
+
+ a #GInetAddress
+
+
+
+
+
+
+
+
+
+ a pointer to an internal array of the bytes in @address,
+which should not be modified, stored, or freed. The size of this
+array can be gotten with g_inet_address_get_native_size().
+
+
+
+
+ a #GInetAddress
+
+
+
+
+
+
+
+ #GInetAddressMask represents a range of IPv4 or IPv6 addresses
+described by a base address and a length indicating how many bits
+of the base address are relevant for matching purposes. These are
+often given in string form. Eg, "10.0.0.0/8", or "fe80::/10".
+
+
+
+ Creates a new #GInetAddressMask representing all addresses whose
+first @length bits match @addr.
+
+
+ a new #GInetAddressMask, or %NULL on error
+
+
+
+
+ a #GInetAddress
+
+
+
+ number of bits of @addr to use
+
+
+
+
+
+ Parses @mask_string as an IP address and (optional) length, and
+creates a new #GInetAddressMask. The length, if present, is
+delimited by a "/". If it is not present, then the length is
+assumed to be the full length of the address.
+
+
+ a new #GInetAddressMask corresponding to @string, or %NULL
+on error.
+
+
+
+
+ an IP address or address/length string
+
+
+
+
+
+ Tests if @mask and @mask2 are the same mask.
+
+
+ whether @mask and @mask2 are the same mask
+
+
+
+
+ a #GInetAddressMask
+
+
+
+ another #GInetAddressMask
+
+
+
+
+
+ Gets @mask's base address
+
+
+ @mask's base address
+
+
+
+
+ a #GInetAddressMask
+
+
+
+
+
+ Gets the #GSocketFamily of @mask's address
+
+
+ the #GSocketFamily of @mask's address
+
+
+
+
+ a #GInetAddressMask
+
+
+
+
+
+ Gets @mask's length
+
+
+ @mask's length
+
+
+
+
+ a #GInetAddressMask
+
+
+
+
+
+ Tests if @address falls within the range described by @mask.
+
+
+ whether @address falls within the range described by
+@mask.
+
+
+
+
+ a #GInetAddressMask
+
+
+
+ a #GInetAddress
+
+
+
+
+
+ Converts @mask back to its corresponding string form.
+
+
+ a string corresponding to @mask.
+
+
+
+
+ a #GInetAddressMask
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ An IPv4 or IPv6 socket address; that is, the combination of a
+#GInetAddress and a port number.
+
+
+
+ Creates a new #GInetSocketAddress for @address and @port.
+
+
+ a new #GInetSocketAddress
+
+
+
+
+ a #GInetAddress
+
+
+
+ a port number
+
+
+
+
+
+ Creates a new #GInetSocketAddress for @address and @port.
+
+If @address is an IPv6 address, it can also contain a scope ID
+(separated from the address by a `%`).
+
+
+ a new #GInetSocketAddress,
+or %NULL if @address cannot be parsed.
+
+
+
+
+ the string form of an IP address
+
+
+
+ a port number
+
+
+
+
+
+ Gets @address's #GInetAddress.
+
+
+ the #GInetAddress for @address, which must be
+g_object_ref()'d if it will be stored
+
+
+
+
+ a #GInetSocketAddress
+
+
+
+
+
+ Gets the `sin6_flowinfo` field from @address,
+which must be an IPv6 address.
+
+
+ the flowinfo field
+
+
+
+
+ a %G_SOCKET_FAMILY_IPV6 #GInetSocketAddress
+
+
+
+
+
+ Gets @address's port.
+
+
+ the port for @address
+
+
+
+
+ a #GInetSocketAddress
+
+
+
+
+
+ Gets the `sin6_scope_id` field from @address,
+which must be an IPv6 address.
+
+
+ the scope id field
+
+
+
+
+ a %G_SOCKET_FAMILY_IPV6 #GInetAddress
+
+
+
+
+
+
+
+
+ The `sin6_flowinfo` field, for IPv6 addresses.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #GInitable is implemented by objects that can fail during
+initialization. If an object implements this interface then
+it must be initialized as the first thing after construction,
+either via g_initable_init() or g_async_initable_init_async()
+(the latter is only available if it also implements #GAsyncInitable).
+
+If the object is not initialized, or initialization returns with an
+error, then all operations on the object except g_object_ref() and
+g_object_unref() are considered to be invalid, and have undefined
+behaviour. They will often fail with g_critical() or g_warning(), but
+this must not be relied on.
+
+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 implementing %GInitable
+during normal construction and automatically initialize them, throwing
+an exception on failure.
+
+
+ Helper function for constructing #GInitable object. This is
+similar to g_object_new() but also initializes the object
+and returns %NULL, setting an error on failure.
+
+
+ a newly allocated
+ #GObject, or %NULL on error
+
+
+
+
+ a #GType supporting #GInitable.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GError location to store the error occurring, or %NULL to
+ ignore.
+
+
+
+ the name of the first property, or %NULL if no
+ properties
+
+
+
+ the value if the first property, followed by and other property
+ value pairs, and ended by %NULL.
+
+
+
+
+
+ Helper function for constructing #GInitable object. This is
+similar to g_object_new_valist() but also initializes the object
+and returns %NULL, setting an error on failure.
+
+
+ a newly allocated
+ #GObject, or %NULL on error
+
+
+
+
+ a #GType supporting #GInitable.
+
+
+
+ the name of the first property, followed by
+the value, and other property value pairs, and ended by %NULL.
+
+
+
+ The var args list generated from @first_property_name.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Helper function for constructing #GInitable object. This is
+similar to g_object_newv() but also initializes the object
+and returns %NULL, setting an error on failure.
+ Use g_object_new_with_properties() and
+g_initable_init() instead. See #GParameter for more information.
+
+
+ a newly allocated
+ #GObject, or %NULL on error
+
+
+
+
+ a #GType supporting #GInitable.
+
+
+
+ the number of parameters in @parameters
+
+
+
+ the parameters to use to construct the object
+
+
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Initializes the object implementing the interface.
+
+This method is intended for language bindings. If writing in C,
+g_initable_new() should typically be used instead.
+
+The object must be initialized before any real use after initial
+construction, either with this function or g_async_initable_init_async().
+
+Implementations may also support cancellation. If @cancellable is not %NULL,
+then initialization can be cancelled by triggering the cancellable object
+from another thread. If the operation was cancelled, the error
+%G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL and
+the object doesn't support cancellable initialization the error
+%G_IO_ERROR_NOT_SUPPORTED will be returned.
+
+If the object is not initialized, or initialization returns with an
+error, then all operations on the object except g_object_ref() and
+g_object_unref() are considered to be invalid, and have undefined
+behaviour. See the [introduction][ginitable] for more details.
+
+Callers should not assume that a class which implements #GInitable can be
+initialized multiple times, unless the class explicitly documents itself as
+supporting this. Generally, a class’ implementation of init() can assume
+(and assert) that it will only be called once. Previously, this documentation
+recommended all #GInitable implementations should be idempotent; that
+recommendation was relaxed in GLib 2.54.
+
+If a class explicitly supports being initialized multiple times, it is
+recommended that the method is idempotent: multiple calls with the same
+arguments should return the same results. Only the first call initializes
+the object; further calls return the result of the first call.
+
+One reason why a class might need to support idempotent initialization is if
+it is designed to be used via the singleton pattern, with a
+#GObjectClass.constructor that sometimes returns an existing instance.
+In this pattern, a caller would expect to be able to call g_initable_init()
+on the result of g_object_new(), regardless of whether it is in fact a new
+instance.
+
+
+ %TRUE if successful. If an error has occurred, this function will
+ return %FALSE and set @error appropriately if present.
+
+
+
+
+ a #GInitable.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Initializes the object implementing the interface.
+
+This method is intended for language bindings. If writing in C,
+g_initable_new() should typically be used instead.
+
+The object must be initialized before any real use after initial
+construction, either with this function or g_async_initable_init_async().
+
+Implementations may also support cancellation. If @cancellable is not %NULL,
+then initialization can be cancelled by triggering the cancellable object
+from another thread. If the operation was cancelled, the error
+%G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL and
+the object doesn't support cancellable initialization the error
+%G_IO_ERROR_NOT_SUPPORTED will be returned.
+
+If the object is not initialized, or initialization returns with an
+error, then all operations on the object except g_object_ref() and
+g_object_unref() are considered to be invalid, and have undefined
+behaviour. See the [introduction][ginitable] for more details.
+
+Callers should not assume that a class which implements #GInitable can be
+initialized multiple times, unless the class explicitly documents itself as
+supporting this. Generally, a class’ implementation of init() can assume
+(and assert) that it will only be called once. Previously, this documentation
+recommended all #GInitable implementations should be idempotent; that
+recommendation was relaxed in GLib 2.54.
+
+If a class explicitly supports being initialized multiple times, it is
+recommended that the method is idempotent: multiple calls with the same
+arguments should return the same results. Only the first call initializes
+the object; further calls return the result of the first call.
+
+One reason why a class might need to support idempotent initialization is if
+it is designed to be used via the singleton pattern, with a
+#GObjectClass.constructor that sometimes returns an existing instance.
+In this pattern, a caller would expect to be able to call g_initable_init()
+on the result of g_object_new(), regardless of whether it is in fact a new
+instance.
+
+
+ %TRUE if successful. If an error has occurred, this function will
+ return %FALSE and set @error appropriately if present.
+
+
+
+
+ a #GInitable.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+
+ Provides an interface for initializing object such that initialization
+may fail.
+
+
+ The parent interface.
+
+
+
+
+
+
+ %TRUE if successful. If an error has occurred, this function will
+ return %FALSE and set @error appropriately if present.
+
+
+
+
+ a #GInitable.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+
+
+ Structure used for scatter/gather data input when receiving multiple
+messages or packets in one go. You generally pass in an array of empty
+#GInputVectors and the operation will use all the buffers as if they
+were one buffer, and will set @bytes_received to the total number of bytes
+received across all #GInputVectors.
+
+This structure closely mirrors `struct mmsghdr` and `struct msghdr` from
+the POSIX sockets API (see `man 2 recvmmsg`).
+
+If @address is non-%NULL then it is set to the source address the message
+was received from, and the caller must free it afterwards.
+
+If @control_messages is non-%NULL then it is set to an array of control
+messages received with the message (if any), and the caller must free it
+afterwards. @num_control_messages is set to the number of elements in
+this array, which may be zero.
+
+Flags relevant to this message will be returned in @flags. For example,
+`MSG_EOR` or `MSG_TRUNC`.
+
+
+ return location
+ for a #GSocketAddress, or %NULL
+
+
+
+ pointer to an
+ array of input vectors
+
+
+
+
+
+ the number of input vectors pointed to by @vectors
+
+
+
+ will be set to the number of bytes that have been
+ received
+
+
+
+ collection of #GSocketMsgFlags for the received message,
+ outputted by the call
+
+
+
+ return location for a
+ caller-allocated array of #GSocketControlMessages, or %NULL
+
+
+
+
+
+ return location for the number of
+ elements in @control_messages
+
+
+
+
+ #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().
+
+See the documentation for #GIOStream for details of thread safety of
+streaming APIs.
+
+All of these functions have async variants too.
+
+
+ Requests an asynchronous closes of the stream, releasing resources related to it.
+When the operation is finished @callback will be called.
+You can then call g_input_stream_close_finish() to get the result of the
+operation.
+
+For behaviour details see g_input_stream_close().
+
+The asynchronous methods have a default fallback that uses threads to implement
+asynchronicity, so they are optional for inheriting classes. However, if you
+override one you must override all.
+
+
+
+
+
+
+ A #GInputStream.
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional cancellable object
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes closing a stream asynchronously, started from g_input_stream_close_async().
+
+
+ %TRUE if the stream was closed successfully.
+
+
+
+
+ a #GInputStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Request an asynchronous read of @count bytes from the stream into the buffer
+starting at @buffer. When the operation is finished @callback will be called.
+You can then call g_input_stream_read_finish() to get the result of the
+operation.
+
+During an async request no other sync and async calls are allowed on @stream, and will
+result in %G_IO_ERROR_PENDING errors.
+
+A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
+
+On success, the number of bytes read into the buffer will be passed to the
+callback. It is not an error if this is not the same as the requested size, as it
+can happen e.g. near the end of a file, but generally we try to read
+as many bytes as requested. Zero is returned on end of file
+(or if @count is zero), but never otherwise.
+
+Any outstanding i/o request with higher priority (lower numerical value) will
+be executed before an outstanding request with lower priority. Default
+priority is %G_PRIORITY_DEFAULT.
+
+The asynchronous methods have a default fallback that uses threads to implement
+asynchronicity, so they are optional for inheriting classes. However, if you
+override one you must override all.
+
+
+
+
+
+
+ A #GInputStream.
+
+
+
+
+ a buffer to read data into (which should be at least count bytes long).
+
+
+
+
+
+ the number of bytes that will be read from the stream
+
+
+
+ the [I/O priority][io-priority]
+of the request.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous stream read operation.
+
+
+ number of bytes read in, or -1 on error, or 0 on end of file.
+
+
+
+
+ a #GInputStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Tries to skip @count bytes from the stream. Will block during the operation.
+
+This is identical to g_input_stream_read(), from a behaviour standpoint,
+but the bytes that are skipped are not returned to the user. Some
+streams have an implementation that is more efficient than reading the data.
+
+This function is optional for inherited classes, as the default implementation
+emulates it using read.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
+operation was partially finished when the operation was cancelled the
+partial result will be returned, without an error.
+
+
+ Number of bytes skipped, or -1 on error
+
+
+
+
+ a #GInputStream.
+
+
+
+ the number of bytes that will be skipped from the stream
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Request an asynchronous skip of @count bytes from the stream.
+When the operation is finished @callback will be called.
+You can then call g_input_stream_skip_finish() to get the result
+of the operation.
+
+During an async request no other sync and async calls are allowed,
+and will result in %G_IO_ERROR_PENDING errors.
+
+A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
+
+On success, the number of bytes skipped will be passed to the callback.
+It is not an error if this is not the same as the requested size, as it
+can happen e.g. near the end of a file, but generally we try to skip
+as many bytes as requested. Zero is returned on end of file
+(or if @count is zero), but never otherwise.
+
+Any outstanding i/o request with higher priority (lower numerical value)
+will be executed before an outstanding request with lower priority.
+Default priority is %G_PRIORITY_DEFAULT.
+
+The asynchronous methods have a default fallback that uses threads to
+implement asynchronicity, so they are optional for inheriting classes.
+However, if you override one, you must override all.
+
+
+
+
+
+
+ A #GInputStream.
+
+
+
+ the number of bytes that will be skipped from the stream
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes a stream skip operation.
+
+
+ the size of the bytes skipped, or `-1` on error.
+
+
+
+
+ a #GInputStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Clears the pending flag on @stream.
+
+
+
+
+
+
+ input stream
+
+
+
+
+
+ Closes the stream, releasing resources related to it.
+
+Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED.
+Closing a stream multiple times will not return an error.
+
+Streams will be automatically closed when the last reference
+is dropped, but you might want to call this function to make sure
+resources are released as early as possible.
+
+Some streams might keep the backing store of the stream (e.g. a file descriptor)
+open after the stream is closed. See the documentation for the individual
+stream for details.
+
+On failure the first error that happened will be reported, but the close
+operation will finish as much as possible. A stream that failed to
+close will still return %G_IO_ERROR_CLOSED for all operations. Still, it
+is important to check and report the error to the user.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+Cancelling a close will still leave the stream closed, but some streams
+can use a faster close that doesn't block to e.g. check errors.
+
+
+ %TRUE on success, %FALSE on failure
+
+
+
+
+ A #GInputStream.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Requests an asynchronous closes of the stream, releasing resources related to it.
+When the operation is finished @callback will be called.
+You can then call g_input_stream_close_finish() to get the result of the
+operation.
+
+For behaviour details see g_input_stream_close().
+
+The asynchronous methods have a default fallback that uses threads to implement
+asynchronicity, so they are optional for inheriting classes. However, if you
+override one you must override all.
+
+
+
+
+
+
+ A #GInputStream.
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional cancellable object
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes closing a stream asynchronously, started from g_input_stream_close_async().
+
+
+ %TRUE if the stream was closed successfully.
+
+
+
+
+ a #GInputStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Checks if an input stream has pending actions.
+
+
+ %TRUE if @stream has pending actions.
+
+
+
+
+ input stream.
+
+
+
+
+
+ Checks if an input stream is closed.
+
+
+ %TRUE if the stream is closed.
+
+
+
+
+ input stream.
+
+
+
+
+
+ Tries to read @count bytes from the stream into the buffer starting at
+@buffer. Will block during this read.
+
+If count is zero returns zero and does nothing. A value of @count
+larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
+
+On success, the number of bytes read into the buffer is returned.
+It is not an error if this is not the same as the requested size, as it
+can happen e.g. near the end of a file. Zero is returned on end of file
+(or if @count is zero), but never otherwise.
+
+The returned @buffer is not a nul-terminated string, it can contain nul bytes
+at any position, and this function doesn't nul-terminate the @buffer.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
+operation was partially finished when the operation was cancelled the
+partial result will be returned, without an error.
+
+On error -1 is returned and @error is set accordingly.
+
+
+ Number of bytes read, or -1 on error, or 0 on end of file.
+
+
+
+
+ a #GInputStream.
+
+
+
+
+ a buffer to read data into (which should be at least count bytes long).
+
+
+
+
+
+ the number of bytes that will be read from the stream
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Tries to read @count bytes from the stream into the buffer starting at
+@buffer. Will block during this read.
+
+This function is similar to g_input_stream_read(), except it tries to
+read as many bytes as requested, only stopping on an error or end of stream.
+
+On a successful read of @count bytes, or if we reached the end of the
+stream, %TRUE is returned, and @bytes_read is set to the number of bytes
+read into @buffer.
+
+If there is an error during the operation %FALSE is returned and @error
+is set to indicate the error status.
+
+As a special exception to the normal conventions for functions that
+use #GError, if this function returns %FALSE (and sets @error) then
+@bytes_read will be set to the number of bytes that were successfully
+read before the error was encountered. This functionality is only
+available from C. If you need it from another language then you must
+write your own loop around g_input_stream_read().
+
+
+ %TRUE on success, %FALSE if there was an error
+
+
+
+
+ a #GInputStream.
+
+
+
+
+ a buffer to read data into (which should be at least count bytes long).
+
+
+
+
+
+ the number of bytes that will be read from the stream
+
+
+
+ location to store the number of bytes that was read from the stream
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Request an asynchronous read of @count bytes from the stream into the
+buffer starting at @buffer.
+
+This is the asynchronous equivalent of g_input_stream_read_all().
+
+Call g_input_stream_read_all_finish() to collect the result.
+
+Any outstanding I/O request with higher priority (lower numerical
+value) will be executed before an outstanding request with lower
+priority. Default priority is %G_PRIORITY_DEFAULT.
+
+
+
+
+
+
+ A #GInputStream
+
+
+
+
+ a buffer to read data into (which should be at least count bytes long)
+
+
+
+
+
+ the number of bytes that will be read from the stream
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous stream read operation started with
+g_input_stream_read_all_async().
+
+As a special exception to the normal conventions for functions that
+use #GError, if this function returns %FALSE (and sets @error) then
+@bytes_read will be set to the number of bytes that were successfully
+read before the error was encountered. This functionality is only
+available from C. If you need it from another language then you must
+write your own loop around g_input_stream_read_async().
+
+
+ %TRUE on success, %FALSE if there was an error
+
+
+
+
+ a #GInputStream
+
+
+
+ a #GAsyncResult
+
+
+
+ location to store the number of bytes that was read from the stream
+
+
+
+
+
+ Request an asynchronous read of @count bytes from the stream into the buffer
+starting at @buffer. When the operation is finished @callback will be called.
+You can then call g_input_stream_read_finish() to get the result of the
+operation.
+
+During an async request no other sync and async calls are allowed on @stream, and will
+result in %G_IO_ERROR_PENDING errors.
+
+A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
+
+On success, the number of bytes read into the buffer will be passed to the
+callback. It is not an error if this is not the same as the requested size, as it
+can happen e.g. near the end of a file, but generally we try to read
+as many bytes as requested. Zero is returned on end of file
+(or if @count is zero), but never otherwise.
+
+Any outstanding i/o request with higher priority (lower numerical value) will
+be executed before an outstanding request with lower priority. Default
+priority is %G_PRIORITY_DEFAULT.
+
+The asynchronous methods have a default fallback that uses threads to implement
+asynchronicity, so they are optional for inheriting classes. However, if you
+override one you must override all.
+
+
+
+
+
+
+ A #GInputStream.
+
+
+
+
+ a buffer to read data into (which should be at least count bytes long).
+
+
+
+
+
+ the number of bytes that will be read from the stream
+
+
+
+ the [I/O priority][io-priority]
+of the request.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Like g_input_stream_read(), this tries to read @count bytes from
+the stream in a blocking fashion. However, rather than reading into
+a user-supplied buffer, this will create a new #GBytes containing
+the data that was read. This may be easier to use from language
+bindings.
+
+If count is zero, returns a zero-length #GBytes and does nothing. A
+value of @count larger than %G_MAXSSIZE will cause a
+%G_IO_ERROR_INVALID_ARGUMENT error.
+
+On success, a new #GBytes is returned. It is not an error if the
+size of this object is not the same as the requested size, as it
+can happen e.g. near the end of a file. A zero-length #GBytes is
+returned on end of file (or if @count is zero), but never
+otherwise.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
+operation was partially finished when the operation was cancelled the
+partial result will be returned, without an error.
+
+On error %NULL is returned and @error is set accordingly.
+
+
+ a new #GBytes, or %NULL on error
+
+
+
+
+ a #GInputStream.
+
+
+
+ maximum number of bytes that will be read from the stream. Common
+values include 4096 and 8192.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Request an asynchronous read of @count bytes from the stream into a
+new #GBytes. When the operation is finished @callback will be
+called. You can then call g_input_stream_read_bytes_finish() to get the
+result of the operation.
+
+During an async request no other sync and async calls are allowed
+on @stream, and will result in %G_IO_ERROR_PENDING errors.
+
+A value of @count larger than %G_MAXSSIZE will cause a
+%G_IO_ERROR_INVALID_ARGUMENT error.
+
+On success, the new #GBytes will be passed to the callback. It is
+not an error if this is smaller than the requested size, as it can
+happen e.g. near the end of a file, but generally we try to read as
+many bytes as requested. Zero is returned on end of file (or if
+@count is zero), but never otherwise.
+
+Any outstanding I/O request with higher priority (lower numerical
+value) will be executed before an outstanding request with lower
+priority. Default priority is %G_PRIORITY_DEFAULT.
+
+
+
+
+
+
+ A #GInputStream.
+
+
+
+ the number of bytes that will be read from the stream
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous stream read-into-#GBytes operation.
+
+
+ the newly-allocated #GBytes, or %NULL on error
+
+
+
+
+ a #GInputStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Finishes an asynchronous stream read operation.
+
+
+ number of bytes read in, or -1 on error, or 0 on end of file.
+
+
+
+
+ a #GInputStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Sets @stream to have actions pending. If the pending flag is
+already set or @stream is closed, it will return %FALSE and set
+@error.
+
+
+ %TRUE if pending was previously unset and is now set.
+
+
+
+
+ input stream
+
+
+
+
+
+ Tries to skip @count bytes from the stream. Will block during the operation.
+
+This is identical to g_input_stream_read(), from a behaviour standpoint,
+but the bytes that are skipped are not returned to the user. Some
+streams have an implementation that is more efficient than reading the data.
+
+This function is optional for inherited classes, as the default implementation
+emulates it using read.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
+operation was partially finished when the operation was cancelled the
+partial result will be returned, without an error.
+
+
+ Number of bytes skipped, or -1 on error
+
+
+
+
+ a #GInputStream.
+
+
+
+ the number of bytes that will be skipped from the stream
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Request an asynchronous skip of @count bytes from the stream.
+When the operation is finished @callback will be called.
+You can then call g_input_stream_skip_finish() to get the result
+of the operation.
+
+During an async request no other sync and async calls are allowed,
+and will result in %G_IO_ERROR_PENDING errors.
+
+A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
+
+On success, the number of bytes skipped will be passed to the callback.
+It is not an error if this is not the same as the requested size, as it
+can happen e.g. near the end of a file, but generally we try to skip
+as many bytes as requested. Zero is returned on end of file
+(or if @count is zero), but never otherwise.
+
+Any outstanding i/o request with higher priority (lower numerical value)
+will be executed before an outstanding request with lower priority.
+Default priority is %G_PRIORITY_DEFAULT.
+
+The asynchronous methods have a default fallback that uses threads to
+implement asynchronicity, so they are optional for inheriting classes.
+However, if you override one, you must override all.
+
+
+
+
+
+
+ A #GInputStream.
+
+
+
+ the number of bytes that will be skipped from the stream
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes a stream skip operation.
+
+
+ the size of the bytes skipped, or `-1` on error.
+
+
+
+
+ a #GInputStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Number of bytes skipped, or -1 on error
+
+
+
+
+ a #GInputStream.
+
+
+
+ the number of bytes that will be skipped from the stream
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ A #GInputStream.
+
+
+
+
+ a buffer to read data into (which should be at least count bytes long).
+
+
+
+
+
+ the number of bytes that will be read from the stream
+
+
+
+ the [I/O priority][io-priority]
+of the request.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ number of bytes read in, or -1 on error, or 0 on end of file.
+
+
+
+
+ a #GInputStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ A #GInputStream.
+
+
+
+ the number of bytes that will be skipped from the stream
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ the size of the bytes skipped, or `-1` on error.
+
+
+
+
+ a #GInputStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ A #GInputStream.
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional cancellable object
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ %TRUE if the stream was closed successfully.
+
+
+
+
+ a #GInputStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Structure used for scatter/gather data input.
+You generally pass in an array of #GInputVectors
+and the operation will store the read data starting in the
+first buffer, switching to the next as needed.
+
+
+ Pointer to a buffer where data will be written.
+
+
+
+ the available size in @buffer.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #GListModel is an interface that represents a mutable list of
+#GObjects. Its main intention is as a model for various widgets in
+user interfaces, such as list views, but it can also be used as a
+convenient method of returning lists of data, with support for
+updates.
+
+Each object in the list may also report changes in itself via some
+mechanism (normally the #GObject::notify signal). Taken together
+with the #GListModel::items-changed signal, this provides for a list
+that can change its membership, and in which the members can change
+their individual properties.
+
+A good example would be the list of visible wireless network access
+points, where each access point can report dynamic properties such as
+signal strength.
+
+It is important to note that the #GListModel itself does not report
+changes to the individual items. It only reports changes to the list
+membership. If you want to observe changes to the objects themselves
+then you need to connect signals to the objects that you are
+interested in.
+
+All items in a #GListModel are of (or derived from) the same type.
+g_list_model_get_item_type() returns that type. The type may be an
+interface, in which case all objects in the list must implement it.
+
+The semantics are close to that of an array:
+g_list_model_get_n_items() returns the number of items in the list and
+g_list_model_get_item() returns an item at a (0-based) position. In
+order to allow implementations to calculate the list length lazily,
+you can also iterate over items: starting from 0, repeatedly call
+g_list_model_get_item() until it returns %NULL.
+
+An implementation may create objects lazily, but must take care to
+return the same object for a given position until all references to
+it are gone.
+
+On the other side, a consumer is expected only to hold references on
+objects that are currently "user visible", in order to facilitate the
+maximum level of laziness in the implementation of the list and to
+reduce the required number of signal connections at a given time.
+
+This interface is intended only to be used from a single thread. The
+thread in which it is appropriate to use it depends on the particular
+implementation, but typically it will be from the thread that owns
+the [thread-default main context][g-main-context-push-thread-default]
+in effect at the time that the model was created.
+
+Over time, it has established itself as good practice for listmodel
+implementations to provide properties `item-type` and `n-items` to
+ease working with them. While it is not required, it is recommended
+that implementations provide these two properties. They should return
+the values of g_list_model_get_item_type() and g_list_model_get_n_items()
+respectively and be defined as such:
+|[<!-- language="C" -->
+properties[PROP_ITEM_TYPE] =
+ g_param_spec_gtype ("item-type", "", "", G_TYPE_OBJECT,
+ G_PARAM_CONSTRUCT_ONLY | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
+properties[PROP_N_ITEMS] =
+ g_param_spec_uint ("n-items", "", "", 0, G_MAXUINT, 0,
+ G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
+]|
+
+
+ Get the item at @position. If @position is greater than the number of
+items in @list, %NULL is returned.
+
+%NULL is never returned for an index that is smaller than the length
+of the list. See g_list_model_get_n_items().
+
+
+ the object at @position.
+
+
+
+
+ a #GListModel
+
+
+
+ the position of the item to fetch
+
+
+
+
+
+ Gets the type of the items in @list.
+
+All items returned from g_list_model_get_item() are of the type
+returned by this function, or a subtype, or if the type is an
+interface, they are an implementation of that interface.
+
+The item type of a #GListModel can not change during the life of the
+model.
+
+
+ the #GType of the items contained in @list.
+
+
+
+
+ a #GListModel
+
+
+
+
+
+ Gets the number of items in @list.
+
+Depending on the model implementation, calling this function may be
+less efficient than iterating the list with increasing values for
+@position until g_list_model_get_item() returns %NULL.
+
+
+ the number of items in @list.
+
+
+
+
+ a #GListModel
+
+
+
+
+
+ Get the item at @position.
+
+If @position is greater than the number of items in @list, %NULL is
+returned.
+
+%NULL is never returned for an index that is smaller than the length
+of the list.
+
+See also: g_list_model_get_n_items()
+
+
+ the item at @position.
+
+
+
+
+ a #GListModel
+
+
+
+ the position of the item to fetch
+
+
+
+
+
+ Gets the type of the items in @list.
+
+All items returned from g_list_model_get_item() are of the type
+returned by this function, or a subtype, or if the type is an
+interface, they are an implementation of that interface.
+
+The item type of a #GListModel can not change during the life of the
+model.
+
+
+ the #GType of the items contained in @list.
+
+
+
+
+ a #GListModel
+
+
+
+
+
+ Gets the number of items in @list.
+
+Depending on the model implementation, calling this function may be
+less efficient than iterating the list with increasing values for
+@position until g_list_model_get_item() returns %NULL.
+
+
+ the number of items in @list.
+
+
+
+
+ a #GListModel
+
+
+
+
+
+ Get the item at @position.
+
+If @position is greater than the number of items in @list, %NULL is
+returned.
+
+%NULL is never returned for an index that is smaller than the length
+of the list.
+
+This function is meant to be used by language bindings in place
+of g_list_model_get_item().
+
+See also: g_list_model_get_n_items()
+
+
+ the object at @position.
+
+
+
+
+ a #GListModel
+
+
+
+ the position of the item to fetch
+
+
+
+
+
+ Emits the #GListModel::items-changed signal on @list.
+
+This function should only be called by classes implementing
+#GListModel. It has to be called after the internal representation
+of @list has been updated, because handlers connected to this signal
+might query the new state of the list.
+
+Implementations must only make changes to the model (as visible to
+its consumer) in places that will not cause problems for that
+consumer. For models that are driven directly by a write API (such
+as #GListStore), changes can be reported in response to uses of that
+API. For models that represent remote data, changes should only be
+made from a fresh mainloop dispatch. It is particularly not
+permitted to make changes in response to a call to the #GListModel
+consumer API.
+
+Stated another way: in general, it is assumed that code making a
+series of accesses to the model via the API, without returning to the
+mainloop, and without calling other code, will continue to view the
+same contents of the model.
+
+
+
+
+
+
+ a #GListModel
+
+
+
+ the position at which @list changed
+
+
+
+ the number of items removed
+
+
+
+ the number of items added
+
+
+
+
+
+ This signal is emitted whenever items were added to or removed
+from @list. At @position, @removed items were removed and @added
+items were added in their place.
+
+Note: If `removed != added`, the positions of all later items
+in the model change.
+
+
+
+
+
+ the position at which @list changed
+
+
+
+ the number of items removed
+
+
+
+ the number of items added
+
+
+
+
+
+
+ The virtual function table for #GListModel.
+
+
+ parent #GTypeInterface
+
+
+
+
+
+
+ the #GType of the items contained in @list.
+
+
+
+
+ a #GListModel
+
+
+
+
+
+
+
+
+
+ the number of items in @list.
+
+
+
+
+ a #GListModel
+
+
+
+
+
+
+
+
+
+ the object at @position.
+
+
+
+
+ a #GListModel
+
+
+
+ the position of the item to fetch
+
+
+
+
+
+
+
+ #GListStore is a simple implementation of #GListModel that stores all
+items in memory.
+
+It provides insertions, deletions, and lookups in logarithmic time
+with a fast path for the common case of iterating the list linearly.
+
+
+
+ Creates a new #GListStore with items of type @item_type. @item_type
+must be a subclass of #GObject.
+
+
+ a new #GListStore
+
+
+
+
+ the #GType of items in the list
+
+
+
+
+
+ Appends @item to @store. @item must be of type #GListStore:item-type.
+
+This function takes a ref on @item.
+
+Use g_list_store_splice() to append multiple items at the same time
+efficiently.
+
+
+
+
+
+
+ a #GListStore
+
+
+
+ the new item
+
+
+
+
+
+ Looks up the given @item in the list store by looping over the items until
+the first occurrence of @item. If @item was not found, then @position will
+not be set, and this method will return %FALSE.
+
+If you need to compare the two items with a custom comparison function, use
+g_list_store_find_with_equal_func() with a custom #GEqualFunc instead.
+
+
+ Whether @store contains @item. If it was found, @position will be
+set to the position where @item occurred for the first time.
+
+
+
+
+ a #GListStore
+
+
+
+ an item
+
+
+
+ the first position of @item, if it was found.
+
+
+
+
+
+ Looks up the given @item in the list store by looping over the items and
+comparing them with @equal_func until the first occurrence of @item which
+matches. If @item was not found, then @position will not be set, and this
+method will return %FALSE.
+
+@item is always passed as second parameter to @equal_func.
+
+Since GLib 2.76 it is possible to pass `NULL` for @item.
+
+
+ Whether @store contains @item. If it was found, @position will be
+set to the position where @item occurred for the first time.
+
+
+
+
+ a #GListStore
+
+
+
+ an item
+
+
+
+ A custom equality check function
+
+
+
+ the first position of @item, if it was found.
+
+
+
+
+
+ Like g_list_store_find_with_equal_func() but with an additional @user_data
+that is passed to @equal_func.
+
+@item is always passed as second parameter to @equal_func.
+
+Since GLib 2.76 it is possible to pass `NULL` for @item.
+
+
+ Whether @store contains @item. If it was found, @position will be
+set to the position where @item occurred for the first time.
+
+
+
+
+ a #GListStore
+
+
+
+ an item
+
+
+
+ A custom equality check function
+
+
+
+ user data for @equal_func
+
+
+
+ the first position of @item, if it was found.
+
+
+
+
+
+ Inserts @item into @store at @position. @item must be of type
+#GListStore:item-type or derived from it. @position must be smaller
+than the length of the list, or equal to it to append.
+
+This function takes a ref on @item.
+
+Use g_list_store_splice() to insert multiple items at the same time
+efficiently.
+
+
+
+
+
+
+ a #GListStore
+
+
+
+ the position at which to insert the new item
+
+
+
+ the new item
+
+
+
+
+
+ Inserts @item into @store at a position to be determined by the
+@compare_func.
+
+The list must already be sorted before calling this function or the
+result is undefined. Usually you would approach this by only ever
+inserting items by way of this function.
+
+This function takes a ref on @item.
+
+
+ the position at which @item was inserted
+
+
+
+
+ a #GListStore
+
+
+
+ the new item
+
+
+
+ pairwise comparison function for sorting
+
+
+
+ user data for @compare_func
+
+
+
+
+
+ Removes the item from @store that is at @position. @position must be
+smaller than the current length of the list.
+
+Use g_list_store_splice() to remove multiple items at the same time
+efficiently.
+
+
+
+
+
+
+ a #GListStore
+
+
+
+ the position of the item that is to be removed
+
+
+
+
+
+ Removes all items from @store.
+
+
+
+
+
+
+ a #GListStore
+
+
+
+
+
+ Sort the items in @store according to @compare_func.
+
+
+
+
+
+
+ a #GListStore
+
+
+
+ pairwise comparison function for sorting
+
+
+
+ user data for @compare_func
+
+
+
+
+
+ Changes @store by removing @n_removals items and adding @n_additions
+items to it. @additions must contain @n_additions items of type
+#GListStore:item-type. %NULL is not permitted.
+
+This function is more efficient than g_list_store_insert() and
+g_list_store_remove(), because it only emits
+#GListModel::items-changed once for the change.
+
+This function takes a ref on each item in @additions.
+
+The parameters @position and @n_removals must be correct (ie:
+@position + @n_removals must be less than or equal to the length of
+the list at the time this function is called).
+
+
+
+
+
+
+ a #GListStore
+
+
+
+ the position at which to make the change
+
+
+
+ the number of items to remove
+
+
+
+ the items to add
+
+
+
+
+
+ the number of items to add
+
+
+
+
+
+ The type of items contained in this list store. Items must be
+subclasses of #GObject.
+
+
+
+ The number of items contained in this list store.
+
+
+
+
+
+
+
+
+
+
+ Extends the #GIcon interface and adds the ability to
+load icons from streams.
+
+
+
+ Loads a loadable icon. For the asynchronous version of this function,
+see g_loadable_icon_load_async().
+
+
+ a #GInputStream to read the icon from.
+
+
+
+
+ a #GLoadableIcon.
+
+
+
+ an integer.
+
+
+
+ a location to store the type of the loaded
+icon, %NULL to ignore.
+
+
+
+ optional #GCancellable object, %NULL to
+ignore.
+
+
+
+
+
+ Loads an icon asynchronously. To finish this function, see
+g_loadable_icon_load_finish(). For the synchronous, blocking
+version of this function, see g_loadable_icon_load().
+
+
+
+
+
+
+ a #GLoadableIcon.
+
+
+
+ an integer.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback to call when the
+ request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous icon load started in g_loadable_icon_load_async().
+
+
+ a #GInputStream to read the icon from.
+
+
+
+
+ a #GLoadableIcon.
+
+
+
+ a #GAsyncResult.
+
+
+
+ a location to store the type of the loaded
+ icon, %NULL to ignore.
+
+
+
+
+
+ Loads a loadable icon. For the asynchronous version of this function,
+see g_loadable_icon_load_async().
+
+
+ a #GInputStream to read the icon from.
+
+
+
+
+ a #GLoadableIcon.
+
+
+
+ an integer.
+
+
+
+ a location to store the type of the loaded
+icon, %NULL to ignore.
+
+
+
+ optional #GCancellable object, %NULL to
+ignore.
+
+
+
+
+
+ Loads an icon asynchronously. To finish this function, see
+g_loadable_icon_load_finish(). For the synchronous, blocking
+version of this function, see g_loadable_icon_load().
+
+
+
+
+
+
+ a #GLoadableIcon.
+
+
+
+ an integer.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback to call when the
+ request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous icon load started in g_loadable_icon_load_async().
+
+
+ a #GInputStream to read the icon from.
+
+
+
+
+ a #GLoadableIcon.
+
+
+
+ a #GAsyncResult.
+
+
+
+ a location to store the type of the loaded
+ icon, %NULL to ignore.
+
+
+
+
+
+
+ Interface for icons that can be loaded as a stream.
+
+
+ The parent interface.
+
+
+
+
+
+
+ a #GInputStream to read the icon from.
+
+
+
+
+ a #GLoadableIcon.
+
+
+
+ an integer.
+
+
+
+ a location to store the type of the loaded
+icon, %NULL to ignore.
+
+
+
+ optional #GCancellable object, %NULL to
+ignore.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GLoadableIcon.
+
+
+
+ an integer.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback to call when the
+ request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ a #GInputStream to read the icon from.
+
+
+
+
+ a #GLoadableIcon.
+
+
+
+ a #GAsyncResult.
+
+
+
+ a location to store the type of the loaded
+ icon, %NULL to ignore.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Extension point for memory usage monitoring functionality.
+See [Extending GIO][extending-gio].
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The menu item attribute which holds the action name of the item. Action
+names are namespaced with an identifier for the action group in which the
+action resides. For example, "win." for window-specific actions and "app."
+for application-wide actions.
+
+See also g_menu_model_get_item_attribute() and g_menu_item_set_attribute().
+
+
+
+
+ The menu item attribute that holds the namespace for all action names in
+menus that are linked from this item.
+
+
+
+
+ The menu item attribute which holds the icon of the item.
+
+The icon is stored in the format returned by g_icon_serialize().
+
+This attribute is intended only to represent 'noun' icons such as
+favicons for a webpage, or application icons. It should not be used
+for 'verbs' (ie: stock icons).
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The menu item attribute which holds the label of the item.
+
+
+
+
+ The menu item attribute which holds the target with which the item's action
+will be activated.
+
+See also g_menu_item_set_action_and_target()
+
+
+
+
+ The maximum number of entries in a menu section supported by
+g_dbus_connection_export_menu_model().
+
+The exact value of the limit may change in future GLib versions.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The name of the link that associates a menu item with a section. The linked
+menu will usually be shown in place of the menu item, using the item's label
+as a header.
+
+See also g_menu_item_set_link().
+
+
+
+
+ The name of the link that associates a menu item with a submenu.
+
+See also g_menu_item_set_link().
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #GMemoryInputStream is a class for using arbitrary
+memory chunks as input for GIO streaming input operations.
+
+As of GLib 2.34, #GMemoryInputStream implements
+#GPollableInputStream.
+
+
+
+
+ Creates a new empty #GMemoryInputStream.
+
+
+ a new #GInputStream
+
+
+
+
+ Creates a new #GMemoryInputStream with data from the given @bytes.
+
+
+ new #GInputStream read from @bytes
+
+
+
+
+ a #GBytes
+
+
+
+
+
+ Creates a new #GMemoryInputStream with data in memory of a given size.
+
+
+ new #GInputStream read from @data of @len bytes.
+
+
+
+
+ input data
+
+
+
+
+
+ length of the data, may be -1 if @data is a nul-terminated string
+
+
+
+ function that is called to free @data, or %NULL
+
+
+
+
+
+ Appends @bytes to data that can be read from the input stream.
+
+
+
+
+
+
+ a #GMemoryInputStream
+
+
+
+ input data
+
+
+
+
+
+ Appends @data to data that can be read from the input stream
+
+
+
+
+
+
+ a #GMemoryInputStream
+
+
+
+ input data
+
+
+
+
+
+ length of the data, may be -1 if @data is a nul-terminated string
+
+
+
+ function that is called to free @data, or %NULL
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #GMemoryMonitor will monitor system memory and suggest to the application
+when to free memory so as to leave more room for other applications.
+It is implemented on Linux using the [Low Memory Monitor](https://gitlab.freedesktop.org/hadess/low-memory-monitor/)
+([API documentation](https://hadess.pages.freedesktop.org/low-memory-monitor/)).
+
+There is also an implementation for use inside Flatpak sandboxes.
+
+Possible actions to take when the signal is received are:
+
+ - Free caches
+ - Save files that haven't been looked at in a while to disk, ready to be reopened when needed
+ - Run a garbage collection cycle
+ - Try and compress fragmented allocations
+ - Exit on idle if the process has no reason to stay around
+ - Call [`malloc_trim(3)`](man:malloc_trim) to return cached heap pages to
+ the kernel (if supported by your libc)
+
+Note that some actions may not always improve system performance, and so
+should be profiled for your application. `malloc_trim()`, for example, may
+make future heap allocations slower (due to releasing cached heap pages back
+to the kernel).
+
+See #GMemoryMonitorWarningLevel for details on the various warning levels.
+
+|[<!-- language="C" -->
+static void
+warning_cb (GMemoryMonitor *m, GMemoryMonitorWarningLevel level)
+{
+ g_debug ("Warning level: %d", level);
+ if (warning_level > G_MEMORY_MONITOR_WARNING_LEVEL_LOW)
+ drop_caches ();
+}
+
+static GMemoryMonitor *
+monitor_low_memory (void)
+{
+ GMemoryMonitor *m;
+ m = g_memory_monitor_dup_default ();
+ g_signal_connect (G_OBJECT (m), "low-memory-warning",
+ G_CALLBACK (warning_cb), NULL);
+ return m;
+}
+]|
+
+Don't forget to disconnect the #GMemoryMonitor::low-memory-warning
+signal, and unref the #GMemoryMonitor itself when exiting.
+
+
+
+ Gets a reference to the default #GMemoryMonitor for the system.
+
+
+ a new reference to the default #GMemoryMonitor
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Emitted when the system is running low on free memory. The signal
+handler should then take the appropriate action depending on the
+warning level. See the #GMemoryMonitorWarningLevel documentation for
+details.
+
+
+
+
+
+ the #GMemoryMonitorWarningLevel warning level
+
+
+
+
+
+
+ The virtual function table for #GMemoryMonitor.
+
+
+ The parent interface.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Memory availability warning levels.
+
+Note that because new values might be added, it is recommended that applications check
+#GMemoryMonitorWarningLevel as ranges, for example:
+|[<!-- language="C" -->
+if (warning_level > G_MEMORY_MONITOR_WARNING_LEVEL_LOW)
+ drop_caches ();
+]|
+
+ Memory on the device is low, processes
+ should free up unneeded resources (for example, in-memory caches) so they can
+ be used elsewhere.
+
+
+ Same as @G_MEMORY_MONITOR_WARNING_LEVEL_LOW
+ but the device has even less free memory, so processes should try harder to free
+ up unneeded resources. If your process does not need to stay running, it is a
+ good time for it to quit.
+
+
+ The system will soon start terminating
+ processes to reclaim memory, including background processes.
+
+
+
+ #GMemoryOutputStream is a class for using arbitrary
+memory chunks as output for GIO streaming output operations.
+
+As of GLib 2.34, #GMemoryOutputStream trivially implements
+#GPollableOutputStream: it always polls as ready.
+
+
+
+
+ Creates a new #GMemoryOutputStream.
+
+In most cases this is not the function you want. See
+g_memory_output_stream_new_resizable() instead.
+
+If @data is non-%NULL, the stream will use that for its internal storage.
+
+If @realloc_fn is non-%NULL, it will be used for resizing the internal
+storage when necessary and the stream will be considered resizable.
+In that case, the stream will start out being (conceptually) empty.
+@size is used only as a hint for how big @data is. Specifically,
+seeking to the end of a newly-created stream will seek to zero, not
+@size. Seeking past the end of the stream and then writing will
+introduce a zero-filled gap.
+
+If @realloc_fn is %NULL then the stream is fixed-sized. Seeking to
+the end will seek to @size exactly. Writing past the end will give
+an 'out of space' error. Attempting to seek past the end will fail.
+Unlike the resizable case, seeking to an offset within the stream and
+writing will preserve the bytes passed in as @data before that point
+and will return them as part of g_memory_output_stream_steal_data().
+If you intend to seek you should probably therefore ensure that @data
+is properly initialised.
+
+It is probably only meaningful to provide @data and @size in the case
+that you want a fixed-sized stream. Put another way: if @realloc_fn
+is non-%NULL then it makes most sense to give @data as %NULL and
+@size as 0 (allowing #GMemoryOutputStream to do the initial
+allocation for itself).
+
+|[<!-- language="C" -->
+// a stream that can grow
+stream = g_memory_output_stream_new (NULL, 0, realloc, free);
+
+// another stream that can grow
+stream2 = g_memory_output_stream_new (NULL, 0, g_realloc, g_free);
+
+// a fixed-size stream
+data = malloc (200);
+stream3 = g_memory_output_stream_new (data, 200, NULL, free);
+]|
+
+
+ A newly created #GMemoryOutputStream object.
+
+
+
+
+ pointer to a chunk of memory to use, or %NULL
+
+
+
+ the size of @data
+
+
+
+ a function with realloc() semantics (like g_realloc())
+ to be called when @data needs to be grown, or %NULL
+
+
+
+ a function to be called on @data when the stream is
+ finalized, or %NULL
+
+
+
+
+
+ Creates a new #GMemoryOutputStream, using g_realloc() and g_free()
+for memory allocation.
+
+
+
+
+
+
+ Gets any loaded data from the @ostream.
+
+Note that the returned pointer may become invalid on the next
+write or truncate operation on the stream.
+
+
+ pointer to the stream's data, or %NULL if the data
+ has been stolen
+
+
+
+
+ a #GMemoryOutputStream
+
+
+
+
+
+ Returns the number of bytes from the start up to including the last
+byte written in the stream that has not been truncated away.
+
+
+ the number of bytes written to the stream
+
+
+
+
+ a #GMemoryOutputStream
+
+
+
+
+
+ Gets the size of the currently allocated data area (available from
+g_memory_output_stream_get_data()).
+
+You probably don't want to use this function on resizable streams.
+See g_memory_output_stream_get_data_size() instead. For resizable
+streams the size returned by this function is an implementation
+detail and may be change at any time in response to operations on the
+stream.
+
+If the stream is fixed-sized (ie: no realloc was passed to
+g_memory_output_stream_new()) then this is the maximum size of the
+stream and further writes will return %G_IO_ERROR_NO_SPACE.
+
+In any case, if you want the number of bytes currently written to the
+stream, use g_memory_output_stream_get_data_size().
+
+
+ the number of bytes allocated for the data buffer
+
+
+
+
+ a #GMemoryOutputStream
+
+
+
+
+
+ Returns data from the @ostream as a #GBytes. @ostream must be
+closed before calling this function.
+
+
+ the stream's data
+
+
+
+
+ a #GMemoryOutputStream
+
+
+
+
+
+ Gets any loaded data from the @ostream. Ownership of the data
+is transferred to the caller; when no longer needed it must be
+freed using the free function set in @ostream's
+#GMemoryOutputStream:destroy-function property.
+
+@ostream must be closed before calling this function.
+
+
+ the stream's data, or %NULL if it has previously
+ been stolen
+
+
+
+
+ a #GMemoryOutputStream
+
+
+
+
+
+ Pointer to buffer where data will be written.
+
+
+
+ Size of data written to the buffer.
+
+
+
+ Function called with the buffer as argument when the stream is destroyed.
+
+
+
+ Function with realloc semantics called to enlarge the buffer.
+
+
+
+ Current size of the data buffer.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #GMenu is a simple implementation of #GMenuModel.
+You populate a #GMenu by adding #GMenuItem instances to it.
+
+There are some convenience functions to allow you to directly
+add items (avoiding #GMenuItem) for the common cases. To add
+a regular item, use g_menu_insert(). To add a section, use
+g_menu_insert_section(). To add a submenu, use
+g_menu_insert_submenu().
+
+ Creates a new #GMenu.
+
+The new menu has no items.
+
+
+ a new #GMenu
+
+
+
+
+ Convenience function for appending a normal menu item to the end of
+@menu. Combine g_menu_item_new() and g_menu_insert_item() for a more
+flexible alternative.
+
+
+
+
+
+
+ a #GMenu
+
+
+
+ the section label, or %NULL
+
+
+
+ the detailed action string, or %NULL
+
+
+
+
+
+ Appends @item to the end of @menu.
+
+See g_menu_insert_item() for more information.
+
+
+
+
+
+
+ a #GMenu
+
+
+
+ a #GMenuItem to append
+
+
+
+
+
+ Convenience function for appending a section menu item to the end of
+@menu. Combine g_menu_item_new_section() and g_menu_insert_item() for a
+more flexible alternative.
+
+
+
+
+
+
+ a #GMenu
+
+
+
+ the section label, or %NULL
+
+
+
+ a #GMenuModel with the items of the section
+
+
+
+
+
+ Convenience function for appending a submenu menu item to the end of
+@menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for a
+more flexible alternative.
+
+
+
+
+
+
+ a #GMenu
+
+
+
+ the section label, or %NULL
+
+
+
+ a #GMenuModel with the items of the submenu
+
+
+
+
+
+ Marks @menu as frozen.
+
+After the menu is frozen, it is an error to attempt to make any
+changes to it. In effect this means that the #GMenu API must no
+longer be used.
+
+This function causes g_menu_model_is_mutable() to begin returning
+%FALSE, which has some positive performance implications.
+
+
+
+
+
+
+ a #GMenu
+
+
+
+
+
+ Convenience function for inserting a normal menu item into @menu.
+Combine g_menu_item_new() and g_menu_insert_item() for a more flexible
+alternative.
+
+
+
+
+
+
+ a #GMenu
+
+
+
+ the position at which to insert the item
+
+
+
+ the section label, or %NULL
+
+
+
+ the detailed action string, or %NULL
+
+
+
+
+
+ Inserts @item into @menu.
+
+The "insertion" is actually done by copying all of the attribute and
+link values of @item and using them to form a new item within @menu.
+As such, @item itself is not really inserted, but rather, a menu item
+that is exactly the same as the one presently described by @item.
+
+This means that @item is essentially useless after the insertion
+occurs. Any changes you make to it are ignored unless it is inserted
+again (at which point its updated values will be copied).
+
+You should probably just free @item once you're done.
+
+There are many convenience functions to take care of common cases.
+See g_menu_insert(), g_menu_insert_section() and
+g_menu_insert_submenu() as well as "prepend" and "append" variants of
+each of these functions.
+
+
+
+
+
+
+ a #GMenu
+
+
+
+ the position at which to insert the item
+
+
+
+ the #GMenuItem to insert
+
+
+
+
+
+ Convenience function for inserting a section menu item into @menu.
+Combine g_menu_item_new_section() and g_menu_insert_item() for a more
+flexible alternative.
+
+
+
+
+
+
+ a #GMenu
+
+
+
+ the position at which to insert the item
+
+
+
+ the section label, or %NULL
+
+
+
+ a #GMenuModel with the items of the section
+
+
+
+
+
+ Convenience function for inserting a submenu menu item into @menu.
+Combine g_menu_item_new_submenu() and g_menu_insert_item() for a more
+flexible alternative.
+
+
+
+
+
+
+ a #GMenu
+
+
+
+ the position at which to insert the item
+
+
+
+ the section label, or %NULL
+
+
+
+ a #GMenuModel with the items of the submenu
+
+
+
+
+
+ Convenience function for prepending a normal menu item to the start
+of @menu. Combine g_menu_item_new() and g_menu_insert_item() for a more
+flexible alternative.
+
+
+
+
+
+
+ a #GMenu
+
+
+
+ the section label, or %NULL
+
+
+
+ the detailed action string, or %NULL
+
+
+
+
+
+ Prepends @item to the start of @menu.
+
+See g_menu_insert_item() for more information.
+
+
+
+
+
+
+ a #GMenu
+
+
+
+ a #GMenuItem to prepend
+
+
+
+
+
+ Convenience function for prepending a section menu item to the start
+of @menu. Combine g_menu_item_new_section() and g_menu_insert_item() for
+a more flexible alternative.
+
+
+
+
+
+
+ a #GMenu
+
+
+
+ the section label, or %NULL
+
+
+
+ a #GMenuModel with the items of the section
+
+
+
+
+
+ Convenience function for prepending a submenu menu item to the start
+of @menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for
+a more flexible alternative.
+
+
+
+
+
+
+ a #GMenu
+
+
+
+ the section label, or %NULL
+
+
+
+ a #GMenuModel with the items of the submenu
+
+
+
+
+
+ Removes an item from the menu.
+
+@position gives the index of the item to remove.
+
+It is an error if position is not in range the range from 0 to one
+less than the number of items in the menu.
+
+It is not possible to remove items by identity since items are added
+to the menu simply by copying their links and attributes (ie:
+identity of the item itself is not preserved).
+
+
+
+
+
+
+ a #GMenu
+
+
+
+ the position of the item to remove
+
+
+
+
+
+ Removes all items in the menu.
+
+
+
+
+
+
+ a #GMenu
+
+
+
+
+
+
+ #GMenuAttributeIter is an opaque structure type. You must access it
+using the functions below.
+
+
+ This function combines g_menu_attribute_iter_next() with
+g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value().
+
+First the iterator is advanced to the next (possibly first) attribute.
+If that fails, then %FALSE is returned and there are no other
+effects.
+
+If successful, @name and @value are set to the name and value of the
+attribute that has just been advanced to. At this point,
+g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value() will
+return the same values again.
+
+The value returned in @name remains valid for as long as the iterator
+remains at the current position. The value returned in @value must
+be unreffed using g_variant_unref() when it is no longer in use.
+
+
+ %TRUE on success, or %FALSE if there is no additional
+ attribute
+
+
+
+
+ a #GMenuAttributeIter
+
+
+
+ the type of the attribute
+
+
+
+ the attribute value
+
+
+
+
+
+ Gets the name of the attribute at the current iterator position, as
+a string.
+
+The iterator is not advanced.
+
+
+ the name of the attribute
+
+
+
+
+ a #GMenuAttributeIter
+
+
+
+
+
+ This function combines g_menu_attribute_iter_next() with
+g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value().
+
+First the iterator is advanced to the next (possibly first) attribute.
+If that fails, then %FALSE is returned and there are no other
+effects.
+
+If successful, @name and @value are set to the name and value of the
+attribute that has just been advanced to. At this point,
+g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value() will
+return the same values again.
+
+The value returned in @name remains valid for as long as the iterator
+remains at the current position. The value returned in @value must
+be unreffed using g_variant_unref() when it is no longer in use.
+
+
+ %TRUE on success, or %FALSE if there is no additional
+ attribute
+
+
+
+
+ a #GMenuAttributeIter
+
+
+
+ the type of the attribute
+
+
+
+ the attribute value
+
+
+
+
+
+ Gets the value of the attribute at the current iterator position.
+
+The iterator is not advanced.
+
+
+ the value of the current attribute
+
+
+
+
+ a #GMenuAttributeIter
+
+
+
+
+
+ Attempts to advance the iterator to the next (possibly first)
+attribute.
+
+%TRUE is returned on success, or %FALSE if there are no more
+attributes.
+
+You must call this function when you first acquire the iterator
+to advance it to the first attribute (and determine if the first
+attribute exists at all).
+
+
+ %TRUE on success, or %FALSE when there are no more attributes
+
+
+
+
+ a #GMenuAttributeIter
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ %TRUE on success, or %FALSE if there is no additional
+ attribute
+
+
+
+
+ a #GMenuAttributeIter
+
+
+
+ the type of the attribute
+
+
+
+ the attribute value
+
+
+
+
+
+
+
+
+
+
+ #GMenuItem is an opaque structure type. You must access it using the
+functions below.
+
+ Creates a new #GMenuItem.
+
+If @label is non-%NULL it is used to set the "label" attribute of the
+new item.
+
+If @detailed_action is non-%NULL it is used to set the "action" and
+possibly the "target" attribute of the new item. See
+g_menu_item_set_detailed_action() for more information.
+
+
+ a new #GMenuItem
+
+
+
+
+ the section label, or %NULL
+
+
+
+ the detailed action string, or %NULL
+
+
+
+
+
+ Creates a #GMenuItem as an exact copy of an existing menu item in a
+#GMenuModel.
+
+@item_index must be valid (ie: be sure to call
+g_menu_model_get_n_items() first).
+
+
+ a new #GMenuItem.
+
+
+
+
+ a #GMenuModel
+
+
+
+ the index of an item in @model
+
+
+
+
+
+ Creates a new #GMenuItem representing a section.
+
+This is a convenience API around g_menu_item_new() and
+g_menu_item_set_section().
+
+The effect of having one menu appear as a section of another is
+exactly as it sounds: the items from @section become a direct part of
+the menu that @menu_item is added to.
+
+Visual separation is typically displayed between two non-empty
+sections. If @label is non-%NULL then it will be encorporated into
+this visual indication. This allows for labeled subsections of a
+menu.
+
+As a simple example, consider a typical "Edit" menu from a simple
+program. It probably contains an "Undo" and "Redo" item, followed by
+a separator, followed by "Cut", "Copy" and "Paste".
+
+This would be accomplished by creating three #GMenu instances. The
+first would be populated with the "Undo" and "Redo" items, and the
+second with the "Cut", "Copy" and "Paste" items. The first and
+second menus would then be added as submenus of the third. In XML
+format, this would look something like the following:
+|[
+<menu id='edit-menu'>
+ <section>
+ <item label='Undo'/>
+ <item label='Redo'/>
+ </section>
+ <section>
+ <item label='Cut'/>
+ <item label='Copy'/>
+ <item label='Paste'/>
+ </section>
+</menu>
+]|
+
+The following example is exactly equivalent. It is more illustrative
+of the exact relationship between the menus and items (keeping in
+mind that the 'link' element defines a new menu that is linked to the
+containing one). The style of the second example is more verbose and
+difficult to read (and therefore not recommended except for the
+purpose of understanding what is really going on).
+|[
+<menu id='edit-menu'>
+ <item>
+ <link name='section'>
+ <item label='Undo'/>
+ <item label='Redo'/>
+ </link>
+ </item>
+ <item>
+ <link name='section'>
+ <item label='Cut'/>
+ <item label='Copy'/>
+ <item label='Paste'/>
+ </link>
+ </item>
+</menu>
+]|
+
+
+ a new #GMenuItem
+
+
+
+
+ the section label, or %NULL
+
+
+
+ a #GMenuModel with the items of the section
+
+
+
+
+
+ Creates a new #GMenuItem representing a submenu.
+
+This is a convenience API around g_menu_item_new() and
+g_menu_item_set_submenu().
+
+
+ a new #GMenuItem
+
+
+
+
+ the section label, or %NULL
+
+
+
+ a #GMenuModel with the items of the submenu
+
+
+
+
+
+ Queries the named @attribute on @menu_item.
+
+If the attribute exists and matches the #GVariantType corresponding
+to @format_string then @format_string is used to deconstruct the
+value into the positional parameters and %TRUE is returned.
+
+If the attribute does not exist, or it does exist but has the wrong
+type, then the positional parameters are ignored and %FALSE is
+returned.
+
+
+ %TRUE if the named attribute was found with the expected
+ type
+
+
+
+
+ a #GMenuItem
+
+
+
+ the attribute name to query
+
+
+
+ a #GVariant format string
+
+
+
+ positional parameters, as per @format_string
+
+
+
+
+
+ Queries the named @attribute on @menu_item.
+
+If @expected_type is specified and the attribute does not have this
+type, %NULL is returned. %NULL is also returned if the attribute
+simply does not exist.
+
+
+ the attribute value, or %NULL
+
+
+
+
+ a #GMenuItem
+
+
+
+ the attribute name to query
+
+
+
+ the expected type of the attribute
+
+
+
+
+
+ Queries the named @link on @menu_item.
+
+
+ the link, or %NULL
+
+
+
+
+ a #GMenuItem
+
+
+
+ the link name to query
+
+
+
+
+
+ Sets or unsets the "action" and "target" attributes of @menu_item.
+
+If @action is %NULL then both the "action" and "target" attributes
+are unset (and @format_string is ignored along with the positional
+parameters).
+
+If @action is non-%NULL then the "action" attribute is set.
+@format_string is then inspected. If it is non-%NULL then the proper
+position parameters are collected to create a #GVariant instance to
+use as the target value. If it is %NULL then the positional
+parameters are ignored and the "target" attribute is unset.
+
+See also g_menu_item_set_action_and_target_value() for an equivalent
+call that directly accepts a #GVariant. See
+g_menu_item_set_detailed_action() for a more convenient version that
+works with string-typed targets.
+
+See also g_menu_item_set_action_and_target_value() for a
+description of the semantics of the action and target attributes.
+
+
+
+
+
+
+ a #GMenuItem
+
+
+
+ the name of the action for this item
+
+
+
+ a GVariant format string
+
+
+
+ positional parameters, as per @format_string
+
+
+
+
+
+ Sets or unsets the "action" and "target" attributes of @menu_item.
+
+If @action is %NULL then both the "action" and "target" attributes
+are unset (and @target_value is ignored).
+
+If @action is non-%NULL then the "action" attribute is set. The
+"target" attribute is then set to the value of @target_value if it is
+non-%NULL or unset otherwise.
+
+Normal menu items (ie: not submenu, section or other custom item
+types) are expected to have the "action" attribute set to identify
+the action that they are associated with. The state type of the
+action help to determine the disposition of the menu item. See
+#GAction and #GActionGroup for an overview of actions.
+
+In general, clicking on the menu item will result in activation of
+the named action with the "target" attribute given as the parameter
+to the action invocation. If the "target" attribute is not set then
+the action is invoked with no parameter.
+
+If the action has no state then the menu item is usually drawn as a
+plain menu item (ie: with no additional decoration).
+
+If the action has a boolean state then the menu item is usually drawn
+as a toggle menu item (ie: with a checkmark or equivalent
+indication). The item should be marked as 'toggled' or 'checked'
+when the boolean state is %TRUE.
+
+If the action has a string state then the menu item is usually drawn
+as a radio menu item (ie: with a radio bullet or equivalent
+indication). The item should be marked as 'selected' when the string
+state is equal to the value of the @target property.
+
+See g_menu_item_set_action_and_target() or
+g_menu_item_set_detailed_action() for two equivalent calls that are
+probably more convenient for most uses.
+
+
+
+
+
+
+ a #GMenuItem
+
+
+
+ the name of the action for this item
+
+
+
+ a #GVariant to use as the action target
+
+
+
+
+
+ Sets or unsets an attribute on @menu_item.
+
+The attribute to set or unset is specified by @attribute. This
+can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL,
+%G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom
+attribute name.
+Attribute names are restricted to lowercase characters, numbers
+and '-'. Furthermore, the names must begin with a lowercase character,
+must not end with a '-', and must not contain consecutive dashes.
+
+If @format_string is non-%NULL then the proper position parameters
+are collected to create a #GVariant instance to use as the attribute
+value. If it is %NULL then the positional parameterrs are ignored
+and the named attribute is unset.
+
+See also g_menu_item_set_attribute_value() for an equivalent call
+that directly accepts a #GVariant.
+
+
+
+
+
+
+ a #GMenuItem
+
+
+
+ the attribute to set
+
+
+
+ a #GVariant format string, or %NULL
+
+
+
+ positional parameters, as per @format_string
+
+
+
+
+
+ Sets or unsets an attribute on @menu_item.
+
+The attribute to set or unset is specified by @attribute. This
+can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL,
+%G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom
+attribute name.
+Attribute names are restricted to lowercase characters, numbers
+and '-'. Furthermore, the names must begin with a lowercase character,
+must not end with a '-', and must not contain consecutive dashes.
+
+must consist only of lowercase
+ASCII characters, digits and '-'.
+
+If @value is non-%NULL then it is used as the new value for the
+attribute. If @value is %NULL then the attribute is unset. If
+the @value #GVariant is floating, it is consumed.
+
+See also g_menu_item_set_attribute() for a more convenient way to do
+the same.
+
+
+
+
+
+
+ a #GMenuItem
+
+
+
+ the attribute to set
+
+
+
+ a #GVariant to use as the value, or %NULL
+
+
+
+
+
+ Sets the "action" and possibly the "target" attribute of @menu_item.
+
+The format of @detailed_action is the same format parsed by
+g_action_parse_detailed_name().
+
+See g_menu_item_set_action_and_target() or
+g_menu_item_set_action_and_target_value() for more flexible (but
+slightly less convenient) alternatives.
+
+See also g_menu_item_set_action_and_target_value() for a description of
+the semantics of the action and target attributes.
+
+
+
+
+
+
+ a #GMenuItem
+
+
+
+ the "detailed" action string
+
+
+
+
+
+ Sets (or unsets) the icon on @menu_item.
+
+This call is the same as calling g_icon_serialize() and using the
+result as the value to g_menu_item_set_attribute_value() for
+%G_MENU_ATTRIBUTE_ICON.
+
+This API is only intended for use with "noun" menu items; things like
+bookmarks or applications in an "Open With" menu. Don't use it on
+menu items corresponding to verbs (eg: stock icons for 'Save' or
+'Quit').
+
+If @icon is %NULL then the icon is unset.
+
+
+
+
+
+
+ a #GMenuItem
+
+
+
+ a #GIcon, or %NULL
+
+
+
+
+
+ Sets or unsets the "label" attribute of @menu_item.
+
+If @label is non-%NULL it is used as the label for the menu item. If
+it is %NULL then the label attribute is unset.
+
+
+
+
+
+
+ a #GMenuItem
+
+
+
+ the label to set, or %NULL to unset
+
+
+
+
+
+ Creates a link from @menu_item to @model if non-%NULL, or unsets it.
+
+Links are used to establish a relationship between a particular menu
+item and another menu. For example, %G_MENU_LINK_SUBMENU is used to
+associate a submenu with a particular menu item, and %G_MENU_LINK_SECTION
+is used to create a section. Other types of link can be used, but there
+is no guarantee that clients will be able to make sense of them.
+Link types are restricted to lowercase characters, numbers
+and '-'. Furthermore, the names must begin with a lowercase character,
+must not end with a '-', and must not contain consecutive dashes.
+
+
+
+
+
+
+ a #GMenuItem
+
+
+
+ type of link to establish or unset
+
+
+
+ the #GMenuModel to link to (or %NULL to unset)
+
+
+
+
+
+ Sets or unsets the "section" link of @menu_item to @section.
+
+The effect of having one menu appear as a section of another is
+exactly as it sounds: the items from @section become a direct part of
+the menu that @menu_item is added to. See g_menu_item_new_section()
+for more information about what it means for a menu item to be a
+section.
+
+
+
+
+
+
+ a #GMenuItem
+
+
+
+ a #GMenuModel, or %NULL
+
+
+
+
+
+ Sets or unsets the "submenu" link of @menu_item to @submenu.
+
+If @submenu is non-%NULL, it is linked to. If it is %NULL then the
+link is unset.
+
+The effect of having one menu appear as a submenu of another is
+exactly as it sounds.
+
+
+
+
+
+
+ a #GMenuItem
+
+
+
+ a #GMenuModel, or %NULL
+
+
+
+
+
+
+ #GMenuLinkIter is an opaque structure type. You must access it using
+the functions below.
+
+
+ This function combines g_menu_link_iter_next() with
+g_menu_link_iter_get_name() and g_menu_link_iter_get_value().
+
+First the iterator is advanced to the next (possibly first) link.
+If that fails, then %FALSE is returned and there are no other effects.
+
+If successful, @out_link and @value are set to the name and #GMenuModel
+of the link that has just been advanced to. At this point,
+g_menu_link_iter_get_name() and g_menu_link_iter_get_value() will return the
+same values again.
+
+The value returned in @out_link remains valid for as long as the iterator
+remains at the current position. The value returned in @value must
+be unreffed using g_object_unref() when it is no longer in use.
+
+
+ %TRUE on success, or %FALSE if there is no additional link
+
+
+
+
+ a #GMenuLinkIter
+
+
+
+ the name of the link
+
+
+
+ the linked #GMenuModel
+
+
+
+
+
+ Gets the name of the link at the current iterator position.
+
+The iterator is not advanced.
+
+
+ the type of the link
+
+
+
+
+ a #GMenuLinkIter
+
+
+
+
+
+ This function combines g_menu_link_iter_next() with
+g_menu_link_iter_get_name() and g_menu_link_iter_get_value().
+
+First the iterator is advanced to the next (possibly first) link.
+If that fails, then %FALSE is returned and there are no other effects.
+
+If successful, @out_link and @value are set to the name and #GMenuModel
+of the link that has just been advanced to. At this point,
+g_menu_link_iter_get_name() and g_menu_link_iter_get_value() will return the
+same values again.
+
+The value returned in @out_link remains valid for as long as the iterator
+remains at the current position. The value returned in @value must
+be unreffed using g_object_unref() when it is no longer in use.
+
+
+ %TRUE on success, or %FALSE if there is no additional link
+
+
+
+
+ a #GMenuLinkIter
+
+
+
+ the name of the link
+
+
+
+ the linked #GMenuModel
+
+
+
+
+
+ Gets the linked #GMenuModel at the current iterator position.
+
+The iterator is not advanced.
+
+
+ the #GMenuModel that is linked to
+
+
+
+
+ a #GMenuLinkIter
+
+
+
+
+
+ Attempts to advance the iterator to the next (possibly first)
+link.
+
+%TRUE is returned on success, or %FALSE if there are no more links.
+
+You must call this function when you first acquire the iterator to
+advance it to the first link (and determine if the first link exists
+at all).
+
+
+ %TRUE on success, or %FALSE when there are no more links
+
+
+
+
+ a #GMenuLinkIter
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ %TRUE on success, or %FALSE if there is no additional link
+
+
+
+
+ a #GMenuLinkIter
+
+
+
+ the name of the link
+
+
+
+ the linked #GMenuModel
+
+
+
+
+
+
+
+
+
+
+ #GMenuModel represents the contents of a menu -- an ordered list of
+menu items. The items are associated with actions, which can be
+activated through them. Items can be grouped in sections, and may
+have submenus associated with them. Both items and sections usually
+have some representation data, such as labels or icons. The type of
+the associated action (ie whether it is stateful, and what kind of
+state it has) can influence the representation of the item.
+
+The conceptual model of menus in #GMenuModel is hierarchical:
+sections and submenus are again represented by #GMenuModels.
+Menus themselves do not define their own roles. Rather, the role
+of a particular #GMenuModel is defined by the item that references
+it (or, in the case of the 'root' menu, is defined by the context
+in which it is used).
+
+As an example, consider the visible portions of this menu:
+
+## An example menu # {#menu-example}
+
+
+
+There are 8 "menus" visible in the screenshot: one menubar, two
+submenus and 5 sections:
+
+- the toplevel menubar (containing 4 items)
+- the View submenu (containing 3 sections)
+- the first section of the View submenu (containing 2 items)
+- the second section of the View submenu (containing 1 item)
+- the final section of the View submenu (containing 1 item)
+- the Highlight Mode submenu (containing 2 sections)
+- the Sources section (containing 2 items)
+- the Markup section (containing 2 items)
+
+The [example][menu-model] illustrates the conceptual connection between
+these 8 menus. Each large block in the figure represents a menu and the
+smaller blocks within the large block represent items in that menu. Some
+items contain references to other menus.
+
+## A menu example # {#menu-model}
+
+
+
+Notice that the separators visible in the [example][menu-example]
+appear nowhere in the [menu model][menu-model]. This is because
+separators are not explicitly represented in the menu model. Instead,
+a separator is inserted between any two non-empty sections of a menu.
+Section items can have labels just like any other item. In that case,
+a display system may show a section header instead of a separator.
+
+The motivation for this abstract model of application controls is
+that modern user interfaces tend to make these controls available
+outside the application. Examples include global menus, jumplists,
+dash boards, etc. To support such uses, it is necessary to 'export'
+information about actions and their representation in menus, which
+is exactly what the [GActionGroup exporter][gio-GActionGroup-exporter]
+and the [GMenuModel exporter][gio-GMenuModel-exporter] do for
+#GActionGroup and #GMenuModel. The client-side counterparts to
+make use of the exported information are #GDBusActionGroup and
+#GDBusMenuModel.
+
+The API of #GMenuModel is very generic, with iterators for the
+attributes and links of an item, see g_menu_model_iterate_item_attributes()
+and g_menu_model_iterate_item_links(). The 'standard' attributes and
+link types have predefined names: %G_MENU_ATTRIBUTE_LABEL,
+%G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, %G_MENU_LINK_SECTION
+and %G_MENU_LINK_SUBMENU.
+
+Items in a #GMenuModel represent active controls if they refer to
+an action that can get activated when the user interacts with the
+menu item. The reference to the action is encoded by the string id
+in the %G_MENU_ATTRIBUTE_ACTION attribute. An action id uniquely
+identifies an action in an action group. Which action group(s) provide
+actions depends on the context in which the menu model is used.
+E.g. when the model is exported as the application menu of a
+#GtkApplication, actions can be application-wide or window-specific
+(and thus come from two different action groups). By convention, the
+application-wide actions have names that start with "app.", while the
+names of window-specific actions start with "win.".
+
+While a wide variety of stateful actions is possible, the following
+is the minimum that is expected to be supported by all users of exported
+menu information:
+- an action with no parameter type and no state
+- an action with no parameter type and boolean state
+- an action with string parameter type and string state
+
+## Stateless
+
+A stateless action typically corresponds to an ordinary menu item.
+
+Selecting such a menu item will activate the action (with no parameter).
+
+## Boolean State
+
+An action with a boolean state will most typically be used with a "toggle"
+or "switch" menu item. The state can be set directly, but activating the
+action (with no parameter) results in the state being toggled.
+
+Selecting a toggle menu item will activate the action. The menu item should
+be rendered as "checked" when the state is true.
+
+## String Parameter and State
+
+Actions with string parameters and state will most typically be used to
+represent an enumerated choice over the items available for a group of
+radio menu items. Activating the action with a string parameter is
+equivalent to setting that parameter as the state.
+
+Radio menu items, in addition to being associated with the action, will
+have a target value. Selecting that menu item will result in activation
+of the action with the target value as the parameter. The menu item should
+be rendered as "selected" when the state of the action is equal to the
+target value of the menu item.
+
+
+ Queries the item at position @item_index in @model for the attribute
+specified by @attribute.
+
+If @expected_type is non-%NULL then it specifies the expected type of
+the attribute. If it is %NULL then any type will be accepted.
+
+If the attribute exists and matches @expected_type (or if the
+expected type is unspecified) then the value is returned.
+
+If the attribute does not exist, or does not match the expected type
+then %NULL is returned.
+
+
+ the value of the attribute
+
+
+
+
+ a #GMenuModel
+
+
+
+ the index of the item
+
+
+
+ the attribute to query
+
+
+
+ the expected type of the attribute, or
+ %NULL
+
+
+
+
+
+ Gets all the attributes associated with the item in the menu model.
+
+
+
+
+
+
+ the #GMenuModel to query
+
+
+
+ The #GMenuItem to query
+
+
+
+ Attributes on the item
+
+
+
+
+
+
+
+
+ Queries the item at position @item_index in @model for the link
+specified by @link.
+
+If the link exists, the linked #GMenuModel is returned. If the link
+does not exist, %NULL is returned.
+
+
+ the linked #GMenuModel, or %NULL
+
+
+
+
+ a #GMenuModel
+
+
+
+ the index of the item
+
+
+
+ the link to query
+
+
+
+
+
+ Gets all the links associated with the item in the menu model.
+
+
+
+
+
+
+ the #GMenuModel to query
+
+
+
+ The #GMenuItem to query
+
+
+
+ Links from the item
+
+
+
+
+
+
+
+
+ Query the number of items in @model.
+
+
+ the number of items
+
+
+
+
+ a #GMenuModel
+
+
+
+
+
+ Queries if @model is mutable.
+
+An immutable #GMenuModel will never emit the #GMenuModel::items-changed
+signal. Consumers of the model may make optimisations accordingly.
+
+
+ %TRUE if the model is mutable (ie: "items-changed" may be
+ emitted).
+
+
+
+
+ a #GMenuModel
+
+
+
+
+
+ Creates a #GMenuAttributeIter to iterate over the attributes of
+the item at position @item_index in @model.
+
+You must free the iterator with g_object_unref() when you are done.
+
+
+ a new #GMenuAttributeIter
+
+
+
+
+ a #GMenuModel
+
+
+
+ the index of the item
+
+
+
+
+
+ Creates a #GMenuLinkIter to iterate over the links of the item at
+position @item_index in @model.
+
+You must free the iterator with g_object_unref() when you are done.
+
+
+ a new #GMenuLinkIter
+
+
+
+
+ a #GMenuModel
+
+
+
+ the index of the item
+
+
+
+
+
+ Queries item at position @item_index in @model for the attribute
+specified by @attribute.
+
+If the attribute exists and matches the #GVariantType corresponding
+to @format_string then @format_string is used to deconstruct the
+value into the positional parameters and %TRUE is returned.
+
+If the attribute does not exist, or it does exist but has the wrong
+type, then the positional parameters are ignored and %FALSE is
+returned.
+
+This function is a mix of g_menu_model_get_item_attribute_value() and
+g_variant_get(), followed by a g_variant_unref(). As such,
+@format_string must make a complete copy of the data (since the
+#GVariant may go away after the call to g_variant_unref()). In
+particular, no '&' characters are allowed in @format_string.
+
+
+ %TRUE if the named attribute was found with the expected
+ type
+
+
+
+
+ a #GMenuModel
+
+
+
+ the index of the item
+
+
+
+ the attribute to query
+
+
+
+ a #GVariant format string
+
+
+
+ positional parameters, as per @format_string
+
+
+
+
+
+ Queries the item at position @item_index in @model for the attribute
+specified by @attribute.
+
+If @expected_type is non-%NULL then it specifies the expected type of
+the attribute. If it is %NULL then any type will be accepted.
+
+If the attribute exists and matches @expected_type (or if the
+expected type is unspecified) then the value is returned.
+
+If the attribute does not exist, or does not match the expected type
+then %NULL is returned.
+
+
+ the value of the attribute
+
+
+
+
+ a #GMenuModel
+
+
+
+ the index of the item
+
+
+
+ the attribute to query
+
+
+
+ the expected type of the attribute, or
+ %NULL
+
+
+
+
+
+ Queries the item at position @item_index in @model for the link
+specified by @link.
+
+If the link exists, the linked #GMenuModel is returned. If the link
+does not exist, %NULL is returned.
+
+
+ the linked #GMenuModel, or %NULL
+
+
+
+
+ a #GMenuModel
+
+
+
+ the index of the item
+
+
+
+ the link to query
+
+
+
+
+
+ Query the number of items in @model.
+
+
+ the number of items
+
+
+
+
+ a #GMenuModel
+
+
+
+
+
+ Queries if @model is mutable.
+
+An immutable #GMenuModel will never emit the #GMenuModel::items-changed
+signal. Consumers of the model may make optimisations accordingly.
+
+
+ %TRUE if the model is mutable (ie: "items-changed" may be
+ emitted).
+
+
+
+
+ a #GMenuModel
+
+
+
+
+
+ Requests emission of the #GMenuModel::items-changed signal on @model.
+
+This function should never be called except by #GMenuModel
+subclasses. Any other calls to this function will very likely lead
+to a violation of the interface of the model.
+
+The implementation should update its internal representation of the
+menu before emitting the signal. The implementation should further
+expect to receive queries about the new state of the menu (and
+particularly added menu items) while signal handlers are running.
+
+The implementation must dispatch this call directly from a mainloop
+entry and not in response to calls -- particularly those from the
+#GMenuModel API. Said another way: the menu must not change while
+user code is running without returning to the mainloop.
+
+
+
+
+
+
+ a #GMenuModel
+
+
+
+ the position of the change
+
+
+
+ the number of items removed
+
+
+
+ the number of items added
+
+
+
+
+
+ Creates a #GMenuAttributeIter to iterate over the attributes of
+the item at position @item_index in @model.
+
+You must free the iterator with g_object_unref() when you are done.
+
+
+ a new #GMenuAttributeIter
+
+
+
+
+ a #GMenuModel
+
+
+
+ the index of the item
+
+
+
+
+
+ Creates a #GMenuLinkIter to iterate over the links of the item at
+position @item_index in @model.
+
+You must free the iterator with g_object_unref() when you are done.
+
+
+ a new #GMenuLinkIter
+
+
+
+
+ a #GMenuModel
+
+
+
+ the index of the item
+
+
+
+
+
+
+
+
+
+
+
+ Emitted when a change has occurred to the menu.
+
+The only changes that can occur to a menu is that items are removed
+or added. Items may not change (except by being removed and added
+back in the same location). This signal is capable of describing
+both of those changes (at the same time).
+
+The signal means that starting at the index @position, @removed
+items were removed and @added items were added in their place. If
+@removed is zero then only items were added. If @added is zero
+then only items were removed.
+
+As an example, if the menu contains items a, b, c, d (in that
+order) and the signal (2, 1, 3) occurs then the new composition of
+the menu will be a, b, _, _, _, d (with each _ representing some
+new item).
+
+Signal handlers may query the model (particularly the added items)
+and expect to see the results of the modification that is being
+reported. The signal is emitted after the modification.
+
+
+
+
+
+ the position of the change
+
+
+
+ the number of items removed
+
+
+
+ the number of items added
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ %TRUE if the model is mutable (ie: "items-changed" may be
+ emitted).
+
+
+
+
+ a #GMenuModel
+
+
+
+
+
+
+
+
+
+ the number of items
+
+
+
+
+ a #GMenuModel
+
+
+
+
+
+
+
+
+
+
+
+
+
+ the #GMenuModel to query
+
+
+
+ The #GMenuItem to query
+
+
+
+ Attributes on the item
+
+
+
+
+
+
+
+
+
+
+
+
+ a new #GMenuAttributeIter
+
+
+
+
+ a #GMenuModel
+
+
+
+ the index of the item
+
+
+
+
+
+
+
+
+
+ the value of the attribute
+
+
+
+
+ a #GMenuModel
+
+
+
+ the index of the item
+
+
+
+ the attribute to query
+
+
+
+ the expected type of the attribute, or
+ %NULL
+
+
+
+
+
+
+
+
+
+
+
+
+
+ the #GMenuModel to query
+
+
+
+ The #GMenuItem to query
+
+
+
+ Links from the item
+
+
+
+
+
+
+
+
+
+
+
+
+ a new #GMenuLinkIter
+
+
+
+
+ a #GMenuModel
+
+
+
+ the index of the item
+
+
+
+
+
+
+
+
+
+ the linked #GMenuModel, or %NULL
+
+
+
+
+ a #GMenuModel
+
+
+
+ the index of the item
+
+
+
+ the link to query
+
+
+
+
+
+
+
+
+
+
+ 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 #GAsyncResult
+and #GTask. To unmount a #GMount instance, first call
+g_mount_unmount_with_operation() with (at least) the #GMount instance and a
+#GAsyncReadyCallback. The callback will be fired when the
+operation has resolved (either with success or failure), and a
+#GAsyncResult structure will be passed to the callback. That
+callback should then call g_mount_unmount_with_operation_finish() with the #GMount
+and the #GAsyncResult 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.
+
+
+ Checks if @mount can be ejected.
+
+
+ %TRUE if the @mount can be ejected.
+
+
+
+
+ a #GMount.
+
+
+
+
+
+ Checks if @mount can be unmounted.
+
+
+ %TRUE if the @mount can be unmounted.
+
+
+
+
+ a #GMount.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Ejects a mount. This is an asynchronous operation, and is
+finished by calling g_mount_eject_finish() with the @mount
+and #GAsyncResult data returned in the @callback.
+ Use g_mount_eject_with_operation() instead.
+
+
+
+
+
+
+ a #GMount.
+
+
+
+ flags affecting the unmount if required for eject
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback, or %NULL.
+
+
+
+ user data passed to @callback.
+
+
+
+
+
+ Finishes ejecting a mount. If any errors occurred during the operation,
+@error will be set to contain the errors and %FALSE will be returned.
+ Use g_mount_eject_with_operation_finish() instead.
+
+
+ %TRUE if the mount was successfully ejected. %FALSE otherwise.
+
+
+
+
+ a #GMount.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Ejects a mount. This is an asynchronous operation, and is
+finished by calling g_mount_eject_with_operation_finish() with the @mount
+and #GAsyncResult data returned in the @callback.
+
+
+
+
+
+
+ a #GMount.
+
+
+
+ flags affecting the unmount if required for eject
+
+
+
+ a #GMountOperation or %NULL to avoid
+ user interaction.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback, or %NULL.
+
+
+
+ user data passed to @callback.
+
+
+
+
+
+ Finishes ejecting a mount. If any errors occurred during the operation,
+@error will be set to contain the errors and %FALSE will be returned.
+
+
+ %TRUE if the mount was successfully ejected. %FALSE otherwise.
+
+
+
+
+ a #GMount.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Gets the default location of @mount. The default location of the given
+@mount is a path that reflects the main entry point for the user (e.g.
+the home directory, or the root of the volume).
+
+
+ a #GFile.
+ The returned object should be unreffed with
+ g_object_unref() when no longer needed.
+
+
+
+
+ a #GMount.
+
+
+
+
+
+ Gets the drive for the @mount.
+
+This is a convenience method for getting the #GVolume and then
+using that object to get the #GDrive.
+
+
+ a #GDrive or %NULL if @mount is not
+ associated with a volume or a drive.
+ The returned object should be unreffed with
+ g_object_unref() when no longer needed.
+
+
+
+
+ a #GMount.
+
+
+
+
+
+ Gets the icon for @mount.
+
+
+ a #GIcon.
+ The returned object should be unreffed with
+ g_object_unref() when no longer needed.
+
+
+
+
+ a #GMount.
+
+
+
+
+
+ Gets the name of @mount.
+
+
+ the name for the given @mount.
+ The returned string should be freed with g_free()
+ when no longer needed.
+
+
+
+
+ a #GMount.
+
+
+
+
+
+ Gets the root directory on @mount.
+
+
+ a #GFile.
+ The returned object should be unreffed with
+ g_object_unref() when no longer needed.
+
+
+
+
+ a #GMount.
+
+
+
+
+
+ Gets the sort key for @mount, if any.
+
+
+ Sorting key for @mount or %NULL if no such key is available.
+
+
+
+
+ A #GMount.
+
+
+
+
+
+ Gets the symbolic icon for @mount.
+
+
+ a #GIcon.
+ The returned object should be unreffed with
+ g_object_unref() when no longer needed.
+
+
+
+
+ a #GMount.
+
+
+
+
+
+ Gets the UUID for the @mount. The reference is typically based on
+the file system UUID for the mount in question and should be
+considered an opaque string. Returns %NULL if there is no UUID
+available.
+
+
+ the UUID for @mount or %NULL if no UUID
+ can be computed.
+ The returned string should be freed with g_free()
+ when no longer needed.
+
+
+
+
+ a #GMount.
+
+
+
+
+
+ Gets the volume for the @mount.
+
+
+ a #GVolume or %NULL if @mount is not
+ associated with a volume.
+ The returned object should be unreffed with
+ g_object_unref() when no longer needed.
+
+
+
+
+ a #GMount.
+
+
+
+
+
+ Tries to guess the type of content stored on @mount. Returns one or
+more textual identifiers of well-known content types (typically
+prefixed with "x-content/"), e.g. x-content/image-dcf for camera
+memory cards. See the
+[shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
+specification for more on x-content types.
+
+This is an asynchronous operation (see
+g_mount_guess_content_type_sync() for the synchronous version), and
+is finished by calling g_mount_guess_content_type_finish() with the
+@mount and #GAsyncResult data returned in the @callback.
+
+
+
+
+
+
+ a #GMount
+
+
+
+ Whether to force a rescan of the content.
+ Otherwise a cached result will be used if available
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback
+
+
+
+ user data passed to @callback
+
+
+
+
+
+ Finishes guessing content types of @mount. If any errors occurred
+during the operation, @error will be set to contain the errors and
+%FALSE will be returned. In particular, you may get an
+%G_IO_ERROR_NOT_SUPPORTED if the mount does not support content
+guessing.
+
+
+ a %NULL-terminated array of content types or %NULL on error.
+ Caller should free this array with g_strfreev() when done with it.
+
+
+
+
+
+
+ a #GMount
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Tries to guess the type of content stored on @mount. Returns one or
+more textual identifiers of well-known content types (typically
+prefixed with "x-content/"), e.g. x-content/image-dcf for camera
+memory cards. See the
+[shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
+specification for more on x-content types.
+
+This is a synchronous operation and as such may block doing IO;
+see g_mount_guess_content_type() for the asynchronous version.
+
+
+ a %NULL-terminated array of content types or %NULL on error.
+ Caller should free this array with g_strfreev() when done with it.
+
+
+
+
+
+
+ a #GMount
+
+
+
+ Whether to force a rescan of the content.
+ Otherwise a cached result will be used if available
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Remounts a mount. This is an asynchronous operation, and is
+finished by calling g_mount_remount_finish() with the @mount
+and #GAsyncResults data returned in the @callback.
+
+Remounting is useful when some setting affecting the operation
+of the volume has been changed, as these may need a remount to
+take affect. While this is semantically equivalent with unmounting
+and then remounting not all backends might need to actually be
+unmounted.
+
+
+
+
+
+
+ a #GMount.
+
+
+
+ flags affecting the operation
+
+
+
+ a #GMountOperation or %NULL to avoid
+ user interaction.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback, or %NULL.
+
+
+
+ user data passed to @callback.
+
+
+
+
+
+ Finishes remounting a mount. If any errors occurred during the operation,
+@error will be set to contain the errors and %FALSE will be returned.
+
+
+ %TRUE if the mount was successfully remounted. %FALSE otherwise.
+
+
+
+
+ a #GMount.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Unmounts a mount. This is an asynchronous operation, and is
+finished by calling g_mount_unmount_finish() with the @mount
+and #GAsyncResult data returned in the @callback.
+ Use g_mount_unmount_with_operation() instead.
+
+
+
+
+
+
+ a #GMount.
+
+
+
+ flags affecting the operation
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback, or %NULL.
+
+
+
+ user data passed to @callback.
+
+
+
+
+
+ Finishes unmounting a mount. If any errors occurred during the operation,
+@error will be set to contain the errors and %FALSE will be returned.
+ Use g_mount_unmount_with_operation_finish() instead.
+
+
+ %TRUE if the mount was successfully unmounted. %FALSE otherwise.
+
+
+
+
+ a #GMount.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Unmounts a mount. This is an asynchronous operation, and is
+finished by calling g_mount_unmount_with_operation_finish() with the @mount
+and #GAsyncResult data returned in the @callback.
+
+
+
+
+
+
+ a #GMount.
+
+
+
+ flags affecting the operation
+
+
+
+ a #GMountOperation or %NULL to avoid
+ user interaction.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback, or %NULL.
+
+
+
+ user data passed to @callback.
+
+
+
+
+
+ Finishes unmounting a mount. If any errors occurred during the operation,
+@error will be set to contain the errors and %FALSE will be returned.
+
+
+ %TRUE if the mount was successfully unmounted. %FALSE otherwise.
+
+
+
+
+ a #GMount.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Checks if @mount can be ejected.
+
+
+ %TRUE if the @mount can be ejected.
+
+
+
+
+ a #GMount.
+
+
+
+
+
+ Checks if @mount can be unmounted.
+
+
+ %TRUE if the @mount can be unmounted.
+
+
+
+
+ a #GMount.
+
+
+
+
+
+ Ejects a mount. This is an asynchronous operation, and is
+finished by calling g_mount_eject_finish() with the @mount
+and #GAsyncResult data returned in the @callback.
+ Use g_mount_eject_with_operation() instead.
+
+
+
+
+
+
+ a #GMount.
+
+
+
+ flags affecting the unmount if required for eject
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback, or %NULL.
+
+
+
+ user data passed to @callback.
+
+
+
+
+
+ Finishes ejecting a mount. If any errors occurred during the operation,
+@error will be set to contain the errors and %FALSE will be returned.
+ Use g_mount_eject_with_operation_finish() instead.
+
+
+ %TRUE if the mount was successfully ejected. %FALSE otherwise.
+
+
+
+
+ a #GMount.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Ejects a mount. This is an asynchronous operation, and is
+finished by calling g_mount_eject_with_operation_finish() with the @mount
+and #GAsyncResult data returned in the @callback.
+
+
+
+
+
+
+ a #GMount.
+
+
+
+ flags affecting the unmount if required for eject
+
+
+
+ a #GMountOperation or %NULL to avoid
+ user interaction.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback, or %NULL.
+
+
+
+ user data passed to @callback.
+
+
+
+
+
+ Finishes ejecting a mount. If any errors occurred during the operation,
+@error will be set to contain the errors and %FALSE will be returned.
+
+
+ %TRUE if the mount was successfully ejected. %FALSE otherwise.
+
+
+
+
+ a #GMount.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Gets the default location of @mount. The default location of the given
+@mount is a path that reflects the main entry point for the user (e.g.
+the home directory, or the root of the volume).
+
+
+ a #GFile.
+ The returned object should be unreffed with
+ g_object_unref() when no longer needed.
+
+
+
+
+ a #GMount.
+
+
+
+
+
+ Gets the drive for the @mount.
+
+This is a convenience method for getting the #GVolume and then
+using that object to get the #GDrive.
+
+
+ a #GDrive or %NULL if @mount is not
+ associated with a volume or a drive.
+ The returned object should be unreffed with
+ g_object_unref() when no longer needed.
+
+
+
+
+ a #GMount.
+
+
+
+
+
+ Gets the icon for @mount.
+
+
+ a #GIcon.
+ The returned object should be unreffed with
+ g_object_unref() when no longer needed.
+
+
+
+
+ a #GMount.
+
+
+
+
+
+ Gets the name of @mount.
+
+
+ the name for the given @mount.
+ The returned string should be freed with g_free()
+ when no longer needed.
+
+
+
+
+ a #GMount.
+
+
+
+
+
+ Gets the root directory on @mount.
+
+
+ a #GFile.
+ The returned object should be unreffed with
+ g_object_unref() when no longer needed.
+
+
+
+
+ a #GMount.
+
+
+
+
+
+ Gets the sort key for @mount, if any.
+
+
+ Sorting key for @mount or %NULL if no such key is available.
+
+
+
+
+ A #GMount.
+
+
+
+
+
+ Gets the symbolic icon for @mount.
+
+
+ a #GIcon.
+ The returned object should be unreffed with
+ g_object_unref() when no longer needed.
+
+
+
+
+ a #GMount.
+
+
+
+
+
+ Gets the UUID for the @mount. The reference is typically based on
+the file system UUID for the mount in question and should be
+considered an opaque string. Returns %NULL if there is no UUID
+available.
+
+
+ the UUID for @mount or %NULL if no UUID
+ can be computed.
+ The returned string should be freed with g_free()
+ when no longer needed.
+
+
+
+
+ a #GMount.
+
+
+
+
+
+ Gets the volume for the @mount.
+
+
+ a #GVolume or %NULL if @mount is not
+ associated with a volume.
+ The returned object should be unreffed with
+ g_object_unref() when no longer needed.
+
+
+
+
+ a #GMount.
+
+
+
+
+
+ Tries to guess the type of content stored on @mount. Returns one or
+more textual identifiers of well-known content types (typically
+prefixed with "x-content/"), e.g. x-content/image-dcf for camera
+memory cards. See the
+[shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
+specification for more on x-content types.
+
+This is an asynchronous operation (see
+g_mount_guess_content_type_sync() for the synchronous version), and
+is finished by calling g_mount_guess_content_type_finish() with the
+@mount and #GAsyncResult data returned in the @callback.
+
+
+
+
+
+
+ a #GMount
+
+
+
+ Whether to force a rescan of the content.
+ Otherwise a cached result will be used if available
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback
+
+
+
+ user data passed to @callback
+
+
+
+
+
+ Finishes guessing content types of @mount. If any errors occurred
+during the operation, @error will be set to contain the errors and
+%FALSE will be returned. In particular, you may get an
+%G_IO_ERROR_NOT_SUPPORTED if the mount does not support content
+guessing.
+
+
+ a %NULL-terminated array of content types or %NULL on error.
+ Caller should free this array with g_strfreev() when done with it.
+
+
+
+
+
+
+ a #GMount
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Tries to guess the type of content stored on @mount. Returns one or
+more textual identifiers of well-known content types (typically
+prefixed with "x-content/"), e.g. x-content/image-dcf for camera
+memory cards. See the
+[shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
+specification for more on x-content types.
+
+This is a synchronous operation and as such may block doing IO;
+see g_mount_guess_content_type() for the asynchronous version.
+
+
+ a %NULL-terminated array of content types or %NULL on error.
+ Caller should free this array with g_strfreev() when done with it.
+
+
+
+
+
+
+ a #GMount
+
+
+
+ Whether to force a rescan of the content.
+ Otherwise a cached result will be used if available
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+
+
+ Determines if @mount is shadowed. Applications or libraries should
+avoid displaying @mount in the user interface if it is shadowed.
+
+A mount is said to be shadowed if there exists one or more user
+visible objects (currently #GMount objects) with a root that is
+inside the root of @mount.
+
+One application of shadow mounts is when exposing a single file
+system that is used to address several logical volumes. In this
+situation, a #GVolumeMonitor implementation would create two
+#GVolume objects (for example, one for the camera functionality of
+the device and one for a SD card reader on the device) with
+activation URIs `gphoto2://[usb:001,002]/store1/`
+and `gphoto2://[usb:001,002]/store2/`. When the
+underlying mount (with root
+`gphoto2://[usb:001,002]/`) is mounted, said
+#GVolumeMonitor implementation would create two #GMount objects
+(each with their root matching the corresponding volume activation
+root) that would shadow the original mount.
+
+The proxy monitor in GVfs 2.26 and later, automatically creates and
+manage shadow mounts (and shadows the underlying mount) if the
+activation root on a #GVolume is set.
+
+
+ %TRUE if @mount is shadowed.
+
+
+
+
+ A #GMount.
+
+
+
+
+
+ Remounts a mount. This is an asynchronous operation, and is
+finished by calling g_mount_remount_finish() with the @mount
+and #GAsyncResults data returned in the @callback.
+
+Remounting is useful when some setting affecting the operation
+of the volume has been changed, as these may need a remount to
+take affect. While this is semantically equivalent with unmounting
+and then remounting not all backends might need to actually be
+unmounted.
+
+
+
+
+
+
+ a #GMount.
+
+
+
+ flags affecting the operation
+
+
+
+ a #GMountOperation or %NULL to avoid
+ user interaction.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback, or %NULL.
+
+
+
+ user data passed to @callback.
+
+
+
+
+
+ Finishes remounting a mount. If any errors occurred during the operation,
+@error will be set to contain the errors and %FALSE will be returned.
+
+
+ %TRUE if the mount was successfully remounted. %FALSE otherwise.
+
+
+
+
+ a #GMount.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Increments the shadow count on @mount. Usually used by
+#GVolumeMonitor implementations when creating a shadow mount for
+@mount, see g_mount_is_shadowed() for more information. The caller
+will need to emit the #GMount::changed signal on @mount manually.
+
+
+
+
+
+
+ A #GMount.
+
+
+
+
+
+ Unmounts a mount. This is an asynchronous operation, and is
+finished by calling g_mount_unmount_finish() with the @mount
+and #GAsyncResult data returned in the @callback.
+ Use g_mount_unmount_with_operation() instead.
+
+
+
+
+
+
+ a #GMount.
+
+
+
+ flags affecting the operation
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback, or %NULL.
+
+
+
+ user data passed to @callback.
+
+
+
+
+
+ Finishes unmounting a mount. If any errors occurred during the operation,
+@error will be set to contain the errors and %FALSE will be returned.
+ Use g_mount_unmount_with_operation_finish() instead.
+
+
+ %TRUE if the mount was successfully unmounted. %FALSE otherwise.
+
+
+
+
+ a #GMount.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Unmounts a mount. This is an asynchronous operation, and is
+finished by calling g_mount_unmount_with_operation_finish() with the @mount
+and #GAsyncResult data returned in the @callback.
+
+
+
+
+
+
+ a #GMount.
+
+
+
+ flags affecting the operation
+
+
+
+ a #GMountOperation or %NULL to avoid
+ user interaction.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback, or %NULL.
+
+
+
+ user data passed to @callback.
+
+
+
+
+
+ Finishes unmounting a mount. If any errors occurred during the operation,
+@error will be set to contain the errors and %FALSE will be returned.
+
+
+ %TRUE if the mount was successfully unmounted. %FALSE otherwise.
+
+
+
+
+ a #GMount.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Decrements the shadow count on @mount. Usually used by
+#GVolumeMonitor implementations when destroying a shadow mount for
+@mount, see g_mount_is_shadowed() for more information. The caller
+will need to emit the #GMount::changed signal on @mount manually.
+
+
+
+
+
+
+ A #GMount.
+
+
+
+
+
+ Emitted when the mount has been changed.
+
+
+
+
+
+ This signal may be emitted when the #GMount is about to be
+unmounted.
+
+This signal depends on the backend and is only emitted if
+GIO was used to unmount.
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+ Interface for implementing operations for mounts.
+
+
+ The parent interface.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GFile.
+ The returned object should be unreffed with
+ g_object_unref() when no longer needed.
+
+
+
+
+ a #GMount.
+
+
+
+
+
+
+
+
+
+ the name for the given @mount.
+ The returned string should be freed with g_free()
+ when no longer needed.
+
+
+
+
+ a #GMount.
+
+
+
+
+
+
+
+
+
+ a #GIcon.
+ The returned object should be unreffed with
+ g_object_unref() when no longer needed.
+
+
+
+
+ a #GMount.
+
+
+
+
+
+
+
+
+
+ the UUID for @mount or %NULL if no UUID
+ can be computed.
+ The returned string should be freed with g_free()
+ when no longer needed.
+
+
+
+
+ a #GMount.
+
+
+
+
+
+
+
+
+
+ a #GVolume or %NULL if @mount is not
+ associated with a volume.
+ The returned object should be unreffed with
+ g_object_unref() when no longer needed.
+
+
+
+
+ a #GMount.
+
+
+
+
+
+
+
+
+
+ a #GDrive or %NULL if @mount is not
+ associated with a volume or a drive.
+ The returned object should be unreffed with
+ g_object_unref() when no longer needed.
+
+
+
+
+ a #GMount.
+
+
+
+
+
+
+
+
+
+ %TRUE if the @mount can be unmounted.
+
+
+
+
+ a #GMount.
+
+
+
+
+
+
+
+
+
+ %TRUE if the @mount can be ejected.
+
+
+
+
+ a #GMount.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GMount.
+
+
+
+ flags affecting the operation
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback, or %NULL.
+
+
+
+ user data passed to @callback.
+
+
+
+
+
+
+
+
+
+ %TRUE if the mount was successfully unmounted. %FALSE otherwise.
+
+
+
+
+ a #GMount.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GMount.
+
+
+
+ flags affecting the unmount if required for eject
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback, or %NULL.
+
+
+
+ user data passed to @callback.
+
+
+
+
+
+
+
+
+
+ %TRUE if the mount was successfully ejected. %FALSE otherwise.
+
+
+
+
+ a #GMount.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GMount.
+
+
+
+ flags affecting the operation
+
+
+
+ a #GMountOperation or %NULL to avoid
+ user interaction.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback, or %NULL.
+
+
+
+ user data passed to @callback.
+
+
+
+
+
+
+
+
+
+ %TRUE if the mount was successfully remounted. %FALSE otherwise.
+
+
+
+
+ a #GMount.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GMount
+
+
+
+ Whether to force a rescan of the content.
+ Otherwise a cached result will be used if available
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback
+
+
+
+ user data passed to @callback
+
+
+
+
+
+
+
+
+
+ a %NULL-terminated array of content types or %NULL on error.
+ Caller should free this array with g_strfreev() when done with it.
+
+
+
+
+
+
+ a #GMount
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+ a %NULL-terminated array of content types or %NULL on error.
+ Caller should free this array with g_strfreev() when done with it.
+
+
+
+
+
+
+ a #GMount
+
+
+
+ Whether to force a rescan of the content.
+ Otherwise a cached result will be used if available
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GMount.
+
+
+
+ flags affecting the operation
+
+
+
+ a #GMountOperation or %NULL to avoid
+ user interaction.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback, or %NULL.
+
+
+
+ user data passed to @callback.
+
+
+
+
+
+
+
+
+
+ %TRUE if the mount was successfully unmounted. %FALSE otherwise.
+
+
+
+
+ a #GMount.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GMount.
+
+
+
+ flags affecting the unmount if required for eject
+
+
+
+ a #GMountOperation or %NULL to avoid
+ user interaction.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback, or %NULL.
+
+
+
+ user data passed to @callback.
+
+
+
+
+
+
+
+
+
+ %TRUE if the mount was successfully ejected. %FALSE otherwise.
+
+
+
+
+ a #GMount.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+ a #GFile.
+ The returned object should be unreffed with
+ g_object_unref() when no longer needed.
+
+
+
+
+ a #GMount.
+
+
+
+
+
+
+
+
+
+ Sorting key for @mount or %NULL if no such key is available.
+
+
+
+
+ A #GMount.
+
+
+
+
+
+
+
+
+
+ a #GIcon.
+ The returned object should be unreffed with
+ g_object_unref() when no longer needed.
+
+
+
+
+ a #GMount.
+
+
+
+
+
+
+
+ Flags used when mounting a mount.
+
+ No flags set.
+
+
+
+ #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.
+
+The term ‘TCRYPT’ is used to mean ‘compatible with TrueCrypt and VeraCrypt’.
+[TrueCrypt](https://en.wikipedia.org/wiki/TrueCrypt) is a discontinued system for
+encrypting file containers, partitions or whole disks, typically used with Windows.
+[VeraCrypt](https://www.veracrypt.fr/) is a maintained fork of TrueCrypt with various
+improvements and auditing fixes.
+
+
+ Creates a new mount operation.
+
+
+ a #GMountOperation.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Virtual implementation of #GMountOperation::ask-question.
+
+
+
+
+
+
+ a #GMountOperation
+
+
+
+ string containing a message to display to the user
+
+
+
+ an array of
+ strings for each possible choice
+
+
+
+
+
+
+
+ Emits the #GMountOperation::reply signal.
+
+
+
+
+
+
+ a #GMountOperation
+
+
+
+ a #GMountOperationResult
+
+
+
+
+
+ Virtual implementation of #GMountOperation::show-processes.
+
+
+
+
+
+
+ a #GMountOperation
+
+
+
+ string containing a message to display to the user
+
+
+
+ an array of #GPid for processes blocking
+ the operation
+
+
+
+
+
+ an array of
+ strings for each possible choice
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Check to see whether the mount operation is being used
+for an anonymous user.
+
+
+ %TRUE if mount operation is anonymous.
+
+
+
+
+ a #GMountOperation.
+
+
+
+
+
+ Gets a choice from the mount operation.
+
+
+ an integer containing an index of the user's choice from
+the choice's list, or `0`.
+
+
+
+
+ a #GMountOperation.
+
+
+
+
+
+ Gets the domain of the mount operation.
+
+
+ a string set to the domain.
+
+
+
+
+ a #GMountOperation.
+
+
+
+
+
+ Check to see whether the mount operation is being used
+for a TCRYPT hidden volume.
+
+
+ %TRUE if mount operation is for hidden volume.
+
+
+
+
+ a #GMountOperation.
+
+
+
+
+
+ Check to see whether the mount operation is being used
+for a TCRYPT system volume.
+
+
+ %TRUE if mount operation is for system volume.
+
+
+
+
+ a #GMountOperation.
+
+
+
+
+
+ Gets a password from the mount operation.
+
+
+ a string containing the password within @op.
+
+
+
+
+ a #GMountOperation.
+
+
+
+
+
+ Gets the state of saving passwords for the mount operation.
+
+
+ a #GPasswordSave flag.
+
+
+
+
+ a #GMountOperation.
+
+
+
+
+
+ Gets a PIM from the mount operation.
+
+
+ The VeraCrypt PIM within @op.
+
+
+
+
+ a #GMountOperation.
+
+
+
+
+
+ Get the user name from the mount operation.
+
+
+ a string containing the user name.
+
+
+
+
+ a #GMountOperation.
+
+
+
+
+
+ Emits the #GMountOperation::reply signal.
+
+
+
+
+
+
+ a #GMountOperation
+
+
+
+ a #GMountOperationResult
+
+
+
+
+
+ Sets the mount operation to use an anonymous user if @anonymous is %TRUE.
+
+
+
+
+
+
+ a #GMountOperation.
+
+
+
+ boolean value.
+
+
+
+
+
+ Sets a default choice for the mount operation.
+
+
+
+
+
+
+ a #GMountOperation.
+
+
+
+ an integer.
+
+
+
+
+
+ Sets the mount operation's domain.
+
+
+
+
+
+
+ a #GMountOperation.
+
+
+
+ the domain to set.
+
+
+
+
+
+ Sets the mount operation to use a hidden volume if @hidden_volume is %TRUE.
+
+
+
+
+
+
+ a #GMountOperation.
+
+
+
+ boolean value.
+
+
+
+
+
+ Sets the mount operation to use a system volume if @system_volume is %TRUE.
+
+
+
+
+
+
+ a #GMountOperation.
+
+
+
+ boolean value.
+
+
+
+
+
+ Sets the mount operation's password to @password.
+
+
+
+
+
+
+ a #GMountOperation.
+
+
+
+ password to set.
+
+
+
+
+
+ Sets the state of saving passwords for the mount operation.
+
+
+
+
+
+
+ a #GMountOperation.
+
+
+
+ a set of #GPasswordSave flags.
+
+
+
+
+
+ Sets the mount operation's PIM to @pim.
+
+
+
+
+
+
+ a #GMountOperation.
+
+
+
+ an unsigned integer.
+
+
+
+
+
+ Sets the user name within @op to @username.
+
+
+
+
+
+
+ a #GMountOperation.
+
+
+
+ input username.
+
+
+
+
+
+ Whether to use an anonymous user when authenticating.
+
+
+
+ The index of the user's choice when a question is asked during the
+mount operation. See the #GMountOperation::ask-question signal.
+
+
+
+ The domain to use for the mount operation.
+
+
+
+ Whether the device to be unlocked is a TCRYPT hidden volume.
+See [the VeraCrypt documentation](https://www.veracrypt.fr/en/Hidden%20Volume.html).
+
+
+
+ Whether the device to be unlocked is a TCRYPT system volume.
+In this context, a system volume is a volume with a bootloader
+and operating system installed. This is only supported for Windows
+operating systems. For further documentation, see
+[the VeraCrypt documentation](https://www.veracrypt.fr/en/System%20Encryption.html).
+
+
+
+ The password that is used for authentication when carrying out
+the mount operation.
+
+
+
+ Determines if and how the password information should be saved.
+
+
+
+ The VeraCrypt PIM value, when unlocking a VeraCrypt volume. See
+[the VeraCrypt documentation](https://www.veracrypt.fr/en/Personal%20Iterations%20Multiplier%20(PIM).html).
+
+
+
+ The user name that is used for authentication when carrying out
+the mount operation.
+
+
+
+
+
+
+
+
+
+ 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.
+
+
+
+
+
+ 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.
+
+
+
+
+
+ string containing a message to display to the user.
+
+
+
+ string containing the default user name.
+
+
+
+ string containing the default domain.
+
+
+
+ a set of #GAskPasswordFlags.
+
+
+
+
+
+ Emitted when asking the user a question and gives a list of
+choices for the user to choose from.
+
+If the message contains a line break, the first line should be
+presented as a heading. For example, it may be used as the
+primary text in a #GtkMessageDialog.
+
+
+
+
+
+ string containing a message to display to the user.
+
+
+
+ an array of strings for each possible choice.
+
+
+
+
+
+
+
+ Emitted when the user has replied to the mount operation.
+
+
+
+
+
+ a #GMountOperationResult indicating how the request was handled
+
+
+
+
+
+ Emitted when one or more processes are blocking an operation
+e.g. unmounting/ejecting a #GMount or stopping a #GDrive.
+
+Note that this signal may be emitted several times to update the
+list of blocking processes as processes close files. The
+application should only respond with g_mount_operation_reply() to
+the latest signal (setting #GMountOperation:choice to the choice
+the user made).
+
+If the message contains a line break, the first line should be
+presented as a heading. For example, it may be used as the
+primary text in a #GtkMessageDialog.
+
+
+
+
+
+ string containing a message to display to the user.
+
+
+
+ an array of #GPid for processes
+ blocking the operation.
+
+
+
+
+
+ an array of strings for each possible choice.
+
+
+
+
+
+
+
+ Emitted when an unmount operation has been busy for more than some time
+(typically 1.5 seconds).
+
+When unmounting or ejecting a volume, the kernel might need to flush
+pending data in its buffers to the volume stable storage, and this operation
+can take a considerable amount of time. This signal may be emitted several
+times as long as the unmount operation is outstanding, and then one
+last time when the operation is completed, with @bytes_left set to zero.
+
+Implementations of GMountOperation should handle this signal by
+showing an UI notification, and then dismiss it, or show another notification
+of completion, when @bytes_left reaches zero.
+
+If the message contains a line break, the first line should be
+presented as a heading. For example, it may be used as the
+primary text in a #GtkMessageDialog.
+
+
+
+
+
+ string containing a message to display to the user
+
+
+
+ the estimated time left before the operation completes,
+ in microseconds, or -1
+
+
+
+ the amount of bytes to be written before the operation
+ completes (or -1 if such amount is not known), or zero if the operation
+ is completed
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GMountOperation
+
+
+
+ string containing a message to display to the user
+
+
+
+ an array of
+ strings for each possible choice
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GMountOperation
+
+
+
+ a #GMountOperationResult
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GMountOperation
+
+
+
+ string containing a message to display to the user
+
+
+
+ an array of #GPid for processes blocking
+ the operation
+
+
+
+
+
+ an array of
+ strings for each possible choice
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #GMountOperationResult is returned as a result when a request for
+information is send by the mounting operation.
+
+ The request was fulfilled and the
+ user specified data is now available
+
+
+ The user requested the mount operation
+ to be aborted
+
+
+ The request was unhandled (i.e. not
+ implemented)
+
+
+
+ Flags used when an unmounting a mount.
+
+ No flags set.
+
+
+ Unmount even if there are outstanding
+ file operations on the mount.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Extension point for network status monitoring functionality.
+See [Extending GIO][extending-gio].
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ A socket address of some unknown native type.
+
+
+
+ Creates a new #GNativeSocketAddress for @native and @len.
+
+
+ a new #GNativeSocketAddress
+
+
+
+
+ a native address object
+
+
+
+ the length of @native, in bytes
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #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.
+
+The enumeration results of resolved addresses *may* be cached as long
+as this object is kept alive which may have unexpected results if
+alive for too long.
+
+See #GSocketConnectable for an example of using the connectable
+interface.
+
+
+
+ Creates a new #GSocketConnectable for connecting to the given
+@hostname and @port.
+
+Note that depending on the configuration of the machine, a
+@hostname of `localhost` may refer to the IPv4 loopback address
+only, or to both IPv4 and IPv6; use
+g_network_address_new_loopback() to create a #GNetworkAddress that
+is guaranteed to resolve to both addresses.
+
+
+ the new #GNetworkAddress
+
+
+
+
+ the hostname
+
+
+
+ the port
+
+
+
+
+
+ Creates a new #GSocketConnectable for connecting to the local host
+over a loopback connection to the given @port. This is intended for
+use in connecting to local services which may be running on IPv4 or
+IPv6.
+
+The connectable will return IPv4 and IPv6 loopback addresses,
+regardless of how the host resolves `localhost`. By contrast,
+g_network_address_new() will often only return an IPv4 address when
+resolving `localhost`, and an IPv6 address for `localhost6`.
+
+g_network_address_get_hostname() will always return `localhost` for
+a #GNetworkAddress created with this constructor.
+
+
+ the new #GNetworkAddress
+
+
+
+
+ the port
+
+
+
+
+
+ Creates a new #GSocketConnectable for connecting to the given
+@hostname and @port. May fail and return %NULL in case
+parsing @host_and_port fails.
+
+@host_and_port may be in any of a number of recognised formats; an IPv6
+address, an IPv4 address, or a domain name (in which case a DNS
+lookup is performed). Quoting with [] is supported for all address
+types. A port override may be specified in the usual way with a
+colon.
+
+If no port is specified in @host_and_port then @default_port will be
+used as the port number to connect to.
+
+In general, @host_and_port is expected to be provided by the user
+(allowing them to give the hostname, and a port override if necessary)
+and @default_port is expected to be provided by the application.
+
+(The port component of @host_and_port can also be specified as a
+service name rather than as a numeric port, but this functionality
+is deprecated, because it depends on the contents of /etc/services,
+which is generally quite sparse on platforms other than Linux.)
+
+
+ the new
+ #GNetworkAddress, or %NULL on error
+
+
+
+
+ the hostname and optionally a port
+
+
+
+ the default port if not in @host_and_port
+
+
+
+
+
+ Creates a new #GSocketConnectable for connecting to the given
+@uri. May fail and return %NULL in case parsing @uri fails.
+
+Using this rather than g_network_address_new() or
+g_network_address_parse() allows #GSocketClient to determine
+when to use application-specific proxy protocols.
+
+
+ the new
+ #GNetworkAddress, or %NULL on error
+
+
+
+
+ the hostname and optionally a port
+
+
+
+ The default port if none is found in the URI
+
+
+
+
+
+ Gets @addr's hostname. This might be either UTF-8 or ASCII-encoded,
+depending on what @addr was created with.
+
+
+ @addr's hostname
+
+
+
+
+ a #GNetworkAddress
+
+
+
+
+
+ Gets @addr's port number
+
+
+ @addr's port (which may be 0)
+
+
+
+
+ a #GNetworkAddress
+
+
+
+
+
+ Gets @addr's scheme
+
+
+ @addr's scheme (%NULL if not built from URI)
+
+
+
+
+ a #GNetworkAddress
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The host's network connectivity state, as reported by #GNetworkMonitor.
+
+ The host is not configured with a
+ route to the Internet; it may or may not be connected to a local
+ network.
+
+
+ The host is connected to a network, but
+ does not appear to be able to reach the full Internet, perhaps
+ due to upstream network problems.
+
+
+ The host is behind a captive portal and
+ cannot reach the full Internet.
+
+
+ The host is connected to a network, and
+ appears to be able to reach the full Internet.
+
+
+
+ #GNetworkMonitor provides an easy-to-use cross-platform API
+for monitoring network connectivity. On Linux, the available
+implementations are based on the kernel's netlink interface and
+on NetworkManager.
+
+There is also an implementation for use inside Flatpak sandboxes.
+
+
+
+ Gets the default #GNetworkMonitor for the system.
+
+
+ a #GNetworkMonitor, which will be
+ a dummy object if no network monitor is available
+
+
+
+
+ Attempts to determine whether or not the host pointed to by
+@connectable can be reached, without actually trying to connect to
+it.
+
+This may return %TRUE even when #GNetworkMonitor:network-available
+is %FALSE, if, for example, @monitor can determine that
+@connectable refers to a host on a local network.
+
+If @monitor believes that an attempt to connect to @connectable
+will succeed, it will return %TRUE. Otherwise, it will return
+%FALSE and set @error to an appropriate error (such as
+%G_IO_ERROR_HOST_UNREACHABLE).
+
+Note that although this does not attempt to connect to
+@connectable, it may still block for a brief period of time (eg,
+trying to do multicast DNS on the local network), so if you do not
+want to block, you should use g_network_monitor_can_reach_async().
+
+
+ %TRUE if @connectable is reachable, %FALSE if not.
+
+
+
+
+ a #GNetworkMonitor
+
+
+
+ a #GSocketConnectable
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Asynchronously attempts to determine whether or not the host
+pointed to by @connectable can be reached, without actually
+trying to connect to it.
+
+For more details, see g_network_monitor_can_reach().
+
+When the operation is finished, @callback will be called.
+You can then call g_network_monitor_can_reach_finish()
+to get the result of the operation.
+
+
+
+
+
+
+ a #GNetworkMonitor
+
+
+
+ a #GSocketConnectable
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ a #GAsyncReadyCallback to call when the
+ request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an async network connectivity test.
+See g_network_monitor_can_reach_async().
+
+
+ %TRUE if network is reachable, %FALSE if not.
+
+
+
+
+ a #GNetworkMonitor
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Attempts to determine whether or not the host pointed to by
+@connectable can be reached, without actually trying to connect to
+it.
+
+This may return %TRUE even when #GNetworkMonitor:network-available
+is %FALSE, if, for example, @monitor can determine that
+@connectable refers to a host on a local network.
+
+If @monitor believes that an attempt to connect to @connectable
+will succeed, it will return %TRUE. Otherwise, it will return
+%FALSE and set @error to an appropriate error (such as
+%G_IO_ERROR_HOST_UNREACHABLE).
+
+Note that although this does not attempt to connect to
+@connectable, it may still block for a brief period of time (eg,
+trying to do multicast DNS on the local network), so if you do not
+want to block, you should use g_network_monitor_can_reach_async().
+
+
+ %TRUE if @connectable is reachable, %FALSE if not.
+
+
+
+
+ a #GNetworkMonitor
+
+
+
+ a #GSocketConnectable
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Asynchronously attempts to determine whether or not the host
+pointed to by @connectable can be reached, without actually
+trying to connect to it.
+
+For more details, see g_network_monitor_can_reach().
+
+When the operation is finished, @callback will be called.
+You can then call g_network_monitor_can_reach_finish()
+to get the result of the operation.
+
+
+
+
+
+
+ a #GNetworkMonitor
+
+
+
+ a #GSocketConnectable
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ a #GAsyncReadyCallback to call when the
+ request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an async network connectivity test.
+See g_network_monitor_can_reach_async().
+
+
+ %TRUE if network is reachable, %FALSE if not.
+
+
+
+
+ a #GNetworkMonitor
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Gets a more detailed networking state than
+g_network_monitor_get_network_available().
+
+If #GNetworkMonitor:network-available is %FALSE, then the
+connectivity state will be %G_NETWORK_CONNECTIVITY_LOCAL.
+
+If #GNetworkMonitor:network-available is %TRUE, then the
+connectivity state will be %G_NETWORK_CONNECTIVITY_FULL (if there
+is full Internet connectivity), %G_NETWORK_CONNECTIVITY_LIMITED (if
+the host has a default route, but appears to be unable to actually
+reach the full Internet), or %G_NETWORK_CONNECTIVITY_PORTAL (if the
+host is trapped behind a "captive portal" that requires some sort
+of login or acknowledgement before allowing full Internet access).
+
+Note that in the case of %G_NETWORK_CONNECTIVITY_LIMITED and
+%G_NETWORK_CONNECTIVITY_PORTAL, it is possible that some sites are
+reachable but others are not. In this case, applications can
+attempt to connect to remote servers, but should gracefully fall
+back to their "offline" behavior if the connection attempt fails.
+
+
+ the network connectivity state
+
+
+
+
+ the #GNetworkMonitor
+
+
+
+
+
+ Checks if the network is available. "Available" here means that the
+system has a default route available for at least one of IPv4 or
+IPv6. It does not necessarily imply that the public Internet is
+reachable. See #GNetworkMonitor:network-available for more details.
+
+
+ whether the network is available
+
+
+
+
+ the #GNetworkMonitor
+
+
+
+
+
+ Checks if the network is metered.
+See #GNetworkMonitor:network-metered for more details.
+
+
+ whether the connection is metered
+
+
+
+
+ the #GNetworkMonitor
+
+
+
+
+
+ More detailed information about the host's network connectivity.
+See g_network_monitor_get_connectivity() and
+#GNetworkConnectivity for more details.
+
+
+
+ Whether the network is considered available. That is, whether the
+system has a default route for at least one of IPv4 or IPv6.
+
+Real-world networks are of course much more complicated than
+this; the machine may be connected to a wifi hotspot that
+requires payment before allowing traffic through, or may be
+connected to a functioning router that has lost its own upstream
+connectivity. Some hosts might only be accessible when a VPN is
+active. Other hosts might only be accessible when the VPN is
+not active. Thus, it is best to use g_network_monitor_can_reach()
+or g_network_monitor_can_reach_async() to test for reachability
+on a host-by-host basis. (On the other hand, when the property is
+%FALSE, the application can reasonably expect that no remote
+hosts at all are reachable, and should indicate this to the user
+in its UI.)
+
+See also #GNetworkMonitor::network-changed.
+
+
+
+ Whether the network is considered metered. That is, whether the
+system has traffic flowing through the default connection that is
+subject to limitations set by service providers. For example, traffic
+might be billed by the amount of data transmitted, or there might be a
+quota on the amount of traffic per month. This is typical with tethered
+connections (3G and 4G) and in such situations, bandwidth intensive
+applications may wish to avoid network activity where possible if it will
+cost the user money or use up their limited quota.
+
+If more information is required about specific devices then the
+system network management API should be used instead (for example,
+NetworkManager or ConnMan).
+
+If this information is not available then no networks will be
+marked as metered.
+
+See also #GNetworkMonitor:network-available.
+
+
+
+ Emitted when the network configuration changes.
+
+
+
+
+
+ the current value of #GNetworkMonitor:network-available
+
+
+
+
+
+
+ The virtual function table for #GNetworkMonitor.
+
+
+ The parent interface.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ %TRUE if @connectable is reachable, %FALSE if not.
+
+
+
+
+ a #GNetworkMonitor
+
+
+
+ a #GSocketConnectable
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GNetworkMonitor
+
+
+
+ a #GSocketConnectable
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ a #GAsyncReadyCallback to call when the
+ request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ %TRUE if network is reachable, %FALSE if not.
+
+
+
+
+ a #GNetworkMonitor
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+ 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 an example of using the connectable
+interface.
+
+
+
+ Creates a new #GNetworkService representing the given @service,
+@protocol, and @domain. This will initially be unresolved; use the
+#GSocketConnectable interface to resolve it.
+
+
+ a new #GNetworkService
+
+
+
+
+ the service type to look up (eg, "ldap")
+
+
+
+ the networking protocol to use for @service (eg, "tcp")
+
+
+
+ the DNS domain to look up the service in
+
+
+
+
+
+ Gets the domain that @srv serves. This might be either UTF-8 or
+ASCII-encoded, depending on what @srv was created with.
+
+
+ @srv's domain name
+
+
+
+
+ a #GNetworkService
+
+
+
+
+
+ Gets @srv's protocol name (eg, "tcp").
+
+
+ @srv's protocol name
+
+
+
+
+ a #GNetworkService
+
+
+
+
+
+ Gets the URI scheme used to resolve proxies. By default, the service name
+is used as scheme.
+
+
+ @srv's scheme name
+
+
+
+
+ a #GNetworkService
+
+
+
+
+
+ Gets @srv's service name (eg, "ldap").
+
+
+ @srv's service name
+
+
+
+
+ a #GNetworkService
+
+
+
+
+
+ Set's the URI scheme used to resolve proxies. By default, the service name
+is used as scheme.
+
+
+
+
+
+
+ a #GNetworkService
+
+
+
+ a URI scheme
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #GNotification is a mechanism for creating a notification to be shown
+to the user -- typically as a pop-up notification presented by the
+desktop environment shell.
+
+The key difference between #GNotification and other similar APIs is
+that, if supported by the desktop environment, notifications sent
+with #GNotification will persist after the application has exited,
+and even across system reboots.
+
+Since the user may click on a notification while the application is
+not running, applications using #GNotification should be able to be
+started as a D-Bus service, using #GApplication.
+
+In order for #GNotification to work, the application must have installed
+a `.desktop` file. For example:
+|[
+ [Desktop Entry]
+ Name=Test Application
+ Comment=Description of what Test Application does
+ Exec=gnome-test-application
+ Icon=org.gnome.TestApplication
+ Terminal=false
+ Type=Application
+ Categories=GNOME;GTK;TestApplication Category;
+ StartupNotify=true
+ DBusActivatable=true
+ X-GNOME-UsesNotifications=true
+]|
+
+The `X-GNOME-UsesNotifications` key indicates to GNOME Control Center
+that this application uses notifications, so it can be listed in the
+Control Center’s ‘Notifications’ panel.
+
+The `.desktop` file must be named as `org.gnome.TestApplication.desktop`,
+where `org.gnome.TestApplication` is the ID passed to g_application_new().
+
+User interaction with a notification (either the default action, or
+buttons) must be associated with actions on the application (ie:
+"app." actions). It is not possible to route user interaction
+through the notification itself, because the object will not exist if
+the application is autostarted as a result of a notification being
+clicked.
+
+A notification can be sent with g_application_send_notification().
+
+ Creates a new #GNotification with @title as its title.
+
+After populating @notification with more details, it can be sent to
+the desktop shell with g_application_send_notification(). Changing
+any properties after this call will not have any effect until
+resending @notification.
+
+
+ a new #GNotification instance
+
+
+
+
+ the title of the notification
+
+
+
+
+
+ Adds a button to @notification that activates the action in
+@detailed_action when clicked. That action must be an
+application-wide action (starting with "app."). If @detailed_action
+contains a target, the action will be activated with that target as
+its parameter.
+
+See g_action_parse_detailed_name() for a description of the format
+for @detailed_action.
+
+
+
+
+
+
+ a #GNotification
+
+
+
+ label of the button
+
+
+
+ a detailed action name
+
+
+
+
+
+ Adds a button to @notification that activates @action when clicked.
+@action must be an application-wide action (it must start with "app.").
+
+If @target_format is given, it is used to collect remaining
+positional parameters into a #GVariant instance, similar to
+g_variant_new(). @action will be activated with that #GVariant as its
+parameter.
+
+
+
+
+
+
+ a #GNotification
+
+
+
+ label of the button
+
+
+
+ an action name
+
+
+
+ a #GVariant format string, or %NULL
+
+
+
+ positional parameters, as determined by @target_format
+
+
+
+
+
+ Adds a button to @notification that activates @action when clicked.
+@action must be an application-wide action (it must start with "app.").
+
+If @target is non-%NULL, @action will be activated with @target as
+its parameter.
+
+
+
+
+
+
+ a #GNotification
+
+
+
+ label of the button
+
+
+
+ an action name
+
+
+
+ a #GVariant to use as @action's parameter, or %NULL
+
+
+
+
+
+ Sets the body of @notification to @body.
+
+
+
+
+
+
+ a #GNotification
+
+
+
+ the new body for @notification, or %NULL
+
+
+
+
+
+ Sets the type of @notification to @category. Categories have a main
+type like `email`, `im` or `device` and can have a detail separated
+by a `.`, e.g. `im.received` or `email.arrived`. Setting the category
+helps the notification server to select proper feedback to the user.
+
+Standard categories are [listed in the specification](https://specifications.freedesktop.org/notification-spec/latest/ar01s06.html).
+
+
+
+
+
+
+ a #GNotification
+
+
+
+ the category for @notification, or %NULL for no category
+
+
+
+
+
+ Sets the default action of @notification to @detailed_action. This
+action is activated when the notification is clicked on.
+
+The action in @detailed_action must be an application-wide action (it
+must start with "app."). If @detailed_action contains a target, the
+given action will be activated with that target as its parameter.
+See g_action_parse_detailed_name() for a description of the format
+for @detailed_action.
+
+When no default action is set, the application that the notification
+was sent on is activated.
+
+
+
+
+
+
+ a #GNotification
+
+
+
+ a detailed action name
+
+
+
+
+
+ Sets the default action of @notification to @action. This action is
+activated when the notification is clicked on. It must be an
+application-wide action (it must start with "app.").
+
+If @target_format is given, it is used to collect remaining
+positional parameters into a #GVariant instance, similar to
+g_variant_new(). @action will be activated with that #GVariant as its
+parameter.
+
+When no default action is set, the application that the notification
+was sent on is activated.
+
+
+
+
+
+
+ a #GNotification
+
+
+
+ an action name
+
+
+
+ a #GVariant format string, or %NULL
+
+
+
+ positional parameters, as determined by @target_format
+
+
+
+
+
+ Sets the default action of @notification to @action. This action is
+activated when the notification is clicked on. It must be an
+application-wide action (start with "app.").
+
+If @target is non-%NULL, @action will be activated with @target as
+its parameter. If @target is floating, it will be consumed.
+
+When no default action is set, the application that the notification
+was sent on is activated.
+
+
+
+
+
+
+ a #GNotification
+
+
+
+ an action name
+
+
+
+ a #GVariant to use as @action's parameter, or %NULL
+
+
+
+
+
+ Sets the icon of @notification to @icon.
+
+
+
+
+
+
+ a #GNotification
+
+
+
+ the icon to be shown in @notification, as a #GIcon
+
+
+
+
+
+ Sets the priority of @notification to @priority. See
+#GNotificationPriority for possible values.
+
+
+
+
+
+
+ a #GNotification
+
+
+
+ a #GNotificationPriority
+
+
+
+
+
+ Sets the title of @notification to @title.
+
+
+
+
+
+
+ a #GNotification
+
+
+
+ the new title for @notification
+
+
+
+
+
+ Deprecated in favor of g_notification_set_priority().
+ Since 2.42, this has been deprecated in favour of
+ g_notification_set_priority().
+
+
+
+
+
+
+ a #GNotification
+
+
+
+ %TRUE if @notification is urgent
+
+
+
+
+
+
+ Priority levels for #GNotifications.
+
+ the default priority, to be used for the
+ majority of notifications (for example email messages, software updates,
+ completed download/sync operations)
+
+
+ for notifications that do not require
+ immediate attention - typically used for contextual background
+ information, such as contact birthdays or local weather
+
+
+ for events that require more attention,
+ usually because responses are time-sensitive (for example chat and SMS
+ messages or alarms)
+
+
+ for urgent notifications, or notifications
+ that require a response in a short space of time (for example phone calls
+ or emergency warnings)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Structure used for scatter/gather data output when sending multiple
+messages or packets in one go. You generally pass in an array of
+#GOutputVectors and the operation will use all the buffers as if they
+were one buffer.
+
+If @address is %NULL then the message is sent to the default receiver
+(as previously set by g_socket_connect()).
+
+
+ a #GSocketAddress, or %NULL
+
+
+
+ pointer to an array of output vectors
+
+
+
+ the number of output vectors pointed to by @vectors.
+
+
+
+ initialize to 0. Will be set to the number of bytes
+ that have been sent
+
+
+
+ a pointer
+ to an array of #GSocketControlMessages, or %NULL.
+
+
+
+
+
+ number of elements in @control_messages.
+
+
+
+
+ #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().
+
+See the documentation for #GIOStream for details of thread safety of
+streaming APIs.
+
+All of these functions have async variants too.
+
+
+ Requests an asynchronous close of the stream, releasing resources
+related to it. When the operation is finished @callback will be
+called. You can then call g_output_stream_close_finish() to get
+the result of the operation.
+
+For behaviour details see g_output_stream_close().
+
+The asynchronous methods have a default fallback that uses threads
+to implement asynchronicity, so they are optional for inheriting
+classes. However, if you override one you must override all.
+
+
+
+
+
+
+ A #GOutputStream.
+
+
+
+ the io priority of the request.
+
+
+
+ optional cancellable object
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Closes an output stream.
+
+
+ %TRUE if stream was successfully closed, %FALSE otherwise.
+
+
+
+
+ a #GOutputStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Forces a write of all user-space buffered data for the given
+@stream. Will block during the operation. Closing the stream will
+implicitly cause a flush.
+
+This function is optional for inherited classes.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ %TRUE on success, %FALSE on error
+
+
+
+
+ a #GOutputStream.
+
+
+
+ optional cancellable object
+
+
+
+
+
+ Forces an asynchronous write of all user-space buffered data for
+the given @stream.
+For behaviour details see g_output_stream_flush().
+
+When the operation is finished @callback will be
+called. You can then call g_output_stream_flush_finish() to get the
+result of the operation.
+
+
+
+
+
+
+ a #GOutputStream.
+
+
+
+ the io priority of the request.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes flushing an output stream.
+
+
+ %TRUE if flush operation succeeded, %FALSE otherwise.
+
+
+
+
+ a #GOutputStream.
+
+
+
+ a GAsyncResult.
+
+
+
+
+
+ Splices an input stream into an output stream.
+
+
+ a #gssize containing the size of the data spliced, or
+ -1 if an error occurred. Note that if the number of bytes
+ spliced is greater than %G_MAXSSIZE, then that will be
+ returned, and there is no way to determine the actual number
+ of bytes spliced.
+
+
+
+
+ a #GOutputStream.
+
+
+
+ a #GInputStream.
+
+
+
+ a set of #GOutputStreamSpliceFlags.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Splices a stream asynchronously.
+When the operation is finished @callback will be called.
+You can then call g_output_stream_splice_finish() to get the
+result of the operation.
+
+For the synchronous, blocking version of this function, see
+g_output_stream_splice().
+
+
+
+
+
+
+ a #GOutputStream.
+
+
+
+ a #GInputStream.
+
+
+
+ a set of #GOutputStreamSpliceFlags.
+
+
+
+ the io priority of the request.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback.
+
+
+
+ user data passed to @callback.
+
+
+
+
+
+ Finishes an asynchronous stream splice operation.
+
+
+ a #gssize of the number of bytes spliced. Note that if the
+ number of bytes spliced is greater than %G_MAXSSIZE, then that
+ will be returned, and there is no way to determine the actual
+ number of bytes spliced.
+
+
+
+
+ a #GOutputStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Request an asynchronous write of @count bytes from @buffer into
+the stream. When the operation is finished @callback will be called.
+You can then call g_output_stream_write_finish() to get the result of the
+operation.
+
+During an async request no other sync and async calls are allowed,
+and will result in %G_IO_ERROR_PENDING errors.
+
+A value of @count larger than %G_MAXSSIZE will cause a
+%G_IO_ERROR_INVALID_ARGUMENT error.
+
+On success, the number of bytes written will be passed to the
+@callback. It is not an error if this is not the same as the
+requested size, as it can happen e.g. on a partial I/O error,
+but generally we try to write as many bytes as requested.
+
+You are guaranteed that this method will never fail with
+%G_IO_ERROR_WOULD_BLOCK - if @stream can't accept more data, the
+method will just wait until this changes.
+
+Any outstanding I/O request with higher priority (lower numerical
+value) will be executed before an outstanding request with lower
+priority. Default priority is %G_PRIORITY_DEFAULT.
+
+The asynchronous methods have a default fallback that uses threads
+to implement asynchronicity, so they are optional for inheriting
+classes. However, if you override one you must override all.
+
+For the synchronous, blocking version of this function, see
+g_output_stream_write().
+
+Note that no copy of @buffer will be made, so it must stay valid
+until @callback is called. See g_output_stream_write_bytes_async()
+for a #GBytes version that will automatically hold a reference to
+the contents (without copying) for the duration of the call.
+
+
+
+
+
+
+ A #GOutputStream.
+
+
+
+ the buffer containing the data to write.
+
+
+
+
+
+ the number of bytes to write
+
+
+
+ the io priority of the request.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes a stream write operation.
+
+
+ a #gssize containing the number of bytes written to the stream.
+
+
+
+
+ a #GOutputStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Tries to write @count bytes from @buffer into the stream. Will block
+during the operation.
+
+If count is 0, returns 0 and does nothing. A value of @count
+larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
+
+On success, the number of bytes written to the stream is returned.
+It is not an error if this is not the same as the requested size, as it
+can happen e.g. on a partial I/O error, or if there is not enough
+storage in the stream. All writes block until at least one byte
+is written or an error occurs; 0 is never returned (unless
+@count is 0).
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
+operation was partially finished when the operation was cancelled the
+partial result will be returned, without an error.
+
+On error -1 is returned and @error is set accordingly.
+
+
+ Number of bytes written, or -1 on error
+
+
+
+
+ a #GOutputStream.
+
+
+
+ the buffer containing the data to write.
+
+
+
+
+
+ the number of bytes to write
+
+
+
+ optional cancellable object
+
+
+
+
+
+ Request an asynchronous write of the bytes contained in @n_vectors @vectors into
+the stream. When the operation is finished @callback will be called.
+You can then call g_output_stream_writev_finish() to get the result of the
+operation.
+
+During an async request no other sync and async calls are allowed,
+and will result in %G_IO_ERROR_PENDING errors.
+
+On success, the number of bytes written will be passed to the
+@callback. It is not an error if this is not the same as the
+requested size, as it can happen e.g. on a partial I/O error,
+but generally we try to write as many bytes as requested.
+
+You are guaranteed that this method will never fail with
+%G_IO_ERROR_WOULD_BLOCK — if @stream can't accept more data, the
+method will just wait until this changes.
+
+Any outstanding I/O request with higher priority (lower numerical
+value) will be executed before an outstanding request with lower
+priority. Default priority is %G_PRIORITY_DEFAULT.
+
+The asynchronous methods have a default fallback that uses threads
+to implement asynchronicity, so they are optional for inheriting
+classes. However, if you override one you must override all.
+
+For the synchronous, blocking version of this function, see
+g_output_stream_writev().
+
+Note that no copy of @vectors will be made, so it must stay valid
+until @callback is called.
+
+
+
+
+
+
+ A #GOutputStream.
+
+
+
+ the buffer containing the #GOutputVectors to write.
+
+
+
+
+
+ the number of vectors to write
+
+
+
+ the I/O priority of the request.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes a stream writev operation.
+
+
+ %TRUE on success, %FALSE if there was an error
+
+
+
+
+ a #GOutputStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+ location to store the number of bytes that were written to the stream
+
+
+
+
+
+ Tries to write the bytes contained in the @n_vectors @vectors into the
+stream. Will block during the operation.
+
+If @n_vectors is 0 or the sum of all bytes in @vectors is 0, returns 0 and
+does nothing.
+
+On success, the number of bytes written to the stream is returned.
+It is not an error if this is not the same as the requested size, as it
+can happen e.g. on a partial I/O error, or if there is not enough
+storage in the stream. All writes block until at least one byte
+is written or an error occurs; 0 is never returned (unless
+@n_vectors is 0 or the sum of all bytes in @vectors is 0).
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
+operation was partially finished when the operation was cancelled the
+partial result will be returned, without an error.
+
+Some implementations of g_output_stream_writev() may have limitations on the
+aggregate buffer size, and will return %G_IO_ERROR_INVALID_ARGUMENT if these
+are exceeded. For example, when writing to a local file on UNIX platforms,
+the aggregate buffer size must not exceed %G_MAXSSIZE bytes.
+
+
+ %TRUE on success, %FALSE if there was an error
+
+
+
+
+ a #GOutputStream.
+
+
+
+ the buffer containing the #GOutputVectors to write.
+
+
+
+
+
+ the number of vectors to write
+
+
+
+ location to store the number of bytes that were
+ written to the stream
+
+
+
+ optional cancellable object
+
+
+
+
+
+ Clears the pending flag on @stream.
+
+
+
+
+
+
+ output stream
+
+
+
+
+
+ Closes the stream, releasing resources related to it.
+
+Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED.
+Closing a stream multiple times will not return an error.
+
+Closing a stream will automatically flush any outstanding buffers in the
+stream.
+
+Streams will be automatically closed when the last reference
+is dropped, but you might want to call this function to make sure
+resources are released as early as possible.
+
+Some streams might keep the backing store of the stream (e.g. a file descriptor)
+open after the stream is closed. See the documentation for the individual
+stream for details.
+
+On failure the first error that happened will be reported, but the close
+operation will finish as much as possible. A stream that failed to
+close will still return %G_IO_ERROR_CLOSED for all operations. Still, it
+is important to check and report the error to the user, otherwise
+there might be a loss of data as all data might not be written.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+Cancelling a close will still leave the stream closed, but there some streams
+can use a faster close that doesn't block to e.g. check errors. On
+cancellation (as with any error) there is no guarantee that all written
+data will reach the target.
+
+
+ %TRUE on success, %FALSE on failure
+
+
+
+
+ A #GOutputStream.
+
+
+
+ optional cancellable object
+
+
+
+
+
+ Requests an asynchronous close of the stream, releasing resources
+related to it. When the operation is finished @callback will be
+called. You can then call g_output_stream_close_finish() to get
+the result of the operation.
+
+For behaviour details see g_output_stream_close().
+
+The asynchronous methods have a default fallback that uses threads
+to implement asynchronicity, so they are optional for inheriting
+classes. However, if you override one you must override all.
+
+
+
+
+
+
+ A #GOutputStream.
+
+
+
+ the io priority of the request.
+
+
+
+ optional cancellable object
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Closes an output stream.
+
+
+ %TRUE if stream was successfully closed, %FALSE otherwise.
+
+
+
+
+ a #GOutputStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Forces a write of all user-space buffered data for the given
+@stream. Will block during the operation. Closing the stream will
+implicitly cause a flush.
+
+This function is optional for inherited classes.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ %TRUE on success, %FALSE on error
+
+
+
+
+ a #GOutputStream.
+
+
+
+ optional cancellable object
+
+
+
+
+
+ Forces an asynchronous write of all user-space buffered data for
+the given @stream.
+For behaviour details see g_output_stream_flush().
+
+When the operation is finished @callback will be
+called. You can then call g_output_stream_flush_finish() to get the
+result of the operation.
+
+
+
+
+
+
+ a #GOutputStream.
+
+
+
+ the io priority of the request.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes flushing an output stream.
+
+
+ %TRUE if flush operation succeeded, %FALSE otherwise.
+
+
+
+
+ a #GOutputStream.
+
+
+
+ a GAsyncResult.
+
+
+
+
+
+ Checks if an output stream has pending actions.
+
+
+ %TRUE if @stream has pending actions.
+
+
+
+
+ a #GOutputStream.
+
+
+
+
+
+ Checks if an output stream has already been closed.
+
+
+ %TRUE if @stream is closed. %FALSE otherwise.
+
+
+
+
+ a #GOutputStream.
+
+
+
+
+
+ Checks if an output stream is being closed. This can be
+used inside e.g. a flush implementation to see if the
+flush (or other i/o operation) is called from within
+the closing operation.
+
+
+ %TRUE if @stream is being closed. %FALSE otherwise.
+
+
+
+
+ a #GOutputStream.
+
+
+
+
+
+ This is a utility function around g_output_stream_write_all(). It
+uses g_strdup_vprintf() to turn @format and @... into a string that
+is then written to @stream.
+
+See the documentation of g_output_stream_write_all() about the
+behavior of the actual write operation.
+
+Note that partial writes cannot be properly checked with this
+function due to the variable length of the written string, if you
+need precise control over partial write failures, you need to
+create you own printf()-like wrapper around g_output_stream_write()
+or g_output_stream_write_all().
+
+
+ %TRUE on success, %FALSE if there was an error
+
+
+
+
+ a #GOutputStream.
+
+
+
+ location to store the number of bytes that was
+ written to the stream
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ location to store the error occurring, or %NULL to ignore
+
+
+
+ the format string. See the printf() documentation
+
+
+
+ the parameters to insert into the format string
+
+
+
+
+
+ Sets @stream to have actions pending. If the pending flag is
+already set or @stream is closed, it will return %FALSE and set
+@error.
+
+
+ %TRUE if pending was previously unset and is now set.
+
+
+
+
+ a #GOutputStream.
+
+
+
+
+
+ Splices an input stream into an output stream.
+
+
+ a #gssize containing the size of the data spliced, or
+ -1 if an error occurred. Note that if the number of bytes
+ spliced is greater than %G_MAXSSIZE, then that will be
+ returned, and there is no way to determine the actual number
+ of bytes spliced.
+
+
+
+
+ a #GOutputStream.
+
+
+
+ a #GInputStream.
+
+
+
+ a set of #GOutputStreamSpliceFlags.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Splices a stream asynchronously.
+When the operation is finished @callback will be called.
+You can then call g_output_stream_splice_finish() to get the
+result of the operation.
+
+For the synchronous, blocking version of this function, see
+g_output_stream_splice().
+
+
+
+
+
+
+ a #GOutputStream.
+
+
+
+ a #GInputStream.
+
+
+
+ a set of #GOutputStreamSpliceFlags.
+
+
+
+ the io priority of the request.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback.
+
+
+
+ user data passed to @callback.
+
+
+
+
+
+ Finishes an asynchronous stream splice operation.
+
+
+ a #gssize of the number of bytes spliced. Note that if the
+ number of bytes spliced is greater than %G_MAXSSIZE, then that
+ will be returned, and there is no way to determine the actual
+ number of bytes spliced.
+
+
+
+
+ a #GOutputStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ This is a utility function around g_output_stream_write_all(). It
+uses g_strdup_vprintf() to turn @format and @args into a string that
+is then written to @stream.
+
+See the documentation of g_output_stream_write_all() about the
+behavior of the actual write operation.
+
+Note that partial writes cannot be properly checked with this
+function due to the variable length of the written string, if you
+need precise control over partial write failures, you need to
+create you own printf()-like wrapper around g_output_stream_write()
+or g_output_stream_write_all().
+
+
+ %TRUE on success, %FALSE if there was an error
+
+
+
+
+ a #GOutputStream.
+
+
+
+ location to store the number of bytes that was
+ written to the stream
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ location to store the error occurring, or %NULL to ignore
+
+
+
+ the format string. See the printf() documentation
+
+
+
+ the parameters to insert into the format string
+
+
+
+
+
+ Tries to write @count bytes from @buffer into the stream. Will block
+during the operation.
+
+If count is 0, returns 0 and does nothing. A value of @count
+larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
+
+On success, the number of bytes written to the stream is returned.
+It is not an error if this is not the same as the requested size, as it
+can happen e.g. on a partial I/O error, or if there is not enough
+storage in the stream. All writes block until at least one byte
+is written or an error occurs; 0 is never returned (unless
+@count is 0).
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
+operation was partially finished when the operation was cancelled the
+partial result will be returned, without an error.
+
+On error -1 is returned and @error is set accordingly.
+
+
+ Number of bytes written, or -1 on error
+
+
+
+
+ a #GOutputStream.
+
+
+
+ the buffer containing the data to write.
+
+
+
+
+
+ the number of bytes to write
+
+
+
+ optional cancellable object
+
+
+
+
+
+ Tries to write @count bytes from @buffer into the stream. Will block
+during the operation.
+
+This function is similar to g_output_stream_write(), except it tries to
+write as many bytes as requested, only stopping on an error.
+
+On a successful write of @count bytes, %TRUE is returned, and @bytes_written
+is set to @count.
+
+If there is an error during the operation %FALSE is returned and @error
+is set to indicate the error status.
+
+As a special exception to the normal conventions for functions that
+use #GError, if this function returns %FALSE (and sets @error) then
+@bytes_written will be set to the number of bytes that were
+successfully written before the error was encountered. This
+functionality is only available from C. If you need it from another
+language then you must write your own loop around
+g_output_stream_write().
+
+
+ %TRUE on success, %FALSE if there was an error
+
+
+
+
+ a #GOutputStream.
+
+
+
+ the buffer containing the data to write.
+
+
+
+
+
+ the number of bytes to write
+
+
+
+ location to store the number of bytes that was
+ written to the stream
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Request an asynchronous write of @count bytes from @buffer into
+the stream. When the operation is finished @callback will be called.
+You can then call g_output_stream_write_all_finish() to get the result of the
+operation.
+
+This is the asynchronous version of g_output_stream_write_all().
+
+Call g_output_stream_write_all_finish() to collect the result.
+
+Any outstanding I/O request with higher priority (lower numerical
+value) will be executed before an outstanding request with lower
+priority. Default priority is %G_PRIORITY_DEFAULT.
+
+Note that no copy of @buffer will be made, so it must stay valid
+until @callback is called.
+
+
+
+
+
+
+ A #GOutputStream
+
+
+
+ the buffer containing the data to write
+
+
+
+
+
+ the number of bytes to write
+
+
+
+ the io priority of the request
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous stream write operation started with
+g_output_stream_write_all_async().
+
+As a special exception to the normal conventions for functions that
+use #GError, if this function returns %FALSE (and sets @error) then
+@bytes_written will be set to the number of bytes that were
+successfully written before the error was encountered. This
+functionality is only available from C. If you need it from another
+language then you must write your own loop around
+g_output_stream_write_async().
+
+
+ %TRUE on success, %FALSE if there was an error
+
+
+
+
+ a #GOutputStream
+
+
+
+ a #GAsyncResult
+
+
+
+ location to store the number of bytes that was written to the stream
+
+
+
+
+
+ Request an asynchronous write of @count bytes from @buffer into
+the stream. When the operation is finished @callback will be called.
+You can then call g_output_stream_write_finish() to get the result of the
+operation.
+
+During an async request no other sync and async calls are allowed,
+and will result in %G_IO_ERROR_PENDING errors.
+
+A value of @count larger than %G_MAXSSIZE will cause a
+%G_IO_ERROR_INVALID_ARGUMENT error.
+
+On success, the number of bytes written will be passed to the
+@callback. It is not an error if this is not the same as the
+requested size, as it can happen e.g. on a partial I/O error,
+but generally we try to write as many bytes as requested.
+
+You are guaranteed that this method will never fail with
+%G_IO_ERROR_WOULD_BLOCK - if @stream can't accept more data, the
+method will just wait until this changes.
+
+Any outstanding I/O request with higher priority (lower numerical
+value) will be executed before an outstanding request with lower
+priority. Default priority is %G_PRIORITY_DEFAULT.
+
+The asynchronous methods have a default fallback that uses threads
+to implement asynchronicity, so they are optional for inheriting
+classes. However, if you override one you must override all.
+
+For the synchronous, blocking version of this function, see
+g_output_stream_write().
+
+Note that no copy of @buffer will be made, so it must stay valid
+until @callback is called. See g_output_stream_write_bytes_async()
+for a #GBytes version that will automatically hold a reference to
+the contents (without copying) for the duration of the call.
+
+
+
+
+
+
+ A #GOutputStream.
+
+
+
+ the buffer containing the data to write.
+
+
+
+
+
+ the number of bytes to write
+
+
+
+ the io priority of the request.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ A wrapper function for g_output_stream_write() which takes a
+#GBytes as input. This can be more convenient for use by language
+bindings or in other cases where the refcounted nature of #GBytes
+is helpful over a bare pointer interface.
+
+However, note that this function may still perform partial writes,
+just like g_output_stream_write(). If that occurs, to continue
+writing, you will need to create a new #GBytes containing just the
+remaining bytes, using g_bytes_new_from_bytes(). Passing the same
+#GBytes instance multiple times potentially can result in duplicated
+data in the output stream.
+
+
+ Number of bytes written, or -1 on error
+
+
+
+
+ a #GOutputStream.
+
+
+
+ the #GBytes to write
+
+
+
+ optional cancellable object
+
+
+
+
+
+ This function is similar to g_output_stream_write_async(), but
+takes a #GBytes as input. Due to the refcounted nature of #GBytes,
+this allows the stream to avoid taking a copy of the data.
+
+However, note that this function may still perform partial writes,
+just like g_output_stream_write_async(). If that occurs, to continue
+writing, you will need to create a new #GBytes containing just the
+remaining bytes, using g_bytes_new_from_bytes(). Passing the same
+#GBytes instance multiple times potentially can result in duplicated
+data in the output stream.
+
+For the synchronous, blocking version of this function, see
+g_output_stream_write_bytes().
+
+
+
+
+
+
+ A #GOutputStream.
+
+
+
+ The bytes to write
+
+
+
+ the io priority of the request.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes a stream write-from-#GBytes operation.
+
+
+ a #gssize containing the number of bytes written to the stream.
+
+
+
+
+ a #GOutputStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Finishes a stream write operation.
+
+
+ a #gssize containing the number of bytes written to the stream.
+
+
+
+
+ a #GOutputStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Tries to write the bytes contained in the @n_vectors @vectors into the
+stream. Will block during the operation.
+
+If @n_vectors is 0 or the sum of all bytes in @vectors is 0, returns 0 and
+does nothing.
+
+On success, the number of bytes written to the stream is returned.
+It is not an error if this is not the same as the requested size, as it
+can happen e.g. on a partial I/O error, or if there is not enough
+storage in the stream. All writes block until at least one byte
+is written or an error occurs; 0 is never returned (unless
+@n_vectors is 0 or the sum of all bytes in @vectors is 0).
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
+operation was partially finished when the operation was cancelled the
+partial result will be returned, without an error.
+
+Some implementations of g_output_stream_writev() may have limitations on the
+aggregate buffer size, and will return %G_IO_ERROR_INVALID_ARGUMENT if these
+are exceeded. For example, when writing to a local file on UNIX platforms,
+the aggregate buffer size must not exceed %G_MAXSSIZE bytes.
+
+
+ %TRUE on success, %FALSE if there was an error
+
+
+
+
+ a #GOutputStream.
+
+
+
+ the buffer containing the #GOutputVectors to write.
+
+
+
+
+
+ the number of vectors to write
+
+
+
+ location to store the number of bytes that were
+ written to the stream
+
+
+
+ optional cancellable object
+
+
+
+
+
+ Tries to write the bytes contained in the @n_vectors @vectors into the
+stream. Will block during the operation.
+
+This function is similar to g_output_stream_writev(), except it tries to
+write as many bytes as requested, only stopping on an error.
+
+On a successful write of all @n_vectors vectors, %TRUE is returned, and
+@bytes_written is set to the sum of all the sizes of @vectors.
+
+If there is an error during the operation %FALSE is returned and @error
+is set to indicate the error status.
+
+As a special exception to the normal conventions for functions that
+use #GError, if this function returns %FALSE (and sets @error) then
+@bytes_written will be set to the number of bytes that were
+successfully written before the error was encountered. This
+functionality is only available from C. If you need it from another
+language then you must write your own loop around
+g_output_stream_write().
+
+The content of the individual elements of @vectors might be changed by this
+function.
+
+
+ %TRUE on success, %FALSE if there was an error
+
+
+
+
+ a #GOutputStream.
+
+
+
+ the buffer containing the #GOutputVectors to write.
+
+
+
+
+
+ the number of vectors to write
+
+
+
+ location to store the number of bytes that were
+ written to the stream
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Request an asynchronous write of the bytes contained in the @n_vectors @vectors into
+the stream. When the operation is finished @callback will be called.
+You can then call g_output_stream_writev_all_finish() to get the result of the
+operation.
+
+This is the asynchronous version of g_output_stream_writev_all().
+
+Call g_output_stream_writev_all_finish() to collect the result.
+
+Any outstanding I/O request with higher priority (lower numerical
+value) will be executed before an outstanding request with lower
+priority. Default priority is %G_PRIORITY_DEFAULT.
+
+Note that no copy of @vectors will be made, so it must stay valid
+until @callback is called. The content of the individual elements
+of @vectors might be changed by this function.
+
+
+
+
+
+
+ A #GOutputStream
+
+
+
+ the buffer containing the #GOutputVectors to write.
+
+
+
+
+
+ the number of vectors to write
+
+
+
+ the I/O priority of the request
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous stream write operation started with
+g_output_stream_writev_all_async().
+
+As a special exception to the normal conventions for functions that
+use #GError, if this function returns %FALSE (and sets @error) then
+@bytes_written will be set to the number of bytes that were
+successfully written before the error was encountered. This
+functionality is only available from C. If you need it from another
+language then you must write your own loop around
+g_output_stream_writev_async().
+
+
+ %TRUE on success, %FALSE if there was an error
+
+
+
+
+ a #GOutputStream
+
+
+
+ a #GAsyncResult
+
+
+
+ location to store the number of bytes that were written to the stream
+
+
+
+
+
+ Request an asynchronous write of the bytes contained in @n_vectors @vectors into
+the stream. When the operation is finished @callback will be called.
+You can then call g_output_stream_writev_finish() to get the result of the
+operation.
+
+During an async request no other sync and async calls are allowed,
+and will result in %G_IO_ERROR_PENDING errors.
+
+On success, the number of bytes written will be passed to the
+@callback. It is not an error if this is not the same as the
+requested size, as it can happen e.g. on a partial I/O error,
+but generally we try to write as many bytes as requested.
+
+You are guaranteed that this method will never fail with
+%G_IO_ERROR_WOULD_BLOCK — if @stream can't accept more data, the
+method will just wait until this changes.
+
+Any outstanding I/O request with higher priority (lower numerical
+value) will be executed before an outstanding request with lower
+priority. Default priority is %G_PRIORITY_DEFAULT.
+
+The asynchronous methods have a default fallback that uses threads
+to implement asynchronicity, so they are optional for inheriting
+classes. However, if you override one you must override all.
+
+For the synchronous, blocking version of this function, see
+g_output_stream_writev().
+
+Note that no copy of @vectors will be made, so it must stay valid
+until @callback is called.
+
+
+
+
+
+
+ A #GOutputStream.
+
+
+
+ the buffer containing the #GOutputVectors to write.
+
+
+
+
+
+ the number of vectors to write
+
+
+
+ the I/O priority of the request.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes a stream writev operation.
+
+
+ %TRUE on success, %FALSE if there was an error
+
+
+
+
+ a #GOutputStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+ location to store the number of bytes that were written to the stream
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Number of bytes written, or -1 on error
+
+
+
+
+ a #GOutputStream.
+
+
+
+ the buffer containing the data to write.
+
+
+
+
+
+ the number of bytes to write
+
+
+
+ optional cancellable object
+
+
+
+
+
+
+
+
+
+ a #gssize containing the size of the data spliced, or
+ -1 if an error occurred. Note that if the number of bytes
+ spliced is greater than %G_MAXSSIZE, then that will be
+ returned, and there is no way to determine the actual number
+ of bytes spliced.
+
+
+
+
+ a #GOutputStream.
+
+
+
+ a #GInputStream.
+
+
+
+ a set of #GOutputStreamSpliceFlags.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+
+
+
+
+ %TRUE on success, %FALSE on error
+
+
+
+
+ a #GOutputStream.
+
+
+
+ optional cancellable object
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ A #GOutputStream.
+
+
+
+ the buffer containing the data to write.
+
+
+
+
+
+ the number of bytes to write
+
+
+
+ the io priority of the request.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ a #gssize containing the number of bytes written to the stream.
+
+
+
+
+ a #GOutputStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GOutputStream.
+
+
+
+ a #GInputStream.
+
+
+
+ a set of #GOutputStreamSpliceFlags.
+
+
+
+ the io priority of the request.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback.
+
+
+
+ user data passed to @callback.
+
+
+
+
+
+
+
+
+
+ a #gssize of the number of bytes spliced. Note that if the
+ number of bytes spliced is greater than %G_MAXSSIZE, then that
+ will be returned, and there is no way to determine the actual
+ number of bytes spliced.
+
+
+
+
+ a #GOutputStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GOutputStream.
+
+
+
+ the io priority of the request.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ %TRUE if flush operation succeeded, %FALSE otherwise.
+
+
+
+
+ a #GOutputStream.
+
+
+
+ a GAsyncResult.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ A #GOutputStream.
+
+
+
+ the io priority of the request.
+
+
+
+ optional cancellable object
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ %TRUE if stream was successfully closed, %FALSE otherwise.
+
+
+
+
+ a #GOutputStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+ %TRUE on success, %FALSE if there was an error
+
+
+
+
+ a #GOutputStream.
+
+
+
+ the buffer containing the #GOutputVectors to write.
+
+
+
+
+
+ the number of vectors to write
+
+
+
+ location to store the number of bytes that were
+ written to the stream
+
+
+
+ optional cancellable object
+
+
+
+
+
+
+
+
+
+
+
+
+
+ A #GOutputStream.
+
+
+
+ the buffer containing the #GOutputVectors to write.
+
+
+
+
+
+ the number of vectors to write
+
+
+
+ the I/O priority of the request.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ callback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ %TRUE on success, %FALSE if there was an error
+
+
+
+
+ a #GOutputStream.
+
+
+
+ a #GAsyncResult.
+
+
+
+ location to store the number of bytes that were written to the stream
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ GOutputStreamSpliceFlags determine how streams should be spliced.
+
+ Do not close either stream.
+
+
+ Close the source stream after
+ the splice.
+
+
+ Close the target stream after
+ the splice.
+
+
+
+ Structure used for scatter/gather data output.
+You generally pass in an array of #GOutputVectors
+and the operation will use all the buffers as if they were
+one buffer.
+
+
+ Pointer to a buffer of data to read.
+
+
+
+ the size of @buffer.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Extension point for power profile usage monitoring functionality.
+See [Extending GIO][extending-gio].
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Extension point for proxy functionality.
+See [Extending GIO][extending-gio].
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Extension point for proxy resolving functionality.
+See [Extending GIO][extending-gio].
+
+
+
+
+
+
+
+
+
+
+
+ #GPasswordSave is used to indicate the lifespan of a saved password.
+
+#Gvfs stores passwords in the Gnome keyring when this flag allows it
+to, and later retrieves it again from there.
+
+ never save a password.
+
+
+ save a password for the session.
+
+
+ save a password permanently.
+
+
+
+ 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.
+
+
+ Attempts to acquire the permission represented by @permission.
+
+The precise method by which this happens depends on the permission
+and the underlying authentication mechanism. A simple example is
+that a dialog may appear asking the user to enter their password.
+
+You should check with g_permission_get_can_acquire() before calling
+this function.
+
+If the permission is acquired then %TRUE is returned. Otherwise,
+%FALSE is returned and @error is set appropriately.
+
+This call is blocking, likely for a very long time (in the case that
+user interaction is required). See g_permission_acquire_async() for
+the non-blocking version.
+
+
+ %TRUE if the permission was successfully acquired
+
+
+
+
+ a #GPermission instance
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Attempts to acquire the permission represented by @permission.
+
+This is the first half of the asynchronous version of
+g_permission_acquire().
+
+
+
+
+
+
+ a #GPermission instance
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ the #GAsyncReadyCallback to call when done
+
+
+
+ the user data to pass to @callback
+
+
+
+
+
+ Collects the result of attempting to acquire the permission
+represented by @permission.
+
+This is the second half of the asynchronous version of
+g_permission_acquire().
+
+
+ %TRUE if the permission was successfully acquired
+
+
+
+
+ a #GPermission instance
+
+
+
+ the #GAsyncResult given to the #GAsyncReadyCallback
+
+
+
+
+
+ Attempts to release the permission represented by @permission.
+
+The precise method by which this happens depends on the permission
+and the underlying authentication mechanism. In most cases the
+permission will be dropped immediately without further action.
+
+You should check with g_permission_get_can_release() before calling
+this function.
+
+If the permission is released then %TRUE is returned. Otherwise,
+%FALSE is returned and @error is set appropriately.
+
+This call is blocking, likely for a very long time (in the case that
+user interaction is required). See g_permission_release_async() for
+the non-blocking version.
+
+
+ %TRUE if the permission was successfully released
+
+
+
+
+ a #GPermission instance
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Attempts to release the permission represented by @permission.
+
+This is the first half of the asynchronous version of
+g_permission_release().
+
+
+
+
+
+
+ a #GPermission instance
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ the #GAsyncReadyCallback to call when done
+
+
+
+ the user data to pass to @callback
+
+
+
+
+
+ Collects the result of attempting to release the permission
+represented by @permission.
+
+This is the second half of the asynchronous version of
+g_permission_release().
+
+
+ %TRUE if the permission was successfully released
+
+
+
+
+ a #GPermission instance
+
+
+
+ the #GAsyncResult given to the #GAsyncReadyCallback
+
+
+
+
+
+ Attempts to acquire the permission represented by @permission.
+
+The precise method by which this happens depends on the permission
+and the underlying authentication mechanism. A simple example is
+that a dialog may appear asking the user to enter their password.
+
+You should check with g_permission_get_can_acquire() before calling
+this function.
+
+If the permission is acquired then %TRUE is returned. Otherwise,
+%FALSE is returned and @error is set appropriately.
+
+This call is blocking, likely for a very long time (in the case that
+user interaction is required). See g_permission_acquire_async() for
+the non-blocking version.
+
+
+ %TRUE if the permission was successfully acquired
+
+
+
+
+ a #GPermission instance
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Attempts to acquire the permission represented by @permission.
+
+This is the first half of the asynchronous version of
+g_permission_acquire().
+
+
+
+
+
+
+ a #GPermission instance
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ the #GAsyncReadyCallback to call when done
+
+
+
+ the user data to pass to @callback
+
+
+
+
+
+ Collects the result of attempting to acquire the permission
+represented by @permission.
+
+This is the second half of the asynchronous version of
+g_permission_acquire().
+
+
+ %TRUE if the permission was successfully acquired
+
+
+
+
+ a #GPermission instance
+
+
+
+ the #GAsyncResult given to the #GAsyncReadyCallback
+
+
+
+
+
+ Gets the value of the 'allowed' property. This property is %TRUE if
+the caller currently has permission to perform the action that
+@permission represents the permission to perform.
+
+
+ the value of the 'allowed' property
+
+
+
+
+ a #GPermission instance
+
+
+
+
+
+ Gets the value of the 'can-acquire' property. This property is %TRUE
+if it is generally possible to acquire the permission by calling
+g_permission_acquire().
+
+
+ the value of the 'can-acquire' property
+
+
+
+
+ a #GPermission instance
+
+
+
+
+
+ Gets the value of the 'can-release' property. This property is %TRUE
+if it is generally possible to release the permission by calling
+g_permission_release().
+
+
+ the value of the 'can-release' property
+
+
+
+
+ a #GPermission instance
+
+
+
+
+
+ This function is called by the #GPermission implementation to update
+the properties of the permission. You should never call this
+function except from a #GPermission implementation.
+
+GObject notify signals are generated, as appropriate.
+
+
+
+
+
+
+ a #GPermission instance
+
+
+
+ the new value for the 'allowed' property
+
+
+
+ the new value for the 'can-acquire' property
+
+
+
+ the new value for the 'can-release' property
+
+
+
+
+
+ Attempts to release the permission represented by @permission.
+
+The precise method by which this happens depends on the permission
+and the underlying authentication mechanism. In most cases the
+permission will be dropped immediately without further action.
+
+You should check with g_permission_get_can_release() before calling
+this function.
+
+If the permission is released then %TRUE is returned. Otherwise,
+%FALSE is returned and @error is set appropriately.
+
+This call is blocking, likely for a very long time (in the case that
+user interaction is required). See g_permission_release_async() for
+the non-blocking version.
+
+
+ %TRUE if the permission was successfully released
+
+
+
+
+ a #GPermission instance
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Attempts to release the permission represented by @permission.
+
+This is the first half of the asynchronous version of
+g_permission_release().
+
+
+
+
+
+
+ a #GPermission instance
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ the #GAsyncReadyCallback to call when done
+
+
+
+ the user data to pass to @callback
+
+
+
+
+
+ Collects the result of attempting to release the permission
+represented by @permission.
+
+This is the second half of the asynchronous version of
+g_permission_release().
+
+
+ %TRUE if the permission was successfully released
+
+
+
+
+ a #GPermission instance
+
+
+
+ the #GAsyncResult given to the #GAsyncReadyCallback
+
+
+
+
+
+ %TRUE if the caller currently has permission to perform the action that
+@permission represents the permission to perform.
+
+
+
+ %TRUE if it is generally possible to acquire the permission by calling
+g_permission_acquire().
+
+
+
+ %TRUE if it is generally possible to release the permission by calling
+g_permission_release().
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ %TRUE if the permission was successfully acquired
+
+
+
+
+ a #GPermission instance
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GPermission instance
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ the #GAsyncReadyCallback to call when done
+
+
+
+ the user data to pass to @callback
+
+
+
+
+
+
+
+
+
+ %TRUE if the permission was successfully acquired
+
+
+
+
+ a #GPermission instance
+
+
+
+ the #GAsyncResult given to the #GAsyncReadyCallback
+
+
+
+
+
+
+
+
+
+ %TRUE if the permission was successfully released
+
+
+
+
+ a #GPermission instance
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GPermission instance
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ the #GAsyncReadyCallback to call when done
+
+
+
+ the user data to pass to @callback
+
+
+
+
+
+
+
+
+
+ %TRUE if the permission was successfully released
+
+
+
+
+ a #GPermission instance
+
+
+
+ the #GAsyncResult given to the #GAsyncReadyCallback
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #GPollableInputStream is implemented by #GInputStreams that
+can be polled for readiness to read. This can be used when
+interfacing with a non-GIO API that expects
+UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
+
+
+
+ Checks if @stream is actually pollable. Some classes may implement
+#GPollableInputStream but have only certain instances of that class
+be pollable. If this method returns %FALSE, then the behavior of
+other #GPollableInputStream methods is undefined.
+
+For any given stream, the value returned by this method is constant;
+a stream cannot switch from pollable to non-pollable or vice versa.
+
+
+ %TRUE if @stream is pollable, %FALSE if not.
+
+
+
+
+ a #GPollableInputStream.
+
+
+
+
+
+ Creates a #GSource that triggers when @stream can be read, or
+@cancellable is triggered or an error occurs. The callback on the
+source is of the #GPollableSourceFunc type.
+
+As with g_pollable_input_stream_is_readable(), it is possible that
+the stream may not actually be readable even after the source
+triggers, so you should use g_pollable_input_stream_read_nonblocking()
+rather than g_input_stream_read() from the callback.
+
+
+ a new #GSource
+
+
+
+
+ a #GPollableInputStream.
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Checks if @stream can be read.
+
+Note that some stream types may not be able to implement this 100%
+reliably, and it is possible that a call to g_input_stream_read()
+after this returns %TRUE would still block. To guarantee
+non-blocking behavior, you should always use
+g_pollable_input_stream_read_nonblocking(), which will return a
+%G_IO_ERROR_WOULD_BLOCK error rather than blocking.
+
+
+ %TRUE if @stream is readable, %FALSE if not. If an error
+ has occurred on @stream, this will result in
+ g_pollable_input_stream_is_readable() returning %TRUE, and the
+ next attempt to read will return the error.
+
+
+
+
+ a #GPollableInputStream.
+
+
+
+
+
+ Attempts to read up to @count bytes from @stream into @buffer, as
+with g_input_stream_read(). If @stream is not currently readable,
+this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can
+use g_pollable_input_stream_create_source() to create a #GSource
+that will be triggered when @stream is readable.
+
+Note that since this method never blocks, you cannot actually
+use @cancellable to cancel it. However, it will return an error
+if @cancellable has already been cancelled when you call, which
+may happen if you call this method after a source triggers due
+to having been cancelled.
+
+
+ the number of bytes read, or -1 on error (including
+ %G_IO_ERROR_WOULD_BLOCK).
+
+
+
+
+ a #GPollableInputStream
+
+
+
+ a
+ buffer to read data into (which should be at least @count bytes long).
+
+
+
+
+
+ the number of bytes you want to read
+
+
+
+
+
+ Checks if @stream is actually pollable. Some classes may implement
+#GPollableInputStream but have only certain instances of that class
+be pollable. If this method returns %FALSE, then the behavior of
+other #GPollableInputStream methods is undefined.
+
+For any given stream, the value returned by this method is constant;
+a stream cannot switch from pollable to non-pollable or vice versa.
+
+
+ %TRUE if @stream is pollable, %FALSE if not.
+
+
+
+
+ a #GPollableInputStream.
+
+
+
+
+
+ Creates a #GSource that triggers when @stream can be read, or
+@cancellable is triggered or an error occurs. The callback on the
+source is of the #GPollableSourceFunc type.
+
+As with g_pollable_input_stream_is_readable(), it is possible that
+the stream may not actually be readable even after the source
+triggers, so you should use g_pollable_input_stream_read_nonblocking()
+rather than g_input_stream_read() from the callback.
+
+
+ a new #GSource
+
+
+
+
+ a #GPollableInputStream.
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Checks if @stream can be read.
+
+Note that some stream types may not be able to implement this 100%
+reliably, and it is possible that a call to g_input_stream_read()
+after this returns %TRUE would still block. To guarantee
+non-blocking behavior, you should always use
+g_pollable_input_stream_read_nonblocking(), which will return a
+%G_IO_ERROR_WOULD_BLOCK error rather than blocking.
+
+
+ %TRUE if @stream is readable, %FALSE if not. If an error
+ has occurred on @stream, this will result in
+ g_pollable_input_stream_is_readable() returning %TRUE, and the
+ next attempt to read will return the error.
+
+
+
+
+ a #GPollableInputStream.
+
+
+
+
+
+ Attempts to read up to @count bytes from @stream into @buffer, as
+with g_input_stream_read(). If @stream is not currently readable,
+this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can
+use g_pollable_input_stream_create_source() to create a #GSource
+that will be triggered when @stream is readable.
+
+Note that since this method never blocks, you cannot actually
+use @cancellable to cancel it. However, it will return an error
+if @cancellable has already been cancelled when you call, which
+may happen if you call this method after a source triggers due
+to having been cancelled.
+
+
+ the number of bytes read, or -1 on error (including
+ %G_IO_ERROR_WOULD_BLOCK).
+
+
+
+
+ a #GPollableInputStream
+
+
+
+ a
+ buffer to read data into (which should be at least @count bytes long).
+
+
+
+
+
+ the number of bytes you want to read
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+
+ 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.
+
+
+ The parent interface.
+
+
+
+
+
+
+ %TRUE if @stream is pollable, %FALSE if not.
+
+
+
+
+ a #GPollableInputStream.
+
+
+
+
+
+
+
+
+
+ %TRUE if @stream is readable, %FALSE if not. If an error
+ has occurred on @stream, this will result in
+ g_pollable_input_stream_is_readable() returning %TRUE, and the
+ next attempt to read will return the error.
+
+
+
+
+ a #GPollableInputStream.
+
+
+
+
+
+
+
+
+
+ a new #GSource
+
+
+
+
+ a #GPollableInputStream.
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+
+
+
+
+ the number of bytes read, or -1 on error (including
+ %G_IO_ERROR_WOULD_BLOCK).
+
+
+
+
+ a #GPollableInputStream
+
+
+
+ a
+ buffer to read data into (which should be at least @count bytes long).
+
+
+
+
+
+ the number of bytes you want to read
+
+
+
+
+
+
+
+ #GPollableOutputStream is implemented by #GOutputStreams that
+can be polled for readiness to write. This can be used when
+interfacing with a non-GIO API that expects
+UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
+
+
+
+ Checks if @stream is actually pollable. Some classes may implement
+#GPollableOutputStream but have only certain instances of that
+class be pollable. If this method returns %FALSE, then the behavior
+of other #GPollableOutputStream methods is undefined.
+
+For any given stream, the value returned by this method is constant;
+a stream cannot switch from pollable to non-pollable or vice versa.
+
+
+ %TRUE if @stream is pollable, %FALSE if not.
+
+
+
+
+ a #GPollableOutputStream.
+
+
+
+
+
+ Creates a #GSource that triggers when @stream can be written, or
+@cancellable is triggered or an error occurs. The callback on the
+source is of the #GPollableSourceFunc type.
+
+As with g_pollable_output_stream_is_writable(), it is possible that
+the stream may not actually be writable even after the source
+triggers, so you should use g_pollable_output_stream_write_nonblocking()
+rather than g_output_stream_write() from the callback.
+
+
+ a new #GSource
+
+
+
+
+ a #GPollableOutputStream.
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Checks if @stream can be written.
+
+Note that some stream types may not be able to implement this 100%
+reliably, and it is possible that a call to g_output_stream_write()
+after this returns %TRUE would still block. To guarantee
+non-blocking behavior, you should always use
+g_pollable_output_stream_write_nonblocking(), which will return a
+%G_IO_ERROR_WOULD_BLOCK error rather than blocking.
+
+
+ %TRUE if @stream is writable, %FALSE if not. If an error
+ has occurred on @stream, this will result in
+ g_pollable_output_stream_is_writable() returning %TRUE, and the
+ next attempt to write will return the error.
+
+
+
+
+ a #GPollableOutputStream.
+
+
+
+
+
+ Attempts to write up to @count bytes from @buffer to @stream, as
+with g_output_stream_write(). If @stream is not currently writable,
+this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can
+use g_pollable_output_stream_create_source() to create a #GSource
+that will be triggered when @stream is writable.
+
+Note that since this method never blocks, you cannot actually
+use @cancellable to cancel it. However, it will return an error
+if @cancellable has already been cancelled when you call, which
+may happen if you call this method after a source triggers due
+to having been cancelled.
+
+Also note that if %G_IO_ERROR_WOULD_BLOCK is returned some underlying
+transports like D/TLS require that you re-send the same @buffer and
+@count in the next write call.
+
+
+ the number of bytes written, or -1 on error (including
+ %G_IO_ERROR_WOULD_BLOCK).
+
+
+
+
+ a #GPollableOutputStream
+
+
+
+ a buffer to write
+ data from
+
+
+
+
+
+ the number of bytes you want to write
+
+
+
+
+
+ Attempts to write the bytes contained in the @n_vectors @vectors to @stream,
+as with g_output_stream_writev(). If @stream is not currently writable,
+this will immediately return %@G_POLLABLE_RETURN_WOULD_BLOCK, and you can
+use g_pollable_output_stream_create_source() to create a #GSource
+that will be triggered when @stream is writable. @error will *not* be
+set in that case.
+
+Note that since this method never blocks, you cannot actually
+use @cancellable to cancel it. However, it will return an error
+if @cancellable has already been cancelled when you call, which
+may happen if you call this method after a source triggers due
+to having been cancelled.
+
+Also note that if %G_POLLABLE_RETURN_WOULD_BLOCK is returned some underlying
+transports like D/TLS require that you re-send the same @vectors and
+@n_vectors in the next write call.
+
+
+ %@G_POLLABLE_RETURN_OK on success, %G_POLLABLE_RETURN_WOULD_BLOCK
+if the stream is not currently writable (and @error is *not* set), or
+%G_POLLABLE_RETURN_FAILED if there was an error in which case @error will
+be set.
+
+
+
+
+ a #GPollableOutputStream
+
+
+
+ the buffer containing the #GOutputVectors to write.
+
+
+
+
+
+ the number of vectors to write
+
+
+
+ location to store the number of bytes that were
+ written to the stream
+
+
+
+
+
+ Checks if @stream is actually pollable. Some classes may implement
+#GPollableOutputStream but have only certain instances of that
+class be pollable. If this method returns %FALSE, then the behavior
+of other #GPollableOutputStream methods is undefined.
+
+For any given stream, the value returned by this method is constant;
+a stream cannot switch from pollable to non-pollable or vice versa.
+
+
+ %TRUE if @stream is pollable, %FALSE if not.
+
+
+
+
+ a #GPollableOutputStream.
+
+
+
+
+
+ Creates a #GSource that triggers when @stream can be written, or
+@cancellable is triggered or an error occurs. The callback on the
+source is of the #GPollableSourceFunc type.
+
+As with g_pollable_output_stream_is_writable(), it is possible that
+the stream may not actually be writable even after the source
+triggers, so you should use g_pollable_output_stream_write_nonblocking()
+rather than g_output_stream_write() from the callback.
+
+
+ a new #GSource
+
+
+
+
+ a #GPollableOutputStream.
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Checks if @stream can be written.
+
+Note that some stream types may not be able to implement this 100%
+reliably, and it is possible that a call to g_output_stream_write()
+after this returns %TRUE would still block. To guarantee
+non-blocking behavior, you should always use
+g_pollable_output_stream_write_nonblocking(), which will return a
+%G_IO_ERROR_WOULD_BLOCK error rather than blocking.
+
+
+ %TRUE if @stream is writable, %FALSE if not. If an error
+ has occurred on @stream, this will result in
+ g_pollable_output_stream_is_writable() returning %TRUE, and the
+ next attempt to write will return the error.
+
+
+
+
+ a #GPollableOutputStream.
+
+
+
+
+
+ Attempts to write up to @count bytes from @buffer to @stream, as
+with g_output_stream_write(). If @stream is not currently writable,
+this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can
+use g_pollable_output_stream_create_source() to create a #GSource
+that will be triggered when @stream is writable.
+
+Note that since this method never blocks, you cannot actually
+use @cancellable to cancel it. However, it will return an error
+if @cancellable has already been cancelled when you call, which
+may happen if you call this method after a source triggers due
+to having been cancelled.
+
+Also note that if %G_IO_ERROR_WOULD_BLOCK is returned some underlying
+transports like D/TLS require that you re-send the same @buffer and
+@count in the next write call.
+
+
+ the number of bytes written, or -1 on error (including
+ %G_IO_ERROR_WOULD_BLOCK).
+
+
+
+
+ a #GPollableOutputStream
+
+
+
+ a buffer to write
+ data from
+
+
+
+
+
+ the number of bytes you want to write
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Attempts to write the bytes contained in the @n_vectors @vectors to @stream,
+as with g_output_stream_writev(). If @stream is not currently writable,
+this will immediately return %@G_POLLABLE_RETURN_WOULD_BLOCK, and you can
+use g_pollable_output_stream_create_source() to create a #GSource
+that will be triggered when @stream is writable. @error will *not* be
+set in that case.
+
+Note that since this method never blocks, you cannot actually
+use @cancellable to cancel it. However, it will return an error
+if @cancellable has already been cancelled when you call, which
+may happen if you call this method after a source triggers due
+to having been cancelled.
+
+Also note that if %G_POLLABLE_RETURN_WOULD_BLOCK is returned some underlying
+transports like D/TLS require that you re-send the same @vectors and
+@n_vectors in the next write call.
+
+
+ %@G_POLLABLE_RETURN_OK on success, %G_POLLABLE_RETURN_WOULD_BLOCK
+if the stream is not currently writable (and @error is *not* set), or
+%G_POLLABLE_RETURN_FAILED if there was an error in which case @error will
+be set.
+
+
+
+
+ a #GPollableOutputStream
+
+
+
+ the buffer containing the #GOutputVectors to write.
+
+
+
+
+
+ the number of vectors to write
+
+
+
+ location to store the number of bytes that were
+ written to the stream
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+
+ 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.
+
+The default implementation of @writev_nonblocking calls
+g_pollable_output_stream_write_nonblocking() for each vector, and converts
+its return value and error (if set) to a #GPollableReturn. You should
+override this where possible to avoid having to allocate a #GError to return
+%G_IO_ERROR_WOULD_BLOCK.
+
+
+ The parent interface.
+
+
+
+
+
+
+ %TRUE if @stream is pollable, %FALSE if not.
+
+
+
+
+ a #GPollableOutputStream.
+
+
+
+
+
+
+
+
+
+ %TRUE if @stream is writable, %FALSE if not. If an error
+ has occurred on @stream, this will result in
+ g_pollable_output_stream_is_writable() returning %TRUE, and the
+ next attempt to write will return the error.
+
+
+
+
+ a #GPollableOutputStream.
+
+
+
+
+
+
+
+
+
+ a new #GSource
+
+
+
+
+ a #GPollableOutputStream.
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+
+
+
+
+ the number of bytes written, or -1 on error (including
+ %G_IO_ERROR_WOULD_BLOCK).
+
+
+
+
+ a #GPollableOutputStream
+
+
+
+ a buffer to write
+ data from
+
+
+
+
+
+ the number of bytes you want to write
+
+
+
+
+
+
+
+
+
+ %@G_POLLABLE_RETURN_OK on success, %G_POLLABLE_RETURN_WOULD_BLOCK
+if the stream is not currently writable (and @error is *not* set), or
+%G_POLLABLE_RETURN_FAILED if there was an error in which case @error will
+be set.
+
+
+
+
+ a #GPollableOutputStream
+
+
+
+ the buffer containing the #GOutputVectors to write.
+
+
+
+
+
+ the number of vectors to write
+
+
+
+ location to store the number of bytes that were
+ written to the stream
+
+
+
+
+
+
+
+ Return value for various IO operations that signal errors via the
+return value and not necessarily via a #GError.
+
+This enum exists to be able to return errors to callers without having to
+allocate a #GError. Allocating #GErrors can be quite expensive for
+regularly happening errors like %G_IO_ERROR_WOULD_BLOCK.
+
+In case of %G_POLLABLE_RETURN_FAILED a #GError should be set for the
+operation to give details about the error that happened.
+
+ Generic error condition for when an operation fails.
+
+
+ The operation was successfully finished.
+
+
+ The operation would block.
+
+
+
+ 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().
+
+
+ it should return %FALSE if the source should be removed.
+
+
+
+
+ the #GPollableInputStream or #GPollableOutputStream
+
+
+
+ data passed in by the user.
+
+
+
+
+
+ #GPowerProfileMonitor makes it possible for applications as well as OS components
+to monitor system power profiles and act upon them. It currently only exports
+whether the system is in “Power Saver” mode (known as “Low Power” mode on
+some systems).
+
+When in “Low Power” mode, it is recommended that applications:
+- disable automatic downloads;
+- reduce the rate of refresh from online sources such as calendar or
+ email synchronisation;
+- reduce the use of expensive visual effects.
+
+It is also likely that OS components providing services to applications will
+lower their own background activity, for the sake of the system.
+
+There are a variety of tools that exist for power consumption analysis, but those
+usually depend on the OS and hardware used. On Linux, one could use `upower` to
+monitor the battery discharge rate, `powertop` to check on the background activity
+or activity at all), `sysprof` to inspect CPU usage, and `intel_gpu_time` to
+profile GPU usage.
+
+Don't forget to disconnect the #GPowerProfileMonitor::notify::power-saver-enabled
+signal, and unref the #GPowerProfileMonitor itself when exiting.
+
+
+
+ Gets a reference to the default #GPowerProfileMonitor for the system.
+
+
+ a new reference to the default #GPowerProfileMonitor
+
+
+
+
+ Gets whether the system is in “Power Saver” mode.
+
+You are expected to listen to the
+#GPowerProfileMonitor::notify::power-saver-enabled signal to know when the profile has
+changed.
+
+
+ Whether the system is in “Power Saver” mode.
+
+
+
+
+ a #GPowerProfileMonitor
+
+
+
+
+
+ Whether “Power Saver” mode is enabled on the system.
+
+
+
+
+ The virtual function table for #GPowerProfileMonitor.
+
+
+ The parent interface.
+
+
+
+
+ A #GPropertyAction is a way to get a #GAction with a state value
+reflecting and controlling the value of a #GObject property.
+
+The state of the action will correspond to the value of the property.
+Changing it will change the property (assuming the requested value
+matches the requirements as specified in the #GParamSpec).
+
+Only the most common types are presently supported. Booleans are
+mapped to booleans, strings to strings, signed/unsigned integers to
+int32/uint32 and floats and doubles to doubles.
+
+If the property is an enum then the state will be string-typed and
+conversion will automatically be performed between the enum value and
+"nick" string as per the #GEnumValue table.
+
+Flags types are not currently supported.
+
+Properties of object types, boxed types and pointer types are not
+supported and probably never will be.
+
+Properties of #GVariant types are not currently supported.
+
+If the property is boolean-valued then the action will have a NULL
+parameter type, and activating the action (with no parameter) will
+toggle the value of the property.
+
+In all other cases, the parameter type will correspond to the type of
+the property.
+
+The general idea here is to reduce the number of locations where a
+particular piece of state is kept (and therefore has to be synchronised
+between). #GPropertyAction does not have a separate state that is kept
+in sync with the property value -- its state is the property value.
+
+For example, it might be useful to create a #GAction corresponding to
+the "visible-child-name" property of a #GtkStack so that the current
+page can be switched from a menu. The active radio indication in the
+menu is then directly determined from the active page of the
+#GtkStack.
+
+An anti-example would be binding the "active-id" property on a
+#GtkComboBox. This is because the state of the combobox itself is
+probably uninteresting and is actually being used to control
+something else.
+
+Another anti-example would be to bind to the "visible-child-name"
+property of a #GtkStack if this value is actually stored in
+#GSettings. In that case, the real source of the value is
+#GSettings. If you want a #GAction to control a setting stored in
+#GSettings, see g_settings_create_action() instead, and possibly
+combine its use with g_settings_bind().
+
+
+ Creates a #GAction corresponding to the value of property
+@property_name on @object.
+
+The property must be existent and readable and writable (and not
+construct-only).
+
+This function takes a reference on @object and doesn't release it
+until the action is destroyed.
+
+
+ a new #GPropertyAction
+
+
+
+
+ the name of the action to create
+
+
+
+ the object that has the property
+ to wrap
+
+
+
+ the name of the property
+
+
+
+
+
+ If @action is currently enabled.
+
+If the action is disabled then calls to g_action_activate() and
+g_action_change_state() have no effect.
+
+
+
+ If %TRUE, the state of the action will be the negation of the
+property value, provided the property is boolean.
+
+
+
+ The name of the action. This is mostly meaningful for identifying
+the action once it has been added to a #GActionMap.
+
+
+
+ The object to wrap a property on.
+
+The object must be a non-%NULL #GObject with properties.
+
+
+
+ The type of the parameter that must be given when activating the
+action.
+
+
+
+ The name of the property to wrap on the object.
+
+The property must exist on the passed-in object and it must be
+readable and writable (and not construct-only).
+
+
+
+ The state of the action, or %NULL if the action is stateless.
+
+
+
+ The #GVariantType of the state that the action has, or %NULL if the
+action is stateless.
+
+
+
+
+ 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().
+
+
+ Find the `gio-proxy` extension point for a proxy implementation that supports
+the specified protocol.
+
+
+ return a #GProxy or NULL if protocol
+ is not supported.
+
+
+
+
+ the proxy protocol name (e.g. http, socks, etc)
+
+
+
+
+
+ Given @connection to communicate with a proxy (eg, a
+#GSocketConnection that is connected to the proxy server), this
+does the necessary handshake to connect to @proxy_address, and if
+required, wraps the #GIOStream to handle proxy payload.
+
+
+ a #GIOStream that will replace @connection. This might
+ be the same as @connection, in which case a reference
+ will be added.
+
+
+
+
+ a #GProxy
+
+
+
+ a #GIOStream
+
+
+
+ a #GProxyAddress
+
+
+
+ a #GCancellable
+
+
+
+
+
+ Asynchronous version of g_proxy_connect().
+
+
+
+
+
+
+ a #GProxy
+
+
+
+ a #GIOStream
+
+
+
+ a #GProxyAddress
+
+
+
+ a #GCancellable
+
+
+
+ a #GAsyncReadyCallback
+
+
+
+ callback data
+
+
+
+
+
+ See g_proxy_connect().
+
+
+ a #GIOStream.
+
+
+
+
+ a #GProxy
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Some proxy protocols expect to be passed a hostname, which they
+will resolve to an IP address themselves. Others, like SOCKS4, do
+not allow this. This function will return %FALSE if @proxy is
+implementing such a protocol. When %FALSE is returned, the caller
+should resolve the destination hostname first, and then pass a
+#GProxyAddress containing the stringified IP address to
+g_proxy_connect() or g_proxy_connect_async().
+
+
+ %TRUE if hostname resolution is supported.
+
+
+
+
+ a #GProxy
+
+
+
+
+
+ Given @connection to communicate with a proxy (eg, a
+#GSocketConnection that is connected to the proxy server), this
+does the necessary handshake to connect to @proxy_address, and if
+required, wraps the #GIOStream to handle proxy payload.
+
+
+ a #GIOStream that will replace @connection. This might
+ be the same as @connection, in which case a reference
+ will be added.
+
+
+
+
+ a #GProxy
+
+
+
+ a #GIOStream
+
+
+
+ a #GProxyAddress
+
+
+
+ a #GCancellable
+
+
+
+
+
+ Asynchronous version of g_proxy_connect().
+
+
+
+
+
+
+ a #GProxy
+
+
+
+ a #GIOStream
+
+
+
+ a #GProxyAddress
+
+
+
+ a #GCancellable
+
+
+
+ a #GAsyncReadyCallback
+
+
+
+ callback data
+
+
+
+
+
+ See g_proxy_connect().
+
+
+ a #GIOStream.
+
+
+
+
+ a #GProxy
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Some proxy protocols expect to be passed a hostname, which they
+will resolve to an IP address themselves. Others, like SOCKS4, do
+not allow this. This function will return %FALSE if @proxy is
+implementing such a protocol. When %FALSE is returned, the caller
+should resolve the destination hostname first, and then pass a
+#GProxyAddress containing the stringified IP address to
+g_proxy_connect() or g_proxy_connect_async().
+
+
+ %TRUE if hostname resolution is supported.
+
+
+
+
+ a #GProxy
+
+
+
+
+
+
+ Support for proxied #GInetSocketAddress.
+
+
+
+ Creates a new #GProxyAddress for @inetaddr with @protocol that should
+tunnel through @dest_hostname and @dest_port.
+
+(Note that this method doesn't set the #GProxyAddress:uri or
+#GProxyAddress:destination-protocol fields; use g_object_new()
+directly if you want to set those.)
+
+
+ a new #GProxyAddress
+
+
+
+
+ The proxy server #GInetAddress.
+
+
+
+ The proxy server port.
+
+
+
+ The proxy protocol to support, in lower case (e.g. socks, http).
+
+
+
+ The destination hostname the proxy should tunnel to.
+
+
+
+ The destination port to tunnel to.
+
+
+
+ The username to authenticate to the proxy server
+ (or %NULL).
+
+
+
+ The password to authenticate to the proxy server
+ (or %NULL).
+
+
+
+
+
+ Gets @proxy's destination hostname; that is, the name of the host
+that will be connected to via the proxy, not the name of the proxy
+itself.
+
+
+ the @proxy's destination hostname
+
+
+
+
+ a #GProxyAddress
+
+
+
+
+
+ Gets @proxy's destination port; that is, the port on the
+destination host that will be connected to via the proxy, not the
+port number of the proxy itself.
+
+
+ the @proxy's destination port
+
+
+
+
+ a #GProxyAddress
+
+
+
+
+
+ Gets the protocol that is being spoken to the destination
+server; eg, "http" or "ftp".
+
+
+ the @proxy's destination protocol
+
+
+
+
+ a #GProxyAddress
+
+
+
+
+
+ Gets @proxy's password.
+
+
+ the @proxy's password
+
+
+
+
+ a #GProxyAddress
+
+
+
+
+
+ Gets @proxy's protocol. eg, "socks" or "http"
+
+
+ the @proxy's protocol
+
+
+
+
+ a #GProxyAddress
+
+
+
+
+
+ Gets the proxy URI that @proxy was constructed from.
+
+
+ the @proxy's URI, or %NULL if unknown
+
+
+
+
+ a #GProxyAddress
+
+
+
+
+
+ Gets @proxy's username.
+
+
+ the @proxy's username
+
+
+
+
+ a #GProxyAddress
+
+
+
+
+
+
+
+
+
+
+
+ The protocol being spoke to the destination host, or %NULL if
+the #GProxyAddress doesn't know.
+
+
+
+
+
+
+
+
+
+ The URI string that the proxy was constructed from (or %NULL
+if the creator didn't specify this).
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Class structure for #GProxyAddress.
+
+
+
+
+
+
+ #GProxyAddressEnumerator is a wrapper around #GSocketAddressEnumerator which
+takes the #GSocketAddress instances returned by the #GSocketAddressEnumerator
+and wraps them in #GProxyAddress instances, using the given
+#GProxyAddressEnumerator:proxy-resolver.
+
+This enumerator will be returned (for example, by
+g_socket_connectable_enumerate()) as appropriate when a proxy is configured;
+there should be no need to manually wrap a #GSocketAddressEnumerator instance
+with one.
+
+
+
+
+
+ The default port to use if #GProxyAddressEnumerator:uri does not
+specify one.
+
+
+
+ The proxy resolver to use.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Class structure for #GProxyAddressEnumerator.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Provides an interface for handling proxy connection and payload.
+
+
+ The parent interface.
+
+
+
+
+
+
+ a #GIOStream that will replace @connection. This might
+ be the same as @connection, in which case a reference
+ will be added.
+
+
+
+
+ a #GProxy
+
+
+
+ a #GIOStream
+
+
+
+ a #GProxyAddress
+
+
+
+ a #GCancellable
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GProxy
+
+
+
+ a #GIOStream
+
+
+
+ a #GProxyAddress
+
+
+
+ a #GCancellable
+
+
+
+ a #GAsyncReadyCallback
+
+
+
+ callback data
+
+
+
+
+
+
+
+
+
+ a #GIOStream.
+
+
+
+
+ a #GProxy
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+ %TRUE if hostname resolution is supported.
+
+
+
+
+ a #GProxy
+
+
+
+
+
+
+
+ #GProxyResolver provides synchronous and asynchronous network proxy
+resolution. #GProxyResolver is used within #GSocketClient through
+the method g_socket_connectable_proxy_enumerate().
+
+Implementations of #GProxyResolver based on libproxy and GNOME settings can
+be found in glib-networking. GIO comes with an implementation for use inside
+Flatpak portals.
+
+
+ Gets the default #GProxyResolver for the system.
+
+
+ the default #GProxyResolver, which
+ will be a dummy object if no proxy resolver is available
+
+
+
+
+ Checks if @resolver can be used on this system. (This is used
+internally; g_proxy_resolver_get_default() will only return a proxy
+resolver that returns %TRUE for this method.)
+
+
+ %TRUE if @resolver is supported.
+
+
+
+
+ a #GProxyResolver
+
+
+
+
+
+ Looks into the system proxy configuration to determine what proxy,
+if any, to use to connect to @uri. The returned proxy URIs are of
+the form `<protocol>://[user[:password]@]host[:port]` or
+`direct://`, where <protocol> could be http, rtsp, socks
+or other proxying protocol.
+
+If you don't know what network protocol is being used on the
+socket, you should use `none` as the URI protocol.
+In this case, the resolver might still return a generic proxy type
+(such as SOCKS), but would not return protocol-specific proxy types
+(such as http).
+
+`direct://` is used when no proxy is needed.
+Direct connection should not be attempted unless it is part of the
+returned array of proxies.
+
+
+ A
+ NULL-terminated array of proxy URIs. Must be freed
+ with g_strfreev().
+
+
+
+
+
+
+ a #GProxyResolver
+
+
+
+ a URI representing the destination to connect to
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Asynchronous lookup of proxy. See g_proxy_resolver_lookup() for more
+details.
+
+
+
+
+
+
+ a #GProxyResolver
+
+
+
+ a URI representing the destination to connect to
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call after resolution completes
+
+
+
+ data for @callback
+
+
+
+
+
+ Call this function to obtain the array of proxy URIs when
+g_proxy_resolver_lookup_async() is complete. See
+g_proxy_resolver_lookup() for more details.
+
+
+ A
+ NULL-terminated array of proxy URIs. Must be freed
+ with g_strfreev().
+
+
+
+
+
+
+ a #GProxyResolver
+
+
+
+ the result passed to your #GAsyncReadyCallback
+
+
+
+
+
+ Checks if @resolver can be used on this system. (This is used
+internally; g_proxy_resolver_get_default() will only return a proxy
+resolver that returns %TRUE for this method.)
+
+
+ %TRUE if @resolver is supported.
+
+
+
+
+ a #GProxyResolver
+
+
+
+
+
+ Looks into the system proxy configuration to determine what proxy,
+if any, to use to connect to @uri. The returned proxy URIs are of
+the form `<protocol>://[user[:password]@]host[:port]` or
+`direct://`, where <protocol> could be http, rtsp, socks
+or other proxying protocol.
+
+If you don't know what network protocol is being used on the
+socket, you should use `none` as the URI protocol.
+In this case, the resolver might still return a generic proxy type
+(such as SOCKS), but would not return protocol-specific proxy types
+(such as http).
+
+`direct://` is used when no proxy is needed.
+Direct connection should not be attempted unless it is part of the
+returned array of proxies.
+
+
+ A
+ NULL-terminated array of proxy URIs. Must be freed
+ with g_strfreev().
+
+
+
+
+
+
+ a #GProxyResolver
+
+
+
+ a URI representing the destination to connect to
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Asynchronous lookup of proxy. See g_proxy_resolver_lookup() for more
+details.
+
+
+
+
+
+
+ a #GProxyResolver
+
+
+
+ a URI representing the destination to connect to
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call after resolution completes
+
+
+
+ data for @callback
+
+
+
+
+
+ Call this function to obtain the array of proxy URIs when
+g_proxy_resolver_lookup_async() is complete. See
+g_proxy_resolver_lookup() for more details.
+
+
+ A
+ NULL-terminated array of proxy URIs. Must be freed
+ with g_strfreev().
+
+
+
+
+
+
+ a #GProxyResolver
+
+
+
+ the result passed to your #GAsyncReadyCallback
+
+
+
+
+
+
+ The virtual function table for #GProxyResolver.
+
+
+ The parent interface.
+
+
+
+
+
+
+ %TRUE if @resolver is supported.
+
+
+
+
+ a #GProxyResolver
+
+
+
+
+
+
+
+
+
+ A
+ NULL-terminated array of proxy URIs. Must be freed
+ with g_strfreev().
+
+
+
+
+
+
+ a #GProxyResolver
+
+
+
+ a URI representing the destination to connect to
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GProxyResolver
+
+
+
+ a URI representing the destination to connect to
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call after resolution completes
+
+
+
+ data for @callback
+
+
+
+
+
+
+
+
+
+ A
+ NULL-terminated array of proxy URIs. Must be freed
+ with g_strfreev().
+
+
+
+
+
+
+ a #GProxyResolver
+
+
+
+ the result passed to your #GAsyncReadyCallback
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Changes the size of the memory block pointed to by @data to
+@size bytes.
+
+The function should have the same semantics as realloc().
+
+
+ a pointer to the reallocated memory
+
+
+
+
+ memory block to reallocate
+
+
+
+ size to reallocate @data to
+
+
+
+
+
+ The GRemoteActionGroup interface is implemented by #GActionGroup
+instances that either transmit action invocations to other processes
+or receive action invocations in the local process from other
+processes.
+
+The interface has `_full` variants of the two
+methods on #GActionGroup used to activate actions:
+g_action_group_activate_action() and
+g_action_group_change_action_state(). These variants allow a
+"platform data" #GVariant to be specified: a dictionary providing
+context for the action invocation (for example: timestamps, startup
+notification IDs, etc).
+
+#GDBusActionGroup implements #GRemoteActionGroup. This provides a
+mechanism to send platform data for action invocations over D-Bus.
+
+Additionally, g_dbus_connection_export_action_group() will check if
+the exported #GActionGroup implements #GRemoteActionGroup and use the
+`_full` variants of the calls if available. This
+provides a mechanism by which to receive platform data for action
+invocations that arrive by way of D-Bus.
+
+
+
+ Activates the remote action.
+
+This is the same as g_action_group_activate_action() except that it
+allows for provision of "platform data" to be sent along with the
+activation request. This typically contains details such as the user
+interaction timestamp or startup notification information.
+
+@platform_data must be non-%NULL and must have the type
+%G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed.
+
+
+
+
+
+
+ a #GDBusActionGroup
+
+
+
+ the name of the action to activate
+
+
+
+ the optional parameter to the activation
+
+
+
+ the platform data to send
+
+
+
+
+
+ Changes the state of a remote action.
+
+This is the same as g_action_group_change_action_state() except that
+it allows for provision of "platform data" to be sent along with the
+state change request. This typically contains details such as the
+user interaction timestamp or startup notification information.
+
+@platform_data must be non-%NULL and must have the type
+%G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed.
+
+
+
+
+
+
+ a #GRemoteActionGroup
+
+
+
+ the name of the action to change the state of
+
+
+
+ the new requested value for the state
+
+
+
+ the platform data to send
+
+
+
+
+
+ Activates the remote action.
+
+This is the same as g_action_group_activate_action() except that it
+allows for provision of "platform data" to be sent along with the
+activation request. This typically contains details such as the user
+interaction timestamp or startup notification information.
+
+@platform_data must be non-%NULL and must have the type
+%G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed.
+
+
+
+
+
+
+ a #GDBusActionGroup
+
+
+
+ the name of the action to activate
+
+
+
+ the optional parameter to the activation
+
+
+
+ the platform data to send
+
+
+
+
+
+ Changes the state of a remote action.
+
+This is the same as g_action_group_change_action_state() except that
+it allows for provision of "platform data" to be sent along with the
+state change request. This typically contains details such as the
+user interaction timestamp or startup notification information.
+
+@platform_data must be non-%NULL and must have the type
+%G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed.
+
+
+
+
+
+
+ a #GRemoteActionGroup
+
+
+
+ the name of the action to change the state of
+
+
+
+ the new requested value for the state
+
+
+
+ the platform data to send
+
+
+
+
+
+
+ The virtual function table for #GRemoteActionGroup.
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GDBusActionGroup
+
+
+
+ the name of the action to activate
+
+
+
+ the optional parameter to the activation
+
+
+
+ the platform data to send
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GRemoteActionGroup
+
+
+
+ the name of the action to change the state of
+
+
+
+ the new requested value for the state
+
+
+
+ the platform data to send
+
+
+
+
+
+
+
+ #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.
+
+
+ Frees @addresses (which should be the return value from
+g_resolver_lookup_by_name() or g_resolver_lookup_by_name_finish()).
+(This is a convenience method; you can also simply free the results
+by hand.)
+
+
+
+
+
+
+ a #GList of #GInetAddress
+
+
+
+
+
+
+
+ Frees @targets (which should be the return value from
+g_resolver_lookup_service() or g_resolver_lookup_service_finish()).
+(This is a convenience method; you can also simply free the
+results by hand.)
+
+
+
+
+
+
+ a #GList of #GSrvTarget
+
+
+
+
+
+
+
+ Gets the default #GResolver. You should unref it when you are done
+with it. #GResolver may use its reference count as a hint about how
+many threads it should allocate for concurrent DNS resolutions.
+
+
+ the default #GResolver.
+
+
+
+
+ Synchronously reverse-resolves @address to determine its
+associated hostname.
+
+If the DNS resolution fails, @error (if non-%NULL) will be set to
+a value from #GResolverError.
+
+If @cancellable is non-%NULL, it can be used to cancel the
+operation, in which case @error (if non-%NULL) will be set to
+%G_IO_ERROR_CANCELLED.
+
+
+ a hostname (either ASCII-only, or in ASCII-encoded
+ form), or %NULL on error.
+
+
+
+
+ a #GResolver
+
+
+
+ the address to reverse-resolve
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Begins asynchronously reverse-resolving @address to determine its
+associated hostname, and eventually calls @callback, which must
+call g_resolver_lookup_by_address_finish() to get the final result.
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the address to reverse-resolve
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call after resolution completes
+
+
+
+ data for @callback
+
+
+
+
+
+ Retrieves the result of a previous call to
+g_resolver_lookup_by_address_async().
+
+If the DNS resolution failed, @error (if non-%NULL) will be set to
+a value from #GResolverError. If the operation was cancelled,
+@error will be set to %G_IO_ERROR_CANCELLED.
+
+
+ a hostname (either ASCII-only, or in ASCII-encoded
+form), or %NULL on error.
+
+
+
+
+ a #GResolver
+
+
+
+ the result passed to your #GAsyncReadyCallback
+
+
+
+
+
+ Synchronously resolves @hostname to determine its associated IP
+address(es). @hostname may be an ASCII-only or UTF-8 hostname, or
+the textual form of an IP address (in which case this just becomes
+a wrapper around g_inet_address_new_from_string()).
+
+On success, g_resolver_lookup_by_name() will return a non-empty #GList of
+#GInetAddress, sorted in order of preference and guaranteed to not
+contain duplicates. That is, if using the result to connect to
+@hostname, you should attempt to connect to the first address
+first, then the second if the first fails, etc. If you are using
+the result to listen on a socket, it is appropriate to add each
+result using e.g. g_socket_listener_add_address().
+
+If the DNS resolution fails, @error (if non-%NULL) will be set to a
+value from #GResolverError and %NULL will be returned.
+
+If @cancellable is non-%NULL, it can be used to cancel the
+operation, in which case @error (if non-%NULL) will be set to
+%G_IO_ERROR_CANCELLED.
+
+If you are planning to connect to a socket on the resolved IP
+address, it may be easier to create a #GNetworkAddress and use its
+#GSocketConnectable interface.
+
+
+ a non-empty #GList
+of #GInetAddress, or %NULL on error. You
+must unref each of the addresses and free the list when you are
+done with it. (You can use g_resolver_free_addresses() to do this.)
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the hostname to look up
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Begins asynchronously resolving @hostname to determine its
+associated IP address(es), and eventually calls @callback, which
+must call g_resolver_lookup_by_name_finish() to get the result.
+See g_resolver_lookup_by_name() for more details.
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the hostname to look up the address of
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call after resolution completes
+
+
+
+ data for @callback
+
+
+
+
+
+ Retrieves the result of a call to
+g_resolver_lookup_by_name_async().
+
+If the DNS resolution failed, @error (if non-%NULL) will be set to
+a value from #GResolverError. If the operation was cancelled,
+@error will be set to %G_IO_ERROR_CANCELLED.
+
+
+ a #GList
+of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name()
+for more details.
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the result passed to your #GAsyncReadyCallback
+
+
+
+
+
+ This differs from g_resolver_lookup_by_name() in that you can modify
+the lookup behavior with @flags. For example this can be used to limit
+results with %G_RESOLVER_NAME_LOOKUP_FLAGS_IPV4_ONLY.
+
+
+ a non-empty #GList
+of #GInetAddress, or %NULL on error. You
+must unref each of the addresses and free the list when you are
+done with it. (You can use g_resolver_free_addresses() to do this.)
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the hostname to look up
+
+
+
+ extra #GResolverNameLookupFlags for the lookup
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Begins asynchronously resolving @hostname to determine its
+associated IP address(es), and eventually calls @callback, which
+must call g_resolver_lookup_by_name_with_flags_finish() to get the result.
+See g_resolver_lookup_by_name() for more details.
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the hostname to look up the address of
+
+
+
+ extra #GResolverNameLookupFlags for the lookup
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call after resolution completes
+
+
+
+ data for @callback
+
+
+
+
+
+ Retrieves the result of a call to
+g_resolver_lookup_by_name_with_flags_async().
+
+If the DNS resolution failed, @error (if non-%NULL) will be set to
+a value from #GResolverError. If the operation was cancelled,
+@error will be set to %G_IO_ERROR_CANCELLED.
+
+
+ a #GList
+of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name()
+for more details.
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the result passed to your #GAsyncReadyCallback
+
+
+
+
+
+ Synchronously performs a DNS record lookup for the given @rrname and returns
+a list of records as #GVariant tuples. See #GResolverRecordType for
+information on what the records contain for each @record_type.
+
+If the DNS resolution fails, @error (if non-%NULL) will be set to
+a value from #GResolverError and %NULL will be returned.
+
+If @cancellable is non-%NULL, it can be used to cancel the
+operation, in which case @error (if non-%NULL) will be set to
+%G_IO_ERROR_CANCELLED.
+
+
+ a non-empty #GList of
+#GVariant, or %NULL on error. You must free each of the records and the list
+when you are done with it. (You can use g_list_free_full() with
+g_variant_unref() to do this.)
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the DNS name to look up the record for
+
+
+
+ the type of DNS record to look up
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Begins asynchronously performing a DNS lookup for the given
+@rrname, and eventually calls @callback, which must call
+g_resolver_lookup_records_finish() to get the final result. See
+g_resolver_lookup_records() for more details.
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the DNS name to look up the record for
+
+
+
+ the type of DNS record to look up
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call after resolution completes
+
+
+
+ data for @callback
+
+
+
+
+
+ Retrieves the result of a previous call to
+g_resolver_lookup_records_async(). Returns a non-empty list of records as
+#GVariant tuples. See #GResolverRecordType for information on what the
+records contain.
+
+If the DNS resolution failed, @error (if non-%NULL) will be set to
+a value from #GResolverError. If the operation was cancelled,
+@error will be set to %G_IO_ERROR_CANCELLED.
+
+
+ a non-empty #GList of
+#GVariant, or %NULL on error. You must free each of the records and the list
+when you are done with it. (You can use g_list_free_full() with
+g_variant_unref() to do this.)
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the result passed to your #GAsyncReadyCallback
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Retrieves the result of a previous call to
+g_resolver_lookup_service_async().
+
+If the DNS resolution failed, @error (if non-%NULL) will be set to
+a value from #GResolverError. If the operation was cancelled,
+@error will be set to %G_IO_ERROR_CANCELLED.
+
+
+ a non-empty #GList of
+#GSrvTarget, or %NULL on error. See g_resolver_lookup_service() for more
+details.
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the result passed to your #GAsyncReadyCallback
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Synchronously reverse-resolves @address to determine its
+associated hostname.
+
+If the DNS resolution fails, @error (if non-%NULL) will be set to
+a value from #GResolverError.
+
+If @cancellable is non-%NULL, it can be used to cancel the
+operation, in which case @error (if non-%NULL) will be set to
+%G_IO_ERROR_CANCELLED.
+
+
+ a hostname (either ASCII-only, or in ASCII-encoded
+ form), or %NULL on error.
+
+
+
+
+ a #GResolver
+
+
+
+ the address to reverse-resolve
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Begins asynchronously reverse-resolving @address to determine its
+associated hostname, and eventually calls @callback, which must
+call g_resolver_lookup_by_address_finish() to get the final result.
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the address to reverse-resolve
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call after resolution completes
+
+
+
+ data for @callback
+
+
+
+
+
+ Retrieves the result of a previous call to
+g_resolver_lookup_by_address_async().
+
+If the DNS resolution failed, @error (if non-%NULL) will be set to
+a value from #GResolverError. If the operation was cancelled,
+@error will be set to %G_IO_ERROR_CANCELLED.
+
+
+ a hostname (either ASCII-only, or in ASCII-encoded
+form), or %NULL on error.
+
+
+
+
+ a #GResolver
+
+
+
+ the result passed to your #GAsyncReadyCallback
+
+
+
+
+
+ Synchronously resolves @hostname to determine its associated IP
+address(es). @hostname may be an ASCII-only or UTF-8 hostname, or
+the textual form of an IP address (in which case this just becomes
+a wrapper around g_inet_address_new_from_string()).
+
+On success, g_resolver_lookup_by_name() will return a non-empty #GList of
+#GInetAddress, sorted in order of preference and guaranteed to not
+contain duplicates. That is, if using the result to connect to
+@hostname, you should attempt to connect to the first address
+first, then the second if the first fails, etc. If you are using
+the result to listen on a socket, it is appropriate to add each
+result using e.g. g_socket_listener_add_address().
+
+If the DNS resolution fails, @error (if non-%NULL) will be set to a
+value from #GResolverError and %NULL will be returned.
+
+If @cancellable is non-%NULL, it can be used to cancel the
+operation, in which case @error (if non-%NULL) will be set to
+%G_IO_ERROR_CANCELLED.
+
+If you are planning to connect to a socket on the resolved IP
+address, it may be easier to create a #GNetworkAddress and use its
+#GSocketConnectable interface.
+
+
+ a non-empty #GList
+of #GInetAddress, or %NULL on error. You
+must unref each of the addresses and free the list when you are
+done with it. (You can use g_resolver_free_addresses() to do this.)
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the hostname to look up
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Begins asynchronously resolving @hostname to determine its
+associated IP address(es), and eventually calls @callback, which
+must call g_resolver_lookup_by_name_finish() to get the result.
+See g_resolver_lookup_by_name() for more details.
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the hostname to look up the address of
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call after resolution completes
+
+
+
+ data for @callback
+
+
+
+
+
+ Retrieves the result of a call to
+g_resolver_lookup_by_name_async().
+
+If the DNS resolution failed, @error (if non-%NULL) will be set to
+a value from #GResolverError. If the operation was cancelled,
+@error will be set to %G_IO_ERROR_CANCELLED.
+
+
+ a #GList
+of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name()
+for more details.
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the result passed to your #GAsyncReadyCallback
+
+
+
+
+
+ This differs from g_resolver_lookup_by_name() in that you can modify
+the lookup behavior with @flags. For example this can be used to limit
+results with %G_RESOLVER_NAME_LOOKUP_FLAGS_IPV4_ONLY.
+
+
+ a non-empty #GList
+of #GInetAddress, or %NULL on error. You
+must unref each of the addresses and free the list when you are
+done with it. (You can use g_resolver_free_addresses() to do this.)
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the hostname to look up
+
+
+
+ extra #GResolverNameLookupFlags for the lookup
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Begins asynchronously resolving @hostname to determine its
+associated IP address(es), and eventually calls @callback, which
+must call g_resolver_lookup_by_name_with_flags_finish() to get the result.
+See g_resolver_lookup_by_name() for more details.
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the hostname to look up the address of
+
+
+
+ extra #GResolverNameLookupFlags for the lookup
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call after resolution completes
+
+
+
+ data for @callback
+
+
+
+
+
+ Retrieves the result of a call to
+g_resolver_lookup_by_name_with_flags_async().
+
+If the DNS resolution failed, @error (if non-%NULL) will be set to
+a value from #GResolverError. If the operation was cancelled,
+@error will be set to %G_IO_ERROR_CANCELLED.
+
+
+ a #GList
+of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name()
+for more details.
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the result passed to your #GAsyncReadyCallback
+
+
+
+
+
+ Synchronously performs a DNS record lookup for the given @rrname and returns
+a list of records as #GVariant tuples. See #GResolverRecordType for
+information on what the records contain for each @record_type.
+
+If the DNS resolution fails, @error (if non-%NULL) will be set to
+a value from #GResolverError and %NULL will be returned.
+
+If @cancellable is non-%NULL, it can be used to cancel the
+operation, in which case @error (if non-%NULL) will be set to
+%G_IO_ERROR_CANCELLED.
+
+
+ a non-empty #GList of
+#GVariant, or %NULL on error. You must free each of the records and the list
+when you are done with it. (You can use g_list_free_full() with
+g_variant_unref() to do this.)
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the DNS name to look up the record for
+
+
+
+ the type of DNS record to look up
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Begins asynchronously performing a DNS lookup for the given
+@rrname, and eventually calls @callback, which must call
+g_resolver_lookup_records_finish() to get the final result. See
+g_resolver_lookup_records() for more details.
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the DNS name to look up the record for
+
+
+
+ the type of DNS record to look up
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call after resolution completes
+
+
+
+ data for @callback
+
+
+
+
+
+ Retrieves the result of a previous call to
+g_resolver_lookup_records_async(). Returns a non-empty list of records as
+#GVariant tuples. See #GResolverRecordType for information on what the
+records contain.
+
+If the DNS resolution failed, @error (if non-%NULL) will be set to
+a value from #GResolverError. If the operation was cancelled,
+@error will be set to %G_IO_ERROR_CANCELLED.
+
+
+ a non-empty #GList of
+#GVariant, or %NULL on error. You must free each of the records and the list
+when you are done with it. (You can use g_list_free_full() with
+g_variant_unref() to do this.)
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the result passed to your #GAsyncReadyCallback
+
+
+
+
+
+ Synchronously performs a DNS SRV lookup for the given @service and
+@protocol in the given @domain and returns an array of #GSrvTarget.
+@domain may be an ASCII-only or UTF-8 hostname. Note also that the
+@service and @protocol arguments do not include the leading underscore
+that appears in the actual DNS entry.
+
+On success, g_resolver_lookup_service() will return a non-empty #GList of
+#GSrvTarget, sorted in order of preference. (That is, you should
+attempt to connect to the first target first, then the second if
+the first fails, etc.)
+
+If the DNS resolution fails, @error (if non-%NULL) will be set to
+a value from #GResolverError and %NULL will be returned.
+
+If @cancellable is non-%NULL, it can be used to cancel the
+operation, in which case @error (if non-%NULL) will be set to
+%G_IO_ERROR_CANCELLED.
+
+If you are planning to connect to the service, it is usually easier
+to create a #GNetworkService and use its #GSocketConnectable
+interface.
+
+
+ a non-empty #GList of
+#GSrvTarget, or %NULL on error. You must free each of the targets and the
+list when you are done with it. (You can use g_resolver_free_targets() to do
+this.)
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the service type to look up (eg, "ldap")
+
+
+
+ the networking protocol to use for @service (eg, "tcp")
+
+
+
+ the DNS domain to look up the service in
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Begins asynchronously performing a DNS SRV lookup for the given
+@service and @protocol in the given @domain, and eventually calls
+@callback, which must call g_resolver_lookup_service_finish() to
+get the final result. See g_resolver_lookup_service() for more
+details.
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the service type to look up (eg, "ldap")
+
+
+
+ the networking protocol to use for @service (eg, "tcp")
+
+
+
+ the DNS domain to look up the service in
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call after resolution completes
+
+
+
+ data for @callback
+
+
+
+
+
+ Retrieves the result of a previous call to
+g_resolver_lookup_service_async().
+
+If the DNS resolution failed, @error (if non-%NULL) will be set to
+a value from #GResolverError. If the operation was cancelled,
+@error will be set to %G_IO_ERROR_CANCELLED.
+
+
+ a non-empty #GList of
+#GSrvTarget, or %NULL on error. See g_resolver_lookup_service() for more
+details.
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the result passed to your #GAsyncReadyCallback
+
+
+
+
+
+ Sets @resolver to be the application's default resolver (reffing
+@resolver, and unreffing the previous default resolver, if any).
+Future calls to g_resolver_get_default() will return this resolver.
+
+This can be used if an application wants to perform any sort of DNS
+caching or "pinning"; it can implement its own #GResolver that
+calls the original default resolver for DNS operations, and
+implements its own cache policies on top of that, and then set
+itself as the default resolver for all later code to use.
+
+
+
+
+
+
+ the new default #GResolver
+
+
+
+
+
+
+
+
+
+
+
+ Emitted when the resolver notices that the system resolver
+configuration has changed.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a non-empty #GList
+of #GInetAddress, or %NULL on error. You
+must unref each of the addresses and free the list when you are
+done with it. (You can use g_resolver_free_addresses() to do this.)
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the hostname to look up
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the hostname to look up the address of
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call after resolution completes
+
+
+
+ data for @callback
+
+
+
+
+
+
+
+
+
+ a #GList
+of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name()
+for more details.
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the result passed to your #GAsyncReadyCallback
+
+
+
+
+
+
+
+
+
+ a hostname (either ASCII-only, or in ASCII-encoded
+ form), or %NULL on error.
+
+
+
+
+ a #GResolver
+
+
+
+ the address to reverse-resolve
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the address to reverse-resolve
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call after resolution completes
+
+
+
+ data for @callback
+
+
+
+
+
+
+
+
+
+ a hostname (either ASCII-only, or in ASCII-encoded
+form), or %NULL on error.
+
+
+
+
+ a #GResolver
+
+
+
+ the result passed to your #GAsyncReadyCallback
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a non-empty #GList of
+#GSrvTarget, or %NULL on error. See g_resolver_lookup_service() for more
+details.
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the result passed to your #GAsyncReadyCallback
+
+
+
+
+
+
+
+
+
+ a non-empty #GList of
+#GVariant, or %NULL on error. You must free each of the records and the list
+when you are done with it. (You can use g_list_free_full() with
+g_variant_unref() to do this.)
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the DNS name to look up the record for
+
+
+
+ the type of DNS record to look up
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the DNS name to look up the record for
+
+
+
+ the type of DNS record to look up
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call after resolution completes
+
+
+
+ data for @callback
+
+
+
+
+
+
+
+
+
+ a non-empty #GList of
+#GVariant, or %NULL on error. You must free each of the records and the list
+when you are done with it. (You can use g_list_free_full() with
+g_variant_unref() to do this.)
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the result passed to your #GAsyncReadyCallback
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the hostname to look up the address of
+
+
+
+ extra #GResolverNameLookupFlags for the lookup
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call after resolution completes
+
+
+
+ data for @callback
+
+
+
+
+
+
+
+
+
+ a #GList
+of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name()
+for more details.
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the result passed to your #GAsyncReadyCallback
+
+
+
+
+
+
+
+
+
+ a non-empty #GList
+of #GInetAddress, or %NULL on error. You
+must unref each of the addresses and free the list when you are
+done with it. (You can use g_resolver_free_addresses() to do this.)
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the hostname to look up
+
+
+
+ extra #GResolverNameLookupFlags for the lookup
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+
+
+ An error code used with %G_RESOLVER_ERROR in a #GError returned
+from a #GResolver routine.
+
+ the requested name/address/service was not
+ found
+
+
+ the requested information could not
+ be looked up due to a network error or similar problem
+
+
+ unknown error
+
+
+ Gets the #GResolver Error Quark.
+
+ a #GQuark.
+
+
+
+
+
+ Flags to modify lookup behavior.
+
+ default behavior (same as g_resolver_lookup_by_name())
+
+
+ only resolve ipv4 addresses
+
+
+ only resolve ipv6 addresses
+
+
+
+
+
+
+ The type of record that g_resolver_lookup_records() or
+g_resolver_lookup_records_async() should retrieve. The records are returned
+as lists of #GVariant tuples. Each record type has different values in
+the variant tuples returned.
+
+%G_RESOLVER_RECORD_SRV records are returned as variants with the signature
+`(qqqs)`, containing a `guint16` with the priority, a `guint16` with the
+weight, a `guint16` with the port, and a string of the hostname.
+
+%G_RESOLVER_RECORD_MX records are returned as variants with the signature
+`(qs)`, representing a `guint16` with the preference, and a string containing
+the mail exchanger hostname.
+
+%G_RESOLVER_RECORD_TXT records are returned as variants with the signature
+`(as)`, representing an array of the strings in the text record. Note: Most TXT
+records only contain a single string, but
+[RFC 1035](https://tools.ietf.org/html/rfc1035#section-3.3.14) does allow a
+record to contain multiple strings. The RFC which defines the interpretation
+of a specific TXT record will likely require concatenation of multiple
+strings if they are present, as with
+[RFC 7208](https://tools.ietf.org/html/rfc7208#section-3.3).
+
+%G_RESOLVER_RECORD_SOA records are returned as variants with the signature
+`(ssuuuuu)`, representing a string containing the primary name server, a
+string containing the administrator, the serial as a `guint32`, the refresh
+interval as a `guint32`, the retry interval as a `guint32`, the expire timeout
+as a `guint32`, and the TTL as a `guint32`.
+
+%G_RESOLVER_RECORD_NS records are returned as variants with the signature
+`(s)`, representing a string of the hostname of the name server.
+
+ look up DNS SRV records for a domain
+
+
+ look up DNS MX records for a domain
+
+
+ look up DNS TXT records for a name
+
+
+ look up DNS SOA records for a zone
+
+
+ look up DNS NS records for a domain
+
+
+
+ Applications and libraries often contain binary or textual data that is
+really part of the application, rather than user data. For instance
+#GtkBuilder .ui files, splashscreen images, GMenu markup XML, CSS files,
+icons, etc. These are often shipped as files in `$datadir/appname`, or
+manually included as literal strings in the code.
+
+The #GResource API and the [glib-compile-resources][glib-compile-resources] program
+provide a convenient and efficient alternative to this which has some nice properties. You
+maintain the files as normal files, so its easy to edit them, but during the build the files
+are combined into a binary bundle that is linked into the executable. This means that loading
+the resource files are efficient (as they are already in memory, shared with other instances) and
+simple (no need to check for things like I/O errors or locate the files in the filesystem). It
+also makes it easier to create relocatable applications.
+
+Resource files can also be marked as compressed. Such files will be included in the resource bundle
+in a compressed form, but will be automatically uncompressed when the resource is used. This
+is very useful e.g. for larger text files that are parsed once (or rarely) and then thrown away.
+
+Resource files can also be marked to be preprocessed, by setting the value of the
+`preprocess` attribute to a comma-separated list of preprocessing options.
+The only options currently supported are:
+
+`xml-stripblanks` which will use the xmllint command
+to strip ignorable whitespace from the XML file. For this to work,
+the `XMLLINT` environment variable must be set to the full path to
+the xmllint executable, or xmllint must be in the `PATH`; otherwise
+the preprocessing step is skipped.
+
+`to-pixdata` (deprecated since gdk-pixbuf 2.32) which will use the
+`gdk-pixbuf-pixdata` command to convert images to the #GdkPixdata format,
+which allows you to create pixbufs directly using the data inside the
+resource file, rather than an (uncompressed) copy of it. For this, the
+`gdk-pixbuf-pixdata` program must be in the `PATH`, or the
+`GDK_PIXBUF_PIXDATA` environment variable must be set to the full path to the
+`gdk-pixbuf-pixdata` executable; otherwise the resource compiler will abort.
+`to-pixdata` has been deprecated since gdk-pixbuf 2.32, as #GResource
+supports embedding modern image formats just as well. Instead of using it,
+embed a PNG or SVG file in your #GResource.
+
+`json-stripblanks` which will use the `json-glib-format` command to strip
+ignorable whitespace from the JSON file. For this to work, the
+`JSON_GLIB_FORMAT` environment variable must be set to the full path to the
+`json-glib-format` executable, or it must be in the `PATH`;
+otherwise the preprocessing step is skipped. In addition, at least version
+1.6 of `json-glib-format` is required.
+
+Resource files will be exported in the GResource namespace using the
+combination of the given `prefix` and the filename from the `file` element.
+The `alias` attribute can be used to alter the filename to expose them at a
+different location in the resource namespace. Typically, this is used to
+include files from a different source directory without exposing the source
+directory in the resource namespace, as in the example below.
+
+Resource bundles are created by the [glib-compile-resources][glib-compile-resources] program
+which takes an XML file that describes the bundle, and a set of files that the XML references. These
+are combined into a binary resource bundle.
+
+An example resource description:
+|[
+<?xml version="1.0" encoding="UTF-8"?>
+<gresources>
+ <gresource prefix="/org/gtk/Example">
+ <file>data/splashscreen.png</file>
+ <file compressed="true">dialog.ui</file>
+ <file preprocess="xml-stripblanks">menumarkup.xml</file>
+ <file alias="example.css">data/example.css</file>
+ </gresource>
+</gresources>
+]|
+
+This will create a resource bundle with the following files:
+|[
+/org/gtk/Example/data/splashscreen.png
+/org/gtk/Example/dialog.ui
+/org/gtk/Example/menumarkup.xml
+/org/gtk/Example/example.css
+]|
+
+Note that all resources in the process share the same namespace, so use Java-style
+path prefixes (like in the above example) to avoid conflicts.
+
+You can then use [glib-compile-resources][glib-compile-resources] to compile the XML to a
+binary bundle that you can load with g_resource_load(). However, its more common to use the --generate-source and
+--generate-header arguments to create a source file and header to link directly into your application.
+This will generate `get_resource()`, `register_resource()` and
+`unregister_resource()` functions, prefixed by the `--c-name` argument passed
+to [glib-compile-resources][glib-compile-resources]. `get_resource()` returns
+the generated #GResource object. The register and unregister functions
+register the resource so its files can be accessed using
+g_resources_lookup_data().
+
+Once a #GResource has been created and registered all the data in it can be accessed globally in the process by
+using API calls like g_resources_open_stream() to stream the data or g_resources_lookup_data() to get a direct pointer
+to the data. You can also use URIs like "resource:///org/gtk/Example/data/splashscreen.png" with #GFile to access
+the resource data.
+
+Some higher-level APIs, such as #GtkApplication, will automatically load
+resources from certain well-known paths in the resource namespace as a
+convenience. See the documentation for those APIs for details.
+
+There are two forms of the generated source, the default version uses the compiler support for constructor
+and destructor functions (where available) to automatically create and register the #GResource on startup
+or library load time. If you pass `--manual-register`, two functions to register/unregister the resource are created
+instead. This requires an explicit initialization call in your application/library, but it works on all platforms,
+even on the minor ones where constructors are not supported. (Constructor support is available for at least Win32, Mac OS and Linux.)
+
+Note that resource data can point directly into the data segment of e.g. a library, so if you are unloading libraries
+during runtime you need to be very careful with keeping around pointers to data from a resource, as this goes away
+when the library is unloaded. However, in practice this is not generally a problem, since most resource accesses
+are for your own resources, and resource data is often used once, during parsing, and then released.
+
+When debugging a program or testing a change to an installed version, it is often useful to be able to
+replace resources in the program or library, without recompiling, for debugging or quick hacking and testing
+purposes. Since GLib 2.50, it is possible to use the `G_RESOURCE_OVERLAYS` environment variable to selectively overlay
+resources with replacements from the filesystem. It is a %G_SEARCHPATH_SEPARATOR-separated list of substitutions to perform
+during resource lookups. It is ignored when running in a setuid process.
+
+A substitution has the form
+
+|[
+ /org/gtk/libgtk=/home/desrt/gtk-overlay
+]|
+
+The part before the `=` is the resource subpath for which the overlay applies. The part after is a
+filesystem path which contains files and subdirectories as you would like to be loaded as resources with the
+equivalent names.
+
+In the example above, if an application tried to load a resource with the resource path
+`/org/gtk/libgtk/ui/gtkdialog.ui` then GResource would check the filesystem path
+`/home/desrt/gtk-overlay/ui/gtkdialog.ui`. If a file was found there, it would be used instead. This is an
+overlay, not an outright replacement, which means that if a file is not found at that path, the built-in
+version will be used instead. Whiteouts are not currently supported.
+
+Substitutions must start with a slash, and must not contain a trailing slash before the '='. The path after
+the slash should ideally be absolute, but this is not strictly required. It is possible to overlay the
+location of a single resource with an individual file.
+
+
+ Creates a GResource from a reference to the binary resource bundle.
+This will keep a reference to @data while the resource lives, so
+the data should not be modified or freed.
+
+If you want to use this resource in the global resource namespace you need
+to register it with g_resources_register().
+
+Note: @data must be backed by memory that is at least pointer aligned.
+Otherwise this function will internally create a copy of the memory since
+GLib 2.56, or in older versions fail and exit the process.
+
+If @data is empty or corrupt, %G_RESOURCE_ERROR_INTERNAL will be returned.
+
+
+ a new #GResource, or %NULL on error
+
+
+
+
+ A #GBytes
+
+
+
+
+
+ Registers the resource with the process-global set of resources.
+Once a resource is registered the files in it can be accessed
+with the global resource lookup functions like g_resources_lookup_data().
+
+
+
+
+
+
+ A #GResource
+
+
+
+
+
+ Unregisters the resource from the process-global set of resources.
+
+
+
+
+
+
+ A #GResource
+
+
+
+
+
+ Returns all the names of children at the specified @path in the resource.
+The return result is a %NULL terminated list of strings which should
+be released with g_strfreev().
+
+If @path is invalid or does not exist in the #GResource,
+%G_RESOURCE_ERROR_NOT_FOUND will be returned.
+
+@lookup_flags controls the behaviour of the lookup.
+
+
+ an array of constant strings
+
+
+
+
+
+
+ A #GResource
+
+
+
+ A pathname inside the resource
+
+
+
+ A #GResourceLookupFlags
+
+
+
+
+
+ Looks for a file at the specified @path in the resource and
+if found returns information about it.
+
+@lookup_flags controls the behaviour of the lookup.
+
+
+ %TRUE if the file was found. %FALSE if there were errors
+
+
+
+
+ A #GResource
+
+
+
+ A pathname inside the resource
+
+
+
+ A #GResourceLookupFlags
+
+
+
+ a location to place the length of the contents of the file,
+ or %NULL if the length is not needed
+
+
+
+ a location to place the flags about the file,
+ or %NULL if the length is not needed
+
+
+
+
+
+ Looks for a file at the specified @path in the resource and
+returns a #GBytes that lets you directly access the data in
+memory.
+
+The data is always followed by a zero byte, so you
+can safely use the data as a C string. However, that byte
+is not included in the size of the GBytes.
+
+For uncompressed resource files this is a pointer directly into
+the resource bundle, which is typically in some readonly data section
+in the program binary. For compressed files we allocate memory on
+the heap and automatically uncompress the data.
+
+@lookup_flags controls the behaviour of the lookup.
+
+
+ #GBytes or %NULL on error.
+ Free the returned object with g_bytes_unref()
+
+
+
+
+ A #GResource
+
+
+
+ A pathname inside the resource
+
+
+
+ A #GResourceLookupFlags
+
+
+
+
+
+ Looks for a file at the specified @path in the resource and
+returns a #GInputStream that lets you read the data.
+
+@lookup_flags controls the behaviour of the lookup.
+
+
+ #GInputStream or %NULL on error.
+ Free the returned object with g_object_unref()
+
+
+
+
+ A #GResource
+
+
+
+ A pathname inside the resource
+
+
+
+ A #GResourceLookupFlags
+
+
+
+
+
+ Atomically increments the reference count of @resource by one. This
+function is MT-safe and may be called from any thread.
+
+
+ The passed in #GResource
+
+
+
+
+ A #GResource
+
+
+
+
+
+ Atomically decrements the reference count of @resource by one. If the
+reference count drops to 0, all memory allocated by the resource is
+released. This function is MT-safe and may be called from any
+thread.
+
+
+
+
+
+
+ A #GResource
+
+
+
+
+
+ Loads a binary resource bundle and creates a #GResource representation of it, allowing
+you to query it for data.
+
+If you want to use this resource in the global resource namespace you need
+to register it with g_resources_register().
+
+If @filename is empty or the data in it is corrupt,
+%G_RESOURCE_ERROR_INTERNAL will be returned. If @filename doesn’t exist, or
+there is an error in reading it, an error from g_mapped_file_new() will be
+returned.
+
+
+ a new #GResource, or %NULL on error
+
+
+
+
+ the path of a filename to load, in the GLib filename encoding
+
+
+
+
+
+
+ An error code used with %G_RESOURCE_ERROR in a #GError returned
+from a #GResource routine.
+
+ no file was found at the requested path
+
+
+ unknown error
+
+
+ Gets the #GResource Error Quark.
+
+ a #GQuark
+
+
+
+
+
+ GResourceFlags give information about a particular file inside a resource
+bundle.
+
+ No flags set.
+
+
+ The file is compressed.
+
+
+
+ GResourceLookupFlags determine how resource path lookups are handled.
+
+ No flags set.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Extension point for #GSettingsBackend functionality.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #GSeekable is implemented by streams (implementations of
+#GInputStream or #GOutputStream) that support seeking.
+
+Seekable streams largely fall into two categories: resizable and
+fixed-size.
+
+#GSeekable on fixed-sized streams is approximately the same as POSIX
+lseek() on a block device (for example: attempting to seek past the
+end of the device is an error). Fixed streams typically cannot be
+truncated.
+
+#GSeekable on resizable streams is approximately the same as POSIX
+lseek() on a normal file. Seeking past the end and writing data will
+usually cause the stream to resize by introducing zero bytes.
+
+
+ Tests if the stream supports the #GSeekableIface.
+
+
+ %TRUE if @seekable can be seeked. %FALSE otherwise.
+
+
+
+
+ a #GSeekable.
+
+
+
+
+
+ Tests if the length of the stream can be adjusted with
+g_seekable_truncate().
+
+
+ %TRUE if the stream can be truncated, %FALSE otherwise.
+
+
+
+
+ a #GSeekable.
+
+
+
+
+
+ Seeks in the stream by the given @offset, modified by @type.
+
+Attempting to seek past the end of the stream will have different
+results depending on if the stream is fixed-sized or resizable. If
+the stream is resizable then seeking past the end and then writing
+will result in zeros filling the empty space. Seeking past the end
+of a resizable stream and reading will result in EOF. Seeking past
+the end of a fixed-sized stream will fail.
+
+Any operation that would result in a negative offset will fail.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ %TRUE if successful. If an error
+ has occurred, this function will return %FALSE and set @error
+ appropriately if present.
+
+
+
+
+ a #GSeekable.
+
+
+
+ a #goffset.
+
+
+
+ a #GSeekType.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Tells the current position within the stream.
+
+
+ the (positive or zero) offset from the beginning of the
+buffer, zero if the target is not seekable.
+
+
+
+
+ a #GSeekable.
+
+
+
+
+
+ Sets the length of the stream to @offset. If the stream was previously
+larger than @offset, the extra data is discarded. If the stream was
+previously shorter than @offset, it is extended with NUL ('\0') bytes.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
+operation was partially finished when the operation was cancelled the
+partial result will be returned, without an error.
+
+
+ %TRUE if successful. If an error
+ has occurred, this function will return %FALSE and set @error
+ appropriately if present.
+
+
+
+
+ a #GSeekable.
+
+
+
+ new length for @seekable, in bytes.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Tests if the stream supports the #GSeekableIface.
+
+
+ %TRUE if @seekable can be seeked. %FALSE otherwise.
+
+
+
+
+ a #GSeekable.
+
+
+
+
+
+ Tests if the length of the stream can be adjusted with
+g_seekable_truncate().
+
+
+ %TRUE if the stream can be truncated, %FALSE otherwise.
+
+
+
+
+ a #GSeekable.
+
+
+
+
+
+ Seeks in the stream by the given @offset, modified by @type.
+
+Attempting to seek past the end of the stream will have different
+results depending on if the stream is fixed-sized or resizable. If
+the stream is resizable then seeking past the end and then writing
+will result in zeros filling the empty space. Seeking past the end
+of a resizable stream and reading will result in EOF. Seeking past
+the end of a fixed-sized stream will fail.
+
+Any operation that would result in a negative offset will fail.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ %TRUE if successful. If an error
+ has occurred, this function will return %FALSE and set @error
+ appropriately if present.
+
+
+
+
+ a #GSeekable.
+
+
+
+ a #goffset.
+
+
+
+ a #GSeekType.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Tells the current position within the stream.
+
+
+ the (positive or zero) offset from the beginning of the
+buffer, zero if the target is not seekable.
+
+
+
+
+ a #GSeekable.
+
+
+
+
+
+ Sets the length of the stream to @offset. If the stream was previously
+larger than @offset, the extra data is discarded. If the stream was
+previously shorter than @offset, it is extended with NUL ('\0') bytes.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
+operation was partially finished when the operation was cancelled the
+partial result will be returned, without an error.
+
+
+ %TRUE if successful. If an error
+ has occurred, this function will return %FALSE and set @error
+ appropriately if present.
+
+
+
+
+ a #GSeekable.
+
+
+
+ new length for @seekable, in bytes.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+
+ Provides an interface for implementing seekable functionality on I/O Streams.
+
+
+ The parent interface.
+
+
+
+
+
+
+ the (positive or zero) offset from the beginning of the
+buffer, zero if the target is not seekable.
+
+
+
+
+ a #GSeekable.
+
+
+
+
+
+
+
+
+
+ %TRUE if @seekable can be seeked. %FALSE otherwise.
+
+
+
+
+ a #GSeekable.
+
+
+
+
+
+
+
+
+
+ %TRUE if successful. If an error
+ has occurred, this function will return %FALSE and set @error
+ appropriately if present.
+
+
+
+
+ a #GSeekable.
+
+
+
+ a #goffset.
+
+
+
+ a #GSeekType.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+
+
+
+
+ %TRUE if the stream can be truncated, %FALSE otherwise.
+
+
+
+
+ a #GSeekable.
+
+
+
+
+
+
+
+
+
+ %TRUE if successful. If an error
+ has occurred, this function will return %FALSE and set @error
+ appropriately if present.
+
+
+
+
+ a #GSeekable.
+
+
+
+ new length for @seekable, in bytes.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+
+
+ The #GSettings class provides a convenient API for storing and retrieving
+application settings.
+
+Reads and writes can be considered to be non-blocking. Reading
+settings with #GSettings is typically extremely fast: on
+approximately the same order of magnitude (but slower than) a
+#GHashTable lookup. Writing settings is also extremely fast in terms
+of time to return to your application, but can be extremely expensive
+for other threads and other processes. Many settings backends
+(including dconf) have lazy initialisation which means in the common
+case of the user using their computer without modifying any settings
+a lot of work can be avoided. For dconf, the D-Bus service doesn't
+even need to be started in this case. For this reason, you should
+only ever modify #GSettings keys in response to explicit user action.
+Particular care should be paid to ensure that modifications are not
+made during startup -- for example, when setting the initial value
+of preferences widgets. The built-in g_settings_bind() functionality
+is careful not to write settings in response to notify signals as a
+result of modifications that it makes to widgets.
+
+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 a fixed path that determines where the settings
+are stored in the conceptual global tree of settings. However, schemas
+can also be '[relocatable][gsettings-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.
+
+Paths must start with and end with a forward slash character ('/')
+and must not contain two sequential slash characters. Paths should
+be chosen based on a domain name associated with the program or
+library to which the settings belong. Examples of paths are
+"/org/gtk/settings/file-chooser/" and "/ca/desrt/dconf-editor/".
+Paths should not start with "/apps/", "/desktop/" or "/system/" as
+they often did in GConf.
+
+Unlike other configuration systems (like GConf), GSettings does not
+restrict keys to basic types like strings and numbers. GSettings stores
+values as #GVariant, and allows any #GVariantType for keys. Key names
+are restricted to lowercase characters, numbers and '-'. Furthermore,
+the names must begin with a lowercase character, must not end
+with a '-', and must not contain consecutive dashes.
+
+Similar to GConf, the default values in GSettings schemas can be
+localized, but the localized values are stored in gettext catalogs
+and looked up with the domain that is specified in the
+`gettext-domain` attribute of the <schemalist> or <schema>
+elements and the category that is specified in the `l10n` attribute of
+the <default> element. The string which is translated includes all text in
+the <default> element, including any surrounding quotation marks.
+
+The `l10n` attribute must be set to `messages` or `time`, and sets the
+[locale category for
+translation](https://www.gnu.org/software/gettext/manual/html_node/Aspects.html#index-locale-categories-1).
+The `messages` category should be used by default; use `time` for
+translatable date or time formats. A translation comment can be added as an
+XML comment immediately above the <default> element — it is recommended to
+add these comments to aid translators understand the meaning and
+implications of the default value. An optional translation `context`
+attribute can be set on the <default> element to disambiguate multiple
+defaults which use the same string.
+
+For example:
+|[
+ <!-- Translators: A list of words which are not allowed to be typed, in
+ GVariant serialization syntax.
+ See: https://developer.gnome.org/glib/stable/gvariant-text.html -->
+ <default l10n='messages' context='Banned words'>['bad', 'words']</default>
+]|
+
+Translations of default values must remain syntactically valid serialized
+#GVariants (e.g. retaining any surrounding quotation marks) or runtime
+errors will occur.
+
+GSettings uses schemas in a compact binary form that is created
+by the [glib-compile-schemas][glib-compile-schemas]
+utility. The input is a schema description in an XML format.
+
+A DTD for the gschema XML format can be found here:
+[gschema.dtd](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/gschema.dtd)
+
+The [glib-compile-schemas][glib-compile-schemas] tool expects schema
+files to have the extension `.gschema.xml`.
+
+At runtime, schemas are identified by their id (as specified in the
+id attribute of the <schema> element). The convention for schema
+ids is to use a dotted name, similar in style to a D-Bus bus name,
+e.g. "org.gnome.SessionManager". In particular, if the settings are
+for a specific service that owns a D-Bus bus name, the D-Bus bus name
+and schema id should match. For schemas which deal with settings not
+associated with one named application, the id should not use
+StudlyCaps, e.g. "org.gnome.font-rendering".
+
+In addition to #GVariant types, keys can have types that have
+enumerated types. These can be described by a <choice>,
+<enum> or <flags> element, as seen in the
+[example][schema-enumerated]. The underlying type of such a key
+is string, but you can use g_settings_get_enum(), g_settings_set_enum(),
+g_settings_get_flags(), g_settings_set_flags() access the numeric values
+corresponding to the string value of enum and flags keys.
+
+An example for default value:
+|[
+<schemalist>
+ <schema id="org.gtk.Test" path="/org/gtk/Test/" gettext-domain="test">
+
+ <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>
+
+ <key name="empty-string" type="s">
+ <default>""</default>
+ <summary>Empty strings have to be provided in GVariant form</summary>
+ </key>
+
+ </schema>
+</schemalist>
+]|
+
+An example for ranges, choices and enumerated types:
+|[
+<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>
+]|
+
+## Vendor overrides
+
+Default values are defined in the schemas that get installed by
+an application. Sometimes, it is necessary for a vendor or distributor
+to adjust these defaults. Since patching the XML source for the schema
+is inconvenient and error-prone,
+[glib-compile-schemas][glib-compile-schemas] reads so-called vendor
+override' files. These are keyfiles in the same directory as the XML
+schema sources which can override default values. The schema id serves
+as the group name in the key file, and the values are expected in
+serialized GVariant form, as in the following example:
+|[
+ [org.gtk.Example]
+ key1='string'
+ key2=1.5
+]|
+
+glib-compile-schemas expects schema files to have the extension
+`.gschema.override`.
+
+## Binding
+
+A very convenient feature of GSettings lets you bind #GObject properties
+directly to settings, using g_settings_bind(). Once a GObject property
+has been bound to a setting, changes on either side are automatically
+propagated to the other side. GSettings handles details like mapping
+between GObject and GVariant types, and preventing infinite cycles.
+
+This makes it very easy to hook up a preferences dialog to the
+underlying settings. To make this even more convenient, GSettings
+looks for a boolean property with the name "sensitivity" and
+automatically binds it to the writability of the bound setting.
+If this 'magic' gets in the way, it can be suppressed with the
+%G_SETTINGS_BIND_NO_SENSITIVITY flag.
+
+## Relocatable schemas # {#gsettings-relocatable}
+
+A relocatable schema is one with no `path` attribute specified on its
+<schema> element. By using g_settings_new_with_path(), a #GSettings object
+can be instantiated for a relocatable schema, assigning a path to the
+instance. Paths passed to g_settings_new_with_path() will typically be
+constructed dynamically from a constant prefix plus some form of instance
+identifier; but they must still be valid GSettings paths. Paths could also
+be constant and used with a globally installed schema originating from a
+dependency library.
+
+For example, a relocatable schema could be used to store geometry information
+for different windows in an application. If the schema ID was
+`org.foo.MyApp.Window`, it could be instantiated for paths
+`/org/foo/MyApp/main/`, `/org/foo/MyApp/document-1/`,
+`/org/foo/MyApp/document-2/`, etc. If any of the paths are well-known
+they can be specified as <child> elements in the parent schema, e.g.:
+|[
+<schema id="org.foo.MyApp" path="/org/foo/MyApp/">
+ <child name="main" schema="org.foo.MyApp.Window"/>
+</schema>
+]|
+
+## Build system integration # {#gsettings-build-system}
+
+GSettings comes with autotools integration to simplify compiling and
+installing schemas. To add GSettings support to an application, add the
+following to your `configure.ac`:
+|[
+GLIB_GSETTINGS
+]|
+
+In the appropriate `Makefile.am`, use the following snippet to compile and
+install the named schema:
+|[
+gsettings_SCHEMAS = org.foo.MyApp.gschema.xml
+EXTRA_DIST = $(gsettings_SCHEMAS)
+
+@GSETTINGS_RULES@
+]|
+
+No changes are needed to the build system to mark a schema XML file for
+translation. Assuming it sets the `gettext-domain` attribute, a schema may
+be marked for translation by adding it to `POTFILES.in`, assuming gettext
+0.19 is in use (the preferred method for translation):
+|[
+data/org.foo.MyApp.gschema.xml
+]|
+
+Alternatively, if intltool 0.50.1 is in use:
+|[
+[type: gettext/gsettings]data/org.foo.MyApp.gschema.xml
+]|
+
+GSettings will use gettext to look up translations for the <summary> and
+<description> elements, and also any <default> elements which have a `l10n`
+attribute set. Translations must not be included in the `.gschema.xml` file
+by the build system, for example by using intltool XML rules with a
+`.gschema.xml.in` template.
+
+If an enumerated type defined in a C header file is to be used in a GSettings
+schema, it can either be defined manually using an <enum> element in the
+schema XML, or it can be extracted automatically from the C header. This
+approach is preferred, as it ensures the two representations are always
+synchronised. To do so, add the following to the relevant `Makefile.am`:
+|[
+gsettings_ENUM_NAMESPACE = org.foo.MyApp
+gsettings_ENUM_FILES = my-app-enums.h my-app-misc.h
+]|
+
+`gsettings_ENUM_NAMESPACE` specifies the schema namespace for the enum files,
+which are specified in `gsettings_ENUM_FILES`. This will generate a
+`org.foo.MyApp.enums.xml` file containing the extracted enums, which will be
+automatically included in the schema compilation, install and uninstall
+rules. It should not be committed to version control or included in
+`EXTRA_DIST`.
+
+
+ Creates a new #GSettings object with the schema specified by
+@schema_id.
+
+It is an error for the schema to not exist: schemas are an
+essential part of a program, as they provide type information.
+If schemas need to be dynamically loaded (for example, from an
+optional runtime dependency), g_settings_schema_source_lookup()
+can be used to test for their existence before loading them.
+
+Signals on the newly created #GSettings object will be dispatched
+via the thread-default #GMainContext in effect at the time of the
+call to g_settings_new(). The new #GSettings will hold a reference
+on the context. See g_main_context_push_thread_default().
+
+
+ a new #GSettings object
+
+
+
+
+ the id of the schema
+
+
+
+
+
+ Creates a new #GSettings object with a given schema, backend and
+path.
+
+It should be extremely rare that you ever want to use this function.
+It is made available for advanced use-cases (such as plugin systems
+that want to provide access to schemas loaded from custom locations,
+etc).
+
+At the most basic level, a #GSettings object is a pure composition of
+4 things: a #GSettingsSchema, a #GSettingsBackend, a path within that
+backend, and a #GMainContext to which signals are dispatched.
+
+This constructor therefore gives you full control over constructing
+#GSettings instances. The first 3 parameters are given directly as
+@schema, @backend and @path, and the main context is taken from the
+thread-default (as per g_settings_new()).
+
+If @backend is %NULL then the default backend is used.
+
+If @path is %NULL then the path from the schema is used. It is an
+error if @path is %NULL and the schema has no path of its own or if
+@path is non-%NULL and not equal to the path that the schema does
+have.
+
+
+ a new #GSettings object
+
+
+
+
+ a #GSettingsSchema
+
+
+
+ a #GSettingsBackend
+
+
+
+ the path to use
+
+
+
+
+
+ Creates a new #GSettings object with the schema specified by
+@schema_id and a given #GSettingsBackend.
+
+Creating a #GSettings object with a different backend allows accessing
+settings from a database other than the usual one. For example, it may make
+sense to pass a backend corresponding to the "defaults" settings database on
+the system to get a settings object that modifies the system default
+settings instead of the settings for this user.
+
+
+ a new #GSettings object
+
+
+
+
+ the id of the schema
+
+
+
+ the #GSettingsBackend to use
+
+
+
+
+
+ Creates a new #GSettings object with the schema specified by
+@schema_id and a given #GSettingsBackend and path.
+
+This is a mix of g_settings_new_with_backend() and
+g_settings_new_with_path().
+
+
+ a new #GSettings object
+
+
+
+
+ the id of the schema
+
+
+
+ the #GSettingsBackend to use
+
+
+
+ the path to use
+
+
+
+
+
+ Creates a new #GSettings object with the relocatable schema specified
+by @schema_id and a given path.
+
+You only need to do this if you want to directly create a settings
+object with a schema that doesn't have a specified path of its own.
+That's quite rare.
+
+It is a programmer error to call this function for a schema that
+has an explicitly specified path.
+
+It is a programmer error if @path is not a valid path. A valid path
+begins and ends with '/' and does not contain two consecutive '/'
+characters.
+
+
+ a new #GSettings object
+
+
+
+
+ the id of the schema
+
+
+
+ the path to use
+
+
+
+
+
+ Deprecated.
+ Use g_settings_schema_source_list_schemas() instead
+
+
+ a list of
+ relocatable #GSettings schemas that are available, in no defined order.
+ The list must not be modified or freed.
+
+
+
+
+
+
+ Deprecated.
+ Use g_settings_schema_source_list_schemas() instead.
+If you used g_settings_list_schemas() to check for the presence of
+a particular schema, use g_settings_schema_source_lookup() instead
+of your whole loop.
+
+
+ a list of
+ #GSettings schemas that are available, in no defined order. The list
+ must not be modified or freed.
+
+
+
+
+
+
+ Ensures that all pending operations are complete for the default backend.
+
+Writes made to a #GSettings are handled asynchronously. For this
+reason, it is very unlikely that the changes have it to disk by the
+time g_settings_set() returns.
+
+This call will block until all of the writes have made it to the
+backend. Since the mainloop is not running, no change notifications
+will be dispatched during this call (but some may be queued by the
+time the call is done).
+
+
+
+
+
+
+ Removes an existing binding for @property on @object.
+
+Note that bindings are automatically removed when the
+object is finalized, so it is rarely necessary to call this
+function.
+
+
+
+
+
+
+ the object
+
+
+
+ the property whose binding is removed
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Applies any changes that have been made to the settings. This
+function does nothing unless @settings is in 'delay-apply' mode;
+see g_settings_delay(). In the normal case settings are always
+applied immediately.
+
+
+
+
+
+
+ a #GSettings instance
+
+
+
+
+
+ Create a binding between the @key in the @settings object
+and the property @property of @object.
+
+The binding uses the default GIO mapping functions to map
+between the settings and property values. These functions
+handle booleans, numeric types and string types in a
+straightforward way. Use g_settings_bind_with_mapping() if
+you need a custom mapping, or map between types that are not
+supported by the default mapping functions.
+
+Unless the @flags include %G_SETTINGS_BIND_NO_SENSITIVITY, this
+function also establishes a binding between the writability of
+@key and the "sensitive" property of @object (if @object has
+a boolean property by that name). See g_settings_bind_writable()
+for more details about writable bindings.
+
+Note that the lifecycle of the binding is tied to @object,
+and that you can have only one binding per object property.
+If you bind the same property twice on the same object, the second
+binding overrides the first one.
+
+
+
+
+
+
+ a #GSettings object
+
+
+
+ the key to bind
+
+
+
+ a #GObject
+
+
+
+ the name of the property to bind
+
+
+
+ flags for the binding
+
+
+
+
+
+ Create a binding between the @key in the @settings object
+and the property @property of @object.
+
+The binding uses the provided mapping functions to map between
+settings and property values.
+
+Note that the lifecycle of the binding is tied to @object,
+and that you can have only one binding per object property.
+If you bind the same property twice on the same object, the second
+binding overrides the first one.
+
+
+
+
+
+
+ a #GSettings object
+
+
+
+ the key to bind
+
+
+
+ a #GObject
+
+
+
+ the name of the property to bind
+
+
+
+ flags for the binding
+
+
+
+ a function that gets called to convert values
+ from @settings to @object, or %NULL to use the default GIO mapping
+
+
+
+ a function that gets called to convert values
+ from @object to @settings, or %NULL to use the default GIO mapping
+
+
+
+ data that gets passed to @get_mapping and @set_mapping
+
+
+
+ #GDestroyNotify function for @user_data
+
+
+
+
+
+ Create a binding between the writability of @key in the
+@settings object and the property @property of @object.
+The property must be boolean; "sensitive" or "visible"
+properties of widgets are the most likely candidates.
+
+Writable bindings are always uni-directional; changes of the
+writability of the setting will be propagated to the object
+property, not the other way.
+
+When the @inverted argument is %TRUE, the binding inverts the
+value as it passes from the setting to the object, i.e. @property
+will be set to %TRUE if the key is not writable.
+
+Note that the lifecycle of the binding is tied to @object,
+and that you can have only one binding per object property.
+If you bind the same property twice on the same object, the second
+binding overrides the first one.
+
+
+
+
+
+
+ a #GSettings object
+
+
+
+ the key to bind
+
+
+
+ a #GObject
+
+
+
+ the name of a boolean property to bind
+
+
+
+ whether to 'invert' the value
+
+
+
+
+
+ Creates a #GAction corresponding to a given #GSettings key.
+
+The action has the same name as the key.
+
+The value of the key becomes the state of the action and the action
+is enabled when the key is writable. Changing the state of the
+action results in the key being written to. Changes to the value or
+writability of the key cause appropriate change notifications to be
+emitted for the action.
+
+For boolean-valued keys, action activations take no parameter and
+result in the toggling of the value. For all other types,
+activations take the new value for the key (which must have the
+correct type).
+
+
+ a new #GAction
+
+
+
+
+ a #GSettings
+
+
+
+ the name of a key in @settings
+
+
+
+
+
+ Changes the #GSettings object into 'delay-apply' mode. In this
+mode, changes to @settings are not immediately propagated to the
+backend, but kept locally until g_settings_apply() is called.
+
+
+
+
+
+
+ a #GSettings object
+
+
+
+
+
+ Gets the value that is stored at @key in @settings.
+
+A convenience function that combines g_settings_get_value() with
+g_variant_get().
+
+It is a programmer error to give a @key that isn't contained in the
+schema for @settings or for the #GVariantType of @format to mismatch
+the type given in the schema.
+
+
+
+
+
+
+ a #GSettings object
+
+
+
+ the key to get the value for
+
+
+
+ a #GVariant format string
+
+
+
+ arguments as per @format
+
+
+
+
+
+ Gets the value that is stored at @key in @settings.
+
+A convenience variant of g_settings_get() for booleans.
+
+It is a programmer error to give a @key that isn't specified as
+having a boolean type in the schema for @settings.
+
+
+ a boolean
+
+
+
+
+ a #GSettings object
+
+
+
+ the key to get the value for
+
+
+
+
+
+ Creates a child settings object which has a base path of
+`base-path/@name`, where `base-path` is the base path of
+@settings.
+
+The schema for the child settings object must have been declared
+in the schema of @settings using a `<child>` element.
+
+The created child settings object will inherit the #GSettings:delay-apply
+mode from @settings.
+
+
+ a 'child' settings object
+
+
+
+
+ a #GSettings object
+
+
+
+ the name of the child schema
+
+
+
+
+
+ Gets the "default value" of a key.
+
+This is the value that would be read if g_settings_reset() were to be
+called on the key.
+
+Note that this may be a different value than returned by
+g_settings_schema_key_get_default_value() if the system administrator
+has provided a default value.
+
+Comparing the return values of g_settings_get_default_value() and
+g_settings_get_value() is not sufficient for determining if a value
+has been set because the user may have explicitly set the value to
+something that happens to be equal to the default. The difference
+here is that if the default changes in the future, the user's key
+will still be set.
+
+This function may be useful for adding an indication to a UI of what
+the default value was before the user set it.
+
+It is a programmer error to give a @key that isn't contained in the
+schema for @settings.
+
+
+ the default value
+
+
+
+
+ a #GSettings object
+
+
+
+ the key to get the default value for
+
+
+
+
+
+ Gets the value that is stored at @key in @settings.
+
+A convenience variant of g_settings_get() for doubles.
+
+It is a programmer error to give a @key that isn't specified as
+having a 'double' type in the schema for @settings.
+
+
+ a double
+
+
+
+
+ a #GSettings object
+
+
+
+ the key to get the value for
+
+
+
+
+
+ Gets the value that is stored in @settings for @key and converts it
+to the enum value that it represents.
+
+In order to use this function the type of the value must be a string
+and it must be marked in the schema file as an enumerated type.
+
+It is a programmer error to give a @key that isn't contained in the
+schema for @settings or is not marked as an enumerated type.
+
+If the value stored in the configuration database is not a valid
+value for the enumerated type then this function will return the
+default value.
+
+
+ the enum value
+
+
+
+
+ a #GSettings object
+
+
+
+ the key to get the value for
+
+
+
+
+
+ Gets the value that is stored in @settings for @key and converts it
+to the flags value that it represents.
+
+In order to use this function the type of the value must be an array
+of strings and it must be marked in the schema file as a flags type.
+
+It is a programmer error to give a @key that isn't contained in the
+schema for @settings or is not marked as a flags type.
+
+If the value stored in the configuration database is not a valid
+value for the flags type then this function will return the default
+value.
+
+
+ the flags value
+
+
+
+
+ a #GSettings object
+
+
+
+ the key to get the value for
+
+
+
+
+
+ Returns whether the #GSettings object has any unapplied
+changes. This can only be the case if it is in 'delayed-apply' mode.
+
+
+ %TRUE if @settings has unapplied changes
+
+
+
+
+ a #GSettings object
+
+
+
+
+
+ Gets the value that is stored at @key in @settings.
+
+A convenience variant of g_settings_get() for 32-bit integers.
+
+It is a programmer error to give a @key that isn't specified as
+having a int32 type in the schema for @settings.
+
+
+ an integer
+
+
+
+
+ a #GSettings object
+
+
+
+ the key to get the value for
+
+
+
+
+
+ Gets the value that is stored at @key in @settings.
+
+A convenience variant of g_settings_get() for 64-bit integers.
+
+It is a programmer error to give a @key that isn't specified as
+having a int64 type in the schema for @settings.
+
+
+ a 64-bit integer
+
+
+
+
+ a #GSettings object
+
+
+
+ the key to get the value for
+
+
+
+
+
+ Gets the value that is stored at @key in @settings, subject to
+application-level validation/mapping.
+
+You should use this function when the application needs to perform
+some processing on the value of the key (for example, parsing). The
+@mapping function performs that processing. If the function
+indicates that the processing was unsuccessful (due to a parse error,
+for example) then the mapping is tried again with another value.
+
+This allows a robust 'fall back to defaults' behaviour to be
+implemented somewhat automatically.
+
+The first value that is tried is the user's setting for the key. If
+the mapping function fails to map this value, other values may be
+tried in an unspecified order (system or site defaults, translated
+schema default values, untranslated schema default values, etc).
+
+If the mapping function fails for all possible values, one additional
+attempt is made: the mapping function is called with a %NULL value.
+If the mapping function still indicates failure at this point then
+the application will be aborted.
+
+The result parameter for the @mapping function is pointed to a
+#gpointer which is initially set to %NULL. The same pointer is given
+to each invocation of @mapping. The final value of that #gpointer is
+what is returned by this function. %NULL is valid; it is returned
+just as any other value would be.
+
+
+ the result, which may be %NULL
+
+
+
+
+ a #GSettings object
+
+
+
+ the key to get the value for
+
+
+
+ the function to map the value in the
+ settings database to the value used by the application
+
+
+
+ user data for @mapping
+
+
+
+
+
+ Queries the range of a key.
+ Use g_settings_schema_key_get_range() instead.
+
+
+
+
+
+
+ a #GSettings
+
+
+
+ the key to query the range of
+
+
+
+
+
+ Gets the value that is stored at @key in @settings.
+
+A convenience variant of g_settings_get() for strings.
+
+It is a programmer error to give a @key that isn't specified as
+having a string type in the schema for @settings.
+
+
+ a newly-allocated string
+
+
+
+
+ a #GSettings object
+
+
+
+ the key to get the value for
+
+
+
+
+
+ A convenience variant of g_settings_get() for string arrays.
+
+It is a programmer error to give a @key that isn't specified as
+having an array of strings type in the schema for @settings.
+
+
+ a
+newly-allocated, %NULL-terminated array of strings, the value that
+is stored at @key in @settings.
+
+
+
+
+
+
+ a #GSettings object
+
+
+
+ the key to get the value for
+
+
+
+
+
+ Gets the value that is stored at @key in @settings.
+
+A convenience variant of g_settings_get() for 32-bit unsigned
+integers.
+
+It is a programmer error to give a @key that isn't specified as
+having a uint32 type in the schema for @settings.
+
+
+ an unsigned integer
+
+
+
+
+ a #GSettings object
+
+
+
+ the key to get the value for
+
+
+
+
+
+ Gets the value that is stored at @key in @settings.
+
+A convenience variant of g_settings_get() for 64-bit unsigned
+integers.
+
+It is a programmer error to give a @key that isn't specified as
+having a uint64 type in the schema for @settings.
+
+
+ a 64-bit unsigned integer
+
+
+
+
+ a #GSettings object
+
+
+
+ the key to get the value for
+
+
+
+
+
+ Checks the "user value" of a key, if there is one.
+
+The user value of a key is the last value that was set by the user.
+
+After calling g_settings_reset() this function should always return
+%NULL (assuming something is not wrong with the system
+configuration).
+
+It is possible that g_settings_get_value() will return a different
+value than this function. This can happen in the case that the user
+set a value for a key that was subsequently locked down by the system
+administrator -- this function will return the user's old value.
+
+This function may be useful for adding a "reset" option to a UI or
+for providing indication that a particular value has been changed.
+
+It is a programmer error to give a @key that isn't contained in the
+schema for @settings.
+
+
+ the user's value, if set
+
+
+
+
+ a #GSettings object
+
+
+
+ the key to get the user value for
+
+
+
+
+
+ Gets the value that is stored in @settings for @key.
+
+It is a programmer error to give a @key that isn't contained in the
+schema for @settings.
+
+
+ a new #GVariant
+
+
+
+
+ a #GSettings object
+
+
+
+ the key to get the value for
+
+
+
+
+
+ Finds out if a key can be written or not
+
+
+ %TRUE if the key @name is writable
+
+
+
+
+ a #GSettings object
+
+
+
+ the name of a key
+
+
+
+
+
+ Gets the list of children on @settings.
+
+The list is exactly the list of strings for which it is not an error
+to call g_settings_get_child().
+
+There is little reason to call this function from "normal" code, since
+you should already know what children are in your schema. This function
+may still be useful there for introspection reasons, however.
+
+You should free the return value with g_strfreev() when you are done
+with it.
+
+
+ a list of the children
+ on @settings, in no defined order
+
+
+
+
+
+
+ a #GSettings object
+
+
+
+
+
+ Introspects the list of keys on @settings.
+
+You should probably not be calling this function from "normal" code
+(since you should already know what keys are in your schema). This
+function is intended for introspection reasons.
+
+You should free the return value with g_strfreev() when you are done
+with it.
+ Use g_settings_schema_list_keys() instead.
+
+
+ a list
+ of the keys on @settings, in no defined order
+
+
+
+
+
+
+ a #GSettings object
+
+
+
+
+
+ Checks if the given @value is of the correct type and within the
+permitted range for @key.
+ Use g_settings_schema_key_range_check() instead.
+
+
+ %TRUE if @value is valid for @key
+
+
+
+
+ a #GSettings
+
+
+
+ the key to check
+
+
+
+ the value to check
+
+
+
+
+
+ Resets @key to its default value.
+
+This call resets the key, as much as possible, to its default value.
+That might be the value specified in the schema or the one set by the
+administrator.
+
+
+
+
+
+
+ a #GSettings object
+
+
+
+ the name of a key
+
+
+
+
+
+ Reverts all non-applied changes to the settings. This function
+does nothing unless @settings is in 'delay-apply' mode; see
+g_settings_delay(). In the normal case settings are always applied
+immediately.
+
+Change notifications will be emitted for affected keys.
+
+
+
+
+
+
+ a #GSettings instance
+
+
+
+
+
+ Sets @key in @settings to @value.
+
+A convenience function that combines g_settings_set_value() with
+g_variant_new().
+
+It is a programmer error to give a @key that isn't contained in the
+schema for @settings or for the #GVariantType of @format to mismatch
+the type given in the schema.
+
+
+ %TRUE if setting the key succeeded,
+ %FALSE if the key was not writable
+
+
+
+
+ a #GSettings object
+
+
+
+ the name of the key to set
+
+
+
+ a #GVariant format string
+
+
+
+ arguments as per @format
+
+
+
+
+
+ Sets @key in @settings to @value.
+
+A convenience variant of g_settings_set() for booleans.
+
+It is a programmer error to give a @key that isn't specified as
+having a boolean type in the schema for @settings.
+
+
+ %TRUE if setting the key succeeded,
+ %FALSE if the key was not writable
+
+
+
+
+ a #GSettings object
+
+
+
+ the name of the key to set
+
+
+
+ the value to set it to
+
+
+
+
+
+ Sets @key in @settings to @value.
+
+A convenience variant of g_settings_set() for doubles.
+
+It is a programmer error to give a @key that isn't specified as
+having a 'double' type in the schema for @settings.
+
+
+ %TRUE if setting the key succeeded,
+ %FALSE if the key was not writable
+
+
+
+
+ a #GSettings object
+
+
+
+ the name of the key to set
+
+
+
+ the value to set it to
+
+
+
+
+
+ Looks up the enumerated type nick for @value and writes it to @key,
+within @settings.
+
+It is a programmer error to give a @key that isn't contained in the
+schema for @settings or is not marked as an enumerated type, or for
+@value not to be a valid value for the named type.
+
+After performing the write, accessing @key directly with
+g_settings_get_string() will return the 'nick' associated with
+@value.
+
+
+ %TRUE, if the set succeeds
+
+
+
+
+ a #GSettings object
+
+
+
+ a key, within @settings
+
+
+
+ an enumerated value
+
+
+
+
+
+ Looks up the flags type nicks for the bits specified by @value, puts
+them in an array of strings and writes the array to @key, within
+@settings.
+
+It is a programmer error to give a @key that isn't contained in the
+schema for @settings or is not marked as a flags type, or for @value
+to contain any bits that are not value for the named type.
+
+After performing the write, accessing @key directly with
+g_settings_get_strv() will return an array of 'nicks'; one for each
+bit in @value.
+
+
+ %TRUE, if the set succeeds
+
+
+
+
+ a #GSettings object
+
+
+
+ a key, within @settings
+
+
+
+ a flags value
+
+
+
+
+
+ Sets @key in @settings to @value.
+
+A convenience variant of g_settings_set() for 32-bit integers.
+
+It is a programmer error to give a @key that isn't specified as
+having a int32 type in the schema for @settings.
+
+
+ %TRUE if setting the key succeeded,
+ %FALSE if the key was not writable
+
+
+
+
+ a #GSettings object
+
+
+
+ the name of the key to set
+
+
+
+ the value to set it to
+
+
+
+
+
+ Sets @key in @settings to @value.
+
+A convenience variant of g_settings_set() for 64-bit integers.
+
+It is a programmer error to give a @key that isn't specified as
+having a int64 type in the schema for @settings.
+
+
+ %TRUE if setting the key succeeded,
+ %FALSE if the key was not writable
+
+
+
+
+ a #GSettings object
+
+
+
+ the name of the key to set
+
+
+
+ the value to set it to
+
+
+
+
+
+ Sets @key in @settings to @value.
+
+A convenience variant of g_settings_set() for strings.
+
+It is a programmer error to give a @key that isn't specified as
+having a string type in the schema for @settings.
+
+
+ %TRUE if setting the key succeeded,
+ %FALSE if the key was not writable
+
+
+
+
+ a #GSettings object
+
+
+
+ the name of the key to set
+
+
+
+ the value to set it to
+
+
+
+
+
+ Sets @key in @settings to @value.
+
+A convenience variant of g_settings_set() for string arrays. If
+@value is %NULL, then @key is set to be the empty array.
+
+It is a programmer error to give a @key that isn't specified as
+having an array of strings type in the schema for @settings.
+
+
+ %TRUE if setting the key succeeded,
+ %FALSE if the key was not writable
+
+
+
+
+ a #GSettings object
+
+
+
+ the name of the key to set
+
+
+
+ the value to set it to, or %NULL
+
+
+
+
+
+
+
+ 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.
+
+
+ %TRUE if setting the key succeeded,
+ %FALSE if the key was not writable
+
+
+
+
+ a #GSettings object
+
+
+
+ the name of the key to set
+
+
+
+ the value to set it to
+
+
+
+
+
+ Sets @key in @settings to @value.
+
+A convenience variant of g_settings_set() for 64-bit unsigned
+integers.
+
+It is a programmer error to give a @key that isn't specified as
+having a uint64 type in the schema for @settings.
+
+
+ %TRUE if setting the key succeeded,
+ %FALSE if the key was not writable
+
+
+
+
+ a #GSettings object
+
+
+
+ the name of the key to set
+
+
+
+ the value to set it to
+
+
+
+
+
+ Sets @key in @settings to @value.
+
+It is a programmer error to give a @key that isn't contained in the
+schema for @settings or for @value to have the incorrect type, per
+the schema.
+
+If @value is floating then this function consumes the reference.
+
+
+ %TRUE if setting the key succeeded,
+ %FALSE if the key was not writable
+
+
+
+
+ a #GSettings object
+
+
+
+ the name of the key to set
+
+
+
+ a #GVariant of the correct type
+
+
+
+
+
+ The name of the context that the settings are stored in.
+
+
+
+ Whether the #GSettings object is in 'delay-apply' mode. See
+g_settings_delay() for details.
+
+
+
+ If this property is %TRUE, the #GSettings object has outstanding
+changes that will be applied when g_settings_apply() is called.
+
+
+
+ The path within the backend where the settings are stored.
+
+
+
+ The name of the schema that describes the types of keys
+for this #GSettings object.
+
+The type of this property is *not* #GSettingsSchema.
+#GSettingsSchema has only existed since version 2.32 and
+unfortunately this name was used in previous versions to refer to
+the schema ID rather than the schema itself. Take care to use the
+'settings-schema' property if you wish to pass in a
+#GSettingsSchema.
+ Use the 'schema-id' property instead. In a future
+version, this property may instead refer to a #GSettingsSchema.
+
+
+
+ The name of the schema that describes the types of keys
+for this #GSettings object.
+
+
+
+ The #GSettingsSchema describing the types of keys for this
+#GSettings object.
+
+Ideally, this property would be called 'schema'. #GSettingsSchema
+has only existed since version 2.32, however, and before then the
+'schema' property was used to refer to the ID of the schema rather
+than the schema itself. Take care.
+
+
+
+
+
+
+
+
+
+ The "change-event" signal is emitted once per change event that
+affects this settings object. You should connect to this signal
+only if you are interested in viewing groups of changes before they
+are split out into multiple emissions of the "changed" signal.
+For most use cases it is more appropriate to use the "changed" signal.
+
+In the event that the change event applies to one or more specified
+keys, @keys will be an array of #GQuark of length @n_keys. In the
+event that the change event applies to the #GSettings object as a
+whole (ie: potentially every key has been changed) then @keys will
+be %NULL and @n_keys will be 0.
+
+The default handler for this signal invokes the "changed" signal
+for each affected key. If any other connected handler returns
+%TRUE then this default functionality will be suppressed.
+
+ %TRUE to stop other handlers from being invoked for the
+ event. FALSE to propagate the event further.
+
+
+
+
+
+ an array of #GQuarks for the changed keys, or %NULL
+
+
+
+
+
+ the length of the @keys array, or 0
+
+
+
+
+
+ The "changed" signal is emitted when a key has potentially changed.
+You should call one of the g_settings_get() calls to check the new
+value.
+
+This signal supports detailed connections. You can connect to the
+detailed signal "changed::x" in order to only receive callbacks
+when key "x" changes.
+
+Note that @settings only emits this signal if you have read @key at
+least once while a signal handler was already connected for @key.
+
+
+
+
+
+ the name of the key that changed
+
+
+
+
+
+ The "writable-change-event" signal is emitted once per writability
+change event that affects this settings object. You should connect
+to this signal if you are interested in viewing groups of changes
+before they are split out into multiple emissions of the
+"writable-changed" signal. For most use cases it is more
+appropriate to use the "writable-changed" signal.
+
+In the event that the writability change applies only to a single
+key, @key will be set to the #GQuark for that key. In the event
+that the writability change affects the entire settings object,
+@key will be 0.
+
+The default handler for this signal invokes the "writable-changed"
+and "changed" signals for each affected key. This is done because
+changes in writability might also imply changes in value (if for
+example, a new mandatory setting is introduced). If any other
+connected handler returns %TRUE then this default functionality
+will be suppressed.
+
+ %TRUE to stop other handlers from being invoked for the
+ event. FALSE to propagate the event further.
+
+
+
+
+ the quark of the key, or 0
+
+
+
+
+
+ The "writable-changed" signal is emitted when the writability of a
+key has potentially changed. You should call
+g_settings_is_writable() in order to determine the new status.
+
+This signal supports detailed connections. You can connect to the
+detailed signal "writable-changed::x" in order to only receive
+callbacks when the writability of "x" changes.
+
+
+
+
+
+ the key
+
+
+
+
+
+
+ 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.
+
+The #GSettingsBackend API is exported to allow third-party
+implementations, but does not carry the same stability guarantees
+as the public GIO API. For this reason, you have to define the
+C preprocessor symbol %G_SETTINGS_ENABLE_BACKEND before including
+`gio/gsettingsbackend.h`.
+
+
+ Calculate the longest common prefix of all keys in a tree and write
+out an array of the key names relative to that prefix and,
+optionally, the value to store at each of those keys.
+
+You must free the value returned in @path, @keys and @values using
+g_free(). You should not attempt to free or unref the contents of
+@keys or @values.
+
+
+
+
+
+
+ a #GTree containing the changes
+
+
+
+ the location to save the path
+
+
+
+ the
+ location to save the relative keys
+
+
+
+
+
+
+ the location to save the values, or %NULL
+
+
+
+
+
+
+
+ Returns the default #GSettingsBackend. It is possible to override
+the default by setting the `GSETTINGS_BACKEND` environment variable
+to the name of a settings backend.
+
+The user gets a reference to the backend.
+
+
+ the default #GSettingsBackend,
+ which will be a dummy (memory) settings backend if no other settings
+ backend is available.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Signals that a single key has possibly changed. Backend
+implementations should call this if a key has possibly changed its
+value.
+
+@key must be a valid key (ie starting with a slash, not containing
+'//', and not ending with a slash).
+
+The implementation must call this function during any call to
+g_settings_backend_write(), before the call returns (except in the
+case that no keys are actually changed and it cares to detect this
+fact). It may not rely on the existence of a mainloop for
+dispatching the signal later.
+
+The implementation may call this function at any other time it likes
+in response to other events (such as changes occurring outside of the
+program). These calls may originate from a mainloop or may originate
+in response to any other action (including from calls to
+g_settings_backend_write()).
+
+In the case that this call is in response to a call to
+g_settings_backend_write() then @origin_tag must be set to the same
+value that was passed to that call.
+
+
+
+
+
+
+ a #GSettingsBackend implementation
+
+
+
+ the name of the key
+
+
+
+ the origin tag
+
+
+
+
+
+ This call is a convenience wrapper. It gets the list of changes from
+@tree, computes the longest common prefix and calls
+g_settings_backend_changed().
+
+
+
+
+
+
+ a #GSettingsBackend implementation
+
+
+
+ a #GTree containing the changes
+
+
+
+ the origin tag
+
+
+
+
+
+ Signals that a list of keys have possibly changed. Backend
+implementations should call this if keys have possibly changed their
+values.
+
+@path must be a valid path (ie starting and ending with a slash and
+not containing '//'). Each string in @items must form a valid key
+name when @path is prefixed to it (ie: each item must not start or
+end with '/' and must not contain '//').
+
+The meaning of this signal is that any of the key names resulting
+from the contatenation of @path with each item in @items may have
+changed.
+
+The same rules for when notifications must occur apply as per
+g_settings_backend_changed(). These two calls can be used
+interchangeably if exactly one item has changed (although in that
+case g_settings_backend_changed() is definitely preferred).
+
+For efficiency reasons, the implementation should strive for @path to
+be as long as possible (ie: the longest common prefix of all of the
+keys that were changed) but this is not strictly required.
+
+
+
+
+
+
+ a #GSettingsBackend implementation
+
+
+
+ the path containing the changes
+
+
+
+ the %NULL-terminated list of changed keys
+
+
+
+
+
+ the origin tag
+
+
+
+
+
+ Signals that all keys below a given path may have possibly changed.
+Backend implementations should call this if an entire path of keys
+have possibly changed their values.
+
+@path must be a valid path (ie starting and ending with a slash and
+not containing '//').
+
+The meaning of this signal is that any of the key which has a name
+starting with @path may have changed.
+
+The same rules for when notifications must occur apply as per
+g_settings_backend_changed(). This call might be an appropriate
+reasponse to a 'reset' call but implementations are also free to
+explicitly list the keys that were affected by that call if they can
+easily do so.
+
+For efficiency reasons, the implementation should strive for @path to
+be as long as possible (ie: the longest common prefix of all of the
+keys that were changed) but this is not strictly required. As an
+example, if this function is called with the path of "/" then every
+single key in the application will be notified of a possible change.
+
+
+
+
+
+
+ a #GSettingsBackend implementation
+
+
+
+ the path containing the changes
+
+
+
+ the origin tag
+
+
+
+
+
+ Signals that the writability of all keys below a given path may have
+changed.
+
+Since GSettings performs no locking operations for itself, this call
+will always be made in response to external events.
+
+
+
+
+
+
+ a #GSettingsBackend implementation
+
+
+
+ the name of the path
+
+
+
+
+
+ Signals that the writability of a single key has possibly changed.
+
+Since GSettings performs no locking operations for itself, this call
+will always be made in response to external events.
+
+
+
+
+
+
+ a #GSettingsBackend implementation
+
+
+
+ the name of the key
+
+
+
+
+
+
+
+
+
+
+
+
+ Class structure for #GSettingsBackend.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Flags used when creating a binding. These flags determine in which
+direction the binding works. The default is to synchronize in both
+directions.
+
+ Equivalent to `G_SETTINGS_BIND_GET|G_SETTINGS_BIND_SET`
+
+
+ Update the #GObject property when the setting changes.
+ It is an error to use this flag if the property is not writable.
+
+
+ Update the setting when the #GObject property changes.
+ It is an error to use this flag if the property is not readable.
+
+
+ Do not try to bind a "sensitivity" property to the writability of the setting
+
+
+ When set in addition to %G_SETTINGS_BIND_GET, set the #GObject property
+ value initially from the setting, but do not listen for changes of the setting
+
+
+ When passed to g_settings_bind(), uses a pair of mapping functions that invert
+ the boolean value when mapping between the setting and the property. The setting and property must both
+ be booleans. You cannot pass this flag to g_settings_bind_with_mapping().
+
+
+
+ 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.
+
+
+ %TRUE if the conversion succeeded, %FALSE in case of an error
+
+
+
+
+ return location for the property value
+
+
+
+ the #GVariant
+
+
+
+ user data that was specified when the binding was created
+
+
+
+
+
+ The type for the function that is used to convert an object property
+value to a #GVariant for storing it in #GSettings.
+
+
+ a new #GVariant holding the data from @value,
+ or %NULL in case of an error
+
+
+
+
+ a #GValue containing the property value to map
+
+
+
+ the #GVariantType to create
+
+
+
+ user data that was specified when the binding was created
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The type of the function that is used to convert from a value stored
+in a #GSettings to a value that is useful to the application.
+
+If the value is successfully mapped, the result should be stored at
+@result and %TRUE returned. If mapping fails (for example, if @value
+is not in the right format) then %FALSE should be returned.
+
+If @value is %NULL then it means that the mapping function is being
+given a "last chance" to successfully return a valid value. %TRUE
+must be returned in this case.
+
+
+ %TRUE if the conversion succeeded, %FALSE in case of an error
+
+
+
+
+ the #GVariant to map, or %NULL
+
+
+
+ the result of the mapping
+
+
+
+ the user data that was passed to
+g_settings_get_mapped()
+
+
+
+
+
+
+
+
+ The #GSettingsSchemaSource and #GSettingsSchema APIs provide a
+mechanism for advanced control over the loading of schemas and a
+mechanism for introspecting their content.
+
+Plugin loading systems that wish to provide plugins a way to access
+settings face the problem of how to make the schemas for these
+settings visible to GSettings. Typically, a plugin will want to ship
+the schema along with itself and it won't be installed into the
+standard system directories for schemas.
+
+#GSettingsSchemaSource provides a mechanism for dealing with this by
+allowing the creation of a new 'schema source' from which schemas can
+be acquired. This schema source can then become part of the metadata
+associated with the plugin and queried whenever the plugin requires
+access to some settings.
+
+Consider the following example:
+
+|[<!-- language="C" -->
+typedef struct
+{
+ ...
+ GSettingsSchemaSource *schema_source;
+ ...
+} Plugin;
+
+Plugin *
+initialise_plugin (const gchar *dir)
+{
+ Plugin *plugin;
+
+ ...
+
+ plugin->schema_source =
+ g_settings_schema_source_new_from_directory (dir,
+ g_settings_schema_source_get_default (), FALSE, NULL);
+
+ ...
+
+ return plugin;
+}
+
+...
+
+GSettings *
+plugin_get_settings (Plugin *plugin,
+ const gchar *schema_id)
+{
+ GSettingsSchema *schema;
+
+ if (schema_id == NULL)
+ schema_id = plugin->identifier;
+
+ schema = g_settings_schema_source_lookup (plugin->schema_source,
+ schema_id, FALSE);
+
+ if (schema == NULL)
+ {
+ ... disable the plugin or abort, etc ...
+ }
+
+ return g_settings_new_full (schema, NULL, NULL);
+}
+]|
+
+The code above shows how hooks should be added to the code that
+initialises (or enables) the plugin to create the schema source and
+how an API can be added to the plugin system to provide a convenient
+way for the plugin to access its settings, using the schemas that it
+ships.
+
+From the standpoint of the plugin, it would need to ensure that it
+ships a gschemas.compiled file as part of itself, and then simply do
+the following:
+
+|[<!-- language="C" -->
+{
+ GSettings *settings;
+ gint some_value;
+
+ settings = plugin_get_settings (self, NULL);
+ some_value = g_settings_get_int (settings, "some-value");
+ ...
+}
+]|
+
+It's also possible that the plugin system expects the schema source
+files (ie: .gschema.xml files) instead of a gschemas.compiled file.
+In that case, the plugin loading system must compile the schemas for
+itself before attempting to create the settings source.
+
+
+ Get the ID of @schema.
+
+
+ the ID
+
+
+
+
+ a #GSettingsSchema
+
+
+
+
+
+ Gets the key named @name from @schema.
+
+It is a programmer error to request a key that does not exist. See
+g_settings_schema_list_keys().
+
+
+ the #GSettingsSchemaKey for @name
+
+
+
+
+ a #GSettingsSchema
+
+
+
+ the name of a key
+
+
+
+
+
+ Gets the path associated with @schema, or %NULL.
+
+Schemas may be single-instance or relocatable. Single-instance
+schemas correspond to exactly one set of keys in the backend
+database: those located at the path returned by this function.
+
+Relocatable schemas can be referenced by other schemas and can
+therefore describe multiple sets of keys at different locations. For
+relocatable schemas, this function will return %NULL.
+
+
+ the path of the schema, or %NULL
+
+
+
+
+ a #GSettingsSchema
+
+
+
+
+
+ Checks if @schema has a key named @name.
+
+
+ %TRUE if such a key exists
+
+
+
+
+ a #GSettingsSchema
+
+
+
+ the name of a key
+
+
+
+
+
+ Gets the list of children in @schema.
+
+You should free the return value with g_strfreev() when you are done
+with it.
+
+
+ a list of
+ the children on @settings, in no defined order
+
+
+
+
+
+
+ a #GSettingsSchema
+
+
+
+
+
+ Introspects the list of keys on @schema.
+
+You should probably not be calling this function from "normal" code
+(since you should already know what keys are in your schema). This
+function is intended for introspection reasons.
+
+
+ a list
+ of the keys on @schema, in no defined order
+
+
+
+
+
+
+ a #GSettingsSchema
+
+
+
+
+
+ Increase the reference count of @schema, returning a new reference.
+
+
+ a new reference to @schema
+
+
+
+
+ a #GSettingsSchema
+
+
+
+
+
+ Decrease the reference count of @schema, possibly freeing it.
+
+
+
+
+
+
+ a #GSettingsSchema
+
+
+
+
+
+
+ #GSettingsSchemaKey is an opaque data structure and can only be accessed
+using the following functions.
+
+
+ Gets the default value for @key.
+
+Note that this is the default value according to the schema. System
+administrator defaults and lockdown are not visible via this API.
+
+
+ the default value for the key
+
+
+
+
+ a #GSettingsSchemaKey
+
+
+
+
+
+ Gets the description for @key.
+
+If no description has been provided in the schema for @key, returns
+%NULL.
+
+The description can be one sentence to several paragraphs in length.
+Paragraphs are delimited with a double newline. Descriptions can be
+translated and the value returned from this function is is the
+current locale.
+
+This function is slow. The summary and description information for
+the schemas is not stored in the compiled schema database so this
+function has to parse all of the source XML files in the schema
+directory.
+
+
+ the description for @key, or %NULL
+
+
+
+
+ a #GSettingsSchemaKey
+
+
+
+
+
+ Gets the name of @key.
+
+
+ the name of @key.
+
+
+
+
+ a #GSettingsSchemaKey
+
+
+
+
+
+ Queries the range of a key.
+
+This function will return a #GVariant that fully describes the range
+of values that are valid for @key.
+
+The type of #GVariant returned is `(sv)`. The string describes
+the type of range restriction in effect. The type and meaning of
+the value contained in the variant depends on the string.
+
+If the string is `'type'` then the variant contains an empty array.
+The element type of that empty array is the expected type of value
+and all values of that type are valid.
+
+If the string is `'enum'` then the variant contains an array
+enumerating the possible values. Each item in the array is
+a possible valid value and no other values are valid.
+
+If the string is `'flags'` then the variant contains an array. Each
+item in the array is a value that may appear zero or one times in an
+array to be used as the value for this key. For example, if the
+variant contained the array `['x', 'y']` then the valid values for
+the key would be `[]`, `['x']`, `['y']`, `['x', 'y']` and
+`['y', 'x']`.
+
+Finally, if the string is `'range'` then the variant contains a pair
+of like-typed values -- the minimum and maximum permissible values
+for this key.
+
+This information should not be used by normal programs. It is
+considered to be a hint for introspection purposes. Normal programs
+should already know what is permitted by their own schema. The
+format may change in any way in the future -- but particularly, new
+forms may be added to the possibilities described above.
+
+You should free the returned value with g_variant_unref() when it is
+no longer needed.
+
+
+ a #GVariant describing the range
+
+
+
+
+ a #GSettingsSchemaKey
+
+
+
+
+
+ Gets the summary for @key.
+
+If no summary has been provided in the schema for @key, returns
+%NULL.
+
+The summary is a short description of the purpose of the key; usually
+one short sentence. Summaries can be translated and the value
+returned from this function is is the current locale.
+
+This function is slow. The summary and description information for
+the schemas is not stored in the compiled schema database so this
+function has to parse all of the source XML files in the schema
+directory.
+
+
+ the summary for @key, or %NULL
+
+
+
+
+ a #GSettingsSchemaKey
+
+
+
+
+
+ Gets the #GVariantType of @key.
+
+
+ the type of @key
+
+
+
+
+ a #GSettingsSchemaKey
+
+
+
+
+
+ Checks if the given @value is within the
+permitted range for @key.
+
+It is a programmer error if @value is not of the correct type — you
+must check for this first.
+
+
+ %TRUE if @value is valid for @key
+
+
+
+
+ a #GSettingsSchemaKey
+
+
+
+ the value to check
+
+
+
+
+
+ Increase the reference count of @key, returning a new reference.
+
+
+ a new reference to @key
+
+
+
+
+ a #GSettingsSchemaKey
+
+
+
+
+
+ Decrease the reference count of @key, possibly freeing it.
+
+
+
+
+
+
+ a #GSettingsSchemaKey
+
+
+
+
+
+
+ This is an opaque structure type. You may not access it directly.
+
+
+ Attempts to create a new schema source corresponding to the contents
+of the given directory.
+
+This function is not required for normal uses of #GSettings but it
+may be useful to authors of plugin management systems.
+
+The directory should contain a file called `gschemas.compiled` as
+produced by the [glib-compile-schemas][glib-compile-schemas] tool.
+
+If @trusted is %TRUE then `gschemas.compiled` is trusted not to be
+corrupted. This assumption has a performance advantage, but can result
+in crashes or inconsistent behaviour in the case of a corrupted file.
+Generally, you should set @trusted to %TRUE for files installed by the
+system and to %FALSE for files in the home directory.
+
+In either case, an empty file or some types of corruption in the file will
+result in %G_FILE_ERROR_INVAL being returned.
+
+If @parent is non-%NULL then there are two effects.
+
+First, if g_settings_schema_source_lookup() is called with the
+@recursive flag set to %TRUE and the schema can not be found in the
+source, the lookup will recurse to the parent.
+
+Second, any references to other schemas specified within this
+source (ie: `child` or `extends`) references may be resolved
+from the @parent.
+
+For this second reason, except in very unusual situations, the
+@parent should probably be given as the default schema source, as
+returned by g_settings_schema_source_get_default().
+
+
+
+
+
+
+ the filename of a directory
+
+
+
+ a #GSettingsSchemaSource, or %NULL
+
+
+
+ %TRUE, if the directory is trusted
+
+
+
+
+
+ Lists the schemas in a given source.
+
+If @recursive is %TRUE then include parent sources. If %FALSE then
+only include the schemas from one source (ie: one directory). You
+probably want %TRUE.
+
+Non-relocatable schemas are those for which you can call
+g_settings_new(). Relocatable schemas are those for which you must
+use g_settings_new_with_path().
+
+Do not call this function from normal programs. This is designed for
+use by database editors, commandline tools, etc.
+
+
+
+
+
+
+ a #GSettingsSchemaSource
+
+
+
+ if we should recurse
+
+
+
+ the
+ list of non-relocatable schemas, in no defined order
+
+
+
+
+
+ the list
+ of relocatable schemas, in no defined order
+
+
+
+
+
+
+
+ Looks up a schema with the identifier @schema_id in @source.
+
+This function is not required for normal uses of #GSettings but it
+may be useful to authors of plugin management systems or to those who
+want to introspect the content of schemas.
+
+If the schema isn't found directly in @source and @recursive is %TRUE
+then the parent sources will also be checked.
+
+If the schema isn't found, %NULL is returned.
+
+
+ a new #GSettingsSchema
+
+
+
+
+ a #GSettingsSchemaSource
+
+
+
+ a schema ID
+
+
+
+ %TRUE if the lookup should be recursive
+
+
+
+
+
+ Increase the reference count of @source, returning a new reference.
+
+
+ a new reference to @source
+
+
+
+
+ a #GSettingsSchemaSource
+
+
+
+
+
+ Decrease the reference count of @source, possibly freeing it.
+
+
+
+
+
+
+ a #GSettingsSchemaSource
+
+
+
+
+
+ Gets the default system schema source.
+
+This function is not required for normal uses of #GSettings but it
+may be useful to authors of plugin management systems or to those who
+want to introspect the content of schemas.
+
+If no schemas are installed, %NULL will be returned.
+
+The returned source may actually consist of multiple schema sources
+from different directories, depending on which directories were given
+in `XDG_DATA_DIRS` and `GSETTINGS_SCHEMA_DIR`. For this reason, all
+lookups performed against the default source should probably be done
+recursively.
+
+
+ the default schema source
+
+
+
+
+
+ A #GSimpleAction is the obvious simple implementation of the #GAction
+interface. This is the easiest way to create an action for purposes of
+adding it to a #GSimpleActionGroup.
+
+See also #GtkAction.
+
+
+ Creates a new action.
+
+The created action is stateless. See g_simple_action_new_stateful() to create
+an action that has state.
+
+
+ a new #GSimpleAction
+
+
+
+
+ the name of the action
+
+
+
+ the type of parameter that will be passed to
+ handlers for the #GSimpleAction::activate signal, or %NULL for no parameter
+
+
+
+
+
+ Creates a new stateful action.
+
+All future state values must have the same #GVariantType as the initial
+@state.
+
+If the @state #GVariant is floating, it is consumed.
+
+
+ a new #GSimpleAction
+
+
+
+
+ the name of the action
+
+
+
+ the type of the parameter that will be passed to
+ handlers for the #GSimpleAction::activate signal, or %NULL for no parameter
+
+
+
+ the initial state of the action
+
+
+
+
+
+ Sets the action as enabled or not.
+
+An action must be enabled in order to be activated or in order to
+have its state changed from outside callers.
+
+This should only be called by the implementor of the action. Users
+of the action should not attempt to modify its enabled flag.
+
+
+
+
+
+
+ a #GSimpleAction
+
+
+
+ whether the action is enabled
+
+
+
+
+
+ Sets the state of the action.
+
+This directly updates the 'state' property to the given value.
+
+This should only be called by the implementor of the action. Users
+of the action should not attempt to directly modify the 'state'
+property. Instead, they should call g_action_change_state() to
+request the change.
+
+If the @value GVariant is floating, it is consumed.
+
+
+
+
+
+
+ a #GSimpleAction
+
+
+
+ the new #GVariant for the state
+
+
+
+
+
+ Sets the state hint for the action.
+
+See g_action_get_state_hint() for more information about
+action state hints.
+
+
+
+
+
+
+ a #GSimpleAction
+
+
+
+ a #GVariant representing the state hint
+
+
+
+
+
+ If @action is currently enabled.
+
+If the action is disabled then calls to g_action_activate() and
+g_action_change_state() have no effect.
+
+
+
+ The name of the action. This is mostly meaningful for identifying
+the action once it has been added to a #GSimpleActionGroup.
+
+
+
+ The type of the parameter that must be given when activating the
+action.
+
+
+
+ The state of the action, or %NULL if the action is stateless.
+
+
+
+ The #GVariantType of the state that the action has, or %NULL if the
+action is stateless.
+
+
+
+ Indicates that the action was just activated.
+
+@parameter will always be of the expected type, i.e. the parameter type
+specified when the action was created. If an incorrect type is given when
+activating the action, this signal is not emitted.
+
+Since GLib 2.40, if no handler is connected to this signal then the
+default behaviour for boolean-stated actions with a %NULL parameter
+type is to toggle them via the #GSimpleAction::change-state signal.
+For stateful actions where the state type is equal to the parameter
+type, the default is to forward them directly to
+#GSimpleAction::change-state. This should allow almost all users
+of #GSimpleAction to connect only one handler or the other.
+
+
+
+
+
+ the parameter to the activation, or %NULL if it has
+ no parameter
+
+
+
+
+
+ Indicates that the action just received a request to change its
+state.
+
+@value will always be of the correct state type, i.e. the type of the
+initial state passed to g_simple_action_new_stateful(). If an incorrect
+type is given when requesting to change the state, this signal is not
+emitted.
+
+If no handler is connected to this signal then the default
+behaviour is to call g_simple_action_set_state() to set the state
+to the requested value. If you connect a signal handler then no
+default action is taken. If the state should change then you must
+call g_simple_action_set_state() from the handler.
+
+An example of a 'change-state' handler:
+|[<!-- language="C" -->
+static void
+change_volume_state (GSimpleAction *action,
+ GVariant *value,
+ gpointer user_data)
+{
+ gint requested;
+
+ requested = g_variant_get_int32 (value);
+
+ // Volume only goes from 0 to 10
+ if (0 <= requested && requested <= 10)
+ g_simple_action_set_state (action, value);
+}
+]|
+
+The handler need not set the state to the requested value.
+It could set it to any value at all, or take some other action.
+
+
+
+
+
+ the requested value for the state
+
+
+
+
+
+
+ #GSimpleActionGroup is a hash table filled with #GAction objects,
+implementing the #GActionGroup and #GActionMap interfaces.
+
+
+
+
+ Creates a new, empty, #GSimpleActionGroup.
+
+
+ a new #GSimpleActionGroup
+
+
+
+
+ A convenience function for creating multiple #GSimpleAction instances
+and adding them to the action group.
+ Use g_action_map_add_action_entries()
+
+
+
+
+
+
+ a #GSimpleActionGroup
+
+
+
+ a pointer to the first item in
+ an array of #GActionEntry structs
+
+
+
+
+
+ the length of @entries, or -1
+
+
+
+ the user data for signal connections
+
+
+
+
+
+ Adds an action to the action group.
+
+If the action group already contains an action with the same name as
+@action then the old action is dropped from the group.
+
+The action group takes its own reference on @action.
+ Use g_action_map_add_action()
+
+
+
+
+
+
+ a #GSimpleActionGroup
+
+
+
+ a #GAction
+
+
+
+
+
+ Looks up the action with the name @action_name in the group.
+
+If no such action exists, returns %NULL.
+ Use g_action_map_lookup_action()
+
+
+ a #GAction, or %NULL
+
+
+
+
+ a #GSimpleActionGroup
+
+
+
+ the name of an action
+
+
+
+
+
+ Removes the named action from the action group.
+
+If no action of this name is in the group then nothing happens.
+ Use g_action_map_remove_action()
+
+
+
+
+
+
+ a #GSimpleActionGroup
+
+
+
+ the name of the action
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ As of GLib 2.46, #GSimpleAsyncResult is deprecated in favor of
+#GTask, which provides a simpler API.
+
+#GSimpleAsyncResult implements #GAsyncResult.
+
+GSimpleAsyncResult handles #GAsyncReadyCallbacks, error
+reporting, operation cancellation and the final state of an operation,
+completely transparent to the application. Results can be returned
+as a pointer e.g. for functions that return data that is collected
+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 #GThreads.
+g_simple_async_result_complete() will finish an I/O task directly
+from the point where it is called. g_simple_async_result_complete_in_idle()
+will finish it from an idle handler in the
+[thread-default main context][g-main-context-push-thread-default]
+where the #GSimpleAsyncResult was created.
+g_simple_async_result_run_in_thread() will run the job in a
+separate thread and then use
+g_simple_async_result_complete_in_idle() to deliver the result.
+
+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:
+
+|[<!-- language="C" -->
+static void
+baked_cb (Cake *cake,
+ gpointer user_data)
+{
+ // In this example, this callback is not given a reference to the cake,
+ // so the GSimpleAsyncResult has to take a reference to it.
+ GSimpleAsyncResult *result = user_data;
+
+ if (cake == NULL)
+ g_simple_async_result_set_error (result,
+ BAKER_ERRORS,
+ BAKER_ERROR_NO_FLOUR,
+ "Go to the supermarket");
+ else
+ g_simple_async_result_set_op_res_gpointer (result,
+ g_object_ref (cake),
+ g_object_unref);
+
+
+ // In this example, we assume that baked_cb is called as a callback from
+ // the mainloop, so it's safe to complete the operation synchronously here.
+ // If, however, _baker_prepare_cake () might call its callback without
+ // first returning to the mainloop — inadvisable, but some APIs do so —
+ // we would need to use g_simple_async_result_complete_in_idle().
+ g_simple_async_result_complete (result);
+ g_object_unref (result);
+}
+
+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);
+}
+]|
+
+
+
+ Creates a #GSimpleAsyncResult.
+
+The common convention is to create the #GSimpleAsyncResult in the
+function that starts the asynchronous operation and use that same
+function as the @source_tag.
+
+If your operation supports cancellation with #GCancellable (which it
+probably should) then you should provide the user's cancellable to
+g_simple_async_result_set_check_cancellable() immediately after
+this function returns.
+ Use g_task_new() instead.
+
+
+ a #GSimpleAsyncResult.
+
+
+
+
+ a #GObject, or %NULL.
+
+
+
+ a #GAsyncReadyCallback.
+
+
+
+ user data passed to @callback.
+
+
+
+ the asynchronous function.
+
+
+
+
+
+ Creates a new #GSimpleAsyncResult with a set error.
+ Use g_task_new() and g_task_return_new_error() instead.
+
+
+ a #GSimpleAsyncResult.
+
+
+
+
+ a #GObject, or %NULL.
+
+
+
+ a #GAsyncReadyCallback.
+
+
+
+ user data passed to @callback.
+
+
+
+ a #GQuark.
+
+
+
+ an error code.
+
+
+
+ a string with format characters.
+
+
+
+ a list of values to insert into @format.
+
+
+
+
+
+ Creates a #GSimpleAsyncResult from an error condition.
+ Use g_task_new() and g_task_return_error() instead.
+
+
+ a #GSimpleAsyncResult.
+
+
+
+
+ a #GObject, or %NULL.
+
+
+
+ a #GAsyncReadyCallback.
+
+
+
+ user data passed to @callback.
+
+
+
+ a #GError
+
+
+
+
+
+ Creates a #GSimpleAsyncResult from an error condition, and takes over the
+caller's ownership of @error, so the caller does not need to free it anymore.
+ Use g_task_new() and g_task_return_error() instead.
+
+
+ a #GSimpleAsyncResult
+
+
+
+
+ a #GObject, or %NULL
+
+
+
+ a #GAsyncReadyCallback
+
+
+
+ user data passed to @callback
+
+
+
+ a #GError
+
+
+
+
+
+ Ensures that the data passed to the _finish function of an async
+operation is consistent. Three checks are performed.
+
+First, @result is checked to ensure that it is really a
+#GSimpleAsyncResult. Second, @source is checked to ensure that it
+matches the source object of @result. Third, @source_tag is
+checked to ensure that it is equal to the @source_tag argument given
+to g_simple_async_result_new() (which, by convention, is a pointer
+to the _async function corresponding to the _finish function from
+which this function is called). (Alternatively, if either
+@source_tag or @result's source tag is %NULL, then the source tag
+check is skipped.)
+ Use #GTask and g_task_is_valid() instead.
+
+
+ #TRUE if all checks passed or #FALSE if any failed.
+
+
+
+
+ the #GAsyncResult passed to the _finish function.
+
+
+
+ the #GObject passed to the _finish function.
+
+
+
+ the asynchronous function.
+
+
+
+
+
+ Completes an asynchronous I/O job immediately. Must be called in
+the thread where the asynchronous result was to be delivered, as it
+invokes the callback directly. If you are in a different thread use
+g_simple_async_result_complete_in_idle().
+
+Calling this function takes a reference to @simple for as long as
+is needed to complete the call.
+ Use #GTask instead.
+
+
+
+
+
+
+ a #GSimpleAsyncResult.
+
+
+
+
+
+ Completes an asynchronous function in an idle handler in the
+[thread-default main context][g-main-context-push-thread-default]
+of the thread that @simple was initially created in
+(and re-pushes that context around the invocation of the callback).
+
+Calling this function takes a reference to @simple for as long as
+is needed to complete the call.
+ Use #GTask instead.
+
+
+
+
+
+
+ a #GSimpleAsyncResult.
+
+
+
+
+
+ Gets the operation result boolean from within the asynchronous result.
+ Use #GTask and g_task_propagate_boolean() instead.
+
+
+ %TRUE if the operation's result was %TRUE, %FALSE
+ if the operation's result was %FALSE.
+
+
+
+
+ a #GSimpleAsyncResult.
+
+
+
+
+
+ Gets a pointer result as returned by the asynchronous function.
+ Use #GTask and g_task_propagate_pointer() instead.
+
+
+ a pointer from the result.
+
+
+
+
+ a #GSimpleAsyncResult.
+
+
+
+
+
+ Gets a gssize from the asynchronous result.
+ Use #GTask and g_task_propagate_int() instead.
+
+
+ a gssize returned from the asynchronous function.
+
+
+
+
+ a #GSimpleAsyncResult.
+
+
+
+
+
+ Gets the source tag for the #GSimpleAsyncResult.
+ Use #GTask and g_task_get_source_tag() instead.
+
+
+ a #gpointer to the source object for the #GSimpleAsyncResult.
+
+
+
+
+ a #GSimpleAsyncResult.
+
+
+
+
+
+ Propagates an error from within the simple asynchronous result to
+a given destination.
+
+If the #GCancellable given to a prior call to
+g_simple_async_result_set_check_cancellable() is cancelled then this
+function will return %TRUE with @dest set appropriately.
+ Use #GTask instead.
+
+
+ %TRUE if the error was propagated to @dest. %FALSE otherwise.
+
+
+
+
+ a #GSimpleAsyncResult.
+
+
+
+
+
+ Runs the asynchronous job in a separate thread and then calls
+g_simple_async_result_complete_in_idle() on @simple to return
+the result to the appropriate main loop.
+
+Calling this function takes a reference to @simple for as long as
+is needed to run the job and report its completion.
+ Use #GTask and g_task_run_in_thread() instead.
+
+
+
+
+
+
+ a #GSimpleAsyncResult.
+
+
+
+ a #GSimpleAsyncThreadFunc.
+
+
+
+ the io priority of the request.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Sets a #GCancellable to check before dispatching results.
+
+This function has one very specific purpose: the provided cancellable
+is checked at the time of g_simple_async_result_propagate_error() If
+it is cancelled, these functions will return an "Operation was
+cancelled" error (%G_IO_ERROR_CANCELLED).
+
+Implementors of cancellable asynchronous functions should use this in
+order to provide a guarantee to their callers that cancelling an
+async operation will reliably result in an error being returned for
+that operation (even if a positive result for the operation has
+already been sent as an idle to the main context to be dispatched).
+
+The checking described above is done regardless of any call to the
+unrelated g_simple_async_result_set_handle_cancellation() function.
+ Use #GTask instead.
+
+
+
+
+
+
+ a #GSimpleAsyncResult
+
+
+
+ a #GCancellable to check, or %NULL to unset
+
+
+
+
+
+ Sets an error within the asynchronous result without a #GError.
+ Use #GTask and g_task_return_new_error() instead.
+
+
+
+
+
+
+ a #GSimpleAsyncResult.
+
+
+
+ a #GQuark (usually %G_IO_ERROR).
+
+
+
+ an error code.
+
+
+
+ a formatted error reporting string.
+
+
+
+ a list of variables to fill in @format.
+
+
+
+
+
+ Sets an error within the asynchronous result without a #GError.
+Unless writing a binding, see g_simple_async_result_set_error().
+ Use #GTask and g_task_return_error() instead.
+
+
+
+
+
+
+ a #GSimpleAsyncResult.
+
+
+
+ a #GQuark (usually %G_IO_ERROR).
+
+
+
+ an error code.
+
+
+
+ a formatted error reporting string.
+
+
+
+ va_list of arguments.
+
+
+
+
+
+ Sets the result from a #GError.
+ Use #GTask and g_task_return_error() instead.
+
+
+
+
+
+
+ a #GSimpleAsyncResult.
+
+
+
+ #GError.
+
+
+
+
+
+ Sets whether to handle cancellation within the asynchronous operation.
+
+This function has nothing to do with
+g_simple_async_result_set_check_cancellable(). It only refers to the
+#GCancellable passed to g_simple_async_result_run_in_thread().
+
+
+
+
+
+
+ a #GSimpleAsyncResult.
+
+
+
+ a #gboolean.
+
+
+
+
+
+ Sets the operation result to a boolean within the asynchronous result.
+ Use #GTask and g_task_return_boolean() instead.
+
+
+
+
+
+
+ a #GSimpleAsyncResult.
+
+
+
+ a #gboolean.
+
+
+
+
+
+ Sets the operation result within the asynchronous result to a pointer.
+ Use #GTask and g_task_return_pointer() instead.
+
+
+
+
+
+
+ a #GSimpleAsyncResult.
+
+
+
+ a pointer result from an asynchronous function.
+
+
+
+ a #GDestroyNotify function.
+
+
+
+
+
+ Sets the operation result within the asynchronous result to
+the given @op_res.
+ Use #GTask and g_task_return_int() instead.
+
+
+
+
+
+
+ a #GSimpleAsyncResult.
+
+
+
+ a #gssize.
+
+
+
+
+
+ Sets the result from @error, and takes over the caller's ownership
+of @error, so the caller does not need to free it any more.
+ Use #GTask and g_task_return_error() instead.
+
+
+
+
+
+
+ a #GSimpleAsyncResult
+
+
+
+ a #GError
+
+
+
+
+
+
+
+
+
+ Simple thread function that runs an asynchronous operation and
+checks for cancellation.
+
+
+
+
+
+
+ a #GSimpleAsyncResult.
+
+
+
+ a #GObject.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ GSimpleIOStream creates a #GIOStream from an arbitrary #GInputStream and
+#GOutputStream. This allows any pair of input and output streams to be used
+with #GIOStream methods.
+
+This is useful when you obtained a #GInputStream and a #GOutputStream
+by other means, for instance creating them with platform specific methods as
+g_unix_input_stream_new() or g_win32_input_stream_new(), and you want
+to take advantage of the methods provided by #GIOStream.
+
+ Creates a new #GSimpleIOStream wrapping @input_stream and @output_stream.
+See also #GIOStream.
+
+
+ a new #GSimpleIOStream instance.
+
+
+
+
+ a #GInputStream.
+
+
+
+ a #GOutputStream.
+
+
+
+
+
+
+
+
+
+
+
+
+ #GSimplePermission is a trivial implementation of #GPermission that
+represents a permission that is either always or never allowed. The
+value is given at construction and doesn't change.
+
+Calling request or release will result in errors.
+
+ Creates a new #GPermission instance that represents an action that is
+either always or never allowed.
+
+
+ the #GSimplePermission, as a #GPermission
+
+
+
+
+ %TRUE if the action is allowed
+
+
+
+
+
+
+ #GSimpleProxyResolver is a simple #GProxyResolver implementation
+that handles a single default proxy, multiple URI-scheme-specific
+proxies, and a list of hosts that proxies should not be used for.
+
+#GSimpleProxyResolver is never the default proxy resolver, but it
+can be used as the base class for another proxy resolver
+implementation, or it can be created and used manually, such as
+with g_socket_client_set_proxy_resolver().
+
+
+
+ Creates a new #GSimpleProxyResolver. See
+#GSimpleProxyResolver:default-proxy and
+#GSimpleProxyResolver:ignore-hosts for more details on how the
+arguments are interpreted.
+
+
+ a new #GSimpleProxyResolver
+
+
+
+
+ the default proxy to use, eg
+ "socks://192.168.1.1"
+
+
+
+ an optional list of hosts/IP addresses
+ to not use a proxy for.
+
+
+
+
+
+
+
+ Sets the default proxy on @resolver, to be used for any URIs that
+don't match #GSimpleProxyResolver:ignore-hosts or a proxy set
+via g_simple_proxy_resolver_set_uri_proxy().
+
+If @default_proxy starts with "socks://",
+#GSimpleProxyResolver will treat it as referring to all three of
+the socks5, socks4a, and socks4 proxy types.
+
+
+
+
+
+
+ a #GSimpleProxyResolver
+
+
+
+ the default proxy to use
+
+
+
+
+
+ Sets the list of ignored hosts.
+
+See #GSimpleProxyResolver:ignore-hosts for more details on how the
+@ignore_hosts argument is interpreted.
+
+
+
+
+
+
+ a #GSimpleProxyResolver
+
+
+
+ %NULL-terminated list of hosts/IP addresses
+ to not use a proxy for
+
+
+
+
+
+
+
+ Adds a URI-scheme-specific proxy to @resolver; URIs whose scheme
+matches @uri_scheme (and which don't match
+#GSimpleProxyResolver:ignore-hosts) will be proxied via @proxy.
+
+As with #GSimpleProxyResolver:default-proxy, if @proxy starts with
+"socks://", #GSimpleProxyResolver will treat it
+as referring to all three of the socks5, socks4a, and socks4 proxy
+types.
+
+
+
+
+
+
+ a #GSimpleProxyResolver
+
+
+
+ the URI scheme to add a proxy for
+
+
+
+ the proxy to use for @uri_scheme
+
+
+
+
+
+ The default proxy URI that will be used for any URI that doesn't
+match #GSimpleProxyResolver:ignore-hosts, and doesn't match any
+of the schemes set with g_simple_proxy_resolver_set_uri_proxy().
+
+Note that as a special case, if this URI starts with
+"socks://", #GSimpleProxyResolver will treat it as referring
+to all three of the socks5, socks4a, and socks4 proxy types.
+
+
+
+ A list of hostnames and IP addresses that the resolver should
+allow direct connections to.
+
+Entries can be in one of 4 formats:
+
+- A hostname, such as "example.com", ".example.com", or
+ "*.example.com", any of which match "example.com" or
+ any subdomain of it.
+
+- An IPv4 or IPv6 address, such as "192.168.1.1",
+ which matches only that address.
+
+- A hostname or IP address followed by a port, such as
+ "example.com:80", which matches whatever the hostname or IP
+ address would match, but only for URLs with the (explicitly)
+ indicated port. In the case of an IPv6 address, the address
+ part must appear in brackets: "[::1]:443"
+
+- An IP address range, given by a base address and prefix length,
+ such as "fe80::/10", which matches any address in that range.
+
+Note that when dealing with Unicode hostnames, the matching is
+done against the ASCII form of the name.
+
+Also note that hostname exclusions apply only to connections made
+to hosts identified by name, and IP address exclusions apply only
+to connections made to hosts identified by address. That is, if
+example.com has an address of 192.168.1.1, and the :ignore-hosts list
+contains only "192.168.1.1", then a connection to "example.com"
+(eg, via a #GNetworkAddress) will use the proxy, and a connection to
+"192.168.1.1" (eg, via a #GInetSocketAddress) will not.
+
+These rules match the "ignore-hosts"/"noproxy" rules most
+commonly used by other applications.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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 (which don’t take an explicit blocking
+parameter) 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.
+
+#GSockets can be either connection oriented or datagram based.
+For connection oriented types you must first establish a connection by
+either connecting to an address or accepting a connection from another
+address. For connectionless socket types the target/source address is
+specified or received in each I/O operation.
+
+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.
+
+Like most other APIs in GLib, #GSocket is not inherently thread safe. To use
+a #GSocket concurrently from multiple threads, you must implement your own
+locking.
+
+
+
+
+ Creates a new #GSocket with the defined family, type and protocol.
+If @protocol is 0 (%G_SOCKET_PROTOCOL_DEFAULT) the default protocol type
+for the family and type is used.
+
+The @protocol is a family and type specific int that specifies what
+kind of protocol to use. #GSocketProtocol lists several common ones.
+Many families only support one protocol, and use 0 for this, others
+support several and using 0 means to use the default protocol for
+the family and type.
+
+The protocol id is passed directly to the operating
+system, so you can use protocols not listed in #GSocketProtocol if you
+know the protocol number used for it.
+
+
+ a #GSocket or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ the socket family to use, e.g. %G_SOCKET_FAMILY_IPV4.
+
+
+
+ the socket type to use.
+
+
+
+ the id of the protocol to use, or 0 for default.
+
+
+
+
+
+ Creates a new #GSocket from a native file descriptor
+or winsock SOCKET handle.
+
+This reads all the settings from the file descriptor so that
+all properties should work. Note that the file descriptor
+will be set to non-blocking mode, independent on the blocking
+mode of the #GSocket.
+
+On success, the returned #GSocket takes ownership of @fd. On failure, the
+caller must close @fd themselves.
+
+Since GLib 2.46, it is no longer a fatal error to call this on a non-socket
+descriptor. Instead, a GError will be set with code %G_IO_ERROR_FAILED
+
+
+ a #GSocket or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a native socket file descriptor.
+
+
+
+
+
+ Accept incoming connections on a connection-based socket. This removes
+the first outstanding connection request from the listening socket and
+creates a #GSocket object for it.
+
+The @socket must be bound to a local address with g_socket_bind() and
+must be listening for incoming connections (g_socket_listen()).
+
+If there are no outstanding connections then the operation will block
+or return %G_IO_ERROR_WOULD_BLOCK if non-blocking I/O is enabled.
+To be notified of an incoming connection, wait for the %G_IO_IN condition.
+
+
+ a new #GSocket, or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GSocket.
+
+
+
+ a %GCancellable or %NULL
+
+
+
+
+
+ When a socket is created it is attached to an address family, but it
+doesn't have an address in this family. g_socket_bind() assigns the
+address (sometimes called name) of the socket.
+
+It is generally required to bind to a local address before you can
+receive connections. (See g_socket_listen() and g_socket_accept() ).
+In certain situations, you may also want to bind a socket that will be
+used to initiate connections, though this is not normally required.
+
+If @socket is a TCP socket, then @allow_reuse controls the setting
+of the `SO_REUSEADDR` socket option; normally it should be %TRUE for
+server sockets (sockets that you will eventually call
+g_socket_accept() on), and %FALSE for client sockets. (Failing to
+set this flag on a server socket may cause g_socket_bind() to return
+%G_IO_ERROR_ADDRESS_IN_USE if the server program is stopped and then
+immediately restarted.)
+
+If @socket is a UDP socket, then @allow_reuse determines whether or
+not other UDP sockets can be bound to the same address at the same
+time. In particular, you can have several UDP sockets bound to the
+same address, and they will all receive all of the multicast and
+broadcast packets sent to that address. (The behavior of unicast
+UDP packets to an address with multiple listeners is not defined.)
+
+
+ %TRUE on success, %FALSE on error.
+
+
+
+
+ a #GSocket.
+
+
+
+ a #GSocketAddress specifying the local address.
+
+
+
+ whether to allow reusing this address
+
+
+
+
+
+ Checks and resets the pending connect error for the socket.
+This is used to check for errors when g_socket_connect() is
+used in non-blocking mode.
+
+
+ %TRUE if no error, %FALSE otherwise, setting @error to the error
+
+
+
+
+ a #GSocket
+
+
+
+
+
+ Closes the socket, shutting down any active connection.
+
+Closing a socket does not wait for all outstanding I/O operations
+to finish, so the caller should not rely on them to be guaranteed
+to complete even if the close returns with no error.
+
+Once the socket is closed, all other operations will return
+%G_IO_ERROR_CLOSED. Closing a socket multiple times will not
+return an error.
+
+Sockets will be automatically closed when the last reference
+is dropped, but you might want to call this function to make sure
+resources are released as early as possible.
+
+Beware that due to the way that TCP works, it is possible for
+recently-sent data to be lost if either you close a socket while the
+%G_IO_IN condition is set, or else if the remote connection tries to
+send something to you after you close the socket but before it has
+finished reading all of the data you sent. There is no easy generic
+way to avoid this problem; the easiest fix is to design the network
+protocol such that the client will never send data "out of turn".
+Another solution is for the server to half-close the connection by
+calling g_socket_shutdown() with only the @shutdown_write flag set,
+and then wait for the client to notice this and close its side of the
+connection, after which the server can safely call g_socket_close().
+(This is what #GTcpConnection does if you call
+g_tcp_connection_set_graceful_disconnect(). But of course, this
+only works if the client will close its connection after the server
+does.)
+
+
+ %TRUE on success, %FALSE on error
+
+
+
+
+ a #GSocket
+
+
+
+
+
+ Checks on the readiness of @socket to perform operations.
+The operations specified in @condition are checked for and masked
+against the currently-satisfied conditions on @socket. The result
+is returned.
+
+Note that on Windows, it is possible for an operation to return
+%G_IO_ERROR_WOULD_BLOCK even immediately after
+g_socket_condition_check() has claimed that the socket is ready for
+writing. Rather than calling g_socket_condition_check() and then
+writing to the socket if it succeeds, it is generally better to
+simply try writing to the socket right away, and try again later if
+the initial attempt returns %G_IO_ERROR_WOULD_BLOCK.
+
+It is meaningless to specify %G_IO_ERR or %G_IO_HUP in condition;
+these conditions will always be set in the output if they are true.
+
+This call never blocks.
+
+
+ the @GIOCondition mask of the current state
+
+
+
+
+ a #GSocket
+
+
+
+ a #GIOCondition mask to check
+
+
+
+
+
+ Waits for up to @timeout_us microseconds for @condition to become true
+on @socket. If the condition is met, %TRUE is returned.
+
+If @cancellable is cancelled before the condition is met, or if
+@timeout_us (or the socket's #GSocket:timeout) is reached before the
+condition is met, then %FALSE is returned and @error, if non-%NULL,
+is set to the appropriate value (%G_IO_ERROR_CANCELLED or
+%G_IO_ERROR_TIMED_OUT).
+
+If you don't want a timeout, use g_socket_condition_wait().
+(Alternatively, you can pass -1 for @timeout_us.)
+
+Note that although @timeout_us is in microseconds for consistency with
+other GLib APIs, this function actually only has millisecond
+resolution, and the behavior is undefined if @timeout_us is not an
+exact number of milliseconds.
+
+
+ %TRUE if the condition was met, %FALSE otherwise
+
+
+
+
+ a #GSocket
+
+
+
+ a #GIOCondition mask to wait for
+
+
+
+ the maximum time (in microseconds) to wait, or -1
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Waits for @condition to become true on @socket. When the condition
+is met, %TRUE is returned.
+
+If @cancellable is cancelled before the condition is met, or if the
+socket has a timeout set and it is reached before the condition is
+met, then %FALSE is returned and @error, if non-%NULL, is set to
+the appropriate value (%G_IO_ERROR_CANCELLED or
+%G_IO_ERROR_TIMED_OUT).
+
+See also g_socket_condition_timed_wait().
+
+
+ %TRUE if the condition was met, %FALSE otherwise
+
+
+
+
+ a #GSocket
+
+
+
+ a #GIOCondition mask to wait for
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Connect the socket to the specified remote address.
+
+For connection oriented socket this generally means we attempt to make
+a connection to the @address. For a connection-less socket it sets
+the default address for g_socket_send() and discards all incoming datagrams
+from other sources.
+
+Generally connection oriented sockets can only connect once, but
+connection-less sockets can connect multiple times to change the
+default address.
+
+If the connect call needs to do network I/O it will block, unless
+non-blocking I/O is enabled. Then %G_IO_ERROR_PENDING is returned
+and the user can be notified of the connection finishing by waiting
+for the G_IO_OUT condition. The result of the connection must then be
+checked with g_socket_check_connect_result().
+
+
+ %TRUE if connected, %FALSE on error.
+
+
+
+
+ a #GSocket.
+
+
+
+ a #GSocketAddress specifying the remote address.
+
+
+
+ a %GCancellable or %NULL
+
+
+
+
+
+ Creates a #GSocketConnection subclass of the right type for
+@socket.
+
+
+ a #GSocketConnection
+
+
+
+
+ a #GSocket
+
+
+
+
+
+ Creates a #GSource that can be attached to a %GMainContext to monitor
+for the availability of the specified @condition on the socket. The #GSource
+keeps a reference to the @socket.
+
+The callback on the source is of the #GSocketSourceFunc type.
+
+It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition;
+these conditions will always be reported output if they are true.
+
+@cancellable if not %NULL can be used to cancel the source, which will
+cause the source to trigger, reporting the current condition (which
+is likely 0 unless cancellation happened at the same time as a
+condition change). You can check for this in the callback using
+g_cancellable_is_cancelled().
+
+If @socket has a timeout set, and it is reached before @condition
+occurs, the source will then trigger anyway, reporting %G_IO_IN or
+%G_IO_OUT depending on @condition. However, @socket will have been
+marked as having had a timeout, and so the next #GSocket I/O method
+you call will then fail with a %G_IO_ERROR_TIMED_OUT.
+
+
+ a newly allocated %GSource, free with g_source_unref().
+
+
+
+
+ a #GSocket
+
+
+
+ a #GIOCondition mask to monitor
+
+
+
+ a %GCancellable or %NULL
+
+
+
+
+
+ Get the amount of data pending in the OS input buffer, without blocking.
+
+If @socket is a UDP or SCTP socket, this will return the size of
+just the next packet, even if additional packets are buffered after
+that one.
+
+Note that on Windows, this function is rather inefficient in the
+UDP case, and so if you know any plausible upper bound on the size
+of the incoming packet, it is better to just do a
+g_socket_receive() with a buffer of that size, rather than calling
+g_socket_get_available_bytes() first and then doing a receive of
+exactly the right size.
+
+
+ the number of bytes that can be read from the socket
+without blocking or truncating, or -1 on error.
+
+
+
+
+ a #GSocket
+
+
+
+
+
+ Gets the blocking mode of the socket. For details on blocking I/O,
+see g_socket_set_blocking().
+
+
+ %TRUE if blocking I/O is used, %FALSE otherwise.
+
+
+
+
+ a #GSocket.
+
+
+
+
+
+ Gets the broadcast setting on @socket; if %TRUE,
+it is possible to send packets to broadcast
+addresses.
+
+
+ the broadcast setting on @socket
+
+
+
+
+ a #GSocket.
+
+
+
+
+
+ Returns the credentials of the foreign process connected to this
+socket, if any (e.g. it is only supported for %G_SOCKET_FAMILY_UNIX
+sockets).
+
+If this operation isn't supported on the OS, the method fails with
+the %G_IO_ERROR_NOT_SUPPORTED error. On Linux this is implemented
+by reading the %SO_PEERCRED option on the underlying socket.
+
+This method can be expected to be available on the following platforms:
+
+- Linux since GLib 2.26
+- OpenBSD since GLib 2.30
+- Solaris, Illumos and OpenSolaris since GLib 2.40
+- NetBSD since GLib 2.42
+- macOS, tvOS, iOS since GLib 2.66
+
+Other ways to obtain credentials from a foreign peer includes the
+#GUnixCredentialsMessage type and
+g_unix_connection_send_credentials() /
+g_unix_connection_receive_credentials() functions.
+
+
+ %NULL if @error is set, otherwise a #GCredentials object
+that must be freed with g_object_unref().
+
+
+
+
+ a #GSocket.
+
+
+
+
+
+ Gets the socket family of the socket.
+
+
+ a #GSocketFamily
+
+
+
+
+ a #GSocket.
+
+
+
+
+
+ Returns the underlying OS socket object. On unix this
+is a socket file descriptor, and on Windows this is
+a Winsock2 SOCKET handle. This may be useful for
+doing platform specific or otherwise unusual operations
+on the socket.
+
+
+ the file descriptor of the socket.
+
+
+
+
+ a #GSocket.
+
+
+
+
+
+ Gets the keepalive mode of the socket. For details on this,
+see g_socket_set_keepalive().
+
+
+ %TRUE if keepalive is active, %FALSE otherwise.
+
+
+
+
+ a #GSocket.
+
+
+
+
+
+ Gets the listen backlog setting of the socket. For details on this,
+see g_socket_set_listen_backlog().
+
+
+ the maximum number of pending connections.
+
+
+
+
+ a #GSocket.
+
+
+
+
+
+ Try to get the local address of a bound socket. This is only
+useful if the socket has been bound to a local address,
+either explicitly or implicitly when connecting.
+
+
+ a #GSocketAddress or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GSocket.
+
+
+
+
+
+ Gets the multicast loopback setting on @socket; if %TRUE (the
+default), outgoing multicast packets will be looped back to
+multicast listeners on the same host.
+
+
+ the multicast loopback setting on @socket
+
+
+
+
+ a #GSocket.
+
+
+
+
+
+ Gets the multicast time-to-live setting on @socket; see
+g_socket_set_multicast_ttl() for more details.
+
+
+ the multicast time-to-live setting on @socket
+
+
+
+
+ a #GSocket.
+
+
+
+
+
+ Gets the value of an integer-valued option on @socket, as with
+getsockopt(). (If you need to fetch a non-integer-valued option,
+you will need to call getsockopt() directly.)
+
+The [<gio/gnetworking.h>][gio-gnetworking.h]
+header pulls in system headers that will define most of the
+standard/portable socket options. For unusual socket protocols or
+platform-dependent options, you may need to include additional
+headers.
+
+Note that even for socket options that are a single byte in size,
+@value is still a pointer to a #gint variable, not a #guchar;
+g_socket_get_option() will handle the conversion internally.
+
+
+ success or failure. On failure, @error will be set, and
+ the system error value (`errno` or WSAGetLastError()) will still
+ be set to the result of the getsockopt() call.
+
+
+
+
+ a #GSocket
+
+
+
+ the "API level" of the option (eg, `SOL_SOCKET`)
+
+
+
+ the "name" of the option (eg, `SO_BROADCAST`)
+
+
+
+ return location for the option value
+
+
+
+
+
+ Gets the socket protocol id the socket was created with.
+In case the protocol is unknown, -1 is returned.
+
+
+ a protocol id, or -1 if unknown
+
+
+
+
+ a #GSocket.
+
+
+
+
+
+ Try to get the remote address of a connected socket. This is only
+useful for connection oriented sockets that have been connected.
+
+
+ a #GSocketAddress or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GSocket.
+
+
+
+
+
+ Gets the socket type of the socket.
+
+
+ a #GSocketType
+
+
+
+
+ a #GSocket.
+
+
+
+
+
+ Gets the timeout setting of the socket. For details on this, see
+g_socket_set_timeout().
+
+
+ the timeout in seconds
+
+
+
+
+ a #GSocket.
+
+
+
+
+
+ Gets the unicast time-to-live setting on @socket; see
+g_socket_set_ttl() for more details.
+
+
+ the time-to-live setting on @socket
+
+
+
+
+ a #GSocket.
+
+
+
+
+
+ Checks whether a socket is closed.
+
+
+ %TRUE if socket is closed, %FALSE otherwise
+
+
+
+
+ a #GSocket
+
+
+
+
+
+ Check whether the socket is connected. This is only useful for
+connection-oriented sockets.
+
+If using g_socket_shutdown(), this function will return %TRUE until the
+socket has been shut down for reading and writing. If you do a non-blocking
+connect, this function will not return %TRUE until after you call
+g_socket_check_connect_result().
+
+
+ %TRUE if socket is connected, %FALSE otherwise.
+
+
+
+
+ a #GSocket.
+
+
+
+
+
+ Registers @socket to receive multicast messages sent to @group.
+@socket must be a %G_SOCKET_TYPE_DATAGRAM socket, and must have
+been bound to an appropriate interface and port with
+g_socket_bind().
+
+If @iface is %NULL, the system will automatically pick an interface
+to bind to based on @group.
+
+If @source_specific is %TRUE, source-specific multicast as defined
+in RFC 4604 is used. Note that on older platforms this may fail
+with a %G_IO_ERROR_NOT_SUPPORTED error.
+
+To bind to a given source-specific multicast address, use
+g_socket_join_multicast_group_ssm() instead.
+
+
+ %TRUE on success, %FALSE on error.
+
+
+
+
+ a #GSocket.
+
+
+
+ a #GInetAddress specifying the group address to join.
+
+
+
+ %TRUE if source-specific multicast should be used
+
+
+
+ Name of the interface to use, or %NULL
+
+
+
+
+
+ Registers @socket to receive multicast messages sent to @group.
+@socket must be a %G_SOCKET_TYPE_DATAGRAM socket, and must have
+been bound to an appropriate interface and port with
+g_socket_bind().
+
+If @iface is %NULL, the system will automatically pick an interface
+to bind to based on @group.
+
+If @source_specific is not %NULL, use source-specific multicast as
+defined in RFC 4604. Note that on older platforms this may fail
+with a %G_IO_ERROR_NOT_SUPPORTED error.
+
+Note that this function can be called multiple times for the same
+@group with different @source_specific in order to receive multicast
+packets from more than one source.
+
+
+ %TRUE on success, %FALSE on error.
+
+
+
+
+ a #GSocket.
+
+
+
+ a #GInetAddress specifying the group address to join.
+
+
+
+ a #GInetAddress specifying the
+source-specific multicast address or %NULL to ignore.
+
+
+
+ Name of the interface to use, or %NULL
+
+
+
+
+
+ Removes @socket from the multicast group defined by @group, @iface,
+and @source_specific (which must all have the same values they had
+when you joined the group).
+
+@socket remains bound to its address and port, and can still receive
+unicast messages after calling this.
+
+To unbind to a given source-specific multicast address, use
+g_socket_leave_multicast_group_ssm() instead.
+
+
+ %TRUE on success, %FALSE on error.
+
+
+
+
+ a #GSocket.
+
+
+
+ a #GInetAddress specifying the group address to leave.
+
+
+
+ %TRUE if source-specific multicast was used
+
+
+
+ Interface used
+
+
+
+
+
+ Removes @socket from the multicast group defined by @group, @iface,
+and @source_specific (which must all have the same values they had
+when you joined the group).
+
+@socket remains bound to its address and port, and can still receive
+unicast messages after calling this.
+
+
+ %TRUE on success, %FALSE on error.
+
+
+
+
+ a #GSocket.
+
+
+
+ a #GInetAddress specifying the group address to leave.
+
+
+
+ a #GInetAddress specifying the
+source-specific multicast address or %NULL to ignore.
+
+
+
+ Name of the interface to use, or %NULL
+
+
+
+
+
+ Marks the socket as a server socket, i.e. a socket that is used
+to accept incoming requests using g_socket_accept().
+
+Before calling this the socket must be bound to a local address using
+g_socket_bind().
+
+To set the maximum amount of outstanding clients, use
+g_socket_set_listen_backlog().
+
+
+ %TRUE on success, %FALSE on error.
+
+
+
+
+ a #GSocket.
+
+
+
+
+
+ Receive data (up to @size bytes) from a socket. This is mainly used by
+connection-oriented sockets; it is identical to g_socket_receive_from()
+with @address set to %NULL.
+
+For %G_SOCKET_TYPE_DATAGRAM and %G_SOCKET_TYPE_SEQPACKET sockets,
+g_socket_receive() will always read either 0 or 1 complete messages from
+the socket. If the received message is too large to fit in @buffer, then
+the data beyond @size bytes will be discarded, without any explicit
+indication that this has occurred.
+
+For %G_SOCKET_TYPE_STREAM sockets, g_socket_receive() can return any
+number of bytes, up to @size. If more than @size bytes have been
+received, the additional data will be returned in future calls to
+g_socket_receive().
+
+If the socket is in blocking mode the call will block until there
+is some data to receive, the connection is closed, or there is an
+error. If there is no data available and the socket is in
+non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error will be
+returned. To be notified when data is available, wait for the
+%G_IO_IN condition.
+
+On error -1 is returned and @error is set accordingly.
+
+
+ Number of bytes read, or 0 if the connection was closed by
+the peer, or -1 on error
+
+
+
+
+ a #GSocket
+
+
+
+
+ a buffer to read data into (which should be at least @size bytes long).
+
+
+
+
+
+ the number of bytes you want to read from the socket
+
+
+
+ a %GCancellable or %NULL
+
+
+
+
+
+ Receive data (up to @size bytes) from a socket.
+
+If @address is non-%NULL then @address will be set equal to the
+source address of the received packet.
+@address is owned by the caller.
+
+See g_socket_receive() for additional information.
+
+
+ Number of bytes read, or 0 if the connection was closed by
+the peer, or -1 on error
+
+
+
+
+ a #GSocket
+
+
+
+ a pointer to a #GSocketAddress
+ pointer, or %NULL
+
+
+
+
+ a buffer to read data into (which should be at least @size bytes long).
+
+
+
+
+
+ the number of bytes you want to read from the socket
+
+
+
+ a %GCancellable or %NULL
+
+
+
+
+
+ Receive data from a socket. For receiving multiple messages, see
+g_socket_receive_messages(); for easier use, see
+g_socket_receive() and g_socket_receive_from().
+
+If @address is non-%NULL then @address will be set equal to the
+source address of the received packet.
+@address is owned by the caller.
+
+@vector must point to an array of #GInputVector structs and
+@num_vectors must be the length of this array. These structs
+describe the buffers that received data will be scattered into.
+If @num_vectors is -1, then @vectors is assumed to be terminated
+by a #GInputVector with a %NULL buffer pointer.
+
+As a special case, if @num_vectors is 0 (in which case, @vectors
+may of course be %NULL), then a single byte is received and
+discarded. This is to facilitate the common practice of sending a
+single '\0' byte for the purposes of transferring ancillary data.
+
+@messages, if non-%NULL, will be set to point to a newly-allocated
+array of #GSocketControlMessage instances or %NULL if no such
+messages was received. These correspond to the control messages
+received from the kernel, one #GSocketControlMessage per message
+from the kernel. This array is %NULL-terminated and must be freed
+by the caller using g_free() after calling g_object_unref() on each
+element. If @messages is %NULL, any control messages received will
+be discarded.
+
+@num_messages, if non-%NULL, will be set to the number of control
+messages received.
+
+If both @messages and @num_messages are non-%NULL, then
+@num_messages gives the number of #GSocketControlMessage instances
+in @messages (ie: not including the %NULL terminator).
+
+@flags is an in/out parameter. The commonly available arguments
+for this are available in the #GSocketMsgFlags enum, but the
+values there are the same as the system values, and the flags
+are passed in as-is, so you can pass in system-specific flags too
+(and g_socket_receive_message() may pass system-specific flags out).
+Flags passed in to the parameter affect the receive operation; flags returned
+out of it are relevant to the specific returned message.
+
+As with g_socket_receive(), data may be discarded if @socket is
+%G_SOCKET_TYPE_DATAGRAM or %G_SOCKET_TYPE_SEQPACKET and you do not
+provide enough buffer space to read a complete message. You can pass
+%G_SOCKET_MSG_PEEK in @flags to peek at the current message without
+removing it from the receive queue, but there is no portable way to find
+out the length of the message other than by reading it into a
+sufficiently-large buffer.
+
+If the socket is in blocking mode the call will block until there
+is some data to receive, the connection is closed, or there is an
+error. If there is no data available and the socket is in
+non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error will be
+returned. To be notified when data is available, wait for the
+%G_IO_IN condition.
+
+On error -1 is returned and @error is set accordingly.
+
+
+ Number of bytes read, or 0 if the connection was closed by
+the peer, or -1 on error
+
+
+
+
+ a #GSocket
+
+
+
+ a pointer to a #GSocketAddress
+ pointer, or %NULL
+
+
+
+ an array of #GInputVector structs
+
+
+
+
+
+ the number of elements in @vectors, or -1
+
+
+
+ a pointer
+ which may be filled with an array of #GSocketControlMessages, or %NULL
+
+
+
+
+
+ a pointer which will be filled with the number of
+ elements in @messages, or %NULL
+
+
+
+ a pointer to an int containing #GSocketMsgFlags flags,
+ which may additionally contain
+ [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html)
+
+
+
+ a %GCancellable or %NULL
+
+
+
+
+
+ Receive multiple data messages from @socket in one go. This is the most
+complicated and fully-featured version of this call. For easier use, see
+g_socket_receive(), g_socket_receive_from(), and g_socket_receive_message().
+
+@messages must point to an array of #GInputMessage structs and
+@num_messages must be the length of this array. Each #GInputMessage
+contains a pointer to an array of #GInputVector structs describing the
+buffers that the data received in each message will be written to. Using
+multiple #GInputVectors is more memory-efficient than manually copying data
+out of a single buffer to multiple sources, and more system-call-efficient
+than making multiple calls to g_socket_receive(), such as in scenarios where
+a lot of data packets need to be received (e.g. high-bandwidth video
+streaming over RTP/UDP).
+
+@flags modify how all messages are received. The commonly available
+arguments for this are available in the #GSocketMsgFlags enum, but the
+values there are the same as the system values, and the flags
+are passed in as-is, so you can pass in system-specific flags too. These
+flags affect the overall receive operation. Flags affecting individual
+messages are returned in #GInputMessage.flags.
+
+The other members of #GInputMessage are treated as described in its
+documentation.
+
+If #GSocket:blocking is %TRUE the call will block until @num_messages have
+been received, or the end of the stream is reached.
+
+If #GSocket:blocking is %FALSE the call will return up to @num_messages
+without blocking, or %G_IO_ERROR_WOULD_BLOCK if no messages are queued in the
+operating system to be received.
+
+In blocking mode, if #GSocket:timeout is positive and is reached before any
+messages are received, %G_IO_ERROR_TIMED_OUT is returned, otherwise up to
+@num_messages are returned. (Note: This is effectively the
+behaviour of `MSG_WAITFORONE` with recvmmsg().)
+
+To be notified when messages are available, wait for the
+%G_IO_IN condition. Note though that you may still receive
+%G_IO_ERROR_WOULD_BLOCK from g_socket_receive_messages() even if you were
+previously notified of a %G_IO_IN condition.
+
+If the remote peer closes the connection, any messages queued in the
+operating system will be returned, and subsequent calls to
+g_socket_receive_messages() will return 0 (with no error set).
+
+On error -1 is returned and @error is set accordingly. An error will only
+be returned if zero messages could be received; otherwise the number of
+messages successfully received before the error will be returned.
+
+
+ number of messages received, or -1 on error. Note that the number
+ of messages received may be smaller than @num_messages if in non-blocking
+ mode, if the peer closed the connection, or if @num_messages
+ was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try
+ to receive the remaining messages.
+
+
+
+
+ a #GSocket
+
+
+
+ an array of #GInputMessage structs
+
+
+
+
+
+ the number of elements in @messages
+
+
+
+ an int containing #GSocketMsgFlags flags for the overall operation,
+ which may additionally contain
+ [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html)
+
+
+
+ a %GCancellable or %NULL
+
+
+
+
+
+ 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.
+
+
+ Number of bytes read, or 0 if the connection was closed by
+the peer, or -1 on error
+
+
+
+
+ a #GSocket
+
+
+
+
+ a buffer to read data into (which should be at least @size bytes long).
+
+
+
+
+
+ the number of bytes you want to read from the socket
+
+
+
+ whether to do blocking or non-blocking I/O
+
+
+
+ a %GCancellable or %NULL
+
+
+
+
+
+ Tries to send @size bytes from @buffer on the socket. This is
+mainly used by connection-oriented sockets; it is identical to
+g_socket_send_to() with @address set to %NULL.
+
+If the socket is in blocking mode the call will block until there is
+space for the data in the socket queue. If there is no space available
+and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error
+will be returned. To be notified when space is available, wait for the
+%G_IO_OUT condition. Note though that you may still receive
+%G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously
+notified of a %G_IO_OUT condition. (On Windows in particular, this is
+very common due to the way the underlying APIs work.)
+
+On error -1 is returned and @error is set accordingly.
+
+
+ Number of bytes written (which may be less than @size), or -1
+on error
+
+
+
+
+ a #GSocket
+
+
+
+ the buffer
+ containing the data to send.
+
+
+
+
+
+ the number of bytes to send
+
+
+
+ a %GCancellable or %NULL
+
+
+
+
+
+ Send data to @address on @socket. For sending multiple messages see
+g_socket_send_messages(); for easier use, see
+g_socket_send() and g_socket_send_to().
+
+If @address is %NULL then the message is sent to the default receiver
+(set by g_socket_connect()).
+
+@vectors must point to an array of #GOutputVector structs and
+@num_vectors must be the length of this array. (If @num_vectors is -1,
+then @vectors is assumed to be terminated by a #GOutputVector with a
+%NULL buffer pointer.) The #GOutputVector structs describe the buffers
+that the sent data will be gathered from. Using multiple
+#GOutputVectors is more memory-efficient than manually copying
+data from multiple sources into a single buffer, and more
+network-efficient than making multiple calls to g_socket_send().
+
+@messages, if non-%NULL, is taken to point to an array of @num_messages
+#GSocketControlMessage instances. These correspond to the control
+messages to be sent on the socket.
+If @num_messages is -1 then @messages is treated as a %NULL-terminated
+array.
+
+@flags modify how the message is sent. The commonly available arguments
+for this are available in the #GSocketMsgFlags enum, but the
+values there are the same as the system values, and the flags
+are passed in as-is, so you can pass in system-specific flags too.
+
+If the socket is in blocking mode the call will block until there is
+space for the data in the socket queue. If there is no space available
+and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error
+will be returned. To be notified when space is available, wait for the
+%G_IO_OUT condition. Note though that you may still receive
+%G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously
+notified of a %G_IO_OUT condition. (On Windows in particular, this is
+very common due to the way the underlying APIs work.)
+
+The sum of the sizes of each #GOutputVector in vectors must not be
+greater than %G_MAXSSIZE. If the message can be larger than this,
+then it is mandatory to use the g_socket_send_message_with_timeout()
+function.
+
+On error -1 is returned and @error is set accordingly.
+
+
+ Number of bytes written (which may be less than @size), or -1
+on error
+
+
+
+
+ a #GSocket
+
+
+
+ a #GSocketAddress, or %NULL
+
+
+
+ an array of #GOutputVector structs
+
+
+
+
+
+ the number of elements in @vectors, or -1
+
+
+
+ a pointer to an
+ array of #GSocketControlMessages, or %NULL.
+
+
+
+
+
+ number of elements in @messages, or -1.
+
+
+
+ an int containing #GSocketMsgFlags flags, which may additionally
+ contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html)
+
+
+
+ a %GCancellable or %NULL
+
+
+
+
+
+ This behaves exactly the same as g_socket_send_message(), except that
+the choice of timeout behavior is determined by the @timeout_us argument
+rather than by @socket's properties.
+
+On error %G_POLLABLE_RETURN_FAILED is returned and @error is set accordingly, or
+if the socket is currently not writable %G_POLLABLE_RETURN_WOULD_BLOCK is
+returned. @bytes_written will contain 0 in both cases.
+
+
+ %G_POLLABLE_RETURN_OK if all data was successfully written,
+%G_POLLABLE_RETURN_WOULD_BLOCK if the socket is currently not writable, or
+%G_POLLABLE_RETURN_FAILED if an error happened and @error is set.
+
+
+
+
+ a #GSocket
+
+
+
+ a #GSocketAddress, or %NULL
+
+
+
+ an array of #GOutputVector structs
+
+
+
+
+
+ the number of elements in @vectors, or -1
+
+
+
+ a pointer to an
+ array of #GSocketControlMessages, or %NULL.
+
+
+
+
+
+ number of elements in @messages, or -1.
+
+
+
+ an int containing #GSocketMsgFlags flags, which may additionally
+ contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html)
+
+
+
+ the maximum time (in microseconds) to wait, or -1
+
+
+
+ location to store the number of bytes that were written to the socket
+
+
+
+ a %GCancellable or %NULL
+
+
+
+
+
+ Send multiple data messages from @socket in one go. This is the most
+complicated and fully-featured version of this call. For easier use, see
+g_socket_send(), g_socket_send_to(), and g_socket_send_message().
+
+@messages must point to an array of #GOutputMessage structs and
+@num_messages must be the length of this array. Each #GOutputMessage
+contains an address to send the data to, and a pointer to an array of
+#GOutputVector structs to describe the buffers that the data to be sent
+for each message will be gathered from. Using multiple #GOutputVectors is
+more memory-efficient than manually copying data from multiple sources
+into a single buffer, and more network-efficient than making multiple
+calls to g_socket_send(). Sending multiple messages in one go avoids the
+overhead of making a lot of syscalls in scenarios where a lot of data
+packets need to be sent (e.g. high-bandwidth video streaming over RTP/UDP),
+or where the same data needs to be sent to multiple recipients.
+
+@flags modify how the message is sent. The commonly available arguments
+for this are available in the #GSocketMsgFlags enum, but the
+values there are the same as the system values, and the flags
+are passed in as-is, so you can pass in system-specific flags too.
+
+If the socket is in blocking mode the call will block until there is
+space for all the data in the socket queue. If there is no space available
+and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error
+will be returned if no data was written at all, otherwise the number of
+messages sent will be returned. To be notified when space is available,
+wait for the %G_IO_OUT condition. Note though that you may still receive
+%G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously
+notified of a %G_IO_OUT condition. (On Windows in particular, this is
+very common due to the way the underlying APIs work.)
+
+On error -1 is returned and @error is set accordingly. An error will only
+be returned if zero messages could be sent; otherwise the number of messages
+successfully sent before the error will be returned.
+
+
+ number of messages sent, or -1 on error. Note that the number of
+ messages sent may be smaller than @num_messages if the socket is
+ non-blocking or if @num_messages was larger than UIO_MAXIOV (1024),
+ in which case the caller may re-try to send the remaining messages.
+
+
+
+
+ a #GSocket
+
+
+
+ an array of #GOutputMessage structs
+
+
+
+
+
+ the number of elements in @messages
+
+
+
+ an int containing #GSocketMsgFlags flags, which may additionally
+ contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html)
+
+
+
+ a %GCancellable or %NULL
+
+
+
+
+
+ Tries to send @size bytes from @buffer to @address. If @address is
+%NULL then the message is sent to the default receiver (set by
+g_socket_connect()).
+
+See g_socket_send() for additional information.
+
+
+ Number of bytes written (which may be less than @size), or -1
+on error
+
+
+
+
+ a #GSocket
+
+
+
+ a #GSocketAddress, or %NULL
+
+
+
+ the buffer
+ containing the data to send.
+
+
+
+
+
+ the number of bytes to send
+
+
+
+ a %GCancellable or %NULL
+
+
+
+
+
+ This behaves exactly the same as g_socket_send(), except that
+the choice of blocking or non-blocking behavior is determined by
+the @blocking argument rather than by @socket's properties.
+
+
+ Number of bytes written (which may be less than @size), or -1
+on error
+
+
+
+
+ a #GSocket
+
+
+
+ the buffer
+ containing the data to send.
+
+
+
+
+
+ the number of bytes to send
+
+
+
+ whether to do blocking or non-blocking I/O
+
+
+
+ a %GCancellable or %NULL
+
+
+
+
+
+ Sets the blocking mode of the socket. In blocking mode
+all operations (which don’t take an explicit blocking parameter) block until
+they succeed or there is an error. In
+non-blocking mode all functions return results immediately or
+with a %G_IO_ERROR_WOULD_BLOCK error.
+
+All sockets are created in blocking mode. However, note that the
+platform level socket is always non-blocking, and blocking mode
+is a GSocket level feature.
+
+
+
+
+
+
+ a #GSocket.
+
+
+
+ Whether to use blocking I/O or not.
+
+
+
+
+
+ Sets whether @socket should allow sending to broadcast addresses.
+This is %FALSE by default.
+
+
+
+
+
+
+ a #GSocket.
+
+
+
+ whether @socket should allow sending to broadcast
+ addresses
+
+
+
+
+
+ Sets or unsets the %SO_KEEPALIVE flag on the underlying socket. When
+this flag is set on a socket, the system will attempt to verify that the
+remote socket endpoint is still present if a sufficiently long period of
+time passes with no data being exchanged. If the system is unable to
+verify the presence of the remote endpoint, it will automatically close
+the connection.
+
+This option is only functional on certain kinds of sockets. (Notably,
+%G_SOCKET_PROTOCOL_TCP sockets.)
+
+The exact time between pings is system- and protocol-dependent, but will
+normally be at least two hours. Most commonly, you would set this flag
+on a server socket if you want to allow clients to remain idle for long
+periods of time, but also want to ensure that connections are eventually
+garbage-collected if clients crash or become unreachable.
+
+
+
+
+
+
+ a #GSocket.
+
+
+
+ Value for the keepalive flag
+
+
+
+
+
+ Sets the maximum number of outstanding connections allowed
+when listening on this socket. If more clients than this are
+connecting to the socket and the application is not handling them
+on time then the new connections will be refused.
+
+Note that this must be called before g_socket_listen() and has no
+effect if called after that.
+
+
+
+
+
+
+ a #GSocket.
+
+
+
+ the maximum number of pending connections.
+
+
+
+
+
+ Sets whether outgoing multicast packets will be received by sockets
+listening on that multicast address on the same host. This is %TRUE
+by default.
+
+
+
+
+
+
+ a #GSocket.
+
+
+
+ whether @socket should receive messages sent to its
+ multicast groups from the local host
+
+
+
+
+
+ Sets the time-to-live for outgoing multicast datagrams on @socket.
+By default, this is 1, meaning that multicast packets will not leave
+the local network.
+
+
+
+
+
+
+ a #GSocket.
+
+
+
+ the time-to-live value for all multicast datagrams on @socket
+
+
+
+
+
+ Sets the value of an integer-valued option on @socket, as with
+setsockopt(). (If you need to set a non-integer-valued option,
+you will need to call setsockopt() directly.)
+
+The [<gio/gnetworking.h>][gio-gnetworking.h]
+header pulls in system headers that will define most of the
+standard/portable socket options. For unusual socket protocols or
+platform-dependent options, you may need to include additional
+headers.
+
+
+ success or failure. On failure, @error will be set, and
+ the system error value (`errno` or WSAGetLastError()) will still
+ be set to the result of the setsockopt() call.
+
+
+
+
+ a #GSocket
+
+
+
+ the "API level" of the option (eg, `SOL_SOCKET`)
+
+
+
+ the "name" of the option (eg, `SO_BROADCAST`)
+
+
+
+ the value to set the option to
+
+
+
+
+
+ Sets the time in seconds after which I/O operations on @socket will
+time out if they have not yet completed.
+
+On a blocking socket, this means that any blocking #GSocket
+operation will time out after @timeout seconds of inactivity,
+returning %G_IO_ERROR_TIMED_OUT.
+
+On a non-blocking socket, calls to g_socket_condition_wait() will
+also fail with %G_IO_ERROR_TIMED_OUT after the given time. Sources
+created with g_socket_create_source() will trigger after
+@timeout seconds of inactivity, with the requested condition
+set, at which point calling g_socket_receive(), g_socket_send(),
+g_socket_check_connect_result(), etc, will fail with
+%G_IO_ERROR_TIMED_OUT.
+
+If @timeout is 0 (the default), operations will never time out
+on their own.
+
+Note that if an I/O operation is interrupted by a signal, this may
+cause the timeout to be reset.
+
+
+
+
+
+
+ a #GSocket.
+
+
+
+ the timeout for @socket, in seconds, or 0 for none
+
+
+
+
+
+ Sets the time-to-live for outgoing unicast packets on @socket.
+By default the platform-specific default value is used.
+
+
+
+
+
+
+ a #GSocket.
+
+
+
+ the time-to-live value for all unicast packets on @socket
+
+
+
+
+
+ Shut down part or all of a full-duplex connection.
+
+If @shutdown_read is %TRUE then the receiving side of the connection
+is shut down, and further reading is disallowed.
+
+If @shutdown_write is %TRUE then the sending side of the connection
+is shut down, and further writing is disallowed.
+
+It is allowed for both @shutdown_read and @shutdown_write to be %TRUE.
+
+One example where it is useful to shut down only one side of a connection is
+graceful disconnect for TCP connections where you close the sending side,
+then wait for the other side to close the connection, thus ensuring that the
+other side saw all sent data.
+
+
+ %TRUE on success, %FALSE on error
+
+
+
+
+ a #GSocket
+
+
+
+ whether to shut down the read side
+
+
+
+ whether to shut down the write side
+
+
+
+
+
+ Checks if a socket is capable of speaking IPv4.
+
+IPv4 sockets are capable of speaking IPv4. On some operating systems
+and under some combinations of circumstances IPv6 sockets are also
+capable of speaking IPv4. See RFC 3493 section 3.7 for more
+information.
+
+No other types of sockets are currently considered as being capable
+of speaking IPv4.
+
+
+ %TRUE if this socket can be used with IPv4.
+
+
+
+
+ a #GSocket
+
+
+
+
+
+
+
+
+ Whether the socket should allow sending to broadcast addresses.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Whether outgoing multicast packets loop back to the local host.
+
+
+
+ Time-to-live out outgoing multicast packets
+
+
+
+
+
+
+
+
+
+ The timeout in seconds on socket I/O
+
+
+
+ Time-to-live for outgoing unicast packets
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #GSocketAddress is the equivalent of struct sockaddr in the BSD
+sockets API. This is an abstract class; use #GInetSocketAddress
+for internet sockets, or #GUnixSocketAddress for UNIX domain sockets.
+
+
+
+ Creates a #GSocketAddress subclass corresponding to the native
+struct sockaddr @native.
+
+
+ a new #GSocketAddress if @native could successfully
+ be converted, otherwise %NULL
+
+
+
+
+ a pointer to a struct sockaddr
+
+
+
+ the size of the memory location pointed to by @native
+
+
+
+
+
+ Gets the socket family type of @address.
+
+
+ the socket family type of @address
+
+
+
+
+ a #GSocketAddress
+
+
+
+
+
+ Gets the size of @address's native struct sockaddr.
+You can use this to allocate memory to pass to
+g_socket_address_to_native().
+
+
+ the size of the native struct sockaddr that
+ @address represents
+
+
+
+
+ a #GSocketAddress
+
+
+
+
+
+ Converts a #GSocketAddress to a native struct sockaddr, which can
+be passed to low-level functions like connect() or bind().
+
+If not enough space is available, a %G_IO_ERROR_NO_SPACE error
+is returned. If the address type is not known on the system
+then a %G_IO_ERROR_NOT_SUPPORTED error is returned.
+
+
+ %TRUE if @dest was filled in, %FALSE on error
+
+
+
+
+ a #GSocketAddress
+
+
+
+ a pointer to a memory location that will contain the native
+struct sockaddr
+
+
+
+ the size of @dest. Must be at least as large as
+ g_socket_address_get_native_size()
+
+
+
+
+
+ Gets the socket family type of @address.
+
+
+ the socket family type of @address
+
+
+
+
+ a #GSocketAddress
+
+
+
+
+
+ Gets the size of @address's native struct sockaddr.
+You can use this to allocate memory to pass to
+g_socket_address_to_native().
+
+
+ the size of the native struct sockaddr that
+ @address represents
+
+
+
+
+ a #GSocketAddress
+
+
+
+
+
+ Converts a #GSocketAddress to a native struct sockaddr, which can
+be passed to low-level functions like connect() or bind().
+
+If not enough space is available, a %G_IO_ERROR_NO_SPACE error
+is returned. If the address type is not known on the system
+then a %G_IO_ERROR_NOT_SUPPORTED error is returned.
+
+
+ %TRUE if @dest was filled in, %FALSE on error
+
+
+
+
+ a #GSocketAddress
+
+
+
+ a pointer to a memory location that will contain the native
+struct sockaddr
+
+
+
+ the size of @dest. Must be at least as large as
+ g_socket_address_get_native_size()
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ the socket family type of @address
+
+
+
+
+ a #GSocketAddress
+
+
+
+
+
+
+
+
+
+ the size of the native struct sockaddr that
+ @address represents
+
+
+
+
+ a #GSocketAddress
+
+
+
+
+
+
+
+
+
+ %TRUE if @dest was filled in, %FALSE on error
+
+
+
+
+ a #GSocketAddress
+
+
+
+ a pointer to a memory location that will contain the native
+struct sockaddr
+
+
+
+ the size of @dest. Must be at least as large as
+ g_socket_address_get_native_size()
+
+
+
+
+
+
+
+ #GSocketAddressEnumerator is an enumerator type for #GSocketAddress
+instances. It is returned by enumeration functions such as
+g_socket_connectable_enumerate(), which returns a #GSocketAddressEnumerator
+to list each #GSocketAddress which could be used to connect to that
+#GSocketConnectable.
+
+Enumeration is typically a blocking operation, so the asynchronous methods
+g_socket_address_enumerator_next_async() and
+g_socket_address_enumerator_next_finish() should be used where possible.
+
+Each #GSocketAddressEnumerator can only be enumerated once. Once
+g_socket_address_enumerator_next() has returned %NULL, further
+enumeration with that #GSocketAddressEnumerator is not possible, and it can
+be unreffed.
+
+
+ Retrieves the next #GSocketAddress from @enumerator. Note that this
+may block for some amount of time. (Eg, a #GNetworkAddress may need
+to do a DNS lookup before it can return an address.) Use
+g_socket_address_enumerator_next_async() if you need to avoid
+blocking.
+
+If @enumerator is expected to yield addresses, but for some reason
+is unable to (eg, because of a DNS error), then the first call to
+g_socket_address_enumerator_next() will return an appropriate error
+in *@error. However, if the first call to
+g_socket_address_enumerator_next() succeeds, then any further
+internal errors (other than @cancellable being triggered) will be
+ignored.
+
+
+ a #GSocketAddress (owned by the caller), or %NULL on
+ error (in which case *@error will be set) or if there are no
+ more addresses.
+
+
+
+
+ a #GSocketAddressEnumerator
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Asynchronously retrieves the next #GSocketAddress from @enumerator
+and then calls @callback, which must call
+g_socket_address_enumerator_next_finish() to get the result.
+
+It is an error to call this multiple times before the previous callback has finished.
+
+
+
+
+
+
+ a #GSocketAddressEnumerator
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback to call when the request
+ is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Retrieves the result of a completed call to
+g_socket_address_enumerator_next_async(). See
+g_socket_address_enumerator_next() for more information about
+error handling.
+
+
+ a #GSocketAddress (owned by the caller), or %NULL on
+ error (in which case *@error will be set) or if there are no
+ more addresses.
+
+
+
+
+ a #GSocketAddressEnumerator
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Retrieves the next #GSocketAddress from @enumerator. Note that this
+may block for some amount of time. (Eg, a #GNetworkAddress may need
+to do a DNS lookup before it can return an address.) Use
+g_socket_address_enumerator_next_async() if you need to avoid
+blocking.
+
+If @enumerator is expected to yield addresses, but for some reason
+is unable to (eg, because of a DNS error), then the first call to
+g_socket_address_enumerator_next() will return an appropriate error
+in *@error. However, if the first call to
+g_socket_address_enumerator_next() succeeds, then any further
+internal errors (other than @cancellable being triggered) will be
+ignored.
+
+
+ a #GSocketAddress (owned by the caller), or %NULL on
+ error (in which case *@error will be set) or if there are no
+ more addresses.
+
+
+
+
+ a #GSocketAddressEnumerator
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Asynchronously retrieves the next #GSocketAddress from @enumerator
+and then calls @callback, which must call
+g_socket_address_enumerator_next_finish() to get the result.
+
+It is an error to call this multiple times before the previous callback has finished.
+
+
+
+
+
+
+ a #GSocketAddressEnumerator
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback to call when the request
+ is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Retrieves the result of a completed call to
+g_socket_address_enumerator_next_async(). See
+g_socket_address_enumerator_next() for more information about
+error handling.
+
+
+ a #GSocketAddress (owned by the caller), or %NULL on
+ error (in which case *@error will be set) or if there are no
+ more addresses.
+
+
+
+
+ a #GSocketAddressEnumerator
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+ Class structure for #GSocketAddressEnumerator.
+
+
+
+
+
+
+
+
+ a #GSocketAddress (owned by the caller), or %NULL on
+ error (in which case *@error will be set) or if there are no
+ more addresses.
+
+
+
+
+ a #GSocketAddressEnumerator
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GSocketAddressEnumerator
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback to call when the request
+ is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+
+
+
+
+ a #GSocketAddress (owned by the caller), or %NULL on
+ error (in which case *@error will be set) or if there are no
+ more addresses.
+
+
+
+
+ a #GSocketAddressEnumerator
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #GSocketClient is a lightweight high-level utility class for connecting to
+a network host using a connection oriented socket type.
+
+You create a #GSocketClient object, set any options you want, and then
+call a sync or async connect operation, which returns a #GSocketConnection
+subclass on success.
+
+The type of the #GSocketConnection object returned depends on the type of
+the underlying socket that is in use. For instance, for a TCP/IP connection
+it will be a #GTcpConnection.
+
+As #GSocketClient is a lightweight object, you don't need to cache it. You
+can just create a new one any time you need one.
+
+
+ Creates a new #GSocketClient with the default options.
+
+
+ a #GSocketClient.
+ Free the returned object with g_object_unref().
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Enable proxy protocols to be handled by the application. When the
+indicated proxy protocol is returned by the #GProxyResolver,
+#GSocketClient will consider this protocol as supported but will
+not try to find a #GProxy instance to handle handshaking. The
+application must check for this case by calling
+g_socket_connection_get_remote_address() on the returned
+#GSocketConnection, and seeing if it's a #GProxyAddress of the
+appropriate type, to determine whether or not it needs to handle
+the proxy handshaking itself.
+
+This should be used for proxy protocols that are dialects of
+another protocol such as HTTP proxy. It also allows cohabitation of
+proxy protocols that are reused between protocols. A good example
+is HTTP. It can be used to proxy HTTP, FTP and Gopher and can also
+be use as generic socket proxy through the HTTP CONNECT method.
+
+When the proxy is detected as being an application proxy, TLS handshake
+will be skipped. This is required to let the application do the proxy
+specific handshake.
+
+
+
+
+
+
+ a #GSocketClient
+
+
+
+ The proxy protocol
+
+
+
+
+
+ Tries to resolve the @connectable and make a network connection to it.
+
+Upon a successful connection, a new #GSocketConnection is constructed
+and returned. The caller owns this new object and must drop their
+reference to it when finished with it.
+
+The type of the #GSocketConnection object returned depends on the type of
+the underlying socket that is used. For instance, for a TCP/IP connection
+it will be a #GTcpConnection.
+
+The socket created will be the same family as the address that the
+@connectable resolves to, unless family is set with g_socket_client_set_family()
+or indirectly via g_socket_client_set_local_address(). The socket type
+defaults to %G_SOCKET_TYPE_STREAM but can be set with
+g_socket_client_set_socket_type().
+
+If a local address is specified with g_socket_client_set_local_address() the
+socket will be bound to this address before connecting.
+
+
+ a #GSocketConnection on success, %NULL on error.
+
+
+
+
+ a #GSocketClient.
+
+
+
+ a #GSocketConnectable specifying the remote address.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ This is the asynchronous version of g_socket_client_connect().
+
+You may wish to prefer the asynchronous version even in synchronous
+command line programs because, since 2.60, it implements
+[RFC 8305](https://tools.ietf.org/html/rfc8305) "Happy Eyeballs"
+recommendations to work around long connection timeouts in networks
+where IPv6 is broken by performing an IPv4 connection simultaneously
+without waiting for IPv6 to time out, which is not supported by the
+synchronous call. (This is not an API guarantee, and may change in
+the future.)
+
+When the operation is finished @callback will be
+called. You can then call g_socket_client_connect_finish() to get
+the result of the operation.
+
+
+
+
+
+
+ a #GSocketClient
+
+
+
+ a #GSocketConnectable specifying the remote address.
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ a #GAsyncReadyCallback
+
+
+
+ user data for the callback
+
+
+
+
+
+ Finishes an async connect operation. See g_socket_client_connect_async()
+
+
+ a #GSocketConnection on success, %NULL on error.
+
+
+
+
+ a #GSocketClient.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ This is a helper function for g_socket_client_connect().
+
+Attempts to create a TCP connection to the named host.
+
+@host_and_port may be in any of a number of recognized formats; an IPv6
+address, an IPv4 address, or a domain name (in which case a DNS
+lookup is performed). Quoting with [] is supported for all address
+types. A port override may be specified in the usual way with a
+colon. Ports may be given as decimal numbers or symbolic names (in
+which case an /etc/services lookup is performed).
+
+If no port override is given in @host_and_port then @default_port will be
+used as the port number to connect to.
+
+In general, @host_and_port is expected to be provided by the user (allowing
+them to give the hostname, and a port override if necessary) and
+@default_port is expected to be provided by the application.
+
+In the case that an IP address is given, a single connection
+attempt is made. In the case that a name is given, multiple
+connection attempts may be made, in turn and according to the
+number of address records in DNS, until a connection succeeds.
+
+Upon a successful connection, a new #GSocketConnection is constructed
+and returned. The caller owns this new object and must drop their
+reference to it when finished with it.
+
+In the event of any failure (DNS error, service not found, no hosts
+connectable) %NULL is returned and @error (if non-%NULL) is set
+accordingly.
+
+
+ a #GSocketConnection on success, %NULL on error.
+
+
+
+
+ a #GSocketClient
+
+
+
+ the name and optionally port of the host to connect to
+
+
+
+ the default port to connect to
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ This is the asynchronous version of g_socket_client_connect_to_host().
+
+When the operation is finished @callback will be
+called. You can then call g_socket_client_connect_to_host_finish() to get
+the result of the operation.
+
+
+
+
+
+
+ a #GSocketClient
+
+
+
+ the name and optionally the port of the host to connect to
+
+
+
+ the default port to connect to
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ a #GAsyncReadyCallback
+
+
+
+ user data for the callback
+
+
+
+
+
+ Finishes an async connect operation. See g_socket_client_connect_to_host_async()
+
+
+ a #GSocketConnection on success, %NULL on error.
+
+
+
+
+ a #GSocketClient.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Attempts to create a TCP connection to a service.
+
+This call looks up the SRV record for @service at @domain for the
+"tcp" protocol. It then attempts to connect, in turn, to each of
+the hosts providing the service until either a connection succeeds
+or there are no hosts remaining.
+
+Upon a successful connection, a new #GSocketConnection is constructed
+and returned. The caller owns this new object and must drop their
+reference to it when finished with it.
+
+In the event of any failure (DNS error, service not found, no hosts
+connectable) %NULL is returned and @error (if non-%NULL) is set
+accordingly.
+
+
+ a #GSocketConnection if successful, or %NULL on error
+
+
+
+
+ a #GSocketConnection
+
+
+
+ a domain name
+
+
+
+ the name of the service to connect to
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ This is the asynchronous version of
+g_socket_client_connect_to_service().
+
+
+
+
+
+
+ a #GSocketClient
+
+
+
+ a domain name
+
+
+
+ the name of the service to connect to
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ a #GAsyncReadyCallback
+
+
+
+ user data for the callback
+
+
+
+
+
+ Finishes an async connect operation. See g_socket_client_connect_to_service_async()
+
+
+ a #GSocketConnection on success, %NULL on error.
+
+
+
+
+ a #GSocketClient.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ This is a helper function for g_socket_client_connect().
+
+Attempts to create a TCP connection with a network URI.
+
+@uri may be any valid URI containing an "authority" (hostname/port)
+component. If a port is not specified in the URI, @default_port
+will be used. TLS will be negotiated if #GSocketClient:tls is %TRUE.
+(#GSocketClient does not know to automatically assume TLS for
+certain URI schemes.)
+
+Using this rather than g_socket_client_connect() or
+g_socket_client_connect_to_host() allows #GSocketClient to
+determine when to use application-specific proxy protocols.
+
+Upon a successful connection, a new #GSocketConnection is constructed
+and returned. The caller owns this new object and must drop their
+reference to it when finished with it.
+
+In the event of any failure (DNS error, service not found, no hosts
+connectable) %NULL is returned and @error (if non-%NULL) is set
+accordingly.
+
+
+ a #GSocketConnection on success, %NULL on error.
+
+
+
+
+ a #GSocketClient
+
+
+
+ A network URI
+
+
+
+ the default port to connect to
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ This is the asynchronous version of g_socket_client_connect_to_uri().
+
+When the operation is finished @callback will be
+called. You can then call g_socket_client_connect_to_uri_finish() to get
+the result of the operation.
+
+
+
+
+
+
+ a #GSocketClient
+
+
+
+ a network uri
+
+
+
+ the default port to connect to
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ a #GAsyncReadyCallback
+
+
+
+ user data for the callback
+
+
+
+
+
+ Finishes an async connect operation. See g_socket_client_connect_to_uri_async()
+
+
+ a #GSocketConnection on success, %NULL on error.
+
+
+
+
+ a #GSocketClient.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Gets the proxy enable state; see g_socket_client_set_enable_proxy()
+
+
+ whether proxying is enabled
+
+
+
+
+ a #GSocketClient.
+
+
+
+
+
+ Gets the socket family of the socket client.
+
+See g_socket_client_set_family() for details.
+
+
+ a #GSocketFamily
+
+
+
+
+ a #GSocketClient.
+
+
+
+
+
+ Gets the local address of the socket client.
+
+See g_socket_client_set_local_address() for details.
+
+
+ a #GSocketAddress or %NULL. Do not free.
+
+
+
+
+ a #GSocketClient.
+
+
+
+
+
+ Gets the protocol name type of the socket client.
+
+See g_socket_client_set_protocol() for details.
+
+
+ a #GSocketProtocol
+
+
+
+
+ a #GSocketClient
+
+
+
+
+
+ Gets the #GProxyResolver being used by @client. Normally, this will
+be the resolver returned by g_proxy_resolver_get_default(), but you
+can override it with g_socket_client_set_proxy_resolver().
+
+
+ The #GProxyResolver being used by
+ @client.
+
+
+
+
+ a #GSocketClient.
+
+
+
+
+
+ Gets the socket type of the socket client.
+
+See g_socket_client_set_socket_type() for details.
+
+
+ a #GSocketFamily
+
+
+
+
+ a #GSocketClient.
+
+
+
+
+
+ Gets the I/O timeout time for sockets created by @client.
+
+See g_socket_client_set_timeout() for details.
+
+
+ the timeout in seconds
+
+
+
+
+ a #GSocketClient
+
+
+
+
+
+ Gets whether @client creates TLS connections. See
+g_socket_client_set_tls() for details.
+
+
+ whether @client uses TLS
+
+
+
+
+ a #GSocketClient.
+
+
+
+
+
+ Gets the TLS validation flags used creating TLS connections via
+@client.
+
+This function does not work as originally designed and is impossible
+to use correctly. See #GSocketClient:tls-validation-flags for more
+information.
+ Do not attempt to ignore validation errors.
+
+
+ the TLS validation flags
+
+
+
+
+ a #GSocketClient.
+
+
+
+
+
+ Sets whether or not @client attempts to make connections via a
+proxy server. When enabled (the default), #GSocketClient will use a
+#GProxyResolver to determine if a proxy protocol such as SOCKS is
+needed, and automatically do the necessary proxy negotiation.
+
+See also g_socket_client_set_proxy_resolver().
+
+
+
+
+
+
+ a #GSocketClient.
+
+
+
+ whether to enable proxies
+
+
+
+
+
+ Sets the socket family of the socket client.
+If this is set to something other than %G_SOCKET_FAMILY_INVALID
+then the sockets created by this object will be of the specified
+family.
+
+This might be useful for instance if you want to force the local
+connection to be an ipv4 socket, even though the address might
+be an ipv6 mapped to ipv4 address.
+
+
+
+
+
+
+ a #GSocketClient.
+
+
+
+ a #GSocketFamily
+
+
+
+
+
+ Sets the local address of the socket client.
+The sockets created by this object will bound to the
+specified address (if not %NULL) before connecting.
+
+This is useful if you want to ensure that the local
+side of the connection is on a specific port, or on
+a specific interface.
+
+
+
+
+
+
+ a #GSocketClient.
+
+
+
+ a #GSocketAddress, or %NULL
+
+
+
+
+
+ Sets the protocol of the socket client.
+The sockets created by this object will use of the specified
+protocol.
+
+If @protocol is %G_SOCKET_PROTOCOL_DEFAULT that means to use the default
+protocol for the socket family and type.
+
+
+
+
+
+
+ a #GSocketClient.
+
+
+
+ a #GSocketProtocol
+
+
+
+
+
+ Overrides the #GProxyResolver used by @client. You can call this if
+you want to use specific proxies, rather than using the system
+default proxy settings.
+
+Note that whether or not the proxy resolver is actually used
+depends on the setting of #GSocketClient:enable-proxy, which is not
+changed by this function (but which is %TRUE by default)
+
+
+
+
+
+
+ a #GSocketClient.
+
+
+
+ a #GProxyResolver, or %NULL for the
+ default.
+
+
+
+
+
+ Sets the socket type of the socket client.
+The sockets created by this object will be of the specified
+type.
+
+It doesn't make sense to specify a type of %G_SOCKET_TYPE_DATAGRAM,
+as GSocketClient is used for connection oriented services.
+
+
+
+
+
+
+ a #GSocketClient.
+
+
+
+ a #GSocketType
+
+
+
+
+
+ Sets the I/O timeout for sockets created by @client. @timeout is a
+time in seconds, or 0 for no timeout (the default).
+
+The timeout value affects the initial connection attempt as well,
+so setting this may cause calls to g_socket_client_connect(), etc,
+to fail with %G_IO_ERROR_TIMED_OUT.
+
+
+
+
+
+
+ a #GSocketClient.
+
+
+
+ the timeout
+
+
+
+
+
+ Sets whether @client creates TLS (aka SSL) connections. If @tls is
+%TRUE, @client will wrap its connections in a #GTlsClientConnection
+and perform a TLS handshake when connecting.
+
+Note that since #GSocketClient must return a #GSocketConnection,
+but #GTlsClientConnection is not a #GSocketConnection, this
+actually wraps the resulting #GTlsClientConnection in a
+#GTcpWrapperConnection when returning it. You can use
+g_tcp_wrapper_connection_get_base_io_stream() on the return value
+to extract the #GTlsClientConnection.
+
+If you need to modify the behavior of the TLS handshake (eg, by
+setting a client-side certificate to use, or connecting to the
+#GTlsConnection::accept-certificate signal), you can connect to
+@client's #GSocketClient::event signal and wait for it to be
+emitted with %G_SOCKET_CLIENT_TLS_HANDSHAKING, which will give you
+a chance to see the #GTlsClientConnection before the handshake
+starts.
+
+
+
+
+
+
+ a #GSocketClient.
+
+
+
+ whether to use TLS
+
+
+
+
+
+ Sets the TLS validation flags used when creating TLS connections
+via @client. The default value is %G_TLS_CERTIFICATE_VALIDATE_ALL.
+
+This function does not work as originally designed and is impossible
+to use correctly. See #GSocketClient:tls-validation-flags for more
+information.
+ Do not attempt to ignore validation errors.
+
+
+
+
+
+
+ a #GSocketClient.
+
+
+
+ the validation flags
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The proxy resolver to use
+
+
+
+
+
+
+
+
+
+ The TLS validation flags used when creating TLS connections. The
+default value is %G_TLS_CERTIFICATE_VALIDATE_ALL.
+
+GLib guarantees that if certificate verification fails, at least one
+flag will be set, but it does not guarantee that all possible flags
+will be set. Accordingly, you may not safely decide to ignore any
+particular type of error. For example, it would be incorrect to mask
+%G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates,
+because this could potentially be the only error flag set even if
+other problems exist with the certificate. Therefore, there is no
+safe way to use this property. This is not a horrible problem,
+though, because you should not be attempting to ignore validation
+errors anyway. If you really must ignore TLS certificate errors,
+connect to the #GSocketClient::event signal, wait for it to be
+emitted with %G_SOCKET_CLIENT_TLS_HANDSHAKING, and use that to
+connect to #GTlsConnection::accept-certificate.
+ Do not attempt to ignore validation errors.
+
+
+
+
+
+
+
+
+
+
+
+
+ Emitted when @client's activity on @connectable changes state.
+Among other things, this can be used to provide progress
+information about a network connection in the UI. The meanings of
+the different @event values are as follows:
+
+- %G_SOCKET_CLIENT_RESOLVING: @client is about to look up @connectable
+ in DNS. @connection will be %NULL.
+
+- %G_SOCKET_CLIENT_RESOLVED: @client has successfully resolved
+ @connectable in DNS. @connection will be %NULL.
+
+- %G_SOCKET_CLIENT_CONNECTING: @client is about to make a connection
+ to a remote host; either a proxy server or the destination server
+ itself. @connection is the #GSocketConnection, which is not yet
+ connected. Since GLib 2.40, you can access the remote
+ address via g_socket_connection_get_remote_address().
+
+- %G_SOCKET_CLIENT_CONNECTED: @client has successfully connected
+ to a remote host. @connection is the connected #GSocketConnection.
+
+- %G_SOCKET_CLIENT_PROXY_NEGOTIATING: @client is about to negotiate
+ with a proxy to get it to connect to @connectable. @connection is
+ the #GSocketConnection to the proxy server.
+
+- %G_SOCKET_CLIENT_PROXY_NEGOTIATED: @client has negotiated a
+ connection to @connectable through a proxy server. @connection is
+ the stream returned from g_proxy_connect(), which may or may not
+ be a #GSocketConnection.
+
+- %G_SOCKET_CLIENT_TLS_HANDSHAKING: @client is about to begin a TLS
+ handshake. @connection is a #GTlsClientConnection.
+
+- %G_SOCKET_CLIENT_TLS_HANDSHAKED: @client has successfully completed
+ the TLS handshake. @connection is a #GTlsClientConnection.
+
+- %G_SOCKET_CLIENT_COMPLETE: @client has either successfully connected
+ to @connectable (in which case @connection is the #GSocketConnection
+ that it will be returning to the caller) or has failed (in which
+ case @connection is %NULL and the client is about to return an error).
+
+Each event except %G_SOCKET_CLIENT_COMPLETE may be emitted
+multiple times (or not at all) for a given connectable (in
+particular, if @client ends up attempting to connect to more than
+one address). However, if @client emits the #GSocketClient::event
+signal at all for a given connectable, then it will always emit
+it with %G_SOCKET_CLIENT_COMPLETE when it is done.
+
+Note that there may be additional #GSocketClientEvent values in
+the future; unrecognized @event values should be ignored.
+
+
+
+
+
+ the event that is occurring
+
+
+
+ the #GSocketConnectable that @event is occurring on
+
+
+
+ the current representation of the connection
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Describes an event occurring on a #GSocketClient. See the
+#GSocketClient::event signal for more details.
+
+Additional values may be added to this type in the future.
+
+ The client is doing a DNS lookup.
+
+
+ The client has completed a DNS lookup.
+
+
+ The client is connecting to a remote
+ host (either a proxy or the destination server).
+
+
+ The client has connected to a remote
+ host.
+
+
+ The client is negotiating
+ with a proxy to connect to the destination server.
+
+
+ The client has negotiated
+ with the proxy server.
+
+
+ The client is performing a
+ TLS handshake.
+
+
+ The client has performed a
+ TLS handshake.
+
+
+ The client is done with a particular
+ #GSocketConnectable.
+
+
+
+
+
+
+ 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.
+
+|[<!-- language="C" -->
+MyConnectionType *
+connect_to_host (const char *hostname,
+ guint16 port,
+ GCancellable *cancellable,
+ GError **error)
+{
+ MyConnection *conn = NULL;
+ GSocketConnectable *addr;
+ GSocketAddressEnumerator *enumerator;
+ GSocketAddress *sockaddr;
+ GError *conn_error = NULL;
+
+ addr = g_network_address_new (hostname, port);
+ enumerator = g_socket_connectable_enumerate (addr);
+ g_object_unref (addr);
+
+ // Try each sockaddr until we succeed. Record the first connection error,
+ // but not any further ones (since they'll probably be basically the same
+ // as the first).
+ while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error))
+ {
+ conn = connect_to_sockaddr (sockaddr, conn_error ? NULL : &conn_error);
+ g_object_unref (sockaddr);
+ }
+ g_object_unref (enumerator);
+
+ if (conn)
+ {
+ if (conn_error)
+ {
+ // We couldn't connect to the first address, but we succeeded
+ // in connecting to a later address.
+ g_error_free (conn_error);
+ }
+ return conn;
+ }
+ else if (error)
+ {
+ /// Either initial lookup failed, or else the caller cancelled us.
+ if (conn_error)
+ g_error_free (conn_error);
+ return NULL;
+ }
+ else
+ {
+ g_error_propagate (error, conn_error);
+ return NULL;
+ }
+}
+]|
+
+
+ Creates a #GSocketAddressEnumerator for @connectable.
+
+
+ a new #GSocketAddressEnumerator.
+
+
+
+
+ a #GSocketConnectable
+
+
+
+
+
+ Creates a #GSocketAddressEnumerator for @connectable that will
+return a #GProxyAddress for each of its addresses that you must connect
+to via a proxy.
+
+If @connectable does not implement
+g_socket_connectable_proxy_enumerate(), this will fall back to
+calling g_socket_connectable_enumerate().
+
+
+ a new #GSocketAddressEnumerator.
+
+
+
+
+ a #GSocketConnectable
+
+
+
+
+
+ Format a #GSocketConnectable as a string. This is a human-readable format for
+use in debugging output, and is not a stable serialization format. It is not
+suitable for use in user interfaces as it exposes too much information for a
+user.
+
+If the #GSocketConnectable implementation does not support string formatting,
+the implementation’s type name will be returned as a fallback.
+
+
+ the formatted string
+
+
+
+
+ a #GSocketConnectable
+
+
+
+
+
+ Creates a #GSocketAddressEnumerator for @connectable.
+
+
+ a new #GSocketAddressEnumerator.
+
+
+
+
+ a #GSocketConnectable
+
+
+
+
+
+ Creates a #GSocketAddressEnumerator for @connectable that will
+return a #GProxyAddress for each of its addresses that you must connect
+to via a proxy.
+
+If @connectable does not implement
+g_socket_connectable_proxy_enumerate(), this will fall back to
+calling g_socket_connectable_enumerate().
+
+
+ a new #GSocketAddressEnumerator.
+
+
+
+
+ a #GSocketConnectable
+
+
+
+
+
+ Format a #GSocketConnectable as a string. This is a human-readable format for
+use in debugging output, and is not a stable serialization format. It is not
+suitable for use in user interfaces as it exposes too much information for a
+user.
+
+If the #GSocketConnectable implementation does not support string formatting,
+the implementation’s type name will be returned as a fallback.
+
+
+ the formatted string
+
+
+
+
+ a #GSocketConnectable
+
+
+
+
+
+
+ Provides an interface for returning a #GSocketAddressEnumerator
+and #GProxyAddressEnumerator
+
+
+ The parent interface.
+
+
+
+
+
+
+ a new #GSocketAddressEnumerator.
+
+
+
+
+ a #GSocketConnectable
+
+
+
+
+
+
+
+
+
+ a new #GSocketAddressEnumerator.
+
+
+
+
+ a #GSocketConnectable
+
+
+
+
+
+
+
+
+
+ the formatted string
+
+
+
+
+ a #GSocketConnectable
+
+
+
+
+
+
+
+ #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().
+
+To close a #GSocketConnection, use g_io_stream_close(). Closing both
+substreams of the #GIOStream separately will not close the underlying
+#GSocket.
+
+
+ Looks up the #GType to be used when creating socket connections on
+sockets with the specified @family, @type and @protocol_id.
+
+If no type is registered, the #GSocketConnection base type is returned.
+
+
+ a #GType
+
+
+
+
+ a #GSocketFamily
+
+
+
+ a #GSocketType
+
+
+
+ a protocol id
+
+
+
+
+
+ Looks up the #GType to be used when creating socket connections on
+sockets with the specified @family, @type and @protocol.
+
+If no type is registered, the #GSocketConnection base type is returned.
+
+
+
+
+
+
+ a #GType, inheriting from %G_TYPE_SOCKET_CONNECTION
+
+
+
+ a #GSocketFamily
+
+
+
+ a #GSocketType
+
+
+
+ a protocol id
+
+
+
+
+
+ Connect @connection to the specified remote address.
+
+
+ %TRUE if the connection succeeded, %FALSE on error
+
+
+
+
+ a #GSocketConnection
+
+
+
+ a #GSocketAddress specifying the remote address.
+
+
+
+ a %GCancellable or %NULL
+
+
+
+
+
+ Asynchronously connect @connection to the specified remote address.
+
+This clears the #GSocket:blocking flag on @connection's underlying
+socket if it is currently set.
+
+Use g_socket_connection_connect_finish() to retrieve the result.
+
+
+
+
+
+
+ a #GSocketConnection
+
+
+
+ a #GSocketAddress specifying the remote address.
+
+
+
+ a %GCancellable or %NULL
+
+
+
+ a #GAsyncReadyCallback
+
+
+
+ user data for the callback
+
+
+
+
+
+ Gets the result of a g_socket_connection_connect_async() call.
+
+
+ %TRUE if the connection succeeded, %FALSE on error
+
+
+
+
+ a #GSocketConnection
+
+
+
+ the #GAsyncResult
+
+
+
+
+
+ Try to get the local address of a socket connection.
+
+
+ a #GSocketAddress or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GSocketConnection
+
+
+
+
+
+ Try to get the remote address of a socket connection.
+
+Since GLib 2.40, when used with g_socket_client_connect() or
+g_socket_client_connect_async(), during emission of
+%G_SOCKET_CLIENT_CONNECTING, this function will return the remote
+address that will be used for the connection. This allows
+applications to print e.g. "Connecting to example.com
+(10.42.77.3)...".
+
+
+ a #GSocketAddress or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GSocketConnection
+
+
+
+
+
+ Gets the underlying #GSocket object of the connection.
+This can be useful if you want to do something unusual on it
+not supported by the #GSocketConnection APIs.
+
+
+ a #GSocket or %NULL on error.
+
+
+
+
+ a #GSocketConnection
+
+
+
+
+
+ Checks if @connection is connected. This is equivalent to calling
+g_socket_is_connected() on @connection's underlying #GSocket.
+
+
+ whether @connection is connected
+
+
+
+
+ a #GSocketConnection
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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 descriptor 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.
+
+
+ Tries to deserialize a socket control message of a given
+@level and @type. This will ask all known (to GType) subclasses
+of #GSocketControlMessage if they can understand this kind
+of message and if so deserialize it into a #GSocketControlMessage.
+
+If there is no implementation for this kind of control message, %NULL
+will be returned.
+
+
+ the deserialized message or %NULL
+
+
+
+
+ a socket level
+
+
+
+ a socket control message type for the given @level
+
+
+
+ the size of the data in bytes
+
+
+
+ pointer to the message data
+
+
+
+
+
+
+
+ Returns the "level" (i.e. the originating protocol) of the control message.
+This is often SOL_SOCKET.
+
+
+ an integer describing the level
+
+
+
+
+ a #GSocketControlMessage
+
+
+
+
+
+ Returns the space required for the control message, not including
+headers or alignment.
+
+
+ The number of bytes required.
+
+
+
+
+ a #GSocketControlMessage
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Converts the data in the message to bytes placed in the
+message.
+
+@data is guaranteed to have enough space to fit the size
+returned by g_socket_control_message_get_size() on this
+object.
+
+
+
+
+
+
+ a #GSocketControlMessage
+
+
+
+ A buffer to write data to
+
+
+
+
+
+ Returns the "level" (i.e. the originating protocol) of the control message.
+This is often SOL_SOCKET.
+
+
+ an integer describing the level
+
+
+
+
+ a #GSocketControlMessage
+
+
+
+
+
+ Returns the protocol specific type of the control message.
+For instance, for UNIX fd passing this would be SCM_RIGHTS.
+
+
+ an integer describing the type of control message
+
+
+
+
+ a #GSocketControlMessage
+
+
+
+
+
+ Returns the space required for the control message, not including
+headers or alignment.
+
+
+ The number of bytes required.
+
+
+
+
+ a #GSocketControlMessage
+
+
+
+
+
+ Converts the data in the message to bytes placed in the
+message.
+
+@data is guaranteed to have enough space to fit the size
+returned by g_socket_control_message_get_size() on this
+object.
+
+
+
+
+
+
+ a #GSocketControlMessage
+
+
+
+ A buffer to write data to
+
+
+
+
+
+
+
+
+
+
+
+
+ Class structure for #GSocketControlMessage.
+
+
+
+
+
+
+
+
+ The number of bytes required.
+
+
+
+
+ a #GSocketControlMessage
+
+
+
+
+
+
+
+
+
+ an integer describing the level
+
+
+
+
+ a #GSocketControlMessage
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GSocketControlMessage
+
+
+
+ A buffer to write data to
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The protocol family of a #GSocketAddress. (These values are
+identical to the system defines %AF_INET, %AF_INET6 and %AF_UNIX,
+if available.)
+
+ no address family
+
+
+ the UNIX domain family
+
+
+ the IPv4 family
+
+
+ the IPv6 family
+
+
+
+ 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.
+
+Add addresses and ports to listen on using g_socket_listener_add_address()
+and g_socket_listener_add_inet_port(). These will be listened on until
+g_socket_listener_close() is called. Dropping your final reference to the
+#GSocketListener will not cause g_socket_listener_close() to be called
+implicitly, as some references to the #GSocketListener may be held
+internally.
+
+If you want to implement a network server, also look at #GSocketService
+and #GThreadedSocketService which are subclasses of #GSocketListener
+that make this even easier.
+
+
+ Creates a new #GSocketListener with no sockets to listen for.
+New listeners can be added with e.g. g_socket_listener_add_address()
+or g_socket_listener_add_inet_port().
+
+
+ a new #GSocketListener.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Blocks waiting for a client to connect to any of the sockets added
+to the listener. Returns a #GSocketConnection for the socket that was
+accepted.
+
+If @source_object is not %NULL it will be filled out with the source
+object specified when the corresponding socket or address was added
+to the listener.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ a #GSocketConnection on success, %NULL on error.
+
+
+
+
+ a #GSocketListener
+
+
+
+ location where #GObject pointer will be stored, or %NULL
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ This is the asynchronous version of g_socket_listener_accept().
+
+When the operation is finished @callback will be
+called. You can then call g_socket_listener_accept_finish()
+to get the result of the operation.
+
+
+
+
+
+
+ a #GSocketListener
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ a #GAsyncReadyCallback
+
+
+
+ user data for the callback
+
+
+
+
+
+ Finishes an async accept operation. See g_socket_listener_accept_async()
+
+
+ a #GSocketConnection on success, %NULL on error.
+
+
+
+
+ a #GSocketListener
+
+
+
+ a #GAsyncResult.
+
+
+
+ Optional #GObject identifying this source
+
+
+
+
+
+ Blocks waiting for a client to connect to any of the sockets added
+to the listener. Returns the #GSocket that was accepted.
+
+If you want to accept the high-level #GSocketConnection, not a #GSocket,
+which is often the case, then you should use g_socket_listener_accept()
+instead.
+
+If @source_object is not %NULL it will be filled out with the source
+object specified when the corresponding socket or address was added
+to the listener.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+
+ a #GSocket on success, %NULL on error.
+
+
+
+
+ a #GSocketListener
+
+
+
+ location where #GObject pointer will be stored, or %NULL.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ This is the asynchronous version of g_socket_listener_accept_socket().
+
+When the operation is finished @callback will be
+called. You can then call g_socket_listener_accept_socket_finish()
+to get the result of the operation.
+
+
+
+
+
+
+ a #GSocketListener
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ a #GAsyncReadyCallback
+
+
+
+ user data for the callback
+
+
+
+
+
+ Finishes an async accept operation. See g_socket_listener_accept_socket_async()
+
+
+ a #GSocket on success, %NULL on error.
+
+
+
+
+ a #GSocketListener
+
+
+
+ a #GAsyncResult.
+
+
+
+ Optional #GObject identifying this source
+
+
+
+
+
+ Creates a socket of type @type and protocol @protocol, binds
+it to @address and adds it to the set of sockets we're accepting
+sockets from.
+
+Note that adding an IPv6 address, depending on the platform,
+may or may not result in a listener that also accepts IPv4
+connections. For more deterministic behavior, see
+g_socket_listener_add_inet_port().
+
+@source_object will be passed out in the various calls
+to accept to identify this particular source, which is
+useful if you're listening on multiple addresses and do
+different things depending on what address is connected to.
+
+If successful and @effective_address is non-%NULL then it will
+be set to the address that the binding actually occurred at. This
+is helpful for determining the port number that was used for when
+requesting a binding to port 0 (ie: "any port"). This address, if
+requested, belongs to the caller and must be freed.
+
+Call g_socket_listener_close() to stop listening on @address; this will not
+be done automatically when you drop your final reference to @listener, as
+references may be held internally.
+
+
+ %TRUE on success, %FALSE on error.
+
+
+
+
+ a #GSocketListener
+
+
+
+ a #GSocketAddress
+
+
+
+ a #GSocketType
+
+
+
+ a #GSocketProtocol
+
+
+
+ Optional #GObject identifying this source
+
+
+
+ location to store the address that was bound to, or %NULL.
+
+
+
+
+
+ Listens for TCP connections on any available port number for both
+IPv6 and IPv4 (if each is available).
+
+This is useful if you need to have a socket for incoming connections
+but don't care about the specific port number.
+
+@source_object will be passed out in the various calls
+to accept to identify this particular source, which is
+useful if you're listening on multiple addresses and do
+different things depending on what address is connected to.
+
+
+ the port number, or 0 in case of failure.
+
+
+
+
+ a #GSocketListener
+
+
+
+ Optional #GObject identifying this source
+
+
+
+
+
+ Helper function for g_socket_listener_add_address() that
+creates a TCP/IP socket listening on IPv4 and IPv6 (if
+supported) on the specified port on all interfaces.
+
+@source_object will be passed out in the various calls
+to accept to identify this particular source, which is
+useful if you're listening on multiple addresses and do
+different things depending on what address is connected to.
+
+Call g_socket_listener_close() to stop listening on @port; this will not
+be done automatically when you drop your final reference to @listener, as
+references may be held internally.
+
+
+ %TRUE on success, %FALSE on error.
+
+
+
+
+ a #GSocketListener
+
+
+
+ an IP port number (non-zero)
+
+
+
+ Optional #GObject identifying this source
+
+
+
+
+
+ Adds @socket to the set of sockets that we try to accept
+new clients from. The socket must be bound to a local
+address and listened to.
+
+@source_object will be passed out in the various calls
+to accept to identify this particular source, which is
+useful if you're listening on multiple addresses and do
+different things depending on what address is connected to.
+
+The @socket will not be automatically closed when the @listener is finalized
+unless the listener held the final reference to the socket. Before GLib 2.42,
+the @socket was automatically closed on finalization of the @listener, even
+if references to it were held elsewhere.
+
+
+ %TRUE on success, %FALSE on error.
+
+
+
+
+ a #GSocketListener
+
+
+
+ a listening #GSocket
+
+
+
+ Optional #GObject identifying this source
+
+
+
+
+
+ Closes all the sockets in the listener.
+
+
+
+
+
+
+ a #GSocketListener
+
+
+
+
+
+ Sets the listen backlog on the sockets in the listener. This must be called
+before adding any sockets, addresses or ports to the #GSocketListener (for
+example, by calling g_socket_listener_add_inet_port()) to be effective.
+
+See g_socket_set_listen_backlog() for details
+
+
+
+
+
+
+ a #GSocketListener
+
+
+
+ an integer
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Emitted when @listener's activity on @socket changes state.
+Note that when @listener is used to listen on both IPv4 and
+IPv6, a separate set of signals will be emitted for each, and
+the order they happen in is undefined.
+
+
+
+
+
+ the event that is occurring
+
+
+
+ the #GSocket the event is occurring on
+
+
+
+
+
+
+ Class structure for #GSocketListener.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Describes an event occurring on a #GSocketListener. See the
+#GSocketListener::event signal for more details.
+
+Additional values may be added to this type in the future.
+
+ The listener is about to bind a socket.
+
+
+ The listener has bound a socket.
+
+
+ The listener is about to start
+ listening on this socket.
+
+
+ The listener is now listening on
+ this socket.
+
+
+
+
+
+
+ Flags used in g_socket_receive_message() and g_socket_send_message().
+The flags listed in the enum are some commonly available flags, but the
+values used for them are the same as on the platform, and any other flags
+are passed in/out as is. So to use a platform specific flag, just include
+the right system header and pass in the flag.
+
+ No flags.
+
+
+ Request to send/receive out of band data.
+
+
+ Read data from the socket without removing it from
+ the queue.
+
+
+ Don't use a gateway to send out the packet,
+ only send to hosts on directly connected networks.
+
+
+
+
+
+
+ A protocol identifier is specified when creating a #GSocket, which is a
+family/type specific identifier, where 0 means the default protocol for
+the particular family/type.
+
+This enum contains a set of commonly available and used protocols. You
+can also pass any other identifiers handled by the platform in order to
+use protocols not listed here.
+
+ The protocol type is unknown
+
+
+ The default protocol for the family/type
+
+
+ TCP over IP
+
+
+ UDP over IP
+
+
+ SCTP over IP
+
+
+
+ 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 of the
+[thread-default context][g-main-context-push-thread-default-context]
+of the thread it is created in, and is not
+threadsafe in general. However, the calls to start and stop the
+service are thread-safe so these can be used from threads that
+handle incoming clients.
+
+
+ Creates a new #GSocketService with no sockets to listen for.
+New listeners can be added with e.g. g_socket_listener_add_address()
+or g_socket_listener_add_inet_port().
+
+New services are created active, there is no need to call
+g_socket_service_start(), unless g_socket_service_stop() has been
+called before.
+
+
+ a new #GSocketService.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Check whether the service is active or not. An active
+service will accept new clients that connect, while
+a non-active service will let connecting clients queue
+up until the service is started.
+
+
+ %TRUE if the service is active, %FALSE otherwise
+
+
+
+
+ a #GSocketService
+
+
+
+
+
+ Restarts the service, i.e. start accepting connections
+from the added sockets when the mainloop runs. This only needs
+to be called after the service has been stopped from
+g_socket_service_stop().
+
+This call is thread-safe, so it may be called from a thread
+handling an incoming client request.
+
+
+
+
+
+
+ a #GSocketService
+
+
+
+
+
+ Stops the service, i.e. stops accepting connections
+from the added sockets when the mainloop runs.
+
+This call is thread-safe, so it may be called from a thread
+handling an incoming client request.
+
+Note that this only stops accepting new connections; it does not
+close the listening sockets, and you can call
+g_socket_service_start() again later to begin listening again. To
+close the listening sockets, call g_socket_listener_close(). (This
+will happen automatically when the #GSocketService is finalized.)
+
+This must be called before calling g_socket_listener_close() as
+the socket service will start accepting connections immediately
+when a new socket is added.
+
+
+
+
+
+
+ a #GSocketService
+
+
+
+
+
+ Whether the service is currently accepting connections.
+
+
+
+
+
+
+
+
+
+ The ::incoming signal is emitted when a new incoming connection
+to @service needs to be handled. The handler must initiate the
+handling of @connection, but may not block; in essence,
+asynchronous operations must be used.
+
+@connection will be unreffed once the signal handler returns,
+so you need to ref it yourself if you are planning to use it.
+
+ %TRUE to stop other handlers from being called
+
+
+
+
+ a new #GSocketConnection object
+
+
+
+ the source_object passed to
+ g_socket_listener_add_address()
+
+
+
+
+
+
+ Class structure for #GSocketService.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This is the function type of the callback used for the #GSource
+returned by g_socket_create_source().
+
+
+ it should return %FALSE if the source should be removed.
+
+
+
+
+ the #GSocket
+
+
+
+ the current condition at the source fired.
+
+
+
+ data passed in by the user.
+
+
+
+
+
+ Flags used when creating a #GSocket. Some protocols may not implement
+all the socket types.
+
+ Type unknown or wrong
+
+
+ Reliable connection-based byte streams (e.g. TCP).
+
+
+ Connectionless, unreliable datagram passing.
+ (e.g. UDP)
+
+
+ Reliable connection-based passing of datagrams
+ of fixed maximum length (e.g. SCTP).
+
+
+
+ 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 #GSrvTargets
+for a given service. However, if you are simply planning to connect
+to the remote service, you can use #GNetworkService's
+#GSocketConnectable interface and not need to worry about
+#GSrvTarget at all.
+
+
+ Creates a new #GSrvTarget with the given parameters.
+
+You should not need to use this; normally #GSrvTargets are
+created by #GResolver.
+
+
+ a new #GSrvTarget.
+
+
+
+
+ the host that the service is running on
+
+
+
+ the port that the service is running on
+
+
+
+ the target's priority
+
+
+
+ the target's weight
+
+
+
+
+
+ Copies @target
+
+
+ a copy of @target
+
+
+
+
+ a #GSrvTarget
+
+
+
+
+
+ Frees @target
+
+
+
+
+
+
+ a #GSrvTarget
+
+
+
+
+
+ Gets @target's hostname (in ASCII form; if you are going to present
+this to the user, you should use g_hostname_is_ascii_encoded() to
+check if it contains encoded Unicode segments, and use
+g_hostname_to_unicode() to convert it if it does.)
+
+
+ @target's hostname
+
+
+
+
+ a #GSrvTarget
+
+
+
+
+
+ Gets @target's port
+
+
+ @target's port
+
+
+
+
+ a #GSrvTarget
+
+
+
+
+
+ Gets @target's priority. You should not need to look at this;
+#GResolver already sorts the targets according to the algorithm in
+RFC 2782.
+
+
+ @target's priority
+
+
+
+
+ a #GSrvTarget
+
+
+
+
+
+ Gets @target's weight. You should not need to look at this;
+#GResolver already sorts the targets according to the algorithm in
+RFC 2782.
+
+
+ @target's weight
+
+
+
+
+ a #GSrvTarget
+
+
+
+
+
+ Sorts @targets in place according to the algorithm in RFC 2782.
+
+
+ the head of the sorted list.
+
+
+
+
+
+
+ a #GList of #GSrvTarget
+
+
+
+
+
+
+
+
+ #GStaticResource is an opaque data structure and can only be accessed
+using the following functions.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Finalized a GResource initialized by g_static_resource_init().
+
+This is normally used by code generated by
+[glib-compile-resources][glib-compile-resources]
+and is not typically used by other code.
+
+
+
+
+
+
+ pointer to a static #GStaticResource
+
+
+
+
+
+ Gets the GResource that was registered by a call to g_static_resource_init().
+
+This is normally used by code generated by
+[glib-compile-resources][glib-compile-resources]
+and is not typically used by other code.
+
+
+ a #GResource
+
+
+
+
+ pointer to a static #GStaticResource
+
+
+
+
+
+ Initializes a GResource from static data using a
+GStaticResource.
+
+This is normally used by code generated by
+[glib-compile-resources][glib-compile-resources]
+and is not typically used by other code.
+
+
+
+
+
+
+ pointer to a static #GStaticResource
+
+
+
+
+
+
+ #GSubprocess allows the creation of and interaction with child
+processes.
+
+Processes can be communicated with using standard GIO-style APIs (ie:
+#GInputStream, #GOutputStream). There are GIO-style APIs to wait for
+process termination (ie: cancellable and with an asynchronous
+variant).
+
+There is an API to force a process to terminate, as well as a
+race-free API for sending UNIX signals to a subprocess.
+
+One major advantage that GIO brings over the core GLib library is
+comprehensive API for asynchronous I/O, such
+g_output_stream_splice_async(). This makes GSubprocess
+significantly more powerful and flexible than equivalent APIs in
+some other languages such as the `subprocess.py`
+included with Python. For example, using #GSubprocess one could
+create two child processes, reading standard output from the first,
+processing it, and writing to the input stream of the second, all
+without blocking the main loop.
+
+A powerful g_subprocess_communicate() API is provided similar to the
+`communicate()` method of `subprocess.py`. This enables very easy
+interaction with a subprocess that has been opened with pipes.
+
+#GSubprocess defaults to tight control over the file descriptors open
+in the child process, avoiding dangling-fd issues that are caused by
+a simple fork()/exec(). The only open file descriptors in the
+spawned process are ones that were explicitly specified by the
+#GSubprocess API (unless %G_SUBPROCESS_FLAGS_INHERIT_FDS was
+specified).
+
+#GSubprocess will quickly reap all child processes as they exit,
+avoiding "zombie processes" remaining around for long periods of
+time. g_subprocess_wait() can be used to wait for this to happen,
+but it will happen even without the call being explicitly made.
+
+As a matter of principle, #GSubprocess has no API that accepts
+shell-style space-separated strings. It will, however, match the
+typical shell behaviour of searching the PATH for executables that do
+not contain a directory separator in their name. By default, the `PATH`
+of the current process is used. You can specify
+%G_SUBPROCESS_FLAGS_SEARCH_PATH_FROM_ENVP to use the `PATH` of the
+launcher environment instead.
+
+#GSubprocess attempts to have a very simple API for most uses (ie:
+spawning a subprocess with arguments and support for most typical
+kinds of input and output redirection). See g_subprocess_new(). The
+#GSubprocessLauncher API is provided for more complicated cases
+(advanced types of redirection, environment variable manipulation,
+change of working directory, child setup functions, etc).
+
+A typical use of #GSubprocess will involve calling
+g_subprocess_new(), followed by g_subprocess_wait_async() or
+g_subprocess_wait(). After the process exits, the status can be
+checked using functions such as g_subprocess_get_if_exited() (which
+are similar to the familiar WIFEXITED-style POSIX macros).
+
+
+ Create a new process with the given flags and varargs argument
+list. By default, matching the g_spawn_async() defaults, the
+child's stdin will be set to the system null device, and
+stdout/stderr will be inherited from the parent. You can use
+@flags to control this behavior.
+
+The argument list must be terminated with %NULL.
+
+
+ A newly created #GSubprocess, or %NULL on error (and @error
+ will be set)
+
+
+
+
+ flags that define the behaviour of the subprocess
+
+
+
+ return location for an error, or %NULL
+
+
+
+ first commandline argument to pass to the subprocess
+
+
+
+ more commandline arguments, followed by %NULL
+
+
+
+
+
+ Create a new process with the given flags and argument list.
+
+The argument list is expected to be %NULL-terminated.
+
+
+ A newly created #GSubprocess, or %NULL on error (and @error
+ will be set)
+
+
+
+
+ commandline arguments for the subprocess
+
+
+
+
+
+ flags that define the behaviour of the subprocess
+
+
+
+
+
+ Communicate with the subprocess until it terminates, and all input
+and output has been completed.
+
+If @stdin_buf is given, the subprocess must have been created with
+%G_SUBPROCESS_FLAGS_STDIN_PIPE. The given data is fed to the
+stdin of the subprocess and the pipe is closed (ie: EOF).
+
+At the same time (as not to cause blocking when dealing with large
+amounts of data), if %G_SUBPROCESS_FLAGS_STDOUT_PIPE or
+%G_SUBPROCESS_FLAGS_STDERR_PIPE were used, reads from those
+streams. The data that was read is returned in @stdout and/or
+the @stderr.
+
+If the subprocess was created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE,
+@stdout_buf will contain the data read from stdout. Otherwise, for
+subprocesses not created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE,
+@stdout_buf will be set to %NULL. Similar provisions apply to
+@stderr_buf and %G_SUBPROCESS_FLAGS_STDERR_PIPE.
+
+As usual, any output variable may be given as %NULL to ignore it.
+
+If you desire the stdout and stderr data to be interleaved, create
+the subprocess with %G_SUBPROCESS_FLAGS_STDOUT_PIPE and
+%G_SUBPROCESS_FLAGS_STDERR_MERGE. The merged result will be returned
+in @stdout_buf and @stderr_buf will be set to %NULL.
+
+In case of any error (including cancellation), %FALSE will be
+returned with @error set. Some or all of the stdin data may have
+been written. Any stdout or stderr data that has been read will be
+discarded. None of the out variables (aside from @error) will have
+been set to anything in particular and should not be inspected.
+
+In the case that %TRUE is returned, the subprocess has exited and the
+exit status inspection APIs (eg: g_subprocess_get_if_exited(),
+g_subprocess_get_exit_status()) may be used.
+
+You should not attempt to use any of the subprocess pipes after
+starting this function, since they may be left in strange states,
+even if the operation was cancelled. You should especially not
+attempt to interact with the pipes while the operation is in progress
+(either from another thread or if using the asynchronous version).
+
+
+ %TRUE if successful
+
+
+
+
+ a #GSubprocess
+
+
+
+ data to send to the stdin of the subprocess, or %NULL
+
+
+
+ a #GCancellable
+
+
+
+ data read from the subprocess stdout
+
+
+
+ data read from the subprocess stderr
+
+
+
+
+
+ Asynchronous version of g_subprocess_communicate(). Complete
+invocation with g_subprocess_communicate_finish().
+
+
+
+
+
+
+ Self
+
+
+
+ Input data, or %NULL
+
+
+
+ Cancellable
+
+
+
+ Callback
+
+
+
+ User data
+
+
+
+
+
+ Complete an invocation of g_subprocess_communicate_async().
+
+
+
+
+
+
+ Self
+
+
+
+ Result
+
+
+
+ Return location for stdout data
+
+
+
+ Return location for stderr data
+
+
+
+
+
+ Like g_subprocess_communicate(), but validates the output of the
+process as UTF-8, and returns it as a regular NUL terminated string.
+
+On error, @stdout_buf and @stderr_buf will be set to undefined values and
+should not be used.
+
+
+
+
+
+
+ a #GSubprocess
+
+
+
+ data to send to the stdin of the subprocess, or %NULL
+
+
+
+ a #GCancellable
+
+
+
+ data read from the subprocess stdout
+
+
+
+ data read from the subprocess stderr
+
+
+
+
+
+ Asynchronous version of g_subprocess_communicate_utf8(). Complete
+invocation with g_subprocess_communicate_utf8_finish().
+
+
+
+
+
+
+ Self
+
+
+
+ Input data, or %NULL
+
+
+
+ Cancellable
+
+
+
+ Callback
+
+
+
+ User data
+
+
+
+
+
+ Complete an invocation of g_subprocess_communicate_utf8_async().
+
+
+
+
+
+
+ Self
+
+
+
+ Result
+
+
+
+ Return location for stdout data
+
+
+
+ Return location for stderr data
+
+
+
+
+
+ Use an operating-system specific method to attempt an immediate,
+forceful termination of the process. There is no mechanism to
+determine whether or not the request itself was successful;
+however, you can use g_subprocess_wait() to monitor the status of
+the process after calling this function.
+
+On Unix, this function sends %SIGKILL.
+
+
+
+
+
+
+ a #GSubprocess
+
+
+
+
+
+ Check the exit status of the subprocess, given that it exited
+normally. This is the value passed to the exit() system call or the
+return value from main.
+
+This is equivalent to the system WEXITSTATUS macro.
+
+It is an error to call this function before g_subprocess_wait() and
+unless g_subprocess_get_if_exited() returned %TRUE.
+
+
+ the exit status
+
+
+
+
+ a #GSubprocess
+
+
+
+
+
+ On UNIX, returns the process ID as a decimal string.
+On Windows, returns the result of GetProcessId() also as a string.
+If the subprocess has terminated, this will return %NULL.
+
+
+ the subprocess identifier, or %NULL if the subprocess
+ has terminated
+
+
+
+
+ a #GSubprocess
+
+
+
+
+
+ Check if the given subprocess exited normally (ie: by way of exit()
+or return from main()).
+
+This is equivalent to the system WIFEXITED macro.
+
+It is an error to call this function before g_subprocess_wait() has
+returned.
+
+
+ %TRUE if the case of a normal exit
+
+
+
+
+ a #GSubprocess
+
+
+
+
+
+ Check if the given subprocess terminated in response to a signal.
+
+This is equivalent to the system WIFSIGNALED macro.
+
+It is an error to call this function before g_subprocess_wait() has
+returned.
+
+
+ %TRUE if the case of termination due to a signal
+
+
+
+
+ a #GSubprocess
+
+
+
+
+
+ Gets the raw status code of the process, as from waitpid().
+
+This value has no particular meaning, but it can be used with the
+macros defined by the system headers such as WIFEXITED. It can also
+be used with g_spawn_check_wait_status().
+
+It is more likely that you want to use g_subprocess_get_if_exited()
+followed by g_subprocess_get_exit_status().
+
+It is an error to call this function before g_subprocess_wait() has
+returned.
+
+
+ the (meaningless) waitpid() exit status from the kernel
+
+
+
+
+ a #GSubprocess
+
+
+
+
+
+ Gets the #GInputStream from which to read the stderr output of
+@subprocess.
+
+The process must have been created with %G_SUBPROCESS_FLAGS_STDERR_PIPE,
+otherwise %NULL will be returned.
+
+
+ the stderr pipe
+
+
+
+
+ a #GSubprocess
+
+
+
+
+
+ Gets the #GOutputStream that you can write to in order to give data
+to the stdin of @subprocess.
+
+The process must have been created with %G_SUBPROCESS_FLAGS_STDIN_PIPE and
+not %G_SUBPROCESS_FLAGS_STDIN_INHERIT, otherwise %NULL will be returned.
+
+
+ the stdout pipe
+
+
+
+
+ a #GSubprocess
+
+
+
+
+
+ Gets the #GInputStream from which to read the stdout output of
+@subprocess.
+
+The process must have been created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE,
+otherwise %NULL will be returned.
+
+
+ the stdout pipe
+
+
+
+
+ a #GSubprocess
+
+
+
+
+
+ Checks if the process was "successful". A process is considered
+successful if it exited cleanly with an exit status of 0, either by
+way of the exit() system call or return from main().
+
+It is an error to call this function before g_subprocess_wait() has
+returned.
+
+
+ %TRUE if the process exited cleanly with a exit status of 0
+
+
+
+
+ a #GSubprocess
+
+
+
+
+
+ Get the signal number that caused the subprocess to terminate, given
+that it terminated due to a signal.
+
+This is equivalent to the system WTERMSIG macro.
+
+It is an error to call this function before g_subprocess_wait() and
+unless g_subprocess_get_if_signaled() returned %TRUE.
+
+
+ the signal causing termination
+
+
+
+
+ a #GSubprocess
+
+
+
+
+
+ Sends the UNIX signal @signal_num to the subprocess, if it is still
+running.
+
+This API is race-free. If the subprocess has terminated, it will not
+be signalled.
+
+This API is not available on Windows.
+
+
+
+
+
+
+ a #GSubprocess
+
+
+
+ the signal number to send
+
+
+
+
+
+ Synchronously wait for the subprocess to terminate.
+
+After the process terminates you can query its exit status with
+functions such as g_subprocess_get_if_exited() and
+g_subprocess_get_exit_status().
+
+This function does not fail in the case of the subprocess having
+abnormal termination. See g_subprocess_wait_check() for that.
+
+Cancelling @cancellable doesn't kill the subprocess. Call
+g_subprocess_force_exit() if it is desirable.
+
+
+ %TRUE on success, %FALSE if @cancellable was cancelled
+
+
+
+
+ a #GSubprocess
+
+
+
+ a #GCancellable
+
+
+
+
+
+ Wait for the subprocess to terminate.
+
+This is the asynchronous version of g_subprocess_wait().
+
+
+
+
+
+
+ a #GSubprocess
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ a #GAsyncReadyCallback to call when the operation is complete
+
+
+
+ user_data for @callback
+
+
+
+
+
+ Combines g_subprocess_wait() with g_spawn_check_wait_status().
+
+
+ %TRUE on success, %FALSE if process exited abnormally, or
+@cancellable was cancelled
+
+
+
+
+ a #GSubprocess
+
+
+
+ a #GCancellable
+
+
+
+
+
+ Combines g_subprocess_wait_async() with g_spawn_check_wait_status().
+
+This is the asynchronous version of g_subprocess_wait_check().
+
+
+
+
+
+
+ a #GSubprocess
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ a #GAsyncReadyCallback to call when the operation is complete
+
+
+
+ user_data for @callback
+
+
+
+
+
+ Collects the result of a previous call to
+g_subprocess_wait_check_async().
+
+
+ %TRUE if successful, or %FALSE with @error set
+
+
+
+
+ a #GSubprocess
+
+
+
+ the #GAsyncResult passed to your #GAsyncReadyCallback
+
+
+
+
+
+ Collects the result of a previous call to
+g_subprocess_wait_async().
+
+
+ %TRUE if successful, or %FALSE with @error set
+
+
+
+
+ a #GSubprocess
+
+
+
+ the #GAsyncResult passed to your #GAsyncReadyCallback
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Flags to define the behaviour of a #GSubprocess.
+
+Note that the default for stdin is to redirect from `/dev/null`. For
+stdout and stderr the default are for them to inherit the
+corresponding descriptor from the calling process.
+
+Note that it is a programmer error to mix 'incompatible' flags. For
+example, you may not request both %G_SUBPROCESS_FLAGS_STDOUT_PIPE and
+%G_SUBPROCESS_FLAGS_STDOUT_SILENCE.
+
+ No flags.
+
+
+ create a pipe for the stdin of the
+ spawned process that can be accessed with
+ g_subprocess_get_stdin_pipe().
+
+
+ stdin is inherited from the
+ calling process.
+
+
+ create a pipe for the stdout of the
+ spawned process that can be accessed with
+ g_subprocess_get_stdout_pipe().
+
+
+ silence the stdout of the spawned
+ process (ie: redirect to `/dev/null`).
+
+
+ create a pipe for the stderr of the
+ spawned process that can be accessed with
+ g_subprocess_get_stderr_pipe().
+
+
+ silence the stderr of the spawned
+ process (ie: redirect to `/dev/null`).
+
+
+ merge the stderr of the spawned
+ process with whatever the stdout happens to be. This is a good way
+ of directing both streams to a common log file, for example.
+
+
+ spawned processes will inherit the
+ file descriptors of their parent, unless those descriptors have
+ been explicitly marked as close-on-exec. This flag has no effect
+ over the "standard" file descriptors (stdin, stdout, stderr).
+
+
+ if path searching is
+ needed when spawning the subprocess, use the `PATH` in the launcher
+ environment. (Since: 2.72)
+
+
+
+ This class contains a set of options for launching child processes,
+such as where its standard input and output will be directed, the
+argument list, the environment, and more.
+
+While the #GSubprocess class has high level functions covering
+popular cases, use of this class allows access to more advanced
+options. It can also be used to launch multiple subprocesses with
+a similar configuration.
+
+ Creates a new #GSubprocessLauncher.
+
+The launcher is created with the default options. A copy of the
+environment of the calling process is made at the time of this call
+and will be used as the environment that the process is launched in.
+
+
+
+
+
+
+ #GSubprocessFlags
+
+
+
+
+
+ Closes all the file descriptors previously passed to the object with
+g_subprocess_launcher_take_fd(), g_subprocess_launcher_take_stderr_fd(), etc.
+
+After calling this method, any subsequent calls to g_subprocess_launcher_spawn() or g_subprocess_launcher_spawnv() will
+return %G_IO_ERROR_CLOSED. This method is idempotent if
+called more than once.
+
+This function is called automatically when the #GSubprocessLauncher
+is disposed, but is provided separately so that garbage collected
+language bindings can call it earlier to guarantee when FDs are closed.
+
+
+
+
+
+
+ a #GSubprocessLauncher
+
+
+
+
+
+ Returns the value of the environment variable @variable in the
+environment of processes launched from this launcher.
+
+On UNIX, the returned string can be an arbitrary byte string.
+On Windows, it will be UTF-8.
+
+
+ the value of the environment variable,
+ %NULL if unset
+
+
+
+
+ a #GSubprocessLauncher
+
+
+
+ the environment variable to get
+
+
+
+
+
+ Sets up a child setup function.
+
+The child setup function will be called after fork() but before
+exec() on the child's side.
+
+@destroy_notify will not be automatically called on the child's side
+of the fork(). It will only be called when the last reference on the
+#GSubprocessLauncher is dropped or when a new child setup function is
+given.
+
+%NULL can be given as @child_setup to disable the functionality.
+
+Child setup functions are only available on UNIX.
+
+
+
+
+
+
+ a #GSubprocessLauncher
+
+
+
+ a #GSpawnChildSetupFunc to use as the child setup function
+
+
+
+ user data for @child_setup
+
+
+
+ a #GDestroyNotify for @user_data
+
+
+
+
+
+ Sets the current working directory that processes will be launched
+with.
+
+By default processes are launched with the current working directory
+of the launching process at the time of launch.
+
+
+
+
+
+
+ a #GSubprocessLauncher
+
+
+
+ the cwd for launched processes
+
+
+
+
+
+ Replace the entire environment of processes launched from this
+launcher with the given 'environ' variable.
+
+Typically you will build this variable by using g_listenv() to copy
+the process 'environ' and using the functions g_environ_setenv(),
+g_environ_unsetenv(), etc.
+
+As an alternative, you can use g_subprocess_launcher_setenv(),
+g_subprocess_launcher_unsetenv(), etc.
+
+Pass an empty array to set an empty environment. Pass %NULL to inherit the
+parent process’ environment. As of GLib 2.54, the parent process’ environment
+will be copied when g_subprocess_launcher_set_environ() is called.
+Previously, it was copied when the subprocess was executed. This means the
+copied environment may now be modified (using g_subprocess_launcher_setenv(),
+etc.) before launching the subprocess.
+
+On UNIX, all strings in this array can be arbitrary byte strings.
+On Windows, they should be in UTF-8.
+
+
+
+
+
+
+ a #GSubprocessLauncher
+
+
+
+
+ the replacement environment
+
+
+
+
+
+
+
+ Sets the flags on the launcher.
+
+The default flags are %G_SUBPROCESS_FLAGS_NONE.
+
+You may not set flags that specify conflicting options for how to
+handle a particular stdio stream (eg: specifying both
+%G_SUBPROCESS_FLAGS_STDIN_PIPE and
+%G_SUBPROCESS_FLAGS_STDIN_INHERIT).
+
+You may also not set a flag that conflicts with a previous call to a
+function like g_subprocess_launcher_set_stdin_file_path() or
+g_subprocess_launcher_take_stdout_fd().
+
+
+
+
+
+
+ a #GSubprocessLauncher
+
+
+
+ #GSubprocessFlags
+
+
+
+
+
+ Sets the file path to use as the stderr for spawned processes.
+
+If @path is %NULL then any previously given path is unset.
+
+The file will be created or truncated when the process is spawned, as
+would be the case if using '2>' at the shell.
+
+If you want to send both stdout and stderr to the same file then use
+%G_SUBPROCESS_FLAGS_STDERR_MERGE.
+
+You may not set a stderr file path if a stderr fd is already set or
+if the launcher flags contain any flags directing stderr elsewhere.
+
+This feature is only available on UNIX.
+
+
+
+
+
+
+ a #GSubprocessLauncher
+
+
+
+ a filename or %NULL
+
+
+
+
+
+ Sets the file path to use as the stdin for spawned processes.
+
+If @path is %NULL then any previously given path is unset.
+
+The file must exist or spawning the process will fail.
+
+You may not set a stdin file path if a stdin fd is already set or if
+the launcher flags contain any flags directing stdin elsewhere.
+
+This feature is only available on UNIX.
+
+
+
+
+
+
+ a #GSubprocessLauncher
+
+
+
+
+
+
+
+
+ Sets the file path to use as the stdout for spawned processes.
+
+If @path is %NULL then any previously given path is unset.
+
+The file will be created or truncated when the process is spawned, as
+would be the case if using '>' at the shell.
+
+You may not set a stdout file path if a stdout fd is already set or
+if the launcher flags contain any flags directing stdout elsewhere.
+
+This feature is only available on UNIX.
+
+
+
+
+
+
+ a #GSubprocessLauncher
+
+
+
+ a filename or %NULL
+
+
+
+
+
+ Sets the environment variable @variable in the environment of
+processes launched from this launcher.
+
+On UNIX, both the variable's name and value can be arbitrary byte
+strings, except that the variable's name cannot contain '='.
+On Windows, they should be in UTF-8.
+
+
+
+
+
+
+ a #GSubprocessLauncher
+
+
+
+ the environment variable to set,
+ must not contain '='
+
+
+
+ the new value for the variable
+
+
+
+ whether to change the variable if it already exists
+
+
+
+
+
+ Creates a #GSubprocess given a provided varargs list of arguments.
+
+
+ A new #GSubprocess, or %NULL on error (and @error will be set)
+
+
+
+
+ a #GSubprocessLauncher
+
+
+
+ Error
+
+
+
+ Command line arguments
+
+
+
+ Continued arguments, %NULL terminated
+
+
+
+
+
+ Creates a #GSubprocess given a provided array of arguments.
+
+
+ A new #GSubprocess, or %NULL on error (and @error will be set)
+
+
+
+
+ a #GSubprocessLauncher
+
+
+
+ Command line arguments
+
+
+
+
+
+
+
+ Transfer an arbitrary file descriptor from parent process to the
+child. This function takes ownership of the @source_fd; it will be closed
+in the parent when @self is freed.
+
+By default, all file descriptors from the parent will be closed.
+This function allows you to create (for example) a custom `pipe()` or
+`socketpair()` before launching the process, and choose the target
+descriptor in the child.
+
+An example use case is GNUPG, which has a command line argument
+`--passphrase-fd` providing a file descriptor number where it expects
+the passphrase to be written.
+
+
+
+
+
+
+ a #GSubprocessLauncher
+
+
+
+ File descriptor in parent process
+
+
+
+ Target descriptor for child process
+
+
+
+
+
+ Sets the file descriptor to use as the stderr for spawned processes.
+
+If @fd is -1 then any previously given fd is unset.
+
+Note that the default behaviour is to pass stderr through to the
+stderr of the parent process.
+
+The passed @fd belongs to the #GSubprocessLauncher. It will be
+automatically closed when the launcher is finalized. The file
+descriptor will also be closed on the child side when executing the
+spawned process.
+
+You may not set a stderr fd if a stderr file path is already set or
+if the launcher flags contain any flags directing stderr elsewhere.
+
+This feature is only available on UNIX.
+
+
+
+
+
+
+ a #GSubprocessLauncher
+
+
+
+ a file descriptor, or -1
+
+
+
+
+
+ Sets the file descriptor to use as the stdin for spawned processes.
+
+If @fd is -1 then any previously given fd is unset.
+
+Note that if your intention is to have the stdin of the calling
+process inherited by the child then %G_SUBPROCESS_FLAGS_STDIN_INHERIT
+is a better way to go about doing that.
+
+The passed @fd is noted but will not be touched in the current
+process. It is therefore necessary that it be kept open by the
+caller until the subprocess is spawned. The file descriptor will
+also not be explicitly closed on the child side, so it must be marked
+O_CLOEXEC if that's what you want.
+
+You may not set a stdin fd if a stdin file path is already set or if
+the launcher flags contain any flags directing stdin elsewhere.
+
+This feature is only available on UNIX.
+
+
+
+
+
+
+ a #GSubprocessLauncher
+
+
+
+ a file descriptor, or -1
+
+
+
+
+
+ Sets the file descriptor to use as the stdout for spawned processes.
+
+If @fd is -1 then any previously given fd is unset.
+
+Note that the default behaviour is to pass stdout through to the
+stdout of the parent process.
+
+The passed @fd is noted but will not be touched in the current
+process. It is therefore necessary that it be kept open by the
+caller until the subprocess is spawned. The file descriptor will
+also not be explicitly closed on the child side, so it must be marked
+O_CLOEXEC if that's what you want.
+
+You may not set a stdout fd if a stdout file path is already set or
+if the launcher flags contain any flags directing stdout elsewhere.
+
+This feature is only available on UNIX.
+
+
+
+
+
+
+ a #GSubprocessLauncher
+
+
+
+ a file descriptor, or -1
+
+
+
+
+
+ Removes the environment variable @variable from the environment of
+processes launched from this launcher.
+
+On UNIX, the variable's name can be an arbitrary byte string not
+containing '='. On Windows, it should be in UTF-8.
+
+
+
+
+
+
+ a #GSubprocessLauncher
+
+
+
+ the environment variable to unset,
+ must not contain '='
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Extension point for TLS functionality via #GTlsBackend.
+See [Extending GIO][extending-gio].
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The purpose used to verify the client certificate in a TLS connection.
+Used by TLS servers.
+
+
+
+
+ The purpose used to verify the server certificate in a TLS connection. This
+is the most common purpose in use. Used by TLS clients.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ A #GTask represents and manages a cancellable "task".
+
+## Asynchronous operations
+
+The most common usage of #GTask is as a #GAsyncResult, to
+manage data during an asynchronous operation. You call
+g_task_new() in the "start" method, followed by
+g_task_set_task_data() and the like if you need to keep some
+additional data associated with the task, and then pass the
+task object around through your asynchronous operation.
+Eventually, you will call a method such as
+g_task_return_pointer() or g_task_return_error(), which will
+save the value you give it and then invoke the task's callback
+function in the
+[thread-default main context][g-main-context-push-thread-default]
+where it was created (waiting until the next iteration of the main
+loop first, if necessary). The caller will pass the #GTask back to
+the operation's finish function (as a #GAsyncResult), and you can
+use g_task_propagate_pointer() or the like to extract the
+return value.
+
+Using #GTask requires the thread-default #GMainContext from when the
+#GTask was constructed to be running at least until the task has completed
+and its data has been freed.
+
+If a #GTask has been constructed and its callback set, it is an error to
+not call `g_task_return_*()` on it. GLib will warn at runtime if this happens
+(since 2.76).
+
+Here is an example for using GTask as a GAsyncResult:
+|[<!-- language="C" -->
+ typedef struct {
+ CakeFrostingType frosting;
+ char *message;
+ } DecorationData;
+
+ static void
+ decoration_data_free (DecorationData *decoration)
+ {
+ g_free (decoration->message);
+ g_slice_free (DecorationData, decoration);
+ }
+
+ static void
+ baked_cb (Cake *cake,
+ gpointer user_data)
+ {
+ GTask *task = user_data;
+ DecorationData *decoration = g_task_get_task_data (task);
+ GError *error = NULL;
+
+ if (cake == NULL)
+ {
+ g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR,
+ "Go to the supermarket");
+ g_object_unref (task);
+ return;
+ }
+
+ if (!cake_decorate (cake, decoration->frosting, decoration->message, &error))
+ {
+ g_object_unref (cake);
+ // g_task_return_error() takes ownership of error
+ g_task_return_error (task, error);
+ g_object_unref (task);
+ return;
+ }
+
+ g_task_return_pointer (task, cake, g_object_unref);
+ g_object_unref (task);
+ }
+
+ void
+ baker_bake_cake_async (Baker *self,
+ guint radius,
+ CakeFlavor flavor,
+ CakeFrostingType frosting,
+ const char *message,
+ GCancellable *cancellable,
+ GAsyncReadyCallback callback,
+ gpointer user_data)
+ {
+ GTask *task;
+ DecorationData *decoration;
+ Cake *cake;
+
+ task = g_task_new (self, cancellable, callback, user_data);
+ if (radius < 3)
+ {
+ g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_TOO_SMALL,
+ "%ucm radius cakes are silly",
+ radius);
+ g_object_unref (task);
+ return;
+ }
+
+ cake = _baker_get_cached_cake (self, radius, flavor, frosting, message);
+ if (cake != NULL)
+ {
+ // _baker_get_cached_cake() returns a reffed cake
+ g_task_return_pointer (task, cake, g_object_unref);
+ g_object_unref (task);
+ return;
+ }
+
+ decoration = g_slice_new (DecorationData);
+ decoration->frosting = frosting;
+ decoration->message = g_strdup (message);
+ g_task_set_task_data (task, decoration, (GDestroyNotify) decoration_data_free);
+
+ _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task);
+ }
+
+ Cake *
+ baker_bake_cake_finish (Baker *self,
+ GAsyncResult *result,
+ GError **error)
+ {
+ g_return_val_if_fail (g_task_is_valid (result, self), NULL);
+
+ return g_task_propagate_pointer (G_TASK (result), error);
+ }
+]|
+
+## Chained asynchronous operations
+
+#GTask also tries to simplify asynchronous operations that
+internally chain together several smaller asynchronous
+operations. g_task_get_cancellable(), g_task_get_context(),
+and g_task_get_priority() allow you to get back the task's
+#GCancellable, #GMainContext, and [I/O priority][io-priority]
+when starting a new subtask, so you don't have to keep track
+of them yourself. g_task_attach_source() simplifies the case
+of waiting for a source to fire (automatically using the correct
+#GMainContext and priority).
+
+Here is an example for chained asynchronous operations:
+ |[<!-- language="C" -->
+ typedef struct {
+ Cake *cake;
+ CakeFrostingType frosting;
+ char *message;
+ } BakingData;
+
+ static void
+ decoration_data_free (BakingData *bd)
+ {
+ if (bd->cake)
+ g_object_unref (bd->cake);
+ g_free (bd->message);
+ g_slice_free (BakingData, bd);
+ }
+
+ static void
+ decorated_cb (Cake *cake,
+ GAsyncResult *result,
+ gpointer user_data)
+ {
+ GTask *task = user_data;
+ GError *error = NULL;
+
+ if (!cake_decorate_finish (cake, result, &error))
+ {
+ g_object_unref (cake);
+ g_task_return_error (task, error);
+ g_object_unref (task);
+ return;
+ }
+
+ // baking_data_free() will drop its ref on the cake, so we have to
+ // take another here to give to the caller.
+ g_task_return_pointer (task, g_object_ref (cake), g_object_unref);
+ g_object_unref (task);
+ }
+
+ static gboolean
+ decorator_ready (gpointer user_data)
+ {
+ GTask *task = user_data;
+ BakingData *bd = g_task_get_task_data (task);
+
+ cake_decorate_async (bd->cake, bd->frosting, bd->message,
+ g_task_get_cancellable (task),
+ decorated_cb, task);
+
+ return G_SOURCE_REMOVE;
+ }
+
+ static void
+ baked_cb (Cake *cake,
+ gpointer user_data)
+ {
+ GTask *task = user_data;
+ BakingData *bd = g_task_get_task_data (task);
+ GError *error = NULL;
+
+ if (cake == NULL)
+ {
+ g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR,
+ "Go to the supermarket");
+ g_object_unref (task);
+ return;
+ }
+
+ bd->cake = cake;
+
+ // Bail out now if the user has already cancelled
+ if (g_task_return_error_if_cancelled (task))
+ {
+ g_object_unref (task);
+ return;
+ }
+
+ if (cake_decorator_available (cake))
+ decorator_ready (task);
+ else
+ {
+ GSource *source;
+
+ source = cake_decorator_wait_source_new (cake);
+ // Attach @source to @task's GMainContext and have it call
+ // decorator_ready() when it is ready.
+ g_task_attach_source (task, source, decorator_ready);
+ g_source_unref (source);
+ }
+ }
+
+ void
+ baker_bake_cake_async (Baker *self,
+ guint radius,
+ CakeFlavor flavor,
+ CakeFrostingType frosting,
+ const char *message,
+ gint priority,
+ GCancellable *cancellable,
+ GAsyncReadyCallback callback,
+ gpointer user_data)
+ {
+ GTask *task;
+ BakingData *bd;
+
+ task = g_task_new (self, cancellable, callback, user_data);
+ g_task_set_priority (task, priority);
+
+ bd = g_slice_new0 (BakingData);
+ bd->frosting = frosting;
+ bd->message = g_strdup (message);
+ g_task_set_task_data (task, bd, (GDestroyNotify) baking_data_free);
+
+ _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task);
+ }
+
+ Cake *
+ baker_bake_cake_finish (Baker *self,
+ GAsyncResult *result,
+ GError **error)
+ {
+ g_return_val_if_fail (g_task_is_valid (result, self), NULL);
+
+ return g_task_propagate_pointer (G_TASK (result), error);
+ }
+]|
+
+## Asynchronous operations from synchronous ones
+
+You can use g_task_run_in_thread() to turn a synchronous
+operation into an asynchronous one, by running it in a thread.
+When it completes, the result will be dispatched to the
+[thread-default main context][g-main-context-push-thread-default]
+where the #GTask was created.
+
+Running a task in a thread:
+ |[<!-- language="C" -->
+ typedef struct {
+ guint radius;
+ CakeFlavor flavor;
+ CakeFrostingType frosting;
+ char *message;
+ } CakeData;
+
+ static void
+ cake_data_free (CakeData *cake_data)
+ {
+ g_free (cake_data->message);
+ g_slice_free (CakeData, cake_data);
+ }
+
+ static void
+ bake_cake_thread (GTask *task,
+ gpointer source_object,
+ gpointer task_data,
+ GCancellable *cancellable)
+ {
+ Baker *self = source_object;
+ CakeData *cake_data = task_data;
+ Cake *cake;
+ GError *error = NULL;
+
+ cake = bake_cake (baker, cake_data->radius, cake_data->flavor,
+ cake_data->frosting, cake_data->message,
+ cancellable, &error);
+ if (cake)
+ g_task_return_pointer (task, cake, g_object_unref);
+ else
+ g_task_return_error (task, error);
+ }
+
+ void
+ baker_bake_cake_async (Baker *self,
+ guint radius,
+ CakeFlavor flavor,
+ CakeFrostingType frosting,
+ const char *message,
+ GCancellable *cancellable,
+ GAsyncReadyCallback callback,
+ gpointer user_data)
+ {
+ CakeData *cake_data;
+ GTask *task;
+
+ cake_data = g_slice_new (CakeData);
+ cake_data->radius = radius;
+ cake_data->flavor = flavor;
+ cake_data->frosting = frosting;
+ cake_data->message = g_strdup (message);
+ task = g_task_new (self, cancellable, callback, user_data);
+ g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
+ g_task_run_in_thread (task, bake_cake_thread);
+ g_object_unref (task);
+ }
+
+ Cake *
+ baker_bake_cake_finish (Baker *self,
+ GAsyncResult *result,
+ GError **error)
+ {
+ g_return_val_if_fail (g_task_is_valid (result, self), NULL);
+
+ return g_task_propagate_pointer (G_TASK (result), error);
+ }
+]|
+
+## Adding cancellability to uncancellable tasks
+
+Finally, g_task_run_in_thread() and g_task_run_in_thread_sync()
+can be used to turn an uncancellable operation into a
+cancellable one. If you call g_task_set_return_on_cancel(),
+passing %TRUE, then if the task's #GCancellable is cancelled,
+it will return control back to the caller immediately, while
+allowing the task thread to continue running in the background
+(and simply discarding its result when it finally does finish).
+Provided that the task thread is careful about how it uses
+locks and other externally-visible resources, this allows you
+to make "GLib-friendly" asynchronous and cancellable
+synchronous variants of blocking APIs.
+
+Cancelling a task:
+ |[<!-- language="C" -->
+ static void
+ bake_cake_thread (GTask *task,
+ gpointer source_object,
+ gpointer task_data,
+ GCancellable *cancellable)
+ {
+ Baker *self = source_object;
+ CakeData *cake_data = task_data;
+ Cake *cake;
+ GError *error = NULL;
+
+ cake = bake_cake (baker, cake_data->radius, cake_data->flavor,
+ cake_data->frosting, cake_data->message,
+ &error);
+ if (error)
+ {
+ g_task_return_error (task, error);
+ return;
+ }
+
+ // If the task has already been cancelled, then we don't want to add
+ // the cake to the cake cache. Likewise, we don't want to have the
+ // task get cancelled in the middle of updating the cache.
+ // g_task_set_return_on_cancel() will return %TRUE here if it managed
+ // to disable return-on-cancel, or %FALSE if the task was cancelled
+ // before it could.
+ if (g_task_set_return_on_cancel (task, FALSE))
+ {
+ // If the caller cancels at this point, their
+ // GAsyncReadyCallback won't be invoked until we return,
+ // so we don't have to worry that this code will run at
+ // the same time as that code does. But if there were
+ // other functions that might look at the cake cache,
+ // then we'd probably need a GMutex here as well.
+ baker_add_cake_to_cache (baker, cake);
+ g_task_return_pointer (task, cake, g_object_unref);
+ }
+ }
+
+ void
+ baker_bake_cake_async (Baker *self,
+ guint radius,
+ CakeFlavor flavor,
+ CakeFrostingType frosting,
+ const char *message,
+ GCancellable *cancellable,
+ GAsyncReadyCallback callback,
+ gpointer user_data)
+ {
+ CakeData *cake_data;
+ GTask *task;
+
+ cake_data = g_slice_new (CakeData);
+
+ ...
+
+ task = g_task_new (self, cancellable, callback, user_data);
+ g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
+ g_task_set_return_on_cancel (task, TRUE);
+ g_task_run_in_thread (task, bake_cake_thread);
+ }
+
+ Cake *
+ baker_bake_cake_sync (Baker *self,
+ guint radius,
+ CakeFlavor flavor,
+ CakeFrostingType frosting,
+ const char *message,
+ GCancellable *cancellable,
+ GError **error)
+ {
+ CakeData *cake_data;
+ GTask *task;
+ Cake *cake;
+
+ cake_data = g_slice_new (CakeData);
+
+ ...
+
+ task = g_task_new (self, cancellable, NULL, NULL);
+ g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
+ g_task_set_return_on_cancel (task, TRUE);
+ g_task_run_in_thread_sync (task, bake_cake_thread);
+
+ cake = g_task_propagate_pointer (task, error);
+ g_object_unref (task);
+ return cake;
+ }
+]|
+
+## Porting from GSimpleAsyncResult
+
+#GTask's API attempts to be simpler than #GSimpleAsyncResult's
+in several ways:
+- You can save task-specific data with g_task_set_task_data(), and
+ retrieve it later with g_task_get_task_data(). This replaces the
+ abuse of g_simple_async_result_set_op_res_gpointer() for the same
+ purpose with #GSimpleAsyncResult.
+- In addition to the task data, #GTask also keeps track of the
+ [priority][io-priority], #GCancellable, and
+ #GMainContext associated with the task, so tasks that consist of
+ a chain of simpler asynchronous operations will have easy access
+ to those values when starting each sub-task.
+- g_task_return_error_if_cancelled() provides simplified
+ handling for cancellation. In addition, cancellation
+ overrides any other #GTask return value by default, like
+ #GSimpleAsyncResult does when
+ g_simple_async_result_set_check_cancellable() is called.
+ (You can use g_task_set_check_cancellable() to turn off that
+ behavior.) On the other hand, g_task_run_in_thread()
+ guarantees that it will always run your
+ `task_func`, even if the task's #GCancellable
+ is already cancelled before the task gets a chance to run;
+ you can start your `task_func` with a
+ g_task_return_error_if_cancelled() check if you need the
+ old behavior.
+- The "return" methods (eg, g_task_return_pointer())
+ automatically cause the task to be "completed" as well, and
+ there is no need to worry about the "complete" vs "complete
+ in idle" distinction. (#GTask automatically figures out
+ whether the task's callback can be invoked directly, or
+ if it needs to be sent to another #GMainContext, or delayed
+ until the next iteration of the current #GMainContext.)
+- The "finish" functions for #GTask based operations are generally
+ much simpler than #GSimpleAsyncResult ones, normally consisting
+ of only a single call to g_task_propagate_pointer() or the like.
+ Since g_task_propagate_pointer() "steals" the return value from
+ the #GTask, it is not necessary to juggle pointers around to
+ prevent it from being freed twice.
+- With #GSimpleAsyncResult, it was common to call
+ g_simple_async_result_propagate_error() from the
+ `_finish()` wrapper function, and have
+ virtual method implementations only deal with successful
+ returns. This behavior is deprecated, because it makes it
+ difficult for a subclass to chain to a parent class's async
+ methods. Instead, the wrapper function should just be a
+ simple wrapper, and the virtual method should call an
+ appropriate `g_task_propagate_` function.
+ Note that wrapper methods can now use
+ g_async_result_legacy_propagate_error() to do old-style
+ #GSimpleAsyncResult error-returning behavior, and
+ g_async_result_is_tagged() to check if a result is tagged as
+ having come from the `_async()` wrapper
+ function (for "short-circuit" results, such as when passing
+ 0 to g_input_stream_read_async()).
+
+## Thread-safety considerations
+
+Due to some infelicities in the API design, there is a
+thread-safety concern that users of GTask have to be aware of:
+
+If the `main` thread drops its last reference to the source object
+or the task data before the task is finalized, then the finalizers
+of these objects may be called on the worker thread.
+
+This is a problem if the finalizers use non-threadsafe API, and
+can lead to hard-to-debug crashes. Possible workarounds include:
+
+- Clear task data in a signal handler for `notify::completed`
+
+- Keep iterating a main context in the main thread and defer
+ dropping the reference to the source object to that main
+ context when the task is finalized
+
+
+
+ Creates a #GTask acting on @source_object, which will eventually be
+used to invoke @callback in the current
+[thread-default main context][g-main-context-push-thread-default].
+
+Call this in the "start" method of your asynchronous method, and
+pass the #GTask around throughout the asynchronous operation. You
+can use g_task_set_task_data() to attach task-specific data to the
+object, which you can retrieve later via g_task_get_task_data().
+
+By default, if @cancellable is cancelled, then the return value of
+the task will always be %G_IO_ERROR_CANCELLED, even if the task had
+already completed before the cancellation. This allows for
+simplified handling in cases where cancellation may imply that
+other objects that the task depends on have been destroyed. If you
+do not want this behavior, you can use
+g_task_set_check_cancellable() to change it.
+
+
+ a #GTask.
+
+
+
+
+ the #GObject that owns
+ this task, or %NULL.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback.
+
+
+
+ user data passed to @callback.
+
+
+
+
+
+ Checks that @result is a #GTask, and that @source_object is its
+source object (or that @source_object is %NULL and @result has no
+source object). This can be used in g_return_if_fail() checks.
+
+
+ %TRUE if @result and @source_object are valid, %FALSE
+if not
+
+
+
+
+ A #GAsyncResult
+
+
+
+ the source object
+ expected to be associated with the task
+
+
+
+
+
+ Creates a #GTask and then immediately calls g_task_return_error()
+on it. Use this in the wrapper function of an asynchronous method
+when you want to avoid even calling the virtual method. You can
+then use g_async_result_is_tagged() in the finish method wrapper to
+check if the result there is tagged as having been created by the
+wrapper method, and deal with it appropriately if so.
+
+See also g_task_report_new_error().
+
+
+
+
+
+
+ the #GObject that owns
+ this task, or %NULL.
+
+
+
+ a #GAsyncReadyCallback.
+
+
+
+ user data passed to @callback.
+
+
+
+ an opaque pointer indicating the source of this task
+
+
+
+ error to report
+
+
+
+
+
+ Creates a #GTask and then immediately calls
+g_task_return_new_error() on it. Use this in the wrapper function
+of an asynchronous method when you want to avoid even calling the
+virtual method. You can then use g_async_result_is_tagged() in the
+finish method wrapper to check if the result there is tagged as
+having been created by the wrapper method, and deal with it
+appropriately if so.
+
+See also g_task_report_error().
+
+
+
+
+
+
+ the #GObject that owns
+ this task, or %NULL.
+
+
+
+ a #GAsyncReadyCallback.
+
+
+
+ user data passed to @callback.
+
+
+
+ an opaque pointer indicating the source of this task
+
+
+
+ a #GQuark.
+
+
+
+ an error code.
+
+
+
+ a string with format characters.
+
+
+
+ a list of values to insert into @format.
+
+
+
+
+
+ A utility function for dealing with async operations where you need
+to wait for a #GSource to trigger. Attaches @source to @task's
+#GMainContext with @task's [priority][io-priority], and sets @source's
+callback to @callback, with @task as the callback's `user_data`.
+
+It will set the @source’s name to the task’s name (as set with
+g_task_set_name()), if one has been set on the task and the source doesn’t
+yet have a name.
+
+This takes a reference on @task until @source is destroyed.
+
+
+
+
+
+
+ a #GTask
+
+
+
+ the source to attach
+
+
+
+ the callback to invoke when @source triggers
+
+
+
+
+
+ Gets @task's #GCancellable
+
+
+ @task's #GCancellable
+
+
+
+
+ a #GTask
+
+
+
+
+
+ Gets @task's check-cancellable flag. See
+g_task_set_check_cancellable() for more details.
+
+
+
+
+
+
+ the #GTask
+
+
+
+
+
+ Gets the value of #GTask:completed. This changes from %FALSE to %TRUE after
+the task’s callback is invoked, and will return %FALSE if called from inside
+the callback.
+
+
+ %TRUE if the task has completed, %FALSE otherwise.
+
+
+
+
+ a #GTask.
+
+
+
+
+
+ Gets the #GMainContext that @task will return its result in (that
+is, the context that was the
+[thread-default main context][g-main-context-push-thread-default]
+at the point when @task was created).
+
+This will always return a non-%NULL value, even if the task's
+context is the default #GMainContext.
+
+
+ @task's #GMainContext
+
+
+
+
+ a #GTask
+
+
+
+
+
+ Gets @task’s name. See g_task_set_name().
+
+
+ @task’s name, or %NULL
+
+
+
+
+ a #GTask
+
+
+
+
+
+ Gets @task's priority
+
+
+ @task's priority
+
+
+
+
+ a #GTask
+
+
+
+
+
+ Gets @task's return-on-cancel flag. See
+g_task_set_return_on_cancel() for more details.
+
+
+
+
+
+
+ the #GTask
+
+
+
+
+
+ Gets the source object from @task. Like
+g_async_result_get_source_object(), but does not ref the object.
+
+
+ @task's source object, or %NULL
+
+
+
+
+ a #GTask
+
+
+
+
+
+ Gets @task's source tag. See g_task_set_source_tag().
+
+
+ @task's source tag
+
+
+
+
+ a #GTask
+
+
+
+
+
+ Gets @task's `task_data`.
+
+
+ @task's `task_data`.
+
+
+
+
+ a #GTask
+
+
+
+
+
+ Tests if @task resulted in an error.
+
+
+ %TRUE if the task resulted in an error, %FALSE otherwise.
+
+
+
+
+ a #GTask.
+
+
+
+
+
+ Gets the result of @task as a #gboolean.
+
+If the task resulted in an error, or was cancelled, then this will
+instead return %FALSE and set @error.
+
+Since this method transfers ownership of the return value (or
+error) to the caller, you may only call it once.
+
+
+ the task result, or %FALSE on error
+
+
+
+
+ a #GTask.
+
+
+
+
+
+ Gets the result of @task as an integer (#gssize).
+
+If the task resulted in an error, or was cancelled, then this will
+instead return -1 and set @error.
+
+Since this method transfers ownership of the return value (or
+error) to the caller, you may only call it once.
+
+
+ the task result, or -1 on error
+
+
+
+
+ a #GTask.
+
+
+
+
+
+ Gets the result of @task as a pointer, and transfers ownership
+of that value to the caller.
+
+If the task resulted in an error, or was cancelled, then this will
+instead return %NULL and set @error.
+
+Since this method transfers ownership of the return value (or
+error) to the caller, you may only call it once.
+
+
+ the task result, or %NULL on error
+
+
+
+
+ a #GTask
+
+
+
+
+
+ Gets the result of @task as a #GValue, and transfers ownership of
+that value to the caller. As with g_task_return_value(), this is
+a generic low-level method; g_task_propagate_pointer() and the like
+will usually be more useful for C code.
+
+If the task resulted in an error, or was cancelled, then this will
+instead set @error and return %FALSE.
+
+Since this method transfers ownership of the return value (or
+error) to the caller, you may only call it once.
+
+
+ %TRUE if @task succeeded, %FALSE on error.
+
+
+
+
+ a #GTask
+
+
+
+ return location for the #GValue
+
+
+
+
+
+ Sets @task's result to @result and completes the task (see
+g_task_return_pointer() for more discussion of exactly what this
+means).
+
+
+
+
+
+
+ a #GTask.
+
+
+
+ the #gboolean result of a task function.
+
+
+
+
+
+ Sets @task's result to @error (which @task assumes ownership of)
+and completes the task (see g_task_return_pointer() for more
+discussion of exactly what this means).
+
+Note that since the task takes ownership of @error, and since the
+task may be completed before returning from g_task_return_error(),
+you cannot assume that @error is still valid after calling this.
+Call g_error_copy() on the error if you need to keep a local copy
+as well.
+
+See also g_task_return_new_error().
+
+
+
+
+
+
+ a #GTask.
+
+
+
+ the #GError result of a task function.
+
+
+
+
+
+ Checks if @task's #GCancellable has been cancelled, and if so, sets
+@task's error accordingly and completes the task (see
+g_task_return_pointer() for more discussion of exactly what this
+means).
+
+
+ %TRUE if @task has been cancelled, %FALSE if not
+
+
+
+
+ a #GTask
+
+
+
+
+
+ Sets @task's result to @result and completes the task (see
+g_task_return_pointer() for more discussion of exactly what this
+means).
+
+
+
+
+
+
+ a #GTask.
+
+
+
+ the integer (#gssize) result of a task function.
+
+
+
+
+
+ Sets @task's result to a new #GError created from @domain, @code,
+@format, and the remaining arguments, and completes the task (see
+g_task_return_pointer() for more discussion of exactly what this
+means).
+
+See also g_task_return_error().
+
+
+
+
+
+
+ a #GTask.
+
+
+
+ a #GQuark.
+
+
+
+ an error code.
+
+
+
+ a string with format characters.
+
+
+
+ a list of values to insert into @format.
+
+
+
+
+
+ Sets @task's result to @result and completes the task. If @result
+is not %NULL, then @result_destroy will be used to free @result if
+the caller does not take ownership of it with
+g_task_propagate_pointer().
+
+"Completes the task" means that for an ordinary asynchronous task
+it will either invoke the task's callback, or else queue that
+callback to be invoked in the proper #GMainContext, or in the next
+iteration of the current #GMainContext. For a task run via
+g_task_run_in_thread() or g_task_run_in_thread_sync(), calling this
+method will save @result to be returned to the caller later, but
+the task will not actually be completed until the #GTaskThreadFunc
+exits.
+
+Note that since the task may be completed before returning from
+g_task_return_pointer(), you cannot assume that @result is still
+valid after calling this, unless you are still holding another
+reference on it.
+
+
+
+
+
+
+ a #GTask
+
+
+
+ the pointer result of a task
+ function
+
+
+
+ a #GDestroyNotify function.
+
+
+
+
+
+ Sets @task's result to @result (by copying it) and completes the task.
+
+If @result is %NULL then a #GValue of type %G_TYPE_POINTER
+with a value of %NULL will be used for the result.
+
+This is a very generic low-level method intended primarily for use
+by language bindings; for C code, g_task_return_pointer() and the
+like will normally be much easier to use.
+
+
+
+
+
+
+ a #GTask
+
+
+
+ the #GValue result of
+ a task function
+
+
+
+
+
+ Runs @task_func in another thread. When @task_func returns, @task's
+#GAsyncReadyCallback will be invoked in @task's #GMainContext.
+
+This takes a ref on @task until the task completes.
+
+See #GTaskThreadFunc for more details about how @task_func is handled.
+
+Although GLib currently rate-limits the tasks queued via
+g_task_run_in_thread(), you should not assume that it will always
+do this. If you have a very large number of tasks to run (several tens of
+tasks), but don't want them to all run at once, you should only queue a
+limited number of them (around ten) at a time.
+
+
+
+
+
+
+ a #GTask
+
+
+
+ a #GTaskThreadFunc
+
+
+
+
+
+ Runs @task_func in another thread, and waits for it to return or be
+cancelled. You can use g_task_propagate_pointer(), etc, afterward
+to get the result of @task_func.
+
+See #GTaskThreadFunc for more details about how @task_func is handled.
+
+Normally this is used with tasks created with a %NULL
+`callback`, but note that even if the task does
+have a callback, it will not be invoked when @task_func returns.
+#GTask:completed will be set to %TRUE just before this function returns.
+
+Although GLib currently rate-limits the tasks queued via
+g_task_run_in_thread_sync(), you should not assume that it will
+always do this. If you have a very large number of tasks to run,
+but don't want them to all run at once, you should only queue a
+limited number of them at a time.
+
+
+
+
+
+
+ a #GTask
+
+
+
+ a #GTaskThreadFunc
+
+
+
+
+
+ Sets or clears @task's check-cancellable flag. If this is %TRUE
+(the default), then g_task_propagate_pointer(), etc, and
+g_task_had_error() will check the task's #GCancellable first, and
+if it has been cancelled, then they will consider the task to have
+returned an "Operation was cancelled" error
+(%G_IO_ERROR_CANCELLED), regardless of any other error or return
+value the task may have had.
+
+If @check_cancellable is %FALSE, then the #GTask will not check the
+cancellable itself, and it is up to @task's owner to do this (eg,
+via g_task_return_error_if_cancelled()).
+
+If you are using g_task_set_return_on_cancel() as well, then
+you must leave check-cancellable set %TRUE.
+
+
+
+
+
+
+ the #GTask
+
+
+
+ whether #GTask will check the state of
+ its #GCancellable for you.
+
+
+
+
+
+ Sets @task’s name, used in debugging and profiling. The name defaults to
+%NULL.
+
+The task name should describe in a human readable way what the task does.
+For example, ‘Open file’ or ‘Connect to network host’. It is used to set the
+name of the #GSource used for idle completion of the task.
+
+This function may only be called before the @task is first used in a thread
+other than the one it was constructed in. It is called automatically by
+g_task_set_source_tag() if not called already.
+
+
+
+
+
+
+ a #GTask
+
+
+
+ a human readable name for the task, or %NULL to unset it
+
+
+
+
+
+ Sets @task's priority. If you do not call this, it will default to
+%G_PRIORITY_DEFAULT.
+
+This will affect the priority of #GSources created with
+g_task_attach_source() and the scheduling of tasks run in threads,
+and can also be explicitly retrieved later via
+g_task_get_priority().
+
+
+
+
+
+
+ the #GTask
+
+
+
+ the [priority][io-priority] of the request
+
+
+
+
+
+ Sets or clears @task's return-on-cancel flag. This is only
+meaningful for tasks run via g_task_run_in_thread() or
+g_task_run_in_thread_sync().
+
+If @return_on_cancel is %TRUE, then cancelling @task's
+#GCancellable will immediately cause it to return, as though the
+task's #GTaskThreadFunc had called
+g_task_return_error_if_cancelled() and then returned.
+
+This allows you to create a cancellable wrapper around an
+uninterruptible function. The #GTaskThreadFunc just needs to be
+careful that it does not modify any externally-visible state after
+it has been cancelled. To do that, the thread should call
+g_task_set_return_on_cancel() again to (atomically) set
+return-on-cancel %FALSE before making externally-visible changes;
+if the task gets cancelled before the return-on-cancel flag could
+be changed, g_task_set_return_on_cancel() will indicate this by
+returning %FALSE.
+
+You can disable and re-enable this flag multiple times if you wish.
+If the task's #GCancellable is cancelled while return-on-cancel is
+%FALSE, then calling g_task_set_return_on_cancel() to set it %TRUE
+again will cause the task to be cancelled at that point.
+
+If the task's #GCancellable is already cancelled before you call
+g_task_run_in_thread()/g_task_run_in_thread_sync(), then the
+#GTaskThreadFunc will still be run (for consistency), but the task
+will also be completed right away.
+
+
+ %TRUE if @task's return-on-cancel flag was changed to
+ match @return_on_cancel. %FALSE if @task has already been
+ cancelled.
+
+
+
+
+ the #GTask
+
+
+
+ whether the task returns automatically when
+ it is cancelled.
+
+
+
+
+
+ Sets @task's source tag.
+
+You can use this to tag a task return
+value with a particular pointer (usually a pointer to the function
+doing the tagging) and then later check it using
+g_task_get_source_tag() (or g_async_result_is_tagged()) in the
+task's "finish" function, to figure out if the response came from a
+particular place.
+
+A macro wrapper around this function will automatically set the
+task’s name to the string form of @source_tag if it’s not already
+set, for convenience.
+
+
+
+
+
+
+ the #GTask
+
+
+
+ an opaque pointer indicating the source of this task
+
+
+
+
+
+ Sets @task’s name, used in debugging and profiling.
+
+This is a variant of g_task_set_name() that avoids copying @name.
+
+
+
+
+
+
+ a #GTask
+
+
+
+ a human readable name for the task. Must be a string literal
+
+
+
+
+
+ Sets @task's task data (freeing the existing task data, if any).
+
+
+
+
+
+
+ the #GTask
+
+
+
+ task-specific data
+
+
+
+ #GDestroyNotify for @task_data
+
+
+
+
+
+ Whether the task has completed, meaning its callback (if set) has been
+invoked. This can only happen after g_task_return_pointer(),
+g_task_return_error() or one of the other return functions have been called
+on the task.
+
+This property is guaranteed to change from %FALSE to %TRUE exactly once.
+
+The #GObject::notify signal for this change is emitted in the same main
+context as the task’s callback, immediately after that callback is invoked.
+
+
+
+
+
+
+
+ The prototype for a task function to be run in a thread via
+g_task_run_in_thread() or g_task_run_in_thread_sync().
+
+If the return-on-cancel flag is set on @task, and @cancellable gets
+cancelled, then the #GTask will be completed immediately (as though
+g_task_return_error_if_cancelled() had been called), without
+waiting for the task function to complete. However, the task
+function will continue running in its thread in the background. The
+function therefore needs to be careful about how it uses
+externally-visible state in this case. See
+g_task_set_return_on_cancel() for more details.
+
+Other than in that case, @task will be completed when the
+#GTaskThreadFunc returns, not when it calls a
+`g_task_return_` function.
+
+
+
+
+
+
+ the #GTask
+
+
+
+ @task's source object
+
+
+
+ @task's task data
+
+
+
+ @task's #GCancellable, or %NULL
+
+
+
+
+
+ This is the subclass of #GSocketConnection that is created
+for TCP/IP sockets.
+
+
+ Checks if graceful disconnects are used. See
+g_tcp_connection_set_graceful_disconnect().
+
+
+ %TRUE if graceful disconnect is used on close, %FALSE otherwise
+
+
+
+
+ a #GTcpConnection
+
+
+
+
+
+ This enables graceful disconnects on close. A graceful disconnect
+means that we signal the receiving end that the connection is terminated
+and wait for it to close the connection before closing the connection.
+
+A graceful disconnect means that we can be sure that we successfully sent
+all the outstanding data to the other end, or get an error reported.
+However, it also means we have to wait for all the data to reach the
+other side and for it to acknowledge this by closing the socket, which may
+take a while. For this reason it is disabled by default.
+
+
+
+
+
+
+ a #GTcpConnection
+
+
+
+ Whether to do graceful disconnects or not
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+
+ Wraps @base_io_stream and @socket together as a #GSocketConnection.
+
+
+ the new #GSocketConnection.
+
+
+
+
+ the #GIOStream to wrap
+
+
+
+ the #GSocket associated with @base_io_stream
+
+
+
+
+
+ Gets @conn's base #GIOStream
+
+
+ @conn's base #GIOStream
+
+
+
+
+ a #GTcpWrapperConnection
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ A helper class for testing code which uses D-Bus without touching the user's
+session bus.
+
+Note that #GTestDBus modifies the user’s environment, calling setenv().
+This is not thread-safe, so all #GTestDBus calls should be completed before
+threads are spawned, or should have appropriate locking to ensure no access
+conflicts to environment variables shared between #GTestDBus and other
+threads.
+
+## Creating unit tests using GTestDBus
+
+Testing of D-Bus services can be tricky because normally we only ever run
+D-Bus services over an existing instance of the D-Bus daemon thus we
+usually don't activate D-Bus services that are not yet installed into the
+target system. The #GTestDBus object makes this easier for us by taking care
+of the lower level tasks such as running a private D-Bus daemon and looking
+up uninstalled services in customizable locations, typically in your source
+code tree.
+
+The first thing you will need is a separate service description file for the
+D-Bus daemon. Typically a `services` subdirectory of your `tests` directory
+is a good place to put this file.
+
+The service file should list your service along with an absolute path to the
+uninstalled service executable in your source tree. Using autotools we would
+achieve this by adding a file such as `my-server.service.in` in the services
+directory and have it processed by configure.
+|[
+ [D-BUS Service]
+ Name=org.gtk.GDBus.Examples.ObjectManager
+ Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server
+]|
+You will also need to indicate this service directory in your test
+fixtures, so you will need to pass the path while compiling your
+test cases. Typically this is done with autotools with an added
+preprocessor flag specified to compile your tests such as:
+|[
+ -DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\"
+]|
+ Once you have a service definition file which is local to your source tree,
+you can proceed to set up a GTest fixture using the #GTestDBus scaffolding.
+
+An example of a test fixture for D-Bus services can be found
+here:
+[gdbus-test-fixture.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-test-fixture.c)
+
+Note that these examples only deal with isolating the D-Bus aspect of your
+service. To successfully run isolated unit tests on your service you may need
+some additional modifications to your test case fixture. For example; if your
+service uses GSettings and installs a schema then it is important that your test service
+not load the schema in the ordinary installed location (chances are that your service
+and schema files are not yet installed, or worse; there is an older version of the
+schema file sitting in the install location).
+
+Most of the time we can work around these obstacles using the
+environment. Since the environment is inherited by the D-Bus daemon
+created by #GTestDBus and then in turn inherited by any services the
+D-Bus daemon activates, using the setup routine for your fixture is
+a practical place to help sandbox your runtime environment. For the
+rather typical GSettings case we can work around this by setting
+`GSETTINGS_SCHEMA_DIR` to the in tree directory holding your schemas
+in the above fixture_setup() routine.
+
+The GSettings schemas need to be locally pre-compiled for this to work. This can be achieved
+by compiling the schemas locally as a step before running test cases, an autotools setup might
+do the following in the directory holding schemas:
+|[
+ all-am:
+ $(GLIB_COMPILE_SCHEMAS) .
+
+ CLEANFILES += gschemas.compiled
+]|
+
+ Create a new #GTestDBus object.
+
+
+ a new #GTestDBus.
+
+
+
+
+ a #GTestDBusFlags
+
+
+
+
+
+ Unset DISPLAY and DBUS_SESSION_BUS_ADDRESS env variables to ensure the test
+won't use user's session bus.
+
+This is useful for unit tests that want to verify behaviour when no session
+bus is running. It is not necessary to call this if unit test already calls
+g_test_dbus_up() before acquiring the session bus.
+
+
+
+
+
+
+ Add a path where dbus-daemon will look up .service files. This can't be
+called after g_test_dbus_up().
+
+
+
+
+
+
+ a #GTestDBus
+
+
+
+ path to a directory containing .service files
+
+
+
+
+
+ Stop the session bus started by g_test_dbus_up().
+
+This will wait for the singleton returned by g_bus_get() or g_bus_get_sync()
+to be destroyed. This is done to ensure that the next unit test won't get a
+leaked singleton from this test.
+
+
+
+
+
+
+ a #GTestDBus
+
+
+
+
+
+ Get the address on which dbus-daemon is running. If g_test_dbus_up() has not
+been called yet, %NULL is returned. This can be used with
+g_dbus_connection_new_for_address().
+
+
+ the address of the bus, or %NULL.
+
+
+
+
+ a #GTestDBus
+
+
+
+
+
+ Get the flags of the #GTestDBus object.
+
+
+ the value of #GTestDBus:flags property
+
+
+
+
+ a #GTestDBus
+
+
+
+
+
+ Stop the session bus started by g_test_dbus_up().
+
+Unlike g_test_dbus_down(), this won't verify the #GDBusConnection
+singleton returned by g_bus_get() or g_bus_get_sync() is destroyed. Unit
+tests wanting to verify behaviour after the session bus has been stopped
+can use this function but should still call g_test_dbus_down() when done.
+
+
+
+
+
+
+ a #GTestDBus
+
+
+
+
+
+ Start a dbus-daemon instance and set DBUS_SESSION_BUS_ADDRESS. After this
+call, it is safe for unit tests to start sending messages on the session bus.
+
+If this function is called from setup callback of g_test_add(),
+g_test_dbus_down() must be called in its teardown callback.
+
+If this function is called from unit test's main(), then g_test_dbus_down()
+must be called after g_test_run().
+
+
+
+
+
+
+ a #GTestDBus
+
+
+
+
+
+ #GTestDBusFlags specifying the behaviour of the D-Bus session.
+
+
+
+
+ Flags to define future #GTestDBus behaviour.
+
+ No flags.
+
+
+
+ #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.
+
+
+
+ Creates a new themed icon for @iconname.
+
+
+ a new #GThemedIcon.
+
+
+
+
+ a string containing an icon name.
+
+
+
+
+
+ Creates a new themed icon for @iconnames.
+
+
+ a new #GThemedIcon
+
+
+
+
+ an array of strings containing icon names.
+
+
+
+
+
+ the length of the @iconnames array, or -1 if @iconnames is
+ %NULL-terminated
+
+
+
+
+
+ Creates a new themed icon for @iconname, and all the names
+that can be created by shortening @iconname at '-' characters.
+
+In the following example, @icon1 and @icon2 are equivalent:
+|[<!-- language="C" -->
+const char *names[] = {
+ "gnome-dev-cdrom-audio",
+ "gnome-dev-cdrom",
+ "gnome-dev",
+ "gnome"
+};
+
+icon1 = g_themed_icon_new_from_names (names, 4);
+icon2 = g_themed_icon_new_with_default_fallbacks ("gnome-dev-cdrom-audio");
+]|
+
+
+ a new #GThemedIcon.
+
+
+
+
+ a string containing an icon name
+
+
+
+
+
+ Append a name to the list of icons from within @icon.
+
+Note that doing so invalidates the hash computed by prior calls
+to g_icon_hash().
+
+
+
+
+
+
+ a #GThemedIcon
+
+
+
+ name of icon to append to list of icons from within @icon.
+
+
+
+
+
+ Gets the names of icons from within @icon.
+
+
+ a list of icon names.
+
+
+
+
+
+
+ a #GThemedIcon.
+
+
+
+
+
+ Prepend a name to the list of icons from within @icon.
+
+Note that doing so invalidates the hash computed by prior calls
+to g_icon_hash().
+
+
+
+
+
+
+ a #GThemedIcon
+
+
+
+ name of icon to prepend to list of icons from within @icon.
+
+
+
+
+
+ The icon name.
+
+
+
+ A %NULL-terminated array of icon names.
+
+
+
+
+
+ Whether to use the default fallbacks found by shortening the icon name
+at '-' characters. If the "names" array has more than one element,
+ignores any past the first.
+
+For example, if the icon name was "gnome-dev-cdrom-audio", the array
+would become
+|[<!-- language="C" -->
+{
+ "gnome-dev-cdrom-audio",
+ "gnome-dev-cdrom",
+ "gnome-dev",
+ "gnome",
+ NULL
+};
+]|
+
+
+
+
+
+
+
+ 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.
+
+
+ Creates a new #GThreadedSocketService with no listeners. Listeners
+must be added with one of the #GSocketListener "add" methods.
+
+
+ a new #GSocketService.
+
+
+
+
+ the maximal number of threads to execute concurrently
+ handling incoming clients, -1 means no limit
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The ::run signal is emitted in a worker thread in response to an
+incoming connection. This thread is dedicated to handling
+@connection and may perform blocking IO. The signal handler need
+not return until the connection is closed.
+
+ %TRUE to stop further signal handlers from being called
+
+
+
+
+ a new #GSocketConnection object.
+
+
+
+ the source_object passed to g_socket_listener_add_address().
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The client authentication mode for a #GTlsServerConnection.
+
+ client authentication not required
+
+
+ client authentication is requested
+
+
+ client authentication is required
+
+
+
+ TLS (Transport Layer Security, aka SSL) and DTLS backend.
+
+
+ Gets the default #GTlsBackend for the system.
+
+
+ a #GTlsBackend, which will be a
+ dummy object if no TLS backend is available
+
+
+
+
+ Gets the default #GTlsDatabase used to verify TLS connections.
+
+
+ the default database, which should be
+ unreffed when done.
+
+
+
+
+ the #GTlsBackend
+
+
+
+
+
+ Checks if DTLS is supported. DTLS support may not be available even if TLS
+support is available, and vice-versa.
+
+
+ whether DTLS is supported
+
+
+
+
+ the #GTlsBackend
+
+
+
+
+
+ Checks if TLS is supported; if this returns %FALSE for the default
+#GTlsBackend, it means no "real" TLS backend is available.
+
+
+ whether or not TLS is supported
+
+
+
+
+ the #GTlsBackend
+
+
+
+
+
+ Gets the #GType of @backend's #GTlsCertificate implementation.
+
+
+ the #GType of @backend's #GTlsCertificate
+ implementation.
+
+
+
+
+ the #GTlsBackend
+
+
+
+
+
+ Gets the #GType of @backend's #GTlsClientConnection implementation.
+
+
+ the #GType of @backend's #GTlsClientConnection
+ implementation.
+
+
+
+
+ the #GTlsBackend
+
+
+
+
+
+ Gets the default #GTlsDatabase used to verify TLS connections.
+
+
+ the default database, which should be
+ unreffed when done.
+
+
+
+
+ the #GTlsBackend
+
+
+
+
+
+ Gets the #GType of @backend’s #GDtlsClientConnection implementation.
+
+
+ the #GType of @backend’s #GDtlsClientConnection
+ implementation, or %G_TYPE_INVALID if this backend doesn’t support DTLS.
+
+
+
+
+ the #GTlsBackend
+
+
+
+
+
+ Gets the #GType of @backend’s #GDtlsServerConnection implementation.
+
+
+ the #GType of @backend’s #GDtlsServerConnection
+ implementation, or %G_TYPE_INVALID if this backend doesn’t support DTLS.
+
+
+
+
+ the #GTlsBackend
+
+
+
+
+
+ Gets the #GType of @backend's #GTlsFileDatabase implementation.
+
+
+ the #GType of backend's #GTlsFileDatabase implementation.
+
+
+
+
+ the #GTlsBackend
+
+
+
+
+
+ Gets the #GType of @backend's #GTlsServerConnection implementation.
+
+
+ the #GType of @backend's #GTlsServerConnection
+ implementation.
+
+
+
+
+ the #GTlsBackend
+
+
+
+
+
+ Set the default #GTlsDatabase used to verify TLS connections
+
+Any subsequent call to g_tls_backend_get_default_database() will return
+the database set in this call. Existing databases and connections are not
+modified.
+
+Setting a %NULL default database will reset to using the system default
+database as if g_tls_backend_set_default_database() had never been called.
+
+
+
+
+
+
+ the #GTlsBackend
+
+
+
+ the #GTlsDatabase
+
+
+
+
+
+ Checks if DTLS is supported. DTLS support may not be available even if TLS
+support is available, and vice-versa.
+
+
+ whether DTLS is supported
+
+
+
+
+ the #GTlsBackend
+
+
+
+
+
+ Checks if TLS is supported; if this returns %FALSE for the default
+#GTlsBackend, it means no "real" TLS backend is available.
+
+
+ whether or not TLS is supported
+
+
+
+
+ the #GTlsBackend
+
+
+
+
+
+
+ Provides an interface for describing TLS-related types.
+
+
+ The parent interface.
+
+
+
+
+
+
+ whether or not TLS is supported
+
+
+
+
+ the #GTlsBackend
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ the default database, which should be
+ unreffed when done.
+
+
+
+
+ the #GTlsBackend
+
+
+
+
+
+
+
+
+
+ whether DTLS is supported
+
+
+
+
+ the #GTlsBackend
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ A certificate used for TLS authentication and encryption.
+This can represent either a certificate only (eg, the certificate
+received by a client from a server), or the combination of
+a certificate and a private key (which is needed when acting as a
+#GTlsServerConnection).
+
+
+ Creates a #GTlsCertificate from the data in @file.
+
+As of 2.72, if the filename ends in `.p12` or `.pfx` the data is loaded by
+g_tls_certificate_new_from_pkcs12() otherwise it is loaded by
+g_tls_certificate_new_from_pem(). See those functions for
+exact details.
+
+If @file cannot be read or parsed, the function will return %NULL and
+set @error.
+
+
+ the new certificate, or %NULL on error
+
+
+
+
+ file containing a certificate to import
+
+
+
+
+
+ Creates a #GTlsCertificate from the data in @file.
+
+If @file cannot be read or parsed, the function will return %NULL and
+set @error.
+
+Any unknown file types will error with %G_IO_ERROR_NOT_SUPPORTED.
+Currently only `.p12` and `.pfx` files are supported.
+See g_tls_certificate_new_from_pkcs12() for more details.
+
+
+ the new certificate, or %NULL on error
+
+
+
+
+ file containing a certificate to import
+
+
+
+ password for PKCS #12 files
+
+
+
+
+
+ Creates a #GTlsCertificate from the PEM-encoded data in @cert_file
+and @key_file. The returned certificate will be the first certificate
+found in @cert_file. As of GLib 2.44, if @cert_file contains more
+certificates it will try to load a certificate chain. All
+certificates will be verified in the order found (top-level
+certificate should be the last one in the file) and the
+#GTlsCertificate:issuer property of each certificate will be set
+accordingly if the verification succeeds. If any certificate in the
+chain cannot be verified, the first certificate in the file will
+still be returned.
+
+If either file cannot be read or parsed, the function will return
+%NULL and set @error. Otherwise, this behaves like
+g_tls_certificate_new_from_pem().
+
+
+ the new certificate, or %NULL on error
+
+
+
+
+ file containing one or more PEM-encoded
+ certificates to import
+
+
+
+ file containing a PEM-encoded private key
+ to import
+
+
+
+
+
+ Creates a #GTlsCertificate from the PEM-encoded data in @data. If
+@data includes both a certificate and a private key, then the
+returned certificate will include the private key data as well. (See
+the #GTlsCertificate:private-key-pem property for information about
+supported formats.)
+
+The returned certificate will be the first certificate found in
+@data. As of GLib 2.44, if @data contains more certificates it will
+try to load a certificate chain. All certificates will be verified in
+the order found (top-level certificate should be the last one in the
+file) and the #GTlsCertificate:issuer property of each certificate
+will be set accordingly if the verification succeeds. If any
+certificate in the chain cannot be verified, the first certificate in
+the file will still be returned.
+
+
+ the new certificate, or %NULL if @data is invalid
+
+
+
+
+ PEM-encoded certificate data
+
+
+
+ the length of @data, or -1 if it's 0-terminated.
+
+
+
+
+
+ Creates a #GTlsCertificate from a
+[PKCS \#11](https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html) URI.
+
+An example @pkcs11_uri would be `pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01`
+
+Where the token’s layout is:
+
+|[
+Object 0:
+ URL: pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01;object=private%20key;type=private
+ Type: Private key (RSA-2048)
+ ID: 01
+
+Object 1:
+ URL: pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01;object=Certificate%20for%20Authentication;type=cert
+ Type: X.509 Certificate (RSA-2048)
+ ID: 01
+]|
+
+In this case the certificate and private key would both be detected and used as expected.
+@pkcs_uri may also just reference an X.509 certificate object and then optionally
+@private_key_pkcs11_uri allows using a private key exposed under a different URI.
+
+Note that the private key is not accessed until usage and may fail or require a PIN later.
+
+
+ the new certificate, or %NULL on error
+
+
+
+
+ A PKCS \#11 URI
+
+
+
+ A PKCS \#11 URI
+
+
+
+
+
+ Creates a #GTlsCertificate from the data in @data. It must contain
+a certificate and matching private key.
+
+If extra certificates are included they will be verified as a chain
+and the #GTlsCertificate:issuer property will be set.
+All other data will be ignored.
+
+You can pass as single password for all of the data which will be
+used both for the PKCS #12 container as well as encrypted
+private keys. If decryption fails it will error with
+%G_TLS_ERROR_BAD_CERTIFICATE_PASSWORD.
+
+This constructor requires support in the current #GTlsBackend.
+If support is missing it will error with
+%G_IO_ERROR_NOT_SUPPORTED.
+
+Other parsing failures will error with %G_TLS_ERROR_BAD_CERTIFICATE.
+
+
+ the new certificate, or %NULL if @data is invalid
+
+
+
+
+ DER-encoded PKCS #12 format certificate data
+
+
+
+
+
+ the length of @data
+
+
+
+ optional password for encrypted certificate data
+
+
+
+
+
+ Creates one or more #GTlsCertificates from the PEM-encoded
+data in @file. If @file cannot be read or parsed, the function will
+return %NULL and set @error. If @file does not contain any
+PEM-encoded certificates, this will return an empty list and not
+set @error.
+
+
+ a
+#GList containing #GTlsCertificate objects. You must free the list
+and its contents when you are done with it.
+
+
+
+
+
+
+ file containing PEM-encoded certificates to import
+
+
+
+
+
+ This verifies @cert and returns a set of #GTlsCertificateFlags
+indicating any problems found with it. This can be used to verify a
+certificate outside the context of making a connection, or to
+check a certificate against a CA that is not part of the system
+CA database.
+
+If @cert is valid, %G_TLS_CERTIFICATE_NO_FLAGS is returned.
+
+If @identity is not %NULL, @cert's name(s) will be compared against
+it, and %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the return
+value if it does not match. If @identity is %NULL, that bit will
+never be set in the return value.
+
+If @trusted_ca is not %NULL, then @cert (or one of the certificates
+in its chain) must be signed by it, or else
+%G_TLS_CERTIFICATE_UNKNOWN_CA will be set in the return value. If
+@trusted_ca is %NULL, that bit will never be set in the return
+value.
+
+GLib guarantees that if certificate verification fails, at least one
+error will be set in the return value, but it does not guarantee
+that all possible errors will be set. Accordingly, you may not safely
+decide to ignore any particular type of error. For example, it would
+be incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow
+expired certificates, because this could potentially be the only
+error flag set even if other problems exist with the certificate.
+
+Because TLS session context is not used, #GTlsCertificate may not
+perform as many checks on the certificates as #GTlsConnection would.
+For example, certificate constraints may not be honored, and
+revocation checks may not be performed. The best way to verify TLS
+certificates used by a TLS connection is to let #GTlsConnection
+handle the verification.
+
+
+ the appropriate #GTlsCertificateFlags
+
+
+
+
+ a #GTlsCertificate
+
+
+
+ the expected peer identity
+
+
+
+ the certificate of a trusted authority
+
+
+
+
+
+ Gets the value of #GTlsCertificate:dns-names.
+
+
+ A #GPtrArray of
+#GBytes elements, or %NULL if it's not available.
+
+
+
+
+
+
+ a #GTlsCertificate
+
+
+
+
+
+ Gets the value of #GTlsCertificate:ip-addresses.
+
+
+ A #GPtrArray
+of #GInetAddress elements, or %NULL if it's not available.
+
+
+
+
+
+
+ a #GTlsCertificate
+
+
+
+
+
+ Gets the #GTlsCertificate representing @cert's issuer, if known
+
+
+ The certificate of @cert's issuer,
+or %NULL if @cert is self-signed or signed with an unknown
+certificate.
+
+
+
+
+ a #GTlsCertificate
+
+
+
+
+
+ Returns the issuer name from the certificate.
+
+
+ The issuer name, or %NULL if it's not available.
+
+
+
+
+ a #GTlsCertificate
+
+
+
+
+
+ Returns the time at which the certificate became or will become invalid.
+
+
+ The not-valid-after date, or %NULL if it's not available.
+
+
+
+
+ a #GTlsCertificate
+
+
+
+
+
+ Returns the time at which the certificate became or will become valid.
+
+
+ The not-valid-before date, or %NULL if it's not available.
+
+
+
+
+ a #GTlsCertificate
+
+
+
+
+
+ Returns the subject name from the certificate.
+
+
+ The subject name, or %NULL if it's not available.
+
+
+
+
+ a #GTlsCertificate
+
+
+
+
+
+ Check if two #GTlsCertificate objects represent the same certificate.
+The raw DER byte data of the two certificates are checked for equality.
+This has the effect that two certificates may compare equal even if
+their #GTlsCertificate:issuer, #GTlsCertificate:private-key, or
+#GTlsCertificate:private-key-pem properties differ.
+
+
+ whether the same or not
+
+
+
+
+ first certificate to compare
+
+
+
+ second certificate to compare
+
+
+
+
+
+ This verifies @cert and returns a set of #GTlsCertificateFlags
+indicating any problems found with it. This can be used to verify a
+certificate outside the context of making a connection, or to
+check a certificate against a CA that is not part of the system
+CA database.
+
+If @cert is valid, %G_TLS_CERTIFICATE_NO_FLAGS is returned.
+
+If @identity is not %NULL, @cert's name(s) will be compared against
+it, and %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the return
+value if it does not match. If @identity is %NULL, that bit will
+never be set in the return value.
+
+If @trusted_ca is not %NULL, then @cert (or one of the certificates
+in its chain) must be signed by it, or else
+%G_TLS_CERTIFICATE_UNKNOWN_CA will be set in the return value. If
+@trusted_ca is %NULL, that bit will never be set in the return
+value.
+
+GLib guarantees that if certificate verification fails, at least one
+error will be set in the return value, but it does not guarantee
+that all possible errors will be set. Accordingly, you may not safely
+decide to ignore any particular type of error. For example, it would
+be incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow
+expired certificates, because this could potentially be the only
+error flag set even if other problems exist with the certificate.
+
+Because TLS session context is not used, #GTlsCertificate may not
+perform as many checks on the certificates as #GTlsConnection would.
+For example, certificate constraints may not be honored, and
+revocation checks may not be performed. The best way to verify TLS
+certificates used by a TLS connection is to let #GTlsConnection
+handle the verification.
+
+
+ the appropriate #GTlsCertificateFlags
+
+
+
+
+ a #GTlsCertificate
+
+
+
+ the expected peer identity
+
+
+
+ the certificate of a trusted authority
+
+
+
+
+
+ The DER (binary) encoded representation of the certificate.
+This property and the #GTlsCertificate:certificate-pem property
+represent the same data, just in different forms.
+
+
+
+
+
+ The PEM (ASCII) encoded representation of the certificate.
+This property and the #GTlsCertificate:certificate
+property represent the same data, just in different forms.
+
+
+
+ The DNS names from the certificate's Subject Alternative Names (SANs),
+%NULL if unavailable.
+
+
+
+
+
+ The IP addresses from the certificate's Subject Alternative Names (SANs),
+%NULL if unavailable.
+
+
+
+
+
+ A #GTlsCertificate representing the entity that issued this
+certificate. If %NULL, this means that the certificate is either
+self-signed, or else the certificate of the issuer is not
+available.
+
+Beware the issuer certificate may not be the same as the
+certificate that would actually be used to construct a valid
+certification path during certificate verification.
+[RFC 4158](https://datatracker.ietf.org/doc/html/rfc4158) explains
+why an issuer certificate cannot be naively assumed to be part of the
+the certification path (though GLib's TLS backends may not follow the
+path building strategies outlined in this RFC). Due to the complexity
+of certification path building, GLib does not provide any way to know
+which certification path will actually be used. Accordingly, this
+property cannot be used to make security-related decisions. Only
+GLib itself should make security decisions about TLS certificates.
+
+
+
+ The issuer from the certificate,
+%NULL if unavailable.
+
+
+
+ The time at which this cert is no longer valid,
+%NULL if unavailable.
+
+
+
+ The time at which this cert is considered to be valid,
+%NULL if unavailable.
+
+
+
+ An optional password used when constructed with GTlsCertificate:pkcs12-data.
+
+
+
+ A URI referencing the [PKCS \#11](https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html)
+objects containing an X.509 certificate and optionally a private key.
+
+If %NULL, the certificate is either not backed by PKCS \#11 or the
+#GTlsBackend does not support PKCS \#11.
+
+
+
+ The PKCS #12 formatted data used to construct the object.
+
+See also: g_tls_certificate_new_from_pkcs12()
+
+
+
+
+
+ The DER (binary) encoded representation of the certificate's
+private key, in either [PKCS \#1 format](https://datatracker.ietf.org/doc/html/rfc8017)
+or unencrypted [PKCS \#8 format.](https://datatracker.ietf.org/doc/html/rfc5208)
+PKCS \#8 format is supported since 2.32; earlier releases only
+support PKCS \#1. You can use the `openssl rsa` tool to convert
+PKCS \#8 keys to PKCS \#1.
+
+This property (or the #GTlsCertificate:private-key-pem property)
+can be set when constructing a key (for example, from a file).
+Since GLib 2.70, it is now also readable; however, be aware that if
+the private key is backed by a PKCS \#11 URI – for example, if it
+is stored on a smartcard – then this property will be %NULL. If so,
+the private key must be referenced via its PKCS \#11 URI,
+#GTlsCertificate:private-key-pkcs11-uri. You must check both
+properties to see if the certificate really has a private key.
+When this property is read, the output format will be unencrypted
+PKCS \#8.
+
+
+
+
+
+ The PEM (ASCII) encoded representation of the certificate's
+private key in either [PKCS \#1 format](https://datatracker.ietf.org/doc/html/rfc8017)
+("`BEGIN RSA PRIVATE KEY`") or unencrypted
+[PKCS \#8 format](https://datatracker.ietf.org/doc/html/rfc5208)
+("`BEGIN PRIVATE KEY`"). PKCS \#8 format is supported since 2.32;
+earlier releases only support PKCS \#1. You can use the `openssl rsa`
+tool to convert PKCS \#8 keys to PKCS \#1.
+
+This property (or the #GTlsCertificate:private-key property)
+can be set when constructing a key (for example, from a file).
+Since GLib 2.70, it is now also readable; however, be aware that if
+the private key is backed by a PKCS \#11 URI - for example, if it
+is stored on a smartcard - then this property will be %NULL. If so,
+the private key must be referenced via its PKCS \#11 URI,
+#GTlsCertificate:private-key-pkcs11-uri. You must check both
+properties to see if the certificate really has a private key.
+When this property is read, the output format will be unencrypted
+PKCS \#8.
+
+
+
+ A URI referencing a [PKCS \#11](https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html)
+object containing a private key.
+
+
+
+ The subject from the cert,
+%NULL if unavailable.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ the appropriate #GTlsCertificateFlags
+
+
+
+
+ a #GTlsCertificate
+
+
+
+ the expected peer identity
+
+
+
+ the certificate of a trusted authority
+
+
+
+
+
+
+
+
+
+
+
+
+ A set of flags describing TLS certification validation. This can be
+used to describe why a particular certificate was rejected (for
+example, in #GTlsConnection::accept-certificate).
+
+GLib guarantees that if certificate verification fails, at least one
+flag will be set, but it does not guarantee that all possible flags
+will be set. Accordingly, you may not safely decide to ignore any
+particular type of error. For example, it would be incorrect to mask
+%G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates,
+because this could potentially be the only error flag set even if
+other problems exist with the certificate.
+
+ No flags set. Since: 2.74
+
+
+ The signing certificate authority is
+ not known.
+
+
+ The certificate does not match the
+ expected identity of the site that it was retrieved from.
+
+
+ The certificate's activation time
+ is still in the future
+
+
+ The certificate has expired
+
+
+ The certificate has been revoked
+ according to the #GTlsConnection's certificate revocation list.
+
+
+ The certificate's algorithm is
+ considered insecure.
+
+
+ Some other error occurred validating
+ the certificate
+
+
+ the combination of all of the above
+ flags
+
+
+
+
+
+
+ Flags for g_tls_interaction_request_certificate(),
+g_tls_interaction_request_certificate_async(), and
+g_tls_interaction_invoke_request_certificate().
+
+ No flags
+
+
+
+ An error code used with %G_TLS_CHANNEL_BINDING_ERROR in a #GError to
+indicate a TLS channel binding retrieval error.
+
+ Either entire binding
+ retrieval facility or specific binding type is not implemented in the
+ TLS backend.
+
+
+ The handshake is not yet
+ complete on the connection which is a strong requirement for any existing
+ binding type.
+
+
+ Handshake is complete but
+ binding data is not available. That normally indicates the TLS
+ implementation failed to provide the binding data. For example, some
+ implementations do not provide a peer certificate for resumed connections.
+
+
+ Binding type is not supported
+ on the current connection. This error could be triggered when requesting
+ `tls-server-end-point` binding data for a certificate which has no hash
+ function or uses multiple hash functions.
+
+
+ Any other backend error
+ preventing binding data retrieval.
+
+
+ Gets the TLS channel binding error quark.
+
+ a #GQuark.
+
+
+
+
+
+ The type of TLS channel binding data to retrieve from #GTlsConnection
+or #GDtlsConnection, as documented by RFC 5929 or RFC 9266. The
+[`tls-unique-for-telnet`](https://tools.ietf.org/html/rfc5929#section-5)
+binding type is not currently implemented.
+
+ [`tls-unique`](https://tools.ietf.org/html/rfc5929#section-3) binding
+ type
+
+
+ [`tls-server-end-point`](https://tools.ietf.org/html/rfc5929#section-4)
+ binding type
+
+
+ [`tls-exporter`](https://www.rfc-editor.org/rfc/rfc9266.html) binding
+ type. Since: 2.74
+
+
+
+ #GTlsClientConnection is the client-side subclass of
+#GTlsConnection, representing a client-side TLS connection.
+
+
+
+ Creates a new #GTlsClientConnection wrapping @base_io_stream (which
+must have pollable input and output streams) which is assumed to
+communicate with the server identified by @server_identity.
+
+See the documentation for #GTlsConnection:base-io-stream for restrictions
+on when application code can run operations on the @base_io_stream after
+this function has returned.
+
+
+ the new
+#GTlsClientConnection, or %NULL on error
+
+
+
+
+ the #GIOStream to wrap
+
+
+
+ the expected identity of the server
+
+
+
+
+
+ Possibly copies session state from one connection to another, for use
+in TLS session resumption. This is not normally needed, but may be
+used when the same session needs to be used between different
+endpoints, as is required by some protocols, such as FTP over TLS.
+@source should have already completed a handshake and, since TLS 1.3,
+it should have been used to read data at least once. @conn should not
+have completed a handshake.
+
+It is not possible to know whether a call to this function will
+actually do anything. Because session resumption is normally used
+only for performance benefit, the TLS backend might not implement
+this function. Even if implemented, it may not actually succeed in
+allowing @conn to resume @source's TLS session, because the server
+may not have sent a session resumption token to @source, or it may
+refuse to accept the token from @conn. There is no way to know
+whether a call to this function is actually successful.
+
+Using this function is not required to benefit from session
+resumption. If the TLS backend supports session resumption, the
+session will be resumed automatically if it is possible to do so
+without weakening the privacy guarantees normally provided by TLS,
+without need to call this function. For example, with TLS 1.3,
+a session ticket will be automatically copied from any
+#GTlsClientConnection that has previously received session tickets
+from the server, provided a ticket is available that has not
+previously been used for session resumption, since session ticket
+reuse would be a privacy weakness. Using this function causes the
+ticket to be copied without regard for privacy considerations.
+
+
+
+
+
+
+ a #GTlsClientConnection
+
+
+
+ a #GTlsClientConnection
+
+
+
+
+
+ Possibly copies session state from one connection to another, for use
+in TLS session resumption. This is not normally needed, but may be
+used when the same session needs to be used between different
+endpoints, as is required by some protocols, such as FTP over TLS.
+@source should have already completed a handshake and, since TLS 1.3,
+it should have been used to read data at least once. @conn should not
+have completed a handshake.
+
+It is not possible to know whether a call to this function will
+actually do anything. Because session resumption is normally used
+only for performance benefit, the TLS backend might not implement
+this function. Even if implemented, it may not actually succeed in
+allowing @conn to resume @source's TLS session, because the server
+may not have sent a session resumption token to @source, or it may
+refuse to accept the token from @conn. There is no way to know
+whether a call to this function is actually successful.
+
+Using this function is not required to benefit from session
+resumption. If the TLS backend supports session resumption, the
+session will be resumed automatically if it is possible to do so
+without weakening the privacy guarantees normally provided by TLS,
+without need to call this function. For example, with TLS 1.3,
+a session ticket will be automatically copied from any
+#GTlsClientConnection that has previously received session tickets
+from the server, provided a ticket is available that has not
+previously been used for session resumption, since session ticket
+reuse would be a privacy weakness. Using this function causes the
+ticket to be copied without regard for privacy considerations.
+
+
+
+
+
+
+ a #GTlsClientConnection
+
+
+
+ a #GTlsClientConnection
+
+
+
+
+
+ Gets the list of distinguished names of the Certificate Authorities
+that the server will accept certificates from. This will be set
+during the TLS handshake if the server requests a certificate.
+Otherwise, it will be %NULL.
+
+Each item in the list is a #GByteArray which contains the complete
+subject DN of the certificate authority.
+
+
+ the list of
+CA DNs. You should unref each element with g_byte_array_unref() and then
+the free the list with g_list_free().
+
+
+
+
+
+
+
+
+ the #GTlsClientConnection
+
+
+
+
+
+ Gets @conn's expected server identity
+
+
+ a #GSocketConnectable describing the
+expected server identity, or %NULL if the expected identity is not
+known.
+
+
+
+
+ the #GTlsClientConnection
+
+
+
+
+
+ SSL 3.0 is no longer supported. See
+g_tls_client_connection_set_use_ssl3() for details.
+ SSL 3.0 is insecure.
+
+
+ %FALSE
+
+
+
+
+ the #GTlsClientConnection
+
+
+
+
+
+ Gets @conn's validation flags
+
+This function does not work as originally designed and is impossible
+to use correctly. See #GTlsClientConnection:validation-flags for more
+information.
+ Do not attempt to ignore validation errors.
+
+
+ the validation flags
+
+
+
+
+ the #GTlsClientConnection
+
+
+
+
+
+ Sets @conn's expected server identity, which is used both to tell
+servers on virtual hosts which certificate to present, and also
+to let @conn know what name to look for in the certificate when
+performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled.
+
+
+
+
+
+
+ the #GTlsClientConnection
+
+
+
+ a #GSocketConnectable describing the expected server identity
+
+
+
+
+
+ Since GLib 2.42.1, SSL 3.0 is no longer supported.
+
+From GLib 2.42.1 through GLib 2.62, this function could be used to
+force use of TLS 1.0, the lowest-supported TLS protocol version at
+the time. In the past, this was needed to connect to broken TLS
+servers that exhibited protocol version intolerance. Such servers
+are no longer common, and using TLS 1.0 is no longer considered
+acceptable.
+
+Since GLib 2.64, this function does nothing.
+ SSL 3.0 is insecure.
+
+
+
+
+
+
+ the #GTlsClientConnection
+
+
+
+ a #gboolean, ignored
+
+
+
+
+
+ Sets @conn's validation flags, to override the default set of
+checks performed when validating a server certificate. By default,
+%G_TLS_CERTIFICATE_VALIDATE_ALL is used.
+
+This function does not work as originally designed and is impossible
+to use correctly. See #GTlsClientConnection:validation-flags for more
+information.
+ Do not attempt to ignore validation errors.
+
+
+
+
+
+
+ the #GTlsClientConnection
+
+
+
+ the #GTlsCertificateFlags to use
+
+
+
+
+
+ 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.
+
+
+
+
+
+ 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.
+
+
+
+ SSL 3.0 is no longer supported. See
+g_tls_client_connection_set_use_ssl3() for details.
+ SSL 3.0 is insecure.
+
+
+
+ What steps to perform when validating a certificate received from
+a server. Server certificates that fail to validate in any of the
+ways indicated here will be rejected unless the application
+overrides the default via #GTlsConnection::accept-certificate.
+
+GLib guarantees that if certificate verification fails, at least one
+flag will be set, but it does not guarantee that all possible flags
+will be set. Accordingly, you may not safely decide to ignore any
+particular type of error. For example, it would be incorrect to mask
+%G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates,
+because this could potentially be the only error flag set even if
+other problems exist with the certificate. Therefore, there is no
+safe way to use this property. This is not a horrible problem,
+though, because you should not be attempting to ignore validation
+errors anyway. If you really must ignore TLS certificate errors,
+connect to #GTlsConnection::accept-certificate.
+ Do not attempt to ignore validation errors.
+
+
+
+
+ vtable for a #GTlsClientConnection implementation.
+
+
+ The parent interface.
+
+
+
+
+
+
+
+
+
+
+ a #GTlsClientConnection
+
+
+
+ a #GTlsClientConnection
+
+
+
+
+
+
+
+ #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.
+
+For DTLS (Datagram TLS) support, see #GDtlsConnection.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Gets the name of the application-layer protocol negotiated during
+the handshake.
+
+If the peer did not use the ALPN extension, or did not advertise a
+protocol that matched one of @conn's protocols, or the TLS backend
+does not support ALPN, then this will be %NULL. See
+g_tls_connection_set_advertised_protocols().
+
+
+ the negotiated protocol, or %NULL
+
+
+
+
+ a #GTlsConnection
+
+
+
+
+
+ Attempts a TLS handshake on @conn.
+
+On the client side, it is never necessary to call this method;
+although the connection needs to perform a handshake after
+connecting (or after sending a "STARTTLS"-type command),
+#GTlsConnection will handle this for you automatically when you try
+to send or receive data on the connection. You can call
+g_tls_connection_handshake() manually if you want to know whether
+the initial handshake succeeded or failed (as opposed to just
+immediately trying to use @conn to read or write, in which case,
+if it fails, it may not be possible to tell if it failed before or
+after completing the handshake), but beware that servers may reject
+client authentication after the handshake has completed, so a
+successful handshake does not indicate the connection will be usable.
+
+Likewise, on the server side, although a handshake is necessary at
+the beginning of the communication, you do not need to call this
+function explicitly unless you want clearer error reporting.
+
+Previously, calling g_tls_connection_handshake() after the initial
+handshake would trigger a rehandshake; however, this usage was
+deprecated in GLib 2.60 because rehandshaking was removed from the
+TLS protocol in TLS 1.3. Since GLib 2.64, calling this function after
+the initial handshake will no longer do anything.
+
+When using a #GTlsConnection created by #GSocketClient, the
+#GSocketClient performs the initial handshake, so calling this
+function manually is not recommended.
+
+#GTlsConnection::accept_certificate may be emitted during the
+handshake.
+
+
+ success or failure
+
+
+
+
+ a #GTlsConnection
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Asynchronously performs a TLS handshake on @conn. See
+g_tls_connection_handshake() for more information.
+
+
+
+
+
+
+ a #GTlsConnection
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call when the handshake is complete
+
+
+
+ the data to pass to the callback function
+
+
+
+
+
+ Finish an asynchronous TLS handshake operation. See
+g_tls_connection_handshake() for more information.
+
+
+ %TRUE on success, %FALSE on failure, in which
+case @error will be set.
+
+
+
+
+ a #GTlsConnection
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Used by #GTlsConnection implementations to emit the
+#GTlsConnection::accept-certificate signal.
+
+
+ %TRUE if one of the signal handlers has returned
+ %TRUE to accept @peer_cert
+
+
+
+
+ a #GTlsConnection
+
+
+
+ the peer's #GTlsCertificate
+
+
+
+ the problems with @peer_cert
+
+
+
+
+
+ Gets @conn's certificate, as set by
+g_tls_connection_set_certificate().
+
+
+ @conn's certificate, or %NULL
+
+
+
+
+ a #GTlsConnection
+
+
+
+
+
+ Query the TLS backend for TLS channel binding data of @type for @conn.
+
+This call retrieves TLS channel binding data as specified in RFC
+[5056](https://tools.ietf.org/html/rfc5056), RFC
+[5929](https://tools.ietf.org/html/rfc5929), and related RFCs. The
+binding data is returned in @data. The @data is resized by the callee
+using #GByteArray buffer management and will be freed when the @data
+is destroyed by g_byte_array_unref(). If @data is %NULL, it will only
+check whether TLS backend is able to fetch the data (e.g. whether @type
+is supported by the TLS backend). It does not guarantee that the data
+will be available though. That could happen if TLS connection does not
+support @type or the binding data is not available yet due to additional
+negotiation or input required.
+
+
+ %TRUE on success, %FALSE otherwise
+
+
+
+
+ a #GTlsConnection
+
+
+
+ #GTlsChannelBindingType type of data to fetch
+
+
+
+ #GByteArray is
+ filled with the binding data, or %NULL
+
+
+
+
+
+
+
+ Returns the name of the current TLS ciphersuite, or %NULL if the
+connection has not handshaked or has been closed. Beware that the TLS
+backend may use any of multiple different naming conventions, because
+OpenSSL and GnuTLS have their own ciphersuite naming conventions that
+are different from each other and different from the standard, IANA-
+registered ciphersuite names. The ciphersuite name is intended to be
+displayed to the user for informative purposes only, and parsing it
+is not recommended.
+
+
+ The name of the current TLS ciphersuite, or %NULL
+
+
+
+
+ a #GTlsConnection
+
+
+
+
+
+ Gets the certificate database that @conn uses to verify
+peer certificates. See g_tls_connection_set_database().
+
+
+ the certificate database that @conn uses or %NULL
+
+
+
+
+ a #GTlsConnection
+
+
+
+
+
+ Get the object that will be used to interact with the user. It will be used
+for things like prompting the user for passwords. If %NULL is returned, then
+no user interaction will occur for this connection.
+
+
+ The interaction object.
+
+
+
+
+ a connection
+
+
+
+
+
+ Gets the name of the application-layer protocol negotiated during
+the handshake.
+
+If the peer did not use the ALPN extension, or did not advertise a
+protocol that matched one of @conn's protocols, or the TLS backend
+does not support ALPN, then this will be %NULL. See
+g_tls_connection_set_advertised_protocols().
+
+
+ the negotiated protocol, or %NULL
+
+
+
+
+ a #GTlsConnection
+
+
+
+
+
+ Gets @conn's peer's certificate after the handshake has completed
+or failed. (It is not set during the emission of
+#GTlsConnection::accept-certificate.)
+
+
+ @conn's peer's certificate, or %NULL
+
+
+
+
+ a #GTlsConnection
+
+
+
+
+
+ Gets the errors associated with validating @conn's peer's
+certificate, after the handshake has completed or failed. (It is
+not set during the emission of #GTlsConnection::accept-certificate.)
+
+See #GTlsConnection:peer-certificate-errors for more information.
+
+
+ @conn's peer's certificate errors
+
+
+
+
+ a #GTlsConnection
+
+
+
+
+
+ Returns the current TLS protocol version, which may be
+%G_TLS_PROTOCOL_VERSION_UNKNOWN if the connection has not handshaked, or
+has been closed, or if the TLS backend has implemented a protocol version
+that is not a recognized #GTlsProtocolVersion.
+
+
+ The current TLS protocol version
+
+
+
+
+ a #GTlsConnection
+
+
+
+
+
+ Gets @conn rehandshaking mode. See
+g_tls_connection_set_rehandshake_mode() for details.
+ Changing the rehandshake mode is no longer
+ required for compatibility. Also, rehandshaking has been removed
+ from the TLS protocol in TLS 1.3.
+
+
+ %G_TLS_REHANDSHAKE_SAFELY
+
+
+
+
+ a #GTlsConnection
+
+
+
+
+
+ Tests whether or not @conn expects a proper TLS close notification
+when the connection is closed. See
+g_tls_connection_set_require_close_notify() for details.
+
+
+ %TRUE if @conn requires a proper TLS close
+notification.
+
+
+
+
+ a #GTlsConnection
+
+
+
+
+
+ Gets whether @conn uses the system certificate database to verify
+peer certificates. See g_tls_connection_set_use_system_certdb().
+ Use g_tls_connection_get_database() instead
+
+
+ whether @conn uses the system certificate database
+
+
+
+
+ a #GTlsConnection
+
+
+
+
+
+ Attempts a TLS handshake on @conn.
+
+On the client side, it is never necessary to call this method;
+although the connection needs to perform a handshake after
+connecting (or after sending a "STARTTLS"-type command),
+#GTlsConnection will handle this for you automatically when you try
+to send or receive data on the connection. You can call
+g_tls_connection_handshake() manually if you want to know whether
+the initial handshake succeeded or failed (as opposed to just
+immediately trying to use @conn to read or write, in which case,
+if it fails, it may not be possible to tell if it failed before or
+after completing the handshake), but beware that servers may reject
+client authentication after the handshake has completed, so a
+successful handshake does not indicate the connection will be usable.
+
+Likewise, on the server side, although a handshake is necessary at
+the beginning of the communication, you do not need to call this
+function explicitly unless you want clearer error reporting.
+
+Previously, calling g_tls_connection_handshake() after the initial
+handshake would trigger a rehandshake; however, this usage was
+deprecated in GLib 2.60 because rehandshaking was removed from the
+TLS protocol in TLS 1.3. Since GLib 2.64, calling this function after
+the initial handshake will no longer do anything.
+
+When using a #GTlsConnection created by #GSocketClient, the
+#GSocketClient performs the initial handshake, so calling this
+function manually is not recommended.
+
+#GTlsConnection::accept_certificate may be emitted during the
+handshake.
+
+
+ success or failure
+
+
+
+
+ a #GTlsConnection
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Asynchronously performs a TLS handshake on @conn. See
+g_tls_connection_handshake() for more information.
+
+
+
+
+
+
+ a #GTlsConnection
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call when the handshake is complete
+
+
+
+ the data to pass to the callback function
+
+
+
+
+
+ Finish an asynchronous TLS handshake operation. See
+g_tls_connection_handshake() for more information.
+
+
+ %TRUE on success, %FALSE on failure, in which
+case @error will be set.
+
+
+
+
+ a #GTlsConnection
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Sets the list of application-layer protocols to advertise that the
+caller is willing to speak on this connection. The
+Application-Layer Protocol Negotiation (ALPN) extension will be
+used to negotiate a compatible protocol with the peer; use
+g_tls_connection_get_negotiated_protocol() to find the negotiated
+protocol after the handshake. Specifying %NULL for the the value
+of @protocols will disable ALPN negotiation.
+
+See [IANA TLS ALPN Protocol IDs](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids)
+for a list of registered protocol IDs.
+
+
+
+
+
+
+ a #GTlsConnection
+
+
+
+ a %NULL-terminated
+ array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL
+
+
+
+
+
+
+
+ This sets the certificate that @conn will present to its peer
+during the TLS handshake. For a #GTlsServerConnection, it is
+mandatory to set this, and that will normally be done at construct
+time.
+
+For a #GTlsClientConnection, this is optional. If a handshake fails
+with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server
+requires a certificate, and if you try connecting again, you should
+call this method first. You can call
+g_tls_client_connection_get_accepted_cas() on the failed connection
+to get a list of Certificate Authorities that the server will
+accept certificates from.
+
+(It is also possible that a server will allow the connection with
+or without a certificate; in that case, if you don't provide a
+certificate, you can tell that the server requested one by the fact
+that g_tls_client_connection_get_accepted_cas() will return
+non-%NULL.)
+
+
+
+
+
+
+ a #GTlsConnection
+
+
+
+ the certificate to use for @conn
+
+
+
+
+
+ Sets the certificate database that is used to verify peer certificates.
+This is set to the default database by default. See
+g_tls_backend_get_default_database(). If set to %NULL, then
+peer certificate validation will always set the
+%G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
+#GTlsConnection::accept-certificate will always be emitted on
+client-side connections, unless that bit is not set in
+#GTlsClientConnection:validation-flags).
+
+There are nonintuitive security implications when using a non-default
+database. See #GTlsConnection:database for details.
+
+
+
+
+
+
+ a #GTlsConnection
+
+
+
+ a #GTlsDatabase
+
+
+
+
+
+ Set the object that will be used to interact with the user. It will be used
+for things like prompting the user for passwords.
+
+The @interaction argument will normally be a derived subclass of
+#GTlsInteraction. %NULL can also be provided if no user interaction
+should occur for this connection.
+
+
+
+
+
+
+ a connection
+
+
+
+ an interaction object, or %NULL
+
+
+
+
+
+ Since GLib 2.64, changing the rehandshake mode is no longer supported
+and will have no effect. With TLS 1.3, rehandshaking has been removed from
+the TLS protocol, replaced by separate post-handshake authentication and
+rekey operations.
+ Changing the rehandshake mode is no longer
+ required for compatibility. Also, rehandshaking has been removed
+ from the TLS protocol in TLS 1.3.
+
+
+
+
+
+
+ a #GTlsConnection
+
+
+
+ the rehandshaking mode
+
+
+
+
+
+ Sets whether or not @conn expects a proper TLS close notification
+before the connection is closed. If this is %TRUE (the default),
+then @conn will expect to receive a TLS close notification from its
+peer before the connection is closed, and will return a
+%G_TLS_ERROR_EOF error if the connection is closed without proper
+notification (since this may indicate a network error, or
+man-in-the-middle attack).
+
+In some protocols, the application will know whether or not the
+connection was closed cleanly based on application-level data
+(because the application-level data includes a length field, or is
+somehow self-delimiting); in this case, the close notify is
+redundant and sometimes omitted. (TLS 1.1 explicitly allows this;
+in TLS 1.0 it is technically an error, but often done anyway.) You
+can use g_tls_connection_set_require_close_notify() to tell @conn
+to allow an "unannounced" connection close, in which case the close
+will show up as a 0-length read, as in a non-TLS
+#GSocketConnection, and it is up to the application to check that
+the data has been fully received.
+
+Note that this only affects the behavior when the peer closes the
+connection; when the application calls g_io_stream_close() itself
+on @conn, this will send a close notification regardless of the
+setting of this property. If you explicitly want to do an unclean
+close, you can close @conn's #GTlsConnection:base-io-stream rather
+than closing @conn itself, but note that this may only be done when no other
+operations are pending on @conn or the base I/O stream.
+
+
+
+
+
+
+ a #GTlsConnection
+
+
+
+ whether or not to require close notification
+
+
+
+
+
+ Sets whether @conn uses the system certificate database to verify
+peer certificates. This is %TRUE by default. If set to %FALSE, then
+peer certificate validation will always set the
+%G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
+#GTlsConnection::accept-certificate will always be emitted on
+client-side connections, unless that bit is not set in
+#GTlsClientConnection:validation-flags).
+ Use g_tls_connection_set_database() instead
+
+
+
+
+
+
+ a #GTlsConnection
+
+
+
+ whether to use the system certificate database
+
+
+
+
+
+ The list of application-layer protocols that the connection
+advertises that it is willing to speak. See
+g_tls_connection_set_advertised_protocols().
+
+
+
+
+
+ The #GIOStream that the connection wraps. The connection holds a reference
+to this stream, and may run operations on the stream from other threads
+throughout its lifetime. Consequently, after the #GIOStream has been
+constructed, application code may only run its own operations on this
+stream when no #GIOStream operations are running.
+
+
+
+ The connection's certificate; see
+g_tls_connection_set_certificate().
+
+
+
+ The name of the TLS ciphersuite in use. See g_tls_connection_get_ciphersuite_name().
+
+
+
+ The certificate database to use when verifying this TLS connection.
+If no certificate database is set, then the default database will be
+used. See g_tls_backend_get_default_database().
+
+When using a non-default database, #GTlsConnection must fall back to using
+the #GTlsDatabase to perform certificate verification using
+g_tls_database_verify_chain(), which means certificate verification will
+not be able to make use of TLS session context. This may be less secure.
+For example, if you create your own #GTlsDatabase that just wraps the
+default #GTlsDatabase, you might expect that you have not changed anything,
+but this is not true because you may have altered the behavior of
+#GTlsConnection by causing it to use g_tls_database_verify_chain(). See the
+documentation of g_tls_database_verify_chain() for more details on specific
+security checks that may not be performed. Accordingly, setting a
+non-default database is discouraged except for specialty applications with
+unusual security requirements.
+
+
+
+ A #GTlsInteraction object to be used when the connection or certificate
+database need to interact with the user. This will be used to prompt the
+user for passwords where necessary.
+
+
+
+ The application-layer protocol negotiated during the TLS
+handshake. See g_tls_connection_get_negotiated_protocol().
+
+
+
+ The connection's peer's certificate, after the TLS handshake has
+completed or failed. Note in particular that this is not yet set
+during the emission of #GTlsConnection::accept-certificate.
+
+(You can watch for a #GObject::notify signal on this property to
+detect when a handshake has occurred.)
+
+
+
+ The errors noticed while verifying
+#GTlsConnection:peer-certificate. Normally this should be 0, but
+it may not be if #GTlsClientConnection:validation-flags is not
+%G_TLS_CERTIFICATE_VALIDATE_ALL, or if
+#GTlsConnection::accept-certificate overrode the default
+behavior.
+
+GLib guarantees that if certificate verification fails, at least
+one error will be set, but it does not guarantee that all possible
+errors will be set. Accordingly, you may not safely decide to
+ignore any particular type of error. For example, it would be
+incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow
+expired certificates, because this could potentially be the only
+error flag set even if other problems exist with the certificate.
+
+
+
+ The TLS protocol version in use. See g_tls_connection_get_protocol_version().
+
+
+
+ The rehandshaking mode. See
+g_tls_connection_set_rehandshake_mode().
+ The rehandshake mode is ignored.
+
+
+
+ Whether or not proper TLS close notification is required.
+See g_tls_connection_set_require_close_notify().
+
+
+
+ Whether or not the system certificate database will be used to
+verify peer certificates. See
+g_tls_connection_set_use_system_certdb().
+ Use GTlsConnection:database instead
+
+
+
+
+
+
+
+
+
+ Emitted during the TLS handshake after the peer certificate has
+been received. You can examine @peer_cert's certification path by
+calling g_tls_certificate_get_issuer() on it.
+
+For a client-side connection, @peer_cert is the server's
+certificate, and the signal will only be emitted if the
+certificate was not acceptable according to @conn's
+#GTlsClientConnection:validation_flags. If you would like the
+certificate to be accepted despite @errors, return %TRUE from the
+signal handler. Otherwise, if no handler accepts the certificate,
+the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE.
+
+GLib guarantees that if certificate verification fails, this signal
+will be emitted with at least one error will be set in @errors, but
+it does not guarantee that all possible errors will be set.
+Accordingly, you may not safely decide to ignore any particular
+type of error. For example, it would be incorrect to ignore
+%G_TLS_CERTIFICATE_EXPIRED if you want to allow expired
+certificates, because this could potentially be the only error flag
+set even if other problems exist with the certificate.
+
+For a server-side connection, @peer_cert is the certificate
+presented by the client, if this was requested via the server's
+#GTlsServerConnection:authentication_mode. On the server side,
+the signal is always emitted when the client presents a
+certificate, and the certificate will only be accepted if a
+handler returns %TRUE.
+
+Note that if this signal is emitted as part of asynchronous I/O
+in the main thread, then you should not attempt to interact with
+the user before returning from the signal handler. If you want to
+let the user decide whether or not to accept the certificate, you
+would have to return %FALSE from the signal handler on the first
+attempt, and then after the connection attempt returns a
+%G_TLS_ERROR_BAD_CERTIFICATE, you can interact with the user, and
+if the user decides to accept the certificate, remember that fact,
+create a new connection, and return %TRUE from the signal handler
+the next time.
+
+If you are doing I/O in another thread, you do not
+need to worry about this, and can simply block in the signal
+handler until the UI thread returns an answer.
+
+ %TRUE to accept @peer_cert (which will also
+immediately end the signal emission). %FALSE to allow the signal
+emission to continue, which will cause the handshake to fail if
+no one else overrides it.
+
+
+
+
+ the peer's #GTlsCertificate
+
+
+
+ the problems with @peer_cert.
+
+
+
+
+
+
+ The class structure for the #GTlsConnection type.
+
+
+ The parent class.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ success or failure
+
+
+
+
+ a #GTlsConnection
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GTlsConnection
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call when the handshake is complete
+
+
+
+ the data to pass to the callback function
+
+
+
+
+
+
+
+
+
+ %TRUE on success, %FALSE on failure, in which
+case @error will be set.
+
+
+
+
+ a #GTlsConnection
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ the negotiated protocol, or %NULL
+
+
+
+
+ a #GTlsConnection
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #GTlsDatabase is used to look up certificates and other information
+from a certificate or key store. It is an abstract base class which
+TLS library specific subtypes override.
+
+A #GTlsDatabase may be accessed from multiple threads by the TLS backend.
+All implementations are required to be fully thread-safe.
+
+Most common client applications will not directly interact with
+#GTlsDatabase. It is used internally by #GTlsConnection.
+
+
+ Create a handle string for the certificate. The database will only be able
+to create a handle for certificates that originate from the database. In
+cases where the database cannot create a handle for a certificate, %NULL
+will be returned.
+
+This handle should be stable across various instances of the application,
+and between applications. If a certificate is modified in the database,
+then it is not guaranteed that this handle will continue to point to it.
+
+
+ a newly allocated string containing the
+handle.
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ certificate for which to create a handle.
+
+
+
+
+
+ Look up a certificate by its handle.
+
+The handle should have been created by calling
+g_tls_database_create_certificate_handle() on a #GTlsDatabase object of
+the same TLS backend. The handle is designed to remain valid across
+instantiations of the database.
+
+If the handle is no longer valid, or does not point to a certificate in
+this database, then %NULL will be returned.
+
+This function can block, use g_tls_database_lookup_certificate_for_handle_async() to perform
+the lookup operation asynchronously.
+
+
+ a newly allocated
+#GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate.
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a certificate handle
+
+
+
+ used to interact with the user if necessary
+
+
+
+ Flags which affect the lookup.
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Asynchronously look up a certificate by its handle in the database. See
+g_tls_database_lookup_certificate_for_handle() for more information.
+
+
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a certificate handle
+
+
+
+ used to interact with the user if necessary
+
+
+
+ Flags which affect the lookup.
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call when the operation completes
+
+
+
+ the data to pass to the callback function
+
+
+
+
+
+ Finish an asynchronous lookup of a certificate by its handle. See
+g_tls_database_lookup_certificate_for_handle() for more information.
+
+If the handle is no longer valid, or does not point to a certificate in
+this database, then %NULL will be returned.
+
+
+ a newly allocated #GTlsCertificate object.
+Use g_object_unref() to release the certificate.
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Look up the issuer of @certificate in the database. The
+#GTlsCertificate:issuer property of @certificate is not modified, and
+the two certificates are not hooked into a chain.
+
+This function can block. Use g_tls_database_lookup_certificate_issuer_async()
+to perform the lookup operation asynchronously.
+
+Beware this function cannot be used to build certification paths. The
+issuer certificate returned by this function may not be the same as
+the certificate that would actually be used to construct a valid
+certification path during certificate verification.
+[RFC 4158](https://datatracker.ietf.org/doc/html/rfc4158) explains
+why an issuer certificate cannot be naively assumed to be part of the
+the certification path (though GLib's TLS backends may not follow the
+path building strategies outlined in this RFC). Due to the complexity
+of certification path building, GLib does not provide any way to know
+which certification path will actually be used when verifying a TLS
+certificate. Accordingly, this function cannot be used to make
+security-related decisions. Only GLib itself should make security
+decisions about TLS certificates.
+
+
+ a newly allocated issuer #GTlsCertificate,
+or %NULL. Use g_object_unref() to release the certificate.
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a #GTlsCertificate
+
+
+
+ used to interact with the user if necessary
+
+
+
+ flags which affect the lookup operation
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Asynchronously look up the issuer of @certificate in the database. See
+g_tls_database_lookup_certificate_issuer() for more information.
+
+
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a #GTlsCertificate
+
+
+
+ used to interact with the user if necessary
+
+
+
+ flags which affect the lookup operation
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call when the operation completes
+
+
+
+ the data to pass to the callback function
+
+
+
+
+
+ Finish an asynchronous lookup issuer operation. See
+g_tls_database_lookup_certificate_issuer() for more information.
+
+
+ a newly allocated issuer #GTlsCertificate,
+or %NULL. Use g_object_unref() to release the certificate.
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Look up certificates issued by this issuer in the database.
+
+This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform
+the lookup operation asynchronously.
+
+
+ a newly allocated list of #GTlsCertificate
+objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.
+
+
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a #GByteArray which holds the DER encoded issuer DN.
+
+
+
+
+
+ used to interact with the user if necessary
+
+
+
+ Flags which affect the lookup operation.
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Asynchronously look up certificates issued by this issuer in the database. See
+g_tls_database_lookup_certificates_issued_by() for more information.
+
+The database may choose to hold a reference to the issuer byte array for the duration
+of of this asynchronous operation. The byte array should not be modified during
+this time.
+
+
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a #GByteArray which holds the DER encoded issuer DN.
+
+
+
+
+
+ used to interact with the user if necessary
+
+
+
+ Flags which affect the lookup operation.
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call when the operation completes
+
+
+
+ the data to pass to the callback function
+
+
+
+
+
+ Finish an asynchronous lookup of certificates. See
+g_tls_database_lookup_certificates_issued_by() for more information.
+
+
+ a newly allocated list of #GTlsCertificate
+objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.
+
+
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Determines the validity of a certificate chain, outside the context
+of a TLS session.
+
+@chain is a chain of #GTlsCertificate objects each pointing to the next
+certificate in the chain by its #GTlsCertificate:issuer property.
+
+@purpose describes the purpose (or usage) for which the certificate
+is being used. Typically @purpose will be set to %G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER
+which means that the certificate is being used to authenticate a server
+(and we are acting as the client).
+
+The @identity is used to ensure the server certificate is valid for
+the expected peer identity. If the identity does not match the
+certificate, %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the
+return value. If @identity is %NULL, that bit will never be set in
+the return value. The peer identity may also be used to check for
+pinned certificates (trust exceptions) in the database. These may
+override the normal verification process on a host-by-host basis.
+
+Currently there are no @flags, and %G_TLS_DATABASE_VERIFY_NONE should be
+used.
+
+If @chain is found to be valid, then the return value will be 0. If
+@chain is found to be invalid, then the return value will indicate at
+least one problem found. If the function is unable to determine
+whether @chain is valid (for example, because @cancellable is
+triggered before it completes) then the return value will be
+%G_TLS_CERTIFICATE_GENERIC_ERROR and @error will be set accordingly.
+@error is not set when @chain is successfully analyzed but found to
+be invalid.
+
+GLib guarantees that if certificate verification fails, at least one
+error will be set in the return value, but it does not guarantee
+that all possible errors will be set. Accordingly, you may not safely
+decide to ignore any particular type of error. For example, it would
+be incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow
+expired certificates, because this could potentially be the only
+error flag set even if other problems exist with the certificate.
+
+Prior to GLib 2.48, GLib's default TLS backend modified @chain to
+represent the certification path built by #GTlsDatabase during
+certificate verification by adjusting the #GTlsCertificate:issuer
+property of each certificate in @chain. Since GLib 2.48, this no
+longer occurs, so you cannot rely on #GTlsCertificate:issuer to
+represent the actual certification path used during certificate
+verification.
+
+Because TLS session context is not used, #GTlsDatabase may not
+perform as many checks on the certificates as #GTlsConnection would.
+For example, certificate constraints may not be honored, and
+revocation checks may not be performed. The best way to verify TLS
+certificates used by a TLS connection is to let #GTlsConnection
+handle the verification.
+
+The TLS backend may attempt to look up and add missing certificates
+to the chain. This may involve HTTP requests to download missing
+certificates.
+
+This function can block. Use g_tls_database_verify_chain_async() to
+perform the verification operation asynchronously.
+
+
+ the appropriate #GTlsCertificateFlags which represents the
+result of verification.
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a #GTlsCertificate chain
+
+
+
+ the purpose that this certificate chain will be used for.
+
+
+
+ the expected peer identity
+
+
+
+ used to interact with the user if necessary
+
+
+
+ additional verify flags
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Asynchronously determines the validity of a certificate chain after
+looking up and adding any missing certificates to the chain. See
+g_tls_database_verify_chain() for more information.
+
+
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a #GTlsCertificate chain
+
+
+
+ the purpose that this certificate chain will be used for.
+
+
+
+ the expected peer identity
+
+
+
+ used to interact with the user if necessary
+
+
+
+ additional verify flags
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call when the operation completes
+
+
+
+ the data to pass to the callback function
+
+
+
+
+
+ Finish an asynchronous verify chain operation. See
+g_tls_database_verify_chain() for more information.
+
+If @chain is found to be valid, then the return value will be 0. If
+@chain is found to be invalid, then the return value will indicate
+the problems found. If the function is unable to determine whether
+@chain is valid or not (eg, because @cancellable is triggered
+before it completes) then the return value will be
+%G_TLS_CERTIFICATE_GENERIC_ERROR and @error will be set
+accordingly. @error is not set when @chain is successfully analyzed
+but found to be invalid.
+
+
+ the appropriate #GTlsCertificateFlags which represents the
+result of verification.
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Create a handle string for the certificate. The database will only be able
+to create a handle for certificates that originate from the database. In
+cases where the database cannot create a handle for a certificate, %NULL
+will be returned.
+
+This handle should be stable across various instances of the application,
+and between applications. If a certificate is modified in the database,
+then it is not guaranteed that this handle will continue to point to it.
+
+
+ a newly allocated string containing the
+handle.
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ certificate for which to create a handle.
+
+
+
+
+
+ Look up a certificate by its handle.
+
+The handle should have been created by calling
+g_tls_database_create_certificate_handle() on a #GTlsDatabase object of
+the same TLS backend. The handle is designed to remain valid across
+instantiations of the database.
+
+If the handle is no longer valid, or does not point to a certificate in
+this database, then %NULL will be returned.
+
+This function can block, use g_tls_database_lookup_certificate_for_handle_async() to perform
+the lookup operation asynchronously.
+
+
+ a newly allocated
+#GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate.
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a certificate handle
+
+
+
+ used to interact with the user if necessary
+
+
+
+ Flags which affect the lookup.
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Asynchronously look up a certificate by its handle in the database. See
+g_tls_database_lookup_certificate_for_handle() for more information.
+
+
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a certificate handle
+
+
+
+ used to interact with the user if necessary
+
+
+
+ Flags which affect the lookup.
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call when the operation completes
+
+
+
+ the data to pass to the callback function
+
+
+
+
+
+ Finish an asynchronous lookup of a certificate by its handle. See
+g_tls_database_lookup_certificate_for_handle() for more information.
+
+If the handle is no longer valid, or does not point to a certificate in
+this database, then %NULL will be returned.
+
+
+ a newly allocated #GTlsCertificate object.
+Use g_object_unref() to release the certificate.
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Look up the issuer of @certificate in the database. The
+#GTlsCertificate:issuer property of @certificate is not modified, and
+the two certificates are not hooked into a chain.
+
+This function can block. Use g_tls_database_lookup_certificate_issuer_async()
+to perform the lookup operation asynchronously.
+
+Beware this function cannot be used to build certification paths. The
+issuer certificate returned by this function may not be the same as
+the certificate that would actually be used to construct a valid
+certification path during certificate verification.
+[RFC 4158](https://datatracker.ietf.org/doc/html/rfc4158) explains
+why an issuer certificate cannot be naively assumed to be part of the
+the certification path (though GLib's TLS backends may not follow the
+path building strategies outlined in this RFC). Due to the complexity
+of certification path building, GLib does not provide any way to know
+which certification path will actually be used when verifying a TLS
+certificate. Accordingly, this function cannot be used to make
+security-related decisions. Only GLib itself should make security
+decisions about TLS certificates.
+
+
+ a newly allocated issuer #GTlsCertificate,
+or %NULL. Use g_object_unref() to release the certificate.
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a #GTlsCertificate
+
+
+
+ used to interact with the user if necessary
+
+
+
+ flags which affect the lookup operation
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Asynchronously look up the issuer of @certificate in the database. See
+g_tls_database_lookup_certificate_issuer() for more information.
+
+
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a #GTlsCertificate
+
+
+
+ used to interact with the user if necessary
+
+
+
+ flags which affect the lookup operation
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call when the operation completes
+
+
+
+ the data to pass to the callback function
+
+
+
+
+
+ Finish an asynchronous lookup issuer operation. See
+g_tls_database_lookup_certificate_issuer() for more information.
+
+
+ a newly allocated issuer #GTlsCertificate,
+or %NULL. Use g_object_unref() to release the certificate.
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Look up certificates issued by this issuer in the database.
+
+This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform
+the lookup operation asynchronously.
+
+
+ a newly allocated list of #GTlsCertificate
+objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.
+
+
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a #GByteArray which holds the DER encoded issuer DN.
+
+
+
+
+
+ used to interact with the user if necessary
+
+
+
+ Flags which affect the lookup operation.
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Asynchronously look up certificates issued by this issuer in the database. See
+g_tls_database_lookup_certificates_issued_by() for more information.
+
+The database may choose to hold a reference to the issuer byte array for the duration
+of of this asynchronous operation. The byte array should not be modified during
+this time.
+
+
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a #GByteArray which holds the DER encoded issuer DN.
+
+
+
+
+
+ used to interact with the user if necessary
+
+
+
+ Flags which affect the lookup operation.
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call when the operation completes
+
+
+
+ the data to pass to the callback function
+
+
+
+
+
+ Finish an asynchronous lookup of certificates. See
+g_tls_database_lookup_certificates_issued_by() for more information.
+
+
+ a newly allocated list of #GTlsCertificate
+objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.
+
+
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Determines the validity of a certificate chain, outside the context
+of a TLS session.
+
+@chain is a chain of #GTlsCertificate objects each pointing to the next
+certificate in the chain by its #GTlsCertificate:issuer property.
+
+@purpose describes the purpose (or usage) for which the certificate
+is being used. Typically @purpose will be set to %G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER
+which means that the certificate is being used to authenticate a server
+(and we are acting as the client).
+
+The @identity is used to ensure the server certificate is valid for
+the expected peer identity. If the identity does not match the
+certificate, %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the
+return value. If @identity is %NULL, that bit will never be set in
+the return value. The peer identity may also be used to check for
+pinned certificates (trust exceptions) in the database. These may
+override the normal verification process on a host-by-host basis.
+
+Currently there are no @flags, and %G_TLS_DATABASE_VERIFY_NONE should be
+used.
+
+If @chain is found to be valid, then the return value will be 0. If
+@chain is found to be invalid, then the return value will indicate at
+least one problem found. If the function is unable to determine
+whether @chain is valid (for example, because @cancellable is
+triggered before it completes) then the return value will be
+%G_TLS_CERTIFICATE_GENERIC_ERROR and @error will be set accordingly.
+@error is not set when @chain is successfully analyzed but found to
+be invalid.
+
+GLib guarantees that if certificate verification fails, at least one
+error will be set in the return value, but it does not guarantee
+that all possible errors will be set. Accordingly, you may not safely
+decide to ignore any particular type of error. For example, it would
+be incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow
+expired certificates, because this could potentially be the only
+error flag set even if other problems exist with the certificate.
+
+Prior to GLib 2.48, GLib's default TLS backend modified @chain to
+represent the certification path built by #GTlsDatabase during
+certificate verification by adjusting the #GTlsCertificate:issuer
+property of each certificate in @chain. Since GLib 2.48, this no
+longer occurs, so you cannot rely on #GTlsCertificate:issuer to
+represent the actual certification path used during certificate
+verification.
+
+Because TLS session context is not used, #GTlsDatabase may not
+perform as many checks on the certificates as #GTlsConnection would.
+For example, certificate constraints may not be honored, and
+revocation checks may not be performed. The best way to verify TLS
+certificates used by a TLS connection is to let #GTlsConnection
+handle the verification.
+
+The TLS backend may attempt to look up and add missing certificates
+to the chain. This may involve HTTP requests to download missing
+certificates.
+
+This function can block. Use g_tls_database_verify_chain_async() to
+perform the verification operation asynchronously.
+
+
+ the appropriate #GTlsCertificateFlags which represents the
+result of verification.
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a #GTlsCertificate chain
+
+
+
+ the purpose that this certificate chain will be used for.
+
+
+
+ the expected peer identity
+
+
+
+ used to interact with the user if necessary
+
+
+
+ additional verify flags
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+ Asynchronously determines the validity of a certificate chain after
+looking up and adding any missing certificates to the chain. See
+g_tls_database_verify_chain() for more information.
+
+
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a #GTlsCertificate chain
+
+
+
+ the purpose that this certificate chain will be used for.
+
+
+
+ the expected peer identity
+
+
+
+ used to interact with the user if necessary
+
+
+
+ additional verify flags
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call when the operation completes
+
+
+
+ the data to pass to the callback function
+
+
+
+
+
+ Finish an asynchronous verify chain operation. See
+g_tls_database_verify_chain() for more information.
+
+If @chain is found to be valid, then the return value will be 0. If
+@chain is found to be invalid, then the return value will indicate
+the problems found. If the function is unable to determine whether
+@chain is valid or not (eg, because @cancellable is triggered
+before it completes) then the return value will be
+%G_TLS_CERTIFICATE_GENERIC_ERROR and @error will be set
+accordingly. @error is not set when @chain is successfully analyzed
+but found to be invalid.
+
+
+ the appropriate #GTlsCertificateFlags which represents the
+result of verification.
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+
+
+
+ The class for #GTlsDatabase. Derived classes should implement the various
+virtual methods. _async and _finish methods have a default
+implementation that runs the corresponding sync method in a thread.
+
+
+
+
+
+
+
+
+ the appropriate #GTlsCertificateFlags which represents the
+result of verification.
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a #GTlsCertificate chain
+
+
+
+ the purpose that this certificate chain will be used for.
+
+
+
+ the expected peer identity
+
+
+
+ used to interact with the user if necessary
+
+
+
+ additional verify flags
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a #GTlsCertificate chain
+
+
+
+ the purpose that this certificate chain will be used for.
+
+
+
+ the expected peer identity
+
+
+
+ used to interact with the user if necessary
+
+
+
+ additional verify flags
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call when the operation completes
+
+
+
+ the data to pass to the callback function
+
+
+
+
+
+
+
+
+
+ the appropriate #GTlsCertificateFlags which represents the
+result of verification.
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+ a newly allocated string containing the
+handle.
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ certificate for which to create a handle.
+
+
+
+
+
+
+
+
+
+ a newly allocated
+#GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate.
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a certificate handle
+
+
+
+ used to interact with the user if necessary
+
+
+
+ Flags which affect the lookup.
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a certificate handle
+
+
+
+ used to interact with the user if necessary
+
+
+
+ Flags which affect the lookup.
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call when the operation completes
+
+
+
+ the data to pass to the callback function
+
+
+
+
+
+
+
+
+
+ a newly allocated #GTlsCertificate object.
+Use g_object_unref() to release the certificate.
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+ a newly allocated issuer #GTlsCertificate,
+or %NULL. Use g_object_unref() to release the certificate.
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a #GTlsCertificate
+
+
+
+ used to interact with the user if necessary
+
+
+
+ flags which affect the lookup operation
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a #GTlsCertificate
+
+
+
+ used to interact with the user if necessary
+
+
+
+ flags which affect the lookup operation
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call when the operation completes
+
+
+
+ the data to pass to the callback function
+
+
+
+
+
+
+
+
+
+ a newly allocated issuer #GTlsCertificate,
+or %NULL. Use g_object_unref() to release the certificate.
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+ a newly allocated list of #GTlsCertificate
+objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.
+
+
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a #GByteArray which holds the DER encoded issuer DN.
+
+
+
+
+
+ used to interact with the user if necessary
+
+
+
+ Flags which affect the lookup operation.
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a #GByteArray which holds the DER encoded issuer DN.
+
+
+
+
+
+ used to interact with the user if necessary
+
+
+
+ Flags which affect the lookup operation.
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+ callback to call when the operation completes
+
+
+
+ the data to pass to the callback function
+
+
+
+
+
+
+
+
+
+ a newly allocated list of #GTlsCertificate
+objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.
+
+
+
+
+
+
+ a #GTlsDatabase
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+
+
+
+
+
+
+
+ Flags for g_tls_database_lookup_certificate_for_handle(),
+g_tls_database_lookup_certificate_issuer(),
+and g_tls_database_lookup_certificates_issued_by().
+
+ No lookup flags
+
+
+ Restrict lookup to certificates that have
+ a private key.
+
+
+
+
+
+
+ Flags for g_tls_database_verify_chain().
+
+ No verification flags
+
+
+
+ An error code used with %G_TLS_ERROR in a #GError returned from a
+TLS-related routine.
+
+ No TLS provider is available
+
+
+ Miscellaneous TLS error
+
+
+ The certificate presented could not
+ be parsed or failed validation.
+
+
+ The TLS handshake failed because the
+ peer does not seem to be a TLS server.
+
+
+ The TLS handshake failed because the
+ peer's certificate was not acceptable.
+
+
+ The TLS handshake failed because
+ the server requested a client-side certificate, but none was
+ provided. See g_tls_connection_set_certificate().
+
+
+ The TLS connection was closed without proper
+ notice, which may indicate an attack. See
+ g_tls_connection_set_require_close_notify().
+
+
+ The TLS handshake failed
+ because the client sent the fallback SCSV, indicating a protocol
+ downgrade attack. Since: 2.60
+
+
+ The certificate failed
+ to load because a password was incorrect. Since: 2.72
+
+
+ Gets the TLS error quark.
+
+ a #GQuark.
+
+
+
+
+
+ #GTlsFileDatabase is implemented by #GTlsDatabase objects which load
+their certificate information from a file. It is an interface which
+TLS library specific subtypes implement.
+
+
+
+ Creates a new #GTlsFileDatabase which uses anchor certificate authorities
+in @anchors to verify certificate chains.
+
+The certificates in @anchors must be PEM encoded.
+
+
+ the new
+#GTlsFileDatabase, or %NULL on error
+
+
+
+
+ filename of anchor certificate authorities.
+
+
+
+
+
+ The path to a file containing PEM encoded certificate authority
+root anchors. The certificates in this file will be treated as
+root authorities for the purpose of verifying other certificates
+via the g_tls_database_verify_chain() operation.
+
+
+
+
+ Provides an interface for #GTlsFileDatabase implementations.
+
+
+ The parent interface.
+
+
+
+
+
+
+
+
+
+ #GTlsInteraction provides a mechanism for the TLS connection and database
+code to interact with the user. It can be used to ask the user for passwords.
+
+To use a #GTlsInteraction with a TLS connection use
+g_tls_connection_set_interaction().
+
+Callers should instantiate a derived class that implements the various
+interaction methods to show the required dialogs.
+
+Callers should use the 'invoke' functions like
+g_tls_interaction_invoke_ask_password() to run interaction methods. These
+functions make sure that the interaction is invoked in the main loop
+and not in the current thread, if the current thread is not running the
+main loop.
+
+Derived classes can choose to implement whichever interactions methods they'd
+like to support by overriding those virtual methods in their class
+initialization function. Any interactions not implemented will return
+%G_TLS_INTERACTION_UNHANDLED. If a derived class implements an async method,
+it must also implement the corresponding finish method.
+
+
+ Run synchronous interaction to ask the user for a password. In general,
+g_tls_interaction_invoke_ask_password() should be used instead of this
+function.
+
+Derived subclasses usually implement a password prompt, although they may
+also choose to provide a password from elsewhere. The @password value will
+be filled in and then @callback will be called. Alternatively the user may
+abort this password request, which will usually abort the TLS connection.
+
+If the interaction is cancelled by the cancellation object, or by the
+user then %G_TLS_INTERACTION_FAILED will be returned with an error that
+contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
+not support immediate cancellation.
+
+
+ The status of the ask password interaction.
+
+
+
+
+ a #GTlsInteraction object
+
+
+
+ a #GTlsPassword object
+
+
+
+ an optional #GCancellable cancellation object
+
+
+
+
+
+ Run asynchronous interaction to ask the user for a password. In general,
+g_tls_interaction_invoke_ask_password() should be used instead of this
+function.
+
+Derived subclasses usually implement a password prompt, although they may
+also choose to provide a password from elsewhere. The @password value will
+be filled in and then @callback will be called. Alternatively the user may
+abort this password request, which will usually abort the TLS connection.
+
+If the interaction is cancelled by the cancellation object, or by the
+user then %G_TLS_INTERACTION_FAILED will be returned with an error that
+contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
+not support immediate cancellation.
+
+Certain implementations may not support immediate cancellation.
+
+
+
+
+
+
+ a #GTlsInteraction object
+
+
+
+ a #GTlsPassword object
+
+
+
+ an optional #GCancellable cancellation object
+
+
+
+ will be called when the interaction completes
+
+
+
+ data to pass to the @callback
+
+
+
+
+
+ Complete an ask password user interaction request. This should be once
+the g_tls_interaction_ask_password_async() completion callback is called.
+
+If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsPassword passed
+to g_tls_interaction_ask_password() will have its password filled in.
+
+If the interaction is cancelled by the cancellation object, or by the
+user then %G_TLS_INTERACTION_FAILED will be returned with an error that
+contains a %G_IO_ERROR_CANCELLED error code.
+
+
+ The status of the ask password interaction.
+
+
+
+
+ a #GTlsInteraction object
+
+
+
+ the result passed to the callback
+
+
+
+
+
+ Run synchronous interaction to ask the user to choose a certificate to use
+with the connection. In general, g_tls_interaction_invoke_request_certificate()
+should be used instead of this function.
+
+Derived subclasses usually implement a certificate selector, although they may
+also choose to provide a certificate from elsewhere. Alternatively the user may
+abort this certificate request, which will usually abort the TLS connection.
+
+If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection
+passed to g_tls_interaction_request_certificate() will have had its
+#GTlsConnection:certificate filled in.
+
+If the interaction is cancelled by the cancellation object, or by the
+user then %G_TLS_INTERACTION_FAILED will be returned with an error that
+contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
+not support immediate cancellation.
+
+
+ The status of the request certificate interaction.
+
+
+
+
+ a #GTlsInteraction object
+
+
+
+ a #GTlsConnection object
+
+
+
+ flags providing more information about the request
+
+
+
+ an optional #GCancellable cancellation object
+
+
+
+
+
+ Run asynchronous interaction to ask the user for a certificate to use with
+the connection. In general, g_tls_interaction_invoke_request_certificate() should
+be used instead of this function.
+
+Derived subclasses usually implement a certificate selector, although they may
+also choose to provide a certificate from elsewhere. @callback will be called
+when the operation completes. Alternatively the user may abort this certificate
+request, which will usually abort the TLS connection.
+
+
+
+
+
+
+ a #GTlsInteraction object
+
+
+
+ a #GTlsConnection object
+
+
+
+ flags providing more information about the request
+
+
+
+ an optional #GCancellable cancellation object
+
+
+
+ will be called when the interaction completes
+
+
+
+ data to pass to the @callback
+
+
+
+
+
+ Complete a request certificate user interaction request. This should be once
+the g_tls_interaction_request_certificate_async() completion callback is called.
+
+If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection
+passed to g_tls_interaction_request_certificate_async() will have had its
+#GTlsConnection:certificate filled in.
+
+If the interaction is cancelled by the cancellation object, or by the
+user then %G_TLS_INTERACTION_FAILED will be returned with an error that
+contains a %G_IO_ERROR_CANCELLED error code.
+
+
+ The status of the request certificate interaction.
+
+
+
+
+ a #GTlsInteraction object
+
+
+
+ the result passed to the callback
+
+
+
+
+
+ Run synchronous interaction to ask the user for a password. In general,
+g_tls_interaction_invoke_ask_password() should be used instead of this
+function.
+
+Derived subclasses usually implement a password prompt, although they may
+also choose to provide a password from elsewhere. The @password value will
+be filled in and then @callback will be called. Alternatively the user may
+abort this password request, which will usually abort the TLS connection.
+
+If the interaction is cancelled by the cancellation object, or by the
+user then %G_TLS_INTERACTION_FAILED will be returned with an error that
+contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
+not support immediate cancellation.
+
+
+ The status of the ask password interaction.
+
+
+
+
+ a #GTlsInteraction object
+
+
+
+ a #GTlsPassword object
+
+
+
+ an optional #GCancellable cancellation object
+
+
+
+
+
+ Run asynchronous interaction to ask the user for a password. In general,
+g_tls_interaction_invoke_ask_password() should be used instead of this
+function.
+
+Derived subclasses usually implement a password prompt, although they may
+also choose to provide a password from elsewhere. The @password value will
+be filled in and then @callback will be called. Alternatively the user may
+abort this password request, which will usually abort the TLS connection.
+
+If the interaction is cancelled by the cancellation object, or by the
+user then %G_TLS_INTERACTION_FAILED will be returned with an error that
+contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
+not support immediate cancellation.
+
+Certain implementations may not support immediate cancellation.
+
+
+
+
+
+
+ a #GTlsInteraction object
+
+
+
+ a #GTlsPassword object
+
+
+
+ an optional #GCancellable cancellation object
+
+
+
+ will be called when the interaction completes
+
+
+
+ data to pass to the @callback
+
+
+
+
+
+ Complete an ask password user interaction request. This should be once
+the g_tls_interaction_ask_password_async() completion callback is called.
+
+If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsPassword passed
+to g_tls_interaction_ask_password() will have its password filled in.
+
+If the interaction is cancelled by the cancellation object, or by the
+user then %G_TLS_INTERACTION_FAILED will be returned with an error that
+contains a %G_IO_ERROR_CANCELLED error code.
+
+
+ The status of the ask password interaction.
+
+
+
+
+ a #GTlsInteraction object
+
+
+
+ the result passed to the callback
+
+
+
+
+
+ Invoke the interaction to ask the user for a password. It invokes this
+interaction in the main loop, specifically the #GMainContext returned by
+g_main_context_get_thread_default() when the interaction is created. This
+is called by called by #GTlsConnection or #GTlsDatabase to ask the user
+for a password.
+
+Derived subclasses usually implement a password prompt, although they may
+also choose to provide a password from elsewhere. The @password value will
+be filled in and then @callback will be called. Alternatively the user may
+abort this password request, which will usually abort the TLS connection.
+
+The implementation can either be a synchronous (eg: modal dialog) or an
+asynchronous one (eg: modeless dialog). This function will take care of
+calling which ever one correctly.
+
+If the interaction is cancelled by the cancellation object, or by the
+user then %G_TLS_INTERACTION_FAILED will be returned with an error that
+contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
+not support immediate cancellation.
+
+
+ The status of the ask password interaction.
+
+
+
+
+ a #GTlsInteraction object
+
+
+
+ a #GTlsPassword object
+
+
+
+ an optional #GCancellable cancellation object
+
+
+
+
+
+ Invoke the interaction to ask the user to choose a certificate to
+use with the connection. It invokes this interaction in the main
+loop, specifically the #GMainContext returned by
+g_main_context_get_thread_default() when the interaction is
+created. This is called by called by #GTlsConnection when the peer
+requests a certificate during the handshake.
+
+Derived subclasses usually implement a certificate selector,
+although they may also choose to provide a certificate from
+elsewhere. Alternatively the user may abort this certificate
+request, which may or may not abort the TLS connection.
+
+The implementation can either be a synchronous (eg: modal dialog) or an
+asynchronous one (eg: modeless dialog). This function will take care of
+calling which ever one correctly.
+
+If the interaction is cancelled by the cancellation object, or by the
+user then %G_TLS_INTERACTION_FAILED will be returned with an error that
+contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
+not support immediate cancellation.
+
+
+ The status of the certificate request interaction.
+
+
+
+
+ a #GTlsInteraction object
+
+
+
+ a #GTlsConnection object
+
+
+
+ flags providing more information about the request
+
+
+
+ an optional #GCancellable cancellation object
+
+
+
+
+
+ Run synchronous interaction to ask the user to choose a certificate to use
+with the connection. In general, g_tls_interaction_invoke_request_certificate()
+should be used instead of this function.
+
+Derived subclasses usually implement a certificate selector, although they may
+also choose to provide a certificate from elsewhere. Alternatively the user may
+abort this certificate request, which will usually abort the TLS connection.
+
+If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection
+passed to g_tls_interaction_request_certificate() will have had its
+#GTlsConnection:certificate filled in.
+
+If the interaction is cancelled by the cancellation object, or by the
+user then %G_TLS_INTERACTION_FAILED will be returned with an error that
+contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
+not support immediate cancellation.
+
+
+ The status of the request certificate interaction.
+
+
+
+
+ a #GTlsInteraction object
+
+
+
+ a #GTlsConnection object
+
+
+
+ flags providing more information about the request
+
+
+
+ an optional #GCancellable cancellation object
+
+
+
+
+
+ Run asynchronous interaction to ask the user for a certificate to use with
+the connection. In general, g_tls_interaction_invoke_request_certificate() should
+be used instead of this function.
+
+Derived subclasses usually implement a certificate selector, although they may
+also choose to provide a certificate from elsewhere. @callback will be called
+when the operation completes. Alternatively the user may abort this certificate
+request, which will usually abort the TLS connection.
+
+
+
+
+
+
+ a #GTlsInteraction object
+
+
+
+ a #GTlsConnection object
+
+
+
+ flags providing more information about the request
+
+
+
+ an optional #GCancellable cancellation object
+
+
+
+ will be called when the interaction completes
+
+
+
+ data to pass to the @callback
+
+
+
+
+
+ Complete a request certificate user interaction request. This should be once
+the g_tls_interaction_request_certificate_async() completion callback is called.
+
+If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection
+passed to g_tls_interaction_request_certificate_async() will have had its
+#GTlsConnection:certificate filled in.
+
+If the interaction is cancelled by the cancellation object, or by the
+user then %G_TLS_INTERACTION_FAILED will be returned with an error that
+contains a %G_IO_ERROR_CANCELLED error code.
+
+
+ The status of the request certificate interaction.
+
+
+
+
+ a #GTlsInteraction object
+
+
+
+ the result passed to the callback
+
+
+
+
+
+
+
+
+
+
+
+
+ The class for #GTlsInteraction. Derived classes implement the various
+virtual interaction methods to handle TLS interactions.
+
+Derived classes can choose to implement whichever interactions methods they'd
+like to support by overriding those virtual methods in their class
+initialization function. If a derived class implements an async method,
+it must also implement the corresponding finish method.
+
+The synchronous interaction methods should implement to display modal dialogs,
+and the asynchronous methods to display modeless dialogs.
+
+If the user cancels an interaction, then the result should be
+%G_TLS_INTERACTION_FAILED and the error should be set with a domain of
+%G_IO_ERROR and code of %G_IO_ERROR_CANCELLED.
+
+
+
+
+
+
+
+
+ The status of the ask password interaction.
+
+
+
+
+ a #GTlsInteraction object
+
+
+
+ a #GTlsPassword object
+
+
+
+ an optional #GCancellable cancellation object
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GTlsInteraction object
+
+
+
+ a #GTlsPassword object
+
+
+
+ an optional #GCancellable cancellation object
+
+
+
+ will be called when the interaction completes
+
+
+
+ data to pass to the @callback
+
+
+
+
+
+
+
+
+
+ The status of the ask password interaction.
+
+
+
+
+ a #GTlsInteraction object
+
+
+
+ the result passed to the callback
+
+
+
+
+
+
+
+
+
+ The status of the request certificate interaction.
+
+
+
+
+ a #GTlsInteraction object
+
+
+
+ a #GTlsConnection object
+
+
+
+ flags providing more information about the request
+
+
+
+ an optional #GCancellable cancellation object
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GTlsInteraction object
+
+
+
+ a #GTlsConnection object
+
+
+
+ flags providing more information about the request
+
+
+
+ an optional #GCancellable cancellation object
+
+
+
+ will be called when the interaction completes
+
+
+
+ data to pass to the @callback
+
+
+
+
+
+
+
+
+
+ The status of the request certificate interaction.
+
+
+
+
+ a #GTlsInteraction object
+
+
+
+ the result passed to the callback
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #GTlsInteractionResult is returned by various functions in #GTlsInteraction
+when finishing an interaction request.
+
+ The interaction was unhandled (i.e. not
+ implemented).
+
+
+ The interaction completed, and resulting data
+ is available.
+
+
+ The interaction has failed, or was cancelled.
+ and the operation should be aborted.
+
+
+
+ Holds a password used in TLS.
+
+
+ Create a new #GTlsPassword object.
+
+
+ The newly allocated password object
+
+
+
+
+ the password flags
+
+
+
+ description of what the password is for
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Get the password value. If @length is not %NULL then it will be
+filled in with the length of the password value. (Note that the
+password value is not nul-terminated, so you can only pass %NULL
+for @length in contexts where you know the password will have a
+certain fixed length.)
+
+
+ The password value (owned by the password object).
+
+
+
+
+
+
+ a #GTlsPassword object
+
+
+
+ location to place the length of the password.
+
+
+
+
+
+ Provide the value for this password.
+
+The @value will be owned by the password object, and later freed using
+the @destroy function callback.
+
+Specify the @length, for a non-nul-terminated password. Pass -1 as
+@length if using a nul-terminated password, and @length will be
+calculated automatically. (Note that the terminating nul is not
+considered part of the password in this case.)
+
+
+
+
+
+
+ a #GTlsPassword object
+
+
+
+ the value for the password
+
+
+
+
+
+ the length of the password, or -1
+
+
+
+ a function to use to free the password.
+
+
+
+
+
+ Get a description string about what the password will be used for.
+
+
+ The description of the password.
+
+
+
+
+ a #GTlsPassword object
+
+
+
+
+
+ Get flags about the password.
+
+
+ The flags about the password.
+
+
+
+
+ a #GTlsPassword object
+
+
+
+
+
+ Get the password value. If @length is not %NULL then it will be
+filled in with the length of the password value. (Note that the
+password value is not nul-terminated, so you can only pass %NULL
+for @length in contexts where you know the password will have a
+certain fixed length.)
+
+
+ The password value (owned by the password object).
+
+
+
+
+
+
+ a #GTlsPassword object
+
+
+
+ location to place the length of the password.
+
+
+
+
+
+ Get a user readable translated warning. Usually this warning is a
+representation of the password flags returned from
+g_tls_password_get_flags().
+
+
+ The warning.
+
+
+
+
+ a #GTlsPassword object
+
+
+
+
+
+ Set a description string about what the password will be used for.
+
+
+
+
+
+
+ a #GTlsPassword object
+
+
+
+ The description of the password
+
+
+
+
+
+ Set flags about the password.
+
+
+
+
+
+
+ a #GTlsPassword object
+
+
+
+ The flags about the password
+
+
+
+
+
+ Set the value for this password. The @value will be copied by the password
+object.
+
+Specify the @length, for a non-nul-terminated password. Pass -1 as
+@length if using a nul-terminated password, and @length will be
+calculated automatically. (Note that the terminating nul is not
+considered part of the password in this case.)
+
+
+
+
+
+
+ a #GTlsPassword object
+
+
+
+ the new password value
+
+
+
+
+
+ the length of the password, or -1
+
+
+
+
+
+ Provide the value for this password.
+
+The @value will be owned by the password object, and later freed using
+the @destroy function callback.
+
+Specify the @length, for a non-nul-terminated password. Pass -1 as
+@length if using a nul-terminated password, and @length will be
+calculated automatically. (Note that the terminating nul is not
+considered part of the password in this case.)
+
+
+
+
+
+
+ a #GTlsPassword object
+
+
+
+ the value for the password
+
+
+
+
+
+ the length of the password, or -1
+
+
+
+ a function to use to free the password.
+
+
+
+
+
+ Set a user readable translated warning. Usually this warning is a
+representation of the password flags returned from
+g_tls_password_get_flags().
+
+
+
+
+
+
+ a #GTlsPassword object
+
+
+
+ The user readable warning
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Class structure for #GTlsPassword.
+
+
+
+
+
+
+
+
+ The password value (owned by the password object).
+
+
+
+
+
+
+ a #GTlsPassword object
+
+
+
+ location to place the length of the password.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GTlsPassword object
+
+
+
+ the value for the password
+
+
+
+
+
+ the length of the password, or -1
+
+
+
+ a function to use to free the password.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Various flags for the password.
+
+ No flags
+
+
+ The password was wrong, and the user should retry.
+
+
+ Hint to the user that the password has been
+ wrong many times, and the user may not have many chances left.
+
+
+ Hint to the user that this is the last try to get
+ this password right.
+
+
+ For PKCS #11, the user PIN is required.
+ Since: 2.70.
+
+
+ For PKCS #11, the security officer
+ PIN is required. Since: 2.70.
+
+
+ For PKCS #11, the context-specific
+ PIN is required. Since: 2.70.
+
+
+
+
+
+
+ The TLS or DTLS protocol version used by a #GTlsConnection or
+#GDtlsConnection. The integer values of these versions are sequential
+to ensure newer known protocol versions compare greater than older
+known versions. Any known DTLS protocol version will compare greater
+than any SSL or TLS protocol version. The protocol version may be
+%G_TLS_PROTOCOL_VERSION_UNKNOWN if the TLS backend supports a newer
+protocol version that GLib does not yet know about. This means that
+it's possible for an unknown DTLS protocol version to compare less
+than the TLS protocol versions.
+
+ No protocol version or unknown protocol version
+
+
+ SSL 3.0, which is insecure and should not be used
+
+
+ TLS 1.0, which is insecure and should not be used
+
+
+ TLS 1.1, which is insecure and should not be used
+
+
+ TLS 1.2, defined by [RFC 5246](https://datatracker.ietf.org/doc/html/rfc5246)
+
+
+ TLS 1.3, defined by [RFC 8446](https://datatracker.ietf.org/doc/html/rfc8446)
+
+
+ DTLS 1.0, which is insecure and should not be used
+
+
+ DTLS 1.2, defined by [RFC 6347](https://datatracker.ietf.org/doc/html/rfc6347)
+
+
+
+ When to allow rehandshaking. See
+g_tls_connection_set_rehandshake_mode().
+ Changing the rehandshake mode is no longer
+ required for compatibility. Also, rehandshaking has been removed
+ from the TLS protocol in TLS 1.3.
+
+ Never allow rehandshaking
+
+
+ Allow safe rehandshaking only
+
+
+ Allow unsafe rehandshaking
+
+
+
+ #GTlsServerConnection is the server-side subclass of #GTlsConnection,
+representing a server-side TLS connection.
+
+
+
+ Creates a new #GTlsServerConnection wrapping @base_io_stream (which
+must have pollable input and output streams).
+
+See the documentation for #GTlsConnection:base-io-stream for restrictions
+on when application code can run operations on the @base_io_stream after
+this function has returned.
+
+
+ the new
+#GTlsServerConnection, or %NULL on error
+
+
+
+
+ the #GIOStream to wrap
+
+
+
+ the default server certificate, or %NULL
+
+
+
+
+
+ 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.
+
+
+
+
+ vtable for a #GTlsServerConnection implementation.
+
+
+ The parent interface.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+Since GLib 2.72, #GUnixConnection is available on all platforms. It requires
+underlying system support (such as Windows 10 with `AF_UNIX`) at run time.
+
+Before GLib 2.72, `<gio/gunixconnection.h>` belonged to the UNIX-specific GIO
+interfaces, thus you had to use the `gio-unix-2.0.pc` pkg-config file when
+using it. This is no longer necessary since GLib 2.72.
+
+
+ Receives credentials from the sending end of the connection. The
+sending end has to call g_unix_connection_send_credentials() (or
+similar) for this to work.
+
+As well as reading the credentials this also reads (and discards) a
+single byte from the stream, as this is required for credentials
+passing to work on some implementations.
+
+This method can be expected to be available on the following platforms:
+
+- Linux since GLib 2.26
+- FreeBSD since GLib 2.26
+- GNU/kFreeBSD since GLib 2.36
+- Solaris, Illumos and OpenSolaris since GLib 2.40
+- GNU/Hurd since GLib 2.40
+
+Other ways to exchange credentials with a foreign peer includes the
+#GUnixCredentialsMessage type and g_socket_get_credentials() function.
+
+
+ Received credentials on success (free with
+g_object_unref()), %NULL if @error is set.
+
+
+
+
+ A #GUnixConnection.
+
+
+
+ A #GCancellable or %NULL.
+
+
+
+
+
+ Asynchronously receive credentials.
+
+For more details, see g_unix_connection_receive_credentials() which is
+the synchronous version of this call.
+
+When the operation is finished, @callback will be called. You can then call
+g_unix_connection_receive_credentials_finish() to get the result of the operation.
+
+
+
+
+
+
+ A #GUnixConnection.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous receive credentials operation started with
+g_unix_connection_receive_credentials_async().
+
+
+ a #GCredentials, or %NULL on error.
+ Free the returned object with g_object_unref().
+
+
+
+
+ A #GUnixConnection.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Receives a file descriptor from the sending end of the connection.
+The sending end has to call g_unix_connection_send_fd() for this
+to work.
+
+As well as reading the fd this also reads a single byte from the
+stream, as this is required for fd passing to work on some
+implementations.
+
+
+ a file descriptor on success, -1 on error.
+
+
+
+
+ a #GUnixConnection
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+
+
+ Passes the credentials of the current user the receiving side
+of the connection. The receiving end has to call
+g_unix_connection_receive_credentials() (or similar) to accept the
+credentials.
+
+As well as sending the credentials this also writes a single NUL
+byte to the stream, as this is required for credentials passing to
+work on some implementations.
+
+This method can be expected to be available on the following platforms:
+
+- Linux since GLib 2.26
+- FreeBSD since GLib 2.26
+- GNU/kFreeBSD since GLib 2.36
+- Solaris, Illumos and OpenSolaris since GLib 2.40
+- GNU/Hurd since GLib 2.40
+
+Other ways to exchange credentials with a foreign peer includes the
+#GUnixCredentialsMessage type and g_socket_get_credentials() function.
+
+
+ %TRUE on success, %FALSE if @error is set.
+
+
+
+
+ A #GUnixConnection.
+
+
+
+ A #GCancellable or %NULL.
+
+
+
+
+
+ Asynchronously send credentials.
+
+For more details, see g_unix_connection_send_credentials() which is
+the synchronous version of this call.
+
+When the operation is finished, @callback will be called. You can then call
+g_unix_connection_send_credentials_finish() to get the result of the operation.
+
+
+
+
+
+
+ A #GUnixConnection.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback to call when the request is satisfied
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Finishes an asynchronous send credentials operation started with
+g_unix_connection_send_credentials_async().
+
+
+ %TRUE if the operation was successful, otherwise %FALSE.
+
+
+
+
+ A #GUnixConnection.
+
+
+
+ a #GAsyncResult.
+
+
+
+
+
+ Passes a file descriptor to the receiving side of the
+connection. The receiving end has to call g_unix_connection_receive_fd()
+to accept the file descriptor.
+
+As well as sending the fd this also writes a single byte to the
+stream, as this is required for fd passing to work on some
+implementations.
+
+
+ a %TRUE on success, %NULL on error.
+
+
+
+
+ a #GUnixConnection
+
+
+
+ a file descriptor
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This #GSocketControlMessage contains a #GCredentials instance. It
+may be sent using g_socket_send_message() and received using
+g_socket_receive_message() over UNIX sockets (ie: sockets in the
+%G_SOCKET_FAMILY_UNIX family).
+
+For an easier way to send and receive credentials over
+stream-oriented UNIX sockets, see
+g_unix_connection_send_credentials() and
+g_unix_connection_receive_credentials(). To receive credentials of
+a foreign process connected to a socket, use
+g_socket_get_credentials().
+
+Since GLib 2.72, #GUnixCredentialMessage is available on all platforms. It
+requires underlying system support (such as Windows 10 with `AF_UNIX`) at run
+time.
+
+Before GLib 2.72, `<gio/gunixcredentialsmessage.h>` belonged to the UNIX-specific
+GIO interfaces, thus you had to use the `gio-unix-2.0.pc` pkg-config file
+when using it. This is no longer necessary since GLib 2.72.
+
+
+ Creates a new #GUnixCredentialsMessage with credentials matching the current processes.
+
+
+ a new #GUnixCredentialsMessage
+
+
+
+
+ Creates a new #GUnixCredentialsMessage holding @credentials.
+
+
+ a new #GUnixCredentialsMessage
+
+
+
+
+ A #GCredentials object.
+
+
+
+
+
+ Checks if passing #GCredentials on a #GSocket is supported on this platform.
+
+
+ %TRUE if supported, %FALSE otherwise
+
+
+
+
+ Gets the credentials stored in @message.
+
+
+ A #GCredentials instance. Do not free, it is owned by @message.
+
+
+
+
+ A #GUnixCredentialsMessage.
+
+
+
+
+
+ The credentials stored in the message.
+
+
+
+
+
+
+
+
+
+
+ Class structure for #GUnixCredentialsMessage.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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_FAMILY_UNIX family by using g_socket_send_message()
+and received using g_socket_receive_message().
+
+Before 2.74, `<gio/gunixfdlist.h>` belonged to the UNIX-specific GIO
+interfaces, thus you had to use the `gio-unix-2.0.pc` pkg-config file when
+using it.
+
+Since 2.74, the API is available for Windows.
+
+
+ Creates a new #GUnixFDList containing no file descriptors.
+
+
+ a new #GUnixFDList
+
+
+
+
+ Creates a new #GUnixFDList containing the file descriptors given in
+@fds. The file descriptors become the property of the new list and
+may no longer be used by the caller. The array itself is owned by
+the caller.
+
+Each file descriptor in the array should be set to close-on-exec.
+
+If @n_fds is -1 then @fds must be terminated with -1.
+
+
+ a new #GUnixFDList
+
+
+
+
+ the initial list of file descriptors
+
+
+
+
+
+ the length of #fds, or -1
+
+
+
+
+
+ Adds a file descriptor to @list.
+
+The file descriptor is duplicated using dup(). You keep your copy
+of the descriptor and the copy contained in @list will be closed
+when @list is finalized.
+
+A possible cause of failure is exceeding the per-process or
+system-wide file descriptor limit.
+
+The index of the file descriptor in the list is returned. If you use
+this index with g_unix_fd_list_get() then you will receive back a
+duplicated copy of the same file descriptor.
+
+
+ the index of the appended fd in case of success, else -1
+ (and @error is set)
+
+
+
+
+ a #GUnixFDList
+
+
+
+ a valid open file descriptor
+
+
+
+
+
+ Gets a file descriptor out of @list.
+
+@index_ specifies the index of the file descriptor to get. It is a
+programmer error for @index_ to be out of range; see
+g_unix_fd_list_get_length().
+
+The file descriptor is duplicated using dup() and set as
+close-on-exec before being returned. You must call close() on it
+when you are done.
+
+A possible cause of failure is exceeding the per-process or
+system-wide file descriptor limit.
+
+
+ the file descriptor, or -1 in case of error
+
+
+
+
+ a #GUnixFDList
+
+
+
+ the index into the list
+
+
+
+
+
+ Gets the length of @list (ie: the number of file descriptors
+contained within).
+
+
+ the length of @list
+
+
+
+
+ a #GUnixFDList
+
+
+
+
+
+ Returns the array of file descriptors that is contained in this
+object.
+
+After this call, the descriptors remain the property of @list. The
+caller must not close them and must not free the array. The array is
+valid only until @list is changed in any way.
+
+If @length is non-%NULL then it is set to the number of file
+descriptors in the returned array. The returned array is also
+terminated with -1.
+
+This function never returns %NULL. In case there are no file
+descriptors contained in @list, an empty array is returned.
+
+
+ an array of file
+ descriptors
+
+
+
+
+
+
+ a #GUnixFDList
+
+
+
+ pointer to the length of the returned
+ array, or %NULL
+
+
+
+
+
+ Returns the array of file descriptors that is contained in this
+object.
+
+After this call, the descriptors are no longer contained in
+@list. Further calls will return an empty list (unless more
+descriptors have been added).
+
+The return result of this function must be freed with g_free().
+The caller is also responsible for closing all of the file
+descriptors. The file descriptors in the array are set to
+close-on-exec.
+
+If @length is non-%NULL then it is set to the number of file
+descriptors in the returned array. The returned array is also
+terminated with -1.
+
+This function never returns %NULL. In case there are no file
+descriptors contained in @list, an empty array is returned.
+
+
+ an array of file
+ descriptors
+
+
+
+
+
+
+ a #GUnixFDList
+
+
+
+ pointer to the length of the returned
+ array, or %NULL
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This #GSocketControlMessage contains a #GUnixFDList.
+It may be sent using g_socket_send_message() and received using
+g_socket_receive_message() over UNIX sockets (ie: sockets in the
+%G_SOCKET_FAMILY_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 `<gio/gunixfdmessage.h>` belongs to the UNIX-specific GIO
+interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
+file when using it.
+
+
+ Creates a new #GUnixFDMessage containing an empty file descriptor
+list.
+
+
+ a new #GUnixFDMessage
+
+
+
+
+ Creates a new #GUnixFDMessage containing @list.
+
+
+ a new #GUnixFDMessage
+
+
+
+
+ a #GUnixFDList
+
+
+
+
+
+ Adds a file descriptor to @message.
+
+The file descriptor is duplicated using dup(). You keep your copy
+of the descriptor and the copy contained in @message will be closed
+when @message is finalized.
+
+A possible cause of failure is exceeding the per-process or
+system-wide file descriptor limit.
+
+
+ %TRUE in case of success, else %FALSE (and @error is set)
+
+
+
+
+ a #GUnixFDMessage
+
+
+
+ a valid open file descriptor
+
+
+
+
+
+ Gets the #GUnixFDList contained in @message. This function does not
+return a reference to the caller, but the returned list is valid for
+the lifetime of @message.
+
+
+ the #GUnixFDList from @message
+
+
+
+
+ a #GUnixFDMessage
+
+
+
+
+
+ Returns the array of file descriptors that is contained in this
+object.
+
+After this call, the descriptors are no longer contained in
+@message. Further calls will return an empty list (unless more
+descriptors have been added).
+
+The return result of this function must be freed with g_free().
+The caller is also responsible for closing all of the file
+descriptors.
+
+If @length is non-%NULL then it is set to the number of file
+descriptors in the returned array. The returned array is also
+terminated with -1.
+
+This function never returns %NULL. In case there are no file
+descriptors contained in @message, an empty array is returned.
+
+
+ an array of file
+ descriptors
+
+
+
+
+
+
+ a #GUnixFDMessage
+
+
+
+ pointer to the length of the returned
+ array, or %NULL
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #GUnixInputStream implements #GInputStream for reading from a UNIX
+file descriptor, including asynchronous operations. (If the file
+descriptor refers to a socket or pipe, this will use poll() to do
+asynchronous I/O. If it refers to a regular file, it will fall back
+to doing asynchronous I/O in another thread.)
+
+Note that `<gio/gunixinputstream.h>` belongs to the UNIX-specific GIO
+interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
+file when using it.
+
+
+
+
+ Creates a new #GUnixInputStream for the given @fd.
+
+If @close_fd is %TRUE, the file descriptor will be closed
+when the stream is closed.
+
+
+ a new #GUnixInputStream
+
+
+
+
+ a UNIX file descriptor
+
+
+
+ %TRUE to close the file descriptor when done
+
+
+
+
+
+ Returns whether the file descriptor of @stream will be
+closed when the stream is closed.
+
+
+ %TRUE if the file descriptor is closed when done
+
+
+
+
+ a #GUnixInputStream
+
+
+
+
+
+ Return the UNIX file descriptor that the stream reads from.
+
+
+ The file descriptor of @stream
+
+
+
+
+ a #GUnixInputStream
+
+
+
+
+
+ Sets whether the file descriptor of @stream shall be closed
+when the stream is closed.
+
+
+
+
+
+
+ a #GUnixInputStream
+
+
+
+ %TRUE to close the file descriptor when done
+
+
+
+
+
+ Whether to close the file descriptor when the stream is closed.
+
+
+
+ The file descriptor that the stream reads from.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Defines a Unix mount entry (e.g. <filename>/media/cdrom</filename>).
+This corresponds roughly to a mtab entry.
+
+
+
+ Watches #GUnixMounts for changes.
+
+
+ Deprecated alias for g_unix_mount_monitor_get().
+
+This function was never a true constructor, which is why it was
+renamed.
+ Use g_unix_mount_monitor_get() instead.
+
+
+ a #GUnixMountMonitor.
+
+
+
+
+ Gets the #GUnixMountMonitor for the current thread-default main
+context.
+
+The mount monitor can be used to monitor for changes to the list of
+mounted filesystems as well as the list of mount points (ie: fstab
+entries).
+
+You must only call g_object_unref() on the return value from under
+the same main context as you called this function.
+
+
+ the #GUnixMountMonitor.
+
+
+
+
+ This function does nothing.
+
+Before 2.44, this was a partially-effective way of controlling the
+rate at which events would be reported under some uncommon
+circumstances. Since @mount_monitor is a singleton, it also meant
+that calling this function would have side effects for other users of
+the monitor.
+ This function does nothing. Don't call it.
+
+
+
+
+
+
+ a #GUnixMountMonitor
+
+
+
+ a integer with the limit in milliseconds to
+ poll for changes.
+
+
+
+
+
+ Emitted when the unix mount points have changed.
+
+
+
+
+
+ Emitted when the unix mounts have changed.
+
+
+
+
+
+
+
+
+
+ Defines a Unix mount point (e.g. <filename>/dev</filename>).
+This corresponds roughly to a fstab entry.
+
+
+ Compares two unix mount points.
+
+
+ 1, 0 or -1 if @mount1 is greater than, equal to,
+or less than @mount2, respectively.
+
+
+
+
+ a #GUnixMount.
+
+
+
+ a #GUnixMount.
+
+
+
+
+
+ Makes a copy of @mount_point.
+
+
+ a new #GUnixMountPoint
+
+
+
+
+ a #GUnixMountPoint.
+
+
+
+
+
+ Frees a unix mount point.
+
+
+
+
+
+
+ unix mount point to free.
+
+
+
+
+
+ Gets the device path for a unix mount point.
+
+
+ a string containing the device path.
+
+
+
+
+ a #GUnixMountPoint.
+
+
+
+
+
+ Gets the file system type for the mount point.
+
+
+ a string containing the file system type.
+
+
+
+
+ a #GUnixMountPoint.
+
+
+
+
+
+ Gets the mount path for a unix mount point.
+
+
+ a string containing the mount path.
+
+
+
+
+ a #GUnixMountPoint.
+
+
+
+
+
+ Gets the options for the mount point.
+
+
+ a string containing the options.
+
+
+
+
+ a #GUnixMountPoint.
+
+
+
+
+
+ Guesses whether a Unix mount point can be ejected.
+
+
+ %TRUE if @mount_point is deemed to be ejectable.
+
+
+
+
+ a #GUnixMountPoint
+
+
+
+
+
+ Guesses the icon of a Unix mount point.
+
+
+ a #GIcon
+
+
+
+
+ a #GUnixMountPoint
+
+
+
+
+
+ Guesses the name of a Unix mount point.
+The result is a translated string.
+
+
+ A newly allocated string that must
+ be freed with g_free()
+
+
+
+
+ a #GUnixMountPoint
+
+
+
+
+
+ Guesses the symbolic icon of a Unix mount point.
+
+
+ a #GIcon
+
+
+
+
+ a #GUnixMountPoint
+
+
+
+
+
+ Checks if a unix mount point is a loopback device.
+
+
+ %TRUE if the mount point is a loopback. %FALSE otherwise.
+
+
+
+
+ a #GUnixMountPoint.
+
+
+
+
+
+ Checks if a unix mount point is read only.
+
+
+ %TRUE if a mount point is read only.
+
+
+
+
+ a #GUnixMountPoint.
+
+
+
+
+
+ Checks if a unix mount point is mountable by the user.
+
+
+ %TRUE if the mount point is user mountable.
+
+
+
+
+ a #GUnixMountPoint.
+
+
+
+
+
+ Gets a #GUnixMountPoint for a given mount path. If @time_read is set, it
+will be filled with a unix timestamp for checking if the mount points have
+changed since with g_unix_mount_points_changed_since().
+
+If more mount points have the same mount path, the last matching mount point
+is returned.
+
+
+ a #GUnixMountPoint, or %NULL if no match
+is found.
+
+
+
+
+ path for a possible unix mount point.
+
+
+
+ guint64 to contain a timestamp.
+
+
+
+
+
+
+ #GUnixOutputStream implements #GOutputStream for writing to a UNIX
+file descriptor, including asynchronous operations. (If the file
+descriptor refers to a socket or pipe, this will use poll() to do
+asynchronous I/O. If it refers to a regular file, it will fall back
+to doing asynchronous I/O in another thread.)
+
+Note that `<gio/gunixoutputstream.h>` belongs to the UNIX-specific GIO
+interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file
+when using it.
+
+
+
+
+ Creates a new #GUnixOutputStream for the given @fd.
+
+If @close_fd, is %TRUE, the file descriptor will be closed when
+the output stream is destroyed.
+
+
+ a new #GOutputStream
+
+
+
+
+ a UNIX file descriptor
+
+
+
+ %TRUE to close the file descriptor when done
+
+
+
+
+
+ Returns whether the file descriptor of @stream will be
+closed when the stream is closed.
+
+
+ %TRUE if the file descriptor is closed when done
+
+
+
+
+ a #GUnixOutputStream
+
+
+
+
+
+ Return the UNIX file descriptor that the stream writes to.
+
+
+ The file descriptor of @stream
+
+
+
+
+ a #GUnixOutputStream
+
+
+
+
+
+ Sets whether the file descriptor of @stream shall be closed
+when the stream is closed.
+
+
+
+
+
+
+ a #GUnixOutputStream
+
+
+
+ %TRUE to close the file descriptor when done
+
+
+
+
+
+ Whether to close the file descriptor when the stream is closed.
+
+
+
+ The file descriptor that the stream writes to.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+Since GLib 2.72, #GUnixSocketAddress is available on all platforms. It
+requires underlying system support (such as Windows 10 with `AF_UNIX`) at
+run time.
+
+Before GLib 2.72, `<gio/gunixsocketaddress.h>` belonged to the UNIX-specific
+GIO interfaces, thus you had to use the `gio-unix-2.0.pc` pkg-config file
+when using it. This is no longer necessary since GLib 2.72.
+
+
+
+ Creates a new #GUnixSocketAddress for @path.
+
+To create abstract socket addresses, on systems that support that,
+use g_unix_socket_address_new_abstract().
+
+
+ a new #GUnixSocketAddress
+
+
+
+
+ the socket path
+
+
+
+
+
+ Creates a new %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED
+#GUnixSocketAddress for @path.
+ Use g_unix_socket_address_new_with_type().
+
+
+ a new #GUnixSocketAddress
+
+
+
+
+ the abstract name
+
+
+
+
+
+ the length of @path, or -1
+
+
+
+
+
+ Creates a new #GUnixSocketAddress of type @type with name @path.
+
+If @type is %G_UNIX_SOCKET_ADDRESS_PATH, this is equivalent to
+calling g_unix_socket_address_new().
+
+If @type is %G_UNIX_SOCKET_ADDRESS_ANONYMOUS, @path and @path_len will be
+ignored.
+
+If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT, then @path_len
+bytes of @path will be copied to the socket's path, and only those
+bytes will be considered part of the name. (If @path_len is -1,
+then @path is assumed to be NUL-terminated.) For example, if @path
+was "test", then calling g_socket_address_get_native_size() on the
+returned socket would return 7 (2 bytes of overhead, 1 byte for the
+abstract-socket indicator byte, and 4 bytes for the name "test").
+
+If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED, then
+@path_len bytes of @path will be copied to the socket's path, the
+rest of the path will be padded with 0 bytes, and the entire
+zero-padded buffer will be considered the name. (As above, if
+@path_len is -1, then @path is assumed to be NUL-terminated.) In
+this case, g_socket_address_get_native_size() will always return
+the full size of a `struct sockaddr_un`, although
+g_unix_socket_address_get_path_len() will still return just the
+length of @path.
+
+%G_UNIX_SOCKET_ADDRESS_ABSTRACT is preferred over
+%G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED for new programs. Of course,
+when connecting to a server created by another process, you must
+use the appropriate type corresponding to how that process created
+its listening socket.
+
+
+ a new #GUnixSocketAddress
+
+
+
+
+ the name
+
+
+
+
+
+ the length of @path, or -1
+
+
+
+ a #GUnixSocketAddressType
+
+
+
+
+
+ Checks if abstract UNIX domain socket names are supported.
+
+
+ %TRUE if supported, %FALSE otherwise
+
+
+
+
+ Gets @address's type.
+
+
+ a #GUnixSocketAddressType
+
+
+
+
+ a #GInetSocketAddress
+
+
+
+
+
+ Tests if @address is abstract.
+ Use g_unix_socket_address_get_address_type()
+
+
+ %TRUE if the address is abstract, %FALSE otherwise
+
+
+
+
+ a #GInetSocketAddress
+
+
+
+
+
+ Gets @address's path, or for abstract sockets the "name".
+
+Guaranteed to be zero-terminated, but an abstract socket
+may contain embedded zeros, and thus you should use
+g_unix_socket_address_get_path_len() to get the true length
+of this string.
+
+
+ the path for @address
+
+
+
+
+ a #GInetSocketAddress
+
+
+
+
+
+ Gets the length of @address's path.
+
+For details, see g_unix_socket_address_get_path().
+
+
+ the length of the path
+
+
+
+
+ a #GInetSocketAddress
+
+
+
+
+
+ Whether or not this is an abstract address
+ Use #GUnixSocketAddress:address-type, which
+distinguishes between zero-padded and non-zero-padded
+abstract addresses.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The type of name used by a #GUnixSocketAddress.
+%G_UNIX_SOCKET_ADDRESS_PATH indicates a traditional unix domain
+socket bound to a filesystem path. %G_UNIX_SOCKET_ADDRESS_ANONYMOUS
+indicates a socket not bound to any name (eg, a client-side socket,
+or a socket created with socketpair()).
+
+For abstract sockets, there are two incompatible ways of naming
+them; the man pages suggest using the entire `struct sockaddr_un`
+as the name, padding the unused parts of the %sun_path field with
+zeroes; this corresponds to %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED.
+However, many programs instead just use a portion of %sun_path, and
+pass an appropriate smaller length to bind() or connect(). This is
+%G_UNIX_SOCKET_ADDRESS_ABSTRACT.
+
+ invalid
+
+
+ anonymous
+
+
+ a filesystem path
+
+
+ an abstract name
+
+
+ an abstract name, 0-padded
+ to the full length of a unix socket name
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Extension point for #GVfs functionality.
+See [Extending GIO][extending-gio].
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The string used to obtain the volume class with g_volume_get_identifier().
+
+Known volume classes include `device`, `network`, and `loop`. Other
+classes may be added in the future.
+
+This is intended to be used by applications to classify #GVolume
+instances into different sections - for example a file manager or
+file chooser can use this information to show `network` volumes under
+a "Network" heading and `device` volumes under a "Devices" heading.
+
+
+
+
+ The string used to obtain a Hal UDI with g_volume_get_identifier().
+ Do not use, HAL is deprecated.
+
+
+
+
+ The string used to obtain a filesystem label with g_volume_get_identifier().
+
+
+
+
+ The string used to obtain a NFS mount with g_volume_get_identifier().
+
+
+
+
+ The string used to obtain a Unix device path with g_volume_get_identifier().
+
+
+
+
+ The string used to obtain a UUID with g_volume_get_identifier().
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Extension point for volume monitor functionality.
+See [Extending GIO][extending-gio].
+
+
+
+
+
+
+
+
+
+
+
+ Entry point for using GIO functionality.
+
+
+ Gets the default #GVfs for the system.
+
+
+ a #GVfs, which will be the local
+ file system #GVfs if no other implementation is available.
+
+
+
+
+ Gets the local #GVfs for the system.
+
+
+ a #GVfs.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Gets a #GFile for @path.
+
+
+ a #GFile.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GVfs.
+
+
+
+ a string containing a VFS path.
+
+
+
+
+
+ Gets a #GFile for @uri.
+
+This operation never fails, but the returned object
+might not support any I/O operation if the URI
+is malformed or if the URI scheme is not supported.
+
+
+ a #GFile.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a#GVfs.
+
+
+
+ a string containing a URI
+
+
+
+
+
+ Gets a list of URI schemes supported by @vfs.
+
+
+ a %NULL-terminated array of strings.
+ The returned array belongs to GIO and must
+ not be freed or modified.
+
+
+
+
+
+
+ a #GVfs.
+
+
+
+
+
+ Checks if the VFS is active.
+
+
+ %TRUE if construction of the @vfs was successful
+ and it is now active.
+
+
+
+
+ a #GVfs.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This operation never fails, but the returned object might
+not support any I/O operations if the @parse_name cannot
+be parsed by the #GVfs module.
+
+
+ a #GFile for the given @parse_name.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GVfs.
+
+
+
+ a string to be parsed by the VFS module.
+
+
+
+
+
+ Gets a #GFile for @path.
+
+
+ a #GFile.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GVfs.
+
+
+
+ a string containing a VFS path.
+
+
+
+
+
+ Gets a #GFile for @uri.
+
+This operation never fails, but the returned object
+might not support any I/O operation if the URI
+is malformed or if the URI scheme is not supported.
+
+
+ a #GFile.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a#GVfs.
+
+
+
+ a string containing a URI
+
+
+
+
+
+ Gets a list of URI schemes supported by @vfs.
+
+
+ a %NULL-terminated array of strings.
+ The returned array belongs to GIO and must
+ not be freed or modified.
+
+
+
+
+
+
+ a #GVfs.
+
+
+
+
+
+ Checks if the VFS is active.
+
+
+ %TRUE if construction of the @vfs was successful
+ and it is now active.
+
+
+
+
+ a #GVfs.
+
+
+
+
+
+ This operation never fails, but the returned object might
+not support any I/O operations if the @parse_name cannot
+be parsed by the #GVfs module.
+
+
+ a #GFile for the given @parse_name.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GVfs.
+
+
+
+ a string to be parsed by the VFS module.
+
+
+
+
+
+ Registers @uri_func and @parse_name_func as the #GFile URI and parse name
+lookup functions for URIs with a scheme matching @scheme.
+Note that @scheme is registered only within the running application, as
+opposed to desktop-wide as it happens with GVfs backends.
+
+When a #GFile is requested with an URI containing @scheme (e.g. through
+g_file_new_for_uri()), @uri_func will be called to allow a custom
+constructor. The implementation of @uri_func should not be blocking, and
+must not call g_vfs_register_uri_scheme() or g_vfs_unregister_uri_scheme().
+
+When g_file_parse_name() is called with a parse name obtained from such file,
+@parse_name_func will be called to allow the #GFile to be created again. In
+that case, it's responsibility of @parse_name_func to make sure the parse
+name matches what the custom #GFile implementation returned when
+g_file_get_parse_name() was previously called. The implementation of
+@parse_name_func should not be blocking, and must not call
+g_vfs_register_uri_scheme() or g_vfs_unregister_uri_scheme().
+
+It's an error to call this function twice with the same scheme. To unregister
+a custom URI scheme, use g_vfs_unregister_uri_scheme().
+
+
+ %TRUE if @scheme was successfully registered, or %FALSE if a handler
+ for @scheme already exists.
+
+
+
+
+ a #GVfs
+
+
+
+ an URI scheme, e.g. "http"
+
+
+
+ a #GVfsFileLookupFunc
+
+
+
+ custom data passed to be passed to @uri_func, or %NULL
+
+
+
+ function to be called when unregistering the
+ URI scheme, or when @vfs is disposed, to free the resources used
+ by the URI lookup function
+
+
+
+ a #GVfsFileLookupFunc
+
+
+
+ custom data passed to be passed to
+ @parse_name_func, or %NULL
+
+
+
+ function to be called when unregistering the
+ URI scheme, or when @vfs is disposed, to free the resources used
+ by the parse name lookup function
+
+
+
+
+
+ Unregisters the URI handler for @scheme previously registered with
+g_vfs_register_uri_scheme().
+
+
+ %TRUE if @scheme was successfully unregistered, or %FALSE if a
+ handler for @scheme does not exist.
+
+
+
+
+ a #GVfs
+
+
+
+ an URI scheme, e.g. "http"
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ %TRUE if construction of the @vfs was successful
+ and it is now active.
+
+
+
+
+ a #GVfs.
+
+
+
+
+
+
+
+
+
+ a #GFile.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GVfs.
+
+
+
+ a string containing a VFS path.
+
+
+
+
+
+
+
+
+
+ a #GFile.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a#GVfs.
+
+
+
+ a string containing a URI
+
+
+
+
+
+
+
+
+
+ a %NULL-terminated array of strings.
+ The returned array belongs to GIO and must
+ not be freed or modified.
+
+
+
+
+
+
+ a #GVfs.
+
+
+
+
+
+
+
+
+
+ a #GFile for the given @parse_name.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GVfs.
+
+
+
+ a string to be parsed by the VFS module.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This function type is used by g_vfs_register_uri_scheme() to make it
+possible for a client to associate an URI scheme to a different #GFile
+implementation.
+
+The client should return a reference to the new file that has been
+created for @uri, or %NULL to continue with the default implementation.
+
+
+ a #GFile for @identifier.
+
+
+
+
+ a #GVfs
+
+
+
+ the identifier to look up a #GFile for. This can either
+ be an URI or a parse name as returned by g_file_get_parse_name()
+
+
+
+ user data passed to the function
+
+
+
+
+
+ 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 #GAsyncResult and
+#GTask. To mount a #GVolume, first call g_volume_mount() with (at
+least) the #GVolume instance, optionally a #GMountOperation object
+and a #GAsyncReadyCallback.
+
+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 #GAsyncResult instance will be
+passed to the callback. That callback should then call
+g_volume_mount_finish() with the #GVolume instance and the
+#GAsyncResult 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.
+
+## Volume Identifiers # {#volume-identifier}
+
+It is sometimes necessary to directly access the underlying
+operating system object behind a volume (e.g. for passing a volume
+to an application via the commandline). For this purpose, GIO
+allows to obtain an 'identifier' for the volume. There can be
+different kinds of identifiers, such as Hal UDIs, filesystem labels,
+traditional Unix devices (e.g. `/dev/sda2`), UUIDs. GIO uses predefined
+strings as names for the different kinds of identifiers:
+%G_VOLUME_IDENTIFIER_KIND_UUID, %G_VOLUME_IDENTIFIER_KIND_LABEL, etc.
+Use g_volume_get_identifier() to obtain an identifier for a volume.
+
+
+Note that %G_VOLUME_IDENTIFIER_KIND_HAL_UDI will only be available
+when the gvfs hal volume monitor is in use. Other volume monitors
+will generally be able to provide the %G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE
+identifier, which can be used to obtain a hal device by means of
+libhal_manager_find_device_string_match().
+
+
+ Checks if a volume can be ejected.
+
+
+ %TRUE if the @volume can be ejected. %FALSE otherwise
+
+
+
+
+ a #GVolume
+
+
+
+
+
+ Checks if a volume can be mounted.
+
+
+ %TRUE if the @volume can be mounted. %FALSE otherwise
+
+
+
+
+ a #GVolume
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Ejects a volume. This is an asynchronous operation, and is
+finished by calling g_volume_eject_finish() with the @volume
+and #GAsyncResult returned in the @callback.
+ Use g_volume_eject_with_operation() instead.
+
+
+
+
+
+
+ a #GVolume
+
+
+
+ flags affecting the unmount if required for eject
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback, or %NULL
+
+
+
+ user data that gets passed to @callback
+
+
+
+
+
+ Finishes ejecting a volume. If any errors occurred during the operation,
+@error will be set to contain the errors and %FALSE will be returned.
+ Use g_volume_eject_with_operation_finish() instead.
+
+
+ %TRUE, %FALSE if operation failed
+
+
+
+
+ pointer to a #GVolume
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Ejects a volume. This is an asynchronous operation, and is
+finished by calling g_volume_eject_with_operation_finish() with the @volume
+and #GAsyncResult data returned in the @callback.
+
+
+
+
+
+
+ a #GVolume
+
+
+
+ flags affecting the unmount if required for eject
+
+
+
+ a #GMountOperation or %NULL to
+ avoid user interaction
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback, or %NULL
+
+
+
+ user data passed to @callback
+
+
+
+
+
+ Finishes ejecting a volume. If any errors occurred during the operation,
+@error will be set to contain the errors and %FALSE will be returned.
+
+
+ %TRUE if the volume was successfully ejected. %FALSE otherwise
+
+
+
+
+ a #GVolume
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Gets the kinds of [identifiers][volume-identifier] that @volume has.
+Use g_volume_get_identifier() to obtain the identifiers themselves.
+
+
+ a %NULL-terminated array
+ of strings containing kinds of identifiers. Use g_strfreev() to free.
+
+
+
+
+
+
+ a #GVolume
+
+
+
+
+
+ Gets the activation root for a #GVolume if it is known ahead of
+mount time. Returns %NULL otherwise. If not %NULL and if @volume
+is mounted, then the result of g_mount_get_root() on the
+#GMount object obtained from g_volume_get_mount() will always
+either be equal or a prefix of what this function returns. In
+other words, in code
+
+|[<!-- language="C" -->
+ GMount *mount;
+ GFile *mount_root
+ GFile *volume_activation_root;
+
+ mount = g_volume_get_mount (volume); // mounted, so never NULL
+ mount_root = g_mount_get_root (mount);
+ volume_activation_root = g_volume_get_activation_root (volume); // assume not NULL
+]|
+then the expression
+|[<!-- language="C" -->
+ (g_file_has_prefix (volume_activation_root, mount_root) ||
+ g_file_equal (volume_activation_root, mount_root))
+]|
+will always be %TRUE.
+
+Activation roots are typically used in #GVolumeMonitor
+implementations to find the underlying mount to shadow, see
+g_mount_is_shadowed() for more details.
+
+
+ the activation root of @volume
+ or %NULL. Use g_object_unref() to free.
+
+
+
+
+ a #GVolume
+
+
+
+
+
+ Gets the drive for the @volume.
+
+
+ a #GDrive or %NULL if @volume is not
+ associated with a drive. The returned object should be unreffed
+ with g_object_unref() when no longer needed.
+
+
+
+
+ a #GVolume
+
+
+
+
+
+ Gets the icon for @volume.
+
+
+ a #GIcon.
+ The returned object should be unreffed with g_object_unref()
+ when no longer needed.
+
+
+
+
+ a #GVolume
+
+
+
+
+
+ Gets the identifier of the given kind for @volume.
+See the [introduction][volume-identifier] for more
+information about volume identifiers.
+
+
+ a newly allocated string containing the
+ requested identifier, or %NULL if the #GVolume
+ doesn't have this kind of identifier
+
+
+
+
+ a #GVolume
+
+
+
+ the kind of identifier to return
+
+
+
+
+
+ Gets the mount for the @volume.
+
+
+ a #GMount or %NULL if @volume isn't mounted.
+ The returned object should be unreffed with g_object_unref()
+ when no longer needed.
+
+
+
+
+ a #GVolume
+
+
+
+
+
+ Gets the name of @volume.
+
+
+ the name for the given @volume. The returned string should
+ be freed with g_free() when no longer needed.
+
+
+
+
+ a #GVolume
+
+
+
+
+
+ Gets the sort key for @volume, if any.
+
+
+ Sorting key for @volume or %NULL if no such key is available
+
+
+
+
+ a #GVolume
+
+
+
+
+
+ Gets the symbolic icon for @volume.
+
+
+ a #GIcon.
+ The returned object should be unreffed with g_object_unref()
+ when no longer needed.
+
+
+
+
+ a #GVolume
+
+
+
+
+
+ Gets the UUID for the @volume. The reference is typically based on
+the file system UUID for the volume in question and should be
+considered an opaque string. Returns %NULL if there is no UUID
+available.
+
+
+ the UUID for @volume or %NULL if no UUID
+ can be computed.
+ The returned string should be freed with g_free()
+ when no longer needed.
+
+
+
+
+ a #GVolume
+
+
+
+
+
+ Finishes mounting a volume. If any errors occurred during the operation,
+@error will be set to contain the errors and %FALSE will be returned.
+
+If the mount operation succeeded, g_volume_get_mount() on @volume
+is guaranteed to return the mount right after calling this
+function; there's no need to listen for the 'mount-added' signal on
+#GVolumeMonitor.
+
+
+ %TRUE, %FALSE if operation failed
+
+
+
+
+ a #GVolume
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Mounts a volume. This is an asynchronous operation, and is
+finished by calling g_volume_mount_finish() with the @volume
+and #GAsyncResult returned in the @callback.
+
+
+
+
+
+
+ a #GVolume
+
+
+
+ flags affecting the operation
+
+
+
+ a #GMountOperation or %NULL to avoid user interaction
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback, or %NULL
+
+
+
+ user data that gets passed to @callback
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Returns whether the volume should be automatically mounted.
+
+
+ %TRUE if the volume should be automatically mounted
+
+
+
+
+ a #GVolume
+
+
+
+
+
+ Checks if a volume can be ejected.
+
+
+ %TRUE if the @volume can be ejected. %FALSE otherwise
+
+
+
+
+ a #GVolume
+
+
+
+
+
+ Checks if a volume can be mounted.
+
+
+ %TRUE if the @volume can be mounted. %FALSE otherwise
+
+
+
+
+ a #GVolume
+
+
+
+
+
+ Ejects a volume. This is an asynchronous operation, and is
+finished by calling g_volume_eject_finish() with the @volume
+and #GAsyncResult returned in the @callback.
+ Use g_volume_eject_with_operation() instead.
+
+
+
+
+
+
+ a #GVolume
+
+
+
+ flags affecting the unmount if required for eject
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback, or %NULL
+
+
+
+ user data that gets passed to @callback
+
+
+
+
+
+ Finishes ejecting a volume. If any errors occurred during the operation,
+@error will be set to contain the errors and %FALSE will be returned.
+ Use g_volume_eject_with_operation_finish() instead.
+
+
+ %TRUE, %FALSE if operation failed
+
+
+
+
+ pointer to a #GVolume
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Ejects a volume. This is an asynchronous operation, and is
+finished by calling g_volume_eject_with_operation_finish() with the @volume
+and #GAsyncResult data returned in the @callback.
+
+
+
+
+
+
+ a #GVolume
+
+
+
+ flags affecting the unmount if required for eject
+
+
+
+ a #GMountOperation or %NULL to
+ avoid user interaction
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback, or %NULL
+
+
+
+ user data passed to @callback
+
+
+
+
+
+ Finishes ejecting a volume. If any errors occurred during the operation,
+@error will be set to contain the errors and %FALSE will be returned.
+
+
+ %TRUE if the volume was successfully ejected. %FALSE otherwise
+
+
+
+
+ a #GVolume
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Gets the kinds of [identifiers][volume-identifier] that @volume has.
+Use g_volume_get_identifier() to obtain the identifiers themselves.
+
+
+ a %NULL-terminated array
+ of strings containing kinds of identifiers. Use g_strfreev() to free.
+
+
+
+
+
+
+ a #GVolume
+
+
+
+
+
+ Gets the activation root for a #GVolume if it is known ahead of
+mount time. Returns %NULL otherwise. If not %NULL and if @volume
+is mounted, then the result of g_mount_get_root() on the
+#GMount object obtained from g_volume_get_mount() will always
+either be equal or a prefix of what this function returns. In
+other words, in code
+
+|[<!-- language="C" -->
+ GMount *mount;
+ GFile *mount_root
+ GFile *volume_activation_root;
+
+ mount = g_volume_get_mount (volume); // mounted, so never NULL
+ mount_root = g_mount_get_root (mount);
+ volume_activation_root = g_volume_get_activation_root (volume); // assume not NULL
+]|
+then the expression
+|[<!-- language="C" -->
+ (g_file_has_prefix (volume_activation_root, mount_root) ||
+ g_file_equal (volume_activation_root, mount_root))
+]|
+will always be %TRUE.
+
+Activation roots are typically used in #GVolumeMonitor
+implementations to find the underlying mount to shadow, see
+g_mount_is_shadowed() for more details.
+
+
+ the activation root of @volume
+ or %NULL. Use g_object_unref() to free.
+
+
+
+
+ a #GVolume
+
+
+
+
+
+ Gets the drive for the @volume.
+
+
+ a #GDrive or %NULL if @volume is not
+ associated with a drive. The returned object should be unreffed
+ with g_object_unref() when no longer needed.
+
+
+
+
+ a #GVolume
+
+
+
+
+
+ Gets the icon for @volume.
+
+
+ a #GIcon.
+ The returned object should be unreffed with g_object_unref()
+ when no longer needed.
+
+
+
+
+ a #GVolume
+
+
+
+
+
+ Gets the identifier of the given kind for @volume.
+See the [introduction][volume-identifier] for more
+information about volume identifiers.
+
+
+ a newly allocated string containing the
+ requested identifier, or %NULL if the #GVolume
+ doesn't have this kind of identifier
+
+
+
+
+ a #GVolume
+
+
+
+ the kind of identifier to return
+
+
+
+
+
+ Gets the mount for the @volume.
+
+
+ a #GMount or %NULL if @volume isn't mounted.
+ The returned object should be unreffed with g_object_unref()
+ when no longer needed.
+
+
+
+
+ a #GVolume
+
+
+
+
+
+ Gets the name of @volume.
+
+
+ the name for the given @volume. The returned string should
+ be freed with g_free() when no longer needed.
+
+
+
+
+ a #GVolume
+
+
+
+
+
+ Gets the sort key for @volume, if any.
+
+
+ Sorting key for @volume or %NULL if no such key is available
+
+
+
+
+ a #GVolume
+
+
+
+
+
+ Gets the symbolic icon for @volume.
+
+
+ a #GIcon.
+ The returned object should be unreffed with g_object_unref()
+ when no longer needed.
+
+
+
+
+ a #GVolume
+
+
+
+
+
+ Gets the UUID for the @volume. The reference is typically based on
+the file system UUID for the volume in question and should be
+considered an opaque string. Returns %NULL if there is no UUID
+available.
+
+
+ the UUID for @volume or %NULL if no UUID
+ can be computed.
+ The returned string should be freed with g_free()
+ when no longer needed.
+
+
+
+
+ a #GVolume
+
+
+
+
+
+ Mounts a volume. This is an asynchronous operation, and is
+finished by calling g_volume_mount_finish() with the @volume
+and #GAsyncResult returned in the @callback.
+
+
+
+
+
+
+ a #GVolume
+
+
+
+ flags affecting the operation
+
+
+
+ a #GMountOperation or %NULL to avoid user interaction
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback, or %NULL
+
+
+
+ user data that gets passed to @callback
+
+
+
+
+
+ Finishes mounting a volume. If any errors occurred during the operation,
+@error will be set to contain the errors and %FALSE will be returned.
+
+If the mount operation succeeded, g_volume_get_mount() on @volume
+is guaranteed to return the mount right after calling this
+function; there's no need to listen for the 'mount-added' signal on
+#GVolumeMonitor.
+
+
+ %TRUE, %FALSE if operation failed
+
+
+
+
+ a #GVolume
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Returns whether the volume should be automatically mounted.
+
+
+ %TRUE if the volume should be automatically mounted
+
+
+
+
+ a #GVolume
+
+
+
+
+
+ Emitted when the volume has been changed.
+
+
+
+
+
+ This signal is emitted when the #GVolume have been removed. If
+the recipient is holding references to the object they should
+release them so the object can be finalized.
+
+
+
+
+
+
+ Interface for implementing operations for mountable volumes.
+
+
+ The parent interface.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ the name for the given @volume. The returned string should
+ be freed with g_free() when no longer needed.
+
+
+
+
+ a #GVolume
+
+
+
+
+
+
+
+
+
+ a #GIcon.
+ The returned object should be unreffed with g_object_unref()
+ when no longer needed.
+
+
+
+
+ a #GVolume
+
+
+
+
+
+
+
+
+
+ the UUID for @volume or %NULL if no UUID
+ can be computed.
+ The returned string should be freed with g_free()
+ when no longer needed.
+
+
+
+
+ a #GVolume
+
+
+
+
+
+
+
+
+
+ a #GDrive or %NULL if @volume is not
+ associated with a drive. The returned object should be unreffed
+ with g_object_unref() when no longer needed.
+
+
+
+
+ a #GVolume
+
+
+
+
+
+
+
+
+
+ a #GMount or %NULL if @volume isn't mounted.
+ The returned object should be unreffed with g_object_unref()
+ when no longer needed.
+
+
+
+
+ a #GVolume
+
+
+
+
+
+
+
+
+
+ %TRUE if the @volume can be mounted. %FALSE otherwise
+
+
+
+
+ a #GVolume
+
+
+
+
+
+
+
+
+
+ %TRUE if the @volume can be ejected. %FALSE otherwise
+
+
+
+
+ a #GVolume
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GVolume
+
+
+
+ flags affecting the operation
+
+
+
+ a #GMountOperation or %NULL to avoid user interaction
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback, or %NULL
+
+
+
+ user data that gets passed to @callback
+
+
+
+
+
+
+
+
+
+ %TRUE, %FALSE if operation failed
+
+
+
+
+ a #GVolume
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GVolume
+
+
+
+ flags affecting the unmount if required for eject
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback, or %NULL
+
+
+
+ user data that gets passed to @callback
+
+
+
+
+
+
+
+
+
+ %TRUE, %FALSE if operation failed
+
+
+
+
+ pointer to a #GVolume
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+ a newly allocated string containing the
+ requested identifier, or %NULL if the #GVolume
+ doesn't have this kind of identifier
+
+
+
+
+ a #GVolume
+
+
+
+ the kind of identifier to return
+
+
+
+
+
+
+
+
+
+ a %NULL-terminated array
+ of strings containing kinds of identifiers. Use g_strfreev() to free.
+
+
+
+
+
+
+ a #GVolume
+
+
+
+
+
+
+
+
+
+ %TRUE if the volume should be automatically mounted
+
+
+
+
+ a #GVolume
+
+
+
+
+
+
+
+
+
+ the activation root of @volume
+ or %NULL. Use g_object_unref() to free.
+
+
+
+
+ a #GVolume
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GVolume
+
+
+
+ flags affecting the unmount if required for eject
+
+
+
+ a #GMountOperation or %NULL to
+ avoid user interaction
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback, or %NULL
+
+
+
+ user data passed to @callback
+
+
+
+
+
+
+
+
+
+ %TRUE if the volume was successfully ejected. %FALSE otherwise
+
+
+
+
+ a #GVolume
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+
+
+
+
+ Sorting key for @volume or %NULL if no such key is available
+
+
+
+
+ a #GVolume
+
+
+
+
+
+
+
+
+
+ a #GIcon.
+ The returned object should be unreffed with g_object_unref()
+ when no longer needed.
+
+
+
+
+ a #GVolume
+
+
+
+
+
+
+
+ #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
+[thread-default-context aware][g-main-context-push-thread-default],
+and so should not be used other than from the main thread, with no
+thread-default-context active.
+
+In order to receive updates about volumes and mounts monitored through GVFS,
+a main loop must be running.
+
+
+ This function should be called by any #GVolumeMonitor
+implementation when a new #GMount object is created that is not
+associated with a #GVolume object. It must be called just before
+emitting the @mount_added signal.
+
+If the return value is not %NULL, the caller must associate the
+returned #GVolume object with the #GMount. This involves returning
+it in its g_mount_get_volume() implementation. The caller must
+also listen for the "removed" signal on the returned object
+and give up its reference when handling that signal
+
+Similarly, if implementing g_volume_monitor_adopt_orphan_mount(),
+the implementor must take a reference to @mount and return it in
+its g_volume_get_mount() implemented. Also, the implementor must
+listen for the "unmounted" signal on @mount and give up its
+reference upon handling that signal.
+
+There are two main use cases for this function.
+
+One is when implementing a user space file system driver that reads
+blocks of a block device that is already represented by the native
+volume monitor (for example a CD Audio file system driver). Such
+a driver will generate its own #GMount object that needs to be
+associated with the #GVolume object that represents the volume.
+
+The other is for implementing a #GVolumeMonitor whose sole purpose
+is to return #GVolume objects representing entries in the users
+"favorite servers" list or similar.
+ Instead of using this function, #GVolumeMonitor
+implementations should instead create shadow mounts with the URI of
+the mount they intend to adopt. See the proxy volume monitor in
+gvfs for an example of this. Also see g_mount_is_shadowed(),
+g_mount_shadow() and g_mount_unshadow() functions.
+
+
+ the #GVolume object that is the parent for @mount or %NULL
+if no wants to adopt the #GMount.
+
+
+
+
+ a #GMount object to find a parent for
+
+
+
+
+
+ Gets the volume monitor used by gio.
+
+
+ a reference to the #GVolumeMonitor used by gio. Call
+ g_object_unref() when done with it.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Gets a list of drives connected to the system.
+
+The returned list should be freed with g_list_free(), after
+its elements have been unreffed with g_object_unref().
+
+
+ a #GList of connected #GDrive objects.
+
+
+
+
+
+
+ a #GVolumeMonitor.
+
+
+
+
+
+ Finds a #GMount object by its UUID (see g_mount_get_uuid())
+
+
+ a #GMount or %NULL if no such mount is available.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GVolumeMonitor.
+
+
+
+ the UUID to look for
+
+
+
+
+
+ Gets a list of the mounts on the system.
+
+The returned list should be freed with g_list_free(), after
+its elements have been unreffed with g_object_unref().
+
+
+ a #GList of #GMount objects.
+
+
+
+
+
+
+ a #GVolumeMonitor.
+
+
+
+
+
+ Finds a #GVolume object by its UUID (see g_volume_get_uuid())
+
+
+ a #GVolume or %NULL if no such volume is available.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GVolumeMonitor.
+
+
+
+ the UUID to look for
+
+
+
+
+
+ Gets a list of the volumes on the system.
+
+The returned list should be freed with g_list_free(), after
+its elements have been unreffed with g_object_unref().
+
+
+ a #GList of #GVolume objects.
+
+
+
+
+
+
+ a #GVolumeMonitor.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Gets a list of drives connected to the system.
+
+The returned list should be freed with g_list_free(), after
+its elements have been unreffed with g_object_unref().
+
+
+ a #GList of connected #GDrive objects.
+
+
+
+
+
+
+ a #GVolumeMonitor.
+
+
+
+
+
+ Finds a #GMount object by its UUID (see g_mount_get_uuid())
+
+
+ a #GMount or %NULL if no such mount is available.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GVolumeMonitor.
+
+
+
+ the UUID to look for
+
+
+
+
+
+ Gets a list of the mounts on the system.
+
+The returned list should be freed with g_list_free(), after
+its elements have been unreffed with g_object_unref().
+
+
+ a #GList of #GMount objects.
+
+
+
+
+
+
+ a #GVolumeMonitor.
+
+
+
+
+
+ Finds a #GVolume object by its UUID (see g_volume_get_uuid())
+
+
+ a #GVolume or %NULL if no such volume is available.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GVolumeMonitor.
+
+
+
+ the UUID to look for
+
+
+
+
+
+ Gets a list of the volumes on the system.
+
+The returned list should be freed with g_list_free(), after
+its elements have been unreffed with g_object_unref().
+
+
+ a #GList of #GVolume objects.
+
+
+
+
+
+
+ a #GVolumeMonitor.
+
+
+
+
+
+
+
+
+
+
+
+ Emitted when a drive changes.
+
+
+
+
+
+ the drive that changed
+
+
+
+
+
+ Emitted when a drive is connected to the system.
+
+
+
+
+
+ a #GDrive that was connected.
+
+
+
+
+
+ Emitted when a drive is disconnected from the system.
+
+
+
+
+
+ a #GDrive that was disconnected.
+
+
+
+
+
+ Emitted when the eject button is pressed on @drive.
+
+
+
+
+
+ the drive where the eject button was pressed
+
+
+
+
+
+ Emitted when the stop button is pressed on @drive.
+
+
+
+
+
+ the drive where the stop button was pressed
+
+
+
+
+
+ Emitted when a mount is added.
+
+
+
+
+
+ a #GMount that was added.
+
+
+
+
+
+ Emitted when a mount changes.
+
+
+
+
+
+ a #GMount that changed.
+
+
+
+
+
+ May be emitted when a mount is about to be removed.
+
+This signal depends on the backend and is only emitted if
+GIO was used to unmount.
+
+
+
+
+
+ a #GMount that is being unmounted.
+
+
+
+
+
+ Emitted when a mount is removed.
+
+
+
+
+
+ a #GMount that was removed.
+
+
+
+
+
+ Emitted when a mountable volume is added to the system.
+
+
+
+
+
+ a #GVolume that was added.
+
+
+
+
+
+ Emitted when mountable volume is changed.
+
+
+
+
+
+ a #GVolume that changed.
+
+
+
+
+
+ Emitted when a mountable volume is removed from the system.
+
+
+
+
+
+ a #GVolume that was removed.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GList of connected #GDrive objects.
+
+
+
+
+
+
+ a #GVolumeMonitor.
+
+
+
+
+
+
+
+
+
+ a #GList of #GVolume objects.
+
+
+
+
+
+
+ a #GVolumeMonitor.
+
+
+
+
+
+
+
+
+
+ a #GList of #GMount objects.
+
+
+
+
+
+
+ a #GVolumeMonitor.
+
+
+
+
+
+
+
+
+
+ a #GVolume or %NULL if no such volume is available.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GVolumeMonitor.
+
+
+
+ the UUID to look for
+
+
+
+
+
+
+
+
+
+ a #GMount or %NULL if no such mount is available.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GVolumeMonitor.
+
+
+
+ the UUID to look for
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #GZlibCompressor is an implementation of #GConverter that
+compresses data using zlib.
+
+
+
+ Creates a new #GZlibCompressor.
+
+
+ a new #GZlibCompressor
+
+
+
+
+ The format to use for the compressed data
+
+
+
+ compression level (0-9), -1 for default
+
+
+
+
+
+ Returns the #GZlibCompressor:file-info property.
+
+
+ a #GFileInfo, or %NULL
+
+
+
+
+ a #GZlibCompressor
+
+
+
+
+
+ Sets @file_info in @compressor. If non-%NULL, and @compressor's
+#GZlibCompressor:format property is %G_ZLIB_COMPRESSOR_FORMAT_GZIP,
+it will be used to set the file name and modification time in
+the GZIP header of the compressed data.
+
+Note: it is an error to call this function while a compression is in
+progress; it may only be called immediately after creation of @compressor,
+or after resetting it with g_converter_reset().
+
+
+
+
+
+
+ a #GZlibCompressor
+
+
+
+ a #GFileInfo
+
+
+
+
+
+ If set to a non-%NULL #GFileInfo object, and #GZlibCompressor:format is
+%G_ZLIB_COMPRESSOR_FORMAT_GZIP, the compressor will write the file name
+and modification time from the file info to the GZIP header.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Used to select the type of data format to use for #GZlibDecompressor
+and #GZlibCompressor.
+
+ deflate compression with zlib header
+
+
+ gzip file format
+
+
+ deflate compression with no header
+
+
+
+ #GZlibDecompressor is an implementation of #GConverter that
+decompresses data compressed with zlib.
+
+
+
+ Creates a new #GZlibDecompressor.
+
+
+ a new #GZlibDecompressor
+
+
+
+
+ The format to use for the compressed data
+
+
+
+
+
+ Retrieves the #GFileInfo constructed from the GZIP header data
+of compressed data processed by @compressor, or %NULL if @decompressor's
+#GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP,
+or the header data was not fully processed yet, or it not present in the
+data stream at all.
+
+
+ a #GFileInfo, or %NULL
+
+
+
+
+ a #GZlibDecompressor
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Checks if @action_name is valid.
+
+@action_name is valid if it consists only of alphanumeric characters,
+plus '-' and '.'. The empty string is not a valid action name.
+
+It is an error to call this function with a non-utf8 @action_name.
+@action_name must not be %NULL.
+
+
+ %TRUE if @action_name is valid
+
+
+
+
+ a potential action name
+
+
+
+
+
+ Parses a detailed action name into its separate name and target
+components.
+
+Detailed action names can have three formats.
+
+The first format is used to represent an action name with no target
+value and consists of just an action name containing no whitespace
+nor the characters `:`, `(` or `)`. For example: `app.action`.
+
+The second format is used to represent an action with a target value
+that is a non-empty string consisting only of alphanumerics, plus `-`
+and `.`. In that case, the action name and target value are
+separated by a double colon (`::`). For example:
+`app.action::target`.
+
+The third format is used to represent an action with any type of
+target value, including strings. The target value follows the action
+name, surrounded in parens. For example: `app.action(42)`. The
+target value is parsed using g_variant_parse(). If a tuple-typed
+value is desired, it must be specified in the same way, resulting in
+two sets of parens, for example: `app.action((1,2,3))`. A string
+target can be specified this way as well: `app.action('target')`.
+For strings, this third format must be used if target value is
+empty or contains characters other than alphanumerics, `-` and `.`.
+
+If this function returns %TRUE, a non-%NULL value is guaranteed to be returned
+in @action_name (if a pointer is passed in). A %NULL value may still be
+returned in @target_value, as the @detailed_name may not contain a target.
+
+If returned, the #GVariant in @target_value is guaranteed to not be floating.
+
+
+ %TRUE if successful, else %FALSE with @error set
+
+
+
+
+ a detailed action name
+
+
+
+ the action name
+
+
+
+ the target value,
+ or %NULL for no target
+
+
+
+
+
+ Formats a detailed action name from @action_name and @target_value.
+
+It is an error to call this function with an invalid action name.
+
+This function is the opposite of g_action_parse_detailed_name().
+It will produce a string that can be parsed back to the @action_name
+and @target_value by that function.
+
+See that function for the types of strings that will be printed by
+this function.
+
+
+ a detailed format string
+
+
+
+
+ a valid action name
+
+
+
+ a #GVariant target value, or %NULL
+
+
+
+
+
+ Creates a new #GAppInfo from the given information.
+
+Note that for @commandline, the quoting rules of the Exec key of the
+[freedesktop.org Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec)
+are applied. For example, if the @commandline contains
+percent-encoded URIs, the percent-character must be doubled in order to prevent it from
+being swallowed by Exec key unquoting. See the specification for exact quoting rules.
+
+
+ new #GAppInfo for given command.
+
+
+
+
+ the commandline to use
+
+
+
+ the application name, or %NULL to use @commandline
+
+
+
+ flags that can specify details of the created #GAppInfo
+
+
+
+
+
+ Gets a list of all of the applications currently registered
+on this system.
+
+For desktop files, this includes applications that have
+`NoDisplay=true` set or are excluded from display by means
+of `OnlyShowIn` or `NotShowIn`. See g_app_info_should_show().
+The returned list does not include applications which have
+the `Hidden` key set.
+
+
+ a newly allocated #GList of references to #GAppInfos.
+
+
+
+
+
+
+ Gets a list of all #GAppInfos for a given content type,
+including the recommended and fallback #GAppInfos. See
+g_app_info_get_recommended_for_type() and
+g_app_info_get_fallback_for_type().
+
+
+ #GList of #GAppInfos
+ for given @content_type or %NULL on error.
+
+
+
+
+
+
+ the content type to find a #GAppInfo for
+
+
+
+
+
+ Gets the default #GAppInfo for a given content type.
+
+
+ #GAppInfo for given @content_type or
+ %NULL on error.
+
+
+
+
+ the content type to find a #GAppInfo for
+
+
+
+ if %TRUE, the #GAppInfo is expected to
+ support URIs
+
+
+
+
+
+ Asynchronously gets the default #GAppInfo for a given content type.
+
+
+
+
+
+
+ the content type to find a #GAppInfo for
+
+
+
+ if %TRUE, the #GAppInfo is expected to
+ support URIs
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call when the request is done
+
+
+
+ data to pass to @callback
+
+
+
+
+
+ Finishes a default #GAppInfo lookup started by
+g_app_info_get_default_for_type_async().
+
+If no #GAppInfo is found, then @error will be set to %G_IO_ERROR_NOT_FOUND.
+
+
+ #GAppInfo for given @content_type or
+ %NULL on error.
+
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Gets the default application for handling URIs with
+the given URI scheme. A URI scheme is the initial part
+of the URI, up to but not including the ':', e.g. "http",
+"ftp" or "sip".
+
+
+ #GAppInfo for given @uri_scheme or
+ %NULL on error.
+
+
+
+
+ a string containing a URI scheme.
+
+
+
+
+
+ Asynchronously gets the default application for handling URIs with
+the given URI scheme. A URI scheme is the initial part
+of the URI, up to but not including the ':', e.g. "http",
+"ftp" or "sip".
+
+
+
+
+
+
+ a string containing a URI scheme.
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call when the request is done
+
+
+
+ data to pass to @callback
+
+
+
+
+
+ Finishes a default #GAppInfo lookup started by
+g_app_info_get_default_for_uri_scheme_async().
+
+If no #GAppInfo is found, then @error will be set to %G_IO_ERROR_NOT_FOUND.
+
+
+ #GAppInfo for given @uri_scheme or
+ %NULL on error.
+
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ 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.
+
+
+ #GList of #GAppInfos
+ for given @content_type or %NULL on error.
+
+
+
+
+
+
+ the content type to find a #GAppInfo for
+
+
+
+
+
+ Gets a list of recommended #GAppInfos for a given content type, i.e.
+those applications which claim to support the given content type exactly,
+and not by MIME type subclassing.
+Note that the first application of the list is the last used one, i.e.
+the last one for which g_app_info_set_as_last_used_for_type() has been
+called.
+
+
+ #GList of #GAppInfos
+ for given @content_type or %NULL on error.
+
+
+
+
+
+
+ the content type to find a #GAppInfo for
+
+
+
+
+
+ Utility function that launches the default application
+registered to handle the specified uri. Synchronous I/O
+is done on the uri to detect the type of the file if
+required.
+
+The D-Bus–activated applications don't have to be started if your application
+terminates too soon after this function. To prevent this, use
+g_app_info_launch_default_for_uri_async() instead.
+
+
+ %TRUE on success, %FALSE on error.
+
+
+
+
+ the uri to show
+
+
+
+ an optional #GAppLaunchContext
+
+
+
+
+
+ Async version of g_app_info_launch_default_for_uri().
+
+This version is useful if you are interested in receiving
+error information in the case where the application is
+sandboxed and the portal may present an application chooser
+dialog to the user.
+
+This is also useful if you want to be sure that the D-Bus–activated
+applications are really started before termination and if you are interested
+in receiving error information from their activation.
+
+
+
+
+
+
+ the uri to show
+
+
+
+ an optional #GAppLaunchContext
+
+
+
+ a #GCancellable
+
+
+
+ a #GAsyncReadyCallback to call when the request is done
+
+
+
+ data to pass to @callback
+
+
+
+
+
+ Finishes an asynchronous launch-default-for-uri operation.
+
+
+ %TRUE if the launch was successful, %FALSE if @error is set
+
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ 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().
+
+
+
+
+
+
+ a content 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.
+ Use g_object_new_with_properties() and
+g_async_initable_init_async() instead. See #GParameter for more information.
+
+
+
+
+
+
+ a #GType supporting #GAsyncInitable.
+
+
+
+ the number of parameters in @parameters
+
+
+
+ the parameters to use to construct the object
+
+
+
+ the [I/O priority][io-priority] of the operation
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+ a #GAsyncReadyCallback to call when the initialization is
+ finished
+
+
+
+ the data to pass to callback function
+
+
+
+
+
+ Asynchronously connects to the message bus specified by @bus_type.
+
+When the operation is finished, @callback will be invoked. You can
+then call g_bus_get_finish() to get the result of the operation.
+
+This is an asynchronous failable function. See g_bus_get_sync() for
+the synchronous version.
+
+
+
+
+
+
+ a #GBusType
+
+
+
+ a #GCancellable or %NULL
+
+
+
+ a #GAsyncReadyCallback to call when the request is satisfied
+
+
+
+ the data to pass to @callback
+
+
+
+
+
+ Finishes an operation started with g_bus_get().
+
+The returned object is a singleton, that is, shared with other
+callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the
+event that you need a private message bus connection, use
+g_dbus_address_get_for_bus_sync() and
+g_dbus_connection_new_for_address() with
+G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT and
+G_DBUS_CONNECTION_FLAGS_MESSAGE_BUS_CONNECTION flags.
+
+Note that the returned #GDBusConnection object will (usually) have
+the #GDBusConnection:exit-on-close property set to %TRUE.
+
+
+ a #GDBusConnection or %NULL if @error is set.
+ Free with g_object_unref().
+
+
+
+
+ a #GAsyncResult obtained from the #GAsyncReadyCallback passed
+ to g_bus_get()
+
+
+
+
+
+ Synchronously connects to the message bus specified by @bus_type.
+Note that the returned object may shared with other callers,
+e.g. if two separate parts of a process calls this function with
+the same @bus_type, they will share the same object.
+
+This is a synchronous failable function. See g_bus_get() and
+g_bus_get_finish() for the asynchronous version.
+
+The returned object is a singleton, that is, shared with other
+callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the
+event that you need a private message bus connection, use
+g_dbus_address_get_for_bus_sync() and
+g_dbus_connection_new_for_address() with
+G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT and
+G_DBUS_CONNECTION_FLAGS_MESSAGE_BUS_CONNECTION flags.
+
+Note that the returned #GDBusConnection object will (usually) have
+the #GDBusConnection:exit-on-close property set to %TRUE.
+
+
+ a #GDBusConnection or %NULL if @error is set.
+ Free with g_object_unref().
+
+
+
+
+ a #GBusType
+
+
+
+ a #GCancellable or %NULL
+
+
+
+
+
+ Starts acquiring @name on the bus specified by @bus_type and calls
+@name_acquired_handler and @name_lost_handler when the name is
+acquired respectively lost. Callbacks will be invoked in the
+[thread-default main context][g-main-context-push-thread-default]
+of the thread you are calling this function from.
+
+You are guaranteed that one of the @name_acquired_handler and @name_lost_handler
+callbacks will be invoked after calling this function - there are three
+possible cases:
+
+- @name_lost_handler with a %NULL connection (if a connection to the bus
+ can't be made).
+
+- @bus_acquired_handler then @name_lost_handler (if the name can't be
+ obtained)
+
+- @bus_acquired_handler then @name_acquired_handler (if the name was
+ obtained).
+
+When you are done owning the name, just call g_bus_unown_name()
+with the owner id this function returns.
+
+If the name is acquired or lost (for example another application
+could acquire the name if you allow replacement or the application
+currently owning the name exits), the handlers are also invoked.
+If the #GDBusConnection that is used for attempting to own the name
+closes, then @name_lost_handler is invoked since it is no longer
+possible for other processes to access the process.
+
+You cannot use g_bus_own_name() several times for the same name (unless
+interleaved with calls to g_bus_unown_name()) - only the first call
+will work.
+
+Another guarantee is that invocations of @name_acquired_handler
+and @name_lost_handler are guaranteed to alternate; that
+is, if @name_acquired_handler is invoked then you are
+guaranteed that the next time one of the handlers is invoked, it
+will be @name_lost_handler. The reverse is also true.
+
+If you plan on exporting objects (using e.g.
+g_dbus_connection_register_object()), note that it is generally too late
+to export the objects in @name_acquired_handler. Instead, you can do this
+in @bus_acquired_handler since you are guaranteed that this will run
+before @name is requested from the bus.
+
+This behavior makes it very simple to write applications that wants
+to [own names][gdbus-owning-names] and export objects.
+Simply register objects to be exported in @bus_acquired_handler and
+unregister the objects (if any) in @name_lost_handler.
+
+
+ an identifier (never 0) that can be used with
+ g_bus_unown_name() to stop owning the name.
+
+
+
+
+ the type of bus to own a name on
+
+
+
+ the well-known name to own
+
+
+
+ a set of flags from the #GBusNameOwnerFlags enumeration
+
+
+
+ handler to invoke when connected to the bus of type @bus_type or %NULL
+
+
+
+ handler to invoke when @name is acquired or %NULL
+
+
+
+ handler to invoke when @name is lost or %NULL
+
+
+
+ user data to pass to handlers
+
+
+
+ function for freeing @user_data or %NULL
+
+
+
+
+
+ Like g_bus_own_name() but takes a #GDBusConnection instead of a
+#GBusType.
+
+
+ an identifier (never 0) that can be used with
+ g_bus_unown_name() to stop owning the name
+
+
+
+
+ a #GDBusConnection
+
+
+
+ the well-known name to own
+
+
+
+ a set of flags from the #GBusNameOwnerFlags enumeration
+
+
+
+ handler to invoke when @name is acquired or %NULL
+
+
+
+ handler to invoke when @name is lost or %NULL
+
+
+
+ user data to pass to handlers
+
+
+
+ function for freeing @user_data or %NULL
+
+
+
+
+
+ Version of g_bus_own_name_on_connection() using closures instead of
+callbacks for easier binding in other languages.
+
+
+ an identifier (never 0) that can be used with
+ g_bus_unown_name() to stop owning the name.
+
+
+
+
+ a #GDBusConnection
+
+
+
+ the well-known name to own
+
+
+
+ a set of flags from the #GBusNameOwnerFlags enumeration
+
+
+
+ #GClosure to invoke when @name is
+ acquired or %NULL
+
+
+
+ #GClosure to invoke when @name is lost
+ or %NULL
+
+
+
+
+
+ Version of g_bus_own_name() using closures instead of callbacks for
+easier binding in other languages.
+
+
+ an identifier (never 0) that can be used with
+ g_bus_unown_name() to stop owning the name.
+
+
+
+
+ the type of bus to own a name on
+
+
+
+ the well-known name to own
+
+
+
+ a set of flags from the #GBusNameOwnerFlags enumeration
+
+
+
+ #GClosure to invoke when connected to
+ the bus of type @bus_type or %NULL
+
+
+
+ #GClosure to invoke when @name is
+ acquired or %NULL
+
+
+
+ #GClosure to invoke when @name is lost or
+ %NULL
+
+
+
+
+
+ Stops owning a name.
+
+Note that there may still be D-Bus traffic to process (relating to owning
+and unowning the name) in the current thread-default #GMainContext after
+this function has returned. You should continue to iterate the #GMainContext
+until the #GDestroyNotify function passed to g_bus_own_name() is called, in
+order to avoid memory leaks through callbacks queued on the #GMainContext
+after it’s stopped being iterated.
+
+
+
+
+
+
+ an identifier obtained from g_bus_own_name()
+
+
+
+
+
+ Stops watching a name.
+
+Note that there may still be D-Bus traffic to process (relating to watching
+and unwatching the name) in the current thread-default #GMainContext after
+this function has returned. You should continue to iterate the #GMainContext
+until the #GDestroyNotify function passed to g_bus_watch_name() is called, in
+order to avoid memory leaks through callbacks queued on the #GMainContext
+after it’s stopped being iterated.
+
+
+
+
+
+
+ An identifier obtained from g_bus_watch_name()
+
+
+
+
+
+ Starts watching @name on the bus specified by @bus_type and calls
+@name_appeared_handler and @name_vanished_handler when the name is
+known to have an owner respectively known to lose its
+owner. Callbacks will be invoked in the
+[thread-default main context][g-main-context-push-thread-default]
+of the thread you are calling this function from.
+
+You are guaranteed that one of the handlers will be invoked after
+calling this function. When you are done watching the name, just
+call g_bus_unwatch_name() with the watcher id this function
+returns.
+
+If the name vanishes or appears (for example the application owning
+the name could restart), the handlers are also invoked. If the
+#GDBusConnection that is used for watching the name disconnects, then
+@name_vanished_handler is invoked since it is no longer
+possible to access the name.
+
+Another guarantee is that invocations of @name_appeared_handler
+and @name_vanished_handler are guaranteed to alternate; that
+is, if @name_appeared_handler is invoked then you are
+guaranteed that the next time one of the handlers is invoked, it
+will be @name_vanished_handler. The reverse is also true.
+
+This behavior makes it very simple to write applications that want
+to take action when a certain [name exists][gdbus-watching-names].
+Basically, the application should create object proxies in
+@name_appeared_handler and destroy them again (if any) in
+@name_vanished_handler.
+
+
+ An identifier (never 0) that can be used with
+g_bus_unwatch_name() to stop watching the name.
+
+
+
+
+ The type of bus to watch a name on.
+
+
+
+ The name (well-known or unique) to watch.
+
+
+
+ Flags from the #GBusNameWatcherFlags enumeration.
+
+
+
+ Handler to invoke when @name is known to exist or %NULL.
+
+
+
+ Handler to invoke when @name is known to not exist or %NULL.
+
+
+
+ User data to pass to handlers.
+
+
+
+ Function for freeing @user_data or %NULL.
+
+
+
+
+
+ Like g_bus_watch_name() but takes a #GDBusConnection instead of a
+#GBusType.
+
+
+ An identifier (never 0) that can be used with
+g_bus_unwatch_name() to stop watching the name.
+
+
+
+
+ A #GDBusConnection.
+
+
+
+ The name (well-known or unique) to watch.
+
+
+
+ Flags from the #GBusNameWatcherFlags enumeration.
+
+
+
+ Handler to invoke when @name is known to exist or %NULL.
+
+
+
+ Handler to invoke when @name is known to not exist or %NULL.
+
+
+
+ User data to pass to handlers.
+
+
+
+ Function for freeing @user_data or %NULL.
+
+
+
+
+
+ Version of g_bus_watch_name_on_connection() using closures instead of callbacks for
+easier binding in other languages.
+
+
+ An identifier (never 0) that can be used with
+g_bus_unwatch_name() to stop watching the name.
+
+
+
+
+ A #GDBusConnection.
+
+
+
+ The name (well-known or unique) to watch.
+
+
+
+ Flags from the #GBusNameWatcherFlags enumeration.
+
+
+
+ #GClosure to invoke when @name is known
+to exist or %NULL.
+
+
+
+ #GClosure to invoke when @name is known
+to not exist or %NULL.
+
+
+
+
+
+ Version of g_bus_watch_name() using closures instead of callbacks for
+easier binding in other languages.
+
+
+ An identifier (never 0) that can be used with
+g_bus_unwatch_name() to stop watching the name.
+
+
+
+
+ The type of bus to watch a name on.
+
+
+
+ The name (well-known or unique) to watch.
+
+
+
+ Flags from the #GBusNameWatcherFlags enumeration.
+
+
+
+ #GClosure to invoke when @name is known
+to exist or %NULL.
+
+
+
+ #GClosure to invoke when @name is known
+to not exist or %NULL.
+
+
+
+
+
+ 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).
+
+
+ %TRUE if the file type corresponds to a type that
+ can be executable, %FALSE otherwise.
+
+
+
+
+ a content type string
+
+
+
+
+
+ Compares two content types for equality.
+
+
+ %TRUE if the two strings are identical or equivalent,
+ %FALSE otherwise.
+
+
+
+
+ a content type string
+
+
+
+ a content type string
+
+
+
+
+
+ Tries to find a content type based on the mime type name.
+
+
+ Newly allocated string with content type or
+ %NULL. Free with g_free()
+
+
+
+
+ a mime type string
+
+
+
+
+
+ Gets the human readable description of the content type.
+
+
+ a short description of the content type @type. Free the
+ returned string with g_free()
+
+
+
+
+ a content type string
+
+
+
+
+
+ Gets the generic icon name for a content type.
+
+See the
+[shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
+specification for more on the generic icon name.
+
+
+ the registered generic icon name for the given @type,
+ or %NULL if unknown. Free with g_free()
+
+
+
+
+ a content type string
+
+
+
+
+
+ Gets the icon for a content type.
+
+
+ #GIcon corresponding to the content type. Free the returned
+ object with g_object_unref()
+
+
+
+
+ a content type string
+
+
+
+
+
+ Get the list of directories which MIME data is loaded from. See
+g_content_type_set_mime_dirs() for details.
+
+
+ %NULL-terminated list of
+ directories to load MIME data from, including any `mime/` subdirectory,
+ and with the first directory to try listed first
+
+
+
+
+
+
+ Gets the mime type for the content type, if one is registered.
+
+
+ the registered mime type for the
+ given @type, or %NULL if unknown; free with g_free().
+
+
+
+
+ a content type string
+
+
+
+
+
+ Gets the symbolic icon for a content type.
+
+
+ symbolic #GIcon corresponding to the content type.
+ Free the returned object with g_object_unref()
+
+
+
+
+ a content type string
+
+
+
+
+
+ Guesses the content type based on example data. If the function is
+uncertain, @result_uncertain will be set to %TRUE. Either @filename
+or @data may be %NULL, in which case the guess will be based solely
+on the other argument.
+
+
+ a string indicating a guessed content type for the
+ given data. Free with g_free()
+
+
+
+
+ a path, or %NULL
+
+
+
+ a stream of data, or %NULL
+
+
+
+
+
+ the size of @data
+
+
+
+ return location for the certainty
+ of the result, or %NULL
+
+
+
+
+
+ Tries to guess the type of the tree with root @root, by
+looking at the files it contains. The result is an array
+of content types, with the best guess coming first.
+
+The types returned all have the form x-content/foo, e.g.
+x-content/audio-cdda (for audio CDs) or x-content/image-dcf
+(for a camera memory card). See the
+[shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
+specification for more on x-content types.
+
+This function is useful in the implementation of
+g_mount_guess_content_type().
+
+
+ an %NULL-terminated
+ array of zero or more content types. Free with g_strfreev()
+
+
+
+
+
+
+ the root of the tree to guess a type for
+
+
+
+
+
+ Determines if @type is a subset of @supertype.
+
+
+ %TRUE if @type is a kind of @supertype,
+ %FALSE otherwise.
+
+
+
+
+ a content type string
+
+
+
+ a content type string
+
+
+
+
+
+ Determines if @type is a subset of @mime_type.
+Convenience wrapper around g_content_type_is_a().
+
+
+ %TRUE if @type is a kind of @mime_type,
+ %FALSE otherwise.
+
+
+
+
+ a content type string
+
+
+
+ a mime type string
+
+
+
+
+
+ Checks if the content type is the generic "unknown" type.
+On UNIX this is the "application/octet-stream" mimetype,
+while on win32 it is "*" and on OSX it is a dynamic type
+or octet-stream.
+
+
+ %TRUE if the type is the unknown type.
+
+
+
+
+ a content type string
+
+
+
+
+
+ Set the list of directories used by GIO to load the MIME database.
+If @dirs is %NULL, the directories used are the default:
+
+ - the `mime` subdirectory of the directory in `$XDG_DATA_HOME`
+ - the `mime` subdirectory of every directory in `$XDG_DATA_DIRS`
+
+This function is intended to be used when writing tests that depend on
+information stored in the MIME database, in order to control the data.
+
+Typically, in case your tests use %G_TEST_OPTION_ISOLATE_DIRS, but they
+depend on the system’s MIME database, you should call this function
+with @dirs set to %NULL before calling g_test_init(), for instance:
+
+|[<!-- language="C" -->
+ // Load MIME data from the system
+ g_content_type_set_mime_dirs (NULL);
+ // Isolate the environment
+ g_test_init (&argc, &argv, G_TEST_OPTION_ISOLATE_DIRS, NULL);
+
+ …
+
+ return g_test_run ();
+]|
+
+
+
+
+
+
+ %NULL-terminated list of
+ directories to load MIME data from, including any `mime/` subdirectory,
+ and with the first directory to try listed first
+
+
+
+
+
+
+
+ Gets a list of strings containing all the registered content types
+known to the system. The list and its data should be freed using
+`g_list_free_full (list, g_free)`.
+
+
+ list of the registered
+ content types
+
+
+
+
+
+
+ Escape @string so it can appear in a D-Bus address as the value
+part of a key-value pair.
+
+For instance, if @string is `/run/bus-for-:0`,
+this function would return `/run/bus-for-%3A0`,
+which could be used in a D-Bus address like
+`unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0`.
+
+
+ a copy of @string with all
+ non-optionally-escaped bytes escaped
+
+
+
+
+ an unescaped string to be included in a D-Bus address
+ as the value in a key-value pair
+
+
+
+
+
+ Synchronously looks up the D-Bus address for the well-known message
+bus instance specified by @bus_type. This may involve using various
+platform specific mechanisms.
+
+The returned address will be in the
+[D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
+
+
+ a valid D-Bus address string for @bus_type or
+ %NULL if @error is set
+
+
+
+
+ a #GBusType
+
+
+
+ a #GCancellable or %NULL
+
+
+
+
+
+ Asynchronously connects to an endpoint specified by @address and
+sets up the connection so it is in a state to run the client-side
+of the D-Bus authentication conversation. @address must be in the
+[D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
+
+When the operation is finished, @callback will be invoked. You can
+then call g_dbus_address_get_stream_finish() to get the result of
+the operation.
+
+This is an asynchronous failable function. See
+g_dbus_address_get_stream_sync() for the synchronous version.
+
+
+
+
+
+
+ A valid D-Bus address.
+
+
+
+ A #GCancellable or %NULL.
+
+
+
+ A #GAsyncReadyCallback to call when the request is satisfied.
+
+
+
+ Data to pass to @callback.
+
+
+
+
+
+ Finishes an operation started with g_dbus_address_get_stream().
+
+A server is not required to set a GUID, so @out_guid may be set to %NULL
+even on success.
+
+
+ A #GIOStream or %NULL if @error is set.
+
+
+
+
+ A #GAsyncResult obtained from the GAsyncReadyCallback passed to g_dbus_address_get_stream().
+
+
+
+ %NULL or return location to store the GUID extracted from @address, if any.
+
+
+
+
+
+ Synchronously connects to an endpoint specified by @address and
+sets up the connection so it is in a state to run the client-side
+of the D-Bus authentication conversation. @address must be in the
+[D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
+
+A server is not required to set a GUID, so @out_guid may be set to %NULL
+even on success.
+
+This is a synchronous failable function. See
+g_dbus_address_get_stream() for the asynchronous version.
+
+
+ A #GIOStream or %NULL if @error is set.
+
+
+
+
+ A valid D-Bus address.
+
+
+
+ %NULL or return location to store the GUID extracted from @address, if any.
+
+
+
+ A #GCancellable or %NULL.
+
+
+
+
+
+ Looks up the value of an annotation.
+
+The cost of this function is O(n) in number of annotations.
+
+
+ The value or %NULL if not found. Do not free, it is owned by @annotations.
+
+
+
+
+ A %NULL-terminated array of annotations or %NULL.
+
+
+
+
+
+ The name of the annotation to look up.
+
+
+
+
+
+ Creates a D-Bus error name to use for @error. If @error matches
+a registered error (cf. g_dbus_error_register_error()), the corresponding
+D-Bus error name will be returned.
+
+Otherwise the a name of the form
+`org.gtk.GDBus.UnmappedGError.Quark._ESCAPED_QUARK_NAME.Code_ERROR_CODE`
+will be used. This allows other GDBus applications to map the error
+on the wire back to a #GError using g_dbus_error_new_for_dbus_error().
+
+This function is typically only used in object mappings to put a
+#GError on the wire. Regular applications should not use it.
+
+
+ A D-Bus error name (never %NULL).
+ Free with g_free().
+
+
+
+
+ A #GError.
+
+
+
+
+
+ Gets the D-Bus error name used for @error, if any.
+
+This function is guaranteed to return a D-Bus error name for all
+#GErrors returned from functions handling remote method calls
+(e.g. g_dbus_connection_call_finish()) unless
+g_dbus_error_strip_remote_error() has been used on @error.
+
+
+ an allocated string or %NULL if the
+ D-Bus error name could not be found. Free with g_free().
+
+
+
+
+ a #GError
+
+
+
+
+
+ Checks if @error represents an error received via D-Bus from a remote peer. If so,
+use g_dbus_error_get_remote_error() to get the name of the error.
+
+
+ %TRUE if @error represents an error from a remote peer,
+%FALSE otherwise.
+
+
+
+
+ A #GError.
+
+
+
+
+
+ Creates a #GError based on the contents of @dbus_error_name and
+@dbus_error_message.
+
+Errors registered with g_dbus_error_register_error() will be looked
+up using @dbus_error_name and if a match is found, the error domain
+and code is used. Applications can use g_dbus_error_get_remote_error()
+to recover @dbus_error_name.
+
+If a match against a registered error is not found and the D-Bus
+error name is in a form as returned by g_dbus_error_encode_gerror()
+the error domain and code encoded in the name is used to
+create the #GError. Also, @dbus_error_name is added to the error message
+such that it can be recovered with g_dbus_error_get_remote_error().
+
+Otherwise, a #GError with the error code %G_IO_ERROR_DBUS_ERROR
+in the %G_IO_ERROR error domain is returned. Also, @dbus_error_name is
+added to the error message such that it can be recovered with
+g_dbus_error_get_remote_error().
+
+In all three cases, @dbus_error_name can always be recovered from the
+returned #GError using the g_dbus_error_get_remote_error() function
+(unless g_dbus_error_strip_remote_error() hasn't been used on the returned error).
+
+This function is typically only used in object mappings to prepare
+#GError instances for applications. Regular applications should not use
+it.
+
+
+ An allocated #GError. Free with g_error_free().
+
+
+
+
+ D-Bus error name.
+
+
+
+ D-Bus error message.
+
+
+
+
+
+
+
+
+
+
+ Creates an association to map between @dbus_error_name and
+#GErrors specified by @error_domain and @error_code.
+
+This is typically done in the routine that returns the #GQuark for
+an error domain.
+
+
+ %TRUE if the association was created, %FALSE if it already
+exists.
+
+
+
+
+ A #GQuark for an error domain.
+
+
+
+ An error code.
+
+
+
+ A D-Bus error name.
+
+
+
+
+
+ Helper function for associating a #GError error domain with D-Bus error names.
+
+While @quark_volatile has a `volatile` qualifier, this is a historical
+artifact and the argument passed to it should not be `volatile`.
+
+
+
+
+
+
+ The error domain name.
+
+
+
+ A pointer where to store the #GQuark.
+
+
+
+ A pointer to @num_entries #GDBusErrorEntry struct items.
+
+
+
+
+
+ Number of items to register.
+
+
+
+
+
+ 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.
+
+
+ %TRUE if information was stripped, %FALSE otherwise.
+
+
+
+
+ A #GError.
+
+
+
+
+
+ Destroys an association previously set up with g_dbus_error_register_error().
+
+
+ %TRUE if the association was destroyed, %FALSE if it wasn't found.
+
+
+
+
+ A #GQuark for an error domain.
+
+
+
+ An error code.
+
+
+
+ A D-Bus error name.
+
+
+
+
+
+ This is a language binding friendly version of g_dbus_escape_object_path_bytestring().
+
+
+ an escaped version of @s. Free with g_free().
+
+
+
+
+ the string to escape
+
+
+
+
+
+ Escapes @bytes for use in a D-Bus object path component.
+@bytes is an array of zero or more nonzero bytes in an
+unspecified encoding, followed by a single zero byte.
+
+The escaping method consists of replacing all non-alphanumeric
+characters (see g_ascii_isalnum()) with their hexadecimal value
+preceded by an underscore (`_`). For example:
+`foo.bar.baz` will become `foo_2ebar_2ebaz`.
+
+This method is appropriate to use when the input is nearly
+a valid object path component but is not when your input
+is far from being a valid object path component.
+Other escaping algorithms are also valid to use with
+D-Bus object paths.
+
+This can be reversed with g_dbus_unescape_object_path().
+
+
+ an escaped version of @bytes. Free with g_free().
+
+
+
+
+ the string of bytes to escape
+
+
+
+
+
+
+
+ Generate a D-Bus GUID that can be used with
+e.g. g_dbus_connection_new().
+
+See the
+[D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#uuids)
+regarding what strings are valid D-Bus GUIDs. The specification refers to
+these as ‘UUIDs’ whereas GLib (for historical reasons) refers to them as
+‘GUIDs’. The terms are interchangeable.
+
+Note that D-Bus GUIDs do not follow
+[RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122).
+
+
+ A valid D-Bus GUID. Free with g_free().
+
+
+
+
+ Converts a #GValue to a #GVariant of the type indicated by the @type
+parameter.
+
+The conversion is using the following rules:
+
+- `G_TYPE_STRING`: 's', 'o', 'g' or 'ay'
+- `G_TYPE_STRV`: 'as', 'ao' or 'aay'
+- `G_TYPE_BOOLEAN`: 'b'
+- `G_TYPE_UCHAR`: 'y'
+- `G_TYPE_INT`: 'i', 'n'
+- `G_TYPE_UINT`: 'u', 'q'
+- `G_TYPE_INT64`: 'x'
+- `G_TYPE_UINT64`: 't'
+- `G_TYPE_DOUBLE`: 'd'
+- `G_TYPE_VARIANT`: Any #GVariantType
+
+This can fail if e.g. @gvalue is of type %G_TYPE_STRING and @type
+is 'i', i.e. %G_VARIANT_TYPE_INT32. It will also fail for any #GType
+(including e.g. %G_TYPE_OBJECT and %G_TYPE_BOXED derived-types) not
+in the table above.
+
+Note that if @gvalue is of type %G_TYPE_VARIANT and its value is
+%NULL, the empty #GVariant instance (never %NULL) for @type is
+returned (e.g. 0 for scalar types, the empty string for string types,
+'/' for object path types, the empty array for any array type and so on).
+
+See the g_dbus_gvariant_to_gvalue() function for how to convert a
+#GVariant to a #GValue.
+
+
+ A #GVariant (never floating) of
+ #GVariantType @type holding the data from @gvalue or an empty #GVariant
+ in case of failure. Free with g_variant_unref().
+
+
+
+
+ A #GValue to convert to a #GVariant
+
+
+
+ A #GVariantType
+
+
+
+
+
+ Converts a #GVariant to a #GValue. If @value is floating, it is consumed.
+
+The rules specified in the g_dbus_gvalue_to_gvariant() function are
+used - this function is essentially its reverse form. So, a #GVariant
+containing any basic or string array type will be converted to a #GValue
+containing a basic value or string array. Any other #GVariant (handle,
+variant, tuple, dict entry) will be converted to a #GValue containing that
+#GVariant.
+
+The conversion never fails - a valid #GValue is always returned in
+@out_gvalue.
+
+
+
+
+
+
+ A #GVariant.
+
+
+
+ Return location pointing to a zero-filled (uninitialized) #GValue.
+
+
+
+
+
+ Checks if @string is a
+[D-Bus address](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
+
+This doesn't check if @string is actually supported by #GDBusServer
+or #GDBusConnection - use g_dbus_is_supported_address() to do more
+checks.
+
+
+ %TRUE if @string is a valid D-Bus address, %FALSE otherwise.
+
+
+
+
+ A string.
+
+
+
+
+
+ Check whether @string is a valid D-Bus error name.
+
+This function returns the same result as g_dbus_is_interface_name(),
+because D-Bus error names are defined to have exactly the
+same syntax as interface names.
+
+
+ %TRUE if valid, %FALSE otherwise.
+
+
+
+
+ The string to check.
+
+
+
+
+
+ Checks if @string is a D-Bus GUID.
+
+See the documentation for g_dbus_generate_guid() for more information about
+the format of a GUID.
+
+
+ %TRUE if @string is a GUID, %FALSE otherwise.
+
+
+
+
+ The string to check.
+
+
+
+
+
+ Checks if @string is a valid D-Bus interface name.
+
+
+ %TRUE if valid, %FALSE otherwise.
+
+
+
+
+ The string to check.
+
+
+
+
+
+ Checks if @string is a valid D-Bus member (e.g. signal or method) name.
+
+
+ %TRUE if valid, %FALSE otherwise.
+
+
+
+
+ The string to check.
+
+
+
+
+
+ Checks if @string is a valid D-Bus bus name (either unique or well-known).
+
+
+ %TRUE if valid, %FALSE otherwise.
+
+
+
+
+ The string to check.
+
+
+
+
+
+ Like g_dbus_is_address() but also checks if the library supports the
+transports in @string and that key/value pairs for each transport
+are valid. See the specification of the
+[D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
+
+
+ %TRUE if @string is a valid D-Bus address that is
+supported by this library, %FALSE if @error is set.
+
+
+
+
+ A string.
+
+
+
+
+
+ Checks if @string is a valid D-Bus unique bus name.
+
+
+ %TRUE if valid, %FALSE otherwise.
+
+
+
+
+ The string to check.
+
+
+
+
+
+ Unescapes an string that was previously escaped with
+g_dbus_escape_object_path(). If the string is in a format that could
+not have been returned by g_dbus_escape_object_path(), this function
+returns %NULL.
+
+Encoding alphanumeric characters which do not need to be
+encoded is not allowed (e.g `_63` is not valid, the string
+should contain `c` instead).
+
+
+ an
+ unescaped version of @s, or %NULL if @s is not a string returned
+ from g_dbus_escape_object_path(). Free with g_free().
+
+
+
+
+
+
+ the string to unescape
+
+
+
+
+
+ Creates a new #GDtlsClientConnection wrapping @base_socket which is
+assumed to communicate with the server identified by @server_identity.
+
+
+ the new
+ #GDtlsClientConnection, or %NULL on error
+
+
+
+
+ the #GDatagramBased to wrap
+
+
+
+ the expected identity of the server
+
+
+
+
+
+ Creates a new #GDtlsServerConnection wrapping @base_socket.
+
+
+ the new
+ #GDtlsServerConnection, or %NULL on error
+
+
+
+
+ the #GDatagramBased to wrap
+
+
+
+ the default server certificate, or %NULL
+
+
+
+
+
+ #GIOExtensionPoint provides a mechanism for modules to extend the
+functionality of the library or application that loaded it in an
+organized fashion.
+
+An extension point is identified by a name, and it may optionally
+require that any implementation must be of a certain type (or derived
+thereof). Use g_io_extension_point_register() to register an
+extension point, and g_io_extension_point_set_required_type() to
+set a required type.
+
+A module can implement an extension point by specifying the #GType
+that implements the functionality. Additionally, each implementation
+of an extension point has a name, and a priority. Use
+g_io_extension_point_implement() to implement an extension point.
+
+ |[<!-- language="C" -->
+ GIOExtensionPoint *ep;
+
+ // Register an extension point
+ ep = g_io_extension_point_register ("my-extension-point");
+ g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE);
+ ]|
+
+ |[<!-- language="C" -->
+ // Implement an extension point
+ G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE)
+ g_io_extension_point_implement ("my-extension-point",
+ my_example_impl_get_type (),
+ "my-example",
+ 10);
+ ]|
+
+ It is up to the code that registered the extension point how
+ it uses the implementations that have been associated with it.
+ Depending on the use case, it may use all implementations, or
+ only the one with the highest priority, or pick a specific
+ one by name.
+
+ To avoid opening all modules just to find out what extension
+ points they implement, GIO makes use of a caching mechanism,
+ see [gio-querymodules][gio-querymodules].
+ You are expected to run this command after installing a
+ GIO module.
+
+ The `GIO_EXTRA_MODULES` environment variable can be used to
+ specify additional directories to automatically load modules
+ from. This environment variable has the same syntax as the
+ `PATH`. If two modules have the same base name in different
+ directories, then the latter one will be ignored. If additional
+ directories are specified GIO will load modules from the built-in
+ directory last.
+
+
+ Creates a #GFile with the given argument from the command line.
+The value of @arg can be either a URI, an absolute path or a
+relative path resolved relative to the current working directory.
+This operation never fails, but the returned object might not
+support any I/O operation if @arg points to a malformed path.
+
+Note that on Windows, this function expects its argument to be in
+UTF-8 -- not the system code page. This means that you
+should not use this function with string from argv as it is passed
+to main(). g_win32_get_command_line() will return a UTF-8 version of
+the commandline. #GApplication also uses UTF-8 but
+g_application_command_line_create_file_for_arg() may be more useful
+for you there. It is also always possible to use this function with
+#GOptionContext arguments of type %G_OPTION_ARG_FILENAME.
+
+
+ a new #GFile.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a command line string
+
+
+
+
+
+ Creates a #GFile with the given argument from the command line.
+
+This function is similar to g_file_new_for_commandline_arg() except
+that it allows for passing the current working directory as an
+argument instead of using the current working directory of the
+process.
+
+This is useful if the commandline argument was given in a context
+other than the invocation of the current process.
+
+See also g_application_command_line_create_file_for_arg().
+
+
+ a new #GFile
+
+
+
+
+ a command line string
+
+
+
+ the current working directory of the commandline
+
+
+
+
+
+ Constructs a #GFile for a given path. This operation never
+fails, but the returned object might not support any I/O
+operation if @path is malformed.
+
+
+ a new #GFile for the given @path.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a string containing a relative or absolute path.
+ The string must be encoded in the glib filename encoding.
+
+
+
+
+
+ Constructs a #GFile for a given URI. This operation never
+fails, but the returned object might not support any I/O
+operation if @uri is malformed or if the uri type is
+not supported.
+
+
+ a new #GFile for the given @uri.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a UTF-8 string containing a URI
+
+
+
+
+
+ Opens a file in the preferred directory for temporary files (as
+returned by g_get_tmp_dir()) and returns a #GFile and
+#GFileIOStream pointing to it.
+
+@tmpl should be a string in the GLib file name encoding
+containing a sequence of six 'X' characters, and containing no
+directory components. If it is %NULL, a default template is used.
+
+Unlike the other #GFile constructors, this will return %NULL if
+a temporary file could not be created.
+
+
+ a new #GFile.
+ Free the returned object with g_object_unref().
+
+
+
+
+ Template for the file
+ name, as in g_file_open_tmp(), or %NULL for a default template
+
+
+
+ on return, a #GFileIOStream for the created file
+
+
+
+
+
+ Asynchronously opens a file in the preferred directory for temporary files
+ (as returned by g_get_tmp_dir()) as g_file_new_tmp().
+
+@tmpl should be a string in the GLib file name encoding
+containing a sequence of six 'X' characters, and containing no
+directory components. If it is %NULL, a default template is used.
+
+
+
+
+
+
+ Template for the file
+ name, as in g_file_open_tmp(), or %NULL for a default template
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call when the request is done
+
+
+
+ data to pass to @callback
+
+
+
+
+
+ Asynchronously creates a directory in the preferred directory for
+temporary files (as returned by g_get_tmp_dir()) as g_dir_make_tmp().
+
+@tmpl should be a string in the GLib file name encoding
+containing a sequence of six 'X' characters, and containing no
+directory components. If it is %NULL, a default template is used.
+
+
+
+
+
+
+ Template for the file
+ name, as in g_dir_make_tmp(), or %NULL for a default template
+
+
+
+ the [I/O priority][io-priority] of the request
+
+
+
+ optional #GCancellable object, %NULL to ignore
+
+
+
+ a #GAsyncReadyCallback to call when the request is done
+
+
+
+ data to pass to @callback
+
+
+
+
+
+ Finishes a temporary directory creation started by
+g_file_new_tmp_dir_async().
+
+
+ a new #GFile.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GAsyncResult
+
+
+
+
+
+ Finishes a temporary file creation started by g_file_new_tmp_async().
+
+
+ a new #GFile.
+ Free the returned object with g_object_unref().
+
+
+
+
+ a #GAsyncResult
+
+
+
+ on return, a #GFileIOStream for the created file
+
+
+
+
+
+ Constructs a #GFile with the given @parse_name (i.e. something
+given by g_file_get_parse_name()). This operation never fails,
+but the returned object might not support any I/O operation if
+the @parse_name cannot be parsed.
+
+
+ a new #GFile.
+
+
+
+
+ a file name or path to be parsed
+
+
+
+
+
+ These functions support exporting a #GActionGroup on D-Bus.
+The D-Bus interface that is used is a private implementation
+detail.
+
+To access an exported #GActionGroup remotely, use
+g_dbus_action_group_get() to obtain a #GDBusActionGroup.
+
+
+ A content type is a platform specific string that defines the type
+of a file. On UNIX it is a
+[MIME type](http://www.wikipedia.org/wiki/Internet_media_type)
+like `text/plain` or `image/png`.
+On Win32 it is an extension string like `.doc`, `.txt` or a perceived
+string like `audio`. Such strings can be looked up in the registry at
+`HKEY_CLASSES_ROOT`.
+On macOS it is a [Uniform Type Identifier](https://en.wikipedia.org/wiki/Uniform_Type_Identifier)
+such as `com.apple.application`.
+
+
+ Routines for working with D-Bus addresses. A D-Bus address is a string
+like `unix:tmpdir=/tmp/my-app-name`. The exact format of addresses
+is explained in detail in the
+[D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
+
+TCP D-Bus connections are supported, but accessing them via a proxy is
+currently not supported.
+
+Since GLib 2.72, `unix:` addresses are supported on Windows with `AF_UNIX`
+support (Windows 10).
+
+
+ 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:
+|[<!-- language="C" -->
+// 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,
+ FOO_BAR_N_ERRORS / *< skip >* /
+} 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"},
+};
+
+// Ensure that every error code has an associated D-Bus error name
+G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) == FOO_BAR_N_ERRORS);
+
+GQuark
+foo_bar_error_quark (void)
+{
+ static gsize quark = 0;
+ g_dbus_error_register_error_domain ("foo-bar-error-quark",
+ &quark,
+ foo_bar_error_entries,
+ G_N_ELEMENTS (foo_bar_error_entries));
+ return (GQuark) quark;
+}
+]|
+With this setup, a D-Bus peer can transparently pass e.g. %FOO_BAR_ERROR_ANOTHER_ERROR and
+other peers will see the D-Bus error name org.project.Foo.Bar.Error.AnotherError.
+
+If the other peer is using GDBus, and has registered the association with
+g_dbus_error_register_error_domain() in advance (e.g. by invoking the %FOO_BAR_ERROR quark
+generation itself in the previous example) the peer will see also %FOO_BAR_ERROR_ANOTHER_ERROR instead
+of %G_IO_ERROR_DBUS_ERROR. Note that GDBus clients can still recover
+org.project.Foo.Bar.Error.AnotherError using g_dbus_error_get_remote_error().
+
+Note that 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 should use the
+%G_IO_ERROR domain.
+
+
+ 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
+[D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format)
+
+
+ Convenience API for owning bus names.
+
+A simple example for owning a name can be found in
+[gdbus-example-own-name.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-own-name.c)
+
+
+ Convenience API for watching bus names.
+
+A simple example for watching a name can be found in
+[gdbus-example-watch-name.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-watch-name.c)
+
+
+ Various utility routines related to D-Bus.
+
+
+ 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 retrieved
+using wildcards, e.g. "standard::*" will return all of the keys in the
+"standard" namespace.
+
+The list of possible attributes for a filesystem (pointed to by a #GFile) is
+available as a #GFileAttributeInfoList. This list is queryable by key names
+as indicated earlier.
+
+Information is stored within the list in #GFileAttributeInfo structures.
+The info structure can store different types, listed in the enum
+#GFileAttributeType. Upon creation of a #GFileAttributeInfo, the type will
+be set to %G_FILE_ATTRIBUTE_TYPE_INVALID.
+
+Classes that implement #GFileIface will create a #GFileAttributeInfoList and
+install default keys and values for their given file system, architecture,
+and other possible implementation details (e.g., on a UNIX system, a file
+attribute key will be registered for the user id for a given file).
+
+## Default Namespaces
+
+- `"standard"`: The "Standard" namespace. General file information that
+ any application may need should be put in this namespace. Examples
+ include the file's name, type, and size.
+- `"etag`: The [Entity Tag][gfile-etag] namespace. Currently, the only key
+ in this namespace is "value", which contains the value of the current
+ entity tag.
+- `"id"`: The "Identification" namespace. This namespace is used by file
+ managers and applications that list directories to check for loops and
+ to uniquely identify files.
+- `"access"`: The "Access" namespace. Used to check if a user has the
+ proper privileges to access files and perform file operations. Keys in
+ this namespace are made to be generic and easily understood, e.g. the
+ "can_read" key is %TRUE if the current user has permission to read the
+ file. UNIX permissions and NTFS ACLs in Windows should be mapped to
+ these values.
+- `"mountable"`: The "Mountable" namespace. Includes simple boolean keys
+ for checking if a file or path supports mount operations, e.g. mount,
+ unmount, eject. These are used for files of type %G_FILE_TYPE_MOUNTABLE.
+- `"time"`: The "Time" namespace. Includes file access, changed, created
+ times.
+- `"unix"`: The "Unix" namespace. Includes UNIX-specific information and
+ may not be available for all files. Examples include the UNIX "UID",
+ "GID", etc.
+- `"dos"`: The "DOS" namespace. Includes DOS-specific information and may
+ not be available for all files. Examples include "is_system" for checking
+ if a file is marked as a system file, and "is_archive" for checking if a
+ file is marked as an archive file.
+- `"owner"`: The "Owner" namespace. Includes information about who owns a
+ file. May not be available for all file systems. Examples include "user"
+ for getting the user name of the file owner. This information is often
+ mapped from some backend specific data such as a UNIX UID.
+- `"thumbnail"`: The "Thumbnail" namespace. Includes information about file
+ thumbnails and their location within the file system. Examples of keys in
+ this namespace include "path" to get the location of a thumbnail, "failed"
+ to check if thumbnailing of the file failed, and "is-valid" to check if
+ the thumbnail is outdated.
+- `"filesystem"`: The "Filesystem" namespace. Gets information about the
+ file system where a file is located, such as its type, how much space is
+ left available, and the overall size of the file system.
+- `"gvfs"`: The "GVFS" namespace. Keys in this namespace contain information
+ about the current GVFS backend in use.
+- `"xattr"`: The "xattr" namespace. Gets information about extended
+ user attributes. See attr(5). The "user." prefix of the extended user
+ attribute name is stripped away when constructing keys in this namespace,
+ e.g. "xattr::mime_type" for the extended attribute with the name
+ "user.mime_type". Note that this information is only available if
+ GLib has been built with extended attribute support.
+- `"xattr-sys"`: The "xattr-sys" namespace. Gets information about
+ extended attributes which are not user-specific. See attr(5). Note
+ that this information is only available if GLib has been built with
+ extended attribute support.
+- `"selinux"`: The "SELinux" namespace. Includes information about the
+ SELinux context of files. Note that this information is only available
+ if GLib has been built with SELinux support.
+
+Please note that these are not all of the possible namespaces.
+More namespaces can be added from GIO modules or by individual applications.
+For more information about writing GIO modules, see #GIOModule.
+
+<!-- TODO: Implementation note about using extended attributes on supported
+file systems -->
+
+## Default Keys
+
+For a list of the built-in keys and their types, see the
+[GFileInfo][GFileInfo] documentation.
+
+Note that there are no predefined keys in the "xattr" and "xattr-sys"
+namespaces. Keys for the "xattr" namespace are constructed by stripping
+away the "user." prefix from the extended user attribute, and prepending
+"xattr::". Keys for the "xattr-sys" namespace are constructed by
+concatenating "xattr-sys::" with the extended attribute name. All extended
+attribute values are returned as hex-encoded strings in which bytes outside
+the ASCII range are encoded as escape sequences of the form \x`nn`
+where `nn` is a 2-digit hexadecimal number.
+
+
+ Contains helper functions for reporting errors to the user.
+
+
+ As of GLib 2.36, #GIOScheduler is deprecated in favor of
+#GThreadPool and #GTask.
+
+Schedules asynchronous I/O operations. #GIOScheduler integrates
+into the main event loop (#GMainLoop) and uses threads.
+
+
+ These functions support exporting a #GMenuModel on D-Bus.
+The D-Bus interface that is used is a private implementation
+detail.
+
+To access an exported #GMenuModel remotely, use
+g_dbus_menu_model_get() to obtain a #GDBusMenuModel.
+
+
+ The `<gio/gnetworking.h>` header can be included to get
+various low-level networking-related system headers, automatically
+taking care of certain portability issues for you.
+
+This can be used, for example, if you want to call setsockopt()
+on a #GSocket.
+
+Note that while WinSock has many of the same APIs as the
+traditional UNIX socket API, most of them behave at least slightly
+differently (particularly with respect to error handling). If you
+want your code to work under both UNIX and Windows, you will need
+to take these differences into account.
+
+Also, under GNU libc, certain non-portable functions are only visible
+in the headers if you define %_GNU_SOURCE before including them. Note
+that this symbol must be defined before including any headers, or it
+may not take effect.
+
+
+ Utility functions for #GPollableInputStream and
+#GPollableOutputStream implementations.
+
+
+ #GTlsConnection and related classes provide TLS (Transport Layer
+Security, previously known as SSL, Secure Sockets Layer) support for
+gio-based network streams.
+
+#GDtlsConnection and related classes provide DTLS (Datagram TLS) support for
+GIO-based network sockets, using the #GDatagramBased interface. The TLS and
+DTLS APIs are almost identical, except TLS is stream-based and DTLS is
+datagram-based. They share certificate and backend infrastructure.
+
+In the simplest case, for a client TLS 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.
+
+
+ Routines for managing mounted UNIX mount points and paths.
+
+Note that `<gio/gunixmounts.h>` belongs to the UNIX-specific GIO
+interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
+file when using it.
+
+
+ #GWin32InputStream implements #GInputStream for reading from a
+Windows file handle.
+
+Note that `<gio/gwin32inputstream.h>` belongs to the Windows-specific GIO
+interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file
+when using it.
+
+
+ #GWin32OutputStream implements #GOutputStream for writing to a
+Windows file handle.
+
+Note that `<gio/gwin32outputstream.h>` belongs to the Windows-specific GIO
+interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file
+when using it.
+
+
+ #GWin32RegistryKey represents a single Windows Registry key.
+
+#GWin32RegistryKey is used by a number of helper functions that read
+Windows Registry. All keys are opened with read-only access, and at
+the moment there is no API for writing into registry keys or creating
+new ones.
+
+#GWin32RegistryKey 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_win32_registry_key_new() and g_win32_registry_key_get_child(), so these
+functions can return %NULL.
+
+To increase efficiency, a UTF-16 variant is available for all functions
+that deal with key or value names in the registry. Use these to perform
+deep registry queries or other operations that require querying a name
+of a key or a value and then opening it (or querying its data). The use
+of UTF-16 functions avoids the overhead of converting names to UTF-8 and
+back.
+
+All functions operate in current user's context (it is not possible to
+access registry tree of a different user).
+
+Key paths must use '\\' as a separator, '/' is not supported. Key names
+must not include '\\', because it's used as a separator. Value names
+can include '\\'.
+
+Key and value names are not case sensitive.
+
+Full key name (excluding the pre-defined ancestor's name) can't exceed
+255 UTF-16 characters, give or take. Value name can't exceed 16383 UTF-16
+characters. Tree depth is limited to 512 levels.
+
+
+ Deserializes a #GIcon previously serialized using g_icon_serialize().
+
+
+ a #GIcon, or %NULL when deserialization fails.
+
+
+
+
+ a #GVariant created with g_icon_serialize()
+
+
+
+
+
+ Generate a #GIcon instance from @str. This function can fail if
+@str is not valid - see g_icon_to_string() for discussion.
+
+If your application or library provides one or more #GIcon
+implementations you need to ensure that each #GType is registered
+with the type system prior to calling g_icon_new_for_string().
+
+
+ An object implementing the #GIcon
+ interface or %NULL if @error is set.
+
+
+
+
+ A string obtained via g_icon_to_string().
+
+
+
+
+
+ Helper function for constructing #GInitable object. This is
+similar to g_object_newv() but also initializes the object
+and returns %NULL, setting an error on failure.
+ Use g_object_new_with_properties() and
+g_initable_init() instead. See #GParameter for more information.
+
+
+ a newly allocated
+ #GObject, or %NULL on error
+
+
+
+
+ a #GType supporting #GInitable.
+
+
+
+ the number of parameters in @parameters
+
+
+
+ the parameters to use to construct the object
+
+
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Converts errno.h error codes into GIO error codes. The fallback
+value %G_IO_ERROR_FAILED is returned for error codes not currently
+handled (but note that future GLib releases may return a more
+specific value instead).
+
+As %errno is global and may be modified by intermediate function
+calls, you should save its value as soon as the call which sets it
+
+
+ #GIOErrorEnum value for the given errno.h error number.
+
+
+
+
+ Error number as defined in errno.h.
+
+
+
+
+
+ Converts #GFileError error codes into GIO error codes.
+
+
+ #GIOErrorEnum value for the given #GFileError error value.
+
+
+
+
+ a #GFileError.
+
+
+
+
+
+ Gets the GIO Error Quark.
+
+ a #GQuark.
+
+
+
+
+ Registers @type as extension for the extension point with name
+@extension_point_name.
+
+If @type has already been registered as an extension for this
+extension point, the existing #GIOExtension object is returned.
+
+
+ a #GIOExtension object for #GType
+
+
+
+
+ the name of the extension point
+
+
+
+ the #GType to register as extension
+
+
+
+ the name for the extension
+
+
+
+ the priority for the extension
+
+
+
+
+
+ Looks up an existing extension point.
+
+
+ the #GIOExtensionPoint, or %NULL if there
+ is no registered extension point with the given name.
+
+
+
+
+ the name of the extension point
+
+
+
+
+
+ Registers an extension point.
+
+
+ the new #GIOExtensionPoint. This object is
+ owned by GIO and should not be freed.
+
+
+
+
+ The name of the extension point
+
+
+
+
+
+ Loads all the modules in the specified directory.
+
+If don't require all modules to be initialized (and thus registering
+all gtypes) then you can use g_io_modules_scan_all_in_directory()
+which allows delayed/lazy loading of modules.
+
+
+ a list of #GIOModules loaded
+ from the directory,
+ All the modules are loaded into memory, if you want to
+ unload them (enabling on-demand loading) you must call
+ g_type_module_unuse() on all the modules. Free the list
+ with g_list_free().
+
+
+
+
+
+
+ pathname for a directory containing modules
+ to load.
+
+
+
+
+
+ Loads all the modules in the specified directory.
+
+If don't require all modules to be initialized (and thus registering
+all gtypes) then you can use g_io_modules_scan_all_in_directory()
+which allows delayed/lazy loading of modules.
+
+
+ a list of #GIOModules loaded
+ from the directory,
+ All the modules are loaded into memory, if you want to
+ unload them (enabling on-demand loading) you must call
+ g_type_module_unuse() on all the modules. Free the list
+ with g_list_free().
+
+
+
+
+
+
+ pathname for a directory containing modules
+ to load.
+
+
+
+ a scope to use when scanning the modules.
+
+
+
+
+
+ Scans all the modules in the specified directory, ensuring that
+any extension point implemented by a module is registered.
+
+This may not actually load and initialize all the types in each
+module, some modules may be lazily loaded and initialized when
+an extension point it implements is used with e.g.
+g_io_extension_point_get_extensions() or
+g_io_extension_point_get_extension_by_name().
+
+If you need to guarantee that all types are loaded in all the modules,
+use g_io_modules_load_all_in_directory().
+
+
+
+
+
+
+ pathname for a directory containing modules
+ to scan.
+
+
+
+
+
+ Scans all the modules in the specified directory, ensuring that
+any extension point implemented by a module is registered.
+
+This may not actually load and initialize all the types in each
+module, some modules may be lazily loaded and initialized when
+an extension point it implements is used with e.g.
+g_io_extension_point_get_extensions() or
+g_io_extension_point_get_extension_by_name().
+
+If you need to guarantee that all types are loaded in all the modules,
+use g_io_modules_load_all_in_directory().
+
+
+
+
+
+
+ pathname for a directory containing modules
+ to scan.
+
+
+
+ a scope to use when scanning the modules
+
+
+
+
+
+ Cancels all cancellable I/O jobs.
+
+A job is cancellable if a #GCancellable was passed into
+g_io_scheduler_push_job().
+ You should never call this function, since you don't
+know how other libraries in your program might be making use of
+gioscheduler.
+
+
+
+
+
+
+ Schedules the I/O job to run in another thread.
+
+@notify will be called on @user_data after @job_func has returned,
+regardless whether the job was cancelled or has run to completion.
+
+If @cancellable is not %NULL, it can be used to cancel the I/O job
+by calling g_cancellable_cancel() or by calling
+g_io_scheduler_cancel_all_jobs().
+ use #GThreadPool or g_task_run_in_thread()
+
+
+
+
+
+
+ a #GIOSchedulerJobFunc.
+
+
+
+ data to pass to @job_func
+
+
+
+ a #GDestroyNotify for @user_data, or %NULL
+
+
+
+ the [I/O priority][io-priority]
+of the request.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Creates a keyfile-backed #GSettingsBackend.
+
+The filename of the keyfile to use is given by @filename.
+
+All settings read to or written from the backend must fall under the
+path given in @root_path (which must start and end with a slash and
+not contain two consecutive slashes). @root_path may be "/".
+
+If @root_group is non-%NULL then it specifies the name of the keyfile
+group used for keys that are written directly below @root_path. For
+example, if @root_path is "/apps/example/" and @root_group is
+"toplevel", then settings the key "/apps/example/enabled" to a value
+of %TRUE will cause the following to appear in the keyfile:
+
+|[
+ [toplevel]
+ enabled=true
+]|
+
+If @root_group is %NULL then it is not permitted to store keys
+directly below the @root_path.
+
+For keys not stored directly below @root_path (ie: in a sub-path),
+the name of the subpath (with the final slash stripped) is used as
+the name of the keyfile group. To continue the example, if
+"/apps/example/profiles/default/font-size" were set to
+12 then the following would appear in the keyfile:
+
+|[
+ [profiles/default]
+ font-size=12
+]|
+
+The backend will refuse writes (and return writability as being
+%FALSE) for keys outside of @root_path and, in the event that
+@root_group is %NULL, also for keys directly under @root_path.
+Writes will also be refused if the backend detects that it has the
+inability to rewrite the keyfile (ie: the containing directory is not
+writable).
+
+There is no checking done for your key namespace clashing with the
+syntax of the key file format. For example, if you have '[' or ']'
+characters in your path names or '=' in your key names you may be in
+trouble.
+
+The backend reads default values from a keyfile called `defaults` in
+the directory specified by the #GKeyfileSettingsBackend:defaults-dir property,
+and a list of locked keys from a text file with the name `locks` in
+the same location.
+
+
+ a keyfile-backed #GSettingsBackend
+
+
+
+
+ the filename of the keyfile
+
+
+
+ the path under which all settings keys appear
+
+
+
+ the group name corresponding to
+ @root_path, or %NULL
+
+
+
+
+
+ Gets a reference to the default #GMemoryMonitor for the system.
+
+
+ a new reference to the default #GMemoryMonitor
+
+
+
+
+ Creates a memory-backed #GSettingsBackend.
+
+This backend allows changes to settings, but does not write them
+to any backing storage, so the next time you run your application,
+the memory backend will start out with the default values again.
+
+
+ a newly created #GSettingsBackend
+
+
+
+
+ Gets the default #GNetworkMonitor for the system.
+
+
+ a #GNetworkMonitor, which will be
+ a dummy object if no network monitor is available
+
+
+
+
+ Initializes the platform networking libraries (eg, on Windows, this
+calls WSAStartup()). GLib will call this itself if it is needed, so
+you only need to call it if you directly call system networking
+functions (without calling any GLib networking functions first).
+
+
+
+
+
+
+ Creates a readonly #GSettingsBackend.
+
+This backend does not allow changes to settings, so all settings
+will always have their default values.
+
+
+ a newly created #GSettingsBackend
+
+
+
+
+ Utility method for #GPollableInputStream and #GPollableOutputStream
+implementations. Creates a new #GSource that expects a callback of
+type #GPollableSourceFunc. The new source does not actually do
+anything on its own; use g_source_add_child_source() to add other
+sources to it to cause it to trigger.
+
+
+ the new #GSource.
+
+
+
+
+ the stream associated with the new source
+
+
+
+
+
+ Utility method for #GPollableInputStream and #GPollableOutputStream
+implementations. Creates a new #GSource, as with
+g_pollable_source_new(), but also attaching @child_source (with a
+dummy callback), and @cancellable, if they are non-%NULL.
+
+
+ the new #GSource.
+
+
+
+
+ the stream associated with the
+ new source
+
+
+
+ optional child source to attach
+
+
+
+ optional #GCancellable to attach
+
+
+
+
+
+ Tries to read from @stream, as with g_input_stream_read() (if
+@blocking is %TRUE) or g_pollable_input_stream_read_nonblocking()
+(if @blocking is %FALSE). This can be used to more easily share
+code between blocking and non-blocking implementations of a method.
+
+If @blocking is %FALSE, then @stream must be a
+#GPollableInputStream for which g_pollable_input_stream_can_poll()
+returns %TRUE, or else the behavior is undefined. If @blocking is
+%TRUE, then @stream does not need to be a #GPollableInputStream.
+
+
+ the number of bytes read, or -1 on error.
+
+
+
+
+ a #GInputStream
+
+
+
+ a buffer to
+ read data into
+
+
+
+
+
+ the number of bytes to read
+
+
+
+ whether to do blocking I/O
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Tries to write to @stream, as with g_output_stream_write() (if
+@blocking is %TRUE) or g_pollable_output_stream_write_nonblocking()
+(if @blocking is %FALSE). This can be used to more easily share
+code between blocking and non-blocking implementations of a method.
+
+If @blocking is %FALSE, then @stream must be a
+#GPollableOutputStream for which
+g_pollable_output_stream_can_poll() returns %TRUE or else the
+behavior is undefined. If @blocking is %TRUE, then @stream does not
+need to be a #GPollableOutputStream.
+
+
+ the number of bytes written, or -1 on error.
+
+
+
+
+ a #GOutputStream.
+
+
+
+ the buffer
+ containing the data to write.
+
+
+
+
+
+ the number of bytes to write
+
+
+
+ whether to do blocking I/O
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Tries to write @count bytes to @stream, as with
+g_output_stream_write_all(), but using g_pollable_stream_write()
+rather than g_output_stream_write().
+
+On a successful write of @count bytes, %TRUE is returned, and
+@bytes_written is set to @count.
+
+If there is an error during the operation (including
+%G_IO_ERROR_WOULD_BLOCK in the non-blocking case), %FALSE is
+returned and @error is set to indicate the error status,
+@bytes_written is updated to contain the number of bytes written
+into the stream before the error occurred.
+
+As with g_pollable_stream_write(), if @blocking is %FALSE, then
+@stream must be a #GPollableOutputStream for which
+g_pollable_output_stream_can_poll() returns %TRUE or else the
+behavior is undefined. If @blocking is %TRUE, then @stream does not
+need to be a #GPollableOutputStream.
+
+
+ %TRUE on success, %FALSE if there was an error
+
+
+
+
+ a #GOutputStream.
+
+
+
+ the buffer
+ containing the data to write.
+
+
+
+
+
+ the number of bytes to write
+
+
+
+ whether to do blocking I/O
+
+
+
+ location to store the number of bytes that was
+ written to the stream
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+ Gets a reference to the default #GPowerProfileMonitor for the system.
+
+
+ a new reference to the default #GPowerProfileMonitor
+
+
+
+
+ Find the `gio-proxy` extension point for a proxy implementation that supports
+the specified protocol.
+
+
+ return a #GProxy or NULL if protocol
+ is not supported.
+
+
+
+
+ the proxy protocol name (e.g. http, socks, etc)
+
+
+
+
+
+ Gets the default #GProxyResolver for the system.
+
+
+ the default #GProxyResolver, which
+ will be a dummy object if no proxy resolver is available
+
+
+
+
+ Gets the #GResolver Error Quark.
+
+ a #GQuark.
+
+
+
+
+ Gets the #GResource Error Quark.
+
+ a #GQuark
+
+
+
+
+ Loads a binary resource bundle and creates a #GResource representation of it, allowing
+you to query it for data.
+
+If you want to use this resource in the global resource namespace you need
+to register it with g_resources_register().
+
+If @filename is empty or the data in it is corrupt,
+%G_RESOURCE_ERROR_INTERNAL will be returned. If @filename doesn’t exist, or
+there is an error in reading it, an error from g_mapped_file_new() will be
+returned.
+
+
+ a new #GResource, or %NULL on error
+
+
+
+
+ the path of a filename to load, in the GLib filename encoding
+
+
+
+
+
+ Returns all the names of children at the specified @path in the set of
+globally registered resources.
+The return result is a %NULL terminated list of strings which should
+be released with g_strfreev().
+
+@lookup_flags controls the behaviour of the lookup.
+
+
+ an array of constant strings
+
+
+
+
+
+
+ A pathname inside the resource
+
+
+
+ A #GResourceLookupFlags
+
+
+
+
+
+ Looks for a file at the specified @path in the set of
+globally registered resources and if found returns information about it.
+
+@lookup_flags controls the behaviour of the lookup.
+
+
+ %TRUE if the file was found. %FALSE if there were errors
+
+
+
+
+ A pathname inside the resource
+
+
+
+ A #GResourceLookupFlags
+
+
+
+ a location to place the length of the contents of the file,
+ or %NULL if the length is not needed
+
+
+
+ a location to place the #GResourceFlags about the file,
+ or %NULL if the flags are not needed
+
+
+
+
+
+ Looks for a file at the specified @path in the set of
+globally registered resources and returns a #GBytes that
+lets you directly access the data in memory.
+
+The data is always followed by a zero byte, so you
+can safely use the data as a C string. However, that byte
+is not included in the size of the GBytes.
+
+For uncompressed resource files this is a pointer directly into
+the resource bundle, which is typically in some readonly data section
+in the program binary. For compressed files we allocate memory on
+the heap and automatically uncompress the data.
+
+@lookup_flags controls the behaviour of the lookup.
+
+
+ #GBytes or %NULL on error.
+ Free the returned object with g_bytes_unref()
+
+
+
+
+ A pathname inside the resource
+
+
+
+ A #GResourceLookupFlags
+
+
+
+
+
+ Looks for a file at the specified @path in the set of
+globally registered resources and returns a #GInputStream
+that lets you read the data.
+
+@lookup_flags controls the behaviour of the lookup.
+
+
+ #GInputStream or %NULL on error.
+ Free the returned object with g_object_unref()
+
+
+
+
+ A pathname inside the resource
+
+
+
+ A #GResourceLookupFlags
+
+
+
+
+
+ Registers the resource with the process-global set of resources.
+Once a resource is registered the files in it can be accessed
+with the global resource lookup functions like g_resources_lookup_data().
+
+
+
+
+
+
+ A #GResource
+
+
+
+
+
+ Unregisters the resource from the process-global set of resources.
+
+
+
+
+
+
+ A #GResource
+
+
+
+
+
+ Gets the default system schema source.
+
+This function is not required for normal uses of #GSettings but it
+may be useful to authors of plugin management systems or to those who
+want to introspect the content of schemas.
+
+If no schemas are installed, %NULL will be returned.
+
+The returned source may actually consist of multiple schema sources
+from different directories, depending on which directories were given
+in `XDG_DATA_DIRS` and `GSETTINGS_SCHEMA_DIR`. For this reason, all
+lookups performed against the default source should probably be done
+recursively.
+
+
+ the default schema source
+
+
+
+
+ Reports an error in an asynchronous function in an idle function by
+directly setting the contents of the #GAsyncResult with the given error
+information.
+ Use g_task_report_error().
+
+
+
+
+
+
+ a #GObject, or %NULL.
+
+
+
+ a #GAsyncReadyCallback.
+
+
+
+ user data passed to @callback.
+
+
+
+ a #GQuark containing the error domain (usually %G_IO_ERROR).
+
+
+
+ a specific error code.
+
+
+
+ a formatted error reporting string.
+
+
+
+ a list of variables to fill in @format.
+
+
+
+
+
+ Reports an error in an idle function. Similar to
+g_simple_async_report_error_in_idle(), but takes a #GError rather
+than building a new one.
+ Use g_task_report_error().
+
+
+
+
+
+
+ a #GObject, or %NULL
+
+
+
+ a #GAsyncReadyCallback.
+
+
+
+ user data passed to @callback.
+
+
+
+ the #GError to report
+
+
+
+
+
+ Reports an error in an idle function. Similar to
+g_simple_async_report_gerror_in_idle(), but takes over the caller's
+ownership of @error, so the caller does not have to free it any more.
+ Use g_task_report_error().
+
+
+
+
+
+
+ a #GObject, or %NULL
+
+
+
+ a #GAsyncReadyCallback.
+
+
+
+ user data passed to @callback.
+
+
+
+ the #GError to report
+
+
+
+
+
+ Sorts @targets in place according to the algorithm in RFC 2782.
+
+
+ the head of the sorted list.
+
+
+
+
+
+
+ a #GList of #GSrvTarget
+
+
+
+
+
+
+
+ Gets the default #GTlsBackend for the system.
+
+
+ a #GTlsBackend, which will be a
+ dummy object if no TLS backend is available
+
+
+
+
+ Gets the TLS channel binding error quark.
+
+ a #GQuark.
+
+
+
+
+ Creates a new #GTlsClientConnection wrapping @base_io_stream (which
+must have pollable input and output streams) which is assumed to
+communicate with the server identified by @server_identity.
+
+See the documentation for #GTlsConnection:base-io-stream for restrictions
+on when application code can run operations on the @base_io_stream after
+this function has returned.
+
+
+ the new
+#GTlsClientConnection, or %NULL on error
+
+
+
+
+ the #GIOStream to wrap
+
+
+
+ the expected identity of the server
+
+
+
+
+
+ Gets the TLS error quark.
+
+ a #GQuark.
+
+
+
+
+ Creates a new #GTlsFileDatabase which uses anchor certificate authorities
+in @anchors to verify certificate chains.
+
+The certificates in @anchors must be PEM encoded.
+
+
+ the new
+#GTlsFileDatabase, or %NULL on error
+
+
+
+
+ filename of anchor certificate authorities.
+
+
+
+
+
+ Creates a new #GTlsServerConnection wrapping @base_io_stream (which
+must have pollable input and output streams).
+
+See the documentation for #GTlsConnection:base-io-stream for restrictions
+on when application code can run operations on the @base_io_stream after
+this function has returned.
+
+
+ the new
+#GTlsServerConnection, or %NULL on error
+
+
+
+
+ the #GIOStream to wrap
+
+
+
+ the default server certificate, or %NULL
+
+
+
+
+
+ Determines if @mount_path is considered an implementation of the
+OS. This is primarily used for hiding mountable and mounted volumes
+that only are used in the OS and has little to no relevance to the
+casual user.
+
+
+ %TRUE if @mount_path is considered an implementation detail
+ of the OS.
+
+
+
+
+ a mount path, e.g. `/media/disk` or `/usr`
+
+
+
+
+
+ Determines if @device_path is considered a block device path which is only
+used in implementation of the OS. This is primarily used for hiding
+mounted volumes that are intended as APIs for programs to read, and system
+administrators at a shell; rather than something that should, for example,
+appear in a GUI. For example, the Linux `/proc` filesystem.
+
+The list of device paths considered ‘system’ ones may change over time.
+
+
+ %TRUE if @device_path is considered an implementation detail of
+ the OS.
+
+
+
+
+ a device path, e.g. `/dev/loop0` or `nfsd`
+
+
+
+
+
+ Determines if @fs_type is considered a type of file system which is only
+used in implementation of the OS. This is primarily used for hiding
+mounted volumes that are intended as APIs for programs to read, and system
+administrators at a shell; rather than something that should, for example,
+appear in a GUI. For example, the Linux `/proc` filesystem.
+
+The list of file system types considered ‘system’ ones may change over time.
+
+
+ %TRUE if @fs_type is considered an implementation detail of the OS.
+
+
+
+
+ a file system type, e.g. `procfs` or `tmpfs`
+
+
+
+
+
+ Gets a #GUnixMountEntry for a given mount path. If @time_read
+is set, it will be filled with a unix timestamp for checking
+if the mounts have changed since with g_unix_mounts_changed_since().
+
+If more mounts have the same mount path, the last matching mount
+is returned.
+
+This will return %NULL if there is no mount point at @mount_path.
+
+
+ a #GUnixMountEntry.
+
+
+
+
+ path for a possible unix mount.
+
+
+
+ guint64 to contain a timestamp.
+
+
+
+
+
+ Compares two unix mounts.
+
+
+ 1, 0 or -1 if @mount1 is greater than, equal to,
+or less than @mount2, respectively.
+
+
+
+
+ first #GUnixMountEntry to compare.
+
+
+
+ second #GUnixMountEntry to compare.
+
+
+
+
+
+ Makes a copy of @mount_entry.
+
+
+ a new #GUnixMountEntry
+
+
+
+
+ a #GUnixMountEntry.
+
+
+
+
+
+ Gets a #GUnixMountEntry for a given file path. If @time_read
+is set, it will be filled with a unix timestamp for checking
+if the mounts have changed since with g_unix_mounts_changed_since().
+
+If more mounts have the same mount path, the last matching mount
+is returned.
+
+This will return %NULL if looking up the mount entry fails, if
+@file_path doesn’t exist or there is an I/O error.
+
+
+ a #GUnixMountEntry.
+
+
+
+
+ file path on some unix mount.
+
+
+
+ guint64 to contain a timestamp.
+
+
+
+
+
+ Frees a unix mount.
+
+
+
+
+
+
+ a #GUnixMountEntry.
+
+
+
+
+
+ Gets the device path for a unix mount.
+
+
+ a string containing the device path.
+
+
+
+
+ a #GUnixMount.
+
+
+
+
+
+ Gets the filesystem type for the unix mount.
+
+
+ a string containing the file system type.
+
+
+
+
+ a #GUnixMount.
+
+
+
+
+
+ Gets the mount path for a unix mount.
+
+
+ the mount path for @mount_entry.
+
+
+
+
+ input #GUnixMountEntry to get the mount path for.
+
+
+
+
+
+ Gets a comma-separated list of mount options for the unix mount. For example,
+`rw,relatime,seclabel,data=ordered`.
+
+This is similar to g_unix_mount_point_get_options(), but it takes
+a #GUnixMountEntry as an argument.
+
+
+ a string containing the options, or %NULL if not
+available.
+
+
+
+
+ a #GUnixMountEntry.
+
+
+
+
+
+ Gets the root of the mount within the filesystem. This is useful e.g. for
+mounts created by bind operation, or btrfs subvolumes.
+
+For example, the root path is equal to "/" for mount created by
+"mount /dev/sda1 /mnt/foo" and "/bar" for
+"mount --bind /mnt/foo/bar /mnt/bar".
+
+
+ a string containing the root, or %NULL if not supported.
+
+
+
+
+ a #GUnixMountEntry.
+
+
+
+
+
+ Guesses whether a Unix mount can be ejected.
+
+
+ %TRUE if @mount_entry is deemed to be ejectable.
+
+
+
+
+ a #GUnixMountEntry
+
+
+
+
+
+ Guesses the icon of a Unix mount.
+
+
+ a #GIcon
+
+
+
+
+ a #GUnixMountEntry
+
+
+
+
+
+ Guesses the name of a Unix mount.
+The result is a translated string.
+
+
+ A newly allocated string that must
+ be freed with g_free()
+
+
+
+
+ a #GUnixMountEntry
+
+
+
+
+
+ Guesses whether a Unix mount should be displayed in the UI.
+
+
+ %TRUE if @mount_entry is deemed to be displayable.
+
+
+
+
+ a #GUnixMountEntry
+
+
+
+
+
+ Guesses the symbolic icon of a Unix mount.
+
+
+ a #GIcon
+
+
+
+
+ a #GUnixMountEntry
+
+
+
+
+
+ Checks if a unix mount is mounted read only.
+
+
+ %TRUE if @mount_entry is read only.
+
+
+
+
+ a #GUnixMount.
+
+
+
+
+
+ Checks if a Unix mount is a system mount. This is the Boolean OR of
+g_unix_is_system_fs_type(), g_unix_is_system_device_path() and
+g_unix_is_mount_path_system_internal() on @mount_entry’s properties.
+
+The definition of what a ‘system’ mount entry is may change over time as new
+file system types and device paths are ignored.
+
+
+ %TRUE if the unix mount is for a system path.
+
+
+
+
+ a #GUnixMount.
+
+
+
+
+
+ Gets a #GUnixMountPoint for a given mount path. If @time_read is set, it
+will be filled with a unix timestamp for checking if the mount points have
+changed since with g_unix_mount_points_changed_since().
+
+If more mount points have the same mount path, the last matching mount point
+is returned.
+
+
+ a #GUnixMountPoint, or %NULL if no match
+is found.
+
+
+
+
+ path for a possible unix mount point.
+
+
+
+ guint64 to contain a timestamp.
+
+
+
+
+
+ Checks if the unix mount points have changed since a given unix time.
+
+
+ %TRUE if the mount points have changed since @time.
+
+
+
+
+ guint64 to contain a timestamp.
+
+
+
+
+
+ Gets a #GList of #GUnixMountPoint containing the unix mount points.
+If @time_read is set, it will be filled with the mount timestamp,
+allowing for checking if the mounts have changed with
+g_unix_mount_points_changed_since().
+
+
+
+ a #GList of the UNIX mountpoints.
+
+
+
+
+
+
+ guint64 to contain a timestamp.
+
+
+
+
+
+ Checks if the unix mounts have changed since a given unix time.
+
+
+ %TRUE if the mounts have changed since @time.
+
+
+
+
+ guint64 to contain a timestamp.
+
+
+
+
+
+ Gets a #GList of #GUnixMountEntry containing the unix mounts.
+If @time_read is set, it will be filled with the mount
+timestamp, allowing for checking if the mounts have changed
+with g_unix_mounts_changed_since().
+
+
+
+ a #GList of the UNIX mounts.
+
+
+
+
+
+
+ guint64 to contain a timestamp, or %NULL
+
+
+
+
+
+
diff --git a/docs/reference/gio/gio.toml.in b/docs/reference/gio/gio.toml.in
new file mode 100644
index 000000000..87489bbf7
--- /dev/null
+++ b/docs/reference/gio/gio.toml.in
@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: LGPL-2.1-or-later
+# Copyright 2023 Matthias Clasen
+# Copyright 2023 Philip Withnall
+
+[library]
+name = "Gio"
+version = "@VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/glib/"
+repository_url = "https://gitlab.gnome.org/GNOME/glib.git"
+website_url = "https://www.gtk.org"
+docs_urls = "https://docs.gtk.org/gio/"
+authors = "GLib Development Team"
+license = "LGPL-2.1-or-later"
+description = "Gio is a library providing useful classes for general purpose I/O, networking, IPC, settings, and other high level application functionality"
+dependencies = [ "GLib-2.0", "GModule-2.0", "GObject-2.0" ]
+devhelp = true
+search_index = true
+
+ [dependencies."GLib-2.0"]
+ name = "GLib"
+ description = "The base utility library"
+ docs_url = "https://docs.gtk.org/glib/"
+
+ [dependencies."GModule-2.0"]
+ name = "GModule"
+ description = "Portable API for dynamically loading modules"
+ docs_url = "https://docs.gtk.org/gmodule/"
+
+ [dependencies."GObject-2.0"]
+ name = "GObject"
+ description = "The base type system library"
+ docs_url = "https://docs.gtk.org/gobject/"
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[extra]
+urlmap_file = "urlmap.js"
+# The same order will be used when generating the index
+content_files = [
+]
+content_images = [
+ "menu-example.png",
+ "menu-model.png",
+]
diff --git a/docs/reference/gio/meson.build b/docs/reference/gio/meson.build
index 38696a1c6..0a421c069 100644
--- a/docs/reference/gio/meson.build
+++ b/docs/reference/gio/meson.build
@@ -234,3 +234,28 @@ if get_option('man')
install_dir: man1_dir)
endforeach
endif
+
+# gi-docgen version
+expand_content_files = [
+]
+
+gio_gir = meson.current_source_dir() / 'Gio-2.0.gir'
+gio_toml = configure_file(input: 'gio.toml.in', output: 'gio.toml', configuration: toml_conf)
+
+custom_target('gio-docs',
+ input: [ gio_toml, gio_gir ],
+ output: 'gio',
+ command: [
+ gidocgen,
+ 'generate',
+ gidocgen_common_args,
+ '--config=@INPUT0@',
+ '--output-dir=@OUTPUT@',
+ '--content-dir=@0@'.format(meson.current_source_dir()),
+ '--add-include-path=@0@'.format(meson.current_source_dir() / '../glib'),
+ '--add-include-path=@0@'.format(meson.current_source_dir() / '../gobject'),
+ '@INPUT1@',
+ ],
+ build_by_default: true,
+ depend_files: expand_content_files,
+)
diff --git a/docs/reference/gio/urlmap.js b/docs/reference/gio/urlmap.js
new file mode 100644
index 000000000..b1f0962b0
--- /dev/null
+++ b/docs/reference/gio/urlmap.js
@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: LGPL-2.1-or-later
+// SPDX-FileCopyrightText: 2023 Matthias Clasen
+var baseURLs = [
+ [ 'GLib', 'https://docs.gtk.org/glib/' ],
+ [ 'GModule', 'https://docs.gtk.org/gmodule/' ],
+ [ 'GObject', 'https://docs.gtk.org/gobject/' ],
+ [ 'Gio', 'https://docs.gtk.org/gio/' ],
+ [ 'Gtk', 'https://docs.gtk.org/gtk4/' ],
+];
diff --git a/docs/reference/glib/GLib-2.0.gir b/docs/reference/glib/GLib-2.0.gir
new file mode 100644
index 000000000..d0d197d59
--- /dev/null
+++ b/docs/reference/glib/GLib-2.0.gir
@@ -0,0 +1,86561 @@
+
+
+
+
+
+
+
+ Integer representing a day of the month; between 1 and 31.
+
+The %G_DATE_BAD_DAY value represents an invalid day of the month.
+
+
+
+
+ Integer type representing a year.
+
+The %G_DATE_BAD_YEAR value is the invalid value. The year
+must be 1 or higher; negative ([BCE](https://en.wikipedia.org/wiki/Common_Era))
+years are not allowed.
+
+The year is represented with four digits.
+
+
+
+
+ Opaque type. See g_main_context_pusher_new() for details.
+
+
+
+
+ Opaque type. See g_mutex_locker_new() for details.
+
+
+
+
+ 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).
+
+GPid is used in GLib only for descendant processes spawned with
+the g_spawn functions.
+
+
+
+
+ A GQuark is a non-zero integer which uniquely identifies a
+particular string. A GQuark value of zero is associated to %NULL.
+
+
+
+
+ Opaque type. See g_rw_lock_reader_locker_new() for details.
+
+
+
+
+ Opaque type. See g_rw_lock_writer_locker_new() for details.
+
+
+
+
+ Opaque type. See g_rec_mutex_locker_new() for details.
+
+
+
+
+ A typedef for a reference-counted string. A pointer to a #GRefString can be
+treated like a standard `char*` array by all code, but can additionally have
+`g_ref_string_*()` methods called on it. `g_ref_string_*()` methods cannot be
+called on `char*` arrays not allocated using g_ref_string_new().
+
+If using #GRefString with autocleanups, g_autoptr() must be used rather than
+g_autofree(), so that the reference counting metadata is also freed.
+
+
+
+
+ A typedef alias for gchar**. This is mostly useful when used together with
+g_auto().
+
+
+
+
+ Simply a replacement for `time_t`. It has been deprecated
+since it is not equivalent to `time_t` on 64-bit platforms
+with a 64-bit `time_t`.
+
+Unrelated to #GTimer.
+
+Note that #GTime is defined to always be a 32-bit integer,
+unlike `time_t` which may be 64-bit on some systems. Therefore,
+#GTime will overflow in the year 2038, and you cannot use the
+address of a #GTime variable as argument to the UNIX time()
+function.
+
+Instead, do the following:
+
+|[<!-- language="C" -->
+time_t ttime;
+GTime gtime;
+
+time (&ttime);
+gtime = (GTime)ttime;
+]|
+ This is not [Y2038-safe](https://en.wikipedia.org/wiki/Year_2038_problem).
+ Use #GDateTime or #time_t instead.
+
+
+
+
+ A value representing an interval of time, in microseconds.
+
+
+
+
+
+
+
+
+ Return the minimal alignment required by the platform ABI for values of the given
+type. The address of a variable or struct member of the given type must always be
+a multiple of this alignment. For example, most platforms require int variables
+to be aligned at a 4-byte boundary, so `G_ALIGNOF (int)` is 4 on most platforms.
+
+Note this is not necessarily the same as the value returned by GCC’s
+`__alignof__` operator, which returns the preferred alignment for a type.
+The preferred alignment may be a stricter alignment than the minimal
+alignment.
+
+
+
+ a type-name
+
+
+
+
+
+
+
+
+ Evaluates to a truth value if the absolute difference between @a and @b is
+smaller than @epsilon, and to a false value otherwise.
+
+For example,
+- `G_APPROX_VALUE (5, 6, 2)` evaluates to true
+- `G_APPROX_VALUE (3.14, 3.15, 0.001)` evaluates to false
+- `G_APPROX_VALUE (n, 0.f, FLT_EPSILON)` evaluates to true if `n` is within
+ the single precision floating point epsilon from zero
+
+
+
+ a numeric value
+
+
+ a numeric value
+
+
+ a numeric value that expresses the tolerance between @a and @b
+
+
+
+
+ A good size for a buffer to be passed into g_ascii_dtostr().
+It is guaranteed to be enough for all output of that function
+on systems with 64bit IEEE-compatible doubles.
+
+The typical usage would be something like:
+|[<!-- language="C" -->
+ char buf[G_ASCII_DTOSTR_BUF_SIZE];
+
+ fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value));
+]|
+
+
+
+
+
+
+
+
+
+
+
+ Contains the public fields of a GArray.
+
+
+ a pointer to the element data. The data may be moved as
+ elements are added to the #GArray.
+
+
+
+ the number of elements in the #GArray not including the
+ possible terminating zero element.
+
+
+
+ Adds @len elements onto the end of the array.
+
+
+ the #GArray
+
+
+
+
+
+
+ a #GArray
+
+
+
+
+
+ a pointer to the elements to append to the end of the array
+
+
+
+ the number of elements to append
+
+
+
+
+
+ Checks whether @target exists in @array by performing a binary
+search based on the given comparison function @compare_func which
+get pointers to items as arguments. If the element is found, %TRUE
+is returned and the element’s index is returned in @out_match_index
+(if non-%NULL). Otherwise, %FALSE is returned and @out_match_index
+is undefined. If @target exists multiple times in @array, the index
+of the first instance is returned. This search is using a binary
+search, so the @array must absolutely be sorted to return a correct
+result (if not, the function may produce false-negative).
+
+This example defines a comparison function and search an element in a #GArray:
+|[<!-- language="C" -->
+static gint
+cmpint (gconstpointer a, gconstpointer b)
+{
+ const gint *_a = a;
+ const gint *_b = b;
+
+ return *_a - *_b;
+}
+...
+gint i = 424242;
+guint matched_index;
+gboolean result = g_array_binary_search (garray, &i, cmpint, &matched_index);
+...
+]|
+
+
+ %TRUE if @target is one of the elements of @array, %FALSE otherwise.
+
+
+
+
+ a #GArray.
+
+
+
+
+
+ a pointer to the item to look up.
+
+
+
+ A #GCompareFunc used to locate @target.
+
+
+
+ return location
+ for the index of the element, if found.
+
+
+
+
+
+ Create a shallow copy of a #GArray. If the array elements consist of
+pointers to data, the pointers are copied but the actual data is not.
+
+
+ A copy of @array.
+
+
+
+
+
+
+ A #GArray.
+
+
+
+
+
+
+
+ Frees the memory allocated for the #GArray. If @free_segment is
+%TRUE it frees the memory block holding the elements as well. Pass
+%FALSE if you want to free the #GArray wrapper but preserve the
+underlying array for use elsewhere. If the reference count of
+@array is greater than one, the #GArray wrapper is preserved but
+the size of @array will be set to zero.
+
+If array contents point to dynamically-allocated memory, they should
+be freed separately if @free_seg is %TRUE and no @clear_func
+function has been set for @array.
+
+This function is not thread-safe. If using a #GArray from multiple
+threads, use only the atomic g_array_ref() and g_array_unref()
+functions.
+
+
+ the element data if @free_segment is %FALSE, otherwise
+ %NULL. The element data should be freed using g_free().
+
+
+
+
+ a #GArray
+
+
+
+
+
+ if %TRUE the actual element data is freed as well
+
+
+
+
+
+ Gets the size of the elements in @array.
+
+
+ Size of each element, in bytes
+
+
+
+
+ A #GArray
+
+
+
+
+
+
+
+ Inserts @len elements into a #GArray at the given index.
+
+If @index_ is greater than the array’s current length, the array is expanded.
+The elements between the old end of the array and the newly inserted elements
+will be initialised to zero if the array was configured to clear elements;
+otherwise their values will be undefined.
+
+If @index_ is less than the array’s current length, new entries will be
+inserted into the array, and the existing entries above @index_ will be moved
+upwards.
+
+@data may be %NULL if (and only if) @len is zero. If @len is zero, this
+function is a no-op.
+
+
+ the #GArray
+
+
+
+
+
+
+ a #GArray
+
+
+
+
+
+ the index to place the elements at
+
+
+
+ a pointer to the elements to insert
+
+
+
+ the number of elements to insert
+
+
+
+
+
+ Creates a new #GArray with a reference count of 1.
+
+
+ the new #GArray
+
+
+
+
+
+
+ %TRUE if the array should have an extra element at
+ the end which is set to 0
+
+
+
+ %TRUE if #GArray elements should be automatically cleared
+ to 0 when they are allocated
+
+
+
+ the size of each element in bytes
+
+
+
+
+
+ Creates a new #GArray with @data as array data, @len as length and a
+reference count of 1.
+
+This avoids having to copy the data manually, when it can just be
+inherited. @data will eventually be freed using g_free(), so must
+have been allocated with a suitable allocator.
+
+In case the elements need to be cleared when the array is freed, use
+g_array_set_clear_func() to set a #GDestroyNotify function to perform
+such task.
+
+Do not use it if @len or @element_size are greater than %G_MAXUINT.
+#GArray stores the length of its data in #guint, which may be shorter
+than #gsize.
+
+
+ A new #GArray
+
+
+
+
+
+
+ an array of
+ elements of @element_size, or %NULL for an empty array
+
+
+
+
+
+ the number of elements in @data
+
+
+
+ %TRUE if #GArray elements should be automatically cleared
+ to 0 when they are allocated
+
+
+
+ the size of each element in bytes
+
+
+
+
+
+ Creates a new #GArray with @data as array data, computing the length of it
+and setting the reference count to 1.
+
+This avoids having to copy the data manually, when it can just be
+inherited. @data will eventually be freed using g_free(), so must
+have been allocated with a suitable allocator.
+
+The length is calculated by iterating through @data until the first %NULL
+element is found.
+
+In case the elements need to be cleared when the array is freed, use
+g_array_set_clear_func() to set a #GDestroyNotify function to perform
+such task.
+
+Do not use it if @data length or @element_size are greater than %G_MAXUINT.
+#GArray stores the length of its data in #guint, which may be shorter
+than #gsize.
+
+
+ A new #GArray
+
+
+
+
+
+
+ an array of elements of @element_size
+
+
+
+
+
+ %TRUE if #GArray elements should be automatically cleared
+ to 0 when they are allocated
+
+
+
+ the size of each element in bytes
+
+
+
+
+
+ Adds @len elements onto the start of the array.
+
+@data may be %NULL if (and only if) @len is zero. If @len is zero, this
+function is a no-op.
+
+This operation is slower than g_array_append_vals() since the
+existing elements in the array have to be moved to make space for
+the new elements.
+
+
+ the #GArray
+
+
+
+
+
+
+ a #GArray
+
+
+
+
+
+ a pointer to the elements to prepend to the start of the array
+
+
+
+ the number of elements to prepend, which may be zero
+
+
+
+
+
+ Atomically increments the reference count of @array by one.
+This function is thread-safe and may be called from any thread.
+
+
+ The passed in #GArray
+
+
+
+
+
+
+ A #GArray
+
+
+
+
+
+
+
+ Removes the element at the given index from a #GArray. The following
+elements are moved down one place.
+
+
+ the #GArray
+
+
+
+
+
+
+ a #GArray
+
+
+
+
+
+ the index of the element to remove
+
+
+
+
+
+ Removes the element at the given index from a #GArray. The last
+element in the array is used to fill in the space, so this function
+does not preserve the order of the #GArray. But it is faster than
+g_array_remove_index().
+
+
+ the #GArray
+
+
+
+
+
+
+ a @GArray
+
+
+
+
+
+ the index of the element to remove
+
+
+
+
+
+ Removes the given number of elements starting at the given index
+from a #GArray. The following elements are moved to close the gap.
+
+
+ the #GArray
+
+
+
+
+
+
+ a @GArray
+
+
+
+
+
+ the index of the first element to remove
+
+
+
+ the number of elements to remove
+
+
+
+
+
+ Sets a function to clear an element of @array.
+
+The @clear_func will be called when an element in the array
+data segment is removed and when the array is freed and data
+segment is deallocated as well. @clear_func will be passed a
+pointer to the element to clear, rather than the element itself.
+
+Note that in contrast with other uses of #GDestroyNotify
+functions, @clear_func is expected to clear the contents of
+the array element it is given, but not free the element itself.
+
+|[<!-- language="C" -->
+typedef struct
+{
+ gchar *str;
+ GObject *obj;
+} ArrayElement;
+
+static void
+array_element_clear (ArrayElement *element)
+{
+ g_clear_pointer (&element->str, g_free);
+ g_clear_object (&element->obj);
+}
+
+// main code
+GArray *garray = g_array_new (FALSE, FALSE, sizeof (ArrayElement));
+g_array_set_clear_func (garray, (GDestroyNotify) array_element_clear);
+// assign data to the structure
+g_array_free (garray, TRUE);
+]|
+
+
+
+
+
+
+ A #GArray
+
+
+
+
+
+ a function to clear an element of @array
+
+
+
+
+
+ Sets the size of the array, expanding it if necessary. If the array
+was created with @clear_ set to %TRUE, the new elements are set to 0.
+
+
+ the #GArray
+
+
+
+
+
+
+ a #GArray
+
+
+
+
+
+ the new size of the #GArray
+
+
+
+
+
+ Creates a new #GArray with @reserved_size elements preallocated and
+a reference count of 1. This avoids frequent reallocation, if you
+are going to add many elements to the array. Note however that the
+size of the array is still 0.
+
+
+ the new #GArray
+
+
+
+
+
+
+ %TRUE if the array should have an extra element at
+ the end with all bits cleared
+
+
+
+ %TRUE if all bits in the array should be cleared to 0 on
+ allocation
+
+
+
+ size of each element in the array
+
+
+
+ number of elements preallocated
+
+
+
+
+
+ Sorts a #GArray using @compare_func which should be a qsort()-style
+comparison function (returns less than zero for first arg is less
+than second arg, zero for equal, greater zero if first arg is
+greater than second arg).
+
+This is guaranteed to be a stable sort since version 2.32.
+
+
+
+
+
+
+ a #GArray
+
+
+
+
+
+ comparison function
+
+
+
+
+
+ Like g_array_sort(), but the comparison function receives an extra
+user data argument.
+
+This is guaranteed to be a stable sort since version 2.32.
+
+There used to be a comment here about making the sort stable by
+using the addresses of the elements in the comparison function.
+This did not actually work, so any such code should be removed.
+
+
+
+
+
+
+ a #GArray
+
+
+
+
+
+ comparison function
+
+
+
+ data to pass to @compare_func
+
+
+
+
+
+ Frees the data in the array and resets the size to zero, while
+the underlying array is preserved for use elsewhere and returned
+to the caller.
+
+If the array was created with the @zero_terminate property
+set to %TRUE, the returned data is zero terminated too.
+
+If array elements contain dynamically-allocated memory,
+the array elements should also be freed by the caller.
+
+A short example of use:
+|[<!-- language="C" -->
+...
+gpointer data;
+gsize data_len;
+data = g_array_steal (some_array, &data_len);
+...
+]|
+
+
+ the element data, which should be
+ freed using g_free().
+
+
+
+
+ a #GArray.
+
+
+
+
+
+ pointer to retrieve the number of
+ elements of the original array
+
+
+
+
+
+ Atomically decrements the reference count of @array by one. If the
+reference count drops to 0, all memory allocated by the array is
+released. This function is thread-safe and may be called from any
+thread.
+
+
+
+
+
+
+ A #GArray
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ An opaque data structure which represents an asynchronous queue.
+
+It should only be accessed through the `g_async_queue_*` functions.
+
+
+ Returns the length of the queue.
+
+Actually this function returns the number of data items in
+the queue minus the number of waiting threads, so a negative
+value means waiting threads, and a positive value means available
+entries in the @queue. A return value of 0 could mean n entries
+in the queue and n threads waiting. This can happen due to locking
+of the queue or due to scheduling.
+
+
+ the length of the @queue
+
+
+
+
+ a #GAsyncQueue.
+
+
+
+
+
+ Returns the length of the queue.
+
+Actually this function returns the number of data items in
+the queue minus the number of waiting threads, so a negative
+value means waiting threads, and a positive value means available
+entries in the @queue. A return value of 0 could mean n entries
+in the queue and n threads waiting. This can happen due to locking
+of the queue or due to scheduling.
+
+This function must be called while holding the @queue's lock.
+
+
+ the length of the @queue.
+
+
+
+
+ a #GAsyncQueue
+
+
+
+
+
+ Acquires the @queue's lock. If another thread is already
+holding the lock, this call will block until the lock
+becomes available.
+
+Call g_async_queue_unlock() to drop the lock again.
+
+While holding the lock, you can only call the
+g_async_queue_*_unlocked() functions on @queue. Otherwise,
+deadlock may occur.
+
+
+
+
+
+
+ a #GAsyncQueue
+
+
+
+
+
+ Pops data from the @queue. If @queue is empty, this function
+blocks until data becomes available.
+
+
+ data from the queue
+
+
+
+
+ a #GAsyncQueue
+
+
+
+
+
+ Pops data from the @queue. If @queue is empty, this function
+blocks until data becomes available.
+
+This function must be called while holding the @queue's lock.
+
+
+ data from the queue.
+
+
+
+
+ a #GAsyncQueue
+
+
+
+
+
+ Pushes the @data into the @queue.
+
+The @data parameter must not be %NULL.
+
+
+
+
+
+
+ a #GAsyncQueue
+
+
+
+ data to push onto the @queue
+
+
+
+
+
+ Pushes the @item into the @queue. @item must not be %NULL.
+In contrast to g_async_queue_push(), this function
+pushes the new item ahead of the items already in the queue,
+so that it will be the next one to be popped off the queue.
+
+
+
+
+
+
+ a #GAsyncQueue
+
+
+
+ data to push into the @queue
+
+
+
+
+
+ Pushes the @item into the @queue. @item must not be %NULL.
+In contrast to g_async_queue_push_unlocked(), this function
+pushes the new item ahead of the items already in the queue,
+so that it will be the next one to be popped off the queue.
+
+This function must be called while holding the @queue's lock.
+
+
+
+
+
+
+ a #GAsyncQueue
+
+
+
+ data to push into the @queue
+
+
+
+
+
+ Inserts @data into @queue using @func to determine the new
+position.
+
+This function requires that the @queue is sorted before pushing on
+new elements, see g_async_queue_sort().
+
+This function will lock @queue before it sorts the queue and unlock
+it when it is finished.
+
+For an example of @func see g_async_queue_sort().
+
+
+
+
+
+
+ a #GAsyncQueue
+
+
+
+ the @data to push into the @queue
+
+
+
+ the #GCompareDataFunc is used to sort @queue
+
+
+
+ user data passed to @func.
+
+
+
+
+
+ Inserts @data into @queue using @func to determine the new
+position.
+
+The sort function @func is passed two elements of the @queue.
+It should return 0 if they are equal, a negative value if the
+first element should be higher in the @queue or a positive value
+if the first element should be lower in the @queue than the second
+element.
+
+This function requires that the @queue is sorted before pushing on
+new elements, see g_async_queue_sort().
+
+This function must be called while holding the @queue's lock.
+
+For an example of @func see g_async_queue_sort().
+
+
+
+
+
+
+ a #GAsyncQueue
+
+
+
+ the data to push into the @queue
+
+
+
+ the #GCompareDataFunc is used to sort @queue
+
+
+
+ user data passed to @func.
+
+
+
+
+
+ Pushes the @data into the @queue.
+
+The @data parameter must not be %NULL.
+
+This function must be called while holding the @queue's lock.
+
+
+
+
+
+
+ a #GAsyncQueue
+
+
+
+ data to push onto the @queue
+
+
+
+
+
+ Increases the reference count of the asynchronous @queue by 1.
+You do not need to hold the lock to call this function.
+
+
+ the @queue that was passed in (since 2.6)
+
+
+
+
+ a #GAsyncQueue
+
+
+
+
+
+ Increases the reference count of the asynchronous @queue by 1.
+ Reference counting is done atomically.
+so g_async_queue_ref() can be used regardless of the @queue's
+lock.
+
+
+
+
+
+
+ a #GAsyncQueue
+
+
+
+
+
+ Remove an item from the queue.
+
+
+ %TRUE if the item was removed
+
+
+
+
+ a #GAsyncQueue
+
+
+
+ the data to remove from the @queue
+
+
+
+
+
+ Remove an item from the queue.
+
+This function must be called while holding the @queue's lock.
+
+
+ %TRUE if the item was removed
+
+
+
+
+ a #GAsyncQueue
+
+
+
+ the data to remove from the @queue
+
+
+
+
+
+ Sorts @queue using @func.
+
+The sort function @func is passed two elements of the @queue.
+It should return 0 if they are equal, a negative value if the
+first element should be higher in the @queue or a positive value
+if the first element should be lower in the @queue than the second
+element.
+
+This function will lock @queue before it sorts the queue and unlock
+it when it is finished.
+
+If you were sorting a list of priority numbers to make sure the
+lowest priority would be at the top of the queue, you could use:
+|[<!-- language="C" -->
+ gint32 id1;
+ gint32 id2;
+
+ id1 = GPOINTER_TO_INT (element1);
+ id2 = GPOINTER_TO_INT (element2);
+
+ return (id1 > id2 ? +1 : id1 == id2 ? 0 : -1);
+]|
+
+
+
+
+
+
+ a #GAsyncQueue
+
+
+
+ the #GCompareDataFunc is used to sort @queue
+
+
+
+ user data passed to @func
+
+
+
+
+
+ Sorts @queue using @func.
+
+The sort function @func is passed two elements of the @queue.
+It should return 0 if they are equal, a negative value if the
+first element should be higher in the @queue or a positive value
+if the first element should be lower in the @queue than the second
+element.
+
+This function must be called while holding the @queue's lock.
+
+
+
+
+
+
+ a #GAsyncQueue
+
+
+
+ the #GCompareDataFunc is used to sort @queue
+
+
+
+ user data passed to @func
+
+
+
+
+
+ Pops data from the @queue. If the queue is empty, blocks until
+@end_time or until data becomes available.
+
+If no data is received before @end_time, %NULL is returned.
+
+To easily calculate @end_time, a combination of g_get_real_time()
+and g_time_val_add() can be used.
+ use g_async_queue_timeout_pop().
+
+
+ data from the queue or %NULL, when no data is
+ received before @end_time.
+
+
+
+
+ a #GAsyncQueue
+
+
+
+ a #GTimeVal, determining the final time
+
+
+
+
+
+ Pops data from the @queue. If the queue is empty, blocks until
+@end_time or until data becomes available.
+
+If no data is received before @end_time, %NULL is returned.
+
+To easily calculate @end_time, a combination of g_get_real_time()
+and g_time_val_add() can be used.
+
+This function must be called while holding the @queue's lock.
+ use g_async_queue_timeout_pop_unlocked().
+
+
+ data from the queue or %NULL, when no data is
+ received before @end_time.
+
+
+
+
+ a #GAsyncQueue
+
+
+
+ a #GTimeVal, determining the final time
+
+
+
+
+
+ Pops data from the @queue. If the queue is empty, blocks for
+@timeout microseconds, or until data becomes available.
+
+If no data is received before the timeout, %NULL is returned.
+
+
+ data from the queue or %NULL, when no data is
+ received before the timeout.
+
+
+
+
+ a #GAsyncQueue
+
+
+
+ the number of microseconds to wait
+
+
+
+
+
+ Pops data from the @queue. If the queue is empty, blocks for
+@timeout microseconds, or until data becomes available.
+
+If no data is received before the timeout, %NULL is returned.
+
+This function must be called while holding the @queue's lock.
+
+
+ data from the queue or %NULL, when no data is
+ received before the timeout.
+
+
+
+
+ a #GAsyncQueue
+
+
+
+ the number of microseconds to wait
+
+
+
+
+
+ Tries to pop data from the @queue. If no data is available,
+%NULL is returned.
+
+
+ data from the queue or %NULL, when no data is
+ available immediately.
+
+
+
+
+ a #GAsyncQueue
+
+
+
+
+
+ Tries to pop data from the @queue. If no data is available,
+%NULL is returned.
+
+This function must be called while holding the @queue's lock.
+
+
+ data from the queue or %NULL, when no data is
+ available immediately.
+
+
+
+
+ a #GAsyncQueue
+
+
+
+
+
+ Releases the queue's lock.
+
+Calling this function when you have not acquired
+the with g_async_queue_lock() leads to undefined
+behaviour.
+
+
+
+
+
+
+ a #GAsyncQueue
+
+
+
+
+
+ Decreases the reference count of the asynchronous @queue by 1.
+
+If the reference count went to 0, the @queue will be destroyed
+and the memory allocated will be freed. So you are not allowed
+to use the @queue afterwards, as it might have disappeared.
+You do not need to hold the lock to call this function.
+
+
+
+
+
+
+ a #GAsyncQueue.
+
+
+
+
+
+ Decreases the reference count of the asynchronous @queue by 1
+and releases the lock. This function must be called while holding
+the @queue's lock. If the reference count went to 0, the @queue
+will be destroyed and the memory allocated will be freed.
+ Reference counting is done atomically.
+so g_async_queue_unref() can be used regardless of the @queue's
+lock.
+
+
+
+
+
+
+ a #GAsyncQueue
+
+
+
+
+
+ Creates a new asynchronous queue.
+
+
+ a new #GAsyncQueue. Free with g_async_queue_unref()
+
+
+
+
+ Creates a new asynchronous queue and sets up a destroy notify
+function that is used to free any remaining queue items when
+the queue is destroyed after the final unref.
+
+
+ a new #GAsyncQueue. Free with g_async_queue_unref()
+
+
+
+
+ function to free queue elements
+
+
+
+
+
+
+ Specifies one of the possible types of byte order.
+See %G_BYTE_ORDER.
+
+
+
+
+ Inserts a breakpoint instruction into the code.
+
+On architectures which support it, this is implemented as a soft interrupt
+and on other architectures it raises a `SIGTRAP` signal.
+
+`SIGTRAP` is used rather than abort() to allow breakpoints to be skipped past
+in a debugger if they are not the desired target of debugging.
+
+
+
+ An opaque data structure representing a set of bookmarks.
+
+
+ Creates a new empty #GBookmarkFile object.
+
+Use g_bookmark_file_load_from_file(), g_bookmark_file_load_from_data()
+or g_bookmark_file_load_from_data_dirs() to read an existing bookmark
+file.
+
+
+ an empty #GBookmarkFile
+
+
+
+
+ Adds the application with @name and @exec to the list of
+applications that have registered a bookmark for @uri into
+@bookmark.
+
+Every bookmark inside a #GBookmarkFile must have at least an
+application registered. Each application must provide a name, a
+command line useful for launching the bookmark, the number of times
+the bookmark has been registered by the application and the last
+time the application registered this bookmark.
+
+If @name is %NULL, the name of the application will be the
+same returned by g_get_application_name(); if @exec is %NULL, the
+command line will be a composition of the program name as
+returned by g_get_prgname() and the "\%u" modifier, which will be
+expanded to the bookmark's URI.
+
+This function will automatically take care of updating the
+registrations count and timestamping in case an application
+with the same @name had already registered a bookmark for
+@uri inside @bookmark.
+
+If no bookmark for @uri is found, one is created.
+
+
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+ the name of the application registering the bookmark
+ or %NULL
+
+
+
+ command line to be used to launch the bookmark or %NULL
+
+
+
+
+
+ Adds @group to the list of groups to which the bookmark for @uri
+belongs to.
+
+If no bookmark for @uri is found then it is created.
+
+
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+ the group name to be added
+
+
+
+
+
+ Deeply copies a @bookmark #GBookmarkFile object to a new one.
+
+
+ the copy of @bookmark. Use
+ g_bookmark_free() when finished using it.
+
+
+
+
+ A #GBookmarkFile
+
+
+
+
+
+ Frees a #GBookmarkFile.
+
+
+
+
+
+
+ a #GBookmarkFile
+
+
+
+
+
+ Gets the time the bookmark for @uri was added to @bookmark
+
+In the event the URI cannot be found, -1 is returned and
+@error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
+ Use g_bookmark_file_get_added_date_time() instead, as
+ `time_t` is deprecated due to the year 2038 problem.
+
+
+ a timestamp
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+
+
+ Gets the time the bookmark for @uri was added to @bookmark
+
+In the event the URI cannot be found, %NULL is returned and
+@error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
+
+
+ a #GDateTime
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+
+
+ Gets the registration information of @app_name for the bookmark for
+@uri. See g_bookmark_file_set_application_info() for more information about
+the returned data.
+
+The string returned in @app_exec must be freed.
+
+In the event the URI cannot be found, %FALSE is returned and
+@error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the
+event that no application with name @app_name has registered a bookmark
+for @uri, %FALSE is returned and error is set to
+%G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. In the event that unquoting
+the command line fails, an error of the %G_SHELL_ERROR domain is
+set and %FALSE is returned.
+ Use g_bookmark_file_get_application_info() instead, as
+ `time_t` is deprecated due to the year 2038 problem.
+
+
+ %TRUE on success.
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+ an application's name
+
+
+
+ return location for the command line of the application, or %NULL
+
+
+
+ return location for the registration count, or %NULL
+
+
+
+ return location for the last registration time, or %NULL
+
+
+
+
+
+ Gets the registration information of @app_name for the bookmark for
+@uri. See g_bookmark_file_set_application_info() for more information about
+the returned data.
+
+The string returned in @app_exec must be freed.
+
+In the event the URI cannot be found, %FALSE is returned and
+@error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the
+event that no application with name @app_name has registered a bookmark
+for @uri, %FALSE is returned and error is set to
+%G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. In the event that unquoting
+the command line fails, an error of the %G_SHELL_ERROR domain is
+set and %FALSE is returned.
+
+
+ %TRUE on success.
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+ an application's name
+
+
+
+ return location for the command line of the application, or %NULL
+
+
+
+ return location for the registration count, or %NULL
+
+
+
+ return location for the last registration time, or %NULL
+
+
+
+
+
+ Retrieves the names of the applications that have registered the
+bookmark for @uri.
+
+In the event the URI cannot be found, %NULL is returned and
+@error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
+
+
+ a newly allocated %NULL-terminated array of strings.
+ Use g_strfreev() to free it.
+
+
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+ return location of the length of the returned list, or %NULL
+
+
+
+
+
+ Retrieves the description of the bookmark for @uri.
+
+In the event the URI cannot be found, %NULL is returned and
+@error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
+
+
+ a newly allocated string or %NULL if the specified
+ URI cannot be found.
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+
+
+ Retrieves the list of group names of the bookmark for @uri.
+
+In the event the URI cannot be found, %NULL is returned and
+@error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
+
+The returned array is %NULL terminated, so @length may optionally
+be %NULL.
+
+
+ a newly allocated %NULL-terminated array of group names.
+ Use g_strfreev() to free it.
+
+
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+ return location for the length of the returned string, or %NULL
+
+
+
+
+
+ Gets the icon of the bookmark for @uri.
+
+In the event the URI cannot be found, %FALSE is returned and
+@error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
+
+
+ %TRUE if the icon for the bookmark for the URI was found.
+ You should free the returned strings.
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+ return location for the icon's location or %NULL
+
+
+
+ return location for the icon's MIME type or %NULL
+
+
+
+
+
+ Gets whether the private flag of the bookmark for @uri is set.
+
+In the event the URI cannot be found, %FALSE is returned and
+@error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the
+event that the private flag cannot be found, %FALSE is returned and
+@error is set to %G_BOOKMARK_FILE_ERROR_INVALID_VALUE.
+
+
+ %TRUE if the private flag is set, %FALSE otherwise.
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+
+
+ Retrieves the MIME type of the resource pointed by @uri.
+
+In the event the URI cannot be found, %NULL is returned and
+@error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the
+event that the MIME type cannot be found, %NULL is returned and
+@error is set to %G_BOOKMARK_FILE_ERROR_INVALID_VALUE.
+
+
+ a newly allocated string or %NULL if the specified
+ URI cannot be found.
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+
+
+ Gets the time when the bookmark for @uri was last modified.
+
+In the event the URI cannot be found, -1 is returned and
+@error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
+ Use g_bookmark_file_get_modified_date_time() instead, as
+ `time_t` is deprecated due to the year 2038 problem.
+
+
+ a timestamp
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+
+
+ Gets the time when the bookmark for @uri was last modified.
+
+In the event the URI cannot be found, %NULL is returned and
+@error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
+
+
+ a #GDateTime
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+
+
+ Gets the number of bookmarks inside @bookmark.
+
+
+ the number of bookmarks
+
+
+
+
+ a #GBookmarkFile
+
+
+
+
+
+ Returns the title of the bookmark for @uri.
+
+If @uri is %NULL, the title of @bookmark is returned.
+
+In the event the URI cannot be found, %NULL is returned and
+@error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
+
+
+ a newly allocated string or %NULL if the specified
+ URI cannot be found.
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI or %NULL
+
+
+
+
+
+ Returns all URIs of the bookmarks in the bookmark file @bookmark.
+The array of returned URIs will be %NULL-terminated, so @length may
+optionally be %NULL.
+
+
+ a newly allocated %NULL-terminated array of strings.
+ Use g_strfreev() to free it.
+
+
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ return location for the number of returned URIs, or %NULL
+
+
+
+
+
+ Gets the time the bookmark for @uri was last visited.
+
+In the event the URI cannot be found, -1 is returned and
+@error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
+ Use g_bookmark_file_get_visited_date_time() instead, as
+ `time_t` is deprecated due to the year 2038 problem.
+
+
+ a timestamp.
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+
+
+ Gets the time the bookmark for @uri was last visited.
+
+In the event the URI cannot be found, %NULL is returned and
+@error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
+
+
+ a #GDateTime
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+
+
+ Checks whether the bookmark for @uri inside @bookmark has been
+registered by application @name.
+
+In the event the URI cannot be found, %FALSE is returned and
+@error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
+
+
+ %TRUE if the application @name was found
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+ the name of the application
+
+
+
+
+
+ Checks whether @group appears in the list of groups to which
+the bookmark for @uri belongs to.
+
+In the event the URI cannot be found, %FALSE is returned and
+@error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
+
+
+ %TRUE if @group was found.
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+ the group name to be searched
+
+
+
+
+
+ Looks whether the desktop bookmark has an item with its URI set to @uri.
+
+
+ %TRUE if @uri is inside @bookmark, %FALSE otherwise
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+
+
+ Loads a bookmark file from memory into an empty #GBookmarkFile
+structure. If the object cannot be created then @error is set to a
+#GBookmarkFileError.
+
+
+ %TRUE if a desktop bookmark could be loaded.
+
+
+
+
+ an empty #GBookmarkFile struct
+
+
+
+ desktop bookmarks
+ loaded in memory
+
+
+
+
+
+ the length of @data in bytes
+
+
+
+
+
+ This function looks for a desktop bookmark file named @file in the
+paths returned from g_get_user_data_dir() and g_get_system_data_dirs(),
+loads the file into @bookmark and returns the file's full path in
+@full_path. If the file could not be loaded then @error is
+set to either a #GFileError or #GBookmarkFileError.
+
+
+ %TRUE if a key file could be loaded, %FALSE otherwise
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a relative path to a filename to open and parse
+
+
+
+ return location for a string
+ containing the full path of the file, or %NULL
+
+
+
+
+
+ Loads a desktop bookmark file into an empty #GBookmarkFile structure.
+If the file could not be loaded then @error is set to either a #GFileError
+or #GBookmarkFileError.
+
+
+ %TRUE if a desktop bookmark file could be loaded
+
+
+
+
+ an empty #GBookmarkFile struct
+
+
+
+ the path of a filename to load, in the
+ GLib file name encoding
+
+
+
+
+
+ Changes the URI of a bookmark item from @old_uri to @new_uri. Any
+existing bookmark for @new_uri will be overwritten. If @new_uri is
+%NULL, then the bookmark is removed.
+
+In the event the URI cannot be found, %FALSE is returned and
+@error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
+
+
+ %TRUE if the URI was successfully changed
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+ a valid URI, or %NULL
+
+
+
+
+
+ Removes application registered with @name from the list of applications
+that have registered a bookmark for @uri inside @bookmark.
+
+In the event the URI cannot be found, %FALSE is returned and
+@error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
+In the event that no application with name @app_name has registered
+a bookmark for @uri, %FALSE is returned and error is set to
+%G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED.
+
+
+ %TRUE if the application was successfully removed.
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+ the name of the application
+
+
+
+
+
+ Removes @group from the list of groups to which the bookmark
+for @uri belongs to.
+
+In the event the URI cannot be found, %FALSE is returned and
+@error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
+In the event no group was defined, %FALSE is returned and
+@error is set to %G_BOOKMARK_FILE_ERROR_INVALID_VALUE.
+
+
+ %TRUE if @group was successfully removed.
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+ the group name to be removed
+
+
+
+
+
+ Removes the bookmark for @uri from the bookmark file @bookmark.
+
+
+ %TRUE if the bookmark was removed successfully.
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+
+
+ Sets the time the bookmark for @uri was added into @bookmark.
+
+If no bookmark for @uri is found then it is created.
+ Use g_bookmark_file_set_added_date_time() instead, as
+ `time_t` is deprecated due to the year 2038 problem.
+
+
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+ a timestamp or -1 to use the current time
+
+
+
+
+
+ Sets the time the bookmark for @uri was added into @bookmark.
+
+If no bookmark for @uri is found then it is created.
+
+
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+ a #GDateTime
+
+
+
+
+
+ Sets the meta-data of application @name inside the list of
+applications that have registered a bookmark for @uri inside
+@bookmark.
+
+You should rarely use this function; use g_bookmark_file_add_application()
+and g_bookmark_file_remove_application() instead.
+
+@name can be any UTF-8 encoded string used to identify an
+application.
+@exec can have one of these two modifiers: "\%f", which will
+be expanded as the local file name retrieved from the bookmark's
+URI; "\%u", which will be expanded as the bookmark's URI.
+The expansion is done automatically when retrieving the stored
+command line using the g_bookmark_file_get_application_info() function.
+@count is the number of times the application has registered the
+bookmark; if is < 0, the current registration count will be increased
+by one, if is 0, the application with @name will be removed from
+the list of registered applications.
+@stamp is the Unix time of the last registration; if it is -1, the
+current time will be used.
+
+If you try to remove an application by setting its registration count to
+zero, and no bookmark for @uri is found, %FALSE is returned and
+@error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND; similarly,
+in the event that no application @name has registered a bookmark
+for @uri, %FALSE is returned and error is set to
+%G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. Otherwise, if no bookmark
+for @uri is found, one is created.
+ Use g_bookmark_file_set_application_info() instead, as
+ `time_t` is deprecated due to the year 2038 problem.
+
+
+ %TRUE if the application's meta-data was successfully
+ changed.
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+ an application's name
+
+
+
+ an application's command line
+
+
+
+ the number of registrations done for this application
+
+
+
+ the time of the last registration for this application
+
+
+
+
+
+ Sets the meta-data of application @name inside the list of
+applications that have registered a bookmark for @uri inside
+@bookmark.
+
+You should rarely use this function; use g_bookmark_file_add_application()
+and g_bookmark_file_remove_application() instead.
+
+@name can be any UTF-8 encoded string used to identify an
+application.
+@exec can have one of these two modifiers: "\%f", which will
+be expanded as the local file name retrieved from the bookmark's
+URI; "\%u", which will be expanded as the bookmark's URI.
+The expansion is done automatically when retrieving the stored
+command line using the g_bookmark_file_get_application_info() function.
+@count is the number of times the application has registered the
+bookmark; if is < 0, the current registration count will be increased
+by one, if is 0, the application with @name will be removed from
+the list of registered applications.
+@stamp is the Unix time of the last registration.
+
+If you try to remove an application by setting its registration count to
+zero, and no bookmark for @uri is found, %FALSE is returned and
+@error is set to %G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND; similarly,
+in the event that no application @name has registered a bookmark
+for @uri, %FALSE is returned and error is set to
+%G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. Otherwise, if no bookmark
+for @uri is found, one is created.
+
+
+ %TRUE if the application's meta-data was successfully
+ changed.
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+ an application's name
+
+
+
+ an application's command line
+
+
+
+ the number of registrations done for this application
+
+
+
+ the time of the last registration for this application,
+ which may be %NULL if @count is 0
+
+
+
+
+
+ Sets @description as the description of the bookmark for @uri.
+
+If @uri is %NULL, the description of @bookmark is set.
+
+If a bookmark for @uri cannot be found then it is created.
+
+
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI or %NULL
+
+
+
+ a string
+
+
+
+
+
+ Sets a list of group names for the item with URI @uri. Each previously
+set group name list is removed.
+
+If @uri cannot be found then an item for it is created.
+
+
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ an item's URI
+
+
+
+ an array of
+ group names, or %NULL to remove all groups
+
+
+
+
+
+ number of group name values in @groups
+
+
+
+
+
+ Sets the icon for the bookmark for @uri. If @href is %NULL, unsets
+the currently set icon. @href can either be a full URL for the icon
+file or the icon name following the Icon Naming specification.
+
+If no bookmark for @uri is found one is created.
+
+
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+ the URI of the icon for the bookmark, or %NULL
+
+
+
+ the MIME type of the icon for the bookmark
+
+
+
+
+
+ Sets the private flag of the bookmark for @uri.
+
+If a bookmark for @uri cannot be found then it is created.
+
+
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+ %TRUE if the bookmark should be marked as private
+
+
+
+
+
+ Sets @mime_type as the MIME type of the bookmark for @uri.
+
+If a bookmark for @uri cannot be found then it is created.
+
+
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+ a MIME type
+
+
+
+
+
+ Sets the last time the bookmark for @uri was last modified.
+
+If no bookmark for @uri is found then it is created.
+
+The "modified" time should only be set when the bookmark's meta-data
+was actually changed. Every function of #GBookmarkFile that
+modifies a bookmark also changes the modification time, except for
+g_bookmark_file_set_visited_date_time().
+ Use g_bookmark_file_set_modified_date_time() instead, as
+ `time_t` is deprecated due to the year 2038 problem.
+
+
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+ a timestamp or -1 to use the current time
+
+
+
+
+
+ Sets the last time the bookmark for @uri was last modified.
+
+If no bookmark for @uri is found then it is created.
+
+The "modified" time should only be set when the bookmark's meta-data
+was actually changed. Every function of #GBookmarkFile that
+modifies a bookmark also changes the modification time, except for
+g_bookmark_file_set_visited_date_time().
+
+
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+ a #GDateTime
+
+
+
+
+
+ Sets @title as the title of the bookmark for @uri inside the
+bookmark file @bookmark.
+
+If @uri is %NULL, the title of @bookmark is set.
+
+If a bookmark for @uri cannot be found then it is created.
+
+
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI or %NULL
+
+
+
+ a UTF-8 encoded string
+
+
+
+
+
+ Sets the time the bookmark for @uri was last visited.
+
+If no bookmark for @uri is found then it is created.
+
+The "visited" time should only be set if the bookmark was launched,
+either using the command line retrieved by g_bookmark_file_get_application_info()
+or by the default application for the bookmark's MIME type, retrieved
+using g_bookmark_file_get_mime_type(). Changing the "visited" time
+does not affect the "modified" time.
+ Use g_bookmark_file_set_visited_date_time() instead, as
+ `time_t` is deprecated due to the year 2038 problem.
+
+
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+ a timestamp or -1 to use the current time
+
+
+
+
+
+ Sets the time the bookmark for @uri was last visited.
+
+If no bookmark for @uri is found then it is created.
+
+The "visited" time should only be set if the bookmark was launched,
+either using the command line retrieved by g_bookmark_file_get_application_info()
+or by the default application for the bookmark's MIME type, retrieved
+using g_bookmark_file_get_mime_type(). Changing the "visited" time
+does not affect the "modified" time.
+
+
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ a valid URI
+
+
+
+ a #GDateTime
+
+
+
+
+
+ This function outputs @bookmark as a string.
+
+
+
+ a newly allocated string holding the contents of the #GBookmarkFile
+
+
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ return location for the length of the returned string, or %NULL
+
+
+
+
+
+ This function outputs @bookmark into a file. The write process is
+guaranteed to be atomic by using g_file_set_contents() internally.
+
+
+ %TRUE if the file was successfully written.
+
+
+
+
+ a #GBookmarkFile
+
+
+
+ path of the output file
+
+
+
+
+
+
+
+
+
+
+
+ Error codes returned by bookmark file parsing.
+
+
+ URI was ill-formed
+
+
+ a requested field was not found
+
+
+ a requested application did
+ not register a bookmark
+
+
+ a requested URI was not found
+
+
+ document was ill formed
+
+
+ the text being parsed was
+ in an unknown encoding
+
+
+ an error occurred while writing
+
+
+ requested file was not found
+
+
+
+ Contains the public fields of a GByteArray.
+
+
+ a pointer to the element data. The data may be moved as
+ elements are added to the #GByteArray
+
+
+
+ the number of elements in the #GByteArray
+
+
+
+ Adds the given bytes to the end of the #GByteArray.
+The array will grow in size automatically if necessary.
+
+
+ the #GByteArray
+
+
+
+
+
+
+ a #GByteArray
+
+
+
+
+
+ the byte data to be added
+
+
+
+ the number of bytes to add
+
+
+
+
+
+ Frees the memory allocated by the #GByteArray. If @free_segment is
+%TRUE it frees the actual byte data. If the reference count of
+@array is greater than one, the #GByteArray wrapper is preserved but
+the size of @array will be set to zero.
+
+
+ the element data if @free_segment is %FALSE, otherwise
+ %NULL. The element data should be freed using g_free().
+
+
+
+
+ a #GByteArray
+
+
+
+
+
+ if %TRUE the actual byte data is freed as well
+
+
+
+
+
+ Transfers the data from the #GByteArray into a new immutable #GBytes.
+
+The #GByteArray is freed unless the reference count of @array is greater
+than one, the #GByteArray wrapper is preserved but the size of @array
+will be set to zero.
+
+This is identical to using g_bytes_new_take() and g_byte_array_free()
+together.
+
+
+ a new immutable #GBytes representing same
+ byte data that was in the array
+
+
+
+
+ a #GByteArray
+
+
+
+
+
+
+
+ Creates a new #GByteArray with a reference count of 1.
+
+
+ the new #GByteArray
+
+
+
+
+
+
+ Create byte array containing the data. The data will be owned by the array
+and will be freed with g_free(), i.e. it could be allocated using g_strdup().
+
+Do not use it if @len is greater than %G_MAXUINT. #GByteArray
+stores the length of its data in #guint, which may be shorter than
+#gsize.
+
+
+ a new #GByteArray
+
+
+
+
+
+
+ byte data for the array
+
+
+
+
+
+ length of @data
+
+
+
+
+
+ Adds the given data to the start of the #GByteArray.
+The array will grow in size automatically if necessary.
+
+
+ the #GByteArray
+
+
+
+
+
+
+ a #GByteArray
+
+
+
+
+
+ the byte data to be added
+
+
+
+ the number of bytes to add
+
+
+
+
+
+ Atomically increments the reference count of @array by one.
+This function is thread-safe and may be called from any thread.
+
+
+ The passed in #GByteArray
+
+
+
+
+
+
+ A #GByteArray
+
+
+
+
+
+
+
+ Removes the byte at the given index from a #GByteArray.
+The following bytes are moved down one place.
+
+
+ the #GByteArray
+
+
+
+
+
+
+ a #GByteArray
+
+
+
+
+
+ the index of the byte to remove
+
+
+
+
+
+ Removes the byte at the given index from a #GByteArray. The last
+element in the array is used to fill in the space, so this function
+does not preserve the order of the #GByteArray. But it is faster
+than g_byte_array_remove_index().
+
+
+ the #GByteArray
+
+
+
+
+
+
+ a #GByteArray
+
+
+
+
+
+ the index of the byte to remove
+
+
+
+
+
+ Removes the given number of bytes starting at the given index from a
+#GByteArray. The following elements are moved to close the gap.
+
+
+ the #GByteArray
+
+
+
+
+
+
+ a @GByteArray
+
+
+
+
+
+ the index of the first byte to remove
+
+
+
+ the number of bytes to remove
+
+
+
+
+
+ Sets the size of the #GByteArray, expanding it if necessary.
+
+
+ the #GByteArray
+
+
+
+
+
+
+ a #GByteArray
+
+
+
+
+
+ the new size of the #GByteArray
+
+
+
+
+
+ Creates a new #GByteArray with @reserved_size bytes preallocated.
+This avoids frequent reallocation, if you are going to add many
+bytes to the array. Note however that the size of the array is still
+0.
+
+
+ the new #GByteArray
+
+
+
+
+
+
+ number of bytes preallocated
+
+
+
+
+
+ Sorts a byte array, using @compare_func which should be a
+qsort()-style comparison function (returns less than zero for first
+arg is less than second arg, zero for equal, greater than zero if
+first arg is greater than second arg).
+
+If two array elements compare equal, their order in the sorted array
+is undefined. If you want equal elements to keep their order (i.e.
+you want a stable sort) you can write a comparison function that,
+if two elements would otherwise compare equal, compares them by
+their addresses.
+
+
+
+
+
+
+ a #GByteArray
+
+
+
+
+
+ comparison function
+
+
+
+
+
+ Like g_byte_array_sort(), but the comparison function takes an extra
+user data argument.
+
+
+
+
+
+
+ a #GByteArray
+
+
+
+
+
+ comparison function
+
+
+
+ data to pass to @compare_func
+
+
+
+
+
+ Frees the data in the array and resets the size to zero, while
+the underlying array is preserved for use elsewhere and returned
+to the caller.
+
+
+ the element data, which should be
+ freed using g_free().
+
+
+
+
+ a #GByteArray.
+
+
+
+
+
+ pointer to retrieve the number of
+ elements of the original array
+
+
+
+
+
+ Atomically decrements the reference count of @array by one. If the
+reference count drops to 0, all memory allocated by the array is
+released. This function is thread-safe and may be called from any
+thread.
+
+
+
+
+
+
+ A #GByteArray
+
+
+
+
+
+
+
+
+ A simple refcounted data type representing an immutable sequence of zero or
+more bytes from an unspecified origin.
+
+The purpose of a #GBytes is to keep the memory region that it holds
+alive for as long as anyone holds a reference to the bytes. When
+the last reference count is dropped, the memory is released. Multiple
+unrelated callers can use byte data in the #GBytes without coordinating
+their activities, resting assured that the byte data will not change or
+move while they hold a reference.
+
+A #GBytes can come from many different origins that may have
+different procedures for freeing the memory region. Examples are
+memory from g_malloc(), from memory slices, from a #GMappedFile or
+memory from other allocators.
+
+#GBytes work well as keys in #GHashTable. Use g_bytes_equal() and
+g_bytes_hash() as parameters to g_hash_table_new() or g_hash_table_new_full().
+#GBytes can also be used as keys in a #GTree by passing the g_bytes_compare()
+function to g_tree_new().
+
+The data pointed to by this bytes must not be modified. For a mutable
+array of bytes see #GByteArray. Use g_bytes_unref_to_array() to create a
+mutable array for a #GBytes sequence. To create an immutable #GBytes from
+a mutable #GByteArray, use the g_byte_array_free_to_bytes() function.
+
+
+ Creates a new #GBytes from @data.
+
+@data is copied. If @size is 0, @data may be %NULL.
+
+
+ a new #GBytes
+
+
+
+
+
+ the data to be used for the bytes
+
+
+
+
+
+ the size of @data
+
+
+
+
+
+ Creates a new #GBytes from static data.
+
+@data must be static (ie: never modified or freed). It may be %NULL if @size
+is 0.
+
+
+ a new #GBytes
+
+
+
+
+
+ the data to be used for the bytes
+
+
+
+
+
+ the size of @data
+
+
+
+
+
+ Creates a new #GBytes from @data.
+
+After this call, @data belongs to the bytes and may no longer be
+modified by the caller. g_free() will be called on @data when the
+bytes is no longer in use. Because of this @data must have been created by
+a call to g_malloc(), g_malloc0() or g_realloc() or by one of the many
+functions that wrap these calls (such as g_new(), g_strdup(), etc).
+
+For creating #GBytes with memory from other allocators, see
+g_bytes_new_with_free_func().
+
+@data may be %NULL if @size is 0.
+
+
+ a new #GBytes
+
+
+
+
+
+ the data to be used for the bytes
+
+
+
+
+
+ the size of @data
+
+
+
+
+
+ Creates a #GBytes from @data.
+
+When the last reference is dropped, @free_func will be called with the
+@user_data argument.
+
+@data must not be modified after this call is made until @free_func has
+been called to indicate that the bytes is no longer in use.
+
+@data may be %NULL if @size is 0.
+
+
+ a new #GBytes
+
+
+
+
+
+ the data to be used for the bytes
+
+
+
+
+
+ the size of @data
+
+
+
+ the function to call to release the data
+
+
+
+ data to pass to @free_func
+
+
+
+
+
+ Compares the two #GBytes values.
+
+This function can be used to sort GBytes instances in lexicographical order.
+
+If @bytes1 and @bytes2 have different length but the shorter one is a
+prefix of the longer one then the shorter one is considered to be less than
+the longer one. Otherwise the first byte where both differ is used for
+comparison. If @bytes1 has a smaller value at that position it is
+considered less, otherwise greater than @bytes2.
+
+
+ a negative value if @bytes1 is less than @bytes2, a positive value
+ if @bytes1 is greater than @bytes2, and zero if @bytes1 is equal to
+ @bytes2
+
+
+
+
+ a pointer to a #GBytes
+
+
+
+ a pointer to a #GBytes to compare with @bytes1
+
+
+
+
+
+ Compares the two #GBytes values being pointed to and returns
+%TRUE if they are equal.
+
+This function can be passed to g_hash_table_new() as the @key_equal_func
+parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable.
+
+
+ %TRUE if the two keys match.
+
+
+
+
+ a pointer to a #GBytes
+
+
+
+ a pointer to a #GBytes to compare with @bytes1
+
+
+
+
+
+ Get the byte data in the #GBytes. This data should not be modified.
+
+This function will always return the same pointer for a given #GBytes.
+
+%NULL may be returned if @size is 0. This is not guaranteed, as the #GBytes
+may represent an empty string with @data non-%NULL and @size as 0. %NULL will
+not be returned if @size is non-zero.
+
+
+
+ a pointer to the byte data, or %NULL
+
+
+
+
+
+
+ a #GBytes
+
+
+
+ location to return size of byte data
+
+
+
+
+
+ Gets a pointer to a region in @bytes.
+
+The region starts at @offset many bytes from the start of the data
+and contains @n_elements many elements of @element_size size.
+
+@n_elements may be zero, but @element_size must always be non-zero.
+Ideally, @element_size is a static constant (eg: sizeof a struct).
+
+This function does careful bounds checking (including checking for
+arithmetic overflows) and returns a non-%NULL pointer if the
+specified region lies entirely within the @bytes. If the region is
+in some way out of range, or if an overflow has occurred, then %NULL
+is returned.
+
+Note: it is possible to have a valid zero-size region. In this case,
+the returned pointer will be equal to the base pointer of the data of
+@bytes, plus @offset. This will be non-%NULL except for the case
+where @bytes itself was a zero-sized region. Since it is unlikely
+that you will be using this function to check for a zero-sized region
+in a zero-sized @bytes, %NULL effectively always means "error".
+
+
+ the requested region, or %NULL in case of an error
+
+
+
+
+ a #GBytes
+
+
+
+ a non-zero element size
+
+
+
+ an offset to the start of the region within the @bytes
+
+
+
+ the number of elements in the region
+
+
+
+
+
+ Get the size of the byte data in the #GBytes.
+
+This function will always return the same value for a given #GBytes.
+
+
+ the size
+
+
+
+
+ a #GBytes
+
+
+
+
+
+ Creates an integer hash code for the byte data in the #GBytes.
+
+This function can be passed to g_hash_table_new() as the @key_hash_func
+parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable.
+
+
+ a hash value corresponding to the key.
+
+
+
+
+ a pointer to a #GBytes key
+
+
+
+
+
+ Creates a #GBytes which is a subsection of another #GBytes. The @offset +
+@length may not be longer than the size of @bytes.
+
+A reference to @bytes will be held by the newly created #GBytes until
+the byte data is no longer needed.
+
+Since 2.56, if @offset is 0 and @length matches the size of @bytes, then
+@bytes will be returned with the reference count incremented by 1. If @bytes
+is a slice of another #GBytes, then the resulting #GBytes will reference
+the same #GBytes instead of @bytes. This allows consumers to simplify the
+usage of #GBytes when asynchronously writing to streams.
+
+
+ a new #GBytes
+
+
+
+
+ a #GBytes
+
+
+
+ offset which subsection starts at
+
+
+
+ length of subsection
+
+
+
+
+
+ Increase the reference count on @bytes.
+
+
+ the #GBytes
+
+
+
+
+ a #GBytes
+
+
+
+
+
+ Releases a reference on @bytes. This may result in the bytes being
+freed. If @bytes is %NULL, it will return immediately.
+
+
+
+
+
+
+ a #GBytes
+
+
+
+
+
+ Unreferences the bytes, and returns a new mutable #GByteArray containing
+the same byte data.
+
+As an optimization, the byte data is transferred to the array without copying
+if this was the last reference to bytes and bytes was created with
+g_bytes_new(), g_bytes_new_take() or g_byte_array_free_to_bytes(). In all
+other cases the data is copied.
+
+Do not use it if @bytes contains more than %G_MAXUINT
+bytes. #GByteArray stores the length of its data in #guint, which
+may be shorter than #gsize, that @bytes is using.
+
+
+ a new mutable #GByteArray containing the same byte data
+
+
+
+
+
+
+ a #GBytes
+
+
+
+
+
+ Unreferences the bytes, and returns a pointer the same byte data
+contents.
+
+As an optimization, the byte data is returned without copying if this was
+the last reference to bytes and bytes was created with g_bytes_new(),
+g_bytes_new_take() or g_byte_array_free_to_bytes(). In all other cases the
+data is copied.
+
+
+ a pointer to the same byte data, which should be
+ freed with g_free()
+
+
+
+
+
+
+ a #GBytes
+
+
+
+ location to place the length of the returned data
+
+
+
+
+
+
+ Checks whether the version of the GLib library that is being compiled
+against is greater than or equal to the given one.
+
+See glib_check_version() for a runtime check.
+
+
+
+ the major version to check for
+
+
+ the minor version to check for
+
+
+ the micro version to check for
+
+
+
+
+ The set of uppercase ASCII alphabet characters.
+Used for specifying valid identifier characters
+in #GScannerConfig.
+
+
+
+
+ The set of ASCII digits.
+Used for specifying valid identifier characters
+in #GScannerConfig.
+
+
+
+
+ The set of lowercase ASCII alphabet characters.
+Used for specifying valid identifier characters
+in #GScannerConfig.
+
+
+
+
+ Macro to check if the current compiler supports a specified @version
+of the C++ standard. Such value must be numeric and can be provided both
+in the short form for the well-known versions (e.g. `11`, `17`...) or in
+the complete form otherwise (e.g. `201103L`, `201703L`, `205503L`...).
+
+When a C compiler is used, the macro is defined and returns always %FALSE.
+
+This value is compared against %G_CXX_STD_VERSION.
+
+|[<!-- language="C" -->
+#if G_CXX_STD_CHECK_VERSION(20)
+#endif
+]|
+
+See also: %G_C_STD_CHECK_VERSION
+
+
+
+ The C++ version to be checked for compatibility
+
+
+
+
+ Macro to check if the current compiler supports a specified @version
+of the C standard. Such value must be numeric and can be provided both
+in the short form for the well-known versions (e.g. `90`, `99`...) or in
+the complete form otherwise (e.g. `199000L`, `199901L`, `205503L`...).
+
+When a C++ compiler is used, the macro is defined and returns always %FALSE.
+
+This value is compared against %G_C_STD_VERSION.
+
+|[<!-- language="C" -->
+#if G_C_STD_CHECK_VERSION(17)
+#endif
+]|
+
+See also: %G_CXX_STD_CHECK_VERSION
+
+
+
+ The C version to be checked for compatibility
+
+
+
+
+ The C standard version the code is compiling against, it's normally
+defined with the same value of `__STDC_VERSION__` for C standard
+compatible compilers, while it uses the lowest standard version
+in pure MSVC, given that in such compiler the definition depends on
+a compilation flag.
+
+This is granted to be undefined when compiling with a C++ compiler.
+
+See also: %G_C_STD_CHECK_VERSION and %G_CXX_STD_VERSION
+
+
+
+
+ An opaque structure representing a checksumming operation.
+
+To create a new GChecksum, use g_checksum_new(). To free
+a GChecksum, use g_checksum_free().
+
+
+ Creates a new #GChecksum, using the checksum algorithm @checksum_type.
+If the @checksum_type is not known, %NULL is returned.
+A #GChecksum can be used to compute the checksum, or digest, of an
+arbitrary binary blob, using different hashing algorithms.
+
+A #GChecksum works by feeding a binary blob through g_checksum_update()
+until there is data to be checked; the digest can then be extracted
+using g_checksum_get_string(), which will return the checksum as a
+hexadecimal string; or g_checksum_get_digest(), which will return a
+vector of raw bytes. Once either g_checksum_get_string() or
+g_checksum_get_digest() have been called on a #GChecksum, the checksum
+will be closed and it won't be possible to call g_checksum_update()
+on it anymore.
+
+
+ the newly created #GChecksum, or %NULL.
+ Use g_checksum_free() to free the memory allocated by it.
+
+
+
+
+ the desired type of checksum
+
+
+
+
+
+ Copies a #GChecksum. If @checksum has been closed, by calling
+g_checksum_get_string() or g_checksum_get_digest(), the copied
+checksum will be closed as well.
+
+
+ the copy of the passed #GChecksum. Use
+ g_checksum_free() when finished using it.
+
+
+
+
+ the #GChecksum to copy
+
+
+
+
+
+ Frees the memory allocated for @checksum.
+
+
+
+
+
+
+ a #GChecksum
+
+
+
+
+
+ Gets the digest from @checksum as a raw binary vector and places it
+into @buffer. The size of the digest depends on the type of checksum.
+
+Once this function has been called, the #GChecksum is closed and can
+no longer be updated with g_checksum_update().
+
+
+
+
+
+
+ a #GChecksum
+
+
+
+ output buffer
+
+
+
+
+
+ an inout parameter. The caller initializes it to the size of @buffer.
+ After the call it contains the length of the digest.
+
+
+
+
+
+ Gets the digest as a hexadecimal string.
+
+Once this function has been called the #GChecksum can no longer be
+updated with g_checksum_update().
+
+The hexadecimal characters will be lower case.
+
+
+ the hexadecimal representation of the checksum. The
+ returned string is owned by the checksum and should not be modified
+ or freed.
+
+
+
+
+ a #GChecksum
+
+
+
+
+
+ Resets the state of the @checksum back to its initial state.
+
+
+
+
+
+
+ the #GChecksum to reset
+
+
+
+
+
+ Feeds @data into an existing #GChecksum. The checksum must still be
+open, that is g_checksum_get_string() or g_checksum_get_digest() must
+not have been called on @checksum.
+
+
+
+
+
+
+ a #GChecksum
+
+
+
+ buffer used to compute the checksum
+
+
+
+
+
+ size of the buffer, or -1 if it is a null-terminated string.
+
+
+
+
+
+ Gets the length in bytes of digests of type @checksum_type
+
+
+ the checksum length, or -1 if @checksum_type is
+not supported.
+
+
+
+
+ a #GChecksumType
+
+
+
+
+
+
+ The hashing algorithm to be used by #GChecksum when performing the
+digest of some data.
+
+Note that the #GChecksumType enumeration may be extended at a later
+date to include new hashing algorithm types.
+
+
+ Use the MD5 hashing algorithm
+
+
+ Use the SHA-1 hashing algorithm
+
+
+ Use the SHA-256 hashing algorithm
+
+
+ Use the SHA-512 hashing algorithm (Since: 2.36)
+
+
+ Use the SHA-384 hashing algorithm (Since: 2.51)
+
+
+
+ Prototype of a #GChildWatchSource callback, called when a child
+process has exited.
+
+To interpret @wait_status, see the documentation
+for g_spawn_check_wait_status(). In particular,
+on Unix platforms, note that it is usually not equal
+to the integer passed to `exit()` or returned from `main()`.
+
+
+
+
+
+
+ the process id of the child process
+
+
+
+ Status information about the child process, encoded
+ in a platform-specific manner
+
+
+
+ user data passed to g_child_watch_add()
+
+
+
+
+
+ Specifies the type of function passed to g_clear_handle_id().
+The implementation is expected to free the resource identified
+by @handle_id; for instance, if @handle_id is a #GSource ID,
+g_source_remove() can be used.
+
+
+
+
+
+
+ the handle ID to clear
+
+
+
+
+
+ Specifies the type of a comparison function used to compare two
+values. The function should return a negative integer if the first
+value comes before the second, 0 if they are equal, or a positive
+integer if the first value comes after the second.
+
+
+ negative value if @a < @b; zero if @a = @b; positive
+ value if @a > @b
+
+
+
+
+ a value
+
+
+
+ a value to compare with
+
+
+
+ user data
+
+
+
+
+
+ Specifies the type of a comparison function used to compare two
+values. The function should return a negative integer if the first
+value comes before the second, 0 if they are equal, or a positive
+integer if the first value comes after the second.
+
+
+ negative value if @a < @b; zero if @a = @b; positive
+ value if @a > @b
+
+
+
+
+ a value
+
+
+
+ a value to compare with
+
+
+
+
+
+ The #GCond struct is an opaque data structure that represents a
+condition. Threads can block on a #GCond if they find a certain
+condition to be false. If other threads change the state of this
+condition they signal the #GCond, and that causes the waiting
+threads to be woken up.
+
+Consider the following example of a shared variable. One or more
+threads can wait for data to be published to the variable and when
+another thread publishes the data, it can signal one of the waiting
+threads to wake up to collect the data.
+
+Here is an example for using GCond to block a thread until a condition
+is satisfied:
+|[<!-- language="C" -->
+ gpointer current_data = NULL;
+ GMutex data_mutex;
+ GCond data_cond;
+
+ void
+ push_data (gpointer data)
+ {
+ g_mutex_lock (&data_mutex);
+ current_data = data;
+ g_cond_signal (&data_cond);
+ g_mutex_unlock (&data_mutex);
+ }
+
+ gpointer
+ pop_data (void)
+ {
+ gpointer data;
+
+ g_mutex_lock (&data_mutex);
+ while (!current_data)
+ g_cond_wait (&data_cond, &data_mutex);
+ data = current_data;
+ current_data = NULL;
+ g_mutex_unlock (&data_mutex);
+
+ return data;
+ }
+]|
+Whenever a thread calls pop_data() now, it will wait until
+current_data is non-%NULL, i.e. until some other thread
+has called push_data().
+
+The example shows that use of a condition variable must always be
+paired with a mutex. Without the use of a mutex, there would be a
+race between the check of @current_data by the while loop in
+pop_data() and waiting. Specifically, another thread could set
+@current_data after the check, and signal the cond (with nobody
+waiting on it) before the first thread goes to sleep. #GCond is
+specifically useful for its ability to release the mutex and go
+to sleep atomically.
+
+It is also important to use the g_cond_wait() and g_cond_wait_until()
+functions only inside a loop which checks for the condition to be
+true. See g_cond_wait() for an explanation of why the condition may
+not be true even after it returns.
+
+If a #GCond is allocated in static storage then it can be used
+without initialisation. Otherwise, you should call g_cond_init()
+on it and g_cond_clear() when done.
+
+A #GCond should only be accessed via the g_cond_ functions.
+
+
+
+
+
+
+
+
+
+
+ If threads are waiting for @cond, all of them are unblocked.
+If no threads are waiting for @cond, this function has no effect.
+It is good practice to lock the same mutex as the waiting threads
+while calling this function, though not required.
+
+
+
+
+
+
+ a #GCond
+
+
+
+
+
+ Frees the resources allocated to a #GCond with g_cond_init().
+
+This function should not be used with a #GCond that has been
+statically allocated.
+
+Calling g_cond_clear() for a #GCond on which threads are
+blocking leads to undefined behaviour.
+
+
+
+
+
+
+ an initialised #GCond
+
+
+
+
+
+ Initialises a #GCond so that it can be used.
+
+This function is useful to initialise a #GCond that has been
+allocated as part of a larger structure. It is not necessary to
+initialise a #GCond that has been statically allocated.
+
+To undo the effect of g_cond_init() when a #GCond is no longer
+needed, use g_cond_clear().
+
+Calling g_cond_init() on an already-initialised #GCond leads
+to undefined behaviour.
+
+
+
+
+
+
+ an uninitialized #GCond
+
+
+
+
+
+ If threads are waiting for @cond, at least one of them is unblocked.
+If no threads are waiting for @cond, this function has no effect.
+It is good practice to hold the same lock as the waiting thread
+while calling this function, though not required.
+
+
+
+
+
+
+ a #GCond
+
+
+
+
+
+ Atomically releases @mutex and waits until @cond is signalled.
+When this function returns, @mutex is locked again and owned by the
+calling thread.
+
+When using condition variables, it is possible that a spurious wakeup
+may occur (ie: g_cond_wait() returns even though g_cond_signal() was
+not called). It's also possible that a stolen wakeup may occur.
+This is when g_cond_signal() is called, but another thread acquires
+@mutex before this thread and modifies the state of the program in
+such a way that when g_cond_wait() is able to return, the expected
+condition is no longer met.
+
+For this reason, g_cond_wait() must always be used in a loop. See
+the documentation for #GCond for a complete example.
+
+
+
+
+
+
+ a #GCond
+
+
+
+ a #GMutex that is currently locked
+
+
+
+
+
+ Waits until either @cond is signalled or @end_time has passed.
+
+As with g_cond_wait() it is possible that a spurious or stolen wakeup
+could occur. For that reason, waiting on a condition variable should
+always be in a loop, based on an explicitly-checked predicate.
+
+%TRUE is returned if the condition variable was signalled (or in the
+case of a spurious wakeup). %FALSE is returned if @end_time has
+passed.
+
+The following code shows how to correctly perform a timed wait on a
+condition variable (extending the example presented in the
+documentation for #GCond):
+
+|[<!-- language="C" -->
+gpointer
+pop_data_timed (void)
+{
+ gint64 end_time;
+ gpointer data;
+
+ g_mutex_lock (&data_mutex);
+
+ end_time = g_get_monotonic_time () + 5 * G_TIME_SPAN_SECOND;
+ while (!current_data)
+ if (!g_cond_wait_until (&data_cond, &data_mutex, end_time))
+ {
+ // timeout has passed.
+ g_mutex_unlock (&data_mutex);
+ return NULL;
+ }
+
+ // there is data for us
+ data = current_data;
+ current_data = NULL;
+
+ g_mutex_unlock (&data_mutex);
+
+ return data;
+}
+]|
+
+Notice that the end time is calculated once, before entering the
+loop and reused. This is the motivation behind the use of absolute
+time on this API -- if a relative time of 5 seconds were passed
+directly to the call and a spurious wakeup occurred, the program would
+have to start over waiting again (which would lead to a total wait
+time of more than 5 seconds).
+
+
+ %TRUE on a signal, %FALSE on a timeout
+
+
+
+
+ a #GCond
+
+
+
+ a #GMutex that is currently locked
+
+
+
+ the monotonic time to wait until
+
+
+
+
+
+
+ Error codes returned by character set conversion routines.
+
+
+ Conversion between the requested character
+ sets is not supported.
+
+
+ Invalid byte sequence in conversion input;
+ or the character sequence could not be represented in the target
+ character set.
+
+
+ Conversion failed for some reason.
+
+
+ Partial character sequence at end of input.
+
+
+ URI is invalid.
+
+
+ Pathname is not an absolute path.
+
+
+ No memory available. Since: 2.40
+
+
+ An embedded NUL character is present in
+ conversion output where a NUL-terminated string is expected.
+ Since: 2.56
+
+
+
+ A function of this signature is used to copy the node data
+when doing a deep-copy of a tree.
+
+
+ A pointer to the copy
+
+
+
+
+ A pointer to the data which should be copied
+
+
+
+ Additional data
+
+
+
+
+
+ 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.
+
+
+
+
+ Represents an invalid #GDateDay.
+
+
+
+
+ Represents an invalid Julian day number.
+
+
+
+
+ Represents an invalid year.
+
+
+
+
+ A convenience form of g_log_structured(), recommended to be added to
+functions when debugging. It prints the current monotonic time and the code
+location using %G_STRLOC.
+
+
+
+ Defines the appropriate cleanup function for a pointer type.
+
+The function will not be called if the variable to be cleaned up
+contains %NULL.
+
+This will typically be the `_free()` or `_unref()` function for the given
+type.
+
+With this definition, it will be possible to use g_autoptr() with
+@TypeName.
+
+|[
+G_DEFINE_AUTOPTR_CLEANUP_FUNC(GObject, g_object_unref)
+]|
+
+This macro should be used unconditionally; it is a no-op on compilers
+where cleanup is not supported.
+
+
+
+ a type name to define a g_autoptr() cleanup function for
+
+
+ the cleanup function
+
+
+
+
+ Defines the appropriate cleanup function for a type.
+
+This will typically be the `_clear()` function for the given type.
+
+With this definition, it will be possible to use g_auto() with
+@TypeName.
+
+|[
+G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(GQueue, g_queue_clear)
+]|
+
+This macro should be used unconditionally; it is a no-op on compilers
+where cleanup is not supported.
+
+
+
+ a type name to define a g_auto() cleanup function for
+
+
+ the clear function
+
+
+
+
+ Defines the appropriate cleanup function for a type.
+
+With this definition, it will be possible to use g_auto() with
+@TypeName.
+
+This function will be rarely used. It is used with pointer-based
+typedefs and non-pointer types where the value of the variable
+represents a resource that must be freed. Two examples are #GStrv
+and file descriptors.
+
+@none specifies the "none" value for the type in question. It is
+probably something like %NULL or `-1`. If the variable is found to
+contain this value then the free function will not be called.
+
+|[
+G_DEFINE_AUTO_CLEANUP_FREE_FUNC(GStrv, g_strfreev, NULL)
+]|
+
+This macro should be used unconditionally; it is a no-op on compilers
+where cleanup is not supported.
+
+
+
+ a type name to define a g_auto() cleanup function for
+
+
+ the free function
+
+
+ the "none" value for the type
+
+
+
+
+ A convenience macro which defines two functions. First, returning
+the #GQuark for the extended error type @ErrorType; it is called
+`error_type_quark()`. Second, returning the private data from a
+passed #GError; it is called `error_type_get_private()`.
+
+For this macro to work, a type named `ErrorTypePrivate` should be
+defined, `error_type_private_init()`, `error_type_private_copy()`
+and `error_type_private_clear()` functions need to be either
+declared or defined. The functions should be similar to
+#GErrorInitFunc, #GErrorCopyFunc and #GErrorClearFunc,
+respectively, but they should receive the private data type instead
+of #GError.
+
+See [Extended #GError Domains][gerror-extended-domains] for an example.
+
+
+
+ name to return a #GQuark for
+
+
+ prefix for the function name
+
+
+
+
+ A convenience macro which defines a function returning the
+#GQuark for the name @QN. The function will be named
+@q_n_quark().
+
+Note that the quark name will be stringified automatically
+in the macro, so you shouldn't use double quotes.
+
+
+
+ the name to return a #GQuark for
+
+
+ prefix for the function name
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The directory separator character.
+This is '/' on UNIX machines and '\' under Windows.
+
+
+
+
+ The directory separator as a string.
+This is "/" on UNIX machines and "\" under Windows.
+
+
+
+
+ An opaque data structure that represents a keyed data list.
+
+See also: [Keyed data lists][glib-Keyed-Data-Lists].
+
+
+
+ Specifies the type of function passed to g_dataset_foreach(). It is
+called with each #GQuark id and associated data element, together
+with the @user_data parameter supplied to g_dataset_foreach().
+
+
+
+
+
+
+ the #GQuark id to identifying the data element.
+
+
+
+ the data element.
+
+
+
+ user data passed to g_dataset_foreach().
+
+
+
+
+
+ Represents a day between January 1, Year 1 and a few thousand years in
+the future. None of its members should be accessed directly.
+
+If the `GDate` is obtained from g_date_new(), it will be safe
+to mutate but invalid and thus not safe for calendrical computations.
+
+If it's declared on the stack, it will contain garbage so must be
+initialized with g_date_clear(). g_date_clear() makes the date invalid
+but safe. An invalid date doesn't represent a day, it's "empty." A date
+becomes valid after you set it to a Julian day or you set a day, month,
+and year.
+
+
+ the Julian representation of the date
+
+
+
+ this bit is set if @julian_days is valid
+
+
+
+ this is set if @day, @month and @year are valid
+
+
+
+ the day of the day-month-year representation of the date,
+ as a number between 1 and 31
+
+
+
+ the day of the day-month-year representation of the date,
+ as a number between 1 and 12
+
+
+
+ the day of the day-month-year representation of the date
+
+
+
+ Allocates a #GDate and initializes
+it to a safe state. The new date will
+be cleared (as if you'd called g_date_clear()) but invalid (it won't
+represent an existing day). Free the return value with g_date_free().
+
+
+ a newly-allocated #GDate
+
+
+
+
+ Create a new #GDate representing the given day-month-year triplet.
+
+The triplet you pass in must represent a valid date. Use g_date_valid_dmy()
+if needed to validate it. The returned #GDate is guaranteed to be non-%NULL
+and valid.
+
+
+ a newly-allocated #GDate
+ initialized with @day, @month, and @year
+
+
+
+
+ day of the month
+
+
+
+ month of the year
+
+
+
+ year
+
+
+
+
+
+ Create a new #GDate representing the given Julian date.
+
+The @julian_day you pass in must be valid. Use g_date_valid_julian() if
+needed to validate it. The returned #GDate is guaranteed to be non-%NULL and
+valid.
+
+
+ a newly-allocated #GDate initialized
+ with @julian_day
+
+
+
+
+ days since January 1, Year 1
+
+
+
+
+
+ Increments a date some number of days.
+To move forward by weeks, add weeks*7 days.
+The date must be valid.
+
+
+
+
+
+
+ a #GDate to increment
+
+
+
+ number of days to move the date forward
+
+
+
+
+
+ Increments a date by some number of months.
+If the day of the month is greater than 28,
+this routine may change the day of the month
+(because the destination month may not have
+the current day in it). The date must be valid.
+
+
+
+
+
+
+ a #GDate to increment
+
+
+
+ number of months to move forward
+
+
+
+
+
+ Increments a date by some number of years.
+If the date is February 29, and the destination
+year is not a leap year, the date will be changed
+to February 28. The date must be valid.
+
+
+
+
+
+
+ a #GDate to increment
+
+
+
+ number of years to move forward
+
+
+
+
+
+ If @date is prior to @min_date, sets @date equal to @min_date.
+If @date falls after @max_date, sets @date equal to @max_date.
+Otherwise, @date is unchanged.
+Either of @min_date and @max_date may be %NULL.
+All non-%NULL dates must be valid.
+
+
+
+
+
+
+ a #GDate to clamp
+
+
+
+ minimum accepted value for @date
+
+
+
+ maximum accepted value for @date
+
+
+
+
+
+ Initializes one or more #GDate structs to a safe but invalid
+state. The cleared dates will not represent an existing date, but will
+not contain garbage. Useful to init a date declared on the stack.
+Validity can be tested with g_date_valid().
+
+
+
+
+
+
+ pointer to one or more dates to clear
+
+
+
+ number of dates to clear
+
+
+
+
+
+ qsort()-style comparison function for dates.
+Both dates must be valid.
+
+
+ 0 for equal, less than zero if @lhs is less than @rhs,
+ greater than zero if @lhs is greater than @rhs
+
+
+
+
+ first date to compare
+
+
+
+ second date to compare
+
+
+
+
+
+ Copies a GDate to a newly-allocated GDate. If the input was invalid
+(as determined by g_date_valid()), the invalid state will be copied
+as is into the new object.
+
+
+ a newly-allocated #GDate initialized from @date
+
+
+
+
+ a #GDate to copy
+
+
+
+
+
+ Computes the number of days between two dates.
+If @date2 is prior to @date1, the returned value is negative.
+Both dates must be valid.
+
+
+ the number of days between @date1 and @date2
+
+
+
+
+ the first date
+
+
+
+ the second date
+
+
+
+
+
+ Frees a #GDate returned from g_date_new().
+
+
+
+
+
+
+ a #GDate to free
+
+
+
+
+
+ Returns the day of the month. The date must be valid.
+
+
+ day of the month
+
+
+
+
+ a #GDate to extract the day of the month from
+
+
+
+
+
+ Returns the day of the year, where Jan 1 is the first day of the
+year. The date must be valid.
+
+
+ day of the year
+
+
+
+
+ a #GDate to extract day of year from
+
+
+
+
+
+ Returns the week of the year, where weeks are interpreted according
+to ISO 8601.
+
+
+ ISO 8601 week number of the year.
+
+
+
+
+ a valid #GDate
+
+
+
+
+
+ Returns the Julian day or "serial number" of the #GDate. The
+Julian day is simply the number of days since January 1, Year 1; i.e.,
+January 1, Year 1 is Julian day 1; January 2, Year 1 is Julian day 2,
+etc. The date must be valid.
+
+
+ Julian day
+
+
+
+
+ a #GDate to extract the Julian day from
+
+
+
+
+
+ Returns the week of the year, where weeks are understood to start on
+Monday. If the date is before the first Monday of the year, return 0.
+The date must be valid.
+
+
+ week of the year
+
+
+
+
+ a #GDate
+
+
+
+
+
+ Returns the month of the year. The date must be valid.
+
+
+ month of the year as a #GDateMonth
+
+
+
+
+ a #GDate to get the month from
+
+
+
+
+
+ Returns the week of the year during which this date falls, if
+weeks are understood to begin on Sunday. The date must be valid.
+Can return 0 if the day is before the first Sunday of the year.
+
+
+ week number
+
+
+
+
+ a #GDate
+
+
+
+
+
+ Returns the day of the week for a #GDate. The date must be valid.
+
+
+ day of the week as a #GDateWeekday.
+
+
+
+
+ a #GDate
+
+
+
+
+
+ Returns the year of a #GDate. The date must be valid.
+
+
+ year in which the date falls
+
+
+
+
+ a #GDate
+
+
+
+
+
+ Returns %TRUE if the date is on the first of a month.
+The date must be valid.
+
+
+ %TRUE if the date is the first of the month
+
+
+
+
+ a #GDate to check
+
+
+
+
+
+ Returns %TRUE if the date is the last day of the month.
+The date must be valid.
+
+
+ %TRUE if the date is the last day of the month
+
+
+
+
+ a #GDate to check
+
+
+
+
+
+ Checks if @date1 is less than or equal to @date2,
+and swap the values if this is not the case.
+
+
+
+
+
+
+ the first date
+
+
+
+ the second date
+
+
+
+
+
+ Sets the day of the month for a #GDate. If the resulting
+day-month-year triplet is invalid, the date will be invalid.
+
+
+
+
+
+
+ a #GDate
+
+
+
+ day to set
+
+
+
+
+
+ Sets the value of a #GDate from a day, month, and year.
+The day-month-year triplet must be valid; if you aren't
+sure it is, call g_date_valid_dmy() to check before you
+set it.
+
+
+
+
+
+
+ a #GDate
+
+
+
+ day
+
+
+
+ month
+
+
+
+ year
+
+
+
+
+
+ Sets the value of a #GDate from a Julian day number.
+
+
+
+
+
+
+ a #GDate
+
+
+
+ Julian day number (days since January 1, Year 1)
+
+
+
+
+
+ Sets the month of the year for a #GDate. If the resulting
+day-month-year triplet is invalid, the date will be invalid.
+
+
+
+
+
+
+ a #GDate
+
+
+
+ month to set
+
+
+
+
+
+ Parses a user-inputted string @str, and try to figure out what date it
+represents, taking the [current locale][setlocale] into account. If the
+string is successfully parsed, the date will be valid after the call.
+Otherwise, it will be invalid. You should check using g_date_valid()
+to see whether the parsing succeeded.
+
+This function is not appropriate for file formats and the like; it
+isn't very precise, and its exact behavior varies with the locale.
+It's intended to be a heuristic routine that guesses what the user
+means by a given string (and it does work pretty well in that
+capacity).
+
+
+
+
+
+
+ a #GDate to fill in
+
+
+
+ string to parse
+
+
+
+
+
+ Sets the value of a date from a #GTime value.
+The time to date conversion is done using the user's current timezone.
+ Use g_date_set_time_t() instead.
+
+
+
+
+
+
+ a #GDate.
+
+
+
+ #GTime value to set.
+
+
+
+
+
+ Sets the value of a date to the date corresponding to a time
+specified as a time_t. The time to date conversion is done using
+the user's current timezone.
+
+To set the value of a date to the current day, you could write:
+|[<!-- language="C" -->
+ time_t now = time (NULL);
+ if (now == (time_t) -1)
+ // handle the error
+ g_date_set_time_t (date, now);
+]|
+
+
+
+
+
+
+ a #GDate
+
+
+
+ time_t value to set
+
+
+
+
+
+ Sets the value of a date from a #GTimeVal value. Note that the
+@tv_usec member is ignored, because #GDate can't make use of the
+additional precision.
+
+The time to date conversion is done using the user's current timezone.
+ #GTimeVal is not year-2038-safe. Use g_date_set_time_t()
+ instead.
+
+
+
+
+
+
+ a #GDate
+
+
+
+ #GTimeVal value to set
+
+
+
+
+
+ Sets the year for a #GDate. If the resulting day-month-year
+triplet is invalid, the date will be invalid.
+
+
+
+
+
+
+ a #GDate
+
+
+
+ year to set
+
+
+
+
+
+ Moves a date some number of days into the past.
+To move by weeks, just move by weeks*7 days.
+The date must be valid.
+
+
+
+
+
+
+ a #GDate to decrement
+
+
+
+ number of days to move
+
+
+
+
+
+ Moves a date some number of months into the past.
+If the current day of the month doesn't exist in
+the destination month, the day of the month
+may change. The date must be valid.
+
+
+
+
+
+
+ a #GDate to decrement
+
+
+
+ number of months to move
+
+
+
+
+
+ Moves a date some number of years into the past.
+If the current day doesn't exist in the destination
+year (i.e. it's February 29 and you move to a non-leap-year)
+then the day is changed to February 29. The date
+must be valid.
+
+
+
+
+
+
+ a #GDate to decrement
+
+
+
+ number of years to move
+
+
+
+
+
+ Fills in the date-related bits of a struct tm using the @date value.
+Initializes the non-date parts with something safe but meaningless.
+
+
+
+
+
+
+ a #GDate to set the struct tm from
+
+
+
+ struct tm to fill
+
+
+
+
+
+ Returns %TRUE if the #GDate represents an existing day. The date must not
+contain garbage; it should have been initialized with g_date_clear()
+if it wasn't allocated by one of the g_date_new() variants.
+
+
+ Whether the date is valid
+
+
+
+
+ a #GDate to check
+
+
+
+
+
+ Returns the number of days in a month, taking leap
+years into account.
+
+
+ number of days in @month during the @year
+
+
+
+
+ month
+
+
+
+ year
+
+
+
+
+
+ Returns the number of weeks in the year, where weeks
+are taken to start on Monday. Will be 52 or 53. The
+date must be valid. (Years always have 52 7-day periods,
+plus 1 or 2 extra days depending on whether it's a leap
+year. This function is basically telling you how many
+Mondays are in the year, i.e. there are 53 Mondays if
+one of the extra days happens to be a Monday.)
+
+
+ number of Mondays in the year
+
+
+
+
+ a year
+
+
+
+
+
+ Returns the number of weeks in the year, where weeks
+are taken to start on Sunday. Will be 52 or 53. The
+date must be valid. (Years always have 52 7-day periods,
+plus 1 or 2 extra days depending on whether it's a leap
+year. This function is basically telling you how many
+Sundays are in the year, i.e. there are 53 Sundays if
+one of the extra days happens to be a Sunday.)
+
+
+ the number of weeks in @year
+
+
+
+
+ year to count weeks in
+
+
+
+
+
+ Returns %TRUE if the year is a leap year.
+
+For the purposes of this function, leap year is every year
+divisible by 4 unless that year is divisible by 100. If it
+is divisible by 100 it would be a leap year only if that year
+is also divisible by 400.
+
+
+ %TRUE if the year is a leap year
+
+
+
+
+ year to check
+
+
+
+
+
+ Generates a printed representation of the date, in a
+[locale][setlocale]-specific way.
+Works just like the platform's C library strftime() function,
+but only accepts date-related formats; time-related formats
+give undefined results. Date must be valid. Unlike strftime()
+(which uses the locale encoding), works on a UTF-8 format
+string and stores a UTF-8 result.
+
+This function does not provide any conversion specifiers in
+addition to those implemented by the platform's C library.
+For example, don't expect that using g_date_strftime() would
+make the \%F provided by the C99 strftime() work on Windows
+where the C library only complies to C89.
+
+
+ number of characters written to the buffer, or 0 the buffer was too small
+
+
+
+
+ destination buffer
+
+
+
+ buffer size
+
+
+
+ format string
+
+
+
+ valid #GDate
+
+
+
+
+
+ Returns %TRUE if the day of the month is valid (a day is valid if it's
+between 1 and 31 inclusive).
+
+
+ %TRUE if the day is valid
+
+
+
+
+ day to check
+
+
+
+
+
+ Returns %TRUE if the day-month-year triplet forms a valid, existing day
+in the range of days #GDate understands (Year 1 or later, no more than
+a few thousand years in the future).
+
+
+ %TRUE if the date is a valid one
+
+
+
+
+ day
+
+
+
+ month
+
+
+
+ year
+
+
+
+
+
+ Returns %TRUE if the Julian day is valid. Anything greater than zero
+is basically a valid Julian, though there is a 32-bit limit.
+
+
+ %TRUE if the Julian day is valid
+
+
+
+
+ Julian day to check
+
+
+
+
+
+ Returns %TRUE if the month value is valid. The 12 #GDateMonth
+enumeration values are the only valid months.
+
+
+ %TRUE if the month is valid
+
+
+
+
+ month
+
+
+
+
+
+ Returns %TRUE if the weekday is valid. The seven #GDateWeekday enumeration
+values are the only valid weekdays.
+
+
+ %TRUE if the weekday is valid
+
+
+
+
+ weekday
+
+
+
+
+
+ Returns %TRUE if the year is valid. Any year greater than 0 is valid,
+though there is a 16-bit limit to what #GDate will understand.
+
+
+ %TRUE if the year is valid
+
+
+
+
+ year
+
+
+
+
+
+
+ This enumeration isn't used in the API, but may be useful if you need
+to mark a number as a day, month, or year.
+
+
+ a day
+
+
+ a month
+
+
+ a year
+
+
+
+ Enumeration representing a month; values are %G_DATE_JANUARY,
+%G_DATE_FEBRUARY, etc. %G_DATE_BAD_MONTH is the invalid value.
+
+
+ invalid value
+
+
+ January
+
+
+ February
+
+
+ March
+
+
+ April
+
+
+ May
+
+
+ June
+
+
+ July
+
+
+ August
+
+
+ September
+
+
+ October
+
+
+ November
+
+
+ December
+
+
+
+ An opaque structure that represents a date and time, including a time zone.
+
+
+ Creates a new #GDateTime corresponding to the given date and time in
+the time zone @tz.
+
+The @year must be between 1 and 9999, @month between 1 and 12 and @day
+between 1 and 28, 29, 30 or 31 depending on the month and the year.
+
+@hour must be between 0 and 23 and @minute must be between 0 and 59.
+
+@seconds must be at least 0.0 and must be strictly less than 60.0.
+It will be rounded down to the nearest microsecond.
+
+If the given time is not representable in the given time zone (for
+example, 02:30 on March 14th 2010 in Toronto, due to daylight savings
+time) then the time will be rounded up to the nearest existing time
+(in this case, 03:00). If this matters to you then you should verify
+the return value for containing the same as the numbers you gave.
+
+In the case that the given time is ambiguous in the given time zone
+(for example, 01:30 on November 7th 2010 in Toronto, due to daylight
+savings time) then the time falling within standard (ie:
+non-daylight) time is taken.
+
+It not considered a programmer error for the values to this function
+to be out of range, but in the case that they are, the function will
+return %NULL.
+
+You should release the return value by calling g_date_time_unref()
+when you are done with it.
+
+
+ a new #GDateTime, or %NULL
+
+
+
+
+ a #GTimeZone
+
+
+
+ the year component of the date
+
+
+
+ the month component of the date
+
+
+
+ the day component of the date
+
+
+
+ the hour component of the date
+
+
+
+ the minute component of the date
+
+
+
+ the number of seconds past the minute
+
+
+
+
+
+ Creates a #GDateTime corresponding to the given
+[ISO 8601 formatted string](https://en.wikipedia.org/wiki/ISO_8601)
+@text. ISO 8601 strings of the form <date><sep><time><tz> are supported, with
+some extensions from [RFC 3339](https://tools.ietf.org/html/rfc3339) as
+mentioned below.
+
+Note that as #GDateTime "is oblivious to leap seconds", leap seconds information
+in an ISO-8601 string will be ignored, so a `23:59:60` time would be parsed as
+`23:59:59`.
+
+<sep> is the separator and can be either 'T', 't' or ' '. The latter two
+separators are an extension from
+[RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6).
+
+<date> is in the form:
+
+- `YYYY-MM-DD` - Year/month/day, e.g. 2016-08-24.
+- `YYYYMMDD` - Same as above without dividers.
+- `YYYY-DDD` - Ordinal day where DDD is from 001 to 366, e.g. 2016-237.
+- `YYYYDDD` - Same as above without dividers.
+- `YYYY-Www-D` - Week day where ww is from 01 to 52 and D from 1-7,
+ e.g. 2016-W34-3.
+- `YYYYWwwD` - Same as above without dividers.
+
+<time> is in the form:
+
+- `hh:mm:ss(.sss)` - Hours, minutes, seconds (subseconds), e.g. 22:10:42.123.
+- `hhmmss(.sss)` - Same as above without dividers.
+
+<tz> is an optional timezone suffix of the form:
+
+- `Z` - UTC.
+- `+hh:mm` or `-hh:mm` - Offset from UTC in hours and minutes, e.g. +12:00.
+- `+hh` or `-hh` - Offset from UTC in hours, e.g. +12.
+
+If the timezone is not provided in @text it must be provided in @default_tz
+(this field is otherwise ignored).
+
+This call can fail (returning %NULL) if @text is not a valid ISO 8601
+formatted string.
+
+You should release the return value by calling g_date_time_unref()
+when you are done with it.
+
+
+ a new #GDateTime, or %NULL
+
+
+
+
+ an ISO 8601 formatted time string.
+
+
+
+ a #GTimeZone to use if the text doesn't contain a
+ timezone, or %NULL.
+
+
+
+
+
+ Creates a #GDateTime corresponding to the given #GTimeVal @tv in the
+local time zone.
+
+The time contained in a #GTimeVal is always stored in the form of
+seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the
+local time offset.
+
+This call can fail (returning %NULL) if @tv represents a time outside
+of the supported range of #GDateTime.
+
+You should release the return value by calling g_date_time_unref()
+when you are done with it.
+ #GTimeVal is not year-2038-safe. Use
+ g_date_time_new_from_unix_local() instead.
+
+
+ a new #GDateTime, or %NULL
+
+
+
+
+ a #GTimeVal
+
+
+
+
+
+ Creates a #GDateTime corresponding to the given #GTimeVal @tv in UTC.
+
+The time contained in a #GTimeVal is always stored in the form of
+seconds elapsed since 1970-01-01 00:00:00 UTC.
+
+This call can fail (returning %NULL) if @tv represents a time outside
+of the supported range of #GDateTime.
+
+You should release the return value by calling g_date_time_unref()
+when you are done with it.
+ #GTimeVal is not year-2038-safe. Use
+ g_date_time_new_from_unix_utc() instead.
+
+
+ a new #GDateTime, or %NULL
+
+
+
+
+ a #GTimeVal
+
+
+
+
+
+ Creates a #GDateTime corresponding to the given Unix time @t in the
+local time zone.
+
+Unix time is the number of seconds that have elapsed since 1970-01-01
+00:00:00 UTC, regardless of the local time offset.
+
+This call can fail (returning %NULL) if @t represents a time outside
+of the supported range of #GDateTime.
+
+You should release the return value by calling g_date_time_unref()
+when you are done with it.
+
+
+ a new #GDateTime, or %NULL
+
+
+
+
+ the Unix time
+
+
+
+
+
+ Creates a #GDateTime corresponding to the given Unix time @t in UTC.
+
+Unix time is the number of seconds that have elapsed since 1970-01-01
+00:00:00 UTC.
+
+This call can fail (returning %NULL) if @t represents a time outside
+of the supported range of #GDateTime.
+
+You should release the return value by calling g_date_time_unref()
+when you are done with it.
+
+
+ a new #GDateTime, or %NULL
+
+
+
+
+ the Unix time
+
+
+
+
+
+ Creates a new #GDateTime corresponding to the given date and time in
+the local time zone.
+
+This call is equivalent to calling g_date_time_new() with the time
+zone returned by g_time_zone_new_local().
+
+
+ a #GDateTime, or %NULL
+
+
+
+
+ the year component of the date
+
+
+
+ the month component of the date
+
+
+
+ the day component of the date
+
+
+
+ the hour component of the date
+
+
+
+ the minute component of the date
+
+
+
+ the number of seconds past the minute
+
+
+
+
+
+ Creates a #GDateTime corresponding to this exact instant in the given
+time zone @tz. The time is as accurate as the system allows, to a
+maximum accuracy of 1 microsecond.
+
+This function will always succeed unless GLib is still being used after the
+year 9999.
+
+You should release the return value by calling g_date_time_unref()
+when you are done with it.
+
+
+ a new #GDateTime, or %NULL
+
+
+
+
+ a #GTimeZone
+
+
+
+
+
+ Creates a #GDateTime corresponding to this exact instant in the local
+time zone.
+
+This is equivalent to calling g_date_time_new_now() with the time
+zone returned by g_time_zone_new_local().
+
+
+ a new #GDateTime, or %NULL
+
+
+
+
+ Creates a #GDateTime corresponding to this exact instant in UTC.
+
+This is equivalent to calling g_date_time_new_now() with the time
+zone returned by g_time_zone_new_utc().
+
+
+ a new #GDateTime, or %NULL
+
+
+
+
+ Creates a new #GDateTime corresponding to the given date and time in
+UTC.
+
+This call is equivalent to calling g_date_time_new() with the time
+zone returned by g_time_zone_new_utc().
+
+
+ a #GDateTime, or %NULL
+
+
+
+
+ the year component of the date
+
+
+
+ the month component of the date
+
+
+
+ the day component of the date
+
+
+
+ the hour component of the date
+
+
+
+ the minute component of the date
+
+
+
+ the number of seconds past the minute
+
+
+
+
+
+ Creates a copy of @datetime and adds the specified timespan to the copy.
+
+
+ the newly created #GDateTime which
+ should be freed with g_date_time_unref(), or %NULL
+
+
+
+
+ a #GDateTime
+
+
+
+ a #GTimeSpan
+
+
+
+
+
+ Creates a copy of @datetime and adds the specified number of days to the
+copy. Add negative values to subtract days.
+
+
+ the newly created #GDateTime which
+ should be freed with g_date_time_unref(), or %NULL
+
+
+
+
+ a #GDateTime
+
+
+
+ the number of days
+
+
+
+
+
+ Creates a new #GDateTime adding the specified values to the current date and
+time in @datetime. Add negative values to subtract.
+
+
+ the newly created #GDateTime which
+ should be freed with g_date_time_unref(), or %NULL
+
+
+
+
+ a #GDateTime
+
+
+
+ the number of years to add
+
+
+
+ the number of months to add
+
+
+
+ the number of days to add
+
+
+
+ the number of hours to add
+
+
+
+ the number of minutes to add
+
+
+
+ the number of seconds to add
+
+
+
+
+
+ Creates a copy of @datetime and adds the specified number of hours.
+Add negative values to subtract hours.
+
+
+ the newly created #GDateTime which
+ should be freed with g_date_time_unref(), or %NULL
+
+
+
+
+ a #GDateTime
+
+
+
+ the number of hours to add
+
+
+
+
+
+ Creates a copy of @datetime adding the specified number of minutes.
+Add negative values to subtract minutes.
+
+
+ the newly created #GDateTime which
+ should be freed with g_date_time_unref(), or %NULL
+
+
+
+
+ a #GDateTime
+
+
+
+ the number of minutes to add
+
+
+
+
+
+ Creates a copy of @datetime and adds the specified number of months to the
+copy. Add negative values to subtract months.
+
+The day of the month of the resulting #GDateTime is clamped to the number
+of days in the updated calendar month. For example, if adding 1 month to
+31st January 2018, the result would be 28th February 2018. In 2020 (a leap
+year), the result would be 29th February.
+
+
+ the newly created #GDateTime which
+ should be freed with g_date_time_unref(), or %NULL
+
+
+
+
+ a #GDateTime
+
+
+
+ the number of months
+
+
+
+
+
+ Creates a copy of @datetime and adds the specified number of seconds.
+Add negative values to subtract seconds.
+
+
+ the newly created #GDateTime which
+ should be freed with g_date_time_unref(), or %NULL
+
+
+
+
+ a #GDateTime
+
+
+
+ the number of seconds to add
+
+
+
+
+
+ Creates a copy of @datetime and adds the specified number of weeks to the
+copy. Add negative values to subtract weeks.
+
+
+ the newly created #GDateTime which
+ should be freed with g_date_time_unref(), or %NULL
+
+
+
+
+ a #GDateTime
+
+
+
+ the number of weeks
+
+
+
+
+
+ Creates a copy of @datetime and adds the specified number of years to the
+copy. Add negative values to subtract years.
+
+As with g_date_time_add_months(), if the resulting date would be 29th
+February on a non-leap year, the day will be clamped to 28th February.
+
+
+ the newly created #GDateTime which
+ should be freed with g_date_time_unref(), or %NULL
+
+
+
+
+ a #GDateTime
+
+
+
+ the number of years
+
+
+
+
+
+ A comparison function for #GDateTimes that is suitable
+as a #GCompareFunc. Both #GDateTimes must be non-%NULL.
+
+
+ -1, 0 or 1 if @dt1 is less than, equal to or greater
+ than @dt2.
+
+
+
+
+ first #GDateTime to compare
+
+
+
+ second #GDateTime to compare
+
+
+
+
+
+ Calculates the difference in time between @end and @begin. The
+#GTimeSpan that is returned is effectively @end - @begin (ie:
+positive if the first parameter is larger).
+
+
+ the difference between the two #GDateTime, as a time
+ span expressed in microseconds.
+
+
+
+
+ a #GDateTime
+
+
+
+ a #GDateTime
+
+
+
+
+
+ Checks to see if @dt1 and @dt2 are equal.
+
+Equal here means that they represent the same moment after converting
+them to the same time zone.
+
+
+ %TRUE if @dt1 and @dt2 are equal
+
+
+
+
+ a #GDateTime
+
+
+
+ a #GDateTime
+
+
+
+
+
+ Creates a newly allocated string representing the requested @format.
+
+The format strings understood by this function are a subset of the
+strftime() format language as specified by C99. The \%D, \%U and \%W
+conversions are not supported, nor is the 'E' modifier. The GNU
+extensions \%k, \%l, \%s and \%P are supported, however, as are the
+'0', '_' and '-' modifiers. The Python extension \%f is also supported.
+
+In contrast to strftime(), this function always produces a UTF-8
+string, regardless of the current locale. Note that the rendering of
+many formats is locale-dependent and may not match the strftime()
+output exactly.
+
+The following format specifiers are supported:
+
+- \%a: the abbreviated weekday name according to the current locale
+- \%A: the full weekday name according to the current locale
+- \%b: the abbreviated month name according to the current locale
+- \%B: the full month name according to the current locale
+- \%c: the preferred date and time representation for the current locale
+- \%C: the century number (year/100) as a 2-digit integer (00-99)
+- \%d: the day of the month as a decimal number (range 01 to 31)
+- \%e: the day of the month as a decimal number (range 1 to 31);
+ single digits are preceded by a figure space
+- \%F: equivalent to `%Y-%m-%d` (the ISO 8601 date format)
+- \%g: the last two digits of the ISO 8601 week-based year as a
+ decimal number (00-99). This works well with \%V and \%u.
+- \%G: the ISO 8601 week-based year as a decimal number. This works
+ well with \%V and \%u.
+- \%h: equivalent to \%b
+- \%H: the hour as a decimal number using a 24-hour clock (range 00 to 23)
+- \%I: the hour as a decimal number using a 12-hour clock (range 01 to 12)
+- \%j: the day of the year as a decimal number (range 001 to 366)
+- \%k: the hour (24-hour clock) as a decimal number (range 0 to 23);
+ single digits are preceded by a figure space
+- \%l: the hour (12-hour clock) as a decimal number (range 1 to 12);
+ single digits are preceded by a figure space
+- \%m: the month as a decimal number (range 01 to 12)
+- \%M: the minute as a decimal number (range 00 to 59)
+- \%f: the microsecond as a decimal number (range 000000 to 999999)
+- \%p: either "AM" or "PM" according to the given time value, or the
+ corresponding strings for the current locale. Noon is treated as
+ "PM" and midnight as "AM". Use of this format specifier is discouraged, as
+ many locales have no concept of AM/PM formatting. Use \%c or \%X instead.
+- \%P: like \%p but lowercase: "am" or "pm" or a corresponding string for
+ the current locale. Use of this format specifier is discouraged, as
+ many locales have no concept of AM/PM formatting. Use \%c or \%X instead.
+- \%r: the time in a.m. or p.m. notation. Use of this format specifier is
+ discouraged, as many locales have no concept of AM/PM formatting. Use \%c
+ or \%X instead.
+- \%R: the time in 24-hour notation (\%H:\%M)
+- \%s: the number of seconds since the Epoch, that is, since 1970-01-01
+ 00:00:00 UTC
+- \%S: the second as a decimal number (range 00 to 60)
+- \%t: a tab character
+- \%T: the time in 24-hour notation with seconds (\%H:\%M:\%S)
+- \%u: the ISO 8601 standard day of the week as a decimal, range 1 to 7,
+ Monday being 1. This works well with \%G and \%V.
+- \%V: the ISO 8601 standard week number of the current year as a decimal
+ number, range 01 to 53, where week 1 is the first week that has at
+ least 4 days in the new year. See g_date_time_get_week_of_year().
+ This works well with \%G and \%u.
+- \%w: the day of the week as a decimal, range 0 to 6, Sunday being 0.
+ This is not the ISO 8601 standard format -- use \%u instead.
+- \%x: the preferred date representation for the current locale without
+ the time
+- \%X: the preferred time representation for the current locale without
+ the date
+- \%y: the year as a decimal number without the century
+- \%Y: the year as a decimal number including the century
+- \%z: the time zone as an offset from UTC (+hhmm)
+- \%:z: the time zone as an offset from UTC (+hh:mm).
+ This is a gnulib strftime() extension. Since: 2.38
+- \%::z: the time zone as an offset from UTC (+hh:mm:ss). This is a
+ gnulib strftime() extension. Since: 2.38
+- \%:::z: the time zone as an offset from UTC, with : to necessary
+ precision (e.g., -04, +05:30). This is a gnulib strftime() extension. Since: 2.38
+- \%Z: the time zone or name or abbreviation
+- \%\%: a literal \% character
+
+Some conversion specifications can be modified by preceding the
+conversion specifier by one or more modifier characters. The
+following modifiers are supported for many of the numeric
+conversions:
+
+- O: Use alternative numeric symbols, if the current locale supports those.
+- _: Pad a numeric result with spaces. This overrides the default padding
+ for the specifier.
+- -: Do not pad a numeric result. This overrides the default padding
+ for the specifier.
+- 0: Pad a numeric result with zeros. This overrides the default padding
+ for the specifier.
+
+Additionally, when O is used with B, b, or h, it produces the alternative
+form of a month name. The alternative form should be used when the month
+name is used without a day number (e.g., standalone). It is required in
+some languages (Baltic, Slavic, Greek, and more) due to their grammatical
+rules. For other languages there is no difference. \%OB is a GNU and BSD
+strftime() extension expected to be added to the future POSIX specification,
+\%Ob and \%Oh are GNU strftime() extensions. Since: 2.56
+
+
+ a newly allocated string formatted to
+ the requested format or %NULL in the case that there was an error (such
+ as a format specifier not being supported in the current locale). The
+ string should be freed with g_free().
+
+
+
+
+ A #GDateTime
+
+
+
+ a valid UTF-8 string, containing the format for the
+ #GDateTime
+
+
+
+
+
+ Format @datetime in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601),
+including the date, time and time zone, and return that as a UTF-8 encoded
+string.
+
+Since GLib 2.66, this will output to sub-second precision if needed.
+
+
+ a newly allocated string formatted in
+ ISO 8601 format or %NULL in the case that there was an error. The string
+ should be freed with g_free().
+
+
+
+
+ A #GDateTime
+
+
+
+
+
+ Retrieves the day of the month represented by @datetime in the gregorian
+calendar.
+
+
+ the day of the month
+
+
+
+
+ a #GDateTime
+
+
+
+
+
+ Retrieves the ISO 8601 day of the week on which @datetime falls (1 is
+Monday, 2 is Tuesday... 7 is Sunday).
+
+
+ the day of the week
+
+
+
+
+ a #GDateTime
+
+
+
+
+
+ Retrieves the day of the year represented by @datetime in the Gregorian
+calendar.
+
+
+ the day of the year
+
+
+
+
+ a #GDateTime
+
+
+
+
+
+ Retrieves the hour of the day represented by @datetime
+
+
+ the hour of the day
+
+
+
+
+ a #GDateTime
+
+
+
+
+
+ Retrieves the microsecond of the date represented by @datetime
+
+
+ the microsecond of the second
+
+
+
+
+ a #GDateTime
+
+
+
+
+
+ Retrieves the minute of the hour represented by @datetime
+
+
+ the minute of the hour
+
+
+
+
+ a #GDateTime
+
+
+
+
+
+ Retrieves the month of the year represented by @datetime in the Gregorian
+calendar.
+
+
+ the month represented by @datetime
+
+
+
+
+ a #GDateTime
+
+
+
+
+
+ Retrieves the second of the minute represented by @datetime
+
+
+ the second represented by @datetime
+
+
+
+
+ a #GDateTime
+
+
+
+
+
+ Retrieves the number of seconds since the start of the last minute,
+including the fractional part.
+
+
+ the number of seconds
+
+
+
+
+ a #GDateTime
+
+
+
+
+
+ Get the time zone for this @datetime.
+
+
+ the time zone
+
+
+
+
+ a #GDateTime
+
+
+
+
+
+ Determines the time zone abbreviation to be used at the time and in
+the time zone of @datetime.
+
+For example, in Toronto this is currently "EST" during the winter
+months and "EDT" during the summer months when daylight savings
+time is in effect.
+
+
+ the time zone abbreviation. The returned
+ string is owned by the #GDateTime and it should not be
+ modified or freed
+
+
+
+
+ a #GDateTime
+
+
+
+
+
+ Determines the offset to UTC in effect at the time and in the time
+zone of @datetime.
+
+The offset is the number of microseconds that you add to UTC time to
+arrive at local time for the time zone (ie: negative numbers for time
+zones west of GMT, positive numbers for east).
+
+If @datetime represents UTC time, then the offset is always zero.
+
+
+ the number of microseconds that should be added to UTC to
+ get the local time
+
+
+
+
+ a #GDateTime
+
+
+
+
+
+ Returns the ISO 8601 week-numbering year in which the week containing
+@datetime falls.
+
+This function, taken together with g_date_time_get_week_of_year() and
+g_date_time_get_day_of_week() can be used to determine the full ISO
+week date on which @datetime falls.
+
+This is usually equal to the normal Gregorian year (as returned by
+g_date_time_get_year()), except as detailed below:
+
+For Thursday, the week-numbering year is always equal to the usual
+calendar year. For other days, the number is such that every day
+within a complete week (Monday to Sunday) is contained within the
+same week-numbering year.
+
+For Monday, Tuesday and Wednesday occurring near the end of the year,
+this may mean that the week-numbering year is one greater than the
+calendar year (so that these days have the same week-numbering year
+as the Thursday occurring early in the next year).
+
+For Friday, Saturday and Sunday occurring near the start of the year,
+this may mean that the week-numbering year is one less than the
+calendar year (so that these days have the same week-numbering year
+as the Thursday occurring late in the previous year).
+
+An equivalent description is that the week-numbering year is equal to
+the calendar year containing the majority of the days in the current
+week (Monday to Sunday).
+
+Note that January 1 0001 in the proleptic Gregorian calendar is a
+Monday, so this function never returns 0.
+
+
+ the ISO 8601 week-numbering year for @datetime
+
+
+
+
+ a #GDateTime
+
+
+
+
+
+ Returns the ISO 8601 week number for the week containing @datetime.
+The ISO 8601 week number is the same for every day of the week (from
+Moday through Sunday). That can produce some unusual results
+(described below).
+
+The first week of the year is week 1. This is the week that contains
+the first Thursday of the year. Equivalently, this is the first week
+that has more than 4 of its days falling within the calendar year.
+
+The value 0 is never returned by this function. Days contained
+within a year but occurring before the first ISO 8601 week of that
+year are considered as being contained in the last week of the
+previous year. Similarly, the final days of a calendar year may be
+considered as being part of the first ISO 8601 week of the next year
+if 4 or more days of that week are contained within the new year.
+
+
+ the ISO 8601 week number for @datetime.
+
+
+
+
+ a #GDateTime
+
+
+
+
+
+ Retrieves the year represented by @datetime in the Gregorian calendar.
+
+
+ the year represented by @datetime
+
+
+
+
+ A #GDateTime
+
+
+
+
+
+ Retrieves the Gregorian day, month, and year of a given #GDateTime.
+
+
+
+
+
+
+ a #GDateTime.
+
+
+
+ the return location for the gregorian year, or %NULL.
+
+
+
+ the return location for the month of the year, or %NULL.
+
+
+
+ the return location for the day of the month, or %NULL.
+
+
+
+
+
+ Hashes @datetime into a #guint, suitable for use within #GHashTable.
+
+
+ a #guint containing the hash
+
+
+
+
+ a #GDateTime
+
+
+
+
+
+ Determines if daylight savings time is in effect at the time and in
+the time zone of @datetime.
+
+
+ %TRUE if daylight savings time is in effect
+
+
+
+
+ a #GDateTime
+
+
+
+
+
+ Atomically increments the reference count of @datetime by one.
+
+
+ the #GDateTime with the reference count increased
+
+
+
+
+ a #GDateTime
+
+
+
+
+
+ Creates a new #GDateTime corresponding to the same instant in time as
+@datetime, but in the local time zone.
+
+This call is equivalent to calling g_date_time_to_timezone() with the
+time zone returned by g_time_zone_new_local().
+
+
+ the newly created #GDateTime which
+ should be freed with g_date_time_unref(), or %NULL
+
+
+
+
+ a #GDateTime
+
+
+
+
+
+ Stores the instant in time that @datetime represents into @tv.
+
+The time contained in a #GTimeVal is always stored in the form of
+seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the time
+zone associated with @datetime.
+
+On systems where 'long' is 32bit (ie: all 32bit systems and all
+Windows systems), a #GTimeVal is incapable of storing the entire
+range of values that #GDateTime is capable of expressing. On those
+systems, this function returns %FALSE to indicate that the time is
+out of range.
+
+On systems where 'long' is 64bit, this function never fails.
+ #GTimeVal is not year-2038-safe. Use
+ g_date_time_to_unix() instead.
+
+
+ %TRUE if successful, else %FALSE
+
+
+
+
+ a #GDateTime
+
+
+
+ a #GTimeVal to modify
+
+
+
+
+
+ Create a new #GDateTime corresponding to the same instant in time as
+@datetime, but in the time zone @tz.
+
+This call can fail in the case that the time goes out of bounds. For
+example, converting 0001-01-01 00:00:00 UTC to a time zone west of
+Greenwich will fail (due to the year 0 being out of range).
+
+
+ the newly created #GDateTime which
+ should be freed with g_date_time_unref(), or %NULL
+
+
+
+
+ a #GDateTime
+
+
+
+ the new #GTimeZone
+
+
+
+
+
+ Gives the Unix time corresponding to @datetime, rounding down to the
+nearest second.
+
+Unix time is the number of seconds that have elapsed since 1970-01-01
+00:00:00 UTC, regardless of the time zone associated with @datetime.
+
+
+ the Unix time corresponding to @datetime
+
+
+
+
+ a #GDateTime
+
+
+
+
+
+ Creates a new #GDateTime corresponding to the same instant in time as
+@datetime, but in UTC.
+
+This call is equivalent to calling g_date_time_to_timezone() with the
+time zone returned by g_time_zone_new_utc().
+
+
+ the newly created #GDateTime which
+ should be freed with g_date_time_unref(), or %NULL
+
+
+
+
+ a #GDateTime
+
+
+
+
+
+ Atomically decrements the reference count of @datetime by one.
+
+When the reference count reaches zero, the resources allocated by
+@datetime are freed
+
+
+
+
+
+
+ a #GDateTime
+
+
+
+
+
+
+ Enumeration representing a day of the week; %G_DATE_MONDAY,
+%G_DATE_TUESDAY, etc. %G_DATE_BAD_WEEKDAY is an invalid weekday.
+
+
+ invalid value
+
+
+ Monday
+
+
+ Tuesday
+
+
+ Wednesday
+
+
+ Thursday
+
+
+ Friday
+
+
+ Saturday
+
+
+ Sunday
+
+
+
+ Associates a string with a bit flag.
+Used in g_parse_debug_string().
+
+
+ the string
+
+
+
+ the flag
+
+
+
+
+ Specifies the type of function which is called when a data element
+is destroyed. It is passed the pointer to the data element and
+should free any memory and resources allocated for it.
+
+
+
+
+
+
+ the data element.
+
+
+
+
+
+ An opaque structure representing an opened directory.
+
+
+ Closes the directory and deallocates all related resources.
+
+
+
+
+
+
+ a #GDir* created by g_dir_open()
+
+
+
+
+
+ Retrieves the name of another entry in the directory, or %NULL.
+The order of entries returned from this function is not defined,
+and may vary by file system or other operating-system dependent
+factors.
+
+%NULL may also be returned in case of errors. On Unix, you can
+check `errno` to find out if %NULL was returned because of an error.
+
+On Unix, the '.' and '..' entries are omitted, and the returned
+name is in the on-disk encoding.
+
+On Windows, as is true of all GLib functions which operate on
+filenames, the returned name is in UTF-8.
+
+
+ The entry's name or %NULL if there are no
+ more entries. The return value is owned by GLib and
+ must not be modified or freed.
+
+
+
+
+ a #GDir* created by g_dir_open()
+
+
+
+
+
+ Resets the given directory. The next call to g_dir_read_name()
+will return the first entry again.
+
+
+
+
+
+
+ a #GDir* created by g_dir_open()
+
+
+
+
+
+ Creates a subdirectory in the preferred directory for temporary
+files (as returned by g_get_tmp_dir()).
+
+@tmpl should be a string in the GLib file name encoding containing
+a sequence of six 'X' characters, as the parameter to g_mkstemp().
+However, unlike these functions, the template should only be a
+basename, no directory components are allowed. If template is
+%NULL, a default template is used.
+
+Note that in contrast to g_mkdtemp() (and mkdtemp()) @tmpl is not
+modified, and might thus be a read-only literal string.
+
+
+ The actual name used. This string
+ should be freed with g_free() when not needed any longer and is
+ is in the GLib file name encoding. In case of errors, %NULL is
+ returned and @error will be set.
+
+
+
+
+ Template for directory name,
+ as in g_mkdtemp(), basename only, or %NULL for a default template
+
+
+
+
+
+ Opens a directory for reading. The names of the files in the
+directory can then be retrieved using g_dir_read_name(). Note
+that the ordering is not defined.
+
+
+ a newly allocated #GDir on success, %NULL on failure.
+ If non-%NULL, you must free the result with g_dir_close()
+ when you are finished with it.
+
+
+
+
+ the path to the directory you are interested in. On Unix
+ in the on-disk encoding. On Windows in UTF-8
+
+
+
+ Currently must be set to 0. Reserved for future use.
+
+
+
+
+
+
+ The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign,
+mantissa and exponent of IEEE floats and doubles. These unions are defined
+as appropriate for a given platform. IEEE floats and doubles are supported
+(used for storage) by at least Intel, PPC and Sparc.
+
+
+ the double value
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The type of functions that are used to 'duplicate' an object.
+What this means depends on the context, it could just be
+incrementing the reference count, if @data is a ref-counted
+object.
+
+
+ a duplicate of data
+
+
+
+
+ the data to duplicate
+
+
+
+ user data that was specified in
+ g_datalist_id_dup_data()
+
+
+
+
+
+ The base of natural logarithms.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Specifies the type of a function used to test two values for
+equality. The function should return %TRUE if both values are equal
+and %FALSE otherwise.
+
+
+ %TRUE if @a = @b; %FALSE otherwise
+
+
+
+
+ a value
+
+
+
+ a value to compare with
+
+
+
+
+
+ Specifies the type of a function used to test two values for
+equality. The function should return %TRUE if both values are equal
+and %FALSE otherwise.
+
+This is a version of #GEqualFunc which provides a @user_data closure from
+the caller.
+
+
+ %TRUE if @a = @b; %FALSE otherwise
+
+
+
+
+ a value
+
+
+
+ a value to compare with
+
+
+
+ user data provided by the caller
+
+
+
+
+
+ The `GError` structure contains information about
+an error that has occurred.
+
+
+ error domain, e.g. %G_FILE_ERROR
+
+
+
+ error code, e.g. %G_FILE_ERROR_NOENT
+
+
+
+ human-readable informative error message
+
+
+
+ Creates a new #GError with the given @domain and @code,
+and a message formatted with @format.
+
+
+ a new #GError
+
+
+
+
+ error domain
+
+
+
+ error code
+
+
+
+ printf()-style format for error message
+
+
+
+ parameters for message format
+
+
+
+
+
+ Creates a new #GError; unlike g_error_new(), @message is
+not a printf()-style format string. Use this function if
+@message contains text you don't have control over,
+that could include printf() escape sequences.
+
+
+ a new #GError
+
+
+
+
+ error domain
+
+
+
+ error code
+
+
+
+ error message
+
+
+
+
+
+ Creates a new #GError with the given @domain and @code,
+and a message formatted with @format.
+
+
+ a new #GError
+
+
+
+
+ error domain
+
+
+
+ error code
+
+
+
+ printf()-style format for error message
+
+
+
+ #va_list of parameters for the message format
+
+
+
+
+
+ Makes a copy of @error.
+
+
+ a new #GError
+
+
+
+
+ a #GError
+
+
+
+
+
+ Frees a #GError and associated resources.
+
+
+
+
+
+
+ a #GError
+
+
+
+
+
+ Returns %TRUE if @error matches @domain and @code, %FALSE
+otherwise. In particular, when @error is %NULL, %FALSE will
+be returned.
+
+If @domain contains a `FAILED` (or otherwise generic) error code,
+you should generally not check for it explicitly, but should
+instead treat any not-explicitly-recognized error code as being
+equivalent to the `FAILED` code. This way, if the domain is
+extended in the future to provide a more specific error code for
+a certain case, your code will still work.
+
+
+ whether @error has @domain and @code
+
+
+
+
+ a #GError
+
+
+
+ an error domain
+
+
+
+ an error code
+
+
+
+
+
+ This function registers an extended #GError domain.
+@error_type_name will be duplicated. Otherwise does the same as
+g_error_domain_register_static().
+
+
+ #GQuark representing the error domain
+
+
+
+
+ string to create a #GQuark from
+
+
+
+ size of the private error data in bytes
+
+
+
+ function initializing fields of the private error data
+
+
+
+ function copying fields of the private error data
+
+
+
+ function freeing fields of the private error data
+
+
+
+
+
+ This function registers an extended #GError domain.
+
+@error_type_name should not be freed. @error_type_private_size must
+be greater than 0.
+
+@error_type_init receives an initialized #GError and should then initialize
+the private data.
+
+@error_type_copy is a function that receives both original and a copy
+#GError and should copy the fields of the private error data. The standard
+#GError fields are already handled.
+
+@error_type_clear receives the pointer to the error, and it should free the
+fields of the private error data. It should not free the struct itself though.
+
+Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it
+already takes care of passing valid information to this function.
+
+
+ #GQuark representing the error domain
+
+
+
+
+ static string to create a #GQuark from
+
+
+
+ size of the private error data in bytes
+
+
+
+ function initializing fields of the private error data
+
+
+
+ function copying fields of the private error data
+
+
+
+ function freeing fields of the private error data
+
+
+
+
+
+
+ Specifies the type of function which is called when an extended
+error instance is freed. It is passed the error pointer about to be
+freed, and should free the error's private data fields.
+
+Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it
+already takes care of getting the private data from @error.
+
+
+
+
+
+
+ extended error to clear
+
+
+
+
+
+ Specifies the type of function which is called when an extended
+error instance is copied. It is passed the pointer to the
+destination error and source error, and should copy only the fields
+of the private data from @src_error to @dest_error.
+
+Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it
+already takes care of getting the private data from @src_error and
+@dest_error.
+
+
+
+
+
+
+ source extended error
+
+
+
+ destination extended error
+
+
+
+
+
+ Specifies the type of function which is called just after an
+extended error instance is created and its fields filled. It should
+only initialize the fields in the private data, which can be
+received with the generated `*_get_private()` function.
+
+Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it
+already takes care of getting the private data from @error.
+
+
+
+
+
+
+ extended error
+
+
+
+
+
+ The possible errors, used in the @v_error field
+of #GTokenValue, when the token is a %G_TOKEN_ERROR.
+
+
+ unknown error
+
+
+ unexpected end of file
+
+
+ unterminated string constant
+
+
+ unterminated comment
+
+
+ non-digit character in a number
+
+
+ digit beyond radix in a number
+
+
+ non-decimal floating point number
+
+
+ malformed floating point number
+
+
+
+ Values corresponding to @errno codes returned from file operations
+on UNIX. Unlike @errno codes, GFileError values are available on
+all systems, even Windows. The exact meaning of each code depends
+on what sort of file operation you were performing; the UNIX
+documentation gives more details. The following error code descriptions
+come from the GNU C Library manual, and are under the copyright
+of that manual.
+
+It's not very portable to make detailed assumptions about exactly
+which errors will be returned from a given operation. Some errors
+don't occur on some systems, etc., sometimes there are subtle
+differences in when a system will report a given error, etc.
+
+
+ Operation not permitted; only the owner of
+ the file (or other resource) or processes with special privileges
+ can perform the operation.
+
+
+ File is a directory; you cannot open a directory
+ for writing, or create or remove hard links to it.
+
+
+ Permission denied; the file permissions do not
+ allow the attempted operation.
+
+
+ Filename too long.
+
+
+ No such file or directory. This is a "file
+ doesn't exist" error for ordinary files that are referenced in
+ contexts where they are expected to already exist.
+
+
+ A file that isn't a directory was specified when
+ a directory is required.
+
+
+ No such device or address. The system tried to
+ use the device represented by a file you specified, and it
+ couldn't find the device. This can mean that the device file was
+ installed incorrectly, or that the physical device is missing or
+ not correctly attached to the computer.
+
+
+ The underlying file system of the specified file
+ does not support memory mapping.
+
+
+ The directory containing the new link can't be
+ modified because it's on a read-only file system.
+
+
+ Text file busy.
+
+
+ You passed in a pointer to bad memory.
+ (GLib won't reliably return this, don't pass in pointers to bad
+ memory.)
+
+
+ Too many levels of symbolic links were encountered
+ in looking up a file name. This often indicates a cycle of symbolic
+ links.
+
+
+ No space left on device; write operation on a
+ file failed because the disk is full.
+
+
+ No memory available. The system cannot allocate
+ more virtual memory because its capacity is full.
+
+
+ The current process has too many files open and
+ can't open any more. Duplicate descriptors do count toward this
+ limit.
+
+
+ There are too many distinct file openings in the
+ entire system.
+
+
+ Bad file descriptor; for example, I/O on a
+ descriptor that has been closed or reading from a descriptor open
+ only for writing (or vice versa).
+
+
+ Invalid argument. This is used to indicate
+ various kinds of problems with passing the wrong argument to a
+ library function.
+
+
+ Broken pipe; there is no process reading from the
+ other end of a pipe. Every library function that returns this
+ error code also generates a 'SIGPIPE' signal; this signal
+ terminates the program if not handled or blocked. Thus, your
+ program will never actually see this code unless it has handled
+ or blocked 'SIGPIPE'.
+
+
+ Resource temporarily unavailable; the call might
+ work if you try again later.
+
+
+ Interrupted function call; an asynchronous signal
+ occurred and prevented completion of the call. When this
+ happens, you should try the call again.
+
+
+ Input/output error; usually used for physical read
+ or write errors. i.e. the disk or other physical device hardware
+ is returning errors.
+
+
+ Operation not permitted; only the owner of the
+ file (or other resource) or processes with special privileges can
+ perform the operation.
+
+
+ Function not implemented; this indicates that
+ the system is missing some functionality.
+
+
+ Does not correspond to a UNIX error code; this
+ is the standard "failed for unspecified reason" error code present
+ in all #GError error code enumerations. Returned if no specific
+ code applies.
+
+
+
+ Flags to pass to g_file_set_contents_full() to affect its safety and
+performance.
+
+
+ No guarantees about file consistency or durability.
+ The most dangerous setting, which is slightly faster than other settings.
+
+
+ Guarantee file consistency: after a crash,
+ either the old version of the file or the new version of the file will be
+ available, but not a mixture. On Unix systems this equates to an `fsync()`
+ on the file and use of an atomic `rename()` of the new version of the file
+ over the old.
+
+
+ Guarantee file durability: after a crash, the
+ new version of the file will be available. On Unix systems this equates to
+ an `fsync()` on the file (if %G_FILE_SET_CONTENTS_CONSISTENT is unset), or
+ the effects of %G_FILE_SET_CONTENTS_CONSISTENT plus an `fsync()` on the
+ directory containing the file after calling `rename()`.
+
+
+ Only apply consistency and durability
+ guarantees if the file already exists. This may speed up file operations
+ if the file doesn’t currently exist, but may result in a corrupted version
+ of the new file if the system crashes while writing it.
+
+
+
+ A test to perform on a file using g_file_test().
+
+
+ %TRUE if the file is a regular file
+ (not a directory). Note that this test will also return %TRUE
+ if the tested file is a symlink to a regular file.
+
+
+ %TRUE if the file is a symlink.
+
+
+ %TRUE if the file is a directory.
+
+
+ %TRUE if the file is executable.
+
+
+ %TRUE if the file exists. It may or may not
+ be a regular file.
+
+
+
+ The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign,
+mantissa and exponent of IEEE floats and doubles. These unions are defined
+as appropriate for a given platform. IEEE floats and doubles are supported
+(used for storage) by at least Intel, PPC and Sparc.
+
+
+ the double value
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Flags to modify the format of the string returned by g_format_size_full().
+
+
+ behave the same as g_format_size()
+
+
+ include the exact number of bytes as part
+ of the returned string. For example, "45.6 kB (45,612 bytes)".
+
+
+ use IEC (base 1024) units with "KiB"-style
+ suffixes. IEC units should only be used for reporting things with
+ a strong "power of 2" basis, like RAM sizes or RAID stripe sizes.
+ Network and storage sizes should be reported in the normal SI units.
+
+
+ set the size as a quantity in bits, rather than
+ bytes, and return units in bits. For example, ‘Mb’ rather than ‘MB’.
+
+
+ return only value, without unit; this should
+ not be used together with @G_FORMAT_SIZE_LONG_FORMAT
+ nor @G_FORMAT_SIZE_ONLY_UNIT. Since: 2.74
+
+
+ return only unit, without value; this should
+ not be used together with @G_FORMAT_SIZE_LONG_FORMAT
+ nor @G_FORMAT_SIZE_ONLY_VALUE. Since: 2.74
+
+
+
+ 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+.
+
+
+
+
+
+
+ a data pointer
+
+
+
+
+
+ Specifies the type of functions passed to g_list_foreach() and
+g_slist_foreach().
+
+
+
+
+
+
+ the element's data
+
+
+
+ user data passed to g_list_foreach() or g_slist_foreach()
+
+
+
+
+
+ This is the platform dependent conversion specifier for scanning and
+printing values of type #gint16. It is a string literal, but doesn't
+include the percent-sign, such that you can add precision and length
+modifiers between percent-sign and conversion specifier.
+
+|[<!-- language="C" -->
+gint16 in;
+gint32 out;
+sscanf ("42", "%" G_GINT16_FORMAT, &in)
+out = in * 1000;
+g_print ("%" G_GINT32_FORMAT, out);
+
+This is not necessarily the correct format for printing and scanning
+`int16_t` values, even though the in-memory representation is the same.
+Standard C macros like `PRId16` and `SCNd16` should be used for `int16_t`.
+]|
+
+
+
+
+ The platform dependent length modifier for conversion specifiers
+for scanning and printing values of type #gint16 or #guint16. It
+is a string literal, but doesn't include the percent-sign, such
+that you can add precision and length modifiers between percent-sign
+and conversion specifier and append a conversion specifier.
+
+The following example prints "0x7b";
+|[<!-- language="C" -->
+gint16 value = 123;
+g_print ("%#" G_GINT16_MODIFIER "x", value);
+]|
+
+This is not necessarily the correct modifier for printing and scanning
+`int16_t` values, even though the in-memory representation is the same.
+Standard C macros like `PRId16` and `SCNd16` should be used for `int16_t`.
+
+
+
+
+ This is the platform dependent conversion specifier for scanning
+and printing values of type #gint32. See also %G_GINT16_FORMAT.
+
+This is not necessarily the correct modifier for printing and scanning
+`int32_t` values, even though the in-memory representation is the same.
+Standard C macros like `PRId32` and `SCNd32` should be used for `int32_t`.
+
+
+
+
+ The platform dependent length modifier for conversion specifiers
+for scanning and printing values of type #gint32 or #guint32. It
+is a string literal. See also %G_GINT16_MODIFIER.
+
+This is not necessarily the correct modifier for printing and scanning
+`int32_t` values, even though the in-memory representation is the same.
+Standard C macros like `PRId32` and `SCNd32` should be used for `int32_t`.
+
+
+
+
+ This macro is used to insert 64-bit integer literals
+into the source code.
+
+It is similar to the standard C `INT64_C` macro,
+which should be preferred in new code.
+
+
+
+ a literal integer value, e.g. 0x1d636b02300a7aa7
+
+
+
+
+ This is the platform dependent conversion specifier for scanning
+and printing values of type #gint64. See also %G_GINT16_FORMAT.
+
+Some platforms do not support scanning and printing 64-bit integers,
+even though the types are supported. On such platforms %G_GINT64_FORMAT
+is not defined. Note that scanf() may not support 64-bit integers, even
+if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf()
+is not recommended for parsing anyway; consider using g_ascii_strtoull()
+instead.
+
+This is not necessarily the correct format for printing and scanning
+`int64_t` values, even though the in-memory representation is the same.
+Standard C macros like `PRId64` and `SCNd64` should be used for `int64_t`.
+
+
+
+
+ The platform dependent length modifier for conversion specifiers
+for scanning and printing values of type #gint64 or #guint64.
+It is a string literal.
+
+Some platforms do not support printing 64-bit integers, even
+though the types are supported. On such platforms %G_GINT64_MODIFIER
+is not defined.
+
+This is not necessarily the correct modifier for printing and scanning
+`int64_t` values, even though the in-memory representation is the same.
+Standard C macros like `PRId64` and `SCNd64` should be used for `int64_t`.
+
+
+
+
+ This is the platform dependent conversion specifier for scanning
+and printing values of type #gintptr.
+
+Note that this is not necessarily the correct format to scan or
+print an `intptr_t`, even though the in-memory representation is the
+same.
+Standard C macros like `PRIdPTR` and `SCNdPTR` should be used for
+`intptr_t`.
+
+
+
+
+ The platform dependent length modifier for conversion specifiers
+for scanning and printing values of type #gintptr or #guintptr.
+It is a string literal.
+
+Note that this is not necessarily the correct modifier to scan or
+print an `intptr_t`, even though the in-memory representation is the
+same.
+Standard C macros like `PRIdPTR` and `SCNdPTR` should be used for
+`intptr_t`.
+
+
+
+
+ Expands to the GNU C `alloc_size` function attribute if the compiler
+is a new enough gcc. This attribute tells the compiler that the
+function returns a pointer to memory of a size that is specified
+by the @xth function parameter.
+
+Place the attribute after the function declaration, just before the
+semicolon.
+
+|[<!-- language="C" -->
+gpointer g_malloc (gsize n_bytes) G_GNUC_MALLOC G_GNUC_ALLOC_SIZE(1);
+]|
+
+See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-alloc_005fsize-function-attribute) for more details.
+
+
+
+ the index of the argument specifying the allocation size
+
+
+
+
+ Expands to the GNU C `alloc_size` function attribute if the compiler is a
+new enough gcc. This attribute tells the compiler that the function returns
+a pointer to memory of a size that is specified by the product of two
+function parameters.
+
+Place the attribute after the function declaration, just before the
+semicolon.
+
+|[<!-- language="C" -->
+gpointer g_malloc_n (gsize n_blocks,
+ gsize n_block_bytes) G_GNUC_MALLOC G_GNUC_ALLOC_SIZE2(1, 2);
+]|
+
+See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-alloc_005fsize-function-attribute) for more details.
+
+
+
+ the index of the argument specifying one factor of the allocation size
+
+
+ the index of the argument specifying the second factor of the allocation size
+
+
+
+
+ Expands to a check for a compiler with __GNUC__ defined and a version
+greater than or equal to the major and minor numbers provided. For example,
+the following would only match on compilers such as GCC 4.8 or newer.
+
+|[<!-- language="C" -->
+#if G_GNUC_CHECK_VERSION(4, 8)
+#endif
+]|
+
+
+
+ major version to check against
+
+
+ minor version to check against
+
+
+
+
+ Like %G_GNUC_DEPRECATED, but names the intended replacement for the
+deprecated symbol if the version of gcc in use is new enough to support
+custom deprecation messages.
+
+Place the attribute after the declaration, just before the semicolon.
+
+|[<!-- language="C" -->
+int my_mistake (void) G_GNUC_DEPRECATED_FOR(my_replacement);
+]|
+
+See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-deprecated-function-attribute) for more details.
+
+Note that if @f is a macro, it will be expanded in the warning message.
+You can enclose it in quotes to prevent this. (The quotes will show up
+in the warning, but it's better than showing the macro expansion.)
+
+
+
+ the intended replacement for the deprecated symbol,
+ such as the name of a function
+
+
+
+
+ Expands to the GNU C `format_arg` function attribute if the compiler
+is gcc. This function attribute specifies that a function takes a
+format string for a `printf()`, `scanf()`, `strftime()` or `strfmon()` style
+function and modifies it, so that the result can be passed to a `printf()`,
+`scanf()`, `strftime()` or `strfmon()` style function (with the remaining
+arguments to the format function the same as they would have been
+for the unmodified string).
+
+Place the attribute after the function declaration, just before the
+semicolon.
+
+See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-nonliteral-1) for more details.
+
+|[<!-- language="C" -->
+gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2);
+]|
+
+
+
+ the index of the argument
+
+
+
+
+ Expands to "" on all modern compilers, and to __FUNCTION__ on gcc
+version 2.x. Don't use it.
+ Use G_STRFUNC() instead
+
+
+
+
+ Expands to "" on all modern compilers, and to __PRETTY_FUNCTION__
+on gcc version 2.x. Don't use it.
+ Use G_STRFUNC() instead
+
+
+
+
+ Expands to the GNU C `format` function attribute if the compiler is gcc.
+This is used for declaring functions which take a variable number of
+arguments, with the same syntax as `printf()`. It allows the compiler
+to type-check the arguments passed to the function.
+
+Place the attribute after the function declaration, just before the
+semicolon.
+
+See the
+[GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288)
+for more details.
+
+|[<!-- language="C" -->
+gint g_snprintf (gchar *string,
+ gulong n,
+ gchar const *format,
+ ...) G_GNUC_PRINTF (3, 4);
+]|
+
+
+
+ the index of the argument corresponding to the
+ format string (the arguments are numbered from 1)
+
+
+ the index of the first of the format arguments, or 0 if
+ there are no format arguments
+
+
+
+
+ Expands to the GNU C `format` function attribute if the compiler is gcc.
+This is used for declaring functions which take a variable number of
+arguments, with the same syntax as `scanf()`. It allows the compiler
+to type-check the arguments passed to the function.
+
+|[<!-- language="C" -->
+int my_scanf (MyStream *stream,
+ const char *format,
+ ...) G_GNUC_SCANF (2, 3);
+int my_vscanf (MyStream *stream,
+ const char *format,
+ va_list ap) G_GNUC_SCANF (2, 0);
+]|
+
+See the
+[GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288)
+for details.
+
+
+
+ the index of the argument corresponding to
+ the format string (the arguments are numbered from 1)
+
+
+ the index of the first of the format arguments, or 0 if
+ there are no format arguments
+
+
+
+
+ Expands to the GNU C `strftime` format function attribute if the compiler
+is gcc. This is used for declaring functions which take a format argument
+which is passed to `strftime()` or an API implementing its formats. It allows
+the compiler check the format passed to the function.
+
+|[<!-- language="C" -->
+gsize my_strftime (MyBuffer *buffer,
+ const char *format,
+ const struct tm *tm) G_GNUC_STRFTIME (2);
+]|
+
+See the
+[GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288)
+for details.
+
+
+
+ the index of the argument corresponding to
+ the format string (the arguments are numbered from 1)
+
+
+
+
+ This macro is used to insert #goffset 64-bit integer literals
+into the source code.
+
+See also G_GINT64_CONSTANT().
+
+
+
+ a literal integer value, e.g. 0x1d636b02300a7aa7
+
+
+
+
+ This is the platform dependent conversion specifier for scanning
+and printing values of type #gsize. See also %G_GINT16_FORMAT.
+
+Note that this is not necessarily the correct format to scan or
+print a `size_t`, even though the in-memory representation is the
+same. The standard C `"zu"` format should be used for `size_t`,
+assuming a C99-compliant `printf` implementation is available.
+
+
+
+
+ The platform dependent length modifier for conversion specifiers
+for scanning and printing values of type #gsize. It
+is a string literal.
+
+Note that this is not necessarily the correct modifier to scan or
+print a `size_t`, even though the in-memory representation is the
+same. The Standard C `"z"` modifier should be used for `size_t`,
+assuming a C99-compliant `printf` implementation is available.
+
+
+
+
+ This is the platform dependent conversion specifier for scanning
+and printing values of type #gssize. See also %G_GINT16_FORMAT.
+
+Note that this is not necessarily the correct format to scan or print
+a POSIX `ssize_t` or a Windows `SSIZE_T`, even though the in-memory
+representation is the same.
+On POSIX platforms, the `"zd"` format should be used for `ssize_t`.
+
+
+
+
+ The platform dependent length modifier for conversion specifiers
+for scanning and printing values of type #gssize. It
+is a string literal.
+
+Note that this is not necessarily the correct modifier to scan or print
+a POSIX `ssize_t` or a Windows `SSIZE_T`, even though the in-memory
+representation is the same.
+On POSIX platforms, the `"z"` modifier should be used for `ssize_t`.
+
+
+
+
+ This is the platform dependent conversion specifier for scanning
+and printing values of type #guint16. See also %G_GINT16_FORMAT
+
+This is not necessarily the correct modifier for printing and scanning
+`uint16_t` values, even though the in-memory representation is the same.
+Standard C macros like `PRIu16` and `SCNu16` should be used for `uint16_t`.
+
+
+
+
+ This is the platform dependent conversion specifier for scanning
+and printing values of type #guint32. See also %G_GINT16_FORMAT.
+
+This is not necessarily the correct modifier for printing and scanning
+`uint32_t` values, even though the in-memory representation is the same.
+Standard C macros like `PRIu32` and `SCNu32` should be used for `uint32_t`.
+
+
+
+
+ This macro is used to insert 64-bit unsigned integer
+literals into the source code.
+
+It is similar to the standard C `UINT64_C` macro,
+which should be preferred in new code.
+
+
+
+ a literal integer value, e.g. 0x1d636b02300a7aa7U
+
+
+
+
+ This is the platform dependent conversion specifier for scanning
+and printing values of type #guint64. See also %G_GINT16_FORMAT.
+
+Some platforms do not support scanning and printing 64-bit integers,
+even though the types are supported. On such platforms %G_GUINT64_FORMAT
+is not defined. Note that scanf() may not support 64-bit integers, even
+if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf()
+is not recommended for parsing anyway; consider using g_ascii_strtoull()
+instead.
+
+This is not necessarily the correct modifier for printing and scanning
+`uint64_t` values, even though the in-memory representation is the same.
+Standard C macros like `PRIu64` and `SCNu64` should be used for `uint64_t`.
+
+
+
+
+ This is the platform dependent conversion specifier
+for scanning and printing values of type #guintptr.
+
+Note that this is not necessarily the correct format to scan or
+print a `uintptr_t`, even though the in-memory representation is the
+same.
+Standard C macros like `PRIuPTR` and `SCNuPTR` should be used for
+`uintptr_t`.
+
+
+
+
+
+
+
+
+
+
+
+
+ Defined to 1 if gcc-style visibility handling is supported.
+
+
+
+
+
+
+
+
+
+
+
+
+ Specifies the type of the function passed to g_hash_table_foreach().
+It is called with each key/value pair, together with the @user_data
+parameter which is passed to g_hash_table_foreach().
+
+
+
+
+
+
+ a key
+
+
+
+ the value corresponding to the key
+
+
+
+ user data passed to g_hash_table_foreach()
+
+
+
+
+
+ Casts a pointer to a `GHook*`.
+
+
+
+ a pointer
+
+
+
+
+ Returns %TRUE if the #GHook is active, which is normally the case
+until the #GHook is destroyed.
+
+
+
+ a #GHook
+
+
+
+
+ Gets the flags of a hook.
+
+
+
+ a #GHook
+
+
+
+
+ The position of the first bit which is not reserved for internal
+use be the #GHook implementation, i.e.
+`1 << G_HOOK_FLAG_USER_SHIFT` is the first
+bit which can be used for application-defined flags.
+
+
+
+
+ Returns %TRUE if the #GHook function is currently executing.
+
+
+
+ a #GHook
+
+
+
+
+ Returns %TRUE if the #GHook is not in a #GHookList.
+
+
+
+ a #GHook
+
+
+
+
+ Returns %TRUE if the #GHook is valid, i.e. it is in a #GHookList,
+it is active and it has not been destroyed.
+
+
+
+ a #GHook
+
+
+
+
+ Specifies the type of the function passed to
+g_hash_table_foreach_remove(). It is called with each key/value
+pair, together with the @user_data parameter passed to
+g_hash_table_foreach_remove(). It should return %TRUE if the
+key/value pair should be removed from the #GHashTable.
+
+
+ %TRUE if the key/value pair should be removed from the
+ #GHashTable
+
+
+
+
+ a key
+
+
+
+ the value associated with the key
+
+
+
+ user data passed to g_hash_table_remove()
+
+
+
+
+
+ Specifies the type of the hash function which is passed to
+g_hash_table_new() when a #GHashTable is created.
+
+The function is passed a key and should return a #guint hash value.
+The functions g_direct_hash(), g_int_hash() and g_str_hash() provide
+hash functions which can be used when the key is a #gpointer, #gint*,
+and #gchar* respectively.
+
+g_direct_hash() is also the appropriate hash function for keys
+of the form `GINT_TO_POINTER (n)` (or similar macros).
+
+A good hash functions should produce
+hash values that are evenly distributed over a fairly large range.
+The modulus is taken with the hash table size (a prime number) to
+find the 'bucket' to place each key into. The function should also
+be very fast, since it is called for each key lookup.
+
+Note that the hash functions provided by GLib have these qualities,
+but are not particularly robust against manufactured keys that
+cause hash collisions. Therefore, you should consider choosing
+a more secure hash function when using a GHashTable with keys
+that originate in untrusted data (such as HTTP requests).
+Using g_str_hash() in that situation might make your application
+vulnerable to
+[Algorithmic Complexity Attacks](https://lwn.net/Articles/474912/).
+
+The key to choosing a good hash is unpredictability. Even
+cryptographic hashes are very easy to find collisions for when the
+remainder is taken modulo a somewhat predictable prime number. There
+must be an element of randomness that an attacker is unable to guess.
+
+
+ the hash value corresponding to the key
+
+
+
+
+ a key
+
+
+
+
+
+ The #GHashTable struct is an opaque data structure to represent a
+[Hash Table][glib-Hash-Tables]. It should only be accessed via the
+following functions.
+
+
+ This is a convenience function for using a #GHashTable as a set. It
+is equivalent to calling g_hash_table_replace() with @key as both the
+key and the value.
+
+In particular, this means that if @key already exists in the hash table, then
+the old copy of @key in the hash table is freed and @key replaces it in the
+table.
+
+When a hash table only ever contains keys that have themselves as the
+corresponding value it is able to be stored more efficiently. See
+the discussion in the section description.
+
+Starting from GLib 2.40, this function returns a boolean value to
+indicate whether the newly added value was already in the hash table
+or not.
+
+
+ %TRUE if the key did not exist yet
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+ a key to insert
+
+
+
+
+
+ Checks if @key is in @hash_table.
+
+
+ %TRUE if @key is in @hash_table, %FALSE otherwise.
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+ a key to check
+
+
+
+
+
+ Destroys all keys and values in the #GHashTable and decrements its
+reference count by 1. If keys and/or values are dynamically allocated,
+you should either free them first or create the #GHashTable with destroy
+notifiers using g_hash_table_new_full(). In the latter case the destroy
+functions you supplied will be called on all keys and values during the
+destruction phase.
+
+
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+
+
+ Calls the given function for key/value pairs in the #GHashTable
+until @predicate returns %TRUE. The function is passed the key
+and value of each pair, and the given @user_data parameter. The
+hash table may not be modified while iterating over it (you can't
+add/remove items).
+
+Note, that hash tables are really only optimized for forward
+lookups, i.e. g_hash_table_lookup(). So code that frequently issues
+g_hash_table_find() or g_hash_table_foreach() (e.g. in the order of
+once per every entry in a hash table) should probably be reworked
+to use additional or different data structures for reverse lookups
+(keep in mind that an O(n) find/foreach operation issued for all n
+values in a hash table ends up needing O(n*n) operations).
+
+
+ The value of the first key/value pair is returned,
+ for which @predicate evaluates to %TRUE. If no pair with the
+ requested property is found, %NULL is returned.
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+ function to test the key/value pairs for a certain property
+
+
+
+ user data to pass to the function
+
+
+
+
+
+ Calls the given function for each of the key/value pairs in the
+#GHashTable. The function is passed the key and value of each
+pair, and the given @user_data parameter. The hash table may not
+be modified while iterating over it (you can't add/remove
+items). To remove all items matching a predicate, use
+g_hash_table_foreach_remove().
+
+The order in which g_hash_table_foreach() iterates over the keys/values in
+the hash table is not defined.
+
+See g_hash_table_find() for performance caveats for linear
+order searches in contrast to g_hash_table_lookup().
+
+
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+ the function to call for each key/value pair
+
+
+
+ user data to pass to the function
+
+
+
+
+
+ Calls the given function for each key/value pair in the
+#GHashTable. If the function returns %TRUE, then the key/value
+pair is removed from the #GHashTable. If you supplied key or
+value destroy functions when creating the #GHashTable, they are
+used to free the memory allocated for the removed keys and values.
+
+See #GHashTableIter for an alternative way to loop over the
+key/value pairs in the hash table.
+
+
+ the number of key/value pairs removed
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+ the function to call for each key/value pair
+
+
+
+ user data to pass to the function
+
+
+
+
+
+ Calls the given function for each key/value pair in the
+#GHashTable. If the function returns %TRUE, then the key/value
+pair is removed from the #GHashTable, but no key or value
+destroy functions are called.
+
+See #GHashTableIter for an alternative way to loop over the
+key/value pairs in the hash table.
+
+
+ the number of key/value pairs removed.
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+ the function to call for each key/value pair
+
+
+
+ user data to pass to the function
+
+
+
+
+
+ Retrieves every key inside @hash_table. The returned data is valid
+until changes to the hash release those keys.
+
+This iterates over every entry in the hash table to build its return value.
+To iterate over the entries in a #GHashTable more efficiently, use a
+#GHashTableIter.
+
+
+ a #GList containing all the keys
+ inside the hash table. The content of the list is owned by the
+ hash table and should not be modified or freed. Use g_list_free()
+ when done using the list.
+
+
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+
+
+ Retrieves every key inside @hash_table, as an array.
+
+The returned array is %NULL-terminated but may contain %NULL as a
+key. Use @length to determine the true length if it's possible that
+%NULL was used as the value for a key.
+
+Note: in the common case of a string-keyed #GHashTable, the return
+value of this function can be conveniently cast to (const gchar **).
+
+This iterates over every entry in the hash table to build its return value.
+To iterate over the entries in a #GHashTable more efficiently, use a
+#GHashTableIter.
+
+You should always free the return result with g_free(). In the
+above-mentioned case of a string-keyed hash table, it may be
+appropriate to use g_strfreev() if you call g_hash_table_steal_all()
+first to transfer ownership of the keys.
+
+
+ a
+ %NULL-terminated array containing each key from the table.
+
+
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+ the length of the returned array
+
+
+
+
+
+ Retrieves every key inside @hash_table, as a #GPtrArray.
+The returned data is valid until changes to the hash release those keys.
+
+This iterates over every entry in the hash table to build its return value.
+To iterate over the entries in a #GHashTable more efficiently, use a
+#GHashTableIter.
+
+You should always unref the returned array with g_ptr_array_unref().
+
+
+ a #GPtrArray containing each key from
+the table. Unref with with g_ptr_array_unref() when done.
+
+
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+
+
+ Retrieves every value inside @hash_table. The returned data
+is valid until @hash_table is modified.
+
+This iterates over every entry in the hash table to build its return value.
+To iterate over the entries in a #GHashTable more efficiently, use a
+#GHashTableIter.
+
+
+ a #GList containing all the values
+ inside the hash table. The content of the list is owned by the
+ hash table and should not be modified or freed. Use g_list_free()
+ when done using the list.
+
+
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+
+
+ Retrieves every value inside @hash_table, as a #GPtrArray.
+The returned data is valid until changes to the hash release those values.
+
+This iterates over every entry in the hash table to build its return value.
+To iterate over the entries in a #GHashTable more efficiently, use a
+#GHashTableIter.
+
+You should always unref the returned array with g_ptr_array_unref().
+
+
+ a #GPtrArray containing each value from
+the table. Unref with with g_ptr_array_unref() when done.
+
+
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+
+
+ Inserts a new key and value into a #GHashTable.
+
+If the key already exists in the #GHashTable its current
+value is replaced with the new value. If you supplied a
+@value_destroy_func when creating the #GHashTable, the old
+value is freed using that function. If you supplied a
+@key_destroy_func when creating the #GHashTable, the passed
+key is freed using that function.
+
+Starting from GLib 2.40, this function returns a boolean value to
+indicate whether the newly added value was already in the hash table
+or not.
+
+
+ %TRUE if the key did not exist yet
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+ a key to insert
+
+
+
+ the value to associate with the key
+
+
+
+
+
+ Looks up a key in a #GHashTable. Note that this function cannot
+distinguish between a key that is not present and one which is present
+and has the value %NULL. If you need this distinction, use
+g_hash_table_lookup_extended().
+
+
+ the associated value, or %NULL if the key is not found
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+ the key to look up
+
+
+
+
+
+ Looks up a key in the #GHashTable, returning the original key and the
+associated value and a #gboolean which is %TRUE if the key was found. This
+is useful if you need to free the memory allocated for the original key,
+for example before calling g_hash_table_remove().
+
+You can actually pass %NULL for @lookup_key to test
+whether the %NULL key exists, provided the hash and equal functions
+of @hash_table are %NULL-safe.
+
+
+ %TRUE if the key was found in the #GHashTable
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+ the key to look up
+
+
+
+ return location for the original key
+
+
+
+ return location for the value associated
+with the key
+
+
+
+
+
+ Creates a new #GHashTable with a reference count of 1.
+
+Hash values returned by @hash_func are used to determine where keys
+are stored within the #GHashTable data structure. The g_direct_hash(),
+g_int_hash(), g_int64_hash(), g_double_hash() and g_str_hash()
+functions are provided for some common types of keys.
+If @hash_func is %NULL, g_direct_hash() is used.
+
+@key_equal_func is used when looking up keys in the #GHashTable.
+The g_direct_equal(), g_int_equal(), g_int64_equal(), g_double_equal()
+and g_str_equal() functions are provided for the most common types
+of keys. If @key_equal_func is %NULL, keys are compared directly in
+a similar fashion to g_direct_equal(), but without the overhead of
+a function call. @key_equal_func is called with the key from the hash table
+as its first parameter, and the user-provided key to check against as
+its second.
+
+
+ a new #GHashTable
+
+
+
+
+
+
+
+ a function to create a hash value from a key
+
+
+
+ a function to check two keys for equality
+
+
+
+
+
+ Creates a new #GHashTable like g_hash_table_new() with a reference
+count of 1 and allows to specify functions to free the memory
+allocated for the key and value that get called when removing the
+entry from the #GHashTable.
+
+Since version 2.42 it is permissible for destroy notify functions to
+recursively remove further items from the hash table. This is only
+permissible if the application still holds a reference to the hash table.
+This means that you may need to ensure that the hash table is empty by
+calling g_hash_table_remove_all() before releasing the last reference using
+g_hash_table_unref().
+
+
+ a new #GHashTable
+
+
+
+
+
+
+
+ a function to create a hash value from a key
+
+
+
+ a function to check two keys for equality
+
+
+
+ a function to free the memory allocated for the key
+ used when removing the entry from the #GHashTable, or %NULL
+ if you don't want to supply such a function.
+
+
+
+ a function to free the memory allocated for the
+ value used when removing the entry from the #GHashTable, or %NULL
+ if you don't want to supply such a function.
+
+
+
+
+
+ Creates a new #GHashTable like g_hash_table_new_full() with a reference
+count of 1.
+
+It inherits the hash function, the key equal function, the key destroy function,
+as well as the value destroy function, from @other_hash_table.
+
+The returned hash table will be empty; it will not contain the keys
+or values from @other_hash_table.
+
+
+ a new #GHashTable
+
+
+
+
+
+
+
+ Another #GHashTable
+
+
+
+
+
+
+
+
+ Atomically increments the reference count of @hash_table by one.
+This function is MT-safe and may be called from any thread.
+
+
+ the passed in #GHashTable
+
+
+
+
+
+
+
+ a valid #GHashTable
+
+
+
+
+
+
+
+
+ Removes a key and its associated value from a #GHashTable.
+
+If the #GHashTable was created using g_hash_table_new_full(), the
+key and value are freed using the supplied destroy functions, otherwise
+you have to make sure that any dynamically allocated values are freed
+yourself.
+
+
+ %TRUE if the key was found and removed from the #GHashTable
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+ the key to remove
+
+
+
+
+
+ Removes all keys and their associated values from a #GHashTable.
+
+If the #GHashTable was created using g_hash_table_new_full(),
+the keys and values are freed using the supplied destroy functions,
+otherwise you have to make sure that any dynamically allocated
+values are freed yourself.
+
+
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+
+
+ Inserts a new key and value into a #GHashTable similar to
+g_hash_table_insert(). The difference is that if the key
+already exists in the #GHashTable, it gets replaced by the
+new key. If you supplied a @value_destroy_func when creating
+the #GHashTable, the old value is freed using that function.
+If you supplied a @key_destroy_func when creating the
+#GHashTable, the old key is freed using that function.
+
+Starting from GLib 2.40, this function returns a boolean value to
+indicate whether the newly added value was already in the hash table
+or not.
+
+
+ %TRUE if the key did not exist yet
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+ a key to insert
+
+
+
+ the value to associate with the key
+
+
+
+
+
+ Returns the number of elements contained in the #GHashTable.
+
+
+ the number of key/value pairs in the #GHashTable.
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+
+
+ Removes a key and its associated value from a #GHashTable without
+calling the key and value destroy functions.
+
+
+ %TRUE if the key was found and removed from the #GHashTable
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+ the key to remove
+
+
+
+
+
+ Removes all keys and their associated values from a #GHashTable
+without calling the key and value destroy functions.
+
+
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+
+
+ Removes all keys and their associated values from a #GHashTable
+without calling the key destroy functions, returning the keys
+as a #GPtrArray with the free func set to the @hash_table key
+destroy function.
+
+
+ a #GPtrArray containing each key of
+the table. Unref with with g_ptr_array_unref() when done.
+
+
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+
+
+ Removes all keys and their associated values from a #GHashTable
+without calling the value destroy functions, returning the values
+as a #GPtrArray with the free func set to the @hash_table value
+destroy function.
+
+
+ a #GPtrArray containing each value of
+the table. Unref with with g_ptr_array_unref() when done.
+
+
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+
+
+ Looks up a key in the #GHashTable, stealing the original key and the
+associated value and returning %TRUE if the key was found. If the key was
+not found, %FALSE is returned.
+
+If found, the stolen key and value are removed from the hash table without
+calling the key and value destroy functions, and ownership is transferred to
+the caller of this method, as with g_hash_table_steal(). That is the case
+regardless whether @stolen_key or @stolen_value output parameters are
+requested.
+
+You can pass %NULL for @lookup_key, provided the hash and equal functions
+of @hash_table are %NULL-safe.
+
+The dictionary implementation optimizes for having all values identical to
+their keys, for example by using g_hash_table_add(). When stealing both the
+key and the value from such a dictionary, the value will be %NULL.
+
+
+ %TRUE if the key was found in the #GHashTable
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+ the key to look up
+
+
+
+ return location for the
+ original key
+
+
+
+ return location
+ for the value associated with the key
+
+
+
+
+
+ Atomically decrements the reference count of @hash_table by one.
+If the reference count drops to 0, all keys and values will be
+destroyed, and all memory allocated by the hash table is released.
+This function is MT-safe and may be called from any thread.
+
+
+
+
+
+
+ a valid #GHashTable
+
+
+
+
+
+
+
+
+
+ A GHashTableIter structure represents an iterator that can be used
+to iterate over the elements of a #GHashTable. GHashTableIter
+structures are typically allocated on the stack and then initialized
+with g_hash_table_iter_init().
+
+The iteration order of a #GHashTableIter over the keys/values in a hash
+table is not defined.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Returns the #GHashTable associated with @iter.
+
+
+ the #GHashTable associated with @iter.
+
+
+
+
+
+
+
+ an initialized #GHashTableIter
+
+
+
+
+
+ Initializes a key/value pair iterator and associates it with
+@hash_table. Modifying the hash table after calling this function
+invalidates the returned iterator.
+
+The iteration order of a #GHashTableIter over the keys/values in a hash
+table is not defined.
+
+|[<!-- language="C" -->
+GHashTableIter iter;
+gpointer key, value;
+
+g_hash_table_iter_init (&iter, hash_table);
+while (g_hash_table_iter_next (&iter, &key, &value))
+ {
+ // do something with key and value
+ }
+]|
+
+
+
+
+
+
+ an uninitialized #GHashTableIter
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+
+
+ Advances @iter and retrieves the key and/or value that are now
+pointed to as a result of this advancement. If %FALSE is returned,
+@key and @value are not set, and the iterator becomes invalid.
+
+
+ %FALSE if the end of the #GHashTable has been reached.
+
+
+
+
+ an initialized #GHashTableIter
+
+
+
+ a location to store the key
+
+
+
+ a location to store the value
+
+
+
+
+
+ Removes the key/value pair currently pointed to by the iterator
+from its associated #GHashTable. Can only be called after
+g_hash_table_iter_next() returned %TRUE, and cannot be called
+more than once for the same key/value pair.
+
+If the #GHashTable was created using g_hash_table_new_full(),
+the key and value are freed using the supplied destroy functions,
+otherwise you have to make sure that any dynamically allocated
+values are freed yourself.
+
+It is safe to continue iterating the #GHashTable afterward:
+|[<!-- language="C" -->
+while (g_hash_table_iter_next (&iter, &key, &value))
+ {
+ if (condition)
+ g_hash_table_iter_remove (&iter);
+ }
+]|
+
+
+
+
+
+
+ an initialized #GHashTableIter
+
+
+
+
+
+ Replaces the value currently pointed to by the iterator
+from its associated #GHashTable. Can only be called after
+g_hash_table_iter_next() returned %TRUE.
+
+If you supplied a @value_destroy_func when creating the
+#GHashTable, the old value is freed using that function.
+
+
+
+
+
+
+ an initialized #GHashTableIter
+
+
+
+ the value to replace with
+
+
+
+
+
+ Removes the key/value pair currently pointed to by the
+iterator from its associated #GHashTable, without calling
+the key and value destroy functions. Can only be called
+after g_hash_table_iter_next() returned %TRUE, and cannot
+be called more than once for the same key/value pair.
+
+
+
+
+
+
+ an initialized #GHashTableIter
+
+
+
+
+
+
+ An opaque structure representing a HMAC operation.
+To create a new GHmac, use g_hmac_new(). To free
+a GHmac, use g_hmac_unref().
+
+
+ Copies a #GHmac. If @hmac has been closed, by calling
+g_hmac_get_string() or g_hmac_get_digest(), the copied
+HMAC will be closed as well.
+
+
+ the copy of the passed #GHmac. Use g_hmac_unref()
+ when finished using it.
+
+
+
+
+ the #GHmac to copy
+
+
+
+
+
+ Gets the digest from @checksum as a raw binary array and places it
+into @buffer. The size of the digest depends on the type of checksum.
+
+Once this function has been called, the #GHmac is closed and can
+no longer be updated with g_checksum_update().
+
+
+
+
+
+
+ a #GHmac
+
+
+
+ output buffer
+
+
+
+
+
+ an inout parameter. The caller initializes it to the
+ size of @buffer. After the call it contains the length of the digest
+
+
+
+
+
+ Gets the HMAC as a hexadecimal string.
+
+Once this function has been called the #GHmac can no longer be
+updated with g_hmac_update().
+
+The hexadecimal characters will be lower case.
+
+
+ the hexadecimal representation of the HMAC. The
+ returned string is owned by the HMAC and should not be modified
+ or freed.
+
+
+
+
+ a #GHmac
+
+
+
+
+
+ Atomically increments the reference count of @hmac by one.
+
+This function is MT-safe and may be called from any thread.
+
+
+ the passed in #GHmac.
+
+
+
+
+ a valid #GHmac
+
+
+
+
+
+ Atomically decrements the reference count of @hmac by one.
+
+If the reference count drops to 0, all keys and values will be
+destroyed, and all memory allocated by the hash table is released.
+This function is MT-safe and may be called from any thread.
+Frees the memory allocated for @hmac.
+
+
+
+
+
+
+ a #GHmac
+
+
+
+
+
+ Feeds @data into an existing #GHmac.
+
+The HMAC must still be open, that is g_hmac_get_string() or
+g_hmac_get_digest() must not have been called on @hmac.
+
+
+
+
+
+
+ a #GHmac
+
+
+
+ buffer used to compute the checksum
+
+
+
+
+
+ size of the buffer, or -1 if it is a nul-terminated string
+
+
+
+
+
+ Creates a new #GHmac, using the digest algorithm @digest_type.
+If the @digest_type is not known, %NULL is returned.
+A #GHmac can be used to compute the HMAC of a key and an
+arbitrary binary blob, using different hashing algorithms.
+
+A #GHmac works by feeding a binary blob through g_hmac_update()
+until the data is complete; the digest can then be extracted
+using g_hmac_get_string(), which will return the checksum as a
+hexadecimal string; or g_hmac_get_digest(), which will return a
+array of raw bytes. Once either g_hmac_get_string() or
+g_hmac_get_digest() have been called on a #GHmac, the HMAC
+will be closed and it won't be possible to call g_hmac_update()
+on it anymore.
+
+Support for digests of type %G_CHECKSUM_SHA512 has been added in GLib 2.42.
+Support for %G_CHECKSUM_SHA384 was added in GLib 2.52.
+
+
+ the newly created #GHmac, or %NULL.
+ Use g_hmac_unref() to free the memory allocated by it.
+
+
+
+
+ the desired type of digest
+
+
+
+ the key for the HMAC
+
+
+
+
+
+ the length of the keys
+
+
+
+
+
+
+ The #GHook struct represents a single hook function in a #GHookList.
+
+
+ data which is passed to func when this hook is invoked
+
+
+
+ pointer to the next hook in the list
+
+
+
+ pointer to the previous hook in the list
+
+
+
+ the reference count of this hook
+
+
+
+ the id of this hook, which is unique within its list
+
+
+
+ flags which are set for this hook. See #GHookFlagMask for
+ predefined flags
+
+
+
+ the function to call when this hook is invoked. The possible
+ signatures for this function are #GHookFunc and #GHookCheckFunc
+
+
+
+ the default @finalize_hook function of a #GHookList calls
+ this member of the hook that is being finalized
+
+
+
+ Compares the ids of two #GHook elements, returning a negative value
+if the second id is greater than the first.
+
+
+ a value <= 0 if the id of @sibling is >= the id of @new_hook
+
+
+
+
+ a #GHook
+
+
+
+ a #GHook to compare with @new_hook
+
+
+
+
+
+ Allocates space for a #GHook and initializes it.
+
+
+ a new #GHook
+
+
+
+
+ a #GHookList
+
+
+
+
+
+ Destroys a #GHook, given its ID.
+
+
+ %TRUE if the #GHook was found in the #GHookList and destroyed
+
+
+
+
+ a #GHookList
+
+
+
+ a hook ID
+
+
+
+
+
+ Removes one #GHook from a #GHookList, marking it
+inactive and calling g_hook_unref() on it.
+
+
+
+
+
+
+ a #GHookList
+
+
+
+ the #GHook to remove
+
+
+
+
+
+ Finds a #GHook in a #GHookList using the given function to
+test for a match.
+
+
+ the found #GHook or %NULL if no matching #GHook is found
+
+
+
+
+ a #GHookList
+
+
+
+ %TRUE if #GHook elements which have been destroyed
+ should be skipped
+
+
+
+ the function to call for each #GHook, which should return
+ %TRUE when the #GHook has been found
+
+
+
+ the data to pass to @func
+
+
+
+
+
+ Finds a #GHook in a #GHookList with the given data.
+
+
+ the #GHook with the given @data or %NULL if no matching
+ #GHook is found
+
+
+
+
+ a #GHookList
+
+
+
+ %TRUE if #GHook elements which have been destroyed
+ should be skipped
+
+
+
+ the data to find
+
+
+
+
+
+ Finds a #GHook in a #GHookList with the given function.
+
+
+ the #GHook with the given @func or %NULL if no matching
+ #GHook is found
+
+
+
+
+ a #GHookList
+
+
+
+ %TRUE if #GHook elements which have been destroyed
+ should be skipped
+
+
+
+ the function to find
+
+
+
+
+
+ Finds a #GHook in a #GHookList with the given function and data.
+
+
+ the #GHook with the given @func and @data or %NULL if
+ no matching #GHook is found
+
+
+
+
+ a #GHookList
+
+
+
+ %TRUE if #GHook elements which have been destroyed
+ should be skipped
+
+
+
+ the function to find
+
+
+
+ the data to find
+
+
+
+
+
+ Returns the first #GHook in a #GHookList which has not been destroyed.
+The reference count for the #GHook is incremented, so you must call
+g_hook_unref() to restore it when no longer needed. (Or call
+g_hook_next_valid() if you are stepping through the #GHookList.)
+
+
+ the first valid #GHook, or %NULL if none are valid
+
+
+
+
+ a #GHookList
+
+
+
+ %TRUE if hooks which are currently running
+ (e.g. in another thread) are considered valid. If set to %FALSE,
+ these are skipped
+
+
+
+
+
+ Calls the #GHookList @finalize_hook function if it exists,
+and frees the memory allocated for the #GHook.
+
+
+
+
+
+
+ a #GHookList
+
+
+
+ the #GHook to free
+
+
+
+
+
+ Returns the #GHook with the given id, or %NULL if it is not found.
+
+
+ the #GHook with the given id, or %NULL if it is not found
+
+
+
+
+ a #GHookList
+
+
+
+ a hook id
+
+
+
+
+
+ Inserts a #GHook into a #GHookList, before a given #GHook.
+
+
+
+
+
+
+ a #GHookList
+
+
+
+ the #GHook to insert the new #GHook before
+
+
+
+ the #GHook to insert
+
+
+
+
+
+ Inserts a #GHook into a #GHookList, sorted by the given function.
+
+
+
+
+
+
+ a #GHookList
+
+
+
+ the #GHook to insert
+
+
+
+ the comparison function used to sort the #GHook elements
+
+
+
+
+
+ Returns the next #GHook in a #GHookList which has not been destroyed.
+The reference count for the #GHook is incremented, so you must call
+g_hook_unref() to restore it when no longer needed. (Or continue to call
+g_hook_next_valid() until %NULL is returned.)
+
+
+ the next valid #GHook, or %NULL if none are valid
+
+
+
+
+ a #GHookList
+
+
+
+ the current #GHook
+
+
+
+ %TRUE if hooks which are currently running
+ (e.g. in another thread) are considered valid. If set to %FALSE,
+ these are skipped
+
+
+
+
+
+ Prepends a #GHook on the start of a #GHookList.
+
+
+
+
+
+
+ a #GHookList
+
+
+
+ the #GHook to add to the start of @hook_list
+
+
+
+
+
+ Increments the reference count for a #GHook.
+
+
+ the @hook that was passed in (since 2.6)
+
+
+
+
+ a #GHookList
+
+
+
+ the #GHook to increment the reference count of
+
+
+
+
+
+ Decrements the reference count of a #GHook.
+If the reference count falls to 0, the #GHook is removed
+from the #GHookList and g_hook_free() is called to free it.
+
+
+
+
+
+
+ a #GHookList
+
+
+
+ the #GHook to unref
+
+
+
+
+
+
+ Defines the type of a hook function that can be invoked
+by g_hook_list_invoke_check().
+
+
+ %FALSE if the #GHook should be destroyed
+
+
+
+
+ the data field of the #GHook is passed to the hook function here
+
+
+
+
+
+ Defines the type of function used by g_hook_list_marshal_check().
+
+
+ %FALSE if @hook should be destroyed
+
+
+
+
+ a #GHook
+
+
+
+ user data
+
+
+
+
+
+ Defines the type of function used to compare #GHook elements in
+g_hook_insert_sorted().
+
+
+ a value <= 0 if @new_hook should be before @sibling
+
+
+
+
+ the #GHook being inserted
+
+
+
+ the #GHook to compare with @new_hook
+
+
+
+
+
+ Defines the type of function to be called when a hook in a
+list of hooks gets finalized.
+
+
+
+
+
+
+ a #GHookList
+
+
+
+ the hook in @hook_list that gets finalized
+
+
+
+
+
+ Defines the type of the function passed to g_hook_find().
+
+
+ %TRUE if the required #GHook has been found
+
+
+
+
+ a #GHook
+
+
+
+ user data passed to g_hook_find_func()
+
+
+
+
+
+ Flags used internally in the #GHook implementation.
+
+
+ set if the hook has not been destroyed
+
+
+ set if the hook is currently being run
+
+
+ A mask covering all bits reserved for
+ hook flags; see %G_HOOK_FLAG_USER_SHIFT
+
+
+
+ Defines the type of a hook function that can be invoked
+by g_hook_list_invoke().
+
+
+
+
+
+
+ the data field of the #GHook is passed to the hook function here
+
+
+
+
+
+ The #GHookList struct represents a list of hook functions.
+
+
+ the next free #GHook id
+
+
+
+ the size of the #GHookList elements, in bytes
+
+
+
+ 1 if the #GHookList has been initialized
+
+
+
+ the first #GHook element in the list
+
+
+
+ unused
+
+
+
+ the function to call to finalize a #GHook element.
+ The default behaviour is to call the hooks @destroy function
+
+
+
+ unused
+
+
+
+
+
+ Removes all the #GHook elements from a #GHookList.
+
+
+
+
+
+
+ a #GHookList
+
+
+
+
+
+ Initializes a #GHookList.
+This must be called before the #GHookList is used.
+
+
+
+
+
+
+ a #GHookList
+
+
+
+ the size of each element in the #GHookList,
+ typically `sizeof (GHook)`.
+
+
+
+
+
+ Calls all of the #GHook functions in a #GHookList.
+
+
+
+
+
+
+ a #GHookList
+
+
+
+ %TRUE if functions which are already running
+ (e.g. in another thread) can be called. If set to %FALSE,
+ these are skipped
+
+
+
+
+
+ Calls all of the #GHook functions in a #GHookList.
+Any function which returns %FALSE is removed from the #GHookList.
+
+
+
+
+
+
+ a #GHookList
+
+
+
+ %TRUE if functions which are already running
+ (e.g. in another thread) can be called. If set to %FALSE,
+ these are skipped
+
+
+
+
+
+ Calls a function on each valid #GHook.
+
+
+
+
+
+
+ a #GHookList
+
+
+
+ %TRUE if hooks which are currently running
+ (e.g. in another thread) are considered valid. If set to %FALSE,
+ these are skipped
+
+
+
+ the function to call for each #GHook
+
+
+
+ data to pass to @marshaller
+
+
+
+
+
+ Calls a function on each valid #GHook and destroys it if the
+function returns %FALSE.
+
+
+
+
+
+
+ a #GHookList
+
+
+
+ %TRUE if hooks which are currently running
+ (e.g. in another thread) are considered valid. If set to %FALSE,
+ these are skipped
+
+
+
+ the function to call for each #GHook
+
+
+
+ data to pass to @marshaller
+
+
+
+
+
+
+ Defines the type of function used by g_hook_list_marshal().
+
+
+
+
+
+
+ a #GHook
+
+
+
+ user data
+
+
+
+
+
+ The GIConv struct wraps an iconv() conversion descriptor. It contains
+private data and should only be accessed using the following functions.
+
+
+ Same as the standard UNIX routine iconv(), but
+may be implemented via libiconv on UNIX flavors that lack
+a native implementation.
+
+GLib provides g_convert() and g_locale_to_utf8() which are likely
+more convenient than the raw iconv wrappers.
+
+Note that the behaviour of iconv() for characters which are valid in the
+input character set, but which have no representation in the output character
+set, is implementation defined. This function may return success (with a
+positive number of non-reversible conversions as replacement characters were
+used), or it may return -1 and set an error such as %EILSEQ, in such a
+situation.
+
+
+ count of non-reversible conversions, or -1 on error
+
+
+
+
+ conversion descriptor from g_iconv_open()
+
+
+
+ bytes to convert
+
+
+
+ inout parameter, bytes remaining to convert in @inbuf
+
+
+
+ converted output bytes
+
+
+
+ inout parameter, bytes available to fill in @outbuf
+
+
+
+
+
+ Same as the standard UNIX routine iconv_close(), but
+may be implemented via libiconv on UNIX flavors that lack
+a native implementation. Should be called to clean up
+the conversion descriptor from g_iconv_open() when
+you are done converting things.
+
+GLib provides g_convert() and g_locale_to_utf8() which are likely
+more convenient than the raw iconv wrappers.
+
+
+ -1 on error, 0 on success
+
+
+
+
+ a conversion descriptor from g_iconv_open()
+
+
+
+
+
+ Same as the standard UNIX routine iconv_open(), but
+may be implemented via libiconv on UNIX flavors that lack
+a native implementation.
+
+GLib provides g_convert() and g_locale_to_utf8() which are likely
+more convenient than the raw iconv wrappers.
+
+
+ a "conversion descriptor", or (GIConv)-1 if
+ opening the converter failed.
+
+
+
+
+ destination codeset
+
+
+
+ source codeset
+
+
+
+
+
+
+ The bias by which exponents in double-precision floats are offset.
+
+
+
+
+ The bias by which exponents in single-precision floats are offset.
+
+
+
+
+ A data structure representing an IO Channel. The fields should be
+considered private and should only be accessed with the following
+functions.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Open a file @filename as a #GIOChannel using mode @mode. This
+channel will be closed when the last reference to it is dropped,
+so there is no need to call g_io_channel_close() (though doing
+so will not cause problems, as long as no attempt is made to
+access the channel after it is closed).
+
+
+ A #GIOChannel on success, %NULL on failure.
+
+
+
+
+ A string containing the name of a file
+
+
+
+ One of "r", "w", "a", "r+", "w+", "a+". These have
+ the same meaning as in fopen()
+
+
+
+
+
+ Creates a new #GIOChannel given a file descriptor. On UNIX systems
+this works for plain files, pipes, and sockets.
+
+The returned #GIOChannel has a reference count of 1.
+
+The default encoding for #GIOChannel is UTF-8. If your application
+is reading output from a command using via pipe, you may need to set
+the encoding to the encoding of the current locale (see
+g_get_charset()) with the g_io_channel_set_encoding() function.
+By default, the fd passed will not be closed when the final reference
+to the #GIOChannel data structure is dropped.
+
+If you want to read raw binary data without interpretation, then
+call the g_io_channel_set_encoding() function with %NULL for the
+encoding argument.
+
+This function is available in GLib on Windows, too, but you should
+avoid using it on Windows. The domain of file descriptors and
+sockets overlap. There is no way for GLib to know which one you mean
+in case the argument you pass to this function happens to be both a
+valid file descriptor and socket. If that happens a warning is
+issued, and GLib assumes that it is the file descriptor you mean.
+
+
+ a new #GIOChannel.
+
+
+
+
+ a file descriptor.
+
+
+
+
+
+ Close an IO channel. Any pending data to be written will be
+flushed, ignoring errors. The channel will not be freed until the
+last reference is dropped using g_io_channel_unref().
+ Use g_io_channel_shutdown() instead.
+
+
+
+
+
+
+ A #GIOChannel
+
+
+
+
+
+ Flushes the write buffer for the GIOChannel.
+
+
+ the status of the operation: One of
+ %G_IO_STATUS_NORMAL, %G_IO_STATUS_AGAIN, or
+ %G_IO_STATUS_ERROR.
+
+
+
+
+ a #GIOChannel
+
+
+
+
+
+ This function returns a #GIOCondition depending on whether there
+is data to be read/space to write data in the internal buffers in
+the #GIOChannel. Only the flags %G_IO_IN and %G_IO_OUT may be set.
+
+
+ A #GIOCondition
+
+
+
+
+ A #GIOChannel
+
+
+
+
+
+ Gets the buffer size.
+
+
+ the size of the buffer.
+
+
+
+
+ a #GIOChannel
+
+
+
+
+
+ Returns whether @channel is buffered.
+
+
+ %TRUE if the @channel is buffered.
+
+
+
+
+ a #GIOChannel
+
+
+
+
+
+ Returns whether the file/socket/whatever associated with @channel
+will be closed when @channel receives its final unref and is
+destroyed. The default value of this is %TRUE for channels created
+by g_io_channel_new_file (), and %FALSE for all other channels.
+
+
+ %TRUE if the channel will be closed, %FALSE otherwise.
+
+
+
+
+ a #GIOChannel.
+
+
+
+
+
+ Gets the encoding for the input/output of the channel.
+The internal encoding is always UTF-8. The encoding %NULL
+makes the channel safe for binary data.
+
+
+ A string containing the encoding, this string is
+ owned by GLib and must not be freed.
+
+
+
+
+ a #GIOChannel
+
+
+
+
+
+ Gets the current flags for a #GIOChannel, including read-only
+flags such as %G_IO_FLAG_IS_READABLE.
+
+The values of the flags %G_IO_FLAG_IS_READABLE and %G_IO_FLAG_IS_WRITABLE
+are cached for internal use by the channel when it is created.
+If they should change at some later point (e.g. partial shutdown
+of a socket with the UNIX shutdown() function), the user
+should immediately call g_io_channel_get_flags() to update
+the internal values of these flags.
+
+
+ the flags which are set on the channel
+
+
+
+
+ a #GIOChannel
+
+
+
+
+
+ This returns the string that #GIOChannel uses to determine
+where in the file a line break occurs. A value of %NULL
+indicates autodetection.
+
+
+ The line termination string. This value
+ is owned by GLib and must not be freed.
+
+
+
+
+ a #GIOChannel
+
+
+
+ a location to return the length of the line terminator
+
+
+
+
+
+ Initializes a #GIOChannel struct.
+
+This is called by each of the above functions when creating a
+#GIOChannel, and so is not often needed by the application
+programmer (unless you are creating a new type of #GIOChannel).
+
+
+
+
+
+
+ a #GIOChannel
+
+
+
+
+
+ Reads data from a #GIOChannel.
+ Use g_io_channel_read_chars() instead.
+
+
+ %G_IO_ERROR_NONE if the operation was successful.
+
+
+
+
+ a #GIOChannel
+
+
+
+ a buffer to read the data into (which should be at least
+ count bytes long)
+
+
+
+ the number of bytes to read from the #GIOChannel
+
+
+
+ returns the number of bytes actually read
+
+
+
+
+
+ Replacement for g_io_channel_read() with the new API.
+
+
+ the status of the operation.
+
+
+
+
+ a #GIOChannel
+
+
+
+
+ a buffer to read data into
+
+
+
+
+
+ the size of the buffer. Note that the buffer may not be
+ completely filled even if there is data in the buffer if the
+ remaining data is not a complete character.
+
+
+
+ The number of bytes read. This may be
+ zero even on success if count < 6 and the channel's encoding
+ is non-%NULL. This indicates that the next UTF-8 character is
+ too wide for the buffer.
+
+
+
+
+
+ Reads a line, including the terminating character(s),
+from a #GIOChannel into a newly-allocated string.
+@str_return will contain allocated memory if the return
+is %G_IO_STATUS_NORMAL.
+
+
+ the status of the operation.
+
+
+
+
+ a #GIOChannel
+
+
+
+ The line read from the #GIOChannel, including the
+ line terminator. This data should be freed with g_free()
+ when no longer needed. This is a nul-terminated string.
+ If a @length of zero is returned, this will be %NULL instead.
+
+
+
+ location to store length of the read data, or %NULL
+
+
+
+ location to store position of line terminator, or %NULL
+
+
+
+
+
+ Reads a line from a #GIOChannel, using a #GString as a buffer.
+
+
+ the status of the operation.
+
+
+
+
+ a #GIOChannel
+
+
+
+ a #GString into which the line will be written.
+ If @buffer already contains data, the old data will
+ be overwritten.
+
+
+
+ location to store position of line terminator, or %NULL
+
+
+
+
+
+ Reads all the remaining data from the file.
+
+
+ %G_IO_STATUS_NORMAL on success.
+ This function never returns %G_IO_STATUS_EOF.
+
+
+
+
+ a #GIOChannel
+
+
+
+ Location to
+ store a pointer to a string holding the remaining data in the
+ #GIOChannel. This data should be freed with g_free() when no
+ longer needed. This data is terminated by an extra nul
+ character, but there may be other nuls in the intervening data.
+
+
+
+
+
+ location to store length of the data
+
+
+
+
+
+ Reads a Unicode character from @channel.
+This function cannot be called on a channel with %NULL encoding.
+
+
+ a #GIOStatus
+
+
+
+
+ a #GIOChannel
+
+
+
+ a location to return a character
+
+
+
+
+
+ Increments the reference count of a #GIOChannel.
+
+
+ the @channel that was passed in (since 2.6)
+
+
+
+
+ a #GIOChannel
+
+
+
+
+
+ Sets the current position in the #GIOChannel, similar to the standard
+library function fseek().
+ Use g_io_channel_seek_position() instead.
+
+
+ %G_IO_ERROR_NONE if the operation was successful.
+
+
+
+
+ a #GIOChannel
+
+
+
+ an offset, in bytes, which is added to the position specified
+ by @type
+
+
+
+ the position in the file, which can be %G_SEEK_CUR (the current
+ position), %G_SEEK_SET (the start of the file), or %G_SEEK_END
+ (the end of the file)
+
+
+
+
+
+ Replacement for g_io_channel_seek() with the new API.
+
+
+ the status of the operation.
+
+
+
+
+ a #GIOChannel
+
+
+
+ The offset in bytes from the position specified by @type
+
+
+
+ a #GSeekType. The type %G_SEEK_CUR is only allowed in those
+ cases where a call to g_io_channel_set_encoding ()
+ is allowed. See the documentation for
+ g_io_channel_set_encoding () for details.
+
+
+
+
+
+ Sets the buffer size.
+
+
+
+
+
+
+ a #GIOChannel
+
+
+
+ the size of the buffer, or 0 to let GLib pick a good size
+
+
+
+
+
+ The buffering state can only be set if the channel's encoding
+is %NULL. For any other encoding, the channel must be buffered.
+
+A buffered channel can only be set unbuffered if the channel's
+internal buffers have been flushed. Newly created channels or
+channels which have returned %G_IO_STATUS_EOF
+not require such a flush. For write-only channels, a call to
+g_io_channel_flush () is sufficient. For all other channels,
+the buffers may be flushed by a call to g_io_channel_seek_position ().
+This includes the possibility of seeking with seek type %G_SEEK_CUR
+and an offset of zero. Note that this means that socket-based
+channels cannot be set unbuffered once they have had data
+read from them.
+
+On unbuffered channels, it is safe to mix read and write
+calls from the new and old APIs, if this is necessary for
+maintaining old code.
+
+The default state of the channel is buffered.
+
+
+
+
+
+
+ a #GIOChannel
+
+
+
+ whether to set the channel buffered or unbuffered
+
+
+
+
+
+ Whether to close the channel on the final unref of the #GIOChannel
+data structure. The default value of this is %TRUE for channels
+created by g_io_channel_new_file (), and %FALSE for all other channels.
+
+Setting this flag to %TRUE for a channel you have already closed
+can cause problems when the final reference to the #GIOChannel is dropped.
+
+
+
+
+
+
+ a #GIOChannel
+
+
+
+ Whether to close the channel on the final unref of
+ the GIOChannel data structure.
+
+
+
+
+
+ Sets the encoding for the input/output of the channel.
+The internal encoding is always UTF-8. The default encoding
+for the external file is UTF-8.
+
+The encoding %NULL is safe to use with binary data.
+
+The encoding can only be set if one of the following conditions
+is true:
+
+- The channel was just created, and has not been written to or read from yet.
+
+- The channel is write-only.
+
+- The channel is a file, and the file pointer was just repositioned
+ by a call to g_io_channel_seek_position(). (This flushes all the
+ internal buffers.)
+
+- The current encoding is %NULL or UTF-8.
+
+- One of the (new API) read functions has just returned %G_IO_STATUS_EOF
+ (or, in the case of g_io_channel_read_to_end(), %G_IO_STATUS_NORMAL).
+
+- One of the functions g_io_channel_read_chars() or
+ g_io_channel_read_unichar() has returned %G_IO_STATUS_AGAIN or
+ %G_IO_STATUS_ERROR. This may be useful in the case of
+ %G_CONVERT_ERROR_ILLEGAL_SEQUENCE.
+ Returning one of these statuses from g_io_channel_read_line(),
+ g_io_channel_read_line_string(), or g_io_channel_read_to_end()
+ does not guarantee that the encoding can be changed.
+
+Channels which do not meet one of the above conditions cannot call
+g_io_channel_seek_position() with an offset of %G_SEEK_CUR, and, if
+they are "seekable", cannot call g_io_channel_write_chars() after
+calling one of the API "read" functions.
+
+
+ %G_IO_STATUS_NORMAL if the encoding was successfully set
+
+
+
+
+ a #GIOChannel
+
+
+
+ the encoding type
+
+
+
+
+
+ Sets the (writeable) flags in @channel to (@flags & %G_IO_FLAG_SET_MASK).
+
+
+ the status of the operation.
+
+
+
+
+ a #GIOChannel
+
+
+
+ the flags to set on the IO channel
+
+
+
+
+
+ This sets the string that #GIOChannel uses to determine
+where in the file a line break occurs.
+
+
+
+
+
+
+ a #GIOChannel
+
+
+
+ The line termination string. Use %NULL for
+ autodetect. Autodetection breaks on "\n", "\r\n", "\r", "\0",
+ and the Unicode paragraph separator. Autodetection should not be
+ used for anything other than file-based channels.
+
+
+
+ The length of the termination string. If -1 is passed, the
+ string is assumed to be nul-terminated. This option allows
+ termination strings with embedded nuls.
+
+
+
+
+
+ Close an IO channel. Any pending data to be written will be
+flushed if @flush is %TRUE. The channel will not be freed until the
+last reference is dropped using g_io_channel_unref().
+
+
+ the status of the operation.
+
+
+
+
+ a #GIOChannel
+
+
+
+ if %TRUE, flush pending
+
+
+
+
+
+ Returns the file descriptor of the #GIOChannel.
+
+On Windows this function returns the file descriptor or socket of
+the #GIOChannel.
+
+
+ the file descriptor of the #GIOChannel.
+
+
+
+
+ a #GIOChannel, created with g_io_channel_unix_new().
+
+
+
+
+
+ Decrements the reference count of a #GIOChannel.
+
+
+
+
+
+
+ a #GIOChannel
+
+
+
+
+
+ Writes data to a #GIOChannel.
+ Use g_io_channel_write_chars() instead.
+
+
+ %G_IO_ERROR_NONE if the operation was successful.
+
+
+
+
+ a #GIOChannel
+
+
+
+ the buffer containing the data to write
+
+
+
+ the number of bytes to write
+
+
+
+ the number of bytes actually written
+
+
+
+
+
+ Replacement for g_io_channel_write() with the new API.
+
+On seekable channels with encodings other than %NULL or UTF-8, generic
+mixing of reading and writing is not allowed. A call to g_io_channel_write_chars ()
+may only be made on a channel from which data has been read in the
+cases described in the documentation for g_io_channel_set_encoding ().
+
+
+ the status of the operation.
+
+
+
+
+ a #GIOChannel
+
+
+
+ a buffer to write data from
+
+
+
+
+
+ the size of the buffer. If -1, the buffer
+ is taken to be a nul-terminated string.
+
+
+
+ The number of bytes written. This can be nonzero
+ even if the return value is not %G_IO_STATUS_NORMAL.
+ If the return value is %G_IO_STATUS_NORMAL and the
+ channel is blocking, this will always be equal
+ to @count if @count >= 0.
+
+
+
+
+
+ Writes a Unicode character to @channel.
+This function cannot be called on a channel with %NULL encoding.
+
+
+ a #GIOStatus
+
+
+
+
+ a #GIOChannel
+
+
+
+ a character
+
+
+
+
+
+ Converts an `errno` error number to a #GIOChannelError.
+
+
+ a #GIOChannelError error number, e.g.
+ %G_IO_CHANNEL_ERROR_INVAL.
+
+
+
+
+ an `errno` error number, e.g. `EINVAL`
+
+
+
+
+
+
+
+
+
+
+
+ Error codes returned by #GIOChannel operations.
+
+
+ File too large.
+
+
+ Invalid argument.
+
+
+ IO error.
+
+
+ File is a directory.
+
+
+ No space left on device.
+
+
+ No such device or address.
+
+
+ Value too large for defined datatype.
+
+
+ Broken pipe.
+
+
+ Some other error.
+
+
+
+ A bitwise combination representing a condition to watch for on an
+event source.
+
+ There is data to read.
+
+
+ Data can be written (without blocking).
+
+
+ There is urgent data to read.
+
+
+ Error condition.
+
+
+ Hung up (the connection has been broken, usually for
+ pipes and sockets).
+
+
+ Invalid request. The file descriptor is not open.
+
+
+
+ #GIOError is only used by the deprecated functions
+g_io_channel_read(), g_io_channel_write(), and g_io_channel_seek().
+
+
+ no error
+
+
+ an EAGAIN error occurred
+
+
+ an EINVAL error occurred
+
+
+ another error occurred
+
+
+
+ Specifies properties of a #GIOChannel. Some of the flags can only be
+read with g_io_channel_get_flags(), but not changed with
+g_io_channel_set_flags().
+
+
+ no special flags set. Since: 2.74
+
+
+ turns on append mode, corresponds to %O_APPEND
+ (see the documentation of the UNIX open() syscall)
+
+
+ turns on nonblocking mode, corresponds to
+ %O_NONBLOCK/%O_NDELAY (see the documentation of the UNIX open()
+ syscall)
+
+
+ indicates that the io channel is readable.
+ This flag cannot be changed.
+
+
+ indicates that the io channel is writable.
+ This flag cannot be changed.
+
+
+ a misspelled version of @G_IO_FLAG_IS_WRITABLE
+ that existed before the spelling was fixed in GLib 2.30. It is kept
+ here for compatibility reasons. Deprecated since 2.30
+
+
+ indicates that the io channel is seekable,
+ i.e. that g_io_channel_seek_position() can be used on it.
+ This flag cannot be changed.
+
+
+ the mask that specifies all the valid flags.
+
+
+ the mask of the flags that are returned from
+ g_io_channel_get_flags()
+
+
+ the mask of the flags that the user can modify
+ with g_io_channel_set_flags()
+
+
+
+ Specifies the type of function passed to g_io_add_watch() or
+g_io_add_watch_full(), which is called when the requested condition
+on a #GIOChannel is satisfied.
+
+
+ the function should return %FALSE if the event source
+ should be removed
+
+
+
+
+ the #GIOChannel event source
+
+
+
+ the condition which has been satisfied
+
+
+
+ user data set in g_io_add_watch() or g_io_add_watch_full()
+
+
+
+
+
+ A table of functions used to handle different types of #GIOChannel
+in a generic way.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Statuses returned by most of the #GIOFuncs functions.
+
+
+ An error occurred.
+
+
+ Success.
+
+
+ End of file.
+
+
+ Resource temporarily unavailable.
+
+
+
+ Checks whether a character is a directory
+separator. It returns %TRUE for '/' on UNIX
+machines and for '\' or '/' under Windows.
+
+
+
+ a character
+
+
+
+
+ The name of the main group of a desktop entry file, as defined in the
+[Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec).
+Consult the specification for more
+details about the meanings of the keys below.
+
+
+
+
+ A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string list
+giving the available application actions.
+
+
+
+
+ A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list
+of strings giving the categories in which the desktop entry
+should be shown in a menu.
+
+
+
+
+ A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
+string giving the tooltip for the desktop entry.
+
+
+
+
+ A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
+set to true if the application is D-Bus activatable.
+
+
+
+
+ A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string
+giving the command line to execute. It is only valid for desktop
+entries with the `Application` type.
+
+
+
+
+ A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
+string giving the generic name of the desktop entry.
+
+
+
+
+ A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
+stating whether the desktop entry has been deleted by the user.
+
+
+
+
+ A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
+string giving the name of the icon to be displayed for the desktop
+entry.
+
+
+
+
+ A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list
+of strings giving the MIME types supported by this desktop entry.
+
+
+
+
+ A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
+string giving the specific name of the desktop entry.
+
+
+
+
+ A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list of
+strings identifying the environments that should not display the
+desktop entry.
+
+
+
+
+ A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
+stating whether the desktop entry should be shown in menus.
+
+
+
+
+ A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list of
+strings identifying the environments that should display the
+desktop entry.
+
+
+
+
+ A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string
+containing the working directory to run the program in. It is only
+valid for desktop entries with the `Application` type.
+
+
+
+
+ A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
+stating whether the application supports the
+[Startup Notification Protocol Specification](http://www.freedesktop.org/Standards/startup-notification-spec).
+
+
+
+
+ A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is string
+identifying the WM class or name hint of a window that the application
+will create, which can be used to emulate Startup Notification with
+older applications.
+
+
+
+
+ A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
+stating whether the program should be run in a terminal window.
+
+It is only valid for desktop entries with the `Application` type.
+
+
+
+
+ A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string
+giving the file name of a binary on disk used to determine if the
+program is actually installed. It is only valid for desktop entries
+with the `Application` type.
+
+
+
+
+ A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string
+giving the type of the desktop entry.
+
+Usually %G_KEY_FILE_DESKTOP_TYPE_APPLICATION,
+%G_KEY_FILE_DESKTOP_TYPE_LINK, or
+%G_KEY_FILE_DESKTOP_TYPE_DIRECTORY.
+
+
+
+
+ A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string
+giving the URL to access. It is only valid for desktop entries
+with the `Link` type.
+
+
+
+
+ A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string
+giving the version of the Desktop Entry Specification used for
+the desktop entry file.
+
+
+
+
+ The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop
+entries representing applications.
+
+
+
+
+ The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop
+entries representing directories.
+
+
+
+
+ The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop
+entries representing links to documents.
+
+
+
+
+ The GKeyFile struct contains only private data
+and should not be accessed directly.
+
+
+ Creates a new empty #GKeyFile object. Use
+g_key_file_load_from_file(), g_key_file_load_from_data(),
+g_key_file_load_from_dirs() or g_key_file_load_from_data_dirs() to
+read an existing key file.
+
+
+ an empty #GKeyFile.
+
+
+
+
+ Clears all keys and groups from @key_file, and decreases the
+reference count by 1. If the reference count reaches zero,
+frees the key file and all its allocated memory.
+
+
+
+
+
+
+ a #GKeyFile
+
+
+
+
+
+ Returns the value associated with @key under @group_name as a
+boolean.
+
+If @key cannot be found then %FALSE is returned and @error is set
+to %G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value
+associated with @key cannot be interpreted as a boolean then %FALSE
+is returned and @error is set to %G_KEY_FILE_ERROR_INVALID_VALUE.
+
+
+ the value associated with the key as a boolean,
+ or %FALSE if the key was not found or could not be parsed.
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name
+
+
+
+ a key
+
+
+
+
+
+ Returns the values associated with @key under @group_name as
+booleans.
+
+If @key cannot be found then %NULL is returned and @error is set to
+%G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated
+with @key cannot be interpreted as booleans then %NULL is returned
+and @error is set to %G_KEY_FILE_ERROR_INVALID_VALUE.
+
+
+
+ the values associated with the key as a list of booleans, or %NULL if the
+ key was not found or could not be parsed. The returned list of booleans
+ should be freed with g_free() when no longer needed.
+
+
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name
+
+
+
+ a key
+
+
+
+ the number of booleans returned
+
+
+
+
+
+ Retrieves a comment above @key from @group_name.
+If @key is %NULL then @comment will be read from above
+@group_name. If both @key and @group_name are %NULL, then
+@comment will be read from above the first group in the file.
+
+Note that the returned string does not include the '#' comment markers,
+but does include any whitespace after them (on each line). It includes
+the line breaks between lines, but does not include the final line break.
+
+
+ a comment that should be freed with g_free()
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name, or %NULL
+
+
+
+ a key
+
+
+
+
+
+ Returns the value associated with @key under @group_name as a
+double. If @group_name is %NULL, the start_group is used.
+
+If @key cannot be found then 0.0 is returned and @error is set to
+%G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated
+with @key cannot be interpreted as a double then 0.0 is returned
+and @error is set to %G_KEY_FILE_ERROR_INVALID_VALUE.
+
+
+ the value associated with the key as a double, or
+ 0.0 if the key was not found or could not be parsed.
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name
+
+
+
+ a key
+
+
+
+
+
+ Returns the values associated with @key under @group_name as
+doubles.
+
+If @key cannot be found then %NULL is returned and @error is set to
+%G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated
+with @key cannot be interpreted as doubles then %NULL is returned
+and @error is set to %G_KEY_FILE_ERROR_INVALID_VALUE.
+
+
+
+ the values associated with the key as a list of doubles, or %NULL if the
+ key was not found or could not be parsed. The returned list of doubles
+ should be freed with g_free() when no longer needed.
+
+
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name
+
+
+
+ a key
+
+
+
+ the number of doubles returned
+
+
+
+
+
+ Returns all groups in the key file loaded with @key_file.
+The array of returned groups will be %NULL-terminated, so
+@length may optionally be %NULL.
+
+
+ a newly-allocated %NULL-terminated array of strings.
+ Use g_strfreev() to free it.
+
+
+
+
+
+
+ a #GKeyFile
+
+
+
+ return location for the number of returned groups, or %NULL
+
+
+
+
+
+ Returns the value associated with @key under @group_name as a signed
+64-bit integer. This is similar to g_key_file_get_integer() but can return
+64-bit results without truncation.
+
+
+ the value associated with the key as a signed 64-bit integer, or
+0 if the key was not found or could not be parsed.
+
+
+
+
+ a non-%NULL #GKeyFile
+
+
+
+ a non-%NULL group name
+
+
+
+ a non-%NULL key
+
+
+
+
+
+ Returns the value associated with @key under @group_name as an
+integer.
+
+If @key cannot be found then 0 is returned and @error is set to
+%G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated
+with @key cannot be interpreted as an integer, or is out of range
+for a #gint, then 0 is returned
+and @error is set to %G_KEY_FILE_ERROR_INVALID_VALUE.
+
+
+ the value associated with the key as an integer, or
+ 0 if the key was not found or could not be parsed.
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name
+
+
+
+ a key
+
+
+
+
+
+ Returns the values associated with @key under @group_name as
+integers.
+
+If @key cannot be found then %NULL is returned and @error is set to
+%G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated
+with @key cannot be interpreted as integers, or are out of range for
+#gint, then %NULL is returned
+and @error is set to %G_KEY_FILE_ERROR_INVALID_VALUE.
+
+
+
+ the values associated with the key as a list of integers, or %NULL if
+ the key was not found or could not be parsed. The returned list of
+ integers should be freed with g_free() when no longer needed.
+
+
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name
+
+
+
+ a key
+
+
+
+ the number of integers returned
+
+
+
+
+
+ Returns all keys for the group name @group_name. The array of
+returned keys will be %NULL-terminated, so @length may
+optionally be %NULL. In the event that the @group_name cannot
+be found, %NULL is returned and @error is set to
+%G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
+
+
+ a newly-allocated %NULL-terminated array of strings.
+ Use g_strfreev() to free it.
+
+
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name
+
+
+
+ return location for the number of keys returned, or %NULL
+
+
+
+
+
+ Returns the actual locale which the result of
+g_key_file_get_locale_string() or g_key_file_get_locale_string_list()
+came from.
+
+If calling g_key_file_get_locale_string() or
+g_key_file_get_locale_string_list() with exactly the same @key_file,
+@group_name, @key and @locale, the result of those functions will
+have originally been tagged with the locale that is the result of
+this function.
+
+
+ the locale from the file, or %NULL if the key was not
+ found or the entry in the file was was untranslated
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name
+
+
+
+ a key
+
+
+
+ a locale identifier or %NULL
+
+
+
+
+
+ Returns the value associated with @key under @group_name
+translated in the given @locale if available. If @locale is
+%NULL then the current locale is assumed.
+
+If @locale is to be non-%NULL, or if the current locale will change over
+the lifetime of the #GKeyFile, it must be loaded with
+%G_KEY_FILE_KEEP_TRANSLATIONS in order to load strings for all locales.
+
+If @key cannot be found then %NULL is returned and @error is set
+to %G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the value associated
+with @key cannot be interpreted or no suitable translation can
+be found then the untranslated value is returned.
+
+
+ a newly allocated string or %NULL if the specified
+ key cannot be found.
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name
+
+
+
+ a key
+
+
+
+ a locale identifier or %NULL
+
+
+
+
+
+ Returns the values associated with @key under @group_name
+translated in the given @locale if available. If @locale is
+%NULL then the current locale is assumed.
+
+If @locale is to be non-%NULL, or if the current locale will change over
+the lifetime of the #GKeyFile, it must be loaded with
+%G_KEY_FILE_KEEP_TRANSLATIONS in order to load strings for all locales.
+
+If @key cannot be found then %NULL is returned and @error is set
+to %G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the values associated
+with @key cannot be interpreted or no suitable translations
+can be found then the untranslated values are returned. The
+returned array is %NULL-terminated, so @length may optionally
+be %NULL.
+
+
+ a newly allocated %NULL-terminated string array
+ or %NULL if the key isn't found. The string array should be freed
+ with g_strfreev().
+
+
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name
+
+
+
+ a key
+
+
+
+ a locale identifier or %NULL
+
+
+
+ return location for the number of returned strings or %NULL
+
+
+
+
+
+ Returns the name of the start group of the file.
+
+
+ The start group of the key file.
+
+
+
+
+ a #GKeyFile
+
+
+
+
+
+ Returns the string value associated with @key under @group_name.
+Unlike g_key_file_get_value(), this function handles escape sequences
+like \s.
+
+In the event the key cannot be found, %NULL is returned and
+@error is set to %G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the
+event that the @group_name cannot be found, %NULL is returned
+and @error is set to %G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
+
+
+ a newly allocated string or %NULL if the specified
+ key cannot be found.
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name
+
+
+
+ a key
+
+
+
+
+
+ Returns the values associated with @key under @group_name.
+
+In the event the key cannot be found, %NULL is returned and
+@error is set to %G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the
+event that the @group_name cannot be found, %NULL is returned
+and @error is set to %G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
+
+
+
+ a %NULL-terminated string array or %NULL if the specified
+ key cannot be found. The array should be freed with g_strfreev().
+
+
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name
+
+
+
+ a key
+
+
+
+ return location for the number of returned strings, or %NULL
+
+
+
+
+
+ Returns the value associated with @key under @group_name as an unsigned
+64-bit integer. This is similar to g_key_file_get_integer() but can return
+large positive results without truncation.
+
+
+ the value associated with the key as an unsigned 64-bit integer,
+or 0 if the key was not found or could not be parsed.
+
+
+
+
+ a non-%NULL #GKeyFile
+
+
+
+ a non-%NULL group name
+
+
+
+ a non-%NULL key
+
+
+
+
+
+ Returns the raw value associated with @key under @group_name.
+Use g_key_file_get_string() to retrieve an unescaped UTF-8 string.
+
+In the event the key cannot be found, %NULL is returned and
+@error is set to %G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the
+event that the @group_name cannot be found, %NULL is returned
+and @error is set to %G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
+
+
+ a newly allocated string or %NULL if the specified
+ key cannot be found.
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name
+
+
+
+ a key
+
+
+
+
+
+ Looks whether the key file has the group @group_name.
+
+
+ %TRUE if @group_name is a part of @key_file, %FALSE
+otherwise.
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name
+
+
+
+
+
+ Looks whether the key file has the key @key in the group
+@group_name.
+
+Note that this function does not follow the rules for #GError strictly;
+the return value both carries meaning and signals an error. To use
+this function, you must pass a #GError pointer in @error, and check
+whether it is not %NULL to see if an error occurred.
+
+Language bindings should use g_key_file_get_value() to test whether
+or not a key exists.
+
+
+ %TRUE if @key is a part of @group_name, %FALSE otherwise
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name
+
+
+
+ a key name
+
+
+
+
+
+ Loads a key file from the data in @bytes into an empty #GKeyFile structure.
+If the object cannot be created then %error is set to a #GKeyFileError.
+
+
+ %TRUE if a key file could be loaded, %FALSE otherwise
+
+
+
+
+ an empty #GKeyFile struct
+
+
+
+ a #GBytes
+
+
+
+ flags from #GKeyFileFlags
+
+
+
+
+
+ Loads a key file from memory into an empty #GKeyFile structure.
+If the object cannot be created then %error is set to a #GKeyFileError.
+
+
+ %TRUE if a key file could be loaded, %FALSE otherwise
+
+
+
+
+ an empty #GKeyFile struct
+
+
+
+ key file loaded in memory
+
+
+
+ the length of @data in bytes (or (gsize)-1 if data is nul-terminated)
+
+
+
+ flags from #GKeyFileFlags
+
+
+
+
+
+ This function looks for a key file named @file in the paths
+returned from g_get_user_data_dir() and g_get_system_data_dirs(),
+loads the file into @key_file and returns the file's full path in
+@full_path. If the file could not be loaded then an %error is
+set to either a #GFileError or #GKeyFileError.
+
+
+ %TRUE if a key file could be loaded, %FALSE otherwise
+
+
+
+
+ an empty #GKeyFile struct
+
+
+
+ a relative path to a filename to open and parse
+
+
+
+ return location for a string containing the full path
+ of the file, or %NULL
+
+
+
+ flags from #GKeyFileFlags
+
+
+
+
+
+ This function looks for a key file named @file in the paths
+specified in @search_dirs, loads the file into @key_file and
+returns the file's full path in @full_path.
+
+If the file could not be found in any of the @search_dirs,
+%G_KEY_FILE_ERROR_NOT_FOUND is returned. If
+the file is found but the OS returns an error when opening or reading the
+file, a %G_FILE_ERROR is returned. If there is a problem parsing the file, a
+%G_KEY_FILE_ERROR is returned.
+
+
+ %TRUE if a key file could be loaded, %FALSE otherwise
+
+
+
+
+ an empty #GKeyFile struct
+
+
+
+ a relative path to a filename to open and parse
+
+
+
+ %NULL-terminated array of directories to search
+
+
+
+
+
+ return location for a string containing the full path
+ of the file, or %NULL
+
+
+
+ flags from #GKeyFileFlags
+
+
+
+
+
+ Loads a key file into an empty #GKeyFile structure.
+
+If the OS returns an error when opening or reading the file, a
+%G_FILE_ERROR is returned. If there is a problem parsing the file, a
+%G_KEY_FILE_ERROR is returned.
+
+This function will never return a %G_KEY_FILE_ERROR_NOT_FOUND error. If the
+@file is not found, %G_FILE_ERROR_NOENT is returned.
+
+
+ %TRUE if a key file could be loaded, %FALSE otherwise
+
+
+
+
+ an empty #GKeyFile struct
+
+
+
+ the path of a filename to load, in the GLib filename encoding
+
+
+
+ flags from #GKeyFileFlags
+
+
+
+
+
+ Increases the reference count of @key_file.
+
+
+ the same @key_file.
+
+
+
+
+ a #GKeyFile
+
+
+
+
+
+ Removes a comment above @key from @group_name.
+If @key is %NULL then @comment will be removed above @group_name.
+If both @key and @group_name are %NULL, then @comment will
+be removed above the first group in the file.
+
+
+ %TRUE if the comment was removed, %FALSE otherwise
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name, or %NULL
+
+
+
+ a key
+
+
+
+
+
+ Removes the specified group, @group_name,
+from the key file.
+
+
+ %TRUE if the group was removed, %FALSE otherwise
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name
+
+
+
+
+
+ Removes @key in @group_name from the key file.
+
+
+ %TRUE if the key was removed, %FALSE otherwise
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name
+
+
+
+ a key name to remove
+
+
+
+
+
+ Writes the contents of @key_file to @filename using
+g_file_set_contents(). If you need stricter guarantees about durability of
+the written file than are provided by g_file_set_contents(), use
+g_file_set_contents_full() with the return value of g_key_file_to_data().
+
+This function can fail for any of the reasons that
+g_file_set_contents() may fail.
+
+
+ %TRUE if successful, else %FALSE with @error set
+
+
+
+
+ a #GKeyFile
+
+
+
+ the name of the file to write to
+
+
+
+
+
+ Associates a new boolean value with @key under @group_name.
+If @key cannot be found then it is created.
+
+
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name
+
+
+
+ a key
+
+
+
+ %TRUE or %FALSE
+
+
+
+
+
+ Associates a list of boolean values with @key under @group_name.
+If @key cannot be found then it is created.
+If @group_name is %NULL, the start_group is used.
+
+
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name
+
+
+
+ a key
+
+
+
+ an array of boolean values
+
+
+
+
+
+ length of @list
+
+
+
+
+
+ Places a comment above @key from @group_name.
+
+If @key is %NULL then @comment will be written above @group_name.
+If both @key and @group_name are %NULL, then @comment will be
+written above the first group in the file.
+
+Note that this function prepends a '#' comment marker to
+each line of @comment.
+
+
+ %TRUE if the comment was written, %FALSE otherwise
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name, or %NULL
+
+
+
+ a key
+
+
+
+ a comment
+
+
+
+
+
+ Associates a new double value with @key under @group_name.
+If @key cannot be found then it is created.
+
+
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name
+
+
+
+ a key
+
+
+
+ a double value
+
+
+
+
+
+ Associates a list of double values with @key under
+@group_name. If @key cannot be found then it is created.
+
+
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name
+
+
+
+ a key
+
+
+
+ an array of double values
+
+
+
+
+
+ number of double values in @list
+
+
+
+
+
+ Associates a new integer value with @key under @group_name.
+If @key cannot be found then it is created.
+
+
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name
+
+
+
+ a key
+
+
+
+ an integer value
+
+
+
+
+
+ Associates a new integer value with @key under @group_name.
+If @key cannot be found then it is created.
+
+
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name
+
+
+
+ a key
+
+
+
+ an integer value
+
+
+
+
+
+ Associates a list of integer values with @key under @group_name.
+If @key cannot be found then it is created.
+
+
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name
+
+
+
+ a key
+
+
+
+ an array of integer values
+
+
+
+
+
+ number of integer values in @list
+
+
+
+
+
+ Sets the character which is used to separate
+values in lists. Typically ';' or ',' are used
+as separators. The default list separator is ';'.
+
+
+
+
+
+
+ a #GKeyFile
+
+
+
+ the separator
+
+
+
+
+
+ Associates a string value for @key and @locale under @group_name.
+If the translation for @key cannot be found then it is created.
+
+
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name
+
+
+
+ a key
+
+
+
+ a locale identifier
+
+
+
+ a string
+
+
+
+
+
+ Associates a list of string values for @key and @locale under
+@group_name. If the translation for @key cannot be found then
+it is created.
+
+
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name
+
+
+
+ a key
+
+
+
+ a locale identifier
+
+
+
+ a %NULL-terminated array of locale string values
+
+
+
+
+
+ the length of @list
+
+
+
+
+
+ Associates a new string value with @key under @group_name.
+If @key cannot be found then it is created.
+If @group_name cannot be found then it is created.
+Unlike g_key_file_set_value(), this function handles characters
+that need escaping, such as newlines.
+
+
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name
+
+
+
+ a key
+
+
+
+ a string
+
+
+
+
+
+ Associates a list of string values for @key under @group_name.
+If @key cannot be found then it is created.
+If @group_name cannot be found then it is created.
+
+
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name
+
+
+
+ a key
+
+
+
+ an array of string values
+
+
+
+
+
+ number of string values in @list
+
+
+
+
+
+ Associates a new integer value with @key under @group_name.
+If @key cannot be found then it is created.
+
+
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name
+
+
+
+ a key
+
+
+
+ an integer value
+
+
+
+
+
+ Associates a new value with @key under @group_name.
+
+If @key cannot be found then it is created. If @group_name cannot
+be found then it is created. To set an UTF-8 string which may contain
+characters that need escaping (such as newlines or spaces), use
+g_key_file_set_string().
+
+
+
+
+
+
+ a #GKeyFile
+
+
+
+ a group name
+
+
+
+ a key
+
+
+
+ a string
+
+
+
+
+
+ This function outputs @key_file as a string.
+
+Note that this function never reports an error,
+so it is safe to pass %NULL as @error.
+
+
+ a newly allocated string holding
+ the contents of the #GKeyFile
+
+
+
+
+ a #GKeyFile
+
+
+
+ return location for the length of the
+ returned string, or %NULL
+
+
+
+
+
+ Decreases the reference count of @key_file by 1. If the reference count
+reaches zero, frees the key file and all its allocated memory.
+
+
+
+
+
+
+ a #GKeyFile
+
+
+
+
+
+
+
+
+
+
+
+ Error codes returned by key file parsing.
+
+
+ the text being parsed was in
+ an unknown encoding
+
+
+ document was ill-formed
+
+
+ the file was not found
+
+
+ a requested key was not found
+
+
+ a requested group was not found
+
+
+ a value could not be parsed
+
+
+
+ Flags which influence the parsing.
+
+
+ No flags, default behaviour
+
+
+ Use this flag if you plan to write the
+ (possibly modified) contents of the key file back to a file;
+ otherwise all comments will be lost when the key file is
+ written back.
+
+
+ Use this flag if you plan to write the
+ (possibly modified) contents of the key file back to a file;
+ otherwise only the translations for the current language will be
+ written back.
+
+
+
+ Hints the compiler that the expression is likely to evaluate to
+a true value. The compiler may use this information for optimizations.
+
+|[<!-- language="C" -->
+if (G_LIKELY (random () != 1))
+ g_print ("not one");
+]|
+
+
+
+ the expression
+
+
+
+
+ Specifies one of the possible types of byte order.
+See %G_BYTE_ORDER.
+
+
+
+
+ The natural logarithm of 10.
+
+
+
+
+ The natural logarithm of 2.
+
+
+
+
+ Works like g_mutex_lock(), but for a lock defined with
+%G_LOCK_DEFINE.
+
+
+
+ the name of the lock
+
+
+
+
+ The `G_LOCK_` macros provide a convenient interface to #GMutex.
+%G_LOCK_DEFINE defines a lock. It can appear in any place where
+variable definitions may appear in programs, i.e. in the first block
+of a function or outside of functions. The @name parameter will be
+mangled to get the name of the #GMutex. This means that you
+can use names of existing variables as the parameter - e.g. the name
+of the variable you intend to protect with the lock. Look at our
+give_me_next_number() example using the `G_LOCK` macros:
+
+Here is an example for using the `G_LOCK` convenience macros:
+
+|[<!-- language="C" -->
+ G_LOCK_DEFINE (current_number);
+
+ int
+ give_me_next_number (void)
+ {
+ static int current_number = 0;
+ int ret_val;
+
+ G_LOCK (current_number);
+ ret_val = current_number = calc_next_number (current_number);
+ G_UNLOCK (current_number);
+
+ return ret_val;
+ }
+]|
+
+
+
+ the name of the lock
+
+
+
+
+ This works like %G_LOCK_DEFINE, but it creates a static object.
+
+
+
+ the name of the lock
+
+
+
+
+ This declares a lock, that is defined with %G_LOCK_DEFINE in another
+module.
+
+
+
+ the name of the lock
+
+
+
+
+
+
+
+
+
+
+
+ Multiplying the base 2 exponent by this number yields the base 10 exponent.
+
+
+
+
+ Defines the log domain. See [Log Domains](#log-domains).
+
+Libraries should define this so that any messages
+which they log can be differentiated from messages from other
+libraries and application code. But be careful not to define
+it in any public header files.
+
+Log domains must be unique, and it is recommended that they are the
+application or library name, optionally followed by a hyphen and a sub-domain
+name. For example, `bloatpad` or `bloatpad-io`.
+
+If undefined, it defaults to the default %NULL (or `""`) log domain; this is
+not advisable, as it cannot be filtered against using the `G_MESSAGES_DEBUG`
+environment variable.
+
+For example, GTK+ uses this in its `Makefile.am`:
+|[
+AM_CPPFLAGS = -DG_LOG_DOMAIN=\"Gtk\"
+]|
+
+Applications can choose to leave it as the default %NULL (or `""`)
+domain. However, defining the domain offers the same advantages as
+above.
+
+
+
+
+ GLib log levels that are considered fatal by default.
+
+This is not used if structured logging is enabled; see
+[Using Structured Logging][using-structured-logging].
+
+
+
+
+ Log levels below 1<<G_LOG_LEVEL_USER_SHIFT are used by GLib.
+Higher bits can be used for user-defined log levels.
+
+
+
+
+ The #GList struct is used for each element in a doubly-linked list.
+
+
+ holds the element's data, which can be a pointer to any kind
+ of data, or any integer value using the
+ [Type Conversion Macros][glib-Type-Conversion-Macros]
+
+
+
+ contains the link to the next element in the list
+
+
+
+
+
+ contains the link to the previous element in the list
+
+
+
+
+
+ Allocates space for one #GList element. It is called by
+g_list_append(), g_list_prepend(), g_list_insert() and
+g_list_insert_sorted() and so is rarely used on its own.
+
+
+ a pointer to the newly-allocated #GList element
+
+
+
+
+
+
+ Adds a new element on to the end of the list.
+
+Note that the return value is the new start of the list,
+if @list was empty; make sure you store the new value.
+
+g_list_append() has to traverse the entire list to find the end,
+which is inefficient when adding multiple elements. A common idiom
+to avoid the inefficiency is to use g_list_prepend() and reverse
+the list with g_list_reverse() when all elements have been added.
+
+|[<!-- language="C" -->
+// Notice that these are initialized to the empty list.
+GList *string_list = NULL, *number_list = NULL;
+
+// This is a list of strings.
+string_list = g_list_append (string_list, "first");
+string_list = g_list_append (string_list, "second");
+
+// This is a list of integers.
+number_list = g_list_append (number_list, GINT_TO_POINTER (27));
+number_list = g_list_append (number_list, GINT_TO_POINTER (14));
+]|
+
+
+ either @list or the new start of the #GList if @list was %NULL
+
+
+
+
+
+
+ a pointer to a #GList
+
+
+
+
+
+ the data for the new element
+
+
+
+
+
+ Adds the second #GList onto the end of the first #GList.
+Note that the elements of the second #GList are not copied.
+They are used directly.
+
+This function is for example used to move an element in the list.
+The following example moves an element to the top of the list:
+|[<!-- language="C" -->
+list = g_list_remove_link (list, llink);
+list = g_list_concat (llink, list);
+]|
+
+
+ the start of the new #GList, which equals @list1 if not %NULL
+
+
+
+
+
+
+ a #GList, this must point to the top of the list
+
+
+
+
+
+ the #GList to add to the end of the first #GList,
+ this must point to the top of the list
+
+
+
+
+
+
+
+ Copies a #GList.
+
+Note that this is a "shallow" copy. If the list elements
+consist of pointers to data, the pointers are copied but
+the actual data is not. See g_list_copy_deep() if you need
+to copy the data as well.
+
+
+ the start of the new list that holds the same data as @list
+
+
+
+
+
+
+ a #GList, this must point to the top of the list
+
+
+
+
+
+
+
+ Makes a full (deep) copy of a #GList.
+
+In contrast with g_list_copy(), this function uses @func to make
+a copy of each list element, in addition to copying the list
+container itself.
+
+@func, as a #GCopyFunc, takes two arguments, the data to be copied
+and a @user_data pointer. On common processor architectures, it's safe to
+pass %NULL as @user_data if the copy function takes only one argument. You
+may get compiler warnings from this though if compiling with GCC’s
+`-Wcast-function-type` warning.
+
+For instance, if @list holds a list of GObjects, you can do:
+|[<!-- language="C" -->
+another_list = g_list_copy_deep (list, (GCopyFunc) g_object_ref, NULL);
+]|
+
+And, to entirely free the new list, you could do:
+|[<!-- language="C" -->
+g_list_free_full (another_list, g_object_unref);
+]|
+
+
+ the start of the new list that holds a full copy of @list,
+ use g_list_free_full() to free it
+
+
+
+
+
+
+ a #GList, this must point to the top of the list
+
+
+
+
+
+ a copy function used to copy every element in the list
+
+
+
+ user data passed to the copy function @func, or %NULL
+
+
+
+
+
+ Removes the node link_ from the list and frees it.
+Compare this to g_list_remove_link() which removes the node
+without freeing it.
+
+
+ the (possibly changed) start of the #GList
+
+
+
+
+
+
+ a #GList, this must point to the top of the list
+
+
+
+
+
+ node to delete from @list
+
+
+
+
+
+
+
+ Finds the element in a #GList which contains the given data.
+
+
+ the found #GList element, or %NULL if it is not found
+
+
+
+
+
+
+ a #GList, this must point to the top of the list
+
+
+
+
+
+ the element data to find
+
+
+
+
+
+ Finds an element in a #GList, using a supplied function to
+find the desired element. It iterates over the list, calling
+the given function which should return 0 when the desired
+element is found. The function takes two #gconstpointer arguments,
+the #GList element's data as the first argument and the
+given user data.
+
+
+ the found #GList element, or %NULL if it is not found
+
+
+
+
+
+
+ a #GList, this must point to the top of the list
+
+
+
+
+
+ user data passed to the function
+
+
+
+ the function to call for each element.
+ It should return 0 when the desired element is found
+
+
+
+
+
+ Gets the first element in a #GList.
+
+
+ the first element in the #GList,
+ or %NULL if the #GList has no elements
+
+
+
+
+
+
+ any #GList element
+
+
+
+
+
+
+
+ Calls a function for each element of a #GList.
+
+It is safe for @func to remove the element from @list, but it must
+not modify any part of the list after that element.
+
+
+
+
+
+
+ a #GList, this must point to the top of the list
+
+
+
+
+
+ the function to call with each element's data
+
+
+
+ user data to pass to the function
+
+
+
+
+
+ Frees all of the memory used by a #GList.
+The freed elements are returned to the slice allocator.
+
+If list elements contain dynamically-allocated memory, you should
+either use g_list_free_full() or free them manually first.
+
+It can be combined with g_steal_pointer() to ensure the list head pointer
+is not left dangling:
+|[<!-- language="C" -->
+GList *list_of_borrowed_things = …; /<!-- -->* (transfer container) *<!-- -->/
+g_list_free (g_steal_pointer (&list_of_borrowed_things));
+]|
+
+
+
+
+
+
+ the first link of a #GList
+
+
+
+
+
+
+
+ Frees one #GList element, but does not update links from the next and
+previous elements in the list, so you should not call this function on an
+element that is currently part of a list.
+
+It is usually used after g_list_remove_link().
+
+
+
+
+
+
+ a #GList element
+
+
+
+
+
+
+
+ Convenience method, which frees all the memory used by a #GList,
+and calls @free_func on every element's data.
+
+@free_func must not modify the list (eg, by removing the freed
+element from it).
+
+It can be combined with g_steal_pointer() to ensure the list head pointer
+is not left dangling — this also has the nice property that the head pointer
+is cleared before any of the list elements are freed, to prevent double frees
+from @free_func:
+|[<!-- language="C" -->
+GList *list_of_owned_things = …; /<!-- -->* (transfer full) (element-type GObject) *<!-- -->/
+g_list_free_full (g_steal_pointer (&list_of_owned_things), g_object_unref);
+]|
+
+
+
+
+
+
+ the first link of a #GList
+
+
+
+
+
+ the function to be called to free each element's data
+
+
+
+
+
+ Gets the position of the element containing
+the given data (starting from 0).
+
+
+ the index of the element containing the data,
+ or -1 if the data is not found
+
+
+
+
+ a #GList, this must point to the top of the list
+
+
+
+
+
+ the data to find
+
+
+
+
+
+ Inserts a new element into the list at the given position.
+
+
+ the (possibly changed) start of the #GList
+
+
+
+
+
+
+ a pointer to a #GList, this must point to the top of the list
+
+
+
+
+
+ the data for the new element
+
+
+
+ the position to insert the element. If this is
+ negative, or is larger than the number of elements in the
+ list, the new element is added on to the end of the list.
+
+
+
+
+
+ Inserts a new element into the list before the given position.
+
+
+ the (possibly changed) start of the #GList
+
+
+
+
+
+
+ a pointer to a #GList, this must point to the top of the list
+
+
+
+
+
+ the list element before which the new element
+ is inserted or %NULL to insert at the end of the list
+
+
+
+
+
+ the data for the new element
+
+
+
+
+
+ Inserts @link_ into the list before the given position.
+
+
+ the (possibly changed) start of the #GList
+
+
+
+
+
+
+ a pointer to a #GList, this must point to the top of the list
+
+
+
+
+
+ the list element before which the new element
+ is inserted or %NULL to insert at the end of the list
+
+
+
+
+
+ the list element to be added, which must not be part of
+ any other list
+
+
+
+
+
+
+
+ Inserts a new element into the list, using the given comparison
+function to determine its position.
+
+If you are adding many new elements to a list, and the number of
+new elements is much larger than the length of the list, use
+g_list_prepend() to add the new items and sort the list afterwards
+with g_list_sort().
+
+
+ the (possibly changed) start of the #GList
+
+
+
+
+
+
+ a pointer to a #GList, this must point to the top of the
+ already sorted list
+
+
+
+
+
+ the data for the new element
+
+
+
+ the function to compare elements in the list. It should
+ return a number > 0 if the first parameter comes after the
+ second parameter in the sort order.
+
+
+
+
+
+ Inserts a new element into the list, using the given comparison
+function to determine its position.
+
+If you are adding many new elements to a list, and the number of
+new elements is much larger than the length of the list, use
+g_list_prepend() to add the new items and sort the list afterwards
+with g_list_sort().
+
+
+ the (possibly changed) start of the #GList
+
+
+
+
+
+
+ a pointer to a #GList, this must point to the top of the
+ already sorted list
+
+
+
+
+
+ the data for the new element
+
+
+
+ the function to compare elements in the list. It should
+ return a number > 0 if the first parameter comes after the
+ second parameter in the sort order.
+
+
+
+ user data to pass to comparison function
+
+
+
+
+
+ Gets the last element in a #GList.
+
+
+ the last element in the #GList,
+ or %NULL if the #GList has no elements
+
+
+
+
+
+
+ any #GList element
+
+
+
+
+
+
+
+ Gets the number of elements in a #GList.
+
+This function iterates over the whole list to count its elements.
+Use a #GQueue instead of a GList if you regularly need the number
+of items. To check whether the list is non-empty, it is faster to check
+@list against %NULL.
+
+
+ the number of elements in the #GList
+
+
+
+
+ a #GList, this must point to the top of the list
+
+
+
+
+
+
+
+ Gets the element at the given position in a #GList.
+
+This iterates over the list until it reaches the @n-th position. If you
+intend to iterate over every element, it is better to use a for-loop as
+described in the #GList introduction.
+
+
+ the element, or %NULL if the position is off
+ the end of the #GList
+
+
+
+
+
+
+ a #GList, this must point to the top of the list
+
+
+
+
+
+ the position of the element, counting from 0
+
+
+
+
+
+ Gets the data of the element at the given position.
+
+This iterates over the list until it reaches the @n-th position. If you
+intend to iterate over every element, it is better to use a for-loop as
+described in the #GList introduction.
+
+
+ the element's data, or %NULL if the position
+ is off the end of the #GList
+
+
+
+
+ a #GList, this must point to the top of the list
+
+
+
+
+
+ the position of the element
+
+
+
+
+
+ Gets the element @n places before @list.
+
+
+ the element, or %NULL if the position is
+ off the end of the #GList
+
+
+
+
+
+
+ a #GList
+
+
+
+
+
+ the position of the element, counting from 0
+
+
+
+
+
+ Gets the position of the given element
+in the #GList (starting from 0).
+
+
+ the position of the element in the #GList,
+ or -1 if the element is not found
+
+
+
+
+ a #GList, this must point to the top of the list
+
+
+
+
+
+ an element in the #GList
+
+
+
+
+
+
+
+ Prepends a new element on to the start of the list.
+
+Note that the return value is the new start of the list,
+which will have changed, so make sure you store the new value.
+
+|[<!-- language="C" -->
+// Notice that it is initialized to the empty list.
+GList *list = NULL;
+
+list = g_list_prepend (list, "last");
+list = g_list_prepend (list, "first");
+]|
+
+Do not use this function to prepend a new element to a different
+element than the start of the list. Use g_list_insert_before() instead.
+
+
+ a pointer to the newly prepended element, which is the new
+ start of the #GList
+
+
+
+
+
+
+ a pointer to a #GList, this must point to the top of the list
+
+
+
+
+
+ the data for the new element
+
+
+
+
+
+ Removes an element from a #GList.
+If two elements contain the same data, only the first is removed.
+If none of the elements contain the data, the #GList is unchanged.
+
+
+ the (possibly changed) start of the #GList
+
+
+
+
+
+
+ a #GList, this must point to the top of the list
+
+
+
+
+
+ the data of the element to remove
+
+
+
+
+
+ Removes all list nodes with data equal to @data.
+Returns the new head of the list. Contrast with
+g_list_remove() which removes only the first node
+matching the given data.
+
+
+ the (possibly changed) start of the #GList
+
+
+
+
+
+
+ a #GList, this must point to the top of the list
+
+
+
+
+
+ data to remove
+
+
+
+
+
+ Removes an element from a #GList, without freeing the element.
+The removed element's prev and next links are set to %NULL, so
+that it becomes a self-contained list with one element.
+
+This function is for example used to move an element in the list
+(see the example for g_list_concat()) or to remove an element in
+the list before freeing its data:
+|[<!-- language="C" -->
+list = g_list_remove_link (list, llink);
+free_some_data_that_may_access_the_list_again (llink->data);
+g_list_free (llink);
+]|
+
+
+ the (possibly changed) start of the #GList
+
+
+
+
+
+
+ a #GList, this must point to the top of the list
+
+
+
+
+
+ an element in the #GList
+
+
+
+
+
+
+
+ Reverses a #GList.
+It simply switches the next and prev pointers of each element.
+
+
+ the start of the reversed #GList
+
+
+
+
+
+
+ a #GList, this must point to the top of the list
+
+
+
+
+
+
+
+ Sorts a #GList using the given comparison function. The algorithm
+used is a stable sort.
+
+
+ the (possibly changed) start of the #GList
+
+
+
+
+
+
+ a #GList, this must point to the top of the list
+
+
+
+
+
+ the comparison function used to sort the #GList.
+ This function is passed the data from 2 elements of the #GList
+ and should return 0 if they are equal, a negative value if the
+ first element comes before the second, or a positive value if
+ the first element comes after the second.
+
+
+
+
+
+ Like g_list_sort(), but the comparison function accepts
+a user data argument.
+
+
+ the (possibly changed) start of the #GList
+
+
+
+
+
+
+ a #GList, this must point to the top of the list
+
+
+
+
+
+ comparison function
+
+
+
+ user data to pass to comparison function
+
+
+
+
+
+
+ Structure representing a single field in a structured log entry. See
+g_log_structured() for details.
+
+Log fields may contain arbitrary values, including binary with embedded nul
+bytes. If the field contains a string, the string must be UTF-8 encoded and
+have a trailing nul byte. Otherwise, @length must be set to a non-negative
+value.
+
+
+ field name (UTF-8 string)
+
+
+
+ field value (arbitrary bytes)
+
+
+
+ length of @value, in bytes, or -1 if it is nul-terminated
+
+
+
+
+ Specifies the prototype of log handler functions.
+
+The default log handler, g_log_default_handler(), automatically appends a
+new-line character to @message when printing it. It is advised that any
+custom log handler functions behave similarly, so that logging calls in user
+code do not need modifying to add a new-line character to the message if the
+log handler is changed.
+
+This is not used if structured logging is enabled; see
+[Using Structured Logging][using-structured-logging].
+
+
+
+
+
+
+ the log domain of the message
+
+
+
+ the log level of the message (including the
+ fatal and recursion flags)
+
+
+
+ the message to process
+
+
+
+ user data, set in g_log_set_handler()
+
+
+
+
+
+ Flags specifying the level of log messages.
+
+It is possible to change how GLib treats messages of the various
+levels using g_log_set_handler() and g_log_set_fatal_mask().
+
+
+ internal flag
+
+
+ internal flag
+
+
+ log level for errors, see g_error().
+ This level is also used for messages produced by g_assert().
+
+
+ log level for critical warning messages, see
+ g_critical().
+ This level is also used for messages produced by g_return_if_fail()
+ and g_return_val_if_fail().
+
+
+ log level for warnings, see g_warning()
+
+
+ log level for messages, see g_message()
+
+
+ log level for informational messages, see g_info()
+
+
+ log level for debug messages, see g_debug()
+
+
+ a mask including all log levels
+
+
+
+ Writer function for log entries. A log entry is a collection of one or more
+#GLogFields, using the standard [field names from journal
+specification](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html).
+See g_log_structured() for more information.
+
+Writer functions must ignore fields which they do not recognise, unless they
+can write arbitrary binary output, as field values may be arbitrary binary.
+
+@log_level is guaranteed to be included in @fields as the `PRIORITY` field,
+but is provided separately for convenience of deciding whether or where to
+output the log entry.
+
+Writer functions should return %G_LOG_WRITER_HANDLED if they handled the log
+message successfully or if they deliberately ignored it. If there was an
+error handling the message (for example, if the writer function is meant to
+send messages to a remote logging server and there is a network error), it
+should return %G_LOG_WRITER_UNHANDLED. This allows writer functions to be
+chained and fall back to simpler handlers in case of failure.
+
+
+ %G_LOG_WRITER_HANDLED if the log entry was handled successfully;
+ %G_LOG_WRITER_UNHANDLED otherwise
+
+
+
+
+ log level of the message
+
+
+
+ fields forming the message
+
+
+
+
+
+ number of @fields
+
+
+
+ user data passed to g_log_set_writer_func()
+
+
+
+
+
+ Return values from #GLogWriterFuncs to indicate whether the given log entry
+was successfully handled by the writer, or whether there was an error in
+handling it (and hence a fallback writer should be used).
+
+If a #GLogWriterFunc ignores a log entry, it should return
+%G_LOG_WRITER_HANDLED.
+
+
+ Log writer has handled the log entry.
+
+
+ Log writer could not handle the log entry.
+
+
+
+ The major version number of the GLib library.
+
+Like #glib_major_version, but from the headers used at
+application compile time, rather than from the library
+linked against at application run time.
+
+
+
+
+ The maximum value which can be held in a #gint16.
+
+This is the same as standard C `INT16_MAX`, which should be
+preferred in new code.
+
+
+
+
+ The maximum value which can be held in a #gint32.
+
+This is the same as standard C `INT32_MAX`, which should be
+preferred in new code.
+
+
+
+
+ The maximum value which can be held in a #gint64.
+
+
+
+
+ The maximum value which can be held in a #gint8.
+
+This is the same as standard C `INT8_MAX`, which should be
+preferred in new code.
+
+
+
+
+ The maximum value which can be held in a #guint16.
+
+This is the same as standard C `UINT16_MAX`, which should be
+preferred in new code.
+
+
+
+
+ The maximum value which can be held in a #guint32.
+
+This is the same as standard C `UINT32_MAX`, which should be
+preferred in new code.
+
+
+
+
+ The maximum value which can be held in a #guint64.
+
+This is the same as standard C `UINT64_MAX`, which should be
+preferred in new code.
+
+
+
+
+ The maximum value which can be held in a #guint8.
+
+This is the same as standard C `UINT8_MAX`, which should be
+preferred in new code.
+
+
+
+
+ The micro version number of the GLib library.
+
+Like #gtk_micro_version, but from the headers used at
+application compile time, rather than from the library
+linked against at application run time.
+
+
+
+
+ The minimum value which can be held in a #gint16.
+
+
+
+
+ The minimum value which can be held in a #gint32.
+
+
+
+
+ The minimum value which can be held in a #gint64.
+
+
+
+
+ The minimum value which can be held in a #gint8.
+
+
+
+
+ The minor version number of the GLib library.
+
+Like #gtk_minor_version, but from the headers used at
+application compile time, rather than from the library
+linked against at application run time.
+
+
+
+
+
+
+
+
+ The `GMainContext` struct is an opaque data
+type representing a set of sources to be handled in a main loop.
+
+
+ Creates a new #GMainContext structure.
+
+
+ the new #GMainContext
+
+
+
+
+ Creates a new #GMainContext structure.
+
+
+ the new #GMainContext
+
+
+
+
+ a bitwise-OR combination of #GMainContextFlags flags that can only be
+ set at creation time.
+
+
+
+
+
+ Tries to become the owner of the specified context.
+If some other thread is the owner of the context,
+returns %FALSE immediately. Ownership is properly
+recursive: the owner can require ownership again
+and will release ownership when g_main_context_release()
+is called as many times as g_main_context_acquire().
+
+You must be the owner of a context before you
+can call g_main_context_prepare(), g_main_context_query(),
+g_main_context_check(), g_main_context_dispatch().
+
+Since 2.76 @context can be %NULL to use the global-default
+main context.
+
+
+ %TRUE if the operation succeeded, and
+ this thread is now the owner of @context.
+
+
+
+
+ a #GMainContext (if %NULL, the global-default
+ main context will be used)
+
+
+
+
+
+ Adds a file descriptor to the set of file descriptors polled for
+this context. This will very seldom be used directly. Instead
+a typical event source will use g_source_add_unix_fd() instead.
+
+
+
+
+
+
+ a #GMainContext (or %NULL for the global-default
+ main context)
+
+
+
+ a #GPollFD structure holding information about a file
+ descriptor to watch.
+
+
+
+ the priority for this file descriptor which should be
+ the same as the priority used for g_source_attach() to ensure that the
+ file descriptor is polled whenever the results may be needed.
+
+
+
+
+
+ Passes the results of polling back to the main loop. You should be
+careful to pass @fds and its length @n_fds as received from
+g_main_context_query(), as this functions relies on assumptions
+on how @fds is filled.
+
+You must have successfully acquired the context with
+g_main_context_acquire() before you may call this function.
+
+Since 2.76 @context can be %NULL to use the global-default
+main context.
+
+
+ %TRUE if some sources are ready to be dispatched.
+
+
+
+
+ a #GMainContext (if %NULL, the global-default
+ main context will be used)
+
+
+
+ the maximum numerical priority of sources to check
+
+
+
+ array of #GPollFD's that was passed to
+ the last call to g_main_context_query()
+
+
+
+
+
+ return value of g_main_context_query()
+
+
+
+
+
+ Dispatches all pending sources.
+
+You must have successfully acquired the context with
+g_main_context_acquire() before you may call this function.
+
+Since 2.76 @context can be %NULL to use the global-default
+main context.
+
+
+
+
+
+
+ a #GMainContext (if %NULL, the global-default
+ main context will be used)
+
+
+
+
+
+ Finds a source with the given source functions and user data. If
+multiple sources exist with the same source function and user data,
+the first one found will be returned.
+
+
+ the source, if one was found, otherwise %NULL
+
+
+
+
+ a #GMainContext (if %NULL, the global-default
+ main context will be used).
+
+
+
+ the @source_funcs passed to g_source_new().
+
+
+
+ the user data from the callback.
+
+
+
+
+
+ Finds a #GSource given a pair of context and ID.
+
+It is a programmer error to attempt to look up a non-existent source.
+
+More specifically: source IDs can be reissued after a source has been
+destroyed and therefore it is never valid to use this function with a
+source ID which may have already been removed. An example is when
+scheduling an idle to run in another thread with g_idle_add(): the
+idle may already have run and been removed by the time this function
+is called on its (now invalid) source ID. This source ID may have
+been reissued, leading to the operation being performed against the
+wrong source.
+
+
+ the #GSource
+
+
+
+
+ a #GMainContext (if %NULL, the global-default
+ main context will be used)
+
+
+
+ the source ID, as returned by g_source_get_id().
+
+
+
+
+
+ Finds a source with the given user data for the callback. If
+multiple sources exist with the same user data, the first
+one found will be returned.
+
+
+ the source, if one was found, otherwise %NULL
+
+
+
+
+ a #GMainContext (if %NULL, the global-default
+ main context will be used)
+
+
+
+ the user_data for the callback.
+
+
+
+
+
+ Gets the poll function set by g_main_context_set_poll_func().
+
+
+ the poll function
+
+
+
+
+ a #GMainContext (if %NULL, the global-default
+ main context will be used)
+
+
+
+
+
+ Invokes a function in such a way that @context is owned during the
+invocation of @function.
+
+If @context is %NULL then the global-default main context — as
+returned by g_main_context_default() — is used.
+
+If @context is owned by the current thread, @function is called
+directly. Otherwise, if @context is the thread-default main context
+of the current thread and g_main_context_acquire() succeeds, then
+@function is called and g_main_context_release() is called
+afterwards.
+
+In any other case, an idle source is created to call @function and
+that source is attached to @context (presumably to be run in another
+thread). The idle source is attached with %G_PRIORITY_DEFAULT
+priority. If you want a different priority, use
+g_main_context_invoke_full().
+
+Note that, as with normal idle functions, @function should probably
+return %FALSE. If it returns %TRUE, it will be continuously run in a
+loop (and may prevent this call from returning).
+
+
+
+
+
+
+ a #GMainContext, or %NULL for the global-default
+ main context
+
+
+
+ function to call
+
+
+
+ data to pass to @function
+
+
+
+
+
+ Invokes a function in such a way that @context is owned during the
+invocation of @function.
+
+This function is the same as g_main_context_invoke() except that it
+lets you specify the priority in case @function ends up being
+scheduled as an idle and also lets you give a #GDestroyNotify for @data.
+
+@notify should not assume that it is called from any particular
+thread or with any particular context acquired.
+
+
+
+
+
+
+ a #GMainContext, or %NULL for the global-default
+ main context
+
+
+
+ the priority at which to run @function
+
+
+
+ function to call
+
+
+
+ data to pass to @function
+
+
+
+ a function to call when @data is no longer in use, or %NULL.
+
+
+
+
+
+ Determines whether this thread holds the (recursive)
+ownership of this #GMainContext. This is useful to
+know before waiting on another thread that may be
+blocking to get ownership of @context.
+
+
+ %TRUE if current thread is owner of @context.
+
+
+
+
+ a #GMainContext (if %NULL, the global-default
+ main context will be used)
+
+
+
+
+
+ Runs a single iteration for the given main loop. This involves
+checking to see if any event sources are ready to be processed,
+then if no events sources are ready and @may_block is %TRUE, waiting
+for a source to become ready, then dispatching the highest priority
+events sources that are ready. Otherwise, if @may_block is %FALSE
+sources are not waited to become ready, only those highest priority
+events sources will be dispatched (if any), that are ready at this
+given moment without further waiting.
+
+Note that even when @may_block is %TRUE, it is still possible for
+g_main_context_iteration() to return %FALSE, since the wait may
+be interrupted for other reasons than an event source becoming ready.
+
+
+ %TRUE if events were dispatched.
+
+
+
+
+ a #GMainContext (if %NULL, the global-default
+ main context will be used)
+
+
+
+ whether the call may block.
+
+
+
+
+
+ Checks if any sources have pending events for the given context.
+
+
+ %TRUE if events are pending.
+
+
+
+
+ a #GMainContext (if %NULL, the global-default
+ main context will be used)
+
+
+
+
+
+ Pops @context off the thread-default context stack (verifying that
+it was on the top of the stack).
+
+
+
+
+
+
+ a #GMainContext, or %NULL for the global-default
+ main context
+
+
+
+
+
+ Prepares to poll sources within a main loop. The resulting information
+for polling is determined by calling g_main_context_query ().
+
+You must have successfully acquired the context with
+g_main_context_acquire() before you may call this function.
+
+
+ %TRUE if some source is ready to be dispatched
+ prior to polling.
+
+
+
+
+ a #GMainContext (if %NULL, the global-default
+ main context will be used)
+
+
+
+ location to store priority of highest priority
+ source already ready.
+
+
+
+
+
+ Acquires @context and sets it as the thread-default context for the
+current thread. This will cause certain asynchronous operations
+(such as most [gio][gio]-based I/O) which are
+started in this thread to run under @context and deliver their
+results to its main loop, rather than running under the global
+default main context in the main thread. Note that calling this function
+changes the context returned by g_main_context_get_thread_default(),
+not the one returned by g_main_context_default(), so it does not affect
+the context used by functions like g_idle_add().
+
+Normally you would call this function shortly after creating a new
+thread, passing it a #GMainContext which will be run by a
+#GMainLoop in that thread, to set a new default context for all
+async operations in that thread. In this case you may not need to
+ever call g_main_context_pop_thread_default(), assuming you want the
+new #GMainContext to be the default for the whole lifecycle of the
+thread.
+
+If you don't have control over how the new thread was created (e.g.
+in the new thread isn't newly created, or if the thread life
+cycle is managed by a #GThreadPool), it is always suggested to wrap
+the logic that needs to use the new #GMainContext inside a
+g_main_context_push_thread_default() / g_main_context_pop_thread_default()
+pair, otherwise threads that are re-used will end up never explicitly
+releasing the #GMainContext reference they hold.
+
+In some cases you may want to schedule a single operation in a
+non-default context, or temporarily use a non-default context in
+the main thread. In that case, you can wrap the call to the
+asynchronous operation inside a
+g_main_context_push_thread_default() /
+g_main_context_pop_thread_default() pair, but it is up to you to
+ensure that no other asynchronous operations accidentally get
+started while the non-default context is active.
+
+Beware that libraries that predate this function may not correctly
+handle being used from a thread with a thread-default context. Eg,
+see g_file_supports_thread_contexts().
+
+
+
+
+
+
+ a #GMainContext, or %NULL for the global-default
+ main context
+
+
+
+
+
+ Determines information necessary to poll this main loop. You should
+be careful to pass the resulting @fds array and its length @n_fds
+as is when calling g_main_context_check(), as this function relies
+on assumptions made when the array is filled.
+
+You must have successfully acquired the context with
+g_main_context_acquire() before you may call this function.
+
+
+ the number of records actually stored in @fds,
+ or, if more than @n_fds records need to be stored, the number
+ of records that need to be stored.
+
+
+
+
+ a #GMainContext (if %NULL, the global-default
+ main context will be used)
+
+
+
+ maximum priority source to check
+
+
+
+ location to store timeout to be used in polling
+
+
+
+ location to
+ store #GPollFD records that need to be polled.
+
+
+
+
+
+ length of @fds.
+
+
+
+
+
+ Increases the reference count on a #GMainContext object by one.
+
+
+ the @context that was passed in (since 2.6)
+
+
+
+
+ a #GMainContext
+
+
+
+
+
+ Releases ownership of a context previously acquired by this thread
+with g_main_context_acquire(). If the context was acquired multiple
+times, the ownership will be released only when g_main_context_release()
+is called as many times as it was acquired.
+
+
+
+
+
+
+ a #GMainContext (if %NULL, the global-default
+ main context will be used)
+
+
+
+
+
+ Removes file descriptor from the set of file descriptors to be
+polled for a particular context.
+
+
+
+
+
+
+ a #GMainContext (if %NULL, the global-default
+ main context will be used)
+
+
+
+ a #GPollFD descriptor previously added with g_main_context_add_poll()
+
+
+
+
+
+ Sets the function to use to handle polling of file descriptors. It
+will be used instead of the poll() system call
+(or GLib's replacement function, which is used where
+poll() isn't available).
+
+This function could possibly be used to integrate the GLib event
+loop with an external event loop.
+
+
+
+
+
+
+ a #GMainContext (if %NULL, the global-default
+ main context will be used)
+
+
+
+ the function to call to poll all file descriptors
+
+
+
+
+
+ Decreases the reference count on a #GMainContext object by one. If
+the result is zero, free the context and free all associated memory.
+
+
+
+
+
+
+ a #GMainContext
+
+
+
+
+
+ Tries to become the owner of the specified context,
+as with g_main_context_acquire(). But if another thread
+is the owner, atomically drop @mutex and wait on @cond until
+that owner releases ownership or until @cond is signaled, then
+try again (once) to become the owner.
+ Use g_main_context_is_owner() and separate locking instead.
+
+
+ %TRUE if the operation succeeded, and
+ this thread is now the owner of @context.
+
+
+
+
+ a #GMainContext (if %NULL, the global-default
+ main context will be used)
+
+
+
+ a condition variable
+
+
+
+ a mutex, currently held
+
+
+
+
+
+ If @context is currently blocking in g_main_context_iteration()
+waiting for a source to become ready, cause it to stop blocking
+and return. Otherwise, cause the next invocation of
+g_main_context_iteration() to return without blocking.
+
+This API is useful for low-level control over #GMainContext; for
+example, integrating it with main loop implementations such as
+#GMainLoop.
+
+Another related use for this function is when implementing a main
+loop with a termination condition, computed from multiple threads:
+
+|[<!-- language="C" -->
+ #define NUM_TASKS 10
+ static gint tasks_remaining = NUM_TASKS; // (atomic)
+ ...
+
+ while (g_atomic_int_get (&tasks_remaining) != 0)
+ g_main_context_iteration (NULL, TRUE);
+]|
+
+Then in a thread:
+|[<!-- language="C" -->
+ perform_work();
+
+ if (g_atomic_int_dec_and_test (&tasks_remaining))
+ g_main_context_wakeup (NULL);
+]|
+
+
+
+
+
+
+ a #GMainContext (if %NULL, the global-default
+ main context will be used)
+
+
+
+
+
+ Returns the global-default main context. This is the main context
+used for main loop functions when a main loop is not explicitly
+specified, and corresponds to the "main" main loop. See also
+g_main_context_get_thread_default().
+
+
+ the global-default main context.
+
+
+
+
+ Gets the thread-default #GMainContext for this thread. Asynchronous
+operations that want to be able to be run in contexts other than
+the default one should call this method or
+g_main_context_ref_thread_default() to get a #GMainContext to add
+their #GSources to. (Note that even in single-threaded
+programs applications may sometimes want to temporarily push a
+non-default context, so it is not safe to assume that this will
+always return %NULL if you are running in the default thread.)
+
+If you need to hold a reference on the context, use
+g_main_context_ref_thread_default() instead.
+
+
+ the thread-default #GMainContext, or
+%NULL if the thread-default context is the global-default main context.
+
+
+
+
+ Gets the thread-default #GMainContext for this thread, as with
+g_main_context_get_thread_default(), but also adds a reference to
+it with g_main_context_ref(). In addition, unlike
+g_main_context_get_thread_default(), if the thread-default context
+is the global-default context, this will return that #GMainContext
+(with a ref added to it) rather than returning %NULL.
+
+
+ the thread-default #GMainContext. Unref
+ with g_main_context_unref() when you are done with it.
+
+
+
+
+
+ Flags to pass to g_main_context_new_with_flags() which affect the behaviour
+of a #GMainContext.
+
+
+ Default behaviour.
+
+
+ Assume that polling for events will
+free the thread to process other jobs. That's useful if you're using
+`g_main_context_{prepare,query,check,dispatch}` to integrate GMainContext in
+other event loops.
+
+
+
+ The `GMainLoop` struct is an opaque data type
+representing the main event loop of a GLib or GTK+ application.
+
+
+ Creates a new #GMainLoop structure.
+
+
+ a new #GMainLoop.
+
+
+
+
+ a #GMainContext (if %NULL, the global-default
+ main context will be used).
+
+
+
+ set to %TRUE to indicate that the loop is running. This
+is not very important since calling g_main_loop_run() will set this to
+%TRUE anyway.
+
+
+
+
+
+ Returns the #GMainContext of @loop.
+
+
+ the #GMainContext of @loop
+
+
+
+
+ a #GMainLoop.
+
+
+
+
+
+ Checks to see if the main loop is currently being run via g_main_loop_run().
+
+
+ %TRUE if the mainloop is currently being run.
+
+
+
+
+ a #GMainLoop.
+
+
+
+
+
+ Stops a #GMainLoop from running. Any calls to g_main_loop_run()
+for the loop will return.
+
+Note that sources that have already been dispatched when
+g_main_loop_quit() is called will still be executed.
+
+
+
+
+
+
+ a #GMainLoop
+
+
+
+
+
+ Increases the reference count on a #GMainLoop object by one.
+
+
+ @loop
+
+
+
+
+ a #GMainLoop
+
+
+
+
+
+ Runs a main loop until g_main_loop_quit() is called on the loop.
+If this is called for the thread of the loop's #GMainContext,
+it will process events from the loop, otherwise it will
+simply wait.
+
+
+
+
+
+
+ a #GMainLoop
+
+
+
+
+
+ Decreases the reference count on a #GMainLoop object by one. If
+the result is zero, free the loop and free all associated memory.
+
+
+
+
+
+
+ a #GMainLoop
+
+
+
+
+
+
+ The #GMappedFile represents a file mapping created with
+g_mapped_file_new(). It has only private members and should
+not be accessed directly.
+
+
+ Maps a file into memory. On UNIX, this is using the mmap() function.
+
+If @writable is %TRUE, the mapped buffer may be modified, otherwise
+it is an error to modify the mapped buffer. Modifications to the buffer
+are not visible to other processes mapping the same file, and are not
+written back to the file.
+
+Note that modifications of the underlying file might affect the contents
+of the #GMappedFile. Therefore, mapping should only be used if the file
+will not be modified, or if all modifications of the file are done
+atomically (e.g. using g_file_set_contents()).
+
+If @filename is the name of an empty, regular file, the function
+will successfully return an empty #GMappedFile. In other cases of
+size 0 (e.g. device files such as /dev/null), @error will be set
+to the #GFileError value %G_FILE_ERROR_INVAL.
+
+
+ a newly allocated #GMappedFile which must be unref'd
+ with g_mapped_file_unref(), or %NULL if the mapping failed.
+
+
+
+
+ The path of the file to load, in the GLib
+ filename encoding
+
+
+
+ whether the mapping should be writable
+
+
+
+
+
+ Maps a file into memory. On UNIX, this is using the mmap() function.
+
+If @writable is %TRUE, the mapped buffer may be modified, otherwise
+it is an error to modify the mapped buffer. Modifications to the buffer
+are not visible to other processes mapping the same file, and are not
+written back to the file.
+
+Note that modifications of the underlying file might affect the contents
+of the #GMappedFile. Therefore, mapping should only be used if the file
+will not be modified, or if all modifications of the file are done
+atomically (e.g. using g_file_set_contents()).
+
+
+ a newly allocated #GMappedFile which must be unref'd
+ with g_mapped_file_unref(), or %NULL if the mapping failed.
+
+
+
+
+ The file descriptor of the file to load
+
+
+
+ whether the mapping should be writable
+
+
+
+
+
+ This call existed before #GMappedFile had refcounting and is currently
+exactly the same as g_mapped_file_unref().
+ Use g_mapped_file_unref() instead.
+
+
+
+
+
+
+ a #GMappedFile
+
+
+
+
+
+ Creates a new #GBytes which references the data mapped from @file.
+The mapped contents of the file must not be modified after creating this
+bytes object, because a #GBytes should be immutable.
+
+
+ A newly allocated #GBytes referencing data
+ from @file
+
+
+
+
+ a #GMappedFile
+
+
+
+
+
+ Returns the contents of a #GMappedFile.
+
+Note that the contents may not be zero-terminated,
+even if the #GMappedFile is backed by a text file.
+
+If the file is empty then %NULL is returned.
+
+
+ the contents of @file, or %NULL.
+
+
+
+
+ a #GMappedFile
+
+
+
+
+
+ Returns the length of the contents of a #GMappedFile.
+
+
+ the length of the contents of @file.
+
+
+
+
+ a #GMappedFile
+
+
+
+
+
+ Increments the reference count of @file by one. It is safe to call
+this function from any thread.
+
+
+ the passed in #GMappedFile.
+
+
+
+
+ a #GMappedFile
+
+
+
+
+
+ Decrements the reference count of @file by one. If the reference count
+drops to 0, unmaps the buffer of @file and frees it.
+
+It is safe to call this function from any thread.
+
+Since 2.22
+
+
+
+
+
+
+ a #GMappedFile
+
+
+
+
+
+
+ A mixed enumerated type and flags field. You must specify one type
+(string, strdup, boolean, tristate). Additionally, you may optionally
+bitwise OR the type with the flag %G_MARKUP_COLLECT_OPTIONAL.
+
+It is likely that this enum will be extended in the future to
+support other types.
+
+
+ used to terminate the list of attributes
+ to collect
+
+
+ collect the string pointer directly from
+ the attribute_values[] array. Expects a parameter of type (const
+ char **). If %G_MARKUP_COLLECT_OPTIONAL is specified and the
+ attribute isn't present then the pointer will be set to %NULL
+
+
+ as with %G_MARKUP_COLLECT_STRING, but
+ expects a parameter of type (char **) and g_strdup()s the
+ returned pointer. The pointer must be freed with g_free()
+
+
+ expects a parameter of type (gboolean *)
+ and parses the attribute value as a boolean. Sets %FALSE if the
+ attribute isn't present. Valid boolean values consist of
+ (case-insensitive) "false", "f", "no", "n", "0" and "true", "t",
+ "yes", "y", "1"
+
+
+ as with %G_MARKUP_COLLECT_BOOLEAN, but
+ in the case of a missing attribute a value is set that compares
+ equal to neither %FALSE nor %TRUE G_MARKUP_COLLECT_OPTIONAL is
+ implied
+
+
+ can be bitwise ORed with the other fields.
+ If present, allows the attribute not to appear. A default value
+ is set depending on what value type is used
+
+
+
+ Error codes returned by markup parsing.
+
+
+ text being parsed was not valid UTF-8
+
+
+ document contained nothing, or only whitespace
+
+
+ document was ill-formed
+
+
+ error should be set by #GMarkupParser
+ functions; element wasn't known
+
+
+ error should be set by #GMarkupParser
+ functions; attribute wasn't known
+
+
+ error should be set by #GMarkupParser
+ functions; content was invalid
+
+
+ error should be set by #GMarkupParser
+ functions; a required attribute was missing
+
+
+
+ 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.
+
+
+ Creates a new parse context. A parse context is used to parse
+marked-up documents. You can feed any number of documents into
+a context, as long as no errors occur; once an error occurs,
+the parse context can't continue to parse text (you have to
+free it and create a new parse context).
+
+
+ a new #GMarkupParseContext
+
+
+
+
+ a #GMarkupParser
+
+
+
+ one or more #GMarkupParseFlags
+
+
+
+ user data to pass to #GMarkupParser functions
+
+
+
+ user data destroy notifier called when
+ the parse context is freed
+
+
+
+
+
+ Signals to the #GMarkupParseContext that all data has been
+fed into the parse context with g_markup_parse_context_parse().
+
+This function reports an error if the document isn't complete,
+for example if elements are still open.
+
+
+ %TRUE on success, %FALSE if an error was set
+
+
+
+
+ a #GMarkupParseContext
+
+
+
+
+
+ Frees a #GMarkupParseContext.
+
+This function can't be called from inside one of the
+#GMarkupParser functions or while a subparser is pushed.
+
+
+
+
+
+
+ a #GMarkupParseContext
+
+
+
+
+
+ Retrieves the name of the currently open element.
+
+If called from the start_element or end_element handlers this will
+give the element_name as passed to those functions. For the parent
+elements, see g_markup_parse_context_get_element_stack().
+
+
+ the name of the currently open element, or %NULL
+
+
+
+
+ a #GMarkupParseContext
+
+
+
+
+
+ Retrieves the element stack from the internal state of the parser.
+
+The returned #GSList is a list of strings where the first item is
+the currently open tag (as would be returned by
+g_markup_parse_context_get_element()) and the next item is its
+immediate parent.
+
+This function is intended to be used in the start_element and
+end_element handlers where g_markup_parse_context_get_element()
+would merely return the name of the element that is being
+processed.
+
+
+ the element stack, which must not be modified
+
+
+
+
+
+
+ a #GMarkupParseContext
+
+
+
+
+
+ Retrieves the current line number and the number of the character on
+that line. Intended for use in error messages; there are no strict
+semantics for what constitutes the "current" line number other than
+"the best number we could come up with for error messages."
+
+
+
+
+
+
+ a #GMarkupParseContext
+
+
+
+ return location for a line number, or %NULL
+
+
+
+ return location for a char-on-line number, or %NULL
+
+
+
+
+
+ Returns the user_data associated with @context.
+
+This will either be the user_data that was provided to
+g_markup_parse_context_new() or to the most recent call
+of g_markup_parse_context_push().
+
+
+ the provided user_data. The returned data belongs to
+ the markup context and will be freed when
+ g_markup_parse_context_free() is called.
+
+
+
+
+ a #GMarkupParseContext
+
+
+
+
+
+ Feed some data to the #GMarkupParseContext.
+
+The data need not be valid UTF-8; an error will be signaled if
+it's invalid. The data need not be an entire document; you can
+feed a document into the parser incrementally, via multiple calls
+to this function. Typically, as you receive data from a network
+connection or file, you feed each received chunk of data into this
+function, aborting the process if an error occurs. Once an error
+is reported, no further data may be fed to the #GMarkupParseContext;
+all errors are fatal.
+
+
+ %FALSE if an error occurred, %TRUE on success
+
+
+
+
+ a #GMarkupParseContext
+
+
+
+ chunk of text to parse
+
+
+
+ length of @text in bytes
+
+
+
+
+
+ Completes the process of a temporary sub-parser redirection.
+
+This function exists to collect the user_data allocated by a
+matching call to g_markup_parse_context_push(). It must be called
+in the end_element handler corresponding to the start_element
+handler during which g_markup_parse_context_push() was called.
+You must not call this function from the error callback -- the
+@user_data is provided directly to the callback in that case.
+
+This function is not intended to be directly called by users
+interested in invoking subparsers. Instead, it is intended to
+be used by the subparsers themselves to implement a higher-level
+interface.
+
+
+ the user data passed to g_markup_parse_context_push()
+
+
+
+
+ a #GMarkupParseContext
+
+
+
+
+
+ Temporarily redirects markup data to a sub-parser.
+
+This function may only be called from the start_element handler of
+a #GMarkupParser. It must be matched with a corresponding call to
+g_markup_parse_context_pop() in the matching end_element handler
+(except in the case that the parser aborts due to an error).
+
+All tags, text and other data between the matching tags is
+redirected to the subparser given by @parser. @user_data is used
+as the user_data for that parser. @user_data is also passed to the
+error callback in the event that an error occurs. This includes
+errors that occur in subparsers of the subparser.
+
+The end tag matching the start tag for which this call was made is
+handled by the previous parser (which is given its own user_data)
+which is why g_markup_parse_context_pop() is provided to allow "one
+last access" to the @user_data provided to this function. In the
+case of error, the @user_data provided here is passed directly to
+the error callback of the subparser and g_markup_parse_context_pop()
+should not be called. In either case, if @user_data was allocated
+then it ought to be freed from both of these locations.
+
+This function is not intended to be directly called by users
+interested in invoking subparsers. Instead, it is intended to be
+used by the subparsers themselves to implement a higher-level
+interface.
+
+As an example, see the following implementation of a simple
+parser that counts the number of tags encountered.
+
+|[<!-- language="C" -->
+typedef struct
+{
+ gint tag_count;
+} CounterData;
+
+static void
+counter_start_element (GMarkupParseContext *context,
+ const gchar *element_name,
+ const gchar **attribute_names,
+ const gchar **attribute_values,
+ gpointer user_data,
+ GError **error)
+{
+ CounterData *data = user_data;
+
+ data->tag_count++;
+}
+
+static void
+counter_error (GMarkupParseContext *context,
+ GError *error,
+ gpointer user_data)
+{
+ CounterData *data = user_data;
+
+ g_slice_free (CounterData, data);
+}
+
+static GMarkupParser counter_subparser =
+{
+ counter_start_element,
+ NULL,
+ NULL,
+ NULL,
+ counter_error
+};
+]|
+
+In order to allow this parser to be easily used as a subparser, the
+following interface is provided:
+
+|[<!-- language="C" -->
+void
+start_counting (GMarkupParseContext *context)
+{
+ CounterData *data = g_slice_new (CounterData);
+
+ data->tag_count = 0;
+ g_markup_parse_context_push (context, &counter_subparser, data);
+}
+
+gint
+end_counting (GMarkupParseContext *context)
+{
+ CounterData *data = g_markup_parse_context_pop (context);
+ int result;
+
+ result = data->tag_count;
+ g_slice_free (CounterData, data);
+
+ return result;
+}
+]|
+
+The subparser would then be used as follows:
+
+|[<!-- language="C" -->
+static void start_element (context, element_name, ...)
+{
+ if (strcmp (element_name, "count-these") == 0)
+ start_counting (context);
+
+ // else, handle other tags...
+}
+
+static void end_element (context, element_name, ...)
+{
+ if (strcmp (element_name, "count-these") == 0)
+ g_print ("Counted %d tags\n", end_counting (context));
+
+ // else, handle other tags...
+}
+]|
+
+
+
+
+
+
+ a #GMarkupParseContext
+
+
+
+ a #GMarkupParser
+
+
+
+ user data to pass to #GMarkupParser functions
+
+
+
+
+
+ Increases the reference count of @context.
+
+
+ the same @context
+
+
+
+
+ a #GMarkupParseContext
+
+
+
+
+
+ Decreases the reference count of @context. When its reference count
+drops to 0, it is freed.
+
+
+
+
+
+
+ a #GMarkupParseContext
+
+
+
+
+
+
+ Flags that affect the behaviour of the parser.
+
+
+ No special behaviour. Since: 2.74
+
+
+ flag you should not use
+
+
+ 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
+ `<![CDATA[` and `]]>`) is
+ passed to the @text function. This flag was added in GLib 2.12
+
+
+ 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
+
+
+ Ignore (don't report) qualified
+ attributes and tags, along with their contents. A qualified
+ attribute or tag is one that contains ':' in its name (ie: is in
+ another namespace). Since: 2.40.
+
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ A GMatchInfo is an opaque struct used to return information about
+matches.
+
+
+ Returns a new string containing the text in @string_to_expand with
+references and escape sequences expanded. References refer to the last
+match done with @string against @regex and have the same syntax used by
+g_regex_replace().
+
+The @string_to_expand must be UTF-8 encoded even if %G_REGEX_RAW was
+passed to g_regex_new().
+
+The backreferences are extracted from the string passed to the match
+function, so you cannot call this function after freeing the string.
+
+@match_info may be %NULL in which case @string_to_expand must not
+contain references. For instance "foo\n" does not refer to an actual
+pattern and '\n' merely will be replaced with \n character,
+while to expand "\0" (whole match) one needs the result of a match.
+Use g_regex_check_replacement() to find out whether @string_to_expand
+contains references.
+
+
+ the expanded string, or %NULL if an error occurred
+
+
+
+
+ a #GMatchInfo or %NULL
+
+
+
+ the string to expand
+
+
+
+
+
+ Retrieves the text matching the @match_num'th capturing
+parentheses. 0 is the full text of the match, 1 is the first paren
+set, 2 the second, and so on.
+
+If @match_num is a valid sub pattern but it didn't match anything
+(e.g. sub pattern 1, matching "b" against "(a)?b") then an empty
+string is returned.
+
+If the match was obtained using the DFA algorithm, that is using
+g_regex_match_all() or g_regex_match_all_full(), the retrieved
+string is not that of a set of parentheses but that of a matched
+substring. Substrings are matched in reverse order of length, so
+0 is the longest match.
+
+The string is fetched from the string passed to the match function,
+so you cannot call this function after freeing the string.
+
+
+ The matched substring, or %NULL if an error
+ occurred. You have to free the string yourself
+
+
+
+
+ #GMatchInfo structure
+
+
+
+ number of the sub expression
+
+
+
+
+
+ Bundles up pointers to each of the matching substrings from a match
+and stores them in an array of gchar pointers. The first element in
+the returned array is the match number 0, i.e. the entire matched
+text.
+
+If a sub pattern didn't match anything (e.g. sub pattern 1, matching
+"b" against "(a)?b") then an empty string is inserted.
+
+If the last match was obtained using the DFA algorithm, that is using
+g_regex_match_all() or g_regex_match_all_full(), the retrieved
+strings are not that matched by sets of parentheses but that of the
+matched substring. Substrings are matched in reverse order of length,
+so the first one is the longest match.
+
+The strings are fetched from the string passed to the match function,
+so you cannot call this function after freeing the string.
+
+
+ a %NULL-terminated array of gchar *
+ pointers. It must be freed using g_strfreev(). If the previous
+ match failed %NULL is returned
+
+
+
+
+
+
+ a #GMatchInfo structure
+
+
+
+
+
+ Retrieves the text matching the capturing parentheses named @name.
+
+If @name is a valid sub pattern name but it didn't match anything
+(e.g. sub pattern "X", matching "b" against "(?P<X>a)?b")
+then an empty string is returned.
+
+The string is fetched from the string passed to the match function,
+so you cannot call this function after freeing the string.
+
+
+ The matched substring, or %NULL if an error
+ occurred. You have to free the string yourself
+
+
+
+
+ #GMatchInfo structure
+
+
+
+ name of the subexpression
+
+
+
+
+
+ Retrieves the position in bytes of the capturing parentheses named @name.
+
+If @name is a valid sub pattern name but it didn't match anything
+(e.g. sub pattern "X", matching "b" against "(?P<X>a)?b")
+then @start_pos and @end_pos are set to -1 and %TRUE is returned.
+
+
+ %TRUE if the position was fetched, %FALSE otherwise.
+ If the position cannot be fetched, @start_pos and @end_pos
+ are left unchanged.
+
+
+
+
+ #GMatchInfo structure
+
+
+
+ name of the subexpression
+
+
+
+ pointer to location where to store
+ the start position, or %NULL
+
+
+
+ pointer to location where to store
+ the end position, or %NULL
+
+
+
+
+
+ Retrieves the position in bytes of the @match_num'th capturing
+parentheses. 0 is the full text of the match, 1 is the first
+paren set, 2 the second, and so on.
+
+If @match_num is a valid sub pattern but it didn't match anything
+(e.g. sub pattern 1, matching "b" against "(a)?b") then @start_pos
+and @end_pos are set to -1 and %TRUE is returned.
+
+If the match was obtained using the DFA algorithm, that is using
+g_regex_match_all() or g_regex_match_all_full(), the retrieved
+position is not that of a set of parentheses but that of a matched
+substring. Substrings are matched in reverse order of length, so
+0 is the longest match.
+
+
+ %TRUE if the position was fetched, %FALSE otherwise. If
+ the position cannot be fetched, @start_pos and @end_pos are left
+ unchanged
+
+
+
+
+ #GMatchInfo structure
+
+
+
+ number of the sub expression
+
+
+
+ pointer to location where to store
+ the start position, or %NULL
+
+
+
+ pointer to location where to store
+ the end position, or %NULL
+
+
+
+
+
+ If @match_info is not %NULL, calls g_match_info_unref(); otherwise does
+nothing.
+
+
+
+
+
+
+ a #GMatchInfo, or %NULL
+
+
+
+
+
+ Retrieves the number of matched substrings (including substring 0,
+that is the whole matched text), so 1 is returned if the pattern
+has no substrings in it and 0 is returned if the match failed.
+
+If the last match was obtained using the DFA algorithm, that is
+using g_regex_match_all() or g_regex_match_all_full(), the retrieved
+count is not that of the number of capturing parentheses but that of
+the number of matched substrings.
+
+
+ Number of matched substrings, or -1 if an error occurred
+
+
+
+
+ a #GMatchInfo structure
+
+
+
+
+
+ Returns #GRegex object used in @match_info. It belongs to Glib
+and must not be freed. Use g_regex_ref() if you need to keep it
+after you free @match_info object.
+
+
+ #GRegex object used in @match_info
+
+
+
+
+ a #GMatchInfo
+
+
+
+
+
+ Returns the string searched with @match_info. This is the
+string passed to g_regex_match() or g_regex_replace() so
+you may not free it before calling this function.
+
+
+ the string searched with @match_info
+
+
+
+
+ a #GMatchInfo
+
+
+
+
+
+ Usually if the string passed to g_regex_match*() matches as far as
+it goes, but is too short to match the entire pattern, %FALSE is
+returned. There are circumstances where it might be helpful to
+distinguish this case from other cases in which there is no match.
+
+Consider, for example, an application where a human is required to
+type in data for a field with specific formatting requirements. An
+example might be a date in the form ddmmmyy, defined by the pattern
+"^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$".
+If the application sees the user’s keystrokes one by one, and can
+check that what has been typed so far is potentially valid, it is
+able to raise an error as soon as a mistake is made.
+
+GRegex supports the concept of partial matching by means of the
+%G_REGEX_MATCH_PARTIAL_SOFT and %G_REGEX_MATCH_PARTIAL_HARD flags.
+When they are used, the return code for
+g_regex_match() or g_regex_match_full() is, as usual, %TRUE
+for a complete match, %FALSE otherwise. But, when these functions
+return %FALSE, you can check if the match was partial calling
+g_match_info_is_partial_match().
+
+The difference between %G_REGEX_MATCH_PARTIAL_SOFT and
+%G_REGEX_MATCH_PARTIAL_HARD is that when a partial match is encountered
+with %G_REGEX_MATCH_PARTIAL_SOFT, matching continues to search for a
+possible complete match, while with %G_REGEX_MATCH_PARTIAL_HARD matching
+stops at the partial match.
+When both %G_REGEX_MATCH_PARTIAL_SOFT and %G_REGEX_MATCH_PARTIAL_HARD
+are set, the latter takes precedence.
+
+There were formerly some restrictions on the pattern for partial matching.
+The restrictions no longer apply.
+
+See pcrepartial(3) for more information on partial matching.
+
+
+ %TRUE if the match was partial, %FALSE otherwise
+
+
+
+
+ a #GMatchInfo structure
+
+
+
+
+
+ Returns whether the previous match operation succeeded.
+
+
+ %TRUE if the previous match operation succeeded,
+ %FALSE otherwise
+
+
+
+
+ a #GMatchInfo structure
+
+
+
+
+
+ Scans for the next match using the same parameters of the previous
+call to g_regex_match_full() or g_regex_match() that returned
+@match_info.
+
+The match is done on the string passed to the match function, so you
+cannot free it before calling this function.
+
+
+ %TRUE is the string matched, %FALSE otherwise
+
+
+
+
+ a #GMatchInfo structure
+
+
+
+
+
+ Increases reference count of @match_info by 1.
+
+
+ @match_info
+
+
+
+
+ a #GMatchInfo
+
+
+
+
+
+ Decreases reference count of @match_info by 1. When reference count drops
+to zero, it frees all the memory associated with the match_info structure.
+
+
+
+
+
+
+ a #GMatchInfo
+
+
+
+
+
+
+ A set of functions used to perform memory allocation. The same #GMemVTable must
+be used for all allocations in the same program; a call to g_mem_set_vtable(),
+if it exists, should be prior to any use of GLib.
+
+This functions related to this has been deprecated in 2.46, and no longer work.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The #GMutex struct is an opaque data structure to represent a mutex
+(mutual exclusion). It can be used to protect data against shared
+access.
+
+Take for example the following function:
+|[<!-- language="C" -->
+ int
+ give_me_next_number (void)
+ {
+ static int current_number = 0;
+
+ // now do a very complicated calculation to calculate the new
+ // number, this might for example be a random number generator
+ current_number = calc_next_number (current_number);
+
+ return current_number;
+ }
+]|
+It is easy to see that this won't work in a multi-threaded
+application. There current_number must be protected against shared
+access. A #GMutex can be used as a solution to this problem:
+|[<!-- language="C" -->
+ int
+ give_me_next_number (void)
+ {
+ static GMutex mutex;
+ static int current_number = 0;
+ int ret_val;
+
+ g_mutex_lock (&mutex);
+ ret_val = current_number = calc_next_number (current_number);
+ g_mutex_unlock (&mutex);
+
+ return ret_val;
+ }
+]|
+Notice that the #GMutex is not initialised to any particular value.
+Its placement in static storage ensures that it will be initialised
+to all-zeros, which is appropriate.
+
+If a #GMutex is placed in other contexts (eg: embedded in a struct)
+then it must be explicitly initialised using g_mutex_init().
+
+A #GMutex should only be accessed via g_mutex_ functions.
+
+
+
+
+
+
+
+
+
+
+ Frees the resources allocated to a mutex with g_mutex_init().
+
+This function should not be used with a #GMutex that has been
+statically allocated.
+
+Calling g_mutex_clear() on a locked mutex leads to undefined
+behaviour.
+
+
+
+
+
+
+ an initialized #GMutex
+
+
+
+
+
+ Initializes a #GMutex so that it can be used.
+
+This function is useful to initialize a mutex that has been
+allocated on the stack, or as part of a larger structure.
+It is not necessary to initialize a mutex that has been
+statically allocated.
+
+|[<!-- language="C" -->
+ typedef struct {
+ GMutex m;
+ ...
+ } Blob;
+
+Blob *b;
+
+b = g_new (Blob, 1);
+g_mutex_init (&b->m);
+]|
+
+To undo the effect of g_mutex_init() when a mutex is no longer
+needed, use g_mutex_clear().
+
+Calling g_mutex_init() on an already initialized #GMutex leads
+to undefined behaviour.
+
+
+
+
+
+
+ an uninitialized #GMutex
+
+
+
+
+
+ Locks @mutex. If @mutex is already locked by another thread, the
+current thread will block until @mutex is unlocked by the other
+thread.
+
+#GMutex is neither guaranteed to be recursive nor to be
+non-recursive. As such, calling g_mutex_lock() on a #GMutex that has
+already been locked by the same thread results in undefined behaviour
+(including but not limited to deadlocks).
+
+
+
+
+
+
+ a #GMutex
+
+
+
+
+
+ Tries to lock @mutex. If @mutex is already locked by another thread,
+it immediately returns %FALSE. Otherwise it locks @mutex and returns
+%TRUE.
+
+#GMutex is neither guaranteed to be recursive nor to be
+non-recursive. As such, calling g_mutex_lock() on a #GMutex that has
+already been locked by the same thread results in undefined behaviour
+(including but not limited to deadlocks or arbitrary return values).
+
+
+ %TRUE if @mutex could be locked
+
+
+
+
+ a #GMutex
+
+
+
+
+
+ Unlocks @mutex. If another thread is blocked in a g_mutex_lock()
+call for @mutex, it will become unblocked and can lock @mutex itself.
+
+Calling g_mutex_unlock() on a mutex that is not locked by the
+current thread leads to undefined behaviour.
+
+
+
+
+
+
+ a #GMutex
+
+
+
+
+
+
+ Returns %TRUE if a #GNode is a leaf node.
+
+
+
+ a #GNode
+
+
+
+
+ Returns %TRUE if a #GNode is the root of a tree.
+
+
+
+ a #GNode
+
+
+
+
+ Determines the number of elements in an array. The array must be
+declared so the compiler knows its size at compile-time; this
+macro will not work on an array allocated on the heap, only static
+arrays or arrays on the stack.
+
+
+
+ the array
+
+
+
+
+ The #GNode struct represents one node in a [n-ary tree][glib-N-ary-Trees].
+
+
+ contains the actual data of the node.
+
+
+
+ points to the node's next sibling (a sibling is another
+ #GNode with the same parent).
+
+
+
+ points to the node's previous sibling.
+
+
+
+ points to the parent of the #GNode, or is %NULL if the
+ #GNode is the root of the tree.
+
+
+
+ points to the first child of the #GNode. The other
+ children are accessed by using the @next pointer of each
+ child.
+
+
+
+ Gets the position of the first child of a #GNode
+which contains the given data.
+
+
+ the index of the child of @node which contains
+ @data, or -1 if the data is not found
+
+
+
+
+ a #GNode
+
+
+
+ the data to find
+
+
+
+
+
+ Gets the position of a #GNode with respect to its siblings.
+@child must be a child of @node. The first child is numbered 0,
+the second 1, and so on.
+
+
+ the position of @child with respect to its siblings
+
+
+
+
+ a #GNode
+
+
+
+ a child of @node
+
+
+
+
+
+ Calls a function for each of the children of a #GNode. Note that it
+doesn't descend beneath the child nodes. @func must not do anything
+that would modify the structure of the tree.
+
+
+
+
+
+
+ a #GNode
+
+
+
+ which types of children are to be visited, one of
+ %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES
+
+
+
+ the function to call for each visited node
+
+
+
+ user data to pass to the function
+
+
+
+
+
+ Recursively copies a #GNode (but does not deep-copy the data inside the
+nodes, see g_node_copy_deep() if you need that).
+
+
+ a new #GNode containing the same data pointers
+
+
+
+
+ a #GNode
+
+
+
+
+
+ Recursively copies a #GNode and its data.
+
+
+ a new #GNode containing copies of the data in @node.
+
+
+
+
+ a #GNode
+
+
+
+ the function which is called to copy the data inside each node,
+ or %NULL to use the original data.
+
+
+
+ data to pass to @copy_func
+
+
+
+
+
+ Gets the depth of a #GNode.
+
+If @node is %NULL the depth is 0. The root node has a depth of 1.
+For the children of the root node the depth is 2. And so on.
+
+
+ the depth of the #GNode
+
+
+
+
+ a #GNode
+
+
+
+
+
+ Removes @root and its children from the tree, freeing any memory
+allocated.
+
+
+
+
+
+
+ the root of the tree/subtree to destroy
+
+
+
+
+
+ Finds a #GNode in a tree.
+
+
+ the found #GNode, or %NULL if the data is not found
+
+
+
+
+ the root #GNode of the tree to search
+
+
+
+ the order in which nodes are visited - %G_IN_ORDER,
+ %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER
+
+
+
+ which types of children are to be searched, one of
+ %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES
+
+
+
+ the data to find
+
+
+
+
+
+ Finds the first child of a #GNode with the given data.
+
+
+ the found child #GNode, or %NULL if the data is not found
+
+
+
+
+ a #GNode
+
+
+
+ which types of children are to be searched, one of
+ %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES
+
+
+
+ the data to find
+
+
+
+
+
+ Gets the first sibling of a #GNode.
+This could possibly be the node itself.
+
+
+ the first sibling of @node
+
+
+
+
+ a #GNode
+
+
+
+
+
+ Gets the root of a tree.
+
+
+ the root of the tree
+
+
+
+
+ a #GNode
+
+
+
+
+
+ Inserts a #GNode beneath the parent at the given position.
+
+
+ the inserted #GNode
+
+
+
+
+ the #GNode to place @node under
+
+
+
+ the position to place @node at, with respect to its siblings
+ If position is -1, @node is inserted as the last child of @parent
+
+
+
+ the #GNode to insert
+
+
+
+
+
+ Inserts a #GNode beneath the parent after the given sibling.
+
+
+ the inserted #GNode
+
+
+
+
+ the #GNode to place @node under
+
+
+
+ the sibling #GNode to place @node after.
+ If sibling is %NULL, the node is inserted as the first child of @parent.
+
+
+
+ the #GNode to insert
+
+
+
+
+
+ Inserts a #GNode beneath the parent before the given sibling.
+
+
+ the inserted #GNode
+
+
+
+
+ the #GNode to place @node under
+
+
+
+ the sibling #GNode to place @node before.
+ If sibling is %NULL, the node is inserted as the last child of @parent.
+
+
+
+ the #GNode to insert
+
+
+
+
+
+ Returns %TRUE if @node is an ancestor of @descendant.
+This is true if node is the parent of @descendant,
+or if node is the grandparent of @descendant etc.
+
+
+ %TRUE if @node is an ancestor of @descendant
+
+
+
+
+ a #GNode
+
+
+
+ a #GNode
+
+
+
+
+
+ Gets the last child of a #GNode.
+
+
+ the last child of @node, or %NULL if @node has no children
+
+
+
+
+ a #GNode (must not be %NULL)
+
+
+
+
+
+ Gets the last sibling of a #GNode.
+This could possibly be the node itself.
+
+
+ the last sibling of @node
+
+
+
+
+ a #GNode
+
+
+
+
+
+ Gets the maximum height of all branches beneath a #GNode.
+This is the maximum distance from the #GNode to all leaf nodes.
+
+If @root is %NULL, 0 is returned. If @root has no children,
+1 is returned. If @root has children, 2 is returned. And so on.
+
+
+ the maximum height of the tree beneath @root
+
+
+
+
+ a #GNode
+
+
+
+
+
+ Gets the number of children of a #GNode.
+
+
+ the number of children of @node
+
+
+
+
+ a #GNode
+
+
+
+
+
+ Gets the number of nodes in a tree.
+
+
+ the number of nodes in the tree
+
+
+
+
+ a #GNode
+
+
+
+ which types of children are to be counted, one of
+ %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES
+
+
+
+
+
+ Gets a child of a #GNode, using the given index.
+The first child is at index 0. If the index is
+too big, %NULL is returned.
+
+
+ the child of @node at index @n
+
+
+
+
+ a #GNode
+
+
+
+ the index of the desired child
+
+
+
+
+
+ Inserts a #GNode as the first child of the given parent.
+
+
+ the inserted #GNode
+
+
+
+
+ the #GNode to place the new #GNode under
+
+
+
+ the #GNode to insert
+
+
+
+
+
+ Reverses the order of the children of a #GNode.
+(It doesn't change the order of the grandchildren.)
+
+
+
+
+
+
+ a #GNode.
+
+
+
+
+
+ Traverses a tree starting at the given root #GNode.
+It calls the given function for each node visited.
+The traversal can be halted at any point by returning %TRUE from @func.
+@func must not do anything that would modify the structure of the tree.
+
+
+
+
+
+
+ the root #GNode of the tree to traverse
+
+
+
+ the order in which nodes are visited - %G_IN_ORDER,
+ %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER.
+
+
+
+ which types of children are to be visited, one of
+ %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES
+
+
+
+ the maximum depth of the traversal. Nodes below this
+ depth will not be visited. If max_depth is -1 all nodes in
+ the tree are visited. If depth is 1, only the root is visited.
+ If depth is 2, the root and its children are visited. And so on.
+
+
+
+ the function to call for each visited #GNode
+
+
+
+ user data to pass to the function
+
+
+
+
+
+ Unlinks a #GNode from a tree, resulting in two separate trees.
+
+
+
+
+
+
+ the #GNode to unlink, which becomes the root of a new tree
+
+
+
+
+
+ Creates a new #GNode containing the given data.
+Used to create the first node in a tree.
+
+
+ a new #GNode
+
+
+
+
+ the data of the new node
+
+
+
+
+
+
+ Specifies the type of function passed to g_node_children_foreach().
+The function is called with each child node, together with the user
+data passed to g_node_children_foreach().
+
+
+
+
+
+
+ a #GNode.
+
+
+
+ user data passed to g_node_children_foreach().
+
+
+
+
+
+ Specifies the type of function passed to g_node_traverse(). The
+function is called with each of the nodes visited, together with the
+user data passed to g_node_traverse(). If the function returns
+%TRUE, then the traversal is stopped.
+
+
+ %TRUE to stop the traversal.
+
+
+
+
+ a #GNode.
+
+
+
+ user data passed to g_node_traverse().
+
+
+
+
+
+ Defines how a Unicode string is transformed in a canonical
+form, standardizing such issues as whether a character with
+an accent is represented as a base character and combining
+accent or as a single precomposed character. Unicode strings
+should generally be normalized before comparing them.
+
+
+ standardize differences that do not affect the
+ text content, such as the above-mentioned accent representation
+
+
+ another name for %G_NORMALIZE_DEFAULT
+
+
+ like %G_NORMALIZE_DEFAULT, but with
+ composed forms rather than a maximally decomposed form
+
+
+ another name for %G_NORMALIZE_DEFAULT_COMPOSE
+
+
+ beyond %G_NORMALIZE_DEFAULT also standardize the
+ "compatibility" characters in Unicode, such as SUPERSCRIPT THREE
+ to the standard forms (in this case DIGIT THREE). Formatting
+ information may be lost but for most text operations such
+ characters should be considered the same
+
+
+ another name for %G_NORMALIZE_ALL
+
+
+ like %G_NORMALIZE_ALL, but with composed
+ forms rather than a maximally decomposed form
+
+
+ another name for %G_NORMALIZE_ALL_COMPOSE
+
+
+
+ Error codes returned by functions converting a string to a number.
+
+
+ String was not a valid number.
+
+
+ String was a number, but out of bounds.
+
+
+
+ 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 `argv`. 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 `argv`
+for leftover arguments has the advantage that GOption takes care of
+necessary encoding conversions for strings or filenames.
+
+
+
+
+ A #GOnce struct controls a one-time initialization function. Any
+one-time initialization function must have its own unique #GOnce
+struct.
+
+
+ the status of the #GOnce
+
+
+
+ the value returned by the call to the function, if @status
+ is %G_ONCE_STATUS_READY
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Function to be called when starting a critical initialization
+section. The argument @location must point to a static
+0-initialized variable that will be set to a value other than 0 at
+the end of the initialization section. In combination with
+g_once_init_leave() and the unique address @value_location, it can
+be ensured that an initialization section will be executed only once
+during a program's life time, and that concurrent threads are
+blocked until initialization completed. To be used in constructs
+like this:
+
+|[<!-- language="C" -->
+ static gsize initialization_value = 0;
+
+ if (g_once_init_enter (&initialization_value))
+ {
+ gsize setup_value = 42; // initialization code here
+
+ g_once_init_leave (&initialization_value, setup_value);
+ }
+
+ // use initialization_value here
+]|
+
+While @location has a `volatile` qualifier, this is a historical artifact and
+the pointer passed to it should not be `volatile`.
+
+
+ %TRUE if the initialization section should be entered,
+ %FALSE and blocks otherwise
+
+
+
+
+ location of a static initializable variable
+ containing 0
+
+
+
+
+
+ Counterpart to g_once_init_enter(). Expects a location of a static
+0-initialized initialization variable, and an initialization value
+other than 0. Sets the variable to the initialization value, and
+releases concurrent threads blocking in g_once_init_enter() on this
+initialization variable.
+
+While @location has a `volatile` qualifier, this is a historical artifact and
+the pointer passed to it should not be `volatile`.
+
+
+
+
+
+
+ location of a static initializable variable
+ containing 0
+
+
+
+ new non-0 value for *@value_location
+
+
+
+
+
+
+ The possible statuses of a one-time initialization function
+controlled by a #GOnce struct.
+
+
+ the function has not been called yet.
+
+
+ the function call is currently in progress.
+
+
+ the function has been called.
+
+
+
+ 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: `-x arg`, with a long
+option: `--name arg` or combined in a single argument: `--name=arg`.
+
+
+ No extra argument. This is useful for simple flags or booleans.
+
+
+ The option takes a UTF-8 string argument.
+
+
+ The option takes an integer argument.
+
+
+ The option provides a callback (of type
+ #GOptionArgFunc) to parse the extra argument.
+
+
+ The option takes a filename as argument, which will
+ be in the GLib filename encoding rather than UTF-8.
+
+
+ The option takes a string argument, multiple
+ uses of the option are collected into an array of strings.
+
+
+ The option takes a filename as argument,
+ multiple uses of the option are collected into an array of strings.
+
+
+ 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
+
+
+ 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 `0x`, for
+ example, `0xffffffff`). Since 2.12
+
+
+
+ The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK
+options.
+
+
+ %TRUE if the option was successfully parsed, %FALSE if an error
+ occurred, in which case @error should be set with g_set_error()
+
+
+
+
+ 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.
+
+
+
+ The value to be parsed.
+
+
+
+ User data added to the #GOptionGroup containing the option when it
+ was created with g_option_group_new()
+
+
+
+
+
+ A `GOptionContext` struct defines which options
+are accepted by the commandline option parser. The struct has only private
+fields and should not be directly accessed.
+
+
+ Adds a #GOptionGroup to the @context, so that parsing with @context
+will recognize the options in the group. Note that this will take
+ownership of the @group and thus the @group should not be freed.
+
+
+
+
+
+
+ a #GOptionContext
+
+
+
+ the group to add
+
+
+
+
+
+ A convenience function which creates a main group if it doesn't
+exist, adds the @entries to it and sets the translation domain.
+
+
+
+
+
+
+ a #GOptionContext
+
+
+
+ a %NULL-terminated array of #GOptionEntrys
+
+
+
+
+
+ a translation domain to use for translating
+ the `--help` output for the options in @entries
+ with gettext(), or %NULL
+
+
+
+
+
+ Frees context and all the groups which have been
+added to it.
+
+Please note that parsed arguments need to be freed separately (see
+#GOptionEntry).
+
+
+
+
+
+
+ a #GOptionContext
+
+
+
+
+
+ Returns the description. See g_option_context_set_description().
+
+
+ the description
+
+
+
+
+ a #GOptionContext
+
+
+
+
+
+ Returns a formatted, translated help text for the given context.
+To obtain the text produced by `--help`, call
+`g_option_context_get_help (context, TRUE, NULL)`.
+To obtain the text produced by `--help-all`, call
+`g_option_context_get_help (context, FALSE, NULL)`.
+To obtain the help text for an option group, call
+`g_option_context_get_help (context, FALSE, group)`.
+
+
+ A newly allocated string containing the help text
+
+
+
+
+ a #GOptionContext
+
+
+
+ if %TRUE, only include the main group
+
+
+
+ the #GOptionGroup to create help for, or %NULL
+
+
+
+
+
+ Returns whether automatic `--help` generation
+is turned on for @context. See g_option_context_set_help_enabled().
+
+
+ %TRUE if automatic help generation is turned on.
+
+
+
+
+ a #GOptionContext
+
+
+
+
+
+ Returns whether unknown options are ignored or not. See
+g_option_context_set_ignore_unknown_options().
+
+
+ %TRUE if unknown options are ignored.
+
+
+
+
+ a #GOptionContext
+
+
+
+
+
+ Returns a pointer to the main group of @context.
+
+
+ the main group of @context, or %NULL if
+ @context doesn't have a main group. Note that group belongs to
+ @context and should not be modified or freed.
+
+
+
+
+ a #GOptionContext
+
+
+
+
+
+ Returns whether strict POSIX code is enabled.
+
+See g_option_context_set_strict_posix() for more information.
+
+
+ %TRUE if strict POSIX is enabled, %FALSE otherwise.
+
+
+
+
+ a #GOptionContext
+
+
+
+
+
+ Returns the summary. See g_option_context_set_summary().
+
+
+ the summary
+
+
+
+
+ a #GOptionContext
+
+
+
+
+
+ Parses the command line arguments, recognizing options
+which have been added to @context. A side-effect of
+calling this function is that g_set_prgname() will be
+called.
+
+If the parsing is successful, any parsed arguments are
+removed from the array and @argc and @argv are updated
+accordingly. A '--' option is stripped from @argv
+unless there are unparsed options before and after it,
+or some of the options after it start with '-'. In case
+of an error, @argc and @argv are left unmodified.
+
+If automatic `--help` support is enabled
+(see g_option_context_set_help_enabled()), and the
+@argv array contains one of the recognized help options,
+this function will produce help output to stdout and
+call `exit (0)`.
+
+Note that function depends on the [current locale][setlocale] for
+automatic character set conversion of string and filename
+arguments.
+
+
+ %TRUE if the parsing was successful,
+ %FALSE if an error occurred
+
+
+
+
+ a #GOptionContext
+
+
+
+ a pointer to the number of command line arguments
+
+
+
+ a pointer to the array of command line arguments
+
+
+
+
+
+
+
+ Parses the command line arguments.
+
+This function is similar to g_option_context_parse() except that it
+respects the normal memory rules when dealing with a strv instead of
+assuming that the passed-in array is the argv of the main function.
+
+In particular, strings that are removed from the arguments list will
+be freed using g_free().
+
+On Windows, the strings are expected to be in UTF-8. This is in
+contrast to g_option_context_parse() which expects them to be in the
+system codepage, which is how they are passed as @argv to main().
+See g_win32_get_command_line() for a solution.
+
+This function is useful if you are trying to use #GOptionContext with
+#GApplication.
+
+
+ %TRUE if the parsing was successful,
+ %FALSE if an error occurred
+
+
+
+
+ a #GOptionContext
+
+
+
+ a pointer
+ to the command line arguments (which must be in UTF-8 on Windows).
+ Starting with GLib 2.62, @arguments can be %NULL, which matches
+ g_option_context_parse().
+
+
+
+
+
+
+
+ Adds a string to be displayed in `--help` output after the list
+of options. This text often includes a bug reporting address.
+
+Note that the summary is translated (see
+g_option_context_set_translate_func()).
+
+
+
+
+
+
+ a #GOptionContext
+
+
+
+ a string to be shown in `--help` output
+ after the list of options, or %NULL
+
+
+
+
+
+ Enables or disables automatic generation of `--help` output.
+By default, g_option_context_parse() recognizes `--help`, `-h`,
+`-?`, `--help-all` and `--help-groupname` and creates suitable
+output to stdout.
+
+
+
+
+
+
+ a #GOptionContext
+
+
+
+ %TRUE to enable `--help`, %FALSE to disable it
+
+
+
+
+
+ Sets whether to ignore unknown options or not. If an argument is
+ignored, it is left in the @argv array after parsing. By default,
+g_option_context_parse() treats unknown options as error.
+
+This setting does not affect non-option arguments (i.e. arguments
+which don't start with a dash). But note that GOption cannot reliably
+determine whether a non-option belongs to a preceding unknown option.
+
+
+
+
+
+
+ a #GOptionContext
+
+
+
+ %TRUE to ignore unknown options, %FALSE to produce
+ an error when unknown options are met
+
+
+
+
+
+ Sets a #GOptionGroup as main group of the @context.
+This has the same effect as calling g_option_context_add_group(),
+the only difference is that the options in the main group are
+treated differently when generating `--help` output.
+
+
+
+
+
+
+ a #GOptionContext
+
+
+
+ the group to set as main group
+
+
+
+
+
+ Sets strict POSIX mode.
+
+By default, this mode is disabled.
+
+In strict POSIX mode, the first non-argument parameter encountered
+(eg: filename) terminates argument processing. Remaining arguments
+are treated as non-options and are not attempted to be parsed.
+
+If strict POSIX mode is disabled then parsing is done in the GNU way
+where option arguments can be freely mixed with non-options.
+
+As an example, consider "ls foo -l". With GNU style parsing, this
+will list "foo" in long mode. In strict POSIX style, this will list
+the files named "foo" and "-l".
+
+It may be useful to force strict POSIX mode when creating "verb
+style" command line tools. For example, the "gsettings" command line
+tool supports the global option "--schemadir" as well as many
+subcommands ("get", "set", etc.) which each have their own set of
+arguments. Using strict POSIX mode will allow parsing the global
+options up to the verb name while leaving the remaining options to be
+parsed by the relevant subcommand (which can be determined by
+examining the verb name, which should be present in argv[1] after
+parsing).
+
+
+
+
+
+
+ a #GOptionContext
+
+
+
+ the new value
+
+
+
+
+
+ Adds a string to be displayed in `--help` output before the list
+of options. This is typically a summary of the program functionality.
+
+Note that the summary is translated (see
+g_option_context_set_translate_func() and
+g_option_context_set_translation_domain()).
+
+
+
+
+
+
+ a #GOptionContext
+
+
+
+ a string to be shown in `--help` output
+ before the list of options, or %NULL
+
+
+
+
+
+ Sets the function which is used to translate the contexts
+user-visible strings, for `--help` output. If @func is %NULL,
+strings are not translated.
+
+Note that option groups have their own translation functions,
+this function only affects the @parameter_string (see g_option_context_new()),
+the summary (see g_option_context_set_summary()) and the description
+(see g_option_context_set_description()).
+
+If you are using gettext(), you only need to set the translation
+domain, see g_option_context_set_translation_domain().
+
+
+
+
+
+
+ a #GOptionContext
+
+
+
+ the #GTranslateFunc, or %NULL
+
+
+
+ user data to pass to @func, or %NULL
+
+
+
+ a function which gets called to free @data, or %NULL
+
+
+
+
+
+ A convenience function to use gettext() for translating
+user-visible strings.
+
+
+
+
+
+
+ a #GOptionContext
+
+
+
+ the domain to use
+
+
+
+
+
+ Creates a new option context.
+
+The @parameter_string can serve multiple purposes. It can be used
+to add descriptions for "rest" arguments, which are not parsed by
+the #GOptionContext, typically something like "FILES" or
+"FILE1 FILE2...". If you are using %G_OPTION_REMAINING for
+collecting "rest" arguments, GLib handles this automatically by
+using the @arg_description of the corresponding #GOptionEntry in
+the usage summary.
+
+Another usage is to give a short summary of the program
+functionality, like " - frob the strings", which will be displayed
+in the same line as the usage. For a longer description of the
+program functionality that should be displayed as a paragraph
+below the usage line, use g_option_context_set_summary().
+
+Note that the @parameter_string is translated using the
+function set with g_option_context_set_translate_func(), so
+it should normally be passed untranslated.
+
+
+ a newly created #GOptionContext, which must be
+ freed with g_option_context_free() after use.
+
+
+
+
+ a string which is displayed in
+ the first line of `--help` output, after the usage summary
+ `programname [OPTION...]`
+
+
+
+
+
+
+ A GOptionEntry struct 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().
+
+
+ The long name of an option can be used to specify it
+ in a commandline as `--long_name`. 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
+ `--groupname-long_name`.
+
+
+
+ If an option has a short name, it can be specified
+ `-short_name` in a commandline. @short_name must be a printable
+ ASCII character different from '-', or zero if the option has no
+ short name.
+
+
+
+ Flags from #GOptionFlags
+
+
+
+ The type of the option, as a #GOptionArg
+
+
+
+ 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:
+ - %G_OPTION_ARG_NONE: %gboolean
+ - %G_OPTION_ARG_STRING: %gchar*
+ - %G_OPTION_ARG_INT: %gint
+ - %G_OPTION_ARG_FILENAME: %gchar*
+ - %G_OPTION_ARG_STRING_ARRAY: %gchar**
+ - %G_OPTION_ARG_FILENAME_ARRAY: %gchar**
+ - %G_OPTION_ARG_DOUBLE: %gdouble
+ 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().
+
+
+
+ the description for the option in `--help`
+ output. The @description is translated using the @translate_func
+ of the group, see g_option_group_set_translation_domain().
+
+
+
+ The placeholder to use for the extra argument parsed
+ by the option in `--help` output. The @arg_description is translated
+ using the @translate_func of the group, see
+ g_option_group_set_translation_domain().
+
+
+
+
+ Error codes returned by option parsing.
+
+
+ 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().
+
+
+ A value couldn't be parsed.
+
+
+ A #GOptionArgFunc callback failed.
+
+
+
+ The type of function to be used as callback when a parse error occurs.
+
+
+
+
+
+
+ The active #GOptionContext
+
+
+
+ The group to which the function belongs
+
+
+
+ User data added to the #GOptionGroup containing the option when it
+ was created with g_option_group_new()
+
+
+
+
+
+ Flags which modify individual options.
+
+
+ No flags. Since: 2.42.
+
+
+ The option doesn't appear in `--help` output.
+
+
+ The option appears in the main section of the
+ `--help` output, even if it is defined in a group.
+
+
+ For options of the %G_OPTION_ARG_NONE kind, this
+ flag indicates that the sense of the option is reversed. i.e. %FALSE will
+ be stored into the argument rather than %TRUE.
+
+
+ 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
+
+
+ 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
+
+
+ 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
+
+
+ This flag turns off the automatic conflict
+ resolution which prefixes long option names with `groupname-` 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.
+
+
+
+ A `GOptionGroup` 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 `GOptionGroup` holding their options, which
+the application can then add to its #GOptionContext.
+
+
+ Creates a new #GOptionGroup.
+
+
+ a newly created option group. It should be added
+ to a #GOptionContext or freed with g_option_group_unref().
+
+
+
+
+ the name for the option group, this is used to provide
+ help for the options in this group with `--help-`@name
+
+
+
+ a description for this group to be shown in
+ `--help`. This string is translated using the translation
+ domain or translation function of the group
+
+
+
+ a description for the `--help-`@name option.
+ This string is translated using the translation domain or translation function
+ of the group
+
+
+
+ user data that will be passed to the pre- and post-parse hooks,
+ the error hook and to callbacks of %G_OPTION_ARG_CALLBACK options, or %NULL
+
+
+
+ a function that will be called to free @user_data, or %NULL
+
+
+
+
+
+ Adds the options specified in @entries to @group.
+
+
+
+
+
+
+ a #GOptionGroup
+
+
+
+ a %NULL-terminated array of #GOptionEntrys
+
+
+
+
+
+
+
+ Frees a #GOptionGroup. Note that you must not free groups
+which have been added to a #GOptionContext.
+ Use g_option_group_unref() instead.
+
+
+
+
+
+
+ a #GOptionGroup
+
+
+
+
+
+ Increments the reference count of @group by one.
+
+
+ a #GOptionGroup
+
+
+
+
+ a #GOptionGroup
+
+
+
+
+
+ Associates a function with @group which will be called
+from g_option_context_parse() when an error occurs.
+
+Note that the user data to be passed to @error_func can be
+specified when constructing the group with g_option_group_new().
+
+
+
+
+
+
+ a #GOptionGroup
+
+
+
+ a function to call when an error occurs
+
+
+
+
+
+ Associates two functions with @group which will be called
+from g_option_context_parse() before the first option is parsed
+and after the last option has been parsed, respectively.
+
+Note that the user data to be passed to @pre_parse_func and
+@post_parse_func can be specified when constructing the group
+with g_option_group_new().
+
+
+
+
+
+
+ a #GOptionGroup
+
+
+
+ a function to call before parsing, or %NULL
+
+
+
+ a function to call after parsing, or %NULL
+
+
+
+
+
+ Sets the function which is used to translate user-visible strings,
+for `--help` output. Different groups can use different
+#GTranslateFuncs. If @func is %NULL, strings are not translated.
+
+If you are using gettext(), you only need to set the translation
+domain, see g_option_group_set_translation_domain().
+
+
+
+
+
+
+ a #GOptionGroup
+
+
+
+ the #GTranslateFunc, or %NULL
+
+
+
+ user data to pass to @func, or %NULL
+
+
+
+ a function which gets called to free @data, or %NULL
+
+
+
+
+
+ A convenience function to use gettext() for translating
+user-visible strings.
+
+
+
+
+
+
+ a #GOptionGroup
+
+
+
+ the domain to use
+
+
+
+
+
+ Decrements the reference count of @group by one.
+If the reference count drops to 0, the @group will be freed.
+and all memory allocated by the @group is released.
+
+
+
+
+
+
+ a #GOptionGroup
+
+
+
+
+
+
+ The type of function that can be called before and after parsing.
+
+
+ %TRUE if the function completed successfully, %FALSE if an error
+ occurred, in which case @error should be set with g_set_error()
+
+
+
+
+ The active #GOptionContext
+
+
+
+ The group to which the function belongs
+
+
+
+ User data added to the #GOptionGroup containing the option when it
+ was created with g_option_group_new()
+
+
+
+
+
+ Specifies one of the possible types of byte order
+(currently unused). See %G_BYTE_ORDER.
+
+
+
+
+ The value of pi (ratio of circle's circumference to its diameter).
+
+
+
+
+ A format specifier that can be used in printf()-style format strings
+when printing a #GPid.
+
+
+
+
+ Pi divided by 2.
+
+
+
+
+ Pi divided by 4.
+
+
+
+
+ A format specifier that can be used in printf()-style format strings
+when printing the @fd member of a #GPollFD.
+
+
+
+
+ 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.
+
+
+
+
+ Use this for default priority idle functions.
+
+In GLib this priority is used when adding idle functions with
+g_idle_add().
+
+
+
+
+ Use this for high priority event sources.
+
+It is not used within GLib or GTK+.
+
+
+
+
+ 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.)
+
+
+
+
+ Use this for very low priority background tasks.
+
+It is not used within GLib or GTK+.
+
+
+
+
+ A macro to assist with the static initialisation of a #GPrivate.
+
+This macro is useful for the case that a #GDestroyNotify function
+should be associated with the key. This is needed when the key will be
+used to point at memory that should be deallocated when the thread
+exits.
+
+Additionally, the #GDestroyNotify will also be called on the previous
+value stored in the key when g_private_replace() is used.
+
+If no #GDestroyNotify is needed, then use of this macro is not
+required -- if the #GPrivate is declared in static scope then it will
+be properly initialised by default (ie: to all zeros). See the
+examples below.
+
+|[<!-- language="C" -->
+static GPrivate name_key = G_PRIVATE_INIT (g_free);
+
+// return value should not be freed
+const gchar *
+get_local_name (void)
+{
+ return g_private_get (&name_key);
+}
+
+void
+set_local_name (const gchar *name)
+{
+ g_private_replace (&name_key, g_strdup (name));
+}
+
+
+static GPrivate count_key; // no free function
+
+gint
+get_local_count (void)
+{
+ return GPOINTER_TO_INT (g_private_get (&count_key));
+}
+
+void
+set_local_count (gint count)
+{
+ g_private_set (&count_key, GINT_TO_POINTER (count));
+}
+]|
+
+
+
+ a #GDestroyNotify
+
+
+
+
+ `GPathBuf` is a helper type that allows you to easily build paths from
+individual elements, using the platform specific conventions for path
+separators.
+
+|[<!-- language="C" -->
+g_auto (GPathBuf) path;
+
+g_path_buf_init (&path);
+
+g_path_buf_push (&path, "usr");
+g_path_buf_push (&path, "bin");
+g_path_buf_push (&path, "echo");
+
+g_autofree char *echo = g_path_buf_to_path (&path);
+g_assert_cmpstr (echo, ==, "/usr/bin/echo");
+]|
+
+You can also load a full path and then operate on its components:
+
+|[<!-- language="C" -->
+g_auto (GPathBuf) path;
+
+g_path_buf_init_from_path (&path, "/usr/bin/echo");
+
+g_path_buf_pop (&path);
+g_path_buf_push (&path, "sh");
+
+g_autofree char *sh = g_path_buf_to_path (&path);
+g_assert_cmpstr (sh, ==, "/usr/bin/sh");
+]|
+
+`GPathBuf` is available since GLib 2.76.
+
+
+
+
+
+
+
+ Clears the contents of the path buffer.
+
+This function should be use to free the resources in a stack-allocated
+`GPathBuf` initialized using g_path_buf_init() or
+g_path_buf_init_from_path().
+
+
+
+
+
+
+ a path buffer
+
+
+
+
+
+ Clears the contents of the path buffer and returns the built path.
+
+This function returns `NULL` if the `GPathBuf` is empty.
+
+See also: g_path_buf_to_path()
+
+
+ the built path
+
+
+
+
+ a path buffer
+
+
+
+
+
+ Copies the contents of a path buffer into a new `GPathBuf`.
+
+
+ the newly allocated path buffer
+
+
+
+
+ a path buffer
+
+
+
+
+
+ Frees a `GPathBuf` allocated by g_path_buf_new().
+
+
+
+
+
+
+ a path buffer
+
+
+
+
+
+ Frees a `GPathBuf` allocated by g_path_buf_new(), and
+returns the path inside the buffer.
+
+This function returns `NULL` if the `GPathBuf` is empty.
+
+See also: g_path_buf_to_path()
+
+
+ the path
+
+
+
+
+ a path buffer
+
+
+
+
+
+ Initializes a `GPathBuf` instance.
+
+
+ the initialized path builder
+
+
+
+
+ a path buffer
+
+
+
+
+
+ Initializes a `GPathBuf` instance with the given path.
+
+
+ the initialized path builder
+
+
+
+
+ a path buffer
+
+
+
+ a file system path
+
+
+
+
+
+ Removes the last element of the path buffer.
+
+If there is only one element in the path buffer (for example, `/` on
+Unix-like operating systems or the drive on Windows systems), it will
+not be removed and %FALSE will be returned instead.
+
+|[<!-- language="C" -->
+GPathBuf buf, cmp;
+
+g_path_buf_init_from_path (&buf, "/bin/sh");
+
+g_path_buf_pop (&buf);
+g_path_buf_init_from_path (&cmp, "/bin");
+g_assert_true (g_path_buf_equal (&buf, &cmp));
+g_path_buf_clear (&cmp);
+
+g_path_buf_pop (&buf);
+g_path_buf_init_from_path (&cmp, "/");
+g_assert_true (g_path_buf_equal (&buf, &cmp));
+g_path_buf_clear (&cmp);
+
+g_path_buf_clear (&buf);
+]|
+
+
+ `TRUE` if the buffer was modified and `FALSE` otherwise
+
+
+
+
+ a path buffer
+
+
+
+
+
+ Extends the given path buffer with @path.
+
+If @path is absolute, it replaces the current path.
+
+If @path contains a directory separator, the buffer is extended by
+as many elements the path provides.
+
+On Windows, both forward slashes and backslashes are treated as
+directory separators. On other platforms, %G_DIR_SEPARATOR_S is the
+only directory separator.
+
+|[<!-- language="C" -->
+GPathBuf buf, cmp;
+
+g_path_buf_init_from_path (&buf, "/tmp");
+g_path_buf_push (&buf, ".X11-unix/X0");
+g_path_buf_init_from_path (&cmp, "/tmp/.X11-unix/X0");
+g_assert_true (g_path_buf_equal (&buf, &cmp));
+g_path_buf_clear (&cmp);
+
+g_path_buf_push (&buf, "/etc/locale.conf");
+g_path_buf_init_from_path (&cmp, "/etc/locale.conf");
+g_assert_true (g_path_buf_equal (&buf, &cmp));
+g_path_buf_clear (&cmp);
+
+g_path_buf_clear (&buf);
+]|
+
+
+ the same pointer to @buf, for convenience
+
+
+
+
+ a path buffer
+
+
+
+ a path
+
+
+
+
+
+ Adds an extension to the file name in the path buffer.
+
+If @extension is `NULL`, the extension will be unset.
+
+If the path buffer does not have a file name set, this function returns
+`FALSE` and leaves the path buffer unmodified.
+
+
+ `TRUE` if the extension was replaced, and `FALSE` otherwise
+
+
+
+
+ a path buffer
+
+
+
+ the file extension
+
+
+
+
+
+ Sets the file name of the path.
+
+If the path buffer is empty, the filename is left unset and this
+function returns `FALSE`.
+
+If the path buffer only contains the root element (on Unix-like operating
+systems) or the drive (on Windows), this is the equivalent of pushing
+the new @file_name.
+
+If the path buffer contains a path, this is the equivalent of
+popping the path buffer and pushing @file_name, creating a
+sibling of the original path.
+
+|[<!-- language="C" -->
+GPathBuf buf, cmp;
+
+g_path_buf_init_from_path (&buf, "/");
+
+g_path_buf_set_filename (&buf, "bar");
+g_path_buf_init_from_path (&cmp, "/bar");
+g_assert_true (g_path_buf_equal (&buf, &cmp));
+g_path_buf_clear (&cmp);
+
+g_path_buf_set_filename (&buf, "baz.txt");
+g_path_buf_init_from_path (&cmp, "/baz.txt");
+g_assert_true (g_path_buf_equal (&buf, &cmp);
+g_path_buf_clear (&cmp);
+
+g_path_buf_clear (&buf);
+]|
+
+
+ `TRUE` if the file name was replaced, and `FALSE` otherwise
+
+
+
+
+ a path buffer
+
+
+
+ the file name in the path
+
+
+
+
+
+ Retrieves the built path from the path buffer.
+
+On Windows, the result contains backslashes as directory separators,
+even if forward slashes were used in input.
+
+If the path buffer is empty, this function returns `NULL`.
+
+
+ the path
+
+
+
+
+ a path buffer
+
+
+
+
+
+ Compares two path buffers for equality and returns `TRUE`
+if they are equal.
+
+The path inside the paths buffers are not going to be normalized,
+so `X/Y/Z/A/..`, `X/./Y/Z` and `X/Y/Z` are not going to be considered
+equal.
+
+This function can be passed to g_hash_table_new() as the
+`key_equal_func` parameter.
+
+
+ `TRUE` if the two path buffers are equal,
+ and `FALSE` otherwise
+
+
+
+
+ a path buffer to compare
+
+
+
+ a path buffer to compare
+
+
+
+
+
+ Allocates a new `GPathBuf`.
+
+
+ the newly allocated path buffer
+
+
+
+
+ Allocates a new `GPathBuf` with the given @path.
+
+
+ the newly allocated path buffer
+
+
+
+
+ the path used to initialize the buffer
+
+
+
+
+
+
+ A GPatternSpec struct is the 'compiled' form of a pattern. This
+structure is opaque and its fields cannot be accessed directly.
+
+
+ Compiles a pattern to a #GPatternSpec.
+
+
+ a newly-allocated #GPatternSpec
+
+
+
+
+ a zero-terminated UTF-8 encoded string
+
+
+
+
+
+ Copies @pspec in a new #GPatternSpec.
+
+
+ a copy of @pspec.
+
+
+
+
+ a #GPatternSpec
+
+
+
+
+
+ Compares two compiled pattern specs and returns whether they will
+match the same set of strings.
+
+
+ Whether the compiled patterns are equal
+
+
+
+
+ a #GPatternSpec
+
+
+
+ another #GPatternSpec
+
+
+
+
+
+ Frees the memory allocated for the #GPatternSpec.
+
+
+
+
+
+
+ a #GPatternSpec
+
+
+
+
+
+ Matches a string against a compiled pattern. Passing the correct
+length of the string given is mandatory. The reversed string can be
+omitted by passing %NULL, this is more efficient if the reversed
+version of the string to be matched is not at hand, as
+g_pattern_match() will only construct it if the compiled pattern
+requires reverse matches.
+
+Note that, if the user code will (possibly) match a string against a
+multitude of patterns containing wildcards, chances are high that
+some patterns will require a reversed string. In this case, it's
+more efficient to provide the reversed string to avoid multiple
+constructions thereof in the various calls to g_pattern_match().
+
+Note also that the reverse of a UTF-8 encoded string can in general
+not be obtained by g_strreverse(). This works only if the string
+does not contain any multibyte characters. GLib offers the
+g_utf8_strreverse() function to reverse UTF-8 encoded strings.
+
+
+ %TRUE if @string matches @pspec
+
+
+
+
+ a #GPatternSpec
+
+
+
+ the length of @string (in bytes, i.e. strlen(),
+ not g_utf8_strlen())
+
+
+
+ the UTF-8 encoded string to match
+
+
+
+ the reverse of @string or %NULL
+
+
+
+
+
+ Matches a string against a compiled pattern. If the string is to be
+matched against more than one pattern, consider using
+g_pattern_match() instead while supplying the reversed string.
+
+
+ %TRUE if @string matches @pspec
+
+
+
+
+ a #GPatternSpec
+
+
+
+ the UTF-8 encoded string to match
+
+
+
+
+
+
+ Represents a file descriptor, which events to poll for, and which events
+occurred.
+
+
+ the file descriptor to poll (or a HANDLE on Win32)
+
+
+
+ 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.
+
+
+
+ a bitwise combination of flags from #GIOCondition, returned
+ from the poll() function to indicate which events occurred.
+
+
+
+
+ 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.
+
+
+ the number of #GPollFD elements which have events or errors
+ reported, or -1 if an error occurred.
+
+
+
+
+ an array of #GPollFD elements
+
+
+
+ the number of elements in @ufds
+
+
+
+ the maximum time to wait for an event of the file descriptors.
+ A negative value indicates an infinite timeout.
+
+
+
+
+
+ Specifies the type of the print handler functions.
+These are called with the complete formatted string to output.
+
+
+
+
+
+
+ the message to output
+
+
+
+
+
+ The #GPrivate struct is an opaque data structure to represent a
+thread-local data key. It is approximately equivalent to the
+pthread_setspecific()/pthread_getspecific() APIs on POSIX and to
+TlsSetValue()/TlsGetValue() on Windows.
+
+If you don't already know why you might want this functionality,
+then you probably don't need it.
+
+#GPrivate is a very limited resource (as far as 128 per program,
+shared between all libraries). It is also not possible to destroy a
+#GPrivate after it has been used. As such, it is only ever acceptable
+to use #GPrivate in static scope, and even then sparingly so.
+
+See G_PRIVATE_INIT() for a couple of examples.
+
+The #GPrivate structure should be considered opaque. It should only
+be accessed via the g_private_ functions.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Returns the current value of the thread local variable @key.
+
+If the value has not yet been set in this thread, %NULL is returned.
+Values are never copied between threads (when a new thread is
+created, for example).
+
+
+ the thread-local value
+
+
+
+
+ a #GPrivate
+
+
+
+
+
+ Sets the thread local variable @key to have the value @value in the
+current thread.
+
+This function differs from g_private_set() in the following way: if
+the previous value was non-%NULL then the #GDestroyNotify handler for
+@key is run on it.
+
+
+
+
+
+
+ a #GPrivate
+
+
+
+ the new value
+
+
+
+
+
+ Sets the thread local variable @key to have the value @value in the
+current thread.
+
+This function differs from g_private_replace() in the following way:
+the #GDestroyNotify for @key is not called on the old value.
+
+
+
+
+
+
+ a #GPrivate
+
+
+
+ the new value
+
+
+
+
+
+
+ Contains the public fields of a pointer array.
+
+
+ points to the array of pointers, which may be moved when the
+ array grows
+
+
+
+ number of pointers in the array
+
+
+
+ Adds a pointer to the end of the pointer array. The array will grow
+in size automatically if necessary.
+
+
+
+
+
+
+ a #GPtrArray
+
+
+
+
+
+ the pointer to add
+
+
+
+
+
+ Makes a full (deep) copy of a #GPtrArray.
+
+@func, as a #GCopyFunc, takes two arguments, the data to be copied
+and a @user_data pointer. On common processor architectures, it's safe to
+pass %NULL as @user_data if the copy function takes only one argument. You
+may get compiler warnings from this though if compiling with GCC’s
+`-Wcast-function-type` warning.
+
+If @func is %NULL, then only the pointers (and not what they are
+pointing to) are copied to the new #GPtrArray.
+
+The copy of @array will have the same #GDestroyNotify for its elements as
+@array. The copy will also be %NULL terminated if (and only if) the source
+array is.
+
+
+ a deep copy of the initial #GPtrArray.
+
+
+
+
+
+
+ #GPtrArray to duplicate
+
+
+
+
+
+ a copy function used to copy every element in the array
+
+
+
+ user data passed to the copy function @func, or %NULL
+
+
+
+
+
+ Adds all pointers of @array to the end of the array @array_to_extend.
+The array will grow in size automatically if needed. @array_to_extend is
+modified in-place.
+
+@func, as a #GCopyFunc, takes two arguments, the data to be copied
+and a @user_data pointer. On common processor architectures, it's safe to
+pass %NULL as @user_data if the copy function takes only one argument. You
+may get compiler warnings from this though if compiling with GCC’s
+`-Wcast-function-type` warning.
+
+If @func is %NULL, then only the pointers (and not what they are
+pointing to) are copied to the new #GPtrArray.
+
+Whether @array_to_extend is %NULL terminated stays unchanged by this function.
+
+
+
+
+
+
+ a #GPtrArray.
+
+
+
+
+
+ a #GPtrArray to add to the end of @array_to_extend.
+
+
+
+
+
+ a copy function used to copy every element in the array
+
+
+
+ user data passed to the copy function @func, or %NULL
+
+
+
+
+
+ Adds all the pointers in @array to the end of @array_to_extend, transferring
+ownership of each element from @array to @array_to_extend and modifying
+@array_to_extend in-place. @array is then freed.
+
+As with g_ptr_array_free(), @array will be destroyed if its reference count
+is 1. If its reference count is higher, it will be decremented and the
+length of @array set to zero.
+
+
+
+
+
+
+ a #GPtrArray.
+
+
+
+
+
+ a #GPtrArray to add to the end of
+ @array_to_extend.
+
+
+
+
+
+
+
+ Checks whether @needle exists in @haystack. If the element is found, %TRUE is
+returned and the element’s index is returned in @index_ (if non-%NULL).
+Otherwise, %FALSE is returned and @index_ is undefined. If @needle exists
+multiple times in @haystack, the index of the first instance is returned.
+
+This does pointer comparisons only. If you want to use more complex equality
+checks, such as string comparisons, use g_ptr_array_find_with_equal_func().
+
+
+ %TRUE if @needle is one of the elements of @haystack
+
+
+
+
+ pointer array to be searched
+
+
+
+
+
+ pointer to look for
+
+
+
+ return location for the index of
+ the element, if found
+
+
+
+
+
+ Checks whether @needle exists in @haystack, using the given @equal_func.
+If the element is found, %TRUE is returned and the element’s index is
+returned in @index_ (if non-%NULL). Otherwise, %FALSE is returned and @index_
+is undefined. If @needle exists multiple times in @haystack, the index of
+the first instance is returned.
+
+@equal_func is called with the element from the array as its first parameter,
+and @needle as its second parameter. If @equal_func is %NULL, pointer
+equality is used.
+
+
+ %TRUE if @needle is one of the elements of @haystack
+
+
+
+
+ pointer array to be searched
+
+
+
+
+
+ pointer to look for
+
+
+
+ the function to call for each element, which should
+ return %TRUE when the desired element is found; or %NULL to use pointer
+ equality
+
+
+
+ return location for the index of
+ the element, if found
+
+
+
+
+
+ Calls a function for each element of a #GPtrArray. @func must not
+add elements to or remove elements from the array.
+
+
+
+
+
+
+ a #GPtrArray
+
+
+
+
+
+ the function to call for each array element
+
+
+
+ user data to pass to the function
+
+
+
+
+
+ Frees the memory allocated for the #GPtrArray. If @free_seg is %TRUE
+it frees the memory block holding the elements as well. Pass %FALSE
+if you want to free the #GPtrArray wrapper but preserve the
+underlying array for use elsewhere. If the reference count of @array
+is greater than one, the #GPtrArray wrapper is preserved but the
+size of @array will be set to zero.
+
+If array contents point to dynamically-allocated memory, they should
+be freed separately if @free_seg is %TRUE and no #GDestroyNotify
+function has been set for @array.
+
+Note that if the array is %NULL terminated and @free_seg is %FALSE
+then this will always return an allocated %NULL terminated buffer.
+If pdata is previously %NULL, a new buffer will be allocated.
+
+This function is not thread-safe. If using a #GPtrArray from multiple
+threads, use only the atomic g_ptr_array_ref() and g_ptr_array_unref()
+functions.
+
+
+ the pointer array if @free_seg is
+ %FALSE, otherwise %NULL. The pointer array should be freed using g_free().
+
+
+
+
+ a #GPtrArray
+
+
+
+
+
+ if %TRUE the actual pointer array is freed as well
+
+
+
+
+
+ Inserts an element into the pointer array at the given index. The
+array will grow in size automatically if necessary.
+
+
+
+
+
+
+ a #GPtrArray
+
+
+
+
+
+ the index to place the new element at, or -1 to append
+
+
+
+ the pointer to add.
+
+
+
+
+
+ Gets whether the @array was constructed as %NULL-terminated.
+
+This will only return %TRUE for arrays constructed by passing %TRUE to the
+`null_terminated` argument of g_ptr_array_new_null_terminated(). It will not
+return %TRUE for normal arrays which have had a %NULL element appended to
+them.
+
+
+ %TRUE if the array is made to be %NULL terminated.
+
+
+
+
+ the #GPtrArray
+
+
+
+
+
+
+
+ Creates a new #GPtrArray with a reference count of 1.
+
+
+ the new #GPtrArray
+
+
+
+
+
+
+ Creates a new #GPtrArray, copying @len pointers from @data, and setting
+the array’s reference count to 1.
+
+This avoids having to manually add each element one by one.
+
+If @copy_func is provided, then it is used to copy each element before
+adding them to the new array. If it is %NULL then the pointers are copied
+directly.
+
+It also sets @element_free_func for freeing each element when the array is
+destroyed either via g_ptr_array_unref(), when g_ptr_array_free() is called
+with @free_segment set to %TRUE or when removing elements.
+
+Do not use it if @len is greater than %G_MAXUINT. #GPtrArray
+stores the length of its data in #guint, which may be shorter than
+#gsize.
+
+
+ A new #GPtrArray
+
+
+
+
+
+
+ an array of pointers,
+or %NULL for an empty array
+
+
+
+
+
+ the number of pointers in @data
+
+
+
+ a copy function used to copy every element in the
+ array or %NULL.
+
+
+
+ user data passed to @copy_func, or %NULL
+
+
+
+ a function to free elements on @array
+ destruction or %NULL
+
+
+
+
+
+ Creates a new #GPtrArray copying the pointers from @data after having
+computed the length of it and with a reference count of 1.
+This avoids having to manually add each element one by one.
+If @copy_func is provided, then it is used to copy the data in the new
+array.
+It also set @element_free_func for freeing each element when the array is
+destroyed either via g_ptr_array_unref(), when g_ptr_array_free() is called
+with @free_segment set to %TRUE or when removing elements.
+
+Do not use it if the @data has more than %G_MAXUINT elements. #GPtrArray
+stores the length of its data in #guint, which may be shorter than
+#gsize.
+
+
+ A new #GPtrArray
+
+
+
+
+
+
+ an array of
+ pointers, %NULL terminated; or %NULL for an empty array
+
+
+
+
+
+ a copy function used to copy every element in the
+ array or %NULL.
+
+
+
+ user data passed to @copy_func, or %NULL
+
+
+
+ a function to free elements on @array
+ destruction or %NULL
+
+
+
+
+
+ Creates a new #GPtrArray with @reserved_size pointers preallocated
+and a reference count of 1. This avoids frequent reallocation, if
+you are going to add many pointers to the array. Note however that
+the size of the array is still 0. It also set @element_free_func
+for freeing each element when the array is destroyed either via
+g_ptr_array_unref(), when g_ptr_array_free() is called with
+@free_segment set to %TRUE or when removing elements.
+
+
+ A new #GPtrArray
+
+
+
+
+
+
+ number of pointers preallocated
+
+
+
+ A function to free elements with
+ destroy @array or %NULL
+
+
+
+
+
+ Like g_ptr_array_new_full() but also allows to set the array to
+be %NULL terminated. A %NULL terminated pointer array has an
+additional %NULL pointer after the last element, beyond the
+current length.
+
+#GPtrArray created by other constructors are not automatically %NULL
+terminated.
+
+Note that if the @array's length is zero and currently no
+data array is allocated, then pdata will still be %NULL.
+%GPtrArray will only %NULL terminate pdata, if an actual
+array is allocated. It does not guarantee that an array
+is always allocated. In other words, if the length is zero,
+then pdata may either point to a %NULL terminated array of length
+zero or be %NULL.
+
+
+ A new #GPtrArray
+
+
+
+
+
+
+ number of pointers preallocated.
+ If @null_terminated is %TRUE, the actually allocated
+ buffer size is @reserved_size plus 1, unless @reserved_size
+ is zero, in which case no initial buffer gets allocated.
+
+
+
+ A function to free elements with
+ destroy @array or %NULL
+
+
+
+ whether to make the array as %NULL terminated.
+
+
+
+
+
+ Creates a new #GPtrArray with @data as pointers, @len as length and a
+reference count of 1.
+
+This avoids having to copy such data manually. @data will eventually be
+freed using g_free(), so must have been allocated with a suitable allocator.
+
+It also sets @element_free_func for freeing each element when the array is
+destroyed either via g_ptr_array_unref(), when g_ptr_array_free() is called
+with @free_segment set to %TRUE or when removing elements.
+
+Do not use it if @len is greater than %G_MAXUINT. #GPtrArray
+stores the length of its data in #guint, which may be shorter than
+#gsize.
+
+
+ A new #GPtrArray
+
+
+
+
+
+
+ an array of pointers,
+ or %NULL for an empty array
+
+
+
+
+
+ the number of pointers in @data
+
+
+
+ A function to free elements on @array
+ destruction or %NULL
+
+
+
+
+
+ Creates a new #GPtrArray with @data as pointers, computing the length of it
+and setting the reference count to 1.
+
+This avoids having to copy such data manually. @data will eventually be
+freed using g_free(), so must have been allocated with a suitable allocator.
+
+The length is calculated by iterating through @data until the first %NULL
+element is found.
+
+It also sets @element_free_func for freeing each element when the array is
+destroyed either via g_ptr_array_unref(), when g_ptr_array_free() is called
+with @free_segment set to %TRUE or when removing elements.
+
+Do not use it if the @data length is greater than %G_MAXUINT. #GPtrArray
+stores the length of its data in #guint, which may be shorter than
+#gsize.
+
+
+ A new #GPtrArray
+
+
+
+
+
+
+ an array
+ of pointers, %NULL terminated, or %NULL for an empty array
+
+
+
+
+
+ a function to free elements on @array
+ destruction or %NULL
+
+
+
+
+
+ Creates a new #GPtrArray with a reference count of 1 and use
+@element_free_func for freeing each element when the array is destroyed
+either via g_ptr_array_unref(), when g_ptr_array_free() is called with
+@free_segment set to %TRUE or when removing elements.
+
+
+ A new #GPtrArray
+
+
+
+
+
+
+ A function to free elements with
+ destroy @array or %NULL
+
+
+
+
+
+ Atomically increments the reference count of @array by one.
+This function is thread-safe and may be called from any thread.
+
+
+ The passed in #GPtrArray
+
+
+
+
+
+
+ a #GPtrArray
+
+
+
+
+
+
+
+ Removes the first occurrence of the given pointer from the pointer
+array. The following elements are moved down one place. If @array
+has a non-%NULL #GDestroyNotify function it is called for the
+removed element.
+
+It returns %TRUE if the pointer was removed, or %FALSE if the
+pointer was not found.
+
+
+ %TRUE if the pointer is removed, %FALSE if the pointer
+ is not found in the array
+
+
+
+
+ a #GPtrArray
+
+
+
+
+
+ the pointer to remove
+
+
+
+
+
+ Removes the first occurrence of the given pointer from the pointer
+array. The last element in the array is used to fill in the space,
+so this function does not preserve the order of the array. But it
+is faster than g_ptr_array_remove(). If @array has a non-%NULL
+#GDestroyNotify function it is called for the removed element.
+
+It returns %TRUE if the pointer was removed, or %FALSE if the
+pointer was not found.
+
+
+ %TRUE if the pointer was found in the array
+
+
+
+
+ a #GPtrArray
+
+
+
+
+
+ the pointer to remove
+
+
+
+
+
+ Removes the pointer at the given index from the pointer array.
+The following elements are moved down one place. If @array has
+a non-%NULL #GDestroyNotify function it is called for the removed
+element. If so, the return value from this function will potentially point
+to freed memory (depending on the #GDestroyNotify implementation).
+
+
+ the pointer which was removed
+
+
+
+
+ a #GPtrArray
+
+
+
+
+
+ the index of the pointer to remove
+
+
+
+
+
+ Removes the pointer at the given index from the pointer array.
+The last element in the array is used to fill in the space, so
+this function does not preserve the order of the array. But it
+is faster than g_ptr_array_remove_index(). If @array has a non-%NULL
+#GDestroyNotify function it is called for the removed element. If so, the
+return value from this function will potentially point to freed memory
+(depending on the #GDestroyNotify implementation).
+
+
+ the pointer which was removed
+
+
+
+
+ a #GPtrArray
+
+
+
+
+
+ the index of the pointer to remove
+
+
+
+
+
+ Removes the given number of pointers starting at the given index
+from a #GPtrArray. The following elements are moved to close the
+gap. If @array has a non-%NULL #GDestroyNotify function it is
+called for the removed elements.
+
+
+ the @array
+
+
+
+
+
+
+ a @GPtrArray
+
+
+
+
+
+ the index of the first pointer to remove
+
+
+
+ the number of pointers to remove
+
+
+
+
+
+ Sets a function for freeing each element when @array is destroyed
+either via g_ptr_array_unref(), when g_ptr_array_free() is called
+with @free_segment set to %TRUE or when removing elements.
+
+
+
+
+
+
+ A #GPtrArray
+
+
+
+
+
+ A function to free elements with
+ destroy @array or %NULL
+
+
+
+
+
+ Sets the size of the array. When making the array larger,
+newly-added elements will be set to %NULL. When making it smaller,
+if @array has a non-%NULL #GDestroyNotify function then it will be
+called for the removed elements.
+
+
+
+
+
+
+ a #GPtrArray
+
+
+
+
+
+ the new length of the pointer array
+
+
+
+
+
+ Creates a new #GPtrArray with @reserved_size pointers preallocated
+and a reference count of 1. This avoids frequent reallocation, if
+you are going to add many pointers to the array. Note however that
+the size of the array is still 0.
+
+
+ the new #GPtrArray
+
+
+
+
+
+
+ number of pointers preallocated
+
+
+
+
+
+ Sorts the array, using @compare_func which should be a qsort()-style
+comparison function (returns less than zero for first arg is less
+than second arg, zero for equal, greater than zero if first arg is
+greater than second arg).
+
+Note that the comparison function for g_ptr_array_sort() doesn't
+take the pointers from the array as arguments, it takes pointers to
+the pointers in the array.
+
+Use g_ptr_array_sort_with_data() if you want to use normal
+#GCompareFuncs, otherwise here is a full example of use:
+
+|[<!-- language="C" -->
+typedef struct
+{
+ gchar *name;
+ gint size;
+} FileListEntry;
+
+static gint
+sort_filelist (gconstpointer a, gconstpointer b)
+{
+ const FileListEntry *entry1 = *((FileListEntry **) a);
+ const FileListEntry *entry2 = *((FileListEntry **) b);
+
+ return g_ascii_strcasecmp (entry1->name, entry2->name);
+}
+
+…
+g_autoptr (GPtrArray) file_list = NULL;
+
+// initialize file_list array and load with many FileListEntry entries
+...
+// now sort it with
+g_ptr_array_sort (file_list, sort_filelist);
+]|
+
+This is guaranteed to be a stable sort since version 2.32.
+
+
+
+
+
+
+ a #GPtrArray
+
+
+
+
+
+ comparison function
+
+
+
+
+
+ Sorts the array, using @compare_func which should be a qsort()-style
+comparison function (returns less than zero for first arg is less
+than second arg, zero for equal, greater than zero if first arg is
+greater than second arg).
+
+This is guaranteed to be a stable sort.
+
+
+
+
+
+
+ a #GPtrArray
+
+
+
+
+
+ a #GCompareFunc comparison function
+
+
+
+
+
+ Like g_ptr_array_sort_values(), but the comparison function has an extra
+user data argument.
+
+This is guaranteed to be a stable sort.
+
+
+
+
+
+
+ a #GPtrArray
+
+
+
+
+
+ a #GCompareDataFunc comparison function
+
+
+
+ data to pass to @compare_func
+
+
+
+
+
+ Like g_ptr_array_sort(), but the comparison function has an extra
+user data argument.
+
+Note that the comparison function for g_ptr_array_sort_with_data()
+doesn't take the pointers from the array as arguments, it takes
+pointers to the pointers in the array.
+
+Use g_ptr_array_sort_with_data() if you want to use normal
+#GCompareDataFuncs, otherwise here is a full example of use:
+
+|[<!-- language="C" -->
+typedef enum { SORT_NAME, SORT_SIZE } SortMode;
+
+typedef struct
+{
+ gchar *name;
+ gint size;
+} FileListEntry;
+
+static gint
+sort_filelist (gconstpointer a, gconstpointer b, gpointer user_data)
+{
+ gint order;
+ const SortMode sort_mode = GPOINTER_TO_INT (user_data);
+ const FileListEntry *entry1 = *((FileListEntry **) a);
+ const FileListEntry *entry2 = *((FileListEntry **) b);
+
+ switch (sort_mode)
+ {
+ case SORT_NAME:
+ order = g_ascii_strcasecmp (entry1->name, entry2->name);
+ break;
+ case SORT_SIZE:
+ order = entry1->size - entry2->size;
+ break;
+ default:
+ order = 0;
+ break;
+ }
+ return order;
+}
+
+...
+g_autoptr (GPtrArray) file_list = NULL;
+SortMode sort_mode;
+
+// initialize file_list array and load with many FileListEntry entries
+...
+// now sort it with
+sort_mode = SORT_NAME;
+g_ptr_array_sort_with_data (file_list,
+ sort_filelist,
+ GINT_TO_POINTER (sort_mode));
+]|
+
+This is guaranteed to be a stable sort since version 2.32.
+
+
+
+
+
+
+ a #GPtrArray
+
+
+
+
+
+ comparison function
+
+
+
+ data to pass to @compare_func
+
+
+
+
+
+ Frees the data in the array and resets the size to zero, while
+the underlying array is preserved for use elsewhere and returned
+to the caller.
+
+Note that if the array is %NULL terminated this may still return
+%NULL if the length of the array was zero and pdata was not yet
+allocated.
+
+Even if set, the #GDestroyNotify function will never be called
+on the current contents of the array and the caller is
+responsible for freeing the array elements.
+
+An example of use:
+|[<!-- language="C" -->
+g_autoptr(GPtrArray) chunk_buffer = g_ptr_array_new_with_free_func (g_bytes_unref);
+
+// Some part of your application appends a number of chunks to the pointer array.
+g_ptr_array_add (chunk_buffer, g_bytes_new_static ("hello", 5));
+g_ptr_array_add (chunk_buffer, g_bytes_new_static ("world", 5));
+
+…
+
+// Periodically, the chunks need to be sent as an array-and-length to some
+// other part of the program.
+GBytes **chunks;
+gsize n_chunks;
+
+chunks = g_ptr_array_steal (chunk_buffer, &n_chunks);
+for (gsize i = 0; i < n_chunks; i++)
+ {
+ // Do something with each chunk here, and then free them, since
+ // g_ptr_array_steal() transfers ownership of all the elements and the
+ // array to the caller.
+ …
+
+ g_bytes_unref (chunks[i]);
+ }
+
+g_free (chunks);
+
+// After calling g_ptr_array_steal(), the pointer array can be reused for the
+// next set of chunks.
+g_assert (chunk_buffer->len == 0);
+]|
+
+
+ the element data, which should be
+ freed using g_free(). This may be %NULL if the array doesn’t have any
+ elements (i.e. if `*len` is zero).
+
+
+
+
+ a #GPtrArray.
+
+
+
+
+
+ pointer to retrieve the number of
+ elements of the original array
+
+
+
+
+
+ Removes the pointer at the given index from the pointer array.
+The following elements are moved down one place. The #GDestroyNotify for
+@array is *not* called on the removed element; ownership is transferred to
+the caller of this function.
+
+
+ the pointer which was removed
+
+
+
+
+ a #GPtrArray
+
+
+
+
+
+ the index of the pointer to steal
+
+
+
+
+
+ Removes the pointer at the given index from the pointer array.
+The last element in the array is used to fill in the space, so
+this function does not preserve the order of the array. But it
+is faster than g_ptr_array_steal_index(). The #GDestroyNotify for @array is
+*not* called on the removed element; ownership is transferred to the caller
+of this function.
+
+
+ the pointer which was removed
+
+
+
+
+ a #GPtrArray
+
+
+
+
+
+ the index of the pointer to steal
+
+
+
+
+
+ Atomically decrements the reference count of @array by one. If the
+reference count drops to 0, the effect is the same as calling
+g_ptr_array_free() with @free_segment set to %TRUE. This function
+is thread-safe and may be called from any thread.
+
+
+
+
+
+
+ A #GPtrArray
+
+
+
+
+
+
+
+
+ Contains the public fields of a
+[Queue][glib-Double-ended-Queues].
+
+
+ a pointer to the first element of the queue
+
+
+
+
+
+ a pointer to the last element of the queue
+
+
+
+
+
+ the number of elements in the queue
+
+
+
+ Removes all the elements in @queue. If queue elements contain
+dynamically-allocated memory, they should be freed first.
+
+
+
+
+
+
+ a #GQueue
+
+
+
+
+
+ Convenience method, which frees all the memory used by a #GQueue,
+and calls the provided @free_func on each item in the #GQueue.
+
+
+
+
+
+
+ a pointer to a #GQueue
+
+
+
+ the function to be called to free memory allocated
+
+
+
+
+
+ Copies a @queue. Note that is a shallow copy. If the elements in the
+queue consist of pointers to data, the pointers are copied, but the
+actual data is not.
+
+
+ a copy of @queue
+
+
+
+
+ a #GQueue
+
+
+
+
+
+ Removes @link_ from @queue and frees it.
+
+@link_ must be part of @queue.
+
+
+
+
+
+
+ a #GQueue
+
+
+
+ a #GList link that must be part of @queue
+
+
+
+
+
+
+
+ Finds the first link in @queue which contains @data.
+
+
+ the first link in @queue which contains @data
+
+
+
+
+
+
+ a #GQueue
+
+
+
+ data to find
+
+
+
+
+
+ Finds an element in a #GQueue, using a supplied function to find the
+desired element. It iterates over the queue, calling the given function
+which should return 0 when the desired element is found. The function
+takes two gconstpointer arguments, the #GQueue element's data as the
+first argument and the given user data as the second argument.
+
+
+ the found link, or %NULL if it wasn't found
+
+
+
+
+
+
+ a #GQueue
+
+
+
+ user data passed to @func
+
+
+
+ a #GCompareFunc to call for each element. It should return 0
+ when the desired element is found
+
+
+
+
+
+ Calls @func for each element in the queue passing @user_data to the
+function.
+
+It is safe for @func to remove the element from @queue, but it must
+not modify any part of the queue after that element.
+
+
+
+
+
+
+ a #GQueue
+
+
+
+ the function to call for each element's data
+
+
+
+ user data to pass to @func
+
+
+
+
+
+ Frees the memory allocated for the #GQueue. Only call this function
+if @queue was created with g_queue_new(). If queue elements contain
+dynamically-allocated memory, they should be freed first.
+
+If queue elements contain dynamically-allocated memory, you should
+either use g_queue_free_full() or free them manually first.
+
+
+
+
+
+
+ a #GQueue
+
+
+
+
+
+ Convenience method, which frees all the memory used by a #GQueue,
+and calls the specified destroy function on every element's data.
+
+@free_func should not modify the queue (eg, by removing the freed
+element from it).
+
+
+
+
+
+
+ a pointer to a #GQueue
+
+
+
+ the function to be called to free each element's data
+
+
+
+
+
+ Returns the number of items in @queue.
+
+
+ the number of items in @queue
+
+
+
+
+ a #GQueue
+
+
+
+
+
+ Returns the position of the first element in @queue which contains @data.
+
+
+ the position of the first element in @queue which
+ contains @data, or -1 if no element in @queue contains @data
+
+
+
+
+ a #GQueue
+
+
+
+ the data to find
+
+
+
+
+
+ A statically-allocated #GQueue must be initialized with this function
+before it can be used. Alternatively you can initialize it with
+%G_QUEUE_INIT. It is not necessary to initialize queues created with
+g_queue_new().
+
+
+
+
+
+
+ an uninitialized #GQueue
+
+
+
+
+
+ Inserts @data into @queue after @sibling.
+
+@sibling must be part of @queue. Since GLib 2.44 a %NULL sibling pushes the
+data at the head of the queue.
+
+
+
+
+
+
+ a #GQueue
+
+
+
+ a #GList link that must be part of @queue, or %NULL to
+ push at the head of the queue.
+
+
+
+
+
+ the data to insert
+
+
+
+
+
+ Inserts @link_ into @queue after @sibling.
+
+@sibling must be part of @queue.
+
+
+
+
+
+
+ a #GQueue
+
+
+
+ a #GList link that must be part of @queue, or %NULL to
+ push at the head of the queue.
+
+
+
+
+
+ a #GList link to insert which must not be part of any other list.
+
+
+
+
+
+
+
+ Inserts @data into @queue before @sibling.
+
+@sibling must be part of @queue. Since GLib 2.44 a %NULL sibling pushes the
+data at the tail of the queue.
+
+
+
+
+
+
+ a #GQueue
+
+
+
+ a #GList link that must be part of @queue, or %NULL to
+ push at the tail of the queue.
+
+
+
+
+
+ the data to insert
+
+
+
+
+
+ Inserts @link_ into @queue before @sibling.
+
+@sibling must be part of @queue.
+
+
+
+
+
+
+ a #GQueue
+
+
+
+ a #GList link that must be part of @queue, or %NULL to
+ push at the tail of the queue.
+
+
+
+
+
+ a #GList link to insert which must not be part of any other list.
+
+
+
+
+
+
+
+ Inserts @data into @queue using @func to determine the new position.
+
+
+
+
+
+
+ a #GQueue
+
+
+
+ the data to insert
+
+
+
+ the #GCompareDataFunc used to compare elements in the queue. It is
+ called with two elements of the @queue and @user_data. It should
+ return 0 if the elements are equal, a negative value if the first
+ element comes before the second, and a positive value if the second
+ element comes before the first.
+
+
+
+ user data passed to @func
+
+
+
+
+
+ Returns %TRUE if the queue is empty.
+
+
+ %TRUE if the queue is empty
+
+
+
+
+ a #GQueue.
+
+
+
+
+
+ Returns the position of @link_ in @queue.
+
+
+ the position of @link_, or -1 if the link is
+ not part of @queue
+
+
+
+
+ a #GQueue
+
+
+
+ a #GList link
+
+
+
+
+
+
+
+ Returns the first element of the queue.
+
+
+ the data of the first element in the queue, or %NULL
+ if the queue is empty
+
+
+
+
+ a #GQueue
+
+
+
+
+
+ Returns the first link in @queue.
+
+
+ the first link in @queue, or %NULL if @queue is empty
+
+
+
+
+
+
+ a #GQueue
+
+
+
+
+
+ Returns the @n'th element of @queue.
+
+
+ the data for the @n'th element of @queue,
+ or %NULL if @n is off the end of @queue
+
+
+
+
+ a #GQueue
+
+
+
+ the position of the element
+
+
+
+
+
+ Returns the link at the given position
+
+
+ the link at the @n'th position, or %NULL
+ if @n is off the end of the list
+
+
+
+
+
+
+ a #GQueue
+
+
+
+ the position of the link
+
+
+
+
+
+ Returns the last element of the queue.
+
+
+ the data of the last element in the queue, or %NULL
+ if the queue is empty
+
+
+
+
+ a #GQueue
+
+
+
+
+
+ Returns the last link in @queue.
+
+
+ the last link in @queue, or %NULL if @queue is empty
+
+
+
+
+
+
+ a #GQueue
+
+
+
+
+
+ Removes the first element of the queue and returns its data.
+
+
+ the data of the first element in the queue, or %NULL
+ if the queue is empty
+
+
+
+
+ a #GQueue
+
+
+
+
+
+ Removes and returns the first element of the queue.
+
+
+ the #GList element at the head of the queue, or %NULL
+ if the queue is empty
+
+
+
+
+
+
+ a #GQueue
+
+
+
+
+
+ Removes the @n'th element of @queue and returns its data.
+
+
+ the element's data, or %NULL if @n is off the end of @queue
+
+
+
+
+ a #GQueue
+
+
+
+ the position of the element
+
+
+
+
+
+ Removes and returns the link at the given position.
+
+
+ the @n'th link, or %NULL if @n is off the end of @queue
+
+
+
+
+
+
+ a #GQueue
+
+
+
+ the link's position
+
+
+
+
+
+ Removes the last element of the queue and returns its data.
+
+
+ the data of the last element in the queue, or %NULL
+ if the queue is empty
+
+
+
+
+ a #GQueue
+
+
+
+
+
+ Removes and returns the last element of the queue.
+
+
+ the #GList element at the tail of the queue, or %NULL
+ if the queue is empty
+
+
+
+
+
+
+ a #GQueue
+
+
+
+
+
+ Adds a new element at the head of the queue.
+
+
+
+
+
+
+ a #GQueue.
+
+
+
+ the data for the new element.
+
+
+
+
+
+ Adds a new element at the head of the queue.
+
+
+
+
+
+
+ a #GQueue
+
+
+
+ a single #GList element, not a list with more than one element
+
+
+
+
+
+
+
+ Inserts a new element into @queue at the given position.
+
+
+
+
+
+
+ a #GQueue
+
+
+
+ the data for the new element
+
+
+
+ the position to insert the new element. If @n is negative or
+ larger than the number of elements in the @queue, the element is
+ added to the end of the queue.
+
+
+
+
+
+ Inserts @link into @queue at the given position.
+
+
+
+
+
+
+ a #GQueue
+
+
+
+ the position to insert the link. If this is negative or larger than
+ the number of elements in @queue, the link is added to the end of
+ @queue.
+
+
+
+ the link to add to @queue
+
+
+
+
+
+
+
+ Adds a new element at the tail of the queue.
+
+
+
+
+
+
+ a #GQueue
+
+
+
+ the data for the new element
+
+
+
+
+
+ Adds a new element at the tail of the queue.
+
+
+
+
+
+
+ a #GQueue
+
+
+
+ a single #GList element, not a list with more than one element
+
+
+
+
+
+
+
+ Removes the first element in @queue that contains @data.
+
+
+ %TRUE if @data was found and removed from @queue
+
+
+
+
+ a #GQueue
+
+
+
+ the data to remove
+
+
+
+
+
+ Remove all elements whose data equals @data from @queue.
+
+
+ the number of elements removed from @queue
+
+
+
+
+ a #GQueue
+
+
+
+ the data to remove
+
+
+
+
+
+ Reverses the order of the items in @queue.
+
+
+
+
+
+
+ a #GQueue
+
+
+
+
+
+ Sorts @queue using @compare_func.
+
+
+
+
+
+
+ a #GQueue
+
+
+
+ the #GCompareDataFunc used to sort @queue. This function
+ is passed two elements of the queue and should return 0 if they are
+ equal, a negative value if the first comes before the second, and
+ a positive value if the second comes before the first.
+
+
+
+ user data passed to @compare_func
+
+
+
+
+
+ Unlinks @link_ so that it will no longer be part of @queue.
+The link is not freed.
+
+@link_ must be part of @queue.
+
+
+
+
+
+
+ a #GQueue
+
+
+
+ a #GList link that must be part of @queue
+
+
+
+
+
+
+
+ Creates a new #GQueue.
+
+
+ a newly allocated #GQueue
+
+
+
+
+
+ The GRWLock struct is an opaque data structure to represent a
+reader-writer lock. It is similar to a #GMutex in that it allows
+multiple threads to coordinate access to a shared resource.
+
+The difference to a mutex is that a reader-writer lock discriminates
+between read-only ('reader') and full ('writer') access. While only
+one thread at a time is allowed write access (by holding the 'writer'
+lock via g_rw_lock_writer_lock()), multiple threads can gain
+simultaneous read-only access (by holding the 'reader' lock via
+g_rw_lock_reader_lock()).
+
+It is unspecified whether readers or writers have priority in acquiring the
+lock when a reader already holds the lock and a writer is queued to acquire
+it.
+
+Here is an example for an array with access functions:
+|[<!-- language="C" -->
+ GRWLock lock;
+ GPtrArray *array;
+
+ gpointer
+ my_array_get (guint index)
+ {
+ gpointer retval = NULL;
+
+ if (!array)
+ return NULL;
+
+ g_rw_lock_reader_lock (&lock);
+ if (index < array->len)
+ retval = g_ptr_array_index (array, index);
+ g_rw_lock_reader_unlock (&lock);
+
+ return retval;
+ }
+
+ void
+ my_array_set (guint index, gpointer data)
+ {
+ g_rw_lock_writer_lock (&lock);
+
+ if (!array)
+ array = g_ptr_array_new ();
+
+ if (index >= array->len)
+ g_ptr_array_set_size (array, index+1);
+ g_ptr_array_index (array, index) = data;
+
+ g_rw_lock_writer_unlock (&lock);
+ }
+ ]|
+This example shows an array which can be accessed by many readers
+(the my_array_get() function) simultaneously, whereas the writers
+(the my_array_set() function) will only be allowed one at a time
+and only if no readers currently access the array. This is because
+of the potentially dangerous resizing of the array. Using these
+functions is fully multi-thread safe now.
+
+If a #GRWLock is allocated in static storage then it can be used
+without initialisation. Otherwise, you should call
+g_rw_lock_init() on it and g_rw_lock_clear() when done.
+
+A GRWLock should only be accessed with the g_rw_lock_ functions.
+
+
+
+
+
+
+
+
+
+
+ Frees the resources allocated to a lock with g_rw_lock_init().
+
+This function should not be used with a #GRWLock that has been
+statically allocated.
+
+Calling g_rw_lock_clear() when any thread holds the lock
+leads to undefined behaviour.
+
+
+
+
+
+
+ an initialized #GRWLock
+
+
+
+
+
+ Initializes a #GRWLock so that it can be used.
+
+This function is useful to initialize a lock that has been
+allocated on the stack, or as part of a larger structure. It is not
+necessary to initialise a reader-writer lock that has been statically
+allocated.
+
+|[<!-- language="C" -->
+ typedef struct {
+ GRWLock l;
+ ...
+ } Blob;
+
+Blob *b;
+
+b = g_new (Blob, 1);
+g_rw_lock_init (&b->l);
+]|
+
+To undo the effect of g_rw_lock_init() when a lock is no longer
+needed, use g_rw_lock_clear().
+
+Calling g_rw_lock_init() on an already initialized #GRWLock leads
+to undefined behaviour.
+
+
+
+
+
+
+ an uninitialized #GRWLock
+
+
+
+
+
+ Obtain a read lock on @rw_lock. If another thread currently holds
+the write lock on @rw_lock, the current thread will block until the
+write lock was (held and) released. If another thread does not hold
+the write lock, but is waiting for it, it is implementation defined
+whether the reader or writer will block. Read locks can be taken
+recursively.
+
+Calling g_rw_lock_reader_lock() while the current thread already
+owns a write lock leads to undefined behaviour. Read locks however
+can be taken recursively, in which case you need to make sure to
+call g_rw_lock_reader_unlock() the same amount of times.
+
+It is implementation-defined how many read locks are allowed to be
+held on the same lock simultaneously. If the limit is hit,
+or if a deadlock is detected, a critical warning will be emitted.
+
+
+
+
+
+
+ a #GRWLock
+
+
+
+
+
+ Tries to obtain a read lock on @rw_lock and returns %TRUE if
+the read lock was successfully obtained. Otherwise it
+returns %FALSE.
+
+
+ %TRUE if @rw_lock could be locked
+
+
+
+
+ a #GRWLock
+
+
+
+
+
+ Release a read lock on @rw_lock.
+
+Calling g_rw_lock_reader_unlock() on a lock that is not held
+by the current thread leads to undefined behaviour.
+
+
+
+
+
+
+ a #GRWLock
+
+
+
+
+
+ Obtain a write lock on @rw_lock. If another thread currently holds
+a read or write lock on @rw_lock, the current thread will block
+until all other threads have dropped their locks on @rw_lock.
+
+Calling g_rw_lock_writer_lock() while the current thread already
+owns a read or write lock on @rw_lock leads to undefined behaviour.
+
+
+
+
+
+
+ a #GRWLock
+
+
+
+
+
+ Tries to obtain a write lock on @rw_lock. If another thread
+currently holds a read or write lock on @rw_lock, it immediately
+returns %FALSE.
+Otherwise it locks @rw_lock and returns %TRUE.
+
+
+ %TRUE if @rw_lock could be locked
+
+
+
+
+ a #GRWLock
+
+
+
+
+
+ Release a write lock on @rw_lock.
+
+Calling g_rw_lock_writer_unlock() on a lock that is not held
+by the current thread leads to undefined behaviour.
+
+
+
+
+
+
+ a #GRWLock
+
+
+
+
+
+
+ The GRand struct is an opaque data structure. It should only be
+accessed through the g_rand_* functions.
+
+
+ Copies a #GRand into a new one with the same exact state as before.
+This way you can take a snapshot of the random number generator for
+replaying later.
+
+
+ the new #GRand
+
+
+
+
+ a #GRand
+
+
+
+
+
+ Returns the next random #gdouble from @rand_ equally distributed over
+the range [0..1).
+
+
+ a random number
+
+
+
+
+ a #GRand
+
+
+
+
+
+ Returns the next random #gdouble from @rand_ equally distributed over
+the range [@begin..@end).
+
+
+ a random number
+
+
+
+
+ a #GRand
+
+
+
+ lower closed bound of the interval
+
+
+
+ upper open bound of the interval
+
+
+
+
+
+ Frees the memory allocated for the #GRand.
+
+
+
+
+
+
+ a #GRand
+
+
+
+
+
+ Returns the next random #guint32 from @rand_ equally distributed over
+the range [0..2^32-1].
+
+
+ a random number
+
+
+
+
+ a #GRand
+
+
+
+
+
+ Returns the next random #gint32 from @rand_ equally distributed over
+the range [@begin..@end-1].
+
+
+ a random number
+
+
+
+
+ a #GRand
+
+
+
+ lower closed bound of the interval
+
+
+
+ upper open bound of the interval
+
+
+
+
+
+ Sets the seed for the random number generator #GRand to @seed.
+
+
+
+
+
+
+ a #GRand
+
+
+
+ a value to reinitialize the random number generator
+
+
+
+
+
+ Initializes the random number generator by an array of longs.
+Array can be of arbitrary size, though only the first 624 values
+are taken. This function is useful if you have many low entropy
+seeds, or if you require more then 32 bits of actual entropy for
+your application.
+
+
+
+
+
+
+ a #GRand
+
+
+
+ array to initialize with
+
+
+
+ length of array
+
+
+
+
+
+ Creates a new random number generator initialized with a seed taken
+either from `/dev/urandom` (if existing) or from the current time
+(as a fallback).
+
+On Windows, the seed is taken from rand_s().
+
+
+ the new #GRand
+
+
+
+
+ Creates a new random number generator initialized with @seed.
+
+
+ the new #GRand
+
+
+
+
+ a value to initialize the random number generator
+
+
+
+
+
+ Creates a new random number generator initialized with @seed.
+
+
+ the new #GRand
+
+
+
+
+ an array of seeds to initialize the random number generator
+
+
+
+ an array of seeds to initialize the random number
+ generator
+
+
+
+
+
+
+ The GRecMutex struct is an opaque data structure to represent a
+recursive mutex. It is similar to a #GMutex with the difference
+that it is possible to lock a GRecMutex multiple times in the same
+thread without deadlock. When doing so, care has to be taken to
+unlock the recursive mutex as often as it has been locked.
+
+If a #GRecMutex is allocated in static storage then it can be used
+without initialisation. Otherwise, you should call
+g_rec_mutex_init() on it and g_rec_mutex_clear() when done.
+
+A GRecMutex should only be accessed with the
+g_rec_mutex_ functions.
+
+
+
+
+
+
+
+
+
+
+ Frees the resources allocated to a recursive mutex with
+g_rec_mutex_init().
+
+This function should not be used with a #GRecMutex that has been
+statically allocated.
+
+Calling g_rec_mutex_clear() on a locked recursive mutex leads
+to undefined behaviour.
+
+
+
+
+
+
+ an initialized #GRecMutex
+
+
+
+
+
+ Initializes a #GRecMutex so that it can be used.
+
+This function is useful to initialize a recursive mutex
+that has been allocated on the stack, or as part of a larger
+structure.
+
+It is not necessary to initialise a recursive mutex that has been
+statically allocated.
+
+|[<!-- language="C" -->
+ typedef struct {
+ GRecMutex m;
+ ...
+ } Blob;
+
+Blob *b;
+
+b = g_new (Blob, 1);
+g_rec_mutex_init (&b->m);
+]|
+
+Calling g_rec_mutex_init() on an already initialized #GRecMutex
+leads to undefined behaviour.
+
+To undo the effect of g_rec_mutex_init() when a recursive mutex
+is no longer needed, use g_rec_mutex_clear().
+
+
+
+
+
+
+ an uninitialized #GRecMutex
+
+
+
+
+
+ Locks @rec_mutex. If @rec_mutex is already locked by another
+thread, the current thread will block until @rec_mutex is
+unlocked by the other thread. If @rec_mutex is already locked
+by the current thread, the 'lock count' of @rec_mutex is increased.
+The mutex will only become available again when it is unlocked
+as many times as it has been locked.
+
+
+
+
+
+
+ a #GRecMutex
+
+
+
+
+
+ Tries to lock @rec_mutex. If @rec_mutex is already locked
+by another thread, it immediately returns %FALSE. Otherwise
+it locks @rec_mutex and returns %TRUE.
+
+
+ %TRUE if @rec_mutex could be locked
+
+
+
+
+ a #GRecMutex
+
+
+
+
+
+ Unlocks @rec_mutex. If another thread is blocked in a
+g_rec_mutex_lock() call for @rec_mutex, it will become unblocked
+and can lock @rec_mutex itself.
+
+Calling g_rec_mutex_unlock() on a recursive mutex that is not
+locked by the current thread leads to undefined behaviour.
+
+
+
+
+
+
+ a #GRecMutex
+
+
+
+
+
+
+ The g_regex_*() functions implement regular
+expression pattern matching using syntax and semantics similar to
+Perl regular expression.
+
+Some functions accept a @start_position argument, setting it differs
+from just passing over a shortened string and setting %G_REGEX_MATCH_NOTBOL
+in the case of a pattern that begins with any kind of lookbehind assertion.
+For example, consider the pattern "\Biss\B" which finds occurrences of "iss"
+in the middle of words. ("\B" matches only if the current position in the
+subject is not a word boundary.) When applied to the string "Mississipi"
+from the fourth byte, namely "issipi", it does not match, because "\B" is
+always false at the start of the subject, which is deemed to be a word
+boundary. However, if the entire string is passed , but with
+@start_position set to 4, it finds the second occurrence of "iss" because
+it is able to look behind the starting point to discover that it is
+preceded by a letter.
+
+Note that, unless you set the %G_REGEX_RAW flag, all the strings passed
+to these functions must be encoded in UTF-8. The lengths and the positions
+inside the strings are in bytes and not in characters, so, for instance,
+"\xc3\xa0" (i.e. "à") is two bytes long but it is treated as a
+single character. If you set %G_REGEX_RAW the strings can be non-valid
+UTF-8 strings and a byte is treated as a character, so "\xc3\xa0" is two
+bytes and two characters long.
+
+When matching a pattern, "\n" matches only against a "\n" character in
+the string, and "\r" matches only a "\r" character. To match any newline
+sequence use "\R". This particular group matches either the two-character
+sequence CR + LF ("\r\n"), or one of the single characters LF (linefeed,
+U+000A, "\n"), VT vertical tab, U+000B, "\v"), FF (formfeed, U+000C, "\f"),
+CR (carriage return, U+000D, "\r"), NEL (next line, U+0085), LS (line
+separator, U+2028), or PS (paragraph separator, U+2029).
+
+The behaviour of the dot, circumflex, and dollar metacharacters are
+affected by newline characters, the default is to recognize any newline
+character (the same characters recognized by "\R"). This can be changed
+with %G_REGEX_NEWLINE_CR, %G_REGEX_NEWLINE_LF and %G_REGEX_NEWLINE_CRLF
+compile options, and with %G_REGEX_MATCH_NEWLINE_ANY,
+%G_REGEX_MATCH_NEWLINE_CR, %G_REGEX_MATCH_NEWLINE_LF and
+%G_REGEX_MATCH_NEWLINE_CRLF match options. These settings are also
+relevant when compiling a pattern if %G_REGEX_EXTENDED is set, and an
+unescaped "#" outside a character class is encountered. This indicates
+a comment that lasts until after the next newline.
+
+Creating and manipulating the same #GRegex structure from different
+threads is not a problem as #GRegex does not modify its internal
+state between creation and destruction, on the other hand #GMatchInfo
+is not threadsafe.
+
+The regular expressions low-level functionalities are obtained through
+the excellent
+[PCRE](http://www.pcre.org/)
+library written by Philip Hazel.
+
+
+ Compiles the regular expression to an internal form, and does
+the initial setup of the #GRegex structure.
+
+
+ a #GRegex structure or %NULL if an error occurred. Call
+ g_regex_unref() when you are done with it
+
+
+
+
+ the regular expression
+
+
+
+ compile options for the regular expression, or 0
+
+
+
+ match options for the regular expression, or 0
+
+
+
+
+
+ Returns the number of capturing subpatterns in the pattern.
+
+
+ the number of capturing subpatterns
+
+
+
+
+ a #GRegex
+
+
+
+
+
+ Returns the compile options that @regex was created with.
+
+Depending on the version of PCRE that is used, this may or may not
+include flags set by option expressions such as `(?i)` found at the
+top-level within the compiled pattern.
+
+
+ flags from #GRegexCompileFlags
+
+
+
+
+ a #GRegex
+
+
+
+
+
+ Checks whether the pattern contains explicit CR or LF references.
+
+
+ %TRUE if the pattern contains explicit CR or LF references
+
+
+
+
+ a #GRegex structure
+
+
+
+
+
+ Returns the match options that @regex was created with.
+
+
+ flags from #GRegexMatchFlags
+
+
+
+
+ a #GRegex
+
+
+
+
+
+ Returns the number of the highest back reference
+in the pattern, or 0 if the pattern does not contain
+back references.
+
+
+ the number of the highest back reference
+
+
+
+
+ a #GRegex
+
+
+
+
+
+ Gets the number of characters in the longest lookbehind assertion in the
+pattern. This information is useful when doing multi-segment matching using
+the partial matching facilities.
+
+
+ the number of characters in the longest lookbehind assertion.
+
+
+
+
+ a #GRegex structure
+
+
+
+
+
+ Gets the pattern string associated with @regex, i.e. a copy of
+the string passed to g_regex_new().
+
+
+ the pattern of @regex
+
+
+
+
+ a #GRegex structure
+
+
+
+
+
+ Retrieves the number of the subexpression named @name.
+
+
+ The number of the subexpression or -1 if @name
+ does not exists
+
+
+
+
+ #GRegex structure
+
+
+
+ name of the subexpression
+
+
+
+
+
+ Scans for a match in @string for the pattern in @regex.
+The @match_options are combined with the match options specified
+when the @regex structure was created, letting you have more
+flexibility in reusing #GRegex structures.
+
+Unless %G_REGEX_RAW is specified in the options, @string must be valid UTF-8.
+
+A #GMatchInfo structure, used to get information on the match,
+is stored in @match_info if not %NULL. Note that if @match_info
+is not %NULL then it is created even if the function returns %FALSE,
+i.e. you must free it regardless if regular expression actually matched.
+
+To retrieve all the non-overlapping matches of the pattern in
+string you can use g_match_info_next().
+
+|[<!-- language="C" -->
+static void
+print_uppercase_words (const gchar *string)
+{
+ // Print all uppercase-only words.
+ GRegex *regex;
+ GMatchInfo *match_info;
+
+ regex = g_regex_new ("[A-Z]+", G_REGEX_DEFAULT, G_REGEX_MATCH_DEFAULT, NULL);
+ g_regex_match (regex, string, 0, &match_info);
+ while (g_match_info_matches (match_info))
+ {
+ gchar *word = g_match_info_fetch (match_info, 0);
+ g_print ("Found: %s\n", word);
+ g_free (word);
+ g_match_info_next (match_info, NULL);
+ }
+ g_match_info_free (match_info);
+ g_regex_unref (regex);
+}
+]|
+
+@string is not copied and is used in #GMatchInfo internally. If
+you use any #GMatchInfo method (except g_match_info_free()) after
+freeing or modifying @string then the behaviour is undefined.
+
+
+ %TRUE is the string matched, %FALSE otherwise
+
+
+
+
+ a #GRegex structure from g_regex_new()
+
+
+
+ the string to scan for matches
+
+
+
+ match options
+
+
+
+ pointer to location where to store
+ the #GMatchInfo, or %NULL if you do not need it
+
+
+
+
+
+ Using the standard algorithm for regular expression matching only
+the longest match in the string is retrieved. This function uses
+a different algorithm so it can retrieve all the possible matches.
+For more documentation see g_regex_match_all_full().
+
+A #GMatchInfo structure, used to get information on the match, is
+stored in @match_info if not %NULL. Note that if @match_info is
+not %NULL then it is created even if the function returns %FALSE,
+i.e. you must free it regardless if regular expression actually
+matched.
+
+@string is not copied and is used in #GMatchInfo internally. If
+you use any #GMatchInfo method (except g_match_info_free()) after
+freeing or modifying @string then the behaviour is undefined.
+
+
+ %TRUE is the string matched, %FALSE otherwise
+
+
+
+
+ a #GRegex structure from g_regex_new()
+
+
+
+ the string to scan for matches
+
+
+
+ match options
+
+
+
+ pointer to location where to store
+ the #GMatchInfo, or %NULL if you do not need it
+
+
+
+
+
+ Using the standard algorithm for regular expression matching only
+the longest match in the @string is retrieved, it is not possible
+to obtain all the available matches. For instance matching
+"<a> <b> <c>" against the pattern "<.*>"
+you get "<a> <b> <c>".
+
+This function uses a different algorithm (called DFA, i.e. deterministic
+finite automaton), so it can retrieve all the possible matches, all
+starting at the same point in the string. For instance matching
+"<a> <b> <c>" against the pattern "<.*>;"
+you would obtain three matches: "<a> <b> <c>",
+"<a> <b>" and "<a>".
+
+The number of matched strings is retrieved using
+g_match_info_get_match_count(). To obtain the matched strings and
+their position you can use, respectively, g_match_info_fetch() and
+g_match_info_fetch_pos(). Note that the strings are returned in
+reverse order of length; that is, the longest matching string is
+given first.
+
+Note that the DFA algorithm is slower than the standard one and it
+is not able to capture substrings, so backreferences do not work.
+
+Setting @start_position differs from just passing over a shortened
+string and setting %G_REGEX_MATCH_NOTBOL in the case of a pattern
+that begins with any kind of lookbehind assertion, such as "\b".
+
+Unless %G_REGEX_RAW is specified in the options, @string must be valid UTF-8.
+
+A #GMatchInfo structure, used to get information on the match, is
+stored in @match_info if not %NULL. Note that if @match_info is
+not %NULL then it is created even if the function returns %FALSE,
+i.e. you must free it regardless if regular expression actually
+matched.
+
+@string is not copied and is used in #GMatchInfo internally. If
+you use any #GMatchInfo method (except g_match_info_free()) after
+freeing or modifying @string then the behaviour is undefined.
+
+
+ %TRUE is the string matched, %FALSE otherwise
+
+
+
+
+ a #GRegex structure from g_regex_new()
+
+
+
+ the string to scan for matches
+
+
+
+
+
+ the length of @string, in bytes, or -1 if @string is nul-terminated
+
+
+
+ starting index of the string to match, in bytes
+
+
+
+ match options
+
+
+
+ pointer to location where to store
+ the #GMatchInfo, or %NULL if you do not need it
+
+
+
+
+
+ Scans for a match in @string for the pattern in @regex.
+The @match_options are combined with the match options specified
+when the @regex structure was created, letting you have more
+flexibility in reusing #GRegex structures.
+
+Setting @start_position differs from just passing over a shortened
+string and setting %G_REGEX_MATCH_NOTBOL in the case of a pattern
+that begins with any kind of lookbehind assertion, such as "\b".
+
+Unless %G_REGEX_RAW is specified in the options, @string must be valid UTF-8.
+
+A #GMatchInfo structure, used to get information on the match, is
+stored in @match_info if not %NULL. Note that if @match_info is
+not %NULL then it is created even if the function returns %FALSE,
+i.e. you must free it regardless if regular expression actually
+matched.
+
+@string is not copied and is used in #GMatchInfo internally. If
+you use any #GMatchInfo method (except g_match_info_free()) after
+freeing or modifying @string then the behaviour is undefined.
+
+To retrieve all the non-overlapping matches of the pattern in
+string you can use g_match_info_next().
+
+|[<!-- language="C" -->
+static void
+print_uppercase_words (const gchar *string)
+{
+ // Print all uppercase-only words.
+ GRegex *regex;
+ GMatchInfo *match_info;
+ GError *error = NULL;
+
+ regex = g_regex_new ("[A-Z]+", G_REGEX_DEFAULT, G_REGEX_MATCH_DEFAULT, NULL);
+ g_regex_match_full (regex, string, -1, 0, 0, &match_info, &error);
+ while (g_match_info_matches (match_info))
+ {
+ gchar *word = g_match_info_fetch (match_info, 0);
+ g_print ("Found: %s\n", word);
+ g_free (word);
+ g_match_info_next (match_info, &error);
+ }
+ g_match_info_free (match_info);
+ g_regex_unref (regex);
+ if (error != NULL)
+ {
+ g_printerr ("Error while matching: %s\n", error->message);
+ g_error_free (error);
+ }
+}
+]|
+
+
+ %TRUE is the string matched, %FALSE otherwise
+
+
+
+
+ a #GRegex structure from g_regex_new()
+
+
+
+ the string to scan for matches
+
+
+
+
+
+ the length of @string, in bytes, or -1 if @string is nul-terminated
+
+
+
+ starting index of the string to match, in bytes
+
+
+
+ match options
+
+
+
+ pointer to location where to store
+ the #GMatchInfo, or %NULL if you do not need it
+
+
+
+
+
+ Increases reference count of @regex by 1.
+
+
+ @regex
+
+
+
+
+ a #GRegex
+
+
+
+
+
+ Replaces all occurrences of the pattern in @regex with the
+replacement text. Backreferences of the form '\number' or
+'\g<number>' in the replacement text are interpolated by the
+number-th captured subexpression of the match, '\g<name>' refers
+to the captured subexpression with the given name. '\0' refers
+to the complete match, but '\0' followed by a number is the octal
+representation of a character. To include a literal '\' in the
+replacement, write '\\\\'.
+
+There are also escapes that changes the case of the following text:
+
+- \l: Convert to lower case the next character
+- \u: Convert to upper case the next character
+- \L: Convert to lower case till \E
+- \U: Convert to upper case till \E
+- \E: End case modification
+
+If you do not need to use backreferences use g_regex_replace_literal().
+
+The @replacement string must be UTF-8 encoded even if %G_REGEX_RAW was
+passed to g_regex_new(). If you want to use not UTF-8 encoded strings
+you can use g_regex_replace_literal().
+
+Setting @start_position differs from just passing over a shortened
+string and setting %G_REGEX_MATCH_NOTBOL in the case of a pattern that
+begins with any kind of lookbehind assertion, such as "\b".
+
+
+ a newly allocated string containing the replacements
+
+
+
+
+ a #GRegex structure
+
+
+
+ the string to perform matches against
+
+
+
+
+
+ the length of @string, in bytes, or -1 if @string is nul-terminated
+
+
+
+ starting index of the string to match, in bytes
+
+
+
+ text to replace each match with
+
+
+
+ options for the match
+
+
+
+
+
+ Replaces occurrences of the pattern in regex with the output of
+@eval for that occurrence.
+
+Setting @start_position differs from just passing over a shortened
+string and setting %G_REGEX_MATCH_NOTBOL in the case of a pattern
+that begins with any kind of lookbehind assertion, such as "\b".
+
+The following example uses g_regex_replace_eval() to replace multiple
+strings at once:
+|[<!-- language="C" -->
+static gboolean
+eval_cb (const GMatchInfo *info,
+ GString *res,
+ gpointer data)
+{
+ gchar *match;
+ gchar *r;
+
+ match = g_match_info_fetch (info, 0);
+ r = g_hash_table_lookup ((GHashTable *)data, match);
+ g_string_append (res, r);
+ g_free (match);
+
+ return FALSE;
+}
+
+...
+
+GRegex *reg;
+GHashTable *h;
+gchar *res;
+
+h = g_hash_table_new (g_str_hash, g_str_equal);
+
+g_hash_table_insert (h, "1", "ONE");
+g_hash_table_insert (h, "2", "TWO");
+g_hash_table_insert (h, "3", "THREE");
+g_hash_table_insert (h, "4", "FOUR");
+
+reg = g_regex_new ("1|2|3|4", G_REGEX_DEFAULT, G_REGEX_MATCH_DEFAULT, NULL);
+res = g_regex_replace_eval (reg, text, -1, 0, 0, eval_cb, h, NULL);
+g_hash_table_destroy (h);
+
+...
+]|
+
+
+ a newly allocated string containing the replacements
+
+
+
+
+ a #GRegex structure from g_regex_new()
+
+
+
+ string to perform matches against
+
+
+
+
+
+ the length of @string, in bytes, or -1 if @string is nul-terminated
+
+
+
+ starting index of the string to match, in bytes
+
+
+
+ options for the match
+
+
+
+ a function to call for each match
+
+
+
+ user data to pass to the function
+
+
+
+
+
+ Replaces all occurrences of the pattern in @regex with the
+replacement text. @replacement is replaced literally, to
+include backreferences use g_regex_replace().
+
+Setting @start_position differs from just passing over a
+shortened string and setting %G_REGEX_MATCH_NOTBOL in the
+case of a pattern that begins with any kind of lookbehind
+assertion, such as "\b".
+
+
+ a newly allocated string containing the replacements
+
+
+
+
+ a #GRegex structure
+
+
+
+ the string to perform matches against
+
+
+
+
+
+ the length of @string, in bytes, or -1 if @string is nul-terminated
+
+
+
+ starting index of the string to match, in bytes
+
+
+
+ text to replace each match with
+
+
+
+ options for the match
+
+
+
+
+
+ Breaks the string on the pattern, and returns an array of the tokens.
+If the pattern contains capturing parentheses, then the text for each
+of the substrings will also be returned. If the pattern does not match
+anywhere in the string, then the whole string is returned as the first
+token.
+
+As a special case, the result of splitting the empty string "" is an
+empty vector, not a vector containing a single string. The reason for
+this special case is that being able to represent an empty vector is
+typically more useful than consistent handling of empty elements. If
+you do need to represent empty elements, you'll need to check for the
+empty string before calling this function.
+
+A pattern that can match empty strings splits @string into separate
+characters wherever it matches the empty string between characters.
+For example splitting "ab c" using as a separator "\s*", you will get
+"a", "b" and "c".
+
+
+ a %NULL-terminated gchar ** array. Free
+it using g_strfreev()
+
+
+
+
+
+
+ a #GRegex structure
+
+
+
+ the string to split with the pattern
+
+
+
+ match time option flags
+
+
+
+
+
+ Breaks the string on the pattern, and returns an array of the tokens.
+If the pattern contains capturing parentheses, then the text for each
+of the substrings will also be returned. If the pattern does not match
+anywhere in the string, then the whole string is returned as the first
+token.
+
+As a special case, the result of splitting the empty string "" is an
+empty vector, not a vector containing a single string. The reason for
+this special case is that being able to represent an empty vector is
+typically more useful than consistent handling of empty elements. If
+you do need to represent empty elements, you'll need to check for the
+empty string before calling this function.
+
+A pattern that can match empty strings splits @string into separate
+characters wherever it matches the empty string between characters.
+For example splitting "ab c" using as a separator "\s*", you will get
+"a", "b" and "c".
+
+Setting @start_position differs from just passing over a shortened
+string and setting %G_REGEX_MATCH_NOTBOL in the case of a pattern
+that begins with any kind of lookbehind assertion, such as "\b".
+
+
+ a %NULL-terminated gchar ** array. Free
+it using g_strfreev()
+
+
+
+
+
+
+ a #GRegex structure
+
+
+
+ the string to split with the pattern
+
+
+
+
+
+ the length of @string, in bytes, or -1 if @string is nul-terminated
+
+
+
+ starting index of the string to match, in bytes
+
+
+
+ match time option flags
+
+
+
+ the maximum number of tokens to split @string into.
+ If this is less than 1, the string is split completely
+
+
+
+
+
+ Decreases reference count of @regex by 1. When reference count drops
+to zero, it frees all the memory associated with the regex structure.
+
+
+
+
+
+
+ a #GRegex
+
+
+
+
+
+ Checks whether @replacement is a valid replacement string
+(see g_regex_replace()), i.e. that all escape sequences in
+it are valid.
+
+If @has_references is not %NULL then @replacement is checked
+for pattern references. For instance, replacement text 'foo\n'
+does not contain references and may be evaluated without information
+about actual match, but '\0\1' (whole match followed by first
+subpattern) requires valid #GMatchInfo object.
+
+
+ whether @replacement is a valid replacement string
+
+
+
+
+ the replacement string
+
+
+
+ location to store information about
+ references in @replacement or %NULL
+
+
+
+
+
+
+
+
+
+
+ Escapes the nul characters in @string to "\x00". It can be used
+to compile a regex with embedded nul characters.
+
+For completeness, @length can be -1 for a nul-terminated string.
+In this case the output string will be of course equal to @string.
+
+
+ a newly-allocated escaped string
+
+
+
+
+ the string to escape
+
+
+
+ the length of @string
+
+
+
+
+
+ Escapes the special characters used for regular expressions
+in @string, for instance "a.b*c" becomes "a\.b\*c". This
+function is useful to dynamically generate regular expressions.
+
+@string can contain nul characters that are replaced with "\0",
+in this case remember to specify the correct length of @string
+in @length.
+
+
+ a newly-allocated escaped string
+
+
+
+
+ the string to escape
+
+
+
+ the length of @string, in bytes, or -1 if @string is nul-terminated
+
+
+
+
+
+ Scans for a match in @string for @pattern.
+
+This function is equivalent to g_regex_match() but it does not
+require to compile the pattern with g_regex_new(), avoiding some
+lines of code when you need just to do a match without extracting
+substrings, capture counts, and so on.
+
+If this function is to be called on the same @pattern more than
+once, it's more efficient to compile the pattern once with
+g_regex_new() and then use g_regex_match().
+
+
+ %TRUE if the string matched, %FALSE otherwise
+
+
+
+
+ the regular expression
+
+
+
+ the string to scan for matches
+
+
+
+ compile options for the regular expression, or 0
+
+
+
+ match options, or 0
+
+
+
+
+
+ Breaks the string on the pattern, and returns an array of
+the tokens. If the pattern contains capturing parentheses,
+then the text for each of the substrings will also be returned.
+If the pattern does not match anywhere in the string, then the
+whole string is returned as the first token.
+
+This function is equivalent to g_regex_split() but it does
+not require to compile the pattern with g_regex_new(), avoiding
+some lines of code when you need just to do a split without
+extracting substrings, capture counts, and so on.
+
+If this function is to be called on the same @pattern more than
+once, it's more efficient to compile the pattern once with
+g_regex_new() and then use g_regex_split().
+
+As a special case, the result of splitting the empty string ""
+is an empty vector, not a vector containing a single string.
+The reason for this special case is that being able to represent
+an empty vector is typically more useful than consistent handling
+of empty elements. If you do need to represent empty elements,
+you'll need to check for the empty string before calling this
+function.
+
+A pattern that can match empty strings splits @string into
+separate characters wherever it matches the empty string between
+characters. For example splitting "ab c" using as a separator
+"\s*", you will get "a", "b" and "c".
+
+
+ a %NULL-terminated array of strings. Free
+it using g_strfreev()
+
+
+
+
+
+
+ the regular expression
+
+
+
+ the string to scan for matches
+
+
+
+ compile options for the regular expression, or 0
+
+
+
+ match options, or 0
+
+
+
+
+
+
+ Flags specifying compile-time options.
+
+
+ No special options set. Since: 2.74
+
+
+ Letters in the pattern match both upper- and
+ lowercase letters. This option can be changed within a pattern
+ by a "(?i)" option setting.
+
+
+ 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.
+
+
+ A dot metacharacter (".") 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.
+
+
+ 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.
+
+
+ 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 "^"
+ metacharacter.
+
+
+ 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.
+
+
+ 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.
+
+
+ Usually strings must be valid UTF-8 strings, using this
+ flag they are considered as a raw sequence of bytes.
+
+
+ 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).
+
+
+ Since 2.74 and the port to pcre2, requests JIT
+ compilation, which, if the just-in-time compiler is available, further
+ processes a compiled pattern into machine code that executes much
+ faster. However, it comes at the cost of extra processing before the
+ match is performed, so it is most beneficial to use this when the same
+ compiled pattern is used for matching many times. Before 2.74 this
+ option used the built-in non-JIT optimizations in pcre1.
+
+
+ Limits an unanchored pattern to match before (or at) the
+ first newline. Since: 2.34
+
+
+ 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.
+
+
+ Usually any newline character or character sequence is
+ recognized. If this option is set, the only recognized newline character
+ is '\r'.
+
+
+ Usually any newline character or character sequence is
+ recognized. If this option is set, the only recognized newline character
+ is '\n'.
+
+
+ Usually any newline character or character sequence is
+ recognized. If this option is set, the only recognized newline character
+ sequence is '\r\n'.
+
+
+ Usually any newline character or character sequence
+ is recognized. If this option is set, the only recognized newline character
+ sequences are '\r', '\n', and '\r\n'. Since: 2.34
+
+
+ Usually any newline character or character sequence
+ is recognised. If this option is set, then "\R" only recognizes the newline
+ characters '\r', '\n' and '\r\n'. Since: 2.34
+
+
+ Changes behaviour so that it is compatible with
+ JavaScript rather than PCRE. Since GLib 2.74 this is no longer supported,
+ as libpcre2 does not support it. Since: 2.34 Deprecated: 2.74
+
+
+
+ Error codes returned by regular expressions functions.
+
+
+ Compilation of the regular expression failed.
+
+
+ Optimization of the regular expression failed.
+
+
+ Replacement failed due to an ill-formed replacement
+ string.
+
+
+ The match process failed.
+
+
+ Internal error of the regular expression engine.
+ Since 2.16
+
+
+ "\\" at end of pattern. Since 2.16
+
+
+ "\\c" at end of pattern. Since 2.16
+
+
+ Unrecognized character follows "\\".
+ Since 2.16
+
+
+ Numbers out of order in "{}"
+ quantifier. Since 2.16
+
+
+ Number too big in "{}" quantifier.
+ Since 2.16
+
+
+ Missing terminating "]" for
+ character class. Since 2.16
+
+
+ Invalid escape sequence
+ in character class. Since 2.16
+
+
+ Range out of order in character class.
+ Since 2.16
+
+
+ Nothing to repeat. Since 2.16
+
+
+ Unrecognized character after "(?",
+ "(?<" or "(?P". Since 2.16
+
+
+ POSIX named classes are
+ supported only within a class. Since 2.16
+
+
+ Missing terminating ")" or ")"
+ without opening "(". Since 2.16
+
+
+ Reference to non-existent
+ subpattern. Since 2.16
+
+
+ Missing terminating ")" after comment.
+ Since 2.16
+
+
+ Regular expression too large.
+ Since 2.16
+
+
+ Failed to get memory. Since 2.16
+
+
+ Lookbehind assertion is not
+ fixed length. Since 2.16
+
+
+ Malformed number or name after "(?(".
+ Since 2.16
+
+
+ Conditional group contains
+ more than two branches. Since 2.16
+
+
+ Assertion expected after "(?(".
+ Since 2.16
+
+
+ Unknown POSIX class name.
+ Since 2.16
+
+
+ POSIX collating
+ elements are not supported. Since 2.16
+
+
+ Character value in "\\x{...}" sequence
+ is too large. Since 2.16
+
+
+ Invalid condition "(?(0)". Since 2.16
+
+
+ \\C not allowed in
+ lookbehind assertion. Since 2.16
+
+
+ Recursive call could loop indefinitely.
+ Since 2.16
+
+
+ Missing terminator
+ in subpattern name. Since 2.16
+
+
+ Two named subpatterns have
+ the same name. Since 2.16
+
+
+ Malformed "\\P" or "\\p" sequence.
+ Since 2.16
+
+
+ Unknown property name after "\\P" or
+ "\\p". Since 2.16
+
+
+ Subpattern name is too long
+ (maximum 32 characters). Since 2.16
+
+
+ Too many named subpatterns (maximum
+ 10,000). Since 2.16
+
+
+ Octal value is greater than "\\377".
+ Since 2.16
+
+
+ "DEFINE" group contains more
+ than one branch. Since 2.16
+
+
+ Repeating a "DEFINE" group is not allowed.
+ This error is never raised. Since: 2.16 Deprecated: 2.34
+
+
+ Inconsistent newline options.
+ Since 2.16
+
+
+ "\\g" is not followed by a braced,
+ angle-bracketed, or quoted name or number, or by a plain number. Since: 2.16
+
+
+ relative reference must not be zero. Since: 2.34
+
+
+ the backtracing
+ control verb used does not allow an argument. Since: 2.34
+
+
+ unknown backtracing
+ control verb. Since: 2.34
+
+
+ number is too big in escape sequence. Since: 2.34
+
+
+ Missing subpattern name. Since: 2.34
+
+
+ Missing digit. Since 2.34
+
+
+ In JavaScript compatibility mode,
+ "[" is an invalid data character. Since: 2.34
+
+
+ different names for subpatterns of the
+ same number are not allowed. Since: 2.34
+
+
+ the backtracing control
+ verb requires an argument. Since: 2.34
+
+
+ "\\c" must be followed by an ASCII
+ character. Since: 2.34
+
+
+ "\\k" is not followed by a braced, angle-bracketed, or
+ quoted name. Since: 2.34
+
+
+ "\\N" is not supported in a class. Since: 2.34
+
+
+ too many forward references. Since: 2.34
+
+
+ the name is too long in "(*MARK)", "(*PRUNE)",
+ "(*SKIP)", or "(*THEN)". Since: 2.34
+
+
+ the character value in the \\u sequence is
+ too large. Since: 2.34
+
+
+
+ Specifies the type of the function passed to g_regex_replace_eval().
+It is called for each occurrence of the pattern in the string passed
+to g_regex_replace_eval(), and it should append the replacement to
+@result.
+
+
+ %FALSE to continue the replacement process, %TRUE to stop it
+
+
+
+
+ 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.
+
+
+
+ a #GString containing the new string
+
+
+
+ user data passed to g_regex_replace_eval()
+
+
+
+
+
+ Flags specifying match-time options.
+
+
+ No special options set. Since: 2.74
+
+
+ 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 "^"
+ metacharacter.
+
+
+ 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".
+
+
+ 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".
+
+
+ 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".
+
+
+ Turns on the partial matching feature, for more
+ documentation on partial matching see g_match_info_is_partial_match().
+
+
+ Overrides the newline definition set when
+ creating a new #GRegex, setting the '\r' character as line terminator.
+
+
+ Overrides the newline definition set when
+ creating a new #GRegex, setting the '\n' character as line terminator.
+
+
+ Overrides the newline definition set when
+ creating a new #GRegex, setting the '\r\n' characters sequence as line terminator.
+
+
+ Overrides the newline definition set when
+ creating a new #GRegex, any Unicode newline sequence
+ is recognised as a newline. These are '\r', '\n' and '\rn', and the
+ single characters U+000B LINE TABULATION, U+000C FORM FEED (FF),
+ U+0085 NEXT LINE (NEL), U+2028 LINE SEPARATOR and
+ U+2029 PARAGRAPH SEPARATOR.
+
+
+ Overrides the newline definition set when
+ creating a new #GRegex; any '\r', '\n', or '\r\n' character sequence
+ is recognized as a newline. Since: 2.34
+
+
+ Overrides the newline definition for "\R" set when
+ creating a new #GRegex; only '\r', '\n', or '\r\n' character sequences
+ are recognized as a newline by "\R". Since: 2.34
+
+
+ Overrides the newline definition for "\R" set when
+ creating a new #GRegex; any Unicode newline character or character sequence
+ are recognized as a newline by "\R". These are '\r', '\n' and '\rn', and the
+ single characters U+000B LINE TABULATION, U+000C FORM FEED (FF),
+ U+0085 NEXT LINE (NEL), U+2028 LINE SEPARATOR and
+ U+2029 PARAGRAPH SEPARATOR. Since: 2.34
+
+
+ An alias for %G_REGEX_MATCH_PARTIAL. Since: 2.34
+
+
+ Turns on the partial matching feature. In contrast to
+ to %G_REGEX_MATCH_PARTIAL_SOFT, this stops matching as soon as a partial match
+ is found, without continuing to search for a possible complete match. See
+ g_match_info_is_partial_match() for more information. Since: 2.34
+
+
+ Like %G_REGEX_MATCH_NOTEMPTY, but only applied to
+ the start of the matched string. For anchored
+ patterns this can only happen for pattern containing "\K". Since: 2.34
+
+
+
+ The search path separator character.
+This is ':' on UNIX machines and ';' under Windows.
+
+
+
+
+ The search path separator as a string.
+This is ":" on UNIX machines and ";" under Windows.
+
+
+
+
+
+
+
+
+ Returns the size of @member in the struct definition without having a
+declared instance of @struct_type.
+
+
+
+ a structure type, e.g. #GOutputVector
+
+
+ a field in the structure, e.g. `size`
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The #GSList struct is used for each element in the singly-linked
+list.
+
+
+ holds the element's data, which can be a pointer to any kind
+ of data, or any integer value using the
+ [Type Conversion Macros][glib-Type-Conversion-Macros]
+
+
+
+ contains the link to the next element in the list.
+
+
+
+
+
+ Allocates space for one #GSList element. It is called by the
+g_slist_append(), g_slist_prepend(), g_slist_insert() and
+g_slist_insert_sorted() functions and so is rarely used on its own.
+
+
+ a pointer to the newly-allocated #GSList element.
+
+
+
+
+
+
+ Adds a new element on to the end of the list.
+
+The return value is the new start of the list, which may
+have changed, so make sure you store the new value.
+
+Note that g_slist_append() has to traverse the entire list
+to find the end, which is inefficient when adding multiple
+elements. A common idiom to avoid the inefficiency is to prepend
+the elements and reverse the list when all elements have been added.
+
+|[<!-- language="C" -->
+// Notice that these are initialized to the empty list.
+GSList *list = NULL, *number_list = NULL;
+
+// This is a list of strings.
+list = g_slist_append (list, "first");
+list = g_slist_append (list, "second");
+
+// This is a list of integers.
+number_list = g_slist_append (number_list, GINT_TO_POINTER (27));
+number_list = g_slist_append (number_list, GINT_TO_POINTER (14));
+]|
+
+
+ the new start of the #GSList
+
+
+
+
+
+
+ a #GSList
+
+
+
+
+
+ the data for the new element
+
+
+
+
+
+ Adds the second #GSList onto the end of the first #GSList.
+Note that the elements of the second #GSList are not copied.
+They are used directly.
+
+
+ the start of the new #GSList
+
+
+
+
+
+
+ a #GSList
+
+
+
+
+
+ the #GSList to add to the end of the first #GSList
+
+
+
+
+
+
+
+ Copies a #GSList.
+
+Note that this is a "shallow" copy. If the list elements
+consist of pointers to data, the pointers are copied but
+the actual data isn't. See g_slist_copy_deep() if you need
+to copy the data as well.
+
+
+ a copy of @list
+
+
+
+
+
+
+ a #GSList
+
+
+
+
+
+
+
+ Makes a full (deep) copy of a #GSList.
+
+In contrast with g_slist_copy(), this function uses @func to make a copy of
+each list element, in addition to copying the list container itself.
+
+@func, as a #GCopyFunc, takes two arguments, the data to be copied
+and a @user_data pointer. On common processor architectures, it's safe to
+pass %NULL as @user_data if the copy function takes only one argument. You
+may get compiler warnings from this though if compiling with GCC’s
+`-Wcast-function-type` warning.
+
+For instance, if @list holds a list of GObjects, you can do:
+|[<!-- language="C" -->
+another_list = g_slist_copy_deep (list, (GCopyFunc) g_object_ref, NULL);
+]|
+
+And, to entirely free the new list, you could do:
+|[<!-- language="C" -->
+g_slist_free_full (another_list, g_object_unref);
+]|
+
+
+ a full copy of @list, use g_slist_free_full() to free it
+
+
+
+
+
+
+ a #GSList
+
+
+
+
+
+ a copy function used to copy every element in the list
+
+
+
+ user data passed to the copy function @func, or #NULL
+
+
+
+
+
+ Removes the node link_ from the list and frees it.
+Compare this to g_slist_remove_link() which removes the node
+without freeing it.
+
+Removing arbitrary nodes from a singly-linked list requires time
+that is proportional to the length of the list (ie. O(n)). If you
+find yourself using g_slist_delete_link() frequently, you should
+consider a different data structure, such as the doubly-linked
+#GList.
+
+
+ the new head of @list
+
+
+
+
+
+
+ a #GSList
+
+
+
+
+
+ node to delete
+
+
+
+
+
+
+
+ Finds the element in a #GSList which
+contains the given data.
+
+
+ the found #GSList element,
+ or %NULL if it is not found
+
+
+
+
+
+
+ a #GSList
+
+
+
+
+
+ the element data to find
+
+
+
+
+
+ Finds an element in a #GSList, using a supplied function to
+find the desired element. It iterates over the list, calling
+the given function which should return 0 when the desired
+element is found. The function takes two #gconstpointer arguments,
+the #GSList element's data as the first argument and the
+given user data.
+
+
+ the found #GSList element, or %NULL if it is not found
+
+
+
+
+
+
+ a #GSList
+
+
+
+
+
+ user data passed to the function
+
+
+
+ the function to call for each element.
+ It should return 0 when the desired element is found
+
+
+
+
+
+ Calls a function for each element of a #GSList.
+
+It is safe for @func to remove the element from @list, but it must
+not modify any part of the list after that element.
+
+
+
+
+
+
+ a #GSList
+
+
+
+
+
+ the function to call with each element's data
+
+
+
+ user data to pass to the function
+
+
+
+
+
+ Frees all of the memory used by a #GSList.
+The freed elements are returned to the slice allocator.
+
+If list elements contain dynamically-allocated memory,
+you should either use g_slist_free_full() or free them manually
+first.
+
+It can be combined with g_steal_pointer() to ensure the list head pointer
+is not left dangling:
+|[<!-- language="C" -->
+GSList *list_of_borrowed_things = …; /<!-- -->* (transfer container) *<!-- -->/
+g_slist_free (g_steal_pointer (&list_of_borrowed_things));
+]|
+
+
+
+
+
+
+ the first link of a #GSList
+
+
+
+
+
+
+
+ Frees one #GSList element.
+It is usually used after g_slist_remove_link().
+
+
+
+
+
+
+ a #GSList element
+
+
+
+
+
+
+
+ Convenience method, which frees all the memory used by a #GSList, and
+calls the specified destroy function on every element's data.
+
+@free_func must not modify the list (eg, by removing the freed
+element from it).
+
+It can be combined with g_steal_pointer() to ensure the list head pointer
+is not left dangling — this also has the nice property that the head pointer
+is cleared before any of the list elements are freed, to prevent double frees
+from @free_func:
+|[<!-- language="C" -->
+GSList *list_of_owned_things = …; /<!-- -->* (transfer full) (element-type GObject) *<!-- -->/
+g_slist_free_full (g_steal_pointer (&list_of_owned_things), g_object_unref);
+]|
+
+
+
+
+
+
+ the first link of a #GSList
+
+
+
+
+
+ the function to be called to free each element's data
+
+
+
+
+
+ Gets the position of the element containing
+the given data (starting from 0).
+
+
+ the index of the element containing the data,
+ or -1 if the data is not found
+
+
+
+
+ a #GSList
+
+
+
+
+
+ the data to find
+
+
+
+
+
+ Inserts a new element into the list at the given position.
+
+
+ the new start of the #GSList
+
+
+
+
+
+
+ a #GSList
+
+
+
+
+
+ the data for the new element
+
+
+
+ the position to insert the element.
+ If this is negative, or is larger than the number
+ of elements in the list, the new element is added on
+ to the end of the list.
+
+
+
+
+
+ Inserts a node before @sibling containing @data.
+
+
+ the new head of the list.
+
+
+
+
+
+
+ a #GSList
+
+
+
+
+
+ node to insert @data before
+
+
+
+
+
+ data to put in the newly-inserted node
+
+
+
+
+
+ Inserts a new element into the list, using the given
+comparison function to determine its position.
+
+
+ the new start of the #GSList
+
+
+
+
+
+
+ a #GSList
+
+
+
+
+
+ the data for the new element
+
+
+
+ the function to compare elements in the list.
+ It should return a number > 0 if the first parameter
+ comes after the second parameter in the sort order.
+
+
+
+
+
+ Inserts a new element into the list, using the given
+comparison function to determine its position.
+
+
+ the new start of the #GSList
+
+
+
+
+
+
+ a #GSList
+
+
+
+
+
+ the data for the new element
+
+
+
+ the function to compare elements in the list.
+ It should return a number > 0 if the first parameter
+ comes after the second parameter in the sort order.
+
+
+
+ data to pass to comparison function
+
+
+
+
+
+ Gets the last element in a #GSList.
+
+This function iterates over the whole list.
+
+
+ the last element in the #GSList,
+ or %NULL if the #GSList has no elements
+
+
+
+
+
+
+ a #GSList
+
+
+
+
+
+
+
+ Gets the number of elements in a #GSList.
+
+This function iterates over the whole list to
+count its elements. To check whether the list is non-empty, it is faster to
+check @list against %NULL.
+
+
+ the number of elements in the #GSList
+
+
+
+
+ a #GSList
+
+
+
+
+
+
+
+ Gets the element at the given position in a #GSList.
+
+
+ the element, or %NULL if the position is off
+ the end of the #GSList
+
+
+
+
+
+
+ a #GSList
+
+
+
+
+
+ the position of the element, counting from 0
+
+
+
+
+
+ Gets the data of the element at the given position.
+
+
+ the element's data, or %NULL if the position
+ is off the end of the #GSList
+
+
+
+
+ a #GSList
+
+
+
+
+
+ the position of the element
+
+
+
+
+
+ Gets the position of the given element
+in the #GSList (starting from 0).
+
+
+ the position of the element in the #GSList,
+ or -1 if the element is not found
+
+
+
+
+ a #GSList
+
+
+
+
+
+ an element in the #GSList
+
+
+
+
+
+
+
+ Adds a new element on to the start of the list.
+
+The return value is the new start of the list, which
+may have changed, so make sure you store the new value.
+
+|[<!-- language="C" -->
+// Notice that it is initialized to the empty list.
+GSList *list = NULL;
+list = g_slist_prepend (list, "last");
+list = g_slist_prepend (list, "first");
+]|
+
+
+ the new start of the #GSList
+
+
+
+
+
+
+ a #GSList
+
+
+
+
+
+ the data for the new element
+
+
+
+
+
+ Removes an element from a #GSList.
+If two elements contain the same data, only the first is removed.
+If none of the elements contain the data, the #GSList is unchanged.
+
+
+ the new start of the #GSList
+
+
+
+
+
+
+ a #GSList
+
+
+
+
+
+ the data of the element to remove
+
+
+
+
+
+ Removes all list nodes with data equal to @data.
+Returns the new head of the list. Contrast with
+g_slist_remove() which removes only the first node
+matching the given data.
+
+
+ new head of @list
+
+
+
+
+
+
+ a #GSList
+
+
+
+
+
+ data to remove
+
+
+
+
+
+ Removes an element from a #GSList, without
+freeing the element. The removed element's next
+link is set to %NULL, so that it becomes a
+self-contained list with one element.
+
+Removing arbitrary nodes from a singly-linked list
+requires time that is proportional to the length of the list
+(ie. O(n)). If you find yourself using g_slist_remove_link()
+frequently, you should consider a different data structure,
+such as the doubly-linked #GList.
+
+
+ the new start of the #GSList, without the element
+
+
+
+
+
+
+ a #GSList
+
+
+
+
+
+ an element in the #GSList
+
+
+
+
+
+
+
+ Reverses a #GSList.
+
+
+ the start of the reversed #GSList
+
+
+
+
+
+
+ a #GSList
+
+
+
+
+
+
+
+ Sorts a #GSList using the given comparison function. The algorithm
+used is a stable sort.
+
+
+ the start of the sorted #GSList
+
+
+
+
+
+
+ a #GSList
+
+
+
+
+
+ the comparison function used to sort the #GSList.
+ This function is passed the data from 2 elements of the #GSList
+ and should return 0 if they are equal, a negative value if the
+ first element comes before the second, or a positive value if
+ the first element comes after the second.
+
+
+
+
+
+ Like g_slist_sort(), but the sort function accepts a user data argument.
+
+
+ new head of the list
+
+
+
+
+
+
+ a #GSList
+
+
+
+
+
+ comparison function
+
+
+
+ data to pass to comparison function
+
+
+
+
+
+
+ Use this macro as the return value of a #GSourceFunc to leave
+the #GSource in the main loop.
+
+
+
+
+ Cast a function pointer to a #GSourceFunc, suppressing warnings from GCC 8
+onwards with `-Wextra` or `-Wcast-function-type` enabled about the function
+types being incompatible.
+
+For example, the correct type of callback for a source created by
+g_child_watch_source_new() is #GChildWatchFunc, which accepts more arguments
+than #GSourceFunc. Casting the function with `(GSourceFunc)` to call
+g_source_set_callback() will trigger a warning, even though it will be cast
+back to the correct type before it is called by the source.
+
+
+
+ a function pointer.
+
+
+
+
+ Use this macro as the return value of a #GSourceFunc to remove
+the #GSource from the main loop.
+
+
+
+
+ The square root of two.
+
+
+
+
+ Accepts a macro or a string and converts it into a string after
+preprocessor argument expansion. For example, the following code:
+
+|[<!-- language="C" -->
+#define AGE 27
+const gchar *greeting = G_STRINGIFY (AGE) " today!";
+]|
+
+is transformed by the preprocessor into (code equivalent to):
+
+|[<!-- language="C" -->
+const gchar *greeting = "27 today!";
+]|
+
+
+
+ a macro or a string
+
+
+
+
+
+
+
+
+
+
+
+ Returns a member of a structure at a given offset, using the given type.
+
+
+
+ the type of the struct field
+
+
+ a pointer to a struct
+
+
+ the offset of the field from the start of the struct,
+ in bytes
+
+
+
+
+ Returns an untyped pointer to a given offset of a struct.
+
+
+
+ a pointer to a struct
+
+
+ the offset from the start of the struct, in bytes
+
+
+
+
+ Returns the offset, in bytes, of a member of a struct.
+
+Consider using standard C `offsetof()`, available since at least C89
+and C++98, in new code (but note that `offsetof()` returns a `size_t`
+rather than a `long`).
+
+
+
+ a structure type, e.g. #GtkWidget
+
+
+ a field in the structure, e.g. @window
+
+
+
+
+ The standard delimiters, used in g_strdelimit().
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The data structure representing a lexical scanner.
+
+You should set @input_name after creating the scanner, since
+it is used by the default message handler when displaying
+warnings and errors. If you are scanning a file, the filename
+would be a good choice.
+
+The @user_data and @max_parse_errors fields are not used.
+If you need to associate extra data with the scanner you
+can place them here.
+
+If you want to use your own message handler you can set the
+@msg_handler field. The type of the message handler function
+is declared by #GScannerMsgFunc.
+
+
+ unused
+
+
+
+ unused
+
+
+
+ g_scanner_error() increments this field
+
+
+
+ name of input stream, featured by the default message handler
+
+
+
+ quarked data
+
+
+
+ link into the scanner configuration
+
+
+
+ token parsed by the last g_scanner_get_next_token()
+
+
+
+ value of the last token from g_scanner_get_next_token()
+
+
+
+ line number of the last token from g_scanner_get_next_token()
+
+
+
+ char number of the last token from g_scanner_get_next_token()
+
+
+
+ token parsed by the last g_scanner_peek_next_token()
+
+
+
+ value of the last token from g_scanner_peek_next_token()
+
+
+
+ line number of the last token from g_scanner_peek_next_token()
+
+
+
+ char number of the last token from g_scanner_peek_next_token()
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ handler function for _warn and _error
+
+
+
+ Returns the current line in the input stream (counting
+from 1). This is the line of the last token parsed via
+g_scanner_get_next_token().
+
+
+ the current line
+
+
+
+
+ a #GScanner
+
+
+
+
+
+ Returns the current position in the current line (counting
+from 0). This is the position of the last token parsed via
+g_scanner_get_next_token().
+
+
+ the current position on the line
+
+
+
+
+ a #GScanner
+
+
+
+
+
+ Gets the current token type. This is simply the @token
+field in the #GScanner structure.
+
+
+ the current token type
+
+
+
+
+ a #GScanner
+
+
+
+
+
+ Gets the current token value. This is simply the @value
+field in the #GScanner structure.
+
+
+ the current token value
+
+
+
+
+ a #GScanner
+
+
+
+
+
+ Frees all memory used by the #GScanner.
+
+
+
+
+
+
+ a #GScanner
+
+
+
+
+
+ Returns %TRUE if the scanner has reached the end of
+the file or text buffer.
+
+
+ %TRUE if the scanner has reached the end of
+ the file or text buffer
+
+
+
+
+ a #GScanner
+
+
+
+
+
+ Outputs an error message, via the #GScanner message handler.
+
+
+
+
+
+
+ a #GScanner
+
+
+
+ the message format. See the printf() documentation
+
+
+
+ the parameters to insert into the format string
+
+
+
+
+
+ Parses the next token just like g_scanner_peek_next_token()
+and also removes it from the input stream. The token data is
+placed in the @token, @value, @line, and @position fields of
+the #GScanner structure.
+
+
+ the type of the token
+
+
+
+
+ a #GScanner
+
+
+
+
+
+ Prepares to scan a file.
+
+
+
+
+
+
+ a #GScanner
+
+
+
+ a file descriptor
+
+
+
+
+
+ Prepares to scan a text buffer.
+
+
+
+
+
+
+ a #GScanner
+
+
+
+ the text buffer to scan
+
+
+
+ the length of the text buffer
+
+
+
+
+
+ Looks up a symbol in the current scope and return its value.
+If the symbol is not bound in the current scope, %NULL is
+returned.
+
+
+ the value of @symbol in the current scope, or %NULL
+ if @symbol is not bound in the current scope
+
+
+
+
+ a #GScanner
+
+
+
+ the symbol to look up
+
+
+
+
+
+ Parses the next token, without removing it from the input stream.
+The token data is placed in the @next_token, @next_value, @next_line,
+and @next_position fields of the #GScanner structure.
+
+Note that, while the token is not removed from the input stream
+(i.e. the next call to g_scanner_get_next_token() will return the
+same token), it will not be reevaluated. This can lead to surprising
+results when changing scope or the scanner configuration after peeking
+the next token. Getting the next token after switching the scope or
+configuration will return whatever was peeked before, regardless of
+any symbols that may have been added or removed in the new scope.
+
+
+ the type of the token
+
+
+
+
+ a #GScanner
+
+
+
+
+
+ Adds a symbol to the given scope.
+
+
+
+
+
+
+ a #GScanner
+
+
+
+ the scope id
+
+
+
+ the symbol to add
+
+
+
+ the value of the symbol
+
+
+
+
+
+ Calls the given function for each of the symbol/value pairs
+in the given scope of the #GScanner. The function is passed
+the symbol and value of each pair, and the given @user_data
+parameter.
+
+
+
+
+
+
+ a #GScanner
+
+
+
+ the scope id
+
+
+
+ the function to call for each symbol/value pair
+
+
+
+ user data to pass to the function
+
+
+
+
+
+ Looks up a symbol in a scope and return its value. If the
+symbol is not bound in the scope, %NULL is returned.
+
+
+ the value of @symbol in the given scope, or %NULL
+ if @symbol is not bound in the given scope.
+
+
+
+
+ a #GScanner
+
+
+
+ the scope id
+
+
+
+ the symbol to look up
+
+
+
+
+
+ Removes a symbol from a scope.
+
+
+
+
+
+
+ a #GScanner
+
+
+
+ the scope id
+
+
+
+ the symbol to remove
+
+
+
+
+
+ Sets the current scope.
+
+
+ the old scope id
+
+
+
+
+ a #GScanner
+
+
+
+ the new scope id
+
+
+
+
+
+ Rewinds the filedescriptor to the current buffer position
+and blows the file read ahead buffer. This is useful for
+third party uses of the scanners filedescriptor, which hooks
+onto the current scanning position.
+
+
+
+
+
+
+ a #GScanner
+
+
+
+
+
+ Outputs a message through the scanner's msg_handler,
+resulting from an unexpected token in the input stream.
+Note that you should not call g_scanner_peek_next_token()
+followed by g_scanner_unexp_token() without an intermediate
+call to g_scanner_get_next_token(), as g_scanner_unexp_token()
+evaluates the scanner's current token (not the peeked token)
+to construct part of the message.
+
+
+
+
+
+
+ a #GScanner
+
+
+
+ the expected token
+
+
+
+ a string describing how the scanner's user
+ refers to identifiers (%NULL defaults to "identifier").
+ This is used if @expected_token is %G_TOKEN_IDENTIFIER or
+ %G_TOKEN_IDENTIFIER_NULL.
+
+
+
+ a string describing how the scanner's user refers
+ to symbols (%NULL defaults to "symbol"). This is used if
+ @expected_token is %G_TOKEN_SYMBOL or any token value greater
+ than %G_TOKEN_LAST.
+
+
+
+ the name of the symbol, if the scanner's current
+ token is a symbol.
+
+
+
+ a message string to output at the end of the
+ warning/error, or %NULL.
+
+
+
+ if %TRUE it is output as an error. If %FALSE it is
+ output as a warning.
+
+
+
+
+
+ Outputs a warning message, via the #GScanner message handler.
+
+
+
+
+
+
+ a #GScanner
+
+
+
+ the message format. See the printf() documentation
+
+
+
+ the parameters to insert into the format string
+
+
+
+
+
+ Creates a new #GScanner.
+
+The @config_templ structure specifies the initial settings
+of the scanner, which are copied into the #GScanner
+@config field. If you pass %NULL then the default settings
+are used.
+
+
+ the new #GScanner
+
+
+
+
+ the initial scanner settings
+
+
+
+
+
+
+ Specifies the #GScanner parser configuration. Most settings can
+be changed during the parsing phase and will affect the lexical
+parsing of the next unpeeked token.
+
+
+ specifies which characters should be skipped
+ by the scanner (the default is the whitespace characters: space,
+ tab, carriage-return and line-feed).
+
+
+
+ specifies the characters which can start
+ identifiers (the default is %G_CSET_a_2_z, "_", and %G_CSET_A_2_Z).
+
+
+
+ specifies the characters which can be used
+ in identifiers, after the first character (the default is
+ %G_CSET_a_2_z, "_0123456789", %G_CSET_A_2_Z, %G_CSET_LATINS,
+ %G_CSET_LATINC).
+
+
+
+ specifies the characters at the start and
+ end of single-line comments. The default is "#\n" which means
+ that single-line comments start with a '#' and continue until
+ a '\n' (end of line).
+
+
+
+ specifies if symbols are case sensitive (the
+ default is %FALSE).
+
+
+
+ specifies if multi-line comments are skipped
+ and not returned as tokens (the default is %TRUE).
+
+
+
+ specifies if single-line comments are skipped
+ and not returned as tokens (the default is %TRUE).
+
+
+
+ specifies if multi-line comments are recognized
+ (the default is %TRUE).
+
+
+
+ specifies if identifiers are recognized (the
+ default is %TRUE).
+
+
+
+ specifies if single-character
+ identifiers are recognized (the default is %FALSE).
+
+
+
+ specifies if %NULL is reported as
+ %G_TOKEN_IDENTIFIER_NULL (the default is %FALSE).
+
+
+
+ specifies if symbols are recognized (the default
+ is %TRUE).
+
+
+
+ specifies if binary numbers are recognized (the
+ default is %FALSE).
+
+
+
+ specifies if octal numbers are recognized (the
+ default is %TRUE).
+
+
+
+ specifies if floating point numbers are recognized
+ (the default is %TRUE).
+
+
+
+ specifies if hexadecimal numbers are recognized (the
+ default is %TRUE).
+
+
+
+ specifies if '$' is recognized as a prefix for
+ hexadecimal numbers (the default is %FALSE).
+
+
+
+ specifies if strings can be enclosed in single
+ quotes (the default is %TRUE).
+
+
+
+ specifies if strings can be enclosed in double
+ quotes (the default is %TRUE).
+
+
+
+ specifies if binary, octal and hexadecimal numbers
+ are reported as %G_TOKEN_INT (the default is %TRUE).
+
+
+
+ specifies if all numbers are reported as %G_TOKEN_FLOAT
+ (the default is %FALSE).
+
+
+
+ specifies if identifiers are reported as strings
+ (the default is %FALSE).
+
+
+
+ specifies if characters are reported by setting
+ `token = ch` or as %G_TOKEN_CHAR (the default is %TRUE).
+
+
+
+ specifies if symbols are reported by setting
+ `token = v_symbol` or as %G_TOKEN_SYMBOL (the default is %FALSE).
+
+
+
+ specifies if a symbol is searched for in the
+ default scope in addition to the current scope (the default is %FALSE).
+
+
+
+ use value.v_int64 rather than v_int
+
+
+
+
+
+
+
+ Specifies the type of the message handler function.
+
+
+
+
+
+
+ a #GScanner
+
+
+
+ the message
+
+
+
+ %TRUE if the message signals an error,
+ %FALSE if it signals a warning.
+
+
+
+
+
+ An enumeration specifying the base position for a
+g_io_channel_seek_position() operation.
+
+
+ the current position in the file.
+
+
+ the start of the file.
+
+
+ the end of the file.
+
+
+
+ The #GSequence struct is an opaque data type representing a
+[sequence][glib-Sequences] data type.
+
+
+ Adds a new item to the end of @seq.
+
+
+ an iterator pointing to the new item
+
+
+
+
+ a #GSequence
+
+
+
+ the data for the new item
+
+
+
+
+
+ Calls @func for each item in the sequence passing @user_data
+to the function. @func must not modify the sequence itself.
+
+
+
+
+
+
+ a #GSequence
+
+
+
+ the function to call for each item in @seq
+
+
+
+ user data passed to @func
+
+
+
+
+
+ Frees the memory allocated for @seq. If @seq has a data destroy
+function associated with it, that function is called on all items
+in @seq.
+
+
+
+
+
+
+ a #GSequence
+
+
+
+
+
+ Returns the begin iterator for @seq.
+
+
+ the begin iterator for @seq.
+
+
+
+
+ a #GSequence
+
+
+
+
+
+ Returns the end iterator for @seg
+
+
+ the end iterator for @seq
+
+
+
+
+ a #GSequence
+
+
+
+
+
+ Returns the iterator at position @pos. If @pos is negative or larger
+than the number of items in @seq, the end iterator is returned.
+
+
+ The #GSequenceIter at position @pos
+
+
+
+
+ a #GSequence
+
+
+
+ a position in @seq, or -1 for the end
+
+
+
+
+
+ Returns the positive length (>= 0) of @seq. Note that this method is
+O(h) where `h' is the height of the tree. It is thus more efficient
+to use g_sequence_is_empty() when comparing the length to zero.
+
+
+ the length of @seq
+
+
+
+
+ a #GSequence
+
+
+
+
+
+ Inserts @data into @seq using @cmp_func to determine the new
+position. The sequence must already be sorted according to @cmp_func;
+otherwise the new position of @data is undefined.
+
+@cmp_func is called with two items of the @seq, and @cmp_data.
+It should return 0 if the items are equal, a negative value
+if the first item comes before the second, and a positive value
+if the second item comes before the first.
+
+Note that when adding a large amount of data to a #GSequence,
+it is more efficient to do unsorted insertions and then call
+g_sequence_sort() or g_sequence_sort_iter().
+
+
+ a #GSequenceIter pointing to the new item.
+
+
+
+
+ a #GSequence
+
+
+
+ the data to insert
+
+
+
+ the function used to compare items in the sequence
+
+
+
+ user data passed to @cmp_func.
+
+
+
+
+
+ Like g_sequence_insert_sorted(), but uses
+a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as
+the compare function.
+
+@iter_cmp is called with two iterators pointing into @seq.
+It should return 0 if the iterators are equal, a negative
+value if the first iterator comes before the second, and a
+positive value if the second iterator comes before the first.
+
+Note that when adding a large amount of data to a #GSequence,
+it is more efficient to do unsorted insertions and then call
+g_sequence_sort() or g_sequence_sort_iter().
+
+
+ a #GSequenceIter pointing to the new item
+
+
+
+
+ a #GSequence
+
+
+
+ data for the new item
+
+
+
+ the function used to compare iterators in the sequence
+
+
+
+ user data passed to @iter_cmp
+
+
+
+
+
+ Returns %TRUE if the sequence contains zero items.
+
+This function is functionally identical to checking the result of
+g_sequence_get_length() being equal to zero. However this function is
+implemented in O(1) running time.
+
+
+ %TRUE if the sequence is empty, otherwise %FALSE.
+
+
+
+
+ a #GSequence
+
+
+
+
+
+ Returns an iterator pointing to the position of the first item found
+equal to @data according to @cmp_func and @cmp_data. If more than one
+item is equal, it is not guaranteed that it is the first which is
+returned. In that case, you can use g_sequence_iter_next() and
+g_sequence_iter_prev() to get others.
+
+@cmp_func is called with two items of the @seq, and @cmp_data.
+It should return 0 if the items are equal, a negative value if
+the first item comes before the second, and a positive value if
+the second item comes before the first.
+
+This function will fail if the data contained in the sequence is
+unsorted.
+
+
+ an #GSequenceIter pointing to the position of the
+ first item found equal to @data according to @cmp_func and
+ @cmp_data, or %NULL if no such item exists
+
+
+
+
+ a #GSequence
+
+
+
+ data to look up
+
+
+
+ the function used to compare items in the sequence
+
+
+
+ user data passed to @cmp_func
+
+
+
+
+
+ Like g_sequence_lookup(), but uses a #GSequenceIterCompareFunc
+instead of a #GCompareDataFunc as the compare function.
+
+@iter_cmp is called with two iterators pointing into @seq.
+It should return 0 if the iterators are equal, a negative value
+if the first iterator comes before the second, and a positive
+value if the second iterator comes before the first.
+
+This function will fail if the data contained in the sequence is
+unsorted.
+
+
+ an #GSequenceIter pointing to the position of
+ the first item found equal to @data according to @iter_cmp
+ and @cmp_data, or %NULL if no such item exists
+
+
+
+
+ a #GSequence
+
+
+
+ data to look up
+
+
+
+ the function used to compare iterators in the sequence
+
+
+
+ user data passed to @iter_cmp
+
+
+
+
+
+ Adds a new item to the front of @seq
+
+
+ an iterator pointing to the new item
+
+
+
+
+ a #GSequence
+
+
+
+ the data for the new item
+
+
+
+
+
+ Returns an iterator pointing to the position where @data would
+be inserted according to @cmp_func and @cmp_data.
+
+@cmp_func is called with two items of the @seq, and @cmp_data.
+It should return 0 if the items are equal, a negative value if
+the first item comes before the second, and a positive value if
+the second item comes before the first.
+
+If you are simply searching for an existing element of the sequence,
+consider using g_sequence_lookup().
+
+This function will fail if the data contained in the sequence is
+unsorted.
+
+
+ an #GSequenceIter pointing to the position where @data
+ would have been inserted according to @cmp_func and @cmp_data
+
+
+
+
+ a #GSequence
+
+
+
+ data for the new item
+
+
+
+ the function used to compare items in the sequence
+
+
+
+ user data passed to @cmp_func
+
+
+
+
+
+ Like g_sequence_search(), but uses a #GSequenceIterCompareFunc
+instead of a #GCompareDataFunc as the compare function.
+
+@iter_cmp is called with two iterators pointing into @seq.
+It should return 0 if the iterators are equal, a negative value
+if the first iterator comes before the second, and a positive
+value if the second iterator comes before the first.
+
+If you are simply searching for an existing element of the sequence,
+consider using g_sequence_lookup_iter().
+
+This function will fail if the data contained in the sequence is
+unsorted.
+
+
+ a #GSequenceIter pointing to the position in @seq
+ where @data would have been inserted according to @iter_cmp
+ and @cmp_data
+
+
+
+
+ a #GSequence
+
+
+
+ data for the new item
+
+
+
+ the function used to compare iterators in the sequence
+
+
+
+ user data passed to @iter_cmp
+
+
+
+
+
+ Sorts @seq using @cmp_func.
+
+@cmp_func is passed two items of @seq and should
+return 0 if they are equal, a negative value if the
+first comes before the second, and a positive value
+if the second comes before the first.
+
+
+
+
+
+
+ a #GSequence
+
+
+
+ the function used to sort the sequence
+
+
+
+ user data passed to @cmp_func
+
+
+
+
+
+ Like g_sequence_sort(), but uses a #GSequenceIterCompareFunc instead
+of a #GCompareDataFunc as the compare function
+
+@cmp_func is called with two iterators pointing into @seq. It should
+return 0 if the iterators are equal, a negative value if the first
+iterator comes before the second, and a positive value if the second
+iterator comes before the first.
+
+
+
+
+
+
+ a #GSequence
+
+
+
+ the function used to compare iterators in the sequence
+
+
+
+ user data passed to @cmp_func
+
+
+
+
+
+ Calls @func for each item in the range (@begin, @end) passing
+@user_data to the function. @func must not modify the sequence
+itself.
+
+
+
+
+
+
+ a #GSequenceIter
+
+
+
+ a #GSequenceIter
+
+
+
+ a #GFunc
+
+
+
+ user data passed to @func
+
+
+
+
+
+ Returns the data that @iter points to.
+
+
+ the data that @iter points to
+
+
+
+
+ a #GSequenceIter
+
+
+
+
+
+ Inserts a new item just before the item pointed to by @iter.
+
+
+ an iterator pointing to the new item
+
+
+
+
+ a #GSequenceIter
+
+
+
+ the data for the new item
+
+
+
+
+
+ Moves the item pointed to by @src to the position indicated by @dest.
+After calling this function @dest will point to the position immediately
+after @src. It is allowed for @src and @dest to point into different
+sequences.
+
+
+
+
+
+
+ a #GSequenceIter pointing to the item to move
+
+
+
+ a #GSequenceIter pointing to the position to which
+ the item is moved
+
+
+
+
+
+ Inserts the (@begin, @end) range at the destination pointed to by @dest.
+The @begin and @end iters must point into the same sequence. It is
+allowed for @dest to point to a different sequence than the one pointed
+into by @begin and @end.
+
+If @dest is %NULL, the range indicated by @begin and @end is
+removed from the sequence. If @dest points to a place within
+the (@begin, @end) range, the range does not move.
+
+
+
+
+
+
+ a #GSequenceIter
+
+
+
+ a #GSequenceIter
+
+
+
+ a #GSequenceIter
+
+
+
+
+
+ Creates a new GSequence. The @data_destroy function, if non-%NULL will
+be called on all items when the sequence is destroyed and on items that
+are removed from the sequence.
+
+
+ a new #GSequence
+
+
+
+
+ a #GDestroyNotify function, or %NULL
+
+
+
+
+
+ Finds an iterator somewhere in the range (@begin, @end). This
+iterator will be close to the middle of the range, but is not
+guaranteed to be exactly in the middle.
+
+The @begin and @end iterators must both point to the same sequence
+and @begin must come before or be equal to @end in the sequence.
+
+
+ a #GSequenceIter pointing somewhere in the
+ (@begin, @end) range
+
+
+
+
+ a #GSequenceIter
+
+
+
+ a #GSequenceIter
+
+
+
+
+
+ Removes the item pointed to by @iter. It is an error to pass the
+end iterator to this function.
+
+If the sequence has a data destroy function associated with it, this
+function is called on the data for the removed item.
+
+
+
+
+
+
+ a #GSequenceIter
+
+
+
+
+
+ Removes all items in the (@begin, @end) range.
+
+If the sequence has a data destroy function associated with it, this
+function is called on the data for the removed items.
+
+
+
+
+
+
+ a #GSequenceIter
+
+
+
+ a #GSequenceIter
+
+
+
+
+
+ Changes the data for the item pointed to by @iter to be @data. If
+the sequence has a data destroy function associated with it, that
+function is called on the existing data that @iter pointed to.
+
+
+
+
+
+
+ a #GSequenceIter
+
+
+
+ new data for the item
+
+
+
+
+
+ Moves the data pointed to by @iter to a new position as indicated by
+@cmp_func. This
+function should be called for items in a sequence already sorted according
+to @cmp_func whenever some aspect of an item changes so that @cmp_func
+may return different values for that item.
+
+@cmp_func is called with two items of the @seq, and @cmp_data.
+It should return 0 if the items are equal, a negative value if
+the first item comes before the second, and a positive value if
+the second item comes before the first.
+
+
+
+
+
+
+ A #GSequenceIter
+
+
+
+ the function used to compare items in the sequence
+
+
+
+ user data passed to @cmp_func.
+
+
+
+
+
+ Like g_sequence_sort_changed(), but uses
+a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as
+the compare function.
+
+@iter_cmp is called with two iterators pointing into the #GSequence that
+@iter points into. It should
+return 0 if the iterators are equal, a negative value if the first
+iterator comes before the second, and a positive value if the second
+iterator comes before the first.
+
+
+
+
+
+
+ a #GSequenceIter
+
+
+
+ the function used to compare iterators in the sequence
+
+
+
+ user data passed to @cmp_func
+
+
+
+
+
+ Swaps the items pointed to by @a and @b. It is allowed for @a and @b
+to point into difference sequences.
+
+
+
+
+
+
+ a #GSequenceIter
+
+
+
+ a #GSequenceIter
+
+
+
+
+
+
+ The #GSequenceIter struct is an opaque data type representing an
+iterator pointing into a #GSequence.
+
+
+ Returns a negative number if @a comes before @b, 0 if they are equal,
+and a positive number if @a comes after @b.
+
+The @a and @b iterators must point into the same sequence.
+
+
+ a negative number if @a comes before @b, 0 if they are
+ equal, and a positive number if @a comes after @b
+
+
+
+
+ a #GSequenceIter
+
+
+
+ a #GSequenceIter
+
+
+
+
+
+ Returns the position of @iter
+
+
+ the position of @iter
+
+
+
+
+ a #GSequenceIter
+
+
+
+
+
+ Returns the #GSequence that @iter points into.
+
+
+ the #GSequence that @iter points into
+
+
+
+
+ a #GSequenceIter
+
+
+
+
+
+ Returns whether @iter is the begin iterator
+
+
+ whether @iter is the begin iterator
+
+
+
+
+ a #GSequenceIter
+
+
+
+
+
+ Returns whether @iter is the end iterator
+
+
+ Whether @iter is the end iterator
+
+
+
+
+ a #GSequenceIter
+
+
+
+
+
+ Returns the #GSequenceIter which is @delta positions away from @iter.
+If @iter is closer than -@delta positions to the beginning of the sequence,
+the begin iterator is returned. If @iter is closer than @delta positions
+to the end of the sequence, the end iterator is returned.
+
+
+ a #GSequenceIter which is @delta positions away from @iter
+
+
+
+
+ a #GSequenceIter
+
+
+
+ A positive or negative number indicating how many positions away
+ from @iter the returned #GSequenceIter will be
+
+
+
+
+
+ Returns an iterator pointing to the next position after @iter.
+If @iter is the end iterator, the end iterator is returned.
+
+
+ a #GSequenceIter pointing to the next position after @iter
+
+
+
+
+ a #GSequenceIter
+
+
+
+
+
+ Returns an iterator pointing to the previous position before @iter.
+If @iter is the begin iterator, the begin iterator is returned.
+
+
+ a #GSequenceIter pointing to the previous position
+ before @iter
+
+
+
+
+ a #GSequenceIter
+
+
+
+
+
+
+ A #GSequenceIterCompareFunc is a function used to compare iterators.
+It must return zero if the iterators compare equal, a negative value
+if @a comes before @b, and a positive value if @b comes before @a.
+
+
+ zero if the iterators are equal, a negative value if @a
+ comes before @b, and a positive value if @b comes before @a.
+
+
+
+
+ a #GSequenceIter
+
+
+
+ a #GSequenceIter
+
+
+
+ user data
+
+
+
+
+
+ Error codes returned by shell functions.
+
+
+ Mismatched or otherwise mangled quoting.
+
+
+ String to be parsed was empty.
+
+
+ Some other error.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The `GSource` struct is an opaque data type
+representing an event source.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Creates a new #GSource structure. The size is specified to
+allow creating structures derived from #GSource that contain
+additional data. The size passed in must be at least
+`sizeof (GSource)`.
+
+The source will not initially be associated with any #GMainContext
+and must be added to one with g_source_attach() before it will be
+executed.
+
+
+ the newly-created #GSource.
+
+
+
+
+ structure containing functions that implement
+ the sources behavior.
+
+
+
+ size of the #GSource structure to create.
+
+
+
+
+
+ Adds @child_source to @source as a "polled" source; when @source is
+added to a #GMainContext, @child_source will be automatically added
+with the same priority, when @child_source is triggered, it will
+cause @source to dispatch (in addition to calling its own
+callback), and when @source is destroyed, it will destroy
+@child_source as well. (@source will also still be dispatched if
+its own prepare/check functions indicate that it is ready.)
+
+If you don't need @child_source to do anything on its own when it
+triggers, you can call g_source_set_dummy_callback() on it to set a
+callback that does nothing (except return %TRUE if appropriate).
+
+@source will hold a reference on @child_source while @child_source
+is attached to it.
+
+This API is only intended to be used by implementations of #GSource.
+Do not call this API on a #GSource that you did not create.
+
+
+
+
+
+
+ a #GSource
+
+
+
+ a second #GSource that @source should "poll"
+
+
+
+
+
+ Adds a file descriptor to the set of file descriptors polled for
+this source. This is usually combined with g_source_new() to add an
+event source. The event source's check function will typically test
+the @revents field in the #GPollFD struct and return %TRUE if events need
+to be processed.
+
+This API is only intended to be used by implementations of #GSource.
+Do not call this API on a #GSource that you did not create.
+
+Using this API forces the linear scanning of event sources on each
+main loop iteration. Newly-written event sources should try to use
+g_source_add_unix_fd() instead of this API.
+
+
+
+
+
+
+ a #GSource
+
+
+
+ a #GPollFD structure holding information about a file
+ descriptor to watch.
+
+
+
+
+
+ Monitors @fd for the IO events in @events.
+
+The tag returned by this function can be used to remove or modify the
+monitoring of the fd using g_source_remove_unix_fd() or
+g_source_modify_unix_fd().
+
+It is not necessary to remove the fd before destroying the source; it
+will be cleaned up automatically.
+
+This API is only intended to be used by implementations of #GSource.
+Do not call this API on a #GSource that you did not create.
+
+As the name suggests, this function is not available on Windows.
+
+
+ an opaque tag
+
+
+
+
+ a #GSource
+
+
+
+ the fd to monitor
+
+
+
+ an event mask
+
+
+
+
+
+ Adds a #GSource to a @context so that it will be executed within
+that context. Remove it by calling g_source_destroy().
+
+This function is safe to call from any thread, regardless of which thread
+the @context is running in.
+
+
+ the ID (greater than 0) for the source within the
+ #GMainContext.
+
+
+
+
+ a #GSource
+
+
+
+ a #GMainContext (if %NULL, the global-default
+ main context will be used)
+
+
+
+
+
+ Removes a source from its #GMainContext, if any, and mark it as
+destroyed. The source cannot be subsequently added to another
+context. It is safe to call this on sources which have already been
+removed from their context.
+
+This does not unref the #GSource: if you still hold a reference, use
+g_source_unref() to drop it.
+
+This function is safe to call from any thread, regardless of which thread
+the #GMainContext is running in.
+
+If the source is currently attached to a #GMainContext, destroying it
+will effectively unset the callback similar to calling g_source_set_callback().
+This can mean, that the data's #GDestroyNotify gets called right away.
+
+
+
+
+
+
+ a #GSource
+
+
+
+
+
+ Checks whether a source is allowed to be called recursively.
+see g_source_set_can_recurse().
+
+
+ whether recursion is allowed.
+
+
+
+
+ a #GSource
+
+
+
+
+
+ Gets the #GMainContext with which the source is associated.
+
+You can call this on a source that has been destroyed, provided
+that the #GMainContext it was attached to still exists (in which
+case it will return that #GMainContext). In particular, you can
+always call this function on the source returned from
+g_main_current_source(). But calling this function on a source
+whose #GMainContext has been destroyed is an error.
+
+
+ the #GMainContext with which the
+ source is associated, or %NULL if the context has not
+ yet been added to a source.
+
+
+
+
+ a #GSource
+
+
+
+
+
+ This function ignores @source and is otherwise the same as
+g_get_current_time().
+ use g_source_get_time() instead
+
+
+
+
+
+
+ a #GSource
+
+
+
+ #GTimeVal structure in which to store current time.
+
+
+
+
+
+ Returns the numeric ID for a particular source. The ID of a source
+is a positive integer which is unique within a particular main loop
+context. The reverse
+mapping from ID to source is done by g_main_context_find_source_by_id().
+
+You can only call this function while the source is associated to a
+#GMainContext instance; calling this function before g_source_attach()
+or after g_source_destroy() yields undefined behavior. The ID returned
+is unique within the #GMainContext instance passed to g_source_attach().
+
+
+ the ID (greater than 0) for the source
+
+
+
+
+ a #GSource
+
+
+
+
+
+ Gets a name for the source, used in debugging and profiling. The
+name may be #NULL if it has never been set with g_source_set_name().
+
+
+ the name of the source
+
+
+
+
+ a #GSource
+
+
+
+
+
+ Gets the priority of a source.
+
+
+ the priority of the source
+
+
+
+
+ a #GSource
+
+
+
+
+
+ Gets the "ready time" of @source, as set by
+g_source_set_ready_time().
+
+Any time before the current monotonic time (including 0) is an
+indication that the source will fire immediately.
+
+
+ the monotonic ready time, -1 for "never"
+
+
+
+
+ a #GSource
+
+
+
+
+
+ Gets the time to be used when checking this source. The advantage of
+calling this function over calling g_get_monotonic_time() directly is
+that when checking multiple sources, GLib can cache a single value
+instead of having to repeatedly get the system monotonic time.
+
+The time here is the system monotonic time, if available, or some
+other reasonable alternative otherwise. See g_get_monotonic_time().
+
+
+ the monotonic time in microseconds
+
+
+
+
+ a #GSource
+
+
+
+
+
+ Returns whether @source has been destroyed.
+
+This is important when you operate upon your objects
+from within idle handlers, but may have freed the object
+before the dispatch of your idle handler.
+
+|[<!-- language="C" -->
+static gboolean
+idle_callback (gpointer data)
+{
+ SomeWidget *self = data;
+
+ g_mutex_lock (&self->idle_id_mutex);
+ // do stuff with self
+ self->idle_id = 0;
+ g_mutex_unlock (&self->idle_id_mutex);
+
+ return G_SOURCE_REMOVE;
+}
+
+static void
+some_widget_do_stuff_later (SomeWidget *self)
+{
+ g_mutex_lock (&self->idle_id_mutex);
+ self->idle_id = g_idle_add (idle_callback, self);
+ g_mutex_unlock (&self->idle_id_mutex);
+}
+
+static void
+some_widget_init (SomeWidget *self)
+{
+ g_mutex_init (&self->idle_id_mutex);
+
+ // ...
+}
+
+static void
+some_widget_finalize (GObject *object)
+{
+ SomeWidget *self = SOME_WIDGET (object);
+
+ if (self->idle_id)
+ g_source_remove (self->idle_id);
+
+ g_mutex_clear (&self->idle_id_mutex);
+
+ G_OBJECT_CLASS (parent_class)->finalize (object);
+}
+]|
+
+This will fail in a multi-threaded application if the
+widget is destroyed before the idle handler fires due
+to the use after free in the callback. A solution, to
+this particular problem, is to check to if the source
+has already been destroy within the callback.
+
+|[<!-- language="C" -->
+static gboolean
+idle_callback (gpointer data)
+{
+ SomeWidget *self = data;
+
+ g_mutex_lock (&self->idle_id_mutex);
+ if (!g_source_is_destroyed (g_main_current_source ()))
+ {
+ // do stuff with self
+ }
+ g_mutex_unlock (&self->idle_id_mutex);
+
+ return FALSE;
+}
+]|
+
+Calls to this function from a thread other than the one acquired by the
+#GMainContext the #GSource is attached to are typically redundant, as the
+source could be destroyed immediately after this function returns. However,
+once a source is destroyed it cannot be un-destroyed, so this function can be
+used for opportunistic checks from any thread.
+
+
+ %TRUE if the source has been destroyed
+
+
+
+
+ a #GSource
+
+
+
+
+
+ Updates the event mask to watch for the fd identified by @tag.
+
+@tag is the tag returned from g_source_add_unix_fd().
+
+If you want to remove a fd, don't set its event mask to zero.
+Instead, call g_source_remove_unix_fd().
+
+This API is only intended to be used by implementations of #GSource.
+Do not call this API on a #GSource that you did not create.
+
+As the name suggests, this function is not available on Windows.
+
+
+
+
+
+
+ a #GSource
+
+
+
+ the tag from g_source_add_unix_fd()
+
+
+
+ the new event mask to watch
+
+
+
+
+
+ Queries the events reported for the fd corresponding to @tag on
+@source during the last poll.
+
+The return value of this function is only defined when the function
+is called from the check or dispatch functions for @source.
+
+This API is only intended to be used by implementations of #GSource.
+Do not call this API on a #GSource that you did not create.
+
+As the name suggests, this function is not available on Windows.
+
+
+ the conditions reported on the fd
+
+
+
+
+ a #GSource
+
+
+
+ the tag from g_source_add_unix_fd()
+
+
+
+
+
+ Increases the reference count on a source by one.
+
+
+ @source
+
+
+
+
+ a #GSource
+
+
+
+
+
+ Detaches @child_source from @source and destroys it.
+
+This API is only intended to be used by implementations of #GSource.
+Do not call this API on a #GSource that you did not create.
+
+
+
+
+
+
+ a #GSource
+
+
+
+ a #GSource previously passed to
+ g_source_add_child_source().
+
+
+
+
+
+ Removes a file descriptor from the set of file descriptors polled for
+this source.
+
+This API is only intended to be used by implementations of #GSource.
+Do not call this API on a #GSource that you did not create.
+
+
+
+
+
+
+ a #GSource
+
+
+
+ a #GPollFD structure previously passed to g_source_add_poll().
+
+
+
+
+
+ Reverses the effect of a previous call to g_source_add_unix_fd().
+
+You only need to call this if you want to remove an fd from being
+watched while keeping the same source around. In the normal case you
+will just want to destroy the source.
+
+This API is only intended to be used by implementations of #GSource.
+Do not call this API on a #GSource that you did not create.
+
+As the name suggests, this function is not available on Windows.
+
+
+
+
+
+
+ a #GSource
+
+
+
+ the tag from g_source_add_unix_fd()
+
+
+
+
+
+ Sets the callback function for a source. The callback for a source is
+called from the source's dispatch function.
+
+The exact type of @func depends on the type of source; ie. you
+should not count on @func being called with @data as its first
+parameter. Cast @func with G_SOURCE_FUNC() to avoid warnings about
+incompatible function types.
+
+See [memory management of sources][mainloop-memory-management] for details
+on how to handle memory management of @data.
+
+Typically, you won't use this function. Instead use functions specific
+to the type of source you are using, such as g_idle_add() or g_timeout_add().
+
+It is safe to call this function multiple times on a source which has already
+been attached to a context. The changes will take effect for the next time
+the source is dispatched after this call returns.
+
+Note that g_source_destroy() for a currently attached source has the effect
+of also unsetting the callback.
+
+
+
+
+
+
+ the source
+
+
+
+ a callback function
+
+
+
+ the data to pass to callback function
+
+
+
+ a function to call when @data is no longer in use, or %NULL.
+
+
+
+
+
+ Sets the callback function storing the data as a refcounted callback
+"object". This is used internally. Note that calling
+g_source_set_callback_indirect() assumes
+an initial reference count on @callback_data, and thus
+@callback_funcs->unref will eventually be called once more
+than @callback_funcs->ref.
+
+It is safe to call this function multiple times on a source which has already
+been attached to a context. The changes will take effect for the next time
+the source is dispatched after this call returns.
+
+
+
+
+
+
+ the source
+
+
+
+ pointer to callback data "object"
+
+
+
+ functions for reference counting @callback_data
+ and getting the callback and data
+
+
+
+
+
+ Sets whether a source can be called recursively. If @can_recurse is
+%TRUE, then while the source is being dispatched then this source
+will be processed normally. Otherwise, all processing of this
+source is blocked until the dispatch function returns.
+
+
+
+
+
+
+ a #GSource
+
+
+
+ whether recursion is allowed for this source
+
+
+
+
+
+ Set @dispose as dispose function on @source. @dispose will be called once
+the reference count of @source reaches 0 but before any of the state of the
+source is freed, especially before the finalize function is called.
+
+This means that at this point @source is still a valid #GSource and it is
+allow for the reference count to increase again until @dispose returns.
+
+The dispose function can be used to clear any "weak" references to the
+@source in other data structures in a thread-safe way where it is possible
+for another thread to increase the reference count of @source again while
+it is being freed.
+
+The finalize function can not be used for this purpose as at that point
+@source is already partially freed and not valid anymore.
+
+This should only ever be called from #GSource implementations.
+
+
+
+
+
+
+ A #GSource to set the dispose function on
+
+
+
+ #GSourceDisposeFunc to set on the source
+
+
+
+
+
+ Sets the source functions (can be used to override
+default implementations) of an unattached source.
+
+
+
+
+
+
+ a #GSource
+
+
+
+ the new #GSourceFuncs
+
+
+
+
+
+ Sets a name for the source, used in debugging and profiling.
+The name defaults to #NULL.
+
+The source name should describe in a human-readable way
+what the source does. For example, "X11 event queue"
+or "GTK+ repaint idle handler" or whatever it is.
+
+It is permitted to call this function multiple times, but is not
+recommended due to the potential performance impact. For example,
+one could change the name in the "check" function of a #GSourceFuncs
+to include details like the event type in the source name.
+
+Use caution if changing the name while another thread may be
+accessing it with g_source_get_name(); that function does not copy
+the value, and changing the value will free it while the other thread
+may be attempting to use it.
+
+Also see g_source_set_static_name().
+
+
+
+
+
+
+ a #GSource
+
+
+
+ debug name for the source
+
+
+
+
+
+ Sets the priority of a source. While the main loop is being run, a
+source will be dispatched if it is ready to be dispatched and no
+sources at a higher (numerically smaller) priority are ready to be
+dispatched.
+
+A child source always has the same priority as its parent. It is not
+permitted to change the priority of a source once it has been added
+as a child of another source.
+
+
+
+
+
+
+ a #GSource
+
+
+
+ the new priority.
+
+
+
+
+
+ Sets a #GSource to be dispatched when the given monotonic time is
+reached (or passed). If the monotonic time is in the past (as it
+always will be if @ready_time is 0) then the source will be
+dispatched immediately.
+
+If @ready_time is -1 then the source is never woken up on the basis
+of the passage of time.
+
+Dispatching the source does not reset the ready time. You should do
+so yourself, from the source dispatch function.
+
+Note that if you have a pair of sources where the ready time of one
+suggests that it will be delivered first but the priority for the
+other suggests that it would be delivered first, and the ready time
+for both sources is reached during the same main context iteration,
+then the order of dispatch is undefined.
+
+It is a no-op to call this function on a #GSource which has already been
+destroyed with g_source_destroy().
+
+This API is only intended to be used by implementations of #GSource.
+Do not call this API on a #GSource that you did not create.
+
+
+
+
+
+
+ a #GSource
+
+
+
+ the monotonic time at which the source will be ready,
+ 0 for "immediately", -1 for "never"
+
+
+
+
+
+ A variant of g_source_set_name() that does not
+duplicate the @name, and can only be used with
+string literals.
+
+
+
+
+
+
+ a #GSource
+
+
+
+ debug name for the source
+
+
+
+
+
+ Decreases the reference count of a source by one. If the
+resulting reference count is zero the source and associated
+memory will be destroyed.
+
+
+
+
+
+
+ a #GSource
+
+
+
+
+
+ Removes the source with the given ID from the default main context. You must
+use g_source_destroy() for sources added to a non-default main context.
+
+The ID of a #GSource is given by g_source_get_id(), or will be
+returned by the functions g_source_attach(), g_idle_add(),
+g_idle_add_full(), g_timeout_add(), g_timeout_add_full(),
+g_child_watch_add(), g_child_watch_add_full(), g_io_add_watch(), and
+g_io_add_watch_full().
+
+It is a programmer error to attempt to remove a non-existent source.
+
+More specifically: source IDs can be reissued after a source has been
+destroyed and therefore it is never valid to use this function with a
+source ID which may have already been removed. An example is when
+scheduling an idle to run in another thread with g_idle_add(): the
+idle may already have run and been removed by the time this function
+is called on its (now invalid) source ID. This source ID may have
+been reissued, leading to the operation being performed against the
+wrong source.
+
+
+ %TRUE if the source was found and removed.
+
+
+
+
+ the ID of the source to remove.
+
+
+
+
+
+ Removes a source from the default main loop context given the
+source functions and user data. If multiple sources exist with the
+same source functions and user data, only one will be destroyed.
+
+
+ %TRUE if a source was found and removed.
+
+
+
+
+ The @source_funcs passed to g_source_new()
+
+
+
+ the user data for the callback
+
+
+
+
+
+ Removes a source from the default main loop context given the user
+data for the callback. If multiple sources exist with the same user
+data, only one will be destroyed.
+
+
+ %TRUE if a source was found and removed.
+
+
+
+
+ the user_data for the callback.
+
+
+
+
+
+ Sets the name of a source using its ID.
+
+This is a convenience utility to set source names from the return
+value of g_idle_add(), g_timeout_add(), etc.
+
+It is a programmer error to attempt to set the name of a non-existent
+source.
+
+More specifically: source IDs can be reissued after a source has been
+destroyed and therefore it is never valid to use this function with a
+source ID which may have already been removed. An example is when
+scheduling an idle to run in another thread with g_idle_add(): the
+idle may already have run and been removed by the time this function
+is called on its (now invalid) source ID. This source ID may have
+been reissued, leading to the operation being performed against the
+wrong source.
+
+
+
+
+
+
+ a #GSource ID
+
+
+
+ debug name for the source
+
+
+
+
+
+
+ The `GSourceCallbackFuncs` struct contains
+functions for managing callback objects.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Dispose function for @source. See g_source_set_dispose_function() for
+details.
+
+
+
+
+
+
+ #GSource that is currently being disposed
+
+
+
+
+
+ This is just a placeholder for #GClosureMarshal,
+which cannot be used here for dependency reasons.
+
+
+
+
+
+
+ Specifies the type of function passed to g_timeout_add(),
+g_timeout_add_full(), g_idle_add(), and g_idle_add_full().
+
+When calling g_source_set_callback(), you may need to cast a function of a
+different type to this type. Use G_SOURCE_FUNC() to avoid warnings about
+incompatible function types.
+
+
+ %FALSE if the source should be removed. %G_SOURCE_CONTINUE and
+%G_SOURCE_REMOVE are more memorable names for the return value.
+
+
+
+
+ data passed to the function, set when the source was
+ created with one of the above functions
+
+
+
+
+
+ The `GSourceFuncs` 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ A source function that is only called once before being removed from the main
+context automatically.
+
+See: g_idle_add_once(), g_timeout_add_once()
+
+
+
+
+
+
+ data passed to the function, set when the source was
+ created
+
+
+
+
+
+
+
+
+ Specifies the type of the setup function passed to g_spawn_async(),
+g_spawn_sync() and g_spawn_async_with_pipes(), which can, in very
+limited ways, be used to affect the child's execution.
+
+On POSIX platforms, the function is called in the child after GLib
+has performed all the setup it plans to perform, but before calling
+exec(). Actions taken in this function will only affect the child,
+not the parent.
+
+On Windows, the function is called in the parent. Its usefulness on
+Windows is thus questionable. In many cases executing the child setup
+function in the parent can have ill effects, and you should be very
+careful when porting software to Windows that uses child setup
+functions.
+
+However, even on POSIX, you are extremely limited in what you can
+safely do from a #GSpawnChildSetupFunc, because any mutexes that were
+held by other threads in the parent process at the time of the fork()
+will still be locked in the child process, and they will never be
+unlocked (since the threads that held them don't exist in the child).
+POSIX allows only async-signal-safe functions (see signal(7)) to be
+called in the child between fork() and exec(), which drastically limits
+the usefulness of child setup functions.
+
+In particular, it is not safe to call any function which may
+call malloc(), which includes POSIX functions such as setenv().
+If you need to set up the child environment differently from
+the parent, you should use g_get_environ(), g_environ_setenv(),
+and g_environ_unsetenv(), and then pass the complete environment
+list to the `g_spawn...` function.
+
+
+
+
+
+
+ user data passed to the function.
+
+
+
+
+
+ Error codes returned by spawning processes.
+
+
+ Fork failed due to lack of memory.
+
+
+ Read or select on pipes failed.
+
+
+ Changing to working directory failed.
+
+
+ execv() returned `EACCES`
+
+
+ execv() returned `EPERM`
+
+
+ execv() returned `E2BIG`
+
+
+ deprecated alias for %G_SPAWN_ERROR_TOO_BIG (deprecated since GLib 2.32)
+
+
+ execv() returned `ENOEXEC`
+
+
+ execv() returned `ENAMETOOLONG`
+
+
+ execv() returned `ENOENT`
+
+
+ execv() returned `ENOMEM`
+
+
+ execv() returned `ENOTDIR`
+
+
+ execv() returned `ELOOP`
+
+
+ execv() returned `ETXTBUSY`
+
+
+ execv() returned `EIO`
+
+
+ execv() returned `ENFILE`
+
+
+ execv() returned `EMFILE`
+
+
+ execv() returned `EINVAL`
+
+
+ execv() returned `EISDIR`
+
+
+ execv() returned `ELIBBAD`
+
+
+ Some other fatal failure,
+ `error->message` should explain.
+
+
+
+ Flags passed to g_spawn_sync(), g_spawn_async() and g_spawn_async_with_pipes().
+
+
+ no flags, default behaviour
+
+
+ the parent's open file descriptors will
+ be inherited by the child; otherwise all descriptors except stdin,
+ stdout and stderr will be closed before calling exec() in the child.
+
+
+ the child will not be automatically reaped;
+ you must use g_child_watch_add() yourself (or call waitpid() or handle
+ `SIGCHLD` yourself), or the child will become a zombie.
+
+
+ `argv[0]` need not be an absolute path, it will be
+ looked for in the user's `PATH`.
+
+
+ the child's standard output will be discarded,
+ instead of going to the same location as the parent's standard output.
+
+
+ the child's standard error will be discarded.
+
+
+ the child will inherit the parent's standard
+ input (by default, the child's standard input is attached to `/dev/null`).
+
+
+ the first element of `argv` is the file to
+ execute, while the remaining elements are the actual argument vector
+ to pass to the file. Normally g_spawn_async_with_pipes() uses `argv[0]`
+ as the file to execute, and passes all of `argv` to the child.
+
+
+ if `argv[0]` is not an absolute path,
+ it will be looked for in the `PATH` from the passed child environment.
+ Since: 2.34
+
+
+ create all pipes with the `O_CLOEXEC` flag set.
+ Since: 2.40
+
+
+ The child will inherit the parent's standard output.
+
+
+ The child will inherit the parent's standard error.
+
+
+ The child's standard input is attached to `/dev/null`.
+
+
+
+ A type corresponding to the appropriate struct type for the stat()
+system call, depending on the platform and/or compiler being used.
+
+See g_stat() for more information.
+
+
+
+ The GString struct contains the public fields of a GString.
+
+
+ points to the character data. It may move as text is added.
+ The @str field is null-terminated and so
+ can be used as an ordinary C string.
+
+
+
+ contains the length of the string, not including the
+ terminating nul byte.
+
+
+
+ the number of bytes that can be stored in the
+ string before it needs to be reallocated. May be larger than @len.
+
+
+
+ Creates a new #GString, initialized with the given string.
+
+
+ the new #GString
+
+
+
+
+ the initial text to copy into the string, or %NULL to
+ start with an empty string
+
+
+
+
+
+ Creates a new #GString with @len bytes of the @init buffer.
+Because a length is provided, @init need not be nul-terminated,
+and can contain embedded nul bytes.
+
+Since this function does not stop at nul bytes, it is the caller's
+responsibility to ensure that @init has at least @len addressable
+bytes.
+
+
+ a new #GString
+
+
+
+
+ initial contents of the string
+
+
+
+ length of @init to use
+
+
+
+
+
+ Creates a new #GString, with enough space for @dfl_size
+bytes. This is useful if you are going to add a lot of
+text to the string and don't want it to be reallocated
+too often.
+
+
+ the new #GString
+
+
+
+
+ the default size of the space allocated to hold the string
+
+
+
+
+
+ Adds a string onto the end of a #GString, expanding
+it if necessary.
+
+
+ @string
+
+
+
+
+ a #GString
+
+
+
+ the string to append onto the end of @string
+
+
+
+
+
+ Adds a byte onto the end of a #GString, expanding
+it if necessary.
+
+
+ @string
+
+
+
+
+ a #GString
+
+
+
+ the byte to append onto the end of @string
+
+
+
+
+
+ Appends @len bytes of @val to @string.
+
+If @len is positive, @val may contain embedded nuls and need
+not be nul-terminated. It is the caller's responsibility to
+ensure that @val has at least @len addressable bytes.
+
+If @len is negative, @val must be nul-terminated and @len
+is considered to request the entire string length. This
+makes g_string_append_len() equivalent to g_string_append().
+
+
+ @string
+
+
+
+
+ a #GString
+
+
+
+ bytes to append
+
+
+
+ number of bytes of @val to use, or -1 for all of @val
+
+
+
+
+
+ Appends a formatted string onto the end of a #GString.
+This function is similar to g_string_printf() except
+that the text is appended to the #GString.
+
+
+
+
+
+
+ a #GString
+
+
+
+ the string format. See the printf() documentation
+
+
+
+ the parameters to insert into the format string
+
+
+
+
+
+ Converts a Unicode character into UTF-8, and appends it
+to the string.
+
+
+ @string
+
+
+
+
+ a #GString
+
+
+
+ a Unicode character
+
+
+
+
+
+ Appends @unescaped to @string, escaping any characters that
+are reserved in URIs using URI-style escape sequences.
+
+
+ @string
+
+
+
+
+ a #GString
+
+
+
+ a string
+
+
+
+ a string of reserved characters allowed
+ to be used, or %NULL
+
+
+
+ set %TRUE if the escaped string may include UTF8 characters
+
+
+
+
+
+ Appends a formatted string onto the end of a #GString.
+This function is similar to g_string_append_printf()
+except that the arguments to the format string are passed
+as a va_list.
+
+
+
+
+
+
+ a #GString
+
+
+
+ the string format. See the printf() documentation
+
+
+
+ the list of arguments to insert in the output
+
+
+
+
+
+ Converts all uppercase ASCII letters to lowercase ASCII letters.
+
+
+ passed-in @string pointer, with all the
+ uppercase characters converted to lowercase in place,
+ with semantics that exactly match g_ascii_tolower().
+
+
+
+
+ a GString
+
+
+
+
+
+ Converts all lowercase ASCII letters to uppercase ASCII letters.
+
+
+ passed-in @string pointer, with all the
+ lowercase characters converted to uppercase in place,
+ with semantics that exactly match g_ascii_toupper().
+
+
+
+
+ a GString
+
+
+
+
+
+ Copies the bytes from a string into a #GString,
+destroying any previous contents. It is rather like
+the standard strcpy() function, except that you do not
+have to worry about having enough space to copy the string.
+
+
+ @string
+
+
+
+
+ the destination #GString. Its current contents
+ are destroyed.
+
+
+
+ the string to copy into @string
+
+
+
+
+
+ Converts a #GString to lowercase.
+ This function uses the locale-specific
+ tolower() function, which is almost never the right thing.
+ Use g_string_ascii_down() or g_utf8_strdown() instead.
+
+
+ the #GString
+
+
+
+
+ a #GString
+
+
+
+
+
+ Compares two strings for equality, returning %TRUE if they are equal.
+For use with #GHashTable.
+
+
+ %TRUE if the strings are the same length and contain the
+ same bytes
+
+
+
+
+ a #GString
+
+
+
+ another #GString
+
+
+
+
+
+ Removes @len bytes from a #GString, starting at position @pos.
+The rest of the #GString is shifted down to fill the gap.
+
+
+ @string
+
+
+
+
+ a #GString
+
+
+
+ the position of the content to remove
+
+
+
+ the number of bytes to remove, or -1 to remove all
+ following bytes
+
+
+
+
+
+ Frees the memory allocated for the #GString.
+If @free_segment is %TRUE it also frees the character data. If
+it's %FALSE, the caller gains ownership of the buffer and must
+free it after use with g_free().
+
+Instead of passing %FALSE to this function, consider using
+g_string_free_and_steal().
+
+
+ the character data of @string
+ (i.e. %NULL if @free_segment is %TRUE)
+
+
+
+
+ a #GString
+
+
+
+ if %TRUE, the actual character data is freed as well
+
+
+
+
+
+ Frees the memory allocated for the #GString.
+
+The caller gains ownership of the buffer and
+must free it after use with g_free().
+
+
+ the character data of @string
+
+
+
+
+ a #GString
+
+
+
+
+
+ Transfers ownership of the contents of @string to a newly allocated
+#GBytes. The #GString structure itself is deallocated, and it is
+therefore invalid to use @string after invoking this function.
+
+Note that while #GString ensures that its buffer always has a
+trailing nul character (not reflected in its "len"), the returned
+#GBytes does not include this extra nul; i.e. it has length exactly
+equal to the "len" member.
+
+
+ A newly allocated #GBytes containing contents of @string; @string itself is freed
+
+
+
+
+ a #GString
+
+
+
+
+
+ Creates a hash code for @str; for use with #GHashTable.
+
+
+ hash code for @str
+
+
+
+
+ a string to hash
+
+
+
+
+
+ Inserts a copy of a string into a #GString,
+expanding it if necessary.
+
+
+ @string
+
+
+
+
+ a #GString
+
+
+
+ the position to insert the copy of the string
+
+
+
+ the string to insert
+
+
+
+
+
+ Inserts a byte into a #GString, expanding it if necessary.
+
+
+ @string
+
+
+
+
+ a #GString
+
+
+
+ the position to insert the byte
+
+
+
+ the byte to insert
+
+
+
+
+
+ Inserts @len bytes of @val into @string at @pos.
+
+If @len is positive, @val may contain embedded nuls and need
+not be nul-terminated. It is the caller's responsibility to
+ensure that @val has at least @len addressable bytes.
+
+If @len is negative, @val must be nul-terminated and @len
+is considered to request the entire string length.
+
+If @pos is -1, bytes are inserted at the end of the string.
+
+
+ @string
+
+
+
+
+ a #GString
+
+
+
+ position in @string where insertion should
+ happen, or -1 for at the end
+
+
+
+ bytes to insert
+
+
+
+ number of bytes of @val to insert, or -1 for all of @val
+
+
+
+
+
+ Converts a Unicode character into UTF-8, and insert it
+into the string at the given position.
+
+
+ @string
+
+
+
+
+ a #GString
+
+
+
+ the position at which to insert character, or -1
+ to append at the end of the string
+
+
+
+ a Unicode character
+
+
+
+
+
+ Overwrites part of a string, lengthening it if necessary.
+
+
+ @string
+
+
+
+
+ a #GString
+
+
+
+ the position at which to start overwriting
+
+
+
+ the string that will overwrite the @string starting at @pos
+
+
+
+
+
+ Overwrites part of a string, lengthening it if necessary.
+This function will work with embedded nuls.
+
+
+ @string
+
+
+
+
+ a #GString
+
+
+
+ the position at which to start overwriting
+
+
+
+ the string that will overwrite the @string starting at @pos
+
+
+
+ the number of bytes to write from @val
+
+
+
+
+
+ Adds a string on to the start of a #GString,
+expanding it if necessary.
+
+
+ @string
+
+
+
+
+ a #GString
+
+
+
+ the string to prepend on the start of @string
+
+
+
+
+
+ Adds a byte onto the start of a #GString,
+expanding it if necessary.
+
+
+ @string
+
+
+
+
+ a #GString
+
+
+
+ the byte to prepend on the start of the #GString
+
+
+
+
+
+ Prepends @len bytes of @val to @string.
+
+If @len is positive, @val may contain embedded nuls and need
+not be nul-terminated. It is the caller's responsibility to
+ensure that @val has at least @len addressable bytes.
+
+If @len is negative, @val must be nul-terminated and @len
+is considered to request the entire string length. This
+makes g_string_prepend_len() equivalent to g_string_prepend().
+
+
+ @string
+
+
+
+
+ a #GString
+
+
+
+ bytes to prepend
+
+
+
+ number of bytes in @val to prepend, or -1 for all of @val
+
+
+
+
+
+ Converts a Unicode character into UTF-8, and prepends it
+to the string.
+
+
+ @string
+
+
+
+
+ a #GString
+
+
+
+ a Unicode character
+
+
+
+
+
+ Writes a formatted string into a #GString.
+This is similar to the standard sprintf() function,
+except that the #GString buffer automatically expands
+to contain the results. The previous contents of the
+#GString are destroyed.
+
+
+
+
+
+
+ a #GString
+
+
+
+ the string format. See the printf() documentation
+
+
+
+ the parameters to insert into the format string
+
+
+
+
+
+ Replaces the string @find with the string @replace in a #GString up to
+@limit times. If the number of instances of @find in the #GString is
+less than @limit, all instances are replaced. If @limit is `0`,
+all instances of @find are replaced.
+
+If @find is the empty string, since versions 2.69.1 and 2.68.4 the
+replacement will be inserted no more than once per possible position
+(beginning of string, end of string and between characters). This did
+not work correctly in earlier versions.
+
+
+ the number of find and replace operations performed.
+
+
+
+
+ a #GString
+
+
+
+ the string to find in @string
+
+
+
+ the string to insert in place of @find
+
+
+
+ the maximum instances of @find to replace with @replace, or `0` for
+no limit
+
+
+
+
+
+ Sets the length of a #GString. If the length is less than
+the current length, the string will be truncated. If the
+length is greater than the current length, the contents
+of the newly added area are undefined. (However, as
+always, string->str[string->len] will be a nul byte.)
+
+
+ @string
+
+
+
+
+ a #GString
+
+
+
+ the new length
+
+
+
+
+
+ Cuts off the end of the GString, leaving the first @len bytes.
+
+
+ @string
+
+
+
+
+ a #GString
+
+
+
+ the new size of @string
+
+
+
+
+
+ Converts a #GString to uppercase.
+ This function uses the locale-specific
+ toupper() function, which is almost never the right thing.
+ Use g_string_ascii_up() or g_utf8_strup() instead.
+
+
+ @string
+
+
+
+
+ a #GString
+
+
+
+
+
+ Writes a formatted string into a #GString.
+This function is similar to g_string_printf() except that
+the arguments to the format string are passed as a va_list.
+
+
+
+
+
+
+ a #GString
+
+
+
+ the string format. See the printf() documentation
+
+
+
+ the parameters to insert into the format string
+
+
+
+
+
+
+ An opaque data structure representing String Chunks.
+It should only be accessed by using the following functions.
+
+
+ Frees all strings contained within the #GStringChunk.
+After calling g_string_chunk_clear() it is not safe to
+access any of the strings which were contained within it.
+
+
+
+
+
+
+ a #GStringChunk
+
+
+
+
+
+ Frees all memory allocated by the #GStringChunk.
+After calling g_string_chunk_free() it is not safe to
+access any of the strings which were contained within it.
+
+
+
+
+
+
+ a #GStringChunk
+
+
+
+
+
+ Adds a copy of @string to the #GStringChunk.
+It returns a pointer to the new copy of the string
+in the #GStringChunk. The characters in the string
+can be changed, if necessary, though you should not
+change anything after the end of the string.
+
+Unlike g_string_chunk_insert_const(), this function
+does not check for duplicates. Also strings added
+with g_string_chunk_insert() will not be searched
+by g_string_chunk_insert_const() when looking for
+duplicates.
+
+
+ a pointer to the copy of @string within
+ the #GStringChunk
+
+
+
+
+ a #GStringChunk
+
+
+
+ the string to add
+
+
+
+
+
+ Adds a copy of @string to the #GStringChunk, unless the same
+string has already been added to the #GStringChunk with
+g_string_chunk_insert_const().
+
+This function is useful if you need to copy a large number
+of strings but do not want to waste space storing duplicates.
+But you must remember that there may be several pointers to
+the same string, and so any changes made to the strings
+should be done very carefully.
+
+Note that g_string_chunk_insert_const() will not return a
+pointer to a string added with g_string_chunk_insert(), even
+if they do match.
+
+
+ a pointer to the new or existing copy of @string
+ within the #GStringChunk
+
+
+
+
+ a #GStringChunk
+
+
+
+ the string to add
+
+
+
+
+
+ Adds a copy of the first @len bytes of @string to the #GStringChunk.
+The copy is nul-terminated.
+
+Since this function does not stop at nul bytes, it is the caller's
+responsibility to ensure that @string has at least @len addressable
+bytes.
+
+The characters in the returned string can be changed, if necessary,
+though you should not change anything after the end of the string.
+
+
+ a pointer to the copy of @string within the #GStringChunk
+
+
+
+
+ a #GStringChunk
+
+
+
+ bytes to insert
+
+
+
+ number of bytes of @string to insert, or -1 to insert a
+ nul-terminated string
+
+
+
+
+
+ Creates a new #GStringChunk.
+
+
+ a new #GStringChunk
+
+
+
+
+ the default size of the blocks of memory which are
+ allocated to store the strings. If a particular string
+ is larger than this default size, a larger block of
+ memory will be allocated for it.
+
+
+
+
+
+
+ #GStrvBuilder is a method of easily building dynamically sized
+NULL-terminated string arrays.
+
+The following example shows how to build a two element array:
+
+|[<!-- language="C" -->
+ g_autoptr(GStrvBuilder) builder = g_strv_builder_new ();
+ g_strv_builder_add (builder, "hello");
+ g_strv_builder_add (builder, "world");
+ g_auto(GStrv) array = g_strv_builder_end (builder);
+]|
+
+
+ Add a string to the end of the array.
+
+Since 2.68
+
+
+
+
+
+
+ a #GStrvBuilder
+
+
+
+ a string.
+
+
+
+
+
+ Appends all the given strings to the builder.
+
+Since 2.70
+
+
+
+
+
+
+ a #GStrvBuilder
+
+
+
+ one or more strings followed by %NULL
+
+
+
+
+
+ Appends all the strings in the given vector to the builder.
+
+Since 2.70
+
+
+
+
+
+
+ a #GStrvBuilder
+
+
+
+ the vector of strings to add
+
+
+
+
+
+
+
+ Ends the builder process and returns the constructed NULL-terminated string
+array. The returned value should be freed with g_strfreev() when no longer
+needed.
+
+
+ the constructed string array.
+
+Since 2.68
+
+
+
+
+
+
+ a #GStrvBuilder
+
+
+
+
+
+ Atomically increments the reference count of @builder by one.
+This function is thread-safe and may be called from any thread.
+
+
+ The passed in #GStrvBuilder
+
+
+
+
+ a #GStrvBuilder
+
+
+
+
+
+ Decreases the reference count on @builder.
+
+In the event that there are no more references, releases all memory
+associated with the #GStrvBuilder.
+
+
+
+
+
+
+ a #GStrvBuilder allocated by g_strv_builder_new()
+
+
+
+
+
+ Creates a new #GStrvBuilder with a reference count of 1.
+Use g_strv_builder_unref() on the returned value when no longer needed.
+
+
+ the new #GStrvBuilder
+
+
+
+
+
+ Creates a unique temporary directory for each unit test and uses
+g_set_user_dirs() to set XDG directories to point into subdirectories of it
+for the duration of the unit test. The directory tree is cleaned up after the
+test finishes successfully. Note that this doesn’t take effect until
+g_test_run() is called, so calls to (for example) g_get_user_home_dir() will
+return the system-wide value when made in a test program’s main() function.
+
+The following functions will return subdirectories of the temporary directory
+when this option is used. The specific subdirectory paths in use are not
+guaranteed to be stable API — always use a getter function to retrieve them.
+
+ - g_get_home_dir()
+ - g_get_user_cache_dir()
+ - g_get_system_config_dirs()
+ - g_get_user_config_dir()
+ - g_get_system_data_dirs()
+ - g_get_user_data_dir()
+ - g_get_user_state_dir()
+ - g_get_user_runtime_dir()
+
+The subdirectories may not be created by the test harness; as with normal
+calls to functions like g_get_user_cache_dir(), the caller must be prepared
+to create the directory if it doesn’t exist.
+
+
+
+
+ Evaluates to a time span of one day.
+
+
+
+
+ Evaluates to a time span of one hour.
+
+
+
+
+ Evaluates to a time span of one millisecond.
+
+
+
+
+ Evaluates to a time span of one minute.
+
+
+
+
+ Evaluates to a time span of one second.
+
+
+
+
+ Works like g_mutex_trylock(), but for a lock defined with
+%G_LOCK_DEFINE.
+
+
+
+ the name of the lock
+
+
+
+
+ An opaque structure representing a test case.
+
+
+ Free the @test_case.
+
+
+
+
+
+
+ a #GTestCase
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The type used for test case functions that take an extra pointer
+argument.
+
+
+
+
+
+
+ the data provided when registering the test
+
+
+
+
+
+ The type of file to return the filename for, when used with
+g_test_build_filename().
+
+These two options correspond rather directly to the 'dist' and
+'built' terminology that automake uses and are explicitly used to
+distinguish between the 'srcdir' and 'builddir' being separate. All
+files in your project should either be dist (in the
+`EXTRA_DIST` or `dist_schema_DATA`
+sense, in which case they will always be in the srcdir) or built (in
+the `BUILT_SOURCES` sense, in which case they will
+always be in the builddir).
+
+Note: as a general rule of automake, files that are generated only as
+part of the build-from-git process (but then are distributed with the
+tarball) always go in srcdir (even if doing a srcdir != builddir
+build from git) and are considered as distributed files.
+
+
+ a file that was included in the distribution tarball
+
+
+ a file that was built on the compiling machine
+
+
+
+ The type used for functions that operate on test fixtures. This is
+used for the fixture setup and teardown functions as well as for the
+testcases themselves.
+
+@user_data is a pointer to the data that was given when registering
+the test case.
+
+@fixture will be a pointer to the area of memory allocated by the
+test framework, of the size requested. If the requested size was
+zero then @fixture will be equal to @user_data.
+
+
+
+
+
+
+ the test fixture
+
+
+
+ the data provided when registering the test
+
+
+
+
+
+ The type used for test case functions.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Internal function for gtester to free test log messages, no ABI guarantees provided.
+
+
+
+
+
+
+
+
+
+
+
+ Internal function for gtester to retrieve test log messages, no ABI guarantees provided.
+
+
+
+
+
+
+
+
+
+
+
+ Internal function for gtester to decode test log messages, no ABI guarantees provided.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Internal function for gtester to decode test log messages, no ABI guarantees provided.
+
+
+
+
+
+
+
+ Specifies the prototype of fatal log handler functions.
+
+
+ %TRUE if the program should abort, %FALSE otherwise
+
+
+
+
+ the log domain of the message
+
+
+
+ the log level of the message (including the fatal and recursion flags)
+
+
+
+ the message to process
+
+
+
+ user data, set in g_test_log_set_fatal_handler()
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Internal function for gtester to free test log messages, no ABI guarantees provided.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Flags to pass to g_test_trap_subprocess() to control input and output.
+
+Note that in contrast with g_test_trap_fork(), the default is to
+not show stdout and stderr.
+
+
+ Default behaviour. Since: 2.74
+
+
+ If this flag is given, the child
+ process will inherit the parent's stdin. Otherwise, the child's
+ stdin is redirected to `/dev/null`.
+
+
+ If this flag is given, the child
+ process will inherit the parent's stdout. Otherwise, the child's
+ stdout will not be visible, but it will be captured to allow
+ later tests with g_test_trap_assert_stdout().
+
+
+ If this flag is given, the child
+ process will inherit the parent's stderr. Otherwise, the child's
+ stderr will not be visible, but it will be captured to allow
+ later tests with g_test_trap_assert_stderr().
+
+
+
+ An opaque structure representing a test suite.
+
+
+ Adds @test_case to @suite.
+
+
+
+
+
+
+ a #GTestSuite
+
+
+
+ a #GTestCase
+
+
+
+
+
+ Adds @nestedsuite to @suite.
+
+
+
+
+
+
+ a #GTestSuite
+
+
+
+ another #GTestSuite
+
+
+
+
+
+ Free the @suite and all nested #GTestSuites.
+
+
+
+
+
+
+ a #GTestSuite
+
+
+
+
+
+
+ Test traps are guards around forked tests.
+These flags determine what traps to set.
+ #GTestTrapFlags is used only with g_test_trap_fork(),
+which is deprecated. g_test_trap_subprocess() uses
+#GTestSubprocessFlags.
+
+
+ Default behaviour. Since: 2.74
+
+
+ Redirect stdout of the test child to
+ `/dev/null` so it cannot be observed on the console during test
+ runs. The actual output is still captured though to allow later
+ tests with g_test_trap_assert_stdout().
+
+
+ Redirect stderr of the test child to
+ `/dev/null` so it cannot be observed on the console during test
+ runs. The actual output is still captured though to allow later
+ tests with g_test_trap_assert_stderr().
+
+
+ If this flag is given, stdin of the
+ child process is shared with stdin of its parent process.
+ It is redirected to `/dev/null` otherwise.
+
+
+
+ The #GThread struct represents a running thread. This struct
+is returned by g_thread_new() or g_thread_try_new(). You can
+obtain the #GThread struct representing the current thread by
+calling g_thread_self().
+
+GThread is refcounted, see g_thread_ref() and g_thread_unref().
+The thread represented by it holds a reference while it is running,
+and g_thread_join() consumes the reference that it is given, so
+it is normally not necessary to manage GThread references
+explicitly.
+
+The structure is opaque -- none of its fields may be directly
+accessed.
+
+
+ This function creates a new thread. The new thread starts by invoking
+@func with the argument data. The thread will run until @func returns
+or until g_thread_exit() is called from the new thread. The return value
+of @func becomes the return value of the thread, which can be obtained
+with g_thread_join().
+
+The @name can be useful for discriminating threads in a debugger.
+It is not used for other purposes and does not have to be unique.
+Some systems restrict the length of @name to 16 bytes.
+
+If the thread can not be created the program aborts. See
+g_thread_try_new() if you want to attempt to deal with failures.
+
+If you are using threads to offload (potentially many) short-lived tasks,
+#GThreadPool may be more appropriate than manually spawning and tracking
+multiple #GThreads.
+
+To free the struct returned by this function, use g_thread_unref().
+Note that g_thread_join() implicitly unrefs the #GThread as well.
+
+New threads by default inherit their scheduler policy (POSIX) or thread
+priority (Windows) of the thread creating the new thread.
+
+This behaviour changed in GLib 2.64: before threads on Windows were not
+inheriting the thread priority but were spawned with the default priority.
+Starting with GLib 2.64 the behaviour is now consistent between Windows and
+POSIX and all threads inherit their parent thread's priority.
+
+
+ the new #GThread
+
+
+
+
+ an (optional) name for the new thread
+
+
+
+ a function to execute in the new thread
+
+
+
+ an argument to supply to the new thread
+
+
+
+
+
+ This function is the same as g_thread_new() except that
+it allows for the possibility of failure.
+
+If a thread can not be created (due to resource limits),
+@error is set and %NULL is returned.
+
+
+ the new #GThread, or %NULL if an error occurred
+
+
+
+
+ an (optional) name for the new thread
+
+
+
+ a function to execute in the new thread
+
+
+
+ an argument to supply to the new thread
+
+
+
+
+
+ Waits until @thread finishes, i.e. the function @func, as
+given to g_thread_new(), returns or g_thread_exit() is called.
+If @thread has already terminated, then g_thread_join()
+returns immediately.
+
+Any thread can wait for any other thread by calling g_thread_join(),
+not just its 'creator'. Calling g_thread_join() from multiple threads
+for the same @thread leads to undefined behaviour.
+
+The value returned by @func or given to g_thread_exit() is
+returned by this function.
+
+g_thread_join() consumes the reference to the passed-in @thread.
+This will usually cause the #GThread struct and associated resources
+to be freed. Use g_thread_ref() to obtain an extra reference if you
+want to keep the GThread alive beyond the g_thread_join() call.
+
+
+ the return value of the thread
+
+
+
+
+ a #GThread
+
+
+
+
+
+ Increase the reference count on @thread.
+
+
+ a new reference to @thread
+
+
+
+
+ a #GThread
+
+
+
+
+
+ Decrease the reference count on @thread, possibly freeing all
+resources associated with it.
+
+Note that each thread holds a reference to its #GThread while
+it is running, so it is safe to drop your own reference to it
+if you don't need it anymore.
+
+
+
+
+
+
+ a #GThread
+
+
+
+
+
+
+
+
+
+
+ Terminates the current thread.
+
+If another thread is waiting for us using g_thread_join() then the
+waiting thread will be woken up and get @retval as the return value
+of g_thread_join().
+
+Calling g_thread_exit() with a parameter @retval is equivalent to
+returning @retval from the function @func, as given to g_thread_new().
+
+You must only call g_thread_exit() from a thread that you created
+yourself with g_thread_new() or related APIs. You must not call
+this function from a thread created with another threading library
+or or from within a #GThreadPool.
+
+
+
+
+
+
+ the return value of this thread
+
+
+
+
+
+ This function returns the #GThread corresponding to the
+current thread. Note that this function does not increase
+the reference count of the returned struct.
+
+This function will return a #GThread even for threads that
+were not created by GLib (i.e. those created by other threading
+APIs). This may be useful for thread identification purposes
+(i.e. comparisons) but you must not use GLib functions (such
+as g_thread_join()) on these threads.
+
+
+ the #GThread representing the current thread
+
+
+
+
+ Causes the calling thread to voluntarily relinquish the CPU, so
+that other threads can run.
+
+This function is often used as a method to make busy wait less evil.
+
+
+
+
+
+
+
+ Possible errors of thread related functions.
+
+
+ a thread couldn't be created due to resource
+ shortage. Try again later.
+
+
+
+ Specifies the type of the @func functions passed to g_thread_new()
+or g_thread_try_new().
+
+
+ the return value of the thread
+
+
+
+
+ data passed to the thread
+
+
+
+
+
+ The #GThreadPool struct represents a thread pool. It has three
+public read-only members, but the underlying struct is bigger,
+so you must not copy this struct.
+
+
+ the function to execute in the threads of this pool
+
+
+
+ the user data for the threads of this pool
+
+
+
+ are all threads exclusive to this pool
+
+
+
+ Frees all resources allocated for @pool.
+
+If @immediate is %TRUE, no new task is processed for @pool.
+Otherwise @pool is not freed before the last task is processed.
+Note however, that no thread of this pool is interrupted while
+processing a task. Instead at least all still running threads
+can finish their tasks before the @pool is freed.
+
+If @wait_ is %TRUE, this function does not return before all
+tasks to be processed (dependent on @immediate, whether all
+or only the currently running) are ready.
+Otherwise this function returns immediately.
+
+After calling this function @pool must not be used anymore.
+
+
+
+
+
+
+ a #GThreadPool
+
+
+
+ should @pool shut down immediately?
+
+
+
+ should the function wait for all tasks to be finished?
+
+
+
+
+
+ Returns the maximal number of threads for @pool.
+
+
+ the maximal number of threads
+
+
+
+
+ a #GThreadPool
+
+
+
+
+
+ Returns the number of threads currently running in @pool.
+
+
+ the number of threads currently running
+
+
+
+
+ a #GThreadPool
+
+
+
+
+
+ Moves the item to the front of the queue of unprocessed
+items, so that it will be processed next.
+
+
+ %TRUE if the item was found and moved
+
+
+
+
+ a #GThreadPool
+
+
+
+ an unprocessed item in the pool
+
+
+
+
+
+ Inserts @data into the list of tasks to be executed by @pool.
+
+When the number of currently running threads is lower than the
+maximal allowed number of threads, a new thread is started (or
+reused) with the properties given to g_thread_pool_new().
+Otherwise, @data stays in the queue until a thread in this pool
+finishes its previous task and processes @data.
+
+@error can be %NULL to ignore errors, or non-%NULL to report
+errors. An error can only occur when a new thread couldn't be
+created. In that case @data is simply appended to the queue of
+work to do.
+
+Before version 2.32, this function did not return a success status.
+
+
+ %TRUE on success, %FALSE if an error occurred
+
+
+
+
+ a #GThreadPool
+
+
+
+ a new task for @pool
+
+
+
+
+
+ Sets the maximal allowed number of threads for @pool.
+A value of -1 means that the maximal number of threads
+is unlimited. If @pool is an exclusive thread pool, setting
+the maximal number of threads to -1 is not allowed.
+
+Setting @max_threads to 0 means stopping all work for @pool.
+It is effectively frozen until @max_threads is set to a non-zero
+value again.
+
+A thread is never terminated while calling @func, as supplied by
+g_thread_pool_new(). Instead the maximal number of threads only
+has effect for the allocation of new threads in g_thread_pool_push().
+A new thread is allocated, whenever the number of currently
+running threads in @pool is smaller than the maximal number.
+
+@error can be %NULL to ignore errors, or non-%NULL to report
+errors. An error can only occur when a new thread couldn't be
+created.
+
+Before version 2.32, this function did not return a success status.
+
+
+ %TRUE on success, %FALSE if an error occurred
+
+
+
+
+ a #GThreadPool
+
+
+
+ a new maximal number of threads for @pool,
+ or -1 for unlimited
+
+
+
+
+
+ Sets the function used to sort the list of tasks. This allows the
+tasks to be processed by a priority determined by @func, and not
+just in the order in which they were added to the pool.
+
+Note, if the maximum number of threads is more than 1, the order
+that threads are executed cannot be guaranteed 100%. Threads are
+scheduled by the operating system and are executed at random. It
+cannot be assumed that threads are executed in the order they are
+created.
+
+
+
+
+
+
+ a #GThreadPool
+
+
+
+ the #GCompareDataFunc used to sort the list of tasks.
+ This function is passed two tasks. It should return
+ 0 if the order in which they are handled does not matter,
+ a negative value if the first task should be processed before
+ the second or a positive value if the second task should be
+ processed first.
+
+
+
+ user data passed to @func
+
+
+
+
+
+ Returns the number of tasks still unprocessed in @pool.
+
+
+ the number of unprocessed tasks
+
+
+
+
+ a #GThreadPool
+
+
+
+
+
+ This function will return the maximum @interval that a
+thread will wait in the thread pool for new tasks before
+being stopped.
+
+If this function returns 0, threads waiting in the thread
+pool for new work are not stopped.
+
+
+ the maximum @interval (milliseconds) to wait
+ for new tasks in the thread pool before stopping the
+ thread
+
+
+
+
+ Returns the maximal allowed number of unused threads.
+
+
+ the maximal number of unused threads
+
+
+
+
+ Returns the number of currently unused threads.
+
+
+ the number of currently unused threads
+
+
+
+
+ This function creates a new thread pool.
+
+Whenever you call g_thread_pool_push(), either a new thread is
+created or an unused one is reused. At most @max_threads threads
+are running concurrently for this thread pool. @max_threads = -1
+allows unlimited threads to be created for this thread pool. The
+newly created or reused thread now executes the function @func
+with the two arguments. The first one is the parameter to
+g_thread_pool_push() and the second one is @user_data.
+
+Pass g_get_num_processors() to @max_threads to create as many threads as
+there are logical processors on the system. This will not pin each thread to
+a specific processor.
+
+The parameter @exclusive determines whether the thread pool owns
+all threads exclusive or shares them with other thread pools.
+If @exclusive is %TRUE, @max_threads threads are started
+immediately and they will run exclusively for this thread pool
+until it is destroyed by g_thread_pool_free(). If @exclusive is
+%FALSE, threads are created when needed and shared between all
+non-exclusive thread pools. This implies that @max_threads may
+not be -1 for exclusive thread pools. Besides, exclusive thread
+pools are not affected by g_thread_pool_set_max_idle_time()
+since their threads are never considered idle and returned to the
+global pool.
+
+Note that the threads used by exclusive threadpools will all inherit the
+scheduler settings of the current thread while the threads used by
+non-exclusive threadpools will inherit the scheduler settings from the
+first thread that created such a threadpool.
+
+@error can be %NULL to ignore errors, or non-%NULL to report
+errors. An error can only occur when @exclusive is set to %TRUE
+and not all @max_threads threads could be created.
+See #GThreadError for possible errors that may occur.
+Note, even in case of error a valid #GThreadPool is returned.
+
+
+ the new #GThreadPool
+
+
+
+
+ a function to execute in the threads of the new thread pool
+
+
+
+ user data that is handed over to @func every time it
+ is called
+
+
+
+ the maximal number of threads to execute concurrently
+ in the new thread pool, -1 means no limit
+
+
+
+ should this thread pool be exclusive?
+
+
+
+
+
+ This function creates a new thread pool similar to g_thread_pool_new()
+but allowing @item_free_func to be specified to free the data passed
+to g_thread_pool_push() in the case that the #GThreadPool is stopped
+and freed before all tasks have been executed.
+
+
+ the new #GThreadPool
+
+
+
+
+ a function to execute in the threads of the new thread pool
+
+
+
+ user data that is handed over to @func every time it
+ is called
+
+
+
+ used to pass as a free function to
+ g_async_queue_new_full()
+
+
+
+ the maximal number of threads to execute concurrently
+ in the new thread pool, `-1` means no limit
+
+
+
+ should this thread pool be exclusive?
+
+
+
+
+
+ This function will set the maximum @interval that a thread
+waiting in the pool for new tasks can be idle for before
+being stopped. This function is similar to calling
+g_thread_pool_stop_unused_threads() on a regular timeout,
+except this is done on a per thread basis.
+
+By setting @interval to 0, idle threads will not be stopped.
+
+The default value is 15000 (15 seconds).
+
+
+
+
+
+
+ the maximum @interval (in milliseconds)
+ a thread can be idle
+
+
+
+
+
+ Sets the maximal number of unused threads to @max_threads.
+If @max_threads is -1, no limit is imposed on the number
+of unused threads.
+
+The default value is 2.
+
+
+
+
+
+
+ maximal number of unused threads
+
+
+
+
+
+ Stops all currently unused threads. This does not change the
+maximal number of unused threads. This function can be used to
+regularly stop all unused threads e.g. from g_timeout_add().
+
+
+
+
+
+
+
+ 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).
+
+
+ the time is in local standard time
+
+
+ the time is in local daylight time
+
+
+ the time is in UTC
+
+
+
+ Represents a precise time, with seconds and microseconds.
+
+Similar to the struct timeval returned by the `gettimeofday()`
+UNIX system call.
+
+GLib is attempting to unify around the use of 64-bit integers to
+represent microsecond-precision time. As such, this type will be
+removed from a future version of GLib. A consequence of using `glong` for
+`tv_sec` is that on 32-bit systems `GTimeVal` is subject to the year 2038
+problem.
+ Use #GDateTime or #guint64 instead.
+
+
+ seconds
+
+
+
+ microseconds
+
+
+
+ Adds the given number of microseconds to @time_. @microseconds can
+also be negative to decrease the value of @time_.
+ #GTimeVal is not year-2038-safe. Use `guint64` for
+ representing microseconds since the epoch, or use #GDateTime.
+
+
+
+
+
+
+ a #GTimeVal
+
+
+
+ number of microseconds to add to @time
+
+
+
+
+
+ Converts @time_ into an RFC 3339 encoded string, relative to the
+Coordinated Universal Time (UTC). This is one of the many formats
+allowed by ISO 8601.
+
+ISO 8601 allows a large number of date/time formats, with or without
+punctuation and optional elements. The format returned by this function
+is a complete date and time, with optional punctuation included, the
+UTC time zone represented as "Z", and the @tv_usec part included if
+and only if it is nonzero, i.e. either
+"YYYY-MM-DDTHH:MM:SSZ" or "YYYY-MM-DDTHH:MM:SS.fffffZ".
+
+This corresponds to the Internet date/time format defined by
+[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt),
+and to either of the two most-precise formats defined by
+the W3C Note
+[Date and Time Formats](http://www.w3.org/TR/NOTE-datetime-19980827).
+Both of these documents are profiles of ISO 8601.
+
+Use g_date_time_format() or g_strdup_printf() if a different
+variation of ISO 8601 format is required.
+
+If @time_ represents a date which is too large to fit into a `struct tm`,
+%NULL will be returned. This is platform dependent. Note also that since
+`GTimeVal` stores the number of seconds as a `glong`, on 32-bit systems it
+is subject to the year 2038 problem. Accordingly, since GLib 2.62, this
+function has been deprecated. Equivalent functionality is available using:
+|[
+GDateTime *dt = g_date_time_new_from_unix_utc (time_val);
+iso8601_string = g_date_time_format_iso8601 (dt);
+g_date_time_unref (dt);
+]|
+
+The return value of g_time_val_to_iso8601() has been nullable since GLib
+2.54; before then, GLib would crash under the same conditions.
+ #GTimeVal is not year-2038-safe. Use
+ g_date_time_format_iso8601(dt) instead.
+
+
+ a newly allocated string containing an ISO 8601 date,
+ or %NULL if @time_ was too large
+
+
+
+
+ a #GTimeVal
+
+
+
+
+
+ Converts a string containing an ISO 8601 encoded date and time
+to a #GTimeVal and puts it into @time_.
+
+@iso_date must include year, month, day, hours, minutes, and
+seconds. It can optionally include fractions of a second and a time
+zone indicator. (In the absence of any time zone indication, the
+timestamp is assumed to be in local time.)
+
+Any leading or trailing space in @iso_date is ignored.
+
+This function was deprecated, along with #GTimeVal itself, in GLib 2.62.
+Equivalent functionality is available using code like:
+|[
+GDateTime *dt = g_date_time_new_from_iso8601 (iso8601_string, NULL);
+gint64 time_val = g_date_time_to_unix (dt);
+g_date_time_unref (dt);
+]|
+ #GTimeVal is not year-2038-safe. Use
+ g_date_time_new_from_iso8601() instead.
+
+
+ %TRUE if the conversion was successful.
+
+
+
+
+ an ISO 8601 encoded date string
+
+
+
+ a #GTimeVal
+
+
+
+
+
+
+ #GTimeZone is an opaque structure whose members cannot be accessed
+directly.
+
+
+ A version of g_time_zone_new_identifier() which returns the UTC time zone
+if @identifier could not be parsed or loaded.
+
+If you need to check whether @identifier was loaded successfully, use
+g_time_zone_new_identifier().
+ Use g_time_zone_new_identifier() instead, as it provides
+ error reporting. Change your code to handle a potentially %NULL return
+ value.
+
+
+ the requested timezone
+
+
+
+
+ a timezone identifier
+
+
+
+
+
+ Creates a #GTimeZone corresponding to @identifier. If @identifier cannot be
+parsed or loaded, %NULL is returned.
+
+@identifier can either be an RFC3339/ISO 8601 time offset or
+something that would pass as a valid value for the `TZ` environment
+variable (including %NULL).
+
+In Windows, @identifier can also be the unlocalized name of a time
+zone for standard time, for example "Pacific Standard Time".
+
+Valid RFC3339 time offsets are `"Z"` (for UTC) or
+`"±hh:mm"`. ISO 8601 additionally specifies
+`"±hhmm"` and `"±hh"`. Offsets are
+time values to be added to Coordinated Universal Time (UTC) to get
+the local time.
+
+In UNIX, the `TZ` environment variable typically corresponds
+to the name of a file in the zoneinfo database, an absolute path to a file
+somewhere else, or a string in
+"std offset [dst [offset],start[/time],end[/time]]" (POSIX) format.
+There are no spaces in the specification. The name of standard
+and daylight savings time zone must be three or more alphabetic
+characters. Offsets are time values to be added to local time to
+get Coordinated Universal Time (UTC) and should be
+`"[±]hh[[:]mm[:ss]]"`. Dates are either
+`"Jn"` (Julian day with n between 1 and 365, leap
+years not counted), `"n"` (zero-based Julian day
+with n between 0 and 365) or `"Mm.w.d"` (day d
+(0 <= d <= 6) of week w (1 <= w <= 5) of month m (1 <= m <= 12), day
+0 is a Sunday). Times are in local wall clock time, the default is
+02:00:00.
+
+In Windows, the "tzn[+|–]hh[:mm[:ss]][dzn]" format is used, but also
+accepts POSIX format. The Windows format uses US rules for all time
+zones; daylight savings time is 60 minutes behind the standard time
+with date and time of change taken from Pacific Standard Time.
+Offsets are time values to be added to the local time to get
+Coordinated Universal Time (UTC).
+
+g_time_zone_new_local() calls this function with the value of the
+`TZ` environment variable. This function itself is independent of
+the value of `TZ`, but if @identifier is %NULL then `/etc/localtime`
+will be consulted to discover the correct time zone on UNIX and the
+registry will be consulted or GetTimeZoneInformation() will be used
+to get the local time zone on Windows.
+
+If intervals are not available, only time zone rules from `TZ`
+environment variable or other means, then they will be computed
+from year 1900 to 2037. If the maximum year for the rules is
+available and it is greater than 2037, then it will followed
+instead.
+
+See
+[RFC3339 §5.6](http://tools.ietf.org/html/rfc3339#section-5.6)
+for a precise definition of valid RFC3339 time offsets
+(the `time-offset` expansion) and ISO 8601 for the
+full list of valid time offsets. See
+[The GNU C Library manual](http://www.gnu.org/s/libc/manual/html_node/TZ-Variable.html)
+for an explanation of the possible
+values of the `TZ` environment variable. See
+[Microsoft Time Zone Index Values](http://msdn.microsoft.com/en-us/library/ms912391%28v=winembedded.11%29.aspx)
+for the list of time zones on Windows.
+
+You should release the return value by calling g_time_zone_unref()
+when you are done with it.
+
+
+ the requested timezone, or %NULL on
+ failure
+
+
+
+
+ a timezone identifier
+
+
+
+
+
+ Creates a #GTimeZone corresponding to local time. The local time
+zone may change between invocations to this function; for example,
+if the system administrator changes it.
+
+This is equivalent to calling g_time_zone_new() with the value of
+the `TZ` environment variable (including the possibility of %NULL).
+
+You should release the return value by calling g_time_zone_unref()
+when you are done with it.
+
+
+ the local timezone
+
+
+
+
+ Creates a #GTimeZone corresponding to the given constant offset from UTC,
+in seconds.
+
+This is equivalent to calling g_time_zone_new() with a string in the form
+`[+|-]hh[:mm[:ss]]`.
+
+It is possible for this function to fail if @seconds is too big (greater than
+24 hours), in which case this function will return the UTC timezone for
+backwards compatibility. To detect failures like this, use
+g_time_zone_new_identifier() directly.
+
+
+ a timezone at the given offset from UTC, or UTC on
+ failure
+
+
+
+
+ offset to UTC, in seconds
+
+
+
+
+
+ Creates a #GTimeZone corresponding to UTC.
+
+This is equivalent to calling g_time_zone_new() with a value like
+"Z", "UTC", "+00", etc.
+
+You should release the return value by calling g_time_zone_unref()
+when you are done with it.
+
+
+ the universal timezone
+
+
+
+
+ Finds an interval within @tz that corresponds to the given @time_,
+possibly adjusting @time_ if required to fit into an interval.
+The meaning of @time_ depends on @type.
+
+This function is similar to g_time_zone_find_interval(), with the
+difference that it always succeeds (by making the adjustments
+described below).
+
+In any of the cases where g_time_zone_find_interval() succeeds then
+this function returns the same value, without modifying @time_.
+
+This function may, however, modify @time_ in order to deal with
+non-existent times. If the non-existent local @time_ of 02:30 were
+requested on March 14th 2010 in Toronto then this function would
+adjust @time_ to be 03:00 and return the interval containing the
+adjusted time.
+
+
+ the interval containing @time_, never -1
+
+
+
+
+ a #GTimeZone
+
+
+
+ the #GTimeType of @time_
+
+
+
+ a pointer to a number of seconds since January 1, 1970
+
+
+
+
+
+ Finds an interval within @tz that corresponds to the given @time_.
+The meaning of @time_ depends on @type.
+
+If @type is %G_TIME_TYPE_UNIVERSAL then this function will always
+succeed (since universal time is monotonic and continuous).
+
+Otherwise @time_ is treated as local time. The distinction between
+%G_TIME_TYPE_STANDARD and %G_TIME_TYPE_DAYLIGHT is ignored except in
+the case that the given @time_ is ambiguous. In Toronto, for example,
+01:30 on November 7th 2010 occurred twice (once inside of daylight
+savings time and the next, an hour later, outside of daylight savings
+time). In this case, the different value of @type would result in a
+different interval being returned.
+
+It is still possible for this function to fail. In Toronto, for
+example, 02:00 on March 14th 2010 does not exist (due to the leap
+forward to begin daylight savings time). -1 is returned in that
+case.
+
+
+ the interval containing @time_, or -1 in case of failure
+
+
+
+
+ a #GTimeZone
+
+
+
+ the #GTimeType of @time_
+
+
+
+ a number of seconds since January 1, 1970
+
+
+
+
+
+ Determines the time zone abbreviation to be used during a particular
+@interval of time in the time zone @tz.
+
+For example, in Toronto this is currently "EST" during the winter
+months and "EDT" during the summer months when daylight savings time
+is in effect.
+
+
+ the time zone abbreviation, which belongs to @tz
+
+
+
+
+ a #GTimeZone
+
+
+
+ an interval within the timezone
+
+
+
+
+
+ Get the identifier of this #GTimeZone, as passed to g_time_zone_new().
+If the identifier passed at construction time was not recognised, `UTC` will
+be returned. If it was %NULL, the identifier of the local timezone at
+construction time will be returned.
+
+The identifier will be returned in the same format as provided at
+construction time: if provided as a time offset, that will be returned by
+this function.
+
+
+ identifier for this timezone
+
+
+
+
+ a #GTimeZone
+
+
+
+
+
+ Determines the offset to UTC in effect during a particular @interval
+of time in the time zone @tz.
+
+The offset is the number of seconds that you add to UTC time to
+arrive at local time for @tz (ie: negative numbers for time zones
+west of GMT, positive numbers for east).
+
+
+ the number of seconds that should be added to UTC to get the
+ local time in @tz
+
+
+
+
+ a #GTimeZone
+
+
+
+ an interval within the timezone
+
+
+
+
+
+ Determines if daylight savings time is in effect during a particular
+@interval of time in the time zone @tz.
+
+
+ %TRUE if daylight savings time is in effect
+
+
+
+
+ a #GTimeZone
+
+
+
+ an interval within the timezone
+
+
+
+
+
+ Increases the reference count on @tz.
+
+
+ a new reference to @tz.
+
+
+
+
+ a #GTimeZone
+
+
+
+
+
+ Decreases the reference count on @tz.
+
+
+
+
+
+
+ a #GTimeZone
+
+
+
+
+
+
+ Opaque datatype that records a start time.
+
+
+ Resumes a timer that has previously been stopped with
+g_timer_stop(). g_timer_stop() must be called before using this
+function.
+
+
+
+
+
+
+ a #GTimer.
+
+
+
+
+
+ Destroys a timer, freeing associated resources.
+
+
+
+
+
+
+ a #GTimer to destroy.
+
+
+
+
+
+ If @timer has been started but not stopped, obtains the time since
+the timer was started. If @timer has been stopped, obtains the
+elapsed time between the time it was started and the time it was
+stopped. The return value is the number of seconds elapsed,
+including any fractional part. The @microseconds out parameter is
+essentially useless.
+
+
+ seconds elapsed as a floating point value, including any
+ fractional part.
+
+
+
+
+ a #GTimer.
+
+
+
+ return location for the fractional part of seconds
+ elapsed, in microseconds (that is, the total number
+ of microseconds elapsed, modulo 1000000), or %NULL
+
+
+
+
+
+ Exposes whether the timer is currently active.
+
+
+ %TRUE if the timer is running, %FALSE otherwise
+
+
+
+
+ a #GTimer.
+
+
+
+
+
+ This function is useless; it's fine to call g_timer_start() on an
+already-started timer to reset the start time, so g_timer_reset()
+serves no purpose.
+
+
+
+
+
+
+ a #GTimer.
+
+
+
+
+
+ Marks a start time, so that future calls to g_timer_elapsed() will
+report the time since g_timer_start() was called. g_timer_new()
+automatically marks the start time, so no need to call
+g_timer_start() immediately after creating the timer.
+
+
+
+
+
+
+ a #GTimer.
+
+
+
+
+
+ Marks an end time, so calls to g_timer_elapsed() will return the
+difference between this end time and the start time.
+
+
+
+
+
+
+ a #GTimer.
+
+
+
+
+
+ Creates a new timer, and starts timing (i.e. g_timer_start() is
+implicitly called for you).
+
+
+ a new #GTimer.
+
+
+
+
+
+ The possible types of token returned from each
+g_scanner_get_next_token() call.
+
+
+ the end of the file
+
+
+ a '(' character
+
+
+ a ')' character
+
+
+ a '{' character
+
+
+ a '}' character
+
+
+ a '[' character
+
+
+ a ']' character
+
+
+ a '=' character
+
+
+ a ',' character
+
+
+ not a token
+
+
+ an error occurred
+
+
+ a character
+
+
+ a binary integer
+
+
+ an octal integer
+
+
+ an integer
+
+
+ a hex integer
+
+
+ a floating point number
+
+
+ a string
+
+
+ a symbol
+
+
+ an identifier
+
+
+ a null identifier
+
+
+ one line comment
+
+
+ multi line comment
+
+
+
+ A union holding the value of the token.
+
+
+ token symbol value
+
+
+
+ token identifier value
+
+
+
+ token binary integer value
+
+
+
+ octal integer value
+
+
+
+ integer value
+
+
+
+ 64-bit integer value
+
+
+
+ floating point value
+
+
+
+ hex integer value
+
+
+
+ string value
+
+
+
+ comment value
+
+
+
+ character value
+
+
+
+ error value
+
+
+
+
+ The type of functions which are used to translate user-visible
+strings, for <option>--help</option> output.
+
+
+ a translation of the string for the current locale.
+ The returned string is owned by GLib and must not be freed.
+
+
+
+
+ the untranslated string
+
+
+
+ user data specified when installing the function, e.g.
+ in g_option_group_set_translate_func()
+
+
+
+
+
+ Each piece of memory that is pushed onto the stack
+is cast to a GTrashStack*.
+ #GTrashStack is deprecated without replacement
+
+
+ pointer to the previous element of the stack,
+ gets stored in the first `sizeof (gpointer)`
+ bytes of the element
+
+
+
+ Returns the height of a #GTrashStack.
+
+Note that execution of this function is of O(N) complexity
+where N denotes the number of items on the stack.
+ #GTrashStack is deprecated without replacement
+
+
+ the height of the stack
+
+
+
+
+ a #GTrashStack
+
+
+
+
+
+ Returns the element at the top of a #GTrashStack
+which may be %NULL.
+ #GTrashStack is deprecated without replacement
+
+
+ the element at the top of the stack
+
+
+
+
+ a #GTrashStack
+
+
+
+
+
+ Pops a piece of memory off a #GTrashStack.
+ #GTrashStack is deprecated without replacement
+
+
+ the element at the top of the stack
+
+
+
+
+ a #GTrashStack
+
+
+
+
+
+ Pushes a piece of memory onto a #GTrashStack.
+ #GTrashStack is deprecated without replacement
+
+
+
+
+
+
+ a #GTrashStack
+
+
+
+ the piece of memory to push on the stack
+
+
+
+
+
+
+ Specifies which nodes are visited during several of the tree
+functions, including g_node_traverse() and g_node_find().
+
+
+ only leaf nodes should be visited. This name has
+ been introduced in 2.6, for older version use
+ %G_TRAVERSE_LEAFS.
+
+
+ only non-leaf nodes should be visited. This
+ name has been introduced in 2.6, for older
+ version use %G_TRAVERSE_NON_LEAFS.
+
+
+ all nodes should be visited.
+
+
+ a mask of all traverse flags.
+
+
+ identical to %G_TRAVERSE_LEAVES.
+
+
+ identical to %G_TRAVERSE_NON_LEAVES.
+
+
+
+ Specifies the type of function passed to g_tree_traverse(). It is
+passed the key and value of each node, together with the @user_data
+parameter passed to g_tree_traverse(). If the function returns
+%TRUE, the traversal is stopped.
+
+
+ %TRUE to stop the traversal
+
+
+
+
+ a key of a #GTree node
+
+
+
+ the value corresponding to the key
+
+
+
+ user data passed to g_tree_traverse()
+
+
+
+
+
+ Specifies the type of function passed to g_tree_foreach_node(). It is
+passed each node, together with the @user_data parameter passed to
+g_tree_foreach_node(). If the function returns %TRUE, the traversal is
+stopped.
+
+
+ %TRUE to stop the traversal
+
+
+
+
+ a #GTreeNode
+
+
+
+ user data passed to g_tree_foreach_node()
+
+
+
+
+
+ Specifies the type of traversal performed by g_tree_traverse(),
+g_node_traverse() and g_node_find(). The different orders are
+illustrated here:
+- In order: A, B, C, D, E, F, G, H, I
+ 
+- Pre order: F, B, A, D, C, E, G, I, H
+ 
+- Post order: A, C, E, D, B, H, I, G, F
+ 
+- Level order: F, B, G, A, D, I, C, E, H
+ 
+
+
+ vists a node's left child first, then the node itself,
+ then its right child. This is the one to use if you
+ want the output sorted according to the compare
+ function.
+
+
+ visits a node, then its children.
+
+
+ visits the node's children, then the node itself.
+
+
+ is not implemented for
+ [balanced binary trees][glib-Balanced-Binary-Trees].
+ For [n-ary trees][glib-N-ary-Trees], it
+ vists the root node first, then its children, then
+ its grandchildren, and so on. Note that this is less
+ efficient than the other orders.
+
+
+
+ The GTree struct is an opaque data structure representing a
+[balanced binary tree][glib-Balanced-Binary-Trees]. It should be
+accessed only by using the following functions.
+
+
+ Creates a new #GTree.
+
+
+ a newly allocated #GTree
+
+
+
+
+ the function used to order the nodes in the #GTree.
+ It should return values similar to the standard strcmp() function -
+ 0 if the two arguments are equal, a negative value if the first argument
+ comes before the second, or a positive value if the first argument comes
+ after the second.
+
+
+
+
+
+ Creates a new #GTree like g_tree_new() and allows to specify functions
+to free the memory allocated for the key and value that get called when
+removing the entry from the #GTree.
+
+
+ a newly allocated #GTree
+
+
+
+
+ qsort()-style comparison function
+
+
+
+ data to pass to comparison function
+
+
+
+ a function to free the memory allocated for the key
+ used when removing the entry from the #GTree or %NULL if you don't
+ want to supply such a function
+
+
+
+ a function to free the memory allocated for the
+ value used when removing the entry from the #GTree or %NULL if you
+ don't want to supply such a function
+
+
+
+
+
+ Creates a new #GTree with a comparison function that accepts user data.
+See g_tree_new() for more details.
+
+
+ a newly allocated #GTree
+
+
+
+
+ qsort()-style comparison function
+
+
+
+ data to pass to comparison function
+
+
+
+
+
+ Removes all keys and values from the #GTree and decreases its
+reference count by one. If keys and/or values are dynamically
+allocated, you should either free them first or create the #GTree
+using g_tree_new_full(). In the latter case the destroy functions
+you supplied will be called on all keys and values before destroying
+the #GTree.
+
+
+
+
+
+
+ a #GTree
+
+
+
+
+
+ Calls the given function for each of the key/value pairs in the #GTree.
+The function is passed the key and value of each pair, and the given
+@data parameter. The tree is traversed in sorted order.
+
+The tree may not be modified while iterating over it (you can't
+add/remove items). To remove all items matching a predicate, you need
+to add each item to a list in your #GTraverseFunc as you walk over
+the tree, then walk the list and remove each item.
+
+
+
+
+
+
+ a #GTree
+
+
+
+ the function to call for each node visited.
+ If this function returns %TRUE, the traversal is stopped.
+
+
+
+ user data to pass to the function
+
+
+
+
+
+ Calls the given function for each of the nodes in the #GTree.
+The function is passed the pointer to the particular node, and the given
+@data parameter. The tree traversal happens in-order.
+
+The tree may not be modified while iterating over it (you can't
+add/remove items). To remove all items matching a predicate, you need
+to add each item to a list in your #GTraverseFunc as you walk over
+the tree, then walk the list and remove each item.
+
+
+
+
+
+
+ a #GTree
+
+
+
+ the function to call for each node visited.
+ If this function returns %TRUE, the traversal is stopped.
+
+
+
+ user data to pass to the function
+
+
+
+
+
+ Gets the height of a #GTree.
+
+If the #GTree contains no nodes, the height is 0.
+If the #GTree contains only one root node the height is 1.
+If the root node has children the height is 2, etc.
+
+
+ the height of @tree
+
+
+
+
+ a #GTree
+
+
+
+
+
+ Inserts a key/value pair into a #GTree.
+
+Inserts a new key and value into a #GTree as g_tree_insert_node() does,
+only this function does not return the inserted or set node.
+
+
+
+
+
+
+ a #GTree
+
+
+
+ the key to insert
+
+
+
+ the value corresponding to the key
+
+
+
+
+
+ Inserts a key/value pair into a #GTree.
+
+If the given key already exists in the #GTree its corresponding value
+is set to the new value. If you supplied a @value_destroy_func when
+creating the #GTree, the old value is freed using that function. If
+you supplied a @key_destroy_func when creating the #GTree, the passed
+key is freed using that function.
+
+The tree is automatically 'balanced' as new key/value pairs are added,
+so that the distance from the root to every leaf is as small as possible.
+The cost of maintaining a balanced tree while inserting new key/value
+result in a O(n log(n)) operation where most of the other operations
+are O(log(n)).
+
+
+ the inserted (or set) node.
+
+
+
+
+ a #GTree
+
+
+
+ the key to insert
+
+
+
+ the value corresponding to the key
+
+
+
+
+
+ Gets the value corresponding to the given key. Since a #GTree is
+automatically balanced as key/value pairs are added, key lookup
+is O(log n) (where n is the number of key/value pairs in the tree).
+
+
+ the value corresponding to the key, or %NULL
+ if the key was not found
+
+
+
+
+ a #GTree
+
+
+
+ the key to look up
+
+
+
+
+
+ Looks up a key in the #GTree, returning the original key and the
+associated value. This is useful if you need to free the memory
+allocated for the original key, for example before calling
+g_tree_remove().
+
+
+ %TRUE if the key was found in the #GTree
+
+
+
+
+ a #GTree
+
+
+
+ the key to look up
+
+
+
+ returns the original key
+
+
+
+ returns the value associated with the key
+
+
+
+
+
+ Gets the tree node corresponding to the given key. Since a #GTree is
+automatically balanced as key/value pairs are added, key lookup
+is O(log n) (where n is the number of key/value pairs in the tree).
+
+
+ the tree node corresponding to
+ the key, or %NULL if the key was not found
+
+
+
+
+ a #GTree
+
+
+
+ the key to look up
+
+
+
+
+
+ Gets the lower bound node corresponding to the given key,
+or %NULL if the tree is empty or all the nodes in the tree
+have keys that are strictly lower than the searched key.
+
+The lower bound is the first node that has its key greater
+than or equal to the searched key.
+
+
+ the tree node corresponding to
+ the lower bound, or %NULL if the tree is empty or has only
+ keys strictly lower than the searched key.
+
+
+
+
+ a #GTree
+
+
+
+ the key to calculate the lower bound for
+
+
+
+
+
+ Gets the number of nodes in a #GTree.
+
+
+ the number of nodes in @tree
+
+
+
+
+ a #GTree
+
+
+
+
+
+ Returns the first in-order node of the tree, or %NULL
+for an empty tree.
+
+
+ the first node in the tree
+
+
+
+
+ a #GTree
+
+
+
+
+
+ Returns the last in-order node of the tree, or %NULL
+for an empty tree.
+
+
+ the last node in the tree
+
+
+
+
+ a #GTree
+
+
+
+
+
+ Increments the reference count of @tree by one.
+
+It is safe to call this function from any thread.
+
+
+ the passed in #GTree
+
+
+
+
+ a #GTree
+
+
+
+
+
+ Removes a key/value pair from a #GTree.
+
+If the #GTree was created using g_tree_new_full(), the key and value
+are freed using the supplied destroy functions, otherwise you have to
+make sure that any dynamically allocated values are freed yourself.
+If the key does not exist in the #GTree, the function does nothing.
+
+The cost of maintaining a balanced tree while removing a key/value
+result in a O(n log(n)) operation where most of the other operations
+are O(log(n)).
+
+
+ %TRUE if the key was found (prior to 2.8, this function
+ returned nothing)
+
+
+
+
+ a #GTree
+
+
+
+ the key to remove
+
+
+
+
+
+ Removes all nodes from a #GTree and destroys their keys and values,
+then resets the #GTree’s root to %NULL.
+
+
+
+
+
+
+ a #GTree
+
+
+
+
+
+ Inserts a new key and value into a #GTree as g_tree_replace_node() does,
+only this function does not return the inserted or set node.
+
+
+
+
+
+
+ a #GTree
+
+
+
+ the key to insert
+
+
+
+ the value corresponding to the key
+
+
+
+
+
+ Inserts a new key and value into a #GTree similar to g_tree_insert_node().
+The difference is that if the key already exists in the #GTree, it gets
+replaced by the new key. If you supplied a @value_destroy_func when
+creating the #GTree, the old value is freed using that function. If you
+supplied a @key_destroy_func when creating the #GTree, the old key is
+freed using that function.
+
+The tree is automatically 'balanced' as new key/value pairs are added,
+so that the distance from the root to every leaf is as small as possible.
+
+
+ the inserted (or set) node.
+
+
+
+
+ a #GTree
+
+
+
+ the key to insert
+
+
+
+ the value corresponding to the key
+
+
+
+
+
+ Searches a #GTree using @search_func.
+
+The @search_func is called with a pointer to the key of a key/value
+pair in the tree, and the passed in @user_data. If @search_func returns
+0 for a key/value pair, then the corresponding value is returned as
+the result of g_tree_search(). If @search_func returns -1, searching
+will proceed among the key/value pairs that have a smaller key; if
+@search_func returns 1, searching will proceed among the key/value
+pairs that have a larger key.
+
+
+ the value corresponding to the found key, or %NULL
+ if the key was not found
+
+
+
+
+ a #GTree
+
+
+
+ a function used to search the #GTree
+
+
+
+ the data passed as the second argument to @search_func
+
+
+
+
+
+ Searches a #GTree using @search_func.
+
+The @search_func is called with a pointer to the key of a key/value
+pair in the tree, and the passed in @user_data. If @search_func returns
+0 for a key/value pair, then the corresponding node is returned as
+the result of g_tree_search(). If @search_func returns -1, searching
+will proceed among the key/value pairs that have a smaller key; if
+@search_func returns 1, searching will proceed among the key/value
+pairs that have a larger key.
+
+
+ the node corresponding to the
+ found key, or %NULL if the key was not found
+
+
+
+
+ a #GTree
+
+
+
+ a function used to search the #GTree
+
+
+
+ the data passed as the second argument to @search_func
+
+
+
+
+
+ Removes a key and its associated value from a #GTree without calling
+the key and value destroy functions.
+
+If the key does not exist in the #GTree, the function does nothing.
+
+
+ %TRUE if the key was found (prior to 2.8, this function
+ returned nothing)
+
+
+
+
+ a #GTree
+
+
+
+ the key to remove
+
+
+
+
+
+ Calls the given function for each node in the #GTree.
+ The order of a balanced tree is somewhat arbitrary.
+ If you just want to visit all nodes in sorted order, use
+ g_tree_foreach() instead. If you really need to visit nodes in
+ a different order, consider using an [n-ary tree][glib-N-ary-Trees].
+
+
+
+
+
+
+ a #GTree
+
+
+
+ the function to call for each node visited. If this
+ function returns %TRUE, the traversal is stopped.
+
+
+
+ the order in which nodes are visited, one of %G_IN_ORDER,
+ %G_PRE_ORDER and %G_POST_ORDER
+
+
+
+ user data to pass to the function
+
+
+
+
+
+ Decrements the reference count of @tree by one.
+If the reference count drops to 0, all keys and values will
+be destroyed (if destroy functions were specified) and all
+memory allocated by @tree will be released.
+
+It is safe to call this function from any thread.
+
+
+
+
+
+
+ a #GTree
+
+
+
+
+
+ Gets the upper bound node corresponding to the given key,
+or %NULL if the tree is empty or all the nodes in the tree
+have keys that are lower than or equal to the searched key.
+
+The upper bound is the first node that has its key strictly greater
+than the searched key.
+
+
+ the tree node corresponding to the
+ upper bound, or %NULL if the tree is empty or has only keys
+ lower than or equal to the searched key.
+
+
+
+
+ a #GTree
+
+
+
+ the key to calculate the upper bound for
+
+
+
+
+
+
+ An opaque type which identifies a specific node in a #GTree.
+
+
+ Gets the key stored at a particular tree node.
+
+
+ the key at the node.
+
+
+
+
+ a #GTree node
+
+
+
+
+
+ Returns the next in-order node of the tree, or %NULL
+if the passed node was already the last one.
+
+
+ the next node in the tree
+
+
+
+
+ a #GTree node
+
+
+
+
+
+ Returns the previous in-order node of the tree, or %NULL
+if the passed node was already the first one.
+
+
+ the previous node in the tree
+
+
+
+
+ a #GTree node
+
+
+
+
+
+ Gets the value stored at a particular tree node.
+
+
+ the value at the node.
+
+
+
+
+ a #GTree node
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The maximum length (in codepoints) of a compatibility or canonical
+decomposition of a single Unicode character.
+
+This is as defined by Unicode 6.1.
+
+
+
+
+ Hints the compiler that the expression is unlikely to evaluate to
+a true value. The compiler may use this information for optimizations.
+
+|[<!-- language="C" -->
+if (G_UNLIKELY (random () == 1))
+ g_print ("a random one");
+]|
+
+
+
+ the expression
+
+
+
+
+ Works like g_mutex_unlock(), but for a lock defined with
+%G_LOCK_DEFINE.
+
+
+
+ the name of the lock
+
+
+
+
+ Generic delimiters characters as defined in
+[RFC 3986](https://tools.ietf.org/html/rfc3986). Includes `:/?#[]@`.
+
+
+
+
+ Subcomponent delimiter characters as defined in
+[RFC 3986](https://tools.ietf.org/html/rfc3986). Includes `!$&'()*+,;=`.
+
+
+
+
+ Number of microseconds in one second (1 million).
+This macro is provided for code readability.
+
+
+
+
+ These are the possible line break classifications.
+
+Since new unicode versions may add new types here, applications should be ready
+to handle unknown values. They may be regarded as %G_UNICODE_BREAK_UNKNOWN.
+
+See [Unicode Line Breaking Algorithm](http://www.unicode.org/unicode/reports/tr14/).
+
+
+ Mandatory Break (BK)
+
+
+ Carriage Return (CR)
+
+
+ Line Feed (LF)
+
+
+ Attached Characters and Combining Marks (CM)
+
+
+ Surrogates (SG)
+
+
+ Zero Width Space (ZW)
+
+
+ Inseparable (IN)
+
+
+ Non-breaking ("Glue") (GL)
+
+
+ Contingent Break Opportunity (CB)
+
+
+ Space (SP)
+
+
+ Break Opportunity After (BA)
+
+
+ Break Opportunity Before (BB)
+
+
+ Break Opportunity Before and After (B2)
+
+
+ Hyphen (HY)
+
+
+ Nonstarter (NS)
+
+
+ Opening Punctuation (OP)
+
+
+ Closing Punctuation (CL)
+
+
+ Ambiguous Quotation (QU)
+
+
+ Exclamation/Interrogation (EX)
+
+
+ Ideographic (ID)
+
+
+ Numeric (NU)
+
+
+ Infix Separator (Numeric) (IS)
+
+
+ Symbols Allowing Break After (SY)
+
+
+ Ordinary Alphabetic and Symbol Characters (AL)
+
+
+ Prefix (Numeric) (PR)
+
+
+ Postfix (Numeric) (PO)
+
+
+ Complex Content Dependent (South East Asian) (SA)
+
+
+ Ambiguous (Alphabetic or Ideographic) (AI)
+
+
+ Unknown (XX)
+
+
+ Next Line (NL)
+
+
+ Word Joiner (WJ)
+
+
+ Hangul L Jamo (JL)
+
+
+ Hangul V Jamo (JV)
+
+
+ Hangul T Jamo (JT)
+
+
+ Hangul LV Syllable (H2)
+
+
+ Hangul LVT Syllable (H3)
+
+
+ Closing Parenthesis (CP). Since 2.28. Deprecated: 2.70: Use %G_UNICODE_BREAK_CLOSE_PARENTHESIS instead.
+
+
+ Closing Parenthesis (CP). Since 2.70
+
+
+ Conditional Japanese Starter (CJ). Since: 2.32
+
+
+ Hebrew Letter (HL). Since: 2.32
+
+
+ Regional Indicator (RI). Since: 2.36
+
+
+ Emoji Base (EB). Since: 2.50
+
+
+ Emoji Modifier (EM). Since: 2.50
+
+
+ Zero Width Joiner (ZWJ). Since: 2.50
+
+
+
+ The #GUnicodeScript enumeration identifies different writing
+systems. The values correspond to the names as defined in the
+Unicode standard. The enumeration has been added in GLib 2.14,
+and is interchangeable with #PangoScript.
+
+Note that new types may be added in the future. Applications
+should be ready to handle unknown values.
+See [Unicode Standard Annex #24: Script names](http://www.unicode.org/reports/tr24/).
+
+
+ a value never returned from g_unichar_get_script()
+
+
+ a character used by multiple different scripts
+
+
+ a mark glyph that takes its script from the
+ base glyph to which it is attached
+
+
+ Arabic
+
+
+ Armenian
+
+
+ Bengali
+
+
+ Bopomofo
+
+
+ Cherokee
+
+
+ Coptic
+
+
+ Cyrillic
+
+
+ Deseret
+
+
+ Devanagari
+
+
+ Ethiopic
+
+
+ Georgian
+
+
+ Gothic
+
+
+ Greek
+
+
+ Gujarati
+
+
+ Gurmukhi
+
+
+ Han
+
+
+ Hangul
+
+
+ Hebrew
+
+
+ Hiragana
+
+
+ Kannada
+
+
+ Katakana
+
+
+ Khmer
+
+
+ Lao
+
+
+ Latin
+
+
+ Malayalam
+
+
+ Mongolian
+
+
+ Myanmar
+
+
+ Ogham
+
+
+ Old Italic
+
+
+ Oriya
+
+
+ Runic
+
+
+ Sinhala
+
+
+ Syriac
+
+
+ Tamil
+
+
+ Telugu
+
+
+ Thaana
+
+
+ Thai
+
+
+ Tibetan
+
+
+ Canadian Aboriginal
+
+
+ Yi
+
+
+ Tagalog
+
+
+ Hanunoo
+
+
+ Buhid
+
+
+ Tagbanwa
+
+
+ Braille
+
+
+ Cypriot
+
+
+ Limbu
+
+
+ Osmanya
+
+
+ Shavian
+
+
+ Linear B
+
+
+ Tai Le
+
+
+ Ugaritic
+
+
+ New Tai Lue
+
+
+ Buginese
+
+
+ Glagolitic
+
+
+ Tifinagh
+
+
+ Syloti Nagri
+
+
+ Old Persian
+
+
+ Kharoshthi
+
+
+ an unassigned code point
+
+
+ Balinese
+
+
+ Cuneiform
+
+
+ Phoenician
+
+
+ Phags-pa
+
+
+ N'Ko
+
+
+ Kayah Li. Since 2.16.3
+
+
+ Lepcha. Since 2.16.3
+
+
+ Rejang. Since 2.16.3
+
+
+ Sundanese. Since 2.16.3
+
+
+ Saurashtra. Since 2.16.3
+
+
+ Cham. Since 2.16.3
+
+
+ Ol Chiki. Since 2.16.3
+
+
+ Vai. Since 2.16.3
+
+
+ Carian. Since 2.16.3
+
+
+ Lycian. Since 2.16.3
+
+
+ Lydian. Since 2.16.3
+
+
+ Avestan. Since 2.26
+
+
+ Bamum. Since 2.26
+
+
+ Egyptian Hieroglpyhs. Since 2.26
+
+
+ Imperial Aramaic. Since 2.26
+
+
+ Inscriptional Pahlavi. Since 2.26
+
+
+ Inscriptional Parthian. Since 2.26
+
+
+ Javanese. Since 2.26
+
+
+ Kaithi. Since 2.26
+
+
+ Lisu. Since 2.26
+
+
+ Meetei Mayek. Since 2.26
+
+
+ Old South Arabian. Since 2.26
+
+
+ Old Turkic. Since 2.28
+
+
+ Samaritan. Since 2.26
+
+
+ Tai Tham. Since 2.26
+
+
+ Tai Viet. Since 2.26
+
+
+ Batak. Since 2.28
+
+
+ Brahmi. Since 2.28
+
+
+ Mandaic. Since 2.28
+
+
+ Chakma. Since: 2.32
+
+
+ Meroitic Cursive. Since: 2.32
+
+
+ Meroitic Hieroglyphs. Since: 2.32
+
+
+ Miao. Since: 2.32
+
+
+ Sharada. Since: 2.32
+
+
+ Sora Sompeng. Since: 2.32
+
+
+ Takri. Since: 2.32
+
+
+ Bassa. Since: 2.42
+
+
+ Caucasian Albanian. Since: 2.42
+
+
+ Duployan. Since: 2.42
+
+
+ Elbasan. Since: 2.42
+
+
+ Grantha. Since: 2.42
+
+
+ Kjohki. Since: 2.42
+
+
+ Khudawadi, Sindhi. Since: 2.42
+
+
+ Linear A. Since: 2.42
+
+
+ Mahajani. Since: 2.42
+
+
+ Manichaean. Since: 2.42
+
+
+ Mende Kikakui. Since: 2.42
+
+
+ Modi. Since: 2.42
+
+
+ Mro. Since: 2.42
+
+
+ Nabataean. Since: 2.42
+
+
+ Old North Arabian. Since: 2.42
+
+
+ Old Permic. Since: 2.42
+
+
+ Pahawh Hmong. Since: 2.42
+
+
+ Palmyrene. Since: 2.42
+
+
+ Pau Cin Hau. Since: 2.42
+
+
+ Psalter Pahlavi. Since: 2.42
+
+
+ Siddham. Since: 2.42
+
+
+ Tirhuta. Since: 2.42
+
+
+ Warang Citi. Since: 2.42
+
+
+ Ahom. Since: 2.48
+
+
+ Anatolian Hieroglyphs. Since: 2.48
+
+
+ Hatran. Since: 2.48
+
+
+ Multani. Since: 2.48
+
+
+ Old Hungarian. Since: 2.48
+
+
+ Signwriting. Since: 2.48
+
+
+ Adlam. Since: 2.50
+
+
+ Bhaiksuki. Since: 2.50
+
+
+ Marchen. Since: 2.50
+
+
+ Newa. Since: 2.50
+
+
+ Osage. Since: 2.50
+
+
+ Tangut. Since: 2.50
+
+
+ Masaram Gondi. Since: 2.54
+
+
+ Nushu. Since: 2.54
+
+
+ Soyombo. Since: 2.54
+
+
+ Zanabazar Square. Since: 2.54
+
+
+ Dogra. Since: 2.58
+
+
+ Gunjala Gondi. Since: 2.58
+
+
+ Hanifi Rohingya. Since: 2.58
+
+
+ Makasar. Since: 2.58
+
+
+ Medefaidrin. Since: 2.58
+
+
+ Old Sogdian. Since: 2.58
+
+
+ Sogdian. Since: 2.58
+
+
+ Elym. Since: 2.62
+
+
+ Nand. Since: 2.62
+
+
+ Rohg. Since: 2.62
+
+
+ Wcho. Since: 2.62
+
+
+ Chorasmian. Since: 2.66
+
+
+ Dives Akuru. Since: 2.66
+
+
+ Khitan small script. Since: 2.66
+
+
+ Yezidi. Since: 2.66
+
+
+ Cypro-Minoan. Since: 2.72
+
+
+ Old Uyghur. Since: 2.72
+
+
+ Tangsa. Since: 2.72
+
+
+ Toto. Since: 2.72
+
+
+ Vithkuqi. Since: 2.72
+
+
+ Mathematical notation. Since: 2.72
+
+
+ Kawi. Since 2.74
+
+
+ Nag Mundari. Since 2.74
+
+
+
+ These are the possible character classifications from the
+Unicode specification.
+See [Unicode Character Database](http://www.unicode.org/reports/tr44/#General_Category_Values).
+
+
+ General category "Other, Control" (Cc)
+
+
+ General category "Other, Format" (Cf)
+
+
+ General category "Other, Not Assigned" (Cn)
+
+
+ General category "Other, Private Use" (Co)
+
+
+ General category "Other, Surrogate" (Cs)
+
+
+ General category "Letter, Lowercase" (Ll)
+
+
+ General category "Letter, Modifier" (Lm)
+
+
+ General category "Letter, Other" (Lo)
+
+
+ General category "Letter, Titlecase" (Lt)
+
+
+ General category "Letter, Uppercase" (Lu)
+
+
+ General category "Mark, Spacing" (Mc)
+
+
+ General category "Mark, Enclosing" (Me)
+
+
+ General category "Mark, Nonspacing" (Mn)
+
+
+ General category "Number, Decimal Digit" (Nd)
+
+
+ General category "Number, Letter" (Nl)
+
+
+ General category "Number, Other" (No)
+
+
+ General category "Punctuation, Connector" (Pc)
+
+
+ General category "Punctuation, Dash" (Pd)
+
+
+ General category "Punctuation, Close" (Pe)
+
+
+ General category "Punctuation, Final quote" (Pf)
+
+
+ General category "Punctuation, Initial quote" (Pi)
+
+
+ General category "Punctuation, Other" (Po)
+
+
+ General category "Punctuation, Open" (Ps)
+
+
+ General category "Symbol, Currency" (Sc)
+
+
+ General category "Symbol, Modifier" (Sk)
+
+
+ General category "Symbol, Math" (Sm)
+
+
+ General category "Symbol, Other" (So)
+
+
+ General category "Separator, Line" (Zl)
+
+
+ General category "Separator, Paragraph" (Zp)
+
+
+ General category "Separator, Space" (Zs)
+
+
+
+ The type of functions to be called when a UNIX fd watch source
+triggers.
+
+
+ %FALSE if the source should be removed
+
+
+
+
+ the fd that triggered the event
+
+
+
+ the IO conditions reported on @fd
+
+
+
+ user data passed to g_unix_fd_add()
+
+
+
+
+
+ The #GUri type and related functions can be used to parse URIs into
+their components, and build valid URIs from individual components.
+
+Note that #GUri scope is to help manipulate URIs in various applications,
+following [RFC 3986](https://tools.ietf.org/html/rfc3986). In particular,
+it doesn't intend to cover web browser needs, and doesn't implement the
+[WHATWG URL](https://url.spec.whatwg.org/) standard. No APIs are provided to
+help prevent
+[homograph attacks](https://en.wikipedia.org/wiki/IDN_homograph_attack), so
+#GUri is not suitable for formatting URIs for display to the user for making
+security-sensitive decisions.
+
+## Relative and absolute URIs # {#relative-absolute-uris}
+
+As defined in [RFC 3986](https://tools.ietf.org/html/rfc3986#section-4), the
+hierarchical nature of URIs means that they can either be ‘relative
+references’ (sometimes referred to as ‘relative URIs’) or ‘URIs’ (for
+clarity, ‘URIs’ are referred to in this documentation as
+‘absolute URIs’ — although
+[in constrast to RFC 3986](https://tools.ietf.org/html/rfc3986#section-4.3),
+fragment identifiers are always allowed).
+
+Relative references have one or more components of the URI missing. In
+particular, they have no scheme. Any other component, such as hostname,
+query, etc. may be missing, apart from a path, which has to be specified (but
+may be empty). The path may be relative, starting with `./` rather than `/`.
+
+For example, a valid relative reference is `./path?query`,
+`/?query#fragment` or `//example.com`.
+
+Absolute URIs have a scheme specified. Any other components of the URI which
+are missing are specified as explicitly unset in the URI, rather than being
+resolved relative to a base URI using g_uri_parse_relative().
+
+For example, a valid absolute URI is `file:///home/bob` or
+`https://search.com?query=string`.
+
+A #GUri instance is always an absolute URI. A string may be an absolute URI
+or a relative reference; see the documentation for individual functions as to
+what forms they accept.
+
+## Parsing URIs
+
+The most minimalist APIs for parsing URIs are g_uri_split() and
+g_uri_split_with_user(). These split a URI into its component
+parts, and return the parts; the difference between the two is that
+g_uri_split() treats the ‘userinfo’ component of the URI as a
+single element, while g_uri_split_with_user() can (depending on the
+#GUriFlags you pass) treat it as containing a username, password,
+and authentication parameters. Alternatively, g_uri_split_network()
+can be used when you are only interested in the components that are
+needed to initiate a network connection to the service (scheme,
+host, and port).
+
+g_uri_parse() is similar to g_uri_split(), but instead of returning
+individual strings, it returns a #GUri structure (and it requires
+that the URI be an absolute URI).
+
+g_uri_resolve_relative() and g_uri_parse_relative() allow you to
+resolve a relative URI relative to a base URI.
+g_uri_resolve_relative() takes two strings and returns a string,
+and g_uri_parse_relative() takes a #GUri and a string and returns a
+#GUri.
+
+All of the parsing functions take a #GUriFlags argument describing
+exactly how to parse the URI; see the documentation for that type
+for more details on the specific flags that you can pass. If you
+need to choose different flags based on the type of URI, you can
+use g_uri_peek_scheme() on the URI string to check the scheme
+first, and use that to decide what flags to parse it with.
+
+For example, you might want to use %G_URI_PARAMS_WWW_FORM when parsing the
+params for a web URI, so compare the result of g_uri_peek_scheme() against
+`http` and `https`.
+
+## Building URIs
+
+g_uri_join() and g_uri_join_with_user() can be used to construct
+valid URI strings from a set of component strings. They are the
+inverse of g_uri_split() and g_uri_split_with_user().
+
+Similarly, g_uri_build() and g_uri_build_with_user() can be used to
+construct a #GUri from a set of component strings.
+
+As with the parsing functions, the building functions take a
+#GUriFlags argument. In particular, it is important to keep in mind
+whether the URI components you are using are already `%`-encoded. If so,
+you must pass the %G_URI_FLAGS_ENCODED flag.
+
+## `file://` URIs
+
+Note that Windows and Unix both define special rules for parsing
+`file://` URIs (involving non-UTF-8 character sets on Unix, and the
+interpretation of path separators on Windows). #GUri does not
+implement these rules. Use g_filename_from_uri() and
+g_filename_to_uri() if you want to properly convert between
+`file://` URIs and local filenames.
+
+## URI Equality
+
+Note that there is no `g_uri_equal ()` function, because comparing
+URIs usefully requires scheme-specific knowledge that #GUri does
+not have. #GUri can help with normalization if you use the various
+encoded #GUriFlags as well as %G_URI_FLAGS_SCHEME_NORMALIZE however
+it is not comprehensive.
+For example, `data:,foo` and `data:;base64,Zm9v` resolve to the same
+thing according to the `data:` URI specification which GLib does not
+handle.
+
+
+ Gets @uri's authentication parameters, which may contain
+`%`-encoding, depending on the flags with which @uri was created.
+(If @uri was not created with %G_URI_FLAGS_HAS_AUTH_PARAMS then this will
+be %NULL.)
+
+Depending on the URI scheme, g_uri_parse_params() may be useful for
+further parsing this information.
+
+
+ @uri's authentication parameters.
+
+
+
+
+ a #GUri
+
+
+
+
+
+ Gets @uri's flags set upon construction.
+
+
+ @uri's flags.
+
+
+
+
+ a #GUri
+
+
+
+
+
+ Gets @uri's fragment, which may contain `%`-encoding, depending on
+the flags with which @uri was created.
+
+
+ @uri's fragment.
+
+
+
+
+ a #GUri
+
+
+
+
+
+ Gets @uri's host. This will never have `%`-encoded characters,
+unless it is non-UTF-8 (which can only be the case if @uri was
+created with %G_URI_FLAGS_NON_DNS).
+
+If @uri contained an IPv6 address literal, this value will be just
+that address, without the brackets around it that are necessary in
+the string form of the URI. Note that in this case there may also
+be a scope ID attached to the address. Eg, `fe80::1234%``em1` (or
+`fe80::1234%``25em1` if the string is still encoded).
+
+
+ @uri's host.
+
+
+
+
+ a #GUri
+
+
+
+
+
+ Gets @uri's password, which may contain `%`-encoding, depending on
+the flags with which @uri was created. (If @uri was not created
+with %G_URI_FLAGS_HAS_PASSWORD then this will be %NULL.)
+
+
+ @uri's password.
+
+
+
+
+ a #GUri
+
+
+
+
+
+ Gets @uri's path, which may contain `%`-encoding, depending on the
+flags with which @uri was created.
+
+
+ @uri's path.
+
+
+
+
+ a #GUri
+
+
+
+
+
+ Gets @uri's port.
+
+
+ @uri's port, or `-1` if no port was specified.
+
+
+
+
+ a #GUri
+
+
+
+
+
+ Gets @uri's query, which may contain `%`-encoding, depending on the
+flags with which @uri was created.
+
+For queries consisting of a series of `name=value` parameters,
+#GUriParamsIter or g_uri_parse_params() may be useful.
+
+
+ @uri's query.
+
+
+
+
+ a #GUri
+
+
+
+
+
+ Gets @uri's scheme. Note that this will always be all-lowercase,
+regardless of the string or strings that @uri was created from.
+
+
+ @uri's scheme.
+
+
+
+
+ a #GUri
+
+
+
+
+
+ Gets the ‘username’ component of @uri's userinfo, which may contain
+`%`-encoding, depending on the flags with which @uri was created.
+If @uri was not created with %G_URI_FLAGS_HAS_PASSWORD or
+%G_URI_FLAGS_HAS_AUTH_PARAMS, this is the same as g_uri_get_userinfo().
+
+
+ @uri's user.
+
+
+
+
+ a #GUri
+
+
+
+
+
+ Gets @uri's userinfo, which may contain `%`-encoding, depending on
+the flags with which @uri was created.
+
+
+ @uri's userinfo.
+
+
+
+
+ a #GUri
+
+
+
+
+
+ Parses @uri_ref according to @flags and, if it is a
+[relative URI][relative-absolute-uris], resolves it relative to @base_uri.
+If the result is not a valid absolute URI, it will be discarded, and an error
+returned.
+
+
+ a new #GUri, or NULL on error.
+
+
+
+
+ a base absolute URI
+
+
+
+ a string representing a relative or absolute URI
+
+
+
+ flags describing how to parse @uri_ref
+
+
+
+
+
+ Increments the reference count of @uri by one.
+
+
+ @uri
+
+
+
+
+ a #GUri
+
+
+
+
+
+ Returns a string representing @uri.
+
+This is not guaranteed to return a string which is identical to the
+string that @uri was parsed from. However, if the source URI was
+syntactically correct (according to RFC 3986), and it was parsed
+with %G_URI_FLAGS_ENCODED, then g_uri_to_string() is guaranteed to return
+a string which is at least semantically equivalent to the source
+URI (according to RFC 3986).
+
+If @uri might contain sensitive details, such as authentication parameters,
+or private data in its query string, and the returned string is going to be
+logged, then consider using g_uri_to_string_partial() to redact parts.
+
+
+ a string representing @uri,
+ which the caller must free.
+
+
+
+
+ a #GUri
+
+
+
+
+
+ Returns a string representing @uri, subject to the options in
+@flags. See g_uri_to_string() and #GUriHideFlags for more details.
+
+
+ a string representing
+ @uri, which the caller must free.
+
+
+
+
+ a #GUri
+
+
+
+ flags describing what parts of @uri to hide
+
+
+
+
+
+ Atomically decrements the reference count of @uri by one.
+
+When the reference count reaches zero, the resources allocated by
+@uri are freed
+
+
+
+
+
+
+ a #GUri
+
+
+
+
+
+ Creates a new #GUri from the given components according to @flags.
+
+See also g_uri_build_with_user(), which allows specifying the
+components of the "userinfo" separately.
+
+
+ a new #GUri
+
+
+
+
+ flags describing how to build the #GUri
+
+
+
+ the URI scheme
+
+
+
+ the userinfo component, or %NULL
+
+
+
+ the host component, or %NULL
+
+
+
+ the port, or `-1`
+
+
+
+ the path component
+
+
+
+ the query component, or %NULL
+
+
+
+ the fragment, or %NULL
+
+
+
+
+
+ Creates a new #GUri from the given components according to @flags
+(%G_URI_FLAGS_HAS_PASSWORD is added unconditionally). The @flags must be
+coherent with the passed values, in particular use `%`-encoded values with
+%G_URI_FLAGS_ENCODED.
+
+In contrast to g_uri_build(), this allows specifying the components
+of the ‘userinfo’ field separately. Note that @user must be non-%NULL
+if either @password or @auth_params is non-%NULL.
+
+
+ a new #GUri
+
+
+
+
+ flags describing how to build the #GUri
+
+
+
+ the URI scheme
+
+
+
+ the user component of the userinfo, or %NULL
+
+
+
+ the password component of the userinfo, or %NULL
+
+
+
+ the auth params of the userinfo, or %NULL
+
+
+
+ the host component, or %NULL
+
+
+
+ the port, or `-1`
+
+
+
+ the path component
+
+
+
+ the query component, or %NULL
+
+
+
+ the fragment, or %NULL
+
+
+
+
+
+
+
+
+
+
+ Escapes arbitrary data for use in a URI.
+
+Normally all characters that are not ‘unreserved’ (i.e. ASCII
+alphanumerical characters plus dash, dot, underscore and tilde) are
+escaped. But if you specify characters in @reserved_chars_allowed
+they are not escaped. This is useful for the ‘reserved’ characters
+in the URI specification, since those are allowed unescaped in some
+portions of a URI.
+
+Though technically incorrect, this will also allow escaping nul
+bytes as `%``00`.
+
+
+ an escaped version of @unescaped.
+ The returned string should be freed when no longer needed.
+
+
+
+
+ the unescaped input data.
+
+
+
+
+
+ the length of @unescaped
+
+
+
+ a string of reserved
+ characters that are allowed to be used, or %NULL.
+
+
+
+
+
+ Escapes a string for use in a URI.
+
+Normally all characters that are not "unreserved" (i.e. ASCII
+alphanumerical characters plus dash, dot, underscore and tilde) are
+escaped. But if you specify characters in @reserved_chars_allowed
+they are not escaped. This is useful for the "reserved" characters
+in the URI specification, since those are allowed unescaped in some
+portions of a URI.
+
+
+ an escaped version of @unescaped. The
+returned string should be freed when no longer needed.
+
+
+
+
+ the unescaped input string.
+
+
+
+ a string of reserved
+ characters that are allowed to be used, or %NULL.
+
+
+
+ %TRUE if the result can include UTF-8 characters.
+
+
+
+
+
+ Parses @uri_string according to @flags, to determine whether it is a valid
+[absolute URI][relative-absolute-uris], i.e. it does not need to be resolved
+relative to another URI using g_uri_parse_relative().
+
+If it’s not a valid URI, an error is returned explaining how it’s invalid.
+
+See g_uri_split(), and the definition of #GUriFlags, for more
+information on the effect of @flags.
+
+
+ %TRUE if @uri_string is a valid absolute URI, %FALSE on error.
+
+
+
+
+ a string containing an absolute URI
+
+
+
+ flags for parsing @uri_string
+
+
+
+
+
+ Joins the given components together according to @flags to create
+an absolute URI string. @path may not be %NULL (though it may be the empty
+string).
+
+When @host is present, @path must either be empty or begin with a slash (`/`)
+character. When @host is not present, @path cannot begin with two slash
+ characters (`//`). See
+[RFC 3986, section 3](https://tools.ietf.org/html/rfc3986#section-3).
+
+See also g_uri_join_with_user(), which allows specifying the
+components of the ‘userinfo’ separately.
+
+%G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set
+in @flags.
+
+
+ an absolute URI string
+
+
+
+
+ flags describing how to build the URI string
+
+
+
+ the URI scheme, or %NULL
+
+
+
+ the userinfo component, or %NULL
+
+
+
+ the host component, or %NULL
+
+
+
+ the port, or `-1`
+
+
+
+ the path component
+
+
+
+ the query component, or %NULL
+
+
+
+ the fragment, or %NULL
+
+
+
+
+
+ Joins the given components together according to @flags to create
+an absolute URI string. @path may not be %NULL (though it may be the empty
+string).
+
+In contrast to g_uri_join(), this allows specifying the components
+of the ‘userinfo’ separately. It otherwise behaves the same.
+
+%G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set
+in @flags.
+
+
+ an absolute URI string
+
+
+
+
+ flags describing how to build the URI string
+
+
+
+ the URI scheme, or %NULL
+
+
+
+ the user component of the userinfo, or %NULL
+
+
+
+ the password component of the userinfo, or
+ %NULL
+
+
+
+ the auth params of the userinfo, or
+ %NULL
+
+
+
+ the host component, or %NULL
+
+
+
+ the port, or `-1`
+
+
+
+ the path component
+
+
+
+ the query component, or %NULL
+
+
+
+ the fragment, or %NULL
+
+
+
+
+
+ Splits an URI list conforming to the text/uri-list
+mime type defined in RFC 2483 into individual URIs,
+discarding any comments. The URIs are not validated.
+
+
+ a newly allocated %NULL-terminated list
+ of strings holding the individual URIs. The array should be freed
+ with g_strfreev().
+
+
+
+
+
+
+ an URI list
+
+
+
+
+
+ Parses @uri_string according to @flags. If the result is not a
+valid [absolute URI][relative-absolute-uris], it will be discarded, and an
+error returned.
+
+
+ a new #GUri, or NULL on error.
+
+
+
+
+ a string representing an absolute URI
+
+
+
+ flags describing how to parse @uri_string
+
+
+
+
+
+ Many URI schemes include one or more attribute/value pairs as part of the URI
+value. This method can be used to parse them into a hash table. When an
+attribute has multiple occurrences, the last value is the final returned
+value. If you need to handle repeated attributes differently, use
+#GUriParamsIter.
+
+The @params string is assumed to still be `%`-encoded, but the returned
+values will be fully decoded. (Thus it is possible that the returned values
+may contain `=` or @separators, if the value was encoded in the input.)
+Invalid `%`-encoding is treated as with the %G_URI_FLAGS_PARSE_RELAXED
+rules for g_uri_parse(). (However, if @params is the path or query string
+from a #GUri that was parsed without %G_URI_FLAGS_PARSE_RELAXED and
+%G_URI_FLAGS_ENCODED, then you already know that it does not contain any
+invalid encoding.)
+
+%G_URI_PARAMS_WWW_FORM is handled as documented for g_uri_params_iter_init().
+
+If %G_URI_PARAMS_CASE_INSENSITIVE is passed to @flags, attributes will be
+compared case-insensitively, so a params string `attr=123&Attr=456` will only
+return a single attribute–value pair, `Attr=456`. Case will be preserved in
+the returned attributes.
+
+If @params cannot be parsed (for example, it contains two @separators
+characters in a row), then @error is set and %NULL is returned.
+
+
+
+ A hash table of attribute/value pairs, with both names and values
+ fully-decoded; or %NULL on error.
+
+
+
+
+
+
+
+ a `%`-encoded string containing `attribute=value`
+ parameters
+
+
+
+ the length of @params, or `-1` if it is nul-terminated
+
+
+
+ the separator byte character set between parameters. (usually
+ `&`, but sometimes `;` or both `&;`). Note that this function works on
+ bytes not characters, so it can't be used to delimit UTF-8 strings for
+ anything but ASCII characters. You may pass an empty set, in which case
+ no splitting will occur.
+
+
+
+ flags to modify the way the parameters are handled.
+
+
+
+
+
+ Gets the scheme portion of a URI string.
+[RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme
+as:
+|[
+URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
+]|
+Common schemes include `file`, `https`, `svn+ssh`, etc.
+
+
+ The ‘scheme’ component of the URI, or
+ %NULL on error. The returned string should be freed when no longer needed.
+
+
+
+
+ a valid URI.
+
+
+
+
+
+ Gets the scheme portion of a URI string.
+[RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme
+as:
+|[
+URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
+]|
+Common schemes include `file`, `https`, `svn+ssh`, etc.
+
+Unlike g_uri_parse_scheme(), the returned scheme is normalized to
+all-lowercase and does not need to be freed.
+
+
+ The ‘scheme’ component of the URI, or
+ %NULL on error. The returned string is normalized to all-lowercase, and
+ interned via g_intern_string(), so it does not need to be freed.
+
+
+
+
+ a valid URI.
+
+
+
+
+
+ Parses @uri_ref according to @flags and, if it is a
+[relative URI][relative-absolute-uris], resolves it relative to
+@base_uri_string. If the result is not a valid absolute URI, it will be
+discarded, and an error returned.
+
+(If @base_uri_string is %NULL, this just returns @uri_ref, or
+%NULL if @uri_ref is invalid or not absolute.)
+
+
+ the resolved URI string,
+or NULL on error.
+
+
+
+
+ a string representing a base URI
+
+
+
+ a string representing a relative or absolute URI
+
+
+
+ flags describing how to parse @uri_ref
+
+
+
+
+
+ Parses @uri_ref (which can be an
+[absolute or relative URI][relative-absolute-uris]) according to @flags, and
+returns the pieces. Any component that doesn't appear in @uri_ref will be
+returned as %NULL (but note that all URIs always have a path component,
+though it may be the empty string).
+
+If @flags contains %G_URI_FLAGS_ENCODED, then `%`-encoded characters in
+@uri_ref will remain encoded in the output strings. (If not,
+then all such characters will be decoded.) Note that decoding will
+only work if the URI components are ASCII or UTF-8, so you will
+need to use %G_URI_FLAGS_ENCODED if they are not.
+
+Note that the %G_URI_FLAGS_HAS_PASSWORD and
+%G_URI_FLAGS_HAS_AUTH_PARAMS @flags are ignored by g_uri_split(),
+since it always returns only the full userinfo; use
+g_uri_split_with_user() if you want it split up.
+
+
+ %TRUE if @uri_ref parsed successfully, %FALSE
+ on error.
+
+
+
+
+ a string containing a relative or absolute URI
+
+
+
+ flags for parsing @uri_ref
+
+
+
+ on return, contains
+ the scheme (converted to lowercase), or %NULL
+
+
+
+ on return, contains
+ the userinfo, or %NULL
+
+
+
+ on return, contains the
+ host, or %NULL
+
+
+
+ on return, contains the
+ port, or `-1`
+
+
+
+ on return, contains the
+ path
+
+
+
+ on return, contains the
+ query, or %NULL
+
+
+
+ on return, contains
+ the fragment, or %NULL
+
+
+
+
+
+ Parses @uri_string (which must be an [absolute URI][relative-absolute-uris])
+according to @flags, and returns the pieces relevant to connecting to a host.
+See the documentation for g_uri_split() for more details; this is
+mostly a wrapper around that function with simpler arguments.
+However, it will return an error if @uri_string is a relative URI,
+or does not contain a hostname component.
+
+
+ %TRUE if @uri_string parsed successfully,
+ %FALSE on error.
+
+
+
+
+ a string containing an absolute URI
+
+
+
+ flags for parsing @uri_string
+
+
+
+ on return, contains
+ the scheme (converted to lowercase), or %NULL
+
+
+
+ on return, contains the
+ host, or %NULL
+
+
+
+ on return, contains the
+ port, or `-1`
+
+
+
+
+
+ Parses @uri_ref (which can be an
+[absolute or relative URI][relative-absolute-uris]) according to @flags, and
+returns the pieces. Any component that doesn't appear in @uri_ref will be
+returned as %NULL (but note that all URIs always have a path component,
+though it may be the empty string).
+
+See g_uri_split(), and the definition of #GUriFlags, for more
+information on the effect of @flags. Note that @password will only
+be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and
+@auth_params will only be parsed out if @flags contains
+%G_URI_FLAGS_HAS_AUTH_PARAMS.
+
+
+ %TRUE if @uri_ref parsed successfully, %FALSE
+ on error.
+
+
+
+
+ a string containing a relative or absolute URI
+
+
+
+ flags for parsing @uri_ref
+
+
+
+ on return, contains
+ the scheme (converted to lowercase), or %NULL
+
+
+
+ on return, contains
+ the user, or %NULL
+
+
+
+ on return, contains
+ the password, or %NULL
+
+
+
+ on return, contains
+ the auth_params, or %NULL
+
+
+
+ on return, contains the
+ host, or %NULL
+
+
+
+ on return, contains the
+ port, or `-1`
+
+
+
+ on return, contains the
+ path
+
+
+
+ on return, contains the
+ query, or %NULL
+
+
+
+ on return, contains
+ the fragment, or %NULL
+
+
+
+
+
+ Unescapes a segment of an escaped string as binary data.
+
+Note that in contrast to g_uri_unescape_string(), this does allow
+nul bytes to appear in the output.
+
+If any of the characters in @illegal_characters appears as an escaped
+character in @escaped_string, then that is an error and %NULL will be
+returned. This is useful if you want to avoid for instance having a slash
+being expanded in an escaped path element, which might confuse pathname
+handling.
+
+
+ an unescaped version of @escaped_string
+ or %NULL on error (if decoding failed, using %G_URI_ERROR_FAILED error
+ code). The returned #GBytes should be unreffed when no longer needed.
+
+
+
+
+ A URI-escaped string
+
+
+
+ the length (in bytes) of @escaped_string to escape, or `-1` if it
+ is nul-terminated.
+
+
+
+ a string of illegal characters
+ not to be allowed, or %NULL.
+
+
+
+
+
+ Unescapes a segment of an escaped string.
+
+If any of the characters in @illegal_characters or the NUL
+character appears as an escaped character in @escaped_string, then
+that is an error and %NULL will be returned. This is useful if you
+want to avoid for instance having a slash being expanded in an
+escaped path element, which might confuse pathname handling.
+
+Note: `NUL` byte is not accepted in the output, in contrast to
+g_uri_unescape_bytes().
+
+
+ an unescaped version of @escaped_string,
+or %NULL on error. The returned string should be freed when no longer
+needed. As a special case if %NULL is given for @escaped_string, this
+function will return %NULL.
+
+
+
+
+ A string, may be %NULL
+
+
+
+ Pointer to end of @escaped_string,
+ may be %NULL
+
+
+
+ An optional string of illegal
+ characters not to be allowed, may be %NULL
+
+
+
+
+
+ Unescapes a whole escaped string.
+
+If any of the characters in @illegal_characters or the NUL
+character appears as an escaped character in @escaped_string, then
+that is an error and %NULL will be returned. This is useful if you
+want to avoid for instance having a slash being expanded in an
+escaped path element, which might confuse pathname handling.
+
+
+ an unescaped version of @escaped_string.
+The returned string should be freed when no longer needed.
+
+
+
+
+ an escaped string to be unescaped.
+
+
+
+ a string of illegal characters
+ not to be allowed, or %NULL.
+
+
+
+
+
+
+ Error codes returned by #GUri methods.
+
+
+ Generic error if no more specific error is available.
+ See the error message for details.
+
+
+ The scheme of a URI could not be parsed.
+
+
+ The user/userinfo of a URI could not be parsed.
+
+
+ The password of a URI could not be parsed.
+
+
+ The authentication parameters of a URI could not be parsed.
+
+
+ The host of a URI could not be parsed.
+
+
+ The port of a URI could not be parsed.
+
+
+ The path of a URI could not be parsed.
+
+
+ The query of a URI could not be parsed.
+
+
+ The fragment of a URI could not be parsed.
+
+
+
+ Flags that describe a URI.
+
+When parsing a URI, if you need to choose different flags based on
+the type of URI, you can use g_uri_peek_scheme() on the URI string
+to check the scheme first, and use that to decide what flags to
+parse it with.
+
+
+ No flags set.
+
+
+ Parse the URI more relaxedly than the
+ [RFC 3986](https://tools.ietf.org/html/rfc3986) grammar specifies,
+ fixing up or ignoring common mistakes in URIs coming from external
+ sources. This is also needed for some obscure URI schemes where `;`
+ separates the host from the path. Don’t use this flag unless you need to.
+
+
+ The userinfo field may contain a password,
+ which will be separated from the username by `:`.
+
+
+ The userinfo may contain additional
+ authentication-related parameters, which will be separated from
+ the username and/or password by `;`.
+
+
+ When parsing a URI, this indicates that `%`-encoded
+ characters in the userinfo, path, query, and fragment fields
+ should not be decoded. (And likewise the host field if
+ %G_URI_FLAGS_NON_DNS is also set.) When building a URI, it indicates
+ that you have already `%`-encoded the components, and so #GUri
+ should not do any encoding itself.
+
+
+ The host component should not be assumed to be a
+ DNS hostname or IP address (for example, for `smb` URIs with NetBIOS
+ hostnames).
+
+
+ Same as %G_URI_FLAGS_ENCODED, for the query
+ field only.
+
+
+ Same as %G_URI_FLAGS_ENCODED, for the path only.
+
+
+ Same as %G_URI_FLAGS_ENCODED, for the
+ fragment only.
+
+
+ A scheme-based normalization will be applied.
+ For example, when parsing an HTTP URI changing omitted path to `/` and
+ omitted port to `80`; and when building a URI, changing empty path to `/`
+ and default port `80`). This only supports a subset of known schemes. (Since: 2.68)
+
+
+
+ Flags describing what parts of the URI to hide in
+g_uri_to_string_partial(). Note that %G_URI_HIDE_PASSWORD and
+%G_URI_HIDE_AUTH_PARAMS will only work if the #GUri was parsed with
+the corresponding flags.
+
+
+ No flags set.
+
+
+ Hide the userinfo.
+
+
+ Hide the password.
+
+
+ Hide the auth_params.
+
+
+ Hide the query.
+
+
+ Hide the fragment.
+
+
+
+ Flags modifying the way parameters are handled by g_uri_parse_params() and
+#GUriParamsIter.
+
+
+ No flags set.
+
+
+ Parameter names are case insensitive.
+
+
+ Replace `+` with space character. Only useful for
+ URLs on the web, using the `https` or `http` schemas.
+
+
+ See %G_URI_FLAGS_PARSE_RELAXED.
+
+
+
+ Many URI schemes include one or more attribute/value pairs as part of the URI
+value. For example `scheme://server/path?query=string&is=there` has two
+attributes – `query=string` and `is=there` – in its query part.
+
+A #GUriParamsIter structure represents an iterator that can be used to
+iterate over the attribute/value pairs of a URI query string. #GUriParamsIter
+structures are typically allocated on the stack and then initialized with
+g_uri_params_iter_init(). See the documentation for g_uri_params_iter_init()
+for a usage example.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Initializes an attribute/value pair iterator.
+
+The iterator keeps pointers to the @params and @separators arguments, those
+variables must thus outlive the iterator and not be modified during the
+iteration.
+
+If %G_URI_PARAMS_WWW_FORM is passed in @flags, `+` characters in the param
+string will be replaced with spaces in the output. For example, `foo=bar+baz`
+will give attribute `foo` with value `bar baz`. This is commonly used on the
+web (the `https` and `http` schemes only), but is deprecated in favour of
+the equivalent of encoding spaces as `%20`.
+
+Unlike with g_uri_parse_params(), %G_URI_PARAMS_CASE_INSENSITIVE has no
+effect if passed to @flags for g_uri_params_iter_init(). The caller is
+responsible for doing their own case-insensitive comparisons.
+
+|[<!-- language="C" -->
+GUriParamsIter iter;
+GError *error = NULL;
+gchar *unowned_attr, *unowned_value;
+
+g_uri_params_iter_init (&iter, "foo=bar&baz=bar&Foo=frob&baz=bar2", -1, "&", G_URI_PARAMS_NONE);
+while (g_uri_params_iter_next (&iter, &unowned_attr, &unowned_value, &error))
+ {
+ g_autofree gchar *attr = g_steal_pointer (&unowned_attr);
+ g_autofree gchar *value = g_steal_pointer (&unowned_value);
+ // do something with attr and value; this code will be called 4 times
+ // for the params string in this example: once with attr=foo and value=bar,
+ // then with baz/bar, then Foo/frob, then baz/bar2.
+ }
+if (error)
+ // handle parsing error
+]|
+
+
+
+
+
+
+ an uninitialized #GUriParamsIter
+
+
+
+ a `%`-encoded string containing `attribute=value`
+ parameters
+
+
+
+ the length of @params, or `-1` if it is nul-terminated
+
+
+
+ the separator byte character set between parameters. (usually
+ `&`, but sometimes `;` or both `&;`). Note that this function works on
+ bytes not characters, so it can't be used to delimit UTF-8 strings for
+ anything but ASCII characters. You may pass an empty set, in which case
+ no splitting will occur.
+
+
+
+ flags to modify the way the parameters are handled.
+
+
+
+
+
+ Advances @iter and retrieves the next attribute/value. %FALSE is returned if
+an error has occurred (in which case @error is set), or if the end of the
+iteration is reached (in which case @attribute and @value are set to %NULL
+and the iterator becomes invalid). If %TRUE is returned,
+g_uri_params_iter_next() may be called again to receive another
+attribute/value pair.
+
+Note that the same @attribute may be returned multiple times, since URIs
+allow repeated attributes.
+
+
+ %FALSE if the end of the parameters has been reached or an error was
+ encountered. %TRUE otherwise.
+
+
+
+
+ an initialized #GUriParamsIter
+
+
+
+ on return, contains
+ the attribute, or %NULL.
+
+
+
+ on return, contains
+ the value, or %NULL.
+
+
+
+
+
+
+ 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.
+
+
+ the user's Desktop directory
+
+
+ the user's Documents directory
+
+
+ the user's Downloads directory
+
+
+ the user's Music directory
+
+
+ the user's Pictures directory
+
+
+ the user's shared directory
+
+
+ the user's Templates directory
+
+
+ the user's Movies directory
+
+
+ the number of enum values
+
+
+
+ A stack-allocated #GVariantBuilder must be initialized if it is
+used together with g_auto() to avoid warnings or crashes if
+function returns before g_variant_builder_init() is called on the
+builder.
+
+This macro can be used as initializer instead of an
+explicit zeroing a variable when declaring it and a following
+g_variant_builder_init(), but it cannot be assigned to a variable.
+
+The passed @variant_type should be a static GVariantType to avoid
+lifetime issues, as copying the @variant_type does not happen in
+the G_VARIANT_BUILDER_INIT() call, but rather in functions that
+make sure that #GVariantBuilder is valid.
+
+|[<!-- language="C" -->
+ g_auto(GVariantBuilder) builder = G_VARIANT_BUILDER_INIT (G_VARIANT_TYPE_BYTESTRING);
+]|
+
+
+
+ a const GVariantType*
+
+
+
+
+ A stack-allocated #GVariantDict must be initialized if it is used
+together with g_auto() to avoid warnings or crashes if function
+returns before g_variant_dict_init() is called on the builder.
+
+This macro can be used as initializer instead of an explicit
+zeroing a variable when declaring it and a following
+g_variant_dict_init(), but it cannot be assigned to a variable.
+
+The passed @asv has to live long enough for #GVariantDict to gather
+the entries from, as the gathering does not happen in the
+G_VARIANT_DICT_INIT() call, but rather in functions that make sure
+that #GVariantDict is valid. In context where the initialization
+value has to be a constant expression, the only possible value of
+@asv is %NULL. It is still possible to call g_variant_dict_init()
+safely with a different @asv right after the variable was
+initialized with G_VARIANT_DICT_INIT().
+
+|[<!-- language="C" -->
+ g_autoptr(GVariant) variant = get_asv_variant ();
+ g_auto(GVariantDict) dict = G_VARIANT_DICT_INIT (variant);
+]|
+
+
+
+ a GVariant*
+
+
+
+
+ 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. If in doubt, use g_variant_type_string_is_valid() to
+check if the string is valid.
+
+Since 2.24
+
+
+
+ a well-formed #GVariantType type string
+
+
+
+
+
+
+
+
+ A macro that should be defined by the user prior to including
+the glib.h header.
+The definition should be one of the predefined GLib version
+macros: %GLIB_VERSION_2_26, %GLIB_VERSION_2_28,...
+
+This macro defines the earliest version of GLib that the package is
+required to be able to compile against.
+
+If the compiler is configured to warn about the use of deprecated
+functions, then using functions that were deprecated in version
+%GLIB_VERSION_MIN_REQUIRED or earlier will cause warnings (but
+using functions deprecated in later releases will not).
+
+
+
+
+ #GVariant is a variant datatype; it can contain one or more values
+along with information about the type of the values.
+
+A #GVariant may contain simple types, like an integer, or a boolean value;
+or complex types, like an array of two strings, or a dictionary of key
+value pairs. A #GVariant is also immutable: once it's been created neither
+its type nor its content can be modified further.
+
+GVariant is useful whenever data needs to be serialized, for example when
+sending method parameters in D-Bus, or when saving settings using GSettings.
+
+When creating a new #GVariant, you pass the data you want to store in it
+along with a string representing the type of data you wish to pass to it.
+
+For instance, if you want to create a #GVariant holding an integer value you
+can use:
+
+|[<!-- language="C" -->
+ GVariant *v = g_variant_new ("u", 40);
+]|
+
+The string "u" in the first argument tells #GVariant that the data passed to
+the constructor (40) is going to be an unsigned integer.
+
+More advanced examples of #GVariant in use can be found in documentation for
+[GVariant format strings][gvariant-format-strings-pointers].
+
+The range of possible values is determined by the type.
+
+The type system used by #GVariant is #GVariantType.
+
+#GVariant instances always have a type and a value (which are given
+at construction time). The type and value of a #GVariant instance
+can never change other than by the #GVariant itself being
+destroyed. A #GVariant cannot contain a pointer.
+
+#GVariant is reference counted using g_variant_ref() and
+g_variant_unref(). #GVariant also has floating reference counts --
+see g_variant_ref_sink().
+
+#GVariant is completely threadsafe. A #GVariant instance can be
+concurrently accessed in any way from any number of threads without
+problems.
+
+#GVariant is heavily optimised for dealing with data in serialized
+form. It works particularly well with data located in memory-mapped
+files. It can perform nearly all deserialization operations in a
+small constant time, usually touching only a single memory page.
+Serialized #GVariant data can also be sent over the network.
+
+#GVariant is largely compatible with D-Bus. Almost all types of
+#GVariant instances can be sent over D-Bus. See #GVariantType for
+exceptions. (However, #GVariant's serialization format is not the same
+as the serialization format of a D-Bus message body: use #GDBusMessage,
+in the gio library, for those.)
+
+For space-efficiency, the #GVariant serialization format does not
+automatically include the variant's length, type or endianness,
+which must either be implied from context (such as knowledge that a
+particular file format always contains a little-endian
+%G_VARIANT_TYPE_VARIANT which occupies the whole length of the file)
+or supplied out-of-band (for instance, a length, type and/or endianness
+indicator could be placed at the beginning of a file, network message
+or network stream).
+
+A #GVariant's size is limited mainly by any lower level operating
+system constraints, such as the number of bits in #gsize. For
+example, it is reasonable to have a 2GB file mapped into memory
+with #GMappedFile, and call g_variant_new_from_data() on it.
+
+For convenience to C programmers, #GVariant features powerful
+varargs-based value construction and destruction. This feature is
+designed to be embedded in other libraries.
+
+There is a Python-inspired text language for describing #GVariant
+values. #GVariant includes a printer for this language and a parser
+with type inferencing.
+
+## Memory Use
+
+#GVariant tries to be quite efficient with respect to memory use.
+This section gives a rough idea of how much memory is used by the
+current implementation. The information here is subject to change
+in the future.
+
+The memory allocated by #GVariant can be grouped into 4 broad
+purposes: memory for serialized data, memory for the type
+information cache, buffer management memory and memory for the
+#GVariant structure itself.
+
+## Serialized Data Memory
+
+This is the memory that is used for storing GVariant data in
+serialized form. This is what would be sent over the network or
+what would end up on disk, not counting any indicator of the
+endianness, or of the length or type of the top-level variant.
+
+The amount of memory required to store a boolean is 1 byte. 16,
+32 and 64 bit integers and double precision floating point numbers
+use their "natural" size. Strings (including object path and
+signature strings) are stored with a nul terminator, and as such
+use the length of the string plus 1 byte.
+
+Maybe types use no space at all to represent the null value and
+use the same amount of space (sometimes plus one byte) as the
+equivalent non-maybe-typed value to represent the non-null case.
+
+Arrays use the amount of space required to store each of their
+members, concatenated. Additionally, if the items stored in an
+array are not of a fixed-size (ie: strings, other arrays, etc)
+then an additional framing offset is stored for each item. The
+size of this offset is either 1, 2 or 4 bytes depending on the
+overall size of the container. Additionally, extra padding bytes
+are added as required for alignment of child values.
+
+Tuples (including dictionary entries) use the amount of space
+required to store each of their members, concatenated, plus one
+framing offset (as per arrays) for each non-fixed-sized item in
+the tuple, except for the last one. Additionally, extra padding
+bytes are added as required for alignment of child values.
+
+Variants use the same amount of space as the item inside of the
+variant, plus 1 byte, plus the length of the type string for the
+item inside the variant.
+
+As an example, consider a dictionary mapping strings to variants.
+In the case that the dictionary is empty, 0 bytes are required for
+the serialization.
+
+If we add an item "width" that maps to the int32 value of 500 then
+we will use 4 byte to store the int32 (so 6 for the variant
+containing it) and 6 bytes for the string. The variant must be
+aligned to 8 after the 6 bytes of the string, so that's 2 extra
+bytes. 6 (string) + 2 (padding) + 6 (variant) is 14 bytes used
+for the dictionary entry. An additional 1 byte is added to the
+array as a framing offset making a total of 15 bytes.
+
+If we add another entry, "title" that maps to a nullable string
+that happens to have a value of null, then we use 0 bytes for the
+null value (and 3 bytes for the variant to contain it along with
+its type string) plus 6 bytes for the string. Again, we need 2
+padding bytes. That makes a total of 6 + 2 + 3 = 11 bytes.
+
+We now require extra padding between the two items in the array.
+After the 14 bytes of the first item, that's 2 bytes required.
+We now require 2 framing offsets for an extra two
+bytes. 14 + 2 + 11 + 2 = 29 bytes to encode the entire two-item
+dictionary.
+
+## Type Information Cache
+
+For each GVariant type that currently exists in the program a type
+information structure is kept in the type information cache. The
+type information structure is required for rapid deserialization.
+
+Continuing with the above example, if a #GVariant exists with the
+type "a{sv}" then a type information struct will exist for
+"a{sv}", "{sv}", "s", and "v". Multiple uses of the same type
+will share the same type information. Additionally, all
+single-digit types are stored in read-only static memory and do
+not contribute to the writable memory footprint of a program using
+#GVariant.
+
+Aside from the type information structures stored in read-only
+memory, there are two forms of type information. One is used for
+container types where there is a single element type: arrays and
+maybe types. The other is used for container types where there
+are multiple element types: tuples and dictionary entries.
+
+Array type info structures are 6 * sizeof (void *), plus the
+memory required to store the type string itself. This means that
+on 32-bit systems, the cache entry for "a{sv}" would require 30
+bytes of memory (plus malloc overhead).
+
+Tuple type info structures are 6 * sizeof (void *), plus 4 *
+sizeof (void *) for each item in the tuple, plus the memory
+required to store the type string itself. A 2-item tuple, for
+example, would have a type information structure that consumed
+writable memory in the size of 14 * sizeof (void *) (plus type
+string) This means that on 32-bit systems, the cache entry for
+"{sv}" would require 61 bytes of memory (plus malloc overhead).
+
+This means that in total, for our "a{sv}" example, 91 bytes of
+type information would be allocated.
+
+The type information cache, additionally, uses a #GHashTable to
+store and look up the cached items and stores a pointer to this
+hash table in static storage. The hash table is freed when there
+are zero items in the type cache.
+
+Although these sizes may seem large it is important to remember
+that a program will probably only have a very small number of
+different types of values in it and that only one type information
+structure is required for many different values of the same type.
+
+## Buffer Management Memory
+
+#GVariant uses an internal buffer management structure to deal
+with the various different possible sources of serialized data
+that it uses. The buffer is responsible for ensuring that the
+correct call is made when the data is no longer in use by
+#GVariant. This may involve a g_free() or a g_slice_free() or
+even g_mapped_file_unref().
+
+One buffer management structure is used for each chunk of
+serialized data. The size of the buffer management structure
+is 4 * (void *). On 32-bit systems, that's 16 bytes.
+
+## GVariant structure
+
+The size of a #GVariant structure is 6 * (void *). On 32-bit
+systems, that's 24 bytes.
+
+#GVariant structures only exist if they are explicitly created
+with API calls. For example, if a #GVariant is constructed out of
+serialized data for the example given above (with the dictionary)
+then although there are 9 individual values that comprise the
+entire dictionary (two keys, two values, two variants containing
+the values, two dictionary entries, plus the dictionary itself),
+only 1 #GVariant instance exists -- the one referring to the
+dictionary.
+
+If calls are made to start accessing the other values then
+#GVariant instances will exist for those values only for as long
+as they are in use (ie: until you call g_variant_unref()). The
+type information is shared. The serialized data and the buffer
+management structure for that serialized data is shared by the
+child.
+
+## Summary
+
+To put the entire example together, for our dictionary mapping
+strings to variants (with two entries, as given above), we are
+using 91 bytes of memory for type information, 29 bytes of memory
+for the serialized data, 16 bytes for buffer management and 24
+bytes for the #GVariant instance, or a total of 160 bytes, plus
+malloc overhead. If we were to use g_variant_get_child_value() to
+access the two dictionary entries, we would use an additional 48
+bytes. If we were to have other dictionaries of the same type, we
+would use more memory for the serialized data and buffer
+management for those dictionaries, but the type information would
+be shared.
+
+
+ Creates a new #GVariant instance.
+
+Think of this function as an analogue to g_strdup_printf().
+
+The type of the created instance and the arguments that are expected
+by this function are determined by @format_string. See the section on
+[GVariant format strings][gvariant-format-strings]. Please note that
+the syntax of the format string is very likely to be extended in the
+future.
+
+The first character of the format string must not be '*' '?' '@' or
+'r'; in essence, a new #GVariant must always be constructed by this
+function (and not merely passed through it unmodified).
+
+Note that the arguments must be of the correct width for their types
+specified in @format_string. This can be achieved by casting them. See
+the [GVariant varargs documentation][gvariant-varargs].
+
+|[<!-- language="C" -->
+MyFlags some_flags = FLAG_ONE | FLAG_TWO;
+const gchar *some_strings[] = { "a", "b", "c", NULL };
+GVariant *new_variant;
+
+new_variant = g_variant_new ("(t^as)",
+ // This cast is required.
+ (guint64) some_flags,
+ some_strings);
+]|
+
+
+ a new floating #GVariant instance
+
+
+
+
+ a #GVariant format string
+
+
+
+ arguments, as per @format_string
+
+
+
+
+
+ Creates a new #GVariant array from @children.
+
+@child_type must be non-%NULL if @n_children is zero. Otherwise, the
+child type is determined by inspecting the first element of the
+@children array. If @child_type is non-%NULL then it must be a
+definite type.
+
+The items of the array are taken from the @children array. No entry
+in the @children array may be %NULL.
+
+All items in the array must have the same type, which must be the
+same as @child_type, if given.
+
+If the @children are floating references (see g_variant_ref_sink()), the
+new instance takes ownership of them as if via g_variant_ref_sink().
+
+
+ a floating reference to a new #GVariant array
+
+
+
+
+ the element type of the new array
+
+
+
+ an array of
+ #GVariant pointers, the children
+
+
+
+
+
+ the length of @children
+
+
+
+
+
+ Creates a new boolean #GVariant instance -- either %TRUE or %FALSE.
+
+
+ a floating reference to a new boolean #GVariant instance
+
+
+
+
+ a #gboolean value
+
+
+
+
+
+ Creates a new byte #GVariant instance.
+
+
+ a floating reference to a new byte #GVariant instance
+
+
+
+
+ a #guint8 value
+
+
+
+
+
+ Creates an array-of-bytes #GVariant with the contents of @string.
+This function is just like g_variant_new_string() except that the
+string need not be valid UTF-8.
+
+The nul terminator character at the end of the string is stored in
+the array.
+
+
+ a floating reference to a new bytestring #GVariant instance
+
+
+
+
+ a normal
+ nul-terminated string in no particular encoding
+
+
+
+
+
+
+
+ Constructs an array of bytestring #GVariant from the given array of
+strings.
+
+If @length is -1 then @strv is %NULL-terminated.
+
+
+ a new floating #GVariant instance
+
+
+
+
+ an array of strings
+
+
+
+
+
+ the length of @strv, or -1
+
+
+
+
+
+ Creates a new dictionary entry #GVariant. @key and @value must be
+non-%NULL. @key must be a value of a basic type (ie: not a container).
+
+If the @key or @value are floating references (see g_variant_ref_sink()),
+the new instance takes ownership of them as if via g_variant_ref_sink().
+
+
+ a floating reference to a new dictionary entry #GVariant
+
+
+
+
+ a basic #GVariant, the key
+
+
+
+ a #GVariant, the value
+
+
+
+
+
+ Creates a new double #GVariant instance.
+
+
+ a floating reference to a new double #GVariant instance
+
+
+
+
+ a #gdouble floating point value
+
+
+
+
+
+ Constructs a new array #GVariant instance, where the elements are
+of @element_type type.
+
+@elements must be an array with fixed-sized elements. Numeric types are
+fixed-size as are tuples containing only other fixed-sized types.
+
+@element_size must be the size of a single element in the array.
+For example, if calling this function for an array of 32-bit integers,
+you might say sizeof(gint32). This value isn't used except for the purpose
+of a double-check that the form of the serialized data matches the caller's
+expectation.
+
+@n_elements must be the length of the @elements array.
+
+
+ a floating reference to a new array #GVariant instance
+
+
+
+
+ the #GVariantType of each element
+
+
+
+ a pointer to the fixed array of contiguous elements
+
+
+
+ the number of elements
+
+
+
+ the size of each element
+
+
+
+
+
+ Constructs a new serialized-mode #GVariant instance. This is the
+inner interface for creation of new serialized values that gets
+called from various functions in gvariant.c.
+
+A reference is taken on @bytes.
+
+The data in @bytes must be aligned appropriately for the @type being loaded.
+Otherwise this function will internally create a copy of the memory (since
+GLib 2.60) or (in older versions) fail and exit the process.
+
+
+ a new #GVariant with a floating reference
+
+
+
+
+ a #GVariantType
+
+
+
+ a #GBytes
+
+
+
+ if the contents of @bytes are trusted
+
+
+
+
+
+ Creates a new #GVariant instance from serialized data.
+
+@type is the type of #GVariant instance that will be constructed.
+The interpretation of @data depends on knowing the type.
+
+@data is not modified by this function and must remain valid with an
+unchanging value until such a time as @notify is called with
+@user_data. If the contents of @data change before that time then
+the result is undefined.
+
+If @data is trusted to be serialized data in normal form then
+@trusted should be %TRUE. This applies to serialized data created
+within this process or read from a trusted location on the disk (such
+as a file installed in /usr/lib alongside your application). You
+should set trusted to %FALSE if @data is read from the network, a
+file in the user's home directory, etc.
+
+If @data was not stored in this machine's native endianness, any multi-byte
+numeric values in the returned variant will also be in non-native
+endianness. g_variant_byteswap() can be used to recover the original values.
+
+@notify will be called with @user_data when @data is no longer
+needed. The exact time of this call is unspecified and might even be
+before this function returns.
+
+Note: @data must be backed by memory that is aligned appropriately for the
+@type being loaded. Otherwise this function will internally create a copy of
+the memory (since GLib 2.60) or (in older versions) fail and exit the
+process.
+
+
+ a new floating #GVariant of type @type
+
+
+
+
+ a definite #GVariantType
+
+
+
+ the serialized data
+
+
+
+
+
+ the size of @data
+
+
+
+ %TRUE if @data is definitely in normal form
+
+
+
+ function to call when @data is no longer needed
+
+
+
+ data for @notify
+
+
+
+
+
+ Creates a new handle #GVariant instance.
+
+By convention, handles are indexes into an array of file descriptors
+that are sent alongside a D-Bus message. If you're not interacting
+with D-Bus, you probably don't need them.
+
+
+ a floating reference to a new handle #GVariant instance
+
+
+
+
+ a #gint32 value
+
+
+
+
+
+ Creates a new int16 #GVariant instance.
+
+
+ a floating reference to a new int16 #GVariant instance
+
+
+
+
+ a #gint16 value
+
+
+
+
+
+ Creates a new int32 #GVariant instance.
+
+
+ a floating reference to a new int32 #GVariant instance
+
+
+
+
+ a #gint32 value
+
+
+
+
+
+ Creates a new int64 #GVariant instance.
+
+
+ a floating reference to a new int64 #GVariant instance
+
+
+
+
+ a #gint64 value
+
+
+
+
+
+ Depending on if @child is %NULL, either wraps @child inside of a
+maybe container or creates a Nothing instance for the given @type.
+
+At least one of @child_type and @child must be non-%NULL.
+If @child_type is non-%NULL then it must be a definite type.
+If they are both non-%NULL then @child_type must be the type
+of @child.
+
+If @child is a floating reference (see g_variant_ref_sink()), the new
+instance takes ownership of @child.
+
+
+ a floating reference to a new #GVariant maybe instance
+
+
+
+
+ the #GVariantType of the child, or %NULL
+
+
+
+ the child value, or %NULL
+
+
+
+
+
+ Creates a D-Bus object path #GVariant with the contents of @string.
+@string must be a valid D-Bus object path. Use
+g_variant_is_object_path() if you're not sure.
+
+
+ a floating reference to a new object path #GVariant instance
+
+
+
+
+ a normal C nul-terminated string
+
+
+
+
+
+ Constructs an array of object paths #GVariant from the given array of
+strings.
+
+Each string must be a valid #GVariant object path; see
+g_variant_is_object_path().
+
+If @length is -1 then @strv is %NULL-terminated.
+
+
+ a new floating #GVariant instance
+
+
+
+
+ an array of strings
+
+
+
+
+
+ the length of @strv, or -1
+
+
+
+
+
+ Parses @format and returns the result.
+
+@format must be a text format #GVariant with one extension: at any
+point that a value may appear in the text, a '%' character followed
+by a GVariant format string (as per g_variant_new()) may appear. In
+that case, the same arguments are collected from the argument list as
+g_variant_new() would have collected.
+
+Note that the arguments must be of the correct width for their types
+specified in @format. This can be achieved by casting them. See
+the [GVariant varargs documentation][gvariant-varargs].
+
+Consider this simple example:
+|[<!-- language="C" -->
+ g_variant_new_parsed ("[('one', 1), ('two', %i), (%s, 3)]", 2, "three");
+]|
+
+In the example, the variable argument parameters are collected and
+filled in as if they were part of the original string to produce the
+result of
+|[<!-- language="C" -->
+[('one', 1), ('two', 2), ('three', 3)]
+]|
+
+This function is intended only to be used with @format as a string
+literal. Any parse error is fatal to the calling process. If you
+want to parse data from untrusted sources, use g_variant_parse().
+
+You may not use this function to return, unmodified, a single
+#GVariant pointer from the argument list. ie: @format may not solely
+be anything along the lines of "%*", "%?", "\%r", or anything starting
+with "%@".
+
+
+ a new floating #GVariant instance
+
+
+
+
+ a text format #GVariant
+
+
+
+ arguments as per @format
+
+
+
+
+
+ Parses @format and returns the result.
+
+This is the version of g_variant_new_parsed() intended to be used
+from libraries.
+
+The return value will be floating if it was a newly created GVariant
+instance. In the case that @format simply specified the collection
+of a #GVariant pointer (eg: @format was "%*") then the collected
+#GVariant pointer will be returned unmodified, without adding any
+additional references.
+
+Note that the arguments in @app must be of the correct width for their types
+specified in @format when collected into the #va_list. See
+the [GVariant varargs documentation][gvariant-varargs].
+
+In order to behave correctly in all cases it is necessary for the
+calling function to g_variant_ref_sink() the return result before
+returning control to the user that originally provided the pointer.
+At this point, the caller will have their own full reference to the
+result. This can also be done by adding the result to a container,
+or by passing it to another g_variant_new() call.
+
+
+ a new, usually floating, #GVariant
+
+
+
+
+ a text format #GVariant
+
+
+
+ a pointer to a #va_list
+
+
+
+
+
+ Creates a string-type GVariant using printf formatting.
+
+This is similar to calling g_strdup_printf() and then
+g_variant_new_string() but it saves a temporary variable and an
+unnecessary copy.
+
+
+ a floating reference to a new string
+ #GVariant instance
+
+
+
+
+ a printf-style format string
+
+
+
+ arguments for @format_string
+
+
+
+
+
+ Creates a D-Bus type signature #GVariant with the contents of
+@string. @string must be a valid D-Bus type signature. Use
+g_variant_is_signature() if you're not sure.
+
+
+ a floating reference to a new signature #GVariant instance
+
+
+
+
+ a normal C nul-terminated string
+
+
+
+
+
+ Creates a string #GVariant with the contents of @string.
+
+@string must be valid UTF-8, and must not be %NULL. To encode
+potentially-%NULL strings, use g_variant_new() with `ms` as the
+[format string][gvariant-format-strings-maybe-types].
+
+
+ a floating reference to a new string #GVariant instance
+
+
+
+
+ a normal UTF-8 nul-terminated string
+
+
+
+
+
+ Constructs an array of strings #GVariant from the given array of
+strings.
+
+If @length is -1 then @strv is %NULL-terminated.
+
+
+ a new floating #GVariant instance
+
+
+
+
+ an array of strings
+
+
+
+
+
+ the length of @strv, or -1
+
+
+
+
+
+ Creates a string #GVariant with the contents of @string.
+
+@string must be valid UTF-8, and must not be %NULL. To encode
+potentially-%NULL strings, use this with g_variant_new_maybe().
+
+This function consumes @string. g_free() will be called on @string
+when it is no longer required.
+
+You must not modify or access @string in any other way after passing
+it to this function. It is even possible that @string is immediately
+freed.
+
+
+ a floating reference to a new string
+ #GVariant instance
+
+
+
+
+ a normal UTF-8 nul-terminated string
+
+
+
+
+
+ Creates a new tuple #GVariant out of the items in @children. The
+type is determined from the types of @children. No entry in the
+@children array may be %NULL.
+
+If @n_children is 0 then the unit tuple is constructed.
+
+If the @children are floating references (see g_variant_ref_sink()), the
+new instance takes ownership of them as if via g_variant_ref_sink().
+
+
+ a floating reference to a new #GVariant tuple
+
+
+
+
+ the items to make the tuple out of
+
+
+
+
+
+ the length of @children
+
+
+
+
+
+ Creates a new uint16 #GVariant instance.
+
+
+ a floating reference to a new uint16 #GVariant instance
+
+
+
+
+ a #guint16 value
+
+
+
+
+
+ Creates a new uint32 #GVariant instance.
+
+
+ a floating reference to a new uint32 #GVariant instance
+
+
+
+
+ a #guint32 value
+
+
+
+
+
+ Creates a new uint64 #GVariant instance.
+
+
+ a floating reference to a new uint64 #GVariant instance
+
+
+
+
+ a #guint64 value
+
+
+
+
+
+ This function is intended to be used by libraries based on
+#GVariant that want to provide g_variant_new()-like functionality
+to their users.
+
+The API is more general than g_variant_new() to allow a wider range
+of possible uses.
+
+@format_string must still point to a valid format string, but it only
+needs to be nul-terminated if @endptr is %NULL. If @endptr is
+non-%NULL then it is updated to point to the first character past the
+end of the format string.
+
+@app is a pointer to a #va_list. The arguments, according to
+@format_string, are collected from this #va_list and the list is left
+pointing to the argument following the last.
+
+Note that the arguments in @app must be of the correct width for their
+types specified in @format_string when collected into the #va_list.
+See the [GVariant varargs documentation][gvariant-varargs].
+
+These two generalisations allow mixing of multiple calls to
+g_variant_new_va() and g_variant_get_va() within a single actual
+varargs call by the user.
+
+The return value will be floating if it was a newly created GVariant
+instance (for example, if the format string was "(ii)"). In the case
+that the format_string was '*', '?', 'r', or a format starting with
+'@' then the collected #GVariant pointer will be returned unmodified,
+without adding any additional references.
+
+In order to behave correctly in all cases it is necessary for the
+calling function to g_variant_ref_sink() the return result before
+returning control to the user that originally provided the pointer.
+At this point, the caller will have their own full reference to the
+result. This can also be done by adding the result to a container,
+or by passing it to another g_variant_new() call.
+
+
+ a new, usually floating, #GVariant
+
+
+
+
+ a string that is prefixed with a format string
+
+
+
+ location to store the end pointer,
+ or %NULL
+
+
+
+ a pointer to a #va_list
+
+
+
+
+
+ Boxes @value. The result is a #GVariant instance representing a
+variant containing the original value.
+
+If @child is a floating reference (see g_variant_ref_sink()), the new
+instance takes ownership of @child.
+
+
+ a floating reference to a new variant #GVariant instance
+
+
+
+
+ a #GVariant instance
+
+
+
+
+
+ Performs a byteswapping operation on the contents of @value. The
+result is that all multi-byte numeric data contained in @value is
+byteswapped. That includes 16, 32, and 64bit signed and unsigned
+integers as well as file handles and double precision floating point
+values.
+
+This function is an identity mapping on any value that does not
+contain multi-byte numeric data. That include strings, booleans,
+bytes and containers containing only these things (recursively).
+
+While this function can safely handle untrusted, non-normal data, it is
+recommended to check whether the input is in normal form beforehand, using
+g_variant_is_normal_form(), and to reject non-normal inputs if your
+application can be strict about what inputs it rejects.
+
+The returned value is always in normal form and is marked as trusted.
+A full, not floating, reference is returned.
+
+
+ the byteswapped form of @value
+
+
+
+
+ a #GVariant
+
+
+
+
+
+ Checks if calling g_variant_get() with @format_string on @value would
+be valid from a type-compatibility standpoint. @format_string is
+assumed to be a valid format string (from a syntactic standpoint).
+
+If @copy_only is %TRUE then this function additionally checks that it
+would be safe to call g_variant_unref() on @value immediately after
+the call to g_variant_get() without invalidating the result. This is
+only possible if deep copies are made (ie: there are no pointers to
+the data inside of the soon-to-be-freed #GVariant instance). If this
+check fails then a g_critical() is printed and %FALSE is returned.
+
+This function is meant to be used by functions that wish to provide
+varargs accessors to #GVariant values of uncertain values (eg:
+g_variant_lookup() or g_menu_model_get_item_attribute()).
+
+
+ %TRUE if @format_string is safe to use
+
+
+
+
+ a #GVariant
+
+
+
+ a valid #GVariant format string
+
+
+
+ %TRUE to ensure the format string makes deep copies
+
+
+
+
+
+ Classifies @value according to its top-level type.
+
+
+ the #GVariantClass of @value
+
+
+
+
+ a #GVariant
+
+
+
+
+
+ Compares @one and @two.
+
+The types of @one and @two are #gconstpointer only to allow use of
+this function with #GTree, #GPtrArray, etc. They must each be a
+#GVariant.
+
+Comparison is only defined for basic types (ie: booleans, numbers,
+strings). For booleans, %FALSE is less than %TRUE. Numbers are
+ordered in the usual way. Strings are in ASCII lexographical order.
+
+It is a programmer error to attempt to compare container values or
+two values that have types that are not exactly equal. For example,
+you cannot compare a 32-bit signed integer with a 32-bit unsigned
+integer. Also note that this function is not particularly
+well-behaved when it comes to comparison of doubles; in particular,
+the handling of incomparable values (ie: NaN) is undefined.
+
+If you only require an equality comparison, g_variant_equal() is more
+general.
+
+
+ negative value if a < b;
+ zero if a = b;
+ positive value if a > b.
+
+
+
+
+ a basic-typed #GVariant instance
+
+
+
+ a #GVariant instance of the same type
+
+
+
+
+
+ Similar to g_variant_get_bytestring() except that instead of
+returning a constant string, the string is duplicated.
+
+The return value must be freed using g_free().
+
+
+
+ a newly allocated string
+
+
+
+
+
+
+ an array-of-bytes #GVariant instance
+
+
+
+ a pointer to a #gsize, to store
+ the length (not including the nul terminator)
+
+
+
+
+
+ Gets the contents of an array of array of bytes #GVariant. This call
+makes a deep copy; the return result should be released with
+g_strfreev().
+
+If @length is non-%NULL then the number of elements in the result is
+stored there. In any case, the resulting array will be
+%NULL-terminated.
+
+For an empty array, @length will be set to 0 and a pointer to a
+%NULL pointer will be returned.
+
+
+ an array of strings
+
+
+
+
+
+
+ an array of array of bytes #GVariant ('aay')
+
+
+
+ the length of the result, or %NULL
+
+
+
+
+
+ Gets the contents of an array of object paths #GVariant. This call
+makes a deep copy; the return result should be released with
+g_strfreev().
+
+If @length is non-%NULL then the number of elements in the result
+is stored there. In any case, the resulting array will be
+%NULL-terminated.
+
+For an empty array, @length will be set to 0 and a pointer to a
+%NULL pointer will be returned.
+
+
+ an array of strings
+
+
+
+
+
+
+ an array of object paths #GVariant
+
+
+
+ the length of the result, or %NULL
+
+
+
+
+
+ Similar to g_variant_get_string() except that instead of returning
+a constant string, the string is duplicated.
+
+The string will always be UTF-8 encoded.
+
+The return value must be freed using g_free().
+
+
+ a newly allocated string, UTF-8 encoded
+
+
+
+
+ a string #GVariant instance
+
+
+
+ a pointer to a #gsize, to store the length
+
+
+
+
+
+ Gets the contents of an array of strings #GVariant. This call
+makes a deep copy; the return result should be released with
+g_strfreev().
+
+If @length is non-%NULL then the number of elements in the result
+is stored there. In any case, the resulting array will be
+%NULL-terminated.
+
+For an empty array, @length will be set to 0 and a pointer to a
+%NULL pointer will be returned.
+
+
+ an array of strings
+
+
+
+
+
+
+ an array of strings #GVariant
+
+
+
+ the length of the result, or %NULL
+
+
+
+
+
+ Checks if @one and @two have the same type and value.
+
+The types of @one and @two are #gconstpointer only to allow use of
+this function with #GHashTable. They must each be a #GVariant.
+
+
+ %TRUE if @one and @two are equal
+
+
+
+
+ a #GVariant instance
+
+
+
+ a #GVariant instance
+
+
+
+
+
+ Deconstructs a #GVariant instance.
+
+Think of this function as an analogue to scanf().
+
+The arguments that are expected by this function are entirely
+determined by @format_string. @format_string also restricts the
+permissible types of @value. It is an error to give a value with
+an incompatible type. See the section on
+[GVariant format strings][gvariant-format-strings].
+Please note that the syntax of the format string is very likely to be
+extended in the future.
+
+@format_string determines the C types that are used for unpacking
+the values and also determines if the values are copied or borrowed,
+see the section on
+[GVariant format strings][gvariant-format-strings-pointers].
+
+
+
+
+
+
+ a #GVariant instance
+
+
+
+ a #GVariant format string
+
+
+
+ arguments, as per @format_string
+
+
+
+
+
+ Returns the boolean value of @value.
+
+It is an error to call this function with a @value of any type
+other than %G_VARIANT_TYPE_BOOLEAN.
+
+
+ %TRUE or %FALSE
+
+
+
+
+ a boolean #GVariant instance
+
+
+
+
+
+ Returns the byte value of @value.
+
+It is an error to call this function with a @value of any type
+other than %G_VARIANT_TYPE_BYTE.
+
+
+ a #guint8
+
+
+
+
+ a byte #GVariant instance
+
+
+
+
+
+ Returns the string value of a #GVariant instance with an
+array-of-bytes type. The string has no particular encoding.
+
+If the array does not end with a nul terminator character, the empty
+string is returned. For this reason, you can always trust that a
+non-%NULL nul-terminated string will be returned by this function.
+
+If the array contains a nul terminator character somewhere other than
+the last byte then the returned string is the string, up to the first
+such nul character.
+
+g_variant_get_fixed_array() should be used instead if the array contains
+arbitrary data that could not be nul-terminated or could contain nul bytes.
+
+It is an error to call this function with a @value that is not an
+array of bytes.
+
+The return value remains valid as long as @value exists.
+
+
+
+ the constant string
+
+
+
+
+
+
+ an array-of-bytes #GVariant instance
+
+
+
+
+
+ Gets the contents of an array of array of bytes #GVariant. This call
+makes a shallow copy; the return result should be released with
+g_free(), but the individual strings must not be modified.
+
+If @length is non-%NULL then the number of elements in the result is
+stored there. In any case, the resulting array will be
+%NULL-terminated.
+
+For an empty array, @length will be set to 0 and a pointer to a
+%NULL pointer will be returned.
+
+
+ an array of constant strings
+
+
+
+
+
+
+ an array of array of bytes #GVariant ('aay')
+
+
+
+ the length of the result, or %NULL
+
+
+
+
+
+ Reads a child item out of a container #GVariant instance and
+deconstructs it according to @format_string. This call is
+essentially a combination of g_variant_get_child_value() and
+g_variant_get().
+
+@format_string determines the C types that are used for unpacking
+the values and also determines if the values are copied or borrowed,
+see the section on
+[GVariant format strings][gvariant-format-strings-pointers].
+
+
+
+
+
+
+ a container #GVariant
+
+
+
+ the index of the child to deconstruct
+
+
+
+ a #GVariant format string
+
+
+
+ arguments, as per @format_string
+
+
+
+
+
+ Reads a child item out of a container #GVariant instance. This
+includes variants, maybes, arrays, tuples and dictionary
+entries. It is an error to call this function on any other type of
+#GVariant.
+
+It is an error if @index_ is greater than the number of child items
+in the container. See g_variant_n_children().
+
+The returned value is never floating. You should free it with
+g_variant_unref() when you're done with it.
+
+Note that values borrowed from the returned child are not guaranteed to
+still be valid after the child is freed even if you still hold a reference
+to @value, if @value has not been serialized at the time this function is
+called. To avoid this, you can serialize @value by calling
+g_variant_get_data() and optionally ignoring the return value.
+
+There may be implementation specific restrictions on deeply nested values,
+which would result in the unit tuple being returned as the child value,
+instead of further nested children. #GVariant is guaranteed to handle
+nesting up to at least 64 levels.
+
+This function is O(1).
+
+
+ the child at the specified index
+
+
+
+
+ a container #GVariant
+
+
+
+ the index of the child to fetch
+
+
+
+
+
+ Returns a pointer to the serialized form of a #GVariant instance.
+The returned data may not be in fully-normalised form if read from an
+untrusted source. The returned data must not be freed; it remains
+valid for as long as @value exists.
+
+If @value is a fixed-sized value that was deserialized from a
+corrupted serialized container then %NULL may be returned. In this
+case, the proper thing to do is typically to use the appropriate
+number of nul bytes in place of @value. If @value is not fixed-sized
+then %NULL is never returned.
+
+In the case that @value is already in serialized form, this function
+is O(1). If the value is not already in serialized form,
+serialization occurs implicitly and is approximately O(n) in the size
+of the result.
+
+To deserialize the data returned by this function, in addition to the
+serialized data, you must know the type of the #GVariant, and (if the
+machine might be different) the endianness of the machine that stored
+it. As a result, file formats or network messages that incorporate
+serialized #GVariants must include this information either
+implicitly (for instance "the file always contains a
+%G_VARIANT_TYPE_VARIANT and it is always in little-endian order") or
+explicitly (by storing the type and/or endianness in addition to the
+serialized data).
+
+
+ the serialized form of @value, or %NULL
+
+
+
+
+ a #GVariant instance
+
+
+
+
+
+ Returns a pointer to the serialized form of a #GVariant instance.
+The semantics of this function are exactly the same as
+g_variant_get_data(), except that the returned #GBytes holds
+a reference to the variant data.
+
+
+ A new #GBytes representing the variant data
+
+
+
+
+ a #GVariant
+
+
+
+
+
+ Returns the double precision floating point value of @value.
+
+It is an error to call this function with a @value of any type
+other than %G_VARIANT_TYPE_DOUBLE.
+
+
+ a #gdouble
+
+
+
+
+ a double #GVariant instance
+
+
+
+
+
+ Provides access to the serialized data for an array of fixed-sized
+items.
+
+@value must be an array with fixed-sized elements. Numeric types are
+fixed-size, as are tuples containing only other fixed-sized types.
+
+@element_size must be the size of a single element in the array,
+as given by the section on
+[serialized data memory][gvariant-serialized-data-memory].
+
+In particular, arrays of these fixed-sized types can be interpreted
+as an array of the given C type, with @element_size set to the size
+the appropriate type:
+- %G_VARIANT_TYPE_INT16 (etc.): #gint16 (etc.)
+- %G_VARIANT_TYPE_BOOLEAN: #guchar (not #gboolean!)
+- %G_VARIANT_TYPE_BYTE: #guint8
+- %G_VARIANT_TYPE_HANDLE: #guint32
+- %G_VARIANT_TYPE_DOUBLE: #gdouble
+
+For example, if calling this function for an array of 32-bit integers,
+you might say `sizeof(gint32)`. This value isn't used except for the purpose
+of a double-check that the form of the serialized data matches the caller's
+expectation.
+
+@n_elements, which must be non-%NULL, is set equal to the number of
+items in the array.
+
+
+ a pointer to
+ the fixed array
+
+
+
+
+
+
+ a #GVariant array with fixed-sized elements
+
+
+
+ a pointer to the location to store the number of items
+
+
+
+ the size of each element
+
+
+
+
+
+ Returns the 32-bit signed integer value of @value.
+
+It is an error to call this function with a @value of any type other
+than %G_VARIANT_TYPE_HANDLE.
+
+By convention, handles are indexes into an array of file descriptors
+that are sent alongside a D-Bus message. If you're not interacting
+with D-Bus, you probably don't need them.
+
+
+ a #gint32
+
+
+
+
+ a handle #GVariant instance
+
+
+
+
+
+ Returns the 16-bit signed integer value of @value.
+
+It is an error to call this function with a @value of any type
+other than %G_VARIANT_TYPE_INT16.
+
+
+ a #gint16
+
+
+
+
+ an int16 #GVariant instance
+
+
+
+
+
+ Returns the 32-bit signed integer value of @value.
+
+It is an error to call this function with a @value of any type
+other than %G_VARIANT_TYPE_INT32.
+
+
+ a #gint32
+
+
+
+
+ an int32 #GVariant instance
+
+
+
+
+
+ Returns the 64-bit signed integer value of @value.
+
+It is an error to call this function with a @value of any type
+other than %G_VARIANT_TYPE_INT64.
+
+
+ a #gint64
+
+
+
+
+ an int64 #GVariant instance
+
+
+
+
+
+ Given a maybe-typed #GVariant instance, extract its value. If the
+value is Nothing, then this function returns %NULL.
+
+
+ the contents of @value, or %NULL
+
+
+
+
+ a maybe-typed value
+
+
+
+
+
+ Gets a #GVariant instance that has the same value as @value and is
+trusted to be in normal form.
+
+If @value is already trusted to be in normal form then a new
+reference to @value is returned.
+
+If @value is not already trusted, then it is scanned to check if it
+is in normal form. If it is found to be in normal form then it is
+marked as trusted and a new reference to it is returned.
+
+If @value is found not to be in normal form then a new trusted
+#GVariant is created with the same value as @value. The non-normal parts of
+@value will be replaced with default values which are guaranteed to be in
+normal form.
+
+It makes sense to call this function if you've received #GVariant
+data from untrusted sources and you want to ensure your serialized
+output is definitely in normal form.
+
+If @value is already in normal form, a new reference will be returned
+(which will be floating if @value is floating). If it is not in normal form,
+the newly created #GVariant will be returned with a single non-floating
+reference. Typically, g_variant_take_ref() should be called on the return
+value from this function to guarantee ownership of a single non-floating
+reference to it.
+
+
+ a trusted #GVariant
+
+
+
+
+ a #GVariant
+
+
+
+
+
+ Gets the contents of an array of object paths #GVariant. This call
+makes a shallow copy; the return result should be released with
+g_free(), but the individual strings must not be modified.
+
+If @length is non-%NULL then the number of elements in the result
+is stored there. In any case, the resulting array will be
+%NULL-terminated.
+
+For an empty array, @length will be set to 0 and a pointer to a
+%NULL pointer will be returned.
+
+
+ an array of constant strings
+
+
+
+
+
+
+ an array of object paths #GVariant
+
+
+
+ the length of the result, or %NULL
+
+
+
+
+
+ Determines the number of bytes that would be required to store @value
+with g_variant_store().
+
+If @value has a fixed-sized type then this function always returned
+that fixed size.
+
+In the case that @value is already in serialized form or the size has
+already been calculated (ie: this function has been called before)
+then this function is O(1). Otherwise, the size is calculated, an
+operation which is approximately O(n) in the number of values
+involved.
+
+
+ the serialized size of @value
+
+
+
+
+ a #GVariant instance
+
+
+
+
+
+ Returns the string value of a #GVariant instance with a string
+type. This includes the types %G_VARIANT_TYPE_STRING,
+%G_VARIANT_TYPE_OBJECT_PATH and %G_VARIANT_TYPE_SIGNATURE.
+
+The string will always be UTF-8 encoded, will never be %NULL, and will never
+contain nul bytes.
+
+If @length is non-%NULL then the length of the string (in bytes) is
+returned there. For trusted values, this information is already
+known. Untrusted values will be validated and, if valid, a strlen() will be
+performed. If invalid, a default value will be returned — for
+%G_VARIANT_TYPE_OBJECT_PATH, this is `"/"`, and for other types it is the
+empty string.
+
+It is an error to call this function with a @value of any type
+other than those three.
+
+The return value remains valid as long as @value exists.
+
+
+ the constant string, UTF-8 encoded
+
+
+
+
+ a string #GVariant instance
+
+
+
+ a pointer to a #gsize,
+ to store the length
+
+
+
+
+
+ Gets the contents of an array of strings #GVariant. This call
+makes a shallow copy; the return result should be released with
+g_free(), but the individual strings must not be modified.
+
+If @length is non-%NULL then the number of elements in the result
+is stored there. In any case, the resulting array will be
+%NULL-terminated.
+
+For an empty array, @length will be set to 0 and a pointer to a
+%NULL pointer will be returned.
+
+
+ an array of constant strings
+
+
+
+
+
+
+ an array of strings #GVariant
+
+
+
+ the length of the result, or %NULL
+
+
+
+
+
+ Determines the type of @value.
+
+The return value is valid for the lifetime of @value and must not
+be freed.
+
+
+ a #GVariantType
+
+
+
+
+ a #GVariant
+
+
+
+
+
+ Returns the type string of @value. Unlike the result of calling
+g_variant_type_peek_string(), this string is nul-terminated. This
+string belongs to #GVariant and must not be freed.
+
+
+ the type string for the type of @value
+
+
+
+
+ a #GVariant
+
+
+
+
+
+ Returns the 16-bit unsigned integer value of @value.
+
+It is an error to call this function with a @value of any type
+other than %G_VARIANT_TYPE_UINT16.
+
+
+ a #guint16
+
+
+
+
+ a uint16 #GVariant instance
+
+
+
+
+
+ Returns the 32-bit unsigned integer value of @value.
+
+It is an error to call this function with a @value of any type
+other than %G_VARIANT_TYPE_UINT32.
+
+
+ a #guint32
+
+
+
+
+ a uint32 #GVariant instance
+
+
+
+
+
+ Returns the 64-bit unsigned integer value of @value.
+
+It is an error to call this function with a @value of any type
+other than %G_VARIANT_TYPE_UINT64.
+
+
+ a #guint64
+
+
+
+
+ a uint64 #GVariant instance
+
+
+
+
+
+ This function is intended to be used by libraries based on #GVariant
+that want to provide g_variant_get()-like functionality to their
+users.
+
+The API is more general than g_variant_get() to allow a wider range
+of possible uses.
+
+@format_string must still point to a valid format string, but it only
+need to be nul-terminated if @endptr is %NULL. If @endptr is
+non-%NULL then it is updated to point to the first character past the
+end of the format string.
+
+@app is a pointer to a #va_list. The arguments, according to
+@format_string, are collected from this #va_list and the list is left
+pointing to the argument following the last.
+
+These two generalisations allow mixing of multiple calls to
+g_variant_new_va() and g_variant_get_va() within a single actual
+varargs call by the user.
+
+@format_string determines the C types that are used for unpacking
+the values and also determines if the values are copied or borrowed,
+see the section on
+[GVariant format strings][gvariant-format-strings-pointers].
+
+
+
+
+
+
+ a #GVariant
+
+
+
+ a string that is prefixed with a format string
+
+
+
+ location to store the end pointer,
+ or %NULL
+
+
+
+ a pointer to a #va_list
+
+
+
+
+
+ Unboxes @value. The result is the #GVariant instance that was
+contained in @value.
+
+
+ the item contained in the variant
+
+
+
+
+ a variant #GVariant instance
+
+
+
+
+
+ Generates a hash value for a #GVariant instance.
+
+The output of this function is guaranteed to be the same for a given
+value only per-process. It may change between different processor
+architectures or even different versions of GLib. Do not use this
+function as a basis for building protocols or file formats.
+
+The type of @value is #gconstpointer only to allow use of this
+function with #GHashTable. @value must be a #GVariant.
+
+
+ a hash value corresponding to @value
+
+
+
+
+ a basic #GVariant value as a #gconstpointer
+
+
+
+
+
+ Checks if @value is a container.
+
+
+ %TRUE if @value is a container
+
+
+
+
+ a #GVariant instance
+
+
+
+
+
+ Checks whether @value has a floating reference count.
+
+This function should only ever be used to assert that a given variant
+is or is not floating, or for debug purposes. To acquire a reference
+to a variant that might be floating, always use g_variant_ref_sink()
+or g_variant_take_ref().
+
+See g_variant_ref_sink() for more information about floating reference
+counts.
+
+
+ whether @value is floating
+
+
+
+
+ a #GVariant
+
+
+
+
+
+ Checks if @value is in normal form.
+
+The main reason to do this is to detect if a given chunk of
+serialized data is in normal form: load the data into a #GVariant
+using g_variant_new_from_data() and then use this function to
+check.
+
+If @value is found to be in normal form then it will be marked as
+being trusted. If the value was already marked as being trusted then
+this function will immediately return %TRUE.
+
+There may be implementation specific restrictions on deeply nested values.
+GVariant is guaranteed to handle nesting up to at least 64 levels.
+
+
+ %TRUE if @value is in normal form
+
+
+
+
+ a #GVariant instance
+
+
+
+
+
+ Checks if a value has a type matching the provided type.
+
+
+ %TRUE if the type of @value matches @type
+
+
+
+
+ a #GVariant instance
+
+
+
+ a #GVariantType
+
+
+
+
+
+ Creates a heap-allocated #GVariantIter for iterating over the items
+in @value.
+
+Use g_variant_iter_free() to free the return value when you no longer
+need it.
+
+A reference is taken to @value and will be released only when
+g_variant_iter_free() is called.
+
+
+ a new heap-allocated #GVariantIter
+
+
+
+
+ a container #GVariant
+
+
+
+
+
+ Looks up a value in a dictionary #GVariant.
+
+This function is a wrapper around g_variant_lookup_value() and
+g_variant_get(). In the case that %NULL would have been returned,
+this function returns %FALSE. Otherwise, it unpacks the returned
+value and returns %TRUE.
+
+@format_string determines the C types that are used for unpacking
+the values and also determines if the values are copied or borrowed,
+see the section on
+[GVariant format strings][gvariant-format-strings-pointers].
+
+This function is currently implemented with a linear scan. If you
+plan to do many lookups then #GVariantDict may be more efficient.
+
+
+ %TRUE if a value was unpacked
+
+
+
+
+ a dictionary #GVariant
+
+
+
+ the key to look up in the dictionary
+
+
+
+ a GVariant format string
+
+
+
+ the arguments to unpack the value into
+
+
+
+
+
+ Looks up a value in a dictionary #GVariant.
+
+This function works with dictionaries of the type a{s*} (and equally
+well with type a{o*}, but we only further discuss the string case
+for sake of clarity).
+
+In the event that @dictionary has the type a{sv}, the @expected_type
+string specifies what type of value is expected to be inside of the
+variant. If the value inside the variant has a different type then
+%NULL is returned. In the event that @dictionary has a value type other
+than v then @expected_type must directly match the value type and it is
+used to unpack the value directly or an error occurs.
+
+In either case, if @key is not found in @dictionary, %NULL is returned.
+
+If the key is found and the value has the correct type, it is
+returned. If @expected_type was specified then any non-%NULL return
+value will have this type.
+
+This function is currently implemented with a linear scan. If you
+plan to do many lookups then #GVariantDict may be more efficient.
+
+
+ the value of the dictionary key, or %NULL
+
+
+
+
+ a dictionary #GVariant
+
+
+
+ the key to look up in the dictionary
+
+
+
+ a #GVariantType, or %NULL
+
+
+
+
+
+ Determines the number of children in a container #GVariant instance.
+This includes variants, maybes, arrays, tuples and dictionary
+entries. It is an error to call this function on any other type of
+#GVariant.
+
+For variants, the return value is always 1. For values with maybe
+types, it is always zero or one. For arrays, it is the length of the
+array. For tuples it is the number of tuple items (which depends
+only on the type). For dictionary entries, it is always 2
+
+This function is O(1).
+
+
+ the number of children in the container
+
+
+
+
+ a container #GVariant
+
+
+
+
+
+ Pretty-prints @value in the format understood by g_variant_parse().
+
+The format is described [here][gvariant-text].
+
+If @type_annotate is %TRUE, then type information is included in
+the output.
+
+
+ a newly-allocated string holding the result.
+
+
+
+
+ a #GVariant
+
+
+
+ %TRUE if type information should be included in
+ the output
+
+
+
+
+
+ Behaves as g_variant_print(), but operates on a #GString.
+
+If @string is non-%NULL then it is appended to and returned. Else,
+a new empty #GString is allocated and it is returned.
+
+
+ a #GString containing the string
+
+
+
+
+ a #GVariant
+
+
+
+ a #GString, or %NULL
+
+
+
+ %TRUE if type information should be included in
+ the output
+
+
+
+
+
+ Increases the reference count of @value.
+
+
+ the same @value
+
+
+
+
+ a #GVariant
+
+
+
+
+
+ #GVariant uses a floating reference count system. All functions with
+names starting with `g_variant_new_` return floating
+references.
+
+Calling g_variant_ref_sink() on a #GVariant with a floating reference
+will convert the floating reference into a full reference. Calling
+g_variant_ref_sink() on a non-floating #GVariant results in an
+additional normal reference being added.
+
+In other words, if the @value is floating, then this call "assumes
+ownership" of the floating reference, converting it to a normal
+reference. If the @value is not floating, then this call adds a
+new normal reference increasing the reference count by one.
+
+All calls that result in a #GVariant instance being inserted into a
+container will call g_variant_ref_sink() on the instance. This means
+that if the value was just created (and has only its floating
+reference) then the container will assume sole ownership of the value
+at that point and the caller will not need to unreference it. This
+makes certain common styles of programming much easier while still
+maintaining normal refcounting semantics in situations where values
+are not floating.
+
+
+ the same @value
+
+
+
+
+ a #GVariant
+
+
+
+
+
+ Stores the serialized form of @value at @data. @data should be
+large enough. See g_variant_get_size().
+
+The stored data is in machine native byte order but may not be in
+fully-normalised form if read from an untrusted source. See
+g_variant_get_normal_form() for a solution.
+
+As with g_variant_get_data(), to be able to deserialize the
+serialized variant successfully, its type and (if the destination
+machine might be different) its endianness must also be available.
+
+This function is approximately O(n) in the size of @data.
+
+
+
+
+
+
+ the #GVariant to store
+
+
+
+ the location to store the serialized data at
+
+
+
+
+
+ If @value is floating, sink it. Otherwise, do nothing.
+
+Typically you want to use g_variant_ref_sink() in order to
+automatically do the correct thing with respect to floating or
+non-floating references, but there is one specific scenario where
+this function is helpful.
+
+The situation where this function is helpful is when creating an API
+that allows the user to provide a callback function that returns a
+#GVariant. We certainly want to allow the user the flexibility to
+return a non-floating reference from this callback (for the case
+where the value that is being returned already exists).
+
+At the same time, the style of the #GVariant API makes it likely that
+for newly-created #GVariant instances, the user can be saved some
+typing if they are allowed to return a #GVariant with a floating
+reference.
+
+Using this function on the return value of the user's callback allows
+the user to do whichever is more convenient for them. The caller
+will always receives exactly one full reference to the value: either
+the one that was returned in the first place, or a floating reference
+that has been converted to a full reference.
+
+This function has an odd interaction when combined with
+g_variant_ref_sink() running at the same time in another thread on
+the same #GVariant instance. If g_variant_ref_sink() runs first then
+the result will be that the floating reference is converted to a hard
+reference. If g_variant_take_ref() runs first then the result will
+be that the floating reference is converted to a hard reference and
+an additional reference on top of that one is added. It is best to
+avoid this situation.
+
+
+ the same @value
+
+
+
+
+ a #GVariant
+
+
+
+
+
+ Decreases the reference count of @value. When its reference count
+drops to 0, the memory used by the variant is freed.
+
+
+
+
+
+
+ a #GVariant
+
+
+
+
+
+ Determines if a given string is a valid D-Bus object path. You
+should ensure that a string is a valid D-Bus object path before
+passing it to g_variant_new_object_path().
+
+A valid object path starts with `/` followed by zero or more
+sequences of characters separated by `/` characters. Each sequence
+must contain only the characters `[A-Z][a-z][0-9]_`. No sequence
+(including the one following the final `/` character) may be empty.
+
+
+ %TRUE if @string is a D-Bus object path
+
+
+
+
+ a normal C nul-terminated string
+
+
+
+
+
+ Determines if a given string is a valid D-Bus type signature. You
+should ensure that a string is a valid D-Bus type signature before
+passing it to g_variant_new_signature().
+
+D-Bus type signatures consist of zero or more definite #GVariantType
+strings in sequence.
+
+
+ %TRUE if @string is a D-Bus type signature
+
+
+
+
+ a normal C nul-terminated string
+
+
+
+
+
+ Parses a #GVariant from a text representation.
+
+A single #GVariant is parsed from the content of @text.
+
+The format is described [here][gvariant-text].
+
+The memory at @limit will never be accessed and the parser behaves as
+if the character at @limit is the nul terminator. This has the
+effect of bounding @text.
+
+If @endptr is non-%NULL then @text is permitted to contain data
+following the value that this function parses and @endptr will be
+updated to point to the first character past the end of the text
+parsed by this function. If @endptr is %NULL and there is extra data
+then an error is returned.
+
+If @type is non-%NULL then the value will be parsed to have that
+type. This may result in additional parse errors (in the case that
+the parsed value doesn't fit the type) but may also result in fewer
+errors (in the case that the type would have been ambiguous, such as
+with empty arrays).
+
+In the event that the parsing is successful, the resulting #GVariant
+is returned. It is never floating, and must be freed with
+g_variant_unref().
+
+In case of any error, %NULL will be returned. If @error is non-%NULL
+then it will be set to reflect the error that occurred.
+
+Officially, the language understood by the parser is "any string
+produced by g_variant_print()".
+
+There may be implementation specific restrictions on deeply nested values,
+which would result in a %G_VARIANT_PARSE_ERROR_RECURSION error. #GVariant is
+guaranteed to handle nesting up to at least 64 levels.
+
+
+ a non-floating reference to a #GVariant, or %NULL
+
+
+
+
+ a #GVariantType, or %NULL
+
+
+
+ a string containing a GVariant in text form
+
+
+
+ a pointer to the end of @text, or %NULL
+
+
+
+ a location to store the end pointer, or %NULL
+
+
+
+
+
+ Pretty-prints a message showing the context of a #GVariant parse
+error within the string for which parsing was attempted.
+
+The resulting string is suitable for output to the console or other
+monospace media where newlines are treated in the usual way.
+
+The message will typically look something like one of the following:
+
+|[
+unterminated string constant:
+ (1, 2, 3, 'abc
+ ^^^^
+]|
+
+or
+
+|[
+unable to find a common type:
+ [1, 2, 3, 'str']
+ ^ ^^^^^
+]|
+
+The format of the message may change in a future version.
+
+@error must have come from a failed attempt to g_variant_parse() and
+@source_str must be exactly the same string that caused the error.
+If @source_str was not nul-terminated when you passed it to
+g_variant_parse() then you must add nul termination before using this
+function.
+
+
+ the printed message
+
+
+
+
+ a #GError from the #GVariantParseError domain
+
+
+
+ the string that was given to the parser
+
+
+
+
+
+
+
+
+
+
+ Same as g_variant_error_quark().
+ Use g_variant_parse_error_quark() instead.
+
+
+
+
+
+
+ A utility type for constructing container-type #GVariant instances.
+
+This is an opaque structure and may only be accessed using the
+following functions.
+
+#GVariantBuilder is not threadsafe in any way. Do not attempt to
+access it from more than one thread.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Allocates and initialises a new #GVariantBuilder.
+
+You should call g_variant_builder_unref() on the return value when it
+is no longer needed. The memory will not be automatically freed by
+any other call.
+
+In most cases it is easier to place a #GVariantBuilder directly on
+the stack of the calling function and initialise it with
+g_variant_builder_init().
+
+
+ a #GVariantBuilder
+
+
+
+
+ a container type
+
+
+
+
+
+ Adds to a #GVariantBuilder.
+
+This call is a convenience wrapper that is exactly equivalent to
+calling g_variant_new() followed by g_variant_builder_add_value().
+
+Note that the arguments must be of the correct width for their types
+specified in @format_string. This can be achieved by casting them. See
+the [GVariant varargs documentation][gvariant-varargs].
+
+This function might be used as follows:
+
+|[<!-- language="C" -->
+GVariant *
+make_pointless_dictionary (void)
+{
+ GVariantBuilder builder;
+ int i;
+
+ g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY);
+ for (i = 0; i < 16; i++)
+ {
+ gchar buf[3];
+
+ sprintf (buf, "%d", i);
+ g_variant_builder_add (&builder, "{is}", i, buf);
+ }
+
+ return g_variant_builder_end (&builder);
+}
+]|
+
+
+
+
+
+
+ a #GVariantBuilder
+
+
+
+ a #GVariant varargs format string
+
+
+
+ arguments, as per @format_string
+
+
+
+
+
+ Adds to a #GVariantBuilder.
+
+This call is a convenience wrapper that is exactly equivalent to
+calling g_variant_new_parsed() followed by
+g_variant_builder_add_value().
+
+Note that the arguments must be of the correct width for their types
+specified in @format_string. This can be achieved by casting them. See
+the [GVariant varargs documentation][gvariant-varargs].
+
+This function might be used as follows:
+
+|[<!-- language="C" -->
+GVariant *
+make_pointless_dictionary (void)
+{
+ GVariantBuilder builder;
+ int i;
+
+ g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY);
+ g_variant_builder_add_parsed (&builder, "{'width', <%i>}", 600);
+ g_variant_builder_add_parsed (&builder, "{'title', <%s>}", "foo");
+ g_variant_builder_add_parsed (&builder, "{'transparency', <0.5>}");
+ return g_variant_builder_end (&builder);
+}
+]|
+
+
+
+
+
+
+ a #GVariantBuilder
+
+
+
+ a text format #GVariant
+
+
+
+ arguments as per @format
+
+
+
+
+
+ Adds @value to @builder.
+
+It is an error to call this function in any way that would create an
+inconsistent value to be constructed. Some examples of this are
+putting different types of items into an array, putting the wrong
+types or number of items in a tuple, putting more than one value into
+a variant, etc.
+
+If @value is a floating reference (see g_variant_ref_sink()),
+the @builder instance takes ownership of @value.
+
+
+
+
+
+
+ a #GVariantBuilder
+
+
+
+ a #GVariant
+
+
+
+
+
+ Releases all memory associated with a #GVariantBuilder without
+freeing the #GVariantBuilder structure itself.
+
+It typically only makes sense to do this on a stack-allocated
+#GVariantBuilder if you want to abort building the value part-way
+through. This function need not be called if you call
+g_variant_builder_end() and it also doesn't need to be called on
+builders allocated with g_variant_builder_new() (see
+g_variant_builder_unref() for that).
+
+This function leaves the #GVariantBuilder structure set to all-zeros.
+It is valid to call this function on either an initialised
+#GVariantBuilder or one that is set to all-zeros but it is not valid
+to call this function on uninitialised memory.
+
+
+
+
+
+
+ a #GVariantBuilder
+
+
+
+
+
+ Closes the subcontainer inside the given @builder that was opened by
+the most recent call to g_variant_builder_open().
+
+It is an error to call this function in any way that would create an
+inconsistent value to be constructed (ie: too few values added to the
+subcontainer).
+
+
+
+
+
+
+ a #GVariantBuilder
+
+
+
+
+
+ Ends the builder process and returns the constructed value.
+
+It is not permissible to use @builder in any way after this call
+except for reference counting operations (in the case of a
+heap-allocated #GVariantBuilder) or by reinitialising it with
+g_variant_builder_init() (in the case of stack-allocated). This
+means that for the stack-allocated builders there is no need to
+call g_variant_builder_clear() after the call to
+g_variant_builder_end().
+
+It is an error to call this function in any way that would create an
+inconsistent value to be constructed (ie: insufficient number of
+items added to a container with a specific number of children
+required). It is also an error to call this function if the builder
+was created with an indefinite array or maybe type and no children
+have been added; in this case it is impossible to infer the type of
+the empty array.
+
+
+ a new, floating, #GVariant
+
+
+
+
+ a #GVariantBuilder
+
+
+
+
+
+ Initialises a #GVariantBuilder structure.
+
+@type must be non-%NULL. It specifies the type of container to
+construct. It can be an indefinite type such as
+%G_VARIANT_TYPE_ARRAY or a definite type such as "as" or "(ii)".
+Maybe, array, tuple, dictionary entry and variant-typed values may be
+constructed.
+
+After the builder is initialised, values are added using
+g_variant_builder_add_value() or g_variant_builder_add().
+
+After all the child values are added, g_variant_builder_end() frees
+the memory associated with the builder and returns the #GVariant that
+was created.
+
+This function completely ignores the previous contents of @builder.
+On one hand this means that it is valid to pass in completely
+uninitialised memory. On the other hand, this means that if you are
+initialising over top of an existing #GVariantBuilder you need to
+first call g_variant_builder_clear() in order to avoid leaking
+memory.
+
+You must not call g_variant_builder_ref() or
+g_variant_builder_unref() on a #GVariantBuilder that was initialised
+with this function. If you ever pass a reference to a
+#GVariantBuilder outside of the control of your own code then you
+should assume that the person receiving that reference may try to use
+reference counting; you should use g_variant_builder_new() instead of
+this function.
+
+
+
+
+
+
+ a #GVariantBuilder
+
+
+
+ a container type
+
+
+
+
+
+ Opens a subcontainer inside the given @builder. When done adding
+items to the subcontainer, g_variant_builder_close() must be called. @type
+is the type of the container: so to build a tuple of several values, @type
+must include the tuple itself.
+
+It is an error to call this function in any way that would cause an
+inconsistent value to be constructed (ie: adding too many values or
+a value of an incorrect type).
+
+Example of building a nested variant:
+|[<!-- language="C" -->
+GVariantBuilder builder;
+guint32 some_number = get_number ();
+g_autoptr (GHashTable) some_dict = get_dict ();
+GHashTableIter iter;
+const gchar *key;
+const GVariant *value;
+g_autoptr (GVariant) output = NULL;
+
+g_variant_builder_init (&builder, G_VARIANT_TYPE ("(ua{sv})"));
+g_variant_builder_add (&builder, "u", some_number);
+g_variant_builder_open (&builder, G_VARIANT_TYPE ("a{sv}"));
+
+g_hash_table_iter_init (&iter, some_dict);
+while (g_hash_table_iter_next (&iter, (gpointer *) &key, (gpointer *) &value))
+ {
+ g_variant_builder_open (&builder, G_VARIANT_TYPE ("{sv}"));
+ g_variant_builder_add (&builder, "s", key);
+ g_variant_builder_add (&builder, "v", value);
+ g_variant_builder_close (&builder);
+ }
+
+g_variant_builder_close (&builder);
+
+output = g_variant_builder_end (&builder);
+]|
+
+
+
+
+
+
+ a #GVariantBuilder
+
+
+
+ the #GVariantType of the container
+
+
+
+
+
+ Increases the reference count on @builder.
+
+Don't call this on stack-allocated #GVariantBuilder instances or bad
+things will happen.
+
+
+ a new reference to @builder
+
+
+
+
+ a #GVariantBuilder allocated by g_variant_builder_new()
+
+
+
+
+
+ Decreases the reference count on @builder.
+
+In the event that there are no more references, releases all memory
+associated with the #GVariantBuilder.
+
+Don't call this on stack-allocated #GVariantBuilder instances or bad
+things will happen.
+
+
+
+
+
+
+ a #GVariantBuilder allocated by g_variant_builder_new()
+
+
+
+
+
+
+ The range of possible top-level types of #GVariant instances.
+
+
+ The #GVariant is a boolean.
+
+
+ The #GVariant is a byte.
+
+
+ The #GVariant is a signed 16 bit integer.
+
+
+ The #GVariant is an unsigned 16 bit integer.
+
+
+ The #GVariant is a signed 32 bit integer.
+
+
+ The #GVariant is an unsigned 32 bit integer.
+
+
+ The #GVariant is a signed 64 bit integer.
+
+
+ The #GVariant is an unsigned 64 bit integer.
+
+
+ The #GVariant is a file handle index.
+
+
+ The #GVariant is a double precision floating
+ point value.
+
+
+ The #GVariant is a normal string.
+
+
+ The #GVariant is a D-Bus object path
+ string.
+
+
+ The #GVariant is a D-Bus signature string.
+
+
+ The #GVariant is a variant.
+
+
+ The #GVariant is a maybe-typed value.
+
+
+ The #GVariant is an array.
+
+
+ The #GVariant is a tuple.
+
+
+ The #GVariant is a dictionary entry.
+
+
+
+ #GVariantDict is a mutable interface to #GVariant dictionaries.
+
+It can be used for doing a sequence of dictionary lookups in an
+efficient way on an existing #GVariant dictionary or it can be used
+to construct new dictionaries with a hashtable-like interface. It
+can also be used for taking existing dictionaries and modifying them
+in order to create new ones.
+
+#GVariantDict can only be used with %G_VARIANT_TYPE_VARDICT
+dictionaries.
+
+It is possible to use #GVariantDict allocated on the stack or on the
+heap. When using a stack-allocated #GVariantDict, you begin with a
+call to g_variant_dict_init() and free the resources with a call to
+g_variant_dict_clear().
+
+Heap-allocated #GVariantDict follows normal refcounting rules: you
+allocate it with g_variant_dict_new() and use g_variant_dict_ref()
+and g_variant_dict_unref().
+
+g_variant_dict_end() is used to convert the #GVariantDict back into a
+dictionary-type #GVariant. When used with stack-allocated instances,
+this also implicitly frees all associated memory, but for
+heap-allocated instances, you must still call g_variant_dict_unref()
+afterwards.
+
+You will typically want to use a heap-allocated #GVariantDict when
+you expose it as part of an API. For most other uses, the
+stack-allocated form will be more convenient.
+
+Consider the following two examples that do the same thing in each
+style: take an existing dictionary and look up the "count" uint32
+key, adding 1 to it if it is found, or returning an error if the
+key is not found. Each returns the new dictionary as a floating
+#GVariant.
+
+## Using a stack-allocated GVariantDict
+
+|[<!-- language="C" -->
+ GVariant *
+ add_to_count (GVariant *orig,
+ GError **error)
+ {
+ GVariantDict dict;
+ guint32 count;
+
+ g_variant_dict_init (&dict, orig);
+ if (!g_variant_dict_lookup (&dict, "count", "u", &count))
+ {
+ g_set_error (...);
+ g_variant_dict_clear (&dict);
+ return NULL;
+ }
+
+ g_variant_dict_insert (&dict, "count", "u", count + 1);
+
+ return g_variant_dict_end (&dict);
+ }
+]|
+
+## Using heap-allocated GVariantDict
+
+|[<!-- language="C" -->
+ GVariant *
+ add_to_count (GVariant *orig,
+ GError **error)
+ {
+ GVariantDict *dict;
+ GVariant *result;
+ guint32 count;
+
+ dict = g_variant_dict_new (orig);
+
+ if (g_variant_dict_lookup (dict, "count", "u", &count))
+ {
+ g_variant_dict_insert (dict, "count", "u", count + 1);
+ result = g_variant_dict_end (dict);
+ }
+ else
+ {
+ g_set_error (...);
+ result = NULL;
+ }
+
+ g_variant_dict_unref (dict);
+
+ return result;
+ }
+]|
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Allocates and initialises a new #GVariantDict.
+
+You should call g_variant_dict_unref() on the return value when it
+is no longer needed. The memory will not be automatically freed by
+any other call.
+
+In some cases it may be easier to place a #GVariantDict directly on
+the stack of the calling function and initialise it with
+g_variant_dict_init(). This is particularly useful when you are
+using #GVariantDict to construct a #GVariant.
+
+
+ a #GVariantDict
+
+
+
+
+ the #GVariant with which to initialise the
+ dictionary
+
+
+
+
+
+ Releases all memory associated with a #GVariantDict without freeing
+the #GVariantDict structure itself.
+
+It typically only makes sense to do this on a stack-allocated
+#GVariantDict if you want to abort building the value part-way
+through. This function need not be called if you call
+g_variant_dict_end() and it also doesn't need to be called on dicts
+allocated with g_variant_dict_new (see g_variant_dict_unref() for
+that).
+
+It is valid to call this function on either an initialised
+#GVariantDict or one that was previously cleared by an earlier call
+to g_variant_dict_clear() but it is not valid to call this function
+on uninitialised memory.
+
+
+
+
+
+
+ a #GVariantDict
+
+
+
+
+
+ Checks if @key exists in @dict.
+
+
+ %TRUE if @key is in @dict
+
+
+
+
+ a #GVariantDict
+
+
+
+ the key to look up in the dictionary
+
+
+
+
+
+ Returns the current value of @dict as a #GVariant of type
+%G_VARIANT_TYPE_VARDICT, clearing it in the process.
+
+It is not permissible to use @dict in any way after this call except
+for reference counting operations (in the case of a heap-allocated
+#GVariantDict) or by reinitialising it with g_variant_dict_init() (in
+the case of stack-allocated).
+
+
+ a new, floating, #GVariant
+
+
+
+
+ a #GVariantDict
+
+
+
+
+
+ Initialises a #GVariantDict structure.
+
+If @from_asv is given, it is used to initialise the dictionary.
+
+This function completely ignores the previous contents of @dict. On
+one hand this means that it is valid to pass in completely
+uninitialised memory. On the other hand, this means that if you are
+initialising over top of an existing #GVariantDict you need to first
+call g_variant_dict_clear() in order to avoid leaking memory.
+
+You must not call g_variant_dict_ref() or g_variant_dict_unref() on a
+#GVariantDict that was initialised with this function. If you ever
+pass a reference to a #GVariantDict outside of the control of your
+own code then you should assume that the person receiving that
+reference may try to use reference counting; you should use
+g_variant_dict_new() instead of this function.
+
+
+
+
+
+
+ a #GVariantDict
+
+
+
+ the initial value for @dict
+
+
+
+
+
+ Inserts a value into a #GVariantDict.
+
+This call is a convenience wrapper that is exactly equivalent to
+calling g_variant_new() followed by g_variant_dict_insert_value().
+
+
+
+
+
+
+ a #GVariantDict
+
+
+
+ the key to insert a value for
+
+
+
+ a #GVariant varargs format string
+
+
+
+ arguments, as per @format_string
+
+
+
+
+
+ Inserts (or replaces) a key in a #GVariantDict.
+
+@value is consumed if it is floating.
+
+
+
+
+
+
+ a #GVariantDict
+
+
+
+ the key to insert a value for
+
+
+
+ the value to insert
+
+
+
+
+
+ Looks up a value in a #GVariantDict.
+
+This function is a wrapper around g_variant_dict_lookup_value() and
+g_variant_get(). In the case that %NULL would have been returned,
+this function returns %FALSE. Otherwise, it unpacks the returned
+value and returns %TRUE.
+
+@format_string determines the C types that are used for unpacking the
+values and also determines if the values are copied or borrowed, see the
+section on [GVariant format strings][gvariant-format-strings-pointers].
+
+
+ %TRUE if a value was unpacked
+
+
+
+
+ a #GVariantDict
+
+
+
+ the key to look up in the dictionary
+
+
+
+ a GVariant format string
+
+
+
+ the arguments to unpack the value into
+
+
+
+
+
+ Looks up a value in a #GVariantDict.
+
+If @key is not found in @dictionary, %NULL is returned.
+
+The @expected_type string specifies what type of value is expected.
+If the value associated with @key has a different type then %NULL is
+returned.
+
+If the key is found and the value has the correct type, it is
+returned. If @expected_type was specified then any non-%NULL return
+value will have this type.
+
+
+ the value of the dictionary key, or %NULL
+
+
+
+
+ a #GVariantDict
+
+
+
+ the key to look up in the dictionary
+
+
+
+ a #GVariantType, or %NULL
+
+
+
+
+
+ Increases the reference count on @dict.
+
+Don't call this on stack-allocated #GVariantDict instances or bad
+things will happen.
+
+
+ a new reference to @dict
+
+
+
+
+ a heap-allocated #GVariantDict
+
+
+
+
+
+ Removes a key and its associated value from a #GVariantDict.
+
+
+ %TRUE if the key was found and removed
+
+
+
+
+ a #GVariantDict
+
+
+
+ the key to remove
+
+
+
+
+
+ Decreases the reference count on @dict.
+
+In the event that there are no more references, releases all memory
+associated with the #GVariantDict.
+
+Don't call this on stack-allocated #GVariantDict instances or bad
+things will happen.
+
+
+
+
+
+
+ a heap-allocated #GVariantDict
+
+
+
+
+
+
+ #GVariantIter is an opaque data structure and can only be accessed
+using the following functions.
+
+
+
+
+
+
+
+ Creates a new heap-allocated #GVariantIter to iterate over the
+container that was being iterated over by @iter. Iteration begins on
+the new iterator from the current position of the old iterator but
+the two copies are independent past that point.
+
+Use g_variant_iter_free() to free the return value when you no longer
+need it.
+
+A reference is taken to the container that @iter is iterating over
+and will be related only when g_variant_iter_free() is called.
+
+
+ a new heap-allocated #GVariantIter
+
+
+
+
+ a #GVariantIter
+
+
+
+
+
+ Frees a heap-allocated #GVariantIter. Only call this function on
+iterators that were returned by g_variant_iter_new() or
+g_variant_iter_copy().
+
+
+
+
+
+
+ a heap-allocated #GVariantIter
+
+
+
+
+
+ Initialises (without allocating) a #GVariantIter. @iter may be
+completely uninitialised prior to this call; its old value is
+ignored.
+
+The iterator remains valid for as long as @value exists, and need not
+be freed in any way.
+
+
+ the number of items in @value
+
+
+
+
+ a pointer to a #GVariantIter
+
+
+
+ a container #GVariant
+
+
+
+
+
+ Gets the next item in the container and unpacks it into the variable
+argument list according to @format_string, returning %TRUE.
+
+If no more items remain then %FALSE is returned.
+
+On the first call to this function, the pointers appearing on the
+variable argument list are assumed to point at uninitialised memory.
+On the second and later calls, it is assumed that the same pointers
+will be given and that they will point to the memory as set by the
+previous call to this function. This allows the previous values to
+be freed, as appropriate.
+
+This function is intended to be used with a while loop as
+demonstrated in the following example. This function can only be
+used when iterating over an array. It is only valid to call this
+function with a string constant for the format string and the same
+string constant must be used each time. Mixing calls to this
+function and g_variant_iter_next() or g_variant_iter_next_value() on
+the same iterator causes undefined behavior.
+
+If you break out of a such a while loop using g_variant_iter_loop() then
+you must free or unreference all the unpacked values as you would with
+g_variant_get(). Failure to do so will cause a memory leak.
+
+Here is an example for memory management with g_variant_iter_loop():
+|[<!-- language="C" -->
+ // Iterates a dictionary of type 'a{sv}'
+ void
+ iterate_dictionary (GVariant *dictionary)
+ {
+ GVariantIter iter;
+ GVariant *value;
+ gchar *key;
+
+ g_variant_iter_init (&iter, dictionary);
+ while (g_variant_iter_loop (&iter, "{sv}", &key, &value))
+ {
+ g_print ("Item '%s' has type '%s'\n", key,
+ g_variant_get_type_string (value));
+
+ // no need to free 'key' and 'value' here
+ // unless breaking out of this loop
+ }
+ }
+]|
+
+For most cases you should use g_variant_iter_next().
+
+This function is really only useful when unpacking into #GVariant or
+#GVariantIter in order to allow you to skip the call to
+g_variant_unref() or g_variant_iter_free().
+
+For example, if you are only looping over simple integer and string
+types, g_variant_iter_next() is definitely preferred. For string
+types, use the '&' prefix to avoid allocating any memory at all (and
+thereby avoiding the need to free anything as well).
+
+@format_string determines the C types that are used for unpacking
+the values and also determines if the values are copied or borrowed.
+
+See the section on
+[GVariant format strings][gvariant-format-strings-pointers].
+
+
+ %TRUE if a value was unpacked, or %FALSE if there was no
+ value
+
+
+
+
+ a #GVariantIter
+
+
+
+ a GVariant format string
+
+
+
+ the arguments to unpack the value into
+
+
+
+
+
+ Queries the number of child items in the container that we are
+iterating over. This is the total number of items -- not the number
+of items remaining.
+
+This function might be useful for preallocation of arrays.
+
+
+ the number of children in the container
+
+
+
+
+ a #GVariantIter
+
+
+
+
+
+ Gets the next item in the container and unpacks it into the variable
+argument list according to @format_string, returning %TRUE.
+
+If no more items remain then %FALSE is returned.
+
+All of the pointers given on the variable arguments list of this
+function are assumed to point at uninitialised memory. It is the
+responsibility of the caller to free all of the values returned by
+the unpacking process.
+
+Here is an example for memory management with g_variant_iter_next():
+|[<!-- language="C" -->
+ // Iterates a dictionary of type 'a{sv}'
+ void
+ iterate_dictionary (GVariant *dictionary)
+ {
+ GVariantIter iter;
+ GVariant *value;
+ gchar *key;
+
+ g_variant_iter_init (&iter, dictionary);
+ while (g_variant_iter_next (&iter, "{sv}", &key, &value))
+ {
+ g_print ("Item '%s' has type '%s'\n", key,
+ g_variant_get_type_string (value));
+
+ // must free data for ourselves
+ g_variant_unref (value);
+ g_free (key);
+ }
+ }
+]|
+
+For a solution that is likely to be more convenient to C programmers
+when dealing with loops, see g_variant_iter_loop().
+
+@format_string determines the C types that are used for unpacking
+the values and also determines if the values are copied or borrowed.
+
+See the section on
+[GVariant format strings][gvariant-format-strings-pointers].
+
+
+ %TRUE if a value was unpacked, or %FALSE if there as no value
+
+
+
+
+ a #GVariantIter
+
+
+
+ a GVariant format string
+
+
+
+ the arguments to unpack the value into
+
+
+
+
+
+ Gets the next item in the container. If no more items remain then
+%NULL is returned.
+
+Use g_variant_unref() to drop your reference on the return value when
+you no longer need it.
+
+Here is an example for iterating with g_variant_iter_next_value():
+|[<!-- language="C" -->
+ // recursively iterate a container
+ void
+ iterate_container_recursive (GVariant *container)
+ {
+ GVariantIter iter;
+ GVariant *child;
+
+ g_variant_iter_init (&iter, container);
+ while ((child = g_variant_iter_next_value (&iter)))
+ {
+ g_print ("type '%s'\n", g_variant_get_type_string (child));
+
+ if (g_variant_is_container (child))
+ iterate_container_recursive (child);
+
+ g_variant_unref (child);
+ }
+ }
+]|
+
+
+ a #GVariant, or %NULL
+
+
+
+
+ a #GVariantIter
+
+
+
+
+
+
+ Error codes returned by parsing text-format GVariants.
+
+
+ generic error (unused)
+
+
+ a non-basic #GVariantType was given where a basic type was expected
+
+
+ cannot infer the #GVariantType
+
+
+ an indefinite #GVariantType was given where a definite type was expected
+
+
+ extra data after parsing finished
+
+
+ invalid character in number or unicode escape
+
+
+ not a valid #GVariant format string
+
+
+ not a valid object path
+
+
+ not a valid type signature
+
+
+ not a valid #GVariant type string
+
+
+ could not find a common type for array entries
+
+
+ the numerical value is out of range of the given type
+
+
+ the numerical value is out of range for any type
+
+
+ cannot parse as variant of the specified type
+
+
+ an unexpected token was encountered
+
+
+ an unknown keyword was encountered
+
+
+ unterminated string constant
+
+
+ no value given
+
+
+ variant was too deeply nested; #GVariant is only guaranteed to handle nesting up to 64 levels (Since: 2.64)
+
+
+
+ This section introduces the GVariant type system. It is based, in
+large part, on the D-Bus type system, with two major changes and
+some minor lifting of restrictions. The
+[D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html),
+therefore, provides a significant amount of
+information that is useful when working with GVariant.
+
+The first major change with respect to the D-Bus type system is the
+introduction of maybe (or "nullable") types. Any type in GVariant can be
+converted to a maybe type, in which case, "nothing" (or "null") becomes a
+valid value. Maybe types have been added by introducing the
+character "m" to type strings.
+
+The second major change is that the GVariant type system supports the
+concept of "indefinite types" -- types that are less specific than
+the normal types found in D-Bus. For example, it is possible to speak
+of "an array of any type" in GVariant, where the D-Bus type system
+would require you to speak of "an array of integers" or "an array of
+strings". Indefinite types have been added by introducing the
+characters "*", "?" and "r" to type strings.
+
+Finally, all arbitrary restrictions relating to the complexity of
+types are lifted along with the restriction that dictionary entries
+may only appear nested inside of arrays.
+
+Just as in D-Bus, GVariant types are described with strings ("type
+strings"). Subject to the differences mentioned above, these strings
+are of the same form as those found in D-Bus. Note, however: D-Bus
+always works in terms of messages and therefore individual type
+strings appear nowhere in its interface. Instead, "signatures"
+are a concatenation of the strings of the type of each argument in a
+message. GVariant deals with single values directly so GVariant type
+strings always describe the type of exactly one value. This means
+that a D-Bus signature string is generally not a valid GVariant type
+string -- except in the case that it is the signature of a message
+containing exactly one argument.
+
+An indefinite type is similar in spirit to what may be called an
+abstract type in other type systems. No value can exist that has an
+indefinite type as its type, but values can exist that have types
+that are subtypes of indefinite types. That is to say,
+g_variant_get_type() will never return an indefinite type, but
+calling g_variant_is_of_type() with an indefinite type may return
+%TRUE. For example, you cannot have a value that represents "an
+array of no particular type", but you can have an "array of integers"
+which certainly matches the type of "an array of no particular type",
+since "array of integers" is a subtype of "array of no particular
+type".
+
+This is similar to how instances of abstract classes may not
+directly exist in other type systems, but instances of their
+non-abstract subtypes may. For example, in GTK, no object that has
+the type of #GtkBin can exist (since #GtkBin is an abstract class),
+but a #GtkWindow can certainly be instantiated, and you would say
+that the #GtkWindow is a #GtkBin (since #GtkWindow is a subclass of
+#GtkBin).
+
+## GVariant Type Strings
+
+A GVariant type string can be any of the following:
+
+- any basic type string (listed below)
+
+- "v", "r" or "*"
+
+- one of the characters 'a' or 'm', followed by another type string
+
+- the character '(', followed by a concatenation of zero or more other
+ type strings, followed by the character ')'
+
+- the character '{', followed by a basic type string (see below),
+ followed by another type string, followed by the character '}'
+
+A basic type string describes a basic type (as per
+g_variant_type_is_basic()) and is always a single character in length.
+The valid basic type strings are "b", "y", "n", "q", "i", "u", "x", "t",
+"h", "d", "s", "o", "g" and "?".
+
+The above definition is recursive to arbitrary depth. "aaaaai" and
+"(ui(nq((y)))s)" are both valid type strings, as is
+"a(aa(ui)(qna{ya(yd)}))". In order to not hit memory limits, #GVariant
+imposes a limit on recursion depth of 65 nested containers. This is the
+limit in the D-Bus specification (64) plus one to allow a #GDBusMessage to
+be nested in a top-level tuple.
+
+The meaning of each of the characters is as follows:
+- `b`: the type string of %G_VARIANT_TYPE_BOOLEAN; a boolean value.
+- `y`: the type string of %G_VARIANT_TYPE_BYTE; a byte.
+- `n`: the type string of %G_VARIANT_TYPE_INT16; a signed 16 bit integer.
+- `q`: the type string of %G_VARIANT_TYPE_UINT16; an unsigned 16 bit integer.
+- `i`: the type string of %G_VARIANT_TYPE_INT32; a signed 32 bit integer.
+- `u`: the type string of %G_VARIANT_TYPE_UINT32; an unsigned 32 bit integer.
+- `x`: the type string of %G_VARIANT_TYPE_INT64; a signed 64 bit integer.
+- `t`: the type string of %G_VARIANT_TYPE_UINT64; an unsigned 64 bit integer.
+- `h`: the type string of %G_VARIANT_TYPE_HANDLE; a signed 32 bit value
+ that, by convention, is used as an index into an array of file
+ descriptors that are sent alongside a D-Bus message.
+- `d`: the type string of %G_VARIANT_TYPE_DOUBLE; a double precision
+ floating point value.
+- `s`: the type string of %G_VARIANT_TYPE_STRING; a string.
+- `o`: the type string of %G_VARIANT_TYPE_OBJECT_PATH; a string in the form
+ of a D-Bus object path.
+- `g`: the type string of %G_VARIANT_TYPE_SIGNATURE; a string in the form of
+ a D-Bus type signature.
+- `?`: the type string of %G_VARIANT_TYPE_BASIC; an indefinite type that
+ is a supertype of any of the basic types.
+- `v`: the type string of %G_VARIANT_TYPE_VARIANT; a container type that
+ contain any other type of value.
+- `a`: used as a prefix on another type string to mean an array of that
+ type; the type string "ai", for example, is the type of an array of
+ signed 32-bit integers.
+- `m`: used as a prefix on another type string to mean a "maybe", or
+ "nullable", version of that type; the type string "ms", for example,
+ is the type of a value that maybe contains a string, or maybe contains
+ nothing.
+- `()`: used to enclose zero or more other concatenated type strings to
+ create a tuple type; the type string "(is)", for example, is the type of
+ a pair of an integer and a string.
+- `r`: the type string of %G_VARIANT_TYPE_TUPLE; an indefinite type that is
+ a supertype of any tuple type, regardless of the number of items.
+- `{}`: used to enclose a basic type string concatenated with another type
+ string to create a dictionary entry type, which usually appears inside of
+ an array to form a dictionary; the type string "a{sd}", for example, is
+ the type of a dictionary that maps strings to double precision floating
+ point values.
+
+ The first type (the basic type) is the key type and the second type is
+ the value type. The reason that the first type is restricted to being a
+ basic type is so that it can easily be hashed.
+- `*`: the type string of %G_VARIANT_TYPE_ANY; the indefinite type that is
+ a supertype of all types. Note that, as with all type strings, this
+ character represents exactly one type. It cannot be used inside of tuples
+ to mean "any number of items".
+
+Any type string of a container that contains an indefinite type is,
+itself, an indefinite type. For example, the type string "a*"
+(corresponding to %G_VARIANT_TYPE_ARRAY) is an indefinite type
+that is a supertype of every array type. "(*s)" is a supertype
+of all tuples that contain exactly two items where the second
+item is a string.
+
+"a{?*}" is an indefinite type that is a supertype of all arrays
+containing dictionary entries where the key is any basic type and
+the value is any type at all. This is, by definition, a dictionary,
+so this type string corresponds to %G_VARIANT_TYPE_DICTIONARY. Note
+that, due to the restriction that the key of a dictionary entry must
+be a basic type, "{**}" is not a valid type string.
+
+
+ Creates a new #GVariantType corresponding to the type string given
+by @type_string. It is appropriate to call g_variant_type_free() on
+the return value.
+
+It is a programmer error to call this function with an invalid type
+string. Use g_variant_type_string_is_valid() if you are unsure.
+
+
+ a new #GVariantType
+
+
+
+
+ a valid GVariant type string
+
+
+
+
+
+ Constructs the type corresponding to an array of elements of the
+type @type.
+
+It is appropriate to call g_variant_type_free() on the return value.
+
+
+ a new array #GVariantType
+
+Since 2.24
+
+
+
+
+ a #GVariantType
+
+
+
+
+
+ Constructs the type corresponding to a dictionary entry with a key
+of type @key and a value of type @value.
+
+It is appropriate to call g_variant_type_free() on the return value.
+
+
+ a new dictionary entry #GVariantType
+
+Since 2.24
+
+
+
+
+ a basic #GVariantType
+
+
+
+ a #GVariantType
+
+
+
+
+
+ Constructs the type corresponding to a maybe instance containing
+type @type or Nothing.
+
+It is appropriate to call g_variant_type_free() on the return value.
+
+
+ a new maybe #GVariantType
+
+Since 2.24
+
+
+
+
+ a #GVariantType
+
+
+
+
+
+ Constructs a new tuple type, from @items.
+
+@length is the number of items in @items, or -1 to indicate that
+@items is %NULL-terminated.
+
+It is appropriate to call g_variant_type_free() on the return value.
+
+
+ a new tuple #GVariantType
+
+Since 2.24
+
+
+
+
+ an array of #GVariantTypes, one for each item
+
+
+
+
+
+ the length of @items, or -1
+
+
+
+
+
+ Makes a copy of a #GVariantType. It is appropriate to call
+g_variant_type_free() on the return value. @type may not be %NULL.
+
+
+ a new #GVariantType
+
+Since 2.24
+
+
+
+
+ a #GVariantType
+
+
+
+
+
+ Returns a newly-allocated copy of the type string corresponding to
+@type. The returned string is nul-terminated. It is appropriate to
+call g_free() on the return value.
+
+
+ the corresponding type string
+
+Since 2.24
+
+
+
+
+ a #GVariantType
+
+
+
+
+
+ Determines the element type of an array or maybe type.
+
+This function may only be used with array or maybe types.
+
+
+ the element type of @type
+
+Since 2.24
+
+
+
+
+ an array or maybe #GVariantType
+
+
+
+
+
+ Compares @type1 and @type2 for equality.
+
+Only returns %TRUE if the types are exactly equal. Even if one type
+is an indefinite type and the other is a subtype of it, %FALSE will
+be returned if they are not exactly equal. If you want to check for
+subtypes, use g_variant_type_is_subtype_of().
+
+The argument types of @type1 and @type2 are only #gconstpointer to
+allow use with #GHashTable without function pointer casting. For
+both arguments, a valid #GVariantType must be provided.
+
+
+ %TRUE if @type1 and @type2 are exactly equal
+
+Since 2.24
+
+
+
+
+ a #GVariantType
+
+
+
+ a #GVariantType
+
+
+
+
+
+ Determines the first item type of a tuple or dictionary entry
+type.
+
+This function may only be used with tuple or dictionary entry types,
+but must not be used with the generic tuple type
+%G_VARIANT_TYPE_TUPLE.
+
+In the case of a dictionary entry type, this returns the type of
+the key.
+
+%NULL is returned in case of @type being %G_VARIANT_TYPE_UNIT.
+
+This call, together with g_variant_type_next() provides an iterator
+interface over tuple and dictionary entry types.
+
+
+ the first item type of @type, or %NULL
+
+Since 2.24
+
+
+
+
+ a tuple or dictionary entry #GVariantType
+
+
+
+
+
+ Frees a #GVariantType that was allocated with
+g_variant_type_copy(), g_variant_type_new() or one of the container
+type constructor functions.
+
+In the case that @type is %NULL, this function does nothing.
+
+Since 2.24
+
+
+
+
+
+
+ a #GVariantType, or %NULL
+
+
+
+
+
+ Returns the length of the type string corresponding to the given
+@type. This function must be used to determine the valid extent of
+the memory region returned by g_variant_type_peek_string().
+
+
+ the length of the corresponding type string
+
+Since 2.24
+
+
+
+
+ a #GVariantType
+
+
+
+
+
+ Hashes @type.
+
+The argument type of @type is only #gconstpointer to allow use with
+#GHashTable without function pointer casting. A valid
+#GVariantType must be provided.
+
+
+ the hash value
+
+Since 2.24
+
+
+
+
+ a #GVariantType
+
+
+
+
+
+ Determines if the given @type is an array type. This is true if the
+type string for @type starts with an 'a'.
+
+This function returns %TRUE for any indefinite type for which every
+definite subtype is an array type -- %G_VARIANT_TYPE_ARRAY, for
+example.
+
+
+ %TRUE if @type is an array type
+
+Since 2.24
+
+
+
+
+ a #GVariantType
+
+
+
+
+
+ Determines if the given @type is a basic type.
+
+Basic types are booleans, bytes, integers, doubles, strings, object
+paths and signatures.
+
+Only a basic type may be used as the key of a dictionary entry.
+
+This function returns %FALSE for all indefinite types except
+%G_VARIANT_TYPE_BASIC.
+
+
+ %TRUE if @type is a basic type
+
+Since 2.24
+
+
+
+
+ a #GVariantType
+
+
+
+
+
+ Determines if the given @type is a container type.
+
+Container types are any array, maybe, tuple, or dictionary
+entry types plus the variant type.
+
+This function returns %TRUE for any indefinite type for which every
+definite subtype is a container -- %G_VARIANT_TYPE_ARRAY, for
+example.
+
+
+ %TRUE if @type is a container type
+
+Since 2.24
+
+
+
+
+ a #GVariantType
+
+
+
+
+
+ Determines if the given @type is definite (ie: not indefinite).
+
+A type is definite if its type string does not contain any indefinite
+type characters ('*', '?', or 'r').
+
+A #GVariant instance may not have an indefinite type, so calling
+this function on the result of g_variant_get_type() will always
+result in %TRUE being returned. Calling this function on an
+indefinite type like %G_VARIANT_TYPE_ARRAY, however, will result in
+%FALSE being returned.
+
+
+ %TRUE if @type is definite
+
+Since 2.24
+
+
+
+
+ a #GVariantType
+
+
+
+
+
+ Determines if the given @type is a dictionary entry type. This is
+true if the type string for @type starts with a '{'.
+
+This function returns %TRUE for any indefinite type for which every
+definite subtype is a dictionary entry type --
+%G_VARIANT_TYPE_DICT_ENTRY, for example.
+
+
+ %TRUE if @type is a dictionary entry type
+
+Since 2.24
+
+
+
+
+ a #GVariantType
+
+
+
+
+
+ Determines if the given @type is a maybe type. This is true if the
+type string for @type starts with an 'm'.
+
+This function returns %TRUE for any indefinite type for which every
+definite subtype is a maybe type -- %G_VARIANT_TYPE_MAYBE, for
+example.
+
+
+ %TRUE if @type is a maybe type
+
+Since 2.24
+
+
+
+
+ a #GVariantType
+
+
+
+
+
+ Checks if @type is a subtype of @supertype.
+
+This function returns %TRUE if @type is a subtype of @supertype. All
+types are considered to be subtypes of themselves. Aside from that,
+only indefinite types can have subtypes.
+
+
+ %TRUE if @type is a subtype of @supertype
+
+Since 2.24
+
+
+
+
+ a #GVariantType
+
+
+
+ a #GVariantType
+
+
+
+
+
+ Determines if the given @type is a tuple type. This is true if the
+type string for @type starts with a '(' or if @type is
+%G_VARIANT_TYPE_TUPLE.
+
+This function returns %TRUE for any indefinite type for which every
+definite subtype is a tuple type -- %G_VARIANT_TYPE_TUPLE, for
+example.
+
+
+ %TRUE if @type is a tuple type
+
+Since 2.24
+
+
+
+
+ a #GVariantType
+
+
+
+
+
+ Determines if the given @type is the variant type.
+
+
+ %TRUE if @type is the variant type
+
+Since 2.24
+
+
+
+
+ a #GVariantType
+
+
+
+
+
+ Determines the key type of a dictionary entry type.
+
+This function may only be used with a dictionary entry type. Other
+than the additional restriction, this call is equivalent to
+g_variant_type_first().
+
+
+ the key type of the dictionary entry
+
+Since 2.24
+
+
+
+
+ a dictionary entry #GVariantType
+
+
+
+
+
+ Determines the number of items contained in a tuple or
+dictionary entry type.
+
+This function may only be used with tuple or dictionary entry types,
+but must not be used with the generic tuple type
+%G_VARIANT_TYPE_TUPLE.
+
+In the case of a dictionary entry type, this function will always
+return 2.
+
+
+ the number of items in @type
+
+Since 2.24
+
+
+
+
+ a tuple or dictionary entry #GVariantType
+
+
+
+
+
+ Determines the next item type of a tuple or dictionary entry
+type.
+
+@type must be the result of a previous call to
+g_variant_type_first() or g_variant_type_next().
+
+If called on the key type of a dictionary entry then this call
+returns the value type. If called on the value type of a dictionary
+entry then this call returns %NULL.
+
+For tuples, %NULL is returned when @type is the last item in a tuple.
+
+
+ the next #GVariantType after @type, or %NULL
+
+Since 2.24
+
+
+
+
+ a #GVariantType from a previous call
+
+
+
+
+
+ Returns the type string corresponding to the given @type. The
+result is not nul-terminated; in order to determine its length you
+must call g_variant_type_get_string_length().
+
+To get a nul-terminated string, see g_variant_type_dup_string().
+
+
+ the corresponding type string (not nul-terminated)
+
+Since 2.24
+
+
+
+
+ a #GVariantType
+
+
+
+
+
+ Determines the value type of a dictionary entry type.
+
+This function may only be used with a dictionary entry type.
+
+
+ the value type of the dictionary entry
+
+Since 2.24
+
+
+
+
+ a dictionary entry #GVariantType
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Checks if @type_string is a valid GVariant type string. This call is
+equivalent to calling g_variant_type_string_scan() and confirming
+that the following character is a nul terminator.
+
+
+ %TRUE if @type_string is exactly one valid type string
+
+Since 2.24
+
+
+
+
+ a pointer to any string
+
+
+
+
+
+ Scan for a single complete and valid GVariant type string in @string.
+The memory pointed to by @limit (or bytes beyond it) is never
+accessed.
+
+If a valid type string is found, @endptr is updated to point to the
+first character past the end of the string that was found and %TRUE
+is returned.
+
+If there is no valid type string starting at @string, or if the type
+string does not end before @limit then %FALSE is returned.
+
+For the simple case of checking if a string is a valid type string,
+see g_variant_type_string_is_valid().
+
+
+ %TRUE if a valid type string was found
+
+
+
+
+ a pointer to any string
+
+
+
+ the end of @string, or %NULL
+
+
+
+ location to store the end pointer, or %NULL
+
+
+
+
+
+
+ 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().
+
+
+
+
+
+
+ On Windows, this macro defines a DllMain() function that stores
+the actual DLL name that the code being compiled will be included in.
+
+On non-Windows platforms, expands to nothing.
+
+
+
+ empty or "static"
+
+
+ the name of the (pointer to the) char array where
+ the DLL name will be stored. If this is used, you must also
+ include `windows.h`. If you need a more complex DLL entry
+ point function, you cannot use this
+
+
+
+
+ On Windows, this macro defines an expression which evaluates to
+%TRUE if the code is running on a version of Windows where the wide
+character versions of the Win32 API functions, and the wide character
+versions of the C library functions work. (They are always present in
+the DLLs, but don't work on Windows 9x and Me.)
+
+On non-Windows platforms, it is not defined.
+
+
+
+ On Windows, this macro defines an expression which evaluates to
+%TRUE if the code is running on an NT-based Windows operating system.
+
+On non-Windows platforms, it is not defined.
+
+
+
+
+
+
+
+ A wrapper for the POSIX abort() function.
+
+On Windows it is a function that makes extra effort (including a call
+to abort()) to ensure that a debugger-catchable exception is thrown
+before the program terminates.
+
+See your C library manual for more details about abort().
+
+
+
+ A wrapper for the POSIX access() function. This function is used to
+test a pathname for one or several of read, write or execute
+permissions, or just existence.
+
+On Windows, the file protection mechanism is not at all POSIX-like,
+and the underlying function in the C library only checks the
+FAT-style READONLY attribute, and does not look at the ACL of a
+file at all. This function is this in practise almost useless on
+Windows. Software that needs to handle file permissions on Windows
+more exactly should use the Win32 API.
+
+See your C library manual for more details about access().
+
+
+ zero if the pathname refers to an existing file system
+ object that has all the tested permissions, or -1 otherwise
+ or on error.
+
+
+
+
+ a pathname in the GLib file name encoding
+ (UTF-8 on Windows)
+
+
+
+ as in access()
+
+
+
+
+
+ This function is similar to g_malloc(), allocating (@n_blocks * @n_block_bytes)
+bytes, but care is taken to align the allocated memory to with the given
+alignment value. Additionally, it will detect possible overflow during
+multiplication.
+
+If the allocation fails (because the system is out of memory),
+the program is terminated.
+
+Aligned memory allocations returned by this function can only be
+freed using g_aligned_free_sized() or g_aligned_free().
+
+
+ the allocated memory
+
+
+
+
+ the number of blocks to allocate
+
+
+
+ the size of each block in bytes
+
+
+
+ the alignment to be enforced, which must be a positive power of 2
+ and a multiple of `sizeof(void*)`
+
+
+
+
+
+ This function is similar to g_aligned_alloc(), but it will
+also clear the allocated memory before returning it.
+
+
+ the allocated, cleared memory
+
+
+
+
+ the number of blocks to allocate
+
+
+
+ the size of each block in bytes
+
+
+
+ the alignment to be enforced, which must be a positive power of 2
+ and a multiple of `sizeof(void*)`
+
+
+
+
+
+ Frees the memory allocated by g_aligned_alloc().
+
+
+
+
+
+
+ the memory to deallocate
+
+
+
+
+
+ Frees the memory pointed to by @mem, assuming it is has the given @size and
+@alignment.
+
+If @mem is %NULL this is a no-op (and @size is ignored).
+
+It is an error if @size doesn’t match the size, or @alignment doesn’t match
+the alignment, passed when @mem was allocated. @size and @alignment are
+passed to this function to allow optimizations in the allocator. If you
+don’t know either of them, use g_aligned_free() instead.
+
+
+
+
+
+
+ the memory to free
+
+
+
+ alignment of @mem
+
+
+
+ size of @mem, in bytes
+
+
+
+
+
+ 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():
+
+- alloca() is very fast, as on most systems it's implemented by just adjusting
+ the stack pointer register.
+
+- It doesn't cause any memory fragmentation, within its scope, separate alloca()
+ blocks just build up and are released together at function end.
+
+- 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.
+
+- 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.
+
+- Allowing @size to be specified by an untrusted party would allow for them
+ to trigger a segmentation fault by specifying a large size, leading to a
+ denial of service vulnerability. @size must always be entirely under the
+ control of the program.
+
+- 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.
+
+
+
+ number of bytes to allocate.
+
+
+
+
+ Wraps g_alloca() and initializes allocated memory to zeroes.
+If @size is `0` it returns %NULL.
+
+Note that the @size argument will be evaluated multiple times.
+
+
+
+ number of bytes to allocate.
+
+
+
+
+ An "atomically reference counted box", or "ArcBox", is an opaque wrapper
+data type that is guaranteed to be as big as the size of a given data type,
+and which augments the given data type with thread safe reference counting
+semantics for its memory management.
+
+ArcBox is useful if you have a plain old data type, like a structure
+typically placed on the stack, and you wish to provide additional API
+to use it on the heap; or if you want to implement a new type to be
+passed around by reference without necessarily implementing copy/free
+semantics or your own reference counting.
+
+The typical use is:
+
+|[<!-- language="C" -->
+typedef struct {
+ char *name;
+ char *address;
+ char *city;
+ char *state;
+ int age;
+} Person;
+
+Person *
+person_new (void)
+{
+ return g_atomic_rc_box_new0 (Person);
+}
+]|
+
+Every time you wish to acquire a reference on the memory, you should
+call g_atomic_rc_box_acquire(); similarly, when you wish to release a reference
+you should call g_atomic_rc_box_release():
+
+|[<!-- language="C" -->
+// Add a Person to the Database; the Database acquires ownership
+// of the Person instance
+void
+add_person_to_database (Database *db, Person *p)
+{
+ db->persons = g_list_prepend (db->persons, g_atomic_rc_box_acquire (p));
+}
+
+// Removes a Person from the Database; the reference acquired by
+// add_person_to_database() is released here
+void
+remove_person_from_database (Database *db, Person *p)
+{
+ db->persons = g_list_remove (db->persons, p);
+ g_atomic_rc_box_release (p);
+}
+]|
+
+If you have additional memory allocated inside the structure, you can
+use g_atomic_rc_box_release_full(), which takes a function pointer, which
+will be called if the reference released was the last:
+
+|[<!-- language="C" -->
+void
+person_clear (Person *p)
+{
+ g_free (p->name);
+ g_free (p->address);
+ g_free (p->city);
+ g_free (p->state);
+}
+
+void
+remove_person_from_database (Database *db, Person *p)
+{
+ db->persons = g_list_remove (db->persons, p);
+ g_atomic_rc_box_release_full (p, (GDestroyNotify) person_clear);
+}
+]|
+
+If you wish to transfer the ownership of a reference counted data
+type without increasing the reference count, you can use g_steal_pointer():
+
+|[<!-- language="C" -->
+ Person *p = g_atomic_rc_box_new (Person);
+
+ fill_person_details (p);
+
+ add_person_to_database (db, g_steal_pointer (&p));
+]|
+
+## Thread safety
+
+The reference counting operations on data allocated using g_atomic_rc_box_alloc(),
+g_atomic_rc_box_new(), and g_atomic_rc_box_dup() are guaranteed to be atomic, and thus
+can be safely be performed by different threads. It is important to note that
+only the reference acquisition and release are atomic; changes to the content
+of the data are your responsibility.
+
+## Automatic pointer clean up
+
+If you want to add g_autoptr() support to your plain old data type through
+reference counting, you can use the G_DEFINE_AUTOPTR_CLEANUP_FUNC() and
+g_atomic_rc_box_release():
+
+|[<!-- language="C" -->
+G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, g_atomic_rc_box_release)
+]|
+
+If you need to clear the contents of the data, you will need to use an
+ancillary function that calls g_rc_box_release_full():
+
+|[<!-- language="C" -->
+static void
+my_data_struct_release (MyDataStruct *data)
+{
+ // my_data_struct_clear() is defined elsewhere
+ g_atomic_rc_box_release_full (data, (GDestroyNotify) my_data_struct_clear);
+}
+
+G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, my_data_struct_release)
+]|
+
+
+ Adds the value on to the end of the array. The array will grow in
+size automatically if necessary.
+
+g_array_append_val() is a macro which uses a reference to the value
+parameter @v. This means that you cannot use it with literal values
+such as "27". You must use variables.
+
+
+
+ a #GArray
+
+
+ the value to append to the #GArray
+
+
+
+
+ Returns the element of a #GArray at the given index. The return
+value is cast to the given type. This is the main way to read or write an
+element in a #GArray.
+
+Writing an element is typically done by reference, as in the following
+example. This example gets a pointer to an element in a #GArray, and then
+writes to a field in it:
+|[<!-- language="C" -->
+ EDayViewEvent *event;
+ // This gets a pointer to the 4th element in the array of
+ // EDayViewEvent structs.
+ event = &g_array_index (events, EDayViewEvent, 3);
+ event->start_time = g_get_current_time ();
+]|
+
+This example reads from and writes to an array of integers:
+|[<!-- language="C" -->
+ g_autoptr(GArray) int_array = g_array_new (FALSE, FALSE, sizeof (guint));
+ for (guint i = 0; i < 10; i++)
+ g_array_append_val (int_array, i);
+
+ guint *my_int = &g_array_index (int_array, guint, 1);
+ g_print ("Int at index 1 is %u; decrementing it\n", *my_int);
+ *my_int = *my_int - 1;
+]|
+
+
+
+ a #GArray
+
+
+ the type of the elements
+
+
+ the index of the element to return
+
+
+
+
+ Inserts an element into an array at the given index.
+
+g_array_insert_val() is a macro which uses a reference to the value
+parameter @v. This means that you cannot use it with literal values
+such as "27". You must use variables.
+
+
+
+ a #GArray
+
+
+ the index to place the element at
+
+
+ the value to insert into the array
+
+
+
+
+ Creates a new #GArray with @data as array data, @len as length and a
+reference count of 1.
+
+This avoids having to copy the data manually, when it can just be
+inherited. @data will eventually be freed using g_free(), so must
+have been allocated with a suitable allocator.
+
+In case the elements need to be cleared when the array is freed, use
+g_array_set_clear_func() to set a #GDestroyNotify function to perform
+such task.
+
+Do not use it if @len or @element_size are greater than %G_MAXUINT.
+#GArray stores the length of its data in #guint, which may be shorter
+than #gsize.
+
+
+ A new #GArray
+
+
+
+
+
+
+ an array of
+ elements of @element_size, or %NULL for an empty array
+
+
+
+
+
+ the number of elements in @data
+
+
+
+ %TRUE if #GArray elements should be automatically cleared
+ to 0 when they are allocated
+
+
+
+ the size of each element in bytes
+
+
+
+
+
+ Creates a new #GArray with @data as array data, computing the length of it
+and setting the reference count to 1.
+
+This avoids having to copy the data manually, when it can just be
+inherited. @data will eventually be freed using g_free(), so must
+have been allocated with a suitable allocator.
+
+The length is calculated by iterating through @data until the first %NULL
+element is found.
+
+In case the elements need to be cleared when the array is freed, use
+g_array_set_clear_func() to set a #GDestroyNotify function to perform
+such task.
+
+Do not use it if @data length or @element_size are greater than %G_MAXUINT.
+#GArray stores the length of its data in #guint, which may be shorter
+than #gsize.
+
+
+ A new #GArray
+
+
+
+
+
+
+ an array of elements of @element_size
+
+
+
+
+
+ %TRUE if #GArray elements should be automatically cleared
+ to 0 when they are allocated
+
+
+
+ the size of each element in bytes
+
+
+
+
+
+ Adds the value on to the start of the array. The array will grow in
+size automatically if necessary.
+
+This operation is slower than g_array_append_val() since the
+existing elements in the array have to be moved to make space for
+the new element.
+
+g_array_prepend_val() is a macro which uses a reference to the value
+parameter @v. This means that you cannot use it with literal values
+such as "27". You must use variables.
+
+
+
+ a #GArray
+
+
+ the value to prepend to the #GArray
+
+
+
+
+ Arrays are similar to standard C arrays, except that they grow
+automatically as elements are added.
+
+Array elements can be of any size (though all elements of one array
+are the same size), and the array can be automatically cleared to
+'0's and zero-terminated.
+
+To create a new array use g_array_new().
+
+To add elements to an array with a cost of O(n) at worst, use
+g_array_append_val(), g_array_append_vals(), g_array_prepend_val(),
+g_array_prepend_vals(), g_array_insert_val() and g_array_insert_vals().
+
+To access an element of an array in O(1) (to read it or to write it),
+use g_array_index().
+
+To set the size of an array, use g_array_set_size().
+
+To free an array, use g_array_unref() or g_array_free().
+
+All the sort functions are internally calling a quick-sort (or similar)
+function with an average cost of O(n log(n)) and a worst case
+cost of O(n^2).
+
+Here is an example that stores integers in a #GArray:
+|[<!-- language="C" -->
+ GArray *garray;
+ gint i;
+ // We create a new array to store gint values.
+ // We don't want it zero-terminated or cleared to 0's.
+ garray = g_array_new (FALSE, FALSE, sizeof (gint));
+ for (i = 0; i < 10000; i++)
+ g_array_append_val (garray, i);
+ for (i = 0; i < 10000; i++)
+ if (g_array_index (garray, gint, i) != i)
+ g_print ("ERROR: got %d instead of %d\n",
+ g_array_index (garray, gint, i), i);
+ g_array_free (garray, TRUE);
+]|
+
+
+ #GByteArray is a mutable array of bytes based on #GArray, to provide arrays
+of bytes which grow automatically as elements are added.
+
+To create a new #GByteArray use g_byte_array_new(). To add elements to a
+#GByteArray, use g_byte_array_append(), and g_byte_array_prepend().
+
+To set the size of a #GByteArray, use g_byte_array_set_size().
+
+To free a #GByteArray, use g_byte_array_free().
+
+An example for using a #GByteArray:
+|[<!-- language="C" -->
+ GByteArray *gbarray;
+ gint i;
+
+ gbarray = g_byte_array_new ();
+ for (i = 0; i < 10000; i++)
+ g_byte_array_append (gbarray, (guint8*) "abcd", 4);
+
+ for (i = 0; i < 10000; i++)
+ {
+ g_assert (gbarray->data[4*i] == 'a');
+ g_assert (gbarray->data[4*i+1] == 'b');
+ g_assert (gbarray->data[4*i+2] == 'c');
+ g_assert (gbarray->data[4*i+3] == 'd');
+ }
+
+ g_byte_array_free (gbarray, TRUE);
+]|
+
+See #GBytes if you are interested in an immutable object representing a
+sequence of bytes.
+
+
+ Pointer Arrays are similar to Arrays but are used only for storing
+pointers.
+
+If you remove elements from the array, elements at the end of the
+array are moved into the space previously occupied by the removed
+element. This means that you should not rely on the index of particular
+elements remaining the same. You should also be careful when deleting
+elements while iterating over the array.
+
+To create a pointer array, use g_ptr_array_new().
+
+To add elements to a pointer array, use g_ptr_array_add().
+
+To remove elements from a pointer array, use g_ptr_array_remove(),
+g_ptr_array_remove_index() or g_ptr_array_remove_index_fast().
+
+To access an element of a pointer array, use g_ptr_array_index().
+
+To set the size of a pointer array, use g_ptr_array_set_size().
+
+To free a pointer array, use g_ptr_array_free().
+
+An example using a #GPtrArray:
+|[<!-- language="C" -->
+ GPtrArray *array;
+ gchar *string1 = "one";
+ gchar *string2 = "two";
+ gchar *string3 = "three";
+
+ array = g_ptr_array_new ();
+ g_ptr_array_add (array, (gpointer) string1);
+ g_ptr_array_add (array, (gpointer) string2);
+ g_ptr_array_add (array, (gpointer) string3);
+
+ if (g_ptr_array_index (array, 0) != (gpointer) string1)
+ g_print ("ERROR: got %p instead of %p\n",
+ g_ptr_array_index (array, 0), string1);
+
+ g_ptr_array_free (array, TRUE);
+]|
+
+
+ Determines the numeric value of a character as a decimal digit.
+Differs from g_unichar_digit_value() because it takes a char, so
+there's no worry about sign extension if characters are signed.
+
+
+ If @c is a decimal digit (according to g_ascii_isdigit()),
+ its numeric value. Otherwise, -1.
+
+
+
+
+ an ASCII character
+
+
+
+
+
+ Converts a #gdouble to a string, using the '.' as
+decimal point.
+
+This function generates enough precision that converting
+the string back using g_ascii_strtod() gives the same machine-number
+(on machines with IEEE compatible 64bit doubles). It is
+guaranteed that the size of the resulting string will never
+be larger than %G_ASCII_DTOSTR_BUF_SIZE bytes, including the terminating
+nul character, which is always added.
+
+
+ The pointer to the buffer with the converted string.
+
+
+
+
+ A buffer to place the resulting string in
+
+
+
+ The length of the buffer.
+
+
+
+ The #gdouble to convert
+
+
+
+
+
+ Converts a #gdouble to a string, using the '.' as
+decimal point. To format the number you pass in
+a printf()-style format string. Allowed conversion
+specifiers are 'e', 'E', 'f', 'F', 'g' and 'G'.
+
+The @format must just be a single format specifier
+starting with `%`, expecting a #gdouble argument.
+
+The returned buffer is guaranteed to be nul-terminated.
+
+If you just want to want to serialize the value into a
+string, use g_ascii_dtostr().
+
+
+ The pointer to the buffer with the converted string.
+
+
+
+
+ A buffer to place the resulting string in
+
+
+
+ The length of the buffer.
+
+
+
+ The printf()-style format to use for the
+ code to use for converting
+
+
+
+ The #gdouble to convert
+
+
+
+
+
+ Determines whether a character is alphanumeric.
+
+Unlike the standard C library isalnum() function, this only
+recognizes standard ASCII letters and ignores the locale,
+returning %FALSE for all non-ASCII characters. Also, unlike
+the standard library function, this takes a char, not an int,
+so don't call it on %EOF, but no need to cast to #guchar before
+passing a possibly non-ASCII character in.
+
+
+
+ any character
+
+
+
+
+ Determines whether a character is alphabetic (i.e. a letter).
+
+Unlike the standard C library isalpha() function, this only
+recognizes standard ASCII letters and ignores the locale,
+returning %FALSE for all non-ASCII characters. Also, unlike
+the standard library function, this takes a char, not an int,
+so don't call it on %EOF, but no need to cast to #guchar before
+passing a possibly non-ASCII character in.
+
+
+
+ any character
+
+
+
+
+ Determines whether a character is a control character.
+
+Unlike the standard C library iscntrl() function, this only
+recognizes standard ASCII control characters and ignores the
+locale, returning %FALSE for all non-ASCII characters. Also,
+unlike the standard library function, this takes a char, not
+an int, so don't call it on %EOF, but no need to cast to #guchar
+before passing a possibly non-ASCII character in.
+
+
+
+ any character
+
+
+
+
+ Determines whether a character is digit (0-9).
+
+Unlike the standard C library isdigit() function, this takes
+a char, not an int, so don't call it on %EOF, but no need to
+cast to #guchar before passing a possibly non-ASCII character in.
+
+
+
+ any character
+
+
+
+
+ Determines whether a character is a printing character and not a space.
+
+Unlike the standard C library isgraph() function, this only
+recognizes standard ASCII characters and ignores the locale,
+returning %FALSE for all non-ASCII characters. Also, unlike
+the standard library function, this takes a char, not an int,
+so don't call it on %EOF, but no need to cast to #guchar before
+passing a possibly non-ASCII character in.
+
+
+
+ any character
+
+
+
+
+ Determines whether a character is an ASCII lower case letter.
+
+Unlike the standard C library islower() function, this only
+recognizes standard ASCII letters and ignores the locale,
+returning %FALSE for all non-ASCII characters. Also, unlike
+the standard library function, this takes a char, not an int,
+so don't call it on %EOF, but no need to worry about casting
+to #guchar before passing a possibly non-ASCII character in.
+
+
+
+ any character
+
+
+
+
+ Determines whether a character is a printing character.
+
+Unlike the standard C library isprint() function, this only
+recognizes standard ASCII characters and ignores the locale,
+returning %FALSE for all non-ASCII characters. Also, unlike
+the standard library function, this takes a char, not an int,
+so don't call it on %EOF, but no need to cast to #guchar before
+passing a possibly non-ASCII character in.
+
+
+
+ any character
+
+
+
+
+ Determines whether a character is a punctuation character.
+
+Unlike the standard C library ispunct() function, this only
+recognizes standard ASCII letters and ignores the locale,
+returning %FALSE for all non-ASCII characters. Also, unlike
+the standard library function, this takes a char, not an int,
+so don't call it on %EOF, but no need to cast to #guchar before
+passing a possibly non-ASCII character in.
+
+
+
+ any character
+
+
+
+
+ Determines whether a character is a white-space character.
+
+Unlike the standard C library isspace() function, this only
+recognizes standard ASCII white-space and ignores the locale,
+returning %FALSE for all non-ASCII characters. Also, unlike
+the standard library function, this takes a char, not an int,
+so don't call it on %EOF, but no need to cast to #guchar before
+passing a possibly non-ASCII character in.
+
+
+
+ any character
+
+
+
+
+ Determines whether a character is an ASCII upper case letter.
+
+Unlike the standard C library isupper() function, this only
+recognizes standard ASCII letters and ignores the locale,
+returning %FALSE for all non-ASCII characters. Also, unlike
+the standard library function, this takes a char, not an int,
+so don't call it on %EOF, but no need to worry about casting
+to #guchar before passing a possibly non-ASCII character in.
+
+
+
+ any character
+
+
+
+
+ Determines whether a character is a hexadecimal-digit character.
+
+Unlike the standard C library isxdigit() function, this takes
+a char, not an int, so don't call it on %EOF, but no need to
+cast to #guchar before passing a possibly non-ASCII character in.
+
+
+
+ any character
+
+
+
+
+ Compare two strings, ignoring the case of ASCII characters.
+
+Unlike the BSD strcasecmp() function, this only recognizes standard
+ASCII letters and ignores the locale, treating all non-ASCII
+bytes as if they are not letters.
+
+This function should be used only on strings that are known to be
+in encodings where the bytes corresponding to ASCII letters always
+represent themselves. This includes UTF-8 and the ISO-8859-*
+charsets, but not for instance double-byte encodings like the
+Windows Codepage 932, where the trailing bytes of double-byte
+characters include all ASCII letters. If you compare two CP932
+strings using this function, you will get false matches.
+
+Both @s1 and @s2 must be non-%NULL.
+
+
+ 0 if the strings match, a negative value if @s1 < @s2,
+ or a positive value if @s1 > @s2.
+
+
+
+
+ string to compare with @s2
+
+
+
+ string to compare with @s1
+
+
+
+
+
+ Converts all upper case ASCII letters to lower case ASCII letters.
+
+
+ a newly-allocated string, with all the upper case
+ characters in @str converted to lower case, with semantics that
+ exactly match g_ascii_tolower(). (Note that this is unlike the
+ old g_strdown(), which modified the string in place.)
+
+
+
+
+ a string
+
+
+
+ length of @str in bytes, or -1 if @str is nul-terminated
+
+
+
+
+
+ A convenience function for converting a string to a signed number.
+
+This function assumes that @str contains only a number of the given
+@base that is within inclusive bounds limited by @min and @max. If
+this is true, then the converted number is stored in @out_num. An
+empty string is not a valid input. A string with leading or
+trailing whitespace is also an invalid input.
+
+@base can be between 2 and 36 inclusive. Hexadecimal numbers must
+not be prefixed with "0x" or "0X". Such a problem does not exist
+for octal numbers, since they were usually prefixed with a zero
+which does not change the value of the parsed number.
+
+Parsing failures result in an error with the %G_NUMBER_PARSER_ERROR
+domain. If the input is invalid, the error code will be
+%G_NUMBER_PARSER_ERROR_INVALID. If the parsed number is out of
+bounds - %G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS.
+
+See g_ascii_strtoll() if you have more complex needs such as
+parsing a string which starts with a number, but then has other
+characters.
+
+
+ %TRUE if @str was a number, otherwise %FALSE.
+
+
+
+
+ a string
+
+
+
+ base of a parsed number
+
+
+
+ a lower bound (inclusive)
+
+
+
+ an upper bound (inclusive)
+
+
+
+ a return location for a number
+
+
+
+
+
+ A convenience function for converting a string to an unsigned number.
+
+This function assumes that @str contains only a number of the given
+@base that is within inclusive bounds limited by @min and @max. If
+this is true, then the converted number is stored in @out_num. An
+empty string is not a valid input. A string with leading or
+trailing whitespace is also an invalid input. A string with a leading sign
+(`-` or `+`) is not a valid input for the unsigned parser.
+
+@base can be between 2 and 36 inclusive. Hexadecimal numbers must
+not be prefixed with "0x" or "0X". Such a problem does not exist
+for octal numbers, since they were usually prefixed with a zero
+which does not change the value of the parsed number.
+
+Parsing failures result in an error with the %G_NUMBER_PARSER_ERROR
+domain. If the input is invalid, the error code will be
+%G_NUMBER_PARSER_ERROR_INVALID. If the parsed number is out of
+bounds - %G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS.
+
+See g_ascii_strtoull() if you have more complex needs such as
+parsing a string which starts with a number, but then has other
+characters.
+
+
+ %TRUE if @str was a number, otherwise %FALSE.
+
+
+
+
+ a string
+
+
+
+ base of a parsed number
+
+
+
+ a lower bound (inclusive)
+
+
+
+ an upper bound (inclusive)
+
+
+
+ a return location for a number
+
+
+
+
+
+ Compare @s1 and @s2, ignoring the case of ASCII characters and any
+characters after the first @n in each string. If either string is
+less than @n bytes long, comparison will stop at the first nul byte
+encountered.
+
+Unlike the BSD strcasecmp() function, this only recognizes standard
+ASCII letters and ignores the locale, treating all non-ASCII
+characters as if they are not letters.
+
+The same warning as in g_ascii_strcasecmp() applies: Use this
+function only on strings known to be in encodings where bytes
+corresponding to ASCII letters always represent themselves.
+
+
+ 0 if the strings match, a negative value if @s1 < @s2,
+ or a positive value if @s1 > @s2.
+
+
+
+
+ string to compare with @s2
+
+
+
+ string to compare with @s1
+
+
+
+ number of characters to compare
+
+
+
+
+
+ Converts a string to a #gdouble value.
+
+This function behaves like the standard strtod() function
+does in the C locale. It does this without actually changing
+the current locale, since that would not be thread-safe.
+A limitation of the implementation is that this function
+will still accept localized versions of infinities and NANs.
+
+This function is typically used when reading configuration
+files or other non-user input that should be locale independent.
+To handle input from the user you should normally use the
+locale-sensitive system strtod() function.
+
+To convert from a #gdouble to a string in a locale-insensitive
+way, use g_ascii_dtostr().
+
+If the correct value would cause overflow, plus or minus %HUGE_VAL
+is returned (according to the sign of the value), and %ERANGE is
+stored in %errno. If the correct value would cause underflow,
+zero is returned and %ERANGE is stored in %errno.
+
+This function resets %errno before calling strtod() so that
+you can reliably detect overflow and underflow.
+
+
+ the #gdouble value.
+
+
+
+
+ the string to convert to a numeric value.
+
+
+
+ if non-%NULL, it returns the
+ character after the last character used in the conversion.
+
+
+
+
+
+ Converts a string to a #gint64 value.
+This function behaves like the standard strtoll() function
+does in the C locale. It does this without actually
+changing the current locale, since that would not be
+thread-safe.
+
+This function is typically used when reading configuration
+files or other non-user input that should be locale independent.
+To handle input from the user you should normally use the
+locale-sensitive system strtoll() function.
+
+If the correct value would cause overflow, %G_MAXINT64 or %G_MININT64
+is returned, and `ERANGE` is stored in `errno`.
+If the base is outside the valid range, zero is returned, and
+`EINVAL` is stored in `errno`. If the
+string conversion fails, zero is returned, and @endptr returns @nptr
+(if @endptr is non-%NULL).
+
+
+ the #gint64 value or zero on error.
+
+
+
+
+ the string to convert to a numeric value.
+
+
+
+ if non-%NULL, it returns the
+ character after the last character used in the conversion.
+
+
+
+ to be used for the conversion, 2..36 or 0
+
+
+
+
+
+ Converts a string to a #guint64 value.
+This function behaves like the standard strtoull() function
+does in the C locale. It does this without actually
+changing the current locale, since that would not be
+thread-safe.
+
+Note that input with a leading minus sign (`-`) is accepted, and will return
+the negation of the parsed number, unless that would overflow a #guint64.
+Critically, this means you cannot assume that a short fixed length input will
+never result in a low return value, as the input could have a leading `-`.
+
+This function is typically used when reading configuration
+files or other non-user input that should be locale independent.
+To handle input from the user you should normally use the
+locale-sensitive system strtoull() function.
+
+If the correct value would cause overflow, %G_MAXUINT64
+is returned, and `ERANGE` is stored in `errno`.
+If the base is outside the valid range, zero is returned, and
+`EINVAL` is stored in `errno`.
+If the string conversion fails, zero is returned, and @endptr returns
+@nptr (if @endptr is non-%NULL).
+
+
+ the #guint64 value or zero on error.
+
+
+
+
+ the string to convert to a numeric value.
+
+
+
+ if non-%NULL, it returns the
+ character after the last character used in the conversion.
+
+
+
+ to be used for the conversion, 2..36 or 0
+
+
+
+
+
+ Converts all lower case ASCII letters to upper case ASCII letters.
+
+
+ a newly allocated string, with all the lower case
+ characters in @str converted to upper case, with semantics that
+ exactly match g_ascii_toupper(). (Note that this is unlike the
+ old g_strup(), which modified the string in place.)
+
+
+
+
+ a string
+
+
+
+ length of @str in bytes, or -1 if @str is nul-terminated
+
+
+
+
+
+ Convert a character to ASCII lower case.
+
+Unlike the standard C library tolower() function, this only
+recognizes standard ASCII letters and ignores the locale, returning
+all non-ASCII characters unchanged, even if they are lower case
+letters in a particular character set. Also unlike the standard
+library function, this takes and returns a char, not an int, so
+don't call it on %EOF but no need to worry about casting to #guchar
+before passing a possibly non-ASCII character in.
+
+
+ the result of converting @c to lower case. If @c is
+ not an ASCII upper case letter, @c is returned unchanged.
+
+
+
+
+ any character
+
+
+
+
+
+ Convert a character to ASCII upper case.
+
+Unlike the standard C library toupper() function, this only
+recognizes standard ASCII letters and ignores the locale, returning
+all non-ASCII characters unchanged, even if they are upper case
+letters in a particular character set. Also unlike the standard
+library function, this takes and returns a char, not an int, so
+don't call it on %EOF but no need to worry about casting to #guchar
+before passing a possibly non-ASCII character in.
+
+
+ the result of converting @c to upper case. If @c is not
+ an ASCII lower case letter, @c is returned unchanged.
+
+
+
+
+ any character
+
+
+
+
+
+ Determines the numeric value of a character as a hexadecimal
+digit. Differs from g_unichar_xdigit_value() because it takes
+a char, so there's no worry about sign extension if characters
+are signed.
+
+
+ If @c is a hex digit (according to g_ascii_isxdigit()),
+ its numeric value. Otherwise, -1.
+
+
+
+
+ an ASCII character.
+
+
+
+
+
+ Debugging macro to terminate the application if the assertion
+fails. If the assertion fails (i.e. the expression is not true),
+an error message is logged and the application is terminated.
+
+The macro can be turned off in final releases of code by defining
+`G_DISABLE_ASSERT` when compiling the application, so code must
+not depend on any side effects from @expr. Similarly, it must not be used
+in unit tests, otherwise the unit tests will be ineffective if compiled with
+`G_DISABLE_ASSERT`. Use g_assert_true() and related macros in unit tests
+instead.
+
+
+
+ the expression to check
+
+
+
+
+ Debugging macro to compare two floating point numbers.
+
+The effect of `g_assert_cmpfloat (n1, op, n2)` is
+the same as `g_assert_true (n1 op n2)`. The advantage
+of this macro is that it can produce a message that includes the
+actual values of @n1 and @n2.
+
+
+
+ a floating point number
+
+
+ The comparison operator to use.
+ One of `==`, `!=`, `<`, `>`, `<=`, `>=`.
+
+
+ another floating point number
+
+
+
+
+ Debugging macro to compare two floating point numbers within an epsilon.
+
+The effect of `g_assert_cmpfloat_with_epsilon (n1, n2, epsilon)` is
+the same as `g_assert_true (abs (n1 - n2) < epsilon)`. The advantage
+of this macro is that it can produce a message that includes the
+actual values of @n1 and @n2.
+
+
+
+ a floating point number
+
+
+ another floating point number
+
+
+ a numeric value that expresses the expected tolerance
+ between @n1 and @n2
+
+
+
+
+ Debugging macro to compare to unsigned integers.
+
+This is a variant of g_assert_cmpuint() that displays the numbers
+in hexadecimal notation in the message.
+
+
+
+ an unsigned integer
+
+
+ The comparison operator to use.
+ One of `==`, `!=`, `<`, `>`, `<=`, `>=`.
+
+
+ another unsigned integer
+
+
+
+
+ Debugging macro to compare two integers.
+
+The effect of `g_assert_cmpint (n1, op, n2)` is
+the same as `g_assert_true (n1 op n2)`. The advantage
+of this macro is that it can produce a message that includes the
+actual values of @n1 and @n2.
+
+
+
+ an integer
+
+
+ The comparison operator to use.
+ One of `==`, `!=`, `<`, `>`, `<=`, `>=`.
+
+
+ another integer
+
+
+
+
+ Debugging macro to compare memory regions. If the comparison fails,
+an error message is logged and the application is either terminated
+or the testcase marked as failed.
+
+The effect of `g_assert_cmpmem (m1, l1, m2, l2)` is
+the same as `g_assert_true (l1 == l2 && memcmp (m1, m2, l1) == 0)`.
+The advantage of this macro is that it can produce a message that
+includes the actual values of @l1 and @l2.
+
+@m1 may be %NULL if (and only if) @l1 is zero; similarly for @m2 and @l2.
+
+|[<!-- language="C" -->
+ g_assert_cmpmem (buf->data, buf->len, expected, sizeof (expected));
+]|
+
+
+
+ pointer to a buffer
+
+
+ length of @m1
+
+
+ pointer to another buffer
+
+
+ length of @m2
+
+
+
+
+ Debugging macro to compare two strings. If the comparison fails,
+an error message is logged and the application is either terminated
+or the testcase marked as failed.
+The strings are compared using g_strcmp0().
+
+The effect of `g_assert_cmpstr (s1, op, s2)` is
+the same as `g_assert_true (g_strcmp0 (s1, s2) op 0)`.
+The advantage of this macro is that it can produce a message that
+includes the actual values of @s1 and @s2.
+
+|[<!-- language="C" -->
+ g_assert_cmpstr (mystring, ==, "fubar");
+]|
+
+
+
+ a string (may be %NULL)
+
+
+ The comparison operator to use.
+ One of `==`, `!=`, `<`, `>`, `<=`, `>=`.
+
+
+ another string (may be %NULL)
+
+
+
+
+ Debugging macro to check if two %NULL-terminated string arrays (i.e. 2
+#GStrv) are equal. If they are not equal, an error message is logged and the
+application is either terminated or the testcase marked as failed.
+If both arrays are %NULL, the check passes. If one array is %NULL but the
+other is not, an error message is logged.
+
+The effect of `g_assert_cmpstrv (strv1, strv2)` is the same as
+`g_assert_true (g_strv_equal (strv1, strv2))` (if both arrays are not
+%NULL). The advantage of this macro is that it can produce a message that
+includes how @strv1 and @strv2 are different.
+
+|[<!-- language="C" -->
+ const char *expected[] = { "one", "two", "three", NULL };
+ g_assert_cmpstrv (mystrv, expected);
+]|
+
+
+
+ a string array (may be %NULL)
+
+
+ another string array (may be %NULL)
+
+
+
+
+ Debugging macro to compare two unsigned integers.
+
+The effect of `g_assert_cmpuint (n1, op, n2)` is
+the same as `g_assert_true (n1 op n2)`. The advantage
+of this macro is that it can produce a message that includes the
+actual values of @n1 and @n2.
+
+
+
+ an unsigned integer
+
+
+ The comparison operator to use.
+ One of `==`, `!=`, `<`, `>`, `<=`, `>=`.
+
+
+ another unsigned integer
+
+
+
+
+ Debugging macro to compare two #GVariants. If the comparison fails,
+an error message is logged and the application is either terminated
+or the testcase marked as failed. The variants are compared using
+g_variant_equal().
+
+The effect of `g_assert_cmpvariant (v1, v2)` is the same as
+`g_assert_true (g_variant_equal (v1, v2))`. The advantage of this macro is
+that it can produce a message that includes the actual values of @v1 and @v2.
+
+
+
+ pointer to a #GVariant
+
+
+ pointer to another #GVariant
+
+
+
+
+ Debugging macro to check that a method has returned
+the correct #GError.
+
+The effect of `g_assert_error (err, dom, c)` is
+the same as `g_assert_true (err != NULL && err->domain
+== dom && err->code == c)`. The advantage of this
+macro is that it can produce a message that includes the incorrect
+error message and code.
+
+This can only be used to test for a specific error. If you want to
+test that @err is set, but don't care what it's set to, just use
+`g_assert_nonnull (err)`.
+
+
+
+ a #GError, possibly %NULL
+
+
+ the expected error domain (a #GQuark)
+
+
+ the expected error code
+
+
+
+
+ Debugging macro to check an expression is false.
+
+If the assertion fails (i.e. the expression is not false),
+an error message is logged and the application is either
+terminated or the testcase marked as failed.
+
+Note that unlike g_assert(), this macro is unaffected by whether
+`G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and,
+conversely, g_assert() should not be used in tests.
+
+See g_test_set_nonfatal_assertions().
+
+
+
+ the expression to check
+
+
+
+
+ Debugging macro to check that an expression has a non-negative return value,
+as used by traditional POSIX functions (such as `rmdir()`) to indicate
+success.
+
+If the assertion fails (i.e. the @expr returns a negative value), an error
+message is logged and the testcase is marked as failed. The error message
+will contain the value of `errno` and its human-readable message from
+g_strerror().
+
+This macro will clear the value of `errno` before executing @expr.
+
+
+
+ the expression to check
+
+
+
+
+ Debugging macro to check that a #GError is not set.
+
+The effect of `g_assert_no_error (err)` is
+the same as `g_assert_true (err == NULL)`. The advantage
+of this macro is that it can produce a message that includes
+the error message and code.
+
+
+
+ a #GError, possibly %NULL
+
+
+
+
+ Debugging macro to check an expression is not %NULL.
+
+If the assertion fails (i.e. the expression is %NULL),
+an error message is logged and the application is either
+terminated or the testcase marked as failed.
+
+Note that unlike g_assert(), this macro is unaffected by whether
+`G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and,
+conversely, g_assert() should not be used in tests.
+
+See g_test_set_nonfatal_assertions().
+
+
+
+ the expression to check
+
+
+
+
+ Debugging macro to terminate the application if it is ever
+reached. If it is reached, an error message is logged and the
+application is terminated.
+
+The macro can be turned off in final releases of code by defining
+`G_DISABLE_ASSERT` when compiling the application. Hence, it should not be
+used in unit tests, where assertions should always be effective.
+
+
+
+ Debugging macro to check an expression is %NULL.
+
+If the assertion fails (i.e. the expression is not %NULL),
+an error message is logged and the application is either
+terminated or the testcase marked as failed.
+
+Note that unlike g_assert(), this macro is unaffected by whether
+`G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and,
+conversely, g_assert() should not be used in tests.
+
+See g_test_set_nonfatal_assertions().
+
+
+
+ the expression to check
+
+
+
+
+ Debugging macro to check that an expression is true.
+
+If the assertion fails (i.e. the expression is not true),
+an error message is logged and the application is either
+terminated or the testcase marked as failed.
+
+Note that unlike g_assert(), this macro is unaffected by whether
+`G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and,
+conversely, g_assert() should not be used in tests.
+
+See g_test_set_nonfatal_assertions().
+
+
+
+ the expression to check
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Internal function used to print messages from the public g_assert() and
+g_assert_not_reached() macros.
+
+
+
+
+
+
+ log domain
+
+
+
+ file containing the assertion
+
+
+
+ line number of the assertion
+
+
+
+ function containing the assertion
+
+
+
+ expression which failed
+
+
+
+
+
+ Often you need to communicate between different threads. In general
+it's safer not to do this by shared memory, but by explicit message
+passing. These messages only make sense asynchronously for
+multi-threaded applications though, as a synchronous operation could
+as well be done in the same thread.
+
+Asynchronous queues are an exception from most other GLib data
+structures, as they can be used simultaneously from multiple threads
+without explicit locking and they bring their own builtin reference
+counting. This is because the nature of an asynchronous queue is that
+it will always be used by at least 2 concurrent threads.
+
+For using an asynchronous queue you first have to create one with
+g_async_queue_new(). #GAsyncQueue structs are reference counted,
+use g_async_queue_ref() and g_async_queue_unref() to manage your
+references.
+
+A thread which wants to send a message to that queue simply calls
+g_async_queue_push() to push the message to the queue.
+
+A thread which is expecting messages from an asynchronous queue
+simply calls g_async_queue_pop() for that queue. If no message is
+available in the queue at that point, the thread is now put to sleep
+until a message arrives. The message will be removed from the queue
+and returned. The functions g_async_queue_try_pop() and
+g_async_queue_timeout_pop() can be used to only check for the presence
+of messages or to only wait a certain time for messages respectively.
+
+For almost every function there exist two variants, one that locks
+the queue and one that doesn't. That way you can hold the queue lock
+(acquire it with g_async_queue_lock() and release it with
+g_async_queue_unlock()) over multiple queue accessing instructions.
+This can be necessary to ensure the integrity of the queue, but should
+only be used when really necessary, as it can make your life harder
+if used unwisely. Normally you should only use the locking function
+variants (those without the _unlocked suffix).
+
+In many cases, it may be more convenient to use #GThreadPool when
+you need to distribute work to a set of worker threads instead of
+using #GAsyncQueue manually. #GThreadPool uses a GAsyncQueue
+internally.
+
+
+ Specifies a function to be called at normal program termination.
+
+Since GLib 2.8.2, on Windows g_atexit() actually is a preprocessor
+macro that maps to a call to the atexit() function in the C
+library. This means that in case the code that calls g_atexit(),
+i.e. atexit(), is in a DLL, the function will be called when the
+DLL is detached from the program. This typically makes more sense
+than that the function is called when the GLib DLL is detached,
+which happened earlier when g_atexit() was a function in the GLib
+DLL.
+
+The behaviour of atexit() in the context of dynamically loaded
+modules is not formally specified and varies wildly.
+
+On POSIX systems, calling g_atexit() (or atexit()) in a dynamically
+loaded module which is unloaded before the program terminates might
+well cause a crash at program exit.
+
+Some POSIX systems implement atexit() like Windows, and have each
+dynamically loaded module maintain an own atexit chain that is
+called when the module is unloaded.
+
+On other POSIX systems, before a dynamically loaded module is
+unloaded, the registered atexit functions (if any) residing in that
+module are called, regardless where the code that registered them
+resided. This is presumably the most robust approach.
+
+As can be seen from the above, for portability it's best to avoid
+calling g_atexit() (or atexit()) except in the main executable of a
+program.
+ It is best to avoid g_atexit().
+
+
+
+
+
+
+ the function to call on normal program termination.
+
+
+
+
+
+ Atomically adds @val to the value of @atomic.
+
+Think of this operation as an atomic version of
+`{ tmp = *atomic; *atomic += val; return tmp; }`.
+
+This call acts as a full compiler and hardware memory barrier.
+
+Before version 2.30, this function did not return a value
+(but g_atomic_int_exchange_and_add() did, and had the same meaning).
+
+While @atomic has a `volatile` qualifier, this is a historical artifact and
+the pointer passed to it should not be `volatile`.
+
+
+ the value of @atomic before the add, signed
+
+
+
+
+ a pointer to a #gint or #guint
+
+
+
+ the value to add
+
+
+
+
+
+ Performs an atomic bitwise 'and' of the value of @atomic and @val,
+storing the result back in @atomic.
+
+This call acts as a full compiler and hardware memory barrier.
+
+Think of this operation as an atomic version of
+`{ tmp = *atomic; *atomic &= val; return tmp; }`.
+
+While @atomic has a `volatile` qualifier, this is a historical artifact and
+the pointer passed to it should not be `volatile`.
+
+
+ the value of @atomic before the operation, unsigned
+
+
+
+
+ a pointer to a #gint or #guint
+
+
+
+ the value to 'and'
+
+
+
+
+
+ Compares @atomic to @oldval and, if equal, sets it to @newval.
+If @atomic was not equal to @oldval then no change occurs.
+
+This compare and exchange is done atomically.
+
+Think of this operation as an atomic version of
+`{ if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }`.
+
+This call acts as a full compiler and hardware memory barrier.
+
+While @atomic has a `volatile` qualifier, this is a historical artifact and
+the pointer passed to it should not be `volatile`.
+
+
+ %TRUE if the exchange took place
+
+
+
+
+ a pointer to a #gint or #guint
+
+
+
+ the value to compare with
+
+
+
+ the value to conditionally replace with
+
+
+
+
+
+ Compares @atomic to @oldval and, if equal, sets it to @newval.
+If @atomic was not equal to @oldval then no change occurs.
+In any case the value of @atomic before this operation is stored in @preval.
+
+This compare and exchange is done atomically.
+
+Think of this operation as an atomic version of
+`{ *preval = *atomic; if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }`.
+
+This call acts as a full compiler and hardware memory barrier.
+
+See also g_atomic_int_compare_and_exchange()
+
+
+ %TRUE if the exchange took place
+
+
+
+
+ a pointer to a #gint or #guint
+
+
+
+ the value to compare with
+
+
+
+ the value to conditionally replace with
+
+
+
+ the contents of @atomic before this operation
+
+
+
+
+
+ Decrements the value of @atomic by 1.
+
+Think of this operation as an atomic version of
+`{ *atomic -= 1; return (*atomic == 0); }`.
+
+This call acts as a full compiler and hardware memory barrier.
+
+While @atomic has a `volatile` qualifier, this is a historical artifact and
+the pointer passed to it should not be `volatile`.
+
+
+ %TRUE if the resultant value is zero
+
+
+
+
+ a pointer to a #gint or #guint
+
+
+
+
+
+ Sets the @atomic to @newval and returns the old value from @atomic.
+
+This exchange is done atomically.
+
+Think of this operation as an atomic version of
+`{ tmp = *atomic; *atomic = val; return tmp; }`.
+
+This call acts as a full compiler and hardware memory barrier.
+
+
+ the value of @atomic before the exchange, signed
+
+
+
+
+ a pointer to a #gint or #guint
+
+
+
+ the value to replace with
+
+
+
+
+
+ This function existed before g_atomic_int_add() returned the prior
+value of the integer (which it now does). It is retained only for
+compatibility reasons. Don't use this function in new code.
+ Use g_atomic_int_add() instead.
+
+
+ the value of @atomic before the add, signed
+
+
+
+
+ a pointer to a #gint
+
+
+
+ the value to add
+
+
+
+
+
+ Gets the current value of @atomic.
+
+This call acts as a full compiler and hardware
+memory barrier (before the get).
+
+While @atomic has a `volatile` qualifier, this is a historical artifact and
+the pointer passed to it should not be `volatile`.
+
+
+ the value of the integer
+
+
+
+
+ a pointer to a #gint or #guint
+
+
+
+
+
+ Increments the value of @atomic by 1.
+
+Think of this operation as an atomic version of `{ *atomic += 1; }`.
+
+This call acts as a full compiler and hardware memory barrier.
+
+While @atomic has a `volatile` qualifier, this is a historical artifact and
+the pointer passed to it should not be `volatile`.
+
+
+
+
+
+
+ a pointer to a #gint or #guint
+
+
+
+
+
+ Performs an atomic bitwise 'or' of the value of @atomic and @val,
+storing the result back in @atomic.
+
+Think of this operation as an atomic version of
+`{ tmp = *atomic; *atomic |= val; return tmp; }`.
+
+This call acts as a full compiler and hardware memory barrier.
+
+While @atomic has a `volatile` qualifier, this is a historical artifact and
+the pointer passed to it should not be `volatile`.
+
+
+ the value of @atomic before the operation, unsigned
+
+
+
+
+ a pointer to a #gint or #guint
+
+
+
+ the value to 'or'
+
+
+
+
+
+ Sets the value of @atomic to @newval.
+
+This call acts as a full compiler and hardware
+memory barrier (after the set).
+
+While @atomic has a `volatile` qualifier, this is a historical artifact and
+the pointer passed to it should not be `volatile`.
+
+
+
+
+
+
+ a pointer to a #gint or #guint
+
+
+
+ a new value to store
+
+
+
+
+
+ Performs an atomic bitwise 'xor' of the value of @atomic and @val,
+storing the result back in @atomic.
+
+Think of this operation as an atomic version of
+`{ tmp = *atomic; *atomic ^= val; return tmp; }`.
+
+This call acts as a full compiler and hardware memory barrier.
+
+While @atomic has a `volatile` qualifier, this is a historical artifact and
+the pointer passed to it should not be `volatile`.
+
+
+ the value of @atomic before the operation, unsigned
+
+
+
+
+ a pointer to a #gint or #guint
+
+
+
+ the value to 'xor'
+
+
+
+
+
+ The following is a collection of compiler macros to provide atomic
+access to integer and pointer-sized values.
+
+The macros that have 'int' in the name will operate on pointers to
+#gint and #guint. The macros with 'pointer' in the name will operate
+on pointers to any pointer-sized value, including #gsize. There is
+no support for 64bit operations on platforms with 32bit pointers
+because it is not generally possible to perform these operations
+atomically.
+
+The get, set and exchange operations for integers and pointers
+nominally operate on #gint and #gpointer, respectively. Of the
+arithmetic operations, the 'add' operation operates on (and returns)
+signed integer values (#gint and #gssize) and the 'and', 'or', and
+'xor' operations operate on (and return) unsigned integer values
+(#guint and #gsize).
+
+All of the operations act as a full compiler and (where appropriate)
+hardware memory barrier. Acquire and release or producer and
+consumer barrier semantics are not available through this API.
+
+It is very important that all accesses to a particular integer or
+pointer be performed using only this API and that different sizes of
+operation are not mixed or used on overlapping memory regions. Never
+read or assign directly from or to a value -- always use this API.
+
+For simple reference counting purposes you should use
+g_atomic_int_inc() and g_atomic_int_dec_and_test(). Other uses that
+fall outside of simple reference counting patterns are prone to
+subtle bugs and occasionally undefined behaviour. It is also worth
+noting that since all of these operations require global
+synchronisation of the entire machine, they can be quite slow. In
+the case of performing multiple atomic operations it can often be
+faster to simply acquire a mutex lock around the critical area,
+perform the operations normally and then release the lock.
+
+
+ Atomically adds @val to the value of @atomic.
+
+Think of this operation as an atomic version of
+`{ tmp = *atomic; *atomic += val; return tmp; }`.
+
+This call acts as a full compiler and hardware memory barrier.
+
+While @atomic has a `volatile` qualifier, this is a historical artifact and
+the pointer passed to it should not be `volatile`.
+
+
+ the value of @atomic before the add, signed
+
+
+
+
+ a pointer to a #gpointer-sized value
+
+
+
+ the value to add
+
+
+
+
+
+ Performs an atomic bitwise 'and' of the value of @atomic and @val,
+storing the result back in @atomic.
+
+Think of this operation as an atomic version of
+`{ tmp = *atomic; *atomic &= val; return tmp; }`.
+
+This call acts as a full compiler and hardware memory barrier.
+
+While @atomic has a `volatile` qualifier, this is a historical artifact and
+the pointer passed to it should not be `volatile`.
+
+
+ the value of @atomic before the operation, unsigned
+
+
+
+
+ a pointer to a #gpointer-sized value
+
+
+
+ the value to 'and'
+
+
+
+
+
+ Compares @atomic to @oldval and, if equal, sets it to @newval.
+If @atomic was not equal to @oldval then no change occurs.
+
+This compare and exchange is done atomically.
+
+Think of this operation as an atomic version of
+`{ if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }`.
+
+This call acts as a full compiler and hardware memory barrier.
+
+While @atomic has a `volatile` qualifier, this is a historical artifact and
+the pointer passed to it should not be `volatile`.
+
+
+ %TRUE if the exchange took place
+
+
+
+
+ a pointer to a #gpointer-sized value
+
+
+
+ the value to compare with
+
+
+
+ the value to conditionally replace with
+
+
+
+
+
+ Compares @atomic to @oldval and, if equal, sets it to @newval.
+If @atomic was not equal to @oldval then no change occurs.
+In any case the value of @atomic before this operation is stored in @preval.
+
+This compare and exchange is done atomically.
+
+Think of this operation as an atomic version of
+`{ *preval = *atomic; if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }`.
+
+This call acts as a full compiler and hardware memory barrier.
+
+See also g_atomic_pointer_compare_and_exchange()
+
+
+ %TRUE if the exchange took place
+
+
+
+
+ a pointer to a #gpointer-sized value
+
+
+
+ the value to compare with
+
+
+
+ the value to conditionally replace with
+
+
+
+ the contents of @atomic before this operation
+
+
+
+
+
+ Sets the @atomic to @newval and returns the old value from @atomic.
+
+This exchange is done atomically.
+
+Think of this operation as an atomic version of
+`{ tmp = *atomic; *atomic = val; return tmp; }`.
+
+This call acts as a full compiler and hardware memory barrier.
+
+
+ the value of @atomic before the exchange
+
+
+
+
+ a pointer to a #gpointer-sized value
+
+
+
+ the value to replace with
+
+
+
+
+
+ Gets the current value of @atomic.
+
+This call acts as a full compiler and hardware
+memory barrier (before the get).
+
+While @atomic has a `volatile` qualifier, this is a historical artifact and
+the pointer passed to it should not be `volatile`.
+
+
+ the value of the pointer
+
+
+
+
+ a pointer to a #gpointer-sized value
+
+
+
+
+
+ Performs an atomic bitwise 'or' of the value of @atomic and @val,
+storing the result back in @atomic.
+
+Think of this operation as an atomic version of
+`{ tmp = *atomic; *atomic |= val; return tmp; }`.
+
+This call acts as a full compiler and hardware memory barrier.
+
+While @atomic has a `volatile` qualifier, this is a historical artifact and
+the pointer passed to it should not be `volatile`.
+
+
+ the value of @atomic before the operation, unsigned
+
+
+
+
+ a pointer to a #gpointer-sized value
+
+
+
+ the value to 'or'
+
+
+
+
+
+ Sets the value of @atomic to @newval.
+
+This call acts as a full compiler and hardware
+memory barrier (after the set).
+
+While @atomic has a `volatile` qualifier, this is a historical artifact and
+the pointer passed to it should not be `volatile`.
+
+
+
+
+
+
+ a pointer to a #gpointer-sized value
+
+
+
+ a new value to store
+
+
+
+
+
+ Performs an atomic bitwise 'xor' of the value of @atomic and @val,
+storing the result back in @atomic.
+
+Think of this operation as an atomic version of
+`{ tmp = *atomic; *atomic ^= val; return tmp; }`.
+
+This call acts as a full compiler and hardware memory barrier.
+
+While @atomic has a `volatile` qualifier, this is a historical artifact and
+the pointer passed to it should not be `volatile`.
+
+
+ the value of @atomic before the operation, unsigned
+
+
+
+
+ a pointer to a #gpointer-sized value
+
+
+
+ the value to 'xor'
+
+
+
+
+
+ Atomically acquires a reference on the data pointed by @mem_block.
+
+
+ a pointer to the data,
+ with its reference count increased
+
+
+
+
+ a pointer to reference counted data
+
+
+
+
+
+ Allocates @block_size bytes of memory, and adds atomic
+reference counting semantics to it.
+
+The data will be freed when its reference count drops to
+zero.
+
+The allocated data is guaranteed to be suitably aligned for any
+built-in type.
+
+
+ a pointer to the allocated memory
+
+
+
+
+ the size of the allocation, must be greater than 0
+
+
+
+
+
+ Allocates @block_size bytes of memory, and adds atomic
+reference counting semantics to it.
+
+The contents of the returned data is set to zero.
+
+The data will be freed when its reference count drops to
+zero.
+
+The allocated data is guaranteed to be suitably aligned for any
+built-in type.
+
+
+ a pointer to the allocated memory
+
+
+
+
+ the size of the allocation, must be greater than 0
+
+
+
+
+
+ Allocates a new block of data with atomic reference counting
+semantics, and copies @block_size bytes of @mem_block
+into it.
+
+
+ a pointer to the allocated
+ memory
+
+
+
+
+ the number of bytes to copy, must be greater than 0
+
+
+
+ the memory to copy
+
+
+
+
+
+ Retrieves the size of the reference counted data pointed by @mem_block.
+
+
+ the size of the data, in bytes
+
+
+
+
+ a pointer to reference counted data
+
+
+
+
+
+ A convenience macro to allocate atomically reference counted
+data with the size of the given @type.
+
+This macro calls g_atomic_rc_box_alloc() with `sizeof (@type)` and
+casts the returned pointer to a pointer of the given @type,
+avoiding a type cast in the source code.
+
+
+
+ the type to allocate, typically a structure name
+
+
+
+
+ A convenience macro to allocate atomically reference counted
+data with the size of the given @type, and set its contents
+to zero.
+
+This macro calls g_atomic_rc_box_alloc0() with `sizeof (@type)` and
+casts the returned pointer to a pointer of the given @type,
+avoiding a type cast in the source code.
+
+
+
+ the type to allocate, typically a structure name
+
+
+
+
+ Atomically releases a reference on the data pointed by @mem_block.
+
+If the reference was the last one, it will free the
+resources allocated for @mem_block.
+
+
+
+
+
+
+ a pointer to reference counted data
+
+
+
+
+
+ Atomically releases a reference on the data pointed by @mem_block.
+
+If the reference was the last one, it will call @clear_func
+to clear the contents of @mem_block, and then will free the
+resources allocated for @mem_block.
+
+
+
+
+
+
+ a pointer to reference counted data
+
+
+
+ a function to call when clearing the data
+
+
+
+
+
+ Atomically compares the current value of @arc with @val.
+
+
+ %TRUE if the reference count is the same
+ as the given value
+
+
+
+
+ the address of an atomic reference count variable
+
+
+
+ the value to compare
+
+
+
+
+
+ Atomically decreases the reference count.
+
+If %TRUE is returned, the reference count reached 0. After this point, @arc
+is an undefined state and must be reinitialized with
+g_atomic_ref_count_init() to be used again.
+
+
+ %TRUE if the reference count reached 0, and %FALSE otherwise
+
+
+
+
+ the address of an atomic reference count variable
+
+
+
+
+
+ Atomically increases the reference count.
+
+
+
+
+
+
+ the address of an atomic reference count variable
+
+
+
+
+
+ Initializes a reference count variable to 1.
+
+
+
+
+
+
+ the address of an atomic reference count variable
+
+
+
+
+
+ Base64 is an encoding that allows a sequence of arbitrary bytes to be
+encoded as a sequence of printable ASCII characters. For the definition
+of Base64, see
+[RFC 1421](http://www.ietf.org/rfc/rfc1421.txt)
+or
+[RFC 2045](http://www.ietf.org/rfc/rfc2045.txt).
+Base64 is most commonly used as a MIME transfer encoding
+for email.
+
+GLib supports incremental encoding using g_base64_encode_step() and
+g_base64_encode_close(). Incremental decoding can be done with
+g_base64_decode_step(). To encode or decode data in one go, use
+g_base64_encode() or g_base64_decode(). To avoid memory allocation when
+decoding, you can use g_base64_decode_inplace().
+
+Support for Base64 encoding has been added in GLib 2.12.
+
+
+ Decode a sequence of Base-64 encoded text into binary data. Note
+that the returned binary data is not necessarily zero-terminated,
+so it should not be used as a character string.
+
+
+
+ newly allocated buffer containing the binary data
+ that @text represents. The returned buffer must
+ be freed with g_free().
+
+
+
+
+
+
+ zero-terminated string with base64 text to decode
+
+
+
+ The length of the decoded data is written here
+
+
+
+
+
+ Decode a sequence of Base-64 encoded text into binary data
+by overwriting the input data.
+
+
+ The binary data that @text responds. This pointer
+ is the same as the input @text.
+
+
+
+
+ zero-terminated
+ string with base64 text to decode
+
+
+
+
+
+ The length of the decoded data is written here
+
+
+
+
+
+ Incrementally decode a sequence of binary data from its Base-64 stringified
+representation. By calling this function multiple times you can convert
+data in chunks to avoid having to have the full encoded data in memory.
+
+The output buffer must be large enough to fit all the data that will
+be written to it. Since base64 encodes 3 bytes in 4 chars you need
+at least: (@len / 4) * 3 + 3 bytes (+ 3 may be needed in case of non-zero
+state).
+
+
+ The number of bytes of output that was written
+
+
+
+
+ binary input data
+
+
+
+
+
+ max length of @in data to decode
+
+
+
+ output buffer
+
+
+
+
+
+ Saved state between steps, initialize to 0
+
+
+
+ Saved state between steps, initialize to 0
+
+
+
+
+
+ Encode a sequence of binary data into its Base-64 stringified
+representation.
+
+
+ a newly allocated, zero-terminated Base-64
+ encoded string representing @data. The returned string must
+ be freed with g_free().
+
+
+
+
+ the binary data to encode
+
+
+
+
+
+ the length of @data
+
+
+
+
+
+ Flush the status from a sequence of calls to g_base64_encode_step().
+
+The output buffer must be large enough to fit all the data that will
+be written to it. It will need up to 4 bytes, or up to 5 bytes if
+line-breaking is enabled.
+
+The @out array will not be automatically nul-terminated.
+
+
+ The number of bytes of output that was written
+
+
+
+
+ whether to break long lines
+
+
+
+ pointer to destination buffer
+
+
+
+
+
+ Saved state from g_base64_encode_step()
+
+
+
+ Saved state from g_base64_encode_step()
+
+
+
+
+
+ Incrementally encode a sequence of binary data into its Base-64 stringified
+representation. By calling this function multiple times you can convert
+data in chunks to avoid having to have the full encoded data in memory.
+
+When all of the data has been converted you must call
+g_base64_encode_close() to flush the saved state.
+
+The output buffer must be large enough to fit all the data that will
+be written to it. Due to the way base64 encodes you will need
+at least: (@len / 3 + 1) * 4 + 4 bytes (+ 4 may be needed in case of
+non-zero state). If you enable line-breaking you will need at least:
+((@len / 3 + 1) * 4 + 4) / 76 + 1 bytes of extra space.
+
+@break_lines is typically used when putting base64-encoded data in emails.
+It breaks the lines at 76 columns instead of putting all of the text on
+the same line. This avoids problems with long lines in the email system.
+Note however that it breaks the lines with `LF` characters, not
+`CR LF` sequences, so the result cannot be passed directly to SMTP
+or certain other protocols.
+
+
+ The number of bytes of output that was written
+
+
+
+
+ the binary data to encode
+
+
+
+
+
+ the length of @in
+
+
+
+ whether to break long lines
+
+
+
+ pointer to destination buffer
+
+
+
+
+
+ Saved state between steps, initialize to 0
+
+
+
+ Saved state between steps, initialize to 0
+
+
+
+
+
+ Gets the name of the file without any leading directory
+components. It returns a pointer into the given file name
+string.
+ Use g_path_get_basename() instead, but notice
+ that g_path_get_basename() allocates new memory for the
+ returned string, unlike this function which returns a pointer
+ into the argument.
+
+
+ the name of the file without any leading
+ directory components
+
+
+
+
+ the name of the file
+
+
+
+
+
+ Sets the indicated @lock_bit in @address. If the bit is already
+set, this call will block until g_bit_unlock() unsets the
+corresponding bit.
+
+Attempting to lock on two different bits within the same integer is
+not supported and will very probably cause deadlocks.
+
+The value of the bit that is set is (1u << @bit). If @bit is not
+between 0 and 31 then the result is undefined.
+
+This function accesses @address atomically. All other accesses to
+@address must be atomic in order for this function to work
+reliably. While @address has a `volatile` qualifier, this is a historical
+artifact and the argument passed to it should not be `volatile`.
+
+
+
+
+
+
+ a pointer to an integer
+
+
+
+ a bit value between 0 and 31
+
+
+
+
+
+ Find the position of the first bit set in @mask, searching
+from (but not including) @nth_bit upwards. Bits are numbered
+from 0 (least significant) to sizeof(#gulong) * 8 - 1 (31 or 63,
+usually). To start searching from the 0th bit, set @nth_bit to -1.
+
+
+ the index of the first bit set which is higher than @nth_bit, or -1
+ if no higher bits are set
+
+
+
+
+ a #gulong containing flags
+
+
+
+ the index of the bit to start the search from
+
+
+
+
+
+ Find the position of the first bit set in @mask, searching
+from (but not including) @nth_bit downwards. Bits are numbered
+from 0 (least significant) to sizeof(#gulong) * 8 - 1 (31 or 63,
+usually). To start searching from the last bit, set @nth_bit to
+-1 or GLIB_SIZEOF_LONG * 8.
+
+
+ the index of the first bit set which is lower than @nth_bit, or -1
+ if no lower bits are set
+
+
+
+
+ a #gulong containing flags
+
+
+
+ the index of the bit to start the search from
+
+
+
+
+
+ Gets the number of bits used to hold @number,
+e.g. if @number is 4, 3 bits are needed.
+
+
+ the number of bits used to hold @number
+
+
+
+
+ a #guint
+
+
+
+
+
+ Sets the indicated @lock_bit in @address, returning %TRUE if
+successful. If the bit is already set, returns %FALSE immediately.
+
+Attempting to lock on two different bits within the same integer is
+not supported.
+
+The value of the bit that is set is (1u << @bit). If @bit is not
+between 0 and 31 then the result is undefined.
+
+This function accesses @address atomically. All other accesses to
+@address must be atomic in order for this function to work
+reliably. While @address has a `volatile` qualifier, this is a historical
+artifact and the argument passed to it should not be `volatile`.
+
+
+ %TRUE if the lock was acquired
+
+
+
+
+ a pointer to an integer
+
+
+
+ a bit value between 0 and 31
+
+
+
+
+
+ Clears the indicated @lock_bit in @address. If another thread is
+currently blocked in g_bit_lock() on this same bit then it will be
+woken up.
+
+This function accesses @address atomically. All other accesses to
+@address must be atomic in order for this function to work
+reliably. While @address has a `volatile` qualifier, this is a historical
+artifact and the argument passed to it should not be `volatile`.
+
+
+
+
+
+
+ a pointer to an integer
+
+
+
+ a bit value between 0 and 31
+
+
+
+
+
+
+
+
+
+
+ GBookmarkFile lets you parse, edit or create files containing bookmarks
+to URI, along with some meta-data about the resource pointed by the URI
+like its MIME type, the application that is registering the bookmark and
+the icon that should be used to represent the bookmark. The data is stored
+using the
+[Desktop Bookmark Specification](http://www.gnome.org/~ebassi/bookmark-spec).
+
+The syntax of the bookmark files is described in detail inside the
+Desktop Bookmark Specification, here is a quick summary: bookmark
+files use a sub-class of the XML Bookmark Exchange Language
+specification, consisting of valid UTF-8 encoded XML, under the
+<xbel> root element; each bookmark is stored inside a
+<bookmark> element, using its URI: no relative paths can
+be used inside a bookmark file. The bookmark may have a user defined
+title and description, to be used instead of the URI. Under the
+<metadata> element, with its owner attribute set to
+`http://freedesktop.org`, is stored the meta-data about a resource
+pointed by its URI. The meta-data consists of the resource's MIME
+type; the applications that have registered a bookmark; the groups
+to which a bookmark belongs to; a visibility flag, used to set the
+bookmark as "private" to the applications and groups that has it
+registered; the URI and MIME type of an icon, to be used when
+displaying the bookmark inside a GUI.
+
+Here is an example of a bookmark file:
+[bookmarks.xbel](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/glib/tests/bookmarks.xbel)
+
+A bookmark file might contain more than one bookmark; each bookmark
+is accessed through its URI.
+
+The important caveat of bookmark files is that when you add a new
+bookmark you must also add the application that is registering it, using
+g_bookmark_file_add_application() or g_bookmark_file_set_application_info().
+If a bookmark has no applications then it won't be dumped when creating
+the on disk representation, using g_bookmark_file_to_data() or
+g_bookmark_file_to_file().
+
+The #GBookmarkFile parser was added in GLib 2.12.
+
+
+ Creates a filename from a series of elements using the correct
+separator for the current platform.
+
+On Unix, this function behaves identically to `g_build_path
+(G_DIR_SEPARATOR_S, first_element, ....)`.
+
+On Windows, it takes into account that either the backslash
+(`\` or slash (`/`) can be used as separator in filenames, but
+otherwise behaves as on UNIX. When file pathname separators need
+to be inserted, the one that last previously occurred in the
+parameters (reading from left to right) is used.
+
+No attempt is made to force the resulting filename to be an absolute
+path. If the first element is a relative path, the result will
+be a relative path.
+
+If you are building a path programmatically you may want to use
+#GPathBuf instead.
+
+
+ the newly allocated path
+
+
+
+
+ the first element in the path
+
+
+
+ remaining elements in path, terminated by %NULL
+
+
+
+
+
+ Creates a filename from a list of elements using the correct
+separator for the current platform.
+
+Behaves exactly like g_build_filename(), but takes the path elements
+as a va_list.
+
+This function is mainly meant for implementing other variadic arguments
+functions.
+
+
+ the newly allocated path
+
+
+
+
+ the first element in the path
+
+
+
+ va_list of remaining elements in path
+
+
+
+
+
+ Creates a filename from a vector of elements using the correct
+separator for the current platform.
+
+This function behaves exactly like g_build_filename(), but takes the path
+elements as a string array, instead of varargs. This function is mainly
+meant for language bindings.
+
+If you are building a path programmatically you may want to use
+#GPathBuf instead.
+
+
+ the newly allocated path
+
+
+
+
+ %NULL-terminated
+ array of strings containing the path elements.
+
+
+
+
+
+
+
+ Creates a path from a series of elements using @separator as the
+separator between elements.
+
+At the boundary between two elements, any trailing occurrences of
+separator in the first element, or leading occurrences of separator
+in the second element are removed and exactly one copy of the
+separator is inserted.
+
+Empty elements are ignored.
+
+The number of leading copies of the separator on the result is
+the same as the number of leading copies of the separator on
+the first non-empty element.
+
+The number of trailing copies of the separator on the result is
+the same as the number of trailing copies of the separator on
+the last non-empty element. (Determination of the number of
+trailing copies is done without stripping leading copies, so
+if the separator is `ABA`, then `ABABA` has 1 trailing copy.)
+
+However, if there is only a single non-empty element, and there
+are no characters in that element not part of the leading or
+trailing separators, then the result is exactly the original value
+of that element.
+
+Other than for determination of the number of leading and trailing
+copies of the separator, elements consisting only of copies
+of the separator are ignored.
+
+
+ the newly allocated path
+
+
+
+
+ a string used to separator the elements of the path.
+
+
+
+ the first element in the path
+
+
+
+ remaining elements in path, terminated by %NULL
+
+
+
+
+
+ Behaves exactly like g_build_path(), but takes the path elements
+as a string array, instead of variadic arguments.
+
+This function is mainly meant for language bindings.
+
+
+ a newly-allocated string that
+ must be freed with g_free().
+
+
+
+
+ a string used to separator the elements of the path.
+
+
+
+ %NULL-terminated
+ array of strings containing the path elements.
+
+
+
+
+
+
+
+ Frees the memory allocated by the #GByteArray. If @free_segment is
+%TRUE it frees the actual byte data. If the reference count of
+@array is greater than one, the #GByteArray wrapper is preserved but
+the size of @array will be set to zero.
+
+
+ the element data if @free_segment is %FALSE, otherwise
+ %NULL. The element data should be freed using g_free().
+
+
+
+
+ a #GByteArray
+
+
+
+
+
+ if %TRUE the actual byte data is freed as well
+
+
+
+
+
+ Transfers the data from the #GByteArray into a new immutable #GBytes.
+
+The #GByteArray is freed unless the reference count of @array is greater
+than one, the #GByteArray wrapper is preserved but the size of @array
+will be set to zero.
+
+This is identical to using g_bytes_new_take() and g_byte_array_free()
+together.
+
+
+ a new immutable #GBytes representing same
+ byte data that was in the array
+
+
+
+
+ a #GByteArray
+
+
+
+
+
+
+
+ Creates a new #GByteArray with a reference count of 1.
+
+
+ the new #GByteArray
+
+
+
+
+
+
+ Create byte array containing the data. The data will be owned by the array
+and will be freed with g_free(), i.e. it could be allocated using g_strdup().
+
+Do not use it if @len is greater than %G_MAXUINT. #GByteArray
+stores the length of its data in #guint, which may be shorter than
+#gsize.
+
+
+ a new #GByteArray
+
+
+
+
+
+
+ byte data for the array
+
+
+
+
+
+ length of @data
+
+
+
+
+
+ Frees the data in the array and resets the size to zero, while
+the underlying array is preserved for use elsewhere and returned
+to the caller.
+
+
+ the element data, which should be
+ freed using g_free().
+
+
+
+
+ a #GByteArray.
+
+
+
+
+
+ pointer to retrieve the number of
+ elements of the original array
+
+
+
+
+
+ Atomically decrements the reference count of @array by one. If the
+reference count drops to 0, all memory allocated by the array is
+released. This function is thread-safe and may be called from any
+thread.
+
+
+
+
+
+
+ A #GByteArray
+
+
+
+
+
+
+
+ These macros provide a portable way to determine the host byte order
+and to convert values between different byte orders.
+
+The byte order is the order in which bytes are stored to create larger
+data types such as the #gint and #glong values.
+The host byte order is the byte order used on the current machine.
+
+Some processors store the most significant bytes (i.e. the bytes that
+hold the largest part of the value) first. These are known as big-endian
+processors. Other processors (notably the x86 family) store the most
+significant byte last. These are known as little-endian processors.
+
+Finally, to complicate matters, some other processors store the bytes in
+a rather curious order known as PDP-endian. For a 4-byte word, the 3rd
+most significant byte is stored first, then the 4th, then the 1st and
+finally the 2nd.
+
+Obviously there is a problem when these different processors communicate
+with each other, for example over networks or by using binary file formats.
+This is where these macros come in. They are typically used to convert
+values into a byte order which has been agreed on for use when
+communicating between different processors. The Internet uses what is
+known as 'network byte order' as the standard byte order (which is in
+fact the big-endian byte order).
+
+Note that the byte order conversion macros may evaluate their arguments
+multiple times, thus you should not use them with arguments which have
+side-effects.
+
+
+ Gets the canonical file name from @filename. All triple slashes are turned into
+single slashes, and all `..` and `.`s resolved against @relative_to.
+
+Symlinks are not followed, and the returned path is guaranteed to be absolute.
+
+If @filename is an absolute path, @relative_to is ignored. Otherwise,
+@relative_to will be prepended to @filename to make it absolute. @relative_to
+must be an absolute path, or %NULL. If @relative_to is %NULL, it'll fallback
+to g_get_current_dir().
+
+This function never fails, and will canonicalize file paths even if they don't
+exist.
+
+No file system I/O is done.
+
+
+ a newly allocated string with the
+ canonical file path
+
+
+
+
+ the name of the file
+
+
+
+ the relative directory, or %NULL
+to use the current working directory
+
+
+
+
+
+ A wrapper for the POSIX chdir() function. The function changes the
+current directory of the process to @path.
+
+See your C library manual for more details about chdir().
+
+
+ 0 on success, -1 if an error occurred.
+
+
+
+
+ a pathname in the GLib file name encoding
+ (UTF-8 on Windows)
+
+
+
+
+
+ Checks that the GLib library in use is compatible with the
+given version.
+
+Generally you would pass in the constants %GLIB_MAJOR_VERSION,
+%GLIB_MINOR_VERSION, %GLIB_MICRO_VERSION as the three arguments
+to this function; that produces a check that the library in use
+is compatible with the version of GLib the application or module
+was compiled against.
+
+Compatibility is defined by two things: first the version
+of the running library is newer than the version
+`@required_major.required_minor.@required_micro`. Second
+the running library must be binary compatible with the
+version `@required_major.@required_minor.@required_micro`
+(same major version.)
+
+
+ %NULL if the GLib library is
+ compatible with the given version, or a string describing the
+ version mismatch. The returned string is owned by GLib and must
+ not be modified or freed.
+
+
+
+
+ the required major version
+
+
+
+ the required minor version
+
+
+
+ the required micro version
+
+
+
+
+
+ GLib offers a set of macros for doing additions and multiplications
+of unsigned integers, with checks for overflows.
+
+The helpers all have three arguments. A pointer to the destination
+is always the first argument and the operands to the operation are
+the other two.
+
+Following standard GLib convention, the helpers return %TRUE in case
+of success (ie: no overflow).
+
+The helpers may be macros, normal functions or inlines. They may be
+implemented with inline assembly or compiler intrinsics where
+available.
+
+
+ GLib provides a generic API for computing checksums (or "digests")
+for a sequence of arbitrary bytes, using various hashing algorithms
+like MD5, SHA-1 and SHA-256. Checksums are commonly used in various
+environments and specifications.
+
+GLib supports incremental checksums using the GChecksum data
+structure, by calling g_checksum_update() as long as there's data
+available and then using g_checksum_get_string() or
+g_checksum_get_digest() to compute the checksum and return it either
+as a string in hexadecimal form, or as a raw sequence of bytes. To
+compute the checksum for binary blobs and NUL-terminated strings in
+one go, use the convenience functions g_compute_checksum_for_data()
+and g_compute_checksum_for_string(), respectively.
+
+Support for checksums has been added in GLib 2.16
+
+
+ Gets the length in bytes of digests of type @checksum_type
+
+
+ the checksum length, or -1 if @checksum_type is
+not supported.
+
+
+
+
+ a #GChecksumType
+
+
+
+
+
+ Sets a function to be called when the child indicated by @pid
+exits, at a default priority, %G_PRIORITY_DEFAULT.
+
+If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes()
+you will need to pass %G_SPAWN_DO_NOT_REAP_CHILD as flag to
+the spawn function for the child watching to work.
+
+Note that on platforms where #GPid must be explicitly closed
+(see g_spawn_close_pid()) @pid must not be closed while the
+source is still active. Typically, you will want to call
+g_spawn_close_pid() in the callback function for the source.
+
+GLib supports only a single callback per process id.
+On POSIX platforms, the same restrictions mentioned for
+g_child_watch_source_new() apply to this function.
+
+This internally creates a main loop source using
+g_child_watch_source_new() and attaches it to the main loop context
+using g_source_attach(). You can do these steps manually if you
+need greater control.
+
+
+ the ID (greater than 0) of the event source.
+
+
+
+
+ process id to watch. On POSIX the positive pid of a child
+ process. On Windows a handle for a process (which doesn't have
+ to be a child).
+
+
+
+ function to call
+
+
+
+ data to pass to @function
+
+
+
+
+
+ Sets a function to be called when the child indicated by @pid
+exits, at the priority @priority.
+
+If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes()
+you will need to pass %G_SPAWN_DO_NOT_REAP_CHILD as flag to
+the spawn function for the child watching to work.
+
+In many programs, you will want to call g_spawn_check_wait_status()
+in the callback to determine whether or not the child exited
+successfully.
+
+Also, note that on platforms where #GPid must be explicitly closed
+(see g_spawn_close_pid()) @pid must not be closed while the source
+is still active. Typically, you should invoke g_spawn_close_pid()
+in the callback function for the source.
+
+GLib supports only a single callback per process id.
+On POSIX platforms, the same restrictions mentioned for
+g_child_watch_source_new() apply to this function.
+
+This internally creates a main loop source using
+g_child_watch_source_new() and attaches it to the main loop context
+using g_source_attach(). You can do these steps manually if you
+need greater control.
+
+
+ the ID (greater than 0) of the event source.
+
+
+
+
+ the priority of the idle source. Typically this will be in the
+ range between %G_PRIORITY_DEFAULT_IDLE and %G_PRIORITY_HIGH_IDLE.
+
+
+
+ process to watch. On POSIX the positive pid of a child process. On
+Windows a handle for a process (which doesn't have to be a child).
+
+
+
+ function to call
+
+
+
+ data to pass to @function
+
+
+
+ function to call when the idle is removed, or %NULL
+
+
+
+
+
+ Creates a new child_watch source.
+
+The source will not initially be associated with any #GMainContext
+and must be added to one with g_source_attach() before it will be
+executed.
+
+Note that child watch sources can only be used in conjunction with
+`g_spawn...` when the %G_SPAWN_DO_NOT_REAP_CHILD flag is used.
+
+Note that on platforms where #GPid must be explicitly closed
+(see g_spawn_close_pid()) @pid must not be closed while the
+source is still active. Typically, you will want to call
+g_spawn_close_pid() in the callback function for the source.
+
+On POSIX platforms, the following restrictions apply to this API
+due to limitations in POSIX process interfaces:
+
+* @pid must be a child of this process
+* @pid must be positive
+* the application must not call `waitpid` with a non-positive
+ first argument, for instance in another thread
+* the application must not wait for @pid to exit by any other
+ mechanism, including `waitpid(pid, ...)` or a second child-watch
+ source for the same @pid
+* the application must not ignore `SIGCHLD`
+
+If any of those conditions are not met, this and related APIs will
+not work correctly. This can often be diagnosed via a GLib warning
+stating that `ECHILD` was received by `waitpid`.
+
+Calling `waitpid` for specific processes other than @pid remains a
+valid thing to do.
+
+
+ the newly-created child watch source
+
+
+
+
+ process to watch. On POSIX the positive pid of a child process. On
+Windows a handle for a process (which doesn't have to be a child).
+
+
+
+
+
+ If @err or *@err is %NULL, does nothing. Otherwise,
+calls g_error_free() on *@err and sets *@err to %NULL.
+
+
+
+
+
+
+ Clears a numeric handler, such as a #GSource ID.
+
+@tag_ptr must be a valid pointer to the variable holding the handler.
+
+If the ID is zero then this function does nothing.
+Otherwise, clear_func() is called with the ID as a parameter, and the tag is
+set to zero.
+
+A macro is also included that allows this function to be used without
+pointer casts.
+
+
+
+
+
+
+ a pointer to the handler ID
+
+
+
+ the function to call to clear the handler
+
+
+
+
+
+ Clears a pointer to a #GList, freeing it and, optionally, freeing its elements using @destroy.
+
+@list_ptr must be a valid pointer. If @list_ptr points to a null #GList, this does nothing.
+
+
+
+
+
+
+ a #GList return location
+
+
+
+
+
+ the function to pass to g_list_free_full() or %NULL to not free elements
+
+
+
+
+
+ Clears a reference to a variable.
+
+@pp must not be %NULL.
+
+If the reference is %NULL then this function does nothing.
+Otherwise, the variable is destroyed using @destroy and the
+pointer is set to %NULL.
+
+A macro is also included that allows this function to be used without
+pointer casts. This will mask any warnings about incompatible function types
+or calling conventions, so you must ensure that your @destroy function is
+compatible with being called as `GDestroyNotify` using the standard calling
+convention for the platform that GLib was compiled for; otherwise the program
+will experience undefined behaviour.
+
+
+
+
+
+
+ a pointer to a
+ variable, struct member etc. holding a pointer
+
+
+
+ a function to which a gpointer can be passed, to destroy *@pp
+
+
+
+
+
+ Clears a pointer to a #GSList, freeing it and, optionally, freeing its elements using @destroy.
+
+@slist_ptr must be a valid pointer. If @slist_ptr points to a null #GSList, this does nothing.
+
+
+
+
+
+
+ a #GSList return location
+
+
+
+
+
+ the function to pass to g_slist_free_full() or %NULL to not free elements
+
+
+
+
+
+ This wraps the close() call. In case of error, %errno will be
+preserved, but the error will also be stored as a #GError in @error.
+In case of success, %errno is undefined.
+
+Besides using #GError, there is another major reason to prefer this
+function over the call provided by the system; on Unix, it will
+attempt to correctly handle %EINTR, which has platform-specific
+semantics.
+
+It is a bug to call this function with an invalid file descriptor.
+
+Since 2.76, this function is guaranteed to be async-signal-safe if (and only
+if) @error is %NULL and @fd is a valid open file descriptor.
+
+
+ %TRUE on success, %FALSE if there was an error.
+
+
+
+
+ A file descriptor
+
+
+
+
+
+ Computes the checksum for a binary @data. This is a
+convenience wrapper for g_checksum_new(), g_checksum_get_string()
+and g_checksum_free().
+
+The hexadecimal string returned will be in lower case.
+
+
+ the digest of the binary data as a
+ string in hexadecimal, or %NULL if g_checksum_new() fails for
+ @checksum_type. The returned string should be freed with g_free() when
+ done using it.
+
+
+
+
+ a #GChecksumType
+
+
+
+ binary blob to compute the digest of
+
+
+
+
+
+ Computes the checksum for a binary @data of @length. This is a
+convenience wrapper for g_checksum_new(), g_checksum_get_string()
+and g_checksum_free().
+
+The hexadecimal string returned will be in lower case.
+
+
+ the digest of the binary data as a
+ string in hexadecimal, or %NULL if g_checksum_new() fails for
+ @checksum_type. The returned string should be freed with g_free() when
+ done using it.
+
+
+
+
+ a #GChecksumType
+
+
+
+ binary blob to compute the digest of
+
+
+
+
+
+ length of @data
+
+
+
+
+
+ Computes the checksum of a string.
+
+The hexadecimal string returned will be in lower case.
+
+
+ the checksum as a hexadecimal string,
+ or %NULL if g_checksum_new() fails for @checksum_type. The returned string
+ should be freed with g_free() when done using it.
+
+
+
+
+ a #GChecksumType
+
+
+
+ the string to compute the checksum of
+
+
+
+ the length of the string, or -1 if the string is null-terminated.
+
+
+
+
+
+ Computes the HMAC for a binary @data. This is a
+convenience wrapper for g_hmac_new(), g_hmac_get_string()
+and g_hmac_unref().
+
+The hexadecimal string returned will be in lower case.
+
+
+ the HMAC of the binary data as a string in hexadecimal.
+ The returned string should be freed with g_free() when done using it.
+
+
+
+
+ a #GChecksumType to use for the HMAC
+
+
+
+ the key to use in the HMAC
+
+
+
+ binary blob to compute the HMAC of
+
+
+
+
+
+ Computes the HMAC for a binary @data of @length. This is a
+convenience wrapper for g_hmac_new(), g_hmac_get_string()
+and g_hmac_unref().
+
+The hexadecimal string returned will be in lower case.
+
+
+ the HMAC of the binary data as a string in hexadecimal.
+ The returned string should be freed with g_free() when done using it.
+
+
+
+
+ a #GChecksumType to use for the HMAC
+
+
+
+ the key to use in the HMAC
+
+
+
+
+
+ the length of the key
+
+
+
+ binary blob to compute the HMAC of
+
+
+
+
+
+ length of @data
+
+
+
+
+
+ Computes the HMAC for a string.
+
+The hexadecimal string returned will be in lower case.
+
+
+ the HMAC as a hexadecimal string.
+ The returned string should be freed with g_free()
+ when done using it.
+
+
+
+
+ a #GChecksumType to use for the HMAC
+
+
+
+ the key to use in the HMAC
+
+
+
+
+
+ the length of the key
+
+
+
+ the string to compute the HMAC for
+
+
+
+ the length of the string, or -1 if the string is nul-terminated
+
+
+
+
+
+ The g_convert() family of function wraps the functionality of iconv().
+In addition to pure character set conversions, GLib has functions to
+deal with the extra complications of encodings for file names.
+
+## File Name Encodings
+
+Historically, UNIX has not had a defined encoding for file names:
+a file name is valid as long as it does not have path separators
+in it ("/"). However, displaying file names may require conversion:
+from the character set in which they were created, to the character
+set in which the application operates. Consider the Spanish file name
+"Presentación.sxi". If the application which created it uses
+ISO-8859-1 for its encoding,
+|[
+Character: P r e s e n t a c i ó n . s x i
+Hex code: 50 72 65 73 65 6e 74 61 63 69 f3 6e 2e 73 78 69
+]|
+However, if the application use UTF-8, the actual file name on
+disk would look like this:
+|[
+Character: P r e s e n t a c i ó n . s x i
+Hex code: 50 72 65 73 65 6e 74 61 63 69 c3 b3 6e 2e 73 78 69
+]|
+Glib uses UTF-8 for its strings, and GUI toolkits like GTK+ that use
+GLib do the same thing. If you get a file name from the file system,
+for example, from readdir() or from g_dir_read_name(), and you wish
+to display the file name to the user, you will need to convert it
+into UTF-8. The opposite case is when the user types the name of a
+file they wish to save: the toolkit will give you that string in
+UTF-8 encoding, and you will need to convert it to the character
+set used for file names before you can create the file with open()
+or fopen().
+
+By default, GLib assumes that file names on disk are in UTF-8
+encoding. This is a valid assumption for file systems which
+were created relatively recently: most applications use UTF-8
+encoding for their strings, and that is also what they use for
+the file names they create. However, older file systems may
+still contain file names created in "older" encodings, such as
+ISO-8859-1. In this case, for compatibility reasons, you may want
+to instruct GLib to use that particular encoding for file names
+rather than UTF-8. You can do this by specifying the encoding for
+file names in the [`G_FILENAME_ENCODING`][G_FILENAME_ENCODING]
+environment variable. For example, if your installation uses
+ISO-8859-1 for file names, you can put this in your `~/.profile`:
+|[
+export G_FILENAME_ENCODING=ISO-8859-1
+]|
+GLib provides the functions g_filename_to_utf8() and
+g_filename_from_utf8() to perform the necessary conversions.
+These functions convert file names from the encoding specified
+in `G_FILENAME_ENCODING` to UTF-8 and vice-versa. This
+[diagram][file-name-encodings-diagram] illustrates how
+these functions are used to convert between UTF-8 and the
+encoding for file names in the file system.
+
+## Conversion between file name encodings # {#file-name-encodings-diagram)
+
+
+
+## Checklist for Application Writers
+
+This section is a practical summary of the detailed
+things to do to make sure your applications process file
+name encodings correctly.
+
+1. If you get a file name from the file system from a function
+ such as readdir() or gtk_file_chooser_get_filename(), you do
+ not need to do any conversion to pass that file name to
+ functions like open(), rename(), or fopen() -- those are "raw"
+ file names which the file system understands.
+
+2. If you need to display a file name, convert it to UTF-8 first
+ by using g_filename_to_utf8(). If conversion fails, display a
+ string like "Unknown file name". Do not convert this string back
+ into the encoding used for file names if you wish to pass it to
+ the file system; use the original file name instead.
+
+ For example, the document window of a word processor could display
+ "Unknown file name" in its title bar but still let the user save
+ the file, as it would keep the raw file name internally. This
+ can happen if the user has not set the `G_FILENAME_ENCODING`
+ environment variable even though they have files whose names are
+ not encoded in UTF-8.
+
+3. If your user interface lets the user type a file name for saving
+ or renaming, convert it to the encoding used for file names in
+ the file system by using g_filename_from_utf8(). Pass the converted
+ file name to functions like fopen(). If conversion fails, ask the
+ user to enter a different file name. This can happen if the user
+ types Japanese characters when `G_FILENAME_ENCODING` is set to
+ `ISO-8859-1`, for example.
+
+
+ Converts a string from one character set to another.
+
+Note that you should use g_iconv() for streaming conversions.
+Despite the fact that @bytes_read can return information about partial
+characters, the g_convert_... functions are not generally suitable
+for streaming. If the underlying converter maintains internal state,
+then this won't be preserved across successive calls to g_convert(),
+g_convert_with_iconv() or g_convert_with_fallback(). (An example of
+this is the GNU C converter for CP1255 which does not emit a base
+character until it knows that the next character is not a mark that
+could combine with the base character.)
+
+Using extensions such as "//TRANSLIT" may not work (or may not work
+well) on many platforms. Consider using g_str_to_ascii() instead.
+
+
+
+ If the conversion was successful, a newly allocated buffer
+ containing the converted string, which must be freed with g_free().
+ Otherwise %NULL and @error will be set.
+
+
+
+
+
+
+
+ the string to convert.
+
+
+
+
+
+ the length of the string in bytes, or -1 if the string is
+ nul-terminated (Note that some encodings may allow nul
+ bytes to occur inside strings. In that case, using -1
+ for the @len parameter is unsafe)
+
+
+
+ name of character set into which to convert @str
+
+
+
+ character set of @str.
+
+
+
+ location to store the number of bytes in
+ the input string that were successfully converted, or %NULL.
+ Even if the conversion was successful, this may be
+ less than @len if there were partial characters
+ at the end of the input. If the error
+ %G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
+ stored will be the byte offset after the last valid
+ input sequence.
+
+
+
+ the number of bytes stored in
+ the output buffer (not including the terminating nul).
+
+
+
+
+
+
+
+
+
+
+ Converts a string from one character set to another, possibly
+including fallback sequences for characters not representable
+in the output. Note that it is not guaranteed that the specification
+for the fallback sequences in @fallback will be honored. Some
+systems may do an approximate conversion from @from_codeset
+to @to_codeset in their iconv() functions,
+in which case GLib will simply return that approximate conversion.
+
+Note that you should use g_iconv() for streaming conversions.
+Despite the fact that @bytes_read can return information about partial
+characters, the g_convert_... functions are not generally suitable
+for streaming. If the underlying converter maintains internal state,
+then this won't be preserved across successive calls to g_convert(),
+g_convert_with_iconv() or g_convert_with_fallback(). (An example of
+this is the GNU C converter for CP1255 which does not emit a base
+character until it knows that the next character is not a mark that
+could combine with the base character.)
+
+
+
+ If the conversion was successful, a newly allocated buffer
+ containing the converted string, which must be freed with g_free().
+ Otherwise %NULL and @error will be set.
+
+
+
+
+
+
+
+ the string to convert.
+
+
+
+
+
+ the length of the string in bytes, or -1 if the string is
+ nul-terminated (Note that some encodings may allow nul
+ bytes to occur inside strings. In that case, using -1
+ for the @len parameter is unsafe)
+
+
+
+ name of character set into which to convert @str
+
+
+
+ character set of @str.
+
+
+
+ UTF-8 string to use in place of characters not
+ present in the target encoding. (The string must be
+ representable in the target encoding).
+ If %NULL, characters not in the target encoding will
+ be represented as Unicode escapes \uxxxx or \Uxxxxyyyy.
+
+
+
+ location to store the number of bytes in
+ the input string that were successfully converted, or %NULL.
+ Even if the conversion was successful, this may be
+ less than @len if there were partial characters
+ at the end of the input.
+
+
+
+ the number of bytes stored in
+ the output buffer (not including the terminating nul).
+
+
+
+
+
+ Converts a string from one character set to another.
+
+Note that you should use g_iconv() for streaming conversions.
+Despite the fact that @bytes_read can return information about partial
+characters, the g_convert_... functions are not generally suitable
+for streaming. If the underlying converter maintains internal state,
+then this won't be preserved across successive calls to g_convert(),
+g_convert_with_iconv() or g_convert_with_fallback(). (An example of
+this is the GNU C converter for CP1255 which does not emit a base
+character until it knows that the next character is not a mark that
+could combine with the base character.)
+
+Characters which are valid in the input character set, but which have no
+representation in the output character set will result in a
+%G_CONVERT_ERROR_ILLEGAL_SEQUENCE error. This is in contrast to the iconv()
+specification, which leaves this behaviour implementation defined. Note that
+this is the same error code as is returned for an invalid byte sequence in
+the input character set. To get defined behaviour for conversion of
+unrepresentable characters, use g_convert_with_fallback().
+
+
+
+ If the conversion was successful, a newly allocated buffer
+ containing the converted string, which must be freed with
+ g_free(). Otherwise %NULL and @error will be set.
+
+
+
+
+
+
+
+ the string to convert.
+
+
+
+
+
+ the length of the string in bytes, or -1 if the string is
+ nul-terminated (Note that some encodings may allow nul
+ bytes to occur inside strings. In that case, using -1
+ for the @len parameter is unsafe)
+
+
+
+ conversion descriptor from g_iconv_open()
+
+
+
+ location to store the number of bytes in
+ the input string that were successfully converted, or %NULL.
+ Even if the conversion was successful, this may be
+ less than @len if there were partial characters
+ at the end of the input. If the error
+ %G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
+ stored will be the byte offset after the last valid
+ input sequence.
+
+
+
+ the number of bytes stored in
+ the output buffer (not including the terminating nul).
+
+
+
+
+
+ Logs a "critical warning" (%G_LOG_LEVEL_CRITICAL).
+
+Critical warnings are intended to be used in the event of an error
+that originated in the current process (a programmer error).
+Logging of a critical error is by definition an indication of a bug
+somewhere in the current program (or its libraries).
+
+g_return_if_fail(), g_return_val_if_fail(), g_return_if_reached() and
+g_return_val_if_reached() log at %G_LOG_LEVEL_CRITICAL.
+
+You can make critical warnings fatal at runtime by
+setting the `G_DEBUG` environment variable (see
+[Running GLib Applications](glib-running.html)):
+
+|[
+ G_DEBUG=fatal-warnings gdb ./my-program
+]|
+
+You can also use g_log_set_always_fatal().
+
+Any unrelated failures can be skipped over in
+[gdb](https://www.gnu.org/software/gdb/) using the `continue` command.
+
+The message should typically *not* be translated to the
+user's language.
+
+If g_log_default_handler() is used as the log handler function, a new-line
+character will automatically be appended to @..., and need not be entered
+manually.
+
+If structured logging is enabled, this will use g_log_structured();
+otherwise it will use g_log(). See
+[Using Structured Logging][using-structured-logging].
+
+
+
+ format string, followed by parameters to insert
+ into the format string (as with printf())
+
+
+
+
+ Keyed data lists provide lists of arbitrary data elements which can
+be accessed either with a string or with a #GQuark corresponding to
+the string.
+
+The #GQuark methods are quicker, since the strings have to be
+converted to #GQuarks anyway.
+
+Data lists are used for associating arbitrary data with #GObjects,
+using g_object_set_data() and related functions.
+
+To create a datalist, use g_datalist_init().
+
+To add data elements to a datalist use g_datalist_id_set_data(),
+g_datalist_id_set_data_full(), g_datalist_set_data() and
+g_datalist_set_data_full().
+
+To get data elements from a datalist use g_datalist_id_get_data()
+and g_datalist_get_data().
+
+To iterate over all data elements in a datalist use
+g_datalist_foreach() (not thread-safe).
+
+To remove data elements from a datalist use
+g_datalist_id_remove_data() and g_datalist_remove_data().
+
+To remove all data elements from a datalist, use g_datalist_clear().
+
+
+ Frees all the data elements of the datalist.
+The data elements' destroy functions are called
+if they have been set.
+
+
+
+
+
+
+ a datalist.
+
+
+
+
+
+ Calls the given function for each data element of the datalist. The
+function is called with each data element's #GQuark id and data,
+together with the given @user_data parameter. Note that this
+function is NOT thread-safe. So unless @datalist can be protected
+from any modifications during invocation of this function, it should
+not be called.
+
+@func can make changes to @datalist, but the iteration will not
+reflect changes made during the g_datalist_foreach() call, other
+than skipping over elements that are removed.
+
+
+
+
+
+
+ a datalist.
+
+
+
+ the function to call for each data element.
+
+
+
+ user data to pass to the function.
+
+
+
+
+
+ Gets a data element, using its string identifier. This is slower than
+g_datalist_id_get_data() because it compares strings.
+
+
+ the data element, or %NULL if it
+ is not found.
+
+
+
+
+ a datalist.
+
+
+
+ the string identifying a data element.
+
+
+
+
+
+ Gets flags values packed in together with the datalist.
+See g_datalist_set_flags().
+
+
+ the flags of the datalist
+
+
+
+
+ pointer to the location that holds a list
+
+
+
+
+
+ This is a variant of g_datalist_id_get_data() which
+returns a 'duplicate' of the value. @dup_func defines the
+meaning of 'duplicate' in this context, it could e.g.
+take a reference on a ref-counted object.
+
+If the @key_id is not set in the datalist then @dup_func
+will be called with a %NULL argument.
+
+Note that @dup_func is called while the datalist is locked, so it
+is not allowed to read or modify the datalist.
+
+This function can be useful to avoid races when multiple
+threads are using the same datalist and the same key.
+
+
+ the result of calling @dup_func on the value
+ associated with @key_id in @datalist, or %NULL if not set.
+ If @dup_func is %NULL, the value is returned unmodified.
+
+
+
+
+ location of a datalist
+
+
+
+ the #GQuark identifying a data element
+
+
+
+ function to duplicate the old value
+
+
+
+ passed as user_data to @dup_func
+
+
+
+
+
+ Retrieves the data element corresponding to @key_id.
+
+
+ the data element, or %NULL if
+ it is not found.
+
+
+
+
+ a datalist.
+
+
+
+ the #GQuark identifying a data element.
+
+
+
+
+
+ Removes an element, using its #GQuark identifier.
+
+
+
+ a datalist.
+
+
+ the #GQuark identifying the data element.
+
+
+
+
+ Removes multiple keys from a datalist.
+
+This is more efficient than calling g_datalist_id_remove_data()
+multiple times in a row.
+
+
+
+
+
+
+ a datalist
+
+
+
+ keys to remove
+
+
+
+
+
+ length of @keys, must be <= 16
+
+
+
+
+
+ Removes an element, without calling its destroy notification
+function.
+
+
+ the data previously stored at @key_id,
+ or %NULL if none.
+
+
+
+
+ a datalist.
+
+
+
+ the #GQuark identifying a data element.
+
+
+
+
+
+ Compares the member that is associated with @key_id in
+@datalist to @oldval, and if they are the same, replace
+@oldval with @newval.
+
+This is like a typical atomic compare-and-exchange
+operation, for a member of @datalist.
+
+If the previous value was replaced then ownership of the
+old value (@oldval) is passed to the caller, including
+the registered destroy notify for it (passed out in @old_destroy).
+Its up to the caller to free this as they wish, which may
+or may not include using @old_destroy as sometimes replacement
+should not destroy the object in the normal way.
+
+
+ %TRUE if the existing value for @key_id was replaced
+ by @newval, %FALSE otherwise.
+
+
+
+
+ location of a datalist
+
+
+
+ the #GQuark identifying a data element
+
+
+
+ the old value to compare against
+
+
+
+ the new value to replace it with
+
+
+
+ destroy notify for the new value
+
+
+
+ destroy notify for the existing value
+
+
+
+
+
+ Sets the data corresponding to the given #GQuark id. Any previous
+data with the same key is removed, and its destroy function is
+called.
+
+
+
+ a datalist.
+
+
+ the #GQuark to identify the data element.
+
+
+ the data element, or %NULL to remove any previous element
+ corresponding to @q.
+
+
+
+
+ Sets the data corresponding to the given #GQuark id, and the
+function to be called when the element is removed from the datalist.
+Any previous data with the same key is removed, and its destroy
+function is called.
+
+
+
+
+
+
+ a datalist.
+
+
+
+ the #GQuark to identify the data element.
+
+
+
+ the data element or %NULL to remove any previous element
+ corresponding to @key_id.
+
+
+
+ the function to call when the data element is
+ removed. This function will be called with the data
+ element and can be used to free any memory allocated
+ for it. If @data is %NULL, then @destroy_func must
+ also be %NULL.
+
+
+
+
+
+ Resets the datalist to %NULL. It does not free any memory or call
+any destroy functions.
+
+
+
+
+
+
+ a pointer to a pointer to a datalist.
+
+
+
+
+
+ Removes an element using its string identifier. The data element's
+destroy function is called if it has been set.
+
+
+
+ a datalist.
+
+
+ the string identifying the data element.
+
+
+
+
+ Removes an element, without calling its destroy notifier.
+
+
+
+ a datalist.
+
+
+ the string identifying the data element.
+
+
+
+
+ Sets the data element corresponding to the given string identifier.
+
+
+
+ a datalist.
+
+
+ the string to identify the data element.
+
+
+ the data element, or %NULL to remove any previous element
+ corresponding to @k.
+
+
+
+
+ Sets the data element corresponding to the given string identifier,
+and the function to be called when the data element is removed.
+
+
+
+ a datalist.
+
+
+ the string to identify the data element.
+
+
+ the data element, or %NULL to remove any previous element
+ corresponding to @k.
+
+
+ the function to call when the data element is removed.
+ This function will be called with the data element and can be used to
+ free any memory allocated for it. If @d is %NULL, then @f must
+ also be %NULL.
+
+
+
+
+ Turns on flag values for a data list. This function is used
+to keep a small number of boolean flags in an object with
+a data list without using any additional space. It is
+not generally useful except in circumstances where space
+is very tight. (It is used in the base #GObject type, for
+example.)
+
+
+
+
+
+
+ pointer to the location that holds a list
+
+
+
+ the flags to turn on. The values of the flags are
+ restricted by %G_DATALIST_FLAGS_MASK (currently
+ 3; giving two possible boolean flags).
+ A value for @flags that doesn't fit within the mask is
+ an error.
+
+
+
+
+
+ Turns off flag values for a data list. See g_datalist_unset_flags()
+
+
+
+
+
+
+ pointer to the location that holds a list
+
+
+
+ the flags to turn off. The values of the flags are
+ restricted by %G_DATALIST_FLAGS_MASK (currently
+ 3: giving two possible boolean flags).
+ A value for @flags that doesn't fit within the mask is
+ an error.
+
+
+
+
+
+ Destroys the dataset, freeing all memory allocated, and calling any
+destroy functions set for data elements.
+
+
+
+
+
+
+ the location identifying the dataset.
+
+
+
+
+
+ Calls the given function for each data element which is associated
+with the given location. Note that this function is NOT thread-safe.
+So unless @dataset_location can be protected from any modifications
+during invocation of this function, it should not be called.
+
+@func can make changes to the dataset, but the iteration will not
+reflect changes made during the g_dataset_foreach() call, other
+than skipping over elements that are removed.
+
+
+
+
+
+
+ the location identifying the dataset.
+
+
+
+ the function to call for each data element.
+
+
+
+ user data to pass to the function.
+
+
+
+
+
+ Gets the data element corresponding to a string.
+
+
+
+ the location identifying the dataset.
+
+
+ the string identifying the data element.
+
+
+
+
+ Gets the data element corresponding to a #GQuark.
+
+
+ the data element corresponding to
+ the #GQuark, or %NULL if it is not found.
+
+
+
+
+ the location identifying the dataset.
+
+
+
+ the #GQuark id to identify the data element.
+
+
+
+
+
+ Removes a data element from a dataset. The data element's destroy
+function is called if it has been set.
+
+
+
+ the location identifying the dataset.
+
+
+ the #GQuark id identifying the data element.
+
+
+
+
+ Removes an element, without calling its destroy notification
+function.
+
+
+ the data previously stored at @key_id,
+ or %NULL if none.
+
+
+
+
+ the location identifying the dataset.
+
+
+
+ the #GQuark ID identifying the data element.
+
+
+
+
+
+ Sets the data element associated with the given #GQuark id. Any
+previous data with the same key is removed, and its destroy function
+is called.
+
+
+
+ the location identifying the dataset.
+
+
+ the #GQuark id to identify the data element.
+
+
+ the data element.
+
+
+
+
+ Sets the data element associated with the given #GQuark id, and also
+the function to call when the data element is destroyed. Any
+previous data with the same key is removed, and its destroy function
+is called.
+
+
+
+
+
+
+ the location identifying the dataset.
+
+
+
+ the #GQuark id to identify the data element.
+
+
+
+ the data element.
+
+
+
+ the function to call when the data element is
+ removed. This function will be called with the data
+ element and can be used to free any memory allocated
+ for it.
+
+
+
+
+
+ Removes a data element corresponding to a string. Its destroy
+function is called if it has been set.
+
+
+
+ the location identifying the dataset.
+
+
+ the string identifying the data element.
+
+
+
+
+ Removes an element, without calling its destroy notifier.
+
+
+
+ the location identifying the dataset.
+
+
+ the string identifying the data element.
+
+
+
+
+ Sets the data corresponding to the given string identifier.
+
+
+
+ the location identifying the dataset.
+
+
+ the string to identify the data element.
+
+
+ the data element.
+
+
+
+
+ Sets the data corresponding to the given string identifier, and the
+function to call when the data element is destroyed.
+
+
+
+ the location identifying the dataset.
+
+
+ the string to identify the data element.
+
+
+ the data element.
+
+
+ the function to call when the data element is removed. This
+ function will be called with the data element and can be used to
+ free any memory allocated for it.
+
+
+
+
+ Datasets associate groups of data elements with particular memory
+locations. These are useful if you need to associate data with a
+structure returned from an external library. Since you cannot modify
+the structure, you use its location in memory as the key into a
+dataset, where you can associate any number of data elements with it.
+
+There are two forms of most of the dataset functions. The first form
+uses strings to identify the data elements associated with a
+location. The second form uses #GQuark identifiers, which are
+created with a call to g_quark_from_string() or
+g_quark_from_static_string(). The second form is quicker, since it
+does not require looking up the string in the hash table of #GQuark
+identifiers.
+
+There is no function to create a dataset. It is automatically
+created as soon as you add elements to it.
+
+To add data elements to a dataset use g_dataset_id_set_data(),
+g_dataset_id_set_data_full(), g_dataset_set_data() and
+g_dataset_set_data_full().
+
+To get data elements from a dataset use g_dataset_id_get_data() and
+g_dataset_get_data().
+
+To iterate over all data elements in a dataset use
+g_dataset_foreach() (not thread-safe).
+
+To remove data elements from a dataset use
+g_dataset_id_remove_data() and g_dataset_remove_data().
+
+To destroy a dataset, use g_dataset_destroy().
+
+
+ The #GDate data structure represents a day between January 1, Year 1,
+and sometime a few thousand years in the future (right now it will go
+to the year 65535 or so, but g_date_set_parse() only parses up to the
+year 8000 or so - just count on "a few thousand"). #GDate is meant to
+represent everyday dates, not astronomical dates or historical dates
+or ISO timestamps or the like. It extrapolates the current Gregorian
+calendar forward and backward in time; there is no attempt to change
+the calendar to match time periods or locations. #GDate does not store
+time information; it represents a day.
+
+The #GDate implementation has several nice features; it is only a
+64-bit struct, so storing large numbers of dates is very efficient. It
+can keep both a Julian and day-month-year representation of the date,
+since some calculations are much easier with one representation or the
+other. A Julian representation is simply a count of days since some
+fixed day in the past; for #GDate the fixed day is January 1, 1 AD.
+("Julian" dates in the #GDate API aren't really Julian dates in the
+technical sense; technically, Julian dates count from the start of the
+Julian period, Jan 1, 4713 BC).
+
+#GDate is simple to use. First you need a "blank" date; you can get a
+dynamically allocated date from g_date_new(), or you can declare an
+automatic variable or array and initialize it by
+calling g_date_clear(). A cleared date is safe; it's safe to call
+g_date_set_dmy() and the other mutator functions to initialize the
+value of a cleared date. However, a cleared date is initially
+invalid, meaning that it doesn't represent a day that exists.
+It is undefined to call any of the date calculation routines on an
+invalid date. If you obtain a date from a user or other
+unpredictable source, you should check its validity with the
+g_date_valid() predicate. g_date_valid() is also used to check for
+errors with g_date_set_parse() and other functions that can
+fail. Dates can be invalidated by calling g_date_clear() again.
+
+It is very important to use the API to access the #GDate
+struct. Often only the day-month-year or only the Julian
+representation is valid. Sometimes neither is valid. Use the API.
+
+GLib also features #GDateTime which represents a precise time.
+
+
+ #GDateTime is a structure that combines a Gregorian date and time
+into a single structure. It provides many conversion and methods to
+manipulate dates and times. Time precision is provided down to
+microseconds and the time can range (proleptically) from 0001-01-01
+00:00:00 to 9999-12-31 23:59:59.999999. #GDateTime follows POSIX
+time in the sense that it is oblivious to leap seconds.
+
+#GDateTime is an immutable object; once it has been created it cannot
+be modified further. All modifiers will create a new #GDateTime.
+Nearly all such functions can fail due to the date or time going out
+of range, in which case %NULL will be returned.
+
+#GDateTime is reference counted: the reference count is increased by calling
+g_date_time_ref() and decreased by calling g_date_time_unref(). When the
+reference count drops to 0, the resources allocated by the #GDateTime
+structure are released.
+
+Many parts of the API may produce non-obvious results. As an
+example, adding two months to January 31st will yield March 31st
+whereas adding one month and then one month again will yield either
+March 28th or March 29th. Also note that adding 24 hours is not
+always the same as adding one day (since days containing daylight
+savings time transitions are either 23 or 25 hours in length).
+
+#GDateTime is available since GLib 2.26.
+
+
+ Returns the number of days in a month, taking leap
+years into account.
+
+
+ number of days in @month during the @year
+
+
+
+
+ month
+
+
+
+ year
+
+
+
+
+
+ Returns the number of weeks in the year, where weeks
+are taken to start on Monday. Will be 52 or 53. The
+date must be valid. (Years always have 52 7-day periods,
+plus 1 or 2 extra days depending on whether it's a leap
+year. This function is basically telling you how many
+Mondays are in the year, i.e. there are 53 Mondays if
+one of the extra days happens to be a Monday.)
+
+
+ number of Mondays in the year
+
+
+
+
+ a year
+
+
+
+
+
+ Returns the number of weeks in the year, where weeks
+are taken to start on Sunday. Will be 52 or 53. The
+date must be valid. (Years always have 52 7-day periods,
+plus 1 or 2 extra days depending on whether it's a leap
+year. This function is basically telling you how many
+Sundays are in the year, i.e. there are 53 Sundays if
+one of the extra days happens to be a Sunday.)
+
+
+ the number of weeks in @year
+
+
+
+
+ year to count weeks in
+
+
+
+
+
+ Returns %TRUE if the year is a leap year.
+
+For the purposes of this function, leap year is every year
+divisible by 4 unless that year is divisible by 100. If it
+is divisible by 100 it would be a leap year only if that year
+is also divisible by 400.
+
+
+ %TRUE if the year is a leap year
+
+
+
+
+ year to check
+
+
+
+
+
+ Generates a printed representation of the date, in a
+[locale][setlocale]-specific way.
+Works just like the platform's C library strftime() function,
+but only accepts date-related formats; time-related formats
+give undefined results. Date must be valid. Unlike strftime()
+(which uses the locale encoding), works on a UTF-8 format
+string and stores a UTF-8 result.
+
+This function does not provide any conversion specifiers in
+addition to those implemented by the platform's C library.
+For example, don't expect that using g_date_strftime() would
+make the \%F provided by the C99 strftime() work on Windows
+where the C library only complies to C89.
+
+
+ number of characters written to the buffer, or 0 the buffer was too small
+
+
+
+
+ destination buffer
+
+
+
+ buffer size
+
+
+
+ format string
+
+
+
+ valid #GDate
+
+
+
+
+
+ Returns %TRUE if the day of the month is valid (a day is valid if it's
+between 1 and 31 inclusive).
+
+
+ %TRUE if the day is valid
+
+
+
+
+ day to check
+
+
+
+
+
+ Returns %TRUE if the day-month-year triplet forms a valid, existing day
+in the range of days #GDate understands (Year 1 or later, no more than
+a few thousand years in the future).
+
+
+ %TRUE if the date is a valid one
+
+
+
+
+ day
+
+
+
+ month
+
+
+
+ year
+
+
+
+
+
+ Returns %TRUE if the Julian day is valid. Anything greater than zero
+is basically a valid Julian, though there is a 32-bit limit.
+
+
+ %TRUE if the Julian day is valid
+
+
+
+
+ Julian day to check
+
+
+
+
+
+ Returns %TRUE if the month value is valid. The 12 #GDateMonth
+enumeration values are the only valid months.
+
+
+ %TRUE if the month is valid
+
+
+
+
+ month
+
+
+
+
+
+ Returns %TRUE if the weekday is valid. The seven #GDateWeekday enumeration
+values are the only valid weekdays.
+
+
+ %TRUE if the weekday is valid
+
+
+
+
+ weekday
+
+
+
+
+
+ Returns %TRUE if the year is valid. Any year greater than 0 is valid,
+though there is a 16-bit limit to what #GDate will understand.
+
+
+ %TRUE if the year is valid
+
+
+
+
+ year
+
+
+
+
+
+ This is a variant of g_dgettext() that allows specifying a locale
+category instead of always using `LC_MESSAGES`. See g_dgettext() for
+more information about how this functions differs from calling
+dcgettext() directly.
+
+
+ the translated string for the given locale category
+
+
+
+
+ the translation domain to use, or %NULL to use
+ the domain set with textdomain()
+
+
+
+ message to translate
+
+
+
+ a locale category
+
+
+
+
+
+ A convenience function/macro to log a debug message. The message should
+typically *not* be translated to the user's language.
+
+If g_log_default_handler() is used as the log handler function, a new-line
+character will automatically be appended to @..., and need not be entered
+manually.
+
+Such messages are suppressed by the g_log_default_handler() and
+g_log_writer_default() unless the `G_MESSAGES_DEBUG` environment variable is
+set appropriately.
+
+If structured logging is enabled, this will use g_log_structured();
+otherwise it will use g_log(). See
+[Using Structured Logging][using-structured-logging].
+
+
+
+ format string, followed by parameters to insert
+ into the format string (as with printf())
+
+
+
+
+ This function is a wrapper of dgettext() which does not translate
+the message if the default domain as set with textdomain() has no
+translations for the current locale.
+
+The advantage of using this function over dgettext() proper is that
+libraries using this function (like GTK+) will not use translations
+if the application using the library does not have translations for
+the current locale. This results in a consistent English-only
+interface instead of one having partial translations. For this
+feature to work, the call to textdomain() and setlocale() should
+precede any g_dgettext() invocations. For GTK+, it means calling
+textdomain() before gtk_init or its variants.
+
+This function disables translations if and only if upon its first
+call all the following conditions hold:
+
+- @domain is not %NULL
+
+- textdomain() has been called to set a default text domain
+
+- there is no translations available for the default text domain
+ and the current locale
+
+- current locale is not "C" or any English locales (those
+ starting with "en_")
+
+Note that this behavior may not be desired for example if an application
+has its untranslated messages in a language other than English. In those
+cases the application should call textdomain() after initializing GTK+.
+
+Applications should normally not use this function directly,
+but use the _() macro for translations.
+
+
+ The translated string
+
+
+
+
+ the translation domain to use, or %NULL to use
+ the domain set with textdomain()
+
+
+
+ message to translate
+
+
+
+
+
+ Creates a subdirectory in the preferred directory for temporary
+files (as returned by g_get_tmp_dir()).
+
+@tmpl should be a string in the GLib file name encoding containing
+a sequence of six 'X' characters, as the parameter to g_mkstemp().
+However, unlike these functions, the template should only be a
+basename, no directory components are allowed. If template is
+%NULL, a default template is used.
+
+Note that in contrast to g_mkdtemp() (and mkdtemp()) @tmpl is not
+modified, and might thus be a read-only literal string.
+
+
+ The actual name used. This string
+ should be freed with g_free() when not needed any longer and is
+ is in the GLib file name encoding. In case of errors, %NULL is
+ returned and @error will be set.
+
+
+
+
+ Template for directory name,
+ as in g_mkdtemp(), basename only, or %NULL for a default template
+
+
+
+
+
+ Compares two #gpointer arguments and returns %TRUE if they are equal.
+It can be passed to g_hash_table_new() as the @key_equal_func
+parameter, when using opaque pointers compared by pointer value as
+keys in a #GHashTable.
+
+This equality function is also appropriate for keys that are integers
+stored in pointers, such as `GINT_TO_POINTER (n)`.
+
+
+ %TRUE if the two keys match.
+
+
+
+
+ a key
+
+
+
+ a key to compare with @v1
+
+
+
+
+
+ Converts a gpointer to a hash value.
+It can be passed to g_hash_table_new() as the @hash_func parameter,
+when using opaque pointers compared by pointer value as keys in a
+#GHashTable.
+
+This hash function is also appropriate for keys that are integers
+stored in pointers, such as `GINT_TO_POINTER (n)`.
+
+
+ a hash value corresponding to the key.
+
+
+
+
+ a #gpointer key
+
+
+
+
+
+ This function is a wrapper of dngettext() which does not translate
+the message if the default domain as set with textdomain() has no
+translations for the current locale.
+
+See g_dgettext() for details of how this differs from dngettext()
+proper.
+
+
+ The translated string
+
+
+
+
+ the translation domain to use, or %NULL to use
+ the domain set with textdomain()
+
+
+
+ message to translate
+
+
+
+ plural form of the message
+
+
+
+ the quantity for which translation is needed
+
+
+
+
+
+ Compares the two #gdouble values being pointed to and returns
+%TRUE if they are equal.
+It can be passed to g_hash_table_new() as the @key_equal_func
+parameter, when using non-%NULL pointers to doubles as keys in a
+#GHashTable.
+
+
+ %TRUE if the two keys match.
+
+
+
+
+ a pointer to a #gdouble key
+
+
+
+ a pointer to a #gdouble key to compare with @v1
+
+
+
+
+
+ Converts a pointer to a #gdouble to a hash value.
+It can be passed to g_hash_table_new() as the @hash_func parameter,
+It can be passed to g_hash_table_new() as the @hash_func parameter,
+when using non-%NULL pointers to doubles as keys in a #GHashTable.
+
+
+ a hash value corresponding to the key.
+
+
+
+
+ a pointer to a #gdouble key
+
+
+
+
+
+ This function is a variant of g_dgettext() which supports
+a disambiguating message context. GNU gettext uses the
+'\004' character to separate the message context and
+message id in @msgctxtid.
+If 0 is passed as @msgidoffset, this function will fall back to
+trying to use the deprecated convention of using "|" as a separation
+character.
+
+This uses g_dgettext() internally. See that functions for differences
+with dgettext() proper.
+
+Applications should normally not use this function directly,
+but use the C_() macro for translations with context.
+
+
+ The translated string
+
+
+
+
+ the translation domain to use, or %NULL to use
+ the domain set with textdomain()
+
+
+
+ a combined message context and message id, separated
+ by a \004 character
+
+
+
+ the offset of the message id in @msgctxid
+
+
+
+
+
+ This function is a variant of g_dgettext() which supports
+a disambiguating message context. GNU gettext uses the
+'\004' character to separate the message context and
+message id in @msgctxtid.
+
+This uses g_dgettext() internally. See that functions for differences
+with dgettext() proper.
+
+This function differs from C_() in that it is not a macro and
+thus you may use non-string-literals as context and msgid arguments.
+
+
+ The translated string
+
+
+
+
+ the translation domain to use, or %NULL to use
+ the domain set with textdomain()
+
+
+
+ the message context
+
+
+
+ the message
+
+
+
+
+
+ Returns the value of the environment variable @variable in the
+provided list @envp.
+
+
+ the value of the environment variable, or %NULL if
+ the environment variable is not set in @envp. The returned
+ string is owned by @envp, and will be freed if @variable is
+ set or unset again.
+
+
+
+
+
+ an environment list (eg, as returned from g_get_environ()), or %NULL
+ for an empty environment list
+
+
+
+
+
+ the environment variable to get
+
+
+
+
+
+ Sets the environment variable @variable in the provided list
+@envp to @value.
+
+
+
+ the updated environment list. Free it using g_strfreev().
+
+
+
+
+
+
+
+ an environment list that can be freed using g_strfreev() (e.g., as
+ returned from g_get_environ()), or %NULL for an empty
+ environment list
+
+
+
+
+
+ the environment variable to set, must not
+ contain '='
+
+
+
+ the value for to set the variable to
+
+
+
+ whether to change the variable if it already exists
+
+
+
+
+
+ Removes the environment variable @variable from the provided
+environment @envp.
+
+
+
+ the updated environment list. Free it using g_strfreev().
+
+
+
+
+
+
+
+ an environment list that can be freed using g_strfreev() (e.g., as
+ returned from g_get_environ()), or %NULL for an empty environment list
+
+
+
+
+
+ the environment variable to remove, must not
+ contain '='
+
+
+
+
+
+ A convenience function/macro to log an error message. The message should
+typically *not* be translated to the user's language.
+
+This is not intended for end user error reporting. Use of #GError is
+preferred for that instead, as it allows calling functions to perform actions
+conditional on the type of error.
+
+Error messages are always fatal, resulting in a call to G_BREAKPOINT()
+to terminate the application. This function will
+result in a core dump; don't use it for errors you expect.
+Using this function indicates a bug in your program, i.e.
+an assertion failure.
+
+If g_log_default_handler() is used as the log handler function, a new-line
+character will automatically be appended to @..., and need not be entered
+manually.
+
+If structured logging is enabled, this will use g_log_structured();
+otherwise it will use g_log(). See
+[Using Structured Logging][using-structured-logging].
+
+
+
+ format string, followed by parameters to insert
+ into the format string (as with printf())
+
+
+
+
+ GLib provides a standard method of reporting errors from a called
+function to the calling code. (This is the same problem solved by
+exceptions in other languages.) It's important to understand that
+this method is both a data type (the #GError struct) and a [set of
+rules][gerror-rules]. If you use #GError incorrectly, then your code will not
+properly interoperate with other code that uses #GError, and users
+of your API will probably get confused. In most cases, [using #GError is
+preferred over numeric error codes][gerror-comparison], but there are
+situations where numeric error codes are useful for performance.
+
+First and foremost: #GError should only be used to report recoverable
+runtime errors, never to report programming errors. If the programmer
+has screwed up, then you should use g_warning(), g_return_if_fail(),
+g_assert(), g_error(), or some similar facility. (Incidentally,
+remember that the g_error() function should only be used for
+programming errors, it should not be used to print any error
+reportable via #GError.)
+
+Examples of recoverable runtime errors are "file not found" or
+"failed to parse input." Examples of programming errors are "NULL
+passed to strcmp()" or "attempted to free the same pointer twice."
+These two kinds of errors are fundamentally different: runtime errors
+should be handled or reported to the user, programming errors should
+be eliminated by fixing the bug in the program. This is why most
+functions in GLib and GTK+ do not use the #GError facility.
+
+Functions that can fail take a return location for a #GError as their
+last argument. On error, a new #GError instance will be allocated and
+returned to the caller via this argument. For example:
+|[<!-- language="C" -->
+gboolean g_file_get_contents (const gchar *filename,
+ gchar **contents,
+ gsize *length,
+ GError **error);
+]|
+If you pass a non-%NULL value for the `error` argument, it should
+point to a location where an error can be placed. For example:
+|[<!-- language="C" -->
+gchar *contents;
+GError *err = NULL;
+
+g_file_get_contents ("foo.txt", &contents, NULL, &err);
+g_assert ((contents == NULL && err != NULL) || (contents != NULL && err == NULL));
+if (err != NULL)
+ {
+ // Report error to user, and free error
+ g_assert (contents == NULL);
+ fprintf (stderr, "Unable to read file: %s\n", err->message);
+ g_error_free (err);
+ }
+else
+ {
+ // Use file contents
+ g_assert (contents != NULL);
+ }
+]|
+Note that `err != NULL` in this example is a reliable indicator
+of whether g_file_get_contents() failed. Additionally,
+g_file_get_contents() returns a boolean which
+indicates whether it was successful.
+
+Because g_file_get_contents() returns %FALSE on failure, if you
+are only interested in whether it failed and don't need to display
+an error message, you can pass %NULL for the @error argument:
+|[<!-- language="C" -->
+if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) // ignore errors
+ // no error occurred
+ ;
+else
+ // error
+ ;
+]|
+
+The #GError object contains three fields: @domain indicates the module
+the error-reporting function is located in, @code indicates the specific
+error that occurred, and @message is a user-readable error message with
+as many details as possible. Several functions are provided to deal
+with an error received from a called function: g_error_matches()
+returns %TRUE if the error matches a given domain and code,
+g_propagate_error() copies an error into an error location (so the
+calling function will receive it), and g_clear_error() clears an
+error location by freeing the error and resetting the location to
+%NULL. To display an error to the user, simply display the @message,
+perhaps along with additional context known only to the calling
+function (the file being opened, or whatever - though in the
+g_file_get_contents() case, the @message already contains a filename).
+
+Since error messages may be displayed to the user, they need to be valid
+UTF-8 (all GTK widgets expect text to be UTF-8). Keep this in mind in
+particular when formatting error messages with filenames, which are in
+the 'filename encoding', and need to be turned into UTF-8 using
+g_filename_to_utf8(), g_filename_display_name() or g_utf8_make_valid().
+
+Note, however, that many error messages are too technical to display to the
+user in an application, so prefer to use g_error_matches() to categorize errors
+from called functions, and build an appropriate error message for the context
+within your application. Error messages from a #GError are more appropriate
+to be printed in system logs or on the command line. They are typically
+translated.
+
+When implementing a function that can report errors, the basic
+tool is g_set_error(). Typically, if a fatal error occurs you
+want to g_set_error(), then return immediately. g_set_error()
+does nothing if the error location passed to it is %NULL.
+Here's an example:
+|[<!-- language="C" -->
+gint
+foo_open_file (GError **error)
+{
+ gint fd;
+ int saved_errno;
+
+ g_return_val_if_fail (error == NULL || *error == NULL, -1);
+
+ fd = open ("file.txt", O_RDONLY);
+ saved_errno = errno;
+
+ if (fd < 0)
+ {
+ g_set_error (error,
+ FOO_ERROR, // error domain
+ FOO_ERROR_BLAH, // error code
+ "Failed to open file: %s", // error message format string
+ g_strerror (saved_errno));
+ return -1;
+ }
+ else
+ return fd;
+}
+]|
+
+Things are somewhat more complicated if you yourself call another
+function that can report a #GError. If the sub-function indicates
+fatal errors in some way other than reporting a #GError, such as
+by returning %TRUE on success, you can simply do the following:
+|[<!-- language="C" -->
+gboolean
+my_function_that_can_fail (GError **err)
+{
+ g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
+
+ if (!sub_function_that_can_fail (err))
+ {
+ // assert that error was set by the sub-function
+ g_assert (err == NULL || *err != NULL);
+ return FALSE;
+ }
+
+ // otherwise continue, no error occurred
+ g_assert (err == NULL || *err == NULL);
+}
+]|
+
+If the sub-function does not indicate errors other than by
+reporting a #GError (or if its return value does not reliably indicate
+errors) you need to create a temporary #GError
+since the passed-in one may be %NULL. g_propagate_error() is
+intended for use in this case.
+|[<!-- language="C" -->
+gboolean
+my_function_that_can_fail (GError **err)
+{
+ GError *tmp_error;
+
+ g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
+
+ tmp_error = NULL;
+ sub_function_that_can_fail (&tmp_error);
+
+ if (tmp_error != NULL)
+ {
+ // store tmp_error in err, if err != NULL,
+ // otherwise call g_error_free() on tmp_error
+ g_propagate_error (err, tmp_error);
+ return FALSE;
+ }
+
+ // otherwise continue, no error occurred
+}
+]|
+
+Error pileups are always a bug. For example, this code is incorrect:
+|[<!-- language="C" -->
+gboolean
+my_function_that_can_fail (GError **err)
+{
+ GError *tmp_error;
+
+ g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
+
+ tmp_error = NULL;
+ sub_function_that_can_fail (&tmp_error);
+ other_function_that_can_fail (&tmp_error);
+
+ if (tmp_error != NULL)
+ {
+ g_propagate_error (err, tmp_error);
+ return FALSE;
+ }
+}
+]|
+@tmp_error should be checked immediately after sub_function_that_can_fail(),
+and either cleared or propagated upward. The rule is: after each error,
+you must either handle the error, or return it to the calling function.
+
+Note that passing %NULL for the error location is the equivalent
+of handling an error by always doing nothing about it. So the
+following code is fine, assuming errors in sub_function_that_can_fail()
+are not fatal to my_function_that_can_fail():
+|[<!-- language="C" -->
+gboolean
+my_function_that_can_fail (GError **err)
+{
+ GError *tmp_error;
+
+ g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
+
+ sub_function_that_can_fail (NULL); // ignore errors
+
+ tmp_error = NULL;
+ other_function_that_can_fail (&tmp_error);
+
+ if (tmp_error != NULL)
+ {
+ g_propagate_error (err, tmp_error);
+ return FALSE;
+ }
+}
+]|
+
+Note that passing %NULL for the error location ignores errors;
+it's equivalent to
+`try { sub_function_that_can_fail (); } catch (...) {}`
+in C++. It does not mean to leave errors unhandled; it means
+to handle them by doing nothing.
+
+Error domains and codes are conventionally named as follows:
+
+- The error domain is called <NAMESPACE>_<MODULE>_ERROR,
+ for example %G_SPAWN_ERROR or %G_THREAD_ERROR:
+ |[<!-- language="C" -->
+ #define G_SPAWN_ERROR g_spawn_error_quark ()
+
+ G_DEFINE_QUARK (g-spawn-error-quark, g_spawn_error)
+ ]|
+
+- The quark function for the error domain is called
+ <namespace>_<module>_error_quark,
+ for example g_spawn_error_quark() or g_thread_error_quark().
+
+- The error codes are in an enumeration called
+ <Namespace><Module>Error;
+ for example, #GThreadError or #GSpawnError.
+
+- Members of the error code enumeration are called
+ <NAMESPACE>_<MODULE>_ERROR_<CODE>,
+ for example %G_SPAWN_ERROR_FORK or %G_THREAD_ERROR_AGAIN.
+
+- If there's a "generic" or "unknown" error code for unrecoverable
+ errors it doesn't make sense to distinguish with specific codes,
+ it should be called <NAMESPACE>_<MODULE>_ERROR_FAILED,
+ for example %G_SPAWN_ERROR_FAILED. In the case of error code
+ enumerations that may be extended in future releases, you should
+ generally not handle this error code explicitly, but should
+ instead treat any unrecognized error code as equivalent to
+ FAILED.
+
+## Comparison of #GError and traditional error handling # {#gerror-comparison}
+
+#GError has several advantages over traditional numeric error codes:
+importantly, tools like
+[gobject-introspection](https://developer.gnome.org/gi/stable/) understand
+#GErrors and convert them to exceptions in bindings; the message includes
+more information than just a code; and use of a domain helps prevent
+misinterpretation of error codes.
+
+#GError has disadvantages though: it requires a memory allocation, and
+formatting the error message string has a performance overhead. This makes it
+unsuitable for use in retry loops where errors are a common case, rather than
+being unusual. For example, using %G_IO_ERROR_WOULD_BLOCK means hitting these
+overheads in the normal control flow. String formatting overhead can be
+eliminated by using g_set_error_literal() in some cases.
+
+These performance issues can be compounded if a function wraps the #GErrors
+returned by the functions it calls: this multiplies the number of allocations
+and string formatting operations. This can be partially mitigated by using
+g_prefix_error().
+
+## Rules for use of #GError # {#gerror-rules}
+
+Summary of rules for use of #GError:
+
+- Do not report programming errors via #GError.
+
+- The last argument of a function that returns an error should
+ be a location where a #GError can be placed (i.e. `GError **error`).
+ If #GError is used with varargs, the `GError**` should be the last
+ argument before the `...`.
+
+- The caller may pass %NULL for the `GError**` if they are not interested
+ in details of the exact error that occurred.
+
+- If %NULL is passed for the `GError**` argument, then errors should
+ not be returned to the caller, but your function should still
+ abort and return if an error occurs. That is, control flow should
+ not be affected by whether the caller wants to get a #GError.
+
+- If a #GError is reported, then your function by definition had a
+ fatal failure and did not complete whatever it was supposed to do.
+ If the failure was not fatal, then you handled it and you should not
+ report it. If it was fatal, then you must report it and discontinue
+ whatever you were doing immediately.
+
+- If a #GError is reported, out parameters are not guaranteed to
+ be set to any defined value.
+
+- A `GError*` must be initialized to %NULL before passing its address
+ to a function that can report errors.
+
+- #GError structs must not be stack-allocated.
+
+- "Piling up" errors is always a bug. That is, if you assign a
+ new #GError to a `GError*` that is non-%NULL, thus overwriting
+ the previous error, it indicates that you should have aborted
+ the operation instead of continuing. If you were able to continue,
+ you should have cleared the previous error with g_clear_error().
+ g_set_error() will complain if you pile up errors.
+
+- By convention, if you return a boolean value indicating success
+ then %TRUE means success and %FALSE means failure. Avoid creating
+ functions which have a boolean return value and a #GError parameter,
+ but where the boolean does something other than signal whether the
+ #GError is set. Among other problems, it requires C callers to allocate
+ a temporary error. Instead, provide a `gboolean *` out parameter.
+ There are functions in GLib itself such as g_key_file_has_key() that
+ are hard to use because of this. If %FALSE is returned, the error must
+ be set to a non-%NULL value. One exception to this is that in situations
+ that are already considered to be undefined behaviour (such as when a
+ g_return_val_if_fail() check fails), the error need not be set.
+ Instead of checking separately whether the error is set, callers
+ should ensure that they do not provoke undefined behaviour, then
+ assume that the error will be set on failure.
+
+- A %NULL return value is also frequently used to mean that an error
+ occurred. You should make clear in your documentation whether %NULL
+ is a valid return value in non-error cases; if %NULL is a valid value,
+ then users must check whether an error was returned to see if the
+ function succeeded.
+
+- When implementing a function that can report errors, you may want
+ to add a check at the top of your function that the error return
+ location is either %NULL or contains a %NULL error (e.g.
+ `g_return_if_fail (error == NULL || *error == NULL);`).
+
+## Extended #GError Domains # {#gerror-extended-domains}
+
+Since GLib 2.68 it is possible to extend the #GError type. This is
+done with the G_DEFINE_EXTENDED_ERROR() macro. To create an
+extended #GError type do something like this in the header file:
+|[<!-- language="C" -->
+typedef enum
+{
+ MY_ERROR_BAD_REQUEST,
+} MyError;
+#define MY_ERROR (my_error_quark ())
+GQuark my_error_quark (void);
+int
+my_error_get_parse_error_id (GError *error);
+const char *
+my_error_get_bad_request_details (GError *error);
+]|
+and in implementation:
+|[<!-- language="C" -->
+typedef struct
+{
+ int parse_error_id;
+ char *bad_request_details;
+} MyErrorPrivate;
+
+static void
+my_error_private_init (MyErrorPrivate *priv)
+{
+ priv->parse_error_id = -1;
+ // No need to set priv->bad_request_details to NULL,
+ // the struct is initialized with zeros.
+}
+
+static void
+my_error_private_copy (const MyErrorPrivate *src_priv, MyErrorPrivate *dest_priv)
+{
+ dest_priv->parse_error_id = src_priv->parse_error_id;
+ dest_priv->bad_request_details = g_strdup (src_priv->bad_request_details);
+}
+
+static void
+my_error_private_clear (MyErrorPrivate *priv)
+{
+ g_free (priv->bad_request_details);
+}
+
+// This defines the my_error_get_private and my_error_quark functions.
+G_DEFINE_EXTENDED_ERROR (MyError, my_error)
+
+int
+my_error_get_parse_error_id (GError *error)
+{
+ MyErrorPrivate *priv = my_error_get_private (error);
+ g_return_val_if_fail (priv != NULL, -1);
+ return priv->parse_error_id;
+}
+
+const char *
+my_error_get_bad_request_details (GError *error)
+{
+ MyErrorPrivate *priv = my_error_get_private (error);
+ g_return_val_if_fail (priv != NULL, NULL);
+ g_return_val_if_fail (error->code != MY_ERROR_BAD_REQUEST, NULL);
+ return priv->bad_request_details;
+}
+
+static void
+my_error_set_bad_request (GError **error,
+ const char *reason,
+ int error_id,
+ const char *details)
+{
+ MyErrorPrivate *priv;
+ g_set_error (error, MY_ERROR, MY_ERROR_BAD_REQUEST, "Invalid request: %s", reason);
+ if (error != NULL && *error != NULL)
+ {
+ priv = my_error_get_private (error);
+ g_return_val_if_fail (priv != NULL, NULL);
+ priv->parse_error_id = error_id;
+ priv->bad_request_details = g_strdup (details);
+ }
+}
+]|
+An example of use of the error could be:
+|[<!-- language="C" -->
+gboolean
+send_request (GBytes *request, GError **error)
+{
+ ParseFailedStatus *failure = validate_request (request);
+ if (failure != NULL)
+ {
+ my_error_set_bad_request (error, failure->reason, failure->error_id, failure->details);
+ parse_failed_status_free (failure);
+ return FALSE;
+ }
+
+ return send_one (request, error);
+}
+]|
+
+Please note that if you are a library author and your library
+exposes an existing error domain, then you can't make this error
+domain an extended one without breaking ABI. This is because
+earlier it was possible to create an error with this error domain
+on the stack and then copy it with g_error_copy(). If the new
+version of your library makes the error domain an extended one,
+then g_error_copy() called by code that allocated the error on the
+stack will try to copy more data than it used to, which will lead
+to undefined behavior. You must not stack-allocate errors with an
+extended error domain, and it is bad practice to stack-allocate any
+other #GErrors.
+
+Extended error domains in unloadable plugins/modules are not
+supported.
+
+
+ Gets a #GFileError constant based on the passed-in @err_no.
+
+For example, if you pass in `EEXIST` this function returns
+%G_FILE_ERROR_EXIST. Unlike `errno` values, you can portably
+assume that all #GFileError values will exist.
+
+Normally a #GFileError value goes into a #GError returned
+from a function that manipulates files. So you would use
+g_file_error_from_errno() when constructing a #GError.
+
+
+ #GFileError corresponding to the given @err_no
+
+
+
+
+ an "errno" value
+
+
+
+
+
+
+
+
+
+
+ Reads an entire file into allocated memory, with good error
+checking.
+
+If the call was successful, it returns %TRUE and sets @contents to the file
+contents and @length to the length of the file contents in bytes. The string
+stored in @contents will be nul-terminated, so for text files you can pass
+%NULL for the @length argument. If the call was not successful, it returns
+%FALSE and sets @error. The error domain is %G_FILE_ERROR. Possible error
+codes are those in the #GFileError enumeration. In the error case,
+@contents is set to %NULL and @length is set to zero.
+
+
+ %TRUE on success, %FALSE if an error occurred
+
+
+
+
+ name of a file to read contents from, in the GLib file name encoding
+
+
+
+ location to store an allocated string, use g_free() to free
+ the returned string
+
+
+
+
+
+ location to store length in bytes of the contents, or %NULL
+
+
+
+
+
+ Opens a file for writing in the preferred directory for temporary
+files (as returned by g_get_tmp_dir()).
+
+@tmpl should be a string in the GLib file name encoding containing
+a sequence of six 'X' characters, as the parameter to g_mkstemp().
+However, unlike these functions, the template should only be a
+basename, no directory components are allowed. If template is
+%NULL, a default template is used.
+
+Note that in contrast to g_mkstemp() (and mkstemp()) @tmpl is not
+modified, and might thus be a read-only literal string.
+
+Upon success, and if @name_used is non-%NULL, the actual name used
+is returned in @name_used. This string should be freed with g_free()
+when not needed any longer. The returned name is in the GLib file
+name encoding.
+
+
+ A file handle (as from open()) to the file opened for
+ reading and writing. The file is opened in binary mode on platforms
+ where there is a difference. The file handle should be closed with
+ close(). In case of errors, -1 is returned and @error will be set.
+
+
+
+
+ Template for file name, as in
+ g_mkstemp(), basename only, or %NULL for a default template
+
+
+
+ location to store actual name used,
+ or %NULL
+
+
+
+
+
+ Reads the contents of the symbolic link @filename like the POSIX
+`readlink()` function.
+
+The returned string is in the encoding used for filenames. Use
+g_filename_to_utf8() to convert it to UTF-8.
+
+The returned string may also be a relative path. Use g_build_filename()
+to convert it to an absolute path:
+
+|[<!-- language="C" -->
+g_autoptr(GError) local_error = NULL;
+g_autofree gchar *link_target = g_file_read_link ("/etc/localtime", &local_error);
+
+if (local_error != NULL)
+ g_error ("Error reading link: %s", local_error->message);
+
+if (!g_path_is_absolute (link_target))
+ {
+ g_autofree gchar *absolute_link_target = g_build_filename ("/etc", link_target, NULL);
+ g_free (link_target);
+ link_target = g_steal_pointer (&absolute_link_target);
+ }
+]|
+
+
+ A newly-allocated string with
+ the contents of the symbolic link, or %NULL if an error occurred.
+
+
+
+
+ the symbolic link
+
+
+
+
+
+ Writes all of @contents to a file named @filename. This is a convenience
+wrapper around calling g_file_set_contents_full() with `flags` set to
+`G_FILE_SET_CONTENTS_CONSISTENT | G_FILE_SET_CONTENTS_ONLY_EXISTING` and
+`mode` set to `0666`.
+
+
+ %TRUE on success, %FALSE if an error occurred
+
+
+
+
+ name of a file to write @contents to, in the GLib file name
+ encoding
+
+
+
+ string to write to the file
+
+
+
+
+
+ length of @contents, or -1 if @contents is a nul-terminated string
+
+
+
+
+
+ Writes all of @contents to a file named @filename, with good error checking.
+If a file called @filename already exists it will be overwritten.
+
+@flags control the properties of the write operation: whether it’s atomic,
+and what the tradeoff is between returning quickly or being resilient to
+system crashes.
+
+As this function performs file I/O, it is recommended to not call it anywhere
+where blocking would cause problems, such as in the main loop of a graphical
+application. In particular, if @flags has any value other than
+%G_FILE_SET_CONTENTS_NONE then this function may call `fsync()`.
+
+If %G_FILE_SET_CONTENTS_CONSISTENT is set in @flags, the operation is atomic
+in the sense that it is first written to a temporary file which is then
+renamed to the final name.
+
+Notes:
+
+- On UNIX, if @filename already exists hard links to @filename will break.
+ Also since the file is recreated, existing permissions, access control
+ lists, metadata etc. may be lost. If @filename is a symbolic link,
+ the link itself will be replaced, not the linked file.
+
+- On UNIX, if @filename already exists and is non-empty, and if the system
+ supports it (via a journalling filesystem or equivalent), and if
+ %G_FILE_SET_CONTENTS_CONSISTENT is set in @flags, the `fsync()` call (or
+ equivalent) will be used to ensure atomic replacement: @filename
+ will contain either its old contents or @contents, even in the face of
+ system power loss, the disk being unsafely removed, etc.
+
+- On UNIX, if @filename does not already exist or is empty, there is a
+ possibility that system power loss etc. after calling this function will
+ leave @filename empty or full of NUL bytes, depending on the underlying
+ filesystem, unless %G_FILE_SET_CONTENTS_DURABLE and
+ %G_FILE_SET_CONTENTS_CONSISTENT are set in @flags.
+
+- On Windows renaming a file will not remove an existing file with the
+ new name, so on Windows there is a race condition between the existing
+ file being removed and the temporary file being renamed.
+
+- On Windows there is no way to remove a file that is open to some
+ process, or mapped into memory. Thus, this function will fail if
+ @filename already exists and is open.
+
+If the call was successful, it returns %TRUE. If the call was not successful,
+it returns %FALSE and sets @error. The error domain is %G_FILE_ERROR.
+Possible error codes are those in the #GFileError enumeration.
+
+Note that the name for the temporary file is constructed by appending up
+to 7 characters to @filename.
+
+If the file didn’t exist before and is created, it will be given the
+permissions from @mode. Otherwise, the permissions of the existing file may
+be changed to @mode depending on @flags, or they may remain unchanged.
+
+
+ %TRUE on success, %FALSE if an error occurred
+
+
+
+
+ name of a file to write @contents to, in the GLib file name
+ encoding
+
+
+
+ string to write to the file
+
+
+
+
+
+ length of @contents, or -1 if @contents is a nul-terminated string
+
+
+
+ flags controlling the safety vs speed of the operation
+
+
+
+ file mode, as passed to `open()`; typically this will be `0666`
+
+
+
+
+
+ Returns %TRUE if any of the tests in the bitfield @test are
+%TRUE. For example, `(G_FILE_TEST_EXISTS | G_FILE_TEST_IS_DIR)`
+will return %TRUE if the file exists; the check whether it's a
+directory doesn't matter since the existence test is %TRUE. With
+the current set of available tests, there's no point passing in
+more than one test at a time.
+
+Apart from %G_FILE_TEST_IS_SYMLINK all tests follow symbolic links,
+so for a symbolic link to a regular file g_file_test() will return
+%TRUE for both %G_FILE_TEST_IS_SYMLINK and %G_FILE_TEST_IS_REGULAR.
+
+Note, that for a dangling symbolic link g_file_test() will return
+%TRUE for %G_FILE_TEST_IS_SYMLINK and %FALSE for all other flags.
+
+You should never use g_file_test() to test whether it is safe
+to perform an operation, because there is always the possibility
+of the condition changing before you actually perform the operation,
+see [TOCTOU](https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use).
+
+For example, you might think you could use %G_FILE_TEST_IS_SYMLINK
+to know whether it is safe to write to a file without being
+tricked into writing into a different location. It doesn't work!
+
+|[<!-- language="C" -->
+ // DON'T DO THIS
+ if (!g_file_test (filename, G_FILE_TEST_IS_SYMLINK))
+ {
+ fd = g_open (filename, O_WRONLY);
+ // write to fd
+ }
+
+ // DO THIS INSTEAD
+ fd = g_open (filename, O_WRONLY | O_NOFOLLOW | O_CLOEXEC);
+ if (fd == -1)
+ {
+ // check error
+ if (errno == ELOOP)
+ // file is a symlink and can be ignored
+ else
+ // handle errors as before
+ }
+ else
+ {
+ // write to fd
+ }
+]|
+
+Another thing to note is that %G_FILE_TEST_EXISTS and
+%G_FILE_TEST_IS_EXECUTABLE are implemented using the access()
+system call. This usually doesn't matter, but if your program
+is setuid or setgid it means that these tests will give you
+the answer for the real user ID and group ID, rather than the
+effective user ID and group ID.
+
+On Windows, there are no symlinks, so testing for
+%G_FILE_TEST_IS_SYMLINK will always return %FALSE. Testing for
+%G_FILE_TEST_IS_EXECUTABLE will just check that the file exists and
+its name indicates that it is executable, checking for well-known
+extensions and those listed in the `PATHEXT` environment variable.
+
+
+ whether a test was %TRUE
+
+
+
+
+ a filename to test in the
+ GLib file name encoding
+
+
+
+ bitfield of #GFileTest flags
+
+
+
+
+
+ Returns the display basename for the particular filename, guaranteed
+to be valid UTF-8. The display name might not be identical to the filename,
+for instance there might be problems converting it to UTF-8, and some files
+can be translated in the display.
+
+If GLib cannot make sense of the encoding of @filename, as a last resort it
+replaces unknown characters with U+FFFD, the Unicode replacement character.
+You can search the result for the UTF-8 encoding of this character (which is
+"\357\277\275" in octal notation) to find out if @filename was in an invalid
+encoding.
+
+You must pass the whole absolute pathname to this functions so that
+translation of well known locations can be done.
+
+This function is preferred over g_filename_display_name() if you know the
+whole path, as it allows translation.
+
+
+ a newly allocated string containing
+ a rendition of the basename of the filename in valid UTF-8
+
+
+
+
+ an absolute pathname in the
+ GLib file name encoding
+
+
+
+
+
+ Converts a filename into a valid UTF-8 string. The conversion is
+not necessarily reversible, so you should keep the original around
+and use the return value of this function only for display purposes.
+Unlike g_filename_to_utf8(), the result is guaranteed to be non-%NULL
+even if the filename actually isn't in the GLib file name encoding.
+
+If GLib cannot make sense of the encoding of @filename, as a last resort it
+replaces unknown characters with U+FFFD, the Unicode replacement character.
+You can search the result for the UTF-8 encoding of this character (which is
+"\357\277\275" in octal notation) to find out if @filename was in an invalid
+encoding.
+
+If you know the whole pathname of the file you should use
+g_filename_display_basename(), since that allows location-based
+translation of filenames.
+
+
+ a newly allocated string containing
+ a rendition of the filename in valid UTF-8
+
+
+
+
+ a pathname hopefully in the
+ GLib file name encoding
+
+
+
+
+
+ Converts an escaped ASCII-encoded URI to a local filename in the
+encoding used for filenames.
+
+
+ a newly-allocated string holding
+ the resulting filename, or %NULL on an error.
+
+
+
+
+ a uri describing a filename (escaped, encoded in ASCII).
+
+
+
+ Location to store hostname for the URI.
+ If there is no hostname in the URI, %NULL will be
+ stored in this location.
+
+
+
+
+
+ Converts a string from UTF-8 to the encoding GLib uses for
+filenames. Note that on Windows GLib uses UTF-8 for filenames;
+on other platforms, this function indirectly depends on the
+[current locale][setlocale].
+
+The input string shall not contain nul characters even if the @len
+argument is positive. A nul character found inside the string will result
+in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. If the filename encoding is
+not UTF-8 and the conversion output contains a nul character, the error
+%G_CONVERT_ERROR_EMBEDDED_NUL is set and the function returns %NULL.
+
+
+
+ The converted string, or %NULL on an error.
+
+
+
+
+ a UTF-8 encoded string.
+
+
+
+ the length of the string, or -1 if the string is
+ nul-terminated.
+
+
+
+ location to store the number of bytes in
+ the input string that were successfully converted, or %NULL.
+ Even if the conversion was successful, this may be
+ less than @len if there were partial characters
+ at the end of the input. If the error
+ %G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
+ stored will be the byte offset after the last valid
+ input sequence.
+
+
+
+ the number of bytes stored in
+ the output buffer (not including the terminating nul).
+
+
+
+
+
+ Converts an absolute filename to an escaped ASCII-encoded URI, with the path
+component following Section 3.3. of RFC 2396.
+
+
+ a newly-allocated string holding the resulting
+ URI, or %NULL on an error.
+
+
+
+
+ an absolute filename specified in the GLib file
+ name encoding, which is the on-disk file name bytes on Unix, and UTF-8
+ on Windows
+
+
+
+ A UTF-8 encoded hostname, or %NULL for none.
+
+
+
+
+
+ Converts a string which is in the encoding used by GLib for
+filenames into a UTF-8 string. Note that on Windows GLib uses UTF-8
+for filenames; on other platforms, this function indirectly depends on
+the [current locale][setlocale].
+
+The input string shall not contain nul characters even if the @len
+argument is positive. A nul character found inside the string will result
+in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE.
+If the source encoding is not UTF-8 and the conversion output contains a
+nul character, the error %G_CONVERT_ERROR_EMBEDDED_NUL is set and the
+function returns %NULL. Use g_convert() to produce output that
+may contain embedded nul characters.
+
+
+ The converted string, or %NULL on an error.
+
+
+
+
+ a string in the encoding for filenames
+
+
+
+ the length of the string, or -1 if the string is
+ nul-terminated (Note that some encodings may allow nul
+ bytes to occur inside strings. In that case, using -1
+ for the @len parameter is unsafe)
+
+
+
+ location to store the number of bytes in the
+ input string that were successfully converted, or %NULL.
+ Even if the conversion was successful, this may be
+ less than @len if there were partial characters
+ at the end of the input. If the error
+ %G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
+ stored will be the byte offset after the last valid
+ input sequence.
+
+
+
+ the number of bytes stored in the output
+ buffer (not including the terminating nul).
+
+
+
+
+
+ Do not use these APIs unless you are porting a POSIX application to Windows.
+A more high-level file access API is provided as GIO — see the documentation
+for #GFile.
+
+There is a group of functions which wrap the common POSIX functions
+dealing with filenames (g_open(), g_rename(), g_mkdir(), g_stat(),
+g_unlink(), g_remove(), g_fopen(), g_freopen()). The point of these
+wrappers is to make it possible to handle file names with any Unicode
+characters in them on Windows without having to use ifdefs and the
+wide character API in the application code.
+
+On some Unix systems, these APIs may be defined as identical to their POSIX
+counterparts. For this reason, you must check for and include the necessary
+header files (such as `fcntl.h`) before using functions like g_creat(). You
+must also define the relevant feature test macros.
+
+The pathname argument should be in the GLib file name encoding.
+On POSIX this is the actual on-disk encoding which might correspond
+to the locale settings of the process (or the `G_FILENAME_ENCODING`
+environment variable), or not.
+
+On Windows the GLib file name encoding is UTF-8. Note that the
+Microsoft C library does not use UTF-8, but has separate APIs for
+current system code page and wide characters (UTF-16). The GLib
+wrappers call the wide character API if present (on modern Windows
+systems), otherwise convert to/from the system code page.
+
+Another group of functions allows to open and read directories
+in the GLib file name encoding. These are g_dir_open(),
+g_dir_read_name(), g_dir_rewind(), g_dir_close().
+
+
+ Locates the first executable named @program in the user's path, in the
+same way that execvp() would locate it. Returns an allocated string
+with the absolute path name, or %NULL if the program is not found in
+the path. If @program is already an absolute path, returns a copy of
+@program if @program exists and is executable, and %NULL otherwise.
+
+On Windows, if @program does not have a file type suffix, tries
+with the suffixes .exe, .cmd, .bat and .com, and the suffixes in
+the `PATHEXT` environment variable.
+
+On Windows, it looks for the file in the same way as CreateProcess()
+would. This means first in the directory where the executing
+program was loaded from, then in the current directory, then in the
+Windows 32-bit system directory, then in the Windows directory, and
+finally in the directories in the `PATH` environment variable. If
+the program is found, the return value contains the full name
+including the type suffix.
+
+
+ a newly-allocated
+ string with the absolute path, or %NULL
+
+
+
+
+ a program name in the GLib file name encoding
+
+
+
+
+
+ Formats a size (for example the size of a file) into a human readable
+string. Sizes are rounded to the nearest size prefix (kB, MB, GB)
+and are displayed rounded to the nearest tenth. E.g. the file size
+3292528 bytes will be converted into the string "3.2 MB". The returned string
+is UTF-8, and may use a non-breaking space to separate the number and units,
+to ensure they aren’t separated when line wrapped.
+
+The prefix units base is 1000 (i.e. 1 kB is 1000 bytes).
+
+This string should be freed with g_free() when not needed any longer.
+
+See g_format_size_full() for more options about how the size might be
+formatted.
+
+
+ a newly-allocated formatted string containing
+ a human readable file size
+
+
+
+
+ a size in bytes
+
+
+
+
+
+ Formats a size (for example the size of a file) into a human
+readable string. Sizes are rounded to the nearest size prefix
+(KB, MB, GB) and are displayed rounded to the nearest tenth.
+E.g. the file size 3292528 bytes will be converted into the
+string "3.1 MB".
+
+The prefix units base is 1024 (i.e. 1 KB is 1024 bytes).
+
+This string should be freed with g_free() when not needed any longer.
+ This function is broken due to its use of SI
+ suffixes to denote IEC units. Use g_format_size() instead.
+
+
+ a newly-allocated formatted string
+ containing a human readable file size
+
+
+
+
+ a size in bytes
+
+
+
+
+
+ Formats a size.
+
+This function is similar to g_format_size() but allows for flags
+that modify the output. See #GFormatSizeFlags.
+
+
+ a newly-allocated formatted string
+ containing a human readable file size
+
+
+
+
+ a size in bytes
+
+
+
+ #GFormatSizeFlags to modify the output
+
+
+
+
+
+ An implementation of the standard fprintf() function which supports
+positional parameters, as specified in the Single Unix Specification.
+
+`glib/gprintf.h` must be explicitly included in order to use this function.
+
+
+ the number of bytes printed.
+
+
+
+
+ the stream to write to.
+
+
+
+ a standard printf() format string, but notice
+ [string precision pitfalls][string-precision]
+
+
+
+ the arguments to insert in the output.
+
+
+
+
+
+ Frees the memory pointed to by @mem.
+
+If you know the allocated size of @mem, calling g_free_sized() may be faster,
+depending on the libc implementation in use.
+
+If @mem is %NULL it simply returns, so there is no need to check @mem
+against %NULL before calling this function.
+
+
+
+
+
+
+ the memory to free
+
+
+
+
+
+ Frees the memory pointed to by @mem, assuming it is has the given @size.
+
+If @mem is %NULL this is a no-op (and @size is ignored).
+
+It is an error if @size doesn’t match the size passed when @mem was
+allocated. @size is passed to this function to allow optimizations in the
+allocator. If you don’t know the allocation size, use g_free() instead.
+
+
+
+
+
+
+ the memory to free
+
+
+
+ size of @mem, in bytes
+
+
+
+
+
+ Gets a human-readable name for the application, as set by
+g_set_application_name(). This name should be localized if
+possible, and is intended for display to the user. Contrast with
+g_get_prgname(), which gets a non-localized name. If
+g_set_application_name() has not been called, returns the result of
+g_get_prgname() (which may be %NULL if g_set_prgname() has also not
+been called).
+
+
+ human-readable application
+ name. May return %NULL
+
+
+
+
+ Obtains the character set for the [current locale][setlocale]; you
+might use this character set as an argument to g_convert(), to convert
+from the current locale's encoding to some other encoding. (Frequently
+g_locale_to_utf8() and g_locale_from_utf8() are nice shortcuts, though.)
+
+On Windows the character set returned by this function is the
+so-called system default ANSI code-page. That is the character set
+used by the "narrow" versions of C library and Win32 functions that
+handle file names. It might be different from the character set
+used by the C library's current locale.
+
+On Linux, the character set is found by consulting nl_langinfo() if
+available. If not, the environment variables `LC_ALL`, `LC_CTYPE`, `LANG`
+and `CHARSET` are queried in order. nl_langinfo() returns the C locale if
+no locale has been loaded by setlocale().
+
+The return value is %TRUE if the locale's encoding is UTF-8, in that
+case you can perhaps avoid calling g_convert().
+
+The string returned in @charset is not allocated, and should not be
+freed.
+
+
+ %TRUE if the returned charset is UTF-8
+
+
+
+
+ return location for character set
+ name, or %NULL.
+
+
+
+
+
+ Gets the character set for the current locale.
+
+
+ a newly allocated string containing the name
+ of the character set. This string must be freed with g_free().
+
+
+
+
+ Obtains the character set used by the console attached to the process,
+which is suitable for printing output to the terminal.
+
+Usually this matches the result returned by g_get_charset(), but in
+environments where the locale's character set does not match the encoding
+of the console this function tries to guess a more suitable value instead.
+
+On Windows the character set returned by this function is the
+output code page used by the console associated with the calling process.
+If the codepage can't be determined (for example because there is no
+console attached) UTF-8 is assumed.
+
+The return value is %TRUE if the locale's encoding is UTF-8, in that
+case you can perhaps avoid calling g_convert().
+
+The string returned in @charset is not allocated, and should not be
+freed.
+
+
+ %TRUE if the returned charset is UTF-8
+
+
+
+
+ return location for character set
+ name, or %NULL.
+
+
+
+
+
+ Gets the current directory.
+
+The returned string should be freed when no longer needed.
+The encoding of the returned string is system defined.
+On Windows, it is always UTF-8.
+
+Since GLib 2.40, this function will return the value of the "PWD"
+environment variable if it is set and it happens to be the same as
+the current directory. This can make a difference in the case that
+the current directory is the target of a symbolic link.
+
+
+ the current directory
+
+
+
+
+ Equivalent to the UNIX gettimeofday() function, but portable.
+
+You may find g_get_real_time() to be more convenient.
+ #GTimeVal is not year-2038-safe. Use g_get_real_time()
+ instead.
+
+
+
+
+
+
+ #GTimeVal structure in which to store current time.
+
+
+
+
+
+ Gets the list of environment variables for the current process.
+
+The list is %NULL terminated and each item in the list is of the
+form 'NAME=VALUE'.
+
+This is equivalent to direct access to the 'environ' global variable,
+except portable.
+
+The return value is freshly allocated and it should be freed with
+g_strfreev() when it is no longer needed.
+
+
+
+ the list of environment variables
+
+
+
+
+
+
+ Determines the preferred character sets used for filenames.
+The first character set from the @charsets is the filename encoding, the
+subsequent character sets are used when trying to generate a displayable
+representation of a filename, see g_filename_display_name().
+
+On Unix, the character sets are determined by consulting the
+environment variables `G_FILENAME_ENCODING` and `G_BROKEN_FILENAMES`.
+On Windows, the character set used in the GLib API is always UTF-8
+and said environment variables have no effect.
+
+`G_FILENAME_ENCODING` may be set to a comma-separated list of
+character set names. The special token "\@locale" is taken
+to mean the character set for the [current locale][setlocale].
+If `G_FILENAME_ENCODING` is not set, but `G_BROKEN_FILENAMES` is,
+the character set of the current locale is taken as the filename
+encoding. If neither environment variable is set, UTF-8 is taken
+as the filename encoding, but the character set of the current locale
+is also put in the list of encodings.
+
+The returned @charsets belong to GLib and must not be freed.
+
+Note that on Unix, regardless of the locale character set or
+`G_FILENAME_ENCODING` value, the actual file names present
+on a system might be in any random encoding or just gibberish.
+
+
+ %TRUE if the filename encoding is UTF-8.
+
+
+
+
+
+ return location for the %NULL-terminated list of encoding names
+
+
+
+
+
+
+
+ Gets the current user's home directory.
+
+As with most UNIX tools, this function will return the value of the
+`HOME` environment variable if it is set to an existing absolute path
+name, falling back to the `passwd` file in the case that it is unset.
+
+If the path given in `HOME` is non-absolute, does not exist, or is
+not a directory, the result is undefined.
+
+Before version 2.36 this function would ignore the `HOME` environment
+variable, taking the value from the `passwd` database instead. This was
+changed to increase the compatibility of GLib with other programs (and
+the XDG basedir specification) and to increase testability of programs
+based on GLib (by making it easier to run them from test frameworks).
+
+If your program has a strong requirement for either the new or the
+old behaviour (and if you don't wish to increase your GLib
+dependency to ensure that the new behaviour is in effect) then you
+should either directly check the `HOME` environment variable yourself
+or unset it before calling any functions in GLib.
+
+
+ the current user's home directory
+
+
+
+
+ Return a name for the machine.
+
+The returned name is not necessarily a fully-qualified domain name,
+or even present in DNS or some other name service at all. It need
+not even be unique on your local network or site, but usually it
+is. Callers should not rely on the return value having any specific
+properties like uniqueness for security purposes. Even if the name
+of the machine is changed while an application is running, the
+return value from this function does not change. The returned
+string is owned by GLib and should not be modified or freed. If no
+name can be determined, a default fixed string "localhost" is
+returned.
+
+The encoding of the returned string is UTF-8.
+
+
+ the host name of the machine.
+
+
+
+
+ Computes a list of applicable locale names, which can be used to
+e.g. construct locale-dependent filenames or search paths. The returned
+list is sorted from most desirable to least desirable and always contains
+the default locale "C".
+
+For example, if LANGUAGE=de:en_US, then the returned list is
+"de", "en_US", "en", "C".
+
+This function consults the environment variables `LANGUAGE`, `LC_ALL`,
+`LC_MESSAGES` and `LANG` to find the list of locales specified by the
+user.
+
+
+ a %NULL-terminated array of strings owned by GLib
+ that must not be modified or freed.
+
+
+
+
+
+
+ Computes a list of applicable locale names with a locale category name,
+which can be used to construct the fallback locale-dependent filenames
+or search paths. The returned list is sorted from most desirable to
+least desirable and always contains the default locale "C".
+
+This function consults the environment variables `LANGUAGE`, `LC_ALL`,
+@category_name, and `LANG` to find the list of locales specified by the
+user.
+
+g_get_language_names() returns g_get_language_names_with_category("LC_MESSAGES").
+
+
+ a %NULL-terminated array of strings owned by
+ the thread g_get_language_names_with_category was called from.
+ It must not be modified or freed. It must be copied if planned to be used in another thread.
+
+
+
+
+
+
+ a locale category name
+
+
+
+
+
+ Returns a list of derived variants of @locale, which can be used to
+e.g. construct locale-dependent filenames or search paths. The returned
+list is sorted from most desirable to least desirable.
+This function handles territory, charset and extra locale modifiers. See
+[`setlocale(3)`](man:setlocale) for information about locales and their format.
+
+@locale itself is guaranteed to be returned in the output.
+
+For example, if @locale is `fr_BE`, then the returned list
+is `fr_BE`, `fr`. If @locale is `en_GB.UTF-8@euro`, then the returned list
+is `en_GB.UTF-8@euro`, `en_GB.UTF-8`, `en_GB@euro`, `en_GB`, `en.UTF-8@euro`,
+`en.UTF-8`, `en@euro`, `en`.
+
+If you need the list of variants for the current locale,
+use g_get_language_names().
+
+
+ a newly
+ allocated array of newly allocated strings with the locale variants. Free with
+ g_strfreev().
+
+
+
+
+
+
+ a locale identifier
+
+
+
+
+
+ Queries the system monotonic time.
+
+The monotonic clock will always increase and doesn't suffer
+discontinuities when the user (or NTP) changes the system time. It
+may or may not continue to tick during times where the machine is
+suspended.
+
+We try to use the clock that corresponds as closely as possible to
+the passage of time as measured by system calls such as poll() but it
+may not always be possible to do this.
+
+
+ the monotonic time, in microseconds
+
+
+
+
+ Determine the approximate number of threads that the system will
+schedule simultaneously for this process. This is intended to be
+used as a parameter to g_thread_pool_new() for CPU bound tasks and
+similar cases.
+
+
+ Number of schedulable threads, always greater than 0
+
+
+
+
+ Get information about the operating system.
+
+On Linux this comes from the `/etc/os-release` file. On other systems, it may
+come from a variety of sources. You can either use the standard key names
+like %G_OS_INFO_KEY_NAME or pass any UTF-8 string key name. For example,
+`/etc/os-release` provides a number of other less commonly used values that may
+be useful. No key is guaranteed to be provided, so the caller should always
+check if the result is %NULL.
+
+
+ The associated value for the requested key or %NULL if
+ this information is not provided.
+
+
+
+
+ a key for the OS info being requested, for example %G_OS_INFO_KEY_NAME.
+
+
+
+
+
+ Gets the name of the program. This name should not be localized,
+in contrast to g_get_application_name().
+
+If you are using #GApplication the program name is set in
+g_application_run(). In case of GDK or GTK+ it is set in
+gdk_init(), which is called by gtk_init() and the
+#GtkApplication::startup handler. The program name is found by
+taking the last component of @argv[0].
+
+
+ the name of the program,
+ or %NULL if it has not been set yet. The returned string belongs
+ to GLib and must not be modified or freed.
+
+
+
+
+ Gets the real name of the user. This usually comes from the user's
+entry in the `passwd` file. The encoding of the returned string is
+system-defined. (On Windows, it is, however, always UTF-8.) If the
+real user name cannot be determined, the string "Unknown" is
+returned.
+
+
+ the user's real name.
+
+
+
+
+ Queries the system wall-clock time.
+
+This call is functionally equivalent to g_get_current_time() except
+that the return value is often more convenient than dealing with a
+#GTimeVal.
+
+You should only use this call if you are actually interested in the real
+wall-clock time. g_get_monotonic_time() is probably more useful for
+measuring intervals.
+
+
+ the number of microseconds since January 1, 1970 UTC.
+
+
+
+
+ Returns an ordered list of base directories in which to access
+system-wide configuration information.
+
+On UNIX platforms this is determined using the mechanisms described
+in the
+[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
+In this case the list of directories retrieved will be `XDG_CONFIG_DIRS`.
+
+On Windows it follows XDG Base Directory Specification if `XDG_CONFIG_DIRS` is defined.
+If `XDG_CONFIG_DIRS` is undefined, the directory that contains application
+data for all users is used instead. A typical path is
+`C:\Documents and Settings\All Users\Application Data`.
+This folder is used for application data
+that is not user specific. For example, an application can store
+a spell-check dictionary, a database of clip art, or a log file in the
+FOLDERID_ProgramData folder. This information will not roam and is available
+to anyone using the computer.
+
+The return value is cached and modifying it at runtime is not supported, as
+it’s not thread-safe to modify environment variables at runtime.
+
+
+
+ a %NULL-terminated array of strings owned by GLib that must not be
+ modified or freed.
+
+
+
+
+
+
+ Returns an ordered list of base directories in which to access
+system-wide application data.
+
+On UNIX platforms this is determined using the mechanisms described
+in the
+[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec)
+In this case the list of directories retrieved will be `XDG_DATA_DIRS`.
+
+On Windows it follows XDG Base Directory Specification if `XDG_DATA_DIRS` is defined.
+If `XDG_DATA_DIRS` is undefined,
+the first elements in the list are the Application Data
+and Documents folders for All Users. (These can be determined only
+on Windows 2000 or later and are not present in the list on other
+Windows versions.) See documentation for FOLDERID_ProgramData and
+FOLDERID_PublicDocuments.
+
+Then follows the "share" subfolder in the installation folder for
+the package containing the DLL that calls this function, if it can
+be determined.
+
+Finally the list contains the "share" subfolder in the installation
+folder for GLib, and in the installation folder for the package the
+application's .exe file belongs to.
+
+The installation folders above are determined by looking up the
+folder where the module (DLL or EXE) in question is located. If the
+folder's name is "bin", its parent is used, otherwise the folder
+itself.
+
+Note that on Windows the returned list can vary depending on where
+this function is called.
+
+The return value is cached and modifying it at runtime is not supported, as
+it’s not thread-safe to modify environment variables at runtime.
+
+
+
+ a %NULL-terminated array of strings owned by GLib that must not be
+ modified or freed.
+
+
+
+
+
+
+ Gets the directory to use for temporary files.
+
+On UNIX, this is taken from the `TMPDIR` environment variable.
+If the variable is not set, `P_tmpdir` is
+used, as defined by the system C library. Failing that, a
+hard-coded default of "/tmp" is returned.
+
+On Windows, the `TEMP` environment variable is used, with the
+root directory of the Windows installation (eg: "C:\") used
+as a default.
+
+The encoding of the returned string is system-defined. On Windows,
+it is always UTF-8. The return value is never %NULL or the empty
+string.
+
+
+ the directory to use for temporary files.
+
+
+
+
+ Returns a base directory in which to store non-essential, cached
+data specific to particular user.
+
+On UNIX platforms this is determined using the mechanisms described
+in the
+[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
+In this case the directory retrieved will be `XDG_CACHE_HOME`.
+
+On Windows it follows XDG Base Directory Specification if `XDG_CACHE_HOME` is defined.
+If `XDG_CACHE_HOME` is undefined, the directory that serves as a common
+repository for temporary Internet files is used instead. A typical path is
+`C:\Documents and Settings\username\Local Settings\Temporary Internet Files`.
+See the [documentation for `FOLDERID_InternetCache`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid).
+
+The return value is cached and modifying it at runtime is not supported, as
+it’s not thread-safe to modify environment variables at runtime.
+
+
+ a string owned by GLib that
+ must not be modified or freed.
+
+
+
+
+ Returns a base directory in which to store user-specific application
+configuration information such as user preferences and settings.
+
+On UNIX platforms this is determined using the mechanisms described
+in the
+[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
+In this case the directory retrieved will be `XDG_CONFIG_HOME`.
+
+On Windows it follows XDG Base Directory Specification if `XDG_CONFIG_HOME` is defined.
+If `XDG_CONFIG_HOME` is undefined, the folder to use for local (as opposed
+to roaming) application data is used instead. See the
+[documentation for `FOLDERID_LocalAppData`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid).
+Note that in this case on Windows it will be the same
+as what g_get_user_data_dir() returns.
+
+The return value is cached and modifying it at runtime is not supported, as
+it’s not thread-safe to modify environment variables at runtime.
+
+
+ a string owned by GLib that
+ must not be modified or freed.
+
+
+
+
+ Returns a base directory in which to access application data such
+as icons that is customized for a particular user.
+
+On UNIX platforms this is determined using the mechanisms described
+in the
+[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
+In this case the directory retrieved will be `XDG_DATA_HOME`.
+
+On Windows it follows XDG Base Directory Specification if `XDG_DATA_HOME`
+is defined. If `XDG_DATA_HOME` is undefined, the folder to use for local (as
+opposed to roaming) application data is used instead. See the
+[documentation for `FOLDERID_LocalAppData`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid).
+Note that in this case on Windows it will be the same
+as what g_get_user_config_dir() returns.
+
+The return value is cached and modifying it at runtime is not supported, as
+it’s not thread-safe to modify environment variables at runtime.
+
+
+ a string owned by GLib that must
+ not be modified or freed.
+
+
+
+
+ Gets the user name of the current user. The encoding of the returned
+string is system-defined. On UNIX, it might be the preferred file name
+encoding, or something else, and there is no guarantee that it is even
+consistent on a machine. On Windows, it is always UTF-8.
+
+
+ the user name of the current user.
+
+
+
+
+ Returns a directory that is unique to the current user on the local
+system.
+
+This is determined using the mechanisms described
+in the
+[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
+This is the directory
+specified in the `XDG_RUNTIME_DIR` environment variable.
+In the case that this variable is not set, we return the value of
+g_get_user_cache_dir(), after verifying that it exists.
+
+The return value is cached and modifying it at runtime is not supported, as
+it’s not thread-safe to modify environment variables at runtime.
+
+
+ a string owned by GLib that must not be
+ modified or freed.
+
+
+
+
+ Returns the full path of a special directory using its logical id.
+
+On UNIX this is done using the XDG special user directories.
+For compatibility with existing practise, %G_USER_DIRECTORY_DESKTOP
+falls back to `$HOME/Desktop` when XDG special user directories have
+not been set up.
+
+Depending on the platform, the user might be able to change the path
+of the special directory without requiring the session to restart; GLib
+will not reflect any change once the special directories are loaded.
+
+
+ the path to the specified special
+ directory, or %NULL if the logical id was not found. The returned string is
+ owned by GLib and should not be modified or freed.
+
+
+
+
+ the logical id of special directory
+
+
+
+
+
+ Returns a base directory in which to store state files specific to
+particular user.
+
+On UNIX platforms this is determined using the mechanisms described
+in the
+[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
+In this case the directory retrieved will be `XDG_STATE_HOME`.
+
+On Windows it follows XDG Base Directory Specification if `XDG_STATE_HOME` is defined.
+If `XDG_STATE_HOME` is undefined, the folder to use for local (as opposed
+to roaming) application data is used instead. See the
+[documentation for `FOLDERID_LocalAppData`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid).
+Note that in this case on Windows it will be the same
+as what g_get_user_data_dir() returns.
+
+The return value is cached and modifying it at runtime is not supported, as
+it’s not thread-safe to modify environment variables at runtime.
+
+
+ a string owned by GLib that
+ must not be modified or freed.
+
+
+
+
+ Returns the value of an environment variable.
+
+On UNIX, the name and value are byte strings which might or might not
+be in some consistent character set and encoding. On Windows, they are
+in UTF-8.
+On Windows, in case the environment variable's value contains
+references to other environment variables, they are expanded.
+
+
+ the value of the environment variable, or %NULL if
+ the environment variable is not found. The returned string
+ may be overwritten by the next call to g_getenv(), g_setenv()
+ or g_unsetenv().
+
+
+
+
+ the environment variable to get
+
+
+
+
+
+ Functions for manipulating internet hostnames; in particular, for
+converting between Unicode and ASCII-encoded forms of
+Internationalized Domain Names (IDNs).
+
+The
+[Internationalized Domain Names for Applications (IDNA)](http://www.ietf.org/rfc/rfc3490.txt)
+standards allow for the use
+of Unicode domain names in applications, while providing
+backward-compatibility with the old ASCII-only DNS, by defining an
+ASCII-Compatible Encoding of any given Unicode name, which can be
+used with non-IDN-aware applications and protocols. (For example,
+"Παν語.org" maps to "xn--4wa8awb4637h.org".)
+
+
+ Most of GLib is intended to be portable; in contrast, this set of
+functions is designed for programs which explicitly target UNIX,
+or are using it to build higher level abstractions which would be
+conditionally compiled if the platform matches %G_OS_UNIX.
+
+To use these functions, you must explicitly include the
+"glib-unix.h" header.
+
+
+ This is a convenience function for using a #GHashTable as a set. It
+is equivalent to calling g_hash_table_replace() with @key as both the
+key and the value.
+
+In particular, this means that if @key already exists in the hash table, then
+the old copy of @key in the hash table is freed and @key replaces it in the
+table.
+
+When a hash table only ever contains keys that have themselves as the
+corresponding value it is able to be stored more efficiently. See
+the discussion in the section description.
+
+Starting from GLib 2.40, this function returns a boolean value to
+indicate whether the newly added value was already in the hash table
+or not.
+
+
+ %TRUE if the key did not exist yet
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+ a key to insert
+
+
+
+
+
+ Checks if @key is in @hash_table.
+
+
+ %TRUE if @key is in @hash_table, %FALSE otherwise.
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+ a key to check
+
+
+
+
+
+ Destroys all keys and values in the #GHashTable and decrements its
+reference count by 1. If keys and/or values are dynamically allocated,
+you should either free them first or create the #GHashTable with destroy
+notifiers using g_hash_table_new_full(). In the latter case the destroy
+functions you supplied will be called on all keys and values during the
+destruction phase.
+
+
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+
+
+ This function is deprecated and will be removed in the next major
+release of GLib. It does nothing.
+
+
+
+ a #GHashTable
+
+
+
+
+ Retrieves every key inside @hash_table, as a #GPtrArray.
+The returned data is valid until changes to the hash release those keys.
+
+This iterates over every entry in the hash table to build its return value.
+To iterate over the entries in a #GHashTable more efficiently, use a
+#GHashTableIter.
+
+You should always unref the returned array with g_ptr_array_unref().
+
+
+ a #GPtrArray containing each key from
+the table. Unref with with g_ptr_array_unref() when done.
+
+
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+
+
+ Retrieves every value inside @hash_table, as a #GPtrArray.
+The returned data is valid until changes to the hash release those values.
+
+This iterates over every entry in the hash table to build its return value.
+To iterate over the entries in a #GHashTable more efficiently, use a
+#GHashTableIter.
+
+You should always unref the returned array with g_ptr_array_unref().
+
+
+ a #GPtrArray containing each value from
+the table. Unref with with g_ptr_array_unref() when done.
+
+
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+
+
+ Inserts a new key and value into a #GHashTable.
+
+If the key already exists in the #GHashTable its current
+value is replaced with the new value. If you supplied a
+@value_destroy_func when creating the #GHashTable, the old
+value is freed using that function. If you supplied a
+@key_destroy_func when creating the #GHashTable, the passed
+key is freed using that function.
+
+Starting from GLib 2.40, this function returns a boolean value to
+indicate whether the newly added value was already in the hash table
+or not.
+
+
+ %TRUE if the key did not exist yet
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+ a key to insert
+
+
+
+ the value to associate with the key
+
+
+
+
+
+ Looks up a key in a #GHashTable. Note that this function cannot
+distinguish between a key that is not present and one which is present
+and has the value %NULL. If you need this distinction, use
+g_hash_table_lookup_extended().
+
+
+ the associated value, or %NULL if the key is not found
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+ the key to look up
+
+
+
+
+
+ Looks up a key in the #GHashTable, returning the original key and the
+associated value and a #gboolean which is %TRUE if the key was found. This
+is useful if you need to free the memory allocated for the original key,
+for example before calling g_hash_table_remove().
+
+You can actually pass %NULL for @lookup_key to test
+whether the %NULL key exists, provided the hash and equal functions
+of @hash_table are %NULL-safe.
+
+
+ %TRUE if the key was found in the #GHashTable
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+ the key to look up
+
+
+
+ return location for the original key
+
+
+
+ return location for the value associated
+with the key
+
+
+
+
+
+ Creates a new #GHashTable like g_hash_table_new_full() with a reference
+count of 1.
+
+It inherits the hash function, the key equal function, the key destroy function,
+as well as the value destroy function, from @other_hash_table.
+
+The returned hash table will be empty; it will not contain the keys
+or values from @other_hash_table.
+
+
+ a new #GHashTable
+
+
+
+
+
+
+
+ Another #GHashTable
+
+
+
+
+
+
+
+
+ Removes a key and its associated value from a #GHashTable.
+
+If the #GHashTable was created using g_hash_table_new_full(), the
+key and value are freed using the supplied destroy functions, otherwise
+you have to make sure that any dynamically allocated values are freed
+yourself.
+
+
+ %TRUE if the key was found and removed from the #GHashTable
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+ the key to remove
+
+
+
+
+
+ Removes all keys and their associated values from a #GHashTable.
+
+If the #GHashTable was created using g_hash_table_new_full(),
+the keys and values are freed using the supplied destroy functions,
+otherwise you have to make sure that any dynamically allocated
+values are freed yourself.
+
+
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+
+
+ Inserts a new key and value into a #GHashTable similar to
+g_hash_table_insert(). The difference is that if the key
+already exists in the #GHashTable, it gets replaced by the
+new key. If you supplied a @value_destroy_func when creating
+the #GHashTable, the old value is freed using that function.
+If you supplied a @key_destroy_func when creating the
+#GHashTable, the old key is freed using that function.
+
+Starting from GLib 2.40, this function returns a boolean value to
+indicate whether the newly added value was already in the hash table
+or not.
+
+
+ %TRUE if the key did not exist yet
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+ a key to insert
+
+
+
+ the value to associate with the key
+
+
+
+
+
+ Returns the number of elements contained in the #GHashTable.
+
+
+ the number of key/value pairs in the #GHashTable.
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+
+
+ Removes a key and its associated value from a #GHashTable without
+calling the key and value destroy functions.
+
+
+ %TRUE if the key was found and removed from the #GHashTable
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+ the key to remove
+
+
+
+
+
+ Removes all keys and their associated values from a #GHashTable
+without calling the key and value destroy functions.
+
+
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+
+
+ Removes all keys and their associated values from a #GHashTable
+without calling the key destroy functions, returning the keys
+as a #GPtrArray with the free func set to the @hash_table key
+destroy function.
+
+
+ a #GPtrArray containing each key of
+the table. Unref with with g_ptr_array_unref() when done.
+
+
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+
+
+ Removes all keys and their associated values from a #GHashTable
+without calling the value destroy functions, returning the values
+as a #GPtrArray with the free func set to the @hash_table value
+destroy function.
+
+
+ a #GPtrArray containing each value of
+the table. Unref with with g_ptr_array_unref() when done.
+
+
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+
+
+ Looks up a key in the #GHashTable, stealing the original key and the
+associated value and returning %TRUE if the key was found. If the key was
+not found, %FALSE is returned.
+
+If found, the stolen key and value are removed from the hash table without
+calling the key and value destroy functions, and ownership is transferred to
+the caller of this method, as with g_hash_table_steal(). That is the case
+regardless whether @stolen_key or @stolen_value output parameters are
+requested.
+
+You can pass %NULL for @lookup_key, provided the hash and equal functions
+of @hash_table are %NULL-safe.
+
+The dictionary implementation optimizes for having all values identical to
+their keys, for example by using g_hash_table_add(). When stealing both the
+key and the value from such a dictionary, the value will be %NULL.
+
+
+ %TRUE if the key was found in the #GHashTable
+
+
+
+
+ a #GHashTable
+
+
+
+
+
+
+ the key to look up
+
+
+
+ return location for the
+ original key
+
+
+
+ return location
+ for the value associated with the key
+
+
+
+
+
+ This function is deprecated and will be removed in the next major
+release of GLib. It does nothing.
+
+
+
+ a #GHashTable
+
+
+
+
+ Atomically decrements the reference count of @hash_table by one.
+If the reference count drops to 0, all keys and values will be
+destroyed, and all memory allocated by the hash table is released.
+This function is MT-safe and may be called from any thread.
+
+
+
+
+
+
+ a valid #GHashTable
+
+
+
+
+
+
+
+
+ A #GHashTable provides associations between keys and values which is
+optimized so that given a key, the associated value can be found,
+inserted or removed in amortized O(1). All operations going through
+each element take O(n) time (list all keys/values, table resize, etc.).
+
+Note that neither keys nor values are copied when inserted into the
+#GHashTable, so they must exist for the lifetime of the #GHashTable.
+This means that the use of static strings is OK, but temporary
+strings (i.e. those created in buffers and those returned by GTK
+widgets) should be copied with g_strdup() before being inserted.
+
+If keys or values are dynamically allocated, you must be careful to
+ensure that they are freed when they are removed from the
+#GHashTable, and also when they are overwritten by new insertions
+into the #GHashTable. It is also not advisable to mix static strings
+and dynamically-allocated strings in a #GHashTable, because it then
+becomes difficult to determine whether the string should be freed.
+
+To create a #GHashTable, use g_hash_table_new().
+
+To insert a key and value into a #GHashTable, use
+g_hash_table_insert().
+
+To look up a value corresponding to a given key, use
+g_hash_table_lookup() and g_hash_table_lookup_extended().
+
+g_hash_table_lookup_extended() can also be used to simply
+check if a key is present in the hash table.
+
+To remove a key and value, use g_hash_table_remove().
+
+To call a function for each key and value pair use
+g_hash_table_foreach() or use an iterator to iterate over the
+key/value pairs in the hash table, see #GHashTableIter. The iteration order
+of a hash table is not defined, and you must not rely on iterating over
+keys/values in the same order as they were inserted.
+
+To destroy a #GHashTable use g_hash_table_destroy().
+
+A common use-case for hash tables is to store information about a
+set of keys, without associating any particular value with each
+key. GHashTable optimizes one way of doing so: If you store only
+key-value pairs where key == value, then GHashTable does not
+allocate memory to store the values, which can be a considerable
+space saving, if your set is large. The functions
+g_hash_table_add() and g_hash_table_contains() are designed to be
+used when using #GHashTable this way.
+
+#GHashTable is not designed to be statically initialised with keys and
+values known at compile time. To build a static hash table, use a tool such
+as [gperf](https://www.gnu.org/software/gperf/).
+
+
+ HMACs should be used when producing a cookie or hash based on data
+and a key. Simple mechanisms for using SHA1 and other algorithms to
+digest a key and data together are vulnerable to various security
+issues.
+[HMAC](http://en.wikipedia.org/wiki/HMAC)
+uses algorithms like SHA1 in a secure way to produce a digest of a
+key and data.
+
+Both the key and data are arbitrary byte arrays of bytes or characters.
+
+Support for HMAC Digests has been added in GLib 2.30, and support for SHA-512
+in GLib 2.42. Support for SHA-384 was added in GLib 2.52.
+
+
+ Appends a #GHook onto the end of a #GHookList.
+
+
+
+ a #GHookList
+
+
+ the #GHook to add to the end of @hook_list
+
+
+
+
+ Destroys a #GHook, given its ID.
+
+
+ %TRUE if the #GHook was found in the #GHookList and destroyed
+
+
+
+
+ a #GHookList
+
+
+
+ a hook ID
+
+
+
+
+
+ Removes one #GHook from a #GHookList, marking it
+inactive and calling g_hook_unref() on it.
+
+
+
+
+
+
+ a #GHookList
+
+
+
+ the #GHook to remove
+
+
+
+
+
+ Calls the #GHookList @finalize_hook function if it exists,
+and frees the memory allocated for the #GHook.
+
+
+
+
+
+
+ a #GHookList
+
+
+
+ the #GHook to free
+
+
+
+
+
+ Inserts a #GHook into a #GHookList, before a given #GHook.
+
+
+
+
+
+
+ a #GHookList
+
+
+
+ the #GHook to insert the new #GHook before
+
+
+
+ the #GHook to insert
+
+
+
+
+
+ Prepends a #GHook on the start of a #GHookList.
+
+
+
+
+
+
+ a #GHookList
+
+
+
+ the #GHook to add to the start of @hook_list
+
+
+
+
+
+ Decrements the reference count of a #GHook.
+If the reference count falls to 0, the #GHook is removed
+from the #GHookList and g_hook_free() is called to free it.
+
+
+
+
+
+
+ a #GHookList
+
+
+
+ the #GHook to unref
+
+
+
+
+
+ The #GHookList, #GHook and their related functions provide support for
+lists of hook functions. Functions can be added and removed from the lists,
+and the list of hook functions can be invoked.
+
+
+ Tests if @hostname contains segments with an ASCII-compatible
+encoding of an Internationalized Domain Name. If this returns
+%TRUE, you should decode the hostname with g_hostname_to_unicode()
+before displaying it to the user.
+
+Note that a hostname might contain a mix of encoded and unencoded
+segments, and so it is possible for g_hostname_is_non_ascii() and
+g_hostname_is_ascii_encoded() to both return %TRUE for a name.
+
+
+ %TRUE if @hostname contains any ASCII-encoded
+segments.
+
+
+
+
+ a hostname
+
+
+
+
+
+ Tests if @hostname is the string form of an IPv4 or IPv6 address.
+(Eg, "192.168.0.1".)
+
+Since 2.66, IPv6 addresses with a zone-id are accepted (RFC6874).
+
+
+ %TRUE if @hostname is an IP address
+
+
+
+
+ a hostname (or IP address in string form)
+
+
+
+
+
+ Tests if @hostname contains Unicode characters. If this returns
+%TRUE, you need to encode the hostname with g_hostname_to_ascii()
+before using it in non-IDN-aware contexts.
+
+Note that a hostname might contain a mix of encoded and unencoded
+segments, and so it is possible for g_hostname_is_non_ascii() and
+g_hostname_is_ascii_encoded() to both return %TRUE for a name.
+
+
+ %TRUE if @hostname contains any non-ASCII characters
+
+
+
+
+ a hostname
+
+
+
+
+
+ Converts @hostname to its canonical ASCII form; an ASCII-only
+string containing no uppercase letters and not ending with a
+trailing dot.
+
+
+ an ASCII hostname, which must be freed,
+ or %NULL if @hostname is in some way invalid.
+
+
+
+
+ a valid UTF-8 or ASCII hostname
+
+
+
+
+
+ Converts @hostname to its canonical presentation form; a UTF-8
+string in Unicode normalization form C, containing no uppercase
+letters, no forbidden characters, and no ASCII-encoded segments,
+and not ending with a trailing dot.
+
+Of course if @hostname is not an internationalized hostname, then
+the canonical presentation form will be entirely ASCII.
+
+
+ a UTF-8 hostname, which must be freed,
+ or %NULL if @hostname is in some way invalid.
+
+
+
+
+ a valid UTF-8 or ASCII hostname
+
+
+
+
+
+ Converts a 32-bit integer value from host to network byte order.
+
+
+
+ a 32-bit integer value in host byte order
+
+
+
+
+ Converts a 16-bit integer value from host to network byte order.
+
+
+
+ a 16-bit integer value in host byte order
+
+
+
+
+ GLib doesn't force any particular localization method upon its users.
+But since GLib itself is localized using the gettext() mechanism, it seems
+natural to offer the de-facto standard gettext() support macros in an
+easy-to-use form.
+
+In order to use these macros in an application, you must include
+`<glib/gi18n.h>`. For use in a library, you must include
+`<glib/gi18n-lib.h>`
+after defining the %GETTEXT_PACKAGE macro suitably for your library:
+|[<!-- language="C" -->
+#define GETTEXT_PACKAGE "gtk20"
+#include <glib/gi18n-lib.h>
+]|
+For an application, note that you also have to call bindtextdomain(),
+bind_textdomain_codeset(), textdomain() and setlocale() early on in your
+main() to make gettext() work. For example:
+|[<!-- language="C" -->
+#include <glib/gi18n.h>
+#include <locale.h>
+
+int
+main (int argc, char **argv)
+{
+ setlocale (LC_ALL, "");
+ bindtextdomain (GETTEXT_PACKAGE, DATADIR "/locale");
+ bind_textdomain_codeset (GETTEXT_PACKAGE, "UTF-8");
+ textdomain (GETTEXT_PACKAGE);
+
+ // Rest of your application.
+}
+]|
+where `DATADIR` is as typically provided by automake or Meson.
+
+For a library, you only have to call bindtextdomain() and
+bind_textdomain_codeset() in your initialization function. If your library
+doesn't have an initialization function, you can call the functions before
+the first translated message.
+
+The
+[gettext manual](http://www.gnu.org/software/gettext/manual/gettext.html#Maintainers)
+covers details of how to integrate gettext into a project’s build system and
+workflow.
+
+
+ Same as the standard UNIX routine iconv(), but
+may be implemented via libiconv on UNIX flavors that lack
+a native implementation.
+
+GLib provides g_convert() and g_locale_to_utf8() which are likely
+more convenient than the raw iconv wrappers.
+
+Note that the behaviour of iconv() for characters which are valid in the
+input character set, but which have no representation in the output character
+set, is implementation defined. This function may return success (with a
+positive number of non-reversible conversions as replacement characters were
+used), or it may return -1 and set an error such as %EILSEQ, in such a
+situation.
+
+
+ count of non-reversible conversions, or -1 on error
+
+
+
+
+ conversion descriptor from g_iconv_open()
+
+
+
+ bytes to convert
+
+
+
+ inout parameter, bytes remaining to convert in @inbuf
+
+
+
+ converted output bytes
+
+
+
+ inout parameter, bytes available to fill in @outbuf
+
+
+
+
+
+ Same as the standard UNIX routine iconv_open(), but
+may be implemented via libiconv on UNIX flavors that lack
+a native implementation.
+
+GLib provides g_convert() and g_locale_to_utf8() which are likely
+more convenient than the raw iconv wrappers.
+
+
+ a "conversion descriptor", or (GIConv)-1 if
+ opening the converter failed.
+
+
+
+
+ destination codeset
+
+
+
+ source codeset
+
+
+
+
+
+ Adds a function to be called whenever there are no higher priority
+events pending to the default main loop. The function is given the
+default idle priority, %G_PRIORITY_DEFAULT_IDLE. If the function
+returns %FALSE it is automatically removed from the list of event
+sources and will not be called again.
+
+See [memory management of sources][mainloop-memory-management] for details
+on how to handle the return value and memory management of @data.
+
+This internally creates a main loop source using g_idle_source_new()
+and attaches it to the global #GMainContext using g_source_attach(), so
+the callback will be invoked in whichever thread is running that main
+context. You can do these steps manually if you need greater control or to
+use a custom main context.
+
+
+ the ID (greater than 0) of the event source.
+
+
+
+
+ function to call
+
+
+
+ data to pass to @function.
+
+
+
+
+
+ Adds a function to be called whenever there are no higher priority
+events pending.
+
+If the function returns %G_SOURCE_REMOVE or %FALSE it is automatically
+removed from the list of event sources and will not be called again.
+
+See [memory management of sources][mainloop-memory-management] for details
+on how to handle the return value and memory management of @data.
+
+This internally creates a main loop source using g_idle_source_new()
+and attaches it to the global #GMainContext using g_source_attach(), so
+the callback will be invoked in whichever thread is running that main
+context. You can do these steps manually if you need greater control or to
+use a custom main context.
+
+
+ the ID (greater than 0) of the event source.
+
+
+
+
+ the priority of the idle source. Typically this will be in the
+ range between %G_PRIORITY_DEFAULT_IDLE and %G_PRIORITY_HIGH_IDLE.
+
+
+
+ function to call
+
+
+
+ data to pass to @function
+
+
+
+ function to call when the idle is removed, or %NULL
+
+
+
+
+
+ Adds a function to be called whenever there are no higher priority
+events pending to the default main loop. The function is given the
+default idle priority, %G_PRIORITY_DEFAULT_IDLE.
+
+The function will only be called once and then the source will be
+automatically removed from the main context.
+
+This function otherwise behaves like g_idle_add().
+
+
+ the ID (greater than 0) of the event source
+
+
+
+
+ function to call
+
+
+
+ data to pass to @function
+
+
+
+
+
+ Removes the idle function with the given data.
+
+
+ %TRUE if an idle source was found and removed.
+
+
+
+
+ the data for the idle source's callback.
+
+
+
+
+
+ Creates a new idle source.
+
+The source will not initially be associated with any #GMainContext
+and must be added to one with g_source_attach() before it will be
+executed. Note that the default priority for idle sources is
+%G_PRIORITY_DEFAULT_IDLE, as compared to other sources which
+have a default priority of %G_PRIORITY_DEFAULT.
+
+
+ the newly-created idle source
+
+
+
+
+ A convenience function/macro to log an informational message. Seldom used.
+
+If g_log_default_handler() is used as the log handler function, a new-line
+character will automatically be appended to @..., and need not be entered
+manually.
+
+Such messages are suppressed by the g_log_default_handler() and
+g_log_writer_default() unless the `G_MESSAGES_DEBUG` environment variable is
+set appropriately.
+
+If structured logging is enabled, this will use g_log_structured();
+otherwise it will use g_log(). See
+[Using Structured Logging][using-structured-logging].
+
+
+
+ format string, followed by parameters to insert
+ into the format string (as with printf())
+
+
+
+
+ Compares the two #gint64 values being pointed to and returns
+%TRUE if they are equal.
+It can be passed to g_hash_table_new() as the @key_equal_func
+parameter, when using non-%NULL pointers to 64-bit integers as keys in a
+#GHashTable.
+
+
+ %TRUE if the two keys match.
+
+
+
+
+ a pointer to a #gint64 key
+
+
+
+ a pointer to a #gint64 key to compare with @v1
+
+
+
+
+
+ Converts a pointer to a #gint64 to a hash value.
+
+It can be passed to g_hash_table_new() as the @hash_func parameter,
+when using non-%NULL pointers to 64-bit integer values as keys in a
+#GHashTable.
+
+
+ a hash value corresponding to the key.
+
+
+
+
+ a pointer to a #gint64 key
+
+
+
+
+
+ Compares the two #gint values being pointed to and returns
+%TRUE if they are equal.
+It can be passed to g_hash_table_new() as the @key_equal_func
+parameter, when using non-%NULL pointers to integers as keys in a
+#GHashTable.
+
+Note that this function acts on pointers to #gint, not on #gint
+directly: if your hash table's keys are of the form
+`GINT_TO_POINTER (n)`, use g_direct_equal() instead.
+
+
+ %TRUE if the two keys match.
+
+
+
+
+ a pointer to a #gint key
+
+
+
+ a pointer to a #gint key to compare with @v1
+
+
+
+
+
+ Converts a pointer to a #gint to a hash value.
+It can be passed to g_hash_table_new() as the @hash_func parameter,
+when using non-%NULL pointers to integer values as keys in a #GHashTable.
+
+Note that this function acts on pointers to #gint, not on #gint
+directly: if your hash table's keys are of the form
+`GINT_TO_POINTER (n)`, use g_direct_hash() instead.
+
+
+ a hash value corresponding to the key.
+
+
+
+
+ a pointer to a #gint key
+
+
+
+
+
+ Returns a canonical representation for @string. Interned strings
+can be compared for equality by comparing the pointers, instead of
+using strcmp(). g_intern_static_string() does not copy the string,
+therefore @string must not be freed or modified.
+
+This function must not be used before library constructors have finished
+running. In particular, this means it cannot be used to initialize global
+variables in C++.
+
+
+ a canonical representation for the string
+
+
+
+
+ a static string
+
+
+
+
+
+ Returns a canonical representation for @string. Interned strings
+can be compared for equality by comparing the pointers, instead of
+using strcmp().
+
+This function must not be used before library constructors have finished
+running. In particular, this means it cannot be used to initialize global
+variables in C++.
+
+
+ a canonical representation for the string
+
+
+
+
+ a string
+
+
+
+
+
+ Adds the #GIOChannel into the default main loop context
+with the default priority.
+
+
+ the event source id
+
+
+
+
+ a #GIOChannel
+
+
+
+ the condition to watch for
+
+
+
+ the function to call when the condition is satisfied
+
+
+
+ user data to pass to @func
+
+
+
+
+
+ Adds the #GIOChannel into the default main loop context
+with the given priority.
+
+This internally creates a main loop source using g_io_create_watch()
+and attaches it to the main loop context with g_source_attach().
+You can do these steps manually if you need greater control.
+
+
+ the event source id
+
+
+
+
+ a #GIOChannel
+
+
+
+ the priority of the #GIOChannel source
+
+
+
+ the condition to watch for
+
+
+
+ the function to call when the condition is satisfied
+
+
+
+ user data to pass to @func
+
+
+
+ the function to call when the source is removed
+
+
+
+
+
+ Converts an `errno` error number to a #GIOChannelError.
+
+
+ a #GIOChannelError error number, e.g.
+ %G_IO_CHANNEL_ERROR_INVAL.
+
+
+
+
+ an `errno` error number, e.g. `EINVAL`
+
+
+
+
+
+
+
+
+
+
+ Creates a #GSource that's dispatched when @condition is met for the
+given @channel. For example, if condition is %G_IO_IN, the source will
+be dispatched when there's data available for reading.
+
+The callback function invoked by the #GSource should be added with
+g_source_set_callback(), but it has type #GIOFunc (not #GSourceFunc).
+
+g_io_add_watch() is a simpler interface to this same functionality, for
+the case where you want to add the source to the default main loop context
+at the default priority.
+
+On Windows, polling a #GSource created to watch a channel for a socket
+puts the socket in non-blocking mode. This is a side-effect of the
+implementation and unavoidable.
+
+
+ a new #GSource
+
+
+
+
+ a #GIOChannel to watch
+
+
+
+ conditions to watch for
+
+
+
+
+
+ The #GIOChannel data type aims to provide a portable method for
+using file descriptors, pipes, and sockets, and integrating them
+into the [main event loop][glib-The-Main-Event-Loop]. Currently,
+full support is available on UNIX platforms, support for Windows
+is only partially complete.
+
+To create a new #GIOChannel on UNIX systems use
+g_io_channel_unix_new(). This works for plain file descriptors,
+pipes and sockets. Alternatively, a channel can be created for a
+file in a system independent manner using g_io_channel_new_file().
+
+Once a #GIOChannel has been created, it can be used in a generic
+manner with the functions g_io_channel_read_chars(),
+g_io_channel_write_chars(), g_io_channel_seek_position(), and
+g_io_channel_shutdown().
+
+To add a #GIOChannel to the [main event loop][glib-The-Main-Event-Loop],
+use g_io_add_watch() or g_io_add_watch_full(). Here you specify which
+events you are interested in on the #GIOChannel, and provide a
+function to be called whenever these events occur.
+
+#GIOChannel instances are created with an initial reference count of 1.
+g_io_channel_ref() and g_io_channel_unref() can be used to
+increment or decrement the reference count respectively. When the
+reference count falls to 0, the #GIOChannel is freed. (Though it
+isn't closed automatically, unless it was created using
+g_io_channel_new_file().) Using g_io_add_watch() or
+g_io_add_watch_full() increments a channel's reference count.
+
+The new functions g_io_channel_read_chars(),
+g_io_channel_read_line(), g_io_channel_read_line_string(),
+g_io_channel_read_to_end(), g_io_channel_write_chars(),
+g_io_channel_seek_position(), and g_io_channel_flush() should not be
+mixed with the deprecated functions g_io_channel_read(),
+g_io_channel_write(), and g_io_channel_seek() on the same channel.
+
+
+
+
+
+
+
+ #GKeyFile lets you parse, edit or create files containing groups of
+key-value pairs, which we call "key files" for lack of a better name.
+Several freedesktop.org specifications use key files now, e.g the
+[Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec)
+and the
+[Icon Theme Specification](http://freedesktop.org/Standards/icon-theme-spec).
+
+The syntax of key files is described in detail in the
+[Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec),
+here is a quick summary: Key files
+consists of groups of key-value pairs, interspersed with comments.
+
+|[
+# this is just an example
+# there can be comments before the first group
+
+[First Group]
+
+Name=Key File Example\tthis value shows\nescaping
+
+# localized strings are stored in multiple key-value pairs
+Welcome=Hello
+Welcome[de]=Hallo
+Welcome[fr_FR]=Bonjour
+Welcome[it]=Ciao
+Welcome[be@latin]=Hello
+
+[Another Group]
+
+Numbers=2;20;-200;0
+
+Booleans=true;false;true;true
+]|
+
+Lines beginning with a '#' and blank lines are considered comments.
+
+Groups are started by a header line containing the group name enclosed
+in '[' and ']', and ended implicitly by the start of the next group or
+the end of the file. Each key-value pair must be contained in a group.
+
+Key-value pairs generally have the form `key=value`, with the
+exception of localized strings, which have the form
+`key[locale]=value`, with a locale identifier of the
+form `lang_COUNTRY@MODIFIER` where `COUNTRY` and `MODIFIER`
+are optional.
+Space before and after the '=' character are ignored. Newline, tab,
+carriage return and backslash characters in value are escaped as \n,
+\t, \r, and \\\\, respectively. To preserve leading spaces in values,
+these can also be escaped as \s.
+
+Key files can store strings (possibly with localized variants), integers,
+booleans and lists of these. Lists are separated by a separator character,
+typically ';' or ','. To use the list separator character in a value in
+a list, it has to be escaped by prefixing it with a backslash.
+
+This syntax is obviously inspired by the .ini files commonly met
+on Windows, but there are some important differences:
+
+- .ini files use the ';' character to begin comments,
+ key files use the '#' character.
+
+- Key files do not allow for ungrouped keys meaning only
+ comments can precede the first group.
+
+- Key files are always encoded in UTF-8.
+
+- Key and Group names are case-sensitive. For example, a group called
+ [GROUP] is a different from [group].
+
+- .ini files don't have a strongly typed boolean entry type,
+ they only have GetProfileInt(). In key files, only
+ true and false (in lower case) are allowed.
+
+Note that in contrast to the
+[Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec),
+groups in key files may contain the same
+key multiple times; the last entry wins. Key files may also contain
+multiple groups with the same name; they are merged together.
+Another difference is that keys and group names in key files are not
+restricted to ASCII characters.
+
+Here is an example of loading a key file and reading a value:
+|[<!-- language="C" -->
+g_autoptr(GError) error = NULL;
+g_autoptr(GKeyFile) key_file = g_key_file_new ();
+
+if (!g_key_file_load_from_file (key_file, "key-file.ini", flags, &error))
+ {
+ if (!g_error_matches (error, G_FILE_ERROR, G_FILE_ERROR_NOENT))
+ g_warning ("Error loading key file: %s", error->message);
+ return;
+ }
+
+g_autofree gchar *val = g_key_file_get_string (key_file, "Group Name", "SomeKey", &error);
+if (val == NULL &&
+ !g_error_matches (error, G_KEY_FILE_ERROR, G_KEY_FILE_ERROR_KEY_NOT_FOUND))
+ {
+ g_warning ("Error finding key in key file: %s", error->message);
+ return;
+ }
+else if (val == NULL)
+ {
+ // Fall back to a default value.
+ val = g_strdup ("default-value");
+ }
+]|
+
+Here is an example of creating and saving a key file:
+|[<!-- language="C" -->
+g_autoptr(GKeyFile) key_file = g_key_file_new ();
+const gchar *val = …;
+g_autoptr(GError) error = NULL;
+
+g_key_file_set_string (key_file, "Group Name", "SomeKey", val);
+
+// Save as a file.
+if (!g_key_file_save_to_file (key_file, "key-file.ini", &error))
+ {
+ g_warning ("Error saving key file: %s", error->message);
+ return;
+ }
+
+// Or store to a GBytes for use elsewhere.
+gsize data_len;
+g_autofree guint8 *data = (guint8 *) g_key_file_to_data (key_file, &data_len, &error);
+if (data == NULL)
+ {
+ g_warning ("Error saving key file: %s", error->message);
+ return;
+ }
+g_autoptr(GBytes) bytes = g_bytes_new_take (g_steal_pointer (&data), data_len);
+]|
+
+
+ The #GList structure and its associated functions provide a standard
+doubly-linked list data structure. The benefit of this data-structure
+is to provide insertion/deletion operations in O(1) complexity where
+access/search operations are in O(n). The benefit of #GList over
+#GSList (singly linked list) is that the worst case on access/search
+operations is divided by two which comes at a cost in space as we need
+to retain two pointers in place of one.
+
+Each element in the list contains a piece of data, together with
+pointers which link to the previous and next elements in the list.
+Using these pointers it is possible to move through the list in both
+directions (unlike the singly-linked [GSList][glib-Singly-Linked-Lists],
+which only allows movement through the list in the forward direction).
+
+The double linked list does not keep track of the number of items
+and does not keep track of both the start and end of the list. If
+you want fast access to both the start and the end of the list,
+and/or the number of items in the list, use a
+[GQueue][glib-Double-ended-Queues] instead.
+
+The data contained in each element can be either integer values, by
+using one of the [Type Conversion Macros][glib-Type-Conversion-Macros],
+or simply pointers to any type of data.
+
+List elements are allocated from the [slice allocator][glib-Memory-Slices],
+which is more efficient than allocating elements individually.
+
+Note that most of the #GList functions expect to be passed a pointer
+to the first element in the list. The functions which insert
+elements return the new start of the list, which may have changed.
+
+There is no function to create a #GList. %NULL is considered to be
+a valid, empty list so you simply set a #GList* to %NULL to initialize
+it.
+
+To add elements, use g_list_append(), g_list_prepend(),
+g_list_insert() and g_list_insert_sorted().
+
+To visit all elements in the list, use a loop over the list:
+|[<!-- language="C" -->
+GList *l;
+for (l = list; l != NULL; l = l->next)
+ {
+ // do something with l->data
+ }
+]|
+
+To call a function for each element in the list, use g_list_foreach().
+
+To loop over the list and modify it (e.g. remove a certain element)
+a while loop is more appropriate, for example:
+|[<!-- language="C" -->
+GList *l = list;
+while (l != NULL)
+ {
+ GList *next = l->next;
+ if (should_be_removed (l))
+ {
+ // possibly free l->data
+ list = g_list_delete_link (list, l);
+ }
+ l = next;
+ }
+]|
+
+To remove elements, use g_list_remove().
+
+To navigate in a list, use g_list_first(), g_list_last(),
+g_list_next(), g_list_previous().
+
+To find elements in the list use g_list_nth(), g_list_nth_data(),
+g_list_find() and g_list_find_custom().
+
+To find the index of an element use g_list_position() and
+g_list_index().
+
+To free the entire list, use g_list_free() or g_list_free_full().
+
+
+ The #GSList structure and its associated functions provide a
+standard singly-linked list data structure. The benefit of this
+data-structure is to provide insertion/deletion operations in O(1)
+complexity where access/search operations are in O(n). The benefit
+of #GSList over #GList (doubly linked list) is that they are lighter
+in space as they only need to retain one pointer but it double the
+cost of the worst case access/search operations.
+
+Each element in the list contains a piece of data, together with a
+pointer which links to the next element in the list. Using this
+pointer it is possible to move through the list in one direction
+only (unlike the [double-linked lists][glib-Doubly-Linked-Lists],
+which allow movement in both directions).
+
+The data contained in each element can be either integer values, by
+using one of the [Type Conversion Macros][glib-Type-Conversion-Macros],
+or simply pointers to any type of data.
+
+List elements are allocated from the [slice allocator][glib-Memory-Slices],
+which is more efficient than allocating elements individually.
+
+Note that most of the #GSList functions expect to be passed a
+pointer to the first element in the list. The functions which insert
+elements return the new start of the list, which may have changed.
+
+There is no function to create a #GSList. %NULL is considered to be
+the empty list so you simply set a #GSList* to %NULL.
+
+To add elements, use g_slist_append(), g_slist_prepend(),
+g_slist_insert() and g_slist_insert_sorted().
+
+To remove elements, use g_slist_remove().
+
+To find elements in the list use g_slist_last(), g_slist_next(),
+g_slist_nth(), g_slist_nth_data(), g_slist_find() and
+g_slist_find_custom().
+
+To find the index of an element use g_slist_position() and
+g_slist_index().
+
+To call a function for each element in the list use
+g_slist_foreach().
+
+To free the entire list, use g_slist_free().
+
+
+ A convenience macro to get the next element in a #GList.
+Note that it is considered perfectly acceptable to access
+@list->next directly.
+
+
+
+ an element in a #GList
+
+
+
+
+ A convenience macro to get the previous element in a #GList.
+Note that it is considered perfectly acceptable to access
+@list->prev directly.
+
+
+
+ an element in a #GList
+
+
+
+
+ Gets the names of all variables set in the environment.
+
+Programs that want to be portable to Windows should typically use
+this function and g_getenv() instead of using the environ array
+from the C library directly. On Windows, the strings in the environ
+array are in system codepage encoding, while in most of the typical
+use cases for environment variables in GLib-using programs you want
+the UTF-8 encoding that this function and g_getenv() provide.
+
+
+
+ a %NULL-terminated list of strings which must be freed with
+ g_strfreev().
+
+
+
+
+
+
+ Converts a string from UTF-8 to the encoding used for strings by
+the C runtime (usually the same as that used by the operating
+system) in the [current locale][setlocale]. On Windows this means
+the system codepage.
+
+The input string shall not contain nul characters even if the @len
+argument is positive. A nul character found inside the string will result
+in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. Use g_convert() to convert
+input that may contain embedded nul characters.
+
+
+
+ A newly-allocated buffer containing the converted string,
+ or %NULL on an error, and error will be set.
+
+
+
+
+
+
+ a UTF-8 encoded string
+
+
+
+ the length of the string, or -1 if the string is
+ nul-terminated.
+
+
+
+ location to store the number of bytes in the
+ input string that were successfully converted, or %NULL.
+ Even if the conversion was successful, this may be
+ less than @len if there were partial characters
+ at the end of the input. If the error
+ %G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
+ stored will be the byte offset after the last valid
+ input sequence.
+
+
+
+ the number of bytes stored in the output
+ buffer (not including the terminating nul).
+
+
+
+
+
+ Converts a string which is in the encoding used for strings by
+the C runtime (usually the same as that used by the operating
+system) in the [current locale][setlocale] into a UTF-8 string.
+
+If the source encoding is not UTF-8 and the conversion output contains a
+nul character, the error %G_CONVERT_ERROR_EMBEDDED_NUL is set and the
+function returns %NULL.
+If the source encoding is UTF-8, an embedded nul character is treated with
+the %G_CONVERT_ERROR_ILLEGAL_SEQUENCE error for backward compatibility with
+earlier versions of this library. Use g_convert() to produce output that
+may contain embedded nul characters.
+
+
+ The converted string, or %NULL on an error.
+
+
+
+
+ a string in the
+ encoding of the current locale. On Windows
+ this means the system codepage.
+
+
+
+
+
+ the length of the string, or -1 if the string is
+ nul-terminated (Note that some encodings may allow nul
+ bytes to occur inside strings. In that case, using -1
+ for the @len parameter is unsafe)
+
+
+
+ location to store the number of bytes in the
+ input string that were successfully converted, or %NULL.
+ Even if the conversion was successful, this may be
+ less than @len if there were partial characters
+ at the end of the input. If the error
+ %G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
+ stored will be the byte offset after the last valid
+ input sequence.
+
+
+
+ the number of bytes stored in the output
+ buffer (not including the terminating nul).
+
+
+
+
+
+ Logs an error or debugging message.
+
+If the log level has been set as fatal, G_BREAKPOINT() is called
+to terminate the program. See the documentation for G_BREAKPOINT() for
+details of the debugging options this provides.
+
+If g_log_default_handler() is used as the log handler function, a new-line
+character will automatically be appended to @..., and need not be entered
+manually.
+
+If [structured logging is enabled][using-structured-logging] this will
+output via the structured log writer function (see g_log_set_writer_func()).
+
+
+
+
+
+
+ the log domain, usually %G_LOG_DOMAIN, or %NULL
+ for the default
+
+
+
+ the log level, either from #GLogLevelFlags
+ or a user-defined level
+
+
+
+ the message format. See the `printf()` documentation
+
+
+
+ the parameters to insert into the format string
+
+
+
+
+
+ The default log handler set up by GLib; g_log_set_default_handler()
+allows to install an alternate default log handler.
+This is used if no log handler has been set for the particular log
+domain and log level combination. It outputs the message to stderr
+or stdout and if the log level is fatal it calls G_BREAKPOINT(). It automatically
+prints a new-line character after the message, so one does not need to be
+manually included in @message.
+
+The behavior of this log handler can be influenced by a number of
+environment variables:
+
+- `G_MESSAGES_PREFIXED`: A :-separated list of log levels for which
+ messages should be prefixed by the program name and PID of the
+ application.
+
+- `G_MESSAGES_DEBUG`: A space-separated list of log domains for
+ which debug and informational messages are printed. By default
+ these messages are not printed.
+
+stderr is used for levels %G_LOG_LEVEL_ERROR, %G_LOG_LEVEL_CRITICAL,
+%G_LOG_LEVEL_WARNING and %G_LOG_LEVEL_MESSAGE. stdout is used for
+the rest, unless stderr was requested by
+g_log_writer_default_set_use_stderr().
+
+This has no effect if structured logging is enabled; see
+[Using Structured Logging][using-structured-logging].
+
+
+
+
+
+
+ the log domain of the message, or %NULL for the
+default "" application domain
+
+
+
+ the level of the message
+
+
+
+ the message
+
+
+
+ data passed from g_log() which is unused
+
+
+
+
+
+ Return whether debug output from the GLib logging system is enabled.
+
+Note that this should not be used to conditionalise calls to g_debug() or
+other logging functions; it should only be used from %GLogWriterFunc
+implementations.
+
+Note also that the value of this does not depend on `G_MESSAGES_DEBUG`; see
+the docs for g_log_set_debug_enabled().
+
+
+ %TRUE if debug output is enabled, %FALSE otherwise
+
+
+
+
+ Removes the log handler.
+
+This has no effect if structured logging is enabled; see
+[Using Structured Logging][using-structured-logging].
+
+
+
+
+
+
+ the log domain
+
+
+
+ the id of the handler, which was returned
+ in g_log_set_handler()
+
+
+
+
+
+ Sets the message levels which are always fatal, in any log domain.
+When a message with any of these levels is logged the program terminates.
+You can only set the levels defined by GLib to be fatal.
+%G_LOG_LEVEL_ERROR is always fatal.
+
+You can also make some message levels fatal at runtime by setting
+the `G_DEBUG` environment variable (see
+[Running GLib Applications](glib-running.html)).
+
+Libraries should not call this function, as it affects all messages logged
+by a process, including those from other libraries.
+
+Structured log messages (using g_log_structured() and
+g_log_structured_array()) are fatal only if the default log writer is used;
+otherwise it is up to the writer function to determine which log messages
+are fatal. See [Using Structured Logging][using-structured-logging].
+
+
+ the old fatal mask
+
+
+
+
+ the mask containing bits set for each level
+ of error which is to be fatal
+
+
+
+
+
+ Enable or disable debug output from the GLib logging system for all domains.
+This value interacts disjunctively with `G_MESSAGES_DEBUG` — if either of
+them would allow a debug message to be outputted, it will be.
+
+Note that this should not be used from within library code to enable debug
+output — it is intended for external use.
+
+
+
+
+
+
+ %TRUE to enable debug output, %FALSE otherwise
+
+
+
+
+
+ Installs a default log handler which is used if no
+log handler has been set for the particular log domain
+and log level combination. By default, GLib uses
+g_log_default_handler() as default log handler.
+
+This has no effect if structured logging is enabled; see
+[Using Structured Logging][using-structured-logging].
+
+
+ the previous default log handler
+
+
+
+
+ the log handler function
+
+
+
+ data passed to the log handler
+
+
+
+
+
+ Sets the log levels which are fatal in the given domain.
+%G_LOG_LEVEL_ERROR is always fatal.
+
+This has no effect on structured log messages (using g_log_structured() or
+g_log_structured_array()). To change the fatal behaviour for specific log
+messages, programs must install a custom log writer function using
+g_log_set_writer_func(). See
+[Using Structured Logging][using-structured-logging].
+
+This function is mostly intended to be used with
+%G_LOG_LEVEL_CRITICAL. You should typically not set
+%G_LOG_LEVEL_WARNING, %G_LOG_LEVEL_MESSAGE, %G_LOG_LEVEL_INFO or
+%G_LOG_LEVEL_DEBUG as fatal except inside of test programs.
+
+
+ the old fatal mask for the log domain
+
+
+
+
+ the log domain
+
+
+
+ the new fatal mask
+
+
+
+
+
+ Sets the log handler for a domain and a set of log levels.
+
+To handle fatal and recursive messages the @log_levels parameter
+must be combined with the %G_LOG_FLAG_FATAL and %G_LOG_FLAG_RECURSION
+bit flags.
+
+Note that since the %G_LOG_LEVEL_ERROR log level is always fatal, if
+you want to set a handler for this log level you must combine it with
+%G_LOG_FLAG_FATAL.
+
+This has no effect if structured logging is enabled; see
+[Using Structured Logging][using-structured-logging].
+
+Here is an example for adding a log handler for all warning messages
+in the default domain:
+
+|[<!-- language="C" -->
+g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL
+ | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
+]|
+
+This example adds a log handler for all critical messages from GTK+:
+
+|[<!-- language="C" -->
+g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL
+ | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
+]|
+
+This example adds a log handler for all messages from GLib:
+
+|[<!-- language="C" -->
+g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL
+ | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
+]|
+
+
+ the id of the new handler
+
+
+
+
+ the log domain, or %NULL for the default ""
+ application domain
+
+
+
+ the log levels to apply the log handler for.
+ To handle fatal and recursive messages as well, combine
+ the log levels with the %G_LOG_FLAG_FATAL and
+ %G_LOG_FLAG_RECURSION bit flags.
+
+
+
+ the log handler function
+
+
+
+ data passed to the log handler
+
+
+
+
+
+ Like g_log_set_handler(), but takes a destroy notify for the @user_data.
+
+This has no effect if structured logging is enabled; see
+[Using Structured Logging][using-structured-logging].
+
+
+ the id of the new handler
+
+
+
+
+ the log domain, or %NULL for the default ""
+ application domain
+
+
+
+ the log levels to apply the log handler for.
+ To handle fatal and recursive messages as well, combine
+ the log levels with the %G_LOG_FLAG_FATAL and
+ %G_LOG_FLAG_RECURSION bit flags.
+
+
+
+ the log handler function
+
+
+
+ data passed to the log handler
+
+
+
+ destroy notify for @user_data, or %NULL
+
+
+
+
+
+ Set a writer function which will be called to format and write out each log
+message. Each program should set a writer function, or the default writer
+(g_log_writer_default()) will be used.
+
+Libraries **must not** call this function — only programs are allowed to
+install a writer function, as there must be a single, central point where
+log messages are formatted and outputted.
+
+There can only be one writer function. It is an error to set more than one.
+
+
+
+
+
+
+ log writer function, which must not be %NULL
+
+
+
+ user data to pass to @func
+
+
+
+ function to free @user_data once it’s
+ finished with, if non-%NULL
+
+
+
+
+
+ Log a message with structured data.
+
+The message will be passed through to the log writer set by the application
+using g_log_set_writer_func(). If the message is fatal (i.e. its log level
+is %G_LOG_LEVEL_ERROR), the program will be aborted by calling
+G_BREAKPOINT() at the end of this function. If the log writer returns
+%G_LOG_WRITER_UNHANDLED (failure), no other fallback writers will be tried.
+See the documentation for #GLogWriterFunc for information on chaining
+writers.
+
+The structured data is provided as key–value pairs, where keys are UTF-8
+strings, and values are arbitrary pointers — typically pointing to UTF-8
+strings, but that is not a requirement. To pass binary (non-nul-terminated)
+structured data, use g_log_structured_array(). The keys for structured data
+should follow the [systemd journal
+fields](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html)
+specification. It is suggested that custom keys are namespaced according to
+the code which sets them. For example, custom keys from GLib all have a
+`GLIB_` prefix.
+
+Note that keys that expect UTF-8 strings (specifically `"MESSAGE"` and
+`"GLIB_DOMAIN"`) must be passed as NUL-terminated UTF-8 strings until GLib
+version 2.74.1 because the default log handler did not consider the length of
+the `GLogField`. Starting with GLib 2.74.1 this is fixed and
+non-NUL-terminated UTF-8 strings can be passed with their correct length.
+
+The @log_domain will be converted into a `GLIB_DOMAIN` field. @log_level will
+be converted into a
+[`PRIORITY`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#PRIORITY=)
+field. The format string will have its placeholders substituted for the provided
+values and be converted into a
+[`MESSAGE`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE=)
+field.
+
+Other fields you may commonly want to pass into this function:
+
+ * [`MESSAGE_ID`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE_ID=)
+ * [`CODE_FILE`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_FILE=)
+ * [`CODE_LINE`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_LINE=)
+ * [`CODE_FUNC`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_FUNC=)
+ * [`ERRNO`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#ERRNO=)
+
+Note that `CODE_FILE`, `CODE_LINE` and `CODE_FUNC` are automatically set by
+the logging macros, G_DEBUG_HERE(), g_message(), g_warning(), g_critical(),
+g_error(), etc, if the symbols `G_LOG_USE_STRUCTURED` is defined before including
+`glib.h`.
+
+For example:
+
+|[<!-- language="C" -->
+g_log_structured (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG,
+ "MESSAGE_ID", "06d4df59e6c24647bfe69d2c27ef0b4e",
+ "MY_APPLICATION_CUSTOM_FIELD", "some debug string",
+ "MESSAGE", "This is a debug message about pointer %p and integer %u.",
+ some_pointer, some_integer);
+]|
+
+Note that each `MESSAGE_ID` must be [uniquely and randomly
+generated](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE_ID=).
+If adding a `MESSAGE_ID`, consider shipping a [message
+catalog](https://www.freedesktop.org/wiki/Software/systemd/catalog/) with
+your software.
+
+To pass a user data pointer to the log writer function which is specific to
+this logging call, you must use g_log_structured_array() and pass the pointer
+as a field with #GLogField.length set to zero, otherwise it will be
+interpreted as a string.
+
+For example:
+
+|[<!-- language="C" -->
+const GLogField fields[] = {
+ { "MESSAGE", "This is a debug message.", -1 },
+ { "MESSAGE_ID", "fcfb2e1e65c3494386b74878f1abf893", -1 },
+ { "MY_APPLICATION_CUSTOM_FIELD", "some debug string", -1 },
+ { "MY_APPLICATION_STATE", state_object, 0 },
+};
+g_log_structured_array (G_LOG_LEVEL_DEBUG, fields, G_N_ELEMENTS (fields));
+]|
+
+Note also that, even if no other structured fields are specified, there
+must always be a `MESSAGE` key before the format string. The `MESSAGE`-format
+pair has to be the last of the key-value pairs, and `MESSAGE` is the only
+field for which printf()-style formatting is supported.
+
+The default writer function for `stdout` and `stderr` will automatically
+append a new-line character after the message, so you should not add one
+manually to the format string.
+
+
+
+
+
+
+ log domain, usually %G_LOG_DOMAIN
+
+
+
+ log level, either from #GLogLevelFlags, or a user-defined
+ level
+
+
+
+ key-value pairs of structured data to add to the log entry, followed
+ by the key "MESSAGE", followed by a printf()-style message format,
+ followed by parameters to insert in the format string
+
+
+
+
+
+ Log a message with structured data. The message will be passed through to the
+log writer set by the application using g_log_set_writer_func(). If the
+message is fatal (i.e. its log level is %G_LOG_LEVEL_ERROR), the program will
+be aborted at the end of this function.
+
+See g_log_structured() for more documentation.
+
+This assumes that @log_level is already present in @fields (typically as the
+`PRIORITY` field).
+
+
+
+
+
+
+ log level, either from #GLogLevelFlags, or a user-defined
+ level
+
+
+
+ key–value pairs of structured data to add
+ to the log message
+
+
+
+
+
+ number of elements in the @fields array
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Log a message with structured data, accepting the data within a #GVariant. This
+version is especially useful for use in other languages, via introspection.
+
+The only mandatory item in the @fields dictionary is the "MESSAGE" which must
+contain the text shown to the user.
+
+The values in the @fields dictionary are likely to be of type String
+(%G_VARIANT_TYPE_STRING). Array of bytes (%G_VARIANT_TYPE_BYTESTRING) is also
+supported. In this case the message is handled as binary and will be forwarded
+to the log writer as such. The size of the array should not be higher than
+%G_MAXSSIZE. Otherwise it will be truncated to this size. For other types
+g_variant_print() will be used to convert the value into a string.
+
+For more details on its usage and about the parameters, see g_log_structured().
+
+
+
+
+
+
+ log domain, usually %G_LOG_DOMAIN
+
+
+
+ log level, either from #GLogLevelFlags, or a user-defined
+ level
+
+
+
+ a dictionary (#GVariant of the type %G_VARIANT_TYPE_VARDICT)
+containing the key-value pairs of message data.
+
+
+
+
+
+ Format a structured log message and output it to the default log destination
+for the platform. On Linux, this is typically the systemd journal, falling
+back to `stdout` or `stderr` if running from the terminal or if output is
+being redirected to a file.
+
+Support for other platform-specific logging mechanisms may be added in
+future. Distributors of GLib may modify this function to impose their own
+(documented) platform-specific log writing policies.
+
+This is suitable for use as a #GLogWriterFunc, and is the default writer used
+if no other is set using g_log_set_writer_func().
+
+As with g_log_default_handler(), this function drops debug and informational
+messages unless their log domain (or `all`) is listed in the space-separated
+`G_MESSAGES_DEBUG` environment variable.
+
+g_log_writer_default() uses the mask set by g_log_set_always_fatal() to
+determine which messages are fatal. When using a custom writer func instead it is
+up to the writer function to determine which log messages are fatal.
+
+
+ %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise
+
+
+
+
+ log level, either from #GLogLevelFlags, or a user-defined
+ level
+
+
+
+ key–value pairs of structured data forming
+ the log message
+
+
+
+
+
+ number of elements in the @fields array
+
+
+
+ user data passed to g_log_set_writer_func()
+
+
+
+
+
+ Configure whether the built-in log functions
+(g_log_default_handler() for the old-style API, and both
+g_log_writer_default() and g_log_writer_standard_streams() for the
+structured API) will output all log messages to `stderr`.
+
+By default, log messages of levels %G_LOG_LEVEL_INFO and
+%G_LOG_LEVEL_DEBUG are sent to `stdout`, and other log messages are
+sent to `stderr`. This is problematic for applications that intend
+to reserve `stdout` for structured output such as JSON or XML.
+
+This function sets global state. It is not thread-aware, and should be
+called at the very start of a program, before creating any other threads
+or creating objects that could create worker threads of their own.
+
+
+
+
+
+
+ If %TRUE, use `stderr` for log messages that would
+ normally have appeared on `stdout`
+
+
+
+
+
+ Check whether g_log_writer_default() and g_log_default_handler() would
+ignore a message with the given domain and level.
+
+As with g_log_default_handler(), this function drops debug and informational
+messages unless their log domain (or `all`) is listed in the space-separated
+`G_MESSAGES_DEBUG` environment variable.
+
+This can be used when implementing log writers with the same filtering
+behaviour as the default, but a different destination or output format:
+
+|[<!-- language="C" -->
+ if (g_log_writer_default_would_drop (log_level, log_domain))
+ return G_LOG_WRITER_HANDLED;
+]|
+
+or to skip an expensive computation if it is only needed for a debugging
+message, and `G_MESSAGES_DEBUG` is not set:
+
+|[<!-- language="C" -->
+ if (!g_log_writer_default_would_drop (G_LOG_LEVEL_DEBUG, G_LOG_DOMAIN))
+ {
+ gchar *result = expensive_computation (my_object);
+
+ g_debug ("my_object result: %s", result);
+ g_free (result);
+ }
+]|
+
+
+ %TRUE if the log message would be dropped by GLib's
+ default log handlers
+
+
+
+
+ log level, either from #GLogLevelFlags, or a user-defined
+ level
+
+
+
+ log domain
+
+
+
+
+
+ Format a structured log message as a string suitable for outputting to the
+terminal (or elsewhere). This will include the values of all fields it knows
+how to interpret, which includes `MESSAGE` and `GLIB_DOMAIN` (see the
+documentation for g_log_structured()). It does not include values from
+unknown fields.
+
+The returned string does **not** have a trailing new-line character. It is
+encoded in the character set of the current locale, which is not necessarily
+UTF-8.
+
+
+ string containing the formatted log message, in
+ the character set of the current locale
+
+
+
+
+ log level, either from #GLogLevelFlags, or a user-defined
+ level
+
+
+
+ key–value pairs of structured data forming
+ the log message
+
+
+
+
+
+ number of elements in the @fields array
+
+
+
+ %TRUE to use ANSI color escape sequences when formatting the
+ message, %FALSE to not
+
+
+
+
+
+ Check whether the given @output_fd file descriptor is a connection to the
+systemd journal, or something else (like a log file or `stdout` or
+`stderr`).
+
+Invalid file descriptors are accepted and return %FALSE, which allows for
+the following construct without needing any additional error handling:
+|[<!-- language="C" -->
+ is_journald = g_log_writer_is_journald (fileno (stderr));
+]|
+
+
+ %TRUE if @output_fd points to the journal, %FALSE otherwise
+
+
+
+
+ output file descriptor to check
+
+
+
+
+
+ Format a structured log message and send it to the systemd journal as a set
+of key–value pairs. All fields are sent to the journal, but if a field has
+length zero (indicating program-specific data) then only its key will be
+sent.
+
+This is suitable for use as a #GLogWriterFunc.
+
+If GLib has been compiled without systemd support, this function is still
+defined, but will always return %G_LOG_WRITER_UNHANDLED.
+
+
+ %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise
+
+
+
+
+ log level, either from #GLogLevelFlags, or a user-defined
+ level
+
+
+
+ key–value pairs of structured data forming
+ the log message
+
+
+
+
+
+ number of elements in the @fields array
+
+
+
+ user data passed to g_log_set_writer_func()
+
+
+
+
+
+ Format a structured log message and print it to either `stdout` or `stderr`,
+depending on its log level. %G_LOG_LEVEL_INFO and %G_LOG_LEVEL_DEBUG messages
+are sent to `stdout`, or to `stderr` if requested by
+g_log_writer_default_set_use_stderr();
+all other log levels are sent to `stderr`. Only fields
+which are understood by this function are included in the formatted string
+which is printed.
+
+If the output stream supports ANSI color escape sequences, they will be used
+in the output.
+
+A trailing new-line character is added to the log message when it is printed.
+
+This is suitable for use as a #GLogWriterFunc.
+
+
+ %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise
+
+
+
+
+ log level, either from #GLogLevelFlags, or a user-defined
+ level
+
+
+
+ key–value pairs of structured data forming
+ the log message
+
+
+
+
+
+ number of elements in the @fields array
+
+
+
+ user data passed to g_log_set_writer_func()
+
+
+
+
+
+ Check whether the given @output_fd file descriptor supports ANSI color
+escape sequences. If so, they can safely be used when formatting log
+messages.
+
+
+ %TRUE if ANSI color escapes are supported, %FALSE otherwise
+
+
+
+
+ output file descriptor to check
+
+
+
+
+
+ Logs an error or debugging message.
+
+If the log level has been set as fatal, G_BREAKPOINT() is called
+to terminate the program. See the documentation for G_BREAKPOINT() for
+details of the debugging options this provides.
+
+If g_log_default_handler() is used as the log handler function, a new-line
+character will automatically be appended to @..., and need not be entered
+manually.
+
+If [structured logging is enabled][using-structured-logging] this will
+output via the structured log writer function (see g_log_set_writer_func()).
+
+
+
+
+
+
+ the log domain, or %NULL for the default ""
+application domain
+
+
+
+ the log level
+
+
+
+ the message format. See the printf() documentation
+
+
+
+ the parameters to insert into the format string
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ These macros provide a few commonly-used features.
+
+
+ These macros provide more specialized features which are not
+needed so often by application programmers.
+
+
+ The main event loop manages all the available sources of events for
+GLib and GTK+ applications. These events can come from any number of
+different types of sources such as file descriptors (plain files,
+pipes or sockets) and timeouts. New types of event sources can also
+be added using g_source_attach().
+
+To allow multiple independent sets of sources to be handled in
+different threads, each source is associated with a #GMainContext.
+A #GMainContext can only be running in a single thread, but
+sources can be added to it and removed from it from other threads. All
+functions which operate on a #GMainContext or a built-in #GSource are
+thread-safe.
+
+Each event source is assigned a priority. The default priority,
+%G_PRIORITY_DEFAULT, is 0. Values less than 0 denote higher priorities.
+Values greater than 0 denote lower priorities. Events from high priority
+sources are always processed before events from lower priority sources: if
+several sources are ready to dispatch, the ones with equal-highest priority
+will be dispatched on the current #GMainContext iteration, and the rest wait
+until a subsequent #GMainContext iteration when they have the highest
+priority of the sources which are ready for dispatch.
+
+Idle functions can also be added, and assigned a priority. These will
+be run whenever no events with a higher priority are ready to be dispatched.
+
+The #GMainLoop data type represents a main event loop. A GMainLoop is
+created with g_main_loop_new(). After adding the initial event sources,
+g_main_loop_run() is called. This continuously checks for new events from
+each of the event sources and dispatches them. Finally, the processing of
+an event from one of the sources leads to a call to g_main_loop_quit() to
+exit the main loop, and g_main_loop_run() returns.
+
+It is possible to create new instances of #GMainLoop recursively.
+This is often used in GTK+ applications when showing modal dialog
+boxes. Note that event sources are associated with a particular
+#GMainContext, and will be checked and dispatched for all main
+loops associated with that GMainContext.
+
+GTK+ contains wrappers of some of these functions, e.g. gtk_main(),
+gtk_main_quit() and gtk_events_pending().
+
+## Creating new source types
+
+One of the unusual features of the #GMainLoop functionality
+is that new types of event source can be created and used in
+addition to the builtin type of event source. A new event source
+type is used for handling GDK events. A new source type is created
+by "deriving" from the #GSource structure. The derived type of
+source is represented by a structure that has the #GSource structure
+as a first element, and other elements specific to the new source
+type. To create an instance of the new source type, call
+g_source_new() passing in the size of the derived structure and
+a table of functions. These #GSourceFuncs determine the behavior of
+the new source type.
+
+New source types basically interact with the main context
+in two ways. Their prepare function in #GSourceFuncs can set a timeout
+to determine the maximum amount of time that the main loop will sleep
+before checking the source again. In addition, or as well, the source
+can add file descriptors to the set that the main context checks using
+g_source_add_poll().
+
+## Customizing the main loop iteration
+
+Single iterations of a #GMainContext can be run with
+g_main_context_iteration(). In some cases, more detailed control
+of exactly how the details of the main loop work is desired, for
+instance, when integrating the #GMainLoop with an external main loop.
+In such cases, you can call the component functions of
+g_main_context_iteration() directly. These functions are
+g_main_context_prepare(), g_main_context_query(),
+g_main_context_check() and g_main_context_dispatch().
+
+If the event loop thread releases #GMainContext ownership until the results
+required by g_main_context_check() are ready you must create a context with
+the flag %G_MAIN_CONTEXT_FLAGS_OWNERLESS_POLLING or else you'll lose
+g_source_attach() notifications. This happens for instance when you integrate
+the GLib event loop into implementations that follow the proactor pattern
+(i.e. in these contexts the `poll()` implementation will reclaim the thread for
+other tasks until the results are ready). One example of the proactor pattern
+is the Boost.Asio library.
+
+## State of a Main Context # {#mainloop-states}
+
+The operation of these functions can best be seen in terms
+of a state diagram, as shown in this image.
+
+
+
+On UNIX, the GLib mainloop is incompatible with fork(). Any program
+using the mainloop must either exec() or exit() from the child
+without returning to the mainloop.
+
+## Memory management of sources # {#mainloop-memory-management}
+
+There are two options for memory management of the user data passed to a
+#GSource to be passed to its callback on invocation. This data is provided
+in calls to g_timeout_add(), g_timeout_add_full(), g_idle_add(), etc. and
+more generally, using g_source_set_callback(). This data is typically an
+object which ‘owns’ the timeout or idle callback, such as a widget or a
+network protocol implementation. In many cases, it is an error for the
+callback to be invoked after this owning object has been destroyed, as that
+results in use of freed memory.
+
+The first, and preferred, option is to store the source ID returned by
+functions such as g_timeout_add() or g_source_attach(), and explicitly
+remove that source from the main context using g_source_remove() when the
+owning object is finalized. This ensures that the callback can only be
+invoked while the object is still alive.
+
+The second option is to hold a strong reference to the object in the
+callback, and to release it in the callback’s #GDestroyNotify. This ensures
+that the object is kept alive until after the source is finalized, which is
+guaranteed to be after it is invoked for the final time. The #GDestroyNotify
+is another callback passed to the ‘full’ variants of #GSource functions (for
+example, g_timeout_add_full()). It is called when the source is finalized,
+and is designed for releasing references like this.
+
+One important caveat of this second approach is that it will keep the object
+alive indefinitely if the main loop is stopped before the #GSource is
+invoked, which may be undesirable.
+
+
+ Returns the global-default main context. This is the main context
+used for main loop functions when a main loop is not explicitly
+specified, and corresponds to the "main" main loop. See also
+g_main_context_get_thread_default().
+
+
+ the global-default main context.
+
+
+
+
+ Gets the thread-default #GMainContext for this thread. Asynchronous
+operations that want to be able to be run in contexts other than
+the default one should call this method or
+g_main_context_ref_thread_default() to get a #GMainContext to add
+their #GSources to. (Note that even in single-threaded
+programs applications may sometimes want to temporarily push a
+non-default context, so it is not safe to assume that this will
+always return %NULL if you are running in the default thread.)
+
+If you need to hold a reference on the context, use
+g_main_context_ref_thread_default() instead.
+
+
+ the thread-default #GMainContext, or
+%NULL if the thread-default context is the global-default main context.
+
+
+
+
+ Gets the thread-default #GMainContext for this thread, as with
+g_main_context_get_thread_default(), but also adds a reference to
+it with g_main_context_ref(). In addition, unlike
+g_main_context_get_thread_default(), if the thread-default context
+is the global-default context, this will return that #GMainContext
+(with a ref added to it) rather than returning %NULL.
+
+
+ the thread-default #GMainContext. Unref
+ with g_main_context_unref() when you are done with it.
+
+
+
+
+ Returns the currently firing source for this thread.
+
+
+ The currently firing source or %NULL.
+
+
+
+
+ Returns the depth of the stack of calls to
+g_main_context_dispatch() on any #GMainContext in the current thread.
+ That is, when called from the toplevel, it gives 0. When
+called from within a callback from g_main_context_iteration()
+(or g_main_loop_run(), etc.) it returns 1. When called from within
+a callback to a recursive call to g_main_context_iteration(),
+it returns 2. And so forth.
+
+This function is useful in a situation like the following:
+Imagine an extremely simple "garbage collected" system.
+
+|[<!-- language="C" -->
+static GList *free_list;
+
+gpointer
+allocate_memory (gsize size)
+{
+ gpointer result = g_malloc (size);
+ free_list = g_list_prepend (free_list, result);
+ return result;
+}
+
+void
+free_allocated_memory (void)
+{
+ GList *l;
+ for (l = free_list; l; l = l->next);
+ g_free (l->data);
+ g_list_free (free_list);
+ free_list = NULL;
+ }
+
+[...]
+
+while (TRUE);
+ {
+ g_main_context_iteration (NULL, TRUE);
+ free_allocated_memory();
+ }
+]|
+
+This works from an application, however, if you want to do the same
+thing from a library, it gets more difficult, since you no longer
+control the main loop. You might think you can simply use an idle
+function to make the call to free_allocated_memory(), but that
+doesn't work, since the idle function could be called from a
+recursive callback. This can be fixed by using g_main_depth()
+
+|[<!-- language="C" -->
+gpointer
+allocate_memory (gsize size)
+{
+ FreeListBlock *block = g_new (FreeListBlock, 1);
+ block->mem = g_malloc (size);
+ block->depth = g_main_depth ();
+ free_list = g_list_prepend (free_list, block);
+ return block->mem;
+}
+
+void
+free_allocated_memory (void)
+{
+ GList *l;
+
+ int depth = g_main_depth ();
+ for (l = free_list; l; );
+ {
+ GList *next = l->next;
+ FreeListBlock *block = l->data;
+ if (block->depth > depth)
+ {
+ g_free (block->mem);
+ g_free (block);
+ free_list = g_list_delete_link (free_list, l);
+ }
+
+ l = next;
+ }
+ }
+]|
+
+There is a temptation to use g_main_depth() to solve
+problems with reentrancy. For instance, while waiting for data
+to be received from the network in response to a menu item,
+the menu item might be selected again. It might seem that
+one could make the menu item's callback return immediately
+and do nothing if g_main_depth() returns a value greater than 1.
+However, this should be avoided since the user then sees selecting
+the menu item do nothing. Furthermore, you'll find yourself adding
+these checks all over your code, since there are doubtless many,
+many things that the user could do. Instead, you can use the
+following techniques:
+
+1. Use gtk_widget_set_sensitive() or modal dialogs to prevent
+ the user from interacting with elements while the main
+ loop is recursing.
+
+2. Avoid main loop recursion in situations where you can't handle
+ arbitrary callbacks. Instead, structure your code so that you
+ simply return to the main loop and then get called again when
+ there is more work to do.
+
+
+ The main loop recursion level in the current thread
+
+
+
+
+ Allocates @n_bytes bytes of memory.
+If @n_bytes is 0 it returns %NULL.
+
+If the allocation fails (because the system is out of memory),
+the program is terminated.
+
+
+ a pointer to the allocated memory
+
+
+
+
+ the number of bytes to allocate
+
+
+
+
+
+ Allocates @n_bytes bytes of memory, initialized to 0's.
+If @n_bytes is 0 it returns %NULL.
+
+If the allocation fails (because the system is out of memory),
+the program is terminated.
+
+
+ a pointer to the allocated memory
+
+
+
+
+ the number of bytes to allocate
+
+
+
+
+
+ This function is similar to g_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes,
+but care is taken to detect possible overflow during multiplication.
+
+If the allocation fails (because the system is out of memory),
+the program is terminated.
+
+
+ a pointer to the allocated memory
+
+
+
+
+ the number of blocks to allocate
+
+
+
+ the size of each block in bytes
+
+
+
+
+
+ This function is similar to g_malloc(), allocating (@n_blocks * @n_block_bytes) bytes,
+but care is taken to detect possible overflow during multiplication.
+
+If the allocation fails (because the system is out of memory),
+the program is terminated.
+
+
+ a pointer to the allocated memory
+
+
+
+
+ the number of blocks to allocate
+
+
+
+ the size of each block in bytes
+
+
+
+
+
+ The "GMarkup" parser is intended to parse a simple markup format
+that's a subset of XML. This is a small, efficient, easy-to-use
+parser. It should not be used if you expect to interoperate with
+other applications generating full-scale XML, and must not be used if you
+expect to parse untrusted input. However, it's very
+useful for application data files, config files, etc. where you
+know your application will be the only one writing the file.
+Full-scale XML parsers should be able to parse the subset used by
+GMarkup, so you can easily migrate to full-scale XML at a later
+time if the need arises.
+
+GMarkup is not guaranteed to signal an error on all invalid XML;
+the parser may accept documents that an XML parser would not.
+However, XML documents which are not well-formed (which is a
+weaker condition than being valid. See the
+[XML specification](http://www.w3.org/TR/REC-xml/)
+for definitions of these terms.) are not considered valid GMarkup
+documents.
+
+Simplifications to XML include:
+
+- Only UTF-8 encoding is allowed
+
+- No user-defined entities
+
+- Processing instructions, comments and the doctype declaration
+ are "passed through" but are not interpreted in any way
+
+- No DTD or validation
+
+The markup format does support:
+
+- Elements
+
+- Attributes
+
+- 5 standard entities: & < > " '
+
+- Character references
+
+- Sections marked as CDATA
+
+
+ Collects the attributes of the element from the data passed to the
+#GMarkupParser start_element function, dealing with common error
+conditions and supporting boolean values.
+
+This utility function is not required to write a parser but can save
+a lot of typing.
+
+The @element_name, @attribute_names, @attribute_values and @error
+parameters passed to the start_element callback should be passed
+unmodified to this function.
+
+Following these arguments is a list of "supported" attributes to collect.
+It is an error to specify multiple attributes with the same name. If any
+attribute not in the list appears in the @attribute_names array then an
+unknown attribute error will result.
+
+The #GMarkupCollectType field allows specifying the type of collection
+to perform and if a given attribute must appear or is optional.
+
+The attribute name is simply the name of the attribute to collect.
+
+The pointer should be of the appropriate type (see the descriptions
+under #GMarkupCollectType) and may be %NULL in case a particular
+attribute is to be allowed but ignored.
+
+This function deals with issuing errors for missing attributes
+(of type %G_MARKUP_ERROR_MISSING_ATTRIBUTE), unknown attributes
+(of type %G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE) and duplicate
+attributes (of type %G_MARKUP_ERROR_INVALID_CONTENT) as well
+as parse errors for boolean-valued attributes (again of type
+%G_MARKUP_ERROR_INVALID_CONTENT). In all of these cases %FALSE
+will be returned and @error will be set as appropriate.
+
+
+ %TRUE if successful
+
+
+
+
+ the current tag name
+
+
+
+ the attribute names
+
+
+
+ the attribute values
+
+
+
+ a pointer to a #GError or %NULL
+
+
+
+ the #GMarkupCollectType of the first attribute
+
+
+
+ the name of the first attribute
+
+
+
+ a pointer to the storage location of the first attribute
+ (or %NULL), followed by more types names and pointers, ending
+ with %G_MARKUP_COLLECT_INVALID
+
+
+
+
+
+
+
+
+
+
+ Escapes text so that the markup parser will parse it verbatim.
+Less than, greater than, ampersand, etc. are replaced with the
+corresponding entities. This function would typically be used
+when writing out a file to be parsed with the markup parser.
+
+Note that this function doesn't protect whitespace and line endings
+from being processed according to the XML rules for normalization
+of line endings and attribute values.
+
+Note also that this function will produce character references in
+the range of  ...  for all control sequences
+except for tabstop, newline and carriage return. The character
+references in this range are not valid XML 1.0, but they are
+valid XML 1.1 and will be accepted by the GMarkup parser.
+
+
+ a newly allocated string with the escaped text
+
+
+
+
+ some valid UTF-8 text
+
+
+
+ length of @text in bytes, or -1 if the text is nul-terminated
+
+
+
+
+
+ Formats arguments according to @format, escaping
+all string and character arguments in the fashion
+of g_markup_escape_text(). This is useful when you
+want to insert literal strings into XML-style markup
+output, without having to worry that the strings
+might themselves contain markup.
+
+|[<!-- language="C" -->
+const char *store = "Fortnum & Mason";
+const char *item = "Tea";
+char *output;
+
+output = g_markup_printf_escaped ("<purchase>"
+ "<store>%s</store>"
+ "<item>%s</item>"
+ "</purchase>",
+ store, item);
+]|
+
+
+ newly allocated result from formatting
+ operation. Free with g_free().
+
+
+
+
+ printf() style format string
+
+
+
+ the arguments to insert in the format string
+
+
+
+
+
+ Formats the data in @args according to @format, escaping
+all string and character arguments in the fashion
+of g_markup_escape_text(). See g_markup_printf_escaped().
+
+
+ newly allocated result from formatting
+ operation. Free with g_free().
+
+
+
+
+ printf() style format string
+
+
+
+ variable argument list, similar to vprintf()
+
+
+
+
+
+ Checks whether the allocator used by g_malloc() is the system's
+malloc implementation. If it returns %TRUE memory allocated with
+malloc() can be used interchangeably with memory allocated using g_malloc().
+This function is useful for avoiding an extra copy of allocated memory returned
+by a non-GLib-based API.
+ GLib always uses the system malloc, so this function always
+returns %TRUE.
+
+
+ if %TRUE, malloc() and g_malloc() can be mixed.
+
+
+
+
+ GLib used to support some tools for memory profiling, but this
+no longer works. There are many other useful tools for memory
+profiling these days which can be used instead.
+ Use other memory profiling tools instead
+
+
+
+
+
+
+ This function used to let you override the memory allocation function.
+However, its use was incompatible with the use of global constructors
+in GLib and GIO, because those use the GLib allocators before main is
+reached. Therefore this function is now deprecated and is just a stub.
+ This function now does nothing. Use other memory
+profiling tools instead
+
+
+
+
+
+
+ table of memory allocation routines.
+
+
+
+
+
+ Allocates @byte_size bytes of memory, and copies @byte_size bytes into it
+from @mem. If @mem is %NULL it returns %NULL.
+ Use g_memdup2() instead, as it accepts a #gsize argument
+ for @byte_size, avoiding the possibility of overflow in a #gsize → #guint
+ conversion
+
+
+ a pointer to the newly-allocated copy of the memory, or %NULL if @mem
+ is %NULL.
+
+
+
+
+ the memory to copy.
+
+
+
+ the number of bytes to copy.
+
+
+
+
+
+ Allocates @byte_size bytes of memory, and copies @byte_size bytes into it
+from @mem. If @mem is %NULL it returns %NULL.
+
+This replaces g_memdup(), which was prone to integer overflows when
+converting the argument from a #gsize to a #guint.
+
+
+ a pointer to the newly-allocated copy of the memory,
+ or %NULL if @mem is %NULL.
+
+
+
+
+ the memory to copy.
+
+
+
+ the number of bytes to copy.
+
+
+
+
+
+ Copies a block of memory @len bytes long, from @src to @dest.
+The source and destination areas may overlap.
+ Just use memmove().
+
+
+
+ the destination address to copy the bytes to.
+
+
+ the source address to copy the bytes from.
+
+
+ the number of bytes to copy.
+
+
+
+
+ These functions provide support for allocating and freeing memory.
+
+If any call to allocate memory using functions g_new(), g_new0(), g_renew(),
+g_malloc(), g_malloc0(), g_malloc0_n(), g_realloc(), and g_realloc_n()
+fails, the application is terminated. This also means that there is no
+need to check if the call succeeded. On the other hand, the `g_try_...()` family
+of functions returns %NULL on failure that can be used as a check
+for unsuccessful memory allocation. The application is not terminated
+in this case.
+
+As all GLib functions and data structures use `g_malloc()` internally, unless
+otherwise specified, any allocation failure will result in the application
+being terminated.
+
+It's important to match g_malloc() (and wrappers such as g_new()) with
+g_free(), g_slice_alloc() (and wrappers such as g_slice_new()) with
+g_slice_free(), plain malloc() with free(), and (if you're using C++)
+new with delete and new[] with delete[]. Otherwise bad things can happen,
+since these allocators may use different memory pools (and new/delete call
+constructors and destructors).
+
+Since GLib 2.46 g_malloc() is hardcoded to always use the system malloc
+implementation.
+
+
+ GSlice was a space-efficient and multi-processing scalable way to allocate
+equal sized pieces of memory. Since GLib 2.76, its implementation has been
+removed and it calls g_malloc() and g_free_sized(), because the performance
+of the system-default allocators has improved on all platforms since GSlice
+was written.
+
+The GSlice APIs have not been deprecated, as they are widely in use and doing
+so would be very disruptive for little benefit.
+
+New code should be written using g_new()/g_malloc() and g_free_sized() or
+g_free(). There is no particular benefit in porting existing code away from
+g_slice_new()/g_slice_free() unless it’s being rewritten anyway.
+
+Here is an example for using the slice allocator:
+|[<!-- language="C" -->
+gchar *mem[10000];
+gint i;
+
+// Allocate 10000 blocks.
+for (i = 0; i < 10000; i++)
+ {
+ mem[i] = g_slice_alloc (50);
+
+ // Fill in the memory with some junk.
+ for (j = 0; j < 50; j++)
+ mem[i][j] = i * j;
+ }
+
+// Now free all of the blocks.
+for (i = 0; i < 10000; i++)
+ g_slice_free1 (50, mem[i]);
+]|
+
+And here is an example for using the using the slice allocator
+with data structures:
+|[<!-- language="C" -->
+GRealArray *array;
+
+// Allocate one block, using the g_slice_new() macro.
+array = g_slice_new (GRealArray);
+
+// We can now use array just like a normal pointer to a structure.
+array->data = NULL;
+array->len = 0;
+array->alloc = 0;
+array->zero_terminated = (zero_terminated ? 1 : 0);
+array->clear = (clear ? 1 : 0);
+array->elt_size = elt_size;
+
+// We can free the block, so it can be reused.
+g_slice_free (GRealArray, array);
+]|
+
+
+ A convenience function/macro to log a normal message.
+
+If g_log_default_handler() is used as the log handler function, a new-line
+character will automatically be appended to @..., and need not be entered
+manually.
+
+If structured logging is enabled, this will use g_log_structured();
+otherwise it will use g_log(). See
+[Using Structured Logging][using-structured-logging].
+
+
+
+ format string, followed by parameters to insert
+ into the format string (as with printf())
+
+
+
+
+ These functions provide support for outputting messages.
+
+The g_return family of macros (g_return_if_fail(),
+g_return_val_if_fail(), g_return_if_reached(),
+g_return_val_if_reached()) should only be used for programming
+errors, a typical use case is checking for invalid parameters at
+the beginning of a public function. They should not be used if
+you just mean "if (error) return", they should only be used if
+you mean "if (bug in program) return". The program behavior is
+generally considered undefined after one of these checks fails.
+They are not intended for normal control flow, only to give a
+perhaps-helpful warning before giving up.
+
+Structured logging output is supported using g_log_structured(). This differs
+from the traditional g_log() API in that log messages are handled as a
+collection of key–value pairs representing individual pieces of information,
+rather than as a single string containing all the information in an arbitrary
+format.
+
+The convenience macros g_info(), g_message(), g_debug(), g_warning() and g_error()
+will use the traditional g_log() API unless you define the symbol
+%G_LOG_USE_STRUCTURED before including `glib.h`. But note that even messages
+logged through the traditional g_log() API are ultimatively passed to
+g_log_structured(), so that all log messages end up in same destination.
+If %G_LOG_USE_STRUCTURED is defined, g_test_expect_message() will become
+ineffective for the wrapper macros g_warning() and friends (see
+[Testing for Messages][testing-for-messages]).
+
+The support for structured logging was motivated by the following needs (some
+of which were supported previously; others weren’t):
+ * Support for multiple logging levels.
+ * Structured log support with the ability to add `MESSAGE_ID`s (see
+ g_log_structured()).
+ * Moving the responsibility for filtering log messages from the program to
+ the log viewer — instead of libraries and programs installing log handlers
+ (with g_log_set_handler()) which filter messages before output, all log
+ messages are outputted, and the log viewer program (such as `journalctl`)
+ must filter them. This is based on the idea that bugs are sometimes hard
+ to reproduce, so it is better to log everything possible and then use
+ tools to analyse the logs than it is to not be able to reproduce a bug to
+ get additional log data. Code which uses logging in performance-critical
+ sections should compile out the g_log_structured() calls in
+ release builds, and compile them in in debugging builds.
+ * A single writer function which handles all log messages in a process, from
+ all libraries and program code; rather than multiple log handlers with
+ poorly defined interactions between them. This allows a program to easily
+ change its logging policy by changing the writer function, for example to
+ log to an additional location or to change what logging output fallbacks
+ are used. The log writer functions provided by GLib are exposed publicly
+ so they can be used from programs’ log writers. This allows log writer
+ policy and implementation to be kept separate.
+ * If a library wants to add standard information to all of its log messages
+ (such as library state) or to redact private data (such as passwords or
+ network credentials), it should use a wrapper function around its
+ g_log_structured() calls or implement that in the single log writer
+ function.
+ * If a program wants to pass context data from a g_log_structured() call to
+ its log writer function so that, for example, it can use the correct
+ server connection to submit logs to, that user data can be passed as a
+ zero-length #GLogField to g_log_structured_array().
+ * Color output needed to be supported on the terminal, to make reading
+ through logs easier.
+
+## Using Structured Logging ## {#using-structured-logging}
+
+To use structured logging (rather than the old-style logging), either use
+the g_log_structured() and g_log_structured_array() functions; or define
+`G_LOG_USE_STRUCTURED` before including any GLib header, and use the
+g_message(), g_debug(), g_error() (etc.) macros.
+
+You do not need to define `G_LOG_USE_STRUCTURED` to use g_log_structured(),
+but it is a good idea to avoid confusion.
+
+## Log Domains ## {#log-domains}
+
+Log domains may be used to broadly split up the origins of log messages.
+Typically, there are one or a few log domains per application or library.
+%G_LOG_DOMAIN should be used to define the default log domain for the current
+compilation unit — it is typically defined at the top of a source file, or in
+the preprocessor flags for a group of source files.
+
+Log domains must be unique, and it is recommended that they are the
+application or library name, optionally followed by a hyphen and a sub-domain
+name. For example, `bloatpad` or `bloatpad-io`.
+
+## Debug Message Output ## {#debug-message-output}
+
+The default log functions (g_log_default_handler() for the old-style API and
+g_log_writer_default() for the structured API) both drop debug and
+informational messages by default, unless the log domains of those messages
+are listed in the `G_MESSAGES_DEBUG` environment variable (or it is set to
+`all`).
+
+It is recommended that custom log writer functions re-use the
+`G_MESSAGES_DEBUG` environment variable, rather than inventing a custom one,
+so that developers can re-use the same debugging techniques and tools across
+projects. Since GLib 2.68, this can be implemented by dropping messages
+for which g_log_writer_default_would_drop() returns %TRUE.
+
+## Testing for Messages ## {#testing-for-messages}
+
+With the old g_log() API, g_test_expect_message() and
+g_test_assert_expected_messages() could be used in simple cases to check
+whether some code under test had emitted a given log message. These
+functions have been deprecated with the structured logging API, for several
+reasons:
+ * They relied on an internal queue which was too inflexible for many use
+ cases, where messages might be emitted in several orders, some
+ messages might not be emitted deterministically, or messages might be
+ emitted by unrelated log domains.
+ * They do not support structured log fields.
+ * Examining the log output of code is a bad approach to testing it, and
+ while it might be necessary for legacy code which uses g_log(), it should
+ be avoided for new code using g_log_structured().
+
+They will continue to work as before if g_log() is in use (and
+%G_LOG_USE_STRUCTURED is not defined). They will do nothing if used with the
+structured logging API.
+
+Examining the log output of code is discouraged: libraries should not emit to
+`stderr` during defined behaviour, and hence this should not be tested. If
+the log emissions of a library during undefined behaviour need to be tested,
+they should be limited to asserting that the library aborts and prints a
+suitable error message before aborting. This should be done with
+g_test_trap_assert_stderr().
+
+If it is really necessary to test the structured log messages emitted by a
+particular piece of code – and the code cannot be restructured to be more
+suitable to more conventional unit testing – you should write a custom log
+writer function (see g_log_set_writer_func()) which appends all log messages
+to a queue. When you want to check the log messages, examine and clear the
+queue, ignoring irrelevant log messages (for example, from log domains other
+than the one under test).
+
+
+ These are portable utility functions.
+
+
+ Create a directory if it doesn't already exist. Create intermediate
+parent directories as needed, too.
+
+
+ 0 if the directory already exists, or was successfully
+created. Returns -1 if an error occurred, with errno set.
+
+
+
+
+ a pathname in the GLib file name encoding
+
+
+
+ permissions to use for newly created directories
+
+
+
+
+
+ Creates a temporary directory. See the mkdtemp() documentation
+on most UNIX-like systems.
+
+The parameter is a string that should follow the rules for
+mkdtemp() templates, i.e. contain the string "XXXXXX".
+g_mkdtemp() is slightly more flexible than mkdtemp() in that the
+sequence does not have to occur at the very end of the template.
+The X string will be modified to form the name of a directory that
+didn't exist.
+The string should be in the GLib file name encoding. Most importantly,
+on Windows it should be in UTF-8.
+
+If you are going to be creating a temporary directory inside the
+directory returned by g_get_tmp_dir(), you might want to use
+g_dir_make_tmp() instead.
+
+
+ A pointer to @tmpl, which has been
+ modified to hold the directory name. In case of errors, %NULL is
+ returned and %errno will be set.
+
+
+
+
+ template directory name
+
+
+
+
+
+ Creates a temporary directory. See the mkdtemp() documentation
+on most UNIX-like systems.
+
+The parameter is a string that should follow the rules for
+mkdtemp() templates, i.e. contain the string "XXXXXX".
+g_mkdtemp_full() is slightly more flexible than mkdtemp() in that the
+sequence does not have to occur at the very end of the template
+and you can pass a @mode. The X string will be modified to form
+the name of a directory that didn't exist. The string should be
+in the GLib file name encoding. Most importantly, on Windows it
+should be in UTF-8.
+
+If you are going to be creating a temporary directory inside the
+directory returned by g_get_tmp_dir(), you might want to use
+g_dir_make_tmp() instead.
+
+
+ A pointer to @tmpl, which has been
+ modified to hold the directory name. In case of errors, %NULL is
+ returned, and %errno will be set.
+
+
+
+
+ template directory name
+
+
+
+ permissions to create the temporary directory with
+
+
+
+
+
+ Opens a temporary file. See the mkstemp() documentation
+on most UNIX-like systems.
+
+The parameter is a string that should follow the rules for
+mkstemp() templates, i.e. contain the string "XXXXXX".
+g_mkstemp() is slightly more flexible than mkstemp() in that the
+sequence does not have to occur at the very end of the template.
+The X string will be modified to form the name of a file that
+didn't exist. The string should be in the GLib file name encoding.
+Most importantly, on Windows it should be in UTF-8.
+
+
+ A file handle (as from open()) to the file
+ opened for reading and writing. The file is opened in binary
+ mode on platforms where there is a difference. The file handle
+ should be closed with close(). In case of errors, -1 is
+ returned and %errno will be set.
+
+
+
+
+ template filename
+
+
+
+
+
+ Opens a temporary file. See the mkstemp() documentation
+on most UNIX-like systems.
+
+The parameter is a string that should follow the rules for
+mkstemp() templates, i.e. contain the string "XXXXXX".
+g_mkstemp_full() is slightly more flexible than mkstemp()
+in that the sequence does not have to occur at the very end of the
+template and you can pass a @mode and additional @flags. The X
+string will be modified to form the name of a file that didn't exist.
+The string should be in the GLib file name encoding. Most importantly,
+on Windows it should be in UTF-8.
+
+
+ A file handle (as from open()) to the file
+ opened for reading and writing. The file handle should be
+ closed with close(). In case of errors, -1 is returned
+ and %errno will be set.
+
+
+
+
+ template filename
+
+
+
+ flags to pass to an open() call in addition to O_EXCL
+ and O_CREAT, which are passed automatically
+
+
+
+ permissions to create the temporary file with
+
+
+
+
+
+ Allocates @n_structs elements of type @struct_type.
+The returned pointer is cast to a pointer to the given type.
+If @n_structs is 0 it returns %NULL.
+Care is taken to avoid overflow when calculating the size of the allocated block.
+
+Since the returned pointer is already casted to the right type,
+it is normally unnecessary to cast it explicitly, and doing
+so might hide memory allocation errors.
+
+
+
+ the type of the elements to allocate
+
+
+ the number of elements to allocate
+
+
+
+
+ Allocates @n_structs elements of type @struct_type, initialized to 0's.
+The returned pointer is cast to a pointer to the given type.
+If @n_structs is 0 it returns %NULL.
+Care is taken to avoid overflow when calculating the size of the allocated block.
+
+Since the returned pointer is already casted to the right type,
+it is normally unnecessary to cast it explicitly, and doing
+so might hide memory allocation errors.
+
+
+
+ the type of the elements to allocate.
+
+
+ the number of elements to allocate.
+
+
+
+
+ Wraps g_alloca() in a more typesafe manner.
+
+As mentioned in the documentation for g_alloca(), @n_structs must always be
+entirely under the control of the program, or you may introduce a denial of
+service vulnerability. In addition, the multiplication of @struct_type by
+@n_structs is not checked, so an overflow may lead to a remote code execution
+vulnerability.
+
+
+
+ Type of memory chunks to be allocated
+
+
+ Number of chunks to be allocated
+
+
+
+
+ Wraps g_alloca0() in a more typesafe manner.
+
+
+
+ the type of the elements to allocate.
+
+
+ the number of elements to allocate.
+
+
+
+
+ Inserts a #GNode as the last child of the given parent.
+
+
+
+ the #GNode to place the new #GNode under
+
+
+ the #GNode to insert
+
+
+
+
+ Inserts a new #GNode as the last child of the given parent.
+
+
+
+ the #GNode to place the new #GNode under
+
+
+ the data for the new #GNode
+
+
+
+
+ Gets the first child of a #GNode.
+
+
+
+ a #GNode
+
+
+
+
+ Inserts a new #GNode at the given position.
+
+
+
+ the #GNode to place the new #GNode under
+
+
+ the position to place the new #GNode at. If position is -1,
+ the new #GNode is inserted as the last child of @parent
+
+
+ the data for the new #GNode
+
+
+
+
+ Inserts a new #GNode after the given sibling.
+
+
+
+ the #GNode to place the new #GNode under
+
+
+ the sibling #GNode to place the new #GNode after
+
+
+ the data for the new #GNode
+
+
+
+
+ Inserts a new #GNode before the given sibling.
+
+
+
+ the #GNode to place the new #GNode under
+
+
+ the sibling #GNode to place the new #GNode before
+
+
+ the data for the new #GNode
+
+
+
+
+ Gets the next sibling of a #GNode.
+
+
+
+ a #GNode
+
+
+
+
+ Inserts a new #GNode as the first child of the given parent.
+
+
+
+ the #GNode to place the new #GNode under
+
+
+ the data for the new #GNode
+
+
+
+
+ Gets the previous sibling of a #GNode.
+
+
+
+ a #GNode
+
+
+
+
+ Converts a 32-bit integer value from network to host byte order.
+
+
+
+ a 32-bit integer value in network byte order
+
+
+
+
+ Converts a 16-bit integer value from network to host byte order.
+
+
+
+ a 16-bit integer value in network byte order
+
+
+
+
+ Set the pointer at the specified location to %NULL.
+
+
+
+
+
+
+ the memory address of the pointer.
+
+
+
+
+
+
+
+
+
+
+ GLib offers mathematical constants such as %G_PI for the value of pi;
+many platforms have these in the C library, but some don't, the GLib
+versions always exist.
+
+The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the
+sign, mantissa and exponent of IEEE floats and doubles. These unions are
+defined as appropriate for a given platform. IEEE floats and doubles are
+supported (used for storage) by at least Intel, PPC and Sparc. See
+[IEEE 754-2008](http://en.wikipedia.org/wiki/IEEE_float)
+for more information about IEEE number formats.
+
+
+ Prompts the user with
+`[E]xit, [H]alt, show [S]tack trace or [P]roceed`.
+This function is intended to be used for debugging use only.
+The following example shows how it can be used together with
+the g_log() functions.
+
+|[<!-- language="C" -->
+#include <glib.h>
+
+static void
+log_handler (const gchar *log_domain,
+ GLogLevelFlags log_level,
+ const gchar *message,
+ gpointer user_data)
+{
+ g_log_default_handler (log_domain, log_level, message, user_data);
+
+ g_on_error_query (MY_PROGRAM_NAME);
+}
+
+int
+main (int argc, char *argv[])
+{
+ g_log_set_handler (MY_LOG_DOMAIN,
+ G_LOG_LEVEL_WARNING |
+ G_LOG_LEVEL_ERROR |
+ G_LOG_LEVEL_CRITICAL,
+ log_handler,
+ NULL);
+ ...
+]|
+
+If "[E]xit" is selected, the application terminates with a call
+to _exit(0).
+
+If "[S]tack" trace is selected, g_on_error_stack_trace() is called.
+This invokes gdb, which attaches to the current process and shows
+a stack trace. The prompt is then shown again.
+
+If "[P]roceed" is selected, the function returns.
+
+This function may cause different actions on non-UNIX platforms.
+
+On Windows consider using the `G_DEBUGGER` environment
+variable (see [Running GLib Applications](glib-running.html)) and
+calling g_on_error_stack_trace() instead.
+
+
+
+
+
+
+ the program name, needed by gdb for the "[S]tack trace"
+ option. If @prg_name is %NULL, g_get_prgname() is called to get
+ the program name (which will work correctly if gdk_init() or
+ gtk_init() has been called)
+
+
+
+
+
+ Invokes gdb, which attaches to the current process and shows a
+stack trace. Called by g_on_error_query() when the "[S]tack trace"
+option is selected. You can get the current process's program name
+with g_get_prgname(), assuming that you have called gtk_init() or
+gdk_init().
+
+This function may cause different actions on non-UNIX platforms.
+
+When running on Windows, this function is *not* called by
+g_on_error_query(). If called directly, it will raise an
+exception, which will crash the program. If the `G_DEBUGGER` environment
+variable is set, a debugger will be invoked to attach and
+handle that exception (see [Running GLib Applications](glib-running.html)).
+
+
+
+
+
+
+ the program name, needed by gdb for the "[S]tack trace"
+ option
+
+
+
+
+
+ The first call to this routine by a process with a given #GOnce
+struct calls @func with the given argument. Thereafter, subsequent
+calls to g_once() with the same #GOnce struct do not call @func
+again, but return the stored result of the first call. On return
+from g_once(), the status of @once will be %G_ONCE_STATUS_READY.
+
+For example, a mutex or a thread-specific data key must be created
+exactly once. In a threaded environment, calling g_once() ensures
+that the initialization is serialized across multiple threads.
+
+Calling g_once() recursively on the same #GOnce struct in
+@func will lead to a deadlock.
+
+|[<!-- language="C" -->
+ gpointer
+ get_debug_flags (void)
+ {
+ static GOnce my_once = G_ONCE_INIT;
+
+ g_once (&my_once, parse_debug_flags, NULL);
+
+ return my_once.retval;
+ }
+]|
+
+
+
+ a #GOnce structure
+
+
+ the #GThreadFunc function associated to @once. This function
+ is called only once, regardless of the number of times it and
+ its associated #GOnce struct are passed to g_once().
+
+
+ data to be passed to @func
+
+
+
+
+ Function to be called when starting a critical initialization
+section. The argument @location must point to a static
+0-initialized variable that will be set to a value other than 0 at
+the end of the initialization section. In combination with
+g_once_init_leave() and the unique address @value_location, it can
+be ensured that an initialization section will be executed only once
+during a program's life time, and that concurrent threads are
+blocked until initialization completed. To be used in constructs
+like this:
+
+|[<!-- language="C" -->
+ static gsize initialization_value = 0;
+
+ if (g_once_init_enter (&initialization_value))
+ {
+ gsize setup_value = 42; // initialization code here
+
+ g_once_init_leave (&initialization_value, setup_value);
+ }
+
+ // use initialization_value here
+]|
+
+While @location has a `volatile` qualifier, this is a historical artifact and
+the pointer passed to it should not be `volatile`.
+
+
+ %TRUE if the initialization section should be entered,
+ %FALSE and blocks otherwise
+
+
+
+
+ location of a static initializable variable
+ containing 0
+
+
+
+
+
+ Counterpart to g_once_init_enter(). Expects a location of a static
+0-initialized initialization variable, and an initialization value
+other than 0. Sets the variable to the initialization value, and
+releases concurrent threads blocking in g_once_init_enter() on this
+initialization variable.
+
+While @location has a `volatile` qualifier, this is a historical artifact and
+the pointer passed to it should not be `volatile`.
+
+
+
+
+
+
+ location of a static initializable variable
+ containing 0
+
+
+
+ new non-0 value for *@value_location
+
+
+
+
+
+ The GOption commandline parser is intended to be a simpler replacement
+for the popt library. It supports short and long commandline options,
+as shown in the following example:
+
+`testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2`
+
+The example demonstrates a number of features of the GOption
+commandline parser:
+
+- Options can be single letters, prefixed by a single dash.
+
+- Multiple short options can be grouped behind a single dash.
+
+- Long options are prefixed by two consecutive dashes.
+
+- Options can have an extra argument, which can be a number, a string or
+ a filename. For long options, the extra argument can be appended with
+ an equals sign after the option name, which is useful if the extra
+ argument starts with a dash, which would otherwise cause it to be
+ interpreted as another option.
+
+- Non-option arguments are returned to the application as rest arguments.
+
+- An argument consisting solely of two dashes turns off further parsing,
+ any remaining arguments (even those starting with a dash) are returned
+ to the application as rest arguments.
+
+Another important feature of GOption is that it can automatically
+generate nicely formatted help output. Unless it is explicitly turned
+off with g_option_context_set_help_enabled(), GOption will recognize
+the `--help`, `-?`, `--help-all` and `--help-groupname` options
+(where `groupname` is the name of a #GOptionGroup) and write a text
+similar to the one shown in the following example to stdout.
+
+|[
+Usage:
+ testtreemodel [OPTION...] - test tree model performance
+
+Help Options:
+ -h, --help Show help options
+ --help-all Show all help options
+ --help-gtk Show GTK+ Options
+
+Application Options:
+ -r, --repeats=N Average over N repetitions
+ -m, --max-size=M Test up to 2^M items
+ --display=DISPLAY X display to use
+ -v, --verbose Be verbose
+ -b, --beep Beep when done
+ --rand Randomize the data
+]|
+
+GOption groups options in #GOptionGroups, which makes it easy to
+incorporate options from multiple sources. The intended use for this is
+to let applications collect option groups from the libraries it uses,
+add them to their #GOptionContext, and parse all options by a single call
+to g_option_context_parse(). See gtk_get_option_group() for an example.
+
+If an option is declared to be of type string or filename, GOption takes
+care of converting it to the right encoding; strings are returned in
+UTF-8, filenames are returned in the GLib filename encoding. Note that
+this only works if setlocale() has been called before
+g_option_context_parse().
+
+Here is a complete example of setting up GOption to parse the example
+commandline above and produce the example help output.
+|[<!-- language="C" -->
+static gint repeats = 2;
+static gint max_size = 8;
+static gboolean verbose = FALSE;
+static gboolean beep = FALSE;
+static gboolean randomize = FALSE;
+
+static GOptionEntry entries[] =
+{
+ { "repeats", 'r', 0, G_OPTION_ARG_INT, &repeats, "Average over N repetitions", "N" },
+ { "max-size", 'm', 0, G_OPTION_ARG_INT, &max_size, "Test up to 2^M items", "M" },
+ { "verbose", 'v', 0, G_OPTION_ARG_NONE, &verbose, "Be verbose", NULL },
+ { "beep", 'b', 0, G_OPTION_ARG_NONE, &beep, "Beep when done", NULL },
+ { "rand", 0, 0, G_OPTION_ARG_NONE, &randomize, "Randomize the data", NULL },
+ G_OPTION_ENTRY_NULL
+};
+
+int
+main (int argc, char *argv[])
+{
+ GError *error = NULL;
+ GOptionContext *context;
+
+ context = g_option_context_new ("- test tree model performance");
+ g_option_context_add_main_entries (context, entries, GETTEXT_PACKAGE);
+ g_option_context_add_group (context, gtk_get_option_group (TRUE));
+ if (!g_option_context_parse (context, &argc, &argv, &error))
+ {
+ g_print ("option parsing failed: %s\n", error->message);
+ exit (1);
+ }
+
+ ...
+
+}
+]|
+
+On UNIX systems, the argv that is passed to main() has no particular
+encoding, even to the extent that different parts of it may have
+different encodings. In general, normal arguments and flags will be
+in the current locale and filenames should be considered to be opaque
+byte strings. Proper use of %G_OPTION_ARG_FILENAME vs
+%G_OPTION_ARG_STRING is therefore important.
+
+Note that on Windows, filenames do have an encoding, but using
+#GOptionContext with the argv as passed to main() will result in a
+program that can only accept commandline arguments with characters
+from the system codepage. This can cause problems when attempting to
+deal with filenames containing Unicode characters that fall outside
+of the codepage.
+
+A solution to this is to use g_win32_get_command_line() and
+g_option_context_parse_strv() which will properly handle full Unicode
+filenames. If you are using #GApplication, this is done
+automatically for you.
+
+The following example shows how you can use #GOptionContext directly
+in order to correctly deal with Unicode filenames on Windows:
+
+|[<!-- language="C" -->
+int
+main (int argc, char **argv)
+{
+ GError *error = NULL;
+ GOptionContext *context;
+ gchar **args;
+
+#ifdef G_OS_WIN32
+ args = g_win32_get_command_line ();
+#else
+ args = g_strdupv (argv);
+#endif
+
+ // set up context
+
+ if (!g_option_context_parse_strv (context, &args, &error))
+ {
+ // error happened
+ }
+
+ ...
+
+ g_strfreev (args);
+
+ ...
+}
+]|
+
+
+
+
+
+
+
+ Parses a string containing debugging options
+into a %guint containing bit flags. This is used
+within GDK and GTK+ to parse the debug options passed on the
+command line or through environment variables.
+
+If @string is equal to "all", all flags are set. Any flags
+specified along with "all" in @string are inverted; thus,
+"all,foo,bar" or "foo,bar,all" sets all flags except those
+corresponding to "foo" and "bar".
+
+If @string is equal to "help", all the available keys in @keys
+are printed out to standard error.
+
+
+ the combined set of bit flags.
+
+
+
+
+ a list of debug options separated by colons, spaces, or
+commas, or %NULL.
+
+
+
+ pointer to an array of #GDebugKey which associate
+ strings with bit flags.
+
+
+
+
+
+ the number of #GDebugKeys in the array.
+
+
+
+
+
+ Compares two path buffers for equality and returns `TRUE`
+if they are equal.
+
+The path inside the paths buffers are not going to be normalized,
+so `X/Y/Z/A/..`, `X/./Y/Z` and `X/Y/Z` are not going to be considered
+equal.
+
+This function can be passed to g_hash_table_new() as the
+`key_equal_func` parameter.
+
+
+ `TRUE` if the two path buffers are equal,
+ and `FALSE` otherwise
+
+
+
+
+ a path buffer to compare
+
+
+
+ a path buffer to compare
+
+
+
+
+
+ Gets the last component of the filename.
+
+If @file_name ends with a directory separator it gets the component
+before the last slash. If @file_name consists only of directory
+separators (and on Windows, possibly a drive letter), a single
+separator is returned. If @file_name is empty, it gets ".".
+
+
+ a newly allocated string
+ containing the last component of the filename
+
+
+
+
+ the name of the file
+
+
+
+
+
+ Gets the directory components of a file name. For example, the directory
+component of `/usr/bin/test` is `/usr/bin`. The directory component of `/`
+is `/`.
+
+If the file name has no directory components "." is returned.
+The returned string should be freed when no longer needed.
+
+
+ the directory components of the file
+
+
+
+
+ the name of the file
+
+
+
+
+
+ Returns %TRUE if the given @file_name is an absolute file name.
+Note that this is a somewhat vague concept on Windows.
+
+On POSIX systems, an absolute file name is well-defined. It always
+starts from the single root directory. For example "/usr/local".
+
+On Windows, the concepts of current drive and drive-specific
+current directory introduce vagueness. This function interprets as
+an absolute file name one that either begins with a directory
+separator such as "\Users\tml" or begins with the root on a drive,
+for example "C:\Windows". The first case also includes UNC paths
+such as "\\\\myserver\docs\foo". In all cases, either slashes or
+backslashes are accepted.
+
+Note that a file name relative to the current drive root does not
+truly specify a file uniquely over time and across processes, as
+the current drive is a per-process value and can be changed.
+
+File names relative the current directory on some specific drive,
+such as "D:foo/bar", are not interpreted as absolute by this
+function, but they obviously are not relative to the normal current
+directory as returned by getcwd() or g_get_current_dir()
+either. Such paths should be avoided, or need to be handled using
+Windows-specific code.
+
+
+ %TRUE if @file_name is absolute
+
+
+
+
+ a file name
+
+
+
+
+
+ Returns a pointer into @file_name after the root component,
+i.e. after the "/" in UNIX or "C:\" under Windows. If @file_name
+is not an absolute path it returns %NULL.
+
+
+ a pointer into @file_name after the
+ root component
+
+
+
+
+ a file name
+
+
+
+
+
+ Matches a string against a compiled pattern. Passing the correct
+length of the string given is mandatory. The reversed string can be
+omitted by passing %NULL, this is more efficient if the reversed
+version of the string to be matched is not at hand, as
+g_pattern_match() will only construct it if the compiled pattern
+requires reverse matches.
+
+Note that, if the user code will (possibly) match a string against a
+multitude of patterns containing wildcards, chances are high that
+some patterns will require a reversed string. In this case, it's
+more efficient to provide the reversed string to avoid multiple
+constructions thereof in the various calls to g_pattern_match().
+
+Note also that the reverse of a UTF-8 encoded string can in general
+not be obtained by g_strreverse(). This works only if the string
+does not contain any multibyte characters. GLib offers the
+g_utf8_strreverse() function to reverse UTF-8 encoded strings.
+ Use g_pattern_spec_match() instead
+
+
+ %TRUE if @string matches @pspec
+
+
+
+
+ a #GPatternSpec
+
+
+
+ the length of @string (in bytes, i.e. strlen(),
+ not g_utf8_strlen())
+
+
+
+ the UTF-8 encoded string to match
+
+
+
+ the reverse of @string or %NULL
+
+
+
+
+
+ Matches a string against a pattern given as a string. If this
+function is to be called in a loop, it's more efficient to compile
+the pattern once with g_pattern_spec_new() and call
+g_pattern_match_string() repeatedly.
+
+
+ %TRUE if @string matches @pspec
+
+
+
+
+ the UTF-8 encoded pattern
+
+
+
+ the UTF-8 encoded string to match
+
+
+
+
+
+ Matches a string against a compiled pattern. If the string is to be
+matched against more than one pattern, consider using
+g_pattern_match() instead while supplying the reversed string.
+ Use g_pattern_spec_match_string() instead
+
+
+ %TRUE if @string matches @pspec
+
+
+
+
+ a #GPatternSpec
+
+
+
+ the UTF-8 encoded string to match
+
+
+
+
+
+ The g_pattern_match* functions match a string
+against a pattern containing '*' and '?' wildcards with similar
+semantics as the standard glob() function: '*' matches an arbitrary,
+possibly empty, string, '?' matches an arbitrary character.
+
+Note that in contrast to glob(), the '/' character can be matched by
+the wildcards, there are no '[...]' character ranges and '*' and '?'
+can not be escaped to include them literally in a pattern.
+
+When multiple strings must be matched against the same pattern, it
+is better to compile the pattern to a #GPatternSpec using
+g_pattern_spec_new() and use g_pattern_match_string() instead of
+g_pattern_match_simple(). This avoids the overhead of repeated
+pattern compilation.
+
+
+ This is equivalent to g_bit_lock, but working on pointers (or other
+pointer-sized values).
+
+For portability reasons, you may only lock on the bottom 32 bits of
+the pointer.
+
+While @address has a `volatile` qualifier, this is a historical
+artifact and the argument passed to it should not be `volatile`.
+
+
+
+
+
+
+ a pointer to a #gpointer-sized value
+
+
+
+ a bit value between 0 and 31
+
+
+
+
+
+ This is equivalent to g_bit_trylock(), but working on pointers (or
+other pointer-sized values).
+
+For portability reasons, you may only lock on the bottom 32 bits of
+the pointer.
+
+While @address has a `volatile` qualifier, this is a historical
+artifact and the argument passed to it should not be `volatile`.
+
+
+ %TRUE if the lock was acquired
+
+
+
+
+ a pointer to a #gpointer-sized value
+
+
+
+ a bit value between 0 and 31
+
+
+
+
+
+ This is equivalent to g_bit_unlock, but working on pointers (or other
+pointer-sized values).
+
+For portability reasons, you may only lock on the bottom 32 bits of
+the pointer.
+
+While @address has a `volatile` qualifier, this is a historical
+artifact and the argument passed to it should not be `volatile`.
+
+
+
+
+
+
+ a pointer to a #gpointer-sized value
+
+
+
+ a bit value between 0 and 31
+
+
+
+
+
+ Polls @fds, as with the poll() system call, but portably. (On
+systems that don't have poll(), it is emulated using select().)
+This is used internally by #GMainContext, but it can be called
+directly if you need to block until a file descriptor is ready, but
+don't want to run the full main loop.
+
+Each element of @fds is a #GPollFD describing a single file
+descriptor to poll. The @fd field indicates the file descriptor,
+and the @events field indicates the events to poll for. On return,
+the @revents fields will be filled with the events that actually
+occurred.
+
+On POSIX systems, the file descriptors in @fds can be any sort of
+file descriptor, but the situation is much more complicated on
+Windows. If you need to use g_poll() in code that has to run on
+Windows, the easiest solution is to construct all of your
+#GPollFDs with g_io_channel_win32_make_pollfd().
+
+
+ the number of entries in @fds whose @revents fields
+were filled in, or 0 if the operation timed out, or -1 on error or
+if the call was interrupted.
+
+
+
+
+ file descriptors to poll
+
+
+
+ the number of file descriptors in @fds
+
+
+
+ amount of time to wait, in milliseconds, or -1 to wait forever
+
+
+
+
+
+ Formats a string according to @format and prefix it to an existing
+error message. If @err is %NULL (ie: no error variable) then do
+nothing.
+
+If *@err is %NULL (ie: an error variable is present but there is no
+error condition) then also do nothing.
+
+
+
+
+
+
+ a return location for a #GError
+
+
+
+ printf()-style format string
+
+
+
+ arguments to @format
+
+
+
+
+
+ Prefixes @prefix to an existing error message. If @err or *@err is
+%NULL (i.e.: no error variable) then do nothing.
+
+
+
+
+
+
+ a return location for a #GError, or %NULL
+
+
+
+ string to prefix @err with
+
+
+
+
+
+ Outputs a formatted message via the print handler.
+The default print handler outputs the encoded message to stdout, without
+appending a trailing new-line character. Typically, @format should end with
+its own new-line character.
+
+g_print() should not be used from within libraries for debugging
+messages, since it may be redirected by applications to special
+purpose message windows or even files. Instead, libraries should
+use g_log(), g_log_structured(), or the convenience macros g_message(),
+g_warning() and g_error().
+
+
+
+
+
+
+ the message format. See the printf() documentation
+
+
+
+ the parameters to insert into the format string
+
+
+
+
+
+ Outputs a formatted message via the error message handler.
+The default handler outputs the encoded message to stderr, without appending
+a trailing new-line character. Typically, @format should end with its own
+new-line character.
+
+g_printerr() should not be used from within libraries.
+Instead g_log() or g_log_structured() should be used, or the convenience
+macros g_message(), g_warning() and g_error().
+
+
+
+
+
+
+ the message format. See the printf() documentation
+
+
+
+ the parameters to insert into the format string
+
+
+
+
+
+ An implementation of the standard printf() function which supports
+positional parameters, as specified in the Single Unix Specification.
+
+As with the standard printf(), this does not automatically append a trailing
+new-line character to the message, so typically @format should end with its
+own new-line character.
+
+`glib/gprintf.h` must be explicitly included in order to use this function.
+
+
+ the number of bytes printed.
+
+
+
+
+ a standard printf() format string, but notice
+ [string precision pitfalls][string-precision]
+
+
+
+ the arguments to insert in the output.
+
+
+
+
+
+ Calculates the maximum space needed to store the output
+of the sprintf() function.
+
+
+ the maximum space needed to store the formatted string
+
+
+
+
+ the format string. See the printf() documentation
+
+
+
+ the parameters to be inserted into the format string
+
+
+
+
+
+ If @dest is %NULL, free @src; otherwise, moves @src into *@dest.
+The error variable @dest points to must be %NULL.
+
+@src must be non-%NULL.
+
+Note that @src is no longer valid after this call. If you want
+to keep using the same GError*, you need to set it to %NULL
+after calling this function on it.
+
+
+
+
+
+
+ error return location
+
+
+
+ error to move into the return location
+
+
+
+
+
+ If @dest is %NULL, free @src; otherwise, moves @src into *@dest.
+*@dest must be %NULL. After the move, add a prefix as with
+g_prefix_error().
+
+
+
+
+
+
+ error return location
+
+
+
+ error to move into the return location
+
+
+
+ printf()-style format string
+
+
+
+ arguments to @format
+
+
+
+
+
+ Checks whether @needle exists in @haystack. If the element is found, %TRUE is
+returned and the element’s index is returned in @index_ (if non-%NULL).
+Otherwise, %FALSE is returned and @index_ is undefined. If @needle exists
+multiple times in @haystack, the index of the first instance is returned.
+
+This does pointer comparisons only. If you want to use more complex equality
+checks, such as string comparisons, use g_ptr_array_find_with_equal_func().
+
+
+ %TRUE if @needle is one of the elements of @haystack
+
+
+
+
+ pointer array to be searched
+
+
+
+
+
+ pointer to look for
+
+
+
+ return location for the index of
+ the element, if found
+
+
+
+
+
+ Checks whether @needle exists in @haystack, using the given @equal_func.
+If the element is found, %TRUE is returned and the element’s index is
+returned in @index_ (if non-%NULL). Otherwise, %FALSE is returned and @index_
+is undefined. If @needle exists multiple times in @haystack, the index of
+the first instance is returned.
+
+@equal_func is called with the element from the array as its first parameter,
+and @needle as its second parameter. If @equal_func is %NULL, pointer
+equality is used.
+
+
+ %TRUE if @needle is one of the elements of @haystack
+
+
+
+
+ pointer array to be searched
+
+
+
+
+
+ pointer to look for
+
+
+
+ the function to call for each element, which should
+ return %TRUE when the desired element is found; or %NULL to use pointer
+ equality
+
+
+
+ return location for the index of
+ the element, if found
+
+
+
+
+
+ Returns the pointer at the given index of the pointer array.
+
+This does not perform bounds checking on the given @index_,
+so you are responsible for checking it against the array length.
+
+
+
+ a #GPtrArray
+
+
+ the index of the pointer to return
+
+
+
+
+ Creates a new #GPtrArray, copying @len pointers from @data, and setting
+the array’s reference count to 1.
+
+This avoids having to manually add each element one by one.
+
+If @copy_func is provided, then it is used to copy each element before
+adding them to the new array. If it is %NULL then the pointers are copied
+directly.
+
+It also sets @element_free_func for freeing each element when the array is
+destroyed either via g_ptr_array_unref(), when g_ptr_array_free() is called
+with @free_segment set to %TRUE or when removing elements.
+
+Do not use it if @len is greater than %G_MAXUINT. #GPtrArray
+stores the length of its data in #guint, which may be shorter than
+#gsize.
+
+
+ A new #GPtrArray
+
+
+
+
+
+
+ an array of pointers,
+or %NULL for an empty array
+
+
+
+
+
+ the number of pointers in @data
+
+
+
+ a copy function used to copy every element in the
+ array or %NULL.
+
+
+
+ user data passed to @copy_func, or %NULL
+
+
+
+ a function to free elements on @array
+ destruction or %NULL
+
+
+
+
+
+ Creates a new #GPtrArray copying the pointers from @data after having
+computed the length of it and with a reference count of 1.
+This avoids having to manually add each element one by one.
+If @copy_func is provided, then it is used to copy the data in the new
+array.
+It also set @element_free_func for freeing each element when the array is
+destroyed either via g_ptr_array_unref(), when g_ptr_array_free() is called
+with @free_segment set to %TRUE or when removing elements.
+
+Do not use it if the @data has more than %G_MAXUINT elements. #GPtrArray
+stores the length of its data in #guint, which may be shorter than
+#gsize.
+
+
+ A new #GPtrArray
+
+
+
+
+
+
+ an array of
+ pointers, %NULL terminated; or %NULL for an empty array
+
+
+
+
+
+ a copy function used to copy every element in the
+ array or %NULL.
+
+
+
+ user data passed to @copy_func, or %NULL
+
+
+
+ a function to free elements on @array
+ destruction or %NULL
+
+
+
+
+
+ Creates a new #GPtrArray with @data as pointers, @len as length and a
+reference count of 1.
+
+This avoids having to copy such data manually. @data will eventually be
+freed using g_free(), so must have been allocated with a suitable allocator.
+
+It also sets @element_free_func for freeing each element when the array is
+destroyed either via g_ptr_array_unref(), when g_ptr_array_free() is called
+with @free_segment set to %TRUE or when removing elements.
+
+Do not use it if @len is greater than %G_MAXUINT. #GPtrArray
+stores the length of its data in #guint, which may be shorter than
+#gsize.
+
+
+ A new #GPtrArray
+
+
+
+
+
+
+ an array of pointers,
+ or %NULL for an empty array
+
+
+
+
+
+ the number of pointers in @data
+
+
+
+ A function to free elements on @array
+ destruction or %NULL
+
+
+
+
+
+ Creates a new #GPtrArray with @data as pointers, computing the length of it
+and setting the reference count to 1.
+
+This avoids having to copy such data manually. @data will eventually be
+freed using g_free(), so must have been allocated with a suitable allocator.
+
+The length is calculated by iterating through @data until the first %NULL
+element is found.
+
+It also sets @element_free_func for freeing each element when the array is
+destroyed either via g_ptr_array_unref(), when g_ptr_array_free() is called
+with @free_segment set to %TRUE or when removing elements.
+
+Do not use it if the @data length is greater than %G_MAXUINT. #GPtrArray
+stores the length of its data in #guint, which may be shorter than
+#gsize.
+
+
+ A new #GPtrArray
+
+
+
+
+
+
+ an array
+ of pointers, %NULL terminated, or %NULL for an empty array
+
+
+
+
+
+ a function to free elements on @array
+ destruction or %NULL
+
+
+
+
+
+ This is just like the standard C qsort() function, but
+the comparison routine accepts a user data argument.
+
+This is guaranteed to be a stable sort since version 2.32.
+
+
+
+
+
+
+ start of array to sort
+
+
+
+ elements in the array
+
+
+
+ size of each element
+
+
+
+ function to compare elements
+
+
+
+ data to pass to @compare_func
+
+
+
+
+
+ Gets the #GQuark identifying the given (static) string. If the
+string does not currently have an associated #GQuark, a new #GQuark
+is created, linked to the given string.
+
+Note that this function is identical to g_quark_from_string() except
+that if a new #GQuark is created the string itself is used rather
+than a copy. This saves memory, but can only be used if the string
+will continue to exist until the program terminates. It can be used
+with statically allocated strings in the main program, but not with
+statically allocated memory in dynamically loaded modules, if you
+expect to ever unload the module again (e.g. do not use this
+function in GTK+ theme engines).
+
+This function must not be used before library constructors have finished
+running. In particular, this means it cannot be used to initialize global
+variables in C++.
+
+
+ the #GQuark identifying the string, or 0 if @string is %NULL
+
+
+
+
+ a string
+
+
+
+
+
+ Gets the #GQuark identifying the given string. If the string does
+not currently have an associated #GQuark, a new #GQuark is created,
+using a copy of the string.
+
+This function must not be used before library constructors have finished
+running. In particular, this means it cannot be used to initialize global
+variables in C++.
+
+
+ the #GQuark identifying the string, or 0 if @string is %NULL
+
+
+
+
+ a string
+
+
+
+
+
+ Gets the string associated with the given #GQuark.
+
+
+ the string associated with the #GQuark
+
+
+
+
+ a #GQuark.
+
+
+
+
+
+ Gets the #GQuark associated with the given string, or 0 if string is
+%NULL or it has no associated #GQuark.
+
+If you want the GQuark to be created if it doesn't already exist,
+use g_quark_from_string() or g_quark_from_static_string().
+
+This function must not be used before library constructors have finished
+running.
+
+
+ the #GQuark associated with the string, or 0 if @string is
+ %NULL or there is no #GQuark associated with it
+
+
+
+
+ a string
+
+
+
+
+
+ Quarks are associations between strings and integer identifiers.
+Given either the string or the #GQuark identifier it is possible to
+retrieve the other.
+
+Quarks are used for both [datasets][glib-Datasets] and
+[keyed data lists][glib-Keyed-Data-Lists].
+
+To create a new quark from a string, use g_quark_from_string() or
+g_quark_from_static_string().
+
+To find the string corresponding to a given #GQuark, use
+g_quark_to_string().
+
+To find the #GQuark corresponding to a given string, use
+g_quark_try_string().
+
+Another use for the string pool maintained for the quark functions
+is string interning, using g_intern_string() or
+g_intern_static_string(). An interned string is a canonical
+representation for a string. One important advantage of interned
+strings is that they can be compared for equality by a simple
+pointer comparison, rather than using strcmp().
+
+
+ The #GQueue structure and its associated functions provide a standard
+queue data structure. Internally, GQueue uses the same data structure
+as #GList to store elements with the same complexity over
+insertion/deletion (O(1)) and access/search (O(n)) operations.
+
+The data contained in each element can be either integer values, by
+using one of the [Type Conversion Macros][glib-Type-Conversion-Macros],
+or simply pointers to any type of data.
+
+As with all other GLib data structures, #GQueue is not thread-safe.
+For a thread-safe queue, use #GAsyncQueue.
+
+To create a new GQueue, use g_queue_new().
+
+To initialize a statically-allocated GQueue, use %G_QUEUE_INIT or
+g_queue_init().
+
+To add elements, use g_queue_push_head(), g_queue_push_head_link(),
+g_queue_push_tail() and g_queue_push_tail_link().
+
+To remove elements, use g_queue_pop_head() and g_queue_pop_tail().
+
+To free the entire queue, use g_queue_free().
+
+
+ Returns a random #gboolean from @rand_.
+This corresponds to an unbiased coin toss.
+
+
+
+ a #GRand
+
+
+
+
+ Returns a random #gboolean.
+This corresponds to an unbiased coin toss.
+
+
+
+ Returns a random #gdouble equally distributed over the range [0..1).
+
+
+ a random number
+
+
+
+
+ Returns a random #gdouble equally distributed over the range
+[@begin..@end).
+
+
+ a random number
+
+
+
+
+ lower closed bound of the interval
+
+
+
+ upper open bound of the interval
+
+
+
+
+
+ Return a random #guint32 equally distributed over the range
+[0..2^32-1].
+
+
+ a random number
+
+
+
+
+ Returns a random #gint32 equally distributed over the range
+[@begin..@end-1].
+
+
+ a random number
+
+
+
+
+ lower closed bound of the interval
+
+
+
+ upper open bound of the interval
+
+
+
+
+
+ The following functions allow you to use a portable, fast and good
+pseudo-random number generator (PRNG).
+
+Do not use this API for cryptographic purposes such as key
+generation, nonces, salts or one-time pads.
+
+This PRNG is suitable for non-cryptographic use such as in games
+(shuffling a card deck, generating levels), generating data for
+a test suite, etc. If you need random data for cryptographic
+purposes, it is recommended to use platform-specific APIs such
+as `/dev/random` on UNIX, or CryptGenRandom() on Windows.
+
+GRand uses the Mersenne Twister PRNG, which was originally
+developed by Makoto Matsumoto and Takuji Nishimura. Further
+information can be found at
+[this page](http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html).
+
+If you just need a random number, you simply call the g_random_*
+functions, which will create a globally used #GRand and use the
+according g_rand_* functions internally. Whenever you need a
+stream of reproducible random numbers, you better create a
+#GRand yourself and use the g_rand_* functions directly, which
+will also be slightly faster. Initializing a #GRand with a
+certain seed will produce exactly the same series of random
+numbers on all platforms. This can thus be used as a seed for
+e.g. games.
+
+The g_rand*_range functions will return high quality equally
+distributed random numbers, whereas for example the
+`(g_random_int()%max)` approach often
+doesn't yield equally distributed numbers.
+
+GLib changed the seeding algorithm for the pseudo-random number
+generator Mersenne Twister, as used by #GRand. This was necessary,
+because some seeds would yield very bad pseudo-random streams.
+Also the pseudo-random integers generated by g_rand*_int_range()
+will have a slightly better equal distribution with the new
+version of GLib.
+
+The original seeding and generation algorithms, as found in
+GLib 2.0.x, can be used instead of the new ones by setting the
+environment variable `G_RANDOM_VERSION` to the value of '2.0'.
+Use the GLib-2.0 algorithms only if you have sequences of numbers
+generated with Glib-2.0 that you need to reproduce exactly.
+
+
+ Sets the seed for the global random number generator, which is used
+by the g_random_* functions, to @seed.
+
+
+
+
+
+
+ a value to reinitialize the global random number generator
+
+
+
+
+
+ Acquires a reference on the data pointed by @mem_block.
+
+
+ a pointer to the data,
+ with its reference count increased
+
+
+
+
+ a pointer to reference counted data
+
+
+
+
+
+ Allocates @block_size bytes of memory, and adds reference
+counting semantics to it.
+
+The data will be freed when its reference count drops to
+zero.
+
+The allocated data is guaranteed to be suitably aligned for any
+built-in type.
+
+
+ a pointer to the allocated memory
+
+
+
+
+ the size of the allocation, must be greater than 0
+
+
+
+
+
+ Allocates @block_size bytes of memory, and adds reference
+counting semantics to it.
+
+The contents of the returned data is set to zero.
+
+The data will be freed when its reference count drops to
+zero.
+
+The allocated data is guaranteed to be suitably aligned for any
+built-in type.
+
+
+ a pointer to the allocated memory
+
+
+
+
+ the size of the allocation, must be greater than 0
+
+
+
+
+
+ Allocates a new block of data with reference counting
+semantics, and copies @block_size bytes of @mem_block
+into it.
+
+
+ a pointer to the allocated
+ memory
+
+
+
+
+ the number of bytes to copy, must be greater than 0
+
+
+
+ the memory to copy
+
+
+
+
+
+ Retrieves the size of the reference counted data pointed by @mem_block.
+
+
+ the size of the data, in bytes
+
+
+
+
+ a pointer to reference counted data
+
+
+
+
+
+ A convenience macro to allocate reference counted data with
+the size of the given @type.
+
+This macro calls g_rc_box_alloc() with `sizeof (@type)` and
+casts the returned pointer to a pointer of the given @type,
+avoiding a type cast in the source code.
+
+
+
+ the type to allocate, typically a structure name
+
+
+
+
+ A convenience macro to allocate reference counted data with
+the size of the given @type, and set its contents to zero.
+
+This macro calls g_rc_box_alloc0() with `sizeof (@type)` and
+casts the returned pointer to a pointer of the given @type,
+avoiding a type cast in the source code.
+
+
+
+ the type to allocate, typically a structure name
+
+
+
+
+ Releases a reference on the data pointed by @mem_block.
+
+If the reference was the last one, it will free the
+resources allocated for @mem_block.
+
+
+
+
+
+
+ a pointer to reference counted data
+
+
+
+
+
+ Releases a reference on the data pointed by @mem_block.
+
+If the reference was the last one, it will call @clear_func
+to clear the contents of @mem_block, and then will free the
+resources allocated for @mem_block.
+
+
+
+
+
+
+ a pointer to reference counted data
+
+
+
+ a function to call when clearing the data
+
+
+
+
+
+ A "reference counted box", or "RcBox", is an opaque wrapper data type
+that is guaranteed to be as big as the size of a given data type, and
+which augments the given data type with reference counting semantics
+for its memory management.
+
+RcBox is useful if you have a plain old data type, like a structure
+typically placed on the stack, and you wish to provide additional API
+to use it on the heap; or if you want to implement a new type to be
+passed around by reference without necessarily implementing copy/free
+semantics or your own reference counting.
+
+The typical use is:
+
+|[<!-- language="C" -->
+typedef struct {
+ char *name;
+ char *address;
+ char *city;
+ char *state;
+ int age;
+} Person;
+
+Person *
+person_new (void)
+{
+ return g_rc_box_new0 (Person);
+}
+]|
+
+Every time you wish to acquire a reference on the memory, you should
+call g_rc_box_acquire(); similarly, when you wish to release a reference
+you should call g_rc_box_release():
+
+|[<!-- language="C" -->
+// Add a Person to the Database; the Database acquires ownership
+// of the Person instance
+void
+add_person_to_database (Database *db, Person *p)
+{
+ db->persons = g_list_prepend (db->persons, g_rc_box_acquire (p));
+}
+
+// Removes a Person from the Database; the reference acquired by
+// add_person_to_database() is released here
+void
+remove_person_from_database (Database *db, Person *p)
+{
+ db->persons = g_list_remove (db->persons, p);
+ g_rc_box_release (p);
+}
+]|
+
+If you have additional memory allocated inside the structure, you can
+use g_rc_box_release_full(), which takes a function pointer, which
+will be called if the reference released was the last:
+
+|[<!-- language="C" -->
+void
+person_clear (Person *p)
+{
+ g_free (p->name);
+ g_free (p->address);
+ g_free (p->city);
+ g_free (p->state);
+}
+
+void
+remove_person_from_database (Database *db, Person *p)
+{
+ db->persons = g_list_remove (db->persons, p);
+ g_rc_box_release_full (p, (GDestroyNotify) person_clear);
+}
+]|
+
+If you wish to transfer the ownership of a reference counted data
+type without increasing the reference count, you can use g_steal_pointer():
+
+|[<!-- language="C" -->
+ Person *p = g_rc_box_new (Person);
+
+ // fill_person_details() is defined elsewhere
+ fill_person_details (p);
+
+ // add_person_to_database_no_ref() is defined elsewhere; it adds
+ // a Person to the Database without taking a reference
+ add_person_to_database_no_ref (db, g_steal_pointer (&p));
+]|
+
+## Thread safety
+
+The reference counting operations on data allocated using g_rc_box_alloc(),
+g_rc_box_new(), and g_rc_box_dup() are not thread safe; it is your code's
+responsibility to ensure that references are acquired are released on the
+same thread.
+
+If you need thread safe reference counting, see the [atomic reference counted
+data][arcbox] API.
+
+## Automatic pointer clean up
+
+If you want to add g_autoptr() support to your plain old data type through
+reference counting, you can use the G_DEFINE_AUTOPTR_CLEANUP_FUNC() and
+g_rc_box_release():
+
+|[<!-- language="C" -->
+G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, g_rc_box_release)
+]|
+
+If you need to clear the contents of the data, you will need to use an
+ancillary function that calls g_rc_box_release_full():
+
+|[<!-- language="C" -->
+static void
+my_data_struct_release (MyDataStruct *data)
+{
+ // my_data_struct_clear() is defined elsewhere
+ g_rc_box_release_full (data, (GDestroyNotify) my_data_struct_clear);
+}
+
+G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, my_data_struct_release)
+]|
+
+
+ Reallocates the memory pointed to by @mem, so that it now has space for
+@n_bytes bytes of memory. It returns the new address of the memory, which may
+have been moved. @mem may be %NULL, in which case it's considered to
+have zero-length. @n_bytes may be 0, in which case %NULL will be returned
+and @mem will be freed unless it is %NULL.
+
+If the allocation fails (because the system is out of memory),
+the program is terminated.
+
+
+ the new address of the allocated memory
+
+
+
+
+ the memory to reallocate
+
+
+
+ new size of the memory in bytes
+
+
+
+
+
+ This function is similar to g_realloc(), allocating (@n_blocks * @n_block_bytes) bytes,
+but care is taken to detect possible overflow during multiplication.
+
+If the allocation fails (because the system is out of memory),
+the program is terminated.
+
+
+ the new address of the allocated memory
+
+
+
+
+ the memory to reallocate
+
+
+
+ the number of blocks to allocate
+
+
+
+ the size of each block in bytes
+
+
+
+
+
+ Compares the current value of @rc with @val.
+
+
+ %TRUE if the reference count is the same
+ as the given value
+
+
+
+
+ the address of a reference count variable
+
+
+
+ the value to compare
+
+
+
+
+
+ Decreases the reference count.
+
+If %TRUE is returned, the reference count reached 0. After this point, @rc
+is an undefined state and must be reinitialized with
+g_ref_count_init() to be used again.
+
+
+ %TRUE if the reference count reached 0, and %FALSE otherwise
+
+
+
+
+ the address of a reference count variable
+
+
+
+
+
+ Increases the reference count.
+
+
+
+
+
+
+ the address of a reference count variable
+
+
+
+
+
+ Initializes a reference count variable to 1.
+
+
+
+
+
+
+ the address of a reference count variable
+
+
+
+
+
+ Acquires a reference on a string.
+
+
+ the given string, with its reference count increased
+
+
+
+
+ a reference counted string
+
+
+
+
+
+ Retrieves the length of @str.
+
+
+ the length of the given string, in bytes
+
+
+
+
+ a reference counted string
+
+
+
+
+
+ Creates a new reference counted string and copies the contents of @str
+into it.
+
+
+ the newly created reference counted string
+
+
+
+
+ a NUL-terminated string
+
+
+
+
+
+ Creates a new reference counted string and copies the content of @str
+into it.
+
+If you call this function multiple times with the same @str, or with
+the same contents of @str, it will return a new reference, instead of
+creating a new string.
+
+
+ the newly created reference
+ counted string, or a new reference to an existing string
+
+
+
+
+ a NUL-terminated string
+
+
+
+
+
+ Creates a new reference counted string and copies the contents of @str
+into it, up to @len bytes.
+
+Since this function does not stop at nul bytes, it is the caller's
+responsibility to ensure that @str has at least @len addressable bytes.
+
+
+ the newly created reference counted string
+
+
+
+
+ a string
+
+
+
+ length of @str to use, or -1 if @str is nul-terminated
+
+
+
+
+
+ Releases a reference on a string; if it was the last reference, the
+resources allocated by the string are freed as well.
+
+
+
+
+
+
+ a reference counted string
+
+
+
+
+
+ Reference counting is a garbage collection mechanism that is based on
+assigning a counter to a data type, or any memory area; the counter is
+increased whenever a new reference to that data type is acquired, and
+decreased whenever the reference is released. Once the last reference
+is released, the resources associated to that data type are freed.
+
+GLib uses reference counting in many of its data types, and provides
+the #grefcount and #gatomicrefcount types to implement safe and atomic
+reference counting semantics in new data types.
+
+It is important to note that #grefcount and #gatomicrefcount should be
+considered completely opaque types; you should always use the provided
+API to increase and decrease the counters, and you should never check
+their content directly, or compare their content with other values.
+
+
+ Reference counted strings are normal C strings that have been augmented
+with a reference counter to manage their resources. You allocate a new
+reference counted string and acquire and release references as needed,
+instead of copying the string among callers; when the last reference on
+the string is released, the resources allocated for it are freed.
+
+Typically, reference counted strings can be used when parsing data from
+files and storing them into data structures that are passed to various
+callers:
+
+|[<!-- language="C" -->
+PersonDetails *
+person_details_from_data (const char *data)
+{
+ // Use g_autoptr() to simplify error cases
+ g_autoptr(GRefString) full_name = NULL;
+ g_autoptr(GRefString) address = NULL;
+ g_autoptr(GRefString) city = NULL;
+ g_autoptr(GRefString) state = NULL;
+ g_autoptr(GRefString) zip_code = NULL;
+
+ // parse_person_details() is defined elsewhere; returns refcounted strings
+ if (!parse_person_details (data, &full_name, &address, &city, &state, &zip_code))
+ return NULL;
+
+ if (!validate_zip_code (zip_code))
+ return NULL;
+
+ // add_address_to_cache() and add_full_name_to_cache() are defined
+ // elsewhere; they add strings to various caches, using refcounted
+ // strings to avoid copying data over and over again
+ add_address_to_cache (address, city, state, zip_code);
+ add_full_name_to_cache (full_name);
+
+ // person_details_new() is defined elsewhere; it takes a reference
+ // on each string
+ PersonDetails *res = person_details_new (full_name,
+ address,
+ city,
+ state,
+ zip_code);
+
+ return res;
+}
+]|
+
+In the example above, we have multiple functions taking the same strings
+for different uses; with typical C strings, we'd have to copy the strings
+every time the life time rules of the data differ from the life time of
+the string parsed from the original buffer. With reference counted strings,
+each caller can take a reference on the data, and keep it as long as it
+needs to own the string.
+
+Reference counted strings can also be "interned" inside a global table
+owned by GLib; while an interned string has at least a reference, creating
+a new interned reference counted string with the same contents will return
+a reference to the existing string instead of creating a new reference
+counted string instance. Once the string loses its last reference, it will
+be automatically removed from the global interned strings table.
+
+
+ Checks whether @replacement is a valid replacement string
+(see g_regex_replace()), i.e. that all escape sequences in
+it are valid.
+
+If @has_references is not %NULL then @replacement is checked
+for pattern references. For instance, replacement text 'foo\n'
+does not contain references and may be evaluated without information
+about actual match, but '\0\1' (whole match followed by first
+subpattern) requires valid #GMatchInfo object.
+
+
+ whether @replacement is a valid replacement string
+
+
+
+
+ the replacement string
+
+
+
+ location to store information about
+ references in @replacement or %NULL
+
+
+
+
+
+
+
+
+
+
+ Escapes the nul characters in @string to "\x00". It can be used
+to compile a regex with embedded nul characters.
+
+For completeness, @length can be -1 for a nul-terminated string.
+In this case the output string will be of course equal to @string.
+
+
+ a newly-allocated escaped string
+
+
+
+
+ the string to escape
+
+
+
+ the length of @string
+
+
+
+
+
+ Escapes the special characters used for regular expressions
+in @string, for instance "a.b*c" becomes "a\.b\*c". This
+function is useful to dynamically generate regular expressions.
+
+@string can contain nul characters that are replaced with "\0",
+in this case remember to specify the correct length of @string
+in @length.
+
+
+ a newly-allocated escaped string
+
+
+
+
+ the string to escape
+
+
+
+ the length of @string, in bytes, or -1 if @string is nul-terminated
+
+
+
+
+
+ Scans for a match in @string for @pattern.
+
+This function is equivalent to g_regex_match() but it does not
+require to compile the pattern with g_regex_new(), avoiding some
+lines of code when you need just to do a match without extracting
+substrings, capture counts, and so on.
+
+If this function is to be called on the same @pattern more than
+once, it's more efficient to compile the pattern once with
+g_regex_new() and then use g_regex_match().
+
+
+ %TRUE if the string matched, %FALSE otherwise
+
+
+
+
+ the regular expression
+
+
+
+ the string to scan for matches
+
+
+
+ compile options for the regular expression, or 0
+
+
+
+ match options, or 0
+
+
+
+
+
+ Breaks the string on the pattern, and returns an array of
+the tokens. If the pattern contains capturing parentheses,
+then the text for each of the substrings will also be returned.
+If the pattern does not match anywhere in the string, then the
+whole string is returned as the first token.
+
+This function is equivalent to g_regex_split() but it does
+not require to compile the pattern with g_regex_new(), avoiding
+some lines of code when you need just to do a split without
+extracting substrings, capture counts, and so on.
+
+If this function is to be called on the same @pattern more than
+once, it's more efficient to compile the pattern once with
+g_regex_new() and then use g_regex_split().
+
+As a special case, the result of splitting the empty string ""
+is an empty vector, not a vector containing a single string.
+The reason for this special case is that being able to represent
+an empty vector is typically more useful than consistent handling
+of empty elements. If you do need to represent empty elements,
+you'll need to check for the empty string before calling this
+function.
+
+A pattern that can match empty strings splits @string into
+separate characters wherever it matches the empty string between
+characters. For example splitting "ab c" using as a separator
+"\s*", you will get "a", "b" and "c".
+
+
+ a %NULL-terminated array of strings. Free
+it using g_strfreev()
+
+
+
+
+
+
+ the regular expression
+
+
+
+ the string to scan for matches
+
+
+
+ compile options for the regular expression, or 0
+
+
+
+ match options, or 0
+
+
+
+
+
+ Resets the cache used for g_get_user_special_dir(), so
+that the latest on-disk version is used. Call this only
+if you just changed the data on disk yourself.
+
+Due to thread safety issues this may cause leaking of strings
+that were previously returned from g_get_user_special_dir()
+that can't be freed. We ensure to only leak the data for
+the directories that actually changed value though.
+
+
+
+
+
+
+ Reallocates the memory pointed to by @mem, so that it now has space for
+@n_structs elements of type @struct_type. It returns the new address of
+the memory, which may have been moved.
+Care is taken to avoid overflow when calculating the size of the allocated block.
+
+
+
+ the type of the elements to allocate
+
+
+ the currently allocated memory
+
+
+ the number of elements to allocate
+
+
+
+
+
+
+
+
+
+
+
+ Internal function used to print messages from the public g_return_if_fail()
+and g_return_val_if_fail() macros.
+
+
+
+
+
+
+ log domain
+
+
+
+ function containing the assertion
+
+
+
+ expression which failed
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ A wrapper for the POSIX rmdir() function. The rmdir() function
+deletes a directory from the filesystem.
+
+See your C library manual for more details about how rmdir() works
+on your system.
+
+
+ 0 if the directory was successfully removed, -1 if an error
+ occurred
+
+
+
+
+ a pathname in the GLib file name encoding
+ (UTF-8 on Windows)
+
+
+
+
+
+ The #GScanner and its associated functions provide a
+general purpose lexical scanner.
+
+
+ Adds a symbol to the default scope.
+ Use g_scanner_scope_add_symbol() instead.
+
+
+
+ a #GScanner
+
+
+ the symbol to add
+
+
+ the value of the symbol
+
+
+
+
+ Calls a function for each symbol in the default scope.
+ Use g_scanner_scope_foreach_symbol() instead.
+
+
+
+ a #GScanner
+
+
+ the function to call with each symbol
+
+
+ data to pass to the function
+
+
+
+
+ There is no reason to use this macro, since it does nothing.
+ This macro does nothing.
+
+
+
+ a #GScanner
+
+
+
+
+ Removes a symbol from the default scope.
+ Use g_scanner_scope_remove_symbol() instead.
+
+
+
+ a #GScanner
+
+
+ the symbol to remove
+
+
+
+
+ There is no reason to use this macro, since it does nothing.
+ This macro does nothing.
+
+
+
+ a #GScanner
+
+
+
+
+ The #GSequence data structure has the API of a list, but is
+implemented internally with a balanced binary tree. This means that
+most of the operations (access, search, insertion, deletion, ...) on
+#GSequence are O(log(n)) in average and O(n) in worst case for time
+complexity. But, note that maintaining a balanced sorted list of n
+elements is done in time O(n log(n)).
+The data contained in each element can be either integer values, by using
+of the [Type Conversion Macros][glib-Type-Conversion-Macros], or simply
+pointers to any type of data.
+
+A #GSequence is accessed through "iterators", represented by a
+#GSequenceIter. An iterator represents a position between two
+elements of the sequence. For example, the "begin" iterator
+represents the gap immediately before the first element of the
+sequence, and the "end" iterator represents the gap immediately
+after the last element. In an empty sequence, the begin and end
+iterators are the same.
+
+Some methods on #GSequence operate on ranges of items. For example
+g_sequence_foreach_range() will call a user-specified function on
+each element with the given range. The range is delimited by the
+gaps represented by the passed-in iterators, so if you pass in the
+begin and end iterators, the range in question is the entire
+sequence.
+
+The function g_sequence_get() is used with an iterator to access the
+element immediately following the gap that the iterator represents.
+The iterator is said to "point" to that element.
+
+Iterators are stable across most operations on a #GSequence. For
+example an iterator pointing to some element of a sequence will
+continue to point to that element even after the sequence is sorted.
+Even moving an element to another sequence using for example
+g_sequence_move_range() will not invalidate the iterators pointing
+to it. The only operation that will invalidate an iterator is when
+the element it points to is removed from any sequence.
+
+To sort the data, either use g_sequence_insert_sorted() or
+g_sequence_insert_sorted_iter() to add data to the #GSequence or, if
+you want to add a large amount of data, it is more efficient to call
+g_sequence_sort() or g_sequence_sort_iter() after doing unsorted
+insertions.
+
+
+ Returns the data that @iter points to.
+
+
+ the data that @iter points to
+
+
+
+
+ a #GSequenceIter
+
+
+
+
+
+ Inserts a new item just before the item pointed to by @iter.
+
+
+ an iterator pointing to the new item
+
+
+
+
+ a #GSequenceIter
+
+
+
+ the data for the new item
+
+
+
+
+
+ Moves the item pointed to by @src to the position indicated by @dest.
+After calling this function @dest will point to the position immediately
+after @src. It is allowed for @src and @dest to point into different
+sequences.
+
+
+
+
+
+
+ a #GSequenceIter pointing to the item to move
+
+
+
+ a #GSequenceIter pointing to the position to which
+ the item is moved
+
+
+
+
+
+ Inserts the (@begin, @end) range at the destination pointed to by @dest.
+The @begin and @end iters must point into the same sequence. It is
+allowed for @dest to point to a different sequence than the one pointed
+into by @begin and @end.
+
+If @dest is %NULL, the range indicated by @begin and @end is
+removed from the sequence. If @dest points to a place within
+the (@begin, @end) range, the range does not move.
+
+
+
+
+
+
+ a #GSequenceIter
+
+
+
+ a #GSequenceIter
+
+
+
+ a #GSequenceIter
+
+
+
+
+
+ Finds an iterator somewhere in the range (@begin, @end). This
+iterator will be close to the middle of the range, but is not
+guaranteed to be exactly in the middle.
+
+The @begin and @end iterators must both point to the same sequence
+and @begin must come before or be equal to @end in the sequence.
+
+
+ a #GSequenceIter pointing somewhere in the
+ (@begin, @end) range
+
+
+
+
+ a #GSequenceIter
+
+
+
+ a #GSequenceIter
+
+
+
+
+
+ Removes the item pointed to by @iter. It is an error to pass the
+end iterator to this function.
+
+If the sequence has a data destroy function associated with it, this
+function is called on the data for the removed item.
+
+
+
+
+
+
+ a #GSequenceIter
+
+
+
+
+
+ Removes all items in the (@begin, @end) range.
+
+If the sequence has a data destroy function associated with it, this
+function is called on the data for the removed items.
+
+
+
+
+
+
+ a #GSequenceIter
+
+
+
+ a #GSequenceIter
+
+
+
+
+
+ Changes the data for the item pointed to by @iter to be @data. If
+the sequence has a data destroy function associated with it, that
+function is called on the existing data that @iter pointed to.
+
+
+
+
+
+
+ a #GSequenceIter
+
+
+
+ new data for the item
+
+
+
+
+
+ Swaps the items pointed to by @a and @b. It is allowed for @a and @b
+to point into difference sequences.
+
+
+
+
+
+
+ a #GSequenceIter
+
+
+
+ a #GSequenceIter
+
+
+
+
+
+ Sets a human-readable name for the application. This name should be
+localized if possible, and is intended for display to the user.
+Contrast with g_set_prgname(), which sets a non-localized name.
+g_set_prgname() will be called automatically by gtk_init(),
+but g_set_application_name() will not.
+
+Note that for thread safety reasons, this function can only
+be called once.
+
+The application name will be used in contexts such as error messages,
+or when displaying an application's name in the task list.
+
+
+
+
+
+
+ localized name of the application
+
+
+
+
+
+ Does nothing if @err is %NULL; if @err is non-%NULL, then *@err
+must be %NULL. A new #GError is created and assigned to *@err.
+
+
+
+
+
+
+ a return location for a #GError
+
+
+
+ error domain
+
+
+
+ error code
+
+
+
+ printf()-style format
+
+
+
+ args for @format
+
+
+
+
+
+ Does nothing if @err is %NULL; if @err is non-%NULL, then *@err
+must be %NULL. A new #GError is created and assigned to *@err.
+Unlike g_set_error(), @message is not a printf()-style format string.
+Use this function if @message contains text you don't have control over,
+that could include printf() escape sequences.
+
+
+
+
+
+
+ a return location for a #GError
+
+
+
+ error domain
+
+
+
+ error code
+
+
+
+ error message
+
+
+
+
+
+ Sets the name of the program. This name should not be localized,
+in contrast to g_set_application_name().
+
+If you are using #GApplication the program name is set in
+g_application_run(). In case of GDK or GTK+ it is set in
+gdk_init(), which is called by gtk_init() and the
+#GtkApplication::startup handler. The program name is found by
+taking the last component of @argv[0].
+
+Since GLib 2.72, this function can be called multiple times
+and is fully thread safe. Prior to GLib 2.72, this function
+could only be called once per process.
+
+
+
+
+
+
+ the name of the program.
+
+
+
+
+
+ Sets the print handler to @func, or resets it to the
+default GLib handler if %NULL.
+
+Any messages passed to g_print() will be output via
+the new handler. The default handler outputs
+the encoded message to stdout. By providing your own handler
+you can redirect the output, to a GTK+ widget or a
+log file for example.
+
+Since 2.76 this functions always returns a valid
+#GPrintFunc, and never returns %NULL. If no custom
+print handler was set, it will return the GLib
+default print handler and that can be re-used to
+decorate its output and/or to write to stderr
+in all platforms. Before GLib 2.76, this was %NULL.
+
+
+ the old print handler
+
+
+
+
+ the new print handler or %NULL to
+ reset to the default
+
+
+
+
+
+ Sets the handler for printing error messages to @func,
+or resets it to the default GLib handler if %NULL.
+
+Any messages passed to g_printerr() will be output via
+the new handler. The default handler outputs the encoded
+message to stderr. By providing your own handler you can
+redirect the output, to a GTK+ widget or a log file for
+example.
+
+Since 2.76 this functions always returns a valid
+#GPrintFunc, and never returns %NULL. If no custom error
+print handler was set, it will return the GLib default
+error print handler and that can be re-used to decorate
+its output and/or to write to stderr in all platforms.
+Before GLib 2.76, this was %NULL.
+
+
+ the old error message handler
+
+
+
+
+ he new error message handler or %NULL
+ to reset to the default
+
+
+
+
+
+ Sets an environment variable. On UNIX, both the variable's name and
+value can be arbitrary byte strings, except that the variable's name
+cannot contain '='. On Windows, they should be in UTF-8.
+
+Note that on some systems, when variables are overwritten, the memory
+used for the previous variables and its value isn't reclaimed.
+
+You should be mindful of the fact that environment variable handling
+in UNIX is not thread-safe, and your program may crash if one thread
+calls g_setenv() while another thread is calling getenv(). (And note
+that many functions, such as gettext(), call getenv() internally.)
+This function is only safe to use at the very start of your program,
+before creating any other threads (or creating objects that create
+worker threads of their own).
+
+If you need to set up the environment for a child process, you can
+use g_get_environ() to get an environment array, modify that with
+g_environ_setenv() and g_environ_unsetenv(), and then pass that
+array directly to execvpe(), g_spawn_async(), or the like.
+
+
+ %FALSE if the environment variable couldn't be set.
+
+
+
+
+ the environment variable to set, must not
+ contain '='.
+
+
+
+ the value for to set the variable to.
+
+
+
+ whether to change the variable if it already exists.
+
+
+
+
+
+ GLib provides the functions g_shell_quote() and g_shell_unquote()
+to handle shell-like quoting in strings. The function g_shell_parse_argv()
+parses a string similar to the way a POSIX shell (/bin/sh) would.
+
+Note that string handling in shells has many obscure and historical
+corner-cases which these functions do not necessarily reproduce. They
+are good enough in practice, though.
+
+
+
+
+
+
+
+ Parses a command line into an argument vector, in much the same way
+the shell would, but without many of the expansions the shell would
+perform (variable expansion, globs, operators, filename expansion,
+etc. are not supported).
+
+The results are defined to be the same as those you would get from
+a UNIX98 `/bin/sh`, as long as the input contains none of the
+unsupported shell expansions. If the input does contain such expansions,
+they are passed through literally.
+
+Possible errors are those from the %G_SHELL_ERROR domain.
+
+In particular, if @command_line is an empty string (or a string containing
+only whitespace), %G_SHELL_ERROR_EMPTY_STRING will be returned. It’s
+guaranteed that @argvp will be a non-empty array if this function returns
+successfully.
+
+Free the returned vector with g_strfreev().
+
+
+ %TRUE on success, %FALSE if error set
+
+
+
+
+ command line to parse
+
+
+
+ return location for number of args
+
+
+
+
+ return location for array of args
+
+
+
+
+
+
+
+ Quotes a string so that the shell (/bin/sh) will interpret the
+quoted string to mean @unquoted_string.
+
+If you pass a filename to the shell, for example, you should first
+quote it with this function.
+
+The return value must be freed with g_free().
+
+The quoting style used is undefined (single or double quotes may be
+used).
+
+
+ quoted string
+
+
+
+
+ a literal string
+
+
+
+
+
+ Unquotes a string as the shell (/bin/sh) would.
+
+This function only handles quotes; if a string contains file globs,
+arithmetic operators, variables, backticks, redirections, or other
+special-to-the-shell features, the result will be different from the
+result a real shell would produce (the variables, backticks, etc.
+will be passed through literally instead of being expanded).
+
+This function is guaranteed to succeed if applied to the result of
+g_shell_quote(). If it fails, it returns %NULL and sets the
+error.
+
+The @quoted_string need not actually contain quoted or escaped text;
+g_shell_unquote() simply goes through the string and unquotes/unescapes
+anything that the shell would. Both single and double quotes are
+handled, as are escapes including escaped newlines.
+
+The return value must be freed with g_free().
+
+Possible errors are in the %G_SHELL_ERROR domain.
+
+Shell quoting rules are a bit strange. Single quotes preserve the
+literal string exactly. escape sequences are not allowed; not even
+`\'` - if you want a `'` in the quoted text, you have to do something
+like `'foo'\''bar'`. Double quotes allow `$`, ```, `"`, `\`, and
+newline to be escaped with backslash. Otherwise double quotes
+preserve things literally.
+
+
+ an unquoted string
+
+
+
+
+ shell-quoted string
+
+
+
+
+
+ Performs a checked addition of @a and @b, storing the result in
+@dest.
+
+If the operation is successful, %TRUE is returned. If the operation
+overflows then the state of @dest is undefined and %FALSE is
+returned.
+
+
+
+ a pointer to the #gsize destination
+
+
+ the #gsize left operand
+
+
+ the #gsize right operand
+
+
+
+
+ Performs a checked multiplication of @a and @b, storing the result in
+@dest.
+
+If the operation is successful, %TRUE is returned. If the operation
+overflows then the state of @dest is undefined and %FALSE is
+returned.
+
+
+
+ a pointer to the #gsize destination
+
+
+ the #gsize left operand
+
+
+ the #gsize right operand
+
+
+
+
+ Allocates a block of memory from the libc allocator.
+
+The block address handed out can be expected to be aligned
+to at least `1 * sizeof (void*)`.
+
+Since GLib 2.76 this always uses the system malloc() implementation
+internally.
+
+
+ a pointer to the allocated memory block, which will
+ be %NULL if and only if @mem_size is 0
+
+
+
+
+ the number of bytes to allocate
+
+
+
+
+
+ Allocates a block of memory via g_slice_alloc() and initializes
+the returned memory to 0.
+
+Since GLib 2.76 this always uses the system malloc() implementation
+internally.
+
+
+ a pointer to the allocated block, which will be %NULL
+ if and only if @mem_size is 0
+
+
+
+
+ the number of bytes to allocate
+
+
+
+
+
+ Allocates a block of memory from the slice allocator
+and copies @block_size bytes into it from @mem_block.
+
+@mem_block must be non-%NULL if @block_size is non-zero.
+
+Since GLib 2.76 this always uses the system malloc() implementation
+internally.
+
+
+ a pointer to the allocated memory block,
+ which will be %NULL if and only if @mem_size is 0
+
+
+
+
+ the number of bytes to allocate
+
+
+
+ the memory to copy
+
+
+
+
+
+ A convenience macro to duplicate a block of memory using
+the slice allocator.
+
+It calls g_slice_copy() with `sizeof (@type)`
+and casts the returned pointer to a pointer of the given type,
+avoiding a type cast in the source code.
+
+This can never return %NULL.
+
+Since GLib 2.76 this always uses the system malloc() implementation
+internally.
+
+
+
+ the type to duplicate, typically a structure name
+
+
+ the memory to copy into the allocated block
+
+
+
+
+ A convenience macro to free a block of memory that has
+been allocated from the slice allocator.
+
+It calls g_slice_free1() using `sizeof (type)`
+as the block size.
+Note that the exact release behaviour can be changed with the
+[`G_DEBUG=gc-friendly`][G_DEBUG] environment variable.
+
+If @mem is %NULL, this macro does nothing.
+
+Since GLib 2.76 this always uses the system free() implementation internally.
+
+
+
+ the type of the block to free, typically a structure name
+
+
+ a pointer to the block to free
+
+
+
+
+ Frees a block of memory.
+
+The memory must have been allocated via g_slice_alloc() or
+g_slice_alloc0() and the @block_size has to match the size
+specified upon allocation. Note that the exact release behaviour
+can be changed with the [`G_DEBUG=gc-friendly`][G_DEBUG] environment
+variable.
+
+If @mem_block is %NULL, this function does nothing.
+
+Since GLib 2.76 this always uses the system free_sized() implementation
+internally.
+
+
+
+
+
+
+ the size of the block
+
+
+
+ a pointer to the block to free
+
+
+
+
+
+ Frees a linked list of memory blocks of structure type @type.
+
+The memory blocks must be equal-sized, allocated via
+g_slice_alloc() or g_slice_alloc0() and linked together by
+a @next pointer (similar to #GSList). The name of the
+@next field in @type is passed as third argument.
+Note that the exact release behaviour can be changed with the
+[`G_DEBUG=gc-friendly`][G_DEBUG] environment variable.
+
+If @mem_chain is %NULL, this function does nothing.
+
+Since GLib 2.76 this always uses the system free() implementation internally.
+
+
+
+ the type of the @mem_chain blocks
+
+
+ a pointer to the first block of the chain
+
+
+ the field name of the next pointer in @type
+
+
+
+
+ Frees a linked list of memory blocks of structure type @type.
+
+The memory blocks must be equal-sized, allocated via
+g_slice_alloc() or g_slice_alloc0() and linked together by a
+@next pointer (similar to #GSList). The offset of the @next
+field in each block is passed as third argument.
+Note that the exact release behaviour can be changed with the
+[`G_DEBUG=gc-friendly`][G_DEBUG] environment variable.
+
+If @mem_chain is %NULL, this function does nothing.
+
+Since GLib 2.76 this always uses the system free_sized() implementation
+internally.
+
+
+
+
+
+
+ the size of the blocks
+
+
+
+ a pointer to the first block of the chain
+
+
+
+ the offset of the @next field in the blocks
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ A convenience macro to allocate a block of memory from the
+slice allocator.
+
+It calls g_slice_alloc() with `sizeof (@type)` and casts the
+returned pointer to a pointer of the given type, avoiding a type
+cast in the source code.
+
+This can never return %NULL as the minimum allocation size from
+`sizeof (@type)` is 1 byte.
+
+Since GLib 2.76 this always uses the system malloc() implementation
+internally.
+
+
+
+ the type to allocate, typically a structure name
+
+
+
+
+ A convenience macro to allocate a block of memory from the
+slice allocator and set the memory to 0.
+
+It calls g_slice_alloc0() with `sizeof (@type)`
+and casts the returned pointer to a pointer of the given type,
+avoiding a type cast in the source code.
+
+This can never return %NULL as the minimum allocation size from
+`sizeof (@type)` is 1 byte.
+
+Since GLib 2.76 this always uses the system malloc() implementation
+internally.
+
+
+
+ the type to allocate, typically a structure name
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ A convenience macro to get the next element in a #GSList.
+Note that it is considered perfectly acceptable to access
+@slist->next directly.
+
+
+
+ an element in a #GSList.
+
+
+
+
+ A safer form of the standard sprintf() function. The output is guaranteed
+to not exceed @n characters (including the terminating nul character), so
+it is easy to ensure that a buffer overflow cannot occur.
+
+See also g_strdup_printf().
+
+In versions of GLib prior to 1.2.3, this function may return -1 if the
+output was truncated, and the truncated string may not be nul-terminated.
+In versions prior to 1.3.12, this function returns the length of the output
+string.
+
+The return value of g_snprintf() conforms to the snprintf()
+function as standardized in ISO C99. Note that this is different from
+traditional snprintf(), which returns the length of the output string.
+
+The format string may contain positional parameters, as specified in
+the Single Unix Specification.
+
+
+ the number of bytes which would be produced if the buffer
+ was large enough.
+
+
+
+
+ the buffer to hold the output.
+
+
+
+ the maximum number of bytes to produce (including the
+ terminating nul character).
+
+
+
+ a standard printf() format string, but notice
+ [string precision pitfalls][string-precision]
+
+
+
+ the arguments to insert in the output.
+
+
+
+
+
+ Removes the source with the given ID from the default main context. You must
+use g_source_destroy() for sources added to a non-default main context.
+
+The ID of a #GSource is given by g_source_get_id(), or will be
+returned by the functions g_source_attach(), g_idle_add(),
+g_idle_add_full(), g_timeout_add(), g_timeout_add_full(),
+g_child_watch_add(), g_child_watch_add_full(), g_io_add_watch(), and
+g_io_add_watch_full().
+
+It is a programmer error to attempt to remove a non-existent source.
+
+More specifically: source IDs can be reissued after a source has been
+destroyed and therefore it is never valid to use this function with a
+source ID which may have already been removed. An example is when
+scheduling an idle to run in another thread with g_idle_add(): the
+idle may already have run and been removed by the time this function
+is called on its (now invalid) source ID. This source ID may have
+been reissued, leading to the operation being performed against the
+wrong source.
+
+
+ %TRUE if the source was found and removed.
+
+
+
+
+ the ID of the source to remove.
+
+
+
+
+
+ Removes a source from the default main loop context given the
+source functions and user data. If multiple sources exist with the
+same source functions and user data, only one will be destroyed.
+
+
+ %TRUE if a source was found and removed.
+
+
+
+
+ The @source_funcs passed to g_source_new()
+
+
+
+ the user data for the callback
+
+
+
+
+
+ Removes a source from the default main loop context given the user
+data for the callback. If multiple sources exist with the same user
+data, only one will be destroyed.
+
+
+ %TRUE if a source was found and removed.
+
+
+
+
+ the user_data for the callback.
+
+
+
+
+
+ Sets the name of a source using its ID.
+
+This is a convenience utility to set source names from the return
+value of g_idle_add(), g_timeout_add(), etc.
+
+It is a programmer error to attempt to set the name of a non-existent
+source.
+
+More specifically: source IDs can be reissued after a source has been
+destroyed and therefore it is never valid to use this function with a
+source ID which may have already been removed. An example is when
+scheduling an idle to run in another thread with g_idle_add(): the
+idle may already have run and been removed by the time this function
+is called on its (now invalid) source ID. This source ID may have
+been reissued, leading to the operation being performed against the
+wrong source.
+
+
+
+
+
+
+ a #GSource ID
+
+
+
+ debug name for the source
+
+
+
+
+
+ Gets the smallest prime number from a built-in array of primes which
+is larger than @num. This is used within GLib to calculate the optimum
+size of a #GHashTable.
+
+The built-in array of primes ranges from 11 to 13845163 such that
+each prime is approximately 1.5-2 times the previous prime.
+
+
+ the smallest prime number from a built-in array of primes
+ which is larger than @num
+
+
+
+
+ a #guint
+
+
+
+
+
+ GLib supports spawning of processes with an API that is more
+convenient than the bare UNIX fork() and exec().
+
+The g_spawn family of functions has synchronous (g_spawn_sync())
+and asynchronous variants (g_spawn_async(), g_spawn_async_with_pipes()),
+as well as convenience variants that take a complete shell-like
+commandline (g_spawn_command_line_sync(), g_spawn_command_line_async()).
+
+See #GSubprocess in GIO for a higher-level API that provides
+stream interfaces for communication with child processes.
+
+An example of using g_spawn_async_with_pipes():
+|[<!-- language="C" -->
+const gchar * const argv[] = { "my-favourite-program", "--args", NULL };
+gint child_stdout, child_stderr;
+GPid child_pid;
+g_autoptr(GError) error = NULL;
+
+// Spawn child process.
+g_spawn_async_with_pipes (NULL, argv, NULL, G_SPAWN_DO_NOT_REAP_CHILD, NULL,
+ NULL, &child_pid, NULL, &child_stdout,
+ &child_stderr, &error);
+if (error != NULL)
+ {
+ g_error ("Spawning child failed: %s", error->message);
+ return;
+ }
+
+// Add a child watch function which will be called when the child process
+// exits.
+g_child_watch_add (child_pid, child_watch_cb, NULL);
+
+// You could watch for output on @child_stdout and @child_stderr using
+// #GUnixInputStream or #GIOChannel here.
+
+static void
+child_watch_cb (GPid pid,
+ gint status,
+ gpointer user_data)
+{
+ g_message ("Child %" G_PID_FORMAT " exited %s", pid,
+ g_spawn_check_wait_status (status, NULL) ? "normally" : "abnormally");
+
+ // Free any resources associated with the child here, such as I/O channels
+ // on its stdout and stderr FDs. If you have no code to put in the
+ // child_watch_cb() callback, you can remove it and the g_child_watch_add()
+ // call, but you must also remove the G_SPAWN_DO_NOT_REAP_CHILD flag,
+ // otherwise the child process will stay around as a zombie until this
+ // process exits.
+
+ g_spawn_close_pid (pid);
+}
+]|
+
+
+ Executes a child program asynchronously.
+
+See g_spawn_async_with_pipes() for a full description; this function
+simply calls the g_spawn_async_with_pipes() without any pipes.
+
+You should call g_spawn_close_pid() on the returned child process
+reference when you don't need it any more.
+
+If you are writing a GTK application, and the program you are spawning is a
+graphical application too, then to ensure that the spawned program opens its
+windows on the right screen, you may want to use #GdkAppLaunchContext,
+#GAppLaunchContext, or set the %DISPLAY environment variable.
+
+Note that the returned @child_pid on Windows is a handle to the child
+process and not its identifier. Process handles and process identifiers
+are different concepts on Windows.
+
+
+ %TRUE on success, %FALSE if error is set
+
+
+
+
+ child's current working
+ directory, or %NULL to inherit parent's
+
+
+
+
+ child's argument vector
+
+
+
+
+
+
+ child's environment, or %NULL to inherit parent's
+
+
+
+
+
+ flags from #GSpawnFlags
+
+
+
+ function to run in the child just before exec()
+
+
+
+ user data for @child_setup
+
+
+
+ return location for child process reference, or %NULL
+
+
+
+
+
+ Executes a child program asynchronously.
+
+Identical to g_spawn_async_with_pipes_and_fds() but with `n_fds` set to zero,
+so no FD assignments are used.
+
+
+ %TRUE on success, %FALSE if an error was set
+
+
+
+
+ child's current working directory, or %NULL to inherit parent's, in the GLib file name encoding
+
+
+
+ child's argument vector, in the GLib file name encoding;
+ it must be non-empty and %NULL-terminated
+
+
+
+
+
+ child's environment, or %NULL to inherit parent's, in the GLib file name encoding
+
+
+
+
+
+ flags from #GSpawnFlags
+
+
+
+ function to run in the child just before exec()
+
+
+
+ user data for @child_setup
+
+
+
+ return location for child process ID, or %NULL
+
+
+
+ file descriptor to use for child's stdin, or `-1`
+
+
+
+ file descriptor to use for child's stdout, or `-1`
+
+
+
+ file descriptor to use for child's stderr, or `-1`
+
+
+
+
+
+ Identical to g_spawn_async_with_pipes_and_fds() but with `n_fds` set to zero,
+so no FD assignments are used.
+
+
+ %TRUE on success, %FALSE if an error was set
+
+
+
+
+ child's current working
+ directory, or %NULL to inherit parent's, in the GLib file name encoding
+
+
+
+ child's argument
+ vector, in the GLib file name encoding; it must be non-empty and %NULL-terminated
+
+
+
+
+
+
+ child's environment, or %NULL to inherit parent's, in the GLib file
+ name encoding
+
+
+
+
+
+ flags from #GSpawnFlags
+
+
+
+ function to run in the child just before exec()
+
+
+
+ user data for @child_setup
+
+
+
+ return location for child process ID, or %NULL
+
+
+
+ return location for file descriptor to write to child's stdin, or %NULL
+
+
+
+ return location for file descriptor to read child's stdout, or %NULL
+
+
+
+ return location for file descriptor to read child's stderr, or %NULL
+
+
+
+
+
+ Executes a child program asynchronously (your program will not
+block waiting for the child to exit).
+
+The child program is specified by the only argument that must be
+provided, @argv. @argv should be a %NULL-terminated array of strings,
+to be passed as the argument vector for the child. The first string
+in @argv is of course the name of the program to execute. By default,
+the name of the program must be a full path. If @flags contains the
+%G_SPAWN_SEARCH_PATH flag, the `PATH` environment variable is used to
+search for the executable. If @flags contains the
+%G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the `PATH` variable from @envp
+is used to search for the executable. If both the
+%G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP flags are
+set, the `PATH` variable from @envp takes precedence over the
+environment variable.
+
+If the program name is not a full path and %G_SPAWN_SEARCH_PATH flag
+is not used, then the program will be run from the current directory
+(or @working_directory, if specified); this might be unexpected or even
+dangerous in some cases when the current directory is world-writable.
+
+On Windows, note that all the string or string vector arguments to
+this function and the other `g_spawn*()` functions are in UTF-8, the
+GLib file name encoding. Unicode characters that are not part of
+the system codepage passed in these arguments will be correctly
+available in the spawned program only if it uses wide character API
+to retrieve its command line. For C programs built with Microsoft's
+tools it is enough to make the program have a `wmain()` instead of
+`main()`. `wmain()` has a wide character argument vector as parameter.
+
+At least currently, mingw doesn't support `wmain()`, so if you use
+mingw to develop the spawned program, it should call
+g_win32_get_command_line() to get arguments in UTF-8.
+
+On Windows the low-level child process creation API `CreateProcess()`
+doesn't use argument vectors, but a command line. The C runtime
+library's `spawn*()` family of functions (which g_spawn_async_with_pipes()
+eventually calls) paste the argument vector elements together into
+a command line, and the C runtime startup code does a corresponding
+reconstruction of an argument vector from the command line, to be
+passed to `main()`. Complications arise when you have argument vector
+elements that contain spaces or double quotes. The `spawn*()` functions
+don't do any quoting or escaping, but on the other hand the startup
+code does do unquoting and unescaping in order to enable receiving
+arguments with embedded spaces or double quotes. To work around this
+asymmetry, g_spawn_async_with_pipes() will do quoting and escaping on
+argument vector elements that need it before calling the C runtime
+`spawn()` function.
+
+The returned @child_pid on Windows is a handle to the child
+process, not its identifier. Process handles and process
+identifiers are different concepts on Windows.
+
+@envp is a %NULL-terminated array of strings, where each string
+has the form `KEY=VALUE`. This will become the child's environment.
+If @envp is %NULL, the child inherits its parent's environment.
+
+@flags should be the bitwise OR of any flags you want to affect the
+function's behaviour. The %G_SPAWN_DO_NOT_REAP_CHILD means that the
+child will not automatically be reaped; you must use a child watch
+(g_child_watch_add()) to be notified about the death of the child process,
+otherwise it will stay around as a zombie process until this process exits.
+Eventually you must call g_spawn_close_pid() on the @child_pid, in order to
+free resources which may be associated with the child process. (On Unix,
+using a child watch is equivalent to calling waitpid() or handling
+the `SIGCHLD` signal manually. On Windows, calling g_spawn_close_pid()
+is equivalent to calling `CloseHandle()` on the process handle returned
+in @child_pid). See g_child_watch_add().
+
+Open UNIX file descriptors marked as `FD_CLOEXEC` will be automatically
+closed in the child process. %G_SPAWN_LEAVE_DESCRIPTORS_OPEN means that
+other open file descriptors will be inherited by the child; otherwise all
+descriptors except stdin/stdout/stderr will be closed before calling `exec()`
+in the child. %G_SPAWN_SEARCH_PATH means that @argv[0] need not be an
+absolute path, it will be looked for in the `PATH` environment
+variable. %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an
+absolute path, it will be looked for in the `PATH` variable from
+@envp. If both %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP
+are used, the value from @envp takes precedence over the environment.
+
+%G_SPAWN_CHILD_INHERITS_STDIN means that the child will inherit the parent's
+standard input (by default, the child's standard input is attached to
+`/dev/null`). %G_SPAWN_STDIN_FROM_DEV_NULL explicitly imposes the default
+behavior. Both flags cannot be enabled at the same time and, in both cases,
+the @stdin_pipe_out argument is ignored.
+
+%G_SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output
+will be discarded (by default, it goes to the same location as the parent's
+standard output). %G_SPAWN_CHILD_INHERITS_STDOUT explicitly imposes the
+default behavior. Both flags cannot be enabled at the same time and, in
+both cases, the @stdout_pipe_out argument is ignored.
+
+%G_SPAWN_STDERR_TO_DEV_NULL means that the child's standard error
+will be discarded (by default, it goes to the same location as the parent's
+standard error). %G_SPAWN_CHILD_INHERITS_STDERR explicitly imposes the
+default behavior. Both flags cannot be enabled at the same time and, in
+both cases, the @stderr_pipe_out argument is ignored.
+
+It is valid to pass the same FD in multiple parameters (e.g. you can pass
+a single FD for both @stdout_fd and @stderr_fd, and include it in
+@source_fds too).
+
+@source_fds and @target_fds allow zero or more FDs from this process to be
+remapped to different FDs in the spawned process. If @n_fds is greater than
+zero, @source_fds and @target_fds must both be non-%NULL and the same length.
+Each FD in @source_fds is remapped to the FD number at the same index in
+@target_fds. The source and target FD may be equal to simply propagate an FD
+to the spawned process. FD remappings are processed after standard FDs, so
+any target FDs which equal @stdin_fd, @stdout_fd or @stderr_fd will overwrite
+them in the spawned process.
+
+@source_fds is supported on Windows since 2.72.
+
+%G_SPAWN_FILE_AND_ARGV_ZERO means that the first element of @argv is
+the file to execute, while the remaining elements are the actual
+argument vector to pass to the file. Normally g_spawn_async_with_pipes()
+uses @argv[0] as the file to execute, and passes all of @argv to the child.
+
+@child_setup and @user_data are a function and user data. On POSIX
+platforms, the function is called in the child after GLib has
+performed all the setup it plans to perform (including creating
+pipes, closing file descriptors, etc.) but before calling `exec()`.
+That is, @child_setup is called just before calling `exec()` in the
+child. Obviously actions taken in this function will only affect
+the child, not the parent.
+
+On Windows, there is no separate `fork()` and `exec()` functionality.
+Child processes are created and run with a single API call,
+`CreateProcess()`. There is no sensible thing @child_setup
+could be used for on Windows so it is ignored and not called.
+
+If non-%NULL, @child_pid will on Unix be filled with the child's
+process ID. You can use the process ID to send signals to the child,
+or to use g_child_watch_add() (or `waitpid()`) if you specified the
+%G_SPAWN_DO_NOT_REAP_CHILD flag. On Windows, @child_pid will be
+filled with a handle to the child process only if you specified the
+%G_SPAWN_DO_NOT_REAP_CHILD flag. You can then access the child
+process using the Win32 API, for example wait for its termination
+with the `WaitFor*()` functions, or examine its exit code with
+`GetExitCodeProcess()`. You should close the handle with `CloseHandle()`
+or g_spawn_close_pid() when you no longer need it.
+
+If non-%NULL, the @stdin_pipe_out, @stdout_pipe_out, @stderr_pipe_out
+locations will be filled with file descriptors for writing to the child's
+standard input or reading from its standard output or standard error.
+The caller of g_spawn_async_with_pipes() must close these file descriptors
+when they are no longer in use. If these parameters are %NULL, the
+corresponding pipe won't be created.
+
+If @stdin_pipe_out is %NULL, the child's standard input is attached to
+`/dev/null` unless %G_SPAWN_CHILD_INHERITS_STDIN is set.
+
+If @stderr_pipe_out is NULL, the child's standard error goes to the same
+location as the parent's standard error unless %G_SPAWN_STDERR_TO_DEV_NULL
+is set.
+
+If @stdout_pipe_out is NULL, the child's standard output goes to the same
+location as the parent's standard output unless %G_SPAWN_STDOUT_TO_DEV_NULL
+is set.
+
+@error can be %NULL to ignore errors, or non-%NULL to report errors.
+If an error is set, the function returns %FALSE. Errors are reported
+even if they occur in the child (for example if the executable in
+`@argv[0]` is not found). Typically the `message` field of returned
+errors should be displayed to users. Possible errors are those from
+the %G_SPAWN_ERROR domain.
+
+If an error occurs, @child_pid, @stdin_pipe_out, @stdout_pipe_out,
+and @stderr_pipe_out will not be filled with valid values.
+
+If @child_pid is not %NULL and an error does not occur then the returned
+process reference must be closed using g_spawn_close_pid().
+
+On modern UNIX platforms, GLib can use an efficient process launching
+codepath driven internally by `posix_spawn()`. This has the advantage of
+avoiding the fork-time performance costs of cloning the parent process
+address space, and avoiding associated memory overcommit checks that are
+not relevant in the context of immediately executing a distinct process.
+This optimized codepath will be used provided that the following conditions
+are met:
+
+1. %G_SPAWN_DO_NOT_REAP_CHILD is set
+2. %G_SPAWN_LEAVE_DESCRIPTORS_OPEN is set
+3. %G_SPAWN_SEARCH_PATH_FROM_ENVP is not set
+4. @working_directory is %NULL
+5. @child_setup is %NULL
+6. The program is of a recognised binary format, or has a shebang.
+ Otherwise, GLib will have to execute the program through the
+ shell, which is not done using the optimized codepath.
+
+If you are writing a GTK application, and the program you are spawning is a
+graphical application too, then to ensure that the spawned program opens its
+windows on the right screen, you may want to use #GdkAppLaunchContext,
+#GAppLaunchContext, or set the `DISPLAY` environment variable.
+
+
+ %TRUE on success, %FALSE if an error was set
+
+
+
+
+ child's current working
+ directory, or %NULL to inherit parent's, in the GLib file name encoding
+
+
+
+ child's argument
+ vector, in the GLib file name encoding; it must be non-empty and %NULL-terminated
+
+
+
+
+
+
+ child's environment, or %NULL to inherit parent's, in the GLib file
+ name encoding
+
+
+
+
+
+ flags from #GSpawnFlags
+
+
+
+ function to run in the child just before `exec()`
+
+
+
+ user data for @child_setup
+
+
+
+ file descriptor to use for child's stdin, or `-1`
+
+
+
+ file descriptor to use for child's stdout, or `-1`
+
+
+
+ file descriptor to use for child's stderr, or `-1`
+
+
+
+ array of FDs from the parent
+ process to make available in the child process
+
+
+
+
+
+ array of FDs to remap
+ @source_fds to in the child process
+
+
+
+
+
+ number of FDs in @source_fds and @target_fds
+
+
+
+ return location for child process ID, or %NULL
+
+
+
+ return location for file descriptor to write to child's stdin, or %NULL
+
+
+
+ return location for file descriptor to read child's stdout, or %NULL
+
+
+
+ return location for file descriptor to read child's stderr, or %NULL
+
+
+
+
+
+ An old name for g_spawn_check_wait_status(), deprecated because its
+name is misleading.
+
+Despite the name of the function, @wait_status must be the wait status
+as returned by g_spawn_sync(), g_subprocess_get_status(), `waitpid()`,
+etc. On Unix platforms, it is incorrect for it to be the exit status
+as passed to `exit()` or returned by g_subprocess_get_exit_status() or
+`WEXITSTATUS()`.
+ Use g_spawn_check_wait_status() instead, and check whether your code is conflating wait and exit statuses.
+
+
+ %TRUE if child exited successfully, %FALSE otherwise (and
+ @error will be set)
+
+
+
+
+ A status as returned from g_spawn_sync()
+
+
+
+
+
+ Set @error if @wait_status indicates the child exited abnormally
+(e.g. with a nonzero exit code, or via a fatal signal).
+
+The g_spawn_sync() and g_child_watch_add() family of APIs return the
+status of subprocesses encoded in a platform-specific way.
+On Unix, this is guaranteed to be in the same format waitpid() returns,
+and on Windows it is guaranteed to be the result of GetExitCodeProcess().
+
+Prior to the introduction of this function in GLib 2.34, interpreting
+@wait_status required use of platform-specific APIs, which is problematic
+for software using GLib as a cross-platform layer.
+
+Additionally, many programs simply want to determine whether or not
+the child exited successfully, and either propagate a #GError or
+print a message to standard error. In that common case, this function
+can be used. Note that the error message in @error will contain
+human-readable information about the wait status.
+
+The @domain and @code of @error have special semantics in the case
+where the process has an "exit code", as opposed to being killed by
+a signal. On Unix, this happens if WIFEXITED() would be true of
+@wait_status. On Windows, it is always the case.
+
+The special semantics are that the actual exit code will be the
+code set in @error, and the domain will be %G_SPAWN_EXIT_ERROR.
+This allows you to differentiate between different exit codes.
+
+If the process was terminated by some means other than an exit
+status (for example if it was killed by a signal), the domain will be
+%G_SPAWN_ERROR and the code will be %G_SPAWN_ERROR_FAILED.
+
+This function just offers convenience; you can of course also check
+the available platform via a macro such as %G_OS_UNIX, and use
+WIFEXITED() and WEXITSTATUS() on @wait_status directly. Do not attempt
+to scan or parse the error message string; it may be translated and/or
+change in future versions of GLib.
+
+Prior to version 2.70, g_spawn_check_exit_status() provides the same
+functionality, although under a misleading name.
+
+
+ %TRUE if child exited successfully, %FALSE otherwise (and
+ @error will be set)
+
+
+
+
+ A platform-specific wait status as returned from g_spawn_sync()
+
+
+
+
+
+ On some platforms, notably Windows, the #GPid type represents a resource
+which must be closed to prevent resource leaking. g_spawn_close_pid()
+is provided for this purpose. It should be used on all platforms, even
+though it doesn't do anything under UNIX.
+
+
+
+
+
+
+ The process reference to close
+
+
+
+
+
+ A simple version of g_spawn_async() that parses a command line with
+g_shell_parse_argv() and passes it to g_spawn_async().
+
+Runs a command line in the background. Unlike g_spawn_async(), the
+%G_SPAWN_SEARCH_PATH flag is enabled, other flags are not. Note
+that %G_SPAWN_SEARCH_PATH can have security implications, so
+consider using g_spawn_async() directly if appropriate. Possible
+errors are those from g_shell_parse_argv() and g_spawn_async().
+
+The same concerns on Windows apply as for g_spawn_command_line_sync().
+
+
+ %TRUE on success, %FALSE if error is set
+
+
+
+
+ a command line
+
+
+
+
+
+ A simple version of g_spawn_sync() with little-used parameters
+removed, taking a command line instead of an argument vector.
+
+See g_spawn_sync() for full details.
+
+The @command_line argument will be parsed by g_shell_parse_argv().
+
+Unlike g_spawn_sync(), the %G_SPAWN_SEARCH_PATH flag is enabled.
+Note that %G_SPAWN_SEARCH_PATH can have security implications, so
+consider using g_spawn_sync() directly if appropriate.
+
+Possible errors are those from g_spawn_sync() and those
+from g_shell_parse_argv().
+
+If @wait_status is non-%NULL, the platform-specific status of
+the child is stored there; see the documentation of
+g_spawn_check_wait_status() for how to use and interpret this.
+On Unix platforms, note that it is usually not equal
+to the integer passed to `exit()` or returned from `main()`.
+
+On Windows, please note the implications of g_shell_parse_argv()
+parsing @command_line. Parsing is done according to Unix shell rules, not
+Windows command interpreter rules.
+Space is a separator, and backslashes are
+special. Thus you cannot simply pass a @command_line containing
+canonical Windows paths, like "c:\\program files\\app\\app.exe", as
+the backslashes will be eaten, and the space will act as a
+separator. You need to enclose such paths with single quotes, like
+"'c:\\program files\\app\\app.exe' 'e:\\folder\\argument.txt'".
+
+
+ %TRUE on success, %FALSE if an error was set
+
+
+
+
+ a command line
+
+
+
+ return location for child output
+
+
+
+
+
+ return location for child errors
+
+
+
+
+
+ return location for child wait status, as returned by waitpid()
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Executes a child synchronously (waits for the child to exit before returning).
+
+All output from the child is stored in @standard_output and @standard_error,
+if those parameters are non-%NULL. Note that you must set the
+%G_SPAWN_STDOUT_TO_DEV_NULL and %G_SPAWN_STDERR_TO_DEV_NULL flags when
+passing %NULL for @standard_output and @standard_error.
+
+If @wait_status is non-%NULL, the platform-specific status of
+the child is stored there; see the documentation of
+g_spawn_check_wait_status() for how to use and interpret this.
+On Unix platforms, note that it is usually not equal
+to the integer passed to `exit()` or returned from `main()`.
+
+Note that it is invalid to pass %G_SPAWN_DO_NOT_REAP_CHILD in
+@flags, and on POSIX platforms, the same restrictions as for
+g_child_watch_source_new() apply.
+
+If an error occurs, no data is returned in @standard_output,
+@standard_error, or @wait_status.
+
+This function calls g_spawn_async_with_pipes() internally; see that
+function for full details on the other parameters and details on
+how these functions work on Windows.
+
+
+ %TRUE on success, %FALSE if an error was set
+
+
+
+
+ child's current working
+ directory, or %NULL to inherit parent's
+
+
+
+
+ child's argument vector, which must be non-empty and %NULL-terminated
+
+
+
+
+
+
+ child's environment, or %NULL to inherit parent's
+
+
+
+
+
+ flags from #GSpawnFlags
+
+
+
+ function to run in the child just before exec()
+
+
+
+ user data for @child_setup
+
+
+
+ return location for child output, or %NULL
+
+
+
+
+
+ return location for child error messages, or %NULL
+
+
+
+
+
+ return location for child wait status, as returned by waitpid(), or %NULL
+
+
+
+
+
+ An implementation of the standard sprintf() function which supports
+positional parameters, as specified in the Single Unix Specification.
+
+Note that it is usually better to use g_snprintf(), to avoid the
+risk of buffer overflow.
+
+`glib/gprintf.h` must be explicitly included in order to use this function.
+
+See also g_strdup_printf().
+
+
+ the number of bytes printed.
+
+
+
+
+ A pointer to a memory buffer to contain the resulting string. It
+ is up to the caller to ensure that the allocated buffer is large
+ enough to hold the formatted result
+
+
+
+ a standard printf() format string, but notice
+ [string precision pitfalls][string-precision]
+
+
+
+ the arguments to insert in the output.
+
+
+
+
+
+ Sets @pp to %NULL, returning the value that was there before.
+
+Conceptually, this transfers the ownership of the pointer from the
+referenced variable to the "caller" of the macro (ie: "steals" the
+reference).
+
+The return value will be properly typed, according to the type of
+@pp.
+
+This can be very useful when combined with g_autoptr() to prevent the
+return value of a function from being automatically freed. Consider
+the following example (which only works on GCC and clang):
+
+|[
+GObject *
+create_object (void)
+{
+ g_autoptr(GObject) obj = g_object_new (G_TYPE_OBJECT, NULL);
+
+ if (early_error_case)
+ return NULL;
+
+ return g_steal_pointer (&obj);
+}
+]|
+
+It can also be used in similar ways for 'out' parameters and is
+particularly useful for dealing with optional out parameters:
+
+|[
+gboolean
+get_object (GObject **obj_out)
+{
+ g_autoptr(GObject) obj = g_object_new (G_TYPE_OBJECT, NULL);
+
+ if (early_error_case)
+ return FALSE;
+
+ if (obj_out)
+ *obj_out = g_steal_pointer (&obj);
+
+ return TRUE;
+}
+]|
+
+In the above example, the object will be automatically freed in the
+early error case and also in the case that %NULL was given for
+@obj_out.
+
+
+
+ a pointer to a pointer
+
+
+
+
+ Copies a nul-terminated string into the destination buffer, including
+the trailing nul byte, and returns a pointer to the trailing nul byte
+in `dest`. The return value is useful for concatenating multiple
+strings without having to repeatedly scan for the end.
+
+
+ a pointer to the trailing nul byte in `dest`.
+
+
+
+
+ destination buffer.
+
+
+
+ source string.
+
+
+
+
+
+ Compares two strings for byte-by-byte equality and returns %TRUE
+if they are equal. It can be passed to g_hash_table_new() as the
+@key_equal_func parameter, when using non-%NULL strings as keys in a
+#GHashTable.
+
+This function is typically used for hash table comparisons, but can be used
+for general purpose comparisons of non-%NULL strings. For a %NULL-safe string
+comparison function, see g_strcmp0().
+
+
+ %TRUE if the two keys match
+
+
+
+
+ a key
+
+
+
+ a key to compare with @v1
+
+
+
+
+
+ Looks whether the string @str begins with @prefix.
+
+
+ %TRUE if @str begins with @prefix, %FALSE otherwise.
+
+
+
+
+ a nul-terminated string
+
+
+
+ the nul-terminated prefix to look for
+
+
+
+
+
+ Looks whether the string @str ends with @suffix.
+
+
+ %TRUE if @str end with @suffix, %FALSE otherwise.
+
+
+
+
+ a nul-terminated string
+
+
+
+ the nul-terminated suffix to look for
+
+
+
+
+
+ Converts a string to a hash value.
+
+This function implements the widely used "djb" hash apparently
+posted by Daniel Bernstein to comp.lang.c some time ago. The 32
+bit unsigned hash value starts at 5381 and for each byte 'c' in
+the string, is updated: `hash = hash * 33 + c`. This function
+uses the signed value of each byte.
+
+It can be passed to g_hash_table_new() as the @hash_func parameter,
+when using non-%NULL strings as keys in a #GHashTable.
+
+Note that this function may not be a perfect fit for all use cases.
+For example, it produces some hash collisions with strings as short
+as 2.
+
+
+ a hash value corresponding to the key
+
+
+
+
+ a string key
+
+
+
+
+
+ Determines if a string is pure ASCII. A string is pure ASCII if it
+contains no bytes with the high bit set.
+
+
+ %TRUE if @str is ASCII
+
+
+
+
+ a string
+
+
+
+
+
+ Checks if a search conducted for @search_term should match
+@potential_hit.
+
+This function calls g_str_tokenize_and_fold() on both
+@search_term and @potential_hit. ASCII alternates are never taken
+for @search_term but will be taken for @potential_hit according to
+the value of @accept_alternates.
+
+A hit occurs when each folded token in @search_term is a prefix of a
+folded token from @potential_hit.
+
+Depending on how you're performing the search, it will typically be
+faster to call g_str_tokenize_and_fold() on each string in
+your corpus and build an index on the returned folded tokens, then
+call g_str_tokenize_and_fold() on the search term and
+perform lookups into that index.
+
+As some examples, searching for ‘fred’ would match the potential hit
+‘Smith, Fred’ and also ‘Frédéric’. Searching for ‘Fréd’ would match
+‘Frédéric’ but not ‘Frederic’ (due to the one-directional nature of
+accent matching). Searching ‘fo’ would match ‘Foo’ and ‘Bar Foo
+Baz’, but not ‘SFO’ (because no word has ‘fo’ as a prefix).
+
+
+ %TRUE if @potential_hit is a hit
+
+
+
+
+ the search term from the user
+
+
+
+ the text that may be a hit
+
+
+
+ %TRUE to accept ASCII alternates
+
+
+
+
+
+ Transliterate @str to plain ASCII.
+
+For best results, @str should be in composed normalised form.
+
+This function performs a reasonably good set of character
+replacements. The particular set of replacements that is done may
+change by version or even by runtime environment.
+
+If the source language of @str is known, it can used to improve the
+accuracy of the translation by passing it as @from_locale. It should
+be a valid POSIX locale string (of the form
+`language[_territory][.codeset][@modifier]`).
+
+If @from_locale is %NULL then the current locale is used.
+
+If you want to do translation for no specific locale, and you want it
+to be done independently of the currently locale, specify `"C"` for
+@from_locale.
+
+
+ a string in plain ASCII
+
+
+
+
+ a string, in UTF-8
+
+
+
+ the source locale, if known
+
+
+
+
+
+ Tokenises @string and performs folding on each token.
+
+A token is a non-empty sequence of alphanumeric characters in the
+source string, separated by non-alphanumeric characters. An
+"alphanumeric" character for this purpose is one that matches
+g_unichar_isalnum() or g_unichar_ismark().
+
+Each token is then (Unicode) normalised and case-folded. If
+@ascii_alternates is non-%NULL and some of the returned tokens
+contain non-ASCII characters, ASCII alternatives will be generated.
+
+The number of ASCII alternatives that are generated and the method
+for doing so is unspecified, but @translit_locale (if specified) may
+improve the transliteration if the language of the source string is
+known.
+
+
+ the folded tokens
+
+
+
+
+
+
+ a string
+
+
+
+ the language code (like 'de' or
+ 'en_GB') from which @string originates
+
+
+
+ a
+ return location for ASCII alternates
+
+
+
+
+
+
+
+ For each character in @string, if the character is not in @valid_chars,
+replaces the character with @substitutor.
+
+Modifies @string in place, and return @string itself, not a copy. The
+return value is to allow nesting such as:
+
+|[<!-- language="C" -->
+ g_ascii_strup (g_strcanon (str, "abc", '?'))
+]|
+
+In order to modify a copy, you may use g_strdup():
+
+|[<!-- language="C" -->
+ reformatted = g_strcanon (g_strdup (const_str), "abc", '?');
+ ...
+ g_free (reformatted);
+]|
+
+
+ the modified @string
+
+
+
+
+ a nul-terminated array of bytes
+
+
+
+ bytes permitted in @string
+
+
+
+ replacement character for disallowed bytes
+
+
+
+
+
+ A case-insensitive string comparison, corresponding to the standard
+strcasecmp() function on platforms which support it.
+ See g_strncasecmp() for a discussion of why this
+ function is deprecated and how to replace it.
+
+
+ 0 if the strings match, a negative value if @s1 < @s2,
+ or a positive value if @s1 > @s2.
+
+
+
+
+ a string
+
+
+
+ a string to compare with @s1
+
+
+
+
+
+ Removes trailing whitespace from a string.
+
+This function doesn't allocate or reallocate any memory;
+it modifies @string in place. Therefore, it cannot be used
+on statically allocated strings.
+
+The pointer to @string is returned to allow the nesting of functions.
+
+Also see g_strchug() and g_strstrip().
+
+
+ @string
+
+
+
+
+ a string to remove the trailing whitespace from
+
+
+
+
+
+ Removes leading whitespace from a string, by moving the rest
+of the characters forward.
+
+This function doesn't allocate or reallocate any memory;
+it modifies @string in place. Therefore, it cannot be used on
+statically allocated strings.
+
+The pointer to @string is returned to allow the nesting of functions.
+
+Also see g_strchomp() and g_strstrip().
+
+
+ @string
+
+
+
+
+ a string to remove the leading whitespace from
+
+
+
+
+
+ Compares @str1 and @str2 like strcmp(). Handles %NULL
+gracefully by sorting it before non-%NULL strings.
+Comparing two %NULL pointers returns 0.
+
+
+ an integer less than, equal to, or greater than zero, if @str1 is <, == or > than @str2.
+
+
+
+
+ a C string or %NULL
+
+
+
+ another C string or %NULL
+
+
+
+
+
+ Replaces all escaped characters with their one byte equivalent.
+
+This function does the reverse conversion of g_strescape().
+
+
+ a newly-allocated copy of @source with all escaped
+ character compressed
+
+
+
+
+ a string to compress
+
+
+
+
+
+ Concatenates all of the given strings into one long string. The
+returned string should be freed with g_free() when no longer needed.
+
+The variable argument list must end with %NULL. If you forget the %NULL,
+g_strconcat() will start appending random memory junk to your string.
+
+Note that this function is usually not the right function to use to
+assemble a translated message from pieces, since proper translation
+often requires the pieces to be reordered.
+
+
+ a newly-allocated string containing all the string arguments
+
+
+
+
+ the first string to add, which must not be %NULL
+
+
+
+ a %NULL-terminated list of strings to append to the string
+
+
+
+
+
+ Converts any delimiter characters in @string to @new_delimiter.
+
+Any characters in @string which are found in @delimiters are
+changed to the @new_delimiter character. Modifies @string in place,
+and returns @string itself, not a copy.
+
+The return value is to allow nesting such as:
+
+|[<!-- language="C" -->
+ g_ascii_strup (g_strdelimit (str, "abc", '?'))
+]|
+
+In order to modify a copy, you may use g_strdup():
+
+|[<!-- language="C" -->
+ reformatted = g_strdelimit (g_strdup (const_str), "abc", '?');
+ ...
+ g_free (reformatted);
+]|
+
+
+ the modified @string
+
+
+
+
+ the string to convert
+
+
+
+ a string containing the current delimiters,
+ or %NULL to use the standard delimiters defined in %G_STR_DELIMITERS
+
+
+
+ the new delimiter character
+
+
+
+
+
+ Converts a string to lower case.
+ This function is totally broken for the reasons discussed
+in the g_strncasecmp() docs - use g_ascii_strdown() or g_utf8_strdown()
+instead.
+
+
+ the string
+
+
+
+
+ the string to convert.
+
+
+
+
+
+ Duplicates a string. If @str is %NULL it returns %NULL.
+The returned string should be freed with g_free()
+when no longer needed.
+
+
+ a newly-allocated copy of @str
+
+
+
+
+ the string to duplicate
+
+
+
+
+
+ Similar to the standard C sprintf() function but safer, since it
+calculates the maximum space required and allocates memory to hold
+the result. The returned string should be freed with g_free() when no
+longer needed.
+
+The returned string is guaranteed to be non-NULL, unless @format
+contains `%lc` or `%ls` conversions, which can fail if no multibyte
+representation is available for the given character.
+
+
+ a newly-allocated string holding the result
+
+
+
+
+ a standard printf() format string, but notice
+ [string precision pitfalls][string-precision]
+
+
+
+ the parameters to insert into the format string
+
+
+
+
+
+ Similar to the standard C vsprintf() function but safer, since it
+calculates the maximum space required and allocates memory to hold
+the result. The returned string should be freed with g_free() when
+no longer needed.
+
+The returned string is guaranteed to be non-NULL, unless @format
+contains `%lc` or `%ls` conversions, which can fail if no multibyte
+representation is available for the given character.
+
+See also g_vasprintf(), which offers the same functionality, but
+additionally returns the length of the allocated string.
+
+
+ a newly-allocated string holding the result
+
+
+
+
+ a standard printf() format string, but notice
+ [string precision pitfalls][string-precision]
+
+
+
+ the list of parameters to insert into the format string
+
+
+
+
+
+ Copies %NULL-terminated array of strings. The copy is a deep copy;
+the new array should be freed by first freeing each string, then
+the array itself. g_strfreev() does this for you. If called
+on a %NULL value, g_strdupv() simply returns %NULL.
+
+
+ a new %NULL-terminated array of strings.
+
+
+
+
+
+
+ a %NULL-terminated array of strings
+
+
+
+
+
+ Returns a string corresponding to the given error code, e.g. "no
+such process". Unlike strerror(), this always returns a string in
+UTF-8 encoding, and the pointer is guaranteed to remain valid for
+the lifetime of the process.
+
+Note that the string may be translated according to the current locale.
+
+The value of %errno will not be changed by this function. However, it may
+be changed by intermediate function calls, so you should save its value
+as soon as the call returns:
+|[
+ int saved_errno;
+
+ ret = read (blah);
+ saved_errno = errno;
+
+ g_strerror (saved_errno);
+]|
+
+
+ a UTF-8 string describing the error code. If the error code
+ is unknown, it returns a string like "Unknown error: <code>".
+
+
+
+
+ the system error number. See the standard C %errno
+ documentation
+
+
+
+
+
+ Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\v', '\'
+and '"' in the string @source by inserting a '\' before
+them. Additionally all characters in the range 0x01-0x1F (everything
+below SPACE) and in the range 0x7F-0xFF (all non-ASCII chars) are
+replaced with a '\' followed by their octal representation.
+Characters supplied in @exceptions are not escaped.
+
+g_strcompress() does the reverse conversion.
+
+
+ a newly-allocated copy of @source with certain
+ characters escaped. See above.
+
+
+
+
+ a string to escape
+
+
+
+ a string of characters not to escape in @source
+
+
+
+
+
+ Frees a %NULL-terminated array of strings, as well as each
+string it contains.
+
+If @str_array is %NULL, this function simply returns.
+
+
+
+
+
+
+ a %NULL-terminated array of strings to free
+
+
+
+
+
+ String chunks are used to store groups of strings. Memory is
+allocated in blocks, and as strings are added to the #GStringChunk
+they are copied into the next free position in a block. When a block
+is full a new block is allocated.
+
+When storing a large number of strings, string chunks are more
+efficient than using g_strdup() since fewer calls to malloc() are
+needed, and less memory is wasted in memory allocation overheads.
+
+By adding strings with g_string_chunk_insert_const() it is also
+possible to remove duplicates.
+
+To create a new #GStringChunk use g_string_chunk_new().
+
+To add strings to a #GStringChunk use g_string_chunk_insert().
+
+To add strings to a #GStringChunk, but without duplicating strings
+which are already in the #GStringChunk, use
+g_string_chunk_insert_const().
+
+To free the entire #GStringChunk use g_string_chunk_free(). It is
+not possible to free individual strings.
+
+
+ This section describes a number of utility functions for creating,
+duplicating, and manipulating strings.
+
+Note that the functions g_printf(), g_fprintf(), g_sprintf(),
+g_vprintf(), g_vfprintf(), g_vsprintf() and g_vasprintf()
+are declared in the header `gprintf.h` which is not included in `glib.h`
+(otherwise using `glib.h` would drag in `stdio.h`), so you'll have to
+explicitly include `<glib/gprintf.h>` in order to use the GLib
+printf() functions.
+
+## String precision pitfalls # {#string-precision}
+
+While you may use the printf() functions to format UTF-8 strings,
+notice that the precision of a \%Ns parameter is interpreted
+as the number of bytes, not characters to print. On top of that,
+the GNU libc implementation of the printf() functions has the
+"feature" that it checks that the string given for the \%Ns
+parameter consists of a whole number of characters in the current
+encoding. So, unless you are sure you are always going to be in an
+UTF-8 locale or your know your text is restricted to ASCII, avoid
+using \%Ns. If your intention is to format strings for a
+certain number of columns, then \%Ns is not a correct solution
+anyway, since it fails to take wide characters (see g_unichar_iswide())
+into account.
+
+Note also that there are various printf() parameters which are platform
+dependent. GLib provides platform independent macros for these parameters
+which should be used instead. A common example is %G_GUINT64_FORMAT, which
+should be used instead of `%llu` or similar parameters for formatting
+64-bit integers. These macros are all named `G_*_FORMAT`; see
+[Basic Types][glib-Basic-Types].
+
+
+ A #GString is an object that handles the memory management of a C
+string for you. The emphasis of #GString is on text, typically
+UTF-8. Crucially, the "str" member of a #GString is guaranteed to
+have a trailing nul character, and it is therefore always safe to
+call functions such as strchr() or g_strdup() on it.
+
+However, a #GString can also hold arbitrary binary data, because it
+has a "len" member, which includes any possible embedded nul
+characters in the data. Conceptually then, #GString is like a
+#GByteArray with the addition of many convenience methods for text,
+and a guaranteed nul terminator.
+
+
+ An auxiliary function for gettext() support (see Q_()).
+
+
+ @msgval, unless @msgval is identical to @msgid
+ and contains a '|' character, in which case a pointer to
+ the substring of msgid after the first '|' character is returned.
+
+
+
+
+ a string
+
+
+
+ another string
+
+
+
+
+
+ Joins a number of strings together to form one long string, with the
+optional @separator inserted between each of them. The returned string
+should be freed with g_free().
+
+
+ a newly-allocated string containing all of the strings joined
+ together, with @separator between them
+
+
+
+
+ a string to insert between each of the
+ strings, or %NULL
+
+
+
+ a %NULL-terminated list of strings to join
+
+
+
+
+
+ Joins a number of strings together to form one long string, with the
+optional @separator inserted between each of them. The returned string
+should be freed with g_free().
+
+If @str_array has no items, the return value will be an
+empty string. If @str_array contains a single item, @separator will not
+appear in the resulting string.
+
+
+ a newly-allocated string containing all of the strings joined
+ together, with @separator between them
+
+
+
+
+ a string to insert between each of the
+ strings, or %NULL
+
+
+
+ a %NULL-terminated array of strings to join
+
+
+
+
+
+ Portability wrapper that calls strlcat() on systems which have it,
+and emulates it otherwise. Appends nul-terminated @src string to @dest,
+guaranteeing nul-termination for @dest. The total size of @dest won't
+exceed @dest_size.
+
+At most @dest_size - 1 characters will be copied. Unlike strncat(),
+@dest_size is the full size of dest, not the space left over. This
+function does not allocate memory. It always nul-terminates (unless
+@dest_size == 0 or there were no nul characters in the @dest_size
+characters of dest to start with).
+
+Caveat: this is supposedly a more secure alternative to strcat() or
+strncat(), but for real security g_strconcat() is harder to mess up.
+
+
+ size of attempted result, which is MIN (dest_size, strlen
+ (original dest)) + strlen (src), so if retval >= dest_size,
+ truncation occurred.
+
+
+
+
+ destination buffer, already containing one nul-terminated string
+
+
+
+ source buffer
+
+
+
+ length of @dest buffer in bytes (not length of existing string
+ inside @dest)
+
+
+
+
+
+ Portability wrapper that calls strlcpy() on systems which have it,
+and emulates strlcpy() otherwise. Copies @src to @dest; @dest is
+guaranteed to be nul-terminated; @src must be nul-terminated;
+@dest_size is the buffer size, not the number of bytes to copy.
+
+At most @dest_size - 1 characters will be copied. Always nul-terminates
+(unless @dest_size is 0). This function does not allocate memory. Unlike
+strncpy(), this function doesn't pad @dest (so it's often faster). It
+returns the size of the attempted result, strlen (src), so if
+@retval >= @dest_size, truncation occurred.
+
+Caveat: strlcpy() is supposedly more secure than strcpy() or strncpy(),
+but if you really want to avoid screwups, g_strdup() is an even better
+idea.
+
+
+ length of @src
+
+
+
+
+ destination buffer
+
+
+
+ source buffer
+
+
+
+ length of @dest in bytes
+
+
+
+
+
+ A case-insensitive string comparison, corresponding to the standard
+strncasecmp() function on platforms which support it. It is similar
+to g_strcasecmp() except it only compares the first @n characters of
+the strings.
+ The problem with g_strncasecmp() is that it does
+ the comparison by calling toupper()/tolower(). These functions
+ are locale-specific and operate on single bytes. However, it is
+ impossible to handle things correctly from an internationalization
+ standpoint by operating on bytes, since characters may be multibyte.
+ Thus g_strncasecmp() is broken if your string is guaranteed to be
+ ASCII, since it is locale-sensitive, and it's broken if your string
+ is localized, since it doesn't work on many encodings at all,
+ including UTF-8, EUC-JP, etc.
+
+ There are therefore two replacement techniques: g_ascii_strncasecmp(),
+ which only works on ASCII and is not locale-sensitive, and
+ g_utf8_casefold() followed by strcmp() on the resulting strings,
+ which is good for case-insensitive sorting of UTF-8.
+
+
+ 0 if the strings match, a negative value if @s1 < @s2,
+ or a positive value if @s1 > @s2.
+
+
+
+
+ a string
+
+
+
+ a string to compare with @s1
+
+
+
+ the maximum number of characters to compare
+
+
+
+
+
+ Duplicates the first @n bytes of a string, returning a newly-allocated
+buffer @n + 1 bytes long which will always be nul-terminated. If @str
+is less than @n bytes long the buffer is padded with nuls. If @str is
+%NULL it returns %NULL. The returned value should be freed when no longer
+needed.
+
+To copy a number of characters from a UTF-8 encoded string,
+use g_utf8_strncpy() instead.
+
+
+ a newly-allocated buffer containing the first @n bytes
+ of @str, nul-terminated
+
+
+
+
+ the string to duplicate
+
+
+
+ the maximum number of bytes to copy from @str
+
+
+
+
+
+ Creates a new string @length bytes long filled with @fill_char.
+The returned string should be freed when no longer needed.
+
+
+ a newly-allocated string filled the @fill_char
+
+
+
+
+ the length of the new string
+
+
+
+ the byte to fill the string with
+
+
+
+
+
+ Reverses all of the bytes in a string. For example,
+`g_strreverse ("abcdef")` will result in "fedcba".
+
+Note that g_strreverse() doesn't work on UTF-8 strings
+containing multibyte characters. For that purpose, use
+g_utf8_strreverse().
+
+
+ the same pointer passed in as @string
+
+
+
+
+ the string to reverse
+
+
+
+
+
+ Searches the string @haystack for the last occurrence
+of the string @needle.
+
+
+ a pointer to the found occurrence, or
+ %NULL if not found.
+
+
+
+
+ a nul-terminated string
+
+
+
+ the nul-terminated string to search for
+
+
+
+
+
+ Searches the string @haystack for the last occurrence
+of the string @needle, limiting the length of the search
+to @haystack_len.
+
+
+ a pointer to the found occurrence, or
+ %NULL if not found.
+
+
+
+
+ a nul-terminated string
+
+
+
+ the maximum length of @haystack in bytes. A length of -1
+ can be used to mean "search the entire string", like g_strrstr().
+
+
+
+ the nul-terminated string to search for
+
+
+
+
+
+ Returns a string describing the given signal, e.g. "Segmentation fault".
+You should use this function in preference to strsignal(), because it
+returns a string in UTF-8 encoding, and since not all platforms support
+the strsignal() function.
+
+
+ a UTF-8 string describing the signal. If the signal is unknown,
+ it returns "unknown signal (<signum>)".
+
+
+
+
+ the signal number. See the `signal` documentation
+
+
+
+
+
+ Splits a string into a maximum of @max_tokens pieces, using the given
+@delimiter. If @max_tokens is reached, the remainder of @string is
+appended to the last token.
+
+As an example, the result of g_strsplit (":a:bc::d:", ":", -1) is a
+%NULL-terminated vector containing the six strings "", "a", "bc", "", "d"
+and "".
+
+As a special case, the result of splitting the empty string "" is an empty
+vector, not a vector containing a single string. The reason for this
+special case is that being able to represent an empty vector is typically
+more useful than consistent handling of empty elements. If you do need
+to represent empty elements, you'll need to check for the empty string
+before calling g_strsplit().
+
+
+ a newly-allocated %NULL-terminated array of strings. Use
+ g_strfreev() to free it.
+
+
+
+
+
+
+ a string to split
+
+
+
+ a string which specifies the places at which to split
+ the string. The delimiter is not included in any of the resulting
+ strings, unless @max_tokens is reached.
+
+
+
+ the maximum number of pieces to split @string into.
+ If this is less than 1, the string is split completely.
+
+
+
+
+
+ Splits @string into a number of tokens not containing any of the characters
+in @delimiter. A token is the (possibly empty) longest string that does not
+contain any of the characters in @delimiters. If @max_tokens is reached, the
+remainder is appended to the last token.
+
+For example the result of g_strsplit_set ("abc:def/ghi", ":/", -1) is a
+%NULL-terminated vector containing the three strings "abc", "def",
+and "ghi".
+
+The result of g_strsplit_set (":def/ghi:", ":/", -1) is a %NULL-terminated
+vector containing the four strings "", "def", "ghi", and "".
+
+As a special case, the result of splitting the empty string "" is an empty
+vector, not a vector containing a single string. The reason for this
+special case is that being able to represent an empty vector is typically
+more useful than consistent handling of empty elements. If you do need
+to represent empty elements, you'll need to check for the empty string
+before calling g_strsplit_set().
+
+Note that this function works on bytes not characters, so it can't be used
+to delimit UTF-8 strings for anything but ASCII characters.
+
+
+ a newly-allocated %NULL-terminated array of strings. Use
+ g_strfreev() to free it.
+
+
+
+
+
+
+ The string to be tokenized
+
+
+
+ A nul-terminated string containing bytes that are used
+ to split the string (it can accept an empty string, which will result
+ in no string splitting).
+
+
+
+ The maximum number of tokens to split @string into.
+ If this is less than 1, the string is split completely
+
+
+
+
+
+ Searches the string @haystack for the first occurrence
+of the string @needle, limiting the length of the search
+to @haystack_len.
+
+
+ a pointer to the found occurrence, or
+ %NULL if not found.
+
+
+
+
+ a nul-terminated string
+
+
+
+ the maximum length of @haystack in bytes. A length of -1
+ can be used to mean "search the entire string", like `strstr()`.
+
+
+
+ the string to search for
+
+
+
+
+
+ Removes leading and trailing whitespace from a string.
+See g_strchomp() and g_strchug().
+
+
+
+ a string to remove the leading and trailing whitespace from
+
+
+
+
+ Converts a string to a #gdouble value.
+It calls the standard strtod() function to handle the conversion, but
+if the string is not completely converted it attempts the conversion
+again with g_ascii_strtod(), and returns the best match.
+
+This function should seldom be used. The normal situation when reading
+numbers not for human consumption is to use g_ascii_strtod(). Only when
+you know that you must expect both locale formatted and C formatted numbers
+should you use this. Make sure that you don't pass strings such as comma
+separated lists of values, since the commas may be interpreted as a decimal
+point in some locales, causing unexpected results.
+
+
+ the #gdouble value.
+
+
+
+
+ the string to convert to a numeric value.
+
+
+
+ if non-%NULL, it returns the
+ character after the last character used in the conversion.
+
+
+
+
+
+ Converts a string to upper case.
+ This function is totally broken for the reasons
+ discussed in the g_strncasecmp() docs - use g_ascii_strup()
+ or g_utf8_strup() instead.
+
+
+ the string
+
+
+
+
+ the string to convert
+
+
+
+
+
+ Checks if @strv contains @str. @strv must not be %NULL.
+
+
+ %TRUE if @str is an element of @strv, according to g_str_equal().
+
+
+
+
+ a %NULL-terminated array of strings
+
+
+
+ a string
+
+
+
+
+
+ Checks if @strv1 and @strv2 contain exactly the same elements in exactly the
+same order. Elements are compared using g_str_equal(). To match independently
+of order, sort the arrays first (using g_qsort_with_data() or similar).
+
+Two empty arrays are considered equal. Neither @strv1 not @strv2 may be
+%NULL.
+
+
+ %TRUE if @strv1 and @strv2 are equal
+
+
+
+
+ a %NULL-terminated array of strings
+
+
+
+ another %NULL-terminated array of strings
+
+
+
+
+
+
+
+
+
+
+
+ Returns the length of the given %NULL-terminated
+string array @str_array. @str_array must not be %NULL.
+
+
+ length of @str_array.
+
+
+
+
+ a %NULL-terminated array of strings
+
+
+
+
+
+ Hook up a new test case at @testpath, similar to g_test_add_func().
+A fixture data structure with setup and teardown functions may be provided,
+similar to g_test_create_case().
+
+g_test_add() is implemented as a macro, so that the fsetup(), ftest() and
+fteardown() callbacks can expect a @Fixture pointer as their first argument
+in a type safe manner. They otherwise have type #GTestFixtureFunc.
+
+
+
+ The test path for a new test case.
+
+
+ The type of a fixture data structure.
+
+
+ Data argument for the test functions.
+
+
+ The function to set up the fixture data.
+
+
+ The actual test function.
+
+
+ The function to tear down the fixture data.
+
+
+
+
+ Create a new test case, similar to g_test_create_case(). However
+the test is assumed to use no fixture, and test suites are automatically
+created on the fly and added to the root fixture, based on the
+slash-separated portions of @testpath. The @test_data argument
+will be passed as first argument to @test_func.
+
+If @testpath includes the component "subprocess" anywhere in it,
+the test will be skipped by default, and only run if explicitly
+required via the `-p` command-line option or g_test_trap_subprocess().
+
+No component of @testpath may start with a dot (`.`) if the
+%G_TEST_OPTION_ISOLATE_DIRS option is being used; and it is recommended to
+do so even if it isn’t.
+
+
+
+
+
+
+ /-separated test case path name for the test.
+
+
+
+ Test data argument for the test function.
+
+
+
+ The test function to invoke for this test.
+
+
+
+
+
+ Create a new test case, as with g_test_add_data_func(), but freeing
+@test_data after the test run is complete.
+
+
+
+
+
+
+ /-separated test case path name for the test.
+
+
+
+ Test data argument for the test function.
+
+
+
+ The test function to invoke for this test.
+
+
+
+ #GDestroyNotify for @test_data.
+
+
+
+
+
+ Create a new test case, similar to g_test_create_case(). However
+the test is assumed to use no fixture, and test suites are automatically
+created on the fly and added to the root fixture, based on the
+slash-separated portions of @testpath.
+
+If @testpath includes the component "subprocess" anywhere in it,
+the test will be skipped by default, and only run if explicitly
+required via the `-p` command-line option or g_test_trap_subprocess().
+
+No component of @testpath may start with a dot (`.`) if the
+%G_TEST_OPTION_ISOLATE_DIRS option is being used; and it is recommended to
+do so even if it isn’t.
+
+
+
+
+
+
+ /-separated test case path name for the test.
+
+
+
+ The test function to invoke for this test.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Asserts that all messages previously indicated via
+g_test_expect_message() have been seen and suppressed.
+
+This API may only be used with the old logging API (g_log() without
+%G_LOG_USE_STRUCTURED defined). It will not work with the structured logging
+API. See [Testing for Messages][testing-for-messages].
+
+If messages at %G_LOG_LEVEL_DEBUG are emitted, but not explicitly
+expected via g_test_expect_message() then they will be ignored.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This function adds a message to test reports that
+associates a bug URI with a test case.
+
+Bug URIs are constructed from a base URI set with g_test_bug_base()
+and @bug_uri_snippet. If g_test_bug_base() has not been called, it is
+assumed to be the empty string, so a full URI can be provided to
+g_test_bug() instead.
+
+Since GLib 2.70, the base URI is not prepended to @bug_uri_snippet if it
+is already a valid URI.
+
+See also: g_test_summary()
+
+
+
+
+
+
+ Bug specific bug tracker URI or URI portion.
+
+
+
+
+
+ Specify the base URI for bug reports.
+
+The base URI is used to construct bug report messages for
+g_test_message() when g_test_bug() is called.
+Calling this function outside of a test case sets the
+default base URI for all test cases. Calling it from within
+a test case changes the base URI for the scope of the test
+case only.
+Bug URIs are constructed by appending a bug specific URI
+portion to @uri_pattern, or by replacing the special string
+`%s` within @uri_pattern if that is present.
+
+If g_test_bug_base() is not called, bug URIs are formed solely
+from the value provided by g_test_bug().
+
+
+
+
+
+
+ the base pattern for bug URIs
+
+
+
+
+
+ Creates the pathname to a data file that is required for a test.
+
+This function is conceptually similar to g_build_filename() except
+that the first argument has been replaced with a #GTestFileType
+argument.
+
+The data file should either have been distributed with the module
+containing the test (%G_TEST_DIST) or built as part of the build
+system of that module (%G_TEST_BUILT).
+
+In order for this function to work in srcdir != builddir situations,
+the G_TEST_SRCDIR and G_TEST_BUILDDIR environment variables need to
+have been defined. As of 2.38, this is done by the glib.mk
+included in GLib. Please ensure that your copy is up to date before
+using this function.
+
+In case neither variable is set, this function will fall back to
+using the dirname portion of argv[0], possibly removing ".libs".
+This allows for casual running of tests directly from the commandline
+in the srcdir == builddir case and should also support running of
+installed tests, assuming the data files have been installed in the
+same relative path as the test binary.
+
+
+ the path of the file, to be freed using g_free()
+
+
+
+
+ the type of file (built vs. distributed)
+
+
+
+ the first segment of the pathname
+
+
+
+ %NULL-terminated additional path segments
+
+
+
+
+
+ Create a new #GTestCase, named @test_name.
+
+This API is fairly low level, and calling g_test_add() or g_test_add_func()
+is preferable.
+
+When this test is executed, a fixture structure of size @data_size
+will be automatically allocated and filled with zeros. Then @data_setup is
+called to initialize the fixture. After fixture setup, the actual test
+function @data_test is called. Once the test run completes, the
+fixture structure is torn down by calling @data_teardown and
+after that the memory is automatically released by the test framework.
+
+Splitting up a test run into fixture setup, test function and
+fixture teardown is most useful if the same fixture type is used for
+multiple tests. In this cases, g_test_create_case() will be
+called with the same type of fixture (the @data_size argument), but varying
+@test_name and @data_test arguments.
+
+
+ a newly allocated #GTestCase.
+
+
+
+
+ the name for the test case
+
+
+
+ the size of the fixture data structure
+
+
+
+ test data argument for the test functions
+
+
+
+ the function to set up the fixture data
+
+
+
+ the actual test function
+
+
+
+ the function to teardown the fixture data
+
+
+
+
+
+ Create a new test suite with the name @suite_name.
+
+
+ A newly allocated #GTestSuite instance.
+
+
+
+
+ a name for the suite
+
+
+
+
+
+ Indicates that a message with the given @log_domain and @log_level,
+with text matching @pattern, is expected to be logged. When this
+message is logged, it will not be printed, and the test case will
+not abort.
+
+This API may only be used with the old logging API (g_log() without
+%G_LOG_USE_STRUCTURED defined). It will not work with the structured logging
+API. See [Testing for Messages][testing-for-messages].
+
+Use g_test_assert_expected_messages() to assert that all
+previously-expected messages have been seen and suppressed.
+
+You can call this multiple times in a row, if multiple messages are
+expected as a result of a single call. (The messages must appear in
+the same order as the calls to g_test_expect_message().)
+
+For example:
+
+|[<!-- language="C" -->
+ // g_main_context_push_thread_default() should fail if the
+ // context is already owned by another thread.
+ g_test_expect_message (G_LOG_DOMAIN,
+ G_LOG_LEVEL_CRITICAL,
+ "assertion*acquired_context*failed");
+ g_main_context_push_thread_default (bad_context);
+ g_test_assert_expected_messages ();
+]|
+
+Note that you cannot use this to test g_error() messages, since
+g_error() intentionally never returns even if the program doesn't
+abort; use g_test_trap_subprocess() in this case.
+
+If messages at %G_LOG_LEVEL_DEBUG are emitted, but not explicitly
+expected via g_test_expect_message() then they will be ignored.
+
+
+
+
+
+
+ the log domain of the message
+
+
+
+ the log level of the message
+
+
+
+ a glob-style [pattern][glib-Glob-style-pattern-matching]
+
+
+
+
+
+ Indicates that a test failed. This function can be called
+multiple times from the same test. You can use this function
+if your test failed in a recoverable way.
+
+Do not use this function if the failure of a test could cause
+other tests to malfunction.
+
+Calling this function will not stop the test from running, you
+need to return from the test function yourself. So you can
+produce additional diagnostic messages or even continue running
+the test.
+
+If not called from inside a test, this function does nothing.
+
+Note that unlike g_test_skip() and g_test_incomplete(), this
+function does not log a message alongside the test failure.
+If details of the test failure are available, either log them with
+g_test_message() before g_test_fail(), or use g_test_fail_printf()
+instead.
+
+
+
+
+
+
+ Equivalent to g_test_fail(), but also record a message like
+g_test_skip_printf().
+
+
+
+
+
+
+ the format string
+
+
+
+ printf-like arguments to @format
+
+
+
+
+
+ Returns whether a test has already failed. This will
+be the case when g_test_fail(), g_test_incomplete()
+or g_test_skip() have been called, but also if an
+assertion has failed.
+
+This can be useful to return early from a test if
+continuing after a failed assertion might be harmful.
+
+The return value of this function is only meaningful
+if it is called from inside a test function.
+
+
+ %TRUE if the test has failed
+
+
+
+
+ Gets the pathname of the directory containing test files of the type
+specified by @file_type.
+
+This is approximately the same as calling g_test_build_filename("."),
+but you don't need to free the return value.
+
+
+ the path of the directory, owned by GLib
+
+
+
+
+ the type of file (built vs. distributed)
+
+
+
+
+
+ Gets the pathname to a data file that is required for a test.
+
+This is the same as g_test_build_filename() with two differences.
+The first difference is that you must only use this function from within
+a testcase function. The second difference is that you need not free
+the return value — it will be automatically freed when the testcase
+finishes running.
+
+It is safe to use this function from a thread inside of a testcase
+but you must ensure that all such uses occur before the main testcase
+function returns (ie: it is best to ensure that all threads have been
+joined).
+
+
+ the path, automatically freed at the end of the testcase
+
+
+
+
+ the type of file (built vs. distributed)
+
+
+
+ the first segment of the pathname
+
+
+
+ %NULL-terminated additional path segments
+
+
+
+
+
+ Gets the test path for the test currently being run.
+
+In essence, it will be the same string passed as the first argument to
+e.g. g_test_add() when the test was added.
+
+This function returns a valid string only within a test function.
+
+Note that this is a test path, not a file system path.
+
+
+ the test path for the test currently being run
+
+
+
+
+ Get the toplevel test suite for the test path API.
+
+
+ the toplevel #GTestSuite
+
+
+
+
+ Indicates that a test failed because of some incomplete
+functionality. This function can be called multiple times
+from the same test.
+
+Calling this function will not stop the test from running, you
+need to return from the test function yourself. So you can
+produce additional diagnostic messages or even continue running
+the test.
+
+If not called from inside a test, this function does nothing.
+
+
+
+
+
+
+ explanation
+
+
+
+
+
+ Equivalent to g_test_incomplete(), but the explanation is formatted
+as if by g_strdup_printf().
+
+
+
+
+
+
+ the format string
+
+
+
+ printf-like arguments to @format
+
+
+
+
+
+ Initialize the GLib testing framework, e.g. by seeding the
+test random number generator, the name for g_get_prgname()
+and parsing test related command line args.
+
+So far, the following arguments are understood:
+
+- `-l`: List test cases available in a test executable.
+- `--seed=SEED`: Provide a random seed to reproduce test
+ runs using random numbers.
+- `--verbose`: Run tests verbosely.
+- `-q`, `--quiet`: Run tests quietly.
+- `-p PATH`: Execute all tests matching the given path.
+- `-s PATH`: Skip all tests matching the given path.
+ This can also be used to force a test to run that would otherwise
+ be skipped (ie, a test whose name contains "/subprocess").
+- `-m {perf|slow|thorough|quick|undefined|no-undefined}`: Execute tests according to these test modes:
+
+ `perf`: Performance tests, may take long and report results (off by default).
+
+ `slow`, `thorough`: Slow and thorough tests, may take quite long and maximize coverage
+ (off by default).
+
+ `quick`: Quick tests, should run really quickly and give good coverage (the default).
+
+ `undefined`: Tests for undefined behaviour, may provoke programming errors
+ under g_test_trap_subprocess() or g_test_expect_message() to check
+ that appropriate assertions or warnings are given (the default).
+
+ `no-undefined`: Avoid tests for undefined behaviour
+
+- `--debug-log`: Debug test logging output.
+
+Options which can be passed to @... are:
+
+ - `"no_g_set_prgname"`: Causes g_test_init() to not call g_set_prgname().
+ - %G_TEST_OPTION_ISOLATE_DIRS: Creates a unique temporary directory for each
+ unit test and uses g_set_user_dirs() to set XDG directories to point into
+ that temporary directory for the duration of the unit test. See the
+ documentation for %G_TEST_OPTION_ISOLATE_DIRS.
+
+Since 2.58, if tests are compiled with `G_DISABLE_ASSERT` defined,
+g_test_init() will print an error and exit. This is to prevent no-op tests
+from being executed, as g_assert() is commonly (erroneously) used in unit
+tests, and is a no-op when compiled with `G_DISABLE_ASSERT`. Ensure your
+tests are compiled without `G_DISABLE_ASSERT` defined.
+
+
+
+
+
+
+ Address of the @argc parameter of the main() function.
+ Changed if any arguments were handled.
+
+
+
+ Address of the @argv parameter of main().
+ Any parameters understood by g_test_init() stripped before return.
+
+
+
+ %NULL-terminated list of special options, documented below.
+
+
+
+
+
+ Returns %TRUE if g_test_init() has been called.
+
+
+
+ Installs a non-error fatal log handler which can be
+used to decide whether log messages which are counted
+as fatal abort the program.
+
+The use case here is that you are running a test case
+that depends on particular libraries or circumstances
+and cannot prevent certain known critical or warning
+messages. So you install a handler that compares the
+domain and message to precisely not abort in such a case.
+
+Note that the handler is reset at the beginning of
+any test case, so you have to set it inside each test
+function which needs the special behavior.
+
+This handler has no effect on g_error messages.
+
+This handler also has no effect on structured log messages (using
+g_log_structured() or g_log_structured_array()). To change the fatal
+behaviour for specific log messages, programs must install a custom log
+writer function using g_log_set_writer_func().See
+[Using Structured Logging][using-structured-logging].
+
+
+
+
+
+
+ the log handler function.
+
+
+
+ data passed to the log handler.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Report the result of a performance or measurement test.
+The test should generally strive to maximize the reported
+quantities (larger values are better than smaller ones),
+this and @maximized_quantity can determine sorting
+order for test result reports.
+
+
+
+
+
+
+ the reported value
+
+
+
+ the format string of the report message
+
+
+
+ arguments to pass to the printf() function
+
+
+
+
+
+ Add a message to the test report.
+
+
+
+
+
+
+ the format string
+
+
+
+ printf-like arguments to @format
+
+
+
+
+
+ Report the result of a performance or measurement test.
+The test should generally strive to minimize the reported
+quantities (smaller values are better than larger ones),
+this and @minimized_quantity can determine sorting
+order for test result reports.
+
+
+
+
+
+
+ the reported value
+
+
+
+ the format string of the report message
+
+
+
+ arguments to pass to the printf() function
+
+
+
+
+
+ Returns %TRUE if tests are run in performance mode.
+
+By default, tests are run in quick mode. In tests that use
+g_test_init(), the option `-m perf` enables performance tests, while
+`-m quick` disables them.
+
+
+
+ This function enqueus a callback @destroy_func to be executed
+during the next test case teardown phase. This is most useful
+to auto destruct allocated test resources at the end of a test run.
+Resources are released in reverse queue order, that means enqueueing
+callback A before callback B will cause B() to be called before
+A() during teardown.
+
+
+
+
+
+
+ Destroy callback for teardown phase.
+
+
+
+ Destroy callback data.
+
+
+
+
+
+ Enqueue a pointer to be released with g_free() during the next
+teardown phase. This is equivalent to calling g_test_queue_destroy()
+with a destroy callback of g_free().
+
+
+
+
+
+
+ the pointer to be stored.
+
+
+
+
+
+ Enqueue an object to be released with g_object_unref() during
+the next teardown phase. This is equivalent to calling
+g_test_queue_destroy() with a destroy callback of g_object_unref().
+
+
+
+ the object to unref
+
+
+
+
+ Returns %TRUE if tests are run in quick mode.
+Exactly one of g_test_quick() and g_test_slow() is active in any run;
+there is no "medium speed".
+
+By default, tests are run in quick mode. In tests that use
+g_test_init(), the options `-m quick`, `-m slow` and `-m thorough`
+can be used to change this.
+
+
+
+ Returns %TRUE if tests are run in quiet mode.
+In tests that use g_test_init(), the option `-q` or `--quiet` enables
+this, while `--verbose` disables it.
+The default is neither g_test_verbose() nor g_test_quiet().
+
+
+
+ Get a reproducible random bit (0 or 1), see g_test_rand_int()
+for details on test case random numbers.
+
+
+
+ Get a reproducible random floating point number,
+see g_test_rand_int() for details on test case random numbers.
+
+
+ a random number from the seeded random number generator.
+
+
+
+
+ Get a reproducible random floating pointer number out of a specified range,
+see g_test_rand_int() for details on test case random numbers.
+
+
+ a number with @range_start <= number < @range_end.
+
+
+
+
+ the minimum value returned by this function
+
+
+
+ the minimum value not returned by this function
+
+
+
+
+
+ Get a reproducible random integer number.
+
+The random numbers generated by the g_test_rand_*() family of functions
+change with every new test program start, unless the --seed option is
+given when starting test programs.
+
+For individual test cases however, the random number generator is
+reseeded, to avoid dependencies between tests and to make --seed
+effective for all test cases.
+
+
+ a random number from the seeded random number generator.
+
+
+
+
+ Get a reproducible random integer number out of a specified range,
+see g_test_rand_int() for details on test case random numbers.
+
+
+ a number with @begin <= number < @end.
+
+
+
+
+ the minimum value returned by this function
+
+
+
+ the smallest value not to be returned by this function
+
+
+
+
+
+ Runs all tests under the toplevel suite which can be retrieved
+with g_test_get_root(). Similar to g_test_run_suite(), the test
+cases to be run are filtered according to test path arguments
+(`-p testpath` and `-s testpath`) as parsed by g_test_init().
+g_test_run_suite() or g_test_run() may only be called once in a
+program.
+
+In general, the tests and sub-suites within each suite are run in
+the order in which they are defined. However, note that prior to
+GLib 2.36, there was a bug in the `g_test_add_*`
+functions which caused them to create multiple suites with the same
+name, meaning that if you created tests "/foo/simple",
+"/bar/simple", and "/foo/using-bar" in that order, they would get
+run in that order (since g_test_run() would run the first "/foo"
+suite, then the "/bar" suite, then the second "/foo" suite). As of
+2.36, this bug is fixed, and adding the tests in that order would
+result in a running order of "/foo/simple", "/foo/using-bar",
+"/bar/simple". If this new ordering is sub-optimal (because it puts
+more-complicated tests before simpler ones, making it harder to
+figure out exactly what has failed), you can fix it by changing the
+test paths to group tests by suite in a way that will result in the
+desired running order. Eg, "/simple/foo", "/simple/bar",
+"/complex/foo-using-bar".
+
+However, you should never make the actual result of a test depend
+on the order that tests are run in. If you need to ensure that some
+particular code runs before or after a given test case, use
+g_test_add(), which lets you specify setup and teardown functions.
+
+If all tests are skipped or marked as incomplete (expected failures),
+this function will return 0 if producing TAP output, or 77 (treated
+as "skip test" by Automake) otherwise.
+
+
+ 0 on success, 1 on failure (assuming it returns at all),
+ 0 or 77 if all tests were skipped with g_test_skip() and/or
+ g_test_incomplete()
+
+
+
+
+ Execute the tests within @suite and all nested #GTestSuites.
+The test suites to be executed are filtered according to
+test path arguments (`-p testpath` and `-s testpath`) as parsed by
+g_test_init(). See the g_test_run() documentation for more
+information on the order that tests are run in.
+
+g_test_run_suite() or g_test_run() may only be called once
+in a program.
+
+
+ 0 on success
+
+
+
+
+ a #GTestSuite
+
+
+
+
+
+ Changes the behaviour of the various `g_assert_*()` macros,
+g_test_assert_expected_messages() and the various
+`g_test_trap_assert_*()` macros to not abort to program, but instead
+call g_test_fail() and continue. (This also changes the behavior of
+g_test_fail() so that it will not cause the test program to abort
+after completing the failed test.)
+
+Note that the g_assert_not_reached() and g_assert() macros are not
+affected by this.
+
+This function can only be called after g_test_init().
+
+
+
+
+
+
+ Indicates that a test was skipped.
+
+Calling this function will not stop the test from running, you
+need to return from the test function yourself. So you can
+produce additional diagnostic messages or even continue running
+the test.
+
+If not called from inside a test, this function does nothing.
+
+
+
+
+
+
+ explanation
+
+
+
+
+
+ Equivalent to g_test_skip(), but the explanation is formatted
+as if by g_strdup_printf().
+
+
+
+
+
+
+ the format string
+
+
+
+ printf-like arguments to @format
+
+
+
+
+
+ Returns %TRUE if tests are run in slow mode.
+Exactly one of g_test_quick() and g_test_slow() is active in any run;
+there is no "medium speed".
+
+By default, tests are run in quick mode. In tests that use
+g_test_init(), the options `-m quick`, `-m slow` and `-m thorough`
+can be used to change this.
+
+
+
+ Returns %TRUE (after g_test_init() has been called) if the test
+program is running under g_test_trap_subprocess().
+
+
+ %TRUE if the test program is running under
+g_test_trap_subprocess().
+
+
+
+
+ Set the summary for a test, which describes what the test checks, and how it
+goes about checking it. This may be included in test report output, and is
+useful documentation for anyone reading the source code or modifying a test
+in future. It must be a single line.
+
+This should be called at the top of a test function.
+
+For example:
+|[<!-- language="C" -->
+static void
+test_array_sort (void)
+{
+ g_test_summary ("Test my_array_sort() sorts the array correctly and stably, "
+ "including testing zero length and one-element arrays.");
+
+ …
+}
+]|
+
+See also: g_test_bug()
+
+
+
+
+
+
+ One or two sentences summarising what the test checks, and how it
+ checks it.
+
+
+
+
+
+ Returns %TRUE if tests are run in thorough mode, equivalent to
+g_test_slow().
+
+By default, tests are run in quick mode. In tests that use
+g_test_init(), the options `-m quick`, `-m slow` and `-m thorough`
+can be used to change this.
+
+
+
+ Get the number of seconds since the last start of the timer with
+g_test_timer_start().
+
+
+ the time since the last start of the timer in seconds, as a double
+
+
+
+
+ Report the last result of g_test_timer_elapsed().
+
+
+ the last result of g_test_timer_elapsed(), as a double
+
+
+
+
+ Start a timing test. Call g_test_timer_elapsed() when the task is supposed
+to be done. Call this function again to restart the timer.
+
+
+
+
+
+
+ Assert that the last test subprocess failed.
+See g_test_trap_subprocess().
+
+This is sometimes used to test situations that are formally considered to
+be undefined behaviour, like inputs that fail a g_return_if_fail()
+check. In these situations you should skip the entire test, including the
+call to g_test_trap_subprocess(), unless g_test_undefined() returns %TRUE
+to indicate that undefined behaviour may be tested.
+
+
+
+ Assert that the last test subprocess passed.
+See g_test_trap_subprocess().
+
+
+
+ Assert that the stderr output of the last test subprocess
+matches @serrpattern. See g_test_trap_subprocess().
+
+This is sometimes used to test situations that are formally
+considered to be undefined behaviour, like code that hits a
+g_assert() or g_error(). In these situations you should skip the
+entire test, including the call to g_test_trap_subprocess(), unless
+g_test_undefined() returns %TRUE to indicate that undefined
+behaviour may be tested.
+
+
+
+ a glob-style [pattern][glib-Glob-style-pattern-matching]
+
+
+
+
+ Assert that the stderr output of the last test subprocess
+does not match @serrpattern. See g_test_trap_subprocess().
+
+
+
+ a glob-style [pattern][glib-Glob-style-pattern-matching]
+
+
+
+
+ Assert that the stdout output of the last test subprocess matches
+@soutpattern. See g_test_trap_subprocess().
+
+
+
+ a glob-style [pattern][glib-Glob-style-pattern-matching]
+
+
+
+
+ Assert that the stdout output of the last test subprocess
+does not match @soutpattern. See g_test_trap_subprocess().
+
+
+
+ a glob-style [pattern][glib-Glob-style-pattern-matching]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Fork the current test program to execute a test case that might
+not return or that might abort.
+
+If @usec_timeout is non-0, the forked test case is aborted and
+considered failing if its run time exceeds it.
+
+The forking behavior can be configured with the #GTestTrapFlags flags.
+
+In the following example, the test code forks, the forked child
+process produces some sample output and exits successfully.
+The forking parent process then asserts successful child program
+termination and validates child program outputs.
+
+|[<!-- language="C" -->
+ static void
+ test_fork_patterns (void)
+ {
+ if (g_test_trap_fork (0, G_TEST_TRAP_SILENCE_STDOUT | G_TEST_TRAP_SILENCE_STDERR))
+ {
+ g_print ("some stdout text: somagic17\n");
+ g_printerr ("some stderr text: semagic43\n");
+ exit (0); // successful test run
+ }
+ g_test_trap_assert_passed ();
+ g_test_trap_assert_stdout ("*somagic17*");
+ g_test_trap_assert_stderr ("*semagic43*");
+ }
+]|
+ This function is implemented only on Unix platforms,
+is not always reliable due to problems inherent in fork-without-exec
+and doesn't set close-on-exec flag on its file descriptors.
+Use g_test_trap_subprocess() instead.
+
+
+ %TRUE for the forked child and %FALSE for the executing parent process.
+
+
+
+
+ Timeout for the forked test in micro seconds.
+
+
+
+ Flags to modify forking behaviour.
+
+
+
+
+
+ Check the result of the last g_test_trap_subprocess() call.
+
+
+ %TRUE if the last test subprocess terminated successfully.
+
+
+
+
+ Check the result of the last g_test_trap_subprocess() call.
+
+
+ %TRUE if the last test subprocess got killed due to a timeout.
+
+
+
+
+ Respawns the test program to run only @test_path in a subprocess.
+This can be used for a test case that might not return, or that
+might abort.
+
+If @test_path is %NULL then the same test is re-run in a subprocess.
+You can use g_test_subprocess() to determine whether the test is in
+a subprocess or not.
+
+@test_path can also be the name of the parent test, followed by
+"`/subprocess/`" and then a name for the specific subtest (or just
+ending with "`/subprocess`" if the test only has one child test);
+tests with names of this form will automatically be skipped in the
+parent process.
+
+If @usec_timeout is non-0, the test subprocess is aborted and
+considered failing if its run time exceeds it.
+
+The subprocess behavior can be configured with the
+#GTestSubprocessFlags flags.
+
+You can use methods such as g_test_trap_assert_passed(),
+g_test_trap_assert_failed(), and g_test_trap_assert_stderr() to
+check the results of the subprocess. (But note that
+g_test_trap_assert_stdout() and g_test_trap_assert_stderr()
+cannot be used if @test_flags specifies that the child should
+inherit the parent stdout/stderr.)
+
+If your `main ()` needs to behave differently in
+the subprocess, you can call g_test_subprocess() (after calling
+g_test_init()) to see whether you are in a subprocess.
+
+The following example tests that calling
+`my_object_new(1000000)` will abort with an error
+message.
+
+|[<!-- language="C" -->
+ static void
+ test_create_large_object (void)
+ {
+ if (g_test_subprocess ())
+ {
+ my_object_new (1000000);
+ return;
+ }
+
+ // Reruns this same test in a subprocess
+ g_test_trap_subprocess (NULL, 0, G_TEST_SUBPROCESS_DEFAULT);
+ g_test_trap_assert_failed ();
+ g_test_trap_assert_stderr ("*ERROR*too large*");
+ }
+
+ int
+ main (int argc, char **argv)
+ {
+ g_test_init (&argc, &argv, NULL);
+
+ g_test_add_func ("/myobject/create_large_object",
+ test_create_large_object);
+ return g_test_run ();
+ }
+]|
+
+
+
+
+
+
+ Test to run in a subprocess
+
+
+
+ Timeout for the subprocess test in micro seconds.
+
+
+
+ Flags to modify subprocess behaviour.
+
+
+
+
+
+ Returns %TRUE if tests may provoke assertions and other formally-undefined
+behaviour, to verify that appropriate warnings are given. It might, in some
+cases, be useful to turn this off with if running tests under valgrind;
+in tests that use g_test_init(), the option `-m no-undefined` disables
+those tests, while `-m undefined` explicitly enables them (normally
+the default behaviour).
+
+Since GLib 2.68, if GLib was compiled with gcc or clang and
+[AddressSanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizer)
+is enabled, the default changes to not exercising undefined behaviour.
+
+
+
+ Returns %TRUE if tests are run in verbose mode.
+In tests that use g_test_init(), the option `--verbose` enables this,
+while `-q` or `--quiet` disables it.
+The default is neither g_test_verbose() nor g_test_quiet().
+
+
+
+ GLib provides a framework for writing and maintaining unit tests
+in parallel to the code they are testing. The API is designed according
+to established concepts found in the other test frameworks (JUnit, NUnit,
+RUnit), which in turn is based on smalltalk unit testing concepts.
+
+- Test case: Tests (test methods) are grouped together with their
+ fixture into test cases.
+
+- Fixture: A test fixture consists of fixture data and setup and
+ teardown methods to establish the environment for the test
+ functions. We use fresh fixtures, i.e. fixtures are newly set
+ up and torn down around each test invocation to avoid dependencies
+ between tests.
+
+- Test suite: Test cases can be grouped into test suites, to allow
+ subsets of the available tests to be run. Test suites can be
+ grouped into other test suites as well.
+
+The API is designed to handle creation and registration of test suites
+and test cases implicitly. A simple call like
+|[<!-- language="C" -->
+ g_test_add_func ("/misc/assertions", test_assertions);
+]|
+creates a test suite called "misc" with a single test case named
+"assertions", which consists of running the test_assertions function.
+
+In addition to the traditional g_assert_true(), the test framework provides
+an extended set of assertions for comparisons: g_assert_cmpfloat(),
+g_assert_cmpfloat_with_epsilon(), g_assert_cmpint(), g_assert_cmpuint(),
+g_assert_cmphex(), g_assert_cmpstr(), g_assert_cmpmem() and
+g_assert_cmpvariant(). The
+advantage of these variants over plain g_assert_true() is that the assertion
+messages can be more elaborate, and include the values of the compared
+entities.
+
+Note that g_assert() should not be used in unit tests, since it is a no-op
+when compiling with `G_DISABLE_ASSERT`. Use g_assert() in production code,
+and g_assert_true() in unit tests.
+
+A full example of creating a test suite with two tests using fixtures:
+|[<!-- language="C" -->
+#include <glib.h>
+#include <locale.h>
+
+typedef struct {
+ MyObject *obj;
+ OtherObject *helper;
+} MyObjectFixture;
+
+static void
+my_object_fixture_set_up (MyObjectFixture *fixture,
+ gconstpointer user_data)
+{
+ fixture->obj = my_object_new ();
+ my_object_set_prop1 (fixture->obj, "some-value");
+ my_object_do_some_complex_setup (fixture->obj, user_data);
+
+ fixture->helper = other_object_new ();
+}
+
+static void
+my_object_fixture_tear_down (MyObjectFixture *fixture,
+ gconstpointer user_data)
+{
+ g_clear_object (&fixture->helper);
+ g_clear_object (&fixture->obj);
+}
+
+static void
+test_my_object_test1 (MyObjectFixture *fixture,
+ gconstpointer user_data)
+{
+ g_assert_cmpstr (my_object_get_property (fixture->obj), ==, "initial-value");
+}
+
+static void
+test_my_object_test2 (MyObjectFixture *fixture,
+ gconstpointer user_data)
+{
+ my_object_do_some_work_using_helper (fixture->obj, fixture->helper);
+ g_assert_cmpstr (my_object_get_property (fixture->obj), ==, "updated-value");
+}
+
+int
+main (int argc, char *argv[])
+{
+ setlocale (LC_ALL, "");
+
+ g_test_init (&argc, &argv, NULL);
+
+ // Define the tests.
+ g_test_add ("/my-object/test1", MyObjectFixture, "some-user-data",
+ my_object_fixture_set_up, test_my_object_test1,
+ my_object_fixture_tear_down);
+ g_test_add ("/my-object/test2", MyObjectFixture, "some-user-data",
+ my_object_fixture_set_up, test_my_object_test2,
+ my_object_fixture_tear_down);
+
+ return g_test_run ();
+}
+]|
+
+### Integrating GTest in your project
+
+If you are using the [Meson](http://mesonbuild.com) build system, you will
+typically use the provided `test()` primitive to call the test binaries,
+e.g.:
+
+|[<!-- language="plain" -->
+ test(
+ 'foo',
+ executable('foo', 'foo.c', dependencies: deps),
+ env: [
+ 'G_TEST_SRCDIR=@0@'.format(meson.current_source_dir()),
+ 'G_TEST_BUILDDIR=@0@'.format(meson.current_build_dir()),
+ ],
+ )
+
+ test(
+ 'bar',
+ executable('bar', 'bar.c', dependencies: deps),
+ env: [
+ 'G_TEST_SRCDIR=@0@'.format(meson.current_source_dir()),
+ 'G_TEST_BUILDDIR=@0@'.format(meson.current_build_dir()),
+ ],
+ )
+]|
+
+If you are using Autotools, you're strongly encouraged to use the Automake
+[TAP](https://testanything.org/) harness; GLib provides template files for
+easily integrating with it:
+
+ - [glib-tap.mk](https://gitlab.gnome.org/GNOME/glib/blob/glib-2-58/glib-tap.mk)
+ - [tap-test](https://gitlab.gnome.org/GNOME/glib/blob/glib-2-58/tap-test)
+ - [tap-driver.sh](https://gitlab.gnome.org/GNOME/glib/blob/glib-2-58/tap-driver.sh)
+
+You can copy these files in your own project's root directory, and then
+set up your `Makefile.am` file to reference them, for instance:
+
+|[<!-- language="plain" -->
+include $(top_srcdir)/glib-tap.mk
+
+# test binaries
+test_programs = \
+ foo \
+ bar
+
+# data distributed in the tarball
+dist_test_data = \
+ foo.data.txt \
+ bar.data.txt
+
+# data not distributed in the tarball
+test_data = \
+ blah.data.txt
+]|
+
+Make sure to distribute the TAP files, using something like the following
+in your top-level `Makefile.am`:
+
+|[<!-- language="plain" -->
+EXTRA_DIST += \
+ tap-driver.sh \
+ tap-test
+]|
+
+`glib-tap.mk` will be distributed implicitly due to being included in a
+`Makefile.am`. All three files should be added to version control.
+
+If you don't have access to the Autotools TAP harness, you can use the
+[gtester][gtester] and [gtester-report][gtester-report] tools, and use
+the [glib.mk](https://gitlab.gnome.org/GNOME/glib/blob/glib-2-58/glib.mk)
+Automake template provided by GLib. Note, however, that since GLib 2.62,
+[gtester][gtester] and [gtester-report][gtester-report] have been deprecated
+in favour of using TAP. The `--tap` argument to tests is enabled by default
+as of GLib 2.62.
+
+
+
+
+
+
+
+ Terminates the current thread.
+
+If another thread is waiting for us using g_thread_join() then the
+waiting thread will be woken up and get @retval as the return value
+of g_thread_join().
+
+Calling g_thread_exit() with a parameter @retval is equivalent to
+returning @retval from the function @func, as given to g_thread_new().
+
+You must only call g_thread_exit() from a thread that you created
+yourself with g_thread_new() or related APIs. You must not call
+this function from a thread created with another threading library
+or or from within a #GThreadPool.
+
+
+
+
+
+
+ the return value of this thread
+
+
+
+
+
+ This function will return the maximum @interval that a
+thread will wait in the thread pool for new tasks before
+being stopped.
+
+If this function returns 0, threads waiting in the thread
+pool for new work are not stopped.
+
+
+ the maximum @interval (milliseconds) to wait
+ for new tasks in the thread pool before stopping the
+ thread
+
+
+
+
+ Returns the maximal allowed number of unused threads.
+
+
+ the maximal number of unused threads
+
+
+
+
+ Returns the number of currently unused threads.
+
+
+ the number of currently unused threads
+
+
+
+
+ This function will set the maximum @interval that a thread
+waiting in the pool for new tasks can be idle for before
+being stopped. This function is similar to calling
+g_thread_pool_stop_unused_threads() on a regular timeout,
+except this is done on a per thread basis.
+
+By setting @interval to 0, idle threads will not be stopped.
+
+The default value is 15000 (15 seconds).
+
+
+
+
+
+
+ the maximum @interval (in milliseconds)
+ a thread can be idle
+
+
+
+
+
+ Sets the maximal number of unused threads to @max_threads.
+If @max_threads is -1, no limit is imposed on the number
+of unused threads.
+
+The default value is 2.
+
+
+
+
+
+
+ maximal number of unused threads
+
+
+
+
+
+ Stops all currently unused threads. This does not change the
+maximal number of unused threads. This function can be used to
+regularly stop all unused threads e.g. from g_timeout_add().
+
+
+
+
+
+
+ Sometimes you wish to asynchronously fork out the execution of work
+and continue working in your own thread. If that will happen often,
+the overhead of starting and destroying a thread each time might be
+too high. In such cases reusing already started threads seems like a
+good idea. And it indeed is, but implementing this can be tedious
+and error-prone.
+
+Therefore GLib provides thread pools for your convenience. An added
+advantage is, that the threads can be shared between the different
+subsystems of your program, when they are using GLib.
+
+To create a new thread pool, you use g_thread_pool_new().
+It is destroyed by g_thread_pool_free().
+
+If you want to execute a certain task within a thread pool,
+you call g_thread_pool_push().
+
+To get the current number of running threads you call
+g_thread_pool_get_num_threads(). To get the number of still
+unprocessed tasks you call g_thread_pool_unprocessed(). To control
+the maximal number of threads for a thread pool, you use
+g_thread_pool_get_max_threads() and g_thread_pool_set_max_threads().
+
+Finally you can control the number of unused threads, that are kept
+alive by GLib for future use. The current number can be fetched with
+g_thread_pool_get_num_unused_threads(). The maximal number can be
+controlled by g_thread_pool_get_max_unused_threads() and
+g_thread_pool_set_max_unused_threads(). All currently unused threads
+can be stopped by calling g_thread_pool_stop_unused_threads().
+
+
+ This function returns the #GThread corresponding to the
+current thread. Note that this function does not increase
+the reference count of the returned struct.
+
+This function will return a #GThread even for threads that
+were not created by GLib (i.e. those created by other threading
+APIs). This may be useful for thread identification purposes
+(i.e. comparisons) but you must not use GLib functions (such
+as g_thread_join()) on these threads.
+
+
+ the #GThread representing the current thread
+
+
+
+
+ Causes the calling thread to voluntarily relinquish the CPU, so
+that other threads can run.
+
+This function is often used as a method to make busy wait less evil.
+
+
+
+
+
+
+ Threads act almost like processes, but unlike processes all threads
+of one process share the same memory. This is good, as it provides
+easy communication between the involved threads via this shared
+memory, and it is bad, because strange things (so called
+"Heisenbugs") might happen if the program is not carefully designed.
+In particular, due to the concurrent nature of threads, no
+assumptions on the order of execution of code running in different
+threads can be made, unless order is explicitly forced by the
+programmer through synchronization primitives.
+
+The aim of the thread-related functions in GLib is to provide a
+portable means for writing multi-threaded software. There are
+primitives for mutexes to protect the access to portions of memory
+(#GMutex, #GRecMutex and #GRWLock). There is a facility to use
+individual bits for locks (g_bit_lock()). There are primitives
+for condition variables to allow synchronization of threads (#GCond).
+There are primitives for thread-private data - data that every
+thread has a private instance of (#GPrivate). There are facilities
+for one-time initialization (#GOnce, g_once_init_enter()). Finally,
+there are primitives to create and manage threads (#GThread).
+
+The GLib threading system used to be initialized with g_thread_init().
+This is no longer necessary. Since version 2.32, the GLib threading
+system is automatically initialized at the start of your program,
+and all thread-creation functions and synchronization primitives
+are available right away.
+
+Note that it is not safe to assume that your program has no threads
+even if you don't call g_thread_new() yourself. GLib and GIO can
+and will create threads for their own purposes in some cases, such
+as when using g_unix_signal_source_new() or when using GDBus.
+
+Originally, UNIX did not have threads, and therefore some traditional
+UNIX APIs are problematic in threaded programs. Some notable examples
+are
+
+- C library functions that return data in statically allocated
+ buffers, such as strtok() or strerror(). For many of these,
+ there are thread-safe variants with a _r suffix, or you can
+ look at corresponding GLib APIs (like g_strsplit() or g_strerror()).
+
+- The functions setenv() and unsetenv() manipulate the process
+ environment in a not thread-safe way, and may interfere with getenv()
+ calls in other threads. Note that getenv() calls may be hidden behind
+ other APIs. For example, GNU gettext() calls getenv() under the
+ covers. In general, it is best to treat the environment as readonly.
+ If you absolutely have to modify the environment, do it early in
+ main(), when no other threads are around yet.
+
+- The setlocale() function changes the locale for the entire process,
+ affecting all threads. Temporary changes to the locale are often made
+ to change the behavior of string scanning or formatting functions
+ like scanf() or printf(). GLib offers a number of string APIs
+ (like g_ascii_formatd() or g_ascii_strtod()) that can often be
+ used as an alternative. Or you can use the uselocale() function
+ to change the locale only for the current thread.
+
+- The fork() function only takes the calling thread into the child's
+ copy of the process image. If other threads were executing in critical
+ sections they could have left mutexes locked which could easily
+ cause deadlocks in the new child. For this reason, you should
+ call exit() or exec() as soon as possible in the child and only
+ make signal-safe library calls before that.
+
+- The daemon() function uses fork() in a way contrary to what is
+ described above. It should not be used with GLib programs.
+
+GLib itself is internally completely thread-safe (all global data is
+automatically locked), but individual data structure instances are
+not automatically locked for performance reasons. For example,
+you must coordinate accesses to the same #GHashTable from multiple
+threads. The two notable exceptions from this rule are #GMainLoop
+and #GAsyncQueue, which are thread-safe and need no further
+application-level locking to be accessed from multiple threads.
+Most refcounting functions such as g_object_ref() are also thread-safe.
+
+A common use for #GThreads is to move a long-running blocking operation out
+of the main thread and into a worker thread. For GLib functions, such as
+single GIO operations, this is not necessary, and complicates the code.
+Instead, the `…_async()` version of the function should be used from the main
+thread, eliminating the need for locking and synchronisation between multiple
+threads. If an operation does need to be moved to a worker thread, consider
+using g_task_run_in_thread(), or a #GThreadPool. #GThreadPool is often a
+better choice than #GThread, as it handles thread reuse and task queueing;
+#GTask uses this internally.
+
+However, if multiple blocking operations need to be performed in sequence,
+and it is not possible to use #GTask for them, moving them to a worker thread
+can clarify the code.
+
+
+ Converts a string containing an ISO 8601 encoded date and time
+to a #GTimeVal and puts it into @time_.
+
+@iso_date must include year, month, day, hours, minutes, and
+seconds. It can optionally include fractions of a second and a time
+zone indicator. (In the absence of any time zone indication, the
+timestamp is assumed to be in local time.)
+
+Any leading or trailing space in @iso_date is ignored.
+
+This function was deprecated, along with #GTimeVal itself, in GLib 2.62.
+Equivalent functionality is available using code like:
+|[
+GDateTime *dt = g_date_time_new_from_iso8601 (iso8601_string, NULL);
+gint64 time_val = g_date_time_to_unix (dt);
+g_date_time_unref (dt);
+]|
+ #GTimeVal is not year-2038-safe. Use
+ g_date_time_new_from_iso8601() instead.
+
+
+ %TRUE if the conversion was successful.
+
+
+
+
+ an ISO 8601 encoded date string
+
+
+
+ a #GTimeVal
+
+
+
+
+
+ Sets a function to be called at regular intervals, with the default
+priority, %G_PRIORITY_DEFAULT.
+
+The given @function is called repeatedly until it returns %G_SOURCE_REMOVE
+or %FALSE, at which point the timeout is automatically destroyed and the
+function will not be called again. The first call to the function will be
+at the end of the first @interval.
+
+Note that timeout functions may be delayed, due to the processing of other
+event sources. Thus they should not be relied on for precise timing.
+After each call to the timeout function, the time of the next
+timeout is recalculated based on the current time and the given interval
+(it does not try to 'catch up' time lost in delays).
+
+See [memory management of sources][mainloop-memory-management] for details
+on how to handle the return value and memory management of @data.
+
+If you want to have a timer in the "seconds" range and do not care
+about the exact time of the first call of the timer, use the
+g_timeout_add_seconds() function; this function allows for more
+optimizations and more efficient system power usage.
+
+This internally creates a main loop source using g_timeout_source_new()
+and attaches it to the global #GMainContext using g_source_attach(), so
+the callback will be invoked in whichever thread is running that main
+context. You can do these steps manually if you need greater control or to
+use a custom main context.
+
+It is safe to call this function from any thread.
+
+The interval given is in terms of monotonic time, not wall clock
+time. See g_get_monotonic_time().
+
+
+ the ID (greater than 0) of the event source.
+
+
+
+
+ the time between calls to the function, in milliseconds
+ (1/1000ths of a second)
+
+
+
+ function to call
+
+
+
+ data to pass to @function
+
+
+
+
+
+ Sets a function to be called at regular intervals, with the given
+priority. The function is called repeatedly until it returns
+%FALSE, at which point the timeout is automatically destroyed and
+the function will not be called again. The @notify function is
+called when the timeout is destroyed. The first call to the
+function will be at the end of the first @interval.
+
+Note that timeout functions may be delayed, due to the processing of other
+event sources. Thus they should not be relied on for precise timing.
+After each call to the timeout function, the time of the next
+timeout is recalculated based on the current time and the given interval
+(it does not try to 'catch up' time lost in delays).
+
+See [memory management of sources][mainloop-memory-management] for details
+on how to handle the return value and memory management of @data.
+
+This internally creates a main loop source using g_timeout_source_new()
+and attaches it to the global #GMainContext using g_source_attach(), so
+the callback will be invoked in whichever thread is running that main
+context. You can do these steps manually if you need greater control or to
+use a custom main context.
+
+The interval given is in terms of monotonic time, not wall clock time.
+See g_get_monotonic_time().
+
+
+ the ID (greater than 0) of the event source.
+
+
+
+
+ the priority of the timeout source. Typically this will be in
+ the range between %G_PRIORITY_DEFAULT and %G_PRIORITY_HIGH.
+
+
+
+ the time between calls to the function, in milliseconds
+ (1/1000ths of a second)
+
+
+
+ function to call
+
+
+
+ data to pass to @function
+
+
+
+ function to call when the timeout is removed, or %NULL
+
+
+
+
+
+ Sets a function to be called after @interval milliseconds have elapsed,
+with the default priority, %G_PRIORITY_DEFAULT.
+
+The given @function is called once and then the source will be automatically
+removed from the main context.
+
+This function otherwise behaves like g_timeout_add().
+
+
+ the ID (greater than 0) of the event source
+
+
+
+
+ the time after which the function will be called, in
+ milliseconds (1/1000ths of a second)
+
+
+
+ function to call
+
+
+
+ data to pass to @function
+
+
+
+
+
+ Sets a function to be called at regular intervals with the default
+priority, %G_PRIORITY_DEFAULT.
+
+The function is called repeatedly until it returns %G_SOURCE_REMOVE
+or %FALSE, at which point the timeout is automatically destroyed
+and the function will not be called again.
+
+This internally creates a main loop source using
+g_timeout_source_new_seconds() and attaches it to the main loop context
+using g_source_attach(). You can do these steps manually if you need
+greater control. Also see g_timeout_add_seconds_full().
+
+It is safe to call this function from any thread.
+
+Note that the first call of the timer may not be precise for timeouts
+of one second. If you need finer precision and have such a timeout,
+you may want to use g_timeout_add() instead.
+
+See [memory management of sources][mainloop-memory-management] for details
+on how to handle the return value and memory management of @data.
+
+The interval given is in terms of monotonic time, not wall clock
+time. See g_get_monotonic_time().
+
+
+ the ID (greater than 0) of the event source.
+
+
+
+
+ the time between calls to the function, in seconds
+
+
+
+ function to call
+
+
+
+ data to pass to @function
+
+
+
+
+
+ Sets a function to be called at regular intervals, with @priority.
+
+The function is called repeatedly until it returns %G_SOURCE_REMOVE
+or %FALSE, at which point the timeout is automatically destroyed and
+the function will not be called again.
+
+Unlike g_timeout_add(), this function operates at whole second granularity.
+The initial starting point of the timer is determined by the implementation
+and the implementation is expected to group multiple timers together so that
+they fire all at the same time. To allow this grouping, the @interval to the
+first timer is rounded and can deviate up to one second from the specified
+interval. Subsequent timer iterations will generally run at the specified
+interval.
+
+Note that timeout functions may be delayed, due to the processing of other
+event sources. Thus they should not be relied on for precise timing.
+After each call to the timeout function, the time of the next
+timeout is recalculated based on the current time and the given @interval
+
+See [memory management of sources][mainloop-memory-management] for details
+on how to handle the return value and memory management of @data.
+
+If you want timing more precise than whole seconds, use g_timeout_add()
+instead.
+
+The grouping of timers to fire at the same time results in a more power
+and CPU efficient behavior so if your timer is in multiples of seconds
+and you don't require the first timer exactly one second from now, the
+use of g_timeout_add_seconds() is preferred over g_timeout_add().
+
+This internally creates a main loop source using
+g_timeout_source_new_seconds() and attaches it to the main loop context
+using g_source_attach(). You can do these steps manually if you need
+greater control.
+
+It is safe to call this function from any thread.
+
+The interval given is in terms of monotonic time, not wall clock
+time. See g_get_monotonic_time().
+
+
+ the ID (greater than 0) of the event source.
+
+
+
+
+ the priority of the timeout source. Typically this will be in
+ the range between %G_PRIORITY_DEFAULT and %G_PRIORITY_HIGH.
+
+
+
+ the time between calls to the function, in seconds
+
+
+
+ function to call
+
+
+
+ data to pass to @function
+
+
+
+ function to call when the timeout is removed, or %NULL
+
+
+
+
+
+ Creates a new timeout source.
+
+The source will not initially be associated with any #GMainContext
+and must be added to one with g_source_attach() before it will be
+executed.
+
+The interval given is in terms of monotonic time, not wall clock
+time. See g_get_monotonic_time().
+
+
+ the newly-created timeout source
+
+
+
+
+ the timeout interval in milliseconds.
+
+
+
+
+
+ Creates a new timeout source.
+
+The source will not initially be associated with any #GMainContext
+and must be added to one with g_source_attach() before it will be
+executed.
+
+The scheduling granularity/accuracy of this timeout source will be
+in seconds.
+
+The interval given is in terms of monotonic time, not wall clock time.
+See g_get_monotonic_time().
+
+
+ the newly-created timeout source
+
+
+
+
+ the timeout interval in seconds
+
+
+
+
+
+ #GTimer records a start time, and counts microseconds elapsed since
+that time. This is done somewhat differently on different platforms,
+and can be tricky to get exactly right, so #GTimer provides a
+portable/convenient interface.
+
+
+ #GTimeZone is a structure that represents a time zone, at no
+particular point in time. It is refcounted and immutable.
+
+Each time zone has an identifier (for example, ‘Europe/London’) which is
+platform dependent. See g_time_zone_new() for information on the identifier
+formats. The identifier of a time zone can be retrieved using
+g_time_zone_get_identifier().
+
+A time zone contains a number of intervals. Each interval has
+an abbreviation to describe it (for example, ‘PDT’), an offset to UTC and a
+flag indicating if the daylight savings time is in effect during that
+interval. A time zone always has at least one interval — interval 0. Note
+that interval abbreviations are not the same as time zone identifiers
+(apart from ‘UTC’), and cannot be passed to g_time_zone_new().
+
+Every UTC time is contained within exactly one interval, but a given
+local time may be contained within zero, one or two intervals (due to
+incontinuities associated with daylight savings time).
+
+An interval may refer to a specific period of time (eg: the duration
+of daylight savings time during 2010) or it may refer to many periods
+of time that share the same properties (eg: all periods of daylight
+savings time). It is also possible (usually for political reasons)
+that some properties (like the abbreviation) change between intervals
+without other properties changing.
+
+#GTimeZone is available since GLib 2.26.
+
+
+ A #GTrashStack is an efficient way to keep a stack of unused allocated
+memory chunks. Each memory chunk is required to be large enough to hold
+a #gpointer. This allows the stack to be maintained without any space
+overhead, since the stack pointers can be stored inside the memory chunks.
+
+There is no function to create a #GTrashStack. A %NULL #GTrashStack*
+is a perfectly valid empty stack.
+
+There is no longer any good reason to use #GTrashStack. If you have
+extra pieces of memory, free() them and allocate them again later.
+
+
+ Returns the height of a #GTrashStack.
+
+Note that execution of this function is of O(N) complexity
+where N denotes the number of items on the stack.
+ #GTrashStack is deprecated without replacement
+
+
+ the height of the stack
+
+
+
+
+ a #GTrashStack
+
+
+
+
+
+ Returns the element at the top of a #GTrashStack
+which may be %NULL.
+ #GTrashStack is deprecated without replacement
+
+
+ the element at the top of the stack
+
+
+
+
+ a #GTrashStack
+
+
+
+
+
+ Pops a piece of memory off a #GTrashStack.
+ #GTrashStack is deprecated without replacement
+
+
+ the element at the top of the stack
+
+
+
+
+ a #GTrashStack
+
+
+
+
+
+ Pushes a piece of memory onto a #GTrashStack.
+ #GTrashStack is deprecated without replacement
+
+
+
+
+
+
+ a #GTrashStack
+
+
+
+ the piece of memory to push on the stack
+
+
+
+
+
+ The #GTree structure and its associated functions provide a sorted
+collection of key/value pairs optimized for searching and traversing
+in order. This means that most of the operations (access, search,
+insertion, deletion, ...) on #GTree are O(log(n)) in average and O(n)
+in worst case for time complexity. But, note that maintaining a
+balanced sorted #GTree of n elements is done in time O(n log(n)).
+
+To create a new #GTree use g_tree_new().
+
+To insert a key/value pair into a #GTree use g_tree_insert()
+(O(n log(n))).
+
+To remove a key/value pair use g_tree_remove() (O(n log(n))).
+
+To look up the value corresponding to a given key, use
+g_tree_lookup() and g_tree_lookup_extended().
+
+To find out the number of nodes in a #GTree, use g_tree_nnodes(). To
+get the height of a #GTree, use g_tree_height().
+
+To traverse a #GTree, calling a function for each node visited in
+the traversal, use g_tree_foreach().
+
+To destroy a #GTree, use g_tree_destroy().
+
+
+ The #GNode struct and its associated functions provide a N-ary tree
+data structure, where nodes in the tree can contain arbitrary data.
+
+To create a new tree use g_node_new().
+
+To insert a node into a tree use g_node_insert(),
+g_node_insert_before(), g_node_append() and g_node_prepend().
+
+To create a new node and insert it into a tree use
+g_node_insert_data(), g_node_insert_data_after(),
+g_node_insert_data_before(), g_node_append_data()
+and g_node_prepend_data().
+
+To reverse the children of a node use g_node_reverse_children().
+
+To find a node use g_node_get_root(), g_node_find(),
+g_node_find_child(), g_node_child_index(), g_node_child_position(),
+g_node_first_child(), g_node_last_child(), g_node_nth_child(),
+g_node_first_sibling(), g_node_prev_sibling(), g_node_next_sibling()
+or g_node_last_sibling().
+
+To get information about a node or tree use G_NODE_IS_LEAF(),
+G_NODE_IS_ROOT(), g_node_depth(), g_node_n_nodes(),
+g_node_n_children(), g_node_is_ancestor() or g_node_max_height().
+
+To traverse a tree, calling a function for each node visited in the
+traversal, use g_node_traverse() or g_node_children_foreach().
+
+To remove a node or subtree from a tree use g_node_unlink() or
+g_node_destroy().
+
+
+ Attempts to allocate @n_bytes, and returns %NULL on failure.
+Contrast with g_malloc(), which aborts the program on failure.
+
+
+ the allocated memory, or %NULL.
+
+
+
+
+ number of bytes to allocate.
+
+
+
+
+
+ Attempts to allocate @n_bytes, initialized to 0's, and returns %NULL on
+failure. Contrast with g_malloc0(), which aborts the program on failure.
+
+
+ the allocated memory, or %NULL
+
+
+
+
+ number of bytes to allocate
+
+
+
+
+
+ This function is similar to g_try_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes,
+but care is taken to detect possible overflow during multiplication.
+
+
+ the allocated memory, or %NULL
+
+
+
+
+ the number of blocks to allocate
+
+
+
+ the size of each block in bytes
+
+
+
+
+
+ This function is similar to g_try_malloc(), allocating (@n_blocks * @n_block_bytes) bytes,
+but care is taken to detect possible overflow during multiplication.
+
+
+ the allocated memory, or %NULL.
+
+
+
+
+ the number of blocks to allocate
+
+
+
+ the size of each block in bytes
+
+
+
+
+
+ Attempts to allocate @n_structs elements of type @struct_type, and returns
+%NULL on failure. Contrast with g_new(), which aborts the program on failure.
+The returned pointer is cast to a pointer to the given type.
+The function returns %NULL when @n_structs is 0 of if an overflow occurs.
+
+
+
+ the type of the elements to allocate
+
+
+ the number of elements to allocate
+
+
+
+
+ Attempts to allocate @n_structs elements of type @struct_type, initialized
+to 0's, and returns %NULL on failure. Contrast with g_new0(), which aborts
+the program on failure.
+The returned pointer is cast to a pointer to the given type.
+The function returns %NULL when @n_structs is 0 or if an overflow occurs.
+
+
+
+ the type of the elements to allocate
+
+
+ the number of elements to allocate
+
+
+
+
+ Attempts to realloc @mem to a new size, @n_bytes, and returns %NULL
+on failure. Contrast with g_realloc(), which aborts the program
+on failure.
+
+If @mem is %NULL, behaves the same as g_try_malloc().
+
+
+ the allocated memory, or %NULL.
+
+
+
+
+ previously-allocated memory, or %NULL.
+
+
+
+ number of bytes to allocate.
+
+
+
+
+
+ This function is similar to g_try_realloc(), allocating (@n_blocks * @n_block_bytes) bytes,
+but care is taken to detect possible overflow during multiplication.
+
+
+ the allocated memory, or %NULL.
+
+
+
+
+ previously-allocated memory, or %NULL.
+
+
+
+ the number of blocks to allocate
+
+
+
+ the size of each block in bytes
+
+
+
+
+
+ Attempts to reallocate the memory pointed to by @mem, so that it now has
+space for @n_structs elements of type @struct_type, and returns %NULL on
+failure. Contrast with g_renew(), which aborts the program on failure.
+It returns the new address of the memory, which may have been moved.
+The function returns %NULL if an overflow occurs.
+
+
+
+ the type of the elements to allocate
+
+
+ the currently allocated memory
+
+
+ the number of elements to allocate
+
+
+
+
+ Many times GLib, GTK+, and other libraries allow you to pass "user
+data" to a callback, in the form of a void pointer. From time to time
+you want to pass an integer instead of a pointer. You could allocate
+an integer, with something like:
+|[<!-- language="C" -->
+ int *ip = g_new (int, 1);
+ *ip = 42;
+]|
+But this is inconvenient, and it's annoying to have to free the
+memory at some later time.
+
+Pointers are always at least 32 bits in size (on all platforms GLib
+intends to support). Thus you can store at least 32-bit integer values
+in a pointer value. Naively, you might try this, but it's incorrect:
+|[<!-- language="C" -->
+ gpointer p;
+ int i;
+ p = (void*) 42;
+ i = (int) p;
+]|
+Again, that example was not correct, don't copy it.
+The problem is that on some systems you need to do this:
+|[<!-- language="C" -->
+ gpointer p;
+ int i;
+ p = (void*) (long) 42;
+ i = (int) (long) p;
+]|
+The GLib macros GPOINTER_TO_INT(), GINT_TO_POINTER(), etc. take care
+to do the right thing on every platform.
+
+Warning: You may not store pointers in integers. This is not
+portable in any way, shape or form. These macros only allow storing
+integers in pointers, and only preserve 32 bits of the integer; values
+outside the range of a 32-bit integer will be mangled.
+
+
+
+
+
+
+
+
+
+ GLib defines a number of commonly used types, which can be divided
+into several groups:
+- New types which are not part of standard C (but are defined in
+ various C standard library header files) — #gboolean, #gssize.
+- Integer types which are guaranteed to be the same size across
+ all platforms — #gint8, #guint8, #gint16, #guint16, #gint32,
+ #guint32, #gint64, #guint64.
+- Types which are easier to use than their standard C counterparts -
+ #gpointer, #gconstpointer, #guchar, #guint, #gushort, #gulong.
+- Types which correspond exactly to standard C types, but are
+ included for completeness — #gchar, #gint, #gshort, #glong,
+ #gfloat, #gdouble.
+- Types which correspond exactly to standard C99 types, but are available
+ to use even if your compiler does not support C99 — #gsize, #goffset,
+ #gintptr, #guintptr.
+
+GLib also defines macros for the limits of some of the standard
+integer and floating point types, as well as macros for suitable
+printf() formats for these types.
+
+Note that depending on the platform and build configuration, the format
+macros might not be compatible with the system provided printf() function,
+because GLib might use a different printf() implementation internally.
+The format macros will always work with GLib API (like g_print()), and with
+any C99 compatible printf() implementation.
+
+
+ Convert a string from UCS-4 to UTF-16. A 0 character will be
+added to the result after the converted text.
+
+
+ a pointer to a newly allocated UTF-16 string.
+ This value must be freed with g_free(). If an error occurs,
+ %NULL will be returned and @error set.
+
+
+
+
+ a UCS-4 encoded string
+
+
+
+
+
+ the maximum length (number of characters) of @str to use.
+ If @len < 0, then the string is nul-terminated.
+
+
+
+ location to store number of
+ bytes read, or %NULL. If an error occurs then the index of the invalid
+ input is stored here.
+
+
+
+ location to store number
+ of #gunichar2 written, or %NULL. The value stored here does not include
+ the trailing 0.
+
+
+
+
+
+ Convert a string from a 32-bit fixed width representation as UCS-4.
+to UTF-8. The result will be terminated with a 0 byte.
+
+
+ a pointer to a newly allocated UTF-8 string.
+ This value must be freed with g_free(). If an error occurs,
+ %NULL will be returned and @error set. In that case, @items_read
+ will be set to the position of the first invalid input character.
+
+
+
+
+ a UCS-4 encoded string
+
+
+
+
+
+ the maximum length (number of characters) of @str to use.
+ If @len < 0, then the string is nul-terminated.
+
+
+
+ location to store number of
+ characters read, or %NULL.
+
+
+
+ location to store number
+ of bytes written or %NULL. The value here stored does not include the
+ trailing 0 byte.
+
+
+
+
+
+ Performs a checked addition of @a and @b, storing the result in
+@dest.
+
+If the operation is successful, %TRUE is returned. If the operation
+overflows then the state of @dest is undefined and %FALSE is
+returned.
+
+
+
+ a pointer to the #guint64 destination
+
+
+ the #guint64 left operand
+
+
+ the #guint64 right operand
+
+
+
+
+ Performs a checked multiplication of @a and @b, storing the result in
+@dest.
+
+If the operation is successful, %TRUE is returned. If the operation
+overflows then the state of @dest is undefined and %FALSE is
+returned.
+
+
+
+ a pointer to the #guint64 destination
+
+
+ the #guint64 left operand
+
+
+ the #guint64 right operand
+
+
+
+
+ Performs a checked addition of @a and @b, storing the result in
+@dest.
+
+If the operation is successful, %TRUE is returned. If the operation
+overflows then the state of @dest is undefined and %FALSE is
+returned.
+
+
+
+ a pointer to the #guint destination
+
+
+ the #guint left operand
+
+
+ the #guint right operand
+
+
+
+
+ Performs a checked multiplication of @a and @b, storing the result in
+@dest.
+
+If the operation is successful, %TRUE is returned. If the operation
+overflows then the state of @dest is undefined and %FALSE is
+returned.
+
+
+
+ a pointer to the #guint destination
+
+
+ the #guint left operand
+
+
+ the #guint right operand
+
+
+
+
+ Determines the break type of @c. @c should be a Unicode character
+(to derive a character from UTF-8 encoded text, use
+g_utf8_get_char()). The break type is used to find word and line
+breaks ("text boundaries"), Pango implements the Unicode boundary
+resolution algorithms and normally you would use a function such
+as pango_break() instead of caring about break types yourself.
+
+
+ the break type of @c
+
+
+
+
+ a Unicode character
+
+
+
+
+
+ Determines the canonical combining class of a Unicode character.
+
+
+ the combining class of the character
+
+
+
+
+ a Unicode character
+
+
+
+
+
+ Performs a single composition step of the
+Unicode canonical composition algorithm.
+
+This function includes algorithmic Hangul Jamo composition,
+but it is not exactly the inverse of g_unichar_decompose().
+No composition can have either of @a or @b equal to zero.
+To be precise, this function composes if and only if
+there exists a Primary Composite P which is canonically
+equivalent to the sequence <@a,@b>. See the Unicode
+Standard for the definition of Primary Composite.
+
+If @a and @b do not compose a new character, @ch is set to zero.
+
+See
+[UAX#15](http://unicode.org/reports/tr15/)
+for details.
+
+
+ %TRUE if the characters could be composed
+
+
+
+
+ a Unicode character
+
+
+
+ a Unicode character
+
+
+
+ return location for the composed character
+
+
+
+
+
+ Performs a single decomposition step of the
+Unicode canonical decomposition algorithm.
+
+This function does not include compatibility
+decompositions. It does, however, include algorithmic
+Hangul Jamo decomposition, as well as 'singleton'
+decompositions which replace a character by a single
+other character. In the case of singletons *@b will
+be set to zero.
+
+If @ch is not decomposable, *@a is set to @ch and *@b
+is set to zero.
+
+Note that the way Unicode decomposition pairs are
+defined, it is guaranteed that @b would not decompose
+further, but @a may itself decompose. To get the full
+canonical decomposition for @ch, one would need to
+recursively call this function on @a. Or use
+g_unichar_fully_decompose().
+
+See
+[UAX#15](http://unicode.org/reports/tr15/)
+for details.
+
+
+ %TRUE if the character could be decomposed
+
+
+
+
+ a Unicode character
+
+
+
+ return location for the first component of @ch
+
+
+
+ return location for the second component of @ch
+
+
+
+
+
+ Determines the numeric value of a character as a decimal
+digit.
+
+
+ If @c is a decimal digit (according to
+g_unichar_isdigit()), its numeric value. Otherwise, -1.
+
+
+
+
+ a Unicode character
+
+
+
+
+
+ Computes the canonical or compatibility decomposition of a
+Unicode character. For compatibility decomposition,
+pass %TRUE for @compat; for canonical decomposition
+pass %FALSE for @compat.
+
+The decomposed sequence is placed in @result. Only up to
+@result_len characters are written into @result. The length
+of the full decomposition (irrespective of @result_len) is
+returned by the function. For canonical decomposition,
+currently all decompositions are of length at most 4, but
+this may change in the future (very unlikely though).
+At any rate, Unicode does guarantee that a buffer of length
+18 is always enough for both compatibility and canonical
+decompositions, so that is the size recommended. This is provided
+as %G_UNICHAR_MAX_DECOMPOSITION_LENGTH.
+
+See
+[UAX#15](http://unicode.org/reports/tr15/)
+for details.
+
+
+ the length of the full decomposition.
+
+
+
+
+ a Unicode character.
+
+
+
+ whether perform canonical or compatibility decomposition
+
+
+
+ location to store decomposed result, or %NULL
+
+
+
+ length of @result
+
+
+
+
+
+ In Unicode, some characters are "mirrored". This means that their
+images are mirrored horizontally in text that is laid out from right
+to left. For instance, "(" would become its mirror image, ")", in
+right-to-left text.
+
+If @ch has the Unicode mirrored property and there is another unicode
+character that typically has a glyph that is the mirror image of @ch's
+glyph and @mirrored_ch is set, it puts that character in the address
+pointed to by @mirrored_ch. Otherwise the original character is put.
+
+
+ %TRUE if @ch has a mirrored character, %FALSE otherwise
+
+
+
+
+ a Unicode character
+
+
+
+ location to store the mirrored character
+
+
+
+
+
+ Looks up the #GUnicodeScript for a particular character (as defined
+by Unicode Standard Annex \#24). No check is made for @ch being a
+valid Unicode character; if you pass in invalid character, the
+result is undefined.
+
+This function is equivalent to pango_script_for_unichar() and the
+two are interchangeable.
+
+
+ the #GUnicodeScript for the character.
+
+
+
+
+ a Unicode character
+
+
+
+
+
+ Determines whether a character is alphanumeric.
+Given some UTF-8 text, obtain a character value
+with g_utf8_get_char().
+
+
+ %TRUE if @c is an alphanumeric character
+
+
+
+
+ a Unicode character
+
+
+
+
+
+ Determines whether a character is alphabetic (i.e. a letter).
+Given some UTF-8 text, obtain a character value with
+g_utf8_get_char().
+
+
+ %TRUE if @c is an alphabetic character
+
+
+
+
+ a Unicode character
+
+
+
+
+
+ Determines whether a character is a control character.
+Given some UTF-8 text, obtain a character value with
+g_utf8_get_char().
+
+
+ %TRUE if @c is a control character
+
+
+
+
+ a Unicode character
+
+
+
+
+
+ Determines if a given character is assigned in the Unicode
+standard.
+
+
+ %TRUE if the character has an assigned value
+
+
+
+
+ a Unicode character
+
+
+
+
+
+ Determines whether a character is numeric (i.e. a digit). This
+covers ASCII 0-9 and also digits in other languages/scripts. Given
+some UTF-8 text, obtain a character value with g_utf8_get_char().
+
+
+ %TRUE if @c is a digit
+
+
+
+
+ a Unicode character
+
+
+
+
+
+ Determines whether a character is printable and not a space
+(returns %FALSE for control characters, format characters, and
+spaces). g_unichar_isprint() is similar, but returns %TRUE for
+spaces. Given some UTF-8 text, obtain a character value with
+g_utf8_get_char().
+
+
+ %TRUE if @c is printable unless it's a space
+
+
+
+
+ a Unicode character
+
+
+
+
+
+ Determines whether a character is a lowercase letter.
+Given some UTF-8 text, obtain a character value with
+g_utf8_get_char().
+
+
+ %TRUE if @c is a lowercase letter
+
+
+
+
+ a Unicode character
+
+
+
+
+
+ Determines whether a character is a mark (non-spacing mark,
+combining mark, or enclosing mark in Unicode speak).
+Given some UTF-8 text, obtain a character value
+with g_utf8_get_char().
+
+Note: in most cases where isalpha characters are allowed,
+ismark characters should be allowed to as they are essential
+for writing most European languages as well as many non-Latin
+scripts.
+
+
+ %TRUE if @c is a mark character
+
+
+
+
+ a Unicode character
+
+
+
+
+
+ Determines whether a character is printable.
+Unlike g_unichar_isgraph(), returns %TRUE for spaces.
+Given some UTF-8 text, obtain a character value with
+g_utf8_get_char().
+
+
+ %TRUE if @c is printable
+
+
+
+
+ a Unicode character
+
+
+
+
+
+ Determines whether a character is punctuation or a symbol.
+Given some UTF-8 text, obtain a character value with
+g_utf8_get_char().
+
+
+ %TRUE if @c is a punctuation or symbol character
+
+
+
+
+ a Unicode character
+
+
+
+
+
+ Determines whether a character is a space, tab, or line separator
+(newline, carriage return, etc.). Given some UTF-8 text, obtain a
+character value with g_utf8_get_char().
+
+(Note: don't use this to do word breaking; you have to use
+Pango or equivalent to get word breaking right, the algorithm
+is fairly complex.)
+
+
+ %TRUE if @c is a space character
+
+
+
+
+ a Unicode character
+
+
+
+
+
+ Determines if a character is titlecase. Some characters in
+Unicode which are composites, such as the DZ digraph
+have three case variants instead of just two. The titlecase
+form is used at the beginning of a word where only the
+first letter is capitalized. The titlecase form of the DZ
+digraph is U+01F2 LATIN CAPITAL LETTTER D WITH SMALL LETTER Z.
+
+
+ %TRUE if the character is titlecase
+
+
+
+
+ a Unicode character
+
+
+
+
+
+ Determines if a character is uppercase.
+
+
+ %TRUE if @c is an uppercase character
+
+
+
+
+ a Unicode character
+
+
+
+
+
+ Determines if a character is typically rendered in a double-width
+cell.
+
+
+ %TRUE if the character is wide
+
+
+
+
+ a Unicode character
+
+
+
+
+
+ Determines if a character is typically rendered in a double-width
+cell under legacy East Asian locales. If a character is wide according to
+g_unichar_iswide(), then it is also reported wide with this function, but
+the converse is not necessarily true. See the
+[Unicode Standard Annex #11](http://www.unicode.org/reports/tr11/)
+for details.
+
+If a character passes the g_unichar_iswide() test then it will also pass
+this test, but not the other way around. Note that some characters may
+pass both this test and g_unichar_iszerowidth().
+
+
+ %TRUE if the character is wide in legacy East Asian locales
+
+
+
+
+ a Unicode character
+
+
+
+
+
+ Determines if a character is a hexadecimal digit.
+
+
+ %TRUE if the character is a hexadecimal digit
+
+
+
+
+ a Unicode character.
+
+
+
+
+
+ Determines if a given character typically takes zero width when rendered.
+The return value is %TRUE for all non-spacing and enclosing marks
+(e.g., combining accents), format characters, zero-width
+space, but not U+00AD SOFT HYPHEN.
+
+A typical use of this function is with one of g_unichar_iswide() or
+g_unichar_iswide_cjk() to determine the number of cells a string occupies
+when displayed on a grid display (terminals). However, note that not all
+terminals support zero-width rendering of zero-width marks.
+
+
+ %TRUE if the character has zero width
+
+
+
+
+ a Unicode character
+
+
+
+
+
+ Converts a single character to UTF-8.
+
+
+ number of bytes written
+
+
+
+
+ a Unicode character code
+
+
+
+ output buffer, must have at
+ least 6 bytes of space. If %NULL, the length will be computed and
+ returned and nothing will be written to @outbuf.
+
+
+
+
+
+ Converts a character to lower case.
+
+
+ the result of converting @c to lower case.
+ If @c is not an upperlower or titlecase character,
+ or has no lowercase equivalent @c is returned unchanged.
+
+
+
+
+ a Unicode character.
+
+
+
+
+
+ Converts a character to the titlecase.
+
+
+ the result of converting @c to titlecase.
+ If @c is not an uppercase or lowercase character,
+ @c is returned unchanged.
+
+
+
+
+ a Unicode character
+
+
+
+
+
+ Converts a character to uppercase.
+
+
+ the result of converting @c to uppercase.
+ If @c is not a lowercase or titlecase character,
+ or has no upper case equivalent @c is returned unchanged.
+
+
+
+
+ a Unicode character
+
+
+
+
+
+ Classifies a Unicode character by type.
+
+
+ the type of the character.
+
+
+
+
+ a Unicode character
+
+
+
+
+
+ Checks whether @ch is a valid Unicode character. Some possible
+integer values of @ch will not be valid. 0 is considered a valid
+character, though it's normally a string terminator.
+
+
+ %TRUE if @ch is a valid Unicode character
+
+
+
+
+ a Unicode character
+
+
+
+
+
+ Determines the numeric value of a character as a hexadecimal
+digit.
+
+
+ If @c is a hex digit (according to
+g_unichar_isxdigit()), its numeric value. Otherwise, -1.
+
+
+
+
+ a Unicode character
+
+
+
+
+
+ This section describes a number of functions for dealing with
+Unicode characters and strings. There are analogues of the
+traditional `ctype.h` character classification and case conversion
+functions, UTF-8 analogues of some string utility functions,
+functions to perform normalization, case conversion and collation
+on UTF-8 strings and finally functions to convert between the UTF-8,
+UTF-16 and UCS-4 encodings of Unicode.
+
+The implementations of the Unicode functions in GLib are based
+on the Unicode Character Data tables, which are available from
+[www.unicode.org](http://www.unicode.org/).
+
+ * Unicode 4.0 was added in GLib 2.8
+ * Unicode 4.1 was added in GLib 2.10
+ * Unicode 5.0 was added in GLib 2.12
+ * Unicode 5.1 was added in GLib 2.16.3
+ * Unicode 6.0 was added in GLib 2.30
+ * Unicode 6.1 was added in GLib 2.32
+ * Unicode 6.2 was added in GLib 2.36
+ * Unicode 6.3 was added in GLib 2.40
+ * Unicode 7.0 was added in GLib 2.42
+ * Unicode 8.0 was added in GLib 2.48
+ * Unicode 9.0 was added in GLib 2.50.1
+ * Unicode 10.0 was added in GLib 2.54
+ * Unicode 11.10 was added in GLib 2.58
+ * Unicode 12.0 was added in GLib 2.62
+ * Unicode 12.1 was added in GLib 2.62
+ * Unicode 13.0 was added in GLib 2.66
+
+
+ Computes the canonical decomposition of a Unicode character.
+ Use the more flexible g_unichar_fully_decompose()
+ instead.
+
+
+ a newly allocated string of Unicode characters.
+ @result_len is set to the resulting length of the string.
+
+
+
+
+ a Unicode character.
+
+
+
+ location to store the length of the return value.
+
+
+
+
+
+ Computes the canonical ordering of a string in-place.
+This rearranges decomposed characters in the string
+according to their combining classes. See the Unicode
+manual for more information.
+
+
+
+
+
+
+ a UCS-4 encoded string.
+
+
+
+
+
+ the maximum length of @string to use.
+
+
+
+
+
+ Looks up the Unicode script for @iso15924. ISO 15924 assigns four-letter
+codes to scripts. For example, the code for Arabic is 'Arab'.
+This function accepts four letter codes encoded as a @guint32 in a
+big-endian fashion. That is, the code expected for Arabic is
+0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc).
+
+See
+[Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html)
+for details.
+
+
+ the Unicode script for @iso15924, or
+ of %G_UNICODE_SCRIPT_INVALID_CODE if @iso15924 is zero and
+ %G_UNICODE_SCRIPT_UNKNOWN if @iso15924 is unknown.
+
+
+
+
+ a Unicode script
+
+
+
+
+
+ Looks up the ISO 15924 code for @script. ISO 15924 assigns four-letter
+codes to scripts. For example, the code for Arabic is 'Arab'. The
+four letter codes are encoded as a @guint32 by this function in a
+big-endian fashion. That is, the code returned for Arabic is
+0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc).
+
+See
+[Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html)
+for details.
+
+
+ the ISO 15924 code for @script, encoded as an integer,
+ of zero if @script is %G_UNICODE_SCRIPT_INVALID_CODE or
+ ISO 15924 code 'Zzzz' (script code for UNKNOWN) if @script is not understood.
+
+
+
+
+ a Unicode script
+
+
+
+
+
+
+
+
+
+
+ Sets a function to be called when the IO condition, as specified by
+@condition becomes true for @fd.
+
+@function will be called when the specified IO condition becomes
+%TRUE. The function is expected to clear whatever event caused the
+IO condition to become true and return %TRUE in order to be notified
+when it happens again. If @function returns %FALSE then the watch
+will be cancelled.
+
+The return value of this function can be passed to g_source_remove()
+to cancel the watch at any time that it exists.
+
+The source will never close the fd -- you must do it yourself.
+
+
+ the ID (greater than 0) of the event source
+
+
+
+
+ a file descriptor
+
+
+
+ IO conditions to watch for on @fd
+
+
+
+ a #GUnixFDSourceFunc
+
+
+
+ data to pass to @function
+
+
+
+
+
+ Sets a function to be called when the IO condition, as specified by
+@condition becomes true for @fd.
+
+This is the same as g_unix_fd_add(), except that it allows you to
+specify a non-default priority and a provide a #GDestroyNotify for
+@user_data.
+
+
+ the ID (greater than 0) of the event source
+
+
+
+
+ the priority of the source
+
+
+
+ a file descriptor
+
+
+
+ IO conditions to watch for on @fd
+
+
+
+ a #GUnixFDSourceFunc
+
+
+
+ data to pass to @function
+
+
+
+ function to call when the idle is removed, or %NULL
+
+
+
+
+
+ Creates a #GSource to watch for a particular IO condition on a file
+descriptor.
+
+The source will never close the fd -- you must do it yourself.
+
+
+ the newly created #GSource
+
+
+
+
+ a file descriptor
+
+
+
+ IO conditions to watch for on @fd
+
+
+
+
+
+ Get the `passwd` file entry for the given @user_name using `getpwnam_r()`.
+This can fail if the given @user_name doesn’t exist.
+
+The returned `struct passwd` has been allocated using g_malloc() and should
+be freed using g_free(). The strings referenced by the returned struct are
+included in the same allocation, so are valid until the `struct passwd` is
+freed.
+
+This function is safe to call from multiple threads concurrently.
+
+You will need to include `pwd.h` to get the definition of `struct passwd`.
+
+
+ passwd entry, or %NULL on error; free the returned
+ value with g_free()
+
+
+
+
+ the username to get the passwd file entry for
+
+
+
+
+
+ Similar to the UNIX pipe() call, but on modern systems like Linux
+uses the pipe2() system call, which atomically creates a pipe with
+the configured flags. The only supported flag currently is
+%FD_CLOEXEC. If for example you want to configure %O_NONBLOCK, that
+must still be done separately with fcntl().
+
+This function does not take %O_CLOEXEC, it takes %FD_CLOEXEC as if
+for fcntl(); these are different on Linux/glibc.
+
+
+ %TRUE on success, %FALSE if not (and errno will be set).
+
+
+
+
+ Array of two integers
+
+
+
+
+
+ Bitfield of file descriptor flags, as for fcntl()
+
+
+
+
+
+ Control the non-blocking state of the given file descriptor,
+according to @nonblock. On most systems this uses %O_NONBLOCK, but
+on some older ones may use %O_NDELAY.
+
+
+ %TRUE if successful
+
+
+
+
+ A file descriptor
+
+
+
+ If %TRUE, set the descriptor to be non-blocking
+
+
+
+
+
+ A convenience function for g_unix_signal_source_new(), which
+attaches to the default #GMainContext. You can remove the watch
+using g_source_remove().
+
+
+ An ID (greater than 0) for the event source
+
+
+
+
+ Signal number
+
+
+
+ Callback
+
+
+
+ Data for @handler
+
+
+
+
+
+ A convenience function for g_unix_signal_source_new(), which
+attaches to the default #GMainContext. You can remove the watch
+using g_source_remove().
+
+
+ An ID (greater than 0) for the event source
+
+
+
+
+ the priority of the signal source. Typically this will be in
+ the range between %G_PRIORITY_DEFAULT and %G_PRIORITY_HIGH.
+
+
+
+ Signal number
+
+
+
+ Callback
+
+
+
+ Data for @handler
+
+
+
+ #GDestroyNotify for @handler
+
+
+
+
+
+ Create a #GSource that will be dispatched upon delivery of the UNIX
+signal @signum. In GLib versions before 2.36, only `SIGHUP`, `SIGINT`,
+`SIGTERM` can be monitored. In GLib 2.36, `SIGUSR1` and `SIGUSR2`
+were added. In GLib 2.54, `SIGWINCH` was added.
+
+Note that unlike the UNIX default, all sources which have created a
+watch will be dispatched, regardless of which underlying thread
+invoked g_unix_signal_source_new().
+
+For example, an effective use of this function is to handle `SIGTERM`
+cleanly; flushing any outstanding files, and then calling
+g_main_loop_quit(). It is not safe to do any of this from a regular
+UNIX signal handler; such a handler may be invoked while malloc() or
+another library function is running, causing reentrancy issues if the
+handler attempts to use those functions. None of the GLib/GObject
+API is safe against this kind of reentrancy.
+
+The interaction of this source when combined with native UNIX
+functions like sigprocmask() is not defined.
+
+The source will not initially be associated with any #GMainContext
+and must be added to one with g_source_attach() before it will be
+executed.
+
+
+ A newly created #GSource
+
+
+
+
+ A signal number
+
+
+
+
+
+ A wrapper for the POSIX unlink() function. The unlink() function
+deletes a name from the filesystem. If this was the last link to the
+file and no processes have it opened, the diskspace occupied by the
+file is freed.
+
+See your C library manual for more details about unlink(). Note
+that on Windows, it is in general not possible to delete files that
+are open to some process, or mapped into memory.
+
+
+ 0 if the name was successfully deleted, -1 if an error
+ occurred
+
+
+
+
+ a pathname in the GLib file name encoding
+ (UTF-8 on Windows)
+
+
+
+
+
+ Removes an environment variable from the environment.
+
+Note that on some systems, when variables are overwritten, the
+memory used for the previous variables and its value isn't reclaimed.
+
+You should be mindful of the fact that environment variable handling
+in UNIX is not thread-safe, and your program may crash if one thread
+calls g_unsetenv() while another thread is calling getenv(). (And note
+that many functions, such as gettext(), call getenv() internally.) This
+function is only safe to use at the very start of your program, before
+creating any other threads (or creating objects that create worker
+threads of their own).
+
+If you need to set up the environment for a child process, you can
+use g_get_environ() to get an environment array, modify that with
+g_environ_setenv() and g_environ_unsetenv(), and then pass that
+array directly to execvpe(), g_spawn_async(), or the like.
+
+
+
+
+
+
+ the environment variable to remove, must
+ not contain '='
+
+
+
+
+
+ Creates a new #GUri from the given components according to @flags.
+
+See also g_uri_build_with_user(), which allows specifying the
+components of the "userinfo" separately.
+
+
+ a new #GUri
+
+
+
+
+ flags describing how to build the #GUri
+
+
+
+ the URI scheme
+
+
+
+ the userinfo component, or %NULL
+
+
+
+ the host component, or %NULL
+
+
+
+ the port, or `-1`
+
+
+
+ the path component
+
+
+
+ the query component, or %NULL
+
+
+
+ the fragment, or %NULL
+
+
+
+
+
+ Creates a new #GUri from the given components according to @flags
+(%G_URI_FLAGS_HAS_PASSWORD is added unconditionally). The @flags must be
+coherent with the passed values, in particular use `%`-encoded values with
+%G_URI_FLAGS_ENCODED.
+
+In contrast to g_uri_build(), this allows specifying the components
+of the ‘userinfo’ field separately. Note that @user must be non-%NULL
+if either @password or @auth_params is non-%NULL.
+
+
+ a new #GUri
+
+
+
+
+ flags describing how to build the #GUri
+
+
+
+ the URI scheme
+
+
+
+ the user component of the userinfo, or %NULL
+
+
+
+ the password component of the userinfo, or %NULL
+
+
+
+ the auth params of the userinfo, or %NULL
+
+
+
+ the host component, or %NULL
+
+
+
+ the port, or `-1`
+
+
+
+ the path component
+
+
+
+ the query component, or %NULL
+
+
+
+ the fragment, or %NULL
+
+
+
+
+
+
+
+
+
+
+ Escapes arbitrary data for use in a URI.
+
+Normally all characters that are not ‘unreserved’ (i.e. ASCII
+alphanumerical characters plus dash, dot, underscore and tilde) are
+escaped. But if you specify characters in @reserved_chars_allowed
+they are not escaped. This is useful for the ‘reserved’ characters
+in the URI specification, since those are allowed unescaped in some
+portions of a URI.
+
+Though technically incorrect, this will also allow escaping nul
+bytes as `%``00`.
+
+
+ an escaped version of @unescaped.
+ The returned string should be freed when no longer needed.
+
+
+
+
+ the unescaped input data.
+
+
+
+
+
+ the length of @unescaped
+
+
+
+ a string of reserved
+ characters that are allowed to be used, or %NULL.
+
+
+
+
+
+ Escapes a string for use in a URI.
+
+Normally all characters that are not "unreserved" (i.e. ASCII
+alphanumerical characters plus dash, dot, underscore and tilde) are
+escaped. But if you specify characters in @reserved_chars_allowed
+they are not escaped. This is useful for the "reserved" characters
+in the URI specification, since those are allowed unescaped in some
+portions of a URI.
+
+
+ an escaped version of @unescaped. The
+returned string should be freed when no longer needed.
+
+
+
+
+ the unescaped input string.
+
+
+
+ a string of reserved
+ characters that are allowed to be used, or %NULL.
+
+
+
+ %TRUE if the result can include UTF-8 characters.
+
+
+
+
+
+ Parses @uri_string according to @flags, to determine whether it is a valid
+[absolute URI][relative-absolute-uris], i.e. it does not need to be resolved
+relative to another URI using g_uri_parse_relative().
+
+If it’s not a valid URI, an error is returned explaining how it’s invalid.
+
+See g_uri_split(), and the definition of #GUriFlags, for more
+information on the effect of @flags.
+
+
+ %TRUE if @uri_string is a valid absolute URI, %FALSE on error.
+
+
+
+
+ a string containing an absolute URI
+
+
+
+ flags for parsing @uri_string
+
+
+
+
+
+ Joins the given components together according to @flags to create
+an absolute URI string. @path may not be %NULL (though it may be the empty
+string).
+
+When @host is present, @path must either be empty or begin with a slash (`/`)
+character. When @host is not present, @path cannot begin with two slash
+ characters (`//`). See
+[RFC 3986, section 3](https://tools.ietf.org/html/rfc3986#section-3).
+
+See also g_uri_join_with_user(), which allows specifying the
+components of the ‘userinfo’ separately.
+
+%G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set
+in @flags.
+
+
+ an absolute URI string
+
+
+
+
+ flags describing how to build the URI string
+
+
+
+ the URI scheme, or %NULL
+
+
+
+ the userinfo component, or %NULL
+
+
+
+ the host component, or %NULL
+
+
+
+ the port, or `-1`
+
+
+
+ the path component
+
+
+
+ the query component, or %NULL
+
+
+
+ the fragment, or %NULL
+
+
+
+
+
+ Joins the given components together according to @flags to create
+an absolute URI string. @path may not be %NULL (though it may be the empty
+string).
+
+In contrast to g_uri_join(), this allows specifying the components
+of the ‘userinfo’ separately. It otherwise behaves the same.
+
+%G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set
+in @flags.
+
+
+ an absolute URI string
+
+
+
+
+ flags describing how to build the URI string
+
+
+
+ the URI scheme, or %NULL
+
+
+
+ the user component of the userinfo, or %NULL
+
+
+
+ the password component of the userinfo, or
+ %NULL
+
+
+
+ the auth params of the userinfo, or
+ %NULL
+
+
+
+ the host component, or %NULL
+
+
+
+ the port, or `-1`
+
+
+
+ the path component
+
+
+
+ the query component, or %NULL
+
+
+
+ the fragment, or %NULL
+
+
+
+
+
+ Splits an URI list conforming to the text/uri-list
+mime type defined in RFC 2483 into individual URIs,
+discarding any comments. The URIs are not validated.
+
+
+ a newly allocated %NULL-terminated list
+ of strings holding the individual URIs. The array should be freed
+ with g_strfreev().
+
+
+
+
+
+
+ an URI list
+
+
+
+
+
+ Parses @uri_string according to @flags. If the result is not a
+valid [absolute URI][relative-absolute-uris], it will be discarded, and an
+error returned.
+
+
+ a new #GUri, or NULL on error.
+
+
+
+
+ a string representing an absolute URI
+
+
+
+ flags describing how to parse @uri_string
+
+
+
+
+
+ Many URI schemes include one or more attribute/value pairs as part of the URI
+value. This method can be used to parse them into a hash table. When an
+attribute has multiple occurrences, the last value is the final returned
+value. If you need to handle repeated attributes differently, use
+#GUriParamsIter.
+
+The @params string is assumed to still be `%`-encoded, but the returned
+values will be fully decoded. (Thus it is possible that the returned values
+may contain `=` or @separators, if the value was encoded in the input.)
+Invalid `%`-encoding is treated as with the %G_URI_FLAGS_PARSE_RELAXED
+rules for g_uri_parse(). (However, if @params is the path or query string
+from a #GUri that was parsed without %G_URI_FLAGS_PARSE_RELAXED and
+%G_URI_FLAGS_ENCODED, then you already know that it does not contain any
+invalid encoding.)
+
+%G_URI_PARAMS_WWW_FORM is handled as documented for g_uri_params_iter_init().
+
+If %G_URI_PARAMS_CASE_INSENSITIVE is passed to @flags, attributes will be
+compared case-insensitively, so a params string `attr=123&Attr=456` will only
+return a single attribute–value pair, `Attr=456`. Case will be preserved in
+the returned attributes.
+
+If @params cannot be parsed (for example, it contains two @separators
+characters in a row), then @error is set and %NULL is returned.
+
+
+
+ A hash table of attribute/value pairs, with both names and values
+ fully-decoded; or %NULL on error.
+
+
+
+
+
+
+
+ a `%`-encoded string containing `attribute=value`
+ parameters
+
+
+
+ the length of @params, or `-1` if it is nul-terminated
+
+
+
+ the separator byte character set between parameters. (usually
+ `&`, but sometimes `;` or both `&;`). Note that this function works on
+ bytes not characters, so it can't be used to delimit UTF-8 strings for
+ anything but ASCII characters. You may pass an empty set, in which case
+ no splitting will occur.
+
+
+
+ flags to modify the way the parameters are handled.
+
+
+
+
+
+ Gets the scheme portion of a URI string.
+[RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme
+as:
+|[
+URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
+]|
+Common schemes include `file`, `https`, `svn+ssh`, etc.
+
+
+ The ‘scheme’ component of the URI, or
+ %NULL on error. The returned string should be freed when no longer needed.
+
+
+
+
+ a valid URI.
+
+
+
+
+
+ Gets the scheme portion of a URI string.
+[RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme
+as:
+|[
+URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
+]|
+Common schemes include `file`, `https`, `svn+ssh`, etc.
+
+Unlike g_uri_parse_scheme(), the returned scheme is normalized to
+all-lowercase and does not need to be freed.
+
+
+ The ‘scheme’ component of the URI, or
+ %NULL on error. The returned string is normalized to all-lowercase, and
+ interned via g_intern_string(), so it does not need to be freed.
+
+
+
+
+ a valid URI.
+
+
+
+
+
+ Parses @uri_ref according to @flags and, if it is a
+[relative URI][relative-absolute-uris], resolves it relative to
+@base_uri_string. If the result is not a valid absolute URI, it will be
+discarded, and an error returned.
+
+(If @base_uri_string is %NULL, this just returns @uri_ref, or
+%NULL if @uri_ref is invalid or not absolute.)
+
+
+ the resolved URI string,
+or NULL on error.
+
+
+
+
+ a string representing a base URI
+
+
+
+ a string representing a relative or absolute URI
+
+
+
+ flags describing how to parse @uri_ref
+
+
+
+
+
+ Parses @uri_ref (which can be an
+[absolute or relative URI][relative-absolute-uris]) according to @flags, and
+returns the pieces. Any component that doesn't appear in @uri_ref will be
+returned as %NULL (but note that all URIs always have a path component,
+though it may be the empty string).
+
+If @flags contains %G_URI_FLAGS_ENCODED, then `%`-encoded characters in
+@uri_ref will remain encoded in the output strings. (If not,
+then all such characters will be decoded.) Note that decoding will
+only work if the URI components are ASCII or UTF-8, so you will
+need to use %G_URI_FLAGS_ENCODED if they are not.
+
+Note that the %G_URI_FLAGS_HAS_PASSWORD and
+%G_URI_FLAGS_HAS_AUTH_PARAMS @flags are ignored by g_uri_split(),
+since it always returns only the full userinfo; use
+g_uri_split_with_user() if you want it split up.
+
+
+ %TRUE if @uri_ref parsed successfully, %FALSE
+ on error.
+
+
+
+
+ a string containing a relative or absolute URI
+
+
+
+ flags for parsing @uri_ref
+
+
+
+ on return, contains
+ the scheme (converted to lowercase), or %NULL
+
+
+
+ on return, contains
+ the userinfo, or %NULL
+
+
+
+ on return, contains the
+ host, or %NULL
+
+
+
+ on return, contains the
+ port, or `-1`
+
+
+
+ on return, contains the
+ path
+
+
+
+ on return, contains the
+ query, or %NULL
+
+
+
+ on return, contains
+ the fragment, or %NULL
+
+
+
+
+
+ Parses @uri_string (which must be an [absolute URI][relative-absolute-uris])
+according to @flags, and returns the pieces relevant to connecting to a host.
+See the documentation for g_uri_split() for more details; this is
+mostly a wrapper around that function with simpler arguments.
+However, it will return an error if @uri_string is a relative URI,
+or does not contain a hostname component.
+
+
+ %TRUE if @uri_string parsed successfully,
+ %FALSE on error.
+
+
+
+
+ a string containing an absolute URI
+
+
+
+ flags for parsing @uri_string
+
+
+
+ on return, contains
+ the scheme (converted to lowercase), or %NULL
+
+
+
+ on return, contains the
+ host, or %NULL
+
+
+
+ on return, contains the
+ port, or `-1`
+
+
+
+
+
+ Parses @uri_ref (which can be an
+[absolute or relative URI][relative-absolute-uris]) according to @flags, and
+returns the pieces. Any component that doesn't appear in @uri_ref will be
+returned as %NULL (but note that all URIs always have a path component,
+though it may be the empty string).
+
+See g_uri_split(), and the definition of #GUriFlags, for more
+information on the effect of @flags. Note that @password will only
+be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and
+@auth_params will only be parsed out if @flags contains
+%G_URI_FLAGS_HAS_AUTH_PARAMS.
+
+
+ %TRUE if @uri_ref parsed successfully, %FALSE
+ on error.
+
+
+
+
+ a string containing a relative or absolute URI
+
+
+
+ flags for parsing @uri_ref
+
+
+
+ on return, contains
+ the scheme (converted to lowercase), or %NULL
+
+
+
+ on return, contains
+ the user, or %NULL
+
+
+
+ on return, contains
+ the password, or %NULL
+
+
+
+ on return, contains
+ the auth_params, or %NULL
+
+
+
+ on return, contains the
+ host, or %NULL
+
+
+
+ on return, contains the
+ port, or `-1`
+
+
+
+ on return, contains the
+ path
+
+
+
+ on return, contains the
+ query, or %NULL
+
+
+
+ on return, contains
+ the fragment, or %NULL
+
+
+
+
+
+ Unescapes a segment of an escaped string as binary data.
+
+Note that in contrast to g_uri_unescape_string(), this does allow
+nul bytes to appear in the output.
+
+If any of the characters in @illegal_characters appears as an escaped
+character in @escaped_string, then that is an error and %NULL will be
+returned. This is useful if you want to avoid for instance having a slash
+being expanded in an escaped path element, which might confuse pathname
+handling.
+
+
+ an unescaped version of @escaped_string
+ or %NULL on error (if decoding failed, using %G_URI_ERROR_FAILED error
+ code). The returned #GBytes should be unreffed when no longer needed.
+
+
+
+
+ A URI-escaped string
+
+
+
+ the length (in bytes) of @escaped_string to escape, or `-1` if it
+ is nul-terminated.
+
+
+
+ a string of illegal characters
+ not to be allowed, or %NULL.
+
+
+
+
+
+ Unescapes a segment of an escaped string.
+
+If any of the characters in @illegal_characters or the NUL
+character appears as an escaped character in @escaped_string, then
+that is an error and %NULL will be returned. This is useful if you
+want to avoid for instance having a slash being expanded in an
+escaped path element, which might confuse pathname handling.
+
+Note: `NUL` byte is not accepted in the output, in contrast to
+g_uri_unescape_bytes().
+
+
+ an unescaped version of @escaped_string,
+or %NULL on error. The returned string should be freed when no longer
+needed. As a special case if %NULL is given for @escaped_string, this
+function will return %NULL.
+
+
+
+
+ A string, may be %NULL
+
+
+
+ Pointer to end of @escaped_string,
+ may be %NULL
+
+
+
+ An optional string of illegal
+ characters not to be allowed, may be %NULL
+
+
+
+
+
+ Unescapes a whole escaped string.
+
+If any of the characters in @illegal_characters or the NUL
+character appears as an escaped character in @escaped_string, then
+that is an error and %NULL will be returned. This is useful if you
+want to avoid for instance having a slash being expanded in an
+escaped path element, which might confuse pathname handling.
+
+
+ an unescaped version of @escaped_string.
+The returned string should be freed when no longer needed.
+
+
+
+
+ an escaped string to be unescaped.
+
+
+
+ a string of illegal characters
+ not to be allowed, or %NULL.
+
+
+
+
+
+ Pauses the current thread for the given number of microseconds.
+
+There are 1 million microseconds per second (represented by the
+%G_USEC_PER_SEC macro). g_usleep() may have limited precision,
+depending on hardware and operating system; don't rely on the exact
+length of the sleep.
+
+
+
+
+
+
+ number of microseconds to pause
+
+
+
+
+
+ Convert a string from UTF-16 to UCS-4. The result will be
+nul-terminated.
+
+
+ a pointer to a newly allocated UCS-4 string.
+ This value must be freed with g_free(). If an error occurs,
+ %NULL will be returned and @error set.
+
+
+
+
+ a UTF-16 encoded string
+
+
+
+
+
+ the maximum length (number of #gunichar2) of @str to use.
+ If @len < 0, then the string is nul-terminated.
+
+
+
+ location to store number of
+ words read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will
+ be returned in case @str contains a trailing partial character. If
+ an error occurs then the index of the invalid input is stored here.
+
+
+
+ location to store number
+ of characters written, or %NULL. The value stored here does not include
+ the trailing 0 character.
+
+
+
+
+
+ Convert a string from UTF-16 to UTF-8. The result will be
+terminated with a 0 byte.
+
+Note that the input is expected to be already in native endianness,
+an initial byte-order-mark character is not handled specially.
+g_convert() can be used to convert a byte buffer of UTF-16 data of
+ambiguous endianness.
+
+Further note that this function does not validate the result
+string; it may e.g. include embedded NUL characters. The only
+validation done by this function is to ensure that the input can
+be correctly interpreted as UTF-16, i.e. it doesn't contain
+unpaired surrogates or partial character sequences.
+
+
+ a pointer to a newly allocated UTF-8 string.
+ This value must be freed with g_free(). If an error occurs,
+ %NULL will be returned and @error set.
+
+
+
+
+ a UTF-16 encoded string
+
+
+
+
+
+ the maximum length (number of #gunichar2) of @str to use.
+ If @len < 0, then the string is nul-terminated.
+
+
+
+ location to store number of
+ words read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will
+ be returned in case @str contains a trailing partial character. If
+ an error occurs then the index of the invalid input is stored here.
+ It’s guaranteed to be non-negative.
+
+
+
+ location to store number
+ of bytes written, or %NULL. The value stored here does not include the
+ trailing 0 byte. It’s guaranteed to be non-negative.
+
+
+
+
+
+ Converts a string into a form that is independent of case. The
+result will not correspond to any particular case, but can be
+compared for equality or ordered with the results of calling
+g_utf8_casefold() on other strings.
+
+Note that calling g_utf8_casefold() followed by g_utf8_collate() is
+only an approximation to the correct linguistic case insensitive
+ordering, though it is a fairly good one. Getting this exactly
+right would require a more sophisticated collation function that
+takes case sensitivity into account. GLib does not currently
+provide such a function.
+
+
+ a newly allocated string, that is a
+ case independent form of @str.
+
+
+
+
+ a UTF-8 encoded string
+
+
+
+ length of @str, in bytes, or -1 if @str is nul-terminated.
+
+
+
+
+
+ Compares two strings for ordering using the linguistically
+correct rules for the [current locale][setlocale].
+When sorting a large number of strings, it will be significantly
+faster to obtain collation keys with g_utf8_collate_key() and
+compare the keys with strcmp() when sorting instead of sorting
+the original strings.
+
+If the two strings are not comparable due to being in different collation
+sequences, the result is undefined. This can happen if the strings are in
+different language scripts, for example.
+
+
+ < 0 if @str1 compares before @str2,
+ 0 if they compare equal, > 0 if @str1 compares after @str2.
+
+
+
+
+ a UTF-8 encoded string
+
+
+
+ a UTF-8 encoded string
+
+
+
+
+
+ Converts a string into a collation key that can be compared
+with other collation keys produced by the same function using
+strcmp().
+
+The results of comparing the collation keys of two strings
+with strcmp() will always be the same as comparing the two
+original keys with g_utf8_collate().
+
+Note that this function depends on the [current locale][setlocale].
+
+
+ a newly allocated string. This string should
+ be freed with g_free() when you are done with it.
+
+
+
+
+ a UTF-8 encoded string.
+
+
+
+ length of @str, in bytes, or -1 if @str is nul-terminated.
+
+
+
+
+
+ Converts a string into a collation key that can be compared
+with other collation keys produced by the same function using strcmp().
+
+In order to sort filenames correctly, this function treats the dot '.'
+as a special case. Most dictionary orderings seem to consider it
+insignificant, thus producing the ordering "event.c" "eventgenerator.c"
+"event.h" instead of "event.c" "event.h" "eventgenerator.c". Also, we
+would like to treat numbers intelligently so that "file1" "file10" "file5"
+is sorted as "file1" "file5" "file10".
+
+Note that this function depends on the [current locale][setlocale].
+
+
+ a newly allocated string. This string should
+ be freed with g_free() when you are done with it.
+
+
+
+
+ a UTF-8 encoded string.
+
+
+
+ length of @str, in bytes, or -1 if @str is nul-terminated.
+
+
+
+
+
+ Finds the start of the next UTF-8 character in the string after @p.
+
+@p does not have to be at the beginning of a UTF-8 character. No check
+is made to see if the character found is actually valid other than
+it starts with an appropriate byte.
+
+If @end is %NULL, the return value will never be %NULL: if the end of the
+string is reached, a pointer to the terminating nul byte is returned. If
+@end is non-%NULL, the return value will be %NULL if the end of the string
+is reached.
+
+
+ a pointer to the found character or %NULL if @end is
+ set and is reached
+
+
+
+
+ a pointer to a position within a UTF-8 encoded string
+
+
+
+ a pointer to the byte following the end of the string,
+ or %NULL to indicate that the string is nul-terminated
+
+
+
+
+
+ Given a position @p with a UTF-8 encoded string @str, find the start
+of the previous UTF-8 character starting before @p. Returns %NULL if no
+UTF-8 characters are present in @str before @p.
+
+@p does not have to be at the beginning of a UTF-8 character. No check
+is made to see if the character found is actually valid other than
+it starts with an appropriate byte.
+
+
+ a pointer to the found character or %NULL.
+
+
+
+
+ pointer to the beginning of a UTF-8 encoded string
+
+
+
+ pointer to some position within @str
+
+
+
+
+
+ Converts a sequence of bytes encoded as UTF-8 to a Unicode character.
+
+If @p does not point to a valid UTF-8 encoded character, results
+are undefined. If you are not sure that the bytes are complete
+valid Unicode characters, you should use g_utf8_get_char_validated()
+instead.
+
+
+ the resulting character
+
+
+
+
+ a pointer to Unicode character encoded as UTF-8
+
+
+
+
+
+ Convert a sequence of bytes encoded as UTF-8 to a Unicode character.
+This function checks for incomplete characters, for invalid characters
+such as characters that are out of the range of Unicode, and for
+overlong encodings of valid characters.
+
+Note that g_utf8_get_char_validated() returns (gunichar)-2 if
+@max_len is positive and any of the bytes in the first UTF-8 character
+sequence are nul.
+
+
+ the resulting character. If @p points to a partial
+ sequence at the end of a string that could begin a valid
+ character (or if @max_len is zero), returns (gunichar)-2;
+ otherwise, if @p does not point to a valid UTF-8 encoded
+ Unicode character, returns (gunichar)-1.
+
+
+
+
+ a pointer to Unicode character encoded as UTF-8
+
+
+
+ the maximum number of bytes to read, or -1 if @p is nul-terminated
+
+
+
+
+
+ If the provided string is valid UTF-8, return a copy of it. If not,
+return a copy in which bytes that could not be interpreted as valid Unicode
+are replaced with the Unicode replacement character (U+FFFD).
+
+For example, this is an appropriate function to use if you have received
+a string that was incorrectly declared to be UTF-8, and you need a valid
+UTF-8 version of it that can be logged or displayed to the user, with the
+assumption that it is close enough to ASCII or UTF-8 to be mostly
+readable as-is.
+
+
+ a valid UTF-8 string whose content resembles @str
+
+
+
+
+ string to coerce into UTF-8
+
+
+
+ the maximum length of @str to use, in bytes. If @len < 0,
+ then the string is nul-terminated.
+
+
+
+
+
+ Skips to the next character in a UTF-8 string.
+
+The string must be valid; this macro is as fast as possible, and has
+no error-checking.
+
+You would use this macro to iterate over a string character by character.
+
+The macro returns the start of the next UTF-8 character.
+
+Before using this macro, use g_utf8_validate() to validate strings
+that may contain invalid UTF-8.
+
+
+
+ Pointer to the start of a valid UTF-8 character
+
+
+
+
+ Converts a string into canonical form, standardizing
+such issues as whether a character with an accent
+is represented as a base character and combining
+accent or as a single precomposed character. The
+string has to be valid UTF-8, otherwise %NULL is
+returned. You should generally call g_utf8_normalize()
+before comparing two Unicode strings.
+
+The normalization mode %G_NORMALIZE_DEFAULT only
+standardizes differences that do not affect the
+text content, such as the above-mentioned accent
+representation. %G_NORMALIZE_ALL also standardizes
+the "compatibility" characters in Unicode, such
+as SUPERSCRIPT THREE to the standard forms
+(in this case DIGIT THREE). Formatting information
+may be lost but for most text operations such
+characters should be considered the same.
+
+%G_NORMALIZE_DEFAULT_COMPOSE and %G_NORMALIZE_ALL_COMPOSE
+are like %G_NORMALIZE_DEFAULT and %G_NORMALIZE_ALL,
+but returned a result with composed forms rather
+than a maximally decomposed form. This is often
+useful if you intend to convert the string to
+a legacy encoding or pass it to a system with
+less capable Unicode handling.
+
+
+ a newly allocated string, that
+ is the normalized form of @str, or %NULL if @str
+ is not valid UTF-8.
+
+
+
+
+ a UTF-8 encoded string.
+
+
+
+ length of @str, in bytes, or -1 if @str is nul-terminated.
+
+
+
+ the type of normalization to perform.
+
+
+
+
+
+ Converts from an integer character offset to a pointer to a position
+within the string.
+
+Since 2.10, this function allows to pass a negative @offset to
+step backwards. It is usually worth stepping backwards from the end
+instead of forwards if @offset is in the last fourth of the string,
+since moving forward is about 3 times faster than moving backward.
+
+Note that this function doesn't abort when reaching the end of @str.
+Therefore you should be sure that @offset is within string boundaries
+before calling that function. Call g_utf8_strlen() when unsure.
+This limitation exists as this function is called frequently during
+text rendering and therefore has to be as fast as possible.
+
+
+ the resulting pointer
+
+
+
+
+ a UTF-8 encoded string
+
+
+
+ a character offset within @str
+
+
+
+
+
+ Converts from a pointer to position within a string to an integer
+character offset.
+
+Since 2.10, this function allows @pos to be before @str, and returns
+a negative offset in this case.
+
+
+ the resulting character offset
+
+
+
+
+ a UTF-8 encoded string
+
+
+
+ a pointer to a position within @str
+
+
+
+
+
+ Finds the previous UTF-8 character in the string before @p.
+
+@p does not have to be at the beginning of a UTF-8 character. No check
+is made to see if the character found is actually valid other than
+it starts with an appropriate byte. If @p might be the first
+character of the string, you must use g_utf8_find_prev_char() instead.
+
+
+ a pointer to the found character
+
+
+
+
+ a pointer to a position within a UTF-8 encoded string
+
+
+
+
+
+ Finds the leftmost occurrence of the given Unicode character
+in a UTF-8 encoded string, while limiting the search to @len bytes.
+If @len is -1, allow unbounded search.
+
+
+ %NULL if the string does not contain the character,
+ otherwise, a pointer to the start of the leftmost occurrence
+ of the character in the string.
+
+
+
+
+ a nul-terminated UTF-8 encoded string
+
+
+
+ the maximum length of @p
+
+
+
+ a Unicode character
+
+
+
+
+
+ Converts all Unicode characters in the string that have a case
+to lowercase. The exact manner that this is done depends
+on the current locale, and may result in the number of
+characters in the string changing.
+
+
+ a newly allocated string, with all characters
+ converted to lowercase.
+
+
+
+
+ a UTF-8 encoded string
+
+
+
+ length of @str, in bytes, or -1 if @str is nul-terminated.
+
+
+
+
+
+ Computes the length of the string in characters, not including
+the terminating nul character. If the @max'th byte falls in the
+middle of a character, the last (partial) character is not counted.
+
+
+ the length of the string in characters
+
+
+
+
+ pointer to the start of a UTF-8 encoded string
+
+
+
+ the maximum number of bytes to examine. If @max
+ is less than 0, then the string is assumed to be
+ nul-terminated. If @max is 0, @p will not be examined and
+ may be %NULL. If @max is greater than 0, up to @max
+ bytes are examined
+
+
+
+
+
+ Like the standard C strncpy() function, but copies a given number
+of characters instead of a given number of bytes. The @src string
+must be valid UTF-8 encoded text. (Use g_utf8_validate() on all
+text before trying to use UTF-8 utility functions with it.)
+
+Note you must ensure @dest is at least 4 * @n + 1 to fit the
+largest possible UTF-8 characters
+
+
+ @dest
+
+
+
+
+ buffer to fill with characters from @src
+
+
+
+ UTF-8 encoded string
+
+
+
+ character count
+
+
+
+
+
+ Find the rightmost occurrence of the given Unicode character
+in a UTF-8 encoded string, while limiting the search to @len bytes.
+If @len is -1, allow unbounded search.
+
+
+ %NULL if the string does not contain the character,
+ otherwise, a pointer to the start of the rightmost occurrence
+ of the character in the string.
+
+
+
+
+ a nul-terminated UTF-8 encoded string
+
+
+
+ the maximum length of @p
+
+
+
+ a Unicode character
+
+
+
+
+
+ Reverses a UTF-8 string. @str must be valid UTF-8 encoded text.
+(Use g_utf8_validate() on all text before trying to use UTF-8
+utility functions with it.)
+
+This function is intended for programmatic uses of reversed strings.
+It pays no attention to decomposed characters, combining marks, byte
+order marks, directional indicators (LRM, LRO, etc) and similar
+characters which might need special handling when reversing a string
+for display purposes.
+
+Note that unlike g_strreverse(), this function returns
+newly-allocated memory, which should be freed with g_free() when
+no longer needed.
+
+
+ a newly-allocated string which is the reverse of @str
+
+
+
+
+ a UTF-8 encoded string
+
+
+
+ the maximum length of @str to use, in bytes. If @len < 0,
+ then the string is nul-terminated.
+
+
+
+
+
+ Converts all Unicode characters in the string that have a case
+to uppercase. The exact manner that this is done depends
+on the current locale, and may result in the number of
+characters in the string increasing. (For instance, the
+German ess-zet will be changed to SS.)
+
+
+ a newly allocated string, with all characters
+ converted to uppercase.
+
+
+
+
+ a UTF-8 encoded string
+
+
+
+ length of @str, in bytes, or -1 if @str is nul-terminated.
+
+
+
+
+
+ Copies a substring out of a UTF-8 encoded string.
+The substring will contain @end_pos - @start_pos characters.
+
+Since GLib 2.72, `-1` can be passed to @end_pos to indicate the
+end of the string.
+
+
+ a newly allocated copy of the requested
+ substring. Free with g_free() when no longer needed.
+
+
+
+
+ a UTF-8 encoded string
+
+
+
+ a character offset within @str
+
+
+
+ another character offset within @str,
+ or `-1` to indicate the end of the string
+
+
+
+
+
+ Convert a string from UTF-8 to a 32-bit fixed width
+representation as UCS-4. A trailing 0 character will be added to the
+string after the converted text.
+
+
+ a pointer to a newly allocated UCS-4 string.
+ This value must be freed with g_free(). If an error occurs,
+ %NULL will be returned and @error set.
+
+
+
+
+ a UTF-8 encoded string
+
+
+
+ the maximum length of @str to use, in bytes. If @len < 0,
+ then the string is nul-terminated.
+
+
+
+ location to store number of
+ bytes read, or %NULL.
+ If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
+ returned in case @str contains a trailing partial
+ character. If an error occurs then the index of the
+ invalid input is stored here.
+
+
+
+ location to store number
+ of characters written or %NULL. The value here stored does not include
+ the trailing 0 character.
+
+
+
+
+
+ Convert a string from UTF-8 to a 32-bit fixed width
+representation as UCS-4, assuming valid UTF-8 input.
+This function is roughly twice as fast as g_utf8_to_ucs4()
+but does no error checking on the input. A trailing 0 character
+will be added to the string after the converted text.
+
+
+ a pointer to a newly allocated UCS-4 string.
+ This value must be freed with g_free().
+
+
+
+
+ a UTF-8 encoded string
+
+
+
+ the maximum length of @str to use, in bytes. If @len < 0,
+ then the string is nul-terminated.
+
+
+
+ location to store the
+ number of characters in the result, or %NULL.
+
+
+
+
+
+ Convert a string from UTF-8 to UTF-16. A 0 character will be
+added to the result after the converted text.
+
+
+ a pointer to a newly allocated UTF-16 string.
+ This value must be freed with g_free(). If an error occurs,
+ %NULL will be returned and @error set.
+
+
+
+
+ a UTF-8 encoded string
+
+
+
+ the maximum length (number of bytes) of @str to use.
+ If @len < 0, then the string is nul-terminated.
+
+
+
+ location to store number of
+ bytes read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will
+ be returned in case @str contains a trailing partial character. If
+ an error occurs then the index of the invalid input is stored here.
+
+
+
+ location to store number
+ of #gunichar2 written, or %NULL. The value stored here does not include
+ the trailing 0.
+
+
+
+
+
+ Validates UTF-8 encoded text. @str is the text to validate;
+if @str is nul-terminated, then @max_len can be -1, otherwise
+@max_len should be the number of bytes to validate.
+If @end is non-%NULL, then the end of the valid range
+will be stored there (i.e. the start of the first invalid
+character if some bytes were invalid, or the end of the text
+being validated otherwise).
+
+Note that g_utf8_validate() returns %FALSE if @max_len is
+positive and any of the @max_len bytes are nul.
+
+Returns %TRUE if all of @str was valid. Many GLib and GTK+
+routines require valid UTF-8 as input; so data read from a file
+or the network should be checked with g_utf8_validate() before
+doing anything else with it.
+
+
+ %TRUE if the text was valid UTF-8
+
+
+
+
+ a pointer to character data
+
+
+
+
+
+ max bytes to validate, or -1 to go until NUL
+
+
+
+ return location for end of valid data
+
+
+
+
+
+ Validates UTF-8 encoded text.
+
+As with g_utf8_validate(), but @max_len must be set, and hence this function
+will always return %FALSE if any of the bytes of @str are nul.
+
+
+ %TRUE if the text was valid UTF-8
+
+
+
+
+ a pointer to character data
+
+
+
+
+
+ max bytes to validate
+
+
+
+ return location for end of valid data
+
+
+
+
+
+ A UUID, or Universally unique identifier, is intended to uniquely
+identify information in a distributed environment. For the
+definition of UUID, see [RFC 4122](https://tools.ietf.org/html/rfc4122.html).
+
+The creation of UUIDs does not require a centralized authority.
+
+UUIDs are of relatively small size (128 bits, or 16 bytes). The
+common string representation (ex:
+1d6c0810-2bd6-45f3-9890-0268422a6f14) needs 37 bytes.
+
+The UUID specification defines 5 versions, and calling
+g_uuid_string_random() will generate a unique (or rather random)
+UUID of the most common version, version 4.
+
+
+ Parses the string @str and verify if it is a UUID.
+
+The function accepts the following syntax:
+
+- simple forms (e.g. `f81d4fae-7dec-11d0-a765-00a0c91e6bf6`)
+
+Note that hyphens are required within the UUID string itself,
+as per the aforementioned RFC.
+
+
+ %TRUE if @str is a valid UUID, %FALSE otherwise.
+
+
+
+
+ a string representing a UUID
+
+
+
+
+
+ Generates a random UUID (RFC 4122 version 4) as a string. It has the same
+randomness guarantees as #GRand, so must not be used for cryptographic
+purposes such as key generation, nonces, salts or one-time pads.
+
+
+ A string that should be freed with g_free().
+
+
+
+
+
+
+
+
+
+
+ Determines if a given string is a valid D-Bus object path. You
+should ensure that a string is a valid D-Bus object path before
+passing it to g_variant_new_object_path().
+
+A valid object path starts with `/` followed by zero or more
+sequences of characters separated by `/` characters. Each sequence
+must contain only the characters `[A-Z][a-z][0-9]_`. No sequence
+(including the one following the final `/` character) may be empty.
+
+
+ %TRUE if @string is a D-Bus object path
+
+
+
+
+ a normal C nul-terminated string
+
+
+
+
+
+ Determines if a given string is a valid D-Bus type signature. You
+should ensure that a string is a valid D-Bus type signature before
+passing it to g_variant_new_signature().
+
+D-Bus type signatures consist of zero or more definite #GVariantType
+strings in sequence.
+
+
+ %TRUE if @string is a D-Bus type signature
+
+
+
+
+ a normal C nul-terminated string
+
+
+
+
+
+ Parses a #GVariant from a text representation.
+
+A single #GVariant is parsed from the content of @text.
+
+The format is described [here][gvariant-text].
+
+The memory at @limit will never be accessed and the parser behaves as
+if the character at @limit is the nul terminator. This has the
+effect of bounding @text.
+
+If @endptr is non-%NULL then @text is permitted to contain data
+following the value that this function parses and @endptr will be
+updated to point to the first character past the end of the text
+parsed by this function. If @endptr is %NULL and there is extra data
+then an error is returned.
+
+If @type is non-%NULL then the value will be parsed to have that
+type. This may result in additional parse errors (in the case that
+the parsed value doesn't fit the type) but may also result in fewer
+errors (in the case that the type would have been ambiguous, such as
+with empty arrays).
+
+In the event that the parsing is successful, the resulting #GVariant
+is returned. It is never floating, and must be freed with
+g_variant_unref().
+
+In case of any error, %NULL will be returned. If @error is non-%NULL
+then it will be set to reflect the error that occurred.
+
+Officially, the language understood by the parser is "any string
+produced by g_variant_print()".
+
+There may be implementation specific restrictions on deeply nested values,
+which would result in a %G_VARIANT_PARSE_ERROR_RECURSION error. #GVariant is
+guaranteed to handle nesting up to at least 64 levels.
+
+
+ a non-floating reference to a #GVariant, or %NULL
+
+
+
+
+ a #GVariantType, or %NULL
+
+
+
+ a string containing a GVariant in text form
+
+
+
+ a pointer to the end of @text, or %NULL
+
+
+
+ a location to store the end pointer, or %NULL
+
+
+
+
+
+ Pretty-prints a message showing the context of a #GVariant parse
+error within the string for which parsing was attempted.
+
+The resulting string is suitable for output to the console or other
+monospace media where newlines are treated in the usual way.
+
+The message will typically look something like one of the following:
+
+|[
+unterminated string constant:
+ (1, 2, 3, 'abc
+ ^^^^
+]|
+
+or
+
+|[
+unable to find a common type:
+ [1, 2, 3, 'str']
+ ^ ^^^^^
+]|
+
+The format of the message may change in a future version.
+
+@error must have come from a failed attempt to g_variant_parse() and
+@source_str must be exactly the same string that caused the error.
+If @source_str was not nul-terminated when you passed it to
+g_variant_parse() then you must add nul termination before using this
+function.
+
+
+ the printed message
+
+
+
+
+ a #GError from the #GVariantParseError domain
+
+
+
+ the string that was given to the parser
+
+
+
+
+
+
+
+
+
+
+ Same as g_variant_error_quark().
+ Use g_variant_parse_error_quark() instead.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Checks if @type_string is a valid GVariant type string. This call is
+equivalent to calling g_variant_type_string_scan() and confirming
+that the following character is a nul terminator.
+
+
+ %TRUE if @type_string is exactly one valid type string
+
+Since 2.24
+
+
+
+
+ a pointer to any string
+
+
+
+
+
+ Scan for a single complete and valid GVariant type string in @string.
+The memory pointed to by @limit (or bytes beyond it) is never
+accessed.
+
+If a valid type string is found, @endptr is updated to point to the
+first character past the end of the string that was found and %TRUE
+is returned.
+
+If there is no valid type string starting at @string, or if the type
+string does not end before @limit then %FALSE is returned.
+
+For the simple case of checking if a string is a valid type string,
+see g_variant_type_string_is_valid().
+
+
+ %TRUE if a valid type string was found
+
+
+
+
+ a pointer to any string
+
+
+
+ the end of @string, or %NULL
+
+
+
+ location to store the end pointer, or %NULL
+
+
+
+
+
+ An implementation of the GNU vasprintf() function which supports
+positional parameters, as specified in the Single Unix Specification.
+This function is similar to g_vsprintf(), except that it allocates a
+string to hold the output, instead of putting the output in a buffer
+you allocate in advance.
+
+The returned value in @string is guaranteed to be non-NULL, unless
+@format contains `%lc` or `%ls` conversions, which can fail if no
+multibyte representation is available for the given character.
+
+`glib/gprintf.h` must be explicitly included in order to use this function.
+
+
+ the number of bytes printed, or `-1` on failure
+
+
+
+
+ the return location for the newly-allocated string,
+ which will be %NULL if (and only if) this function fails
+
+
+
+ a standard printf() format string, but notice
+ [string precision pitfalls][string-precision]
+
+
+
+ the list of arguments to insert in the output.
+
+
+
+
+
+ GLib provides version information, primarily useful in configure
+checks for builds that have a configure script. Applications will
+not typically use the features described here.
+
+The GLib headers annotate deprecated APIs in a way that produces
+compiler warnings if these deprecated APIs are used. The warnings
+can be turned off by defining the macro %GLIB_DISABLE_DEPRECATION_WARNINGS
+before including the glib.h header.
+
+GLib also provides support for building applications against
+defined subsets of deprecated or new GLib APIs. Define the macro
+%GLIB_VERSION_MIN_REQUIRED to specify up to what version of GLib
+you want to receive warnings about deprecated APIs. Define the
+macro %GLIB_VERSION_MAX_ALLOWED to specify the newest version of
+GLib whose API you want to use.
+
+
+ An implementation of the standard fprintf() function which supports
+positional parameters, as specified in the Single Unix Specification.
+
+`glib/gprintf.h` must be explicitly included in order to use this function.
+
+
+ the number of bytes printed.
+
+
+
+
+ the stream to write to.
+
+
+
+ a standard printf() format string, but notice
+ [string precision pitfalls][string-precision]
+
+
+
+ the list of arguments to insert in the output.
+
+
+
+
+
+ An implementation of the standard vprintf() function which supports
+positional parameters, as specified in the Single Unix Specification.
+
+`glib/gprintf.h` must be explicitly included in order to use this function.
+
+
+ the number of bytes printed.
+
+
+
+
+ a standard printf() format string, but notice
+ [string precision pitfalls][string-precision]
+
+
+
+ the list of arguments to insert in the output.
+
+
+
+
+
+ A safer form of the standard vsprintf() function. The output is guaranteed
+to not exceed @n characters (including the terminating nul character), so
+it is easy to ensure that a buffer overflow cannot occur.
+
+See also g_strdup_vprintf().
+
+In versions of GLib prior to 1.2.3, this function may return -1 if the
+output was truncated, and the truncated string may not be nul-terminated.
+In versions prior to 1.3.12, this function returns the length of the output
+string.
+
+The return value of g_vsnprintf() conforms to the vsnprintf() function
+as standardized in ISO C99. Note that this is different from traditional
+vsnprintf(), which returns the length of the output string.
+
+The format string may contain positional parameters, as specified in
+the Single Unix Specification.
+
+
+ the number of bytes which would be produced if the buffer
+ was large enough.
+
+
+
+
+ the buffer to hold the output.
+
+
+
+ the maximum number of bytes to produce (including the
+ terminating nul character).
+
+
+
+ a standard printf() format string, but notice
+ [string precision pitfalls][string-precision]
+
+
+
+ the list of arguments to insert in the output.
+
+
+
+
+
+ An implementation of the standard vsprintf() function which supports
+positional parameters, as specified in the Single Unix Specification.
+
+`glib/gprintf.h` must be explicitly included in order to use this function.
+
+
+ the number of bytes printed.
+
+
+
+
+ the buffer to hold the output.
+
+
+
+ a standard printf() format string, but notice
+ [string precision pitfalls][string-precision]
+
+
+
+ the list of arguments to insert in the output.
+
+
+
+
+
+ Logs a warning if the expression is not true.
+
+
+
+ the expression to check
+
+
+
+
+ Logs a warning.
+
+
+
+ Internal function used to print messages from the public g_warn_if_reached()
+and g_warn_if_fail() macros.
+
+
+
+
+
+
+ log domain
+
+
+
+ file containing the warning
+
+
+
+ line number of the warning
+
+
+
+ function containing the warning
+
+
+
+ expression which failed
+
+
+
+
+
+ A convenience function/macro to log a warning message. The message should
+typically *not* be translated to the user's language.
+
+This is not intended for end user error reporting. Use of #GError is
+preferred for that instead, as it allows calling functions to perform actions
+conditional on the type of error.
+
+Warning messages are intended to be used in the event of unexpected
+external conditions (system misconfiguration, missing files,
+other trusted programs violating protocol, invalid contents in
+trusted files, etc.)
+
+If attempting to deal with programmer errors (for example, incorrect function
+parameters) then you should use %G_LOG_LEVEL_CRITICAL instead.
+
+g_warn_if_reached() and g_warn_if_fail() log at %G_LOG_LEVEL_WARNING.
+
+You can make warnings fatal at runtime by setting the `G_DEBUG`
+environment variable (see
+[Running GLib Applications](glib-running.html)):
+
+|[
+ G_DEBUG=fatal-warnings gdb ./my-program
+]|
+
+Any unrelated failures can be skipped over in
+[gdb](https://www.gnu.org/software/gdb/) using the `continue` command.
+
+If g_log_default_handler() is used as the log handler function,
+a newline character will automatically be appended to @..., and
+need not be entered manually.
+
+If structured logging is enabled, this will use g_log_structured();
+otherwise it will use g_log(). See
+[Using Structured Logging][using-structured-logging].
+
+
+
+ format string, followed by parameters to insert
+ into the format string (as with printf())
+
+
+
+
+ Logs a warning only once.
+
+g_warning_once() calls g_warning() with the passed message the first time
+the statement is executed; subsequent times it is a no-op.
+
+Note! On platforms where the compiler doesn't support variadic macros, the
+warning is printed each time instead of only once.
+
+
+
+ format string, followed by parameters to insert
+ into the format string (as with printf())
+
+
+
+
+ GLib defines several warning functions and assertions which can be used to
+warn of programmer errors when calling functions, and print error messages
+from command line programs.
+
+The g_return_if_fail(), g_return_val_if_fail(), g_return_if_reached() and
+g_return_val_if_reached() macros are intended as pre-condition assertions, to
+be used at the top of a public function to check that the function’s
+arguments are acceptable. Any failure of such a pre-condition assertion is
+considered a programming error on the part of the caller of the public API,
+and the program is considered to be in an undefined state afterwards. They
+are similar to the libc assert() function, but provide more context on
+failures.
+
+For example:
+|[<!-- language="C" -->
+gboolean
+g_dtls_connection_shutdown (GDtlsConnection *conn,
+ gboolean shutdown_read,
+ gboolean shutdown_write,
+ GCancellable *cancellable,
+ GError **error)
+{
+ // local variable declarations
+
+ g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
+ g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), FALSE);
+ g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
+
+ // function body
+
+ return return_val;
+}
+]|
+
+g_print() and g_printerr() are intended to be used for
+output from command line applications, since they output to standard output
+and standard error by default — whereas functions like g_message() and
+g_log() may be redirected to special purpose message windows, files, or the
+system journal.
+
+If the console encoding is not UTF-8 (as specified by g_get_console_charset())
+then these functions convert the message first. Any Unicode
+characters not defined by that charset are replaced by `'?'`. On Linux,
+setlocale() must be called early in main() to load the encoding. This behaviour
+can be changed by providing custom handlers to g_set_print_handler(),
+g_set_printerr_handler() and g_log_set_handler().
+
+
+ These functions provide some level of UNIX emulation on the
+Windows platform. If your application really needs the POSIX
+APIs, we suggest you try the Cygwin project.
+
+
+
diff --git a/docs/reference/glib/glib.toml.in b/docs/reference/glib/glib.toml.in
new file mode 100644
index 000000000..5910f3ce8
--- /dev/null
+++ b/docs/reference/glib/glib.toml.in
@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: LGPL-2.1-or-later
+# Copyright 2023 Matthias Clasen
+# Copyright 2023 Philip Withnall
+
+[library]
+name = "GLib"
+version = "@VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/glib/"
+repository_url = "https://gitlab.gnome.org/GNOME/glib.git"
+website_url = "https://www.gtk.org"
+docs_url = "https://docs.gtk.org/glib/"
+authors = "GLib Development Team"
+license = "LGPL-2.1-or-later"
+description = "GLib is a general-purpose, portable utility library, which provides many useful data types, macros, type conversions, string utilities, file utilities, a mainloop abstraction, and so on."
+related = [ "GModule-2.0", "GObject-2.0", "Gio-2.0" ]
+devhelp = true
+search_index = true
+
+ [related."GModule-2.0"]
+ name = "GModule"
+ description = "Portable API for dynamically loading modules"
+ docs_url = "https://docs.gtk.org/gmodule/"
+
+ [related."GObject-2.0"]
+ name = "GObject"
+ description = "The base type system library"
+ docs_url = "https://docs.gtk.org/gobject/"
+
+ [related."Gio-2.0"]
+ name = "GIO"
+ description = "GObject Interfaces and Objects, Networking, IPC, and I/O"
+ docs_url = "https://docs.gtk.org/gio/"
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[extra]
+urlmap_file = "urlmap.js"
+# The same order will be used when generating the index
+content_files = [
+]
+content_images = [
+ "Sorted_binary_tree_breadth-first_traversal.svg",
+ "Sorted_binary_tree_inorder.svg",
+ "Sorted_binary_tree_postorder.svg",
+ "Sorted_binary_tree_preorder.svg",
+]
+
+[[object]]
+pattern = "DEPRECATED_IN_2_*"
+hidden = true
+
+[[object]]
+pattern = "DEPRECATED_MACRO_IN_2_*"
+hidden = true
+
+[[object]]
+pattern = "DEPRECATED_ENUMERATOR_IN_2_*"
+hidden = true
+
+[[object]]
+pattern = "DEPRECATED_TYPE_IN_2_*"
+hidden = true
+
+[[object]]
+name = "test_assert_expected_messages_internal"
+hidden = true
+
+[[object]]
+pattern = "macro__has_*"
+hidden = true
diff --git a/docs/reference/glib/meson.build b/docs/reference/glib/meson.build
index 78acc83c8..7835a6c7e 100644
--- a/docs/reference/glib/meson.build
+++ b/docs/reference/glib/meson.build
@@ -149,3 +149,26 @@ if get_option('gtk_doc')
)
endif
endif
+
+# gi-docgen version
+expand_content_files = [
+]
+
+glib_gir = meson.current_source_dir() / 'GLib-2.0.gir'
+glib_toml = configure_file(input: 'glib.toml.in', output: 'glib.toml', configuration: toml_conf)
+
+custom_target('glib-docs',
+ input: [ glib_toml, glib_gir ],
+ output: 'glib',
+ command: [
+ gidocgen,
+ 'generate',
+ gidocgen_common_args,
+ '--config=@INPUT0@',
+ '--output-dir=@OUTPUT@',
+ '--content-dir=@0@'.format(meson.current_source_dir()),
+ '@INPUT1@',
+ ],
+ build_by_default: true,
+ depend_files: expand_content_files,
+)
diff --git a/docs/reference/glib/urlmap.js b/docs/reference/glib/urlmap.js
new file mode 100644
index 000000000..b1f0962b0
--- /dev/null
+++ b/docs/reference/glib/urlmap.js
@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: LGPL-2.1-or-later
+// SPDX-FileCopyrightText: 2023 Matthias Clasen
+var baseURLs = [
+ [ 'GLib', 'https://docs.gtk.org/glib/' ],
+ [ 'GModule', 'https://docs.gtk.org/gmodule/' ],
+ [ 'GObject', 'https://docs.gtk.org/gobject/' ],
+ [ 'Gio', 'https://docs.gtk.org/gio/' ],
+ [ 'Gtk', 'https://docs.gtk.org/gtk4/' ],
+];
diff --git a/docs/reference/gmodule/GModule-2.0.gir b/docs/reference/gmodule/GModule-2.0.gir
new file mode 100644
index 000000000..3de9a41ba
--- /dev/null
+++ b/docs/reference/gmodule/GModule-2.0.gir
@@ -0,0 +1,535 @@
+
+
+
+
+
+
+
+
+ The #GModule struct is an opaque data structure to represent a
+[dynamically-loaded module][glib-Dynamic-Loading-of-Modules].
+It should only be accessed via the following functions.
+
+
+ Closes a module.
+
+
+ %TRUE on success
+
+
+
+
+ a #GModule to close
+
+
+
+
+
+ Ensures that a module will never be unloaded.
+Any future g_module_close() calls on the module will be ignored.
+
+
+
+
+
+
+ a #GModule to make permanently resident
+
+
+
+
+
+ Returns the filename that the module was opened with.
+
+If @module refers to the application itself, "main" is returned.
+
+
+ the filename of the module
+
+
+
+
+ a #GModule
+
+
+
+
+
+ Gets a symbol pointer from a module, such as one exported
+by %G_MODULE_EXPORT. Note that a valid symbol can be %NULL.
+
+
+ %TRUE on success
+
+
+
+
+ a #GModule
+
+
+
+ the name of the symbol to find
+
+
+
+ returns the pointer to the symbol value
+
+
+
+
+
+ A portable way to build the filename of a module. The platform-specific
+prefix and suffix are added to the filename, if needed, and the result
+is added to the directory, using the correct separator character.
+
+The directory should specify the directory where the module can be found.
+It can be %NULL or an empty string to indicate that the module is in a
+standard platform-specific directory, though this is not recommended
+since the wrong module may be found.
+
+For example, calling g_module_build_path() on a Linux system with a
+@directory of `/lib` and a @module_name of "mylibrary" will return
+`/lib/libmylibrary.so`. On a Windows system, using `\Windows` as the
+directory it will return `\Windows\mylibrary.dll`.
+ Use g_module_open() instead with @module_name as the
+basename of the file_name argument. See %G_MODULE_SUFFIX for why.
+
+
+ the complete path of the module, including the standard library
+ prefix and suffix. This should be freed when no longer needed
+
+
+
+
+ the directory where the module is. This can be
+ %NULL or the empty string to indicate that the standard platform-specific
+ directories will be used, though that is not recommended
+
+
+
+ the name of the module
+
+
+
+
+
+ Gets a string describing the last module error.
+
+
+ a string describing the last module error
+
+
+
+
+
+
+
+
+
+ A thin wrapper function around g_module_open_full()
+
+
+ a #GModule on success, or %NULL on failure
+
+
+
+
+ the name or path to the file containing the module,
+ or %NULL to obtain a #GModule representing the main program itself
+
+
+
+ the flags used for opening the module. This can be the
+ logical OR of any of the #GModuleFlags.
+
+
+
+
+
+ Opens a module. If the module has already been opened, its reference count
+is incremented. If not, the module is searched in the following order:
+
+1. If @file_name exists as a regular file, it is used as-is; else
+2. If @file_name doesn't have the correct suffix and/or prefix for the
+ platform, then possible suffixes and prefixes will be added to the
+ basename till a file is found and whatever is found will be used; else
+3. If @file_name doesn't have the ".la"-suffix, ".la" is appended. Either
+ way, if a matching .la file exists (and is a libtool archive) the
+ libtool archive is parsed to find the actual file name, and that is
+ used.
+
+At the end of all this, we would have a file path that we can access on
+disk, and it is opened as a module. If not, @file_name is opened as
+a module verbatim in the hopes that the system implementation will somehow
+be able to access it.
+
+
+ a #GModule on success, or %NULL on failure
+
+
+
+
+ the name or path to the file containing the module,
+ or %NULL to obtain a #GModule representing the main program itself
+
+
+
+ the flags used for opening the module. This can be the
+ logical OR of any of the #GModuleFlags
+
+
+
+
+
+ Checks if modules are supported on the current platform.
+
+
+ %TRUE if modules are supported
+
+
+
+
+
+ Specifies the type of the module initialization function.
+If a module contains a function named g_module_check_init() it is called
+automatically when the module is loaded. It is passed the #GModule structure
+and should return %NULL on success or a string describing the initialization
+error.
+
+
+ %NULL on success, or a string describing the initialization error
+
+
+
+
+ the #GModule corresponding to the module which has just been loaded
+
+
+
+
+
+ Errors returned by g_module_open_full().
+
+
+ there was an error loading or opening a module file
+
+
+ a module returned an error from its `g_module_check_init()` function
+
+
+
+ Flags passed to g_module_open().
+Note that these flags are not supported on all platforms.
+
+
+ specifies that symbols are only resolved when
+ needed. The default action is to bind all symbols when the module
+ is loaded.
+
+
+ specifies that symbols in the module should
+ not be added to the global name space. The default action on most
+ platforms is to place symbols in the module in the global name space,
+ which may cause conflicts with existing symbols.
+
+
+ mask for all flags.
+
+
+
+ Specifies the type of the module function called when it is unloaded.
+If a module contains a function named g_module_unload() it is called
+automatically when the module is unloaded.
+It is passed the #GModule structure.
+
+
+
+
+
+
+ the #GModule about to be unloaded
+
+
+
+
+
+ A portable way to build the filename of a module. The platform-specific
+prefix and suffix are added to the filename, if needed, and the result
+is added to the directory, using the correct separator character.
+
+The directory should specify the directory where the module can be found.
+It can be %NULL or an empty string to indicate that the module is in a
+standard platform-specific directory, though this is not recommended
+since the wrong module may be found.
+
+For example, calling g_module_build_path() on a Linux system with a
+@directory of `/lib` and a @module_name of "mylibrary" will return
+`/lib/libmylibrary.so`. On a Windows system, using `\Windows` as the
+directory it will return `\Windows\mylibrary.dll`.
+ Use g_module_open() instead with @module_name as the
+basename of the file_name argument. See %G_MODULE_SUFFIX for why.
+
+
+ the complete path of the module, including the standard library
+ prefix and suffix. This should be freed when no longer needed
+
+
+
+
+ the directory where the module is. This can be
+ %NULL or the empty string to indicate that the standard platform-specific
+ directories will be used, though that is not recommended
+
+
+
+ the name of the module
+
+
+
+
+
+ Gets a string describing the last module error.
+
+
+ a string describing the last module error
+
+
+
+
+
+
+
+
+
+ Checks if modules are supported on the current platform.
+
+
+ %TRUE if modules are supported
+
+
+
+
+ These functions provide a portable way to dynamically load object files
+(commonly known as 'plug-ins'). The current implementation supports all
+systems that provide an implementation of dlopen() (e.g. Linux/Sun), as
+well as Windows platforms via DLLs.
+
+A program which wants to use these functions must be linked to the
+libraries output by the command `pkg-config --libs gmodule-2.0`.
+
+To use them you must first determine whether dynamic loading
+is supported on the platform by calling g_module_supported().
+If it is, you can open a module with g_module_open(),
+find the module's symbols (e.g. function names) with g_module_symbol(),
+and later close the module with g_module_close().
+g_module_name() will return the file name of a currently opened module.
+
+If any of the above functions fail, the error status can be found with
+g_module_error().
+
+The #GModule implementation features reference counting for opened modules,
+and supports hook functions within a module which are called when the
+module is loaded and unloaded (see #GModuleCheckInit and #GModuleUnload).
+
+If your module introduces static data to common subsystems in the running
+program, e.g. through calling
+`g_quark_from_static_string ("my-module-stuff")`,
+it must ensure that it is never unloaded, by calling g_module_make_resident().
+
+Example: Calling a function defined in a GModule
+|[<!-- language="C" -->
+// the function signature for 'say_hello'
+typedef void (* SayHelloFunc) (const char *message);
+
+gboolean
+just_say_hello (const char *filename, GError **error)
+{
+ SayHelloFunc say_hello;
+ GModule *module;
+
+ module = g_module_open (filename, G_MODULE_BIND_LAZY);
+ if (!module)
+ {
+ g_set_error (error, FOO_ERROR, FOO_ERROR_BLAH,
+ "%s", g_module_error ());
+ return FALSE;
+ }
+
+ if (!g_module_symbol (module, "say_hello", (gpointer *)&say_hello))
+ {
+ g_set_error (error, SAY_ERROR, SAY_ERROR_OPEN,
+ "%s: %s", filename, g_module_error ());
+ if (!g_module_close (module))
+ g_warning ("%s: %s", filename, g_module_error ());
+ return FALSE;
+ }
+
+ if (say_hello == NULL)
+ {
+ g_set_error (error, SAY_ERROR, SAY_ERROR_OPEN,
+ "symbol say_hello is NULL");
+ if (!g_module_close (module))
+ g_warning ("%s: %s", filename, g_module_error ());
+ return FALSE;
+ }
+
+ // call our function in the module
+ say_hello ("Hello world!");
+
+ if (!g_module_close (module))
+ g_warning ("%s: %s", filename, g_module_error ());
+ return TRUE;
+ }
+]|
+
+
+
diff --git a/docs/reference/gmodule/gmodule.toml.in b/docs/reference/gmodule/gmodule.toml.in
new file mode 100644
index 000000000..7f937aa33
--- /dev/null
+++ b/docs/reference/gmodule/gmodule.toml.in
@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: LGPL-2.1-or-later
+# Copyright 2023 Matthias Clasen
+# Copyright 2023 Philip Withnall
+
+[library]
+name = "GModule"
+version = "@VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/glib/"
+repository_url = "https://gitlab.gnome.org/GNOME/glib.git"
+website_url = "https://www.gtk.org"
+docs_url = "https://docs.gtk.org/gmodule/"
+authors = "GLib Development Team"
+license = "LGPL-2.1-or-later"
+description = "Portable API for dynamically loading modules"
+dependencies = [ "GLib-2.0", "GObject-2.0", "Gio-2.0" ]
+devhelp = true
+search_index = true
+
+ [dependencies."GLib-2.0"]
+ name = "GLib"
+ description = "The base utility library"
+ docs_url = "https://docs.gtk.org/glib/"
+
+ [dependencies."GObject-2.0"]
+ name = "GObject"
+ description = "The base type system library"
+ docs_url = "https://docs.gtk.org/gobject/"
+
+ [dependencies."Gio-2.0"]
+ name = "GIO"
+ description = "GObject Interfaces and Objects, Networking, IPC, and I/O"
+ docs_url = "https://docs.gtk.org/gio/"
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/"
+
+[extra]
+urlmap_file = "urlmap.js"
+# The same order will be used when generating the index
+content_files = [
+]
+content_images = [
+]
diff --git a/docs/reference/gmodule/meson.build b/docs/reference/gmodule/meson.build
new file mode 100644
index 000000000..42478418e
--- /dev/null
+++ b/docs/reference/gmodule/meson.build
@@ -0,0 +1,22 @@
+expand_content_files = [
+]
+
+gmodule_gir = meson.current_source_dir() / 'GModule-2.0.gir'
+gmodule_toml = configure_file(input: 'gmodule.toml.in', output: 'gmodule.toml', configuration: toml_conf)
+
+custom_target('gmodule-docs',
+ input: [ gmodule_toml, gmodule_gir ],
+ output: 'gmodule',
+ command: [
+ gidocgen,
+ 'generate',
+ gidocgen_common_args,
+ '--config=@INPUT0@',
+ '--output-dir=@OUTPUT@',
+ '--content-dir=@0@'.format(meson.current_source_dir()),
+ '--add-include-path=@0@'.format(meson.current_source_dir() / '../glib'),
+ '@INPUT1@',
+ ],
+ build_by_default: true,
+ depend_files: expand_content_files,
+)
diff --git a/docs/reference/gmodule/urlmap.js b/docs/reference/gmodule/urlmap.js
new file mode 100644
index 000000000..b1f0962b0
--- /dev/null
+++ b/docs/reference/gmodule/urlmap.js
@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: LGPL-2.1-or-later
+// SPDX-FileCopyrightText: 2023 Matthias Clasen
+var baseURLs = [
+ [ 'GLib', 'https://docs.gtk.org/glib/' ],
+ [ 'GModule', 'https://docs.gtk.org/gmodule/' ],
+ [ 'GObject', 'https://docs.gtk.org/gobject/' ],
+ [ 'Gio', 'https://docs.gtk.org/gio/' ],
+ [ 'Gtk', 'https://docs.gtk.org/gtk4/' ],
+];
diff --git a/docs/reference/gobject/GObject-2.0.gir b/docs/reference/gobject/GObject-2.0.gir
new file mode 100644
index 000000000..fd75df84e
--- /dev/null
+++ b/docs/reference/gobject/GObject-2.0.gir
@@ -0,0 +1,27587 @@
+
+
+
+
+
+
+
+
+ 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.
+
+
+
+
+ This is the signature of va_list marshaller functions, an optional
+marshaller that can be used in some situations to avoid
+marshalling the signal argument into GValues.
+
+
+
+
+ A numerical value which represents the unique identifier of a registered
+type.
+
+
+
+
+ A convenience macro to ease adding private data to instances of a new type
+in the @_C_ section of G_DEFINE_TYPE_WITH_CODE() or
+G_DEFINE_ABSTRACT_TYPE_WITH_CODE().
+
+For instance:
+
+|[<!-- language="C" -->
+ typedef struct _MyObject MyObject;
+ typedef struct _MyObjectClass MyObjectClass;
+
+ typedef struct {
+ gint foo;
+ gint bar;
+ } MyObjectPrivate;
+
+ G_DEFINE_TYPE_WITH_CODE (MyObject, my_object, G_TYPE_OBJECT,
+ G_ADD_PRIVATE (MyObject))
+]|
+
+Will add `MyObjectPrivate` as the private data to any instance of the
+`MyObject` type.
+
+`G_DEFINE_TYPE_*` macros will automatically create a private function
+based on the arguments to this macro, which can be used to safely
+retrieve the private data from an instance of the type; for instance:
+
+|[<!-- language="C" -->
+ gint
+ my_object_get_foo (MyObject *obj)
+ {
+ MyObjectPrivate *priv = my_object_get_instance_private (obj);
+
+ g_return_val_if_fail (MY_IS_OBJECT (obj), 0);
+
+ return priv->foo;
+ }
+
+ void
+ my_object_set_bar (MyObject *obj,
+ gint bar)
+ {
+ MyObjectPrivate *priv = my_object_get_instance_private (obj);
+
+ g_return_if_fail (MY_IS_OBJECT (obj));
+
+ if (priv->bar != bar)
+ priv->bar = bar;
+ }
+]|
+
+Since GLib 2.72, the returned `MyObjectPrivate` pointer is guaranteed to be
+aligned to at least the alignment of the largest basic GLib type (typically
+this is #guint64 or #gdouble). If you need larger alignment for an element in
+the struct, you should allocate it on the heap (aligned), or arrange for your
+`MyObjectPrivate` struct to be appropriately padded.
+
+Note that this macro can only be used together with the `G_DEFINE_TYPE_*`
+macros, since it depends on variable names from those macros.
+
+Also note that private structs added with these macros must have a struct
+name of the form `TypeNamePrivate`.
+
+It is safe to call the `_get_instance_private` function on %NULL or invalid
+objects since it's only adding an offset to the instance pointer. In that
+case the returned pointer must not be dereferenced.
+
+
+
+ the name of the type in CamelCase
+
+
+
+
+ A convenience macro to ease adding private data to instances of a new dynamic
+type in the @_C_ section of G_DEFINE_DYNAMIC_TYPE_EXTENDED().
+
+See G_ADD_PRIVATE() for details, it is similar but for static types.
+
+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.
+
+
+
+ the name of the type in CamelCase
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ A callback function used by the type system to finalize those portions
+of a derived types class structure that were setup from the corresponding
+GBaseInitFunc() function.
+
+Class finalization basically works the inverse way in which class
+initialization is performed.
+
+See GClassInitFunc() for a discussion of the class initialization process.
+
+
+
+
+
+
+ The #GTypeClass structure to finalize
+
+
+
+
+
+ A callback function used by the type system to do base initialization
+of the class structures of derived types.
+
+This function is called as part of the initialization process of all derived
+classes and should reallocate or reset all dynamic class members copied over
+from the parent class.
+
+For example, class members (such as strings) that are not sufficiently
+handled by a plain memory copy of the parent class into the derived class
+have to be altered. See GClassInitFunc() for a discussion of the class
+initialization process.
+
+
+
+
+
+
+ The #GTypeClass structure to initialize
+
+
+
+
+
+ #GBinding is the representation of a binding between a property on a
+#GObject instance (or source) and another property on another #GObject
+instance (or target).
+
+Whenever the source property changes, the same value is applied to the
+target property; for instance, the following binding:
+
+|[<!-- language="C" -->
+ g_object_bind_property (object1, "property-a",
+ object2, "property-b",
+ G_BINDING_DEFAULT);
+]|
+
+will cause the property named "property-b" of @object2 to be updated
+every time g_object_set() or the specific accessor changes the value of
+the property "property-a" of @object1.
+
+It is possible to create a bidirectional binding between two properties
+of two #GObject instances, so that if either property changes, the
+other is updated as well, for instance:
+
+|[<!-- language="C" -->
+ g_object_bind_property (object1, "property-a",
+ object2, "property-b",
+ G_BINDING_BIDIRECTIONAL);
+]|
+
+will keep the two properties in sync.
+
+It is also possible to set a custom transformation function (in both
+directions, in case of a bidirectional binding) to apply a custom
+transformation from the source value to the target value before
+applying it; for instance, the following binding:
+
+|[<!-- language="C" -->
+ g_object_bind_property_full (adjustment1, "value",
+ adjustment2, "value",
+ G_BINDING_BIDIRECTIONAL,
+ celsius_to_fahrenheit,
+ fahrenheit_to_celsius,
+ NULL, NULL);
+]|
+
+will keep the "value" property of the two adjustments in sync; the
+@celsius_to_fahrenheit function will be called whenever the "value"
+property of @adjustment1 changes and will transform the current value
+of the property before applying it to the "value" property of @adjustment2.
+
+Vice versa, the @fahrenheit_to_celsius function will be called whenever
+the "value" property of @adjustment2 changes, and will transform the
+current value of the property before applying it to the "value" property
+of @adjustment1.
+
+Note that #GBinding does not resolve cycles by itself; a cycle like
+
+|[
+ object1:propertyA -> object2:propertyB
+ object2:propertyB -> object3:propertyC
+ object3:propertyC -> object1:propertyA
+]|
+
+might lead to an infinite loop. The loop, in this particular case,
+can be avoided if the objects emit the #GObject::notify signal only
+if the value has effectively been changed. A binding is implemented
+using the #GObject::notify signal, so it is susceptible to all the
+various ways of blocking a signal emission, like g_signal_stop_emission()
+or g_signal_handler_block().
+
+A binding will be severed, and the resources it allocates freed, whenever
+either one of the #GObject instances it refers to are finalized, or when
+the #GBinding instance loses its last reference.
+
+Bindings for languages with garbage collection can use
+g_binding_unbind() to explicitly release a binding between the source
+and target properties, instead of relying on the last reference on the
+binding, source, and target instances to drop.
+
+#GBinding is available since GObject 2.26
+
+ Retrieves the #GObject instance used as the source of the binding.
+
+A #GBinding can outlive the source #GObject as the binding does not hold a
+strong reference to the source. If the source is destroyed before the
+binding then this function will return %NULL.
+
+
+ the source #GObject, or %NULL if the
+ source does not exist any more.
+
+
+
+
+ a #GBinding
+
+
+
+
+
+ Retrieves the #GObject instance used as the target of the binding.
+
+A #GBinding can outlive the target #GObject as the binding does not hold a
+strong reference to the target. If the target is destroyed before the
+binding then this function will return %NULL.
+
+
+ the target #GObject, or %NULL if the
+ target does not exist any more.
+
+
+
+
+ a #GBinding
+
+
+
+
+
+ Retrieves the flags passed when constructing the #GBinding.
+
+
+ the #GBindingFlags used by the #GBinding
+
+
+
+
+ a #GBinding
+
+
+
+
+
+ Retrieves the #GObject instance used as the source of the binding.
+
+A #GBinding can outlive the source #GObject as the binding does not hold a
+strong reference to the source. If the source is destroyed before the
+binding then this function will return %NULL.
+
+Use g_binding_dup_source() if the source or binding are used from different
+threads as otherwise the pointer returned from this function might become
+invalid if the source is finalized from another thread in the meantime.
+ Use g_binding_dup_source() for a safer version of this
+function.
+
+
+ the source #GObject, or %NULL if the
+ source does not exist any more.
+
+
+
+
+ a #GBinding
+
+
+
+
+
+ Retrieves the name of the property of #GBinding:source used as the source
+of the binding.
+
+
+ the name of the source property
+
+
+
+
+ a #GBinding
+
+
+
+
+
+ Retrieves the #GObject instance used as the target of the binding.
+
+A #GBinding can outlive the target #GObject as the binding does not hold a
+strong reference to the target. If the target is destroyed before the
+binding then this function will return %NULL.
+
+Use g_binding_dup_target() if the target or binding are used from different
+threads as otherwise the pointer returned from this function might become
+invalid if the target is finalized from another thread in the meantime.
+ Use g_binding_dup_target() for a safer version of this
+function.
+
+
+ the target #GObject, or %NULL if the
+ target does not exist any more.
+
+
+
+
+ a #GBinding
+
+
+
+
+
+ Retrieves the name of the property of #GBinding:target used as the target
+of the binding.
+
+
+ the name of the target property
+
+
+
+
+ a #GBinding
+
+
+
+
+
+ Explicitly releases the binding between the source and the target
+property expressed by @binding.
+
+This function will release the reference that is being held on
+the @binding instance if the binding is still bound; if you want to hold on
+to the #GBinding instance after calling g_binding_unbind(), you will need
+to hold a reference to it.
+
+Note however that this function does not take ownership of @binding, it
+only unrefs the reference that was initially created by
+g_object_bind_property() and is owned by the binding.
+
+
+
+
+
+
+ a #GBinding
+
+
+
+
+
+ Flags to be used to control the #GBinding
+
+
+
+ The #GObject that should be used as the source of the binding
+
+
+
+ The name of the property of #GBinding:source that should be used
+as the source of the binding.
+
+This should be in [canonical form][canonical-parameter-names] to get the
+best performance.
+
+
+
+ The #GObject that should be used as the target of the binding
+
+
+
+ The name of the property of #GBinding:target that should be used
+as the target of the binding.
+
+This should be in [canonical form][canonical-parameter-names] to get the
+best performance.
+
+
+
+
+ Flags to be passed to g_object_bind_property() or
+g_object_bind_property_full().
+
+This enumeration can be extended at later date.
+
+ The default binding; if the source property
+ changes, the target property is updated with its value.
+
+
+ Bidirectional binding; if either the
+ property of the source or the property of the target changes,
+ the other is updated.
+
+
+ Synchronize the values of the source and
+ target properties when creating the binding; the direction of
+ the synchronization is always from the source to the target.
+
+
+ If the two properties being bound are
+ booleans, setting one to %TRUE will result in the other being
+ set to %FALSE and vice versa. This flag will only work for
+ boolean properties, and cannot be used when passing custom
+ transformation functions to g_object_bind_property_full().
+
+
+
+ The #GBindingGroup can be used to bind multiple properties
+from an object collectively.
+
+Use the various methods to bind properties from a single source
+object to multiple destination objects. Properties can be bound
+bidirectionally and are connected when the source object is set
+with g_binding_group_set_source().
+
+ Creates a new #GBindingGroup.
+
+
+ a new #GBindingGroup
+
+
+
+
+ Creates a binding between @source_property on the source object
+and @target_property on @target. Whenever the @source_property
+is changed the @target_property is updated using the same value.
+The binding flag %G_BINDING_SYNC_CREATE is automatically specified.
+
+See g_object_bind_property() for more information.
+
+
+
+
+
+
+ the #GBindingGroup
+
+
+
+ the property on the source to bind
+
+
+
+ the target #GObject
+
+
+
+ the property on @target to bind
+
+
+
+ the flags used to create the #GBinding
+
+
+
+
+
+ Creates a binding between @source_property on the source object and
+@target_property on @target, allowing you to set the transformation
+functions to be used by the binding. The binding flag
+%G_BINDING_SYNC_CREATE is automatically specified.
+
+See g_object_bind_property_full() for more information.
+
+
+
+
+
+
+ the #GBindingGroup
+
+
+
+ the property on the source to bind
+
+
+
+ the target #GObject
+
+
+
+ the property on @target to bind
+
+
+
+ the flags used to create the #GBinding
+
+
+
+ the transformation function
+ from the source object to the @target, or %NULL to use the default
+
+
+
+ the transformation function
+ from the @target to the source object, or %NULL to use the default
+
+
+
+ custom data to be passed to the transformation
+ functions, or %NULL
+
+
+
+ function to be called when disposing the binding,
+ to free the resources used by the transformation functions
+
+
+
+
+
+ Creates a binding between @source_property on the source object and
+@target_property on @target, allowing you to set the transformation
+functions to be used by the binding. The binding flag
+%G_BINDING_SYNC_CREATE is automatically specified.
+
+This function is the language bindings friendly version of
+g_binding_group_bind_property_full(), using #GClosures
+instead of function pointers.
+
+See g_object_bind_property_with_closures() for more information.
+
+
+
+
+
+
+ the #GBindingGroup
+
+
+
+ the property on the source to bind
+
+
+
+ the target #GObject
+
+
+
+ the property on @target to bind
+
+
+
+ the flags used to create the #GBinding
+
+
+
+ a #GClosure wrapping the
+ transformation function from the source object to the @target,
+ or %NULL to use the default
+
+
+
+ a #GClosure wrapping the
+ transformation function from the @target to the source object,
+ or %NULL to use the default
+
+
+
+
+
+ Gets the source object used for binding properties.
+
+
+ a #GObject or %NULL.
+
+
+
+
+ the #GBindingGroup
+
+
+
+
+
+ Sets @source as the source object used for creating property
+bindings. If there is already a source object all bindings from it
+will be removed.
+
+Note that all properties that have been bound must exist on @source.
+
+
+
+
+
+
+ the #GBindingGroup
+
+
+
+ the source #GObject,
+ or %NULL to clear it
+
+
+
+
+
+ The source object used for binding properties.
+
+
+
+
+ A function to be called to transform @from_value to @to_value.
+
+If this is the @transform_to function of a binding, then @from_value
+is the @source_property on the @source object, and @to_value is the
+@target_property on the @target object. If this is the
+@transform_from function of a %G_BINDING_BIDIRECTIONAL binding,
+then those roles are reversed.
+
+
+ %TRUE if the transformation was successful, and %FALSE
+ otherwise
+
+
+
+
+ a #GBinding
+
+
+
+ the #GValue containing the value to transform
+
+
+
+ the #GValue in which to store the transformed value
+
+
+
+ data passed to the transform function
+
+
+
+
+
+ This function is provided by the user and should produce a copy
+of the passed in boxed structure.
+
+
+ The newly created copy of the boxed structure.
+
+
+
+
+ The boxed structure to be copied.
+
+
+
+
+
+ This function is provided by the user and should free the boxed
+structure passed.
+
+
+
+
+
+
+ The boxed structure to be freed.
+
+
+
+
+
+ Cast a function pointer to a #GCallback.
+
+
+
+ a function pointer.
+
+
+
+
+ Checks whether the user data of the #GCClosure should be passed as the
+first parameter to the callback. See g_cclosure_new_swap().
+
+
+
+ a #GCClosure
+
+
+
+
+ A #GCClosure is a specialization of #GClosure for C function callbacks.
+
+
+ the #GClosure
+
+
+
+ the callback function
+
+
+
+ A #GClosureMarshal function for use with signals with handlers that
+take two boxed pointers as arguments and return a boolean. If you
+have such a signal, you will probably also need to use an
+accumulator, such as g_signal_accumulator_true_handled().
+
+
+
+
+
+
+ A #GClosure.
+
+
+
+ A #GValue to store the return value. May be %NULL
+ if the callback of closure doesn't return a value.
+
+
+
+ The length of the @param_values array.
+
+
+
+ An array of #GValues holding the arguments
+ on which to invoke the callback of closure.
+
+
+
+ The invocation hint given as the last argument to
+ g_closure_invoke().
+
+
+
+ Additional data specified when registering the
+ marshaller, see g_closure_set_marshal() and
+ g_closure_set_meta_marshal()
+
+
+
+
+
+ The #GVaClosureMarshal equivalent to g_cclosure_marshal_BOOLEAN__BOXED_BOXED().
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ a #GValue to store the return
+ value. May be %NULL if the callback of @closure doesn't return a
+ value.
+
+
+
+ the instance on which the closure is invoked.
+
+
+
+ va_list of arguments to be passed to the closure.
+
+
+
+ additional data specified when
+ registering the marshaller, see g_closure_set_marshal() and
+ g_closure_set_meta_marshal()
+
+
+
+ the length of the @param_types array
+
+
+
+ the #GType of each argument from
+ @args.
+
+
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter
+denotes a flags type.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ a #GValue which can store the returned #gboolean
+
+
+
+ 2
+
+
+
+ a #GValue array holding instance and arg1
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ The #GVaClosureMarshal equivalent to g_cclosure_marshal_BOOLEAN__FLAGS().
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ a #GValue to store the return
+ value. May be %NULL if the callback of @closure doesn't return a
+ value.
+
+
+
+ the instance on which the closure is invoked.
+
+
+
+ va_list of arguments to be passed to the closure.
+
+
+
+ additional data specified when
+ registering the marshaller, see g_closure_set_marshal() and
+ g_closure_set_meta_marshal()
+
+
+
+ the length of the @param_types array
+
+
+
+ the #GType of each argument from
+ @args.
+
+
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ a #GValue, which can store the returned string
+
+
+
+ 3
+
+
+
+ a #GValue array holding instance, arg1 and arg2
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ The #GVaClosureMarshal equivalent to g_cclosure_marshal_STRING__OBJECT_POINTER().
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ a #GValue to store the return
+ value. May be %NULL if the callback of @closure doesn't return a
+ value.
+
+
+
+ the instance on which the closure is invoked.
+
+
+
+ va_list of arguments to be passed to the closure.
+
+
+
+ additional data specified when
+ registering the marshaller, see g_closure_set_marshal() and
+ g_closure_set_meta_marshal()
+
+
+
+ the length of the @param_types array
+
+
+
+ the #GType of each argument from
+ @args.
+
+
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the #gboolean parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__BOOLEAN().
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ a #GValue to store the return
+ value. May be %NULL if the callback of @closure doesn't return a
+ value.
+
+
+
+ the instance on which the closure is invoked.
+
+
+
+ va_list of arguments to be passed to the closure.
+
+
+
+ additional data specified when
+ registering the marshaller, see g_closure_set_marshal() and
+ g_closure_set_meta_marshal()
+
+
+
+ the length of the @param_types array
+
+
+
+ the #GType of each argument from
+ @args.
+
+
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the #GBoxed* parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__BOXED().
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ a #GValue to store the return
+ value. May be %NULL if the callback of @closure doesn't return a
+ value.
+
+
+
+ the instance on which the closure is invoked.
+
+
+
+ va_list of arguments to be passed to the closure.
+
+
+
+ additional data specified when
+ registering the marshaller, see g_closure_set_marshal() and
+ g_closure_set_meta_marshal()
+
+
+
+ the length of the @param_types array
+
+
+
+ the #GType of each argument from
+ @args.
+
+
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, gchar arg1, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the #gchar parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__CHAR().
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ a #GValue to store the return
+ value. May be %NULL if the callback of @closure doesn't return a
+ value.
+
+
+
+ the instance on which the closure is invoked.
+
+
+
+ va_list of arguments to be passed to the closure.
+
+
+
+ additional data specified when
+ registering the marshaller, see g_closure_set_marshal() and
+ g_closure_set_meta_marshal()
+
+
+
+ the length of the @param_types array
+
+
+
+ the #GType of each argument from
+ @args.
+
+
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the #gdouble parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__DOUBLE().
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ a #GValue to store the return
+ value. May be %NULL if the callback of @closure doesn't return a
+ value.
+
+
+
+ the instance on which the closure is invoked.
+
+
+
+ va_list of arguments to be passed to the closure.
+
+
+
+ additional data specified when
+ registering the marshaller, see g_closure_set_marshal() and
+ g_closure_set_meta_marshal()
+
+
+
+ the length of the @param_types array
+
+
+
+ the #GType of each argument from
+ @args.
+
+
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes an enumeration type..
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the enumeration parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__ENUM().
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ a #GValue to store the return
+ value. May be %NULL if the callback of @closure doesn't return a
+ value.
+
+
+
+ the instance on which the closure is invoked.
+
+
+
+ va_list of arguments to be passed to the closure.
+
+
+
+ additional data specified when
+ registering the marshaller, see g_closure_set_marshal() and
+ g_closure_set_meta_marshal()
+
+
+
+ the length of the @param_types array
+
+
+
+ the #GType of each argument from
+ @args.
+
+
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes a flags type.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the flags parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__FLAGS().
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ a #GValue to store the return
+ value. May be %NULL if the callback of @closure doesn't return a
+ value.
+
+
+
+ the instance on which the closure is invoked.
+
+
+
+ va_list of arguments to be passed to the closure.
+
+
+
+ additional data specified when
+ registering the marshaller, see g_closure_set_marshal() and
+ g_closure_set_meta_marshal()
+
+
+
+ the length of the @param_types array
+
+
+
+ the #GType of each argument from
+ @args.
+
+
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the #gfloat parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__FLOAT().
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ a #GValue to store the return
+ value. May be %NULL if the callback of @closure doesn't return a
+ value.
+
+
+
+ the instance on which the closure is invoked.
+
+
+
+ va_list of arguments to be passed to the closure.
+
+
+
+ additional data specified when
+ registering the marshaller, see g_closure_set_marshal() and
+ g_closure_set_meta_marshal()
+
+
+
+ the length of the @param_types array
+
+
+
+ the #GType of each argument from
+ @args.
+
+
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, gint arg1, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the #gint parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__INT().
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ a #GValue to store the return
+ value. May be %NULL if the callback of @closure doesn't return a
+ value.
+
+
+
+ the instance on which the closure is invoked.
+
+
+
+ va_list of arguments to be passed to the closure.
+
+
+
+ additional data specified when
+ registering the marshaller, see g_closure_set_marshal() and
+ g_closure_set_meta_marshal()
+
+
+
+ the length of the @param_types array
+
+
+
+ the #GType of each argument from
+ @args.
+
+
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, glong arg1, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the #glong parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__LONG().
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ a #GValue to store the return
+ value. May be %NULL if the callback of @closure doesn't return a
+ value.
+
+
+
+ the instance on which the closure is invoked.
+
+
+
+ va_list of arguments to be passed to the closure.
+
+
+
+ additional data specified when
+ registering the marshaller, see g_closure_set_marshal() and
+ g_closure_set_meta_marshal()
+
+
+
+ the length of the @param_types array
+
+
+
+ the #GType of each argument from
+ @args.
+
+
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the #GObject* parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__OBJECT().
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ a #GValue to store the return
+ value. May be %NULL if the callback of @closure doesn't return a
+ value.
+
+
+
+ the instance on which the closure is invoked.
+
+
+
+ va_list of arguments to be passed to the closure.
+
+
+
+ additional data specified when
+ registering the marshaller, see g_closure_set_marshal() and
+ g_closure_set_meta_marshal()
+
+
+
+ the length of the @param_types array
+
+
+
+ the #GType of each argument from
+ @args.
+
+
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the #GParamSpec* parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__PARAM().
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ a #GValue to store the return
+ value. May be %NULL if the callback of @closure doesn't return a
+ value.
+
+
+
+ the instance on which the closure is invoked.
+
+
+
+ va_list of arguments to be passed to the closure.
+
+
+
+ additional data specified when
+ registering the marshaller, see g_closure_set_marshal() and
+ g_closure_set_meta_marshal()
+
+
+
+ the length of the @param_types array
+
+
+
+ the #GType of each argument from
+ @args.
+
+
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the #gpointer parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__POINTER().
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ a #GValue to store the return
+ value. May be %NULL if the callback of @closure doesn't return a
+ value.
+
+
+
+ the instance on which the closure is invoked.
+
+
+
+ va_list of arguments to be passed to the closure.
+
+
+
+ additional data specified when
+ registering the marshaller, see g_closure_set_marshal() and
+ g_closure_set_meta_marshal()
+
+
+
+ the length of the @param_types array
+
+
+
+ the #GType of each argument from
+ @args.
+
+
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the #gchar* parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__STRING().
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ a #GValue to store the return
+ value. May be %NULL if the callback of @closure doesn't return a
+ value.
+
+
+
+ the instance on which the closure is invoked.
+
+
+
+ va_list of arguments to be passed to the closure.
+
+
+
+ additional data specified when
+ registering the marshaller, see g_closure_set_marshal() and
+ g_closure_set_meta_marshal()
+
+
+
+ the length of the @param_types array
+
+
+
+ the #GType of each argument from
+ @args.
+
+
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, guchar arg1, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the #guchar parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__UCHAR().
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ a #GValue to store the return
+ value. May be %NULL if the callback of @closure doesn't return a
+ value.
+
+
+
+ the instance on which the closure is invoked.
+
+
+
+ va_list of arguments to be passed to the closure.
+
+
+
+ additional data specified when
+ registering the marshaller, see g_closure_set_marshal() and
+ g_closure_set_meta_marshal()
+
+
+
+ the length of the @param_types array
+
+
+
+ the #GType of each argument from
+ @args.
+
+
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, guint arg1, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the #guint parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 3
+
+
+
+ a #GValue array holding instance, arg1 and arg2
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__UINT_POINTER().
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ a #GValue to store the return
+ value. May be %NULL if the callback of @closure doesn't return a
+ value.
+
+
+
+ the instance on which the closure is invoked.
+
+
+
+ va_list of arguments to be passed to the closure.
+
+
+
+ additional data specified when
+ registering the marshaller, see g_closure_set_marshal() and
+ g_closure_set_meta_marshal()
+
+
+
+ the length of the @param_types array
+
+
+
+ the #GType of each argument from
+ @args.
+
+
+
+
+
+
+
+ The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__UINT().
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ a #GValue to store the return
+ value. May be %NULL if the callback of @closure doesn't return a
+ value.
+
+
+
+ the instance on which the closure is invoked.
+
+
+
+ va_list of arguments to be passed to the closure.
+
+
+
+ additional data specified when
+ registering the marshaller, see g_closure_set_marshal() and
+ g_closure_set_meta_marshal()
+
+
+
+ the length of the @param_types array
+
+
+
+ the #GType of each argument from
+ @args.
+
+
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, gulong arg1, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the #gulong parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__ULONG().
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ a #GValue to store the return
+ value. May be %NULL if the callback of @closure doesn't return a
+ value.
+
+
+
+ the instance on which the closure is invoked.
+
+
+
+ va_list of arguments to be passed to the closure.
+
+
+
+ additional data specified when
+ registering the marshaller, see g_closure_set_marshal() and
+ g_closure_set_meta_marshal()
+
+
+
+ the length of the @param_types array
+
+
+
+ the #GType of each argument from
+ @args.
+
+
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the #GVariant* parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__VARIANT().
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ a #GValue to store the return
+ value. May be %NULL if the callback of @closure doesn't return a
+ value.
+
+
+
+ the instance on which the closure is invoked.
+
+
+
+ va_list of arguments to be passed to the closure.
+
+
+
+ additional data specified when
+ registering the marshaller, see g_closure_set_marshal() and
+ g_closure_set_meta_marshal()
+
+
+
+ the length of the @param_types array
+
+
+
+ the #GType of each argument from
+ @args.
+
+
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 1
+
+
+
+ a #GValue array holding only the instance
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__VOID().
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ a #GValue to store the return
+ value. May be %NULL if the callback of @closure doesn't return a
+ value.
+
+
+
+ the instance on which the closure is invoked.
+
+
+
+ va_list of arguments to be passed to the closure.
+
+
+
+ additional data specified when
+ registering the marshaller, see g_closure_set_marshal() and
+ g_closure_set_meta_marshal()
+
+
+
+ the length of the @param_types array
+
+
+
+ the #GType of each argument from
+ @args.
+
+
+
+
+
+
+
+ A generic marshaller function implemented via
+[libffi](http://sourceware.org/libffi/).
+
+Normally this function is not passed explicitly to g_signal_new(),
+but used automatically by GLib when specifying a %NULL marshaller.
+
+
+
+
+
+
+ A #GClosure.
+
+
+
+ A #GValue to store the return value. May be %NULL
+ if the callback of closure doesn't return a value.
+
+
+
+ The length of the @param_values array.
+
+
+
+ An array of #GValues holding the arguments
+ on which to invoke the callback of closure.
+
+
+
+ The invocation hint given as the last argument to
+ g_closure_invoke().
+
+
+
+ Additional data specified when registering the
+ marshaller, see g_closure_set_marshal() and
+ g_closure_set_meta_marshal()
+
+
+
+
+
+ A generic #GVaClosureMarshal function implemented via
+[libffi](http://sourceware.org/libffi/).
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ a #GValue to store the return
+ value. May be %NULL if the callback of @closure doesn't return a
+ value.
+
+
+
+ the instance on which the closure is
+ invoked.
+
+
+
+ va_list of arguments to be passed to the closure.
+
+
+
+ additional data specified when
+ registering the marshaller, see g_closure_set_marshal() and
+ g_closure_set_meta_marshal()
+
+
+
+ the length of the @param_types array
+
+
+
+ the #GType of each argument from
+ @args_list.
+
+
+
+
+
+
+
+ Creates a new closure which invokes @callback_func with @user_data as
+the last parameter.
+
+@destroy_data will be called as a finalize notifier on the #GClosure.
+
+
+ a floating reference to a new #GCClosure
+
+
+
+
+ the function to invoke
+
+
+
+ user data to pass to @callback_func
+
+
+
+ destroy notify to be called when @user_data is no longer used
+
+
+
+
+
+ A variant of g_cclosure_new() which uses @object as @user_data and
+calls g_object_watch_closure() on @object and the created
+closure. This function is useful when you have a callback closely
+associated with a #GObject, and want the callback to no longer run
+after the object is is freed.
+
+
+ a new #GCClosure
+
+
+
+
+ the function to invoke
+
+
+
+ a #GObject pointer to pass to @callback_func
+
+
+
+
+
+ A variant of g_cclosure_new_swap() which uses @object as @user_data
+and calls g_object_watch_closure() on @object and the created
+closure. This function is useful when you have a callback closely
+associated with a #GObject, and want the callback to no longer run
+after the object is is freed.
+
+
+ a new #GCClosure
+
+
+
+
+ the function to invoke
+
+
+
+ a #GObject pointer to pass to @callback_func
+
+
+
+
+
+ Creates a new closure which invokes @callback_func with @user_data as
+the first parameter.
+
+@destroy_data will be called as a finalize notifier on the #GClosure.
+
+
+ a floating reference to a new #GCClosure
+
+
+
+
+ the function to invoke
+
+
+
+ user data to pass to @callback_func
+
+
+
+ destroy notify to be called when @user_data is no longer used
+
+
+
+
+
+
+ Check if the closure still needs a marshaller. See g_closure_set_marshal().
+
+
+
+ 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().
+
+
+
+ a #GClosure
+
+
+
+
+ The type used for callback functions in structure definitions and function
+signatures.
+
+This doesn't mean that all callback functions must take no parameters and
+return void. The required signature of a callback function is determined by
+the context in which is used (e.g. the signal to which it is connected).
+
+Use G_CALLBACK() to cast the callback function to a #GCallback.
+
+
+
+
+
+
+ A callback function used by the type system to finalize a class.
+
+This function is rarely needed, as dynamically allocated class resources
+should be handled by GBaseInitFunc() and GBaseFinalizeFunc().
+
+Also, specification of a GClassFinalizeFunc() in the #GTypeInfo
+structure of a static type is invalid, because classes of static types
+will never be finalized (they are artificially kept alive when their
+reference count drops to zero).
+
+
+
+
+
+
+ The #GTypeClass structure to finalize
+
+
+
+ The @class_data member supplied via the #GTypeInfo structure
+
+
+
+
+
+ A callback function used by the type system to initialize the class
+of a specific type.
+
+This function should initialize all static class members.
+
+The initialization process of a class involves:
+
+- Copying common members from the parent class over to the
+ derived class structure.
+- Zero initialization of the remaining members not copied
+ over from the parent class.
+- Invocation of the GBaseInitFunc() initializers of all parent
+ types and the class' type.
+- Invocation of the class' GClassInitFunc() initializer.
+
+Since derived classes are partially initialized through a memory copy
+of the parent class, the general rule is that GBaseInitFunc() and
+GBaseFinalizeFunc() should take care of necessary reinitialization
+and release of those class members that were introduced by the type
+that specified these GBaseInitFunc()/GBaseFinalizeFunc().
+GClassInitFunc() should only care about initializing static
+class members, while dynamic class members (such as allocated strings
+or reference counted resources) are better handled by a GBaseInitFunc()
+for this type, so proper initialization of the dynamic class members
+is performed for class initialization of derived types as well.
+
+An example may help to correspond the intend of the different class
+initializers:
+
+|[<!-- language="C" -->
+typedef struct {
+ GObjectClass parent_class;
+ gint static_integer;
+ gchar *dynamic_string;
+} TypeAClass;
+static void
+type_a_base_class_init (TypeAClass *class)
+{
+ class->dynamic_string = g_strdup ("some string");
+}
+static void
+type_a_base_class_finalize (TypeAClass *class)
+{
+ g_free (class->dynamic_string);
+}
+static void
+type_a_class_init (TypeAClass *class)
+{
+ class->static_integer = 42;
+}
+
+typedef struct {
+ TypeAClass parent_class;
+ gfloat static_float;
+ GString *dynamic_gstring;
+} TypeBClass;
+static void
+type_b_base_class_init (TypeBClass *class)
+{
+ class->dynamic_gstring = g_string_new ("some other string");
+}
+static void
+type_b_base_class_finalize (TypeBClass *class)
+{
+ g_string_free (class->dynamic_gstring);
+}
+static void
+type_b_class_init (TypeBClass *class)
+{
+ class->static_float = 3.14159265358979323846;
+}
+]|
+
+Initialization of TypeBClass will first cause initialization of
+TypeAClass (derived classes reference their parent classes, see
+g_type_class_ref() on this).
+
+Initialization of TypeAClass roughly involves zero-initializing its fields,
+then calling its GBaseInitFunc() type_a_base_class_init() to allocate
+its dynamic members (dynamic_string), and finally calling its GClassInitFunc()
+type_a_class_init() to initialize its static members (static_integer).
+The first step in the initialization process of TypeBClass is then
+a plain memory copy of the contents of TypeAClass into TypeBClass and
+zero-initialization of the remaining fields in TypeBClass.
+The dynamic members of TypeAClass within TypeBClass now need
+reinitialization which is performed by calling type_a_base_class_init()
+with an argument of TypeBClass.
+
+After that, the GBaseInitFunc() of TypeBClass, type_b_base_class_init()
+is called to allocate the dynamic members of TypeBClass (dynamic_gstring),
+and finally the GClassInitFunc() of TypeBClass, type_b_class_init(),
+is called to complete the initialization process with the static members
+(static_float).
+
+Corresponding finalization counter parts to the GBaseInitFunc() functions
+have to be provided to release allocated resources at class finalization
+time.
+
+
+
+
+
+
+ The #GTypeClass structure to initialize.
+
+
+
+ The @class_data member supplied via the #GTypeInfo structure.
+
+
+
+
+
+ A #GClosure represents a callback supplied by the programmer.
+
+It will generally comprise a function of some kind and a marshaller
+used to call it. It is the responsibility of the marshaller to
+convert the arguments for the invocation from #GValues into
+a suitable form, perform the callback on the converted arguments,
+and transform the return value back into a #GValue.
+
+In the case of C programs, a closure usually just holds a pointer
+to a function and maybe a data argument, and the marshaller
+converts between #GValue and native C types. The GObject
+library provides the #GCClosure type for this purpose. Bindings for
+other languages need marshallers which convert between #GValues
+and suitable representations in the runtime of the language in
+order to use functions written in that language as callbacks. Use
+g_closure_set_marshal() to set the marshaller on such a custom
+closure implementation.
+
+Within GObject, closures play an important role in the
+implementation of signals. When a signal is registered, the
+@c_marshaller argument to g_signal_new() specifies the default C
+marshaller for any closure which is connected to this
+signal. GObject provides a number of C marshallers for this
+purpose, see the g_cclosure_marshal_*() functions. Additional C
+marshallers can be generated with the [glib-genmarshal][glib-genmarshal]
+utility. Closures can be explicitly connected to signals with
+g_signal_connect_closure(), but it usually more convenient to let
+GObject create a closure automatically by using one of the
+g_signal_connect_*() functions which take a callback function/user
+data pair.
+
+Using closures has a number of important advantages over a simple
+callback function/data pointer combination:
+
+- Closures allow the callee to get the types of the callback parameters,
+ which means that language bindings don't have to write individual glue
+ for each callback type.
+
+- The reference counting of #GClosure makes it easy to handle reentrancy
+ right; if a callback is removed while it is being invoked, the closure
+ and its parameters won't be freed until the invocation finishes.
+
+- g_closure_invalidate() and invalidation notifiers allow callbacks to be
+ automatically removed when the objects they point to go away.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Indicates whether the closure is currently being invoked with
+ g_closure_invoke()
+
+
+
+ Indicates whether the closure has been invalidated by
+ g_closure_invalidate()
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ A variant of g_closure_new_simple() which stores @object in the
+@data field of the closure and calls g_object_watch_closure() on
+@object and the created closure. This function is mainly useful
+when implementing new types of closures.
+
+
+ a newly allocated #GClosure
+
+
+
+
+ the size of the structure to allocate, must be at least
+ `sizeof (GClosure)`
+
+
+
+ a #GObject pointer to store in the @data field of the newly
+ allocated #GClosure
+
+
+
+
+
+ Allocates a struct of the given size and initializes the initial
+part as a #GClosure.
+
+This function is mainly useful when implementing new types of closures:
+
+|[<!-- language="C" -->
+typedef struct _MyClosure MyClosure;
+struct _MyClosure
+{
+ GClosure closure;
+ // extra data goes here
+};
+
+static void
+my_closure_finalize (gpointer notify_data,
+ GClosure *closure)
+{
+ MyClosure *my_closure = (MyClosure *)closure;
+
+ // free extra data here
+}
+
+MyClosure *my_closure_new (gpointer data)
+{
+ GClosure *closure;
+ MyClosure *my_closure;
+
+ closure = g_closure_new_simple (sizeof (MyClosure), data);
+ my_closure = (MyClosure *) closure;
+
+ // initialize extra data here
+
+ g_closure_add_finalize_notifier (closure, notify_data,
+ my_closure_finalize);
+ return my_closure;
+}
+]|
+
+
+ a floating reference to a new #GClosure
+
+
+
+
+ the size of the structure to allocate, must be at least
+ `sizeof (GClosure)`
+
+
+
+ data to store in the @data field of the newly allocated #GClosure
+
+
+
+
+
+ Registers a finalization notifier which will be called when the
+reference count of @closure goes down to 0.
+
+Multiple finalization notifiers on a single closure are invoked in
+unspecified order. If a single call to g_closure_unref() results in
+the closure being both invalidated and finalized, then the invalidate
+notifiers will be run before the finalize notifiers.
+
+
+
+
+
+
+ a #GClosure
+
+
+
+ data to pass to @notify_func
+
+
+
+ the callback function to register
+
+
+
+
+
+ Registers an invalidation notifier which will be called when the
+@closure is invalidated with g_closure_invalidate().
+
+Invalidation notifiers are invoked before finalization notifiers,
+in an unspecified order.
+
+
+
+
+
+
+ a #GClosure
+
+
+
+ data to pass to @notify_func
+
+
+
+ the callback function to register
+
+
+
+
+
+ Adds a pair of notifiers which get invoked before and after the
+closure callback, respectively.
+
+This is typically used to protect the extra arguments for the
+duration of the callback. See g_object_watch_closure() for an
+example of marshal guards.
+
+
+
+
+
+
+ a #GClosure
+
+
+
+ data to pass
+ to @pre_marshal_notify
+
+
+
+ a function to call before the closure callback
+
+
+
+ data to pass
+ to @post_marshal_notify
+
+
+
+ a function to call after the closure callback
+
+
+
+
+
+ Sets a flag on the closure to indicate that its calling
+environment has become invalid, and thus causes any future
+invocations of g_closure_invoke() on this @closure to be
+ignored.
+
+Also, invalidation notifiers installed on the closure will
+be called at this point. Note that unless you are holding a
+reference to the closure yourself, the invalidation notifiers may
+unref the closure and cause it to be destroyed, so if you need to
+access the closure after calling g_closure_invalidate(), make sure
+that you've previously called g_closure_ref().
+
+Note that g_closure_invalidate() will also be called when the
+reference count of a closure drops to zero (unless it has already
+been invalidated before).
+
+
+
+
+
+
+ #GClosure to invalidate
+
+
+
+
+
+ Invokes the closure, i.e. executes the callback represented by the @closure.
+
+
+
+
+
+
+ a #GClosure
+
+
+
+ a #GValue to store the return
+ value. May be %NULL if the callback of @closure
+ doesn't return a value.
+
+
+
+ the length of the @param_values array
+
+
+
+ an array of
+ #GValues holding the arguments on which to
+ invoke the callback of @closure
+
+
+
+
+
+ a context-dependent invocation hint
+
+
+
+
+
+ Increments the reference count on a closure to force it staying
+alive while the caller holds a pointer to it.
+
+
+ The @closure passed in, for convenience
+
+
+
+
+ #GClosure to increment the reference count on
+
+
+
+
+
+ Removes a finalization notifier.
+
+Notice that notifiers are automatically removed after they are run.
+
+
+
+
+
+
+ a #GClosure
+
+
+
+ data which was passed to g_closure_add_finalize_notifier()
+ when registering @notify_func
+
+
+
+ the callback function to remove
+
+
+
+
+
+ Removes an invalidation notifier.
+
+Notice that notifiers are automatically removed after they are run.
+
+
+
+
+
+
+ a #GClosure
+
+
+
+ data which was passed to g_closure_add_invalidate_notifier()
+ when registering @notify_func
+
+
+
+ the callback function to remove
+
+
+
+
+
+ Sets the marshaller of @closure.
+
+The `marshal_data` of @marshal provides a way for a meta marshaller to
+provide additional information to the marshaller.
+
+For GObject's C predefined marshallers (the `g_cclosure_marshal_*()`
+functions), what it provides is a callback function to use instead of
+@closure->callback.
+
+See also: g_closure_set_meta_marshal()
+
+
+
+
+
+
+ a #GClosure
+
+
+
+ a #GClosureMarshal function
+
+
+
+
+
+ Sets the meta marshaller of @closure.
+
+A meta marshaller wraps the @closure's marshal and modifies the way
+it is called in some fashion. The most common use of this facility
+is for C callbacks.
+
+The same marshallers (generated by [glib-genmarshal][glib-genmarshal]),
+are used everywhere, but the way that we get the callback function
+differs. In most cases we want to use the @closure's callback, but in
+other cases we want to use some different technique to retrieve the
+callback function.
+
+For example, class closures for signals (see
+g_signal_type_cclosure_new()) retrieve the callback function from a
+fixed offset in the class structure. The meta marshaller retrieves
+the right callback and passes it to the marshaller as the
+@marshal_data argument.
+
+
+
+
+
+
+ a #GClosure
+
+
+
+ context-dependent data to pass
+ to @meta_marshal
+
+
+
+ a #GClosureMarshal function
+
+
+
+
+
+ Takes over the initial ownership of a closure.
+
+Each closure is initially created in a "floating" state, which means
+that the initial reference count is not owned by any caller.
+
+This function checks to see if the object is still floating, and if so,
+unsets the floating state and decreases the reference count. If the
+closure is not floating, g_closure_sink() does nothing.
+
+The reason for the existence of the floating state is to prevent
+cumbersome code sequences like:
+
+|[<!-- language="C" -->
+closure = g_cclosure_new (cb_func, cb_data);
+g_source_set_closure (source, closure);
+g_closure_unref (closure); // GObject doesn't really need this
+]|
+
+Because g_source_set_closure() (and similar functions) take ownership of the
+initial reference count, if it is unowned, we instead can write:
+
+|[<!-- language="C" -->
+g_source_set_closure (source, g_cclosure_new (cb_func, cb_data));
+]|
+
+Generally, this function is used together with g_closure_ref(). An example
+of storing a closure for later notification looks like:
+
+|[<!-- language="C" -->
+static GClosure *notify_closure = NULL;
+void
+foo_notify_set_closure (GClosure *closure)
+{
+ if (notify_closure)
+ g_closure_unref (notify_closure);
+ notify_closure = closure;
+ if (notify_closure)
+ {
+ g_closure_ref (notify_closure);
+ g_closure_sink (notify_closure);
+ }
+}
+]|
+
+Because g_closure_sink() may decrement the reference count of a closure
+(if it hasn't been called on @closure yet) just like g_closure_unref(),
+g_closure_ref() should be called prior to this function.
+
+
+
+
+
+
+ #GClosure to decrement the initial reference count on, if it's
+ still being held
+
+
+
+
+
+ Decrements the reference count of a closure after it was previously
+incremented by the same caller.
+
+If no other callers are using the closure, then the closure will be
+destroyed and freed.
+
+
+
+
+
+
+ #GClosure to decrement the reference count on
+
+
+
+
+
+
+ The type used for marshaller functions.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ a #GValue to store the return
+ value. May be %NULL if the callback of @closure doesn't return a
+ value.
+
+
+
+ the length of the @param_values array
+
+
+
+ an array of
+ #GValues holding the arguments on which to invoke the
+ callback of @closure
+
+
+
+
+
+ the invocation hint given as the
+ last argument to g_closure_invoke()
+
+
+
+ additional data specified when
+ registering the marshaller, see g_closure_set_marshal() and
+ g_closure_set_meta_marshal()
+
+
+
+
+
+ The type used for the various notification callbacks which can be registered
+on closures.
+
+
+
+
+
+
+ data specified when registering the notification callback
+
+
+
+ the #GClosure on which the notification is emitted
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The connection flags are used to specify the behaviour of a signal's
+connection.
+
+
+ Default behaviour (no special flags). Since: 2.74
+
+
+ If set, the handler should be called after the
+ default handler of the signal. Normally, the handler is called before
+ the default handler.
+
+
+ If set, the instance and data should be swapped when
+ calling the handler; see g_signal_connect_swapped() for an example.
+
+
+
+ A convenience macro for emitting the usual declarations in the
+header file for a type which is intended to be subclassed.
+
+You might use it in a header as follows:
+
+|[<!-- language="C" -->
+#ifndef _gtk_frobber_h_
+#define _gtk_frobber_h_
+
+#define GTK_TYPE_FROBBER gtk_frobber_get_type ()
+GDK_AVAILABLE_IN_3_12
+G_DECLARE_DERIVABLE_TYPE (GtkFrobber, gtk_frobber, GTK, FROBBER, GtkWidget)
+
+struct _GtkFrobberClass
+{
+ GtkWidgetClass parent_class;
+
+ void (* handle_frob) (GtkFrobber *frobber,
+ guint n_frobs);
+
+ gpointer padding[12];
+};
+
+GtkWidget * gtk_frobber_new (void);
+
+...
+
+#endif
+]|
+
+Since the instance structure is public it is often needed to declare a
+private struct as follow in your C file:
+
+|[<!-- language="C" -->
+typedef struct _GtkFrobberPrivate GtkFrobberPrivate;
+struct _GtkFrobberPrivate
+{
+ ...
+};
+G_DEFINE_TYPE_WITH_PRIVATE (GtkFrobber, gtk_frobber, GTK_TYPE_WIDGET)
+]|
+
+This results in the following things happening:
+
+- the usual `gtk_frobber_get_type()` function is declared with a return type of #GType
+
+- the `GtkFrobber` struct is created with `GtkWidget` as the first and only item. You are expected to use
+ a private structure from your .c file to store your instance variables.
+
+- the `GtkFrobberClass` type is defined as a typedef to `struct _GtkFrobberClass`, which is left undefined.
+ You should do this from the header file directly after you use the macro.
+
+- the `GTK_FROBBER()` and `GTK_FROBBER_CLASS()` casts are emitted as `static inline` functions along with
+ the `GTK_IS_FROBBER()` and `GTK_IS_FROBBER_CLASS()` type checking functions and `GTK_FROBBER_GET_CLASS()`
+ function.
+
+- g_autoptr() support being added for your type, based on the type of your parent class
+
+You can only use this function if your parent type also supports g_autoptr().
+
+Because the type macro (`GTK_TYPE_FROBBER` in the above example) is not a callable, you must continue to
+manually define this as a macro for yourself.
+
+The declaration of the `_get_type()` function is the first thing emitted by the macro. This allows this macro
+to be used in the usual way with export control and API versioning macros.
+
+If you are writing a library, it is important to note that it is possible to convert a type from using
+G_DECLARE_FINAL_TYPE() to G_DECLARE_DERIVABLE_TYPE() without breaking API or ABI. As a precaution, you
+should therefore use G_DECLARE_FINAL_TYPE() until you are sure that it makes sense for your class to be
+subclassed. Once a class structure has been exposed it is not possible to change its size or remove or
+reorder items without breaking the API and/or ABI. If you want to declare your own class structure, use
+G_DECLARE_DERIVABLE_TYPE(). If you want to declare a class without exposing the class or instance
+structures, use G_DECLARE_FINAL_TYPE().
+
+If you must use G_DECLARE_DERIVABLE_TYPE() you should be sure to include some padding at the bottom of your
+class structure to leave space for the addition of future virtual functions.
+
+
+
+ The name of the new type, in camel case (like `GtkWidget`)
+
+
+ The name of the new type in lowercase, with words
+ separated by `_` (like `gtk_widget`)
+
+
+ The name of the module, in all caps (like `GTK`)
+
+
+ The bare name of the type, in all caps (like `WIDGET`)
+
+
+ the name of the parent type, in camel case (like `GtkWidget`)
+
+
+
+
+ A convenience macro for emitting the usual declarations in the header file
+for a type which is not (at the present time) intended to be subclassed.
+
+You might use it in a header as follows:
+
+|[<!-- language="C" -->
+#ifndef _myapp_window_h_
+#define _myapp_window_h_
+
+#include <gtk/gtk.h>
+
+#define MY_APP_TYPE_WINDOW my_app_window_get_type ()
+G_DECLARE_FINAL_TYPE (MyAppWindow, my_app_window, MY_APP, WINDOW, GtkWindow)
+
+MyAppWindow * my_app_window_new (void);
+
+...
+
+#endif
+]|
+
+And use it as follow in your C file:
+
+|[<!-- language="C" -->
+struct _MyAppWindow
+{
+ GtkWindow parent;
+ ...
+};
+G_DEFINE_TYPE (MyAppWindow, my_app_window, GTK_TYPE_WINDOW)
+]|
+
+This results in the following things happening:
+
+- the usual `my_app_window_get_type()` function is declared with a return type of #GType
+
+- the `MyAppWindow` type is defined as a `typedef` of `struct _MyAppWindow`. The struct itself is not
+ defined and should be defined from the .c file before G_DEFINE_TYPE() is used.
+
+- the `MY_APP_WINDOW()` cast is emitted as `static inline` function along with the `MY_APP_IS_WINDOW()` type
+ checking function
+
+- the `MyAppWindowClass` type is defined as a struct containing `GtkWindowClass`. This is done for the
+ convenience of the person defining the type and should not be considered to be part of the ABI. In
+ particular, without a firm declaration of the instance structure, it is not possible to subclass the type
+ and therefore the fact that the size of the class structure is exposed is not a concern and it can be
+ freely changed at any point in the future.
+
+- g_autoptr() support being added for your type, based on the type of your parent class
+
+You can only use this function if your parent type also supports g_autoptr().
+
+Because the type macro (`MY_APP_TYPE_WINDOW` in the above example) is not a callable, you must continue to
+manually define this as a macro for yourself.
+
+The declaration of the `_get_type()` function is the first thing emitted by the macro. This allows this macro
+to be used in the usual way with export control and API versioning macros.
+
+If you want to declare your own class structure, use G_DECLARE_DERIVABLE_TYPE().
+
+If you are writing a library, it is important to note that it is possible to convert a type from using
+G_DECLARE_FINAL_TYPE() to G_DECLARE_DERIVABLE_TYPE() without breaking API or ABI. As a precaution, you
+should therefore use G_DECLARE_FINAL_TYPE() until you are sure that it makes sense for your class to be
+subclassed. Once a class structure has been exposed it is not possible to change its size or remove or
+reorder items without breaking the API and/or ABI.
+
+
+
+ The name of the new type, in camel case (like `GtkWidget`)
+
+
+ The name of the new type in lowercase, with words
+ separated by `_` (like `gtk_widget`)
+
+
+ The name of the module, in all caps (like `GTK`)
+
+
+ The bare name of the type, in all caps (like `WIDGET`)
+
+
+ the name of the parent type, in camel case (like `GtkWidget`)
+
+
+
+
+ A convenience macro for emitting the usual declarations in the header file for a #GInterface type.
+
+You might use it in a header as follows:
+
+|[<!-- language="C" -->
+#ifndef _my_model_h_
+#define _my_model_h_
+
+#define MY_TYPE_MODEL my_model_get_type ()
+GDK_AVAILABLE_IN_3_12
+G_DECLARE_INTERFACE (MyModel, my_model, MY, MODEL, GObject)
+
+struct _MyModelInterface
+{
+ GTypeInterface g_iface;
+
+ gpointer (* get_item) (MyModel *model);
+};
+
+gpointer my_model_get_item (MyModel *model);
+
+...
+
+#endif
+]|
+
+And use it as follow in your C file:
+
+|[<!-- language="C" -->
+G_DEFINE_INTERFACE (MyModel, my_model, G_TYPE_OBJECT);
+
+static void
+my_model_default_init (MyModelInterface *iface)
+{
+ ...
+}
+]|
+
+This results in the following things happening:
+
+- the usual `my_model_get_type()` function is declared with a return type of #GType
+
+- the `MyModelInterface` type is defined as a typedef to `struct _MyModelInterface`,
+ which is left undefined. You should do this from the header file directly after
+ you use the macro.
+
+- the `MY_MODEL()` cast is emitted as `static inline` functions along with
+ the `MY_IS_MODEL()` type checking function and `MY_MODEL_GET_IFACE()` function.
+
+- g_autoptr() support being added for your type, based on your prerequisite type.
+
+You can only use this function if your prerequisite type also supports g_autoptr().
+
+Because the type macro (`MY_TYPE_MODEL` in the above example) is not a callable, you must continue to
+manually define this as a macro for yourself.
+
+The declaration of the `_get_type()` function is the first thing emitted by the macro. This allows this macro
+to be used in the usual way with export control and API versioning macros.
+
+
+
+ The name of the new type, in camel case (like `GtkWidget`)
+
+
+ The name of the new type in lowercase, with words
+ separated by `_` (like `gtk_widget`)
+
+
+ The name of the module, in all caps (like `GTK`)
+
+
+ The bare name of the type, in all caps (like `WIDGET`)
+
+
+ the name of the prerequisite type, in camel case (like `GtkWidget`)
+
+
+
+
+ A convenience macro for type implementations.
+
+Similar to G_DEFINE_TYPE(), but defines an abstract type.
+See G_DEFINE_TYPE_EXTENDED() for an example.
+
+
+
+ The name of the new type, in Camel case.
+
+
+ The name of the new type, in lowercase, with words
+ separated by `_`.
+
+
+ The #GType of the parent type.
+
+
+
+
+ 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.
+
+
+
+ The name of the new type, in Camel case.
+
+
+ The name of the new type, in lowercase, with words
+ separated by `_`.
+
+
+ The #GType of the parent type.
+
+
+ Custom code that gets inserted in the `type_name_get_type()` function.
+
+
+
+
+ Similar to G_DEFINE_TYPE_WITH_PRIVATE(), but defines an abstract type.
+
+See G_DEFINE_TYPE_EXTENDED() for an example.
+
+
+
+ The name of the new type, in Camel case.
+
+
+ The name of the new type, in lowercase, with words
+ separated by `_`.
+
+
+ The #GType of the parent type.
+
+
+
+
+ A convenience macro for defining a new custom boxed type.
+
+Using this macro is the recommended way of defining new custom boxed
+types, over calling g_boxed_type_register_static() directly. It defines
+a `type_name_get_type()` function which will return the newly defined
+#GType, enabling lazy instantiation.
+
+You might start by putting declarations in a header as follows:
+
+|[<!-- language="C" -->
+#define MY_TYPE_STRUCT my_struct_get_type ()
+GType my_struct_get_type (void) G_GNUC_CONST;
+
+MyStruct * my_struct_new (void);
+void my_struct_free (MyStruct *self);
+MyStruct * my_struct_copy (MyStruct *self);
+]|
+
+And then use this macro and define your implementation in the source file as
+follows:
+
+|[<!-- language="C" -->
+MyStruct *
+my_struct_new (void)
+{
+ // ... your code to allocate a new MyStruct ...
+}
+
+void
+my_struct_free (MyStruct *self)
+{
+ // ... your code to free a MyStruct ...
+}
+
+MyStruct *
+my_struct_copy (MyStruct *self)
+{
+ // ... your code return a newly allocated copy of a MyStruct ...
+}
+
+G_DEFINE_BOXED_TYPE (MyStruct, my_struct, my_struct_copy, my_struct_free)
+
+void
+foo ()
+{
+ MyStruct *ms;
+
+ ms = my_struct_new ();
+ // ... your code ...
+ my_struct_free (ms);
+}
+]|
+
+
+
+ The name of the new type, in Camel case
+
+
+ The name of the new type, in lowercase, with words
+ separated by `_`
+
+
+ the #GBoxedCopyFunc for the new type
+
+
+ the #GBoxedFreeFunc for the new type
+
+
+
+
+ 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(), for instance:
+
+|[<!-- language="C" -->
+G_DEFINE_BOXED_TYPE_WITH_CODE (GdkRectangle, gdk_rectangle,
+ gdk_rectangle_copy,
+ gdk_rectangle_free,
+ register_rectangle_transform_funcs (g_define_type_id))
+]|
+
+Similarly to the `G_DEFINE_TYPE_*` family of macros, the #GType of the newly
+defined boxed type is exposed in the `g_define_type_id` variable.
+
+
+
+ The name of the new type, in Camel case
+
+
+ The name of the new type, in lowercase, with words
+ separated by `_`
+
+
+ the #GBoxedCopyFunc for the new type
+
+
+ the #GBoxedFreeFunc for the new type
+
+
+ Custom code that gets inserted in the `*_get_type()` function
+
+
+
+
+ A convenience macro for dynamic type implementations, which declares a
+class initialization function, an instance initialization function (see
+#GTypeInfo for information about these) and a static variable named
+`t_n`_parent_class pointing to the parent class.
+
+Furthermore, it defines a `*_get_type()` and a static `*_register_type()`
+functions for use in your `module_init()`.
+
+See G_DEFINE_DYNAMIC_TYPE_EXTENDED() for an example.
+
+
+
+ The name of the new type, in Camel case.
+
+
+ The name of the new type, in lowercase, with words
+ separated by '_'.
+
+
+ The #GType of the parent type.
+
+
+
+
+ A more general version of G_DEFINE_DYNAMIC_TYPE() which
+allows to specify #GTypeFlags and custom code.
+
+|[<!-- language="C" -->
+G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget,
+ gtk_gadget,
+ GTK_TYPE_THING,
+ 0,
+ G_IMPLEMENT_INTERFACE_DYNAMIC (TYPE_GIZMO,
+ gtk_gadget_gizmo_init));
+]|
+
+expands to
+
+|[<!-- language="C" -->
+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);
+ }
+}
+]|
+
+
+
+ The name of the new type, in Camel case.
+
+
+ The name of the new type, in lowercase, with words
+ separated by '_'.
+
+
+ The #GType of the parent type.
+
+
+ #GTypeFlags to pass to g_type_module_register_type()
+
+
+ Custom code that gets inserted in the *_get_type() function.
+
+
+
+
+ A convenience macro for defining enumeration types.
+
+This macro will generate a `*_get_type()` function for the
+given @TypeName, using @type_name as the function prefix.
+
+|[<!-- language="C" -->
+G_DEFINE_ENUM_TYPE (GtkOrientation, gtk_orientation,
+ G_DEFINE_ENUM_VALUE (GTK_ORIENTATION_HORIZONTAL, "horizontal"),
+ G_DEFINE_ENUM_VALUE (GTK_ORIENTATION_VERTICAL, "vertical"))
+]|
+
+For projects that have multiple enumeration types, or enumeration
+types with many values, you should consider using glib-mkenums to
+generate the type function.
+
+
+
+ the enumeration type, in `CamelCase`
+
+
+ the enumeration type prefixed, in `snake_case`
+
+
+ a list of enumeration values, defined using G_DEFINE_ENUM_VALUE()
+
+
+
+
+ Defines an enumeration value, and maps it to a "nickname".
+
+This macro can only be used with G_DEFINE_ENUM_TYPE() and
+G_DEFINE_FLAGS_TYPE().
+
+
+
+ an enumeration value
+
+
+ a short string representing the enumeration value
+
+
+
+
+ A convenience macro for type implementations.
+
+Similar to G_DEFINE_TYPE(), but defines a final type.
+
+See G_DEFINE_TYPE_EXTENDED() for an example.
+
+
+
+ the name of the new type, in Camel case
+
+
+ the name of the new type, in lower case, with words
+ separated by `_` (snake case)
+
+
+ the #GType of the parent type
+
+
+
+
+ A convenience macro for type implementations.
+
+Similar to G_DEFINE_TYPE_WITH_CODE(), but defines a final 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.
+
+
+
+ the name of the new type, in Camel case
+
+
+ the name of the new type, in lower case, with words
+ separated by `_` (snake case)
+
+
+ the #GType of the parent type
+
+
+ Custom code that gets inserted in the `type_name_get_type()` function.
+
+
+
+
+ A convenience macro for type implementations.
+
+Similar to G_DEFINE_TYPE_WITH_PRIVATE(), but defines a final type.
+
+See G_DEFINE_TYPE_EXTENDED() for an example.
+
+
+
+ the name of the new type, in Camel case
+
+
+ the name of the new type, in lower case, with words
+ separated by `_` (snake case)
+
+
+ the #GType of the parent type
+
+
+
+
+ A convenience macro for defining flag types.
+
+This macro will generate a `*_get_type()` function for the
+given @TypeName, using @type_name as the function prefix.
+
+|[<!-- language="C" -->
+G_DEFINE_FLAGS_TYPE (GSettingsBindFlags, g_settings_bind_flags,
+ G_DEFINE_ENUM_VALUE (G_SETTINGS_BIND_DEFAULT, "default"),
+ G_DEFINE_ENUM_VALUE (G_SETTINGS_BIND_GET, "get"),
+ G_DEFINE_ENUM_VALUE (G_SETTINGS_BIND_SET, "set"),
+ G_DEFINE_ENUM_VALUE (G_SETTINGS_BIND_NO_SENSITIVITY, "no-sensitivity"),
+ G_DEFINE_ENUM_VALUE (G_SETTINGS_BIND_GET_NO_CHANGES, "get-no-changes"),
+ G_DEFINE_ENUM_VALUE (G_SETTINGS_BIND_INVERT_BOOLEAN, "invert-boolean"))
+]|
+
+For projects that have multiple enumeration types, or enumeration
+types with many values, you should consider using glib-mkenums to
+generate the type function.
+
+
+
+ the enumeration type, in `CamelCase`
+
+
+ the enumeration type prefixed, in `snake_case`
+
+
+ a list of enumeration values, defined using G_DEFINE_ENUM_VALUE()
+
+
+
+
+ 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 `t_n ## _default_init`, and the interface structure to have the
+name `TN ## Interface`.
+
+The initialization function has signature
+`static void t_n ## _default_init (TypeName##Interface *klass);`, rather than
+the full #GInterfaceInitFunc signature, for brevity and convenience. If you
+need to use an initialization function with an `iface_data` argument, you
+must write the #GTypeInterface definitions manually.
+
+
+
+ The name of the new type, in Camel case.
+
+
+ The name of the new type, in lowercase, with words separated by `_`.
+
+
+ The #GType of the prerequisite type for the interface, or %G_TYPE_INVALID
+for no prerequisite type.
+
+
+
+
+ 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().
+
+
+
+ The name of the new type, in Camel case.
+
+
+ The name of the new type, in lowercase, with words separated by `_`.
+
+
+ The #GType of the prerequisite type for the interface, or %G_TYPE_INVALID
+for no prerequisite type.
+
+
+ Custom code that gets inserted in the `*_get_type()` function.
+
+
+
+
+ A convenience macro for pointer type implementations, which defines a
+`type_name_get_type()` function registering the pointer type.
+
+
+
+ The name of the new type, in Camel case
+
+
+ The name of the new type, in lowercase, with words
+ separated by `_`
+
+
+
+
+ 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.
+
+
+
+ The name of the new type, in Camel case
+
+
+ The name of the new type, in lowercase, with words
+ separated by `_`
+
+
+ Custom code that gets inserted in the `*_get_type()` function
+
+
+
+
+ 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.
+
+
+
+ The name of the new type, in Camel case.
+
+
+ The name of the new type, in lowercase, with words
+ separated by `_`.
+
+
+ The #GType of the parent type.
+
+
+
+
+ The most general convenience macro for type implementations, on which
+G_DEFINE_TYPE(), etc are based.
+
+|[<!-- language="C" -->
+G_DEFINE_TYPE_EXTENDED (GtkGadget,
+ gtk_gadget,
+ GTK_TYPE_WIDGET,
+ 0,
+ G_ADD_PRIVATE (GtkGadget)
+ G_IMPLEMENT_INTERFACE (TYPE_GIZMO,
+ gtk_gadget_gizmo_init));
+]|
+
+expands to
+
+|[<!-- language="C" -->
+static void gtk_gadget_init (GtkGadget *self);
+static void gtk_gadget_class_init (GtkGadgetClass *klass);
+static gpointer gtk_gadget_parent_class = NULL;
+static gint GtkGadget_private_offset;
+static void gtk_gadget_class_intern_init (gpointer klass)
+{
+ gtk_gadget_parent_class = g_type_class_peek_parent (klass);
+ if (GtkGadget_private_offset != 0)
+ g_type_class_adjust_private_offset (klass, &GtkGadget_private_offset);
+ gtk_gadget_class_init ((GtkGadgetClass*) klass);
+}
+static inline gpointer gtk_gadget_get_instance_private (GtkGadget *self)
+{
+ return (G_STRUCT_MEMBER_P (self, GtkGadget_private_offset));
+}
+
+GType
+gtk_gadget_get_type (void)
+{
+ static gsize static_g_define_type_id = 0;
+ if (g_once_init_enter (&static_g_define_type_id))
+ {
+ 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,
+ 0);
+ {
+ GtkGadget_private_offset =
+ g_type_add_instance_private (g_define_type_id, sizeof (GtkGadgetPrivate));
+ }
+ {
+ 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 (&static_g_define_type_id, g_define_type_id);
+ }
+ return static_g_define_type_id;
+}
+]|
+
+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.
+
+
+
+ The name of the new type, in Camel case.
+
+
+ The name of the new type, in lowercase, with words
+ separated by `_`.
+
+
+ The #GType of the parent type.
+
+
+ #GTypeFlags to pass to g_type_register_static()
+
+
+ Custom code that gets inserted in the `*_get_type()` function.
+
+
+
+
+ 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 name of the new type, in Camel case.
+
+
+ The name of the new type in lowercase, with words separated by `_`.
+
+
+ The #GType of the parent type.
+
+
+ Custom code that gets inserted in the `*_get_type()` function.
+
+
+
+
+ A convenience macro for type implementations, which declares a class
+initialization function, an instance initialization function (see #GTypeInfo
+for information about these), a static variable named `t_n_parent_class`
+pointing to the parent class, and adds private instance data to the type.
+
+Furthermore, it defines a `*_get_type()` function. See G_DEFINE_TYPE_EXTENDED()
+for an example.
+
+Note that private structs added with this macros must have a struct
+name of the form `TN ## Private`.
+
+The private instance data can be retrieved using the automatically generated
+getter function `t_n_get_instance_private()`.
+
+See also: G_ADD_PRIVATE()
+
+
+
+ The name of the new type, in Camel case.
+
+
+ The name of the new type, in lowercase, with words
+ separated by `_`.
+
+
+ The #GType of the parent type.
+
+
+
+
+ Casts a derived #GEnumClass structure into a #GEnumClass structure.
+
+
+
+ a valid #GEnumClass
+
+
+
+
+ Get the type identifier from a given #GEnumClass structure.
+
+
+
+ a #GEnumClass
+
+
+
+
+ Get the static type name from a given #GEnumClass structure.
+
+
+
+ a #GEnumClass
+
+
+
+
+ The class of an enumeration type holds information about its
+possible values.
+
+
+ the parent class
+
+
+
+ the smallest possible value.
+
+
+
+ the largest possible value.
+
+
+
+ the number of possible values.
+
+
+
+ an array of #GEnumValue structs describing the
+ individual values.
+
+
+
+
+ A structure which contains a single enum value, its name, and its
+nickname.
+
+
+ the enum value
+
+
+
+ the name of the value
+
+
+
+ the nickname of the value
+
+
+
+
+ Casts a derived #GFlagsClass structure into a #GFlagsClass structure.
+
+
+
+ a valid #GFlagsClass
+
+
+
+
+ Get the type identifier from a given #GFlagsClass structure.
+
+
+
+ a #GFlagsClass
+
+
+
+
+ Get the static type name from a given #GFlagsClass structure.
+
+
+
+ a #GFlagsClass
+
+
+
+
+ The class of a flags type holds information about its
+possible values.
+
+
+ the parent class
+
+
+
+ a mask covering all possible values.
+
+
+
+ the number of possible values.
+
+
+
+ an array of #GFlagsValue structs describing the
+ individual values.
+
+
+
+
+ A structure which contains a single flags value, its name, and its
+nickname.
+
+
+ the flags value
+
+
+
+ the name of the value
+
+
+
+ the nickname of the value
+
+
+
+
+ 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.
+
+
+
+ The #GType of the interface to add
+
+
+ The interface init function, of type #GInterfaceInitFunc
+
+
+
+
+ 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.
+
+
+
+ The #GType of the interface to add
+
+
+ The interface init function
+
+
+
+
+ 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.
+
+
+
+ Object which is subject to casting.
+
+
+
+
+ Casts a derived #GInitiallyUnownedClass structure into a
+#GInitiallyUnownedClass structure.
+
+
+
+ a valid #GInitiallyUnownedClass
+
+
+
+
+ Get the class structure associated to a #GInitiallyUnowned instance.
+
+
+
+ a #GInitiallyUnowned instance.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Checks whether @class "is a" valid #GEnumClass structure of type %G_TYPE_ENUM
+or derived.
+
+
+
+ a #GEnumClass
+
+
+
+
+ Checks whether @class "is a" valid #GFlagsClass structure of type %G_TYPE_FLAGS
+or derived.
+
+
+
+ a #GFlagsClass
+
+
+
+
+ Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_INITIALLY_UNOWNED.
+
+
+
+ Instance to check for being a %G_TYPE_INITIALLY_UNOWNED.
+
+
+
+
+ Checks whether @class "is a" valid #GInitiallyUnownedClass structure of type
+%G_TYPE_INITIALLY_UNOWNED or derived.
+
+
+
+ a #GInitiallyUnownedClass
+
+
+
+
+ Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT.
+
+
+
+ Instance to check for being a %G_TYPE_OBJECT.
+
+
+
+
+ Checks whether @class "is a" valid #GObjectClass structure of type
+%G_TYPE_OBJECT or derived.
+
+
+
+ a #GObjectClass
+
+
+
+
+ Checks whether @pspec "is a" valid #GParamSpec structure of type %G_TYPE_PARAM
+or derived.
+
+
+
+ a #GParamSpec
+
+
+
+
+ Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOOLEAN.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOXED.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_CHAR.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Checks whether @pclass "is a" valid #GParamSpecClass structure of type
+%G_TYPE_PARAM or derived.
+
+
+
+ a #GParamSpecClass
+
+
+
+
+ Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_DOUBLE.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ENUM.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLAGS.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLOAT.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_GTYPE.
+
+
+
+ a #GParamSpec
+
+
+
+
+ Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT64.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_LONG.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OBJECT.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OVERRIDE.
+
+
+
+ a #GParamSpec
+
+
+
+
+ Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_PARAM.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_POINTER.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_STRING.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UCHAR.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT64.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ULONG.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UNICHAR.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VALUE_ARRAY.
+ Use #GArray instead of #GValueArray
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VARIANT.
+
+
+
+ a #GParamSpec
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Checks if @value is a valid and initialized #GValue structure.
+
+
+
+ A #GValue structure.
+
+
+
+
+ A type for objects that have an initially floating reference.
+
+All the fields in the `GInitiallyUnowned` structure are private to the
+implementation and should never be accessed directly.
+
+
+
+
+
+
+
+
+
+
+
+
+ The class structure for the GInitiallyUnowned type.
+
+
+ the parent class
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GObject
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+The extended members of @instance are guaranteed to have been filled with
+zeros before this function is called.
+
+
+
+
+
+
+ The instance to initialize
+
+
+
+ The class of the type the instance is
+ created for
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+ The interface structure to finalize
+
+
+
+ The @interface_data supplied via the #GInterfaceInfo structure
+
+
+
+
+
+ A structure that provides information to the type system which is
+used specifically for managing interface types.
+
+
+ location of the interface initialization function
+
+
+
+ location of the interface finalization function
+
+
+
+ user-supplied data passed to the interface init/finalize functions
+
+
+
+
+ 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 members of @iface_data are guaranteed to have been filled with
+zeros before this function is called.
+
+
+
+
+
+
+ The interface structure to initialize
+
+
+
+ The @interface_data supplied via the #GInterfaceInfo structure
+
+
+
+
+
+ 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.
+
+
+
+ Object which is subject to casting.
+
+
+
+
+ Casts a derived #GObjectClass structure into a #GObjectClass structure.
+
+
+
+ a valid #GObjectClass
+
+
+
+
+ Return the name of a class structure's type.
+
+
+
+ a valid #GObjectClass
+
+
+
+
+ Get the type id of a class structure.
+
+
+
+ a valid #GObjectClass
+
+
+
+
+ Get the class structure associated to a #GObject instance.
+
+
+
+ a #GObject instance.
+
+
+
+
+ Get the type id of an object.
+
+
+
+ Object to return the type id for.
+
+
+
+
+ Get the name of an object's type.
+
+
+
+ Object to return the type name for.
+
+
+
+
+ This macro should be used to emit a standard warning about unexpected
+properties in set_property() and get_property() implementations.
+
+
+
+ the #GObject on which set_property() or get_property() was called
+
+
+ the numeric id of the property
+
+
+ the #GParamSpec of the property
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The base object type.
+
+All the fields in the `GObject` structure are private to the implementation
+and should never be accessed directly.
+
+Since GLib 2.72, all #GObjects are guaranteed to be aligned to at least the
+alignment of the largest basic GLib type (typically this is #guint64 or
+#gdouble). If you need larger alignment for an element in a #GObject, you
+should allocate it on the heap (aligned), or arrange for your #GObject to be
+appropriately padded. This guarantee applies to the #GObject (or derived)
+struct, the #GObjectClass (or derived) struct, and any private data allocated
+by G_ADD_PRIVATE().
+
+
+ Creates a new instance of a #GObject subtype and sets its properties.
+
+Construction parameters (see %G_PARAM_CONSTRUCT, %G_PARAM_CONSTRUCT_ONLY)
+which are not explicitly specified are set to their default values. Any
+private data for the object is guaranteed to be initialized with zeros, as
+per g_type_create_instance().
+
+Note that in C, small integer types in variable argument lists are promoted
+up to `gint` or `guint` as appropriate, and read back accordingly. `gint` is
+32 bits on every platform on which GLib is currently supported. This means that
+you can use C expressions of type `gint` with g_object_new() and properties of
+type `gint` or `guint` or smaller. Specifically, you can use integer literals
+with these property types.
+
+When using property types of `gint64` or `guint64`, you must ensure that the
+value that you provide is 64 bit. This means that you should use a cast or
+make use of the %G_GINT64_CONSTANT or %G_GUINT64_CONSTANT macros.
+
+Similarly, `gfloat` is promoted to `gdouble`, so you must ensure that the value
+you provide is a `gdouble`, even for a property of type `gfloat`.
+
+Since GLib 2.72, all #GObjects are guaranteed to be aligned to at least the
+alignment of the largest basic GLib type (typically this is `guint64` or
+`gdouble`). If you need larger alignment for an element in a #GObject, you
+should allocate it on the heap (aligned), or arrange for your #GObject to be
+appropriately padded.
+
+
+ a new instance of
+ @object_type
+
+
+
+
+ the type id of the #GObject subtype to instantiate
+
+
+
+ the name of the first property
+
+
+
+ the value of the first property, followed optionally by more
+ name/value pairs, followed by %NULL
+
+
+
+
+
+ Creates a new instance of a #GObject subtype and sets its properties.
+
+Construction parameters (see %G_PARAM_CONSTRUCT, %G_PARAM_CONSTRUCT_ONLY)
+which are not explicitly specified are set to their default values.
+
+
+ a new instance of @object_type
+
+
+
+
+ the type id of the #GObject subtype to instantiate
+
+
+
+ the name of the first property
+
+
+
+ the value of the first property, followed optionally by more
+ name/value pairs, followed by %NULL
+
+
+
+
+
+ Creates a new instance of a #GObject subtype and sets its properties using
+the provided arrays. Both arrays must have exactly @n_properties elements,
+and the names and values correspond by index.
+
+Construction parameters (see %G_PARAM_CONSTRUCT, %G_PARAM_CONSTRUCT_ONLY)
+which are not explicitly specified are set to their default values.
+
+
+ a new instance of
+@object_type
+
+
+
+
+ the object type to instantiate
+
+
+
+ the number of properties
+
+
+
+ the names of each property to be set
+
+
+
+
+
+ the values of each property to be set
+
+
+
+
+
+
+
+ Creates a new instance of a #GObject subtype and sets its properties.
+
+Construction parameters (see %G_PARAM_CONSTRUCT, %G_PARAM_CONSTRUCT_ONLY)
+which are not explicitly specified are set to their default values.
+ Use g_object_new_with_properties() instead.
+deprecated. See #GParameter for more information.
+
+
+ a new instance of
+@object_type
+
+
+
+
+ the type id of the #GObject subtype to instantiate
+
+
+
+ the length of the @parameters array
+
+
+
+ an array of #GParameter
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Find the #GParamSpec with the given name for an
+interface. Generally, the interface vtable passed in as @g_iface
+will be the default vtable from g_type_default_interface_ref(), or,
+if you know the interface has already been loaded,
+g_type_default_interface_peek().
+
+
+ the #GParamSpec for the property of the
+ interface with the name @property_name, or %NULL if no
+ such property exists.
+
+
+
+
+ any interface vtable for the
+ interface, or the default vtable for the interface
+
+
+
+ name of a property to look up.
+
+
+
+
+
+ Add a property to an interface; this is only useful for interfaces
+that are added to GObject-derived types. Adding a property to an
+interface forces all objects classes with that interface to have a
+compatible property. The compatible property could be a newly
+created #GParamSpec, but normally
+g_object_class_override_property() will be used so that the object
+class only needs to provide an implementation and inherits the
+property description, default value, bounds, and so forth from the
+interface property.
+
+This function is meant to be called from the interface's default
+vtable initialization function (the @class_init member of
+#GTypeInfo.) It must not be called after after @class_init has
+been called for any object types implementing this interface.
+
+If @pspec is a floating reference, it will be consumed.
+
+
+
+
+
+
+ any interface vtable for the
+ interface, or the default
+ vtable for the interface.
+
+
+
+ the #GParamSpec for the new property
+
+
+
+
+
+ Lists the properties of an interface.Generally, the interface
+vtable passed in as @g_iface will be the default vtable from
+g_type_default_interface_ref(), or, if you know the interface has
+already been loaded, g_type_default_interface_peek().
+
+
+ a
+ pointer to an array of pointers to #GParamSpec
+ structures. The paramspecs are owned by GLib, but the
+ array should be freed with g_free() when you are done with
+ it.
+
+
+
+
+
+
+ any interface vtable for the
+ interface, or the default vtable for the interface
+
+
+
+ location to store number of properties returned.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Emits a "notify" signal for the property @property_name on @object.
+
+When possible, eg. when signaling a property change from within the class
+that registered the property, you should use g_object_notify_by_pspec()
+instead.
+
+Note that emission of the notify signal may be blocked with
+g_object_freeze_notify(). In this case, the signal emissions are queued
+and will be emitted (in reverse order) when g_object_thaw_notify() is
+called.
+
+
+
+
+
+
+ a #GObject
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Increases the reference count of the object by one and sets a
+callback to be called when all other references to the object are
+dropped, or when this is already the last reference to the object
+and another reference is established.
+
+This functionality is intended for binding @object to a proxy
+object managed by another memory manager. This is done with two
+paired references: the strong reference added by
+g_object_add_toggle_ref() and a reverse reference to the proxy
+object which is either a strong reference or weak reference.
+
+The setup is that when there are no other references to @object,
+only a weak reference is held in the reverse direction from @object
+to the proxy object, but when there are other references held to
+@object, a strong reference is held. The @notify callback is called
+when the reference from @object to the proxy object should be
+"toggled" from strong to weak (@is_last_ref true) or weak to strong
+(@is_last_ref false).
+
+Since a (normal) reference must be held to the object before
+calling g_object_add_toggle_ref(), the initial state of the reverse
+link is always strong.
+
+Multiple toggle references may be added to the same gobject,
+however if there are multiple toggle references to an object, none
+of them will ever be notified until all but one are removed. For
+this reason, you should only ever use a toggle reference if there
+is important state in the proxy object.
+
+
+
+
+
+
+ a #GObject
+
+
+
+ a function to call when this reference is the
+ last reference to the object, or is no longer
+ the last reference.
+
+
+
+ data to pass to @notify
+
+
+
+
+
+ Adds a weak reference from weak_pointer to @object to indicate that
+the pointer located at @weak_pointer_location is only valid during
+the lifetime of @object. When the @object is finalized,
+@weak_pointer will be set to %NULL.
+
+Note that as with g_object_weak_ref(), the weak references created by
+this method are not thread-safe: they cannot safely be used in one
+thread if the object's last g_object_unref() might happen in another
+thread. Use #GWeakRef if thread-safety is required.
+
+
+
+
+
+
+ The object that should be weak referenced.
+
+
+
+ The memory address
+ of a pointer.
+
+
+
+
+
+ Creates a binding between @source_property on @source and @target_property
+on @target.
+
+Whenever the @source_property is changed the @target_property is
+updated using the same value. For instance:
+
+|[<!-- language="C" -->
+ g_object_bind_property (action, "active", widget, "sensitive", 0);
+]|
+
+Will result in the "sensitive" property of the widget #GObject instance to be
+updated with the same value of the "active" property of the action #GObject
+instance.
+
+If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual:
+if @target_property on @target changes then the @source_property on @source
+will be updated as well.
+
+The binding will automatically be removed when either the @source or the
+@target instances are finalized. To remove the binding without affecting the
+@source and the @target you can just call g_object_unref() on the returned
+#GBinding instance.
+
+Removing the binding by calling g_object_unref() on it must only be done if
+the binding, @source and @target are only used from a single thread and it
+is clear that both @source and @target outlive the binding. Especially it
+is not safe to rely on this if the binding, @source or @target can be
+finalized from different threads. Keep another reference to the binding and
+use g_binding_unbind() instead to be on the safe side.
+
+A #GObject can have multiple bindings.
+
+
+ the #GBinding instance representing the
+ binding between the two #GObject instances. The binding is released
+ whenever the #GBinding reference count reaches zero.
+
+
+
+
+ the source #GObject
+
+
+
+ the property on @source to bind
+
+
+
+ the target #GObject
+
+
+
+ the property on @target to bind
+
+
+
+ flags to pass to #GBinding
+
+
+
+
+
+ Complete version of g_object_bind_property().
+
+Creates a binding between @source_property on @source and @target_property
+on @target, allowing you to set the transformation functions to be used by
+the binding.
+
+If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual:
+if @target_property on @target changes then the @source_property on @source
+will be updated as well. The @transform_from function is only used in case
+of bidirectional bindings, otherwise it will be ignored
+
+The binding will automatically be removed when either the @source or the
+@target instances are finalized. This will release the reference that is
+being held on the #GBinding instance; if you want to hold on to the
+#GBinding instance, you will need to hold a reference to it.
+
+To remove the binding, call g_binding_unbind().
+
+A #GObject can have multiple bindings.
+
+The same @user_data parameter will be used for both @transform_to
+and @transform_from transformation functions; the @notify function will
+be called once, when the binding is removed. If you need different data
+for each transformation function, please use
+g_object_bind_property_with_closures() instead.
+
+
+ the #GBinding instance representing the
+ binding between the two #GObject instances. The binding is released
+ whenever the #GBinding reference count reaches zero.
+
+
+
+
+ the source #GObject
+
+
+
+ the property on @source to bind
+
+
+
+ the target #GObject
+
+
+
+ the property on @target to bind
+
+
+
+ flags to pass to #GBinding
+
+
+
+ the transformation function
+ from the @source to the @target, or %NULL to use the default
+
+
+
+ the transformation function
+ from the @target to the @source, or %NULL to use the default
+
+
+
+ custom data to be passed to the transformation functions,
+ or %NULL
+
+
+
+ a function to call when disposing the binding, to free
+ resources used by the transformation functions, or %NULL if not required
+
+
+
+
+
+ Creates a binding between @source_property on @source and @target_property
+on @target, allowing you to set the transformation functions to be used by
+the binding.
+
+This function is the language bindings friendly version of
+g_object_bind_property_full(), using #GClosures instead of
+function pointers.
+
+
+ the #GBinding instance representing the
+ binding between the two #GObject instances. The binding is released
+ whenever the #GBinding reference count reaches zero.
+
+
+
+
+ the source #GObject
+
+
+
+ the property on @source to bind
+
+
+
+ the target #GObject
+
+
+
+ the property on @target to bind
+
+
+
+ flags to pass to #GBinding
+
+
+
+ a #GClosure wrapping the transformation function
+ from the @source to the @target, or %NULL to use the default
+
+
+
+ a #GClosure wrapping the transformation function
+ from the @target to the @source, or %NULL to use the default
+
+
+
+
+
+ A convenience function to connect multiple signals at once.
+
+The signal specs expected by this function have the form
+"modifier::signal_name", where modifier can be one of the following:
+- signal: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_DEFAULT)
+- object-signal, object_signal: equivalent to g_signal_connect_object (..., G_CONNECT_DEFAULT)
+- swapped-signal, swapped_signal: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED)
+- swapped_object_signal, swapped-object-signal: equivalent to g_signal_connect_object (..., G_CONNECT_SWAPPED)
+- signal_after, signal-after: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_AFTER)
+- object_signal_after, object-signal-after: equivalent to g_signal_connect_object (..., G_CONNECT_AFTER)
+- swapped_signal_after, swapped-signal-after: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED | G_CONNECT_AFTER)
+- swapped_object_signal_after, swapped-object-signal-after: equivalent to g_signal_connect_object (..., G_CONNECT_SWAPPED | G_CONNECT_AFTER)
+
+|[<!-- language="C" -->
+ menu->toplevel = g_object_connect (g_object_new (GTK_TYPE_WINDOW,
+ "type", GTK_WINDOW_POPUP,
+ "child", menu,
+ NULL),
+ "signal::event", gtk_menu_window_event, menu,
+ "signal::size_request", gtk_menu_window_size_request, menu,
+ "signal::destroy", gtk_widget_destroyed, &menu->toplevel,
+ NULL);
+]|
+
+
+ @object
+
+
+
+
+ a #GObject
+
+
+
+ the spec for the first signal
+
+
+
+ #GCallback for the first signal, followed by data for the
+ first signal, followed optionally by more signal
+ spec/callback/data triples, followed by %NULL
+
+
+
+
+
+ A convenience function to disconnect multiple signals at once.
+
+The signal specs expected by this function have the form
+"any_signal", which means to disconnect any signal with matching
+callback and data, or "any_signal::signal_name", which only
+disconnects the signal named "signal_name".
+
+
+
+
+
+
+ a #GObject
+
+
+
+ the spec for the first signal
+
+
+
+ #GCallback for the first signal, followed by data for the first signal,
+ followed optionally by more signal spec/callback/data triples,
+ followed by %NULL
+
+
+
+
+
+ This is a variant of g_object_get_data() which returns
+a 'duplicate' of the value. @dup_func defines the
+meaning of 'duplicate' in this context, it could e.g.
+take a reference on a ref-counted object.
+
+If the @key is not set on the object then @dup_func
+will be called with a %NULL argument.
+
+Note that @dup_func is called while user data of @object
+is locked.
+
+This function can be useful to avoid races when multiple
+threads are using object data on the same key on the same
+object.
+
+
+ the result of calling @dup_func on the value
+ associated with @key on @object, or %NULL if not set.
+ If @dup_func is %NULL, the value is returned
+ unmodified.
+
+
+
+
+ the #GObject to store user data on
+
+
+
+ a string, naming the user data pointer
+
+
+
+ function to dup the value
+
+
+
+ passed as user_data to @dup_func
+
+
+
+
+
+ This is a variant of g_object_get_qdata() which returns
+a 'duplicate' of the value. @dup_func defines the
+meaning of 'duplicate' in this context, it could e.g.
+take a reference on a ref-counted object.
+
+If the @quark is not set on the object then @dup_func
+will be called with a %NULL argument.
+
+Note that @dup_func is called while user data of @object
+is locked.
+
+This function can be useful to avoid races when multiple
+threads are using object data on the same key on the same
+object.
+
+
+ the result of calling @dup_func on the value
+ associated with @quark on @object, or %NULL if not set.
+ If @dup_func is %NULL, the value is returned
+ unmodified.
+
+
+
+
+ the #GObject to store user data on
+
+
+
+ a #GQuark, naming the user data pointer
+
+
+
+ function to dup the value
+
+
+
+ passed as user_data to @dup_func
+
+
+
+
+
+ This function is intended for #GObject implementations to re-enforce
+a [floating][floating-ref] object reference. Doing this is seldom
+required: all #GInitiallyUnowneds are created with a floating reference
+which usually just needs to be sunken by calling g_object_ref_sink().
+
+
+
+
+
+
+ a #GObject
+
+
+
+
+
+ Increases the freeze count on @object. If the freeze count is
+non-zero, the emission of "notify" signals on @object is
+stopped. The signals are queued until the freeze count is decreased
+to zero. Duplicate notifications are squashed so that at most one
+#GObject::notify signal is emitted for each property modified while the
+object is frozen.
+
+This is necessary for accessors that modify multiple properties to prevent
+premature notification while the object is still being modified.
+
+
+
+
+
+
+ a #GObject
+
+
+
+
+
+ Gets properties of an object.
+
+In general, a copy is made of the property contents and the caller
+is responsible for freeing the memory in the appropriate manner for
+the type, for instance by calling g_free() or g_object_unref().
+
+Here is an example of using g_object_get() to get the contents
+of three properties: an integer, a string and an object:
+|[<!-- language="C" -->
+ gint intval;
+ guint64 uint64val;
+ gchar *strval;
+ GObject *objval;
+
+ g_object_get (my_object,
+ "int-property", &intval,
+ "uint64-property", &uint64val,
+ "str-property", &strval,
+ "obj-property", &objval,
+ NULL);
+
+ // Do something with intval, uint64val, strval, objval
+
+ g_free (strval);
+ g_object_unref (objval);
+]|
+
+
+
+
+
+
+ a #GObject
+
+
+
+ name of the first property to get
+
+
+
+ return location for the first property, followed optionally by more
+ name/return location pairs, followed by %NULL
+
+
+
+
+
+ Gets a named field from the objects table of associations (see g_object_set_data()).
+
+
+ the data if found,
+ or %NULL if no such data exists.
+
+
+
+
+ #GObject containing the associations
+
+
+
+ name of the key for that association
+
+
+
+
+
+ Gets a property of an object.
+
+The @value can be:
+
+ - an empty #GValue initialized by %G_VALUE_INIT, which will be
+ automatically initialized with the expected type of the property
+ (since GLib 2.60)
+ - a #GValue initialized with the expected type of the property
+ - a #GValue initialized with a type to which the expected type
+ of the property can be transformed
+
+In general, a copy is made of the property contents and the caller is
+responsible for freeing the memory by calling g_value_unset().
+
+Note that g_object_get_property() is really intended for language
+bindings, g_object_get() is much more convenient for C programming.
+
+
+
+
+
+
+ a #GObject
+
+
+
+ the name of the property to get
+
+
+
+ return location for the property value
+
+
+
+
+
+ This function gets back user data pointers stored via
+g_object_set_qdata().
+
+
+ The user data pointer set, or %NULL
+
+
+
+
+ The GObject to get a stored user data pointer from
+
+
+
+ A #GQuark, naming the user data pointer
+
+
+
+
+
+ Gets properties of an object.
+
+In general, a copy is made of the property contents and the caller
+is responsible for freeing the memory in the appropriate manner for
+the type, for instance by calling g_free() or g_object_unref().
+
+See g_object_get().
+
+
+
+
+
+
+ a #GObject
+
+
+
+ name of the first property to get
+
+
+
+ return location for the first property, followed optionally by more
+ name/return location pairs, followed by %NULL
+
+
+
+
+
+ Gets @n_properties properties for an @object.
+Obtained properties will be set to @values. All properties must be valid.
+Warnings will be emitted and undefined behaviour may result if invalid
+properties are passed in.
+
+
+
+
+
+
+ a #GObject
+
+
+
+ the number of properties
+
+
+
+ the names of each property to get
+
+
+
+
+
+ the values of each property to get
+
+
+
+
+
+
+
+ Checks whether @object has a [floating][floating-ref] reference.
+
+
+ %TRUE if @object has a floating reference
+
+
+
+
+ a #GObject
+
+
+
+
+
+ Emits a "notify" signal for the property @property_name on @object.
+
+When possible, eg. when signaling a property change from within the class
+that registered the property, you should use g_object_notify_by_pspec()
+instead.
+
+Note that emission of the notify signal may be blocked with
+g_object_freeze_notify(). In this case, the signal emissions are queued
+and will be emitted (in reverse order) when g_object_thaw_notify() is
+called.
+
+
+
+
+
+
+ a #GObject
+
+
+
+ the name of a property installed on the class of @object.
+
+
+
+
+
+ Emits a "notify" signal for the property specified by @pspec on @object.
+
+This function omits the property name lookup, hence it is faster than
+g_object_notify().
+
+One way to avoid using g_object_notify() from within the
+class that registered the properties, and using g_object_notify_by_pspec()
+instead, is to store the GParamSpec used with
+g_object_class_install_property() inside a static array, e.g.:
+
+|[<!-- language="C" -->
+ typedef enum
+ {
+ PROP_FOO = 1,
+ PROP_LAST
+ } MyObjectProperty;
+
+ static GParamSpec *properties[PROP_LAST];
+
+ static void
+ my_object_class_init (MyObjectClass *klass)
+ {
+ properties[PROP_FOO] = g_param_spec_int ("foo", "Foo", "The foo",
+ 0, 100,
+ 50,
+ G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
+ g_object_class_install_property (gobject_class,
+ PROP_FOO,
+ properties[PROP_FOO]);
+ }
+]|
+
+and then notify a change on the "foo" property with:
+
+|[<!-- language="C" -->
+ g_object_notify_by_pspec (self, properties[PROP_FOO]);
+]|
+
+
+
+
+
+
+ a #GObject
+
+
+
+ the #GParamSpec of a property installed on the class of @object.
+
+
+
+
+
+ Increases the reference count of @object.
+
+Since GLib 2.56, if `GLIB_VERSION_MAX_ALLOWED` is 2.56 or greater, the type
+of @object will be propagated to the return type (using the GCC typeof()
+extension), so any casting the caller needs to do on the return type must be
+explicit.
+
+
+ the same @object
+
+
+
+
+ a #GObject
+
+
+
+
+
+ Increase the reference count of @object, and possibly remove the
+[floating][floating-ref] reference, if @object has a floating reference.
+
+In other words, if the object is floating, then this call "assumes
+ownership" of the floating reference, converting it to a normal
+reference by clearing the floating flag while leaving the reference
+count unchanged. If the object is not floating, then this call
+adds a new normal reference increasing the reference count by one.
+
+Since GLib 2.56, the type of @object will be propagated to the return type
+under the same conditions as for g_object_ref().
+
+
+ @object
+
+
+
+
+ a #GObject
+
+
+
+
+
+ Removes a reference added with g_object_add_toggle_ref(). The
+reference count of the object is decreased by one.
+
+
+
+
+
+
+ a #GObject
+
+
+
+ a function to call when this reference is the
+ last reference to the object, or is no longer
+ the last reference.
+
+
+
+ data to pass to @notify, or %NULL to
+ match any toggle refs with the @notify argument.
+
+
+
+
+
+ Removes a weak reference from @object that was previously added
+using g_object_add_weak_pointer(). The @weak_pointer_location has
+to match the one used with g_object_add_weak_pointer().
+
+
+
+
+
+
+ The object that is weak referenced.
+
+
+
+ The memory address
+ of a pointer.
+
+
+
+
+
+ Compares the user data for the key @key on @object with
+@oldval, and if they are the same, replaces @oldval with
+@newval.
+
+This is like a typical atomic compare-and-exchange
+operation, for user data on an object.
+
+If the previous value was replaced then ownership of the
+old value (@oldval) is passed to the caller, including
+the registered destroy notify for it (passed out in @old_destroy).
+It’s up to the caller to free this as needed, which may
+or may not include using @old_destroy as sometimes replacement
+should not destroy the object in the normal way.
+
+See g_object_set_data() for guidance on using a small, bounded set of values
+for @key.
+
+
+ %TRUE if the existing value for @key was replaced
+ by @newval, %FALSE otherwise.
+
+
+
+
+ the #GObject to store user data on
+
+
+
+ a string, naming the user data pointer
+
+
+
+ the old value to compare against
+
+
+
+ the new value
+
+
+
+ a destroy notify for the new value
+
+
+
+ destroy notify for the existing value
+
+
+
+
+
+ Compares the user data for the key @quark on @object with
+@oldval, and if they are the same, replaces @oldval with
+@newval.
+
+This is like a typical atomic compare-and-exchange
+operation, for user data on an object.
+
+If the previous value was replaced then ownership of the
+old value (@oldval) is passed to the caller, including
+the registered destroy notify for it (passed out in @old_destroy).
+It’s up to the caller to free this as needed, which may
+or may not include using @old_destroy as sometimes replacement
+should not destroy the object in the normal way.
+
+
+ %TRUE if the existing value for @quark was replaced
+ by @newval, %FALSE otherwise.
+
+
+
+
+ the #GObject to store user data on
+
+
+
+ a #GQuark, naming the user data pointer
+
+
+
+ the old value to compare against
+
+
+
+ the new value
+
+
+
+ a destroy notify for the new value
+
+
+
+ destroy notify for the existing value
+
+
+
+
+
+ Releases all references to other objects. This can be used to break
+reference cycles.
+
+This function should only be called from object system implementations.
+
+
+
+
+
+
+ a #GObject
+
+
+
+
+
+ Sets properties on an object.
+
+The same caveats about passing integer literals as varargs apply as with
+g_object_new(). In particular, any integer literals set as the values for
+properties of type #gint64 or #guint64 must be 64 bits wide, using the
+%G_GINT64_CONSTANT or %G_GUINT64_CONSTANT macros.
+
+Note that the "notify" signals are queued and only emitted (in
+reverse order) after all properties have been set. See
+g_object_freeze_notify().
+
+
+
+
+
+
+ a #GObject
+
+
+
+ name of the first property to set
+
+
+
+ value for the first property, followed optionally by more
+ name/value pairs, followed by %NULL
+
+
+
+
+
+ Each object carries around a table of associations from
+strings to pointers. This function lets you set an association.
+
+If the object already had an association with that name,
+the old association will be destroyed.
+
+Internally, the @key is converted to a #GQuark using g_quark_from_string().
+This means a copy of @key is kept permanently (even after @object has been
+finalized) — so it is recommended to only use a small, bounded set of values
+for @key in your program, to avoid the #GQuark storage growing unbounded.
+
+
+
+
+
+
+ #GObject containing the associations.
+
+
+
+ name of the key
+
+
+
+ data to associate with that key
+
+
+
+
+
+ Like g_object_set_data() except it adds notification
+for when the association is destroyed, either by setting it
+to a different value or when the object is destroyed.
+
+Note that the @destroy callback is not called if @data is %NULL.
+
+
+
+
+
+
+ #GObject containing the associations
+
+
+
+ name of the key
+
+
+
+ data to associate with that key
+
+
+
+ function to call when the association is destroyed
+
+
+
+
+
+ Sets a property on an object.
+
+
+
+
+
+
+ a #GObject
+
+
+
+ the name of the property to set
+
+
+
+ the value
+
+
+
+
+
+ This sets an opaque, named pointer on an object.
+The name is specified through a #GQuark (retrieved e.g. via
+g_quark_from_static_string()), and the pointer
+can be gotten back from the @object with g_object_get_qdata()
+until the @object is finalized.
+Setting a previously set user data pointer, overrides (frees)
+the old pointer set, using #NULL as pointer essentially
+removes the data stored.
+
+
+
+
+
+
+ The GObject to set store a user data pointer
+
+
+
+ A #GQuark, naming the user data pointer
+
+
+
+ An opaque user data pointer
+
+
+
+
+
+ This function works like g_object_set_qdata(), but in addition,
+a void (*destroy) (gpointer) function may be specified which is
+called with @data as argument when the @object is finalized, or
+the data is being overwritten by a call to g_object_set_qdata()
+with the same @quark.
+
+
+
+
+
+
+ The GObject to set store a user data pointer
+
+
+
+ A #GQuark, naming the user data pointer
+
+
+
+ An opaque user data pointer
+
+
+
+ Function to invoke with @data as argument, when @data
+ needs to be freed
+
+
+
+
+
+ Sets properties on an object.
+
+
+
+
+
+
+ a #GObject
+
+
+
+ name of the first property to set
+
+
+
+ value for the first property, followed optionally by more
+ name/value pairs, followed by %NULL
+
+
+
+
+
+ Sets @n_properties properties for an @object.
+Properties to be set will be taken from @values. All properties must be
+valid. Warnings will be emitted and undefined behaviour may result if invalid
+properties are passed in.
+
+
+
+
+
+
+ a #GObject
+
+
+
+ the number of properties
+
+
+
+ the names of each property to be set
+
+
+
+
+
+ the values of each property to be set
+
+
+
+
+
+
+
+ Remove a specified datum from the object's data associations,
+without invoking the association's destroy handler.
+
+
+ the data if found, or %NULL
+ if no such data exists.
+
+
+
+
+ #GObject containing the associations
+
+
+
+ name of the key
+
+
+
+
+
+ This function gets back user data pointers stored via
+g_object_set_qdata() and removes the @data from object
+without invoking its destroy() function (if any was
+set).
+Usually, calling this function is only required to update
+user data pointers with a destroy notifier, for example:
+|[<!-- language="C" -->
+void
+object_add_to_user_list (GObject *object,
+ const gchar *new_string)
+{
+ // the quark, naming the object data
+ GQuark quark_string_list = g_quark_from_static_string ("my-string-list");
+ // retrieve the old string list
+ GList *list = g_object_steal_qdata (object, quark_string_list);
+
+ // prepend new string
+ list = g_list_prepend (list, g_strdup (new_string));
+ // this changed 'list', so we need to set it again
+ g_object_set_qdata_full (object, quark_string_list, list, free_string_list);
+}
+static void
+free_string_list (gpointer data)
+{
+ GList *node, *list = data;
+
+ for (node = list; node; node = node->next)
+ g_free (node->data);
+ g_list_free (list);
+}
+]|
+Using g_object_get_qdata() in the above example, instead of
+g_object_steal_qdata() would have left the destroy function set,
+and thus the partial string list would have been freed upon
+g_object_set_qdata_full().
+
+
+ The user data pointer set, or %NULL
+
+
+
+
+ The GObject to get a stored user data pointer from
+
+
+
+ A #GQuark, naming the user data pointer
+
+
+
+
+
+ If @object is floating, sink it. Otherwise, do nothing.
+
+In other words, this function will convert a floating reference (if
+present) into a full reference.
+
+Typically you want to use g_object_ref_sink() in order to
+automatically do the correct thing with respect to floating or
+non-floating references, but there is one specific scenario where
+this function is helpful.
+
+The situation where this function is helpful is when creating an API
+that allows the user to provide a callback function that returns a
+GObject. We certainly want to allow the user the flexibility to
+return a non-floating reference from this callback (for the case
+where the object that is being returned already exists).
+
+At the same time, the API style of some popular GObject-based
+libraries (such as Gtk) make it likely that for newly-created GObject
+instances, the user can be saved some typing if they are allowed to
+return a floating reference.
+
+Using this function on the return value of the user's callback allows
+the user to do whichever is more convenient for them. The caller will
+alway receives exactly one full reference to the value: either the
+one that was returned in the first place, or a floating reference
+that has been converted to a full reference.
+
+This function has an odd interaction when combined with
+g_object_ref_sink() running at the same time in another thread on
+the same #GObject instance. If g_object_ref_sink() runs first then
+the result will be that the floating reference is converted to a hard
+reference. If g_object_take_ref() runs first then the result will be
+that the floating reference is converted to a hard reference and an
+additional reference on top of that one is added. It is best to avoid
+this situation.
+
+
+ @object
+
+
+
+
+ a #GObject
+
+
+
+
+
+ Reverts the effect of a previous call to
+g_object_freeze_notify(). The freeze count is decreased on @object
+and when it reaches zero, queued "notify" signals are emitted.
+
+Duplicate notifications for each property are squashed so that at most one
+#GObject::notify signal is emitted for each property, in the reverse order
+in which they have been queued.
+
+It is an error to call this function when the freeze count is zero.
+
+
+
+
+
+
+ a #GObject
+
+
+
+
+
+ Decreases the reference count of @object. When its reference count
+drops to 0, the object is finalized (i.e. its memory is freed).
+
+If the pointer to the #GObject may be reused in future (for example, if it is
+an instance variable of another object), it is recommended to clear the
+pointer to %NULL rather than retain a dangling pointer to a potentially
+invalid #GObject instance. Use g_clear_object() for this.
+
+
+
+
+
+
+ a #GObject
+
+
+
+
+
+ This function essentially limits the life time of the @closure to
+the life time of the object. That is, when the object is finalized,
+the @closure is invalidated by calling g_closure_invalidate() on
+it, in order to prevent invocations of the closure with a finalized
+(nonexisting) object. Also, g_object_ref() and g_object_unref() are
+added as marshal guards to the @closure, to ensure that an extra
+reference count is held on @object during invocation of the
+@closure. Usually, this function will be called on closures that
+use this @object as closure data.
+
+
+
+
+
+
+ #GObject restricting lifetime of @closure
+
+
+
+ #GClosure to watch
+
+
+
+
+
+ Adds a weak reference callback to an object. Weak references are
+used for notification when an object is disposed. They are called
+"weak references" because they allow you to safely hold a pointer
+to an object without calling g_object_ref() (g_object_ref() adds a
+strong reference, that is, forces the object to stay alive).
+
+Note that the weak references created by this method are not
+thread-safe: they cannot safely be used in one thread if the
+object's last g_object_unref() might happen in another thread.
+Use #GWeakRef if thread-safety is required.
+
+
+
+
+
+
+ #GObject to reference weakly
+
+
+
+ callback to invoke before the object is freed
+
+
+
+ extra data to pass to notify
+
+
+
+
+
+ Removes a weak reference callback to an object.
+
+
+
+
+
+
+ #GObject to remove a weak reference from
+
+
+
+ callback to search for
+
+
+
+ data to search for
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The notify signal is emitted on an object when one of its properties has
+its value set through g_object_set_property(), g_object_set(), et al.
+
+Note that getting this signal doesn’t itself guarantee that the value of
+the property has actually changed. When it is emitted is determined by the
+derived GObject class. If the implementor did not create the property with
+%G_PARAM_EXPLICIT_NOTIFY, then any call to g_object_set_property() results
+in ::notify being emitted, even if the new value is the same as the old.
+If they did pass %G_PARAM_EXPLICIT_NOTIFY, then this signal is emitted only
+when they explicitly call g_object_notify() or g_object_notify_by_pspec(),
+and common practice is to do that only when the value has actually changed.
+
+This signal is typically used to obtain change notification for a
+single property, by specifying the property name as a detail in the
+g_signal_connect() call, like this:
+
+|[<!-- language="C" -->
+g_signal_connect (text_view->buffer, "notify::paste-target-list",
+ G_CALLBACK (gtk_text_view_target_list_notify),
+ text_view)
+]|
+
+It is important to note that you must use
+[canonical parameter names][canonical-parameter-names] as
+detail strings for the notify signal.
+
+
+
+
+
+ the #GParamSpec of the property which changed.
+
+
+
+
+
+
+ The class structure for the GObject type.
+
+|[<!-- language="C" -->
+// Example of implementing a singleton using a constructor.
+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;
+}
+]|
+
+
+ the parent class
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GObject
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Looks up the #GParamSpec for a property of a class.
+
+
+ the #GParamSpec for the property, or
+ %NULL if the class doesn't have a property of that name
+
+
+
+
+ a #GObjectClass
+
+
+
+ the name of the property to look up
+
+
+
+
+
+ Installs new properties from an array of #GParamSpecs.
+
+All properties should be installed during the class initializer. It
+is possible to install properties after that, but doing so is not
+recommend, and specifically, is not guaranteed to be thread-safe vs.
+use of properties on the same type on other threads.
+
+The property id of each property is the index of each #GParamSpec in
+the @pspecs array.
+
+The property id of 0 is treated specially by #GObject and it should not
+be used to store a #GParamSpec.
+
+This function should be used if you plan to use a static array of
+#GParamSpecs and g_object_notify_by_pspec(). For instance, this
+class initialization:
+
+|[<!-- language="C" -->
+typedef enum {
+ PROP_FOO = 1,
+ PROP_BAR,
+ N_PROPERTIES
+} MyObjectProperty;
+
+static GParamSpec *obj_properties[N_PROPERTIES] = { NULL, };
+
+static void
+my_object_class_init (MyObjectClass *klass)
+{
+ GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
+
+ obj_properties[PROP_FOO] =
+ g_param_spec_int ("foo", "Foo", "Foo",
+ -1, G_MAXINT,
+ 0,
+ G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
+
+ obj_properties[PROP_BAR] =
+ g_param_spec_string ("bar", "Bar", "Bar",
+ NULL,
+ G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
+
+ gobject_class->set_property = my_object_set_property;
+ gobject_class->get_property = my_object_get_property;
+ g_object_class_install_properties (gobject_class,
+ G_N_ELEMENTS (obj_properties),
+ obj_properties);
+}
+]|
+
+allows calling g_object_notify_by_pspec() to notify of property changes:
+
+|[<!-- language="C" -->
+void
+my_object_set_foo (MyObject *self, gint foo)
+{
+ if (self->foo != foo)
+ {
+ self->foo = foo;
+ g_object_notify_by_pspec (G_OBJECT (self), obj_properties[PROP_FOO]);
+ }
+ }
+]|
+
+
+
+
+
+
+ a #GObjectClass
+
+
+
+ the length of the #GParamSpecs array
+
+
+
+ the #GParamSpecs array
+ defining the new properties
+
+
+
+
+
+
+
+ Installs a new property.
+
+All properties should be installed during the class initializer. It
+is possible to install properties after that, but doing so is not
+recommend, and specifically, is not guaranteed to be thread-safe vs.
+use of properties on the same type on other threads.
+
+Note that it is possible to redefine a property in a derived class,
+by installing a property with the same name. This can be useful at times,
+e.g. to change the range of allowed values or the default value.
+
+
+
+
+
+
+ a #GObjectClass
+
+
+
+ the id for the new property
+
+
+
+ the #GParamSpec for the new property
+
+
+
+
+
+ Get an array of #GParamSpec* for all properties of a class.
+
+
+ an array of
+ #GParamSpec* which should be freed after use
+
+
+
+
+
+
+ a #GObjectClass
+
+
+
+ return location for the length of the returned array
+
+
+
+
+
+ Registers @property_id as referring to a property with the name
+@name in a parent class or in an interface implemented by @oclass.
+This allows this class to "override" a property implementation in
+a parent class or to provide the implementation of a property from
+an interface.
+
+Internally, overriding is implemented by creating a property of type
+#GParamSpecOverride; generally operations that query the properties of
+the object class, such as g_object_class_find_property() or
+g_object_class_list_properties() will return the overridden
+property. However, in one case, the @construct_properties argument of
+the @constructor virtual function, the #GParamSpecOverride is passed
+instead, so that the @param_id field of the #GParamSpec will be
+correct. For virtually all uses, this makes no difference. If you
+need to get the overridden property, you can call
+g_param_spec_get_redirect_target().
+
+
+
+
+
+
+ a #GObjectClass
+
+
+
+ the new property ID
+
+
+
+ the name of a property registered in a parent class or
+ in an interface of this class.
+
+
+
+
+
+
+ The GObjectConstructParam struct is an auxiliary structure used to hand
+#GParamSpec/#GValue pairs to the @constructor of a #GObjectClass.
+
+
+ the #GParamSpec of the construct parameter
+
+
+
+ the value to set the parameter to
+
+
+
+
+ The type of the @finalize function of #GObjectClass.
+
+
+
+
+
+
+ the #GObject being finalized
+
+
+
+
+
+ The type of the @get_property function of #GObjectClass.
+
+
+
+
+
+
+ a #GObject
+
+
+
+ the numeric id under which the property was registered with
+ g_object_class_install_property().
+
+
+
+ a #GValue to return the property value in
+
+
+
+ the #GParamSpec describing the property
+
+
+
+
+
+ The type of the @set_property function of #GObjectClass.
+
+
+
+
+
+
+ a #GObject
+
+
+
+ the numeric id under which the property was registered with
+ g_object_class_install_property().
+
+
+
+ the new value for the property
+
+
+
+ the #GParamSpec describing the property
+
+
+
+
+
+ Mask containing the bits of #GParamSpec.flags which are reserved for GLib.
+
+
+
+
+ Casts a derived #GParamSpec object (e.g. of type #GParamSpecInt) into
+a #GParamSpec object.
+
+
+
+ a valid #GParamSpec
+
+
+
+
+ Cast a #GParamSpec instance into a #GParamSpecBoolean.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Cast a #GParamSpec instance into a #GParamSpecBoxed.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Cast a #GParamSpec instance into a #GParamSpecChar.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Casts a derived #GParamSpecClass structure into a #GParamSpecClass structure.
+
+
+
+ a valid #GParamSpecClass
+
+
+
+
+ Cast a #GParamSpec instance into a #GParamSpecDouble.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Cast a #GParamSpec instance into a #GParamSpecEnum.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Cast a #GParamSpec instance into a #GParamSpecFlags.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Cast a #GParamSpec instance into a #GParamSpecFloat.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Retrieves the #GParamSpecClass of a #GParamSpec.
+
+
+
+ a valid #GParamSpec
+
+
+
+
+ Casts a #GParamSpec into a #GParamSpecGType.
+
+
+
+ a #GParamSpec
+
+
+
+
+ Cast a #GParamSpec instance into a #GParamSpecInt.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Cast a #GParamSpec instance into a #GParamSpecInt64.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Cast a #GParamSpec instance into a #GParamSpecLong.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Casts a #GParamSpec instance into a #GParamSpecObject.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Casts a #GParamSpec into a #GParamSpecOverride.
+
+
+
+ a #GParamSpec
+
+
+
+
+ Casts a #GParamSpec instance into a #GParamSpecParam.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Casts a #GParamSpec instance into a #GParamSpecPointer.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Casts a #GParamSpec instance into a #GParamSpecString.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Retrieves the #GType of this @pspec.
+
+
+
+ a valid #GParamSpec
+
+
+
+
+ Retrieves the #GType name of this @pspec.
+
+
+
+ a valid #GParamSpec
+
+
+
+
+ Cast a #GParamSpec instance into a #GParamSpecUChar.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Cast a #GParamSpec instance into a #GParamSpecUInt.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Cast a #GParamSpec instance into a #GParamSpecUInt64.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Cast a #GParamSpec instance into a #GParamSpecULong.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Cast a #GParamSpec instance into a #GParamSpecUnichar.
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Cast a #GParamSpec instance into a #GParamSpecValueArray.
+ Use #GArray instead of #GValueArray
+
+
+
+ a valid #GParamSpec instance
+
+
+
+
+ Retrieves the #GType to initialize a #GValue for this parameter.
+
+
+
+ a valid #GParamSpec
+
+
+
+
+ Casts a #GParamSpec into a #GParamSpecVariant.
+
+
+
+ a #GParamSpec
+
+
+
+
+ #GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB.
+
+It is recommended to use this for all properties by default, as it allows for
+internal performance improvements in GObject.
+
+It is very rare that a property would have a dynamically constructed name,
+nickname or blurb.
+
+Since 2.13.0
+
+
+
+
+ Minimum shift count to be used for user defined flags, to be stored in
+#GParamSpec.flags. The maximum allowed is 10.
+
+
+
+
+ Evaluates to the @field_name inside the @inst private data
+structure for @TypeName.
+
+Note that this macro can only be used together with the `G_DEFINE_TYPE_*`
+and G_ADD_PRIVATE() macros, since it depends on variable names from
+those macros.
+
+
+
+ the name of the type in CamelCase
+
+
+ the instance of @TypeName you wish to access
+
+
+ the type of the field in the private data structure
+
+
+ the name of the field in the private data structure
+
+
+
+
+ Evaluates to a pointer to the @field_name inside the @inst private data
+structure for @TypeName.
+
+Note that this macro can only be used together with the `G_DEFINE_TYPE_*`
+and G_ADD_PRIVATE() macros, since it depends on variable names from
+those macros.
+
+
+
+ the name of the type in CamelCase
+
+
+ the instance of @TypeName you wish to access
+
+
+ the name of the field in the private data structure
+
+
+
+
+ Evaluates to the offset of the @field inside the instance private data
+structure for @TypeName.
+
+Note that this macro can only be used together with the `G_DEFINE_TYPE_*`
+and G_ADD_PRIVATE() macros, since it depends on variable names from
+those macros.
+
+
+
+ the name of the type in CamelCase
+
+
+ the name of the field in the private data structure
+
+
+
+
+ Through the #GParamFlags flag values, certain aspects of parameters
+can be configured.
+
+See also: %G_PARAM_STATIC_STRINGS
+
+
+ the parameter is readable
+
+
+ the parameter is writable
+
+
+ alias for %G_PARAM_READABLE | %G_PARAM_WRITABLE
+
+
+ the parameter will be set upon object construction
+
+
+ the parameter can only be set upon object construction
+
+
+ upon parameter conversion (see g_param_value_convert())
+ strict validation is not required
+
+
+ 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
+
+
+ internal
+
+
+ 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
+
+
+ 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
+
+
+ calls to g_object_set_property() for this
+ property will not automatically result in a "notify" signal being
+ emitted: the implementation must call g_object_notify() themselves
+ in case the property actually changes. Since: 2.42.
+
+
+ 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
+
+
+
+ #GParamSpec is an object structure that encapsulates the metadata
+required to specify parameters, such as e.g. #GObject properties.
+
+## Parameter names # {#canonical-parameter-names}
+
+A property name consists of one or more segments consisting of ASCII letters
+and digits, separated by either the `-` or `_` character. The first
+character of a property name must be a letter. These are the same rules as
+for signal naming (see g_signal_new()).
+
+When creating and looking up a #GParamSpec, either separator can be
+used, but they cannot be mixed. Using `-` is considerably more
+efficient, and is the ‘canonical form’. Using `_` is discouraged.
+
+
+ Creates a new #GParamSpec instance.
+
+See [canonical parameter names][canonical-parameter-names] for details of
+the rules for @name. Names which violate these rules lead to undefined
+behaviour.
+
+Beyond the name, #GParamSpecs have two more descriptive strings, the
+@nick and @blurb, which may be used as a localized label and description.
+For GTK and related libraries these are considered deprecated and may be
+omitted, while for other libraries such as GStreamer and its plugins they
+are essential. When in doubt, follow the conventions used in the
+surrounding code and supporting libraries.
+
+
+ (transfer floating): a newly allocated
+ #GParamSpec instance, which is initially floating
+
+
+
+
+ the #GType for the property; must be derived from %G_TYPE_PARAM
+
+
+
+ the canonical name of the property
+
+
+
+ the nickname of the property
+
+
+
+ a short description of the property
+
+
+
+ a combination of #GParamFlags
+
+
+
+
+
+ Validate a property name for a #GParamSpec. This can be useful for
+dynamically-generated properties which need to be validated at run-time
+before actually trying to create them.
+
+See [canonical parameter names][canonical-parameter-names] for details of
+the rules for valid names.
+
+
+ %TRUE if @name is a valid property name, %FALSE otherwise.
+
+
+
+
+ the canonical name of the property
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Get the short description of a #GParamSpec.
+
+
+ the short description of @pspec.
+
+
+
+
+ a valid #GParamSpec
+
+
+
+
+
+ Gets the default value of @pspec as a pointer to a #GValue.
+
+The #GValue will remain valid for the life of @pspec.
+
+
+ a pointer to a #GValue which must not be modified
+
+
+
+
+ a #GParamSpec
+
+
+
+
+
+ Get the name of a #GParamSpec.
+
+The name is always an "interned" string (as per g_intern_string()).
+This allows for pointer-value comparisons.
+
+
+ the name of @pspec.
+
+
+
+
+ a valid #GParamSpec
+
+
+
+
+
+ Gets the GQuark for the name.
+
+
+ the GQuark for @pspec->name.
+
+
+
+
+ a #GParamSpec
+
+
+
+
+
+ Get the nickname of a #GParamSpec.
+
+
+ the nickname of @pspec.
+
+
+
+
+ a valid #GParamSpec
+
+
+
+
+
+ Gets back user data pointers stored via g_param_spec_set_qdata().
+
+
+ the user data pointer set, or %NULL
+
+
+
+
+ a valid #GParamSpec
+
+
+
+ a #GQuark, naming the user data pointer
+
+
+
+
+
+ If the paramspec redirects operations to another paramspec,
+returns that paramspec. Redirect is used typically for
+providing a new implementation of a property in a derived
+type while preserving all the properties from the parent
+type. Redirection is established by creating a property
+of type #GParamSpecOverride. See g_object_class_override_property()
+for an example of the use of this capability.
+
+
+ paramspec to which requests on this
+ paramspec should be redirected, or %NULL if none.
+
+
+
+
+ a #GParamSpec
+
+
+
+
+
+ Increments the reference count of @pspec.
+
+
+ the #GParamSpec that was passed into this function
+
+
+
+
+ a valid #GParamSpec
+
+
+
+
+
+ Convenience function to ref and sink a #GParamSpec.
+
+
+ the #GParamSpec that was passed into this function
+
+
+
+
+ a valid #GParamSpec
+
+
+
+
+
+ Sets an opaque, named pointer on a #GParamSpec. The name is
+specified through a #GQuark (retrieved e.g. via
+g_quark_from_static_string()), and the pointer can be gotten back
+from the @pspec with g_param_spec_get_qdata(). Setting a
+previously set user data pointer, overrides (frees) the old pointer
+set, using %NULL as pointer essentially removes the data stored.
+
+
+
+
+
+
+ the #GParamSpec to set store a user data pointer
+
+
+
+ a #GQuark, naming the user data pointer
+
+
+
+ an opaque user data pointer
+
+
+
+
+
+ This function works like g_param_spec_set_qdata(), but in addition,
+a `void (*destroy) (gpointer)` function may be
+specified which is called with @data as argument when the @pspec is
+finalized, or the data is being overwritten by a call to
+g_param_spec_set_qdata() with the same @quark.
+
+
+
+
+
+
+ the #GParamSpec to set store a user data pointer
+
+
+
+ a #GQuark, naming the user data pointer
+
+
+
+ an opaque user data pointer
+
+
+
+ function to invoke with @data as argument, when @data needs to
+ be freed
+
+
+
+
+
+ The initial reference count of a newly created #GParamSpec is 1,
+even though no one has explicitly called g_param_spec_ref() on it
+yet. So the initial reference count is flagged as "floating", until
+someone calls `g_param_spec_ref (pspec); g_param_spec_sink
+(pspec);` in sequence on it, taking over the initial
+reference count (thus ending up with a @pspec that has a reference
+count of 1 still, but is not flagged "floating" anymore).
+
+
+
+
+
+
+ a valid #GParamSpec
+
+
+
+
+
+ Gets back user data pointers stored via g_param_spec_set_qdata()
+and removes the @data from @pspec without invoking its destroy()
+function (if any was set). Usually, calling this function is only
+required to update user data pointers with a destroy notifier.
+
+
+ the user data pointer set, or %NULL
+
+
+
+
+ the #GParamSpec to get a stored user data pointer from
+
+
+
+ a #GQuark, naming the user data pointer
+
+
+
+
+
+ Decrements the reference count of a @pspec.
+
+
+
+
+
+
+ a valid #GParamSpec
+
+
+
+
+
+ private #GTypeInstance portion
+
+
+
+ name of this parameter: always an interned string
+
+
+
+ #GParamFlags flags for this parameter
+
+
+
+ the #GValue type for this parameter
+
+
+
+ #GType type that uses (introduces) this parameter
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ A #GParamSpec derived structure that contains the meta data for boolean properties.
+
+ private #GParamSpec portion
+
+
+
+ default value for the property specified
+
+
+
+
+ A #GParamSpec derived structure that contains the meta data for boxed properties.
+
+ private #GParamSpec portion
+
+
+
+
+ A #GParamSpec derived structure that contains the meta data for character properties.
+
+ private #GParamSpec portion
+
+
+
+ minimum value for the property specified
+
+
+
+ maximum value for the property specified
+
+
+
+ default value for the property specified
+
+
+
+
+ The class structure for the GParamSpec type.
+Normally, GParamSpec classes are filled by
+g_param_type_register_static().
+
+
+ the parent class
+
+
+
+ the #GValue type for this parameter
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ A #GParamSpec derived structure that contains the meta data for double properties.
+
+ private #GParamSpec portion
+
+
+
+ minimum value for the property specified
+
+
+
+ maximum value for the property specified
+
+
+
+ default value for the property specified
+
+
+
+ values closer than @epsilon will be considered identical
+ by g_param_values_cmp(); the default value is 1e-90.
+
+
+
+
+ A #GParamSpec derived structure that contains the meta data for enum
+properties.
+
+ private #GParamSpec portion
+
+
+
+ the #GEnumClass for the enum
+
+
+
+ default value for the property specified
+
+
+
+
+ A #GParamSpec derived structure that contains the meta data for flags
+properties.
+
+ private #GParamSpec portion
+
+
+
+ the #GFlagsClass for the flags
+
+
+
+ default value for the property specified
+
+
+
+
+ A #GParamSpec derived structure that contains the meta data for float properties.
+
+ private #GParamSpec portion
+
+
+
+ minimum value for the property specified
+
+
+
+ maximum value for the property specified
+
+
+
+ default value for the property specified
+
+
+
+ values closer than @epsilon will be considered identical
+ by g_param_values_cmp(); the default value is 1e-30.
+
+
+
+
+ A #GParamSpec derived structure that contains the meta data for #GType properties.
+
+ private #GParamSpec portion
+
+
+
+ a #GType whose subtypes can occur as values
+
+
+
+
+ A #GParamSpec derived structure that contains the meta data for integer properties.
+
+ private #GParamSpec portion
+
+
+
+ minimum value for the property specified
+
+
+
+ maximum value for the property specified
+
+
+
+ default value for the property specified
+
+
+
+
+ A #GParamSpec derived structure that contains the meta data for 64bit integer properties.
+
+ private #GParamSpec portion
+
+
+
+ minimum value for the property specified
+
+
+
+ maximum value for the property specified
+
+
+
+ default value for the property specified
+
+
+
+
+ A #GParamSpec derived structure that contains the meta data for long integer properties.
+
+ private #GParamSpec portion
+
+
+
+ minimum value for the property specified
+
+
+
+ maximum value for the property specified
+
+
+
+ default value for the property specified
+
+
+
+
+ A #GParamSpec derived structure that contains the meta data for object properties.
+
+ private #GParamSpec portion
+
+
+
+
+ A #GParamSpec derived structure that redirects operations to
+other types of #GParamSpec.
+
+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 overridden
+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.
+
+
+
+
+
+
+
+
+ A #GParamSpec derived structure that contains the meta data for %G_TYPE_PARAM
+properties.
+
+ private #GParamSpec portion
+
+
+
+
+ A #GParamSpec derived structure that contains the meta data for pointer properties.
+
+ private #GParamSpec portion
+
+
+
+
+ A #GParamSpecPool maintains a collection of #GParamSpecs which can be
+quickly accessed by owner and name.
+
+The implementation of the #GObject property system uses such a pool to
+store the #GParamSpecs of the properties all object types.
+
+
+ Inserts a #GParamSpec in the pool.
+
+
+
+
+
+
+ a #GParamSpecPool.
+
+
+
+ the #GParamSpec to insert
+
+
+
+ a #GType identifying the owner of @pspec
+
+
+
+
+
+ Gets an array of all #GParamSpecs owned by @owner_type in
+the pool.
+
+
+ a newly
+ allocated array containing pointers to all #GParamSpecs
+ owned by @owner_type in the pool
+
+
+
+
+
+
+ a #GParamSpecPool
+
+
+
+ the owner to look for
+
+
+
+ return location for the length of the returned array
+
+
+
+
+
+ Gets an #GList of all #GParamSpecs owned by @owner_type in
+the pool.
+
+
+ a
+ #GList of all #GParamSpecs owned by @owner_type in
+ the pool#GParamSpecs.
+
+
+
+
+
+
+ a #GParamSpecPool
+
+
+
+ the owner to look for
+
+
+
+
+
+ Looks up a #GParamSpec in the pool.
+
+
+ The found #GParamSpec, or %NULL if no
+matching #GParamSpec was found.
+
+
+
+
+ a #GParamSpecPool
+
+
+
+ the name to look for
+
+
+
+ the owner to look for
+
+
+
+ If %TRUE, also try to find a #GParamSpec with @param_name
+ owned by an ancestor of @owner_type.
+
+
+
+
+
+ Removes a #GParamSpec from the pool.
+
+
+
+
+
+
+ a #GParamSpecPool
+
+
+
+ the #GParamSpec to remove
+
+
+
+
+
+ Creates a new #GParamSpecPool.
+
+If @type_prefixing is %TRUE, lookups in the newly created pool will
+allow to specify the owner as a colon-separated prefix of the
+property name, like "GtkContainer:border-width". This feature is
+deprecated, so you should always set @type_prefixing to %FALSE.
+
+
+ a newly allocated #GParamSpecPool.
+
+
+
+
+ Whether the pool will support type-prefixed property names.
+
+
+
+
+
+
+ A #GParamSpec derived structure that contains the meta data for string
+properties.
+
+ private #GParamSpec portion
+
+
+
+ default value for the property specified
+
+
+
+ a string containing the allowed values for the first byte
+
+
+
+ a string containing the allowed values for the subsequent bytes
+
+
+
+ the replacement byte for bytes which don't match @cset_first or @cset_nth.
+
+
+
+ replace empty string by %NULL
+
+
+
+ replace %NULL strings by an empty string
+
+
+
+
+ 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().
+
+
+ Size of the instance (object) structure.
+
+
+
+ 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 [slice allocator][glib-Memory-Slices] now.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The #GType of values conforming to this #GParamSpec
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ A #GParamSpec derived structure that contains the meta data for unsigned character properties.
+
+ private #GParamSpec portion
+
+
+
+ minimum value for the property specified
+
+
+
+ maximum value for the property specified
+
+
+
+ default value for the property specified
+
+
+
+
+ A #GParamSpec derived structure that contains the meta data for unsigned integer properties.
+
+ private #GParamSpec portion
+
+
+
+ minimum value for the property specified
+
+
+
+ maximum value for the property specified
+
+
+
+ default value for the property specified
+
+
+
+
+ A #GParamSpec derived structure that contains the meta data for unsigned 64bit integer properties.
+
+ private #GParamSpec portion
+
+
+
+ minimum value for the property specified
+
+
+
+ maximum value for the property specified
+
+
+
+ default value for the property specified
+
+
+
+
+ A #GParamSpec derived structure that contains the meta data for unsigned long integer properties.
+
+ private #GParamSpec portion
+
+
+
+ minimum value for the property specified
+
+
+
+ maximum value for the property specified
+
+
+
+ default value for the property specified
+
+
+
+
+ A #GParamSpec derived structure that contains the meta data for unichar (unsigned integer) properties.
+
+ private #GParamSpec portion
+
+
+
+ default value for the property specified
+
+
+
+
+ A #GParamSpec derived structure that contains the meta data for #GValueArray properties.
+
+ private #GParamSpec portion
+
+
+
+ a #GParamSpec describing the elements contained in arrays of this property, may be %NULL
+
+
+
+ if greater than 0, arrays of this property will always have this many elements
+
+
+
+
+ A #GParamSpec derived structure that contains the meta data for #GVariant properties.
+
+When comparing values with g_param_values_cmp(), scalar values with the same
+type will be compared with g_variant_compare(). Other non-%NULL variants will
+be checked for equality with g_variant_equal(), and their sort order is
+otherwise undefined. %NULL is ordered before non-%NULL variants. Two %NULL
+values compare equal.
+
+ private #GParamSpec portion
+
+
+
+ a #GVariantType, or %NULL
+
+
+
+ a #GVariant, or %NULL
+
+
+
+
+
+
+
+
+
+ The GParameter struct is an auxiliary structure used
+to hand parameter name/value pairs to g_object_newv().
+ This type is not introspectable.
+
+
+ the parameter name
+
+
+
+ the parameter value
+
+
+
+
+ A mask for all #GSignalFlags bits.
+
+
+
+
+
+
+
+
+
+
+
+ A mask for all #GSignalMatchType bits.
+
+
+
+
+ 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.
+
+
+ The accumulator function returns whether the signal emission
+ should be aborted. Returning %TRUE will continue with
+ the signal emission. Returning %FALSE will abort the current emission.
+ Since 2.62, returning %FALSE will skip to the CLEANUP stage. In this case,
+ emission will occur as normal in the CLEANUP stage and the handler's
+ return value will be accumulated.
+
+
+
+
+ Signal invocation hint, see #GSignalInvocationHint.
+
+
+
+ Accumulator to collect callback return values in, this
+ is the return value of the current signal emission.
+
+
+
+ A #GValue holding the return value of the signal handler.
+
+
+
+ Callback data that was specified when creating the signal.
+
+
+
+
+
+ A simple function pointer to get invoked when the signal is emitted.
+
+Emission hooks allow 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.
+
+
+ whether it wants to stay connected. If it returns %FALSE, the signal
+ hook is disconnected (and destroyed).
+
+
+
+
+ Signal invocation hint, see #GSignalInvocationHint.
+
+
+
+ the number of parameters to the function, including
+ the instance on which the signal was emitted.
+
+
+
+ the instance on which
+ the signal was emitted, followed by the parameters of the emission.
+
+
+
+
+
+ user data associated with the hook.
+
+
+
+
+
+ The signal flags are used to specify a signal's behaviour.
+
+
+ Invoke the object method handler in the first emission stage.
+
+
+ Invoke the object method handler in the third emission stage.
+
+
+ Invoke the object method handler in the last emission stage.
+
+
+ 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.
+
+
+ This signal supports "::detail" appendices to the signal name
+ upon handler connections and emissions.
+
+
+ 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.
+
+
+ No emissions hooks are supported for this signal.
+
+
+ Varargs signal emission will always collect the
+ arguments, even if there are no signal handlers connected. Since 2.30.
+
+
+ The signal is deprecated and will be removed
+ in a future version. A warning will be generated if it is connected while
+ running with G_ENABLE_DIAGNOSTIC=1. Since 2.32.
+
+
+ Only used in #GSignalAccumulator accumulator
+ functions for the #GSignalInvocationHint::run_type field to mark the first
+ call to the accumulator function for a signal emission. Since 2.68.
+
+
+
+ #GSignalGroup manages to simplify the process of connecting
+many signals to a #GObject as a group. As such there is no API
+to disconnect a signal from the group.
+
+In particular, this allows you to:
+
+ - Change the target instance, which automatically causes disconnection
+ of the signals from the old instance and connecting to the new instance.
+ - Block and unblock signals as a group
+ - Ensuring that blocked state transfers across target instances.
+
+One place you might want to use such a structure is with #GtkTextView and
+#GtkTextBuffer. Often times, you'll need to connect to many signals on
+#GtkTextBuffer from a #GtkTextView subclass. This allows you to create a
+signal group during instance construction, simply bind the
+#GtkTextView:buffer property to #GSignalGroup:target and connect
+all the signals you need. When the #GtkTextView:buffer property changes
+all of the signals will be transitioned correctly.
+
+ Creates a new #GSignalGroup for target instances of @target_type.
+
+
+ a new #GSignalGroup
+
+
+
+
+ the #GType of the target instance.
+
+
+
+
+
+ Blocks all signal handlers managed by @self so they will not
+be called during any signal emissions. Must be unblocked exactly
+the same number of times it has been blocked to become active again.
+
+This blocked state will be kept across changes of the target instance.
+
+
+
+
+
+
+ the #GSignalGroup
+
+
+
+
+
+ Connects @c_handler to the signal @detailed_signal
+on the target instance of @self.
+
+You cannot connect a signal handler after #GSignalGroup:target has been set.
+
+
+
+
+
+
+ a #GSignalGroup
+
+
+
+ a string of the form "signal-name::detail"
+
+
+
+ the #GCallback to connect
+
+
+
+ the data to pass to @c_handler calls
+
+
+
+
+
+ Connects @c_handler to the signal @detailed_signal
+on the target instance of @self.
+
+The @c_handler will be called after the default handler of the signal.
+
+You cannot connect a signal handler after #GSignalGroup:target has been set.
+
+
+
+
+
+
+ a #GSignalGroup
+
+
+
+ a string of the form "signal-name::detail"
+
+
+
+ the #GCallback to connect
+
+
+
+ the data to pass to @c_handler calls
+
+
+
+
+
+ Connects @closure to the signal @detailed_signal on #GSignalGroup:target.
+
+You cannot connect a signal handler after #GSignalGroup:target has been set.
+
+
+
+
+
+
+ a #GSignalGroup
+
+
+
+ a string of the form `signal-name` with optional `::signal-detail`
+
+
+
+ the closure to connect.
+
+
+
+ whether the handler should be called before or after the
+ default handler of the signal.
+
+
+
+
+
+ Connects @c_handler to the signal @detailed_signal
+on the target instance of @self.
+
+You cannot connect a signal handler after #GSignalGroup:target has been set.
+
+
+
+
+
+
+ a #GSignalGroup
+
+
+
+ a string of the form "signal-name::detail"
+
+
+
+ the #GCallback to connect
+
+
+
+ the data to pass to @c_handler calls
+
+
+
+ function to be called when disposing of @self
+
+
+
+ the flags used to create the signal connection
+
+
+
+
+
+ Connects @c_handler to the signal @detailed_signal on #GSignalGroup:target.
+
+Ensures that the @object stays alive during the call to @c_handler
+by temporarily adding a reference count. When the @object is destroyed
+the signal handler will automatically be removed.
+
+You cannot connect a signal handler after #GSignalGroup:target has been set.
+
+
+
+
+
+
+ a #GSignalGroup
+
+
+
+ a string of the form `signal-name` with optional `::signal-detail`
+
+
+
+ the #GCallback to connect
+
+
+
+ the #GObject to pass as data to @c_handler calls
+
+
+
+ #GConnectFlags for the signal connection
+
+
+
+
+
+ Connects @c_handler to the signal @detailed_signal
+on the target instance of @self.
+
+The instance on which the signal is emitted and @data
+will be swapped when calling @c_handler.
+
+You cannot connect a signal handler after #GSignalGroup:target has been set.
+
+
+
+
+
+
+ a #GSignalGroup
+
+
+
+ a string of the form "signal-name::detail"
+
+
+
+ the #GCallback to connect
+
+
+
+ the data to pass to @c_handler calls
+
+
+
+
+
+ Gets the target instance used when connecting signals.
+
+
+ The target instance
+
+
+
+
+ the #GSignalGroup
+
+
+
+
+
+ Sets the target instance used when connecting signals. Any signal
+that has been registered with g_signal_group_connect_object() or
+similar functions will be connected to this object.
+
+If the target instance was previously set, signals will be
+disconnected from that object prior to connecting to @target.
+
+
+
+
+
+
+ the #GSignalGroup.
+
+
+
+ The target instance used
+ when connecting signals.
+
+
+
+
+
+ Unblocks all signal handlers managed by @self so they will be
+called again during any signal emissions unless it is blocked
+again. Must be unblocked exactly the same number of times it
+has been blocked to become active again.
+
+
+
+
+
+
+ the #GSignalGroup
+
+
+
+
+
+ The target instance used when connecting signals.
+
+
+
+ The #GType of the target property.
+
+
+
+ This signal is emitted when #GSignalGroup:target is set to a new value
+other than %NULL. It is similar to #GObject::notify on `target` except it
+will not emit when #GSignalGroup:target is %NULL and also allows for
+receiving the #GObject without a data-race.
+
+
+
+
+
+ a #GObject containing the new value for #GSignalGroup:target
+
+
+
+
+
+ This signal is emitted when the target instance of @self is set to a
+new #GObject.
+
+This signal will only be emitted if the previous target of @self is
+non-%NULL.
+
+
+
+
+
+
+ The #GSignalInvocationHint structure is used to pass on additional information
+to callbacks during a signal emission.
+
+
+ The signal id of the signal invoking the callback
+
+
+
+ The detail passed on for this emission
+
+
+
+ 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 and %G_SIGNAL_ACCUMULATOR_FIRST_RUN.
+ %G_SIGNAL_ACCUMULATOR_FIRST_RUN is only set for the first run of the accumulator
+ function for a signal emission.
+
+
+
+
+ The match types specify what g_signal_handlers_block_matched(),
+g_signal_handlers_unblock_matched() and g_signal_handlers_disconnect_matched()
+match signals by.
+
+
+ The signal id must be equal.
+
+
+ The signal detail must be equal.
+
+
+ The closure must be the same.
+
+
+ The C closure callback must be the same.
+
+
+ The closure data must be the same.
+
+
+ Only unblocked signals may be matched.
+
+
+
+ A structure holding in-depth information for a specific signal.
+
+See also: g_signal_query()
+
+
+ The signal id of the signal being queried, or 0 if the
+ signal to be queried was unknown.
+
+
+
+ The signal name.
+
+
+
+ The interface/instance type that this signal can be emitted for.
+
+
+
+ The signal flags as passed in to g_signal_new().
+
+
+
+ The return type for user callbacks.
+
+
+
+ The number of parameters that user callbacks take.
+
+
+
+ The individual parameter types for
+ user callbacks, note that the effective callback signature is:
+ |[<!-- language="C" -->
+ @return_type callback (#gpointer data1,
+ [param_types param_names,]
+ gpointer data2);
+ ]|
+
+
+
+
+
+
+ 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. %NULL is not a valid class structure.
+
+This macro should only be used in type implementations.
+
+
+
+ Location of a #GTypeClass structure
+
+
+ The type to be returned
+
+
+ The corresponding C type of class structure of @g_type
+
+
+
+
+ Checks if @g_class is a class structure of the type identified by
+@g_type. If @g_class is %NULL, %FALSE will be returned.
+
+This macro should only be used in type implementations.
+
+
+
+ Location of a #GTypeClass structure
+
+
+ The type to be checked
+
+
+
+
+ Checks if @instance is a valid #GTypeInstance structure,
+otherwise issues a warning and returns %FALSE. %NULL is not a valid
+#GTypeInstance.
+
+This macro should only be used in type implementations.
+
+
+
+ Location of a #GTypeInstance structure
+
+
+
+
+ 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.
+
+No warning will be issued if @instance is %NULL, and %NULL will be returned.
+
+This macro should only be used in type implementations.
+
+
+
+ Location of a #GTypeInstance structure
+
+
+ The type to be returned
+
+
+ The corresponding C type of @g_type
+
+
+
+
+ Checks if @instance is an instance of the fundamental type identified by @g_type.
+If @instance is %NULL, %FALSE will be returned.
+
+This macro should only be used in type implementations.
+
+
+
+ Location of a #GTypeInstance structure.
+
+
+ The fundamental type to be checked
+
+
+
+
+ Checks if @instance is an instance of the type identified by @g_type. If
+@instance is %NULL, %FALSE will be returned.
+
+This macro should only be used in type implementations.
+
+
+
+ Location of a #GTypeInstance structure.
+
+
+ The type to be checked
+
+
+
+
+ Checks if @value has been initialized to hold values
+of a value type.
+
+This macro should only be used in type implementations.
+
+
+
+ a #GValue
+
+
+
+
+ Checks if @value has been initialized to hold values
+of type @g_type.
+
+This macro should only be used in type implementations.
+
+
+
+ a #GValue
+
+
+ The type to be checked
+
+
+
+
+ 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.
+
+
+
+ the class of a type deriving from @private_type
+
+
+ the type identifying which private data to retrieve
+
+
+ The C type for the private structure
+
+
+
+
+ A bit in the type number that's supposed to be left untouched.
+
+
+
+
+ Get the type identifier from a given @class structure.
+
+This macro should only be used in type implementations.
+
+
+
+ Location of a valid #GTypeClass structure
+
+
+
+
+ Get the type identifier from a given @instance structure.
+
+This macro should only be used in type implementations.
+
+
+
+ Location of a valid #GTypeInstance structure
+
+
+
+
+ Get the type identifier from a given @interface structure.
+
+This macro should only be used in type implementations.
+
+
+
+ Location of a valid #GTypeInterface structure
+
+
+
+
+ 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.
+
+
+
+ A #GType value.
+
+
+
+
+ An integer constant that represents the number of identifiers reserved
+for types that are assigned at compile-time.
+
+
+
+
+ Shift value used in converting numbers to type IDs.
+
+
+
+
+ Checks if @type has a #GTypeValueTable.
+
+
+
+ A #GType value
+
+
+
+
+ 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.
+
+
+
+ Location of the #GTypeInstance structure
+
+
+ The #GType of the class to be returned
+
+
+ The C type of the class structure
+
+
+
+
+ Get the interface structure for interface @g_type of a given @instance.
+
+This macro should only be used in type implementations.
+
+
+
+ Location of the #GTypeInstance structure
+
+
+ The #GType of the interface to be returned
+
+
+ The C type of the interface 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().
+
+This macro should only be used in type implementations.
+ Use G_ADD_PRIVATE() and the generated
+ `your_type_get_instance_private()` function instead
+
+
+
+ the instance of a type deriving from @private_type
+
+
+ the type identifying which private data to retrieve
+
+
+ The C type for the private structure
+
+
+
+
+ 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.
+
+
+
+ A #GType value
+
+
+
+
+
+
+
+
+
+
+
+ Checks if @type is a classed type.
+
+
+
+ A #GType value
+
+
+
+
+ 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.
+
+
+
+ A #GType value
+
+
+
+
+ Checks if @type is deprecated. Instantiating a deprecated type will
+trigger a warning if running with `G_ENABLE_DIAGNOSTIC=1`.
+
+
+
+ a #GType value
+
+
+
+
+ Checks if @type is a derivable type. A derivable type can
+be used as the base class of a flat (single-level) class hierarchy.
+
+
+
+ A #GType value
+
+
+
+
+ Checks if @type is derived (or in object-oriented terminology:
+inherited) from another type (this holds true for all non-fundamental
+types).
+
+
+
+ A #GType value
+
+
+
+
+ Checks whether @type "is a" %G_TYPE_ENUM.
+
+
+
+ a #GType ID.
+
+
+
+
+ Checks if @type is a final type. A final type cannot be derived any
+further.
+
+
+
+ a #GType value
+
+
+
+
+ Checks whether @type "is a" %G_TYPE_FLAGS.
+
+
+
+ a #GType ID.
+
+
+
+
+ Checks if @type is a fundamental type.
+
+
+
+ A #GType value
+
+
+
+
+ Checks if @type can be instantiated. Instantiation is the
+process of creating an instance (object) of this type.
+
+
+
+ A #GType value
+
+
+
+
+ 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).
+
+
+
+ A #GType value
+
+
+
+
+ Check if the passed in type id is a %G_TYPE_OBJECT or derived from it.
+
+
+
+ Type id to check
+
+
+
+
+ Checks whether @type "is a" %G_TYPE_PARAM.
+
+
+
+ a #GType ID
+
+
+
+
+ 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.
+
+
+
+ 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.
+
+
+
+ A #GType value
+
+
+
+
+ Checks if @type is a value type and can be used with g_value_init().
+
+
+
+ A #GType value
+
+
+
+
+ Get the type ID for the fundamental type number @x.
+
+Use g_type_fundamental_next() instead of this macro to create new fundamental
+types.
+
+
+
+ the fundamental type number.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ First fundamental type number to create a new fundamental type id with
+G_TYPE_MAKE_FUNDAMENTAL() reserved for BSE.
+
+
+
+
+ Last fundamental type number reserved for BSE.
+
+
+
+
+ First fundamental type number to create a new fundamental type id with
+G_TYPE_MAKE_FUNDAMENTAL() reserved for GLib.
+
+
+
+
+ Last fundamental type number reserved for GLib.
+
+
+
+
+ First available fundamental type number to create new fundamental
+type id with G_TYPE_MAKE_FUNDAMENTAL().
+
+
+
+
+ A callback function used for notification when the state
+of a toggle reference changes.
+
+See also: g_object_add_toggle_ref()
+
+
+
+
+
+
+ Callback data passed to g_object_add_toggle_ref()
+
+
+
+ The object on which g_object_add_toggle_ref() was called.
+
+
+
+ %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.
+
+
+
+
+
+
+
+
+ An opaque structure used as the base of all classes.
+
+
+
+
+
+ Registers a private structure for an instantiatable type.
+
+When an object is allocated, the private structures for
+the type and all of its parent types are allocated
+sequentially in the same memory block as the public
+structures, and are zero-filled.
+
+Note that the accumulated size of the private structures of
+a type and all its parent types cannot exceed 64 KiB.
+
+This function should be called in the type's class_init() function.
+The private structure can be retrieved using the
+G_TYPE_INSTANCE_GET_PRIVATE() macro.
+
+The following example shows attaching a private structure
+MyObjectPrivate to an object MyObject defined in the standard
+GObject fashion in the type's class_init() function.
+
+Note the use of a structure member "priv" to avoid the overhead
+of repeatedly calling MY_OBJECT_GET_PRIVATE().
+
+|[<!-- language="C" -->
+typedef struct _MyObject MyObject;
+typedef struct _MyObjectPrivate MyObjectPrivate;
+
+struct _MyObject {
+ GObject parent;
+
+ MyObjectPrivate *priv;
+};
+
+struct _MyObjectPrivate {
+ int some_field;
+};
+
+static void
+my_object_class_init (MyObjectClass *klass)
+{
+ g_type_class_add_private (klass, sizeof (MyObjectPrivate));
+}
+
+static void
+my_object_init (MyObject *my_object)
+{
+ my_object->priv = G_TYPE_INSTANCE_GET_PRIVATE (my_object,
+ MY_TYPE_OBJECT,
+ MyObjectPrivate);
+ // my_object->priv->some_field will be automatically initialised to 0
+}
+
+static int
+my_object_get_some_field (MyObject *my_object)
+{
+ MyObjectPrivate *priv;
+
+ g_return_val_if_fail (MY_IS_OBJECT (my_object), 0);
+
+ priv = my_object->priv;
+
+ return priv->some_field;
+}
+]|
+ Use the G_ADD_PRIVATE() macro with the `G_DEFINE_*`
+ family of macros to add instance private data to a type
+
+
+
+
+
+
+ class structure for an instantiatable
+ type
+
+
+
+ size of private structure
+
+
+
+
+
+ Gets the offset of the private data for instances of @g_class.
+
+This is how many bytes you should add to the instance pointer of a
+class in order to get the private data for the type represented by
+@g_class.
+
+You can only call this function after you have registered a private
+data area for @g_class using g_type_class_add_private().
+
+
+ the offset, in bytes
+
+
+
+
+ a #GTypeClass
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This is a convenience function often needed in class initializers.
+It returns the class structure of the immediate parent type of the
+class passed in. Since derived classes hold a reference count on
+their parent classes as long as they are instantiated, the returned
+class will always exist.
+
+This function is essentially equivalent to:
+g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class)))
+
+
+ the parent class
+ of @g_class
+
+
+
+
+ the #GTypeClass structure to
+ retrieve the parent class for
+
+
+
+
+
+ Decrements the reference count of the class structure being passed in.
+Once the last reference count of a class has been released, classes
+may be finalized by the type system, so further dereferencing of a
+class pointer after g_type_class_unref() are invalid.
+
+
+
+
+
+
+ a #GTypeClass structure to unref
+
+
+
+
+
+ A variant of g_type_class_unref() for use in #GTypeClassCacheFunc
+implementations. It unreferences a class without consulting the chain
+of #GTypeClassCacheFuncs, avoiding the recursion which would occur
+otherwise.
+
+
+
+
+
+
+ a #GTypeClass structure to unref
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This function is essentially the same as g_type_class_ref(),
+except that the classes reference count isn't incremented.
+As a consequence, this function may return %NULL if the class
+of the type passed in does not currently exist (hasn't been
+referenced before).
+
+
+ the #GTypeClass
+ structure for the given type ID or %NULL if the class does not
+ currently exist
+
+
+
+
+ type ID of a classed type
+
+
+
+
+
+ A more efficient version of g_type_class_peek() which works only for
+static types.
+
+
+ the #GTypeClass
+ structure for the given type ID or %NULL if the class does not
+ currently exist or is dynamically loaded
+
+
+
+
+ type ID of a classed type
+
+
+
+
+
+ Increments the reference count of the class structure belonging to
+@type. This function will demand-create the class if it doesn't
+exist already.
+
+
+ the #GTypeClass
+ structure for the given type ID
+
+
+
+
+ type ID of a classed type
+
+
+
+
+
+
+ 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.
+
+
+ %TRUE to stop further #GTypeClassCacheFuncs from being
+ called, %FALSE to continue
+
+
+
+
+ data that was given to the g_type_add_class_cache_func() call
+
+
+
+ The #GTypeClass structure which is
+ unreferenced
+
+
+
+
+
+ These flags used to be passed to g_type_init_with_debug_flags() which
+is now deprecated.
+
+If you need to enable debugging features, use the GOBJECT_DEBUG
+environment variable.
+ g_type_init() is now done automatically
+
+
+ Print no messages
+
+
+ Print messages about object bookkeeping
+
+
+ Print messages about signal emissions
+
+
+ Keep a count of instances of each type
+
+
+ Mask covering all debug flags
+
+
+
+ Bit masks used to check or determine characteristics of a type.
+
+
+ No special flags. Since: 2.74
+
+
+ Indicates an abstract type. No instances can be
+ created for an abstract type
+
+
+ Indicates an abstract value type, i.e. a type
+ that introduces a value table, but can't be used for
+ g_value_init()
+
+
+ Indicates a final type. A final type is a non-derivable
+ leaf node in a deep derivable type hierarchy tree. Since: 2.70
+
+
+ The type is deprecated and may be removed in a
+ future version. A warning will be emitted if it is instantiated while
+ running with `G_ENABLE_DIAGNOSTIC=1`. Since 2.76
+
+
+
+ Bit masks used to check or determine specific characteristics of a
+fundamental type.
+
+
+ Indicates a classed type
+
+
+ Indicates an instantiatable type (implies classed)
+
+
+ Indicates a flat derivable type
+
+
+ Indicates a deep derivable type (implies derivable)
+
+
+
+ A structure that provides information to the type system which is
+used specifically for managing fundamental types.
+
+
+ #GTypeFundamentalFlags describing the characteristics of the fundamental type
+
+
+
+
+ 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().
+
+
+ Size of the class structure (required for interface, classed and instantiatable types)
+
+
+
+ Location of the base initialization function (optional)
+
+
+
+ Location of the base finalization function (optional)
+
+
+
+ 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.
+
+
+
+ Location of the class finalization function for
+ classed and instantiatable types. Location of the default vtable
+ finalization function for interface types. (optional)
+
+
+
+ User-supplied data passed to the class init/finalize functions
+
+
+
+ Size of the instance (object) structure (required for instantiatable types only)
+
+
+
+ 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 this field is ignored.
+
+
+
+ Location of the instance initialization function (optional, for instantiatable types only)
+
+
+
+ A #GTypeValueTable function table for generic handling of GValues
+ of this type (usually only useful for fundamental types)
+
+
+
+
+ An opaque structure used as the base of all type instances.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ An opaque structure used as the base of all interface types.
+
+
+
+
+
+
+
+
+ Returns the corresponding #GTypeInterface structure of the parent type
+of the instance type to which @g_iface belongs. This is useful when
+deriving the implementation of an interface from the parent type and
+then possibly overriding some methods.
+
+
+ the
+ corresponding #GTypeInterface structure of the parent type of the
+ instance type to which @g_iface belongs, or %NULL if the parent
+ type doesn't conform to the interface
+
+
+
+
+ a #GTypeInterface structure
+
+
+
+
+
+ Adds @prerequisite_type to the list of prerequisites of @interface_type.
+This means that any type implementing @interface_type must also implement
+@prerequisite_type. Prerequisites can be thought of as an alternative to
+interface derivation (which GType doesn't support). An interface can have
+at most one instantiatable prerequisite type.
+
+
+
+
+
+
+ #GType value of an interface type
+
+
+
+ #GType value of an interface or instantiatable type
+
+
+
+
+
+ Returns the #GTypePlugin structure for the dynamic interface
+@interface_type which has been added to @instance_type, or %NULL
+if @interface_type has not been added to @instance_type or does
+not have a #GTypePlugin structure. See g_type_add_interface_dynamic().
+
+
+ the #GTypePlugin for the dynamic
+ interface @interface_type of @instance_type
+
+
+
+
+ #GType of an instantiatable type
+
+
+
+ #GType of an interface type
+
+
+
+
+
+ Returns the most specific instantiatable prerequisite of an
+interface type. If the interface type has no instantiatable
+prerequisite, %G_TYPE_INVALID is returned.
+
+See g_type_interface_add_prerequisite() for more information
+about prerequisites.
+
+
+ the instantiatable prerequisite type or %G_TYPE_INVALID if none
+
+
+
+
+ an interface type
+
+
+
+
+
+ Returns the #GTypeInterface structure of an interface to which the
+passed in class conforms.
+
+
+ the #GTypeInterface
+ structure of @iface_type if implemented by @instance_class, %NULL
+ otherwise
+
+
+
+
+ a #GTypeClass structure
+
+
+
+ an interface ID which this class conforms to
+
+
+
+
+
+ Returns the prerequisites of an interfaces type.
+
+
+ a
+ newly-allocated zero-terminated array of #GType containing
+ the prerequisites of @interface_type
+
+
+
+
+
+
+ an interface type
+
+
+
+ location to return the number
+ of prerequisites, or %NULL
+
+
+
+
+
+
+ A callback called after an interface vtable is initialized.
+
+See g_type_add_interface_check().
+
+
+
+
+
+
+ data passed to g_type_add_interface_check()
+
+
+
+ the interface that has been
+ initialized
+
+
+
+
+
+ #GTypeModule provides a simple implementation of the #GTypePlugin
+interface.
+
+The model of #GTypeModule is a dynamically loaded module which
+implements some number of types and interface implementations.
+
+When the module is loaded, it registers its types and interfaces
+using g_type_module_register_type() and g_type_module_add_interface().
+As long as any instances of these 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
+reference cannot be released from within the 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
+using a use count - it starts at zero, and whenever it is greater than
+zero, the module is loaded. The use count is maintained internally by
+the type system, but also can be explicitly controlled by
+g_type_module_use() and g_type_module_unuse(). Typically, when loading
+a module for the first type, g_type_module_use() will be used to load
+it so that it can initialize its types. At some later point, when the
+module no longer needs to be loaded except for the type
+implementations it contains, g_type_module_unuse() is called.
+
+#GTypeModule does not actually provide any implementation of module
+loading and unloading. To create a particular module type you must
+derive from #GTypeModule and implement the load and unload functions
+in #GTypeModuleClass.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Registers an additional interface for a type, whose interface lives
+in the given type plugin. If the interface was already registered
+for the type in this plugin, nothing will be done.
+
+As long as any instances of the type exist, the type plugin will
+not be unloaded.
+
+Since 2.56 if @module is %NULL this will call g_type_add_interface_static()
+instead. This can be used when making a static build of the module.
+
+
+
+
+
+
+ a #GTypeModule
+
+
+
+ type to which to add the interface.
+
+
+
+ interface type to add
+
+
+
+ type information structure
+
+
+
+
+
+ Looks up or registers an enumeration that is implemented with a particular
+type plugin. If a type with name @type_name was previously registered,
+the #GType identifier for the type is returned, otherwise the type
+is newly registered, and the resulting #GType identifier returned.
+
+As long as any instances of the type exist, the type plugin will
+not be unloaded.
+
+Since 2.56 if @module is %NULL this will call g_type_register_static()
+instead. This can be used when making a static build of the module.
+
+
+ the new or existing type ID
+
+
+
+
+ a #GTypeModule
+
+
+
+ name for the type
+
+
+
+ an array of #GEnumValue structs for the
+ possible enumeration values. The array is
+ terminated by a struct with all members being
+ 0.
+
+
+
+
+
+ Looks up or registers a flags type that is implemented with a particular
+type plugin. If a type with name @type_name was previously registered,
+the #GType identifier for the type is returned, otherwise the type
+is newly registered, and the resulting #GType identifier returned.
+
+As long as any instances of the type exist, the type plugin will
+not be unloaded.
+
+Since 2.56 if @module is %NULL this will call g_type_register_static()
+instead. This can be used when making a static build of the module.
+
+
+ the new or existing type ID
+
+
+
+
+ a #GTypeModule
+
+
+
+ name for the type
+
+
+
+ an array of #GFlagsValue structs for the
+ possible flags values. The array is
+ terminated by a struct with all members being
+ 0.
+
+
+
+
+
+ Looks up or registers a type that is implemented with a particular
+type plugin. If a type with name @type_name was previously registered,
+the #GType identifier for the type is returned, otherwise the type
+is newly registered, and the resulting #GType identifier returned.
+
+When reregistering a type (typically because a module is unloaded
+then reloaded, and reinitialized), @module and @parent_type must
+be the same as they were previously.
+
+As long as any instances of the type exist, the type plugin will
+not be unloaded.
+
+Since 2.56 if @module is %NULL this will call g_type_register_static()
+instead. This can be used when making a static build of the module.
+
+
+ the new or existing type ID
+
+
+
+
+ a #GTypeModule
+
+
+
+ the type for the parent class
+
+
+
+ name for the type
+
+
+
+ type information structure
+
+
+
+ flags field providing details about the type
+
+
+
+
+
+ Sets the name for a #GTypeModule
+
+
+
+
+
+
+ a #GTypeModule.
+
+
+
+ a human-readable name to use in error messages.
+
+
+
+
+
+ Decreases the use count of a #GTypeModule by one. If the
+result is zero, the module will be unloaded. (However, the
+#GTypeModule will not be freed, and types associated with the
+#GTypeModule are not unregistered. Once a #GTypeModule is
+initialized, it must exist forever.)
+
+
+
+
+
+
+ a #GTypeModule
+
+
+
+
+
+ Increases the use count of a #GTypeModule by one. If the
+use count was zero before, the plugin will be loaded.
+If loading the plugin fails, the use count is reset to
+its prior value.
+
+
+ %FALSE if the plugin needed to be loaded and
+ loading the plugin failed.
+
+
+
+
+ a #GTypeModule
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ the name of the module
+
+
+
+
+ In order to implement dynamic loading of types based on #GTypeModule,
+the @load and @unload functions in #GTypeModuleClass must be implemented.
+
+
+ the parent class
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ An interface that handles the lifecycle of dynamically loaded types.
+
+The GObject type system supports dynamic loading of types.
+It goes as follows:
+
+1. The type is initially introduced (usually upon loading the module
+ the first time, or by your main application that knows what modules
+ introduces what types), like this:
+ |[<!-- language="C" -->
+ new_type_id = g_type_register_dynamic (parent_type_id,
+ "TypeName",
+ new_type_plugin,
+ type_flags);
+ ]|
+ where @new_type_plugin is an implementation of the
+ #GTypePlugin interface.
+
+2. The type's implementation is referenced, e.g. through
+ g_type_class_ref() or through g_type_create_instance() (this is
+ being called by g_object_new()) or through one of the above done on
+ a type derived from @new_type_id.
+
+3. This causes the type system to load the type's implementation by
+ calling g_type_plugin_use() and g_type_plugin_complete_type_info()
+ on @new_type_plugin.
+
+4. At some point the type's implementation isn't required anymore,
+ e.g. after g_type_class_unref() or g_type_free_instance() (called
+ when the reference count of an instance drops to zero).
+
+5. This causes the type system to throw away the information retrieved
+ from g_type_plugin_complete_type_info() and then it calls
+ g_type_plugin_unuse() on @new_type_plugin.
+
+6. Things may repeat from the second step.
+
+So basically, you need to implement a #GTypePlugin type that
+carries a use_count, once use_count goes from zero to one, you need
+to load the implementation to successfully handle the upcoming
+g_type_plugin_complete_type_info() call. Later, maybe after
+succeeding use/unuse calls, once use_count drops to zero, you can
+unload the implementation again. The type system makes sure to call
+g_type_plugin_use() and g_type_plugin_complete_type_info() again
+when the type is needed again.
+
+#GTypeModule is an implementation of #GTypePlugin that already
+implements most of this except for the actual module loading and
+unloading. It even handles multiple registered types per module.
+
+ Calls the @complete_interface_info function from the
+#GTypePluginClass of @plugin. There should be no need to use this
+function outside of the GObject type system itself.
+
+
+
+
+
+
+ the #GTypePlugin
+
+
+
+ the #GType of an instantiatable type to which the interface
+ is added
+
+
+
+ the #GType of the interface whose info is completed
+
+
+
+ the #GInterfaceInfo to fill in
+
+
+
+
+
+ Calls the @complete_type_info function from the #GTypePluginClass of @plugin.
+There should be no need to use this function outside of the GObject
+type system itself.
+
+
+
+
+
+
+ a #GTypePlugin
+
+
+
+ the #GType whose info is completed
+
+
+
+ the #GTypeInfo struct to fill in
+
+
+
+ the #GTypeValueTable to fill in
+
+
+
+
+
+ Calls the @unuse_plugin function from the #GTypePluginClass of
+@plugin. There should be no need to use this function outside of
+the GObject type system itself.
+
+
+
+
+
+
+ a #GTypePlugin
+
+
+
+
+
+ Calls the @use_plugin function from the #GTypePluginClass of
+@plugin. There should be no need to use this function outside of
+the GObject type system itself.
+
+
+
+
+
+
+ a #GTypePlugin
+
+
+
+
+
+
+ The #GTypePlugin interface is used by the type system in order to handle
+the lifecycle of dynamically loaded types.
+
+
+
+
+
+ Increases the use count of the plugin.
+
+
+
+ Decreases the use count of the plugin.
+
+
+
+ Fills in the #GTypeInfo and
+ #GTypeValueTable structs for the type. The structs are initialized
+ with `memset(s, 0, sizeof (s))` before calling this function.
+
+
+
+ Fills in missing parts of the #GInterfaceInfo
+ for the interface. The structs is initialized with
+ `memset(s, 0, sizeof (s))` before calling this function.
+
+
+
+
+ The type of the @complete_interface_info function of #GTypePluginClass.
+
+
+
+
+
+
+ the #GTypePlugin
+
+
+
+ the #GType of an instantiatable type to which the interface
+ is added
+
+
+
+ the #GType of the interface whose info is completed
+
+
+
+ the #GInterfaceInfo to fill in
+
+
+
+
+
+ The type of the @complete_type_info function of #GTypePluginClass.
+
+
+
+
+
+
+ the #GTypePlugin
+
+
+
+ the #GType whose info is completed
+
+
+
+ the #GTypeInfo struct to fill in
+
+
+
+ the #GTypeValueTable to fill in
+
+
+
+
+
+ The type of the @unuse_plugin function of #GTypePluginClass.
+
+
+
+
+
+
+ the #GTypePlugin whose use count should be decreased
+
+
+
+
+
+ The type of the @use_plugin function of #GTypePluginClass, which gets called
+to increase the use count of @plugin.
+
+
+
+
+
+
+ the #GTypePlugin whose use count should be increased
+
+
+
+
+
+ A structure holding information for a specific type.
+
+See also: g_type_query()
+
+
+ the #GType value of the type
+
+
+
+ the name of the type
+
+
+
+ the size of the class structure
+
+
+
+ the size of the instance structure
+
+
+
+
+ The #GTypeValueTable provides the functions required by the #GValue
+implementation, to serve as a container for values of a type.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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:
+ - 'i' - Integers. passed as collect_values[].v_int.
+ - 'l' - Longs. passed as collect_values[].v_long.
+ - 'd' - Doubles. passed as collect_values[].v_double.
+ - 'p' - Pointers. passed as collect_values[].v_pointer.
+ 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'.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Returns the location of the #GTypeValueTable associated with @type.
+
+Note that this function should only be used from source code
+that implements or has internal knowledge of the implementation of
+@type.
+
+
+ location of the #GTypeValueTable associated with @type or
+ %NULL if there is no #GTypeValueTable associated with @type
+
+
+
+
+ a #GType
+
+
+
+
+
+
+ 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.
+
+
+
+ A #GValue structure.
+
+
+ A #GType value.
+
+
+
+
+ Checks whether the given #GValue can hold values of type %G_TYPE_BOOLEAN.
+
+
+
+ a valid #GValue structure
+
+
+
+
+ Checks whether the given #GValue can hold values derived
+from type %G_TYPE_BOXED.
+
+
+
+ a valid #GValue structure
+
+
+
+
+ Checks whether the given #GValue can hold values of type %G_TYPE_CHAR.
+
+
+
+ a valid #GValue structure
+
+
+
+
+ Checks whether the given #GValue can hold values of type %G_TYPE_DOUBLE.
+
+
+
+ a valid #GValue structure
+
+
+
+
+ Checks whether the given #GValue can hold values derived from type %G_TYPE_ENUM.
+
+
+
+ a valid #GValue structure
+
+
+
+
+ Checks whether the given #GValue can hold values derived from type %G_TYPE_FLAGS.
+
+
+
+ a valid #GValue structure
+
+
+
+
+ Checks whether the given #GValue can hold values of type %G_TYPE_FLOAT.
+
+
+
+ a valid #GValue structure
+
+
+
+
+ Checks whether the given #GValue can hold values of type %G_TYPE_GTYPE.
+
+
+
+ a valid #GValue structure
+
+
+
+
+ Checks whether the given #GValue can hold values of type %G_TYPE_INT.
+
+
+
+ a valid #GValue structure
+
+
+
+
+ Checks whether the given #GValue can hold values of type %G_TYPE_INT64.
+
+
+
+ a valid #GValue structure
+
+
+
+
+ Checks whether the given #GValue can hold values of type %G_TYPE_LONG.
+
+
+
+ a valid #GValue structure
+
+
+
+
+ Checks whether the given #GValue can hold values derived from type %G_TYPE_OBJECT.
+
+
+
+ a valid #GValue structure
+
+
+
+
+ Checks whether the given #GValue can hold values derived from type %G_TYPE_PARAM.
+
+
+
+ a valid #GValue structure
+
+
+
+
+ Checks whether the given #GValue can hold values of type %G_TYPE_POINTER.
+
+
+
+ a valid #GValue structure
+
+
+
+
+ Checks whether the given #GValue can hold values of type %G_TYPE_STRING.
+
+
+
+ a valid #GValue structure
+
+
+
+
+ Checks whether the given #GValue can hold values of type %G_TYPE_UCHAR.
+
+
+
+ a valid #GValue structure
+
+
+
+
+ Checks whether the given #GValue can hold values of type %G_TYPE_UINT.
+
+
+
+ a valid #GValue structure
+
+
+
+
+ Checks whether the given #GValue can hold values of type %G_TYPE_UINT64.
+
+
+
+ a valid #GValue structure
+
+
+
+
+ Checks whether the given #GValue can hold values of type %G_TYPE_ULONG.
+
+
+
+ a valid #GValue structure
+
+
+
+
+ Checks whether the given #GValue can hold values of type %G_TYPE_VARIANT.
+
+
+
+ a valid #GValue structure
+
+
+
+
+ For string values, indicates that the string contained is canonical and will
+exist for the duration of the process. See g_value_set_interned_string().
+
+
+
+
+ Checks whether @value contains a string which is canonical.
+
+
+
+ a valid #GValue structure
+
+
+
+
+ If passed to G_VALUE_COLLECT(), allocated data won't be copied
+but used verbatim. This does not affect ref-counted types like
+objects. This does not affect usage of g_value_copy(), the data will
+be copied if it is not ref-counted.
+
+
+
+
+ Get the type identifier of @value.
+
+
+
+ A #GValue structure.
+
+
+
+
+ Gets the type name of @value.
+
+
+
+ A #GValue structure.
+
+
+
+
+ This is the signature of va_list marshaller functions, an optional
+marshaller that can be used in some situations to avoid
+marshalling the signal argument into GValues.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ a #GValue to store the return
+ value. May be %NULL if the callback of @closure doesn't return a
+ value.
+
+
+
+ the instance on which the closure is
+ invoked.
+
+
+
+ va_list of arguments to be passed to the closure.
+
+
+
+ additional data specified when
+ registering the marshaller, see g_closure_set_marshal() and
+ g_closure_set_meta_marshal()
+
+
+
+ the length of the @param_types array
+
+
+
+ the #GType of each argument from
+ @args.
+
+
+
+
+
+
+
+ An opaque structure used to hold different types of values.
+
+The data within the structure has protected scope: it is accessible only
+to functions within a #GTypeValueTable structure, or implementations of
+the g_value_*() API. That is, code portions which implement new fundamental
+types.
+
+#GValue users cannot make any assumptions about how data is stored
+within the 2 element @data union, and the @g_type member should
+only be accessed through the G_VALUE_TYPE() macro.
+
+
+
+
+
+
+
+
+
+
+ Copies the value of @src_value into @dest_value.
+
+
+
+
+
+
+ An initialized #GValue structure.
+
+
+
+ An initialized #GValue structure of the same type as @src_value.
+
+
+
+
+
+ Get the contents of a %G_TYPE_BOXED derived #GValue. Upon getting,
+the boxed value is duplicated and needs to be later freed with
+g_boxed_free(), e.g. like: g_boxed_free (G_VALUE_TYPE (@value),
+return_value);
+
+
+ boxed contents of @value
+
+
+
+
+ a valid #GValue of %G_TYPE_BOXED derived type
+
+
+
+
+
+ Get the contents of a %G_TYPE_OBJECT derived #GValue, increasing
+its reference count. If the contents of the #GValue are %NULL, then
+%NULL will be returned.
+
+
+ object content of @value,
+ should be unreferenced when no longer needed.
+
+
+
+
+ a valid #GValue whose type is derived from %G_TYPE_OBJECT
+
+
+
+
+
+ Get the contents of a %G_TYPE_PARAM #GValue, increasing its
+reference count.
+
+
+ #GParamSpec content of @value, should be
+ unreferenced when no longer needed.
+
+
+
+
+ a valid #GValue whose type is derived from %G_TYPE_PARAM
+
+
+
+
+
+ Get a copy the contents of a %G_TYPE_STRING #GValue.
+
+
+ a newly allocated copy of the string content of @value
+
+
+
+
+ a valid #GValue of type %G_TYPE_STRING
+
+
+
+
+
+ Get the contents of a variant #GValue, increasing its refcount. The returned
+#GVariant is never floating.
+
+
+ variant contents of @value (may be %NULL);
+ should be unreffed using g_variant_unref() when no longer needed
+
+
+
+
+ a valid #GValue of type %G_TYPE_VARIANT
+
+
+
+
+
+ Determines if @value will fit inside the size of a pointer value.
+This is an internal function introduced mainly for C marshallers.
+
+
+ %TRUE if @value will fit inside a pointer value.
+
+
+
+
+ An initialized #GValue structure.
+
+
+
+
+
+ Get the contents of a %G_TYPE_BOOLEAN #GValue.
+
+
+ boolean contents of @value
+
+
+
+
+ a valid #GValue of type %G_TYPE_BOOLEAN
+
+
+
+
+
+ Get the contents of a %G_TYPE_BOXED derived #GValue.
+
+
+ boxed contents of @value
+
+
+
+
+ a valid #GValue of %G_TYPE_BOXED derived type
+
+
+
+
+
+ Do not use this function; it is broken on platforms where the %char
+type is unsigned, such as ARM and PowerPC. See g_value_get_schar().
+
+Get the contents of a %G_TYPE_CHAR #GValue.
+ This function's return type is broken, see g_value_get_schar()
+
+
+ character contents of @value
+
+
+
+
+ a valid #GValue of type %G_TYPE_CHAR
+
+
+
+
+
+ Get the contents of a %G_TYPE_DOUBLE #GValue.
+
+
+ double contents of @value
+
+
+
+
+ a valid #GValue of type %G_TYPE_DOUBLE
+
+
+
+
+
+ Get the contents of a %G_TYPE_ENUM #GValue.
+
+
+ enum contents of @value
+
+
+
+
+ a valid #GValue whose type is derived from %G_TYPE_ENUM
+
+
+
+
+
+ Get the contents of a %G_TYPE_FLAGS #GValue.
+
+
+ flags contents of @value
+
+
+
+
+ a valid #GValue whose type is derived from %G_TYPE_FLAGS
+
+
+
+
+
+ Get the contents of a %G_TYPE_FLOAT #GValue.
+
+
+ float contents of @value
+
+
+
+
+ a valid #GValue of type %G_TYPE_FLOAT
+
+
+
+
+
+ Get the contents of a %G_TYPE_GTYPE #GValue.
+
+
+ the #GType stored in @value
+
+
+
+
+ a valid #GValue of type %G_TYPE_GTYPE
+
+
+
+
+
+ Get the contents of a %G_TYPE_INT #GValue.
+
+
+ integer contents of @value
+
+
+
+
+ a valid #GValue of type %G_TYPE_INT
+
+
+
+
+
+ Get the contents of a %G_TYPE_INT64 #GValue.
+
+
+ 64bit integer contents of @value
+
+
+
+
+ a valid #GValue of type %G_TYPE_INT64
+
+
+
+
+
+ Get the contents of a %G_TYPE_LONG #GValue.
+
+
+ long integer contents of @value
+
+
+
+
+ a valid #GValue of type %G_TYPE_LONG
+
+
+
+
+
+ Get the contents of a %G_TYPE_OBJECT derived #GValue.
+
+
+ object contents of @value
+
+
+
+
+ a valid #GValue of %G_TYPE_OBJECT derived type
+
+
+
+
+
+ Get the contents of a %G_TYPE_PARAM #GValue.
+
+
+ #GParamSpec content of @value
+
+
+
+
+ a valid #GValue whose type is derived from %G_TYPE_PARAM
+
+
+
+
+
+ Get the contents of a pointer #GValue.
+
+
+ pointer contents of @value
+
+
+
+
+ a valid #GValue of %G_TYPE_POINTER
+
+
+
+
+
+ Get the contents of a %G_TYPE_CHAR #GValue.
+
+
+ signed 8 bit integer contents of @value
+
+
+
+
+ a valid #GValue of type %G_TYPE_CHAR
+
+
+
+
+
+ Get the contents of a %G_TYPE_STRING #GValue.
+
+
+ string content of @value
+
+
+
+
+ a valid #GValue of type %G_TYPE_STRING
+
+
+
+
+
+ Get the contents of a %G_TYPE_UCHAR #GValue.
+
+
+ unsigned character contents of @value
+
+
+
+
+ a valid #GValue of type %G_TYPE_UCHAR
+
+
+
+
+
+ Get the contents of a %G_TYPE_UINT #GValue.
+
+
+ unsigned integer contents of @value
+
+
+
+
+ a valid #GValue of type %G_TYPE_UINT
+
+
+
+
+
+ Get the contents of a %G_TYPE_UINT64 #GValue.
+
+
+ unsigned 64bit integer contents of @value
+
+
+
+
+ a valid #GValue of type %G_TYPE_UINT64
+
+
+
+
+
+ Get the contents of a %G_TYPE_ULONG #GValue.
+
+
+ unsigned long integer contents of @value
+
+
+
+
+ a valid #GValue of type %G_TYPE_ULONG
+
+
+
+
+
+ Get the contents of a variant #GValue.
+
+
+ variant contents of @value (may be %NULL)
+
+
+
+
+ a valid #GValue of type %G_TYPE_VARIANT
+
+
+
+
+
+ Initializes @value with the default value of @type.
+
+
+ the #GValue structure that has been passed in
+
+
+
+
+ A zero-filled (uninitialized) #GValue structure.
+
+
+
+ Type the #GValue should hold values of.
+
+
+
+
+
+ Initializes and sets @value from an instantiatable type via the
+value_table's collect_value() function.
+
+Note: The @value will be initialised with the exact type of
+@instance. If you wish to set the @value's type to a different GType
+(such as a parent class GType), you need to manually call
+g_value_init() and g_value_set_instance().
+
+
+
+
+
+
+ An uninitialized #GValue structure.
+
+
+
+ the instance
+
+
+
+
+
+ Returns the value contents as pointer. This function asserts that
+g_value_fits_pointer() returned %TRUE for the passed in value.
+This is an internal function introduced mainly for C marshallers.
+
+
+ the value contents as pointer
+
+
+
+
+ An initialized #GValue structure
+
+
+
+
+
+ Clears the current value in @value and resets it to the default value
+(as if the value had just been initialized).
+
+
+ the #GValue structure that has been passed in
+
+
+
+
+ An initialized #GValue structure.
+
+
+
+
+
+ Set the contents of a %G_TYPE_BOOLEAN #GValue to @v_boolean.
+
+
+
+
+
+
+ a valid #GValue of type %G_TYPE_BOOLEAN
+
+
+
+ boolean value to be set
+
+
+
+
+
+ Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed.
+
+
+
+
+
+
+ a valid #GValue of %G_TYPE_BOXED derived type
+
+
+
+ boxed value to be set
+
+
+
+
+
+ This is an internal function introduced mainly for C marshallers.
+ Use g_value_take_boxed() instead.
+
+
+
+
+
+
+ a valid #GValue of %G_TYPE_BOXED derived type
+
+
+
+ duplicated unowned boxed value to be set
+
+
+
+
+
+ Set the contents of a %G_TYPE_CHAR #GValue to @v_char.
+ This function's input type is broken, see g_value_set_schar()
+
+
+
+
+
+
+ a valid #GValue of type %G_TYPE_CHAR
+
+
+
+ character value to be set
+
+
+
+
+
+ Set the contents of a %G_TYPE_DOUBLE #GValue to @v_double.
+
+
+
+
+
+
+ a valid #GValue of type %G_TYPE_DOUBLE
+
+
+
+ double value to be set
+
+
+
+
+
+ Set the contents of a %G_TYPE_ENUM #GValue to @v_enum.
+
+
+
+
+
+
+ a valid #GValue whose type is derived from %G_TYPE_ENUM
+
+
+
+ enum value to be set
+
+
+
+
+
+ Set the contents of a %G_TYPE_FLAGS #GValue to @v_flags.
+
+
+
+
+
+
+ a valid #GValue whose type is derived from %G_TYPE_FLAGS
+
+
+
+ flags value to be set
+
+
+
+
+
+ Set the contents of a %G_TYPE_FLOAT #GValue to @v_float.
+
+
+
+
+
+
+ a valid #GValue of type %G_TYPE_FLOAT
+
+
+
+ float value to be set
+
+
+
+
+
+ Set the contents of a %G_TYPE_GTYPE #GValue to @v_gtype.
+
+
+
+
+
+
+ a valid #GValue of type %G_TYPE_GTYPE
+
+
+
+ #GType to be set
+
+
+
+
+
+ Sets @value from an instantiatable type via the
+value_table's collect_value() function.
+
+
+
+
+
+
+ An initialized #GValue structure.
+
+
+
+ the instance
+
+
+
+
+
+ Set the contents of a %G_TYPE_INT #GValue to @v_int.
+
+
+
+
+
+
+ a valid #GValue of type %G_TYPE_INT
+
+
+
+ integer value to be set
+
+
+
+
+
+ Set the contents of a %G_TYPE_INT64 #GValue to @v_int64.
+
+
+
+
+
+
+ a valid #GValue of type %G_TYPE_INT64
+
+
+
+ 64bit integer value to be set
+
+
+
+
+
+ Set the contents of a %G_TYPE_STRING #GValue to @v_string. The string is
+assumed to be static and interned (canonical, for example from
+g_intern_string()), and is thus not duplicated when setting the #GValue.
+
+
+
+
+
+
+ a valid #GValue of type %G_TYPE_STRING
+
+
+
+ static string to be set
+
+
+
+
+
+ Set the contents of a %G_TYPE_LONG #GValue to @v_long.
+
+
+
+
+
+
+ a valid #GValue of type %G_TYPE_LONG
+
+
+
+ long integer value to be set
+
+
+
+
+
+ Set the contents of a %G_TYPE_OBJECT derived #GValue to @v_object.
+
+g_value_set_object() increases the reference count of @v_object
+(the #GValue holds a reference to @v_object). If you do not wish
+to increase the reference count of the object (i.e. you wish to
+pass your current reference to the #GValue because you no longer
+need it), use g_value_take_object() instead.
+
+It is important that your #GValue holds a reference to @v_object (either its
+own, or one it has taken) to ensure that the object won't be destroyed while
+the #GValue still exists).
+
+
+
+
+
+
+ a valid #GValue of %G_TYPE_OBJECT derived type
+
+
+
+ object value to be set
+
+
+
+
+
+ This is an internal function introduced mainly for C marshallers.
+ Use g_value_take_object() instead.
+
+
+
+
+
+
+ a valid #GValue of %G_TYPE_OBJECT derived type
+
+
+
+ object value to be set
+
+
+
+
+
+ Set the contents of a %G_TYPE_PARAM #GValue to @param.
+
+
+
+
+
+
+ a valid #GValue of type %G_TYPE_PARAM
+
+
+
+ the #GParamSpec to be set
+
+
+
+
+
+ This is an internal function introduced mainly for C marshallers.
+ Use g_value_take_param() instead.
+
+
+
+
+
+
+ a valid #GValue of type %G_TYPE_PARAM
+
+
+
+ the #GParamSpec to be set
+
+
+
+
+
+ Set the contents of a pointer #GValue to @v_pointer.
+
+
+
+
+
+
+ a valid #GValue of %G_TYPE_POINTER
+
+
+
+ pointer value to be set
+
+
+
+
+
+ Set the contents of a %G_TYPE_CHAR #GValue to @v_char.
+
+
+
+
+
+
+ a valid #GValue of type %G_TYPE_CHAR
+
+
+
+ signed 8 bit integer to be set
+
+
+
+
+
+ Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed.
+
+The boxed value is assumed to be static, and is thus not duplicated
+when setting the #GValue.
+
+
+
+
+
+
+ a valid #GValue of %G_TYPE_BOXED derived type
+
+
+
+ static boxed value to be set
+
+
+
+
+
+ Set the contents of a %G_TYPE_STRING #GValue to @v_string.
+The string is assumed to be static, and is thus not duplicated
+when setting the #GValue.
+
+If the the string is a canonical string, using g_value_set_interned_string()
+is more appropriate.
+
+
+
+
+
+
+ a valid #GValue of type %G_TYPE_STRING
+
+
+
+ static string to be set
+
+
+
+
+
+ Set the contents of a %G_TYPE_STRING #GValue to a copy of @v_string.
+
+
+
+
+
+
+ a valid #GValue of type %G_TYPE_STRING
+
+
+
+ caller-owned string to be duplicated for the #GValue
+
+
+
+
+
+ This is an internal function introduced mainly for C marshallers.
+ Use g_value_take_string() instead.
+
+
+
+
+
+
+ a valid #GValue of type %G_TYPE_STRING
+
+
+
+ duplicated unowned string to be set
+
+
+
+
+
+ Set the contents of a %G_TYPE_UCHAR #GValue to @v_uchar.
+
+
+
+
+
+
+ a valid #GValue of type %G_TYPE_UCHAR
+
+
+
+ unsigned character value to be set
+
+
+
+
+
+ Set the contents of a %G_TYPE_UINT #GValue to @v_uint.
+
+
+
+
+
+
+ a valid #GValue of type %G_TYPE_UINT
+
+
+
+ unsigned integer value to be set
+
+
+
+
+
+ Set the contents of a %G_TYPE_UINT64 #GValue to @v_uint64.
+
+
+
+
+
+
+ a valid #GValue of type %G_TYPE_UINT64
+
+
+
+ unsigned 64bit integer value to be set
+
+
+
+
+
+ Set the contents of a %G_TYPE_ULONG #GValue to @v_ulong.
+
+
+
+
+
+
+ a valid #GValue of type %G_TYPE_ULONG
+
+
+
+ unsigned long integer value to be set
+
+
+
+
+
+ Set the contents of a variant #GValue to @variant.
+If the variant is floating, it is consumed.
+
+
+
+
+
+
+ a valid #GValue of type %G_TYPE_VARIANT
+
+
+
+ a #GVariant, or %NULL
+
+
+
+
+
+ Sets the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed
+and takes over the ownership of the caller’s reference to @v_boxed;
+the caller doesn’t have to unref it any more.
+
+
+
+
+
+
+ a valid #GValue of %G_TYPE_BOXED derived type
+
+
+
+ duplicated unowned boxed value to be set
+
+
+
+
+
+ Sets the contents of a %G_TYPE_OBJECT derived #GValue to @v_object
+and takes over the ownership of the caller’s reference to @v_object;
+the caller doesn’t have to unref it any more (i.e. the reference
+count of the object is not increased).
+
+If you want the #GValue to hold its own reference to @v_object, use
+g_value_set_object() instead.
+
+
+
+
+
+
+ a valid #GValue of %G_TYPE_OBJECT derived type
+
+
+
+ object value to be set
+
+
+
+
+
+ Sets the contents of a %G_TYPE_PARAM #GValue to @param and takes
+over the ownership of the caller’s reference to @param; the caller
+doesn’t have to unref it any more.
+
+
+
+
+
+
+ a valid #GValue of type %G_TYPE_PARAM
+
+
+
+ the #GParamSpec to be set
+
+
+
+
+
+ Sets the contents of a %G_TYPE_STRING #GValue to @v_string.
+
+
+
+
+
+
+ a valid #GValue of type %G_TYPE_STRING
+
+
+
+ string to take ownership of
+
+
+
+
+
+ Set the contents of a variant #GValue to @variant, and takes over
+the ownership of the caller's reference to @variant;
+the caller doesn't have to unref it any more (i.e. the reference
+count of the variant is not increased).
+
+If @variant was floating then its floating reference is converted to
+a hard reference.
+
+If you want the #GValue to hold its own reference to @variant, use
+g_value_set_variant() instead.
+
+This is an internal function introduced mainly for C marshallers.
+
+
+
+
+
+
+ a valid #GValue of type %G_TYPE_VARIANT
+
+
+
+ a #GVariant, or %NULL
+
+
+
+
+
+ Tries to cast the contents of @src_value into a type appropriate
+to store in @dest_value, e.g. to transform a %G_TYPE_INT value
+into a %G_TYPE_FLOAT value. Performing transformations between
+value types might incur precision lossage. Especially
+transformations into strings might reveal seemingly arbitrary
+results and shouldn't be relied upon for production code (such
+as rcfile value or object property serialization).
+
+
+ Whether a transformation rule was found and could be applied.
+ Upon failing transformations, @dest_value is left untouched.
+
+
+
+
+ Source value.
+
+
+
+ Target value.
+
+
+
+
+
+ Clears the current value in @value (if any) and "unsets" the type,
+this releases all resources associated with this GValue. An unset
+value is the same as an uninitialized (zero-filled) #GValue
+structure.
+
+
+
+
+
+
+ An initialized #GValue structure.
+
+
+
+
+
+ Registers a value transformation function for use in g_value_transform().
+A previously registered transformation function for @src_type and @dest_type
+will be replaced.
+
+
+
+
+
+
+ Source type.
+
+
+
+ Target type.
+
+
+
+ a function which transforms values of type @src_type
+ into value of type @dest_type
+
+
+
+
+
+ Returns whether a #GValue of type @src_type can be copied into
+a #GValue of type @dest_type.
+
+
+ %TRUE if g_value_copy() is possible with @src_type and @dest_type.
+
+
+
+
+ source type to be copied.
+
+
+
+ destination type for copying.
+
+
+
+
+
+ Check whether g_value_transform() is able to transform values
+of type @src_type into values of type @dest_type. Note that for
+the types to be transformable, they must be compatible or a
+transformation function must be registered.
+
+
+ %TRUE if the transformation is possible, %FALSE otherwise.
+
+
+
+
+ Source type.
+
+
+
+ Target type.
+
+
+
+
+
+
+ A #GValueArray contains an array of #GValue elements.
+
+
+ number of values contained in the array
+
+
+
+ array of values
+
+
+
+
+
+
+ Allocate and initialize a new #GValueArray, optionally preserve space
+for @n_prealloced elements. New arrays always contain 0 elements,
+regardless of the value of @n_prealloced.
+ Use #GArray and g_array_sized_new() instead.
+
+
+ a newly allocated #GValueArray with 0 values
+
+
+
+
+ number of values to preallocate space for
+
+
+
+
+
+ Insert a copy of @value as last element of @value_array. If @value is
+%NULL, an uninitialized value is appended.
+ Use #GArray and g_array_append_val() instead.
+
+
+ the #GValueArray passed in as @value_array
+
+
+
+
+ #GValueArray to add an element to
+
+
+
+ #GValue to copy into #GValueArray, or %NULL
+
+
+
+
+
+ Construct an exact copy of a #GValueArray by duplicating all its
+contents.
+ Use #GArray and g_array_ref() instead.
+
+
+ Newly allocated copy of #GValueArray
+
+
+
+
+ #GValueArray to copy
+
+
+
+
+
+ Free a #GValueArray including its contents.
+ Use #GArray and g_array_unref() instead.
+
+
+
+
+
+
+ #GValueArray to free
+
+
+
+
+
+ Return a pointer to the value at @index_ containd in @value_array.
+ Use g_array_index() instead.
+
+
+ pointer to a value at @index_ in @value_array
+
+
+
+
+ #GValueArray to get a value from
+
+
+
+ index of the value of interest
+
+
+
+
+
+ Insert a copy of @value at specified position into @value_array. If @value
+is %NULL, an uninitialized value is inserted.
+ Use #GArray and g_array_insert_val() instead.
+
+
+ the #GValueArray passed in as @value_array
+
+
+
+
+ #GValueArray to add an element to
+
+
+
+ insertion position, must be <= value_array->;n_values
+
+
+
+ #GValue to copy into #GValueArray, or %NULL
+
+
+
+
+
+ Insert a copy of @value as first element of @value_array. If @value is
+%NULL, an uninitialized value is prepended.
+ Use #GArray and g_array_prepend_val() instead.
+
+
+ the #GValueArray passed in as @value_array
+
+
+
+
+ #GValueArray to add an element to
+
+
+
+ #GValue to copy into #GValueArray, or %NULL
+
+
+
+
+
+ Remove the value at position @index_ from @value_array.
+ Use #GArray and g_array_remove_index() instead.
+
+
+ the #GValueArray passed in as @value_array
+
+
+
+
+ #GValueArray to remove an element from
+
+
+
+ position of value to remove, which must be less than
+ @value_array->n_values
+
+
+
+
+
+ Sort @value_array using @compare_func to compare the elements according to
+the semantics of #GCompareFunc.
+
+The current implementation uses the same sorting algorithm as standard
+C qsort() function.
+ Use #GArray and g_array_sort().
+
+
+ the #GValueArray passed in as @value_array
+
+
+
+
+ #GValueArray to sort
+
+
+
+ function to compare elements
+
+
+
+
+
+ Sort @value_array using @compare_func to compare the elements according
+to the semantics of #GCompareDataFunc.
+
+The current implementation uses the same sorting algorithm as standard
+C qsort() function.
+ Use #GArray and g_array_sort_with_data().
+
+
+ the #GValueArray passed in as @value_array
+
+
+
+
+ #GValueArray to sort
+
+
+
+ function to compare elements
+
+
+
+ extra data argument provided for @compare_func
+
+
+
+
+
+
+ The type of value transformation functions which can be registered with
+g_value_register_transform_func().
+
+@dest_value will be initialized to the correct destination type.
+
+
+
+
+
+
+ Source value.
+
+
+
+ Target value.
+
+
+
+
+
+ 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 disposed when the #GWeakNotify is called,
+there's not much you could do with the object, apart from e.g. using its
+address as hash-index or the like.
+
+In particular, this means it’s invalid to call g_object_ref(),
+g_weak_ref_init(), g_weak_ref_set(), g_object_add_toggle_ref(),
+g_object_weak_ref(), g_object_add_weak_pointer() or any function which calls
+them on the object from this callback.
+
+
+
+
+
+
+ data that was provided when the weak reference was established
+
+
+
+ the object being disposed
+
+
+
+
+
+ A structure containing a weak reference to a #GObject.
+
+A `GWeakRef` can either be empty (i.e. point to %NULL), or point to an
+object for as long as at least one "strong" reference to that object
+exists. Before the object's #GObjectClass.dispose method is called,
+every #GWeakRef associated with becomes empty (i.e. points to %NULL).
+
+Like #GValue, #GWeakRef can be statically allocated, stack- or
+heap-allocated, or embedded in larger structures.
+
+Unlike g_object_weak_ref() and g_object_add_weak_pointer(), this weak
+reference is thread-safe: converting a weak pointer to a reference is
+atomic with respect to invalidation of weak pointers to destroyed
+objects.
+
+If the object's #GObjectClass.dispose method results in additional
+references to the object being held (‘re-referencing’), any #GWeakRefs taken
+before it was disposed will continue to point to %NULL. Any #GWeakRefs taken
+during disposal and after re-referencing, or after disposal has returned due
+to the re-referencing, will continue to point to the object until its refcount
+goes back to zero, at which point they too will be invalidated.
+
+It is invalid to take a #GWeakRef on an object during #GObjectClass.dispose
+without first having or creating a strong reference to the object.
+
+
+
+
+
+
+
+
+ Frees resources associated with a non-statically-allocated #GWeakRef.
+After this call, the #GWeakRef is left in an undefined state.
+
+You should only call this on a #GWeakRef that previously had
+g_weak_ref_init() called on it.
+
+
+
+
+
+
+ location of a weak reference, which
+ may be empty
+
+
+
+
+
+ If @weak_ref is not empty, atomically acquire a strong
+reference to the object it points to, and return that reference.
+
+This function is needed because of the potential race between taking
+the pointer value and g_object_ref() on it, if the object was losing
+its last reference at the same time in a different thread.
+
+The caller should release the resulting reference in the usual way,
+by using g_object_unref().
+
+
+ the object pointed to
+ by @weak_ref, or %NULL if it was empty
+
+
+
+
+ location of a weak reference to a #GObject
+
+
+
+
+
+ Initialise a non-statically-allocated #GWeakRef.
+
+This function also calls g_weak_ref_set() with @object on the
+freshly-initialised weak reference.
+
+This function should always be matched with a call to
+g_weak_ref_clear(). It is not necessary to use this function for a
+#GWeakRef in static storage because it will already be
+properly initialised. Just use g_weak_ref_set() directly.
+
+
+
+
+
+
+ uninitialized or empty location for a weak
+ reference
+
+
+
+ a #GObject or %NULL
+
+
+
+
+
+ Change the object to which @weak_ref points, or set it to
+%NULL.
+
+You must own a strong reference on @object while calling this
+function.
+
+
+
+
+
+
+ location for a weak reference
+
+
+
+ a #GObject or %NULL
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Assert that @object is non-%NULL, then release one reference to it with
+g_object_unref() and assert that it has been finalized (i.e. that there
+are no more references).
+
+If assertions are disabled via `G_DISABLE_ASSERT`,
+this macro just calls g_object_unref() without any further checks.
+
+This macro should only be used in regression tests.
+
+
+
+ an object
+
+
+
+
+ Provide a copy of a boxed structure @src_boxed which is of type @boxed_type.
+
+
+ The newly created copy of the boxed
+ structure.
+
+
+
+
+ The type of @src_boxed.
+
+
+
+ The boxed structure to be copied.
+
+
+
+
+
+ Free the boxed structure @boxed which is of type @boxed_type.
+
+
+
+
+
+
+ The type of @boxed.
+
+
+
+ The boxed structure to be freed.
+
+
+
+
+
+ This function creates a new %G_TYPE_BOXED derived type id for a new
+boxed type with name @name.
+
+Boxed type handling functions have to be provided to copy and free
+opaque boxed structures of this type.
+
+For the general case, it is recommended to use G_DEFINE_BOXED_TYPE()
+instead of calling g_boxed_type_register_static() directly. The macro
+will create the appropriate `*_get_type()` function for the boxed type.
+
+
+ New %G_TYPE_BOXED derived type id for @name.
+
+
+
+
+ Name of the new boxed type.
+
+
+
+ Boxed structure copy function.
+
+
+
+ Boxed structure free function.
+
+
+
+
+
+ A #GClosureMarshal function for use with signals with handlers that
+take two boxed pointers as arguments and return a boolean. If you
+have such a signal, you will probably also need to use an
+accumulator, such as g_signal_accumulator_true_handled().
+
+
+
+
+
+
+ A #GClosure.
+
+
+
+ A #GValue to store the return value. May be %NULL
+ if the callback of closure doesn't return a value.
+
+
+
+ The length of the @param_values array.
+
+
+
+ An array of #GValues holding the arguments
+ on which to invoke the callback of closure.
+
+
+
+ The invocation hint given as the last argument to
+ g_closure_invoke().
+
+
+
+ Additional data specified when registering the
+ marshaller, see g_closure_set_marshal() and
+ g_closure_set_meta_marshal()
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter
+denotes a flags type.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ a #GValue which can store the returned #gboolean
+
+
+
+ 2
+
+
+
+ a #GValue array holding instance and arg1
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ a #GValue, which can store the returned string
+
+
+
+ 3
+
+
+
+ a #GValue array holding instance, arg1 and arg2
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the #gboolean parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the #GBoxed* parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, gchar arg1, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the #gchar parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the #gdouble parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes an enumeration type..
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the enumeration parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes a flags type.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the flags parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the #gfloat parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, gint arg1, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the #gint parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, glong arg1, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the #glong parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the #GObject* parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the #GParamSpec* parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the #gpointer parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the #gchar* parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, guchar arg1, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the #guchar parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, guint arg1, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the #guint parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 3
+
+
+
+ a #GValue array holding instance, arg1 and arg2
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, gulong arg1, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the #gulong parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 2
+
+
+
+ a #GValue array holding the instance and the #GVariant* parameter
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ A marshaller for a #GCClosure with a callback of type
+`void (*callback) (gpointer instance, gpointer user_data)`.
+
+
+
+
+
+
+ the #GClosure to which the marshaller belongs
+
+
+
+ ignored
+
+
+
+ 1
+
+
+
+ a #GValue array holding only the instance
+
+
+
+ the invocation hint given as the last argument
+ to g_closure_invoke()
+
+
+
+ additional data specified when registering the marshaller
+
+
+
+
+
+ A generic marshaller function implemented via
+[libffi](http://sourceware.org/libffi/).
+
+Normally this function is not passed explicitly to g_signal_new(),
+but used automatically by GLib when specifying a %NULL marshaller.
+
+
+
+
+
+
+ A #GClosure.
+
+
+
+ A #GValue to store the return value. May be %NULL
+ if the callback of closure doesn't return a value.
+
+
+
+ The length of the @param_values array.
+
+
+
+ An array of #GValues holding the arguments
+ on which to invoke the callback of closure.
+
+
+
+ The invocation hint given as the last argument to
+ g_closure_invoke().
+
+
+
+ Additional data specified when registering the
+ marshaller, see g_closure_set_marshal() and
+ g_closure_set_meta_marshal()
+
+
+
+
+
+ Creates a new closure which invokes @callback_func with @user_data as
+the last parameter.
+
+@destroy_data will be called as a finalize notifier on the #GClosure.
+
+
+ a floating reference to a new #GCClosure
+
+
+
+
+ the function to invoke
+
+
+
+ user data to pass to @callback_func
+
+
+
+ destroy notify to be called when @user_data is no longer used
+
+
+
+
+
+ A variant of g_cclosure_new() which uses @object as @user_data and
+calls g_object_watch_closure() on @object and the created
+closure. This function is useful when you have a callback closely
+associated with a #GObject, and want the callback to no longer run
+after the object is is freed.
+
+
+ a new #GCClosure
+
+
+
+
+ the function to invoke
+
+
+
+ a #GObject pointer to pass to @callback_func
+
+
+
+
+
+ A variant of g_cclosure_new_swap() which uses @object as @user_data
+and calls g_object_watch_closure() on @object and the created
+closure. This function is useful when you have a callback closely
+associated with a #GObject, and want the callback to no longer run
+after the object is is freed.
+
+
+ a new #GCClosure
+
+
+
+
+ the function to invoke
+
+
+
+ a #GObject pointer to pass to @callback_func
+
+
+
+
+
+ Creates a new closure which invokes @callback_func with @user_data as
+the first parameter.
+
+@destroy_data will be called as a finalize notifier on the #GClosure.
+
+
+ a floating reference to a new #GCClosure
+
+
+
+
+ the function to invoke
+
+
+
+ user data to pass to @callback_func
+
+
+
+ destroy notify to be called when @user_data is no longer used
+
+
+
+
+
+ Clears a reference to a #GObject.
+
+@object_ptr must not be %NULL.
+
+If the reference is %NULL then this function does nothing.
+Otherwise, the reference count of the object is decreased and the
+pointer is set to %NULL.
+
+A macro is also included that allows this function to be used without
+pointer casts.
+
+
+
+
+
+
+ a pointer to a #GObject reference
+
+
+
+
+
+ Disconnects a handler from @instance so it will not be called during
+any future or currently ongoing emissions of the signal it has been
+connected to. The @handler_id_ptr is then set to zero, which is never a valid handler ID value (see g_signal_connect()).
+
+If the handler ID is 0 then this function does nothing.
+
+There is also a macro version of this function so that the code
+will be inlined.
+
+
+
+
+
+
+ A pointer to a handler ID (of type #gulong) of the handler to be disconnected.
+
+
+
+ The instance to remove the signal handler from.
+ This pointer may be %NULL or invalid, if the handler ID is zero.
+
+
+
+
+
+ Clears a weak reference to a #GObject.
+
+@weak_pointer_location must not be %NULL.
+
+If the weak reference is %NULL then this function does nothing.
+Otherwise, the weak reference to the object is removed for that location
+and the pointer is set to %NULL.
+
+A macro is also included that allows this function to be used without
+pointer casts. The function itself is static inline, so its address may vary
+between compilation units.
+
+
+
+ The memory address of a pointer
+
+
+
+
+ This function is meant to be called from the `complete_type_info`
+function of a #GTypePlugin implementation, as in the following
+example:
+
+|[<!-- language="C" -->
+static void
+my_enum_complete_type_info (GTypePlugin *plugin,
+ GType g_type,
+ GTypeInfo *info,
+ GTypeValueTable *value_table)
+{
+ static const GEnumValue values[] = {
+ { MY_ENUM_FOO, "MY_ENUM_FOO", "foo" },
+ { MY_ENUM_BAR, "MY_ENUM_BAR", "bar" },
+ { 0, NULL, NULL }
+ };
+
+ g_enum_complete_type_info (type, info, values);
+}
+]|
+
+
+
+
+
+
+ the type identifier of the type being completed
+
+
+
+ the #GTypeInfo struct to be filled in
+
+
+
+ An array of #GEnumValue structs for the possible
+ enumeration values. The array is terminated by a struct with all
+ members being 0.
+
+
+
+
+
+ Returns the #GEnumValue for a value.
+
+
+ the #GEnumValue for @value, or %NULL
+ if @value is not a member of the enumeration
+
+
+
+
+ a #GEnumClass
+
+
+
+ the value to look up
+
+
+
+
+
+ Looks up a #GEnumValue by name.
+
+
+ the #GEnumValue with name @name,
+ or %NULL if the enumeration doesn't have a member
+ with that name
+
+
+
+
+ a #GEnumClass
+
+
+
+ the name to look up
+
+
+
+
+
+ Looks up a #GEnumValue by nickname.
+
+
+ the #GEnumValue with nickname @nick,
+ or %NULL if the enumeration doesn't have a member
+ with that nickname
+
+
+
+
+ a #GEnumClass
+
+
+
+ the nickname to look up
+
+
+
+
+
+ Registers a new static enumeration type with the name @name.
+
+It is normally more convenient to let [glib-mkenums][glib-mkenums],
+generate a my_enum_get_type() function from a usual C enumeration
+definition than to write one yourself using g_enum_register_static().
+
+
+ The new type identifier.
+
+
+
+
+ A nul-terminated string used as the name of the new type.
+
+
+
+ An array of #GEnumValue structs for the possible
+ enumeration values. The array is terminated by a struct with all
+ members being 0. GObject keeps a reference to the data, so it cannot
+ be stack-allocated.
+
+
+
+
+
+ Pretty-prints @value in the form of the enum’s name.
+
+This is intended to be used for debugging purposes. The format of the output
+may change in the future.
+
+
+ a newly-allocated text string
+
+
+
+
+ the type identifier of a #GEnumClass type
+
+
+
+ the value
+
+
+
+
+
+ The GLib type system provides fundamental types for enumeration and
+flags types. (Flags types are like enumerations, but allow their
+values to be combined by bitwise or). A registered enumeration or
+flags type associates a name and a nickname with each allowed
+value, and the methods g_enum_get_value_by_name(),
+g_enum_get_value_by_nick(), g_flags_get_value_by_name() and
+g_flags_get_value_by_nick() can look up values by their name or
+nickname. When an enumeration or flags type is registered with the
+GLib type system, it can be used as value type for object
+properties, using g_param_spec_enum() or g_param_spec_flags().
+
+GObject ships with a utility called [glib-mkenums][glib-mkenums],
+that can construct suitable type registration functions from C enumeration
+definitions.
+
+Example of how to get a string representation of an enum value:
+|[<!-- language="C" -->
+GEnumClass *enum_class;
+GEnumValue *enum_value;
+
+enum_class = g_type_class_ref (MAMAN_TYPE_MY_ENUM);
+enum_value = g_enum_get_value (enum_class, MAMAN_MY_ENUM_FOO);
+
+g_print ("Name: %s\n", enum_value->value_name);
+
+g_type_class_unref (enum_class);
+]|
+
+
+ This function is meant to be called from the complete_type_info()
+function of a #GTypePlugin implementation, see the example for
+g_enum_complete_type_info() above.
+
+
+
+
+
+
+ the type identifier of the type being completed
+
+
+
+ the #GTypeInfo struct to be filled in
+
+
+
+ An array of #GFlagsValue structs for the possible
+ enumeration values. The array is terminated by a struct with all
+ members being 0.
+
+
+
+
+
+ Returns the first #GFlagsValue which is set in @value.
+
+
+ the first #GFlagsValue which is set in
+ @value, or %NULL if none is set
+
+
+
+
+ a #GFlagsClass
+
+
+
+ the value
+
+
+
+
+
+ Looks up a #GFlagsValue by name.
+
+
+ the #GFlagsValue with name @name,
+ or %NULL if there is no flag with that name
+
+
+
+
+ a #GFlagsClass
+
+
+
+ the name to look up
+
+
+
+
+
+ Looks up a #GFlagsValue by nickname.
+
+
+ the #GFlagsValue with nickname @nick,
+ or %NULL if there is no flag with that nickname
+
+
+
+
+ a #GFlagsClass
+
+
+
+ the nickname to look up
+
+
+
+
+
+ Registers a new static flags type with the name @name.
+
+It is normally more convenient to let [glib-mkenums][glib-mkenums]
+generate a my_flags_get_type() function from a usual C enumeration
+definition than to write one yourself using g_flags_register_static().
+
+
+ The new type identifier.
+
+
+
+
+ A nul-terminated string used as the name of the new type.
+
+
+
+ An array of #GFlagsValue structs for the possible
+ flags values. The array is terminated by a struct with all members being 0.
+ GObject keeps a reference to the data, so it cannot be stack-allocated.
+
+
+
+
+
+ Pretty-prints @value in the form of the flag names separated by ` | ` and
+sorted. Any extra bits will be shown at the end as a hexadecimal number.
+
+This is intended to be used for debugging purposes. The format of the output
+may change in the future.
+
+
+ a newly-allocated text string
+
+
+
+
+ the type identifier of a #GFlagsClass type
+
+
+
+ the value
+
+
+
+
+
+ #GBoxed is a generic wrapper mechanism for arbitrary C structures.
+
+The only thing the type system needs to know about the structures is how to
+copy them (a #GBoxedCopyFunc) and how to free them (a #GBoxedFreeFunc);
+beyond that, they are treated as opaque chunks of memory.
+
+Boxed types are useful for simple value-holder structures like rectangles or
+points. They can also be used for wrapping structures defined in non-#GObject
+based libraries. They allow arbitrary structures to be handled in a uniform
+way, allowing uniform copying (or referencing) and freeing (or unreferencing)
+of them, and uniform representation of the type of the contained structure.
+In turn, this allows any type which can be boxed to be set as the data in a
+#GValue, which allows for polymorphic handling of a much wider range of data
+types, and hence usage of such types as #GObject property values.
+
+#GBoxed is designed so that reference counted types can be boxed. Use the
+type’s ‘ref’ function as the #GBoxedCopyFunc, and its ‘unref’ function as the
+#GBoxedFreeFunc. For example, for #GBytes, the #GBoxedCopyFunc is
+g_bytes_ref(), and the #GBoxedFreeFunc is g_bytes_unref().
+
+
+ The #GValue structure is basically a variable container that consists
+of a type identifier and a specific value of that type.
+
+The type identifier within a #GValue structure always determines the
+type of the associated value.
+
+To create an undefined #GValue structure, simply create a zero-filled
+#GValue structure. To initialize the #GValue, use the g_value_init()
+function. A #GValue cannot be used until it is initialized. Before
+destruction you must always use g_value_unset() to make sure allocated
+memory is freed.
+
+The basic type operations (such as freeing and copying) are determined
+by the #GTypeValueTable associated with the type ID stored in the #GValue.
+Other #GValue operations (such as converting values between types) are
+provided by this interface.
+
+The code in the example program below demonstrates #GValue's
+features.
+
+|[<!-- language="C" -->
+#include <glib-object.h>
+
+static void
+int2string (const GValue *src_value,
+ GValue *dest_value)
+{
+ if (g_value_get_int (src_value) == 42)
+ g_value_set_static_string (dest_value, "An important number");
+ else
+ g_value_set_static_string (dest_value, "What's that?");
+}
+
+int
+main (int argc,
+ char *argv[])
+{
+ // GValues must be initialized
+ GValue a = G_VALUE_INIT;
+ GValue b = G_VALUE_INIT;
+ const gchar *message;
+
+ // The GValue starts empty
+ g_assert (!G_VALUE_HOLDS_STRING (&a));
+
+ // Put a string in it
+ g_value_init (&a, G_TYPE_STRING);
+ g_assert (G_VALUE_HOLDS_STRING (&a));
+ g_value_set_static_string (&a, "Hello, world!");
+ g_printf ("%s\n", g_value_get_string (&a));
+
+ // Reset it to its pristine state
+ g_value_unset (&a);
+
+ // It can then be reused for another type
+ g_value_init (&a, G_TYPE_INT);
+ g_value_set_int (&a, 42);
+
+ // Attempt to transform it into a GValue of type STRING
+ g_value_init (&b, G_TYPE_STRING);
+
+ // An INT is transformable to a STRING
+ g_assert (g_value_type_transformable (G_TYPE_INT, G_TYPE_STRING));
+
+ g_value_transform (&a, &b);
+ g_printf ("%s\n", g_value_get_string (&b));
+
+ // Attempt to transform it again using a custom transform function
+ g_value_register_transform_func (G_TYPE_INT, G_TYPE_STRING, int2string);
+ g_value_transform (&a, &b);
+ g_printf ("%s\n", g_value_get_string (&b));
+ return 0;
+}
+]|
+
+See also [gobject-Standard-Parameter-and-Value-Types] for more information on
+validation of #GValue.
+
+For letting a #GValue own (and memory manage) arbitrary types or pointers,
+they need to become a [boxed type][gboxed]. The example below shows how
+the pointer `mystruct` of type `MyStruct` is used as a [boxed type][gboxed].
+
+|[<!-- language="C" -->
+typedef struct { ... } MyStruct;
+G_DEFINE_BOXED_TYPE (MyStruct, my_struct, my_struct_copy, my_struct_free)
+
+// These two lines normally go in a public header. By GObject convention,
+// the naming scheme is NAMESPACE_TYPE_NAME:
+#define MY_TYPE_STRUCT (my_struct_get_type ())
+GType my_struct_get_type (void);
+
+void
+foo ()
+{
+ GValue *value = g_new0 (GValue, 1);
+ g_value_init (value, MY_TYPE_STRUCT);
+ g_value_set_boxed (value, mystruct);
+ // [... your code ....]
+ g_value_unset (value);
+ g_value_free (value);
+}
+]|
+
+
+ The GType API is the foundation of the GObject system. It provides the
+facilities for registering and managing all fundamental data types,
+user-defined object and interface types.
+
+For type creation and registration purposes, all types fall into one of
+two categories: static or dynamic. Static types are never loaded or
+unloaded at run-time as dynamic types may be. Static types are created
+with g_type_register_static() that gets type specific information passed
+in via a #GTypeInfo structure.
+
+Dynamic types are created with g_type_register_dynamic() which takes a
+#GTypePlugin structure instead. The remaining type information (the
+#GTypeInfo structure) is retrieved during runtime through #GTypePlugin
+and the g_type_plugin_*() API.
+
+These registration functions are usually called only once from a
+function whose only purpose is to return the type identifier for a
+specific class. Once the type (or class or interface) is registered,
+it may be instantiated, inherited, or implemented depending on exactly
+what sort of type it is.
+
+There is also a third registration function for registering fundamental
+types called g_type_register_fundamental() which requires both a #GTypeInfo
+structure and a #GTypeFundamentalInfo structure but it is seldom used
+since most fundamental types are predefined rather than user-defined.
+
+Type instance and class structs are limited to a total of 64 KiB,
+including all parent types. Similarly, type instances' private data
+(as created by G_ADD_PRIVATE()) are limited to a total of
+64 KiB. If a type instance needs a large static buffer, allocate it
+separately (typically by using #GArray or #GPtrArray) and put a pointer
+to the buffer in the structure.
+
+As mentioned in the [GType conventions][gtype-conventions], type names must
+be at least three characters long. There is no upper length limit. The first
+character must be a letter (a–z or A–Z) or an underscore (‘_’). Subsequent
+characters can be letters, numbers or any of ‘-_+’.
+
+
+
+
+
+
+
+
+ GObject is the fundamental type providing the common attributes and
+methods for all object types in GTK+, Pango and other libraries
+based on GObject. The GObject class provides methods for object
+construction and destruction, property access methods, and signal
+support. Signals are described in detail [here][gobject-Signals].
+
+For a tutorial on implementing a new GObject class, see [How to define and
+implement a new GObject][howto-gobject]. For a list of naming conventions for
+GObjects and their methods, see the [GType conventions][gtype-conventions].
+For the high-level concepts behind GObject, read [Instantiatable classed types:
+Objects][gtype-instantiatable-classed].
+
+## Floating references # {#floating-ref}
+
+**Note**: Floating references are a C convenience API and should not be
+used in modern GObject code. Language bindings in particular find the
+concept highly problematic, as floating references are not identifiable
+through annotations, and neither are deviations from the floating reference
+behavior, like types that inherit from #GInitiallyUnowned and still return
+a full reference from g_object_new().
+
+GInitiallyUnowned is derived from GObject. The only difference between
+the two is that the initial reference of a GInitiallyUnowned is flagged
+as a "floating" 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:
+
+|[<!-- language="C" -->
+container = create_container ();
+container_add_child (container, create_child());
+]|
+
+If container_add_child() calls g_object_ref_sink() on the passed-in child,
+no reference of the newly created child is leaked. Without floating
+references, container_add_child() can only g_object_ref() the new child,
+so to implement this code without reference leaks, it would have to be
+written as:
+
+|[<!-- language="C" -->
+Child *child;
+container = create_container ();
+child = create_child ();
+container_add_child (container, child);
+g_object_unref (child);
+]|
+
+The floating reference can be converted into an ordinary reference by
+calling g_object_ref_sink(). For already sunken objects (objects that
+don't have a floating reference anymore), g_object_ref_sink() is equivalent
+to g_object_ref() and returns 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) should not
+expose floating references in their API. The best practice for handling
+types that have initially floating references is to immediately sink those
+references after g_object_new() returns, by checking if the #GType
+inherits from #GInitiallyUnowned. For instance:
+
+|[<!-- language="C" -->
+GObject *res = g_object_new_with_properties (gtype,
+ n_props,
+ prop_names,
+ prop_values);
+
+// or: if (g_type_is_a (gtype, G_TYPE_INITIALLY_UNOWNED))
+if (G_IS_INITIALLY_UNOWNED (res))
+ g_object_ref_sink (res);
+
+return res;
+]|
+
+Some object implementations may need to save an objects floating state
+across certain code portions (an example is #GtkMenu), to achieve this,
+the following sequence can be used:
+
+|[<!-- language="C" -->
+// save floating state
+gboolean was_floating = g_object_is_floating (object);
+g_object_ref_sink (object);
+// protected code portion
+
+...
+
+// restore floating state
+if (was_floating)
+ g_object_force_floating (object);
+else
+ g_object_unref (object); // release previously acquired reference
+]|
+
+
+ Creates a new #GParamSpecBoolean instance specifying a %G_TYPE_BOOLEAN
+property. In many cases, it may be more appropriate to use an enum with
+g_param_spec_enum(), both to improve code clarity by using explicitly named
+values, and to allow for more values to be added in future without breaking
+API.
+
+See g_param_spec_internal() for details on property names.
+
+
+ a newly created parameter specification
+
+
+
+
+ canonical name of the property specified
+
+
+
+ nick name for the property specified
+
+
+
+ description of the property specified
+
+
+
+ default value for the property specified
+
+
+
+ flags for the property specified
+
+
+
+
+
+ Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_BOXED
+derived property.
+
+See g_param_spec_internal() for details on property names.
+
+
+ a newly created parameter specification
+
+
+
+
+ canonical name of the property specified
+
+
+
+ nick name for the property specified
+
+
+
+ description of the property specified
+
+
+
+ %G_TYPE_BOXED derived type of this property
+
+
+
+ flags for the property specified
+
+
+
+
+
+ Creates a new #GParamSpecChar instance specifying a %G_TYPE_CHAR property.
+
+
+ a newly created parameter specification
+
+
+
+
+ canonical name of the property specified
+
+
+
+ nick name for the property specified
+
+
+
+ description of the property specified
+
+
+
+ minimum value for the property specified
+
+
+
+ maximum value for the property specified
+
+
+
+ default value for the property specified
+
+
+
+ flags for the property specified
+
+
+
+
+
+ Creates a new #GParamSpecDouble instance specifying a %G_TYPE_DOUBLE
+property.
+
+See g_param_spec_internal() for details on property names.
+
+
+ a newly created parameter specification
+
+
+
+
+ canonical name of the property specified
+
+
+
+ nick name for the property specified
+
+
+
+ description of the property specified
+
+
+
+ minimum value for the property specified
+
+
+
+ maximum value for the property specified
+
+
+
+ default value for the property specified
+
+
+
+ flags for the property specified
+
+
+
+
+
+ Creates a new #GParamSpecEnum instance specifying a %G_TYPE_ENUM
+property.
+
+See g_param_spec_internal() for details on property names.
+
+
+ a newly created parameter specification
+
+
+
+
+ canonical name of the property specified
+
+
+
+ nick name for the property specified
+
+
+
+ description of the property specified
+
+
+
+ a #GType derived from %G_TYPE_ENUM
+
+
+
+ default value for the property specified
+
+
+
+ flags for the property specified
+
+
+
+
+
+ Creates a new #GParamSpecFlags instance specifying a %G_TYPE_FLAGS
+property.
+
+See g_param_spec_internal() for details on property names.
+
+
+ a newly created parameter specification
+
+
+
+
+ canonical name of the property specified
+
+
+
+ nick name for the property specified
+
+
+
+ description of the property specified
+
+
+
+ a #GType derived from %G_TYPE_FLAGS
+
+
+
+ default value for the property specified
+
+
+
+ flags for the property specified
+
+
+
+
+
+ Creates a new #GParamSpecFloat instance specifying a %G_TYPE_FLOAT property.
+
+See g_param_spec_internal() for details on property names.
+
+
+ a newly created parameter specification
+
+
+
+
+ canonical name of the property specified
+
+
+
+ nick name for the property specified
+
+
+
+ description of the property specified
+
+
+
+ minimum value for the property specified
+
+
+
+ maximum value for the property specified
+
+
+
+ default value for the property specified
+
+
+
+ flags for the property specified
+
+
+
+
+
+ Creates a new #GParamSpecGType instance specifying a
+%G_TYPE_GTYPE property.
+
+See g_param_spec_internal() for details on property names.
+
+
+ a newly created parameter specification
+
+
+
+
+ canonical name of the property specified
+
+
+
+ nick name for the property specified
+
+
+
+ description of the property specified
+
+
+
+ a #GType whose subtypes are allowed as values
+ of the property (use %G_TYPE_NONE for any type)
+
+
+
+ flags for the property specified
+
+
+
+
+
+ Creates a new #GParamSpecInt instance specifying a %G_TYPE_INT property.
+
+See g_param_spec_internal() for details on property names.
+
+
+ a newly created parameter specification
+
+
+
+
+ canonical name of the property specified
+
+
+
+ nick name for the property specified
+
+
+
+ description of the property specified
+
+
+
+ minimum value for the property specified
+
+
+
+ maximum value for the property specified
+
+
+
+ default value for the property specified
+
+
+
+ flags for the property specified
+
+
+
+
+
+ Creates a new #GParamSpecInt64 instance specifying a %G_TYPE_INT64 property.
+
+See g_param_spec_internal() for details on property names.
+
+
+ a newly created parameter specification
+
+
+
+
+ canonical name of the property specified
+
+
+
+ nick name for the property specified
+
+
+
+ description of the property specified
+
+
+
+ minimum value for the property specified
+
+
+
+ maximum value for the property specified
+
+
+
+ default value for the property specified
+
+
+
+ flags for the property specified
+
+
+
+
+
+ Creates a new #GParamSpecLong instance specifying a %G_TYPE_LONG property.
+
+See g_param_spec_internal() for details on property names.
+
+
+ a newly created parameter specification
+
+
+
+
+ canonical name of the property specified
+
+
+
+ nick name for the property specified
+
+
+
+ description of the property specified
+
+
+
+ minimum value for the property specified
+
+
+
+ maximum value for the property specified
+
+
+
+ default value for the property specified
+
+
+
+ flags for the property specified
+
+
+
+
+
+ Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_OBJECT
+derived property.
+
+See g_param_spec_internal() for details on property names.
+
+
+ a newly created parameter specification
+
+
+
+
+ canonical name of the property specified
+
+
+
+ nick name for the property specified
+
+
+
+ description of the property specified
+
+
+
+ %G_TYPE_OBJECT derived type of this property
+
+
+
+ flags for the property specified
+
+
+
+
+
+ Creates a new property of type #GParamSpecOverride. This is used
+to direct operations to another paramspec, and will not be directly
+useful unless you are implementing a new base type similar to GObject.
+
+
+ the newly created #GParamSpec
+
+
+
+
+ the name of the property.
+
+
+
+ The property that is being overridden
+
+
+
+
+
+ Creates a new #GParamSpecParam instance specifying a %G_TYPE_PARAM
+property.
+
+See g_param_spec_internal() for details on property names.
+
+
+ a newly created parameter specification
+
+
+
+
+ canonical name of the property specified
+
+
+
+ nick name for the property specified
+
+
+
+ description of the property specified
+
+
+
+ a #GType derived from %G_TYPE_PARAM
+
+
+
+ flags for the property specified
+
+
+
+
+
+ Creates a new #GParamSpecPointer instance specifying a pointer property.
+Where possible, it is better to use g_param_spec_object() or
+g_param_spec_boxed() to expose memory management information.
+
+See g_param_spec_internal() for details on property names.
+
+
+ a newly created parameter specification
+
+
+
+
+ canonical name of the property specified
+
+
+
+ nick name for the property specified
+
+
+
+ description of the property specified
+
+
+
+ flags for the property specified
+
+
+
+
+
+ Creates a new #GParamSpecString instance.
+
+See g_param_spec_internal() for details on property names.
+
+
+ a newly created parameter specification
+
+
+
+
+ canonical name of the property specified
+
+
+
+ nick name for the property specified
+
+
+
+ description of the property specified
+
+
+
+ default value for the property specified
+
+
+
+ flags for the property specified
+
+
+
+
+
+ Creates a new #GParamSpecUChar instance specifying a %G_TYPE_UCHAR property.
+
+
+ a newly created parameter specification
+
+
+
+
+ canonical name of the property specified
+
+
+
+ nick name for the property specified
+
+
+
+ description of the property specified
+
+
+
+ minimum value for the property specified
+
+
+
+ maximum value for the property specified
+
+
+
+ default value for the property specified
+
+
+
+ flags for the property specified
+
+
+
+
+
+ Creates a new #GParamSpecUInt instance specifying a %G_TYPE_UINT property.
+
+See g_param_spec_internal() for details on property names.
+
+
+ a newly created parameter specification
+
+
+
+
+ canonical name of the property specified
+
+
+
+ nick name for the property specified
+
+
+
+ description of the property specified
+
+
+
+ minimum value for the property specified
+
+
+
+ maximum value for the property specified
+
+
+
+ default value for the property specified
+
+
+
+ flags for the property specified
+
+
+
+
+
+ Creates a new #GParamSpecUInt64 instance specifying a %G_TYPE_UINT64
+property.
+
+See g_param_spec_internal() for details on property names.
+
+
+ a newly created parameter specification
+
+
+
+
+ canonical name of the property specified
+
+
+
+ nick name for the property specified
+
+
+
+ description of the property specified
+
+
+
+ minimum value for the property specified
+
+
+
+ maximum value for the property specified
+
+
+
+ default value for the property specified
+
+
+
+ flags for the property specified
+
+
+
+
+
+ Creates a new #GParamSpecULong instance specifying a %G_TYPE_ULONG
+property.
+
+See g_param_spec_internal() for details on property names.
+
+
+ a newly created parameter specification
+
+
+
+
+ canonical name of the property specified
+
+
+
+ nick name for the property specified
+
+
+
+ description of the property specified
+
+
+
+ minimum value for the property specified
+
+
+
+ maximum value for the property specified
+
+
+
+ default value for the property specified
+
+
+
+ flags for the property specified
+
+
+
+
+
+ Creates a new #GParamSpecUnichar instance specifying a %G_TYPE_UINT
+property. #GValue structures for this property can be accessed with
+g_value_set_uint() and g_value_get_uint().
+
+See g_param_spec_internal() for details on property names.
+
+
+ a newly created parameter specification
+
+
+
+
+ canonical name of the property specified
+
+
+
+ nick name for the property specified
+
+
+
+ description of the property specified
+
+
+
+ default value for the property specified
+
+
+
+ flags for the property specified
+
+
+
+
+
+ Creates a new #GParamSpecValueArray instance specifying a
+%G_TYPE_VALUE_ARRAY property. %G_TYPE_VALUE_ARRAY is a
+%G_TYPE_BOXED type, as such, #GValue structures for this property
+can be accessed with g_value_set_boxed() and g_value_get_boxed().
+
+See g_param_spec_internal() for details on property names.
+
+
+ a newly created parameter specification
+
+
+
+
+ canonical name of the property specified
+
+
+
+ nick name for the property specified
+
+
+
+ description of the property specified
+
+
+
+ a #GParamSpec describing the elements contained in
+ arrays of this property, may be %NULL
+
+
+
+ flags for the property specified
+
+
+
+
+
+ Creates a new #GParamSpecVariant instance specifying a #GVariant
+property.
+
+If @default_value is floating, it is consumed.
+
+See g_param_spec_internal() for details on property names.
+
+
+ the newly created #GParamSpec
+
+
+
+
+ canonical name of the property specified
+
+
+
+ nick name for the property specified
+
+
+
+ description of the property specified
+
+
+
+ a #GVariantType
+
+
+
+ a #GVariant of type @type to
+ use as the default value, or %NULL
+
+
+
+ flags for the property specified
+
+
+
+
+
+ Registers @name as the name of a new static type derived
+from %G_TYPE_PARAM.
+
+The type system uses the information contained in the #GParamSpecTypeInfo
+structure pointed to by @info to manage the #GParamSpec type and its
+instances.
+
+
+ The new type identifier.
+
+
+
+
+ 0-terminated string used as the name of the new #GParamSpec type.
+
+
+
+ The #GParamSpecTypeInfo for this #GParamSpec type.
+
+
+
+
+
+ Transforms @src_value into @dest_value if possible, and then
+validates @dest_value, in order for it to conform to @pspec. If
+@strict_validation is %TRUE this function will only succeed if the
+transformed @dest_value complied to @pspec without modifications.
+
+See also g_value_type_transformable(), g_value_transform() and
+g_param_value_validate().
+
+
+ %TRUE if transformation and validation were successful,
+ %FALSE otherwise and @dest_value is left untouched.
+
+
+
+
+ a valid #GParamSpec
+
+
+
+ source #GValue
+
+
+
+ destination #GValue of correct type for @pspec
+
+
+
+ %TRUE requires @dest_value to conform to @pspec
+without modifications
+
+
+
+
+
+ Checks whether @value contains the default value as specified in @pspec.
+
+
+ whether @value contains the canonical default for this @pspec
+
+
+
+
+ a valid #GParamSpec
+
+
+
+ a #GValue of correct type for @pspec
+
+
+
+
+
+ Return whether the contents of @value comply with the specifications
+set out by @pspec.
+
+
+ whether the contents of @value comply with the specifications
+ set out by @pspec.
+
+
+
+
+ a valid #GParamSpec
+
+
+
+ a #GValue of correct type for @pspec
+
+
+
+
+
+ Sets @value to its default value as specified in @pspec.
+
+
+
+
+
+
+ a valid #GParamSpec
+
+
+
+ a #GValue of correct type for @pspec; since 2.64, you
+ can also pass an empty #GValue, initialized with %G_VALUE_INIT
+
+
+
+
+
+ #GValue provides an abstract container structure which can be
+copied, transformed and compared while holding a value of any
+(derived) type, which is registered as a #GType with a
+#GTypeValueTable in its #GTypeInfo structure. Parameter
+specifications for most value types can be created as #GParamSpec
+derived instances, to implement e.g. #GObject properties which
+operate on #GValue containers.
+
+Parameter names need to start with a letter (a-z or A-Z). Subsequent
+characters can be letters, numbers or a '-'.
+All other characters are replaced by a '-' during construction.
+
+See also #GValue for more information.
+
+
+ Ensures that the contents of @value comply with the specifications
+set out by @pspec. For example, a #GParamSpecInt might require
+that integers stored in @value may not be smaller than -42 and not be
+greater than +42. If @value contains an integer outside of this range,
+it is modified accordingly, so the resulting value will fit into the
+range -42 .. +42.
+
+
+ whether modifying @value was necessary to ensure validity
+
+
+
+
+ a valid #GParamSpec
+
+
+
+ a #GValue of correct type for @pspec
+
+
+
+
+
+ Compares @value1 with @value2 according to @pspec, and return -1, 0 or +1,
+if @value1 is found to be less than, equal to or greater than @value2,
+respectively.
+
+
+ -1, 0 or +1, for a less than, equal to or greater than result
+
+
+
+
+ a valid #GParamSpec
+
+
+
+ a #GValue of correct type for @pspec
+
+
+
+ a #GValue of correct type for @pspec
+
+
+
+
+
+ Creates a new %G_TYPE_POINTER derived type id for a new
+pointer type with name @name.
+
+
+ a new %G_TYPE_POINTER derived type id for @name.
+
+
+
+
+ the name of the new pointer type.
+
+
+
+
+
+ Updates a #GObject pointer to refer to @new_object.
+
+It increments the reference count of @new_object (if non-%NULL), decrements
+the reference count of the current value of @object_ptr (if non-%NULL), and
+assigns @new_object to @object_ptr. The assignment is not atomic.
+
+@object_ptr must not be %NULL, but can point to a %NULL value.
+
+A macro is also included that allows this function to be used without
+pointer casts. The function itself is static inline, so its address may vary
+between compilation units.
+
+One convenient usage of this function is in implementing property setters:
+|[
+ void
+ foo_set_bar (Foo *foo,
+ Bar *new_bar)
+ {
+ g_return_if_fail (IS_FOO (foo));
+ g_return_if_fail (new_bar == NULL || IS_BAR (new_bar));
+
+ if (g_set_object (&foo->bar, new_bar))
+ g_object_notify (foo, "bar");
+ }
+]|
+
+
+
+ a pointer to a #GObject reference
+
+
+ a pointer to the new #GObject to
+ assign to @object_ptr, or %NULL to clear the pointer
+
+
+
+
+ Updates a pointer to weakly refer to @new_object.
+
+It assigns @new_object to @weak_pointer_location and ensures
+that @weak_pointer_location will automatically be set to %NULL
+if @new_object gets destroyed. The assignment is not atomic.
+The weak reference is not thread-safe, see g_object_add_weak_pointer()
+for details.
+
+The @weak_pointer_location argument must not be %NULL.
+
+A macro is also included that allows this function to be used without
+pointer casts. The function itself is static inline, so its address may vary
+between compilation units.
+
+One convenient usage of this function is in implementing property setters:
+|[
+ void
+ foo_set_bar (Foo *foo,
+ Bar *new_bar)
+ {
+ g_return_if_fail (IS_FOO (foo));
+ g_return_if_fail (new_bar == NULL || IS_BAR (new_bar));
+
+ if (g_set_weak_pointer (&foo->bar, new_bar))
+ g_object_notify (foo, "bar");
+ }
+]|
+
+
+
+ the memory address of a pointer
+
+
+ a pointer to the new #GObject to
+ assign to it, or %NULL to clear the pointer
+
+
+
+
+ A predefined #GSignalAccumulator for signals intended to be used as a
+hook for application code to provide a particular value. Usually
+only one such value is desired and multiple handlers for the same
+signal don't make much sense (except for the case of the default
+handler defined in the class structure, in which case you will
+usually want the signal connection to override the class handler).
+
+This accumulator will use the return value from the first signal
+handler that is run as the return value for the signal and not run
+any further handlers (ie: the first handler "wins").
+
+
+ standard #GSignalAccumulator result
+
+
+
+
+ standard #GSignalAccumulator parameter
+
+
+
+ standard #GSignalAccumulator parameter
+
+
+
+ standard #GSignalAccumulator parameter
+
+
+
+ standard #GSignalAccumulator parameter
+
+
+
+
+
+ A predefined #GSignalAccumulator for signals that return a
+boolean values. The behavior that this accumulator gives is
+that a return of %TRUE stops the signal emission: no further
+callbacks will be invoked, while a return of %FALSE allows
+the emission to continue. The idea here is that a %TRUE return
+indicates that the callback handled the signal, and no further
+handling is needed.
+
+
+ standard #GSignalAccumulator result
+
+
+
+
+ standard #GSignalAccumulator parameter
+
+
+
+ standard #GSignalAccumulator parameter
+
+
+
+ standard #GSignalAccumulator parameter
+
+
+
+ standard #GSignalAccumulator parameter
+
+
+
+
+
+ Adds an emission hook for a signal, which will get called for any emission
+of that signal, independent of the instance. This is possible only
+for signals which don't have %G_SIGNAL_NO_HOOKS flag set.
+
+
+ the hook id, for later use with g_signal_remove_emission_hook().
+
+
+
+
+ the signal identifier, as returned by g_signal_lookup().
+
+
+
+ the detail on which to call the hook.
+
+
+
+ a #GSignalEmissionHook function.
+
+
+
+ user data for @hook_func.
+
+
+
+ a #GDestroyNotify for @hook_data.
+
+
+
+
+
+ Calls the original class closure of a signal. This function should only
+be called from an overridden class closure; see
+g_signal_override_class_closure() and
+g_signal_override_class_handler().
+
+
+
+
+
+
+ the argument list of the signal emission.
+ The first element in the array is a #GValue for the instance the signal
+ is being emitted on. The rest are any arguments to be passed to the signal.
+
+
+
+
+
+ Location for the return value.
+
+
+
+
+
+ Calls the original class closure of a signal. This function should
+only be called from an overridden class closure; see
+g_signal_override_class_closure() and
+g_signal_override_class_handler().
+
+
+
+
+
+
+ the instance the signal is being
+ emitted on.
+
+
+
+ parameters to be passed to the parent class closure, followed by a
+ location for the return value. If the return type of the signal
+ is %G_TYPE_NONE, the return value location can be omitted.
+
+
+
+
+
+ Connects a #GCallback function to a signal for a particular object.
+
+The handler will be called synchronously, before the default handler of the signal. g_signal_emit() will not return control until all handlers are called.
+
+See [memory management of signal handlers][signal-memory-management] for
+details on how to handle the return value and memory management of @data.
+
+
+
+ the instance to connect to.
+
+
+ a string of the form "signal-name::detail".
+
+
+ the #GCallback to connect.
+
+
+ data to pass to @c_handler calls.
+
+
+
+
+ Connects a #GCallback function to a signal for a particular object.
+
+The handler will be called synchronously, after the default handler of the signal.
+
+
+
+ the instance to connect to.
+
+
+ a string of the form "signal-name::detail".
+
+
+ the #GCallback to connect.
+
+
+ data to pass to @c_handler calls.
+
+
+
+
+ Connects a closure to a signal for a particular object.
+
+If @closure is a floating reference (see g_closure_sink()), this function
+takes ownership of @closure.
+
+
+ the handler ID (always greater than 0 for successful connections)
+
+
+
+
+ the instance to connect to.
+
+
+
+ a string of the form "signal-name::detail".
+
+
+
+ the closure to connect.
+
+
+
+ whether the handler should be called before or after the
+ default handler of the signal.
+
+
+
+
+
+ Connects a closure to a signal for a particular object.
+
+If @closure is a floating reference (see g_closure_sink()), this function
+takes ownership of @closure.
+
+
+ the handler ID (always greater than 0 for successful connections)
+
+
+
+
+ the instance to connect to.
+
+
+
+ the id of the signal.
+
+
+
+ the detail.
+
+
+
+ the closure to connect.
+
+
+
+ whether the handler should be called before or after the
+ default handler of the signal.
+
+
+
+
+
+ Connects a #GCallback function to a signal for a particular object. Similar
+to g_signal_connect(), but allows to provide a #GClosureNotify for the data
+which will be called when the signal handler is disconnected and no longer
+used. Specify @connect_flags if you need `..._after()` or
+`..._swapped()` variants of this function.
+
+
+ the handler ID (always greater than 0 for successful connections)
+
+
+
+
+ the instance to connect to.
+
+
+
+ a string of the form "signal-name::detail".
+
+
+
+ the #GCallback to connect.
+
+
+
+ data to pass to @c_handler calls.
+
+
+
+ a #GClosureNotify for @data.
+
+
+
+ a combination of #GConnectFlags.
+
+
+
+
+
+ This is similar to g_signal_connect_data(), but uses a closure which
+ensures that the @gobject stays alive during the call to @c_handler
+by temporarily adding a reference count to @gobject.
+
+When the @gobject is destroyed the signal handler will be automatically
+disconnected. Note that this is not currently threadsafe (ie:
+emitting a signal while @gobject is being destroyed in another thread
+is not safe).
+
+
+ the handler id.
+
+
+
+
+ the instance to connect to.
+
+
+
+ a string of the form "signal-name::detail".
+
+
+
+ the #GCallback to connect.
+
+
+
+ the object to pass as data
+ to @c_handler.
+
+
+
+ a combination of #GConnectFlags.
+
+
+
+
+
+ Connects a #GCallback function to a signal for a particular object.
+
+The instance on which the signal is emitted and @data will be swapped when
+calling the handler. This is useful when calling pre-existing functions to
+operate purely on the @data, rather than the @instance: swapping the
+parameters avoids the need to write a wrapper function.
+
+For example, this allows the shorter code:
+|[<!-- language="C" -->
+g_signal_connect_swapped (button, "clicked",
+ (GCallback) gtk_widget_hide, other_widget);
+]|
+
+Rather than the cumbersome:
+|[<!-- language="C" -->
+static void
+button_clicked_cb (GtkButton *button, GtkWidget *other_widget)
+{
+ gtk_widget_hide (other_widget);
+}
+
+...
+
+g_signal_connect (button, "clicked",
+ (GCallback) button_clicked_cb, other_widget);
+]|
+
+
+
+ the instance to connect to.
+
+
+ a string of the form "signal-name::detail".
+
+
+ the #GCallback to connect.
+
+
+ data to pass to @c_handler calls.
+
+
+
+
+ Emits a signal. Signal emission is done synchronously.
+The method will only return control after all handlers are called or signal emission was stopped.
+
+Note that g_signal_emit() resets the return value to the default
+if no handlers are connected, in contrast to g_signal_emitv().
+
+
+
+
+
+
+ the instance the signal is being emitted on.
+
+
+
+ the signal id
+
+
+
+ the detail
+
+
+
+ parameters to be passed to the signal, followed by a
+ location for the return value. If the return type of the signal
+ is %G_TYPE_NONE, the return value location can be omitted.
+
+
+
+
+
+ Emits a signal. Signal emission is done synchronously.
+The method will only return control after all handlers are called or signal emission was stopped.
+
+Note that g_signal_emit_by_name() resets the return value to the default
+if no handlers are connected, in contrast to g_signal_emitv().
+
+
+
+
+
+
+ the instance the signal is being emitted on.
+
+
+
+ a string of the form "signal-name::detail".
+
+
+
+ parameters to be passed to the signal, followed by a
+ location for the return value. If the return type of the signal
+ is %G_TYPE_NONE, the return value location can be omitted. The
+ number of parameters to pass to this function is defined when creating the signal.
+
+
+
+
+
+ Emits a signal. Signal emission is done synchronously.
+The method will only return control after all handlers are called or signal emission was stopped.
+
+Note that g_signal_emit_valist() resets the return value to the default
+if no handlers are connected, in contrast to g_signal_emitv().
+
+
+
+
+
+
+ the instance the signal is being
+ emitted on.
+
+
+
+ the signal id
+
+
+
+ the detail
+
+
+
+ a list of parameters to be passed to the signal, followed by a
+ location for the return value. If the return type of the signal
+ is %G_TYPE_NONE, the return value location can be omitted.
+
+
+
+
+
+ Emits a signal. Signal emission is done synchronously.
+The method will only return control after all handlers are called or signal emission was stopped.
+
+Note that g_signal_emitv() doesn't change @return_value if no handlers are
+connected, in contrast to g_signal_emit() and g_signal_emit_valist().
+
+
+
+
+
+
+ argument list for the signal emission.
+ The first element in the array is a #GValue for the instance the signal
+ is being emitted on. The rest are any arguments to be passed to the signal.
+
+
+
+
+
+ the signal id
+
+
+
+ the detail
+
+
+
+ Location to
+store the return value of the signal emission. This must be provided if the
+specified signal returns a value, but may be ignored otherwise.
+
+
+
+
+
+ Returns the invocation hint of the innermost signal emission of instance.
+
+
+ the invocation hint of the innermost
+ signal emission, or %NULL if not found.
+
+
+
+
+ the instance to query
+
+
+
+
+
+ Blocks a handler of an instance so it will not be called during any
+signal emissions unless it is unblocked again. Thus "blocking" a
+signal handler means to temporarily deactivate it, a signal handler
+has to be unblocked exactly the same amount of times it has been
+blocked before to become active again.
+
+The @handler_id has to be a valid signal handler id, connected to a
+signal of @instance.
+
+
+
+
+
+
+ The instance to block the signal handler of.
+
+
+
+ Handler id of the handler to be blocked.
+
+
+
+
+
+ Disconnects a handler from an instance so it will not be called during
+any future or currently ongoing emissions of the signal it has been
+connected to. The @handler_id becomes invalid and may be reused.
+
+The @handler_id has to be a valid signal handler id, connected to a
+signal of @instance.
+
+
+
+
+
+
+ The instance to remove the signal handler from.
+
+
+
+ Handler id of the handler to be disconnected.
+
+
+
+
+
+ Finds the first signal handler that matches certain selection criteria.
+The criteria mask is passed as an OR-ed combination of #GSignalMatchType
+flags, and the criteria values are passed as arguments.
+The match @mask has to be non-0 for successful matches.
+If no handler was found, 0 is returned.
+
+
+ A valid non-0 signal handler id for a successful match.
+
+
+
+
+ The instance owning the signal handler to be found.
+
+
+
+ Mask indicating which of @signal_id, @detail, @closure, @func
+ and/or @data the handler has to match.
+
+
+
+ Signal the handler has to be connected to.
+
+
+
+ Signal detail the handler has to be connected to.
+
+
+
+ The closure the handler will invoke.
+
+
+
+ The C closure callback of the handler (useless for non-C closures).
+
+
+
+ The closure data of the handler's closure.
+
+
+
+
+
+ Returns whether @handler_id is the ID of a handler connected to @instance.
+
+
+ whether @handler_id identifies a handler connected to @instance.
+
+
+
+
+ The instance where a signal handler is sought.
+
+
+
+ the handler ID.
+
+
+
+
+
+ Undoes the effect of a previous g_signal_handler_block() call. A
+blocked handler is skipped during signal emissions and will not be
+invoked, unblocking it (for exactly the amount of times it has been
+blocked before) reverts its "blocked" state, so the handler will be
+recognized by the signal system and is called upon future or
+currently ongoing signal emissions (since the order in which
+handlers are called during signal emissions is deterministic,
+whether the unblocked handler in question is called as part of a
+currently ongoing emission depends on how far that emission has
+proceeded yet).
+
+The @handler_id has to be a valid id of a signal handler that is
+connected to a signal of @instance and is currently blocked.
+
+
+
+
+
+
+ The instance to unblock the signal handler of.
+
+
+
+ Handler id of the handler to be unblocked.
+
+
+
+
+
+ Blocks all handlers on an instance that match @func and @data.
+
+
+
+ The instance to block handlers from.
+
+
+ The C closure callback of the handlers (useless for non-C closures).
+
+
+ The closure data of the handlers' closures.
+
+
+
+
+ Blocks all handlers on an instance that match a certain selection criteria.
+The criteria mask is passed as an OR-ed combination of #GSignalMatchType
+flags, and the criteria values are passed as arguments.
+Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC
+or %G_SIGNAL_MATCH_DATA match flags is required for successful matches.
+If no handlers were found, 0 is returned, the number of blocked handlers
+otherwise.
+
+
+ The number of handlers that matched.
+
+
+
+
+ The instance to block handlers from.
+
+
+
+ Mask indicating which of @signal_id, @detail, @closure, @func
+ and/or @data the handlers have to match.
+
+
+
+ Signal the handlers have to be connected to.
+
+
+
+ Signal detail the handlers have to be connected to.
+
+
+
+ The closure the handlers will invoke.
+
+
+
+ The C closure callback of the handlers (useless for non-C closures).
+
+
+
+ The closure data of the handlers' closures.
+
+
+
+
+
+ Destroy all signal handlers of a type instance. This function is
+an implementation detail of the #GObject dispose implementation,
+and should not be used outside of the type system.
+
+
+
+
+
+
+ The instance whose signal handlers are destroyed
+
+
+
+
+
+ Disconnects all handlers on an instance that match @data.
+
+
+
+ The instance to remove handlers from
+
+
+ the closure data of the handlers' closures
+
+
+
+
+ Disconnects all handlers on an instance that match @func and @data.
+
+
+
+ The instance to remove handlers from.
+
+
+ The C closure callback of the handlers (useless for non-C closures).
+
+
+ The closure data of the handlers' closures.
+
+
+
+
+ Disconnects all handlers on an instance that match a certain
+selection criteria. The criteria mask is passed as an OR-ed
+combination of #GSignalMatchType flags, and the criteria values are
+passed as arguments. Passing at least one of the
+%G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC or
+%G_SIGNAL_MATCH_DATA match flags is required for successful
+matches. If no handlers were found, 0 is returned, the number of
+disconnected handlers otherwise.
+
+
+ The number of handlers that matched.
+
+
+
+
+ The instance to remove handlers from.
+
+
+
+ Mask indicating which of @signal_id, @detail, @closure, @func
+ and/or @data the handlers have to match.
+
+
+
+ Signal the handlers have to be connected to.
+
+
+
+ Signal detail the handlers have to be connected to.
+
+
+
+ The closure the handlers will invoke.
+
+
+
+ The C closure callback of the handlers (useless for non-C closures).
+
+
+
+ The closure data of the handlers' closures.
+
+
+
+
+
+ Unblocks all handlers on an instance that match @func and @data.
+
+
+
+ The instance to unblock handlers from.
+
+
+ The C closure callback of the handlers (useless for non-C closures).
+
+
+ The closure data of the handlers' closures.
+
+
+
+
+ Unblocks all handlers on an instance that match a certain selection
+criteria. The criteria mask is passed as an OR-ed combination of
+#GSignalMatchType flags, and the criteria values are passed as arguments.
+Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC
+or %G_SIGNAL_MATCH_DATA match flags is required for successful matches.
+If no handlers were found, 0 is returned, the number of unblocked handlers
+otherwise. The match criteria should not apply to any handlers that are
+not currently blocked.
+
+
+ The number of handlers that matched.
+
+
+
+
+ The instance to unblock handlers from.
+
+
+
+ Mask indicating which of @signal_id, @detail, @closure, @func
+ and/or @data the handlers have to match.
+
+
+
+ Signal the handlers have to be connected to.
+
+
+
+ Signal detail the handlers have to be connected to.
+
+
+
+ The closure the handlers will invoke.
+
+
+
+ The C closure callback of the handlers (useless for non-C closures).
+
+
+
+ The closure data of the handlers' closures.
+
+
+
+
+
+ Returns whether there are any handlers connected to @instance for the
+given signal id and detail.
+
+If @detail is 0 then it will only match handlers that were connected
+without detail. If @detail is non-zero then it will match handlers
+connected both without detail and with the given detail. This is
+consistent with how a signal emitted with @detail would be delivered
+to those handlers.
+
+Since 2.46 this also checks for a non-default class closure being
+installed, as this is basically always what you want.
+
+One example of when you might use this is when the arguments to the
+signal are difficult to compute. A class implementor may opt to not
+emit the signal if no one is attached anyway, thus saving the cost
+of building the arguments.
+
+
+ %TRUE if a handler is connected to the signal, %FALSE
+ otherwise.
+
+
+
+
+ the object whose signal handlers are sought.
+
+
+
+ the signal id.
+
+
+
+ the detail.
+
+
+
+ whether blocked handlers should count as match.
+
+
+
+
+
+ Validate a signal name. This can be useful for dynamically-generated signals
+which need to be validated at run-time before actually trying to create them.
+
+See [canonical parameter names][canonical-parameter-names] for details of
+the rules for valid names. The rules for signal names are the same as those
+for property names.
+
+
+ %TRUE if @name is a valid signal name, %FALSE otherwise.
+
+
+
+
+ the canonical name of the signal
+
+
+
+
+
+ Lists the signals by id that a certain instance or interface type
+created. Further information about the signals can be acquired through
+g_signal_query().
+
+
+ Newly allocated array of signal IDs.
+
+
+
+
+
+
+ Instance or interface type.
+
+
+
+ Location to store the number of signal ids for @itype.
+
+
+
+
+
+ Given the name of the signal and the type of object it connects to, gets
+the signal's identifying integer. Emitting the signal by number is
+somewhat faster than using the name each time.
+
+Also tries the ancestors of the given type.
+
+The type class passed as @itype must already have been instantiated (for
+example, using g_type_class_ref()) for this function to work, as signals are
+always installed during class initialization.
+
+See g_signal_new() for details on allowed signal names.
+
+
+ the signal's identifying number, or 0 if no signal was found.
+
+
+
+
+ the signal's name.
+
+
+
+ the type that the signal operates on.
+
+
+
+
+
+ Given the signal's identifier, finds its name.
+
+Two different signals may have the same name, if they have differing types.
+
+
+ the signal name, or %NULL if the signal number was invalid.
+
+
+
+
+ the signal's identifying number.
+
+
+
+
+
+ Creates a new signal. (This is usually done in the class initializer.)
+
+A signal name consists of segments consisting of ASCII letters and
+digits, separated by either the `-` or `_` character. The first
+character of a signal name must be a letter. Names which violate these
+rules lead to undefined behaviour. These are the same rules as for property
+naming (see g_param_spec_internal()).
+
+When registering a signal and looking up a signal, either separator can
+be used, but they cannot be mixed. Using `-` is considerably more efficient.
+Using `_` is discouraged.
+
+If 0 is used for @class_offset subclasses cannot override the class handler
+in their class_init method by doing super_class->signal_handler = my_signal_handler.
+Instead they will have to use g_signal_override_class_handler().
+
+If @c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as
+the marshaller for this signal. In some simple cases, g_signal_new()
+will use a more optimized c_marshaller and va_marshaller for the signal
+instead of g_cclosure_marshal_generic().
+
+If @c_marshaller is non-%NULL, you need to also specify a va_marshaller
+using g_signal_set_va_marshaller() or the generic va_marshaller will
+be used.
+
+
+ the signal id
+
+
+
+
+ the name for the signal
+
+
+
+ the type this signal pertains to. It will also pertain to
+ types which are derived from this type.
+
+
+
+ a combination of #GSignalFlags specifying detail of when
+ the default handler is to be invoked. You should at least specify
+ %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST.
+
+
+
+ The offset of the function pointer in the class structure
+ for this type. Used to invoke a class method generically. Pass 0 to
+ not associate a class method slot with this signal.
+
+
+
+ the accumulator for this signal; may be %NULL.
+
+
+
+ user data for the @accumulator.
+
+
+
+ the function to translate arrays of parameter
+ values to signal emissions into C language callback invocations or %NULL.
+
+
+
+ the type of return value, or %G_TYPE_NONE for a signal
+ without a return value.
+
+
+
+ the number of parameter types to follow.
+
+
+
+ a list of types, one for each parameter.
+
+
+
+
+
+ Creates a new signal. (This is usually done in the class initializer.)
+
+This is a variant of g_signal_new() that takes a C callback instead
+of a class offset for the signal's class handler. This function
+doesn't need a function pointer exposed in the class structure of
+an object definition, instead the function pointer is passed
+directly and can be overridden by derived classes with
+g_signal_override_class_closure() or
+g_signal_override_class_handler() and chained to with
+g_signal_chain_from_overridden() or
+g_signal_chain_from_overridden_handler().
+
+See g_signal_new() for information about signal names.
+
+If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as
+the marshaller for this signal.
+
+
+ the signal id
+
+
+
+
+ the name for the signal
+
+
+
+ the type this signal pertains to. It will also pertain to
+ types which are derived from this type.
+
+
+
+ a combination of #GSignalFlags specifying detail of when
+ the default handler is to be invoked. You should at least specify
+ %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST.
+
+
+
+ a #GCallback which acts as class implementation of
+ this signal. Used to invoke a class method generically. Pass %NULL to
+ not associate a class method with this signal.
+
+
+
+ the accumulator for this signal; may be %NULL.
+
+
+
+ user data for the @accumulator.
+
+
+
+ the function to translate arrays of parameter
+ values to signal emissions into C language callback invocations or %NULL.
+
+
+
+ the type of return value, or %G_TYPE_NONE for a signal
+ without a return value.
+
+
+
+ the number of parameter types to follow.
+
+
+
+ a list of types, one for each parameter.
+
+
+
+
+
+ Creates a new signal. (This is usually done in the class initializer.)
+
+See g_signal_new() for details on allowed signal names.
+
+If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as
+the marshaller for this signal.
+
+
+ the signal id
+
+
+
+
+ the name for the signal
+
+
+
+ the type this signal pertains to. It will also pertain to
+ types which are derived from this type.
+
+
+
+ a combination of #GSignalFlags specifying detail of when
+ the default handler is to be invoked. You should at least specify
+ %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST.
+
+
+
+ The closure to invoke on signal emission; may be %NULL.
+
+
+
+ the accumulator for this signal; may be %NULL.
+
+
+
+ user data for the @accumulator.
+
+
+
+ the function to translate arrays of parameter
+ values to signal emissions into C language callback invocations or %NULL.
+
+
+
+ the type of return value, or %G_TYPE_NONE for a signal
+ without a return value.
+
+
+
+ the number of parameter types in @args.
+
+
+
+ va_list of #GType, one for each parameter.
+
+
+
+
+
+ Creates a new signal. (This is usually done in the class initializer.)
+
+See g_signal_new() for details on allowed signal names.
+
+If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as
+the marshaller for this signal.
+
+
+ the signal id
+
+
+
+
+ the name for the signal
+
+
+
+ the type this signal pertains to. It will also pertain to
+ types which are derived from this type
+
+
+
+ a combination of #GSignalFlags specifying detail of when
+ the default handler is to be invoked. You should at least specify
+ %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST
+
+
+
+ The closure to invoke on signal emission;
+ may be %NULL
+
+
+
+ the accumulator for this signal; may be %NULL
+
+
+
+ user data for the @accumulator
+
+
+
+ the function to translate arrays of
+ parameter values to signal emissions into C language callback
+ invocations or %NULL
+
+
+
+ the type of return value, or %G_TYPE_NONE for a signal
+ without a return value
+
+
+
+ the length of @param_types
+
+
+
+ an array of types, one for
+ each parameter (may be %NULL if @n_params is zero)
+
+
+
+
+
+
+
+ Overrides the class closure (i.e. the default handler) for the given signal
+for emissions on instances of @instance_type. @instance_type must be derived
+from the type to which the signal belongs.
+
+See g_signal_chain_from_overridden() and
+g_signal_chain_from_overridden_handler() for how to chain up to the
+parent class closure from inside the overridden one.
+
+
+
+
+
+
+ the signal id
+
+
+
+ the instance type on which to override the class closure
+ for the signal.
+
+
+
+ the closure.
+
+
+
+
+
+ Overrides the class closure (i.e. the default handler) for the
+given signal for emissions on instances of @instance_type with
+callback @class_handler. @instance_type must be derived from the
+type to which the signal belongs.
+
+See g_signal_chain_from_overridden() and
+g_signal_chain_from_overridden_handler() for how to chain up to the
+parent class closure from inside the overridden one.
+
+
+
+
+
+
+ the name for the signal
+
+
+
+ the instance type on which to override the class handler
+ for the signal.
+
+
+
+ the handler.
+
+
+
+
+
+ Internal function to parse a signal name into its @signal_id
+and @detail quark.
+
+
+ Whether the signal name could successfully be parsed and @signal_id_p and @detail_p contain valid return values.
+
+
+
+
+ a string of the form "signal-name::detail".
+
+
+
+ The interface/instance type that introduced "signal-name".
+
+
+
+ Location to store the signal id.
+
+
+
+ Location to store the detail quark.
+
+
+
+ %TRUE forces creation of a #GQuark for the detail.
+
+
+
+
+
+ Queries the signal system for in-depth information about a
+specific signal. This function will fill in a user-provided
+structure to hold signal-specific information. If an invalid
+signal id is passed in, the @signal_id member of the #GSignalQuery
+is 0. All members filled into the #GSignalQuery structure should
+be considered constant and have to be left untouched.
+
+
+
+
+
+
+ The signal id of the signal to query information for.
+
+
+
+ A user provided structure that is
+ filled in with constant values upon success.
+
+
+
+
+
+ Deletes an emission hook.
+
+
+
+
+
+
+ the id of the signal
+
+
+
+ the id of the emission hook, as returned by
+ g_signal_add_emission_hook()
+
+
+
+
+
+ Change the #GSignalCVaMarshaller used for a given signal. This is a
+specialised form of the marshaller that can often be used for the
+common case of a single connected signal handler and avoids the
+overhead of #GValue. Its use is optional.
+
+
+
+
+
+
+ the signal id
+
+
+
+ the instance type on which to set the marshaller.
+
+
+
+ the marshaller to set.
+
+
+
+
+
+ Stops a signal's current emission.
+
+This will prevent the default method from running, if the signal was
+%G_SIGNAL_RUN_LAST and you connected normally (i.e. without the "after"
+flag).
+
+Prints a warning if used on a signal which isn't being emitted.
+
+
+
+
+
+
+ the object whose signal handlers you wish to stop.
+
+
+
+ the signal identifier, as returned by g_signal_lookup().
+
+
+
+ the detail which the signal was emitted with.
+
+
+
+
+
+ Stops a signal's current emission.
+
+This is just like g_signal_stop_emission() except it will look up the
+signal id for you.
+
+
+
+
+
+
+ the object whose signal handlers you wish to stop.
+
+
+
+ a string of the form "signal-name::detail".
+
+
+
+
+
+ Creates a new closure which invokes the function found at the offset
+@struct_offset in the class structure of the interface or classed type
+identified by @itype.
+
+
+ a floating reference to a new #GCClosure
+
+
+
+
+ the #GType identifier of an interface or classed type
+
+
+
+ the offset of the member function of @itype's class
+ structure which is to be invoked by the new closure
+
+
+
+
+
+ The basic concept of the signal system is that of the emission
+of a signal. Signals are introduced per-type and are identified
+through strings. Signals introduced for a parent type are available
+in derived types as well, so basically they are a per-type facility
+that is inherited.
+
+A signal emission mainly involves invocation of a certain set of
+callbacks in precisely defined manner. There are two main categories
+of such callbacks, per-object ones and user provided ones.
+(Although signals can deal with any kind of instantiatable type, I'm
+referring to those types as "object types" in the following, simply
+because that is the context most users will encounter signals in.)
+The per-object callbacks are most often referred to as "object method
+handler" or "default (signal) handler", while user provided callbacks are
+usually just called "signal handler".
+
+The object method handler is provided at signal creation time (this most
+frequently happens at the end of an object class' creation), while user
+provided handlers are frequently connected and disconnected to/from a
+certain signal on certain object instances.
+
+A signal emission consists of five stages, unless prematurely stopped:
+
+1. Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals
+
+2. Invocation of normal user-provided signal handlers (where the @after
+ flag is not set)
+
+3. Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals
+
+4. Invocation of user provided signal handlers (where the @after flag is set)
+
+5. Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals
+
+The user-provided signal handlers are called in the order they were
+connected in.
+
+All handlers may prematurely stop a signal emission, and any number of
+handlers may be connected, disconnected, blocked or unblocked during
+a signal emission.
+
+There are certain criteria for skipping user handlers in stages 2 and 4
+of a signal emission.
+
+First, user handlers may be blocked. Blocked handlers are omitted during
+callback invocation, to return from the blocked state, a handler has to
+get unblocked exactly the same amount of times it has been blocked before.
+
+Second, upon emission of a %G_SIGNAL_DETAILED signal, an additional
+@detail argument passed in to g_signal_emit() has to match the detail
+argument of the signal handler currently subject to invocation.
+Specification of no detail argument for signal handlers (omission of the
+detail part of the signal specification upon connection) serves as a
+wildcard and matches any detail argument passed in to emission.
+
+While the @detail argument is typically used to pass an object property name
+(as with #GObject::notify), no specific format is mandated for the detail
+string, other than that it must be non-empty.
+
+## Memory management of signal handlers # {#signal-memory-management}
+
+If you are connecting handlers to signals and using a #GObject instance as
+your signal handler user data, you should remember to pair calls to
+g_signal_connect() with calls to g_signal_handler_disconnect() or
+g_signal_handlers_disconnect_by_func(). While signal handlers are
+automatically disconnected when the object emitting the signal is finalised,
+they are not automatically disconnected when the signal handler user data is
+destroyed. If this user data is a #GObject instance, using it from a
+signal handler after it has been finalised is an error.
+
+There are two strategies for managing such user data. The first is to
+disconnect the signal handler (using g_signal_handler_disconnect() or
+g_signal_handlers_disconnect_by_func()) when the user data (object) is
+finalised; this has to be implemented manually. For non-threaded programs,
+g_signal_connect_object() can be used to implement this automatically.
+Currently, however, it is unsafe to use in threaded programs.
+
+The second is to hold a strong reference on the user data until after the
+signal is disconnected for other reasons. This can be implemented
+automatically using g_signal_connect_data().
+
+The first approach is recommended, as the second approach can result in
+effective memory leaks of the user data if the signal handler is never
+disconnected for some reason.
+
+
+ Set the callback for a source as a #GClosure.
+
+If the source is not one of the standard GLib types, the @closure_callback
+and @closure_marshal fields of the #GSourceFuncs structure must have been
+filled in with pointers to appropriate functions.
+
+
+
+
+
+
+ the source
+
+
+
+ a #GClosure
+
+
+
+
+
+ Sets a dummy callback for @source. The callback will do nothing, and
+if the source expects a #gboolean return value, it will return %TRUE.
+(If the source expects any other type of return value, it will return
+a 0/%NULL value; whatever g_value_init() initializes a #GValue to for
+that type.)
+
+If the source is not one of the standard GLib types, the
+@closure_callback and @closure_marshal fields of the #GSourceFuncs
+structure must have been filled in with pointers to appropriate
+functions.
+
+
+
+
+
+
+ the source
+
+
+
+
+
+ Return a newly allocated string, which describes the contents of a
+#GValue. The main purpose of this function is to describe #GValue
+contents for debugging output, the way in which the contents are
+described may change between different GLib versions.
+
+
+ Newly allocated string.
+
+
+
+
+ #GValue which contents are to be described.
+
+
+
+
+
+ Adds a #GTypeClassCacheFunc to be called before the reference count of a
+class goes from one to zero. This can be used to prevent premature class
+destruction. All installed #GTypeClassCacheFunc functions will be chained
+until one of them returns %TRUE. 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.
+
+
+
+
+
+
+ data to be passed to @cache_func
+
+
+
+ a #GTypeClassCacheFunc
+
+
+
+
+
+ Registers a private class structure for a classed type;
+when the class is allocated, the private structures for
+the class and all of its parent types are allocated
+sequentially in the same memory block as the public
+structures, and are zero-filled.
+
+This function should be called in the
+type's get_type() function after the type is registered.
+The private structure can be retrieved using the
+G_TYPE_CLASS_GET_PRIVATE() macro.
+
+
+
+
+
+
+ GType of a classed type
+
+
+
+ size of private structure
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Adds a function to be called after an interface vtable is
+initialized for any class (i.e. after the @interface_init
+member of #GInterfaceInfo has been called).
+
+This function is useful when you want to check an invariant
+that depends on the interfaces of a class. For instance, the
+implementation of #GObject uses this facility to check that an
+object implements all of the properties that are defined on its
+interfaces.
+
+
+
+
+
+
+ data to pass to @check_func
+
+
+
+ function to be called after each interface
+ is initialized
+
+
+
+
+
+ Adds @interface_type to the dynamic @instance_type. The information
+contained in the #GTypePlugin structure pointed to by @plugin
+is used to manage the relationship.
+
+
+
+
+
+
+ #GType value of an instantiatable type
+
+
+
+ #GType value of an interface type
+
+
+
+ #GTypePlugin structure to retrieve the #GInterfaceInfo from
+
+
+
+
+
+ Adds @interface_type to the static @instance_type.
+The information contained in the #GInterfaceInfo structure
+pointed to by @info is used to manage the relationship.
+
+
+
+
+
+
+ #GType value of an instantiatable type
+
+
+
+ #GType value of an interface type
+
+
+
+ #GInterfaceInfo structure for this
+ (@instance_type, @interface_type) combination
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Private helper function to aid implementation of the
+G_TYPE_CHECK_INSTANCE() macro.
+
+
+ %TRUE if @instance is valid, %FALSE otherwise
+
+
+
+
+ a valid #GTypeInstance structure
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Return a newly allocated and 0-terminated array of type IDs, listing
+the child types of @type.
+
+
+ Newly allocated
+ and 0-terminated array of child types, free with g_free()
+
+
+
+
+
+
+ the parent type
+
+
+
+ location to store the length of
+ the returned array, or %NULL
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This function is essentially the same as g_type_class_ref(),
+except that the classes reference count isn't incremented.
+As a consequence, this function may return %NULL if the class
+of the type passed in does not currently exist (hasn't been
+referenced before).
+
+
+ the #GTypeClass
+ structure for the given type ID or %NULL if the class does not
+ currently exist
+
+
+
+
+ type ID of a classed type
+
+
+
+
+
+ A more efficient version of g_type_class_peek() which works only for
+static types.
+
+
+ the #GTypeClass
+ structure for the given type ID or %NULL if the class does not
+ currently exist or is dynamically loaded
+
+
+
+
+ type ID of a classed type
+
+
+
+
+
+ Increments the reference count of the class structure belonging to
+@type. This function will demand-create the class if it doesn't
+exist already.
+
+
+ the #GTypeClass
+ structure for the given type ID
+
+
+
+
+ type ID of a classed type
+
+
+
+
+
+ Creates and initializes an instance of @type if @type is valid and
+can be instantiated. The type system only performs basic allocation
+and structure setups for instances: actual instance creation should
+happen through functions supplied by the type's fundamental type
+implementation. So use of g_type_create_instance() is reserved for
+implementers of fundamental types only. E.g. instances of the
+#GObject hierarchy should be created via g_object_new() and never
+directly through g_type_create_instance() which doesn't handle things
+like singleton objects or object construction.
+
+The extended members of the returned instance are guaranteed to be filled
+with zeros.
+
+Note: Do not use this function, unless you're implementing a
+fundamental type. Also language bindings should not use this
+function, but g_object_new() instead.
+
+
+ an allocated and initialized instance, subject to further
+ treatment by the fundamental type implementation
+
+
+
+
+ an instantiatable type to create an instance for
+
+
+
+
+
+ If the interface type @g_type is currently in use, returns its
+default interface vtable.
+
+
+ the default
+ vtable for the interface, or %NULL if the type is not currently
+ in use
+
+
+
+
+ an interface type
+
+
+
+
+
+ Increments the reference count for the interface type @g_type,
+and returns the default interface vtable for the type.
+
+If the type is not currently in use, then the default vtable
+for the type will be created and initialized by calling
+the base interface init and default vtable init functions for
+the type (the @base_init and @class_init members of #GTypeInfo).
+Calling g_type_default_interface_ref() is useful when you
+want to make sure that signals and properties for an interface
+have been installed.
+
+
+ the default
+ vtable for the interface; call g_type_default_interface_unref()
+ when you are done using the interface.
+
+
+
+
+ an interface type
+
+
+
+
+
+ Decrements the reference count for the type corresponding to the
+interface default vtable @g_iface. If the type is dynamic, then
+when no one is using the interface and all references have
+been released, the finalize function for the interface's default
+vtable (the @class_finalize member of #GTypeInfo) will be called.
+
+
+
+
+
+
+ the default vtable
+ structure for an interface, as returned by g_type_default_interface_ref()
+
+
+
+
+
+ Returns the length of the ancestry of the passed in type. This
+includes the type itself, so that e.g. a fundamental type has depth 1.
+
+
+ the depth of @type
+
+
+
+
+ a #GType
+
+
+
+
+
+ Ensures that the indicated @type has been registered with the
+type system, and its _class_init() method has been run.
+
+In theory, simply calling the type's _get_type() method (or using
+the corresponding macro) is supposed take care of this. However,
+_get_type() methods are often marked %G_GNUC_CONST for performance
+reasons, even though this is technically incorrect (since
+%G_GNUC_CONST requires that the function not have side effects,
+which _get_type() methods do on the first call). As a result, if
+you write a bare call to a _get_type() macro, it may get optimized
+out by the compiler. Using g_type_ensure() guarantees that the
+type's _get_type() method is called.
+
+
+
+
+
+
+ a #GType
+
+
+
+
+
+ Frees an instance of a type, returning it to the instance pool for
+the type, if there is one.
+
+Like g_type_create_instance(), this function is reserved for
+implementors of fundamental types.
+
+
+
+
+
+
+ an instance of a type
+
+
+
+
+
+ Look up the type ID from a given type name, returning 0 if no type
+has been registered under this name (this is the preferred method
+to find out by name whether a specific type has been registered
+yet).
+
+
+ corresponding type ID or 0
+
+
+
+
+ type name to look up
+
+
+
+
+
+ Internal function, used to extract the fundamental type ID portion.
+Use G_TYPE_FUNDAMENTAL() instead.
+
+
+ fundamental type ID
+
+
+
+
+ valid type ID
+
+
+
+
+
+ Returns the next free fundamental type id which can be used to
+register a new fundamental type with g_type_register_fundamental().
+The returned type ID represents the highest currently registered
+fundamental type identifier.
+
+
+ the next available fundamental type ID to be registered,
+ or 0 if the type system ran out of fundamental type IDs
+
+
+
+
+ Returns the number of instances allocated of the particular type;
+this is only available if GLib is built with debugging support and
+the instance_count debug flag is set (by setting the GOBJECT_DEBUG
+variable to include instance-count).
+
+
+ the number of instances allocated of the given type;
+ if instance counts are not available, returns 0.
+
+
+
+
+ a #GType
+
+
+
+
+
+ Returns the #GTypePlugin structure for @type.
+
+
+ the corresponding plugin
+ if @type is a dynamic type, %NULL otherwise
+
+
+
+
+ #GType to retrieve the plugin for
+
+
+
+
+
+ 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().
+
+
+ the data, or %NULL if no data was found
+
+
+
+
+ a #GType
+
+
+
+ a #GQuark id to identify the data
+
+
+
+
+
+ Returns an opaque serial number that represents the state of the set
+of registered types. Any time a type is registered this serial changes,
+which means you can cache information based on type lookups (such as
+g_type_from_name()) and know if the cache is still valid at a later
+time by comparing the current serial with the one at the type lookup.
+
+
+ An unsigned int, representing the state of type registrations
+
+
+
+
+ This function used to initialise the type system. Since GLib 2.36,
+the type system is initialised automatically and this function does
+nothing.
+ the type system is now initialised automatically
+
+
+
+
+
+
+ This function used to initialise the type system with debugging
+flags. Since GLib 2.36, the type system is initialised automatically
+and this function does nothing.
+
+If you need to enable debugging features, use the GOBJECT_DEBUG
+environment variable.
+ the type system is now initialised automatically
+
+
+
+
+
+
+ bitwise combination of #GTypeDebugFlags values for
+ debugging purposes
+
+
+
+
+
+ Adds @prerequisite_type to the list of prerequisites of @interface_type.
+This means that any type implementing @interface_type must also implement
+@prerequisite_type. Prerequisites can be thought of as an alternative to
+interface derivation (which GType doesn't support). An interface can have
+at most one instantiatable prerequisite type.
+
+
+
+
+
+
+ #GType value of an interface type
+
+
+
+ #GType value of an interface or instantiatable type
+
+
+
+
+
+ Returns the #GTypePlugin structure for the dynamic interface
+@interface_type which has been added to @instance_type, or %NULL
+if @interface_type has not been added to @instance_type or does
+not have a #GTypePlugin structure. See g_type_add_interface_dynamic().
+
+
+ the #GTypePlugin for the dynamic
+ interface @interface_type of @instance_type
+
+
+
+
+ #GType of an instantiatable type
+
+
+
+ #GType of an interface type
+
+
+
+
+
+ Returns the most specific instantiatable prerequisite of an
+interface type. If the interface type has no instantiatable
+prerequisite, %G_TYPE_INVALID is returned.
+
+See g_type_interface_add_prerequisite() for more information
+about prerequisites.
+
+
+ the instantiatable prerequisite type or %G_TYPE_INVALID if none
+
+
+
+
+ an interface type
+
+
+
+
+
+ Returns the #GTypeInterface structure of an interface to which the
+passed in class conforms.
+
+
+ the #GTypeInterface
+ structure of @iface_type if implemented by @instance_class, %NULL
+ otherwise
+
+
+
+
+ a #GTypeClass structure
+
+
+
+ an interface ID which this class conforms to
+
+
+
+
+
+ Returns the prerequisites of an interfaces type.
+
+
+ a
+ newly-allocated zero-terminated array of #GType containing
+ the prerequisites of @interface_type
+
+
+
+
+
+
+ an interface type
+
+
+
+ location to return the number
+ of prerequisites, or %NULL
+
+
+
+
+
+ Return a newly allocated and 0-terminated array of type IDs, listing
+the interface types that @type conforms to.
+
+
+ Newly allocated
+ and 0-terminated array of interface types, free with g_free()
+
+
+
+
+
+
+ the type to list interface types for
+
+
+
+ location to store the length of
+ the returned array, or %NULL
+
+
+
+
+
+ If @is_a_type is a derivable type, check whether @type is a
+descendant of @is_a_type. If @is_a_type is an interface, check
+whether @type conforms to it.
+
+
+ %TRUE if @type is a @is_a_type
+
+
+
+
+ type to check ancestry for
+
+
+
+ possible ancestor of @type or interface that @type
+ could conform to
+
+
+
+
+
+ Get the unique name that is assigned to a type ID. Note that this
+function (like all other GType API) cannot cope with invalid type
+IDs. %G_TYPE_INVALID may be passed to this function, as may be any
+other validly registered type ID, but randomized type IDs should
+not be passed in and will most likely lead to a crash.
+
+
+ static type name or %NULL
+
+
+
+
+ type to return name for
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Given a @leaf_type and a @root_type which is contained in its
+ancestry, return the type that @root_type is the immediate parent
+of. In other words, this function determines the type that is
+derived directly from @root_type which is also a base class of
+@leaf_type. Given a root type and a leaf type, this function can
+be used to determine the types and order in which the leaf type is
+descended from the root type.
+
+
+ immediate child of @root_type and ancestor of @leaf_type
+
+
+
+
+ descendant of @root_type and the type to be returned
+
+
+
+ immediate parent of the returned type
+
+
+
+
+
+ Return the direct parent type of the passed in type. If the passed
+in type has no parent, i.e. is a fundamental type, 0 is returned.
+
+
+ the parent type
+
+
+
+
+ the derived type
+
+
+
+
+
+ Get the corresponding quark of the type IDs name.
+
+
+ the type names quark or 0
+
+
+
+
+ type to return quark of type name for
+
+
+
+
+
+ Queries the type system for information about a specific type.
+This function will fill in a user-provided structure to hold
+type-specific information. If an invalid #GType is passed in, the
+@type member of the #GTypeQuery is 0. All members filled into the
+#GTypeQuery structure should be considered constant and have to be
+left untouched.
+
+
+
+
+
+
+ #GType of a static, classed type
+
+
+
+ a user provided structure that is
+ filled in with constant values upon success
+
+
+
+
+
+ Registers @type_name as the name of a new dynamic type derived from
+@parent_type. The type system uses the information contained in the
+#GTypePlugin structure pointed to by @plugin to manage the type and its
+instances (if not abstract). The value of @flags determines the nature
+(e.g. abstract or not) of the type.
+
+
+ the new type identifier or %G_TYPE_INVALID if registration failed
+
+
+
+
+ type from which this type will be derived
+
+
+
+ 0-terminated string used as the name of the new type
+
+
+
+ #GTypePlugin structure to retrieve the #GTypeInfo from
+
+
+
+ bitwise combination of #GTypeFlags values
+
+
+
+
+
+ Registers @type_id as the predefined identifier and @type_name as the
+name of a fundamental type. If @type_id is already registered, or a
+type named @type_name is already registered, the behaviour is undefined.
+The type system uses the information contained in the #GTypeInfo structure
+pointed to by @info and the #GTypeFundamentalInfo structure pointed to by
+@finfo to manage the type and its instances. The value of @flags determines
+additional characteristics of the fundamental type.
+
+
+ the predefined type identifier
+
+
+
+
+ a predefined type identifier
+
+
+
+ 0-terminated string used as the name of the new type
+
+
+
+ #GTypeInfo structure for this type
+
+
+
+ #GTypeFundamentalInfo structure for this type
+
+
+
+ bitwise combination of #GTypeFlags values
+
+
+
+
+
+ Registers @type_name as the name of a new static type derived from
+@parent_type. The type system uses the information contained in the
+#GTypeInfo structure pointed to by @info to manage the type and its
+instances (if not abstract). The value of @flags determines the nature
+(e.g. abstract or not) of the type.
+
+
+ the new type identifier
+
+
+
+
+ type from which this type will be derived
+
+
+
+ 0-terminated string used as the name of the new type
+
+
+
+ #GTypeInfo structure for this type
+
+
+
+ bitwise combination of #GTypeFlags values
+
+
+
+
+
+ Registers @type_name as the name of a new static type derived from
+@parent_type. The value of @flags determines the nature (e.g.
+abstract or not) of the type. It works by filling a #GTypeInfo
+struct and calling g_type_register_static().
+
+
+ the new type identifier
+
+
+
+
+ type from which this type will be derived
+
+
+
+ 0-terminated string used as the name of the new type
+
+
+
+ size of the class structure (see #GTypeInfo)
+
+
+
+ location of the class initialization function (see #GTypeInfo)
+
+
+
+ size of the instance structure (see #GTypeInfo)
+
+
+
+ location of the instance initialization function (see #GTypeInfo)
+
+
+
+ bitwise combination of #GTypeFlags values
+
+
+
+
+
+ Removes a previously installed #GTypeClassCacheFunc. The cache
+maintained by @cache_func has to be empty when calling
+g_type_remove_class_cache_func() to avoid leaks.
+
+
+
+
+
+
+ data that was given when adding @cache_func
+
+
+
+ a #GTypeClassCacheFunc
+
+
+
+
+
+ Removes an interface check function added with
+g_type_add_interface_check().
+
+
+
+
+
+
+ callback data passed to g_type_add_interface_check()
+
+
+
+ callback function passed to g_type_add_interface_check()
+
+
+
+
+
+ Attaches arbitrary data to a type.
+
+
+
+
+
+
+ a #GType
+
+
+
+ a #GQuark id to identify the data
+
+
+
+ the data
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Returns the location of the #GTypeValueTable associated with @type.
+
+Note that this function should only be used from source code
+that implements or has internal knowledge of the implementation of
+@type.
+
+
+ location of the #GTypeValueTable associated with @type or
+ %NULL if there is no #GTypeValueTable associated with @type
+
+
+
+
+ a #GType
+
+
+
+
+
+ The prime purpose of a #GValueArray is for it to be used as an
+object property that holds an array of values. A #GValueArray wraps
+an array of #GValue elements in order for it to be used as a boxed
+type through %G_TYPE_VALUE_ARRAY.
+
+#GValueArray is deprecated in favour of #GArray since GLib 2.32. It
+is possible to create a #GArray that behaves like a #GValueArray by
+using the size of #GValue as the element size, and by setting
+g_value_unset() as the clear function using g_array_set_clear_func(),
+for instance, the following code:
+
+|[<!-- language="C" -->
+ GValueArray *array = g_value_array_new (10);
+]|
+
+can be replaced by:
+
+|[<!-- language="C" -->
+ GArray *array = g_array_sized_new (FALSE, TRUE, sizeof (GValue), 10);
+ g_array_set_clear_func (array, (GDestroyNotify) g_value_unset);
+]|
+
+
+ Registers a value transformation function for use in g_value_transform().
+A previously registered transformation function for @src_type and @dest_type
+will be replaced.
+
+
+
+
+
+
+ Source type.
+
+
+
+ Target type.
+
+
+
+ a function which transforms values of type @src_type
+ into value of type @dest_type
+
+
+
+
+
+ Returns whether a #GValue of type @src_type can be copied into
+a #GValue of type @dest_type.
+
+
+ %TRUE if g_value_copy() is possible with @src_type and @dest_type.
+
+
+
+
+ source type to be copied.
+
+
+
+ destination type for copying.
+
+
+
+
+
+ Check whether g_value_transform() is able to transform values
+of type @src_type into values of type @dest_type. Note that for
+the types to be transformable, they must be compatible or a
+transformation function must be registered.
+
+
+ %TRUE if the transformation is possible, %FALSE otherwise.
+
+
+
+
+ Source type.
+
+
+
+ Target type.
+
+
+
+
+
+
diff --git a/docs/reference/gobject/gobject.toml.in b/docs/reference/gobject/gobject.toml.in
new file mode 100644
index 000000000..8f14ff542
--- /dev/null
+++ b/docs/reference/gobject/gobject.toml.in
@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: LGPL-2.1-or-later
+# Copyright 2023 Matthias Clasen
+# Copyright 2023 Philip Withnall
+
+[library]
+name = "GObject"
+version = "@VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/glib/"
+repository_url = "https://gitlab.gnome.org/GNOME/glib.git"
+website_url = "https://www.gtk.org"
+docs_url = "https://docs.gtk.org/gobject/"
+authors = "GLib Development Team"
+license = "LGPL-2.1-or-later"
+description = "The base type system and object class"
+devhelp = true
+search_index = true
+dependencies = ["GLib-2.0"]
+
+ [dependencies."GLib-2.0"]
+ name = "GLib"
+ description = "The base utility library"
+ docs_url = "https://docs.gtk.org/glib/"
+
+related = ["GModule-2.0", "Gio-2.0"]
+
+ [related."GModule-2.0"]
+ name = "GModule"
+ description = "Portable API for dynamically loading modules"
+ docs_url = "https://docs.gtk.org/gmodule/"
+
+ [related."Gio-2.0"]
+ name = "GIO"
+ description = "GObject Interfaces and Objects, Networking, IPC, and I/O"
+ docs_url = "https://docs.gtk.org/gio/"
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[extra]
+urlmap_file = "urlmap.js"
+# The same order will be used when generating the index
+content_files = [
+]
+content_images = [
+]
+
+# This is the anonymous union inside GValue; we don't need it
+# as a type, and including it just generates a dummy union
+# definition
+[[object]]
+name = "_Value__data__union"
+hidden = true
diff --git a/docs/reference/gobject/meson.build b/docs/reference/gobject/meson.build
index dd3e53dbf..83f91a539 100644
--- a/docs/reference/gobject/meson.build
+++ b/docs/reference/gobject/meson.build
@@ -68,3 +68,27 @@ if get_option('man')
install_dir: man1_dir)
endforeach
endif
+
+# gi-docgen version
+expand_content_files = [
+]
+
+gobject_gir = meson.current_source_dir() / 'GObject-2.0.gir'
+gobject_toml = configure_file(input: 'gobject.toml.in', output: 'gobject.toml', configuration: toml_conf)
+
+custom_target('gobject-docs',
+ input: [ gobject_toml, gobject_gir ],
+ output: 'gobject',
+ command: [
+ gidocgen,
+ 'generate',
+ gidocgen_common_args,
+ '--config=@INPUT0@',
+ '--output-dir=@OUTPUT@',
+ '--content-dir=@0@'.format(meson.current_source_dir()),
+ '--add-include-path=@0@'.format(meson.current_source_dir() / '../glib'),
+ '@INPUT1@',
+ ],
+ build_by_default: true,
+ depend_files: expand_content_files,
+)
diff --git a/docs/reference/gobject/urlmap.js b/docs/reference/gobject/urlmap.js
new file mode 100644
index 000000000..b1f0962b0
--- /dev/null
+++ b/docs/reference/gobject/urlmap.js
@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: LGPL-2.1-or-later
+// SPDX-FileCopyrightText: 2023 Matthias Clasen
+var baseURLs = [
+ [ 'GLib', 'https://docs.gtk.org/glib/' ],
+ [ 'GModule', 'https://docs.gtk.org/gmodule/' ],
+ [ 'GObject', 'https://docs.gtk.org/gobject/' ],
+ [ 'Gio', 'https://docs.gtk.org/gio/' ],
+ [ 'Gtk', 'https://docs.gtk.org/gtk4/' ],
+];
diff --git a/docs/reference/meson.build b/docs/reference/meson.build
index c417ffecb..8dbc50a4f 100644
--- a/docs/reference/meson.build
+++ b/docs/reference/meson.build
@@ -53,6 +53,25 @@ if get_option('gtk_doc')
endif
endif
-subdir('gio')
-subdir('glib')
-subdir('gobject')
+# gi-docgen version
+if get_option('gtk_doc')
+ gidocgen_dep = dependency('gi-docgen', version: '>= 2023.1',
+ fallback: ['gi-docgen', 'dummy_dep'],
+ required: true)
+
+ toml_conf = configuration_data()
+ toml_conf.set('VERSION', meson.project_version())
+
+ gidocgen = find_program('gi-docgen', required: true)
+
+ gidocgen_common_args = [
+ '--quiet',
+ '--no-namespace-dir',
+ '--fatal-warnings',
+ ]
+
+ subdir('glib')
+ subdir('gmodule')
+ subdir('gobject')
+ subdir('gio')
+endif
diff --git a/subprojects/gi-docgen.wrap b/subprojects/gi-docgen.wrap
new file mode 100644
index 000000000..022c7ac34
--- /dev/null
+++ b/subprojects/gi-docgen.wrap
@@ -0,0 +1,5 @@
+[wrap-git]
+directory=gi-docgen
+url=https://gitlab.gnome.org/GNOME/gi-docgen.git
+revision=2023.1
+depth=1