Functions ¶

Returns:

True if successful, else False with error set

action_name:: the action name
target_value:: the target value, or None for no target

Return type:

(bool, action_name: str, target_value: GLib.Variant or None)

Parses a detailed action name into its separate name and target components.

Detailed action names can have three formats.

The first format is used to represent an action name with no target value and consists of just an action name containing no whitespace nor the characters :, ( or ). For example: app.action.

The second format is used to represent an action with a target value that is a non-empty string consisting only of alphanumerics, plus - and .. In that case, the action name and target value are separated by a double colon (::). For example: app.action::target.

The third format is used to represent an action with any type of target value, including strings. The target value follows the action name, surrounded in parens. For example: app.action(42). The target value is parsed using GLib.Variant.parse(). If a tuple-typed value is desired, it must be specified in the same way, resulting in two sets of parens, for example: app.action((1,2,3)). A string target can be specified this way as well: app.action('target'). For strings, this third format must be used if target value is empty or contains characters other than alphanumerics, - and ..

If this function returns True, a non-None value is guaranteed to be returned in action_name (if a pointer is passed in). A None value may still be returned in target_value, as the detailed_name may not contain a target.

If returned, the GLib.Variant in target_value is guaranteed to not be floating.

New in version 2.38.

Gio.action_print_detailed_name(action_name, target_value)[source]¶

Parameters:

action_name (str) – a valid action name
target_value (GLib.Variant or None) – a GLib.Variant target value, or None

Returns:

a detailed format string

Return type:

str

Formats a detailed action name from action_name and target_value.

It is an error to call this function with an invalid action name.

This function is the opposite of Gio.Action.parse_detailed_name(). It will produce a string that can be parsed back to the action_name and target_value by that function.

See that function for the types of strings that will be printed by this function.

New in version 2.38.

Gio.app_info_create_from_commandline(commandline, application_name, flags)[source]¶

Parameters:

commandline (str) – the commandline to use
application_name (str or None) – the application name, or None to use commandline
flags (Gio.AppInfoCreateFlags) – flags that can specify details of the created Gio.AppInfo

Raises:

Returns:

new Gio.AppInfo for given command.

Return type:

Gio.AppInfo

Creates a new Gio.AppInfo from the given information.

Note that for commandline, the quoting rules of the Exec key of the freedesktop.org Desktop Entry Specification are applied. For example, if the commandline contains percent-encoded URIs, the percent-character must be doubled in order to prevent it from being swallowed by Exec key unquoting. See the specification for exact quoting rules.

Gio.app_info_get_all()[source]¶

Returns:: a newly allocated GLib.List of references to Gio.AppInfos.
Return type:: [Gio.AppInfo]

Gets a list of all of the applications currently registered on this system.

For desktop files, this includes applications that have NoDisplay=true set or are excluded from display by means of OnlyShowIn or NotShowIn. See Gio.AppInfo.should_show(). The returned list does not include applications which have the Hidden key set.

Gio.app_info_get_all_for_type(content_type)[source]¶

Parameters:: content_type (str) – the content type to find a Gio.AppInfo for
Returns:: GLib.List of Gio.AppInfos for given content_type or None on error.
Return type:: [Gio.AppInfo]

Gets a list of all Gio.AppInfos for a given content type, including the recommended and fallback Gio.AppInfos. See Gio.AppInfo.get_recommended_for_type() and Gio.AppInfo.get_fallback_for_type().

Gio.app_info_get_default_for_type(content_type, must_support_uris)[source]¶

Parameters:

content_type (str) – the content type to find a Gio.AppInfo for
must_support_uris (bool) – if True, the Gio.AppInfo is expected to support URIs

Returns:

Gio.AppInfo for given content_type or None on error.

Return type:

Gio.AppInfo or None

Gets the default Gio.AppInfo for a given content type.

Gio.app_info_get_default_for_type_async(content_type, must_support_uris, cancellable, callback, *user_data)[source]¶

Parameters:

content_type (str) – the content type to find a Gio.AppInfo for
must_support_uris (bool) – if True, the Gio.AppInfo is expected to support URIs
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the request is done
user_data (object or None) – data to pass to callback

Asynchronously gets the default Gio.AppInfo for a given content type.

New in version 2.74.

Gio.app_info_get_default_for_type_finish(result)[source]¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: Gio.AppInfo for given content_type or None on error.
Return type:: Gio.AppInfo

Finishes a default Gio.AppInfo lookup started by Gio.AppInfo.get_default_for_type_async().

If no Gio.AppInfo is found, then error will be set to Gio.IOErrorEnum.NOT_FOUND.

New in version 2.74.

Gio.app_info_get_default_for_uri_scheme(uri_scheme)[source]¶

Parameters:: uri_scheme (str) – a string containing a URI scheme.
Returns:: Gio.AppInfo for given uri_scheme or None on error.
Return type:: Gio.AppInfo or None

Gets the default application for handling URIs with the given URI scheme. A URI scheme is the initial part of the URI, up to but not including the ‘:’, e.g. “http”, “ftp” or “sip”.

Gio.app_info_get_default_for_uri_scheme_async(uri_scheme, cancellable, callback, *user_data)[source]¶

Parameters:

uri_scheme (str) – a string containing a URI scheme.
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the request is done
user_data (object or None) – data to pass to callback

Asynchronously gets the default application for handling URIs with the given URI scheme. A URI scheme is the initial part of the URI, up to but not including the ‘:’, e.g. “http”, “ftp” or “sip”.

New in version 2.74.

Gio.app_info_get_default_for_uri_scheme_finish(result)[source]¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: Gio.AppInfo for given uri_scheme or None on error.
Return type:: Gio.AppInfo

Finishes a default Gio.AppInfo lookup started by Gio.AppInfo.get_default_for_uri_scheme_async().

If no Gio.AppInfo is found, then error will be set to Gio.IOErrorEnum.NOT_FOUND.

New in version 2.74.

Gio.app_info_get_fallback_for_type(content_type)[source]¶

Parameters:: content_type (str) – the content type to find a Gio.AppInfo for
Returns:: GLib.List of Gio.AppInfos for given content_type or None on error.
Return type:: [Gio.AppInfo]

Gets a list of fallback Gio.AppInfos for a given content type, i.e. those applications which claim to support the given content type by MIME type subclassing and not directly.

New in version 2.28.

Gio.app_info_get_recommended_for_type(content_type)[source]¶

Parameters:: content_type (str) – the content type to find a Gio.AppInfo for
Returns:: GLib.List of Gio.AppInfos for given content_type or None on error.
Return type:: [Gio.AppInfo]

Gets a list of recommended Gio.AppInfos for a given content type, i.e. those applications which claim to support the given content type exactly, and not by MIME type subclassing. Note that the first application of the list is the last used one, i.e. the last one for which Gio.AppInfo.set_as_last_used_for_type() has been called.

New in version 2.28.

Gio.app_info_launch_default_for_uri(uri, context)[source]¶

Parameters:

uri (str) – the uri to show
context (Gio.AppLaunchContext or None) – an optional Gio.AppLaunchContext

Raises:

Returns:

True on success, False on error.

Return type:

Utility function that launches the default application registered to handle the specified uri. Synchronous I/O is done on the uri to detect the type of the file if required.

The D-Bus–activated applications don’t have to be started if your application terminates too soon after this function. To prevent this, use Gio.AppInfo.launch_default_for_uri_async() instead.

Gio.app_info_launch_default_for_uri_async(uri, context, cancellable, callback, *user_data)[source]¶

Parameters:

uri (str) – the uri to show
context (Gio.AppLaunchContext or None) – an optional Gio.AppLaunchContext
cancellable (Gio.Cancellable or None) – a Gio.Cancellable
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the request is done
user_data (object or None) – data to pass to callback

Async version of Gio.AppInfo.launch_default_for_uri().

This version is useful if you are interested in receiving error information in the case where the application is sandboxed and the portal may present an application chooser dialog to the user.

This is also useful if you want to be sure that the D-Bus–activated applications are really started before termination and if you are interested in receiving error information from their activation.

New in version 2.50.

Gio.app_info_launch_default_for_uri_finish(result)[source]¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: True if the launch was successful, False if error is set
Return type:: bool

Finishes an asynchronous launch-default-for-uri operation.

New in version 2.50.

Gio.app_info_reset_type_associations(content_type)[source]¶

Parameters:: content_type (str) – a content type

Removes all changes to the type associations done by Gio.AppInfo.set_as_default_for_type(), Gio.AppInfo.set_as_default_for_extension(), Gio.AppInfo.add_supports_type() or Gio.AppInfo.remove_supports_type().

New in version 2.20.

