Functions

  action_name_is_valid (action_name)
  action_parse_detailed_name (detailed_name)
  action_print_detailed_name (action_name, target_value)
  app_info_create_from_commandline (commandline, application_name, flags)
  app_info_get_all ()
  app_info_get_all_for_type (content_type)
  app_info_get_default_for_type (content_type, must_support_uris)
  app_info_get_default_for_uri_scheme (uri_scheme)
  app_info_get_fallback_for_type (content_type)
  app_info_get_recommended_for_type (content_type)
  app_info_launch_default_for_uri (uri, context)
  app_info_launch_default_for_uri_async (uri, context, cancellable, callback, *user_data)
  app_info_launch_default_for_uri_finish (result)
  app_info_reset_type_associations (content_type)
  async_initable_newv_async (object_type, n_parameters, parameters, io_priority, cancellable, callback, *user_data)
  bus_get (bus_type, cancellable, callback, *user_data)
  bus_get_finish (res)
  bus_get_sync (bus_type, cancellable)
  bus_own_name (bus_type, name, flags, bus_acquired_closure, name_acquired_closure, name_lost_closure)
  bus_own_name_on_connection (connection, name, flags, name_acquired_closure, name_lost_closure)
  bus_unown_name (owner_id)
  bus_unwatch_name (watcher_id)
  bus_watch_name (bus_type, name, flags, name_appeared_closure, name_vanished_closure)
  bus_watch_name_on_connection (connection, name, flags, name_appeared_closure, name_vanished_closure)
  content_type_can_be_executable (type)
  content_type_equals (type1, type2)
  content_type_from_mime_type (mime_type)
  content_type_get_description (type)
  content_type_get_generic_icon_name (type)
  content_type_get_icon (type)
  content_type_get_mime_dirs ()
  content_type_get_mime_type (type)
  content_type_get_symbolic_icon (type)
  content_type_guess (filename, data)
  content_type_guess_for_tree (root)
  content_type_is_a (type, supertype)
  content_type_is_mime_type (type, mime_type)
  content_type_is_unknown (type)
  content_type_set_mime_dirs (dirs)
  content_types_get_registered ()
  dbus_address_escape_value (string)
  dbus_address_get_for_bus_sync (bus_type, cancellable)
  dbus_address_get_stream (address, cancellable, callback, *user_data)
  dbus_address_get_stream_finish (res)
  dbus_address_get_stream_sync (address, cancellable)
  dbus_annotation_info_lookup (annotations, name)
  dbus_error_encode_gerror (error)
  dbus_error_get_remote_error (error)
  dbus_error_is_remote_error (error)
  dbus_error_new_for_dbus_error (dbus_error_name, dbus_error_message)
  dbus_error_quark ()
  dbus_error_register_error (error_domain, error_code, dbus_error_name)
  dbus_error_register_error_domain (error_domain_quark_name, quark_volatile, entries)
  dbus_error_strip_remote_error (error)
  dbus_error_unregister_error (error_domain, error_code, dbus_error_name)
  dbus_generate_guid ()
  dbus_gvalue_to_gvariant (gvalue, type)
  dbus_gvariant_to_gvalue (value)
  dbus_is_address (string)
  dbus_is_guid (string)
  dbus_is_interface_name (string)
  dbus_is_member_name (string)
  dbus_is_name (string)
  dbus_is_supported_address (string)
  dbus_is_unique_name (string)
  dtls_client_connection_new (base_socket, server_identity)
  dtls_server_connection_new (base_socket, certificate)
  file_new_for_commandline_arg (arg)
  file_new_for_commandline_arg_and_cwd (arg, cwd)
  file_new_for_path (path)
  file_new_for_uri (uri)
  file_new_tmp (tmpl)
  file_parse_name (parse_name)
  icon_deserialize (value)
  icon_hash (icon)
  icon_new_for_string (str)
  initable_newv (object_type, parameters, cancellable)
  io_error_from_errno (err_no)
  io_error_quark ()
  io_extension_point_implement (extension_point_name, type, extension_name, priority)
  io_extension_point_lookup (name)
  io_extension_point_register (name)
  io_modules_load_all_in_directory (dirname)
  io_modules_load_all_in_directory_with_scope (dirname, scope)
  io_modules_scan_all_in_directory (dirname)
  io_modules_scan_all_in_directory_with_scope (dirname, scope)
  io_scheduler_cancel_all_jobs ()
  io_scheduler_push_job (job_func, user_data, io_priority, cancellable)
  keyfile_settings_backend_new (filename, root_path, root_group)
  memory_monitor_dup_default ()
  memory_settings_backend_new ()
  network_monitor_get_default ()
  networking_init ()
  null_settings_backend_new ()
  pollable_source_new (pollable_stream)
  pollable_source_new_full (pollable_stream, child_source, cancellable)
  pollable_stream_read (stream, buffer, blocking, cancellable)
  pollable_stream_write (stream, buffer, blocking, cancellable)
  pollable_stream_write_all (stream, buffer, blocking, cancellable)
  proxy_get_default_for_protocol (protocol)
  proxy_resolver_get_default ()
  resolver_error_quark ()
  resource_error_quark ()
  resource_load (filename)
  resources_enumerate_children (path, lookup_flags)
  resources_get_info (path, lookup_flags)
  resources_lookup_data (path, lookup_flags)
  resources_open_stream (path, lookup_flags)
  resources_register (resource)
  resources_unregister (resource)
  settings_schema_source_get_default ()
  simple_async_report_gerror_in_idle (object, callback, user_data, error)
  tls_backend_get_default ()
  tls_channel_binding_error_quark ()
  tls_client_connection_new (base_io_stream, server_identity)
  tls_error_quark ()
  tls_file_database_new (anchors)
  tls_server_connection_new (base_io_stream, certificate)
  unix_is_mount_path_system_internal (mount_path)
  unix_is_system_device_path (device_path)
  unix_is_system_fs_type (fs_type)
  unix_mount_at (mount_path)
  unix_mount_compare (mount1, mount2)
  unix_mount_copy (mount_entry)
  unix_mount_for (file_path)
  unix_mount_free (mount_entry)
  unix_mount_get_device_path (mount_entry)
  unix_mount_get_fs_type (mount_entry)
  unix_mount_get_mount_path (mount_entry)
  unix_mount_get_options (mount_entry)
  unix_mount_get_root_path (mount_entry)
  unix_mount_guess_can_eject (mount_entry)
  unix_mount_guess_icon (mount_entry)
  unix_mount_guess_name (mount_entry)
  unix_mount_guess_should_display (mount_entry)
  unix_mount_guess_symbolic_icon (mount_entry)
  unix_mount_is_readonly (mount_entry)
  unix_mount_is_system_internal (mount_entry)
  unix_mount_point_at (mount_path)
  unix_mount_points_changed_since (time)
  unix_mount_points_get ()
  unix_mounts_changed_since (time)
  unix_mounts_get ()

