#GAction represents a single named action. The main interface to an action is that it can be activated with g_action_activate(). This results in the 'activate' signal being emitted. An activation has a #GVariant parameter (which may be %NULL). The correct type for the parameter is determined by a static parameter type (which is given at construction time). An action may optionally have a state, in which case the state may be set with g_action_set_state(). This call takes a #GVariant. The correct type for the state is determined by a static state type (which is given at construction time). The state may have a hint associated with it, specifying its valid range. #GAction is merely the interface to the concept of an action, as described above. Various implementations of actions exist, including #GSimpleAction and #GtkAction. In all cases, the implementing class is responsible for storing the name of the action, the parameter type, the enabled state, the optional state type and the state and emitting the appropriate signals when these change. The implementor responsible for filtering calls to g_action_activate() and g_action_set_state() for type safety and for the state being enabled. Probably the only useful thing to do with a #GAction is to put it inside of a #GSimpleActionGroup.

Activates the action. the parameter type given at construction time). If the parameter type was %NULL then @parameter must also be %NULL.

the parameter to the activation

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

Queries the name of @action.

the name of the action

Queries the type of the parameter that must be given when activating When activating the action using g_action_activate(), the #GVariant given to that function must be of the type returned by this function. In the case that this function returns %NULL, you must not give any #GVariant, but %NULL instead.

the parameter type

Queries the current state of @action. If the action is not stateful then %NULL will be returned. If the action is stateful then the type of the return value is the type given by g_action_get_state_type(). The return value (if non-%NULL) should be freed with g_variant_unref() when it is no longer required.

the current state of the action

Requests a hint about the valid range of values for the state of If %NULL is returned it either means that the action is not stateful or that there is no hint about the valid range of values for the state of the action. If a #GVariant array is returned then each item in the array is a returned then the tuple specifies the inclusive lower and upper bound of valid values for the state. In any case, the information is merely a hint. It may be possible to have a state value outside of the hinted range and setting a value within the range may fail. The return value (if non-%NULL) should be freed with g_variant_unref() when it is no longer required.

the state range hint

Queries the type of the state of @action. g_action_new_stateful()) then this function returns the #GVariantType of the state. This is the type of the initial value given as the state. All calls to g_action_set_state() must give a #GVariant of this type and g_action_get_state() will return a #GVariant of the same type. this function will return %NULL. In that case, g_action_get_state() will return %NULL and you must not call g_action_set_state().

the state type, if the action is stateful

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.

the new state

Activates the action. the parameter type given at construction time). If the parameter type was %NULL then @parameter must also be %NULL.

the parameter to the activation 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

Queries the name of @action.

the name of the action

the parameter type

the current state of the action

the state range hint

the state type, if the action is stateful

the new state If @action is currently enabled. If the action is disabled then calls to g_action_activate() and g_action_set_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. 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. #GActionGroup represents a group of actions. Each action in the group has a unique name (which is a string). All method calls, except g_action_group_list_actions() take the name of an action as an argument. The #GActionGroup API is meant to be the 'public' API to the action group. The calls here are exactly the interaction that 'external the action group implementation) are found on subclasses. This is why you will find -- for example -- g_action_group_get_enabled() but not an equivalent <function>set()</function> call. Signals are emitted on the action group in response to state changes on individual actions.

Emits the #GActionGroup::action-added signal on @action_group. This function should only be called by #GActionGroup implementations.

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.

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.

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.

the name of an action in the group

Activate the named action within @action_group. If the action is expecting a parameter, then the correct type of parameter must be given as @parameter. If the action is expecting no parameters then @parameter must be %NULL. See g_action_group_get_parameter_type().

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_state_type(). This call merely requests a change. The action may refuse to change its state or may change its state to something other than @value. See g_action_group_get_state_hint(). If the @value GVariant is floating, it is consumed.

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

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(), 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

the name of the action to query

Queries the current state of the named action within @action_group. If the action is not stateful then %NULL will be returned. If the action is stateful then the type of the return value is the type given by g_action_group_get_state_type(). The return value (if non-%NULL) should be freed with g_variant_unref() when it is no longer required.

the current state of the action

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 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

the name of the action to query

Queries the type of the state of the named action within If the action is stateful then this function returns the #GVariantType of the state. All calls to g_action_group_set_state() must give a #GVariant of this type and g_action_group_get_state() will return a #GVariant of the same type. If the action is not stateful then this function will return %NULL. In that case, g_action_group_get_state() will return %NULL and you must not call g_action_group_set_state(). The state type of a particular action will never change but it is possible for an action to be removed and for a new action to be added with the same name but a different state type.

the state type, if the action is stateful

the name of the action to query

Checks if the named action exists within @action_group.

whether the named action exists

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. actions in the groupb

a %NULL-terminated array of the names of the

Emits the #GActionGroup::action-added signal on @action_group. This function should only be called by #GActionGroup implementations.

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.

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.

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.

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_parameter_type().

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_state_type(). This call merely requests a change. The action may refuse to change its state or may change its state to something other than @value. See g_action_group_get_state_hint(). If the @value GVariant is floating, it is consumed.

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

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(), 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

the name of the action to query Queries the current state of the named action within @action_group. If the action is not stateful then %NULL will be returned. If the action is stateful then the type of the return value is the type given by g_action_group_get_state_type(). The return value (if non-%NULL) should be freed with g_variant_unref() when it is no longer required.

the current state of the action

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 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

the name of the action to query Queries the type of the state of the named action within If the action is stateful then this function returns the #GVariantType of the state. All calls to g_action_group_set_state() must give a #GVariant of this type and g_action_group_get_state() will return a #GVariant of the same type. If the action is not stateful then this function will return %NULL. In that case, g_action_group_get_state() will return %NULL and you must not call g_action_group_set_state(). The state type of a particular action will never change but it is possible for an action to be removed and for a new action to be added with the same name but a different state type.

the state type, if the action is stateful

the name of the action to query Checks if the named action exists within @action_group.

whether the named action exists

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. actions in the groupb

a %NULL-terminated array of the names of the

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

the name of the action to check for

a %NULL-terminated array of the names of the

whether or not the action is currently enabled

the name of the action to query

the parameter type

the name of the action to query

the state type, if the action is stateful

the name of the action to query

the state range hint

the name of the action to query

the current state of the action

the name of the action to query

the name of the action to request the change on the new state

the name of the action to activate parameters to the activation

the name of an action in the group

the name of an action in the group whether or not the action is now enabled

the name of an action in the group

the name of the action

the parameter type

the state type, if the action is stateful

the state range hint

whether the action is enabled

the current state of the action

the new state

the parameter to the activation #GAppInfo and #GAppLaunchContext are used for describing and launching applications installed on the system. As of GLib 2.20, URIs will always be converted to POSIX paths (using g_file_get_path()) when using g_app_info_launch() even if the application requested an URI and not a POSIX path. For example for an desktop-file based application with Exec key <literal>totem %%U</literal> and a single URI, <literal>sftp://foo/file.avi</literal>, then <literal>/home/user/.gvfs/sftp on foo/file.avi</literal> will be passed. This will only work if a set of suitable GIO extensions (such as gvfs 2.26 compiled with FUSE support), is available and operational; if this is not the case, the URI will be passed unmodified to the application. Some URIs, such as <literal>mailto:</literal>, of course cannot be mapped to a POSIX path (in gvfs there's no FUSE mount for it); such URIs will be passed unmodified to the application. Specifically for gvfs 2.26 and later, the POSIX URI will be mapped back to the GIO URI in the #GFile constructors (since gvfs implements the #GVfs extension point). As such, if the application needs to examine the URI, it needs to use g_file_get_uri() or similar on #GFile. In other words, an application cannot assume that the URI passed to e.g. g_file_new_for_commandline_arg() is equal to the result of g_file_get_uri(). The following snippet illustrates this: <programlisting> GFile *f; char *uri; file = g_file_new_for_commandline_arg (uri_from_commandline); uri = g_file_get_uri (file); strcmp (uri, uri_from_commandline) == 0; // FALSE g_free (uri); if (g_file_has_uri_scheme (file, "cdda")) { // do something special with uri } g_object_unref (file); </programlisting> This code will work when both <literal>cdda://sr0/Track 1.wav</literal> and <literal>/home/user/.gvfs/cdda on sr0/Track 1.wav</literal> is passed to the application. It should be noted that it's generally not safe for applications to rely on the format of a particular URIs. Different launcher applications (e.g. file managers) may have different ideas of what a given URI means.

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 string.

Obtains the information whether the #GAppInfo can be deleted. See g_app_info_delete().

%TRUE if @appinfo can be deleted

Checks if a supported content type can be removed from an application. content types from a given @appinfo, %FALSE if not.

%TRUE if it is possible to remove supported

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

Creates a duplicate of a #GAppInfo.

a duplicate of @appinfo.

Checks if two #GAppInfos are equal.

%TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise.

the second #GAppInfo.

Gets the commandline with which the application will be started. or %NULL if this information is not available

a string containing the @appinfo's commandline,

Gets a human-readable description of an installed application. application @appinfo, or %NULL if none.

a string containing a description of the

Gets the display name of the application. The display name is often more descriptive to the user than the name itself. no display name is available.

the display name of the application for @appinfo, or the name if

Gets the executable's name for the installed application. binaries name

a string containing the @appinfo's application

Gets the icon for the application.

the default #GIcon for @appinfo.

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.

Gets the installed name of the application.

the name of the application for @appinfo.

Launches the application. Passes @files to the launched application as arguments, using the optional @launch_context to get information about the details of the launcher (like what screen it is on). On error, @error will be set accordingly. To launch the application without arguments pass a %NULL @files list. Note that even if the launch is successful the application launched can fail to start if it runs into problems during startup. There is no way to detect this. Some URIs can be changed when passed through a GFile (for instance unsupported uris with strange formats like mailto:), so if you have a textual uri you want to pass in as argument, consider using g_app_info_launch_uris() instead. On UNIX, this function sets the <envar>GIO_LAUNCHED_DESKTOP_FILE</envar> environment variable with the path of the launched desktop file and <envar>GIO_LAUNCHED_DESKTOP_FILE_PID</envar> to the process id of the launched process. This can be used to ignore <envar>GIO_LAUNCHED_DESKTOP_FILE</envar>, should it be inherited by further processes. The <envar>DISPLAY</envar> and <envar>DESKTOP_STARTUP_ID</envar> environment variables are also set, based on information provided in @launch_context.

%TRUE on successful launch, %FALSE otherwise.

a #GList of #GFile objects a #GAppLaunchContext or %NULL

Launches the application. Passes @uris to the launched application as arguments, using the optional @launch_context to get information about the details of the launcher (like what screen it is on). On error, @error will be set accordingly. To lauch the application without arguments pass a %NULL @uris list. Note that even if the launch is successful the application launched can fail to start if it runs into problems during startup. There is no way to detect this.

%TRUE on successful launch, %FALSE otherwise.

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 string.

Sets the application as the default handler for the given file extension.

%TRUE on success, %FALSE on error.

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.

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.

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.

Checks if the application accepts files as arguments.

%TRUE if the @appinfo supports files.

Checks if the application supports reading files and directories from URIs.

%TRUE if the @appinfo supports URIs.

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 string. Obtains the information whether the #GAppInfo can be deleted. See g_app_info_delete().

%TRUE if @appinfo can be deleted

Checks if a supported content type can be removed from an application. content types from a given @appinfo, %FALSE if not.

%TRUE if it is possible to remove supported

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

Creates a duplicate of a #GAppInfo.

a duplicate of @appinfo.

Checks if two #GAppInfos are equal.

%TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise.

the second #GAppInfo. Gets the commandline with which the application will be started. or %NULL if this information is not available

a string containing the @appinfo's commandline,

Gets a human-readable description of an installed application. application @appinfo, or %NULL if none.

a string containing a description of the

Gets the display name of the application. The display name is often more descriptive to the user than the name itself. no display name is available.

the display name of the application for @appinfo, or the name if

Gets the executable's name for the installed application. binaries name

a string containing the @appinfo's application

Gets the icon for the application.

the default #GIcon for @appinfo.

a string containing the application's ID.

Gets the installed name of the application.

the name of the application for @appinfo.

%TRUE on successful launch, %FALSE otherwise.

a #GList of #GFile objects a #GAppLaunchContext or %NULL Launches the application. Passes @uris to the launched application as arguments, using the optional @launch_context to get information about the details of the launcher (like what screen it is on). On error, @error will be set accordingly. To lauch the application without arguments pass a %NULL @uris list. Note that even if the launch is successful the application launched can fail to start if it runs into problems during startup. There is no way to detect this.

%TRUE on successful launch, %FALSE otherwise.

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 string. Sets the application as the default handler for the given file extension.

%TRUE on success, %FALSE on error.

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.

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.

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.

Checks if the application accepts files as arguments.

%TRUE if the @appinfo supports files.

Checks if the application supports reading files and directories from URIs.

%TRUE if the @appinfo supports URIs.

Flags used when creating a #GAppInfo. Application Information interface, for operating system portability.

a duplicate of @appinfo.

%TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise.

the second #GAppInfo.

a string containing the application's ID.

the name of the application for @appinfo.

a string containing a description of the

a string containing the @appinfo's application

the default #GIcon for @appinfo.

%TRUE on successful launch, %FALSE otherwise.

a #GList of #GFile objects a #GAppLaunchContext or %NULL

%TRUE if the @appinfo supports URIs.

%TRUE if the @appinfo supports files.