Gio.async_initable_newv_async(object_type, n_parameters, parameters, io_priority, cancellable, callback, *user_data)[source]¶

Parameters:

object_type (GObject.GType) – a GObject.GType supporting Gio.AsyncInitable.
n_parameters (int) – the number of parameters in parameters
parameters (GObject.Parameter) – the parameters to use to construct the object
io_priority (int) – the I/O priority of the operation
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore.
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the initialization is finished
user_data (object or None) – the data to pass to callback function

Helper function for constructing Gio.AsyncInitable object. This is similar to GObject.Object.newv() but also initializes the object asynchronously.

When the initialization is finished, callback will be called. You can then call Gio.AsyncInitable.new_finish() to get the new object and check for any errors.

New in version 2.22.

Deprecated since version 2.54: Use g_object_new_with_properties() and Gio.AsyncInitable.init_async() instead. See GObject.Parameter for more information.

Gio.bus_get(bus_type, cancellable, callback, *user_data)[source]¶

Parameters:

bus_type (Gio.BusType) – a Gio.BusType
cancellable (Gio.Cancellable or None) – a Gio.Cancellable or None
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the request is satisfied
user_data (object or None) – the data to pass to callback

Asynchronously connects to the message bus specified by bus_type.

When the operation is finished, callback will be invoked. You can then call Gio.bus_get_finish() to get the result of the operation.

This is an asynchronous failable function. See Gio.bus_get_sync() for the synchronous version.

New in version 2.26.

Gio.bus_get_finish(res)[source]¶

Parameters:: res (Gio.AsyncResult) – a Gio.AsyncResult obtained from the Gio.AsyncReadyCallback passed to Gio.bus_get()
Raises:: GLib.Error
Returns:: a Gio.DBusConnection or None if error is set. Free with GObject.Object.unref().
Return type:: Gio.DBusConnection

Finishes an operation started with Gio.bus_get().

The returned object is a singleton, that is, shared with other callers of Gio.bus_get() and Gio.bus_get_sync() for bus_type. In the event that you need a private message bus connection, use Gio.dbus_address_get_for_bus_sync() and Gio.DBusConnection.new_for_address() with Gio.DBusConnectionFlags.AUTHENTICATION_CLIENT and Gio.DBusConnectionFlags.MESSAGE_BUS_CONNECTION flags.

Note that the returned Gio.DBusConnection object will (usually) have the Gio.DBusConnection :exit-on-close property set to True.

New in version 2.26.

Gio.bus_get_sync(bus_type, cancellable)[source]¶

Parameters:

bus_type (Gio.BusType) – a Gio.BusType
cancellable (Gio.Cancellable or None) – a Gio.Cancellable or None

Raises:

Returns:

a Gio.DBusConnection or None if error is set. Free with GObject.Object.unref().

Return type:

Gio.DBusConnection

Synchronously connects to the message bus specified by bus_type. Note that the returned object may shared with other callers, e.g. if two separate parts of a process calls this function with the same bus_type, they will share the same object.

This is a synchronous failable function. See Gio.bus_get() and Gio.bus_get_finish() for the asynchronous version.

The returned object is a singleton, that is, shared with other callers of Gio.bus_get() and Gio.bus_get_sync() for bus_type. In the event that you need a private message bus connection, use Gio.dbus_address_get_for_bus_sync() and Gio.DBusConnection.new_for_address() with Gio.DBusConnectionFlags.AUTHENTICATION_CLIENT and Gio.DBusConnectionFlags.MESSAGE_BUS_CONNECTION flags.

Note that the returned Gio.DBusConnection object will (usually) have the Gio.DBusConnection :exit-on-close property set to True.

New in version 2.26.

Gio.bus_own_name(bus_type, name, flags, bus_acquired_closure, name_acquired_closure, name_lost_closure)[source]¶

Parameters:

bus_type (Gio.BusType) – the type of bus to own a name on
name (str) – the well-known name to own
flags (Gio.BusNameOwnerFlags) – a set of flags from the Gio.BusNameOwnerFlags enumeration
bus_acquired_closure (GObject.Closure or None) – GObject.Closure to invoke when connected to the bus of type bus_type or None
name_acquired_closure (GObject.Closure or None) – GObject.Closure to invoke when name is acquired or None
name_lost_closure (GObject.Closure or None) – GObject.Closure to invoke when name is lost or None

Returns:

an identifier (never 0) that can be used with Gio.bus_unown_name() to stop owning the name.

Return type:

Version of Gio.bus_own_name() using closures instead of callbacks for easier binding in other languages.

New in version 2.26.

Gio.bus_own_name_on_connection(connection, name, flags, name_acquired_closure, name_lost_closure)[source]¶

Parameters:

connection (Gio.DBusConnection) – a Gio.DBusConnection
name (str) – the well-known name to own
flags (Gio.BusNameOwnerFlags) – a set of flags from the Gio.BusNameOwnerFlags enumeration
name_acquired_closure (GObject.Closure or None) – GObject.Closure to invoke when name is acquired or None
name_lost_closure (GObject.Closure or None) – GObject.Closure to invoke when name is lost or None

Returns:

an identifier (never 0) that can be used with Gio.bus_unown_name() to stop owning the name.

Return type:

Version of Gio.bus_own_name_on_connection() using closures instead of callbacks for easier binding in other languages.

New in version 2.26.

Gio.bus_unown_name(owner_id)[source]¶

Parameters:: owner_id (int) – an identifier obtained from Gio.bus_own_name()

Stops owning a name.

Note that there may still be D-Bus traffic to process (relating to owning and unowning the name) in the current thread-default GLib.MainContext after this function has returned. You should continue to iterate the GLib.MainContext until the GLib.DestroyNotify function passed to Gio.bus_own_name() is called, in order to avoid memory leaks through callbacks queued on the GLib.MainContext after it’s stopped being iterated.

New in version 2.26.

Gio.bus_unwatch_name(watcher_id)[source]¶

Parameters:: watcher_id (int) – An identifier obtained from Gio.bus_watch_name()

Stops watching a name.

Note that there may still be D-Bus traffic to process (relating to watching and unwatching the name) in the current thread-default GLib.MainContext after this function has returned. You should continue to iterate the GLib.MainContext until the GLib.DestroyNotify function passed to Gio.bus_watch_name() is called, in order to avoid memory leaks through callbacks queued on the GLib.MainContext after it’s stopped being iterated.

New in version 2.26.

Gio.bus_watch_name(bus_type, name, flags, name_appeared_closure, name_vanished_closure)[source]¶

Parameters:

bus_type (Gio.BusType) – The type of bus to watch a name on.
name (str) – The name (well-known or unique) to watch.
flags (Gio.BusNameWatcherFlags) – Flags from the Gio.BusNameWatcherFlags enumeration.
name_appeared_closure (GObject.Closure or None) – GObject.Closure to invoke when name is known to exist or None.
name_vanished_closure (GObject.Closure or None) – GObject.Closure to invoke when name is known to not exist or None.

Returns:

An identifier (never 0) that can be used with Gio.bus_unwatch_name() to stop watching the name.

Return type:

Version of Gio.bus_watch_name() using closures instead of callbacks for easier binding in other languages.

New in version 2.26.

Gio.bus_watch_name_on_connection(connection, name, flags, name_appeared_closure, name_vanished_closure)[source]¶

Parameters:

connection (Gio.DBusConnection) – A Gio.DBusConnection.
name (str) – The name (well-known or unique) to watch.
flags (Gio.BusNameWatcherFlags) – Flags from the Gio.BusNameWatcherFlags enumeration.
name_appeared_closure (GObject.Closure or None) – GObject.Closure to invoke when name is known to exist or None.
name_vanished_closure (GObject.Closure or None) – GObject.Closure to invoke when name is known to not exist or None.

Returns:

An identifier (never 0) that can be used with Gio.bus_unwatch_name() to stop watching the name.

Return type:

Version of Gio.bus_watch_name_on_connection() using closures instead of callbacks for easier binding in other languages.

New in version 2.26.

Gio.content_type_can_be_executable(type)[source]¶

Parameters:: type (str) – a content type string
Returns:: True if the file type corresponds to a type that can be executable, False otherwise.
Return type:: bool

Checks if a content type can be executable. Note that for instance things like text files can be executables (i.e. scripts and batch files).

Gio.content_type_equals(type1, type2)[source]¶

Parameters:

type1 (str) – a content type string
type2 (str) – a content type string

Returns:

True if the two strings are identical or equivalent, False otherwise.

Return type:

Compares two content types for equality.

Gio.content_type_from_mime_type(mime_type)[source]¶

Parameters:: mime_type (str) – a mime type string
Returns:: Newly allocated string with content type or None. Free with GLib.free()
Return type:: str or None

