diff --git a/Gir_GstNet.toml b/Gir_GstNet.toml
new file mode 100644
index 000000000..fe5847d5b
--- /dev/null
+++ b/Gir_GstNet.toml
@@ -0,0 +1,14 @@
+[options]
+girs_dir = "gir-files"
+library = "GstNet"
+version = "1.0"
+min_cfg_version = "1.0"
+target_path = "gstreamer-net-sys"
+work_mode = "sys"
+
+external_libraries = [
+ "GLib",
+ "GObject",
+ "Gio",
+ "Gst",
+]
diff --git a/gir-files/Gio-2.0.gir b/gir-files/Gio-2.0.gir
new file mode 100644
index 000000000..035bdf5a6
--- /dev/null
+++ b/gir-files/Gio-2.0.gir
@@ -0,0 +1,92999 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #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
+
+
+
+
+ an 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 '.'.
+
+ %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().
+
+
+
+
+
+ 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().
+
+
+
+
+
+ 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 an desktop-file based application with Exec key `totem
+%U` and a single URI, `sftp://foo/file.avi`, then
+`/home/user/.gvfs/sftp on foo/file.avi` will be passed. This will
+only work if a set of suitable GIO extensions (such as gvfs 2.26
+compiled with FUSE support), is available and operational; if this
+is not the case, the URI will be passed unmodified to the application.
+Some URIs, such as `mailto:`, of course cannot be mapped to a POSIX
+path (in gvfs there's no FUSE mount for it); such URIs will be
+passed unmodified to the application.
+
+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
+
+
+
+
+
+ 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.
+
+
+
+
+
+ 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.
+
+ %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.
+
+
+
+
+
+ the uri to show
+
+
+
+
+
+
+
+
+
+ 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 <em>may not</em> 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 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 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 @launch_context to get information
+about the details of the launcher (like what screen it is on).
+On error, @error will be set accordingly.
+
+To launch the application without arguments pass a %NULL @files list.
+
+Note that even if the launch is successful the application launched
+can fail to start if it runs into problems during startup. There is
+no way to detect this.
+
+Some URIs can be changed when passed through a GFile (for instance
+unsupported URIs with strange formats like mailto:), so if you have
+a textual URI you want to pass in as argument, consider using
+g_app_info_launch_uris() instead.
+
+The launched application inherits the environment of the launching
+process, but it can be modified with g_app_launch_context_setenv()
+and g_app_launch_context_unsetenv().
+
+On UNIX, this function sets the `GIO_LAUNCHED_DESKTOP_FILE`
+environment variable with the path of the launched desktop file and
+`GIO_LAUNCHED_DESKTOP_FILE_PID` to the process id of the launched
+process. This can be used to ignore `GIO_LAUNCHED_DESKTOP_FILE`,
+should it be inherited by further processes. The `DISPLAY` and
+`DESKTOP_STARTUP_ID` environment variables are also set, based
+on information provided in @launch_context.
+
+ %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 @launch_context to get information
+about the details of the launcher (like what screen it is on).
+On error, @error will be set accordingly.
+
+To launch the application without arguments pass a %NULL @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
+
+
+
+
+
+ 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 <em>may not</em> 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.
+
+ 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 @launch_context to get information
+about the details of the launcher (like what screen it is on).
+On error, @error will be set accordingly.
+
+To launch the application without arguments pass a %NULL @files list.
+
+Note that even if the launch is successful the application launched
+can fail to start if it runs into problems during startup. There is
+no way to detect this.
+
+Some URIs can be changed when passed through a GFile (for instance
+unsupported URIs with strange formats like mailto:), so if you have
+a textual URI you want to pass in as argument, consider using
+g_app_info_launch_uris() instead.
+
+The launched application inherits the environment of the launching
+process, but it can be modified with g_app_launch_context_setenv()
+and g_app_launch_context_unsetenv().
+
+On UNIX, this function sets the `GIO_LAUNCHED_DESKTOP_FILE`
+environment variable with the path of the launched desktop file and
+`GIO_LAUNCHED_DESKTOP_FILE_PID` to the process id of the launched
+process. This can be used to ignore `GIO_LAUNCHED_DESKTOP_FILE`,
+should it be inherited by further processes. The `DISPLAY` and
+`DESKTOP_STARTUP_ID` environment variables are also set, based
+on information provided in @launch_context.
+
+ %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 @launch_context to get information
+about the details of the launcher (like what screen it is on).
+On error, @error will be set accordingly.
+
+To launch the application without arguments pass a %NULL @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
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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
+
+
+
+
+
+
+
+ #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
+`DESKTOP_STARTUP_ID` for the launched operation, if supported.
+
+Startup notification IDs are defined in the
+[FreeDesktop.Org Startup Notifications standard](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt").
+
+ 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
+`DESKTOP_STARTUP_ID` for the launched operation, if supported.
+
+Startup notification IDs are defined in the
+[FreeDesktop.Org Startup Notifications standard](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt").
+
+ 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 ::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.
+
+
+
+
+
+ the startup notification id for the failed launch
+
+
+
+
+
+ The ::launched signal is emitted when a #GAppInfo is successfully
+launched. The @platform_data is an GVariant dictionary mapping
+strings to variants (ie a{sv}), which contains additional,
+platform-specific data about this launch. On UNIX, at least the
+"pid" and "startup-notification-id" keys will be present.
+
+
+
+
+
+ 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
+the always the current instance. On Linux, the D-Bus session bus
+is used for communication.
+
+The use of #GApplication differs from some other commonly-used
+uniqueness libraries (such as libunique) in important ways. The
+application is not expected to manually register itself and check
+if it is the primary instance. Instead, the main() function of a
+#GApplication should do very little more than instantiating the
+application instance, possibly connecting signal handlers, then
+calling g_application_run(). All checks for uniqueness are done
+internally. If the application is the primary instance then the
+startup signal is emitted and the mainloop runs. If the application
+is not the primary instance then a signal is sent to the primary
+instance and g_application_run() promptly returns. See the code
+examples below.
+
+If used, the expected form of an application identifier is very close
+to that of of a
+[D-Bus bus name](http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface).
+Examples include: "com.example.MyApp", "org.example.internal-apps.Calculator".
+For details on valid application identifiers, see g_application_id_is_valid().
+
+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://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-open.c).
+
+For an example of using actions with GApplication, see
+[gapplication-example-actions.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-actions.c).
+
+For an example of using extra D-Bus hooks with GApplication, see
+[gapplication-example-dbushooks.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-dbushooks.c).
+
+
+
+ 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().
+
+For convenience, the restrictions on application identifiers are
+reproduced here:
+
+- Application identifiers must contain only the ASCII characters
+ "[A-Z][a-z][0-9]_-." and must not begin with a digit.
+
+- Application identifiers must contain at least one '.' (period)
+ character (and thus at least two elements).
+
+- Application identifiers must not begin or end with a '.' (period)
+ character.
+
+- Application identifiers must not contain consecutive '.' (period)
+ characters.
+
+- Application identifiers must not exceed 255 characters.
+
+ %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.
+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 &as
+- for %G_OPTION_ARG_FILENAME_ARRAY, use ^aay
+
+
+
+
+
+ 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 currenty 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().
+
+
+
+
+
+ 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.
+
+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][gapplication-example-cmdline2]
+for an example.
+
+If, after the above is done, the use count of the application is zero
+then the exit status is returned immediately. If the use count is
+non-zero then the default main context is iterated until the use count
+falls to zero, at which point 0 is returned.
+
+If the %G_APPLICATION_IS_SERVICE flag is set, then the service will
+run for as much as 10 seconds with a use count of zero while waiting
+for the message that caused the activation to arrive. After that,
+if the use count falls to zero the application will exit immediately,
+except in the case that g_application_set_inactivity_timeout() is in
+use.
+
+This function sets the prgname (g_set_prgname()), if not already set,
+to the basename of argv[0].
+
+Much like g_main_loop_run(), this function will acquire the main context
+for the duration that the application is running.
+
+Since 2.40, applications that are not explicitly flagged as services
+or launchers (ie: neither %G_APPLICATION_IS_SERVICE or
+%G_APPLICATION_IS_LAUNCHER are given as flags) will check (from the
+default handler for local_command_line) if "--gapplication-service"
+was given in the command line. If this flag is present then normal
+commandline processing is interrupted and the
+%G_APPLICATION_IS_SERVICE flag is set. This provides a "compromise"
+solution whereby running an application directly from the commandline
+will invoke it in the normal way (which can be useful for debugging)
+while still allowing applications to be D-Bus activated in service
+mode. The D-Bus service file should invoke the executable with
+"--gapplication-service" as the sole commandline argument. This
+approach is suitable for use by most graphical applications but
+should not be used from applications like editors that need precise
+control over when processes invoked via the commandline will exit and
+what their exit status will be.
+
+ 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
+
+
+
+
+
+ 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 ::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://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline.c)
+
+In more complicated cases, the handling of the comandline can be
+split between the launcher and the primary instance.
+|[<!-- language="C" -->
+static gboolean
+ test_local_cmdline (GApplication *application,
+ gchar ***arguments,
+ gint *exit_status)
+{
+ gint i, j;
+ gchar **argv;
+
+ argv = *arguments;
+
+ i = 1;
+ while (argv[i])
+ {
+ if (g_str_has_prefix (argv[i], "--local-"))
+ {
+ g_print ("handling argument %s locally\n", argv[i]);
+ g_free (argv[i]);
+ for (j = i; argv[j]; j++)
+ argv[j] = argv[j + 1];
+ }
+ else
+ {
+ g_print ("not handling argument %s locally\n", argv[i]);
+ i++;
+ }
+ }
+
+ *exit_status = 0;
+
+ return FALSE;
+}
+
+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://git.gnome.org/browse/glib/tree/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://git.gnome.org/browse/glib/tree/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 DBus daemon capable of passing file descriptors.
+If stdin is not available then %NULL will be returned. In the
+future, support may be expanded to other platforms.
+
+You must only call this function once per commandline invocation.
+
+ 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 there 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.
+
+ 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.
+
+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 DBus daemon capable of passing file descriptors.
+If stdin is not available then %NULL will be returned. In the
+future, support may be expanded to other platforms.
+
+You must only call this function once per commandline invocation.
+
+ 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
+
+
+ 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
+
+
+
+
+
+ #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.
+
+
+
+ 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);
+
+ 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.
+
+
+
+
+
+ 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 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 a 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 a owner.
+
+This is also invoked when the #GDBusConection 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.
+
+ a #GIcon for the given
+ @bytes, or %NULL on error.
+
+
+
+
+ a #GBytes.
+
+
+
+
+
+ Gets the #GBytes associated with the given @icon.
+
+ a #GBytes, or %NULL.
+
+
+
+
+ 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 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.
+
+ 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 an warning to be
+logged) to use this method if there is no #GCredentials support for
+the OS or if @native_type isn't supported by the OS.
+
+ The pointer to native credentials or %NULL if the
+operation there is no #GCredentials support for the OS or if
+@native_type isn't supported by the OS. Do not free the returned
+data, it is owned by @credentials.
+
+
+
+
+ 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 an warning to be
+logged) to use this method if there is no #GCredentials support for
+the OS or if @native_type isn't supported by the OS.
+
+
+
+
+
+ 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.
+
+
+
+ #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
+
+
+
+ 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 # {#auth-observer}
+
+For example, if you only want to allow D-Bus connections from
+processes owned by the same uid as the server, you would use a
+signal handler like the following:
+
+|[<!-- 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 an #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://git.gnome.org/browse/glib/tree/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://git.gnome.org/browse/glib/tree/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://git.gnome.org/browse/glib/tree/gio/tests/gdbus-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://git.gnome.org/browse/glib/tree/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 or
+%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags.
+
+This is a synchronous failable constructor. See
+g_dbus_connection_new_for_address() for the asynchronous version.
+
+If @observer is not %NULL it may be used to control the
+authentication process.
+
+ 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 a 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 a asynchronous failable constructor. See
+g_dbus_connection_new_sync() for the synchronous
+version.
+
+
+
+
+
+ a #GIOStream
+
+
+
+ the GUID to use if a 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 or
+%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags.
+
+When the operation is finished, @callback will be invoked. You can
+then call g_dbus_connection_new_finish() to get the result of the
+operation.
+
+If @observer is not %NULL it may be used to control the
+authentication process.
+
+This is a asynchronous failable constructor. See
+g_dbus_connection_new_for_address_sync() for the synchronous
+version.
+
+
+
+
+
+ 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. Similary, if a filter consumes an outgoing message, the
+message will not be sent to the other peer.
+
+If @user_data_free_func is non-%NULL, it will be called (in the
+thread-default main context of the thread you are calling this
+method from) at some point after @user_data is no longer
+needed. (It is not guaranteed to be called synchronously when the
+filter is removed, and may be called after @connection has been
+destroyed.)
+
+ 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.
+
+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, 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 #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 #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.
+
+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().
+
+ %NULL if @error is set. Otherwise a #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.
+
+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 #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 closees @connection. The calling thread is blocked
+until this is done. See g_dbus_connection_close() for the
+asynchronous version of this method and more details about what it
+does.
+
+ %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.
+
+ %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).
+
+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
+
+
+
+
+
+ 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.
+
+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.
+
+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.
+
+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 the session bus, and expect
+all of a users applications to quit when their bus connection goes away.
+If you are setting @exit_on_close to %FALSE for the shared session
+bus connection, you should make sure that your application exits
+when the user session ends.
+
+
+
+
+
+ a #GDBusConnection
+
+
+
+ whether the process should be terminated
+ when @connection is closed by the remote peer
+
+
+
+
+
+ Subscribes to signals on @connection and invokes @callback with a whenever
+the signal is received. Note that @callback will be invoked in the
+[thread-default main context][g-main-context-push-thread-default]
+of the thread you are calling this method from.
+
+If @connection is not a message bus connection, @sender must be
+%NULL.
+
+If @sender is a well-known name note that @callback is invoked with
+the unique name for the owner of @sender, not the well-known name
+as one would expect. This is because the message bus rewrites the
+name. As such, to avoid certain race conditions, users should be
+tracking the name owner of the well-known name and use that when
+processing the received signal.
+
+If one of %G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_NAMESPACE or
+%G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_PATH are given, @arg0 is
+interpreted as part of a namespace or path. The first argument
+of a signal is matched against that part as specified by D-Bus.
+
+If @user_data_free_func is non-%NULL, it will be called (in the
+thread-default main context of the thread you are calling this
+method from) at some point after @user_data is no longer
+needed. (It is not guaranteed to be called synchronously when the
+signal is unsubscribed from, and may be called after @connection
+has been destroyed.)
+
+ 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.
+
+
+
+
+
+ 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.
+
+
+
+ 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.
+
+
+
+ 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 a error domain.
+
+
+
+ An error code.
+
+
+
+ A D-Bus error name.
+
+
+
+
+
+ Helper function for associating a #GError error domain with D-Bus error names.
+
+
+
+
+
+ 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 a 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
+
+
+
+ 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().
+
+ A new #GDBusMessage or %NULL if @error is set. Free with
+g_object_unref().
+
+
+
+
+ A blob represent 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 represent 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.
+
+ 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.
+
+ The value.
+
+
+
+
+ A #GDBusMessage.
+
+
+
+
+
+ Gets the UNIX file descriptors associated with @message, if any.
+
+This method is only available on UNIX.
+
+ 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.
+
+
+
+
+
+ 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 is set *<!-- -->/
+ g_object_unref (message);
+
+ /<!-- -->* modify @copy *<!-- -->/
+
+ return copy;
+}
+]|
+If the returned #GDBusMessage is different from @message and cannot
+be sent on @connection (it could use features, such as file
+descriptors, not compatible with @connection), then a warning is
+logged to 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 lookup.
+
+
+
+ D-Bus interface name to lookup.
+
+
+
+
+
+ Gets the #GDBusObjectProxy at @object_path, if any.
+
+ A #GDBusObject or %NULL. Free with
+ g_object_unref().
+
+
+
+
+ A #GDBusObjectManager.
+
+
+
+ Object path to lookup.
+
+
+
+
+
+ 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 lookup.
+
+
+
+ D-Bus interface name to lookup.
+
+
+
+
+
+ Gets the #GDBusObjectProxy at @object_path, if any.
+
+ A #GDBusObject or %NULL. Free with
+ g_object_unref().
+
+
+
+
+ A #GDBusObjectManager.
+
+
+
+ Object path to lookup.
+
+
+
+
+
+ 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.
+
+
+
+ A %NULL terminated array of properties that was 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 lookup.
+
+
+
+
+
+
+
+
+ A #GDBusInterface instance or %NULL. Free
+ with g_object_unref().
+
+
+
+
+ A #GDBusObjectManager.
+
+
+
+ Object path to lookup.
+
+
+
+ D-Bus interface name to lookup.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #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 gets
+emitted. This behaviour can be changed by passing suitable
+#GDBusProxyFlags when the proxy is created. If the proxy is for a
+well-known name, the property cache is flushed when the name owner
+vanishes and reloaded when a name owner appears.
+
+If a #GDBusProxy is used for a well-known name, the owner of the
+name is tracked and can be read from
+#GDBusProxy:g-name-owner. Connect to the #GObject::notify signal to
+get notified of changes. Additionally, only signals and property
+changes emitted from the current name owner are considered and
+calls are always sent to the current name owner. This avoids a
+number of race conditions when the name is lost by one owner and
+claimed by another. However, if no name owner currently exists,
+then calls will be sent to the well-known name which may result in
+the message bus launching an owner (unless
+%G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set).
+
+The generic #GDBusProxy::g-properties-changed and
+#GDBusProxy::g-signal signals are not very convenient to work with.
+Therefore, the recommended way of working with proxies is to subclass
+#GDBusProxy, and have more natural properties and signals in your derived
+class. 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://git.gnome.org/browse/glib/tree/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 @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 @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.
+
+ 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
+
+
+
+ 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.
+
+
+
+
+
+ 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.
+
+
+
+
+
+ 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.
+
+
+
+ User data.
+
+
+
+
+
+ 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 G-DBus can be found
+in [gdbus-example-peer.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-peer.c).
+
+
+ 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.
+
+Connect to the #GDBusServer::new-connection signal to handle
+incoming connections.
+
+The returned #GDBusServer isn't active - you have to start it with
+g_dbus_server_start().
+
+#GDBusServer is used in this [example][gdbus-peer-to-peer].
+
+This is a synchronous failable constructor. See
+g_dbus_server_new() for the asynchronous version.
+
+ 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.
+
+ 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.
+
+ 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.
+
+
+
+ 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.
+
+
+
+ Signature for callback function used in g_dbus_connection_signal_subscribe().
+
+
+
+
+
+ A #GDBusConnection.
+
+
+
+ The unique bus name of the sender of the signal.
+
+
+
+ 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 (never %NULL).
+
+
+
+ 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 default handler to URI association. See
+[Extending GIO][extending-gio].
+
+
+
+ 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.
+
+ 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.
+
+
+
+
+
+ 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().
+
+ 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.
+
+ 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.
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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
+
+
+
+
+
+ #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
+
+
+
+
+ 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.
+
+ 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 destkop 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
+
+
+
+
+
+ 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
+
+
+
+
+
+ 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 traditional UNIX fork()/exec()
+then @spawn_flags, @user_setup and @user_setup_data are used for the
+call to g_spawn_async(). Additionally, @pid_callback (with
+@pid_callback_data) will be called to inform about the PID of the
+created process.
+
+If application launching occurs via some other mechanism (eg: D-Bus
+activation) then @spawn_flags, @user_setup, @user_setup_data,
+@pid_callback and @pid_callback_data are ignored.
+
+ %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
+
+
+
+
+
+ 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.
+
+ 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 potententially expensive and may
+spin up the drive creating noise.
+
+#GDrive supports starting and stopping drives with authentication
+support for the former. This can be used to support a diverse set
+of use cases including connecting/disconnecting iSCSI devices,
+powering down external disk enclosures and starting/stopping
+multi-disk devices such as RAID devices. Note that the actual
+semantics and side-effects of starting/stopping a #GDrive may vary
+according to implementation. To choose the correct verbs in e.g. a
+file manager, use g_drive_get_start_stop_type().
+
+For porting from GnomeVFS note that there is no equivalent of
+#GDrive in that API.
+
+ 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.
+
+ a newly allocated string containing the
+ requested identfier, 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 capabable of automatically detecting media changes.
+
+ %TRUE if the @drive is capabable 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.
+
+ a newly allocated string containing the
+ requested identfier, 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 capabable of automatically detecting media changes.
+
+ %TRUE if the @drive is capabable 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 capabable 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 identfier, 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
+
+ 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.
+
+
+
+
+
+ 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 all of the
+ways indicated here will be rejected unless the application
+overrides the default via #GDtlsConnection::accept-certificate.
+
+
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Attempts a TLS handshake on @conn.
+
+On the client side, it is never necessary to call this method;
+although the connection needs to perform a handshake after
+connecting (or after sending a "STARTTLS"-type command) and may
+need to rehandshake later if the server requests it,
+#GDtlsConnection will handle this for you automatically when you try
+to send or receive data on the connection. However, you can call
+g_dtls_connection_handshake() manually if you want to know for sure
+whether the initial handshake succeeded or failed (as opposed to
+just immediately trying to write to @conn, in which
+case if it fails, it may not be possible to tell if it failed
+before or after completing the handshake).
+
+Likewise, on the server side, although a handshake is necessary at
+the beginning of the communication, you do not need to call this
+function explicitly unless you want clearer error reporting.
+However, you may call g_dtls_connection_handshake() later on to
+renegotiate parameters (encryption methods, etc) with the client.
+
+#GDtlsConnection::accept_certificate may be emitted during the
+handshake.
+
+ 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.
+
+
+
+
+
+ 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
+
+
+
+
+
+ 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 @conn's peer's certificate after the handshake has completed.
+(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. (It is not set
+during the emission of #GDtlsConnection::accept-certificate.)
+
+ @conn's peer's certificate errors
+
+
+
+
+ a #GDtlsConnection
+
+
+
+
+
+ Gets @conn rehandshaking mode. See
+g_dtls_connection_set_rehandshake_mode() for details.
+
+ @conn's rehandshaking mode
+
+
+
+
+ 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 (or after sending a "STARTTLS"-type command) and may
+need to rehandshake later if the server requests it,
+#GDtlsConnection will handle this for you automatically when you try
+to send or receive data on the connection. However, you can call
+g_dtls_connection_handshake() manually if you want to know for sure
+whether the initial handshake succeeded or failed (as opposed to
+just immediately trying to write to @conn, in which
+case if it fails, it may not be possible to tell if it failed
+before or after completing the handshake).
+
+Likewise, on the server side, although a handshake is necessary at
+the beginning of the communication, you do not need to call this
+function explicitly unless you want clearer error reporting.
+However, you may call g_dtls_connection_handshake() later on to
+renegotiate parameters (encryption methods, etc) with the client.
+
+#GDtlsConnection::accept_certificate may be emitted during the
+handshake.
+
+ 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.
+
+
+
+
+
+ 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_dtls_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).
+
+
+
+
+
+ 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
+
+
+
+
+
+ Sets how @conn behaves with respect to rehandshaking requests.
+
+%G_TLS_REHANDSHAKE_NEVER means that it will never agree to
+rehandshake after the initial handshake is complete. (For a client,
+this means it will refuse rehandshake requests from the server, and
+for a server, this means it will close the connection with an error
+if the client attempts to rehandshake.)
+
+%G_TLS_REHANDSHAKE_SAFELY means that the connection will allow a
+rehandshake only if the other end of the connection supports the
+TLS `renegotiation_info` extension. This is the default behavior,
+but means that rehandshaking will not work against older
+implementations that do not support that extension.
+
+%G_TLS_REHANDSHAKE_UNSAFELY means that the connection will allow
+rehandshaking even without the `renegotiation_info` extension. On
+the server side in particular, this is not recommended, since it
+leaves the server open to certain attacks. However, this mode is
+necessary if you need to allow renegotiation with older client
+software.
+
+
+
+
+
+ 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 #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 certificate database to use when verifying this TLS connection.
+If no certificate database is set, then the default database will be
+used. See g_dtls_backend_get_default_database().
+
+
+
+ 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 connection's peer's certificate, after the TLS handshake has
+completed and the certificate has been accepted. Note in
+particular that this is not yet set during the emission of
+#GDtlsConnection::accept-certificate.
+
+(You can watch for a #GObject::notify signal on this property to
+detect when a handshake has occurred.)
+
+
+
+ The errors noticed-and-ignored 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.
+
+
+
+ The rehandshaking mode. See
+g_dtls_connection_set_rehandshake_mode().
+
+
+
+ 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.
+
+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_HANDSHAKE, you can interact with the user, and if
+the user decides to accept the certificate, remember that fact,
+create a new connection, and return %TRUE from the signal handler
+the next time.
+
+If you are doing I/O in another thread, you do not
+need to worry about this, and can simply block in the signal
+handler until the UI thread returns an answer.
+
+ %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
+
+
+
+
+
+
+
+ #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'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 "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 of used 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 furter information. Example descriptions
+could be "filename (on hostname)" for a remote file or "filename (in trash)"
+for a file in the trash. This is useful for instance as the window title
+when displaying a directory or for a bookmarks menu.
+
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+
+
+
+ A key in the "standard" namespace for getting the display name of the file.
+A display name is guaranteed to be in UTF8 and can thus be displayed in
+the UI.
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+
+
+
+ A key in the "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.
+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.
+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 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 getting the path to the 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 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 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 corresponds to the NTFS ctime.
+
+
+
+ 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 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. When requested against
+items in `trash:///`, will return the date and time when the file
+was trashed. The format of the returned string is YYYY-MM-DDThh:mm:ss.
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+
+
+
+ A key in the "trash" namespace. When requested against
+`trash:///` returns the number of (toplevel) items in the trash folder.
+Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+
+
+
+ A key in the "trash" namespace. When requested against
+items in `trash:///`, will return the original path to the file before it
+was trashed. Corresponding #GFileAttributeType is
+%G_FILE_ATTRIBUTE_TYPE_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. 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 lstat()
+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 number of hard links
+for a file. See lstat() documentation. This attribute is only available
+for UNIX file systems. Corresponding #GFileAttributeType is
+%G_FILE_ATTRIBUTE_TYPE_UINT32.
+
+
+
+ A key in the "unix" namespace for getting the device ID for the file
+(if it is a special file). See lstat() documentation. This attribute
+is only available for UNIX file systems. Corresponding #GFileAttributeType
+is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+
+
+
+ A key in the "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_parse_name() from a UTF-8 string gotten from g_file_get_parse_name().
+
+One way to think of a #GFile is as an abstraction of a pathname. For
+normal files the system pathname is what is stored internally, but as
+#GFiles are extensible it could also be something else that corresponds
+to a pathname in a userspace implementation of a filesystem.
+
+#GFiles make up hierarchies of directories and files that correspond to
+the files on a filesystem. You can move through the file system with
+#GFile using g_file_get_parent() to get an identifier for the parent
+directory, g_file_get_child() to get a child within a directory,
+g_file_resolve_relative_path() to resolve a relative path between two
+#GFiles. There can be multiple hierarchies, so you may not end up at
+the same root if you repeatedly call g_file_get_parent() on two different
+files.
+
+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.
+
+ 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
+
+
+
+
+
+ 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 @cancellable is not %NULL, then the operation can 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.
+
+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.
+
+If @cancellable is not %NULL, then the operation can 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.
+
+If the #GFileIface for @file does not have a mount (e.g.
+possibly a remote share), @error will be set to %G_IO_ERROR_NOT_FOUND
+and %NULL will be returned.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+ 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 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 URI for the @file.
+
+This call does no blocking I/O.
+
+ a string containing the #GFile's URI.
+ 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.
+
+This call does no blocking I/O.
+
+ a string containing the URI scheme for the given
+ #GFile. 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 s one expressed in the platform-native filename format,
+e.g. "C:\Windows" or "/usr/bin/". This does not mean the file is local,
+as it might be on a locally mounted remote filesystem.
+
+On some systems non-native files may be available using the native
+filesystem via a userspace filesystem (FUSE), in these cases this call
+will return %FALSE, but g_file_get_path() will still return a native path.
+
+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
+
+
+
+
+
+ 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_DISK_USAGE_REPORT_ALL_ERRORS is given in @flags.
+
+The returned size, @disk_usage, is in bytes and should be formatted
+with g_format_size() in order to get something reasonable for showing
+in a user interface.
+
+@progress_callback and @progress_data can be given to request
+periodic progress updates while scanning. See the documentation for
+#GFileMeasureProgressCallback for information about when and how the
+callback will be invoked.
+
+ %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 the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks
+will be copied as symlinks, otherwise the target of the
+@source symlink will be copied.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+If @progress_callback is not %NULL, then the operation can be monitored
+by setting this to a #GFileProgressCallback function.
+@progress_callback_data will be passed to this function. It is
+guaranteed that this callback will be called after all data has been
+transferred with the total number of bytes copied during the operation.
+
+If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND
+error is returned, independent on the status of the @destination.
+
+If #G_FILE_COPY_OVERWRITE is not specified and the target exists,
+then the error %G_IO_ERROR_EXISTS is returned.
+
+If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY
+error is returned. If trying to overwrite a directory with a directory the
+%G_IO_ERROR_WOULD_MERGE error is returned.
+
+If the source is a directory and the target does not exist, or
+#G_FILE_COPY_OVERWRITE is specified and the target is a file, then
+the %G_IO_ERROR_WOULD_RECURSE error may be returned (if the native
+move operation isn't available).
+
+ %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
+
+
+
+
+
+ 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 @files'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.
+
+ #GFile to the resolved path.
+ %NULL if @relative_path is %NULL or if @file is invalid.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a given relative path string
+
+
+
+
+
+ Sets an attribute in the file with attribute name @attribute to @value.
+
+Some attributes can be unset by setting @attribute 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 an 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.
+
+If @cancellable is not %NULL, then the operation can 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
+
+
+
+
+
+ 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 @cancellable is not %NULL, then the operation can 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.
+
+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.
+
+If @cancellable is not %NULL, then the operation can 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.
+
+If the #GFileIface for @file does not have a mount (e.g.
+possibly a remote share), @error will be set to %G_IO_ERROR_NOT_FOUND
+and %NULL will be returned.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+ 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.
+ 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.
+
+This call does no blocking I/O.
+
+ a string containing the URI scheme for the given
+ #GFile. 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 @files'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 s one expressed in the platform-native filename format,
+e.g. "C:\Windows" or "/usr/bin/". This does not mean the file is local,
+as it might be on a locally mounted remote filesystem.
+
+On some systems non-native files may be available using the native
+filesystem via a userspace filesystem (FUSE), in these cases this call
+will return %FALSE, but g_file_get_path() will still return a native path.
+
+This call does no blocking I/O.
+
+ %TRUE if @file is native
+
+
+
+
+ input #GFile
+
+
+
+
+
+ Loads the content of the file into memory. The data is always
+zero-terminated, but this is not included in the resultant @length.
+The returned @content should be freed with g_free() when no longer
+needed.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+ %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 @content should be freed with
+g_free() when no longer needed. If @etag_out is present, it will be
+set to the new entity tag for the @file.
+
+ %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 @content 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
+
+
+
+
+
+ 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_DISK_USAGE_REPORT_ALL_ERRORS is given in @flags.
+
+The returned size, @disk_usage, is in bytes and should be formatted
+with g_format_size() in order to get something reasonable for showing
+in a user interface.
+
+@progress_callback and @progress_data can be given to request
+periodic progress updates while scanning. See the documentation for
+#GFileMeasureProgressCallback for information about when and how the
+callback will be invoked.
+
+ %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 the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks
+will be copied as symlinks, otherwise the target of the
+@source symlink will be copied.
+
+If @cancellable is not %NULL, then the operation can be cancelled by
+triggering the cancellable object from another thread. If the operation
+was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+
+If @progress_callback is not %NULL, then the operation can be monitored
+by setting this to a #GFileProgressCallback function.
+@progress_callback_data will be passed to this function. It is
+guaranteed that this callback will be called after all data has been
+transferred with the total number of bytes copied during the operation.
+
+If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND
+error is returned, independent on the status of the @destination.
+
+If #G_FILE_COPY_OVERWRITE is not specified and the target exists,
+then the error %G_IO_ERROR_EXISTS is returned.
+
+If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY
+error is returned. If trying to overwrite a directory with a directory the
+%G_IO_ERROR_WOULD_MERGE error is returned.
+
+If the source is a directory and the target does not exist, or
+#G_FILE_COPY_OVERWRITE is specified and the target is a file, then
+the %G_IO_ERROR_WOULD_RECURSE error may be returned (if the native
+move operation isn't available).
+
+ %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
+
+
+
+
+
+ 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
+
+
+
+
+
+ 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
+
+
+
+
+
+ Utility function to check if a particular file exists. This is
+implemented using g_file_query_info() and as such does blocking I/O.
+
+Note that in many cases it is racy to first check for file existence
+and then execute something based on the outcome of that, because the
+file might have been created or removed in between the operations. The
+general approach to handling that is to not check, but just do the
+operation and handle the errors as they come.
+
+As an example of race-free checking, take the case of reading a file,
+and if it doesn't exist, creating it. There are two racy versions: read
+it, and on error create it; and: check if it exists, if not create it.
+These can both result in two processes creating the file (with perhaps
+a partially written file as the result). The correct approach is to
+always try to create the file with g_file_create() which will either
+atomically create the file or fail with a %G_IO_ERROR_EXISTS error.
+
+However, in many cases an existence check is useful in a user interface,
+for instance to make a menu item sensitive/insensitive, so that you don't
+have to fool users that something is possible and then just show an error
+dialog. If you do this, you should make sure to also handle the errors
+that can happen due to races when you execute the operation.
+
+ %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 @content will be made, so it must stay valid
+until @callback is called. See g_file_replace_contents_bytes_async()
+for a #GBytes version that will automatically hold a reference to the
+contents (without copying) for the duration of the call.
+
+
+
+
+
+ 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.
+
+ #GFile to the resolved path.
+ %NULL if @relative_path is %NULL or if @file is invalid.
+ Free the returned object with g_object_unref().
+
+
+
+
+ input #GFile
+
+
+
+ a given relative path string
+
+
+
+
+
+ Sets an attribute in the file with attribute name @attribute to @value.
+
+Some attributes can be unset by setting @attribute 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 an 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.
+
+If @cancellable is not %NULL, then the operation can 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 lookup.
+
+
+
+
+
+ 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 @attribute string should be formatted with specific keys separated
+from namespaces with a double colon. Several "namespace::key" strings may be
+concatenated with a single comma (e.g. "standard::type,standard::is-hidden").
+The wildcard "*" may be used to match all keys and namespaces, or
+"namespace::*" will match all keys in a given namespace.
+
+## Examples of file attribute matcher strings and results
+
+- `"*"`: matches all attributes.
+- `"standard::is-hidden"`: matches only the key is-hidden in the
+ standard namespace.
+- `"standard::type,unix::*"`: matches the type key in the standard
+ namespace and all keys in the unix namespace.
+
+ 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 a 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 uninitalized 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. 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().
+
+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, or %NULL.
+
+
+
+
+ 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. The returned string should be freed with g_free()
+ when no longer needed.
+
+
+
+
+ input #GFile
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a string containing the #GFile's URI.
+ 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 @files's parent, grandparent, etc is @prefix,
+ %FALSE otherwise.
+
+
+
+
+ input #GFile
+
+
+
+ input #GFile
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #GFile to the resolved path.
+ %NULL if @relative_path is %NULL or if @file is invalid.
+ Free the returned object with g_object_unref().
+
+
+
+
+ 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
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ %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
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+#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 value of a attribute, formated as a string.
+This escapes things as needed to make the string valid
+utf8.
+
+ a UTF-8 string associated with the given @attribute.
+ 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 an 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.
+
+ a string containing the file's content type.
+
+
+
+
+ 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.
+
+ a string containing the display name.
+
+
+
+
+ a #GFileInfo.
+
+
+
+
+
+ Gets the edit name for a file.
+
+ a string containing the edit name.
+
+
+
+
+ a #GFileInfo.
+
+
+
+
+
+ Gets the [entity tag][gfile-etag] for a given
+#GFileInfo. See %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().
+
+ a #GFileType for the given file.
+
+
+
+
+ a #GFileInfo.
+
+
+
+
+
+ Gets the icon for a file.
+
+ #GIcon for the given @info.
+
+
+
+
+ a #GFileInfo.
+
+
+
+
+
+ Checks if a file is a backup file.
+
+ %TRUE if file is a backup file, %FALSE otherwise.
+
+
+
+
+ a #GFileInfo.
+
+
+
+
+
+ Checks if a file is hidden.
+
+ %TRUE if the file is a hidden file, %FALSE otherwise.
+
+
+
+
+ a #GFileInfo.
+
+
+
+
+
+ Checks if a file is a symlink.
+
+ %TRUE if the given @info is a symlink.
+
+
+
+
+ a #GFileInfo.
+
+
+
+
+
+ Gets the modification time of the current @info and sets it
+in @result.
+
+
+
+
+
+ a #GFileInfo.
+
+
+
+ a #GTimeVal.
+
+
+
+
+
+ Gets the name for a file.
+
+ a string containing the file name.
+
+
+
+
+ a #GFileInfo.
+
+
+
+
+
+ Gets the file's size.
+
+ a #goffset containing the file's size.
+
+
+
+
+ a #GFileInfo.
+
+
+
+
+
+ Gets the value of the sort_order attribute from the #GFileInfo.
+See %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.
+
+ #GIcon for the given @info.
+
+
+
+
+ a #GFileInfo.
+
+
+
+
+
+ Gets the symlink target for a given #GFileInfo.
+
+ a string containing the symlink target.
+
+
+
+
+ a #GFileInfo.
+
+
+
+
+
+ Checks if a file info structure has an attribute named @attribute.
+
+ %TRUE if @Ginfo 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 @Ginfo 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 @attribute to contain the given value, if possible. To unset the
+attribute, use %G_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 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 attribute in the file
+info to the given time value.
+
+
+
+
+
+ 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_DISK_USAGE_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.
+
+ 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.
+
+ 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.
+
+
+
+ #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.
+
+ 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().
+
+
+
+
+
+ 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.
+
+
+
+
+
+ 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.
+
+
+
+ the data to pass to 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
+
+
+
+
+
+ Asyncronously splice the output stream of @stream1 to the input stream of
+@stream2, and splice the output stream of @stream2 to the input stream of
+@stream1.
+
+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()
+
+
+
+
+
+ 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.
+
+
+
+
+
+ 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.
+
+
+
+
+ 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, 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+
+
+
+
+ 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.
+
+
+
+
+ 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, 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.
+
+
+
+
+
+
+
+
+ An allocated NUL-terminated UTF8 string or
+%NULL if @icon can't be serialized. Use g_free() to free.
+
+
+
+
+ a #GIcon.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GVariant, or %NULL when serialization fails.
+
+
+
+
+ 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 implemention %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 faciliate the
+maximum level of laziness in the implementation of the list and to
+reduce the required number of signal connections at a given time.
+
+This interface is intended only to be used from a single thread. The
+thread in which it is appropriate to use it depends on the particular
+implementation, but typically it will be from the thread that owns
+the [thread-default main context][g-main-context-push-thread-default]
+in effect at the time that the model was created.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Gets the type of the items in @list. All items returned from
+g_list_model_get_type() are of that type or a subtype, or are an
+implementation of that interface.
+
+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 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_type() are of that type or a subtype, or 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 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 or removed to
+@list. At @position, @removed items were removed and @added items
+were added in their place.
+
+
+
+
+
+ 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
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #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
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+
+ 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 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
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #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}
+
+![](menu-example.png)
+
+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}
+
+![](menu-model.png)
+
+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 occured to the menu.
+
+The only changes that can occur to a menu is that items are removed
+or added. Items may not change (except by being removed and added
+back in the same location). This signal is capable of describing
+both of those changes (at the same time).
+
+The signal means that starting at the index @position, @removed
+items were removed and @added items were added in their place. If
+@removed is zero then only items were added. If @added is zero
+then only items were removed.
+
+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
+#GAsyncReady structure will be passed to the callback. That
+callback should then call g_mount_unmount_with_operation_finish() with the #GMount
+and the #GAsyncReady data to see if the operation was completed
+successfully. If an @error is present when g_mount_unmount_with_operation_finish()
+is called, then it will be filled with any error information.
+
+ 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 an 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 an 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 is emitted when the #GMount is about to be
+unmounted.
+
+
+
+
+
+ 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.
+
+ Creates a new mount operation.
+
+ a #GMountOperation.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Emits the #GMountOperation::reply signal.
+
+
+
+
+
+ a #GMountOperation
+
+
+
+ a #GMountOperationResult
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+
+
+
+
+ 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.
+
+
+
+
+
+ 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'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 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.
+
+
+
+ The password that is used for authentication when carrying out
+the mount operation.
+
+
+
+ Determines if and how the password information should be saved.
+
+
+
+ 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 mesage 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
+
+
+
+ a #GMountOperationResult
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #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].
+
+
+
+ An socket address of some unknown native type.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #GNetworkAddress provides an easy way to resolve a hostname and
+then attempt to connect to that host, handling the possibility of
+multiple IP addresses and multiple address families.
+
+See #GSocketConnectable for and example of using the connectable
+interface.
+
+
+ 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
+#GNetworkAddresses 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 overide if necessary)
+and @default_port is expected to be provided by the application.
+
+(The port component of @host_and_port can also be specified as a
+service name rather than as a numeric port, but this functionality
+is deprecated, because it depends on the contents of /etc/services,
+which is generally quite sparse on platforms other than Linux.)
+
+ 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
+
+
+
+
+ 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. If @available is
+%TRUE, then some hosts may be reachable that were not reachable
+before, while others that were reachable before may no longer be
+reachable. If @available is %FALSE, then no remote hosts are
+reachable.
+
+
+
+
+
+ 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 and 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
+
+
+
+
+
+ Get's 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.
+
+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 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.
+
+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().
+
+
+
+
+
+ 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
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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 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.
+
+ 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
+
+
+
+
+
+ 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.
+
+ 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
+
+
+
+
+
+
+ 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 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
+
+
+
+
+
+
+
+ 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.
+
+
+
+
+
+ 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().
+
+ Lookup "gio-proxy" extension point for a proxy implementation that supports
+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.
+
+
+
+
+
+ A subclass of #GSocketAddressEnumerator that takes another address
+enumerator and wraps its results in #GProxyAddress<!-- -->es as
+directed by the default #GProxyResolver.
+
+
+
+
+ The default port to use if #GProxyAddressEnumerator:uri does not
+specify one.
+
+
+
+ The proxy resolver to use.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+
+
+
+ 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
+
+
+
+
+
+ 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 lookup the record for
+
+
+
+ the type of DNS record to lookup
+
+
+
+ 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 lookup the record for
+
+
+
+ the type of DNS record to lookup
+
+
+
+ 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
+
+
+
+
+
+ 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 lookup the record for
+
+
+
+ the type of DNS record to lookup
+
+
+
+ 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 lookup the record for
+
+
+
+ the type of DNS record to lookup
+
+
+
+ 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 lookup the record for
+
+
+
+ the type of DNS record to lookup
+
+
+
+ a #GCancellable, or %NULL
+
+
+
+
+
+
+
+
+
+
+
+
+ a #GResolver
+
+
+
+ the DNS name to lookup the record for
+
+
+
+ the type of DNS record to lookup
+
+
+
+ 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
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+
+ 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.
+
+%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 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.
+
+ lookup DNS SRV records for a domain
+
+
+ lookup DNS MX records for a domain
+
+
+ lookup DNS TXT records for a name
+
+
+ lookup DNS SOA records for a zone
+
+
+ lookup 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` which will use the gdk-pixbuf-pixdata command to convert
+images to the GdkPixdata format, which allows you to create pixbufs directly using the data inside
+the resource file, rather than an (uncompressed) copy if it. For this, the gdk-pixbuf-pixdata
+program must be in the PATH, or the `GDK_PIXBUF_PIXDATA` environment variable must be
+set to the full path to the gdk-pixbuf-pixdata executable; otherwise the resource compiler will
+abort.
+
+Resource 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 colon-separated list of substitutions to perform
+during resource lookups.
+
+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().
+
+ 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().
+
+ 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: attmepting 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 stream can be truncated.
+
+ %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 offset from the beginning of the buffer.
+
+
+
+
+ a #GSeekable.
+
+
+
+
+
+ Truncates a stream with a given #offset.
+
+If @cancellable is not %NULL, then the operation can 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.
+
+
+
+ a #goffset.
+
+
+
+ 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 stream can be truncated.
+
+ %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 offset from the beginning of the buffer.
+
+
+
+
+ a #GSeekable.
+
+
+
+
+
+ Truncates a stream with a given #offset.
+
+If @cancellable is not %NULL, then the operation can 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.
+
+
+
+ a #goffset.
+
+
+
+ optional #GCancellable object, %NULL to ignore.
+
+
+
+
+
+
+ Provides an interface for implementing seekable functionality on I/O Streams.
+
+ The parent interface.
+
+
+
+
+
+ the offset from the beginning of the buffer.
+
+
+
+
+ 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.
+
+
+
+ a #goffset.
+
+
+
+ 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 as 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://git.gnome.org/browse/glib/tree/gio/gschema.dtd)
+
+The [glib-compile-schemas][glib-compile-schemas] tool expects schema
+files to have the extension `.gschema.xml`.
+
+At runtime, schemas are identified by their id (as specified in the
+id attribute of the <schema> element). The convention for schema
+ids is to use a dotted name, similar in style to a D-Bus bus name,
+e.g. "org.gnome.SessionManager". In particular, if the settings are
+for a specific service that owns a D-Bus bus name, the D-Bus bus name
+and schema id should match. For schemas which deal with settings not
+associated with one named application, the id should not use
+StudlyCaps, e.g. "org.gnome.font-rendering".
+
+In addition to #GVariant types, keys can have types that have
+enumerated types. These can be described by a <choice>,
+<enum> or <flags> element, as seen in the
+[example][schema-enumerated]. The underlying type of such a key
+is string, but you can use g_settings_get_enum(), g_settings_set_enum(),
+g_settings_get_flags(), g_settings_set_flags() access the numeric values
+corresponding to the string value of enum and flags keys.
+
+An example for default value:
+|[
+<schemalist>
+ <schema id="org.gtk.Test" path="/org/gtk/Test/" gettext-domain="test">
+
+ <key name="greeting" type="s">
+ <default l10n="messages">"Hello, earthlings"</default>
+ <summary>A greeting</summary>
+ <description>
+ Greeting of the invading martians
+ </description>
+ </key>
+
+ <key name="box" type="(ii)">
+ <default>(20,30)</default>
+ </key>
+
+ </schema>
+</schemalist>
+]|
+
+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.
+
+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
+
+
+
+
+
+ <!-- -->
+ Use g_settings_schema_source_list_schemas() instead
+
+ a list of relocatable
+ #GSettings schemas that are available. The list must not be
+ modified or freed.
+
+
+
+
+
+
+ <!-- -->
+ 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. 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 the object,
+and that you can have only one binding per object property.
+If you bind the same property twice on the same object, the second
+binding overrides the first one.
+
+
+
+
+
+ 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 the object,
+and that you can have only one binding per object property.
+If you bind the same property twice on the same object, the second
+binding overrides the first one.
+
+
+
+
+
+ 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 the object,
+and that you can have only one binding per object property.
+If you bind the same property twice on the same object, the second
+binding overrides the first one.
+
+
+
+
+
+ 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.
+
+ 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 an flags type.
+
+It is a programmer error to give a @key that isn't contained in the
+schema for @settings or is not marked as a flags type.
+
+If the value stored in the configuration database is not a valid
+value for the flags type then this function will return the default
+value.
+
+ 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().
+
+For GSettings objects that are lists, this value can change at any
+time and you should connect to the "children-changed" signal to watch
+for those changes. Note that there is a race condition here: you may
+request a child after listing it only for it to have been destroyed
+in the meantime. For this reason, g_settings_get_child() may return
+%NULL even for a child that was listed by this function.
+
+For GSettings objects that are not lists, you should probably not be
+calling this function from "normal" code (since you should already
+know what children are in your schema). This function may still be
+useful there for introspection reasons, however.
+
+You should free the return value with g_strfreev() when you are done
+with it.
+
+ a list of the children on @settings
+
+
+
+
+
+
+ a #GSettings object
+
+
+
+
+
+ Introspects the list of keys on @settings.
+
+You should probably not be calling this function from "normal" code
+(since you should already know what keys are in your schema). This
+function is intended for introspection reasons.
+
+You should free the return value with g_strfreev() when you are done
+with it.
+
+ a list of the keys on @settings
+
+
+
+
+
+
+ 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 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
+
+
+
+
+
+
+
+
+ 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
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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_new_schema_source_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
+threfore 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
+
+
+
+
+
+
+ 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
+
+
+
+
+
+
+ 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 of the correct type and 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.
+
+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
+
+
+
+
+
+ the list
+ of relocatable schemas
+
+
+
+
+
+
+
+ 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().
+
+ a new #GSimpleAction
+
+
+
+
+ the name of the action
+
+
+
+ the type of parameter to the activate function
+
+
+
+
+
+ Creates a new stateful action.
+
+@state is the initial state of the action. All future state values
+must have the same #GVariantType as the initial state.
+
+If the @state GVariant is floating, it is consumed.
+
+ a new #GSimpleAction
+
+
+
+
+ the name of the action
+
+
+
+ the type of the parameter to the activate function
+
+
+
+ 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. In the event that
+an incorrect type was given, no signal will be emitted.
+
+Since GLib 2.40, if no handler is connected to this signal then the
+default behaviour for boolean-stated actions with a %NULL parameter
+type is to toggle them via the #GSimpleAction::change-state signal.
+For stateful actions where the state type is equal to the parameter
+type, the default is to forward them directly to
+#GSimpleAction::change-state. This should allow almost all users
+of #GSimpleAction to connect only one handler or the other.
+
+
+
+
+
+ the parameter to the activation
+
+
+
+
+
+ Indicates that the action just received a request to change its
+state.
+
+@value will always be of the correct state type. In the event that
+an incorrect type was given, no signal will be emitted.
+
+If no handler is connected to this signal then the default
+behaviour is to call g_simple_action_set_state() to set the state
+to the requested value. If you connect a signal handler then no
+default action is taken. If the state should change then you must
+call g_simple_action_set_state() from the handler.
+
+An example of a 'change-state' handler:
+|[<!-- language="C" -->
+static void
+change_volume_state (GSimpleAction *action,
+ GVariant *value,
+ gpointer user_data)
+{
+ gint requested;
+
+ requested = g_variant_get_int32 (value);
+
+ // Volume only goes from 0 to 10
+ if (0 <= requested && requested <= 10)
+ g_simple_action_set_state (action, value);
+}
+]|
+
+The handler need not set the state to the requested value.
+It could set it to any value at all, or take some other action.
+
+
+
+
+
+ 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]
+. g_simple_async_result_run_in_thread() will run the
+job in a separate thread and then deliver the result to the
+thread-default main context.
+
+To set the results of an asynchronous function,
+g_simple_async_result_set_op_res_gpointer(),
+g_simple_async_result_set_op_res_gboolean(), and
+g_simple_async_result_set_op_res_gssize()
+are provided, setting the operation's result to a gpointer, gboolean, or
+gssize, respectively.
+
+Likewise, to get the result of an asynchronous function,
+g_simple_async_result_get_op_res_gpointer(),
+g_simple_async_result_get_op_res_gboolean(), and
+g_simple_async_result_get_op_res_gssize() are
+provided, getting the operation's result as a gpointer, gboolean, and
+gssize, respectively.
+
+For the details of the requirements implementations must respect, see
+#GAsyncResult. A typical implementation of an asynchronous operation
+using GSimpleAsyncResult looks something like this:
+
+|[<!-- 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 microseconds for @condition to become true
+on @socket. If the condition is met, %TRUE is returned.
+
+If @cancellable is cancelled before the condition is met, or if
+@timeout (or the socket's #GSocket:timeout) is reached before the
+condition is met, then %FALSE is returned and @error, if non-%NULL,
+is set to the appropriate value (%G_IO_ERROR_CANCELLED or
+%G_IO_ERROR_TIMED_OUT).
+
+If you don't want a timeout, use g_socket_condition_wait().
+(Alternatively, you can pass -1 for @timeout.)
+
+Note that although @timeout is in microseconds for consistency with
+other GLib APIs, this function actually only has millisecond
+resolution, and the behavior is undefined if @timeout is not an
+exact number of milliseconds.
+
+ %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.
+
+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 remove 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.
+
+ %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
+
+
+
+
+
+ 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.
+
+
+
+ %TRUE if source-specific multicast was used
+
+
+
+ Interface used
+
+
+
+
+
+ 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
+
+
+
+ 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
+
+
+
+ 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.)
+
+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
+
+
+
+ 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
+
+
+
+ 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()
+
+
+
+
+
+
+
+ Enumerator type for objects that contain or generate
+#GSocketAddress<!-- -->es.
+
+ 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.
+
+
+
+
+
+ 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.
+
+
+
+
+
+ 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
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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().
+
+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.
+
+ 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 %0 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.
+
+
+
+
+
+ a #GSocketClient.
+
+
+
+ the validation flags
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The proxy resolver to use
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Emitted when @client's activity on @connectable changes state.
+Among other things, this can be used to provide progress
+information about a network connection in the UI. The meanings of
+the different @event values are as follows:
+
+- %G_SOCKET_CLIENT_RESOLVING: @client is about to look up @connectable
+ in DNS. @connection will be %NULL.
+
+- %G_SOCKET_CLIENT_RESOLVED: @client has successfully resolved
+ @connectable in DNS. @connection will be %NULL.
+
+- %G_SOCKET_CLIENT_CONNECTING: @client is about to make a connection
+ to a remote host; either a proxy server or the destination server
+ itself. @connection is the #GSocketConnection, which is not yet
+ connected. Since GLib 2.40, you can access the remote
+ address via g_socket_connection_get_remote_address().
+
+- %G_SOCKET_CLIENT_CONNECTED: @client has successfully connected
+ to a remote host. @connection is the connected #GSocketConnection.
+
+- %G_SOCKET_CLIENT_PROXY_NEGOTIATING: @client is about to negotiate
+ with a proxy to get it to connect to @connectable. @connection is
+ the #GSocketConnection to the proxy server.
+
+- %G_SOCKET_CLIENT_PROXY_NEGOTIATED: @client has negotiated a
+ connection to @connectable through a proxy server. @connection is
+ the stream returned from g_proxy_connect(), which may or may not
+ be a #GSocketConnection.
+
+- %G_SOCKET_CLIENT_TLS_HANDSHAKING: @client is about to begin a TLS
+ handshake. @connection is a #GTlsClientConnection.
+
+- %G_SOCKET_CLIENT_TLS_HANDSHAKED: @client has successfully completed
+ the TLS handshake. @connection is a #GTlsClientConnection.
+
+- %G_SOCKET_CLIENT_COMPLETE: @client has either successfully connected
+ to @connectable (in which case @connection is the #GSocketConnection
+ that it will be returning to the caller) or has failed (in which
+ case @connection is %NULL and the client is about to return an error).
+
+Each event except %G_SOCKET_CLIENT_COMPLETE may be emitted
+multiple times (or not at all) for a given connectable (in
+particular, if @client ends up attempting to connect to more than
+one address). However, if @client emits the #GSocketClient::event
+signal at all for a given connectable, that it will always emit
+it with %G_SOCKET_CLIENT_COMPLETE when it is done.
+
+Note that there may be additional #GSocketClientEvent values in
+the future; unrecognized @event values should be ignored.
+
+
+
+
+
+ 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 #GProxyAddresses for addresses that you must connect
+to via a proxy.
+
+If @connectable does not implement
+g_socket_connectable_proxy_enumerate(), this will fall back to
+calling g_socket_connectable_enumerate().
+
+ 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 #GProxyAddresses for addresses that you must connect
+to via a proxy.
+
+If @connectable does not implement
+g_socket_connectable_proxy_enumerate(), this will fall back to
+calling g_socket_connectable_enumerate().
+
+ 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.
+
+If you want to implement a network server, also look at #GSocketService
+and #GThreadedSocketService which are subclass of #GSocketListener
+that makes 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_socket()
+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.
+
+ %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.
+
+ %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.
+
+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.
+
+#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.
+
+
+
+
+
+ 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.
+
+
+
+
+
+ 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_exit_status().
+
+It is more likely that you want to use g_subprocess_get_if_exited()
+followed by g_subprocess_get_exit_status().
+
+It is an error to call this function before g_subprocess_wait() has
+returned.
+
+ 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.
+
+ 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.
+
+ 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.
+
+ 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_exit_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_exit_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).
+
+
+
+ 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
+
+
+
+
+
+ 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 #GSubprocess
+
+
+
+ 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 #GSubprocess
+
+
+
+ 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 #GSubprocess
+
+
+
+ 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 #GSubprocess
+
+
+
+ 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 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 #GSubprocess
+
+
+
+ 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 (waiting until the next iteration of the main
+loop first, if necessary). The caller will pass the #GTask back
+to the operation's finish function (as a #GAsyncResult), and
+you can use g_task_propagate_pointer() or the like to extract
+the return value.
+
+Here is an example for using GTask as a GAsyncResult:
+|[<!-- language="C" -->
+ typedef struct {
+ CakeFrostingType frosting;
+ char *message;
+ } DecorationData;
+
+ static void
+ decoration_data_free (DecorationData *decoration)
+ {
+ g_free (decoration->message);
+ g_slice_free (DecorationData, decoration);
+ }
+
+ static void
+ baked_cb (Cake *cake,
+ gpointer user_data)
+ {
+ GTask *task = user_data;
+ DecorationData *decoration = g_task_get_task_data (task);
+ GError *error = NULL;
+
+ if (cake == NULL)
+ {
+ g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR,
+ "Go to the supermarket");
+ g_object_unref (task);
+ return;
+ }
+
+ if (!cake_decorate (cake, decoration->frosting, decoration->message, &error))
+ {
+ g_object_unref (cake);
+ // g_task_return_error() takes ownership of error
+ g_task_return_error (task, error);
+ g_object_unref (task);
+ return;
+ }
+
+ g_task_return_pointer (task, cake, g_object_unref);
+ g_object_unref (task);
+ }
+
+ void
+ baker_bake_cake_async (Baker *self,
+ guint radius,
+ CakeFlavor flavor,
+ CakeFrostingType frosting,
+ const char *message,
+ GCancellable *cancellable,
+ GAsyncReadyCallback callback,
+ gpointer user_data)
+ {
+ GTask *task;
+ DecorationData *decoration;
+ Cake *cake;
+
+ task = g_task_new (self, cancellable, callback, user_data);
+ if (radius < 3)
+ {
+ g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_TOO_SMALL,
+ "%ucm radius cakes are silly",
+ radius);
+ g_object_unref (task);
+ return;
+ }
+
+ cake = _baker_get_cached_cake (self, radius, flavor, frosting, message);
+ if (cake != NULL)
+ {
+ // _baker_get_cached_cake() returns a reffed cake
+ g_task_return_pointer (task, cake, g_object_unref);
+ g_object_unref (task);
+ return;
+ }
+
+ decoration = g_slice_new (DecorationData);
+ decoration->frosting = frosting;
+ decoration->message = g_strdup (message);
+ g_task_set_task_data (task, decoration, (GDestroyNotify) decoration_data_free);
+
+ _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task);
+ }
+
+ Cake *
+ baker_bake_cake_finish (Baker *self,
+ GAsyncResult *result,
+ GError **error)
+ {
+ g_return_val_if_fail (g_task_is_valid (result, self), NULL);
+
+ return g_task_propagate_pointer (G_TASK (result), error);
+ }
+]|
+
+## 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
+which will then dispatch the result back to the caller's
+#GMainContext when it completes.
+
+Running a task in a thread:
+ |[<!-- language="C" -->
+ typedef struct {
+ guint radius;
+ CakeFlavor flavor;
+ CakeFrostingType frosting;
+ char *message;
+ } CakeData;
+
+ static void
+ cake_data_free (CakeData *cake_data)
+ {
+ g_free (cake_data->message);
+ g_slice_free (CakeData, cake_data);
+ }
+
+ static void
+ bake_cake_thread (GTask *task,
+ gpointer source_object,
+ gpointer task_data,
+ GCancellable *cancellable)
+ {
+ Baker *self = source_object;
+ CakeData *cake_data = task_data;
+ Cake *cake;
+ GError *error = NULL;
+
+ cake = bake_cake (baker, cake_data->radius, cake_data->flavor,
+ cake_data->frosting, cake_data->message,
+ cancellable, &error);
+ if (cake)
+ g_task_return_pointer (task, cake, g_object_unref);
+ else
+ g_task_return_error (task, error);
+ }
+
+ void
+ baker_bake_cake_async (Baker *self,
+ guint radius,
+ CakeFlavor flavor,
+ CakeFrostingType frosting,
+ const char *message,
+ GCancellable *cancellable,
+ GAsyncReadyCallback callback,
+ gpointer user_data)
+ {
+ CakeData *cake_data;
+ GTask *task;
+
+ cake_data = g_slice_new (CakeData);
+ cake_data->radius = radius;
+ cake_data->flavor = flavor;
+ cake_data->frosting = frosting;
+ cake_data->message = g_strdup (message);
+ task = g_task_new (self, cancellable, callback, user_data);
+ g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
+ g_task_run_in_thread (task, bake_cake_thread);
+ g_object_unref (task);
+ }
+
+ Cake *
+ baker_bake_cake_finish (Baker *self,
+ GAsyncResult *result,
+ GError **error)
+ {
+ g_return_val_if_fail (g_task_is_valid (result, self), NULL);
+
+ return g_task_propagate_pointer (G_TASK (result), error);
+ }
+]|
+
+## 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()).
+
+
+ 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`.
+
+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 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
+
+
+
+
+
+ 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.
+
+
+
+
+
+ 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, 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
+
+
+
+
+
+ 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 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
+uninterruptable function. The #GTaskThreadFunc just needs to be
+careful that it does not modify any externally-visible state after
+it has been cancelled. To do that, the thread should call
+g_task_set_return_on_cancel() again to (atomically) set
+return-on-cancel %FALSE before making externally-visible changes;
+if the task gets cancelled before the return-on-cancel flag could
+be changed, g_task_set_return_on_cancel() will indicate this by
+returning %FALSE.
+
+You can disable and re-enable this flag multiple times if you wish.
+If the task's #GCancellable is cancelled while return-on-cancel is
+%FALSE, then calling g_task_set_return_on_cancel() to set it %TRUE
+again will cause the task to be cancelled at that point.
+
+If the task's #GCancellable is already cancelled before you call
+g_task_run_in_thread()/g_task_run_in_thread_sync(), then the
+#GTaskThreadFunc will still be run (for consistency), but the task
+will also be completed right away.
+
+ %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.
+
+
+
+
+
+ the #GTask
+
+
+
+ an opaque pointer indicating the source of this task
+
+
+
+
+
+ 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
+
+
+
+
+
+ Get's @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://git.gnome.org/browse/glib/tree/gio/tests/gdbus-test-fixture.c)
+
+Note that these examples only deal with isolating the D-Bus aspect of your
+service. To successfully run isolated unit tests on your service you may need
+some additional modifications to your test case fixture. For example; if your
+service uses GSettings and installs a schema then it is important that your test service
+not load the schema in the ordinary installed location (chances are that your service
+and schema files are not yet installed, or worse; there is an older version of the
+schema file sitting in the install location).
+
+Most of the time we can work around these obstacles using the
+environment. Since the environment is inherited by the D-Bus daemon
+created by #GTestDBus and then in turn inherited by any services the
+D-Bus daemon activates, using the setup routine for your fixture is
+a practical place to help sandbox your runtime environment. For the
+rather typical GSettings case we can work around this by setting
+`GSETTINGS_SCHEMA_DIR` to the in tree directory holding your schemas
+in the above fixture_setup() routine.
+
+The GSettings schemas need to be locally pre-compiled for this to work. This can be achieved
+by compiling the schemas locally as a step before running test cases, an autotools setup might
+do the following in the directory holding schemas:
+|[
+ all-am:
+ $(GLIB_COMPILE_SCHEMAS) .
+
+ 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()
+is 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
+
+
+
+
+ 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.
+
+
+
+
+ the #GTlsBackend
+
+
+
+
+
+ Gets the #GType of @backend’s #GDtlsServerConnection implementation.
+
+ the #GType of @backend’s #GDtlsServerConnection
+ implementation.
+
+
+
+
+ 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
+
+
+
+
+
+ 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 PEM-encoded data in @file. The
+returned certificate will be the first certificate found in @file. As
+of GLib 2.44, if @file contains more certificates it will try to load
+a certificate chain. All certificates will be verified in the order
+found (top-level certificate should be the last one in the file) and
+the #GTlsCertificate:issuer property of each certificate will be set
+accordingly if the verification succeeds. If any certificate in the
+chain cannot be verified, the first certificate in the file will
+still be returned.
+
+If @file cannot be read or parsed, the function will return %NULL and
+set @error. Otherwise, this behaves like
+g_tls_certificate_new_from_pem().
+
+ the new certificate, or %NULL on error
+
+
+
+
+ file containing a PEM-encoded certificate to import
+
+
+
+
+
+ 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 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 @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.
+
+(All other #GTlsCertificateFlags values will always be set or unset
+as appropriate.)
+
+ the appropriate #GTlsCertificateFlags
+
+
+
+
+ a #GTlsCertificate
+
+
+
+ the expected peer identity
+
+
+
+ the certificate of a trusted authority
+
+
+
+
+
+ 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
+
+
+
+
+
+ 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 @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.
+
+(All other #GTlsCertificateFlags values will always be set or unset
+as appropriate.)
+
+ 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.
+
+
+
+ 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.
+
+
+
+ The DER (binary) encoded representation of the certificate's
+private key, in either PKCS#1 format or unencrypted PKCS#8
+format. This property (or the #GTlsCertificate:private-key-pem
+property) can be set when constructing a key (eg, from a file),
+but cannot be read.
+
+PKCS#8 format is supported since 2.32; earlier releases only
+support PKCS#1. You can use the `openssl rsa`
+tool to convert PKCS#8 keys to PKCS#1.
+
+
+
+
+
+ The PEM (ASCII) encoded representation of the certificate's
+private key in either PKCS#1 format ("`BEGIN RSA PRIVATE
+KEY`") or unencrypted PKCS#8 format ("`BEGIN
+PRIVATE KEY`"). This property (or the
+#GTlsCertificate:private-key property) can be set when
+constructing a key (eg, from a file), but cannot be read.
+
+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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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 set which validation steps to perform (eg, with
+g_tls_client_connection_set_validation_flags()), or to describe why
+a particular certificate was rejected (eg, in
+#GTlsConnection::accept-certificate).
+
+ 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
+
+
+
+ #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
+
+
+
+
+
+ Copies session state from one connection to another. This is
+not normally needed, but may be used when the same session
+needs to be used between different endpoints as is required
+by some protocols such as FTP over TLS. @source should have
+already completed a handshake, and @conn should not have
+completed a handshake.
+
+
+
+
+
+ a #GTlsClientConnection
+
+
+
+ a #GTlsClientConnection
+
+
+
+
+
+ Copies session state from one connection to another. This is
+not normally needed, but may be used when the same session
+needs to be used between different endpoints as is required
+by some protocols such as FTP over TLS. @source should have
+already completed a handshake, and @conn should not have
+completed a handshake.
+
+
+
+
+
+ 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
+
+
+
+
+
+ Gets whether @conn will use SSL 3.0 rather than the
+highest-supported version of TLS; see
+g_tls_client_connection_set_use_ssl3().
+
+ whether @conn will use SSL 3.0
+
+
+
+
+ the #GTlsClientConnection
+
+
+
+
+
+ Gets @conn's validation flags
+
+ 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
+
+
+
+
+
+ If @use_ssl3 is %TRUE, this forces @conn to use SSL 3.0 rather than
+trying to properly negotiate the right version of TLS or SSL to use.
+This can be used when talking to servers that do not implement the
+fallbacks correctly and which will therefore fail to handshake with
+a "modern" TLS handshake attempt.
+
+
+
+
+
+ the #GTlsClientConnection
+
+
+
+ whether to use SSL 3.0
+
+
+
+
+
+ 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.
+
+
+
+
+
+ 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.
+
+
+
+ If %TRUE, tells the connection to use a fallback version of TLS
+or SSL, rather than trying to negotiate the best version of TLS
+to use. This can be used when talking to servers that don't
+implement version negotiation correctly and therefore refuse to
+handshake at all with a "modern" TLS handshake.
+
+Despite the property name, the fallback version is not
+necessarily SSL 3.0; if SSL 3.0 has been disabled, the
+#GTlsClientConnection will use the next highest available version
+(normally TLS 1.0) as the fallback version.
+
+
+
+ What steps to perform when validating a certificate received from
+a server. Server certificates that fail to validate in all of the
+ways indicated here will be rejected unless the application
+overrides the default via #GTlsConnection::accept-certificate.
+
+
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Attempts a TLS handshake on @conn.
+
+On the client side, it is never necessary to call this method;
+although the connection needs to perform a handshake after
+connecting (or after sending a "STARTTLS"-type command) and may
+need to rehandshake later if the server requests it,
+#GTlsConnection will handle this for you automatically when you try
+to send or receive data on the connection. However, you can call
+g_tls_connection_handshake() manually if you want to know for sure
+whether the initial handshake succeeded or failed (as opposed to
+just immediately trying to write to @conn's output stream, in which
+case if it fails, it may not be possible to tell if it failed
+before or after completing the handshake).
+
+Likewise, on the server side, although a handshake is necessary at
+the beginning of the communication, you do not need to call this
+function explicitly unless you want clearer error reporting.
+However, you may call g_tls_connection_handshake() later on to
+renegotiate parameters (encryption methods, etc) with the client.
+
+#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
+
+
+
+
+
+ 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 @conn's peer's certificate after the handshake has completed.
+(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. (It is not set
+during the emission of #GTlsConnection::accept-certificate.)
+
+ @conn's peer's certificate errors
+
+
+
+
+ a #GTlsConnection
+
+
+
+
+
+ Gets @conn rehandshaking mode. See
+g_tls_connection_set_rehandshake_mode() for details.
+
+ @conn's rehandshaking mode
+
+
+
+
+ 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) and may
+need to rehandshake later if the server requests it,
+#GTlsConnection will handle this for you automatically when you try
+to send or receive data on the connection. However, you can call
+g_tls_connection_handshake() manually if you want to know for sure
+whether the initial handshake succeeded or failed (as opposed to
+just immediately trying to write to @conn's output stream, in which
+case if it fails, it may not be possible to tell if it failed
+before or after completing the handshake).
+
+Likewise, on the server side, although a handshake is necessary at
+the beginning of the communication, you do not need to call this
+function explicitly unless you want clearer error reporting.
+However, you may call g_tls_connection_handshake() later on to
+renegotiate parameters (encryption methods, etc) with the client.
+
+#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.
+
+
+
+
+
+ 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).
+
+
+
+
+
+ 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
+
+
+
+
+
+ Sets how @conn behaves with respect to rehandshaking requests.
+
+%G_TLS_REHANDSHAKE_NEVER means that it will never agree to
+rehandshake after the initial handshake is complete. (For a client,
+this means it will refuse rehandshake requests from the server, and
+for a server, this means it will close the connection with an error
+if the client attempts to rehandshake.)
+
+%G_TLS_REHANDSHAKE_SAFELY means that the connection will allow a
+rehandshake only if the other end of the connection supports the
+TLS `renegotiation_info` extension. This is the default behavior,
+but means that rehandshaking will not work against older
+implementations that do not support that extension.
+
+%G_TLS_REHANDSHAKE_UNSAFELY means that the connection will allow
+rehandshaking even without the `renegotiation_info` extension. On
+the server side in particular, this is not recommended, since it
+leaves the server open to certain attacks. However, this mode is
+necessary if you need to allow renegotiation with older client
+software.
+
+
+
+
+
+ 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 #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 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().
+
+
+
+ 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 connection's peer's certificate, after the TLS handshake has
+completed and the certificate has been accepted. Note in
+particular that this is not yet set during the emission of
+#GTlsConnection::accept-certificate.
+
+(You can watch for a #GObject::notify signal on this property to
+detect when a handshake has occurred.)
+
+
+
+ The errors noticed-and-ignored while verifying
+#GTlsConnection:peer-certificate. Normally this should be 0, but
+it may not be if #GTlsClientConnection:validation-flags is not
+%G_TLS_CERTIFICATE_VALIDATE_ALL, or if
+#GTlsConnection::accept-certificate overrode the default
+behavior.
+
+
+
+ The rehandshaking mode. See
+g_tls_connection_set_rehandshake_mode().
+
+
+
+ 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.
+
+For a server-side connection, @peer_cert is the certificate
+presented by the client, if this was requested via the server's
+#GTlsServerConnection:authentication_mode. On the server side,
+the signal is always emitted when the client presents a
+certificate, and the certificate will only be accepted if a
+handler returns %TRUE.
+
+Note that if this signal is emitted as part of asynchronous I/O
+in the main thread, then you should not attempt to interact with
+the user before returning from the signal handler. If you want to
+let the user decide whether or not to accept the certificate, you
+would have to return %FALSE from the signal handler on the first
+attempt, and then after the connection attempt returns a
+%G_TLS_ERROR_HANDSHAKE, you can interact with the user, and if
+the user decides to accept the certificate, remember that fact,
+create a new connection, and return %TRUE from the signal handler
+the next time.
+
+If you are doing I/O in another thread, you do not
+need to worry about this, and can simply block in the signal
+handler until the UI thread returns an answer.
+
+ %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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #GTlsDatabase is used to lookup certificates and other information
+from a certificate or key store. It is an abstract base class which
+TLS library specific subtypes override.
+
+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.
+
+
+
+
+
+ Lookup a certificate by its handle.
+
+The handle should have been created by calling
+g_tls_database_create_certificate_handle() on a #GTlsDatabase object of
+the same TLS backend. The handle is designed to remain valid across
+instantiations of the database.
+
+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 lookup 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_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.
+
+
+
+
+
+ Lookup the issuer of @certificate in the database.
+
+The %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.
+
+ 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 lookup 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.
+
+
+
+
+
+ Lookup 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 lookup 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 after looking up and
+adding any missing certificates to the chain.
+
+@chain is a chain of #GTlsCertificate objects each pointing to the next
+certificate in the chain by its %issuer property. The chain may initially
+consist of one or more certificates. After the verification process is
+complete, @chain may be modified by adding missing certificates, or removing
+extra certificates. If a certificate anchor was found, then it is added to
+the @chain.
+
+@purpose describes the purpose (or usage) for which the certificate
+is being used. Typically @purpose will be set to #G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER
+which means that the certificate is being used to authenticate a server
+(and we are acting as the client).
+
+The @identity is used to check for pinned certificates (trust exceptions)
+in the database. These will override the normal verification process on a
+host by host basis.
+
+Currently there are no @flags, and %G_TLS_DATABASE_VERIFY_NONE should be
+used.
+
+If @chain is found to be valid, then the return value will be 0. If
+@chain is found to be invalid, then the return value will indicate
+the problems found. If the function is unable to determine whether
+@chain is valid or not (eg, because @cancellable is triggered
+before it completes) then the return value will be
+%G_TLS_CERTIFICATE_GENERIC_ERROR and @error will be set
+accordingly. @error is not set when @chain is successfully analyzed
+but found to be invalid.
+
+This function can block, use g_tls_database_verify_chain_async() to perform
+the verification operation asynchronously.
+
+ 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.
+
+
+
+
+
+ Lookup a certificate by its handle.
+
+The handle should have been created by calling
+g_tls_database_create_certificate_handle() on a #GTlsDatabase object of
+the same TLS backend. The handle is designed to remain valid across
+instantiations of the database.
+
+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 lookup 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_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.
+
+
+
+
+
+ Lookup the issuer of @certificate in the database.
+
+The %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.
+
+ 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 lookup 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.
+
+
+
+
+
+ Lookup 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 lookup 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 after looking up and
+adding any missing certificates to the chain.
+
+@chain is a chain of #GTlsCertificate objects each pointing to the next
+certificate in the chain by its %issuer property. The chain may initially
+consist of one or more certificates. After the verification process is
+complete, @chain may be modified by adding missing certificates, or removing
+extra certificates. If a certificate anchor was found, then it is added to
+the @chain.
+
+@purpose describes the purpose (or usage) for which the certificate
+is being used. Typically @purpose will be set to #G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER
+which means that the certificate is being used to authenticate a server
+(and we are acting as the client).
+
+The @identity is used to check for pinned certificates (trust exceptions)
+in the database. These will override the normal verification process on a
+host by host basis.
+
+Currently there are no @flags, and %G_TLS_DATABASE_VERIFY_NONE should be
+used.
+
+If @chain is found to be valid, then the return value will be 0. If
+@chain is found to be invalid, then the return value will indicate
+the problems found. If the function is unable to determine whether
+@chain is valid or not (eg, because @cancellable is triggered
+before it completes) then the return value will be
+%G_TLS_CERTIFICATE_GENERIC_ERROR and @error will be set
+accordingly. @error is not set when @chain is successfully analyzed
+but found to be invalid.
+
+This function can block, use g_tls_database_verify_chain_async() to perform
+the verification operation asynchronously.
+
+ 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_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
+
+
+ A certificate could not be parsed
+
+
+ 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().
+
+
+ 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 an request certificate user interaction request. This should be once
+the g_tls_interaction_request_certificate_async() completion callback is called.
+
+If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection
+passed to g_tls_interaction_request_certificate_async() will have had its
+#GTlsConnection:certificate filled in.
+
+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 an request certificate user interaction request. This should be once
+the g_tls_interaction_request_certificate_async() completion callback is called.
+
+If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection
+passed to g_tls_interaction_request_certificate_async() will have had its
+#GTlsConnection:certificate filled in.
+
+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.
+
+
+
+
+
+ When to allow rehandshaking. See
+g_tls_connection_set_rehandshake_mode().
+
+ 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.
+
+Note that `<gio/gunixconnection.h>` belongs to the UNIX-specific
+GIO interfaces, thus you have to use the `gio-unix-2.0.pc`
+pkg-config file when using it.
+
+ 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.
+
+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.
+
+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().
+
+ 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_ADDRESS_UNIX family by using g_socket_send_message()
+and received using g_socket_receive_message().
+
+Note that `<gio/gunixfdlist.h>` belongs to the UNIX-specific GIO
+interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
+file when using it.
+
+ 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_ADDRESS_UNIX family). The file descriptors are copied
+between processes by the kernel.
+
+For an easier way to send and receive file descriptors over
+stream-oriented UNIX sockets, see g_unix_connection_send_fd() and
+g_unix_connection_receive_fd().
+
+Note that `<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.
+
+
+
+
+
+
+ #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.
+
+Note that `<gio/gunixsocketaddress.h>` belongs to the UNIX-specific GIO
+interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file
+when using it.
+
+
+ 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` and `network`. 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().
+
+
+
+ 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.
+
+
+
+
+ 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 lookup 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 #GAsyncReady structure will be
+passed to the callback. That callback should then call
+g_volume_mount_finish() with the #GVolume instance and the
+#GAsyncReady data to see if the operation was completed
+successfully. If an @error is present when g_volume_mount_finish()
+is called, then it will be filled with any error information.
+
+## 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_HAL_UDI, #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 identfier, 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 identfier, 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 identfier, 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.
+
+ 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
+
+Similary, if implementing g_volume_monitor_adopt_orphan_mount(),
+the implementor must take a reference to @mount and return it in
+its g_volume_get_mount() implemented. Also, the implementor must
+listen for the "unmounted" signal on @mount and give up its
+reference upon handling that signal.
+
+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.
+
+
+
+
+
+ Emitted when a mount is about to be removed.
+
+
+
+
+
+ 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
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Zlib decompression
+
+
+ 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
+
+
+
+ Zlib decompression
+
+
+ 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
+
+
+
+
+ an 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 '.'.
+
+ %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
+
+
+
+
+
+ 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.
+
+
+
+
+
+ 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.
+
+ %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.
+
+
+
+
+
+ the uri to show
+
+
+
+
+
+
+
+
+
+ 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 a 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().
+
+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().
+
+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 an 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 an 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 an 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 an 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.
+
+
+
+
+
+ an identifier obtained from g_bus_own_name()
+
+
+
+
+
+ Stops watching a name.
+
+
+
+
+
+ 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 a owner respectively known to lose its
+owner. Callbacks will be invoked in the
+[thread-default main context][g-main-context-push-thread-default]
+of the thread you are calling this function from.
+
+You are guaranteed that one of the handlers will be invoked after
+calling this function. When you are done watching the name, just
+call g_bus_unwatch_name() with the watcher id this function
+returns.
+
+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 an 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 an 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 an 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 an 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
+
+
+
+
+
+ Gets the mime type for the content type, if one is registered.
+
+ the registered mime type for the given @type,
+ or %NULL if unknown.
+
+
+
+
+ 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 string, 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
+
+
+
+
+
+ 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 #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).
+
+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 a error domain.
+
+
+
+ An error code.
+
+
+
+ A D-Bus error name.
+
+
+
+
+
+ Helper function for associating a #GError error domain with D-Bus error names.
+
+
+
+
+
+ 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 a error domain.
+
+
+
+ An error code.
+
+
+
+ A D-Bus error name.
+
+
+
+
+
+ Generate a D-Bus GUID that can be used with
+e.g. g_dbus_connection_new().
+
+See the D-Bus specification regarding what strings are valid D-Bus
+GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).
+
+ 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'][G-VARIANT-TYPE-INT32:CAPS]. It will also fail for any #GType
+(including e.g. #G_TYPE_OBJECT and #G_TYPE_BOXED derived-types) not
+in the table above.
+
+Note that if @gvalue is of type #G_TYPE_VARIANT and its value is
+%NULL, the empty #GVariant instance (never %NULL) for @type is
+returned (e.g. 0 for scalar types, the empty string for string types,
+'/' for object path types, the empty array for any array type and so on).
+
+See the g_dbus_gvariant_to_gvalue() function for how to convert a
+#GVariant to a #GValue.
+
+ A #GVariant (never floating) of #GVariantType @type holding
+ the data from @gvalue or %NULL 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.
+
+
+
+
+
+ Checks if @string is a D-Bus GUID.
+
+See the D-Bus specification regarding what strings are valid D-Bus
+GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).
+
+ %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.
+
+
+
+
+
+ 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
+
+
+
+
+
+ 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
+
+
+
+
+
+ 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
+
+
+
+
+
+ Deserializes a #GIcon previously serialized using g_icon_serialize().
+
+ a #GIcon, or %NULL when deserialization fails.
+
+
+
+
+ a #GVariant created with g_icon_serialize()
+
+
+
+
+
+ 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.
+
+
+
+
+
+ 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.
+
+
+
+
+
+ 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 implementes 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 implementes 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.
+
+ 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
+
+
+
+
+
+ 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
+
+
+
+
+ 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.
+
+
+
+
+
+ Lookup "gio-proxy" extension point for a proxy implementation that supports
+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.
+
+
+
+
+ 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().
+
+ 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
+
+
+
+
+ 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`
+
+
+
+
+
+ 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().
+
+ 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().
+
+ 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.
+
+
+
+
+
+ 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 path.
+
+ %TRUE if the unix mount is for a system path.
+
+
+
+
+ a #GUnixMount.
+
+
+
+
+
+ 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/gir-files/GstNet-1.0.gir b/gir-files/GstNet-1.0.gir
new file mode 100644
index 000000000..81e10263e
--- /dev/null
+++ b/gir-files/GstNet-1.0.gir
@@ -0,0 +1,851 @@
+
+
+
+
+
+
+
+
+
+ The size of the packets sent between network clocks.
+
+
+
+ #GstNetAddressMeta can be used to store a network address (a #GSocketAddress)
+in a #GstBuffer so that it network elements can track the to and from address
+of the buffer.
+
+ the parent type
+
+
+
+ a #GSocketAddress stored as metadata
+
+
+
+
+
+
+
+
+
+ #GstNetClientClock implements a custom #GstClock that synchronizes its time
+to a remote time provider such as #GstNetTimeProvider. #GstNtpClock
+implements a #GstClock that synchronizes its time to a remote NTPv4 server.
+
+A new clock is created with gst_net_client_clock_new() or
+gst_ntp_clock_new(), which takes the address and port of the remote time
+provider along with a name and an initial time.
+
+This clock will poll the time provider and will update its calibration
+parameters based on the local and remote observations.
+
+The "round-trip" property limits the maximum round trip packets can take.
+
+Various parameters of the clock can be configured with the parent #GstClock
+"timeout", "window-size" and "window-threshold" object properties.
+
+A #GstNetClientClock and #GstNtpClock is typically set on a #GstPipeline with
+gst_pipeline_use_clock().
+
+If you set a #GstBus on the clock via the "bus" object property, it will
+send @GST_MESSAGE_ELEMENT messages with an attached #GstStructure containing
+statistics about clock accuracy and network traffic.
+
+ Create a new #GstNetClientInternalClock that will report the time
+provided by the #GstNetTimeProvider on @remote_address and
+@remote_port.
+
+ a new #GstClock that receives a time from the remote
+clock.
+
+
+
+
+ a name for the clock
+
+
+
+ the address or hostname of the remote clock provider
+
+
+
+ the port of the remote clock provider
+
+
+
+ initial time of the clock
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #GstNetControlMessageMeta can be used to store control messages (ancillary
+data) which was received with or is to be sent alongside the buffer data.
+When used with socket sinks and sources which understand this meta it allows
+sending and receiving ancillary data such as unix credentials (See
+#GUnixCredentialsMessage) and Unix file descriptions (See #GUnixFDMessage).
+
+ the parent type
+
+
+
+ a #GSocketControlMessage stored as metadata
+
+
+
+
+
+
+
+
+
+ Various functions for receiving, sending an serializing #GstNetTimePacket
+structures.
+
+ the local time when this packet was sent
+
+
+
+ the remote time observation
+
+
+
+ Creates a new #GstNetTimePacket from a buffer received over the network. The
+caller is responsible for ensuring that @buffer is at least
+#GST_NET_TIME_PACKET_SIZE bytes long.
+
+If @buffer is #NULL, the local and remote times will be set to
+#GST_CLOCK_TIME_NONE.
+
+MT safe. Caller owns return value (gst_net_time_packet_free to free).
+
+ The new #GstNetTimePacket.
+
+
+
+
+ a buffer from which to construct the packet, or NULL
+
+
+
+
+
+
+
+ Make a copy of @packet.
+
+ a copy of @packet, free with gst_net_time_packet_free().
+
+
+
+
+ the #GstNetTimePacket
+
+
+
+
+
+ Free @packet.
+
+
+
+
+
+ the #GstNetTimePacket
+
+
+
+
+
+ Sends a #GstNetTimePacket over a socket.
+
+MT safe.
+
+ TRUE if successful, FALSE in case an error occurred.
+
+
+
+
+ the #GstNetTimePacket to send
+
+
+
+ socket to send the time packet on
+
+
+
+ address to send the time packet to
+
+
+
+
+
+ Serialized a #GstNetTimePacket into a newly-allocated sequence of
+#GST_NET_TIME_PACKET_SIZE bytes, in network byte order. The value returned is
+suitable for passing to write(2) or sendto(2) for communication over the
+network.
+
+MT safe. Caller owns return value (g_free to free).
+
+ A newly allocated sequence of #GST_NET_TIME_PACKET_SIZE bytes.
+
+
+
+
+ the #GstNetTimePacket
+
+
+
+
+
+ Receives a #GstNetTimePacket over a socket. Handles interrupted system
+calls, but otherwise returns NULL on error.
+
+ a new #GstNetTimePacket, or NULL on error. Free
+ with gst_net_time_packet_free() when done.
+
+
+
+
+ socket to receive the time packet on
+
+
+
+ address of variable to return sender address
+
+
+
+
+
+
+ This object exposes the time of a #GstClock on the network.
+
+A #GstNetTimeProvider is created with gst_net_time_provider_new() which
+takes a #GstClock, an address and a port number as arguments.
+
+After creating the object, a client clock such as #GstNetClientClock can
+query the exposed clock over the network for its values.
+
+The #GstNetTimeProvider typically wraps the clock used by a #GstPipeline.
+
+
+ Allows network clients to get the current time of @clock.
+
+ the new #GstNetTimeProvider, or NULL on error
+
+
+
+
+ a #GstClock to export over the network
+
+
+
+ an address to bind on as a dotted quad
+ (xxx.xxx.xxx.xxx), IPv6 address, or NULL to bind to all addresses
+
+
+
+ a port to bind on, or 0 to let the kernel choose
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Create a new #GstNtpClock that will report the time provided by
+the NTPv4 server on @remote_address and @remote_port.
+
+ a new #GstClock that receives a time from the remote
+clock.
+
+
+
+
+ a name for the clock
+
+
+
+ the address or hostname of the remote clock provider
+
+
+
+ the port of the remote clock provider
+
+
+
+ initial time of the clock
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ PTP clock identification that can be passed to gst_ptp_init() to
+automatically select one based on the MAC address of interfaces
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ GstPtpClock implements a PTP (IEEE1588:2008) ordinary clock in slave-only
+mode, that allows a GStreamer pipeline to synchronize to a PTP network
+clock in some specific domain.
+
+The PTP subsystem can be initialized with gst_ptp_init(), which then starts
+a helper process to do the actual communication via the PTP ports. This is
+required as PTP listens on ports < 1024 and thus requires special
+privileges. Once this helper process is started, the main process will
+synchronize to all PTP domains that are detected on the selected
+interfaces.
+
+gst_ptp_clock_new() then allows to create a GstClock that provides the PTP
+time from a master clock inside a specific PTP domain. This clock will only
+return valid timestamps once the timestamps in the PTP domain are known. To
+check this, you can use gst_clock_wait_for_sync(), the GstClock::synced
+signal and gst_clock_is_synced().
+
+To gather statistics about the PTP clock synchronization,
+gst_ptp_statistics_callback_add() can be used. This gives the application
+the possibility to collect all kinds of statistics from the clock
+synchronization.
+
+ Creates a new PTP clock instance that exports the PTP time of the master
+clock in @domain. This clock can be slaved to other clocks as needed.
+
+If gst_ptp_init() was not called before, this will call gst_ptp_init() with
+default parameters.
+
+This clock only returns valid timestamps after it received the first
+times from the PTP master clock on the network. Once this happens the
+GstPtpClock::internal-clock property will become non-NULL. You can
+check this with gst_clock_wait_for_sync(), the GstClock::synced signal and
+gst_clock_is_synced().
+
+
+
+
+
+ Name of the clock
+
+
+
+ PTP domain
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Opaque #GstPtpClockClass structure.
+
+ parented to #GstSystemClockClass
+
+
+
+
+
+
+
+
+
+
+
+ The statistics can be the following structures:
+
+GST_PTP_STATISTICS_NEW_DOMAIN_FOUND:
+"domain" G_TYPE_UINT The domain identifier of the domain
+"clock" GST_TYPE_CLOCK The internal clock that is slaved to the
+ PTP domain
+
+GST_PTP_STATISTICS_BEST_MASTER_CLOCK_SELECTED:
+"domain" G_TYPE_UINT The domain identifier of the domain
+"master-clock-id" G_TYPE_UINT64 PTP clock identifier of the selected master
+ clock
+"master-clock-port" G_TYPE_UINT PTP port number of the selected master clock
+"grandmaster-clock-id" G_TYPE_UINT64 PTP clock identifier of the grandmaster clock
+
+GST_PTP_STATISTICS_PATH_DELAY_MEASURED:
+"domain" G_TYPE_UINT The domain identifier of the domain
+"mean-path-delay-avg" GST_TYPE_CLOCK_TIME Average mean path delay
+"mean-path-delay" GST_TYPE_CLOCK_TIME Latest mean path delay
+"delay-request-delay" GST_TYPE_CLOCK_TIME Delay of DELAY_REQ / DELAY_RESP messages
+
+GST_PTP_STATISTICS_TIME_UPDATED:
+"domain" G_TYPE_UINT The domain identifier of the domain
+"mean-path-delay-avg" GST_TYPE_CLOCK_TIME Average mean path delay
+"local-time" GST_TYPE_CLOCK_TIME Local time that corresponds to ptp-time
+"ptp-time" GST_TYPE_CLOCK_TIME Newly measured PTP time at local-time
+"estimated-ptp-time" GST_TYPE_CLOCK_TIME Estimated PTP time based on previous measurements
+"discontinuity" G_TYPE_INT64 Difference between estimated and measured PTP time
+"synced" G_TYPE_BOOLEAN Currently synced to the remote clock
+"r-squared" G_TYPE_DOUBLE R² of clock estimation regression
+"internal-time" GST_TYPE_CLOCK_TIME Internal time clock parameter
+"external-time" GST_TYPE_CLOCK_TIME External time clock parameter
+"rate-num" G_TYPE_UINT64 Internal/external rate numerator
+"rate-den" G_TYPE_UINT64 Internal/external rate denominator
+"rate" G_TYPE_DOUBLE Internal/external rate
+
+If %FALSE is returned, the callback is removed and never called again.
+
+
+
+
+
+ PTP domain identifier
+
+
+
+ New statistics
+
+
+
+ Data passed to gst_ptp_statistics_callback_add()
+
+
+
+
+
+ Attaches @addr as metadata in a #GstNetAddressMeta to @buffer.
+
+ a #GstNetAddressMeta connected to @buffer
+
+
+
+
+ a #GstBuffer
+
+
+
+ a @GSocketAddress to connect to @buffer
+
+
+
+
+
+ Attaches @message as metadata in a #GstNetControlMessageMeta to @buffer.
+
+ a #GstNetControlMessageMeta connected to @buffer
+
+
+
+
+ a #GstBuffer
+
+
+
+ a @GSocketControlMessage to attach to @buffer
+
+
+
+
+
+ Find the #GstNetAddressMeta on @buffer.
+
+ the #GstNetAddressMeta or %NULL when there
+is no such metadata on @buffer.
+
+
+
+
+ a #GstBuffer
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Receives a #GstNetTimePacket over a socket. Handles interrupted system
+calls, but otherwise returns NULL on error.
+
+ a new #GstNetTimePacket, or NULL on error. Free
+ with gst_net_time_packet_free() when done.
+
+
+
+
+ socket to receive the time packet on
+
+
+
+ address of variable to return sender address
+
+
+
+
+
+ Deinitialize the GStreamer PTP subsystem and stop the PTP clock. If there
+are any remaining GstPtpClock instances, they won't be further synchronized
+to the PTP network clock.
+
+
+
+
+
+ Initialize the GStreamer PTP subsystem and create a PTP ordinary clock in
+slave-only mode for all domains on the given @interfaces with the
+given @clock_id.
+
+If @clock_id is %GST_PTP_CLOCK_ID_NONE, a clock id is automatically
+generated from the MAC address of the first network interface.
+
+This function is automatically called by gst_ptp_clock_new() with default
+parameters if it wasn't called before.
+
+ %TRUE if the GStreamer PTP clock subsystem could be initialized.
+
+
+
+
+ PTP clock id of this process' clock or %GST_PTP_CLOCK_ID_NONE
+
+
+
+ network interfaces to run the clock on
+
+
+
+
+
+
+
+ Check if the GStreamer PTP clock subsystem is initialized.
+
+ %TRUE if the GStreamer PTP clock subsystem is intialized.
+
+
+
+
+ Check if PTP clocks are generally supported on this system, and if previous
+initializations did not fail.
+
+ %TRUE if PTP clocks are generally supported on this system, and
+previous initializations did not fail.
+
+
+
+
+ Installs a new statistics callback for gathering PTP statistics. See
+GstPtpStatisticsCallback for a list of statistics that are provided.
+
+ Id for the callback that can be passed to
+gst_ptp_statistics_callback_remove()
+
+
+
+
+ GstPtpStatisticsCallback to call
+
+
+
+ Data to pass to the callback
+
+
+
+ GDestroyNotify to destroy the data
+
+
+
+
+
+ Removes a PTP statistics callback that was previously added with
+gst_ptp_statistics_callback_add().
+
+
+
+
+
+ Callback id to remove
+
+
+
+
+
+