%TRUE on successful launch, %FALSE otherwise.

a #GList containing URIs to launch. a #GAppLaunchContext or %NULL

%TRUE if the @appinfo should be shown, %FALSE otherwise.

%TRUE on success, %FALSE on error.

the content type.

%TRUE on success, %FALSE on error.

a string containing the file extension (without the dot).

%TRUE on success, %FALSE on error.

a string.

%TRUE if it is possible to remove supported

%TRUE on success, %FALSE on error.

a string.

%TRUE if @appinfo can be deleted

%TRUE if @appinfo has been deleted

a string containing the @appinfo's commandline,

the display name of the application for @appinfo, or the name if

%TRUE on success, %FALSE on error.

the content type. 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 <envar>DISPLAY</envar> environment variable.

a display string for the display.

a #GAppInfo a #GList of #GFile objects

Initiates startup notification for the application and returns the <envar>DESKTOP_STARTUP_ID</envar> for the launched operation, if supported. Startup notification IDs are defined in the <ulink url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt"> FreeDesktop.Org Startup Notifications standard</ulink>. not supported.

a startup notification ID for the application, or %NULL if

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().

the startup notification id that was returned by g_app_launch_context_get_startup_notify_id().

a display string for the display.

a #GAppInfo a #GList of #GFile objects Initiates startup notification for the application and returns the <envar>DESKTOP_STARTUP_ID</envar> for the launched operation, if supported. Startup notification IDs are defined in the <ulink url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt"> FreeDesktop.Org Startup Notifications standard</ulink>. not supported.

a startup notification ID for the application, or %NULL if

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().

the startup notification id that was returned by g_app_launch_context_get_startup_notify_id().

a display string for the display.

a #GAppInfo a #GList of #GFile objects

a startup notification ID for the application, or %NULL if

a #GAppInfo a #GList of of #GFile objects

the startup notification id that was returned by g_app_launch_context_get_startup_notify_id().

A #GApplication is the foundation of an application, unique for a given application identifier. The GApplication class wraps some low-level platform-specific services and is intended to act as the foundation for higher-level application classes such as #GtkApplication or #MxApplication. In general, you should not use this class outside of a higher level framework. One of the core features that GApplication provides is process uniqueness, in the context of a "session". The session concept is platform-dependent, but corresponds roughly to a graphical desktop login. When your application is launched again, its arguments are passed through platform communication to the already running program. The already running instance of the program is called the <firstterm>primary instance</firstterm>. Before using GApplication, you must choose an "application identifier". The expected form of an application identifier is very close to that of of a <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface">DBus bus name</ulink>. For details on valid application identifiers, see g_application_id_is_valid(). The application identifier is claimed by the application as a well-known bus name on the user's session bus. This means that the uniqueness of your application is scoped to the current session. It also means that your application may provide additional services (through registration of other object paths) at that bus name. The registration of these object paths should be done with the shared GDBus session bus. Note that due to the internal architecture of GDBus, method calls can be dispatched at any time (even if a main loop is not running). For this reason, you must ensure that any object paths that you wish to register are registered before #GApplication attempts to acquire the bus name of your application (which happens in g_application_register()). Unfortunately, this means that you cannot use g_application_get_is_remote() to decide if you want to register object paths. GApplication provides convenient life cycle management by maintaining a <firstterm>use count</firstterm> for the primary application instance. The use count can be changed using g_application_hold() and g_application_release(). If it drops to zero, the application exits. GApplication also implements the #GActionGroup interface and lets you easily export actions by adding them with g_application_set_action_group(). When invoking an action by calling g_action_group_activate_action() on the application, it is always invoked in the primary instance. There is a number of different entry points into a #GApplication: <itemizedlist> <listitem>via 'Activate' (i.e. just starting the application)</listitem> <listitem>via 'Open' (i.e. opening some files)</listitem> <listitem>by handling a command-line</listitem> <listitem>via activating an action</listitem> </itemizedlist> The #GApplication::startup signal lets you handle the application initialization for all of these in a single place. Regardless of which of these entry points is used to start the application, GApplication passes some <firstterm id="platform-data">platform data</firstterm> from the launching instance to the primary instance, in the form of a #GVariant dictionary mapping strings to variants. To use platform data, override the @before_emit or @after_emit virtual functions in your #GApplication subclass. When dealing with #GApplicationCommandline objects, the platform data is directly available via g_application_command_line_get_cwd(), g_application_command_line_get_environ() and g_application_command_line_get_platform_data(). As the name indicates, the platform data may vary depending on the operating system, but it always includes the current directory (key "cwd"), and optionally the environment (ie the set of environment variables and their values) of the calling process (key "environ"). The environment is only added to the platform data if the #G_APPLICATION_SEND_ENVIONMENT flag is set. GApplication subclasses can add their own platform data by overriding the @add_platform_data virtual function. For instance, #GtkApplication adds startup notification data in this way. To parse commandline arguments you may handle the #GApplication::command-line signal or override the local_command_line() vfunc, to parse them in either the primary instance or the local instance, respectively. <example id="gapplication-example-open"><title>Opening files with a GApplication</title> <programlisting> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-open.c"> <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback> </xi:include> </programlisting> </example> <example id="gapplication-example-actions"><title>A GApplication with actions</title> <programlisting> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-actions.c"> <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback> </xi:include> </programlisting> </example> Creates a new #GApplication instance. This function calls g_type_init() for you. The application id must be valid. See g_application_id_is_valid().

a new #GApplication instance

the application id the application flags Checks if @application_id is a valid application identifier. A valid ID is required for calls to g_application_new() and g_application_set_application_id(). For convenience, the restrictions on application identifiers are reproduced here: <itemizedlist> <listitem>Application identifiers must contain only the ASCII characters "[A-Z][a-z][0-9]_-." and must not begin with a digit.</listitem> <listitem>Application identifiers must contain at least one '.' (period) character (and thus at least three elements).</listitem> <listitem>Application identifiers must not begin or end with a '.' (period) character.</listitem> <listitem>Application identifiers must not contain consecutive '.' (period) characters.</listitem> <listitem>Application identifiers must not exceed 255 characters.</listitem> </itemizedlist>

%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.

Opens the given files. In essence, this results in the #GApplication::open signal being emitted in the primary instance. intended to be used by applications that have multiple modes for for this functionality, you should use "". The application must be registered before calling this function and it must have the %G_APPLICATION_HANDLES_OPEN flag set.

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.

Gets the unique identifier for @application.

the identifier for @application, owned by @application

Gets the flags for @application. See #GApplicationFlags.

the flags for @application

Gets the current inactivity timeout for the application. This is the amount of time (in milliseconds) after the last call to g_application_release() before the application stops running.

the timeout, in milliseconds

Checks if @application is registered. An application is registered if g_application_register() has been successfully called.

%TRUE if @application is registered

Checks if @application is remote. If @application is remote then it means that another instance of application already exists (the 'primary' instance). Calls to perform actions on @application will result in the actions being performed by the primary instance. The value of this property cannot be accessed before g_application_register() has been called. See g_application_get_is_registered().

%TRUE if @application is remote

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().

an array of #GFiles to open the length of the @files array a hint (or ""), but never %NULL Attempts registration of the application. This is the point at which the application discovers if it is the primary instance or merely acting as a remote for an already-existing primary instance. This is implemented by attempting to acquire the application identifier as a unique bus name on the session bus using GDBus. Due to the internal architecture of GDBus, method calls can be dispatched at any time (even if a main loop is not running). For this reason, you must ensure that any object paths that you wish to register are registered before calling this function. If the application has already been registered then %TRUE is returned with no work performed. The #GApplication::startup signal is emitted if registration succeeds and @application is the primary instance. In the event of an error (such as @cancellable being cancelled, or a failure to connect to the session bus), %FALSE is returned and @error is set appropriately. instance is or is not the primary instance of the application. See g_application_get_is_remote() for that.

%TRUE if registration succeeded

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().

Runs the application. This function is intended to be run from main() and its return value is intended to be returned by main(). Although you are expected to pass the @argc, @argv parameters from main() to this function, it is possible to pass %NULL if @argv is not available or commandline handling is not required. First, the local_command_line() virtual function is invoked. This function always runs on the local instance. It gets passed a pointer to a %NULL-terminated copy of @argv and is expected to remove the arguments that it handled (shifting up remaining arguments). See <xref linkend="gapplication-example-cmdline2"/> for an example of parsing @argv manually. Alternatively, you may use the #GOptionContext API, after setting <literal>argc = g_strv_length (argv);</literal>. The last argument to local_command_line() is a pointer to the @status variable which can used to set the exit status that is returned from g_application_run(). If local_command_line() returns %TRUE, the command line is expected to be completely handled, including possibly registering as the primary instance, calling g_application_activate() or g_application_open(), etc. If local_command_line() returns %FALSE then the application is registered and the #GApplication::command-line signal is emitted in the primary instance (which may or may not be this instance). The signal handler gets passed a #GApplicationCommandline object that (among other things) contains the remaining commandline arguments that have not been handled by local_command_line(). If the application has the %G_APPLICATION_HANDLES_COMMAND_LINE flag set then the default implementation of local_command_line() always returns %FALSE immediately, resulting in the commandline always being handled in the primary instance. Otherwise, the default implementation of local_command_line() tries to do a couple of things that are probably reasonable for most applications. First, g_application_register() is called to attempt to register the application. If that works, then the command line arguments are inspected. If no commandline arguments are given, then g_application_activate() is called. If commandline arguments are given and the %G_APPLICATION_HANDLES_OPEN flag is set then they are assumed to be filenames and g_application_open() is called. If you need to handle commandline arguments that are not filenames, and you don't mind commandline handling to happen in the primary instance, you should set %G_APPLICATION_HANDLED_COMMAND_LINE and process the commandline arguments in your #GApplication::command-line signal handler, either manually or using the #GOptionContext API. If you are interested in doing more complicated local handling of the commandline then you should implement your own #GApplication subclass and override local_command_line(). In this case, you most likely want to return %TRUE from your local_command_line() implementation to suppress the default handling. See <xref linkend="gapplication-example-cmdline2"/> for an example. If, after the above is done, the use count of the application is zero then the exit status is returned immediately. If the use count is non-zero then the mainloop is run until the use count falls to zero, at which point 0 is returned. If the %G_APPLICATION_IS_SERVICE flag is set, then the exiting at around to provide its <emphasis>service</emphasis> to others).

the exit status

the argc from main() (or 0 if @argv is %NULL) the argv from main(), or %NULL Sets or unsets the group of actions associated with the application. These actions are the actions that can be remotely invoked. It is an error to call this function after the application has been registered.

a #GActionGroup, or %NULL Sets the unique identifier for @application. The application id can only be modified if @application has not yet been registered. The application id must be valid. See g_application_id_is_valid().

the identifier for @application Sets the flags for @application. The flags can only be modified if @application has not yet been registered. See #GApplicationFlags.

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.

the timeout, in milliseconds

the timeout, in milliseconds 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. process. See g_application_command_line_set_exit_status().

An integer that is set as the exit status for the calling

a #GApplicationCommandLine representing the passed commandline 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 ::startup signal is emitted on the primary instance immediately after registration. See g_application_register().

an array of #GFiles to open the length of the @files array a hint (or ""), but never %NULL

#GApplicationCommandLine represents a command-line invocation of an application. It is created by #GApplication and emitted in the #GApplication::command-line signal and virtual function. The class contains the list of arguments that the program was invoked with. It is also possible to query if the commandline invocation was commandline to this process). The GApplicationCommandLine object can provide the @argc and @argv parameters for use with the #GOptionContext command-line parsing API, with the g_application_command_line_get_arguments() function. See <xref linkend="gapplication-example-cmdline3"/> for an example. The exit status of the originally-invoked process may be set and messages can be printed to stdout or stderr of that process. The lifecycle of the originally-invoked process is tied to the lifecycle dropped). The main use for #GApplicationCommandline (and the #GApplication::command-line signal) is 'Emacs server' like use cases: You can set the <envar>EDITOR</envar> environment variable to have e.g. git use your favourite editor to edit commit messages, and if you already have an instance of the editor running, the editing will happen in the running instance, instead of opening a new one. An important aspect of this use case is that the process that gets started by git does not return until the editing is done. <example id="gapplication-example-cmdline"><title>Handling commandline arguments with GApplication</title> <para> A simple example where the commandline is completely handled in the #GApplication::command-line handler. The launching instance exits once the signal handler in the primary instance has returned, and the return value of the signal handler becomes the exit status of the launching instance. </para> <programlisting> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline.c"> <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback> </xi:include> </programlisting> </example> <example id="gapplication-example-cmdline2"><title>Split commandline handling</title> <para> An example of split commandline handling. Options that start with <literal>--local-</literal> are handled locally, all other options are passed to the #GApplication::command-line handler which runs in the primary instance. </para> <programlisting> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline2.c"> <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback> </xi:include> </programlisting> </example> <example id="gapplication-example-cmdline3"><title>Deferred commandline handling</title> <para> An example of deferred commandline handling. Here, the commandline is not completely handled before the #GApplication::command-line handler returns. Instead, we keep a reference to the GApplicationCommandline object and handle it later(in this example, in an idle). Note that it is necessary to hold the application until you are done with the commandline. </para> <para> This example also shows how to use #GOptionContext for parsing the commandline arguments. </para> <programlisting> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline3.c"> <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback> </xi:include> </programlisting> </example>