Tries to find a content type based on the mime type name.

New in version 2.18.

Gio.content_type_get_description(type)[source]¶

Parameters:: type (str) – a content type string
Returns:: a short description of the content type type. Free the returned string with GLib.free()
Return type:: str

Gets the human readable description of the content type.

Gio.content_type_get_generic_icon_name(type)[source]¶

Parameters:: type (str) – a content type string
Returns:: the registered generic icon name for the given type, or None if unknown. Free with GLib.free()
Return type:: str or None

Gets the generic icon name for a content type.

See the shared-mime-info specification for more on the generic icon name.

New in version 2.34.

Gio.content_type_get_icon(type)[source]¶

Parameters:: type (str) – a content type string
Returns:: Gio.Icon corresponding to the content type. Free the returned object with GObject.Object.unref()
Return type:: Gio.Icon

Gets the icon for a content type.

Gio.content_type_get_mime_dirs()[source]¶

Returns:: None-terminated list of directories to load MIME data from, including any mime/ subdirectory, and with the first directory to try listed first
Return type:: [str]

Get the list of directories which MIME data is loaded from. See Gio.content_type_set_mime_dirs() for details.

New in version 2.60.

Gio.content_type_get_mime_type(type)[source]¶

Parameters:: type (str) – a content type string
Returns:: the registered mime type for the given type, or None if unknown; free with GLib.free().
Return type:: str or None

Gets the mime type for the content type, if one is registered.

Gio.content_type_get_symbolic_icon(type)[source]¶

Parameters:: type (str) – a content type string
Returns:: symbolic Gio.Icon corresponding to the content type. Free the returned object with GObject.Object.unref()
Return type:: Gio.Icon

Gets the symbolic icon for a content type.

New in version 2.34.

Gio.content_type_guess(filename, data)[source]¶

Parameters:

filename (str or None) – a path, or None
data (bytes or None) – a stream of data, or None

Returns:

a string indicating a guessed content type for the given data. Free with GLib.free()

result_uncertain:: return location for the certainty of the result, or None

Return type:

(str, result_uncertain: bool)

Guesses the content type based on example data. If the function is uncertain, result_uncertain will be set to True. Either filename or data may be None, in which case the guess will be based solely on the other argument.

Gio.content_type_guess_for_tree(root)[source]¶

Parameters:: root (Gio.File) – the root of the tree to guess a type for
Returns:: an None-terminated array of zero or more content types. Free with GLib.strfreev()
Return type:: [str]

Tries to guess the type of the tree with root root, by looking at the files it contains. The result is an array of content types, with the best guess coming first.

The types returned all have the form x-content/foo, e.g. x-content/audio-cdda (for audio CDs) or x-content/image-dcf (for a camera memory card). See the shared-mime-info specification for more on x-content types.

This function is useful in the implementation of Gio.Mount.guess_content_type().

New in version 2.18.

Gio.content_type_is_a(type, supertype)[source]¶

Parameters:

type (str) – a content type string
supertype (str) – a content type string

Returns:

True if type is a kind of supertype, False otherwise.

Return type:

Determines if type is a subset of supertype.

Gio.content_type_is_mime_type(type, mime_type)[source]¶

Parameters:

type (str) – a content type string
mime_type (str) – a mime type string

Returns:

True if type is a kind of mime_type, False otherwise.

Return type:

Determines if type is a subset of mime_type. Convenience wrapper around Gio.content_type_is_a().

New in version 2.52.

Gio.content_type_is_unknown(type)[source]¶

Parameters:: type (str) – a content type string
Returns:: True if the type is the unknown type.
Return type:: bool

Checks if the content type is the generic “unknown” type. On UNIX this is the “application/octet-stream” mimetype, while on win32 it is “*” and on OSX it is a dynamic type or octet-stream.

Gio.content_type_set_mime_dirs(dirs)[source]¶

Parameters:: dirs ([str] or None) – None-terminated list of directories to load MIME data from, including any mime/ subdirectory, and with the first directory to try listed first

Set the list of directories used by GIO to load the MIME database. If dirs is None, the directories used are the default:

the mime subdirectory of the directory in $XDG_DATA_HOME
the mime subdirectory of every directory in $XDG_DATA_DIRS

This function is intended to be used when writing tests that depend on information stored in the MIME database, in order to control the data.

Typically, in case your tests use GLib.TEST_OPTION_ISOLATE_DIRS, but they depend on the system’s MIME database, you should call this function with dirs set to None before calling g_test_init(), for instance:

// Load MIME data from the system
g_content_type_set_mime_dirs (NULL);
// Isolate the environment
g_test_init (&argc, &argv, G_TEST_OPTION_ISOLATE_DIRS, NULL);

…

return g_test_run ();

New in version 2.60.

Gio.content_types_get_registered()[source]¶

Returns:: list of the registered content types
Return type:: [str]

Gets a list of strings containing all the registered content types known to the system. The list and its data should be freed using g_list_free_full (list, g_free).

Gio.dbus_address_escape_value(string)[source]¶

Parameters:: string (str) – an unescaped string to be included in a D-Bus address as the value in a key-value pair
Returns:: a copy of string with all non-optionally-escaped bytes escaped
Return type:: str

Escape string so it can appear in a D-Bus address as the value part of a key-value pair.

For instance, if string is /run/bus-for-:0, this function would return /run/bus-for-%3A0, which could be used in a D-Bus address like unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0.

New in version 2.36.

Gio.dbus_address_get_for_bus_sync(bus_type, cancellable)[source]¶

Parameters:

bus_type (Gio.BusType) – a Gio.BusType
cancellable (Gio.Cancellable or None) – a Gio.Cancellable or None

Raises:

Returns:

a valid D-Bus address string for bus_type or None if error is set

Return type:

str

Synchronously looks up the D-Bus address for the well-known message bus instance specified by bus_type. This may involve using various platform specific mechanisms.

The returned address will be in the D-Bus address format.

New in version 2.26.

Gio.dbus_address_get_stream(address, cancellable, callback, *user_data)[source]¶

Parameters:

address (str) – A valid D-Bus address.
cancellable (Gio.Cancellable or None) – A Gio.Cancellable or None.
callback (Gio.AsyncReadyCallback or None) – A Gio.AsyncReadyCallback to call when the request is satisfied.
user_data (object or None) – Data to pass to callback.

Asynchronously connects to an endpoint specified by address and sets up the connection so it is in a state to run the client-side of the D-Bus authentication conversation. address must be in the D-Bus address format.

When the operation is finished, callback will be invoked. You can then call Gio.dbus_address_get_stream_finish() to get the result of the operation.

This is an asynchronous failable function. See Gio.dbus_address_get_stream_sync() for the synchronous version.

New in version 2.26.

Gio.dbus_address_get_stream_finish(res)[source]¶

Parameters:

res (Gio.AsyncResult) – A Gio.AsyncResult obtained from the Gio.AsyncReadyCallback passed to Gio.dbus_address_get_stream().

Raises:

Returns:

A Gio.IOStream or None if error is set.

out_guid:: None or return location to store the GUID extracted from address, if any.

Return type:

(Gio.IOStream, out_guid: str or None)

Finishes an operation started with Gio.dbus_address_get_stream().

A server is not required to set a GUID, so out_guid may be set to None even on success.

New in version 2.26.

Gio.dbus_address_get_stream_sync(address, cancellable)[source]¶

Parameters:

address (str) – A valid D-Bus address.
cancellable (Gio.Cancellable or None) – A Gio.Cancellable or None.

Raises:

Returns:

A Gio.IOStream or None if error is set.

out_guid:: None or return location to store the GUID extracted from address, if any.

Return type:

(Gio.IOStream, out_guid: str or None)

Synchronously connects to an endpoint specified by address and sets up the connection so it is in a state to run the client-side of the D-Bus authentication conversation. address must be in the D-Bus address format.

A server is not required to set a GUID, so out_guid may be set to None even on success.

This is a synchronous failable function. See Gio.dbus_address_get_stream() for the asynchronous version.

New in version 2.26.

Gio.dbus_annotation_info_lookup(annotations, name)[source]¶

Parameters:

annotations ([Gio.DBusAnnotationInfo] or None) – A None-terminated array of annotations or None.
name (str) – The name of the annotation to look up.

Returns:

The value or None if not found. Do not free, it is owned by annotations.

Return type:

str or None

Looks up the value of an annotation.

The cost of this function is O(n) in number of annotations.

New in version 2.26.

Gio.dbus_error_encode_gerror(error)[source]¶

Parameters:: error (GLib.Error) – A GLib.Error.
Returns:: A D-Bus error name (never None). Free with GLib.free().
Return type:: str