Details

Gio.action_name_is_valid(action_name)[source]
Parameters:action_name (str) – a potential action name
Returns:True if action_name is valid
Return type:bool

Checks if action_name is valid.

action_name is valid if it consists only of alphanumeric characters, plus ‘-’ and ‘.’. The empty string is not a valid action name.

It is an error to call this function with a non-utf8 action_name. action_name must not be None.

New in version 2.38.

Gio.action_parse_detailed_name(detailed_name)[source]
Parameters:detailed_name (str) – a detailed action name
Raises:GLib.Error
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)

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

New in version 2.38.

Gio.action_print_detailed_name(action_name, target_value)[source]
Parameters:
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:
Raises:

GLib.Error
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:
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_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_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.

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

GLib.Error
Returns:

True on success, False on error.
Return type:

bool

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:

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:

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:

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

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

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

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

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

int

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

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

int

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

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

int

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

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

int

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:

bool

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

bool

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:

bool

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

GLib.Error
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:

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:GLib.Error
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)

Finishes an operation started with Gio.dbus_address_get_stream().

New in version 2.26.

Gio.dbus_address_get_stream_sync(address, cancellable)[source]
Parameters:
Raises:

GLib.Error
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)

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.

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

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

str

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

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:

GLib.Error

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:

bool

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.

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:

bool

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

New in version 2.26.

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 GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).

New in version 2.26.

Gio.dbus_gvalue_to_gvariant(gvalue, type)[source]
Parameters:
Returns:

A GLib.Variant (never floating) of GLib.VariantType type holding the data from gvalue or None 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:

This can fail if e.g. gvalue is of type GObject.TYPE_STRING and type is ‘’i’ [G-VARIANT-TYPE-INT32:CAPS]’. 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_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 D-Bus specification regarding what strings are valid D-Bus GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).

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.dtls_client_connection_new(base_socket, server_identity)[source]
Parameters:
Raises:

GLib.Error
Returns:

the new Gio.DtlsClientConnection, or None on error
Return type:

Gio.DtlsClientConnection

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

GLib.Error
Returns:

the new Gio.DtlsServerConnection, or None on error
Return type:

Gio.DtlsServerConnection

Creates a new Gio.DtlsServerConnection wrapping base_socket.

New in version 2.48.

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.

See also Gio.ApplicationCommandLine.create_file_for_arg().

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:GLib.Error
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_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

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

New in version 2.38.

Gio.icon_hash(icon)[source]
Parameters:icon (object) – #gconstpointer to an icon object.
Returns:a int containing a hash for the icon, suitable for use in a GLib.HashTable or similar data structure.
Return type:int

Gets a hash for an icon.

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

GLib.Error
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 as soon as the call which sets it

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

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 ???: 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
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:
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:
Raises:

GLib.Error
Returns:

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

int

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

GLib.Error
Returns:

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

int

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

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

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

GLib.Error
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:
Raises:

GLib.Error
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:
Raises:

GLib.Error
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:
Raises:

GLib.Error
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:

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

GLib.Error
Returns:

the new Gio.TlsClientConnection, or None on error
Return type:

Gio.TlsClientConnection

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

GLib.Error
Returns:

the new Gio.TlsServerConnection, or None on error
Return type:

Gio.TlsServerConnection

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

Gio.unix_mount_compare(mount1, mount2)[source]
Parameters:
Returns:

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

int

Compares two unix mounts.

Gio.unix_mount_copy(mount_entry)[source]
Parameters:mount_entry (Gio.UnixMountEntry) – a Gio.UnixMountEntry.
Returns:a new Gio.UnixMountEntry
Return type:Gio.UnixMountEntry

Makes a copy of mount_entry.

New in version 2.54.

Gio.unix_mount_for(file_path)[source]
Parameters:file_path (str) – file path on some unix mount.
Returns:a Gio.UnixMountEntry.
time_read:guint64 to contain a timestamp.
Return type:(Gio.UnixMountEntry, time_read: int)

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

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

New in version 2.52.

Gio.unix_mount_free(mount_entry)[source]
Parameters:mount_entry (Gio.UnixMountEntry) – a Gio.UnixMountEntry.

Frees a unix mount.

Gio.unix_mount_get_device_path(mount_entry)[source]
Parameters:mount_entry (Gio.UnixMountEntry) – a #GUnixMount.
Returns:a string containing the device path.
Return type:str

Gets the device path for a unix mount.

Gio.unix_mount_get_fs_type(mount_entry)[source]
Parameters:mount_entry (Gio.UnixMountEntry) – a #GUnixMount.
Returns:a string containing the file system type.
Return type:str

Gets the filesystem type for the unix mount.

Gio.unix_mount_get_mount_path(mount_entry)[source]
Parameters:mount_entry (Gio.UnixMountEntry) – input Gio.UnixMountEntry to get the mount path for.
Returns:the mount path for mount_entry.
Return type:str

Gets the mount path for a unix mount.

Gio.unix_mount_get_options(mount_entry)[source]
Parameters:mount_entry (Gio.UnixMountEntry) – a Gio.UnixMountEntry.
Returns:a string containing the options, or None if not available.
Return type:str or None

Gets a comma-separated list of mount options for the unix mount. For example, rw,relatime,seclabel,data=ordered.

This is similar to Gio.UnixMountPoint.get_options(), but it takes a Gio.UnixMountEntry as an argument.

New in version 2.58.

Gio.unix_mount_get_root_path(mount_entry)[source]
Parameters:mount_entry (Gio.UnixMountEntry) – a Gio.UnixMountEntry.
Returns:a string containing the root, or None if not supported.
Return type:str or None