Gets the list of arguments that was passed on the command line. The strings in the array may contain non-utf8 data. The return value is %NULL-terminated and should be freed using g_strfreev(). containing the arguments (the argv)

the string array

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

Gets the contents of the 'environ' variable of the command line invocation, as would be returned by g_get_environ(), ie as a %NULL-terminated list of strings in the form 'NAME=VALUE'. The strings may contain non-utf8 data. The remote application usually does not send an environment. Use %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag set it is possible that the environment is still not available (due to invocation messages from other applications). The return value should not be modified or freed and is valid for as long as @cmdline exists. See g_application_command_line_getenv() if you are only interested in the value of a single environment variable. strings, or %NULL if they were not sent

the environment

Gets the exit status of @cmdline. See g_application_command_line_set_exit_status() for more information.

the exit status

Determines if @cmdline represents a remote invocation.

%TRUE if the invocation was remote

Gets the platform data associated with the invocation of @cmdline. This is a #GVariant dictionary containing information about the context in which the invocation occured. It typically contains information like the current working directory and the startup notification ID. For local invocation, it will be %NULL.

the platform data, or %NULL

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

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 printf-style format string 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 printf-style format string Sets the exit status that will be used when the invoking process exits. The return value of the #GApplication::command-line signal is passed to this function when the handler returns. This is the usual way of setting the exit status. In the event that you want the remote invocation to continue running and want to decide on the exit status in the future, you can use this call. For the case of a remote invocation, the remote process will typically exit when the last reference is dropped on @cmdline. The exit status of the remote process will be equal to the last value that was set with this function. In the case that the commandline invocation is local, the situation is slightly more complicated. If the commandline invocation results increased to a non-zero value) then the application is considered to have been 'successful' in a certain sense, and the exit status is always zero. If the application use count is zero, though, the exit status of the local #GApplicationCommandLine is used.

the exit status The <structname>GApplicationCommandLineClass</structname> structure contains private data only

Flags used to define the behaviour of a #GApplication. #GAskPasswordFlags are used to request specific information from the user, or to notify the user of their choices in an authentication situation. This is the asynchronous version of #GInitable; it behaves the same in all ways except that initialization is asynchronous. For more details see the descriptions on #GInitable. A class may implement both the #GInitable and #GAsyncInitable interfaces. Users of objects implementing this are not intended to use the interface method directly; instead it will be used automatically in various ways. For C applications you generally just call g_async_initable_new_async() directly, or indirectly via a foo_thing_new_async() wrapper. This will call g_async_initable_init_async() under the cover, calling back with %NULL and a set %GError on failure. A typical implementation might look something like this: |[ enum { NOT_INITIALIZED, INITIALIZING, INITIALIZED }; static void _foo_ready_cb (Foo *self) { GList *l; self->priv->state = INITIALIZED; for (l = self->priv->init_results; l != NULL; l = l->next) { GSimpleAsyncResult *simple = l->data; if (!self->priv->success) g_simple_async_result_set_error (simple, ...); g_simple_async_result_complete (simple); g_object_unref (simple); } g_list_free (self->priv->init_results); self->priv->init_results = NULL; } static void foo_init_async (GAsyncInitable *initable, int io_priority, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data) { Foo *self = FOO (initable); GSimpleAsyncResult *simple; simple = g_simple_async_result_new (G_OBJECT (initable) callback, user_data, foo_init_async); switch (self->priv->state) { case NOT_INITIALIZED: _foo_get_ready (self); self->priv->init_results = g_list_append (self->priv->init_results, simple); self->priv->state = INITIALIZING; break; case INITIALIZING: self->priv->init_results = g_list_append (self->priv->init_results, simple); break; case INITIALIZED: if (!self->priv->success) g_simple_async_result_set_error (simple, ...); g_simple_async_result_complete_in_idle (simple); g_object_unref (simple); break; } } static gboolean foo_init_finish (GAsyncInitable *initable, GAsyncResult *result, GError **error) { g_return_val_if_fail (g_simple_async_result_is_valid (result, G_OBJECT (initable), foo_init_async), FALSE); if (g_simple_async_result_propagate_error (G_SIMPLE_ASYNC_RESULT (result), error)) return FALSE; return TRUE; } static void foo_async_initable_iface_init (gpointer g_iface, gpointer data) { GAsyncInitableIface *iface = g_iface; iface->init_async = foo_init_async; iface->init_finish = foo_init_finish; } ]|

Starts asynchronous initialization of the object implementing the interface. This must be done before any real use of the object after initial construction. If the object also implements #GInitable you can optionally call g_initable_init() instead. When the initialization is finished, @callback will be called. You can then call g_async_initable_init_finish() to get the result of the initialization. Implementations may also support cancellation. If @cancellable is not %NULL, then initialization can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL, and the object doesn't support cancellable initialization, the error %G_IO_ERROR_NOT_SUPPORTED will be returned. If this function is not called, or returns with an error, then all operations on the object should fail, generally returning the error %G_IO_ERROR_NOT_INITIALIZED. to this function with the same argument should return the same results. Only the first call initializes the object; further calls return the result of the first call. This is so that it's safe to implement the singleton pattern in the GObject constructor function. For classes that also support the #GInitable interface, the default implementation of this method will run the g_initable_init() function in a thread, so if you want to support asynchronous initialization via threads, just implement the #GAsyncInitable interface without overriding any interface methods.

Finishes asynchronous initialization and returns the result. See g_async_initable_init_async(). will return %FALSE and set @error appropriately if present.

%TRUE if successful. If an error has occurred, this function

a #GAsyncResult.

the <link linkend="io-priority">I/O priority</link> 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(). will return %FALSE and set @error appropriately if present.

%TRUE if successful. If an error has occurred, this function

a #GAsyncResult. Finishes the async construction for the various g_async_initable_new calls, returning the created object or %NULL on error. g_object_unref().

a newly created #GObject, or %NULL on error. Free with

the #GAsyncResult.from the callback Provides an interface for asynchronous initializing object such that initialization may fail.

%TRUE if successful. If an error has occurred, this function

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. Applications may also take a reference to the #GAsyncResult and call "_finish()" later; however, the "_finish()" function may be called at most once. Example of a typical asynchronous operation flow: |[ void _theoretical_frobnitz_async (Theoretical *t, GCancellable *c, GAsyncReadyCallback *cb, gpointer u); gboolean _theoretical_frobnitz_finish (Theoretical *t, GAsyncResult *res, GError **e); static void frobnitz_result_func (GObject *source_object, GAsyncResult *res, gpointer user_data) { gboolean success = FALSE; success = _theoretical_frobnitz_finish (source_object, res, NULL); if (success) g_printf ("Hurray!\n"); else g_printf ("Uh oh!\n"); /* ... */ } int main (int argc, void *argv[]) { /* ... */ _theoretical_frobnitz_async (theoretical_data, NULL, frobnitz_result_func, NULL); /* ... */ } ]| The callback for an asynchronous operation is called only once, and is always called, even in the case of a cancelled operation. On cancellation the result is a %G_IO_ERROR_CANCELLED error. Some asynchronous operations are implemented using synchronous calls. These are run in a separate thread, if #GThread has been initialized, but otherwise they are sent to the Main Event Loop and processed in an idle function. So, if you truly need asynchronous operations, make sure to initialize #GThread.

Gets the source object from a #GAsyncResult. or %NULL if there is none.

a new reference to the source object for the @res,

Gets the user data from a #GAsyncResult.

the user data for @res.

Gets the source object from a #GAsyncResult. or %NULL if there is none.

a new reference to the source object for the @res,

Gets the user data from a #GAsyncResult.

the user data for @res.

Interface definition for #GAsyncResult.

the user data for @res.

a new reference to the source object for the @res,

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(). or -1 on error.

the number of bytes read into @stream's buffer, up to @count,

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. 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.

the number of bytes that will be read from the stream the <link linkend="io-priority">I/O priority</link> 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 #GAsyncResult

the number of bytes read into @stream's buffer, up to @count,

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. 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.

the number of bytes that will be read from the stream the <link linkend="io-priority">I/O priority</link> 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 #GAsyncResult Gets the size of the available data within the stream.

size of the available stream.

Gets the size of the input buffer.

the current buffer size.

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 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 #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.

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 #gsize

the number of bytes read into @stream's buffer, up to @count,

the number of bytes that will be read from the stream optional #GCancellable object, %NULL to ignore

the number of bytes that will be read from the stream the <link linkend="io-priority">I/O priority</link> of the request optional #GCancellable object a #GAsyncReadyCallback a #gpointer

a #gssize of the read stream, or %-1 on an error.

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. %FALSE otherwise.

%TRUE if the @stream's buffer automatically grows,

Gets the size of the buffer in the @stream.

the current size of the buffer.

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 #gboolean. Sets the size of the internal buffer to @size.

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(). Invoked when the name being watched is known not to have to have a owner.

The #GDBusConnection the name is being watched on. The name being watched. User data passed to g_bus_watch_name(). Flags used in g_bus_watch_name(). An enumeration for well-known message buses. 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, but not in multiple concurrent operations.

a #GCancellable.

Gets the top cancellable from the stack. if the stack is empty.

a #GCancellable from the top of the stack, or %NULL

Will set @cancellable to cancelled, and will emit the #GCancellable::cancelled signal. (However, see the warning about race conditions in the documentation for that signal if you are planning to connect to it.) This function is thread-safe. In other words, you can safely call it from a thread other than the one running the operation that was passed the @cancellable. The convention within gio is that cancelling an asynchronous operation causes it to complete asynchronously. That is, if you cancel the operation from the same thread in which it is running, then the operation's #GAsyncReadyCallback will not be invoked until the application returns to the main loop.

Convenience function to connect to the #GCancellable::cancelled signal. Also handles the race condition that may happen if the cancellable is cancelled right before connecting. time of the connect if @cancellable is already cancelled, or when @cancellable is cancelled in some thread. disconnected, or immediately if the cancellable is already cancelled. See #GCancellable::cancelled for details on how to use this. been cancelled.

The id of the signal handler or 0 if @cancellable has already

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.

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(). is not supported, or on errors.

A valid file descriptor. %-1 if the file descriptor

Checks if a cancellable job has been cancelled. FALSE if called with %NULL or if item is not cancelled.

%TRUE if @cancellable is cancelled,

Creates a #GPollFD corresponding to @cancellable; this can be passed to g_poll() and used to poll for cancellation. This is useful both for unix systems without a native poll and for portability to windows. When this function returns %TRUE, you should use g_cancellable_release_fd() to free up resources allocated for the If this function returns %FALSE, either no @cancellable was given or resource limits prevent this function from allocating the necessary structures for polling. (On Linux, you will likely have reached the maximum number of file descriptors.) The suggested way to handle these cases is to ignore the @cancellable. You are not supposed to read from the fd yourself, just check for readable status. Reading to unset the readable status is done with g_cancellable_reset(). failure to prepare the cancellable.

%TRUE if @pollfd was successfully initialized, %FALSE on

a pointer to a #GPollFD Pops @cancellable off the cancellable stack (verifying that @cancellable is on the top of the stack).

Pushes @cancellable onto the cancellable stack. The current cancellable can then be recieved using g_cancellable_get_current(). This is useful when implementing cancellable operations in code that does not allow you to pass down the cancellable object. This is typically called automatically by e.g. #GFile operations, so you rarely have to call this yourself.

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.