Creates a D-Bus error name to use for error. If error matches a registered error (cf. Gio.DBusError.register_error()), the corresponding D-Bus error name will be returned.

Otherwise the a name of the form org.gtk.GDBus.UnmappedGError.Quark._ESCAPED_QUARK_NAME.Code_ERROR_CODE will be used. This allows other GDBus applications to map the error on the wire back to a GLib.Error using Gio.DBusError.new_for_dbus_error().

This function is typically only used in object mappings to put a GLib.Error on the wire. Regular applications should not use it.

New in version 2.26.

Gio.dbus_error_get_remote_error(error)[source]¶

Parameters:: error (GLib.Error) – a GLib.Error
Returns:: an allocated string or None if the D-Bus error name could not be found. Free with GLib.free().
Return type:: str or None

Gets the D-Bus error name used for error, if any.

This function is guaranteed to return a D-Bus error name for all GLib.Errors returned from functions handling remote method calls (e.g. Gio.DBusConnection.call_finish()) unless Gio.DBusError.strip_remote_error() has been used on error.

New in version 2.26.

Gio.dbus_error_is_remote_error(error)[source]¶

Parameters:: error (GLib.Error) – A GLib.Error.
Returns:: True if error represents an error from a remote peer, False otherwise.
Return type:: bool

Checks if error represents an error received via D-Bus from a remote peer. If so, use Gio.DBusError.get_remote_error() to get the name of the error.

New in version 2.26.

Gio.dbus_error_new_for_dbus_error(dbus_error_name, dbus_error_message)[source]¶

Parameters:

dbus_error_name (str) – D-Bus error name.
dbus_error_message (str) – D-Bus error message.

Returns:

An allocated GLib.Error. Free with GLib.Error.free().

Return type:

Creates a GLib.Error based on the contents of dbus_error_name and dbus_error_message.

Errors registered with Gio.DBusError.register_error() will be looked up using dbus_error_name and if a match is found, the error domain and code is used. Applications can use Gio.DBusError.get_remote_error() to recover dbus_error_name.

If a match against a registered error is not found and the D-Bus error name is in a form as returned by Gio.DBusError.encode_gerror() the error domain and code encoded in the name is used to create the GLib.Error. Also, dbus_error_name is added to the error message such that it can be recovered with Gio.DBusError.get_remote_error().

Otherwise, a GLib.Error with the error code Gio.IOErrorEnum.DBUS_ERROR in the %G_IO_ERROR error domain is returned. Also, dbus_error_name is added to the error message such that it can be recovered with Gio.DBusError.get_remote_error().

In all three cases, dbus_error_name can always be recovered from the returned GLib.Error using the Gio.DBusError.get_remote_error() function (unless Gio.DBusError.strip_remote_error() hasn’t been used on the returned error).

This function is typically only used in object mappings to prepare GLib.Error instances for applications. Regular applications should not use it.

New in version 2.26.

Gio.dbus_error_quark()[source]¶

Return type:: int

Gio.dbus_error_register_error(error_domain, error_code, dbus_error_name)[source]¶

Parameters:

error_domain (int) – A #GQuark for an error domain.
error_code (int) – An error code.
dbus_error_name (str) – A D-Bus error name.

Returns:

True if the association was created, False if it already exists.

Return type:

Creates an association to map between dbus_error_name and GLib.Errors specified by error_domain and error_code.

This is typically done in the routine that returns the #GQuark for an error domain.

New in version 2.26.

Gio.dbus_error_register_error_domain(error_domain_quark_name, quark_volatile, entries)[source]¶

Parameters:

error_domain_quark_name (str) – The error domain name.
quark_volatile (int) – A pointer where to store the #GQuark.
entries ([Gio.DBusErrorEntry]) – A pointer to num_entries Gio.DBusErrorEntry struct items.

Helper function for associating a GLib.Error error domain with D-Bus error names.

While quark_volatile has a volatile qualifier, this is a historical artifact and the argument passed to it should not be volatile.

New in version 2.26.

Gio.dbus_error_strip_remote_error(error)[source]¶

Parameters:: error (GLib.Error) – A GLib.Error.
Returns:: True if information was stripped, False otherwise.
Return type:: bool

Looks for extra information in the error message used to recover the D-Bus error name and strips it if found. If stripped, the message field in error will correspond exactly to what was received on the wire.

This is typically used when presenting errors to the end user.

New in version 2.26.

Gio.dbus_error_unregister_error(error_domain, error_code, dbus_error_name)[source]¶

Parameters:

error_domain (int) – A #GQuark for an error domain.
error_code (int) – An error code.
dbus_error_name (str) – A D-Bus error name.

Returns:

True if the association was destroyed, False if it wasn’t found.

Return type:

Destroys an association previously set up with Gio.DBusError.register_error().

New in version 2.26.

Gio.dbus_escape_object_path(s)[source]¶

Parameters:: s (str) – the string to escape
Returns:: an escaped version of s. Free with GLib.free().
Return type:: str

This is a language binding friendly version of Gio.dbus_escape_object_path_bytestring().

New in version 2.68.

Gio.dbus_escape_object_path_bytestring(bytes)[source]¶

Parameters:: bytes (bytes) – the string of bytes to escape
Returns:: an escaped version of bytes. Free with GLib.free().
Return type:: str

Escapes bytes for use in a D-Bus object path component. bytes is an array of zero or more nonzero bytes in an unspecified encoding, followed by a single zero byte.

The escaping method consists of replacing all non-alphanumeric characters (see g_ascii_isalnum()) with their hexadecimal value preceded by an underscore (_). For example: foo.bar.baz will become foo_2ebar_2ebaz.

This method is appropriate to use when the input is nearly a valid object path component but is not when your input is far from being a valid object path component. Other escaping algorithms are also valid to use with D-Bus object paths.

This can be reversed with Gio.dbus_unescape_object_path().

New in version 2.68.

Gio.dbus_generate_guid()[source]¶

Returns:: A valid D-Bus GUID. Free with GLib.free().
Return type:: str

Generate a D-Bus GUID that can be used with e.g. Gio.DBusConnection.new().

See the D-Bus specification regarding what strings are valid D-Bus GUIDs. The specification refers to these as ‘UUIDs’ whereas GLib (for historical reasons) refers to them as ‘GUIDs’. The terms are interchangeable.

Note that D-Bus GUIDs do not follow RFC 4122.

New in version 2.26.

Gio.dbus_gvalue_to_gvariant(gvalue, type)[source]¶

Parameters:

gvalue (GObject.Value) – A GObject.Value to convert to a GLib.Variant
type (GLib.VariantType) – A GLib.VariantType

Returns:

A GLib.Variant (never floating) of GLib.VariantType type holding the data from gvalue or an empty GLib.Variant in case of failure. Free with GLib.Variant.unref().

Return type:

GLib.Variant

Converts a GObject.Value to a GLib.Variant of the type indicated by the type parameter.

The conversion is using the following rules:

G_TYPE_STRING: ‘s’, ‘o’, ‘g’ or ‘ay’
G_TYPE_STRV: ‘as’, ‘ao’ or ‘aay’
G_TYPE_BOOLEAN: ‘b’
G_TYPE_UCHAR: ‘y’
G_TYPE_INT: ‘i’, ‘n’
G_TYPE_UINT: ‘u’, ‘q’
G_TYPE_INT64: ‘x’
G_TYPE_UINT64: ‘t’
G_TYPE_DOUBLE: ‘d’
G_TYPE_VARIANT: Any GLib.VariantType

This can fail if e.g. gvalue is of type GObject.TYPE_STRING and type is ‘i’, i.e. %G_VARIANT_TYPE_INT32. It will also fail for any GObject.GType (including e.g. GObject.TYPE_OBJECT and GObject.TYPE_BOXED derived-types) not in the table above.

Note that if gvalue is of type GObject.TYPE_VARIANT and its value is None, the empty GLib.Variant instance (never None) for type is returned (e.g. 0 for scalar types, the empty string for string types, ‘/’ for object path types, the empty array for any array type and so on).

See the Gio.dbus_gvariant_to_gvalue() function for how to convert a GLib.Variant to a GObject.Value.

New in version 2.30.

Gio.dbus_gvariant_to_gvalue(value)[source]¶

Parameters:: value (GLib.Variant) – A GLib.Variant.
Returns:: Return location pointing to a zero-filled (uninitialized) GObject.Value.
Return type:: out_gvalue: GObject.Value

Converts a GLib.Variant to a GObject.Value. If value is floating, it is consumed.