Gets the root of the mount within the filesystem. This is useful e.g. for mounts created by bind operation, or btrfs subvolumes.

For example, the root path is equal to “/” for mount created by “mount /dev/sda1 /mnt/foo” and “/bar” for “mount –bind /mnt/foo/bar /mnt/bar”.

New in version 2.60.

Gio.unix_mount_guess_can_eject(mount_entry)[source]
Parameters:mount_entry (Gio.UnixMountEntry) – a Gio.UnixMountEntry
Returns:True if mount_entry is deemed to be ejectable.
Return type:bool

Guesses whether a Unix mount can be ejected.

Gio.unix_mount_guess_icon(mount_entry)[source]
Parameters:mount_entry (Gio.UnixMountEntry) – a Gio.UnixMountEntry
Returns:a Gio.Icon
Return type:Gio.Icon

Guesses the icon of a Unix mount.

Gio.unix_mount_guess_name(mount_entry)[source]
Parameters:mount_entry (Gio.UnixMountEntry) – a Gio.UnixMountEntry
Returns:A newly allocated string that must be freed with GLib.free()
Return type:str

Guesses the name of a Unix mount. The result is a translated string.

Gio.unix_mount_guess_should_display(mount_entry)[source]
Parameters:mount_entry (Gio.UnixMountEntry) – a Gio.UnixMountEntry
Returns:True if mount_entry is deemed to be displayable.
Return type:bool

Guesses whether a Unix mount should be displayed in the UI.

Gio.unix_mount_guess_symbolic_icon(mount_entry)[source]
Parameters:mount_entry (Gio.UnixMountEntry) – a Gio.UnixMountEntry
Returns:a Gio.Icon
Return type:Gio.Icon

Guesses the symbolic icon of a Unix mount.

New in version 2.34.

Gio.unix_mount_is_readonly(mount_entry)[source]
Parameters:mount_entry (Gio.UnixMountEntry) – a #GUnixMount.
Returns:True if mount_entry is read only.
Return type:bool

Checks if a unix mount is mounted read only.

Gio.unix_mount_is_system_internal(mount_entry)[source]
Parameters:mount_entry (Gio.UnixMountEntry) – a #GUnixMount.
Returns:True if the unix mount is for a system path.
Return type:bool

Checks if a Unix mount is a system mount. This is the Boolean OR of Gio.unix_is_system_fs_type(), Gio.unix_is_system_device_path() and Gio.unix_is_mount_path_system_internal() on mount_entry’s properties.

The definition of what a ‘system’ mount entry is may change over time as new file system types and device paths are ignored.

Gio.unix_mount_point_at(mount_path)[source]
Parameters:mount_path (str) – path for a possible unix mount point.
Returns:a Gio.UnixMountPoint, or None if no match is found.
time_read:guint64 to contain a timestamp.
Return type:(Gio.UnixMountPoint or None, time_read: int)

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

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

New in version 2.66.

Gio.unix_mount_points_changed_since(time)[source]
Parameters:time (int) – guint64 to contain a timestamp.
Returns:True if the mount points have changed since time.
Return type:bool

Checks if the unix mount points have changed since a given unix time.

Gio.unix_mount_points_get()[source]
Returns:a GLib.List of the UNIX mountpoints.
time_read:guint64 to contain a timestamp.
Return type:([Gio.UnixMountPoint], time_read: int)

Gets a GLib.List of Gio.UnixMountPoint containing the unix mount points. If time_read is set, it will be filled with the mount timestamp, allowing for checking if the mounts have changed with Gio.unix_mount_points_changed_since().

Gio.unix_mounts_changed_since(time)[source]
Parameters:time (int) – guint64 to contain a timestamp.
Returns:True if the mounts have changed since time.
Return type:bool

Checks if the unix mounts have changed since a given unix time.

Gio.unix_mounts_get()[source]
Returns:a GLib.List of the UNIX mounts.
time_read:guint64 to contain a timestamp, or None
Return type:([Gio.UnixMountEntry], time_read: int)

Gets a GLib.List of Gio.UnixMountEntry containing the unix mounts. If time_read is set, it will be filled with the mount timestamp, allowing for checking if the mounts have changed with Gio.unix_mounts_changed_since().