Resets @cancellable to its uncancelled state.

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.

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.

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 <emphasis>after</emphasis> a call to g_signal_handler_disconnect() for that handler has already returned. There is also a problem when cancellation happen 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 g_cancellable_disconnect() which protect against problems like this. An example of how to us this: |[ /* Make sure we don't do any unnecessary work if already cancelled */ if (g_cancellable_set_error_if_cancelled (cancellable)) 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

Gets the #GCharsetConverter:use-fallback property.

%TRUE if fallbacks are used by @converter

Sets the #GCharsetConverter:use-fallback property.

%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. 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 availible input has been consumed and all internal state has been produced then %G_CONVERTER_FLUSHED (or %G_CONVERTER_FINISHED if really at the end) is returned instead of %G_CONVERTER_CONVERTED. This is somewhat similar to what happens at the end of the input stream, but done in the middle of the data. This has different meanings for different conversions. For instance in a compression converter it would mean that we flush all the compression state into output such that if you uncompress the compressed data you get back all the input data. Doing this may make the final file larger due to padding though. Another example is a regexp conversion, where if you at the end of the flushed data have a match, but there is also a potential longer match. In the non-flushed case we would ask for more input, but when flushing we treat this as the end of input and do the match. Flushing is not always possible (like if a charset converter flushes at a partial multibyte sequence). Converters are supposed to try to produce as much output as possible and then return an error (typically %G_IO_ERROR_PARTIAL_INPUT).

a #GConverterResult, %G_CONVERTER_ERROR on error.

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 #GConverterResult, %G_CONVERTER_ERROR on error.

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 #GConvertFlags 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.

Flags used when calling a g_converter_convert(). Provides an interface for converting data from one type to another type. The conversion can be stateful and may fail at any place.

a #GConverterResult, %G_CONVERTER_ERROR on error.

Converter input stream implements #GInputStream and allows conversion of data of various types during reading. 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

Converter output stream implements #GOutputStream and allows conversion of data of various types during reading. 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

Results returned from g_converter_convert(). The #GCredentials type is a reference-counted wrapper for native credentials. This information is typically used for identifying, authenticating and authorizing other processes. Some operating systems supports looking up the credentials of the remote peer of a communication endpoint - see e.g. g_socket_get_credentials(). Some operating systems supports securely sending and receiving credentials over a Unix Domain Socket, see #GUnixCredentialsMessage, g_unix_connection_send_credentials() and g_unix_connection_receive_credentials() for details. On Linux, the native credential type is a <type>struct ucred</type> - see the <citerefentry><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry> man page for details. This corresponds to %G_CREDENTIALS_TYPE_LINUX_UCRED. On FreeBSD, the native credential type is a <type>struct cmsgcred</type>. This corresponds to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED. 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 It is a programming error (which will cause an warning to be logged) to use this method if there is no #GCredentials support for the OS or if @native_type isn't supported by the OS. operation there is no #GCredentials support for the OS or if data, it is owned by @credentials.

The pointer to native credentials or %NULL if the

The type of native credentials to get. 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.

Checks if @credentials and @other_credentials is the same user. This operation can fail if #GCredentials is not supported on the the OS. user, %FALSE otherwise or if @error is set.

%TRUE if @credentials and @other_credentials has the same

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.

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.

%TRUE if @uid was set, %FALSE if error is set.

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().

Class structure for #GCredentials. Enumeration describing different kinds of native credential types. Information about an annotation. If @info is statically allocated does nothing. Otherwise increases the reference count.

The same @info.

If @info is statically allocated, does nothing. Otherwise decreases the reference count of @info. When its reference count drops to 0, the memory used is freed.

Information about an argument for a method or a signal. If @info is statically allocated does nothing. Otherwise increases the reference count.

The same @info.

If @info is statically allocated, does nothing. Otherwise decreases the reference count of @info. When its reference count drops to 0, the memory used is freed.

The #GDBusAuthObserver type provides a mechanism for participating in how a #GDBusServer (or a #GDBusConnection) authenticates remote peers. Simply instantiate a #GDBusAuthObserver and connect to the signals you are interested in. Note that new signals may be added in the future For example, if you only want to allow D-Bus connections from processes owned by the same uid as the server, you would use a signal handler like the following: <example id="auth-observer"><title>Controlling Authentication</title><programlisting> static gboolean on_authorize_authenticated_peer (GDBusAuthObserver *observer, GIOStream *stream, GCredentials *credentials, gpointer user_data) { gboolean authorized; authorized = FALSE; if (credentials != NULL) { GCredentials *own_credentials; own_credentials = g_credentials_new (); if (g_credentials_is_same_user (credentials, own_credentials, NULL)) authorized = TRUE; g_object_unref (own_credentials); } return authorized; } </programlisting></example> Creates a new #GDBusAuthObserver object.

A #GDBusAuthObserver. Free with g_object_unref().

Emits the #GDBusAuthObserver::authorize-authenticated-peer signal on @observer.

%TRUE if the peer is authorized, %FALSE if not.

A #GIOStream for the #GDBusConnection. Credentials received from the peer or %NULL. 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. Capabilities negotiated 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 an D-Bus client, it is often easier to use the g_bus_own_name(), g_bus_watch_name() or g_dbus_proxy_new_for_bus() APIs. <example id="gdbus-server"><title>D-Bus server example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-server.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> <example id="gdbus-subtree-server"><title>D-Bus subtree example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-subtree.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> <example id="gdbus-unix-fd-client"><title>D-Bus UNIX File Descriptor example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-unix-fd-client.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> <example id="gdbus-export"><title>Exporting a GObject</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-export.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> 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. 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 @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 @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. 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 - see the #GDBusMessageFilterResult enumeration for details. Note that filters are run in a dedicated message handling thread so they can't block and, generally, can't do anything but signal a worker thread. Also note that filters are rarely needed - use API such as g_dbus_connection_send_message_with_reply(), g_dbus_connection_signal_subscribe() or g_dbus_connection_call() instead. If a filter consumes an incoming message the message is not dispatched anywhere else - not even the standard dispatch machinery (that API such as g_dbus_connection_signal_subscribe() and g_dbus_connection_send_message_with_reply() relies on) will see the message. Similary, if a filter consumes an outgoing message, the message will not be sent to the other peer. g_dbus_connection_remove_filter().

A filter identifier that can be used with

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 If @connection is closed then the operation will fail with %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will fail with %G_IO_ERROR_CANCELLED. If @parameters contains a value not compatible with the D-Bus protocol, the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. If @reply_type is non-%NULL then the reply will be checked for having this type and an error will be raised if it does not match. Said another way, if you give a @reply_type then any non-%NULL return value will be of this type. If the @parameters #GVariant is floating, it is consumed. This allows convenient 'inline' use of g_variant_new(), e.g.: |[ g_dbus_connection_call (connection, "org.freedesktop.StringThings", "/org/freedesktop/StringThings", "org.freedesktop.StringThings", "TwoStrings", g_variant_new ("(ss)", "Thing One", "Thing Two"), NULL, G_DBUS_CALL_FLAGS_NONE, -1, NULL, (GAsyncReadyCallback) two_strings_done, NULL); ]| This is an asynchronous method. When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from. You can then call g_dbus_connection_call_finish() to get the result of the operation. See g_dbus_connection_call_sync() for the synchronous version of this function.

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(). return values. Free with g_variant_unref().

%NULL if @error is set. Otherwise a #GVariant tuple with

A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call(). Synchronously invokes the @method_name method on the If @connection is closed then the operation will fail with %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will fail with %G_IO_ERROR_CANCELLED. If @parameters contains a value not compatible with the D-Bus protocol, the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. If @reply_type is non-%NULL then the reply will be checked for having this type and an error will be raised if it does not match. Said another way, if you give a @reply_type then any non-%NULL return value will be of this type. If the @parameters #GVariant is floating, it is consumed. This allows convenient 'inline' use of g_variant_new(), e.g.: |[ g_dbus_connection_call_sync (connection, "org.freedesktop.StringThings", "/org/freedesktop/StringThings", "org.freedesktop.StringThings", "TwoStrings", g_variant_new ("(ss)", "Thing One", "Thing Two"), NULL, G_DBUS_CALL_FLAGS_NONE, -1, NULL, &error); ]| The calling thread is blocked until a reply is received. See g_dbus_connection_call() for the asynchronous version of this method. return values. Free with g_variant_unref().

%NULL if @error is set. Otherwise a #GVariant tuple with

A unique or well-known bus name. 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. Closes @connection. Note that this never causes the process to exit (this might only happen if the other end of a shared message bus connection disconnects, see #GDBusConnection:exit-on-close). Once the connection is closed, operations such as sending a message will return with the error %G_IO_ERROR_CLOSED. Closing a connection will not automatically flush the connection so queued messages may be lost. Use g_dbus_connection_flush() if you need such guarantees. If @connection is already closed, this method fails with %G_IO_ERROR_CLOSED. When @connection has been closed, the #GDBusConnection::closed signal is emitted in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread that @connection was constructed in. This is an asynchronous method. When the operation is finished, linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from. You can then call g_dbus_connection_close_finish() to get the result of the operation. See g_dbus_connection_close_sync() for the synchronous version.

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 #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 #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.

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. Asynchronously flushes @connection, that is, writes all queued outgoing message to the transport and then flushes the transport (using g_output_stream_flush_async()). This is useful in programs that wants to emit a D-Bus signal and then exit immediately. Without flushing the connection, there is no guarantee that the message has been sent to the networking buffers in the OS kernel. This is an asynchronous method. When the operation is finished, linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from. You can then call g_dbus_connection_flush_finish() to get the result of the operation. See g_dbus_connection_flush_sync() for the synchronous version.

%TRUE if the operation succeeded, %FALSE if @error is set.

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 #GCancellable or %NULL. Gets the capabilities negotiated with the remote peer

Zero or more flags from the #GDBusCapabilityFlags enumeration.

Gets whether the process is terminated when @connection is closed by the remote peer. See #GDBusConnection:exit-on-close for more details. closed by the remote peer.

Whether the process is terminated when @connection is

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

Gets the credentials of the authenticated peer. This will always return %NULL unless @connection acted as a server (e.g. %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER was passed) when set up and the client passed credentials as part of the authentication process. In a message bus setup, the message bus is always the server and each application is a client. So this method will always return %NULL for message bus clients. this object, it is owned by @connection.

A #GCredentials or %NULL if not available. Do not free

Gets the underlying stream used for IO.

the stream used for IO

Gets the unique name of @connection as assigned by the message bus. This can also be used to figure out if @connection is a message bus connection. bus connection. Do not free this string, it is owned by

The unique name or %NULL if @connection is not a message

Gets whether @connection is closed.

%TRUE if the connection is closed, %FALSE otherwise.

Registers callbacks for exported objects at @object_path with the D-Bus interface that is described in @interface_info. Calls to functions in @vtable (and @user_data_free_func) will happen in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from. Note that all #GVariant values passed to functions in @vtable will match the signature given in @interface_info - if a remote caller passes incorrect values, the <literal>org.freedesktop.DBus.Error.InvalidArgs</literal> is returned to the remote caller. Additionally, if the remote caller attempts to invoke methods or access properties not mentioned in @interface_info the <literal>org.freedesktop.DBus.Error.UnknownMethod</literal> resp. <literal>org.freedesktop.DBus.Error.InvalidArgs</literal> errors are returned to the caller. It is considered a programming error if the #GDBusInterfaceGetPropertyFunc function in @vtable returns a #GVariant of incorrect type. If an existing callback is already registered at @object_path and GDBus automatically implements the standard D-Bus interfaces org.freedesktop.DBus.Properties, org.freedesktop.DBus.Introspectable and org.freedesktop.Peer, so you don't have to implement those for the objects you export. You <emphasis>can</emphasis> implement org.freedesktop.DBus.Properties yourself, e.g. to handle getting and setting of properties asynchronously. Note that the reference count on @interface_info will be incremented by 1 (unless allocated statically, e.g. if the reference count is -1, see g_dbus_interface_info_ref()) for as long as the object is exported. Also note that @vtable will be copied. See <xref linkend="gdbus-server"/> for an example of how to use this method. that can be used with g_dbus_connection_unregister_object() .

0 if @error is set, otherwise a registration id (never 0)

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. Registers a whole subtree of <quote>dynamic</quote> objects. The @enumerate and @introspection functions in @vtable are used to convey, to remote callers, what nodes exist in the subtree rooted by @object_path. When handling remote calls into any node in the subtree, first the or the #G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is set the @introspection function is used to check if the node supports the requested method. If so, the @dispatch function is used to determine where to dispatch the call. The collected #GDBusInterfaceVTable and #gpointer will be used to call into the interface vtable for processing the request. All calls into user-provided code will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from. If an existing subtree is already registered at @object_path or then @error is set to #G_IO_ERROR_EXISTS. Note that it is valid to register regular objects (using g_dbus_connection_register_object()) in a subtree registered with g_dbus_connection_register_subtree() - if so, the subtree handler is tried as the last resort. One way to think about a subtree handler is to consider it a <quote>fallback handler</quote> for object paths not registered via g_dbus_connection_register_object() or other bindings. Note that @vtable will be copied so you cannot change it after registration. See <xref linkend="gdbus-subtree-server"/> for an example of how to use this method. that can be used with g_dbus_connection_unregister_subtree() .

0 if @error is set, otherwise a subtree registration id (never 0)

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.

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 <xref linkend="gdbus-server"/> and <xref linkend="gdbus-unix-fd-client"/> for an example of how to use this low-level API to send and receive UNIX file descriptors. Note that @message must be unlocked, unless @flags contain the %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. transmission, %FALSE if @error is set.

%TRUE if the message was well-formed and queued for

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 <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from. You can then call g_dbus_connection_send_message_with_reply_finish() to get the result of the operation. See g_dbus_connection_send_message_with_reply_sync() for the synchronous version. Note that @message must be unlocked, unless @flags contain the %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. See <xref linkend="gdbus-server"/> and <xref linkend="gdbus-unix-fd-client"/> for an example of how to use this low-level API to send and receive UNIX file descriptors.

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 occured. That is to say that the returned #GDBusMessage object may be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use g_dbus_message_to_gerror() to transcode this to a #GError. See <xref linkend="gdbus-server"/> and <xref linkend="gdbus-unix-fd-client"/> for an example of how to use this low-level API to send and receive UNIX file descriptors.

A locked #GDBusMessage or %NULL if @error is set.

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 occured. That is to say that the returned #GDBusMessage object may be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use g_dbus_message_to_gerror() to transcode this to a #GError. See <xref linkend="gdbus-server"/> and <xref linkend="gdbus-unix-fd-client"/> for an example of how to use this low-level API to send and receive UNIX file descriptors. Note that @message must be unlocked, unless @flags contain the %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.

A locked #GDBusMessage that is the reply to @message or %NULL if @error is set.

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.

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 <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from. If @connection is not a message bus connection, @sender must be %NULL. If @sender is a well-known name note that @callback is invoked with the unique name for the owner of @sender, not the well-known name as one would expect. This is because the message bus rewrites the name. As such, to avoid certain race conditions, users should be tracking the name owner of the well-known name and use that when processing the received signal.

A subscription identifier that can be used with g_dbus_connection_signal_unsubscribe().

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. Flags describing how to subscribe to the signal (currently unused). 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 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.

Unregisters an object.

%TRUE if the object was unregistered, %FALSE otherwise.

A registration id obtained from g_dbus_connection_register_object(). Unregisters a subtree.

%TRUE if the subtree was unregistered, %FALSE otherwise.

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 <literal>raise(SIGTERM)</literal>) if the connection is closed by the remote peer. 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. 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 <itemizedlist> <listitem><para> If g_dbus_connection_close() is called. In this case </para></listitem> <listitem><para> If the remote peer closes the connection. In this case </para></listitem> <listitem><para> If the remote peer sends invalid or malformed data. In this case @remote_peer_vanished is set to %FALSE and @error is set. </para></listitem> </itemizedlist> Upon receiving this signal, you should give up your reference to 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. 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. 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. Error codes for the %G_DBUS_ERROR error domain. Struct used in g_dbus_error_register_error_domain(). The type of the @get_property function in #GDBusInterfaceVTable. consumed - otherwise its reference count is decreased by one.

A #GVariant with the value for @property_name or %NULL if

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(). Information about a D-Bus interface. Appends an XML representation of @info (and its children) to @string_builder. This function is typically used for generating introspection XML documents at run-time for handling the <literal>org.freedesktop.DBus.Introspectable.Introspect</literal> method.

Indentation level. A #GString to to append XML data to. Looks up information about a method. This cost of this function is O(n) in number of methods unless g_dbus_interface_info_cache_build() has been used on @info.

A #GDBusMethodInfo or %NULL if not found. Do not free, it is owned by @info.

A D-Bus method name (typically in CamelCase) Looks up information about a property. This cost of this function is O(n) in number of properties unless g_dbus_interface_info_cache_build() has been used on @info.

A #GDBusPropertyInfo or %NULL if not found. Do not free, it is owned by @info.

A D-Bus property name (typically in CamelCase). Looks up information about a signal. This cost of this function is O(n) in number of signals unless g_dbus_interface_info_cache_build() has been used on @info.

A #GDBusSignalInfo or %NULL if not found. Do not free, it is owned by @info.

A D-Bus signal name (typically in CamelCase) If @info is statically allocated does nothing. Otherwise increases the reference count.

The same @info.

If @info is statically allocated, does nothing. Otherwise decreases the reference count of @info. When its reference count drops to 0, the memory used is freed.

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 can 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(). Virtual table for handling properties and method calls for a D-Bus interface. If you want to handle getting/setting D-Bus properties asynchronously, simply register an object with the <literal>org.freedesktop.DBus.Properties</literal> D-Bus interface using g_dbus_connection_register_object(). 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(). g_object_unref().

A new #GDBusMessage or %NULL if @error is set. Free with

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. determine the size).