The rules specified in the Gio.dbus_gvalue_to_gvariant() function are used - this function is essentially its reverse form. So, a GLib.Variant containing any basic or string array type will be converted to a GObject.Value containing a basic value or string array. Any other GLib.Variant (handle, variant, tuple, dict entry) will be converted to a GObject.Value containing that GLib.Variant.

The conversion never fails - a valid GObject.Value is always returned in out_gvalue.

New in version 2.30.

Gio.dbus_is_address(string)[source]¶

Parameters:: string (str) – A string.
Returns:: True if string is a valid D-Bus address, False otherwise.
Return type:: bool

Checks if string is a D-Bus address.

This doesn’t check if string is actually supported by Gio.DBusServer or Gio.DBusConnection - use Gio.dbus_is_supported_address() to do more checks.

New in version 2.26.

Gio.dbus_is_error_name(string)[source]¶

Parameters:: string (str) – The string to check.
Returns:: True if valid, False otherwise.
Return type:: bool

Check whether string is a valid D-Bus error name.

This function returns the same result as Gio.dbus_is_interface_name(), because D-Bus error names are defined to have exactly the same syntax as interface names.

New in version 2.70.

Gio.dbus_is_guid(string)[source]¶

Parameters:: string (str) – The string to check.
Returns:: True if string is a GUID, False otherwise.
Return type:: bool

Checks if string is a D-Bus GUID.

See the documentation for Gio.dbus_generate_guid() for more information about the format of a GUID.

New in version 2.26.

Gio.dbus_is_interface_name(string)[source]¶

Parameters:: string (str) – The string to check.
Returns:: True if valid, False otherwise.
Return type:: bool

Checks if string is a valid D-Bus interface name.

New in version 2.26.

Gio.dbus_is_member_name(string)[source]¶

Parameters:: string (str) – The string to check.
Returns:: True if valid, False otherwise.
Return type:: bool

Checks if string is a valid D-Bus member (e.g. signal or method) name.

New in version 2.26.

Gio.dbus_is_name(string)[source]¶

Parameters:: string (str) – The string to check.
Returns:: True if valid, False otherwise.
Return type:: bool

Checks if string is a valid D-Bus bus name (either unique or well-known).

New in version 2.26.

Gio.dbus_is_supported_address(string)[source]¶

Parameters:: string (str) – A string.
Raises:: GLib.Error
Returns:: True if string is a valid D-Bus address that is supported by this library, False if error is set.
Return type:: bool

Like Gio.dbus_is_address() but also checks if the library supports the transports in string and that key/value pairs for each transport are valid. See the specification of the D-Bus address format.

New in version 2.26.

Gio.dbus_is_unique_name(string)[source]¶

Parameters:: string (str) – The string to check.
Returns:: True if valid, False otherwise.
Return type:: bool

Checks if string is a valid D-Bus unique bus name.

New in version 2.26.

Gio.dbus_unescape_object_path(s)[source]¶

Parameters:: s (str) – the string to unescape
Returns:: an unescaped version of s, or None if s is not a string returned from Gio.dbus_escape_object_path(). Free with GLib.free().
Return type:: bytes or None

Unescapes an string that was previously escaped with Gio.dbus_escape_object_path(). If the string is in a format that could not have been returned by Gio.dbus_escape_object_path(), this function returns None.

Encoding alphanumeric characters which do not need to be encoded is not allowed (e.g _63 is not valid, the string should contain c instead).

New in version 2.68.

Gio.dtls_client_connection_new(base_socket, server_identity)[source]¶

Parameters:

base_socket (Gio.DatagramBased) – the Gio.DatagramBased to wrap
server_identity (Gio.SocketConnectable or None) – the expected identity of the server

Raises:

Gio.DtlsClientConnection

Returns:

the new Gio.DtlsClientConnection, or None on error

Return type:

Creates a new Gio.DtlsClientConnection wrapping base_socket which is assumed to communicate with the server identified by server_identity.

New in version 2.48.

Gio.dtls_server_connection_new(base_socket, certificate)[source]¶

Parameters:

base_socket (Gio.DatagramBased) – the Gio.DatagramBased to wrap
certificate (Gio.TlsCertificate or None) – the default server certificate, or None

Raises:

Gio.DtlsServerConnection

Returns:

the new Gio.DtlsServerConnection, or None on error

Return type:

Creates a new Gio.DtlsServerConnection wrapping base_socket.

New in version 2.48.

Gio.file_new_build_filenamev(args)[source]¶

Parameters:: args ([str]) – None-terminated array of strings containing the path elements.
Returns:: a new Gio.File
Return type:: Gio.File

Constructs a Gio.File from a vector of elements using the correct separator for filenames.

Using this function is equivalent to calling GLib.build_filenamev(), followed by Gio.File.new_for_path() on the result.

New in version 2.78.

Gio.file_new_for_commandline_arg(arg)[source]¶

Parameters:: arg (str) – a command line string
Returns:: a new Gio.File. Free the returned object with GObject.Object.unref().
Return type:: Gio.File

Creates a Gio.File with the given argument from the command line. The value of arg can be either a URI, an absolute path or a relative path resolved relative to the current working directory. This operation never fails, but the returned object might not support any I/O operation if arg points to a malformed path.

Note that on Windows, this function expects its argument to be in UTF-8 – not the system code page. This means that you should not use this function with string from argv as it is passed to main(). g_win32_get_command_line() will return a UTF-8 version of the commandline. Gio.Application also uses UTF-8 but Gio.ApplicationCommandLine.create_file_for_arg() may be more useful for you there. It is also always possible to use this function with GLib.OptionContext arguments of type GLib.OptionArg.FILENAME.

Gio.file_new_for_commandline_arg_and_cwd(arg, cwd)[source]¶

Parameters:

arg (str) – a command line string
cwd (str) – the current working directory of the commandline

Returns:

a new Gio.File

Return type:

Gio.File

Creates a Gio.File with the given argument from the command line.

This function is similar to Gio.File.new_for_commandline_arg() except that it allows for passing the current working directory as an argument instead of using the current working directory of the process.

This is useful if the commandline argument was given in a context other than the invocation of the current process.

New in version 2.36.

Gio.file_new_for_path(path)[source]¶

Parameters:: path (str) – a string containing a relative or absolute path. The string must be encoded in the glib filename encoding.
Returns:: a new Gio.File for the given path. Free the returned object with GObject.Object.unref().
Return type:: Gio.File

Constructs a Gio.File for a given path. This operation never fails, but the returned object might not support any I/O operation if path is malformed.

Gio.file_new_for_uri(uri)[source]¶

Parameters:: uri (str) – a UTF-8 string containing a URI
Returns:: a new Gio.File for the given uri. Free the returned object with GObject.Object.unref().
Return type:: Gio.File

Constructs a Gio.File for a given URI. This operation never fails, but the returned object might not support any I/O operation if uri is malformed or if the uri type is not supported.

Gio.file_new_tmp(tmpl)[source]¶

Parameters:

tmpl (str or None) – Template for the file name, as in GLib.file_open_tmp(), or None for a default template

Raises:

Returns:

a new Gio.File. Free the returned object with GObject.Object.unref().

iostream:: on return, a Gio.FileIOStream for the created file

Return type:

(Gio.File, iostream: Gio.FileIOStream)

Opens a file in the preferred directory for temporary files (as returned by GLib.get_tmp_dir()) and returns a Gio.File and Gio.FileIOStream pointing to it.

tmpl should be a string in the GLib file name encoding containing a sequence of six ‘X’ characters, and containing no directory components. If it is None, a default template is used.

Unlike the other Gio.File constructors, this will return None if a temporary file could not be created.

New in version 2.32.

Gio.file_new_tmp_async(tmpl, io_priority, cancellable, callback, *user_data)[source]¶

Parameters:

tmpl (str or None) – Template for the file name, as in GLib.file_open_tmp(), or None for a default template
io_priority (int) – the I/O priority of the request
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the request is done
user_data (object or None) – data to pass to callback

Asynchronously opens a file in the preferred directory for temporary files (as returned by GLib.get_tmp_dir()) as Gio.File.new_tmp().

tmpl should be a string in the GLib file name encoding containing a sequence of six ‘X’ characters, and containing no directory components. If it is None, a default template is used.

New in version 2.74.

Gio.file_new_tmp_dir_async(tmpl, io_priority, cancellable, callback, *user_data)[source]¶

Parameters:

tmpl (str or None) – Template for the file name, as in GLib.Dir.make_tmp(), or None for a default template
io_priority (int) – the I/O priority of the request
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the request is done
user_data (object or None) – data to pass to callback

Asynchronously creates a directory in the preferred directory for temporary files (as returned by GLib.get_tmp_dir()) as GLib.Dir.make_tmp().