Number of bytes needed or -1 if @error is set (e.g. if

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. g_object_unref().

A new #GDBusMessage or %NULL if @error is set. Free with

Convenience to get the first item in the body of @message.

The string item or %NULL if the first item in the body of

Gets the body of a message.

A #GVariant or %NULL if the body is empty. Do not free, it is owned by @message.

Gets the byte order of @message.

The byte order.

Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.

The value.

Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.

The value.

Gets the flags for @message.

Flags that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together).

Gets a header field on @message. otherwise. Do not free, it is owned by @message.

A #GVariant with the value if the header was found, %NULL

A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration) Gets an array of all header fields on @message that are set. %G_DBUS_MESSAGE_HEADER_FIELD_INVALID. Each element is a #guchar. Free with g_free().

An array of header fields terminated by

Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.

The value.

Checks whether @message is locked. To monitor changes to this value, conncet to the #GObject::notify signal to listen for changes on the #GDBusMessage:locked property.

%TRUE if @message is locked, %FALSE otherwise.

Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.

The value.

Gets the type of @message.

A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration).

Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.

The value.

Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.

The value.

Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.

The value.

Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.

The value.

Gets the serial for @message.

A #guint32.

Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.

The value.

Gets the UNIX file descriptors associated with @message, if any. This method is only available on UNIX. associated. Do not free, this object is owned by @message.

A #GUnixFDList or %NULL if no file descriptors are

If @message is locked, does nothing. Otherwise locks the message.

Creates a new #GDBusMessage that is an error reply to @method_call_message.

A #GDBusMessage. Free with g_object_unref().

A valid D-Bus error name. The D-Bus error message in a printf() format. Creates a new #GDBusMessage that is an error reply to @method_call_message.

A #GDBusMessage. Free with g_object_unref().

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 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().

Produces a human-readable multi-line description of @message. The contents of the description has no ABI guarantees, the contents and formatting is subject to change at any time. Typical output looks something like this: <programlisting> Headers: path -> objectpath '/org/gtk/GDBus/TestObject' interface -> 'org.gtk.GDBus.TestInterface' member -> 'GimmeStdout' destination -> ':1.146' UNIX File Descriptors: (none) </programlisting> or <programlisting> Headers: reply-serial -> uint32 4 destination -> ':1.159' sender -> ':1.146' num-unix-fds -> uint32 1 UNIX File Descriptors: </programlisting>

A string that should be freed with g_free().

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.

Either %NULL or a #GVariant that is a tuple. Sets the byte order of @message.

The byte order. Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.

The value to set. Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.

The value to set. Sets the flags to set on @message.

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 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.

The value to set. Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.

The value to set. Sets @message to be of @type.

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.

The value to set. Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.

The value to set. Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.

The value to set. Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.

The value to set. Sets the serial for @message.

A #guint32. Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.

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 This method is only available on UNIX.

A #GUnixFDList or %NULL. Serializes @message to a blob. The byte order returned by g_dbus_message_get_byte_order() will be used. generated by @message or %NULL if @error is set. Free with g_free().

A pointer to a valid binary D-Bus message of @out_size bytes

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.

Enumeration used to describe the byte order of a D-Bus message. 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 <emphasis>standard error</emphasis>. Applications can check this ahead of time using g_dbus_message_to_blob() passing a #GDBusCapabilityFlags value obtained from @connection. g_object_unref() or %NULL to drop the message. Passive filter functions can simply return the passed @message object.

A #GDBusMessage that will be freed with

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. Header fields used in #GDBusMessage. Message types used in #GDBusMessage. Information about a method on an D-Bus interface. If @info is statically allocated does nothing. Otherwise increases the reference count.

The same @info.

If @info is statically allocated, does nothing. Otherwise decreases the reference count of @info. When its reference count drops to 0, the memory used is freed.

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.

Gets the name of the D-Bus interface the method was invoked on.

A string. Do not free, it is owned by @invocation.

Gets the #GDBusMessage for the method invocation. This is useful if you need to use low-level protocol features, such as UNIX file descriptor passing, that cannot be properly expressed in the #GVariant API. See <xref linkend="gdbus-server"/> and <xref linkend="gdbus-unix-fd-client"/> for an example of how to use this low-level API to send and receive UNIX file descriptors.

#GDBusMessage. Do not free, it is owned by @invocation.

Gets information about the method call, if any.

A #GDBusMethodInfo or %NULL. Do not free, it is owned by @invocation.

Gets the name of the method that was invoked.

A string. Do not free, it is owned by @invocation.

Gets the object path the method was invoked on.

A string. Do not free, it is owned by @invocation.

Gets the parameters of the method invocation.

A #GVariant. Do not free, it is owned by @invocation.

Gets the bus name that invoked the method.

A string. Do not free, it is owned by @invocation.

Gets the @user_data #gpointer passed to g_dbus_connection_register_object().

A #gpointer.

Finishes handling a D-Bus method call by returning an error. This method will free @invocation, you cannot use it afterwards.

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 <literal>org.gtk.GDBus.UnmappedGError.Quark...</literal> is used. This provides transparent mapping of #GError between applications using GDBus. If you are writing an application intended to be portable, <emphasis>always</emphasis> register errors with g_dbus_error_register_error() or use g_dbus_method_invocation_return_dbus_error(). This method will free @invocation, you cannot use it afterwards.

A #GQuark for the #GError error domain. The error code. printf()-style format. Like g_dbus_method_invocation_return_error() but without printf()-style formatting. This method will free @invocation, you cannot use it afterwards.

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 free @invocation, you cannot use it afterwards.

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 free @invocation, you cannot use it afterwards.

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. This method will free @invocation, you cannot use it afterwards.

A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters. Information about nodes in a remote object hierarchy. Parses @xml_data and returns a #GDBusNodeInfo representing the data. with g_dbus_node_info_unref().

A #GDBusNodeInfo structure or %NULL if @error is set. Free

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 <literal>org.freedesktop.DBus.Introspectable.Introspect</literal> method.

Indentation level. A #GString to to append XML data to. Looks up information about an interface. This 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 D-Bus interface name. If @info is statically allocated does nothing. Otherwise increases the reference count.

The same @info.

If @info is statically allocated, does nothing. Otherwise decreases the reference count of @info. When its reference count drops to 0, the memory used is freed.

Information about a D-Bus property on a D-Bus interface. If @info is statically allocated does nothing. Otherwise increases the reference count.

The same @info.

If @info is statically allocated, does nothing. Otherwise decreases the reference count of @info. When its reference count drops to 0, the memory used is freed.

Flags describing the access control of a D-Bus property. #GDBusProxy is a base class used for proxies to access a D-Bus interface on a remote object. A #GDBusProxy can be constructed for both well-known and unique names. By default, #GDBusProxy will cache all properties (and listen to changes) of the remote object, and proxy all signals that gets emitted. This behaviour can be changed by passing suitable #GDBusProxyFlags when the proxy is created. If the proxy is for a well-known name, the property cache is flushed when the name owner vanishes and reloaded when a name owner appears. If a #GDBusProxy is used for a well-known name, the owner of the name is tracked and can be read from #GDBusProxy:g-name-owner. Connect to the #GObject::notify signal to get notified of changes. Additionally, only signals and property changes emitted from the current name owner are considered and calls are always sent to the current name owner. This avoids a number of race conditions when the name is lost by one owner and claimed by another. However, if no name owner currently exists, then calls will be sent to the well-known name which may result in the message bus launching an owner (unless %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set). The generic #GDBusProxy::g-properties-changed and #GDBusProxy::g-signal signals are not very convenient to work with. Therefore, the recommended way of working with proxies is to subclass #GDBusProxy, and have more natural properties and signals in your derived class. See <xref linkend="gdbus-example-proxy-subclass"/> for an example. <example id="gdbus-wellknown-proxy"><title>GDBusProxy for a well-known-name</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-watch-proxy.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> 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. See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used.

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 flag isn'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. See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used.

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 flag isn'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. See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used.

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 %G_IO_ERROR_CANCELLED. If @parameters contains a value not compatible with the D-Bus protocol, the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. If the @parameters #GVariant is floating, it is consumed. This allows convenient 'inline' use of g_variant_new(), e.g.: |[ g_dbus_proxy_call (proxy, "TwoStrings", g_variant_new ("(ss)", "Thing One", "Thing Two"), G_DBUS_CALL_FLAGS_NONE, -1, NULL, (GAsyncReadyCallback) two_strings_done, &data); ]| This is an asynchronous method. When the operation is finished, <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from. 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.

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(). return values. Free with g_variant_unref().

%NULL if @error is set. Otherwise a #GVariant tuple with

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 %G_IO_ERROR_CANCELLED. If @parameters contains a value not compatible with the D-Bus protocol, the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. If the @parameters #GVariant is floating, it is consumed. This allows convenient 'inline' use of g_variant_new(), e.g.: |[ g_dbus_proxy_call_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. return values. Free with g_variant_unref().

%NULL if @error is set. Otherwise a #GVariant tuple with

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. 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), then @property_name (for existence) is checked against it. for @property_name or %NULL if the value is not in the cache. The returned reference must be freed with g_variant_unref().

A reference to the #GVariant instance that holds the value

Property name. Gets the names of all cached properties on @proxy. no cached properties. Free the returned array with g_strfreev().

A %NULL-terminated array of strings or %NULL if @proxy has

Gets the connection @proxy is for.

A #GDBusConnection owned by @proxy. Do not free.

Gets the timeout to use if -1 (specifying default timeout) is passed as @timeout_msec in the g_dbus_proxy_call() and g_dbus_proxy_call_sync() functions. See the #GDBusProxy:g-default-timeout property for more details.

Timeout to use for @proxy.

Gets the flags that @proxy was constructed with.

Flags from the #GDBusProxyFlags enumeration.

Returns the #GDBusInterfaceInfo, if any, specifying the minimal interface that @proxy conforms to. See the #GDBusProxy:g-interface-info property for more details. object, it is owned by @proxy.

A #GDBusInterfaceInfo or %NULL. Do not unref the returned

Gets the D-Bus interface name @proxy is for.

A string owned by @proxy. Do not free.

Gets the name that @proxy was constructed for.

A string owned by @proxy. Do not free.

The unique name that owns the name that @proxy is for or %NULL if no-one currently owns that name. You may connect to the #GObject::notify signal to track changes to the #GDBusProxy:g-name-owner property.

The name owner or %NULL if no name owner exists. Free with g_free().

Gets the object path @proxy is for.

A string owned by @proxy. Do not free.

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), then @property_name (for existence) and @value (for the type) is checked against it. If the @value #GVariant is floating, it is consumed. This allows convenient 'inline' use of g_variant_new(), e.g. |[ g_dbus_proxy_set_cached_property (proxy, "SomeProperty", g_variant_new ("(si)", "A String", 42)); ]| Normally you will not need to use this method since @proxy is tracking changes using the <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal> 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 <literal>ChatroomParticipants</literal> 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 <literal>ChatroomParticipantJoined(String name)</literal> and <literal>ChatroomParticipantParted(String name)</literal>.

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.

Timeout in milliseconds. Ensure that interactions with @proxy conform to the given interface. For example, when completing a method call, if the type signature of the message isn't what's expected, the given #GError is set. Signals that have a type signature mismatch are simply dropped. See the #GDBusProxy:g-interface-info property for more details.

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. For example, when completing a method call, if the type signature of the message isn't what's expected, the given #GError is set. Signals that have a type signature mismatch are simply dropped. 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: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). This signal corresponds to the <literal>PropertiesChanged</literal> D-Bus signal on the <literal>org.freedesktop.DBus.Properties</literal> 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. Flags used when sending #GDBusMessages on a #GDBusConnection. #GDBusServer is a helper for listening to and accepting D-Bus connections. <example id="gdbus-peer-to-peer"><title>D-Bus peer-to-peer example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-peer.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> Creates a new D-Bus server that listens on the first address in 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(). See <xref linkend="gdbus-peer-to-peer"/> for how #GDBusServer can be used. This is a synchronous failable constructor. See g_dbus_server_new() for the asynchronous version. g_object_unref().

A #GDBusServer or %NULL if @error is set. Free with

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 string that can be used by clients to connect to @server. by @server.

A D-Bus address string. Do not free, the string is owned

Gets the flags for @server.

A set of flags from the #GDBusServerFlags enumeration.

Gets the GUID for @server.

A D-Bus GUID. Do not free this string, it is owned by @server.

Gets whether @server is active.

%TRUE if server is active, %FALSE otherwise.

Starts @server.

Stops @server.

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 call g_dbus_connection_close() and give up your reference. Note that the other peer may disconnect at any time - a typical thing to do when accepting a connection is to listen to the #GDBusConnection::closed signal. If #GDBusServer:flags contains %G_DBUS_SERVER_FLAGS_RUN_IN_THREAD then the signal is emitted in a new thread dedicated to the connection. Otherwise the signal is emitted in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread that @server was constructed in. You are guaranteed that signal handlers for this signal runs before incoming messages on @connection are processed. This means that it's suitable to call g_dbus_connection_register_object() or similar from the signal handler. run.

%TRUE to claim @connection, %FALSE to let other handlers

A #GDBusConnection for the new connection. Flags used when creating a #GDBusServer. 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(). Information about a signal on a D-Bus interface. If @info is statically allocated does nothing. Otherwise increases the reference count.

The same @info.

If @info is statically allocated, does nothing. Otherwise decreases the reference count of @info. When its reference count drops to 0, the memory used is freed.

The type of the @dispatch function in #GDBusSubtreeVTable. Subtrees are flat. @node, if non-%NULL, is always exactly one

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 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(). The type of the @introspect function in #GDBusSubtreeVTable. Subtrees are flat. @node, if non-%NULL, is always exactly one This function should return %NULL to indicate that there is no object at this node. If this function returns non-%NULL, the return value is expected to be a %NULL-terminated array of pointers to #GDBusInterfaceInfo structures describing the interfaces implemented by @node. This array will have g_dbus_interface_info_unref() called on each item before being freed with g_free(). The difference between returning %NULL and an array containing zero items is that the standard DBus interfaces will returned to the remote introspector in the empty array case, but not in the %NULL case.

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(). 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.

Gets the current newline type for the @stream.

#GDataStreamNewlineType for the given @stream.

Reads an unsigned 8-bit/1-byte value from @stream. if an error occurred.

an unsigned 8-bit/1-byte value read from the @stream or %0

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(). an error occurred.

a signed 16-bit/2-byte value read from @stream or %0 if

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. an error occurred.

a signed 32-bit/4-byte value read from the @stream or %0 if

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. an error occurred.

a signed 64-bit/8-byte value read from @stream or %0 if

optional #GCancellable object, %NULL to ignore. Reads a line from the data input stream. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. (without the newlines). Set @length to a #gsize to get the length of the read line. On an error, it will return %NULL and still return %NULL, but @error won't be set.

a string with the line that was read in

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.

the <link linkend="io-priority">I/O priority</link> 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(). (without the newlines). Set @length to a #gsize to get the length of the read line. On an error, it will return %NULL and still return %NULL, but @error won't be set.

a string with the line that was read in

the #GAsyncResult that was provided to the callback. a #gsize to get the length of the data read in. Reads an unsigned 16-bit/2-byte value from @stream. In order to get the correct byte order for this read operation, see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). an error occurred.

an unsigned 16-bit/2-byte value read from the @stream or %0 if

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 error occurred.

an unsigned 32-bit/4-byte value read from the @stream or %0 if

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 error occurred.

an unsigned 64-bit/8-byte read from @stream or %0 if

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. 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 string with the data that was read

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.

characters to terminate the read. the <link linkend="io-priority">I/O priority</link> 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(). 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 string with the data that was read

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 <emphasis>not</emphasis> consume the stop character. You have to use g_data_input_stream_read_byte() to get it before calling g_data_input_stream_read_upto() again. Note that @stop_chars may contain '\0' if @stop_chars_len is specified. before encountering any of the stop characters. Set @length to a #gsize to get the length of the string. This function will return %NULL on an error

a string with the data that was read

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 <emphasis>not</emphasis> consume the stop character. You have to use g_data_input_stream_read_byte() to get it before calling g_data_input_stream_read_upto() again. Note that @stop_chars may contain '\0' if @stop_chars_len is specified. When the operation is finished, @callback will be called. You can then call g_data_input_stream_read_upto_finish() to get the result of the operation.

characters to terminate the read length of @stop_chars. May be -1 if @stop_chars is nul-terminated the <link linkend="io-priority">I/O priority</link> 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 <emphasis>not</emphasis> consume the stop character. You have to use g_data_input_stream_read_byte() to get it before calling g_data_input_stream_read_upto_async() again. before encountering any of the stop characters. Set @length to a #gsize to get the length of the string. This function will return %NULL on an error.

a string with the data that was read

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 #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 availible.

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.

Puts a byte into the output stream.

%TRUE if @data was successfully added to the @stream.

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 #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 #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 #gint64. optional #GCancellable object, %NULL to ignore. Puts a string into the output stream.

%TRUE if @string was successfully added to the @stream.

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 #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 #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 #guint64. optional #GCancellable object, %NULL to ignore. Sets the byte order of the data output stream to @order.

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. #GDataStreamNewlineType is used when checking for or setting the line endings for a given file. #GDesktopAppInfo is an implementation of #GAppInfo based on desktop files. Note that <filename><gio/gdesktopappinfo.h></filename> belongs to the UNIX-specific GIO interfaces, thus you have to use the <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. 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 <filename>applications</filename> subdirectories of the XDG data directories (i.e. the directories specified in the <envar>XDG_DATA_HOME</envar> and <envar>XDG_DATA_DIRS</envar> environment variables). GIO also supports the prefix-to-subdirectory mapping that is described in the <ulink url="http://standards.freedesktop.org/menu-spec/latest/">Menu Spec</ulink> (i.e. a desktop id of kde-foo.desktop will match <filename>/usr/share/applications/kde/foo.desktop</filename>).

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 Sets the name of the desktop that the application is running in. This is used by g_app_info_should_show() to evaluate the <literal>OnlyShowIn</literal> and <literal>NotShowIn</literal> desktop entry fields. The <ulink url="http://standards.freedesktop.org/menu-spec/latest/">Desktop Menu specification</ulink> recognizes the following: <simplelist> <member>GNOME</member> <member>KDE</member> <member>ROX</member> <member>XFCE</member> <member>Old</member> </simplelist> Should be called only once; subsequent calls are ignored.

a string specifying what desktop this is 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 desktop file is hidden if the Hidden key in it is set to True.

%TRUE if hidden, %FALSE otherwise.

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(). In contrast to g_app_info_launch_uris(), all processes created will always be run directly as children as if by the UNIX fork()/exec() calls. This guarantee allows additional control over the exact environment of the child processes, which is provided via a setup function semantics of the @setup function.

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

Interface that is used by backends to associate default handlers with URI schemes.

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().

#GAppInfo for given @uri_scheme or %NULL on error.

a string containing a URI scheme.

#GAppInfo for given @uri_scheme or %NULL on error.

a string containing a URI scheme.

#GAppInfo for given @uri_scheme or %NULL on error.

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, determing whether media change is automatically detected and ejecting the media. If the #GDrive reports that media isn't automatically detected, one can poll for media; typically one should not do this periodically as a poll for media operation is potententially expensive and may spin up the drive creating noise. #GDrive supports starting and stopping drives with authentication support for the former. This can be used to support a diverse set of use cases including connecting/disconnecting iSCSI devices, powering down external disk enclosures and starting/stopping multi-disk devices such as RAID devices. Note that the actual semantics and side-effects of starting/stopping a #GDrive may vary according to implementation. To choose the correct verbs in e.g. a file manager, use g_drive_get_start_stop_type(). For porting from GnomeVFS note that there is no equivalent of #GDrive in that API.

Checks if a drive can be ejected.

%TRUE if the @drive can be ejected, %FALSE otherwise.

Checks if a drive can be polled for media changes. %FALSE otherwise.

%TRUE if the @drive can be polled for media changes,

Checks if a drive can be started.

%TRUE if the @drive can be started, %FALSE otherwise.

Checks if a drive can be started degraded.

%TRUE if the @drive can be started degraded, %FALSE otherwise.

Checks if a drive can be stopped.

%TRUE if the @drive can be stopped, %FALSE otherwise.

Asynchronously ejects a drive. When the operation is finished, @callback will be called. You can then call g_drive_eject_finish() to obtain the result of the operation.

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. %FALSE otherwise.

%TRUE if the drive has been ejected successfully,

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.

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,

%TRUE if the drive was successfully ejected. %FALSE otherwise.

a #GAsyncResult.

Gets the kinds of identifiers that @drive has. Use g_drive_get_identifer() to obtain the identifiers themselves. array of strings containing kinds of identifiers. Use g_strfreev() to free.

a %NULL-terminated

Gets the icon for @drive. Free the returned object with g_object_unref().

#GIcon for the @drive.

Gets the identifier of the given kind for @drive. requested identfier, or %NULL if the #GDrive doesn't have this kind of identifier.

a newly allocated string containing the

the kind of identifier to return

Gets the name of @drive. string should be freed when no longer needed.

a string containing @drive's name. The returned

Gets a hint about how a drive can be started/stopped.

A value from the #GDriveStartStopType enumeration.

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.

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.

Check if @drive has any mountable volumes.

%TRUE if the @drive contains volumes, %FALSE otherwise.

Checks if @drive is capabable of automatically detecting media changes. media changes, %FALSE otherwise.

%TRUE if the @drive is capabable of automatically detecting

Checks if the @drive supports removable media.

%TRUE if @drive supports removable media, %FALSE otherwise.

Asynchronously polls @drive to see if media has been inserted or removed. When the operation is finished, @callback will be called. You can then call g_drive_poll_for_media_finish() to obtain the result of the operation.

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. %FALSE otherwise.

%TRUE if the drive has been poll_for_mediaed successfully,

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.

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. %FALSE otherwise.

%TRUE if the drive has been started successfully,

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.

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. %FALSE otherwise.

%TRUE if the drive has been stopped successfully,

a #GAsyncResult.

Checks if a drive can be ejected.

%TRUE if the @drive can be ejected, %FALSE otherwise.

Checks if a drive can be polled for media changes. %FALSE otherwise.

%TRUE if the @drive can be polled for media changes,

Checks if a drive can be started.

%TRUE if the @drive can be started, %FALSE otherwise.

Checks if a drive can be started degraded.

%TRUE if the @drive can be started degraded, %FALSE otherwise.

Checks if a drive can be stopped.

%TRUE if the @drive can be stopped, %FALSE otherwise.

Asynchronously ejects a drive. When the operation is finished, @callback will be called. You can then call g_drive_eject_finish() to obtain the result of the operation.

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. %FALSE otherwise.

%TRUE if the drive has been ejected successfully,

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.

%TRUE if the drive was successfully ejected. %FALSE otherwise.

a #GAsyncResult. Gets the kinds of identifiers that @drive has. Use g_drive_get_identifer() to obtain the identifiers themselves. array of strings containing kinds of identifiers. Use g_strfreev() to free.

a %NULL-terminated

Gets the icon for @drive. Free the returned object with g_object_unref().

#GIcon for the @drive.

Gets the identifier of the given kind for @drive. requested identfier, or %NULL if the #GDrive doesn't have this kind of identifier.

a newly allocated string containing the

the kind of identifier to return Gets the name of @drive. string should be freed when no longer needed.

a string containing @drive's name. The returned

Gets a hint about how a drive can be started/stopped.

A value from the #GDriveStartStopType enumeration.

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.

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.

Check if @drive has any mountable volumes.

%TRUE if the @drive contains volumes, %FALSE otherwise.

Checks if @drive is capabable of automatically detecting media changes. media changes, %FALSE otherwise.

%TRUE if the @drive is capabable of automatically detecting

Checks if the @drive supports removable media.

%TRUE if @drive supports removable media, %FALSE otherwise.

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. %FALSE otherwise.

%TRUE if the drive has been poll_for_mediaed successfully,

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.

%TRUE if the drive has been started successfully,

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.

%TRUE if the drive has been stopped successfully,

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.

a string containing @drive's name. The returned

#GIcon for the @drive.

%TRUE if the @drive contains volumes, %FALSE otherwise.

#GList containing any #GVolume objects on the given @drive.

%TRUE if @drive supports removable media, %FALSE otherwise.

%TRUE if @drive has media, %FALSE otherwise.

%TRUE if the @drive is capabable of automatically detecting

%TRUE if the @drive can be ejected, %FALSE otherwise.