tmpl should be a string in the GLib file name encoding containing a sequence of six ‘X’ characters, and containing no directory components. If it is None, a default template is used.

New in version 2.74.

Gio.file_new_tmp_dir_finish(result)[source]¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: a new Gio.File. Free the returned object with GObject.Object.unref().
Return type:: Gio.File

Finishes a temporary directory creation started by Gio.File.new_tmp_dir_async().

New in version 2.74.

Gio.file_new_tmp_finish(result)[source]¶

Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult

Raises:

Returns:

a new Gio.File. Free the returned object with GObject.Object.unref().

iostream:: on return, a Gio.FileIOStream for the created file

Return type:

(Gio.File, iostream: Gio.FileIOStream)

Finishes a temporary file creation started by Gio.File.new_tmp_async().

New in version 2.74.

Gio.file_parse_name(parse_name)[source]¶

Parameters:: parse_name (str) – a file name or path to be parsed
Returns:: a new Gio.File.
Return type:: Gio.File

Constructs a Gio.File with the given parse_name (i.e. something given by Gio.File.get_parse_name()). This operation never fails, but the returned object might not support any I/O operation if the parse_name cannot be parsed.

Gio.icon_deserialize(value)[source]¶

Parameters:: value (GLib.Variant) – a GLib.Variant created with Gio.Icon.serialize()
Returns:: a Gio.Icon, or None when deserialization fails.
Return type:: Gio.Icon or None

Deserializes a Gio.Icon previously serialized using Gio.Icon.serialize().

New in version 2.38.

Gio.icon_new_for_string(str)[source]¶

Parameters:: str (str) – A string obtained via Gio.Icon.to_string().
Raises:: GLib.Error
Returns:: An object implementing the Gio.Icon interface or None if error is set.
Return type:: Gio.Icon

Generate a Gio.Icon instance from str. This function can fail if str is not valid - see Gio.Icon.to_string() for discussion.

If your application or library provides one or more Gio.Icon implementations you need to ensure that each GObject.GType is registered with the type system prior to calling Gio.Icon.new_for_string().

New in version 2.20.

Gio.initable_newv(object_type, parameters, cancellable)[source]¶

Parameters:

object_type (GObject.GType) – a GObject.GType supporting Gio.Initable.
parameters ([GObject.Parameter]) – the parameters to use to construct the object
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore.

Raises:

Returns:

a newly allocated GObject.Object, or None on error

Return type:

GObject.Object

Helper function for constructing Gio.Initable object. This is similar to GObject.Object.newv() but also initializes the object and returns None, setting an error on failure.

New in version 2.22.

Deprecated since version 2.54: Use g_object_new_with_properties() and Gio.Initable.init() instead. See GObject.Parameter for more information.

Gio.io_error_from_errno(err_no)[source]¶

Parameters:: err_no (int) – Error number as defined in errno.h.
Returns:: Gio.IOErrorEnum value for the given errno.h error number
Return type:: Gio.IOErrorEnum

Converts errno.h error codes into GIO error codes.

The fallback value Gio.IOErrorEnum.FAILED is returned for error codes not currently handled (but note that future GLib releases may return a more specific value instead).

As errno is global and may be modified by intermediate function calls, you should save its value immediately after the call returns, and use the saved value instead of errno :

int saved_errno;

ret = read (blah);
saved_errno = errno;

g_io_error_from_errno (saved_errno);

Gio.io_error_from_file_error(file_error)[source]¶

Parameters:: file_error (GLib.FileError) – a GLib.FileError.
Returns:: Gio.IOErrorEnum value for the given GLib.FileError error value.
Return type:: Gio.IOErrorEnum

Converts GLib.FileError error codes into GIO error codes.

New in version 2.74.

Gio.io_error_quark()[source]¶

Returns:: a #GQuark.
Return type:: int

Gets the GIO Error Quark.

Gio.io_extension_point_implement(extension_point_name, type, extension_name, priority)[source]¶

Parameters:

extension_point_name (str) – the name of the extension point
type (GObject.GType) – the GObject.GType to register as extension
extension_name (str) – the name for the extension
priority (int) – the priority for the extension

Returns:

a Gio.IOExtension object for GObject.GType

Return type:

Gio.IOExtension

Registers type as extension for the extension point with name extension_point_name.

If type has already been registered as an extension for this extension point, the existing Gio.IOExtension object is returned.

Gio.io_extension_point_lookup(name)[source]¶

Parameters:: name (str) – the name of the extension point
Returns:: the Gio.IOExtensionPoint, or None if there is no registered extension point with the given name.
Return type:: Gio.IOExtensionPoint

Looks up an existing extension point.

Gio.io_extension_point_register(name)[source]¶

Parameters:: name (str) – The name of the extension point
Returns:: the new Gio.IOExtensionPoint. This object is owned by GIO and should not be freed.
Return type:: Gio.IOExtensionPoint

Registers an extension point.

Gio.io_modules_load_all_in_directory(dirname)[source]¶

Parameters:: dirname (str) – pathname for a directory containing modules to load.
Returns:: a list of Gio.IOModules loaded from the directory, All the modules are loaded into memory, if you want to unload them (enabling on-demand loading) you must call GObject.TypeModule.unuse() on all the modules. Free the list with g_list_free().
Return type:: [Gio.IOModule]

Loads all the modules in the specified directory.

If don’t require all modules to be initialized (and thus registering all gtypes) then you can use Gio.io_modules_scan_all_in_directory() which allows delayed/lazy loading of modules.

Gio.io_modules_load_all_in_directory_with_scope(dirname, scope)[source]¶

Parameters:

dirname (str) – pathname for a directory containing modules to load.
scope (Gio.IOModuleScope) – a scope to use when scanning the modules.

Returns:

a list of Gio.IOModules loaded from the directory, All the modules are loaded into memory, if you want to unload them (enabling on-demand loading) you must call GObject.TypeModule.unuse() on all the modules. Free the list with g_list_free().

Return type:

[Gio.IOModule]

Loads all the modules in the specified directory.

If don’t require all modules to be initialized (and thus registering all gtypes) then you can use Gio.io_modules_scan_all_in_directory() which allows delayed/lazy loading of modules.

New in version 2.30.

Gio.io_modules_scan_all_in_directory(dirname)[source]¶

Parameters:: dirname (str) – pathname for a directory containing modules to scan.

Scans all the modules in the specified directory, ensuring that any extension point implemented by a module is registered.

This may not actually load and initialize all the types in each module, some modules may be lazily loaded and initialized when an extension point it implements is used with e.g. Gio.IOExtensionPoint.get_extensions() or Gio.IOExtensionPoint.get_extension_by_name().

If you need to guarantee that all types are loaded in all the modules, use Gio.io_modules_load_all_in_directory().

New in version 2.24.

Gio.io_modules_scan_all_in_directory_with_scope(dirname, scope)[source]¶

Parameters:

dirname (str) – pathname for a directory containing modules to scan.
scope (Gio.IOModuleScope) – a scope to use when scanning the modules

Scans all the modules in the specified directory, ensuring that any extension point implemented by a module is registered.

This may not actually load and initialize all the types in each module, some modules may be lazily loaded and initialized when an extension point it implements is used with e.g. Gio.IOExtensionPoint.get_extensions() or Gio.IOExtensionPoint.get_extension_by_name().

If you need to guarantee that all types are loaded in all the modules, use Gio.io_modules_load_all_in_directory().

New in version 2.30.

Gio.io_scheduler_cancel_all_jobs()[source]¶

Cancels all cancellable I/O jobs.

A job is cancellable if a Gio.Cancellable was passed into Gio.io_scheduler_push_job().

Deprecated since version 2.36: You should never call this function, since you don’t know how other libraries in your program might be making use of gioscheduler.

Gio.io_scheduler_push_job(job_func, user_data, io_priority, cancellable)[source]¶

Parameters:

job_func (Gio.IOSchedulerJobFunc) – a Gio.IOSchedulerJobFunc.
user_data (object or None) – data to pass to job_func
io_priority (int) – the I/O priority of the request.
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore.

Schedules the I/O job to run in another thread.

notify will be called on user_data after job_func has returned, regardless whether the job was cancelled or has run to completion.

If cancellable is not None, it can be used to cancel the I/O job by calling Gio.Cancellable.cancel() or by calling Gio.io_scheduler_cancel_all_jobs().

Deprecated since version 2.36: use GLib.ThreadPool or Gio.Task.run_in_thread()

Gio.keyfile_settings_backend_new(filename, root_path, root_group)[source]¶

Parameters:

filename (str) – the filename of the keyfile
root_path (str) – the path under which all settings keys appear
root_group (str or None) – the group name corresponding to root_path, or None

Returns:

a keyfile-backed Gio.SettingsBackend

Return type:

Gio.SettingsBackend

Creates a keyfile-backed Gio.SettingsBackend.

The filename of the keyfile to use is given by filename.

All settings read to or written from the backend must fall under the path given in root_path (which must start and end with a slash and not contain two consecutive slashes). root_path may be “/”.

If root_group is non-None then it specifies the name of the keyfile group used for keys that are written directly below root_path. For example, if root_path is “/apps/example/” and root_group is “toplevel”, then settings the key “/apps/example/enabled” to a value of True will cause the following to appear in the keyfile:

[toplevel]
enabled=true

If root_group is None then it is not permitted to store keys directly below the root_path.

For keys not stored directly below root_path (ie: in a sub-path), the name of the subpath (with the final slash stripped) is used as the name of the keyfile group. To continue the example, if “/apps/example/profiles/default/font-size” were set to 12 then the following would appear in the keyfile:

[profiles/default]
font-size=12

The backend will refuse writes (and return writability as being False) for keys outside of root_path and, in the event that root_group is None, also for keys directly under root_path. Writes will also be refused if the backend detects that it has the inability to rewrite the keyfile (ie: the containing directory is not writable).

There is no checking done for your key namespace clashing with the syntax of the key file format. For example, if you have ‘[’ or ‘]’ characters in your path names or ‘=’ in your key names you may be in trouble.

The backend reads default values from a keyfile called defaults in the directory specified by the #GKeyfileSettingsBackend:defaults-dir property, and a list of locked keys from a text file with the name locks in the same location.

Gio.memory_monitor_dup_default()[source]¶

Returns:: a new reference to the default Gio.MemoryMonitor
Return type:: Gio.MemoryMonitor

Gets a reference to the default Gio.MemoryMonitor for the system.

New in version 2.64.

Gio.memory_settings_backend_new()[source]¶

Returns:: a newly created Gio.SettingsBackend
Return type:: Gio.SettingsBackend

Creates a memory-backed Gio.SettingsBackend.

This backend allows changes to settings, but does not write them to any backing storage, so the next time you run your application, the memory backend will start out with the default values again.

New in version 2.28.

Gio.network_monitor_get_default()[source]¶

Returns:: a Gio.NetworkMonitor, which will be a dummy object if no network monitor is available
Return type:: Gio.NetworkMonitor

Gets the default Gio.NetworkMonitor for the system.

New in version 2.32.

Gio.networking_init()[source]¶: Initializes the platform networking libraries (eg, on Windows, this calls WSAStartup()). GLib will call this itself if it is needed, so you only need to call it if you directly call system networking functions (without calling any GLib networking functions first).

New in version 2.36.

Gio.null_settings_backend_new()[source]¶

Returns:: a newly created Gio.SettingsBackend
Return type:: Gio.SettingsBackend

Creates a readonly Gio.SettingsBackend.

This backend does not allow changes to settings, so all settings will always have their default values.

New in version 2.28.

Gio.pollable_source_new(pollable_stream)[source]¶

Parameters:: pollable_stream (GObject.Object) – the stream associated with the new source
Returns:: the new GLib.Source.
Return type:: GLib.Source

Utility method for Gio.PollableInputStream and Gio.PollableOutputStream implementations. Creates a new GLib.Source that expects a callback of type Gio.PollableSourceFunc. The new source does not actually do anything on its own; use GLib.Source.add_child_source() to add other sources to it to cause it to trigger.

New in version 2.28.

Gio.pollable_source_new_full(pollable_stream, child_source, cancellable)[source]¶

Parameters:

pollable_stream (GObject.Object) – the stream associated with the new source
child_source (GLib.Source or None) – optional child source to attach
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable to attach

Returns:

the new GLib.Source.

Return type:

GLib.Source

Utility method for Gio.PollableInputStream and Gio.PollableOutputStream implementations. Creates a new GLib.Source, as with Gio.pollable_source_new(), but also attaching child_source (with a dummy callback), and cancellable, if they are non-None.

New in version 2.34.

Gio.pollable_stream_read(stream, buffer, blocking, cancellable)[source]¶

Parameters:

stream (Gio.InputStream) – a Gio.InputStream
buffer (bytes) – a buffer to read data into
blocking (bool) – whether to do blocking I/O
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore.

Raises:

Returns:

the number of bytes read, or -1 on error.

Return type:

Tries to read from stream, as with Gio.InputStream.read() (if blocking is True) or Gio.PollableInputStream.read_nonblocking() (if blocking is False). This can be used to more easily share code between blocking and non-blocking implementations of a method.

If blocking is False, then stream must be a Gio.PollableInputStream for which Gio.PollableInputStream.can_poll() returns True, or else the behavior is undefined. If blocking is True, then stream does not need to be a Gio.PollableInputStream.

New in version 2.34.

Gio.pollable_stream_write(stream, buffer, blocking, cancellable)[source]¶

Parameters:

stream (Gio.OutputStream) – a Gio.OutputStream.
buffer (bytes) – the buffer containing the data to write.
blocking (bool) – whether to do blocking I/O
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore.

Raises:

Returns:

the number of bytes written, or -1 on error.

Return type:

Tries to write to stream, as with Gio.OutputStream.write() (if blocking is True) or Gio.PollableOutputStream.write_nonblocking() (if blocking is False). This can be used to more easily share code between blocking and non-blocking implementations of a method.

If blocking is False, then stream must be a Gio.PollableOutputStream for which Gio.PollableOutputStream.can_poll() returns True or else the behavior is undefined. If blocking is True, then stream does not need to be a Gio.PollableOutputStream.

New in version 2.34.

Gio.pollable_stream_write_all(stream, buffer, blocking, cancellable)[source]¶

Parameters:

stream (Gio.OutputStream) – a Gio.OutputStream.
buffer (bytes) – the buffer containing the data to write.
blocking (bool) – whether to do blocking I/O
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore.

Raises:

Returns:

True on success, False if there was an error

bytes_written:: location to store the number of bytes that was written to the stream

Return type:

(bool, bytes_written: int)

Tries to write count bytes to stream, as with Gio.OutputStream.write_all(), but using Gio.pollable_stream_write() rather than Gio.OutputStream.write().

On a successful write of count bytes, True is returned, and bytes_written is set to count.

If there is an error during the operation (including Gio.IOErrorEnum.WOULD_BLOCK in the non-blocking case), False is returned and error is set to indicate the error status, bytes_written is updated to contain the number of bytes written into the stream before the error occurred.

As with Gio.pollable_stream_write(), if blocking is False, then stream must be a Gio.PollableOutputStream for which Gio.PollableOutputStream.can_poll() returns True or else the behavior is undefined. If blocking is True, then stream does not need to be a Gio.PollableOutputStream.

New in version 2.34.

Gio.power_profile_monitor_dup_default()[source]¶

Returns:: a new reference to the default Gio.PowerProfileMonitor
Return type:: Gio.PowerProfileMonitor

Gets a reference to the default Gio.PowerProfileMonitor for the system.

New in version 2.70.

Gio.proxy_get_default_for_protocol(protocol)[source]¶

Parameters:: protocol (str) – the proxy protocol name (e.g. http, socks, etc)
Returns:: return a Gio.Proxy or None if protocol is not supported.
Return type:: Gio.Proxy or None

Find the gio-proxy extension point for a proxy implementation that supports the specified protocol.

New in version 2.26.

Gio.proxy_resolver_get_default()[source]¶

Returns:: the default Gio.ProxyResolver, which will be a dummy object if no proxy resolver is available
Return type:: Gio.ProxyResolver

Gets the default Gio.ProxyResolver for the system.

New in version 2.26.

Gio.resolver_error_quark()[source]¶

Returns:: a #GQuark.
Return type:: int

Gets the Gio.Resolver Error Quark.

New in version 2.22.

Gio.resource_error_quark()[source]¶

Returns:: a #GQuark
Return type:: int

Gets the Gio.Resource Error Quark.

New in version 2.32.

Gio.resource_load(filename)[source]¶

Parameters:: filename (str) – the path of a filename to load, in the GLib filename encoding
Raises:: GLib.Error
Returns:: a new Gio.Resource, or None on error
Return type:: Gio.Resource

Loads a binary resource bundle and creates a Gio.Resource representation of it, allowing you to query it for data.

If you want to use this resource in the global resource namespace you need to register it with Gio.Resource._register().

If filename is empty or the data in it is corrupt, Gio.ResourceError.INTERNAL will be returned. If filename doesn’t exist, or there is an error in reading it, an error from GLib.MappedFile.new() will be returned.

New in version 2.32.

Gio.resources_enumerate_children(path, lookup_flags)[source]¶