%TRUE if the @drive can be polled for media changes,

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,

a #GAsyncResult.

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,

a #GAsyncResult.

a newly allocated string containing the

the kind of identifier to return

a %NULL-terminated

A value from the #GDriveStartStopType enumeration.

%TRUE if the @drive can be started, %FALSE otherwise.

%TRUE if the @drive can be started degraded, %FALSE otherwise.

%TRUE if the drive has been started successfully,

a #GAsyncResult.

%TRUE if the @drive can be stopped, %FALSE otherwise.

%TRUE if the drive has been stopped successfully,

a #GAsyncResult.

%TRUE if the drive was successfully ejected. %FALSE otherwise.

a #GAsyncResult. Flags used when starting a drive. Enumeration describing how a drive can be started/stopped. #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. the emblem and should not be modified or freed.

a #GIcon. The returned object belongs to

Gets the origin of the emblem.

the origin of the emblem

GEmblemOrigin is used to add information about the origin of the emblem to #GEmblem. #GEmblemedIcon is an implementation of #GIcon that supports adding an emblem to an icon. Adding multiple emblems to an icon is ensured via g_emblemed_icon_add_emblem(). Note that #GEmblemedIcon allows no control over the position of the emblems. See also #GEmblem for more information. 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 #GEmblem s.

a #GEmblem Removes all the emblems from @icon.

Gets the list of emblems for the @icon. #GEmblem s that is owned by @emblemed

a #GList of

Gets the main icon for @emblemed.

a #GIcon that is owned by @emblemed

#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). g_file_new_for_path() if you have a path. g_file_new_for_uri() if you have a URI. g_file_new_for_commandline_arg() for a command line argument. g_file_parse_name() from a utf8 string gotten from g_file_get_parse_name(). One way to think of a #GFile is as an abstraction of a pathname. For normal files the system pathname is what is stored internally, but as #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 utf8 and can be used in a user interface. But always store the real basename or the #GFile to use to actually access the file, because there is no way to go from a display name to the actual name. Using #GFile as an identifier has the same weaknesses as using a path in that there may be multiple aliases for the same file. For instance, hard or soft links may cause two different #GFiles to refer to the same file. 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. Some #GFile operations do not have synchronous analogs, as they may take a very long time to finish, and blocking may leave an application unusable. Notable cases include: g_file_mount_mountable() to mount a mountable file. g_file_unmount_mountable_with_operation() to unmount a mountable file. g_file_eject_mountable_with_operation() to eject a mountable file. <para id="gfile-etag"><indexterm><primary>entity tag</primary></indexterm> One notable feature of #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 <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html">specification</ulink> for HTTP Etag headers, which are a very similar concept. </para> To construct a #gfile, you can use:

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. Free the returned object with g_object_unref().

a #GFileOutputStream, or %NULL on error.

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.

Finishes an asynchronous file append operation started with g_file_append_to_async(). Free the returned object with g_object_unref().

a valid #GFileOutputStream or %NULL on error.

#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 If @cancellable is not %NULL, then the operation can 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.

destination #GFile set of #GFileCopyFlags optional #GCancellable object, %NULL to ignore. function to callback with progress information 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(), however the callback will run in the main loop, not in the thread that is doing the I/O operation. When the operation is finished, @callback will be called. You can then call g_file_copy_finish() to get the result of the operation.

Finishes copying the file started with g_file_copy_async().

a %TRUE on success, %FALSE on error.

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. %NULL on error. Free the returned object with g_object_unref().

a #GFileOutputStream for the newly created file, or

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.

Finishes an asynchronous file create operation started with g_file_create_async(). Free the returned object with g_object_unref().

a #GFileOutputStream or %NULL on error.

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. Free the returned object with g_object_unref().

a #GFileIOStream for the newly created file, or %NULL on error.

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.

Finishes an asynchronous file create operation started with g_file_create_readwrite_async(). Free the returned object with g_object_unref().

a #GFileIOStream or %NULL on error.

a #GAsyncResult

Deletes a file. If the @file is a directory, it will only be deleted if it is empty. If @cancellable is not %NULL, then the operation can 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.

optional #GCancellable object, %NULL to ignore.

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.

Starts an asynchronous eject on a mountable. When this operation has completed, @callback will be called 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.

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(). otherwise.

%TRUE if the @file was ejected successfully. %FALSE

a #GAsyncResult.

Starts an asynchronous eject on a mountable. When this operation has completed, @callback will be called 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.

Finishes an asynchronous eject operation started by g_file_eject_mountable_with_operation(). otherwise.

%TRUE if the @file was ejected successfully. %FALSE

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_FILE_ERROR_NOTDIR error will be returned. Other errors are possible too. Free the returned object with g_object_unref().

A #GFileEnumerator if successful, %NULL on error.

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.

Finishes an async enumerate children operation. See g_file_enumerate_children_async(). Free the returned object with g_object_unref().

a #GFileEnumerator or %NULL if an error occurred.

a #GAsyncResult.

Checks equality of two given #GFiles. 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. %FALSE if either is not a #GFile.

%TRUE if @file1 and @file2 are equal.

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. Free the returned object with g_object_unref().

a #GMount where the @file is located or %NULL on error.

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.

Finishes an asynchronous find mount request. See g_file_find_enclosing_mount_async(). Free the returned object with g_object_unref().

#GMount for given @file or %NULL on error.

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. if given #GFile is invalid. The returned string should be freed with g_free() when no longer needed.

string containing the #GFile's base name, or %NULL

Gets the child of @file for a given @display_name (i.e. a UTF8 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. %NULL if the display name couldn't be converted. Free the returned object with g_object_unref().

a #GFile to the specified child, or

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. #GFile or %NULL if there is no parent. Free the returned object with g_object_unref().

a #GFile structure to the parent of the given

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 UTF8 the pathname is used, otherwise the IRI is used (a form of URI that allows UTF8 characters unescaped). This call does no blocking i/o. string should be freed with g_free() when no longer needed.

a string containing the #GFile's parse name. The returned

Gets the local pathname for #GFile, if one exists. This call does no blocking i/o. no such path exists. The returned string should be freed with g_free() when no longer needed.

string containing the #GFile's path, or %NULL if

Gets the path for @descendant relative to @parent. This call does no blocking i/o. 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.

string with the relative path from @descendant

input #GFile.

Gets the URI for the @file. This call does no blocking i/o. The returned string should be freed with g_free() when no longer needed.

a string containing the #GFile's URI.

Gets the URI scheme for a #GFile. RFC 3986 decodes the scheme as: <programlisting> URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] </programlisting> Common schemes include "file", "http", "ftp", etc. This call does no blocking i/o. #GFile. The returned string should be freed with g_free() when no longer needed.

a string containing the URI scheme for the given

Checks to see if a #GFile has a given URI scheme. This call does no blocking i/o. given URI scheme, %FALSE if URI scheme is %NULL, not supported, or #GFile is invalid.

%TRUE if #GFile's backend supports the

a string containing a URI scheme.

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.

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 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.

optional #GCancellable object, %NULL to ignore.

Creates a symbolic link named @file which contains the string If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.

%TRUE on the creation of a new symlink, %FALSE otherwise.

a string with the path for the target of the new symlink 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. Free the returned object with g_object_unref().

a #GFileMonitor for the given @file, or %NULL on error.

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. Free the returned object with g_object_unref().

a #GFileMonitor for the given @file, or %NULL on error.

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 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.

Finishes a mount operation started by g_file_mount_enclosing_volume(). has occurred, this function will return %FALSE and set @error appropriately if present.

%TRUE if successful. If an error

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.

Finishes a mount operation. See g_file_mount_mountable() for details. Finish an asynchronous mount operation that was started with g_file_mount_mountable(). Free the returned object with g_object_unref().

a #GFile or %NULL on error.

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 If @cancellable is not %NULL, then the operation can 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.

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. Free the returned object with g_object_unref().

#GFileIOStream or %NULL on error.

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.

Finishes an asynchronous file read operation started with g_file_open_readwrite_async(). Free the returned object with g_object_unref().

a #GFileIOStream or %NULL on error.

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.

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(). otherwise.

%TRUE if the operation finished successfully. %FALSE

a #GAsyncResult.

Checks whether @file has the prefix specified by @prefix. In other word, if the names of inital elements of @files 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. 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. %FALSE otherwise.

%TRUE if the @files's parent, grandparent, etc is @prefix.

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 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 "fs:*" means all attributes in the fs namespace. The standard namespace for filesystem attributes is "fs". 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. Free the returned object with g_object_unref().

a #GFileInfo or %NULL if there was an error.

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.

Finishes an asynchronous filesystem info query. See g_file_query_filesystem_info_async(). Free the returned object with g_object_unref().

#GFileInfo for given @file or %NULL on error.

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. Free the returned object with g_object_unref().

a #GFileInfo for the given @file, or %NULL on error.

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.

Finishes an asynchronous file info query. See g_file_query_info_async(). Free the returned object with g_object_unref().

#GFileInfo for given @file or %NULL on error.

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. When you are done with it, release it with g_file_attribute_info_list_unref()

a #GFileAttributeInfoList describing the settable attributes.

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. When you are done with it, release it with g_file_attribute_info_list_unref()

a #GFileAttributeInfoList describing the writable namespaces.

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.

Finishes an asynchronous file read operation started with g_file_read_async(). Free the returned object with g_object_unref().

a #GFileInputStream or %NULL on error.

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. Free the returned object with g_object_unref().

#GFileInputStream or %NULL on error.

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, 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 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. Free the returned object with g_object_unref().

a #GFileOutputStream or %NULL on error.

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.

Finishes an asynchronous file replace operation started with g_file_replace_async(). Free the returned object with g_object_unref().

a #GFileOutputStream, or %NULL on error.

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. Free the returned object with g_object_unref().

a #GFileIOStream or %NULL on error.

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.

Finishes an asynchronous file replace operation started with g_file_replace_readwrite_async(). Free the returned object with g_object_unref().

a #GFileIOStream, or %NULL on error.

a #GAsyncResult.

Resolves a relative path for @file to an absolute path. This call does no blocking i/o. is %NULL or if @file is invalid. Free the returned object with g_object_unref().

#GFile to the resolved path. %NULL if @relative_path

a given relative path string.

Sets an attribute in the file with attribute name @attribute to @value. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.

%TRUE if the attribute was set, %FALSE otherwise.

Asynchronously sets the attributes of @file with @info. For more details, see g_file_set_attributes_from_info() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_set_attributes_finish() to get the result of the operation.

a #GFileInfo. a #GFileQueryInfoFlags. the <link linkend="io-priority">I/O priority</link> 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.

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.

%TRUE if there was any error, %FALSE otherwise.

a #GFileInfo. #GFileQueryInfoFlags optional #GCancellable object, %NULL to ignore.

Renames @file to the specified display name. The display name is converted from UTF8 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. if there was an error. Free the returned object with g_object_unref().

a #GFile specifying what @file was renamed to, or %NULL

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.

Finishes setting a display name started with g_file_set_display_name_async(). Free the returned object with g_object_unref().

a #GFile or %NULL on error.

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.

Finishes a start operation. See g_file_start_mountable() for details. Finish an asynchronous start operation that was started with g_file_start_mountable(). otherwise.

%TRUE if the operation finished successfully. %FALSE

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.

Finishes an stop operation, see g_file_stop_mountable() for details. Finish an asynchronous stop operation that was started with g_file_stop_mountable(). otherwise.

%TRUE if the operation finished successfully. %FALSE

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.

optional #GCancellable object, %NULL to ignore.

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.

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(). otherwise.

%TRUE if the operation finished successfully. %FALSE

a #GAsyncResult.

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(). otherwise.

%TRUE if the operation finished successfully. %FALSE

a #GAsyncResult.

a #GFileOutputStream, or %NULL on error.

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.

a set of #GFileCreateFlags. the <link linkend="io-priority">I/O priority</link> 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(). Free the returned object with g_object_unref().

a valid #GFileOutputStream or %NULL on error.

#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 If @cancellable is not %NULL, then the operation can 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.

destination #GFile set of #GFileCopyFlags optional #GCancellable object, %NULL to ignore. function to callback with progress information 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(), however the callback will run in the main loop, not in the thread that is doing the I/O operation. When the operation is finished, @callback will be called. You can then call g_file_copy_finish() to get the result of the operation.

destination #GFile set of #GFileCopyFlags the <link linkend="io-priority">I/O priority</link> of the request. optional #GCancellable object, %NULL to ignore. function to callback with progress information 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 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.

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. %NULL on error. Free the returned object with g_object_unref().

a #GFileOutputStream for the newly created file, or

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.

a set of #GFileCreateFlags. the <link linkend="io-priority">I/O priority</link> 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(). Free the returned object with g_object_unref().

a #GFileOutputStream or %NULL on error.

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. Free the returned object with g_object_unref().

a #GFileIOStream for the newly created file, or %NULL on error.

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.

a set of #GFileCreateFlags the <link linkend="io-priority">I/O priority</link> 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(). Free the returned object with g_object_unref().

a #GFileIOStream or %NULL on error.

a #GAsyncResult Deletes a file. If the @file is a directory, it will only be deleted if it is empty. If @cancellable is not %NULL, then the operation can 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.

optional #GCancellable object, %NULL to ignore. 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.

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(). otherwise.

%TRUE if the @file was ejected successfully. %FALSE

a #GAsyncResult. Starts an asynchronous eject on a mountable. When this operation has completed, @callback will be called 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.

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(). otherwise.

%TRUE if the @file was ejected successfully. %FALSE

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_FILE_ERROR_NOTDIR error will be returned. Other errors are possible too. Free the returned object with g_object_unref().

A #GFileEnumerator if successful, %NULL on error.

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.

an attribute query string. a set of #GFileQueryInfoFlags. the <link linkend="io-priority">I/O priority</link> 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(). Free the returned object with g_object_unref().

a #GFileEnumerator or %NULL if an error occurred.

a #GAsyncResult. Checks equality of two given #GFiles. 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. %FALSE if either is not a #GFile.

%TRUE if @file1 and @file2 are equal.

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. Free the returned object with g_object_unref().

a #GMount where the @file is located or %NULL on error.

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.

the <link linkend="io-priority">I/O priority</link> 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(). Free the returned object with g_object_unref().

#GMount for given @file or %NULL on error.

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. if given #GFile is invalid. The returned string should be freed with g_free() when no longer needed.

string containing the #GFile's base name, or %NULL

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. Free the returned object with g_object_unref().

a #GFile to a child specified by @name.

string containing the child's basename. Gets the child of @file for a given @display_name (i.e. a UTF8 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. %NULL if the display name couldn't be converted. Free the returned object with g_object_unref().

a #GFile to the specified child, or

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. #GFile or %NULL if there is no parent. Free the returned object with g_object_unref().

a #GFile structure to the parent of the given

a string containing the #GFile's parse name. The returned

Gets the local pathname for #GFile, if one exists. This call does no blocking i/o. no such path exists. The returned string should be freed with g_free() when no longer needed.

string containing the #GFile's path, or %NULL if

string with the relative path from @descendant

input #GFile. Gets the URI for the @file. This call does no blocking i/o. The returned string should be freed with g_free() when no longer needed.

a string containing the #GFile's URI.

a string containing the URI scheme for the given

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 a child of @parent. case that @parent is %NULL).

%TRUE if @file is a child of @parent (or any parent in the

the parent to check for, or %NULL Checks whether @file has the prefix specified by @prefix. In other word, if the names of inital elements of @files 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. 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. %FALSE otherwise.

%TRUE if the @files's parent, grandparent, etc is @prefix.

input #GFile. Checks to see if a #GFile has a given URI scheme. This call does no blocking i/o. given URI scheme, %FALSE if URI scheme is %NULL, not supported, or #GFile is invalid.

%TRUE if #GFile's backend supports the

a string containing a URI scheme. Creates a new icon for a file.

a #GIcon for the given @file, or %NULL on error.

%TRUE if file is native.

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. %FALSE if there were errors.

%TRUE if the @file's contents were successfully loaded.

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.

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. present, it will be set appropriately.

%TRUE if the load was successful. If %FALSE and @error is

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.

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. present, it will be set appropriately.

%TRUE if the load was successful. If %FALSE and @error is

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 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.

optional #GCancellable object, %NULL to ignore. 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. 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. otherwise.

%TRUE if all directories have been successfully created, %FALSE

optional #GCancellable object, %NULL to ignore. Creates a symbolic link named @file which contains the string If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.

%TRUE on the creation of a new symlink, %FALSE otherwise.

a string with the path for the target of the new symlink optional #GCancellable object, %NULL to ignore. 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. Free the returned object with g_object_unref().

a #GFileMonitor for the given @file, or %NULL on error.

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. Free the returned object with g_object_unref().

a #GFileMonitor for the given @file, or %NULL on error.

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. Free the returned object with g_object_unref().

a #GFileMonitor for the given @file, or %NULL on error.

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 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.

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(). has occurred, this function will return %FALSE and set @error appropriately if present.

%TRUE if successful. If an error

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.

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(). Free the returned object with g_object_unref().

a #GFile or %NULL on error.

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 If @cancellable is not %NULL, then the operation can 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 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. Free the returned object with g_object_unref().

#GFileIOStream or %NULL on error.

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.

a #GFileIOStream or %NULL on error.

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.

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(). otherwise.

%TRUE if the operation finished successfully. %FALSE

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. When you are done with it, release it with g_object_unref()

a #GAppInfo if the handle was found, %NULL if there were errors.

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 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 and 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).

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. does not exist

The #GFileType of the file and #G_FILE_TYPE_UNKNOWN if the file

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 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 "fs:*" means all attributes in the fs namespace. The standard namespace for filesystem attributes is "fs". 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. Free the returned object with g_object_unref().

a #GFileInfo or %NULL if there was an error.

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.

an attribute query string. the <link linkend="io-priority">I/O priority</link> 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(). Free the returned object with g_object_unref().

#GFileInfo for given @file or %NULL on error.

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. Free the returned object with g_object_unref().

a #GFileInfo for the given @file, or %NULL on error.

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.

an attribute query string. a set of #GFileQueryInfoFlags. the <link linkend="io-priority">I/O priority</link> 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(). Free the returned object with g_object_unref().

#GFileInfo for given @file or %NULL on error.

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. When you are done with it, release it with g_file_attribute_info_list_unref()

a #GFileAttributeInfoList describing the settable attributes.

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. When you are done with it, release it with g_file_attribute_info_list_unref()

a #GFileAttributeInfoList describing the writable namespaces.

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. Free the returned object with g_object_unref().

#GFileInputStream or %NULL on error.

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.

a #GFileInputStream or %NULL on error.

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, 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 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. Free the returned object with g_object_unref().

a #GFileOutputStream or %NULL on error.

an optional <link linkend="gfile-etag">entity tag</link> 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.

an <link linkend="gfile-etag">entity tag</link> for the current #GFile, or NULL to ignore. %TRUE if a backup should be created. a set of #GFileCreateFlags. the <link linkend="io-priority">I/O priority</link> 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. If @cancellable is not %NULL, then the operation can 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. has occurred, this function will return %FALSE and set @error appropriately if present.

%TRUE if successful. If an error

a string containing the new contents for @file. the length of @contents in bytes. the old <link linkend="gfile-etag">entity tag</link> for the document, or %NULL %TRUE if a backup should be created. a set of #GFileCreateFlags. a location to a new <link linkend="gfile-etag">entity tag</link> 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 current entity tag. When this operation has completed, @callback will be called 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.

string of contents to replace the file with. the length of @contents in bytes. a new <link linkend="gfile-etag">entity tag</link> 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.

a #GAsyncResult. a location of a new <link linkend="gfile-etag">entity tag</link> 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(). Free the returned object with g_object_unref().

a #GFileOutputStream, or %NULL on error.

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. Free the returned object with g_object_unref().

a #GFileIOStream or %NULL on error.

an optional <link linkend="gfile-etag">entity tag</link> 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.

a #GFileIOStream, or %NULL on error.

a #GAsyncResult. Resolves a relative path for @file to an absolute path. This call does no blocking i/o. is %NULL or if @file is invalid. Free the returned object with g_object_unref().

#GFile to the resolved path. %NULL if @relative_path

a given relative path string. Sets an attribute in the file with attribute name @attribute to @value. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.

%TRUE if the attribute was set, %FALSE otherwise.

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. in the @file, %FALSE otherwise.

%TRUE if the @attribute was successfully set to @value

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. in the @file, %FALSE otherwise.

%TRUE if the @attribute was successfully set to @value

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.

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.

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. in the @file, %FALSE otherwise.

%TRUE if the @attribute was successfully set to @value

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. in the @file, %FALSE otherwise.

%TRUE if the @attribute was successfully set to @value

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.

a #GFileInfo. a #GFileQueryInfoFlags. the <link linkend="io-priority">I/O priority</link> 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.

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.

%TRUE if there was any error, %FALSE otherwise.

a #GFileInfo. #GFileQueryInfoFlags optional #GCancellable object, %NULL to ignore. Renames @file to the specified display name. The display name is converted from UTF8 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. if there was an error. Free the returned object with g_object_unref().

a #GFile specifying what @file was renamed to, or %NULL

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.

a string. the <link linkend="io-priority">I/O priority</link> 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(). Free the returned object with g_object_unref().

a #GFile or %NULL on error.

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.

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(). otherwise.

%TRUE if the operation finished successfully. %FALSE

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.

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(). otherwise.

%TRUE if the operation finished successfully. %FALSE

a #GAsyncResult. Checks if @file supports <link linkend="g-main-context-push-thread-default-context">thread-default contexts</link>. 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.

%TRUE on successful trash, %FALSE otherwise.

optional #GCancellable object, %NULL to ignore. 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.

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(). otherwise.

%TRUE if the operation finished successfully. %FALSE

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.

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(). otherwise.

%TRUE if the operation finished successfully. %FALSE

a #GAsyncResult. Information about a specific attribute. Flags specifying the behaviour of an attribute. Acts as a lightweight registry for possible valid file attributes. The registry stores Key-Value pair formats as #GFileAttributeInfos. Creates a new file attribute info list.

a #GFileAttributeInfoList.

Adds a new attribute with @name to the @list, setting its @type and @flags.

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.

Gets the file attribute with the name @name from @list. attribute isn't found.

a #GFileAttributeInfo for the @name, or %NULL if an

the name of the attribute to lookup. References a file attribute info list.

#GFileAttributeInfoList or %NULL on error.

Removes a reference from the given @list. If the reference count falls to zero, the @list is deleted.

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 strings to use: <table> <title>File Attribute Matcher strings and results</title> <tgroup cols='2' align='left'><thead> <row><entry> Matcher String </entry><entry> Matches </entry></row></thead> <tbody> <row><entry>"*"</entry><entry>matches all attributes.</entry></row> <row><entry>"standard::is-hidden"</entry><entry>matches only the key is-hidden in the standard namespace.</entry></row> <row><entry>"standard::type,unix::*"</entry><entry>matches the type key in the standard namespace and all keys in the unix namespace.</entry></row> </tbody></tgroup> </table>

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.) in the given @ns, %FALSE otherwise.

%TRUE if the matcher matches all of the entries

a string containing a file attribute namespace. Gets the next matched attribute from a #GFileAttributeMatcher. no more attribute exist.

a string containing the next attribute or %NULL if

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 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 file attribute key. References a file attribute matcher.

a #GFileAttributeMatcher.

Unreferences @matcher. If the reference count falls below 1, the @matcher is automatically freed.

Used by g_file_set_attributes_from_info() when setting file attributes. The data types for file attributes. Flags used when copying or moving files. Flags used when an operation may create a file. #GFileDescriptorBased is implemented by streams (implementations of #GInputStream or #GOutputStream) that are based on file descriptors. Note that <filename><gio/gfiledescriptorbased.h></filename> belongs to the UNIX-specific GIO interfaces, thus you have to use the <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.

Gets the underlying file descriptor.

The file descriptor

Gets the underlying file descriptor.

The file descriptor

#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. 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().

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 #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. 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. Free the returned object with g_object_unref() when no longer needed.

A #GFileInfo or %NULL on error or end of enumerator.

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. 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.

Finishes the asynchronous operation started with g_file_enumerator_next_files_async(). g_list_free() and unref the infos with g_object_unref() when you're done with them.

a #GList of #GFileInfos. You must free the list with

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.

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().

the <link linkend="io-priority">I/O priority</link> 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 #GAsyncResult. Get the #GFile container which is being enumerated.

the #GFile which is being enumerated.

Checks if the file enumerator has pending operations.

%TRUE if the @enumerator has pending operations.

Checks if the file enumerator has been closed.

%TRUE if the @enumerator is closed.

A #GFileInfo or %NULL on error or end of enumerator.

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. 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.

the number of file info objects to request the <link linkend="gioscheduler">io priority</link> 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(). g_list_free() and unref the infos with g_object_unref() when you're done with them.

a #GList of #GFileInfos. You must free the list with

a #GAsyncResult. Sets the file enumerator as having pending operations.

a boolean value.

A #GFileInfo or %NULL on error or end of enumerator.

optional #GCancellable object, %NULL to ignore.

a #GList of #GFileInfos. You must free the list with

a #GAsyncResult.

%TRUE if the close operation has finished successfully.

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.

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 file attribute query string. optional #GCancellable object, %NULL to ignore.

Asynchronously queries the @stream for a #GFileInfo. When completed, 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 file attribute query string. the <link linkend="gio-GIOScheduler">I/O priority</link> 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 #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 #GFileInfo for the @stream, or %NULL on error.

a file attribute query string. optional #GCancellable object, %NULL to ignore. Asynchronously queries the @stream for a #GFileInfo. When completed, 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 #GFileInfo for the finished query.

a #GAsyncResult.

a #GFileInfo for the @stream, or %NULL on error.

a file attribute query string. optional #GCancellable object, %NULL to ignore.

A #GFileInfo for the finished query.

a #GAsyncResult.

the entity tag for the stream.

#GFileIcon specifies an icon by pointing to an image file to be used as icon. Gets the #GFile associated with the given @icon.

a #GFile, or %NULL.

The file containing the icon. An interface for writing VFS file handles.

a new #GFile that is a duplicate of the given #GFile.

%TRUE if @file1 and @file2 are equal.

the second #GFile.

%TRUE if file is native.

%TRUE if #GFile's backend supports the

a string containing a URI scheme.

a string containing the URI scheme for the given

string containing the #GFile's base name, or %NULL

string containing the #GFile's path, or %NULL if

a string containing the #GFile's URI.

a string containing the #GFile's parse name. The returned

a #GFile structure to the parent of the given

%TRUE if the @files's parent, grandparent, etc is @prefix.

input #GFile.

string with the relative path from @descendant

input