Parameters:

path (str) – A pathname inside the resource
lookup_flags (Gio.ResourceLookupFlags) – A Gio.ResourceLookupFlags

Raises:

Returns:

an array of constant strings

Return type:

[str]

Returns all the names of children at the specified path in the set of globally registered resources. The return result is a None terminated list of strings which should be released with GLib.strfreev().

lookup_flags controls the behaviour of the lookup.

New in version 2.32.

Gio.resources_get_info(path, lookup_flags)[source]¶

Parameters:

path (str) – A pathname inside the resource
lookup_flags (Gio.ResourceLookupFlags) – A Gio.ResourceLookupFlags

Raises:

Returns:

True if the file was found. False if there were errors

size:: a location to place the length of the contents of the file, or None if the length is not needed
flags:: a location to place the Gio.ResourceFlags about the file, or None if the flags are not needed

Return type:

(bool, size: int, flags: int)

Looks for a file at the specified path in the set of globally registered resources and if found returns information about it.

lookup_flags controls the behaviour of the lookup.

New in version 2.32.

Gio.resources_lookup_data(path, lookup_flags)[source]¶

Parameters:

path (str) – A pathname inside the resource
lookup_flags (Gio.ResourceLookupFlags) – A Gio.ResourceLookupFlags

Raises:

Returns:

GLib.Bytes or None on error. Free the returned object with GLib.Bytes.unref()

Return type:

GLib.Bytes

Looks for a file at the specified path in the set of globally registered resources and returns a GLib.Bytes that lets you directly access the data in memory.

The data is always followed by a zero byte, so you can safely use the data as a C string. However, that byte is not included in the size of the GLib.Bytes.

For uncompressed resource files this is a pointer directly into the resource bundle, which is typically in some readonly data section in the program binary. For compressed files we allocate memory on the heap and automatically uncompress the data.

lookup_flags controls the behaviour of the lookup.

New in version 2.32.

Gio.resources_open_stream(path, lookup_flags)[source]¶

Parameters:

path (str) – A pathname inside the resource
lookup_flags (Gio.ResourceLookupFlags) – A Gio.ResourceLookupFlags

Raises:

Returns:

Gio.InputStream or None on error. Free the returned object with GObject.Object.unref()

Return type:

Gio.InputStream

Looks for a file at the specified path in the set of globally registered resources and returns a Gio.InputStream that lets you read the data.

lookup_flags controls the behaviour of the lookup.

New in version 2.32.

Gio.resources_register(resource)[source]¶

Parameters:: resource (Gio.Resource) – A Gio.Resource

Registers the resource with the process-global set of resources. Once a resource is registered the files in it can be accessed with the global resource lookup functions like Gio.resources_lookup_data().

New in version 2.32.

Gio.resources_unregister(resource)[source]¶

Parameters:: resource (Gio.Resource) – A Gio.Resource

Unregisters the resource from the process-global set of resources.

New in version 2.32.

Gio.settings_schema_source_get_default()[source]¶

Returns:: the default schema source
Return type:: Gio.SettingsSchemaSource or None

Gets the default system schema source.

This function is not required for normal uses of Gio.Settings but it may be useful to authors of plugin management systems or to those who want to introspect the content of schemas.

If no schemas are installed, None will be returned.

The returned source may actually consist of multiple schema sources from different directories, depending on which directories were given in XDG_DATA_DIRS and GSETTINGS_SCHEMA_DIR. For this reason, all lookups performed against the default source should probably be done recursively.

New in version 2.32.

Gio.simple_async_report_gerror_in_idle(object, callback, user_data, error)[source]¶

Parameters:

object (GObject.Object or None) – a GObject.Object, or None
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback.
user_data (object or None) – user data passed to callback.
error (GLib.Error) – the GLib.Error to report

Reports an error in an idle function. Similar to g_simple_async_report_error_in_idle(), but takes a GLib.Error rather than building a new one.

Deprecated since version 2.46: Use Gio.Task.report_error().

Gio.tls_backend_get_default()[source]¶

Returns:: a Gio.TlsBackend, which will be a dummy object if no TLS backend is available
Return type:: Gio.TlsBackend

Gets the default Gio.TlsBackend for the system.

New in version 2.28.

Gio.tls_channel_binding_error_quark()[source]¶

Returns:: a #GQuark.
Return type:: int

Gets the TLS channel binding error quark.

New in version 2.66.

Gio.tls_client_connection_new(base_io_stream, server_identity)[source]¶

Parameters:

base_io_stream (Gio.IOStream) – the Gio.IOStream to wrap
server_identity (Gio.SocketConnectable or None) – the expected identity of the server

Raises:

Gio.TlsClientConnection

Returns:

the new Gio.TlsClientConnection, or None on error

Return type:

Creates a new Gio.TlsClientConnection wrapping base_io_stream (which must have pollable input and output streams) which is assumed to communicate with the server identified by server_identity.

See the documentation for Gio.TlsConnection :base-io-stream for restrictions on when application code can run operations on the base_io_stream after this function has returned.

New in version 2.28.

Gio.tls_error_quark()[source]¶

Returns:: a #GQuark.
Return type:: int

Gets the TLS error quark.

New in version 2.28.

Gio.tls_file_database_new(anchors)[source]¶

Parameters:: anchors (str) – filename of anchor certificate authorities.
Raises:: GLib.Error
Returns:: the new Gio.TlsFileDatabase, or None on error
Return type:: Gio.TlsFileDatabase

Creates a new Gio.TlsFileDatabase which uses anchor certificate authorities in anchors to verify certificate chains.

The certificates in anchors must be PEM encoded.

New in version 2.30.

Gio.tls_server_connection_new(base_io_stream, certificate)[source]¶

Parameters:

base_io_stream (Gio.IOStream) – the Gio.IOStream to wrap
certificate (Gio.TlsCertificate or None) – the default server certificate, or None

Raises:

Gio.TlsServerConnection

Returns:

the new Gio.TlsServerConnection, or None on error

Return type:

Creates a new Gio.TlsServerConnection wrapping base_io_stream (which must have pollable input and output streams).

See the documentation for Gio.TlsConnection :base-io-stream for restrictions on when application code can run operations on the base_io_stream after this function has returned.

New in version 2.28.

Gio.unix_is_mount_path_system_internal(mount_path)[source]¶

Parameters:: mount_path (str) – a mount path, e.g. /media/disk or /usr
Returns:: True if mount_path is considered an implementation detail of the OS.
Return type:: bool

Determines if mount_path is considered an implementation of the OS. This is primarily used for hiding mountable and mounted volumes that only are used in the OS and has little to no relevance to the casual user.

Gio.unix_is_system_device_path(device_path)[source]¶

Parameters:: device_path (str) – a device path, e.g. /dev/loop0 or nfsd
Returns:: True if device_path is considered an implementation detail of the OS.
Return type:: bool

Determines if device_path is considered a block device path which is only used in implementation of the OS. This is primarily used for hiding mounted volumes that are intended as APIs for programs to read, and system administrators at a shell; rather than something that should, for example, appear in a GUI. For example, the Linux /proc filesystem.

The list of device paths considered ‘system’ ones may change over time.

New in version 2.56.

Gio.unix_is_system_fs_type(fs_type)[source]¶

Parameters:: fs_type (str) – a file system type, e.g. procfs or tmpfs
Returns:: True if fs_type is considered an implementation detail of the OS.
Return type:: bool

Determines if fs_type is considered a type of file system which is only used in implementation of the OS. This is primarily used for hiding mounted volumes that are intended as APIs for programs to read, and system administrators at a shell; rather than something that should, for example, appear in a GUI. For example, the Linux /proc filesystem.

The list of file system types considered ‘system’ ones may change over time.

New in version 2.56.

Gio.unix_mount_at(mount_path)[source]¶

Parameters:

mount_path (str) – path for a possible unix mount.

Returns:

a Gio.UnixMountEntry.

time_read:: guint64 to contain a timestamp.

Return type:

(Gio.UnixMountEntry or None, time_read: int)

Gets a Gio.UnixMountEntry for a given mount path. If time_read is set, it will be filled with a unix timestamp for checking if the mounts have changed since with Gio.unix_mounts_changed_since().

If more mounts have the same mount path, the last matching mount is returned.

This will return None if there is no mount point at mount_path.

Gio.unix_mount_compare(mount1, mount2)[source]¶

Parameters:

mount1 (Gio.UnixMountEntry) – first Gio.UnixMountEntry to compare.
mount2 (Gio.UnixMountEntry) – second Gio.UnixMountEntry to compare.

Returns:

1, 0 or -1 if mount1 is greater than, equal to, or less than mount2, respectively.

Return type: