Functions#

action_name_is_valid(action_name: str) → bool#
Parameters:

action_name

action_parse_detailed_name(detailed_name: str) → tuple[bool, str, Variant | None]#
Parameters:

detailed_name

action_print_detailed_name(action_name: str, target_value: Variant | None = None) → str#
Parameters:

  • action_name

  • target_value

app_info_create_from_commandline(commandline: str, application_name: str | None, flags: AppInfoCreateFlags) → AppInfo#
Parameters:

  • commandline

  • application_name

  • flags

app_info_get_all() → list[AppInfo]#
app_info_get_all_for_type(content_type: str) → list[AppInfo]#
Parameters:

content_type

app_info_get_default_for_type(content_type: str, must_support_uris: bool) → AppInfo | None#
Parameters:

  • content_type

  • must_support_uris

app_info_get_default_for_type_async(content_type: str, must_support_uris: bool, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None#
Parameters:

  • content_type

  • must_support_uris

  • cancellable

  • callback

  • user_data

app_info_get_default_for_type_finish(result: AsyncResult) → AppInfo#
Parameters:

result

app_info_get_default_for_uri_scheme(uri_scheme: str) → AppInfo | None#
Parameters:

uri_scheme

app_info_get_default_for_uri_scheme_async(uri_scheme: str, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None#
Parameters:

  • uri_scheme

  • cancellable

  • callback

  • user_data

app_info_get_default_for_uri_scheme_finish(result: AsyncResult) → AppInfo#
Parameters:

result

app_info_get_fallback_for_type(content_type: str) → list[AppInfo]#
Parameters:

content_type

Parameters:

content_type

app_info_launch_default_for_uri(uri: str, context: AppLaunchContext | None = None) → bool#
Parameters:

  • uri

  • context

app_info_launch_default_for_uri_async(uri: str, context: AppLaunchContext | None = None, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None#
Parameters:

  • uri

  • context

  • cancellable

  • callback

  • user_data

app_info_launch_default_for_uri_finish(result: AsyncResult) → bool#
Parameters:

result

app_info_reset_type_associations(content_type: str) → None#
Parameters:

content_type

async_initable_newv_async(object_type: GType, n_parameters: int, parameters: Parameter, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None#
Parameters:

  • object_type

  • n_parameters

  • parameters

  • io_priority

  • cancellable

  • callback

  • user_data

bus_get(bus_type: BusType, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None#

Asynchronously connects to the message bus specified by bus_type.

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

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

Added in version 2.26.

Parameters:

  • bus_type – a BusType

  • cancellable – a Cancellable or None

  • callback – a AsyncReadyCallback to call when the request is satisfied

  • user_data – the data to pass to callback

bus_get_finish(res: AsyncResult) → DBusConnection#

Finishes an operation started with bus_get().

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

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

Added in version 2.26.

Parameters:

res – a AsyncResult obtained from the AsyncReadyCallback passed to bus_get()

Returns:

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

bus_get_sync(bus_type: BusType, cancellable: Cancellable | None = None) → 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 bus_get() and bus_get_finish() for the asynchronous version.

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

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

Added in version 2.26.

Parameters:
Returns:

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

bus_own_name(bus_type: BusType, name: str, flags: BusNameOwnerFlags, bus_acquired_closure: Closure | None = None, name_acquired_closure: Closure | None = None, name_lost_closure: Closure | None = None) → int#

Starts acquiring name on the bus specified by bus_type and calls name_acquired_handler and name_lost_handler when the name is acquired respectively lost. Callbacks will be invoked in the [thread-default main context][g-main-context-push-thread-default] of the thread you are calling this function from.

You are guaranteed that one of the name_acquired_handler and name_lost_handler callbacks will be invoked after calling this function - there are three possible cases:

  • name_lost_handler with a None connection (if a connection to the bus can’t be made).

  • bus_acquired_handler then name_lost_handler (if the name can’t be obtained)

  • bus_acquired_handler then name_acquired_handler (if the name was obtained).

When you are done owning the name, just call bus_unown_name() with the owner id this function returns.

If the name is acquired or lost (for example another application could acquire the name if you allow replacement or the application currently owning the name exits), the handlers are also invoked. If the DBusConnection that is used for attempting to own the name closes, then name_lost_handler is invoked since it is no longer possible for other processes to access the process.

You cannot use bus_own_name() several times for the same name (unless interleaved with calls to bus_unown_name()) - only the first call will work.

Another guarantee is that invocations of name_acquired_handler and name_lost_handler are guaranteed to alternate; that is, if name_acquired_handler is invoked then you are guaranteed that the next time one of the handlers is invoked, it will be name_lost_handler. The reverse is also true.

If you plan on exporting objects (using e.g. register_object()), note that it is generally too late to export the objects in name_acquired_handler. Instead, you can do this in bus_acquired_handler since you are guaranteed that this will run before name is requested from the bus.

This behavior makes it very simple to write applications that wants to [own names][gdbus-owning-names] and export objects. Simply register objects to be exported in bus_acquired_handler and unregister the objects (if any) in name_lost_handler.

Added in version 2.26.

Parameters:

  • bus_type – the type of bus to own a name on

  • name – the well-known name to own

  • flags – a set of flags from the BusNameOwnerFlags enumeration

  • bus_acquired_closure

  • name_acquired_closure

  • name_lost_closure

Returns:

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

bus_own_name_on_connection(connection: DBusConnection, name: str, flags: BusNameOwnerFlags, name_acquired_closure: Closure | None = None, name_lost_closure: Closure | None = None) → int#

Like bus_own_name() but takes a DBusConnection instead of a BusType.

Added in version 2.26.

Parameters:

  • connection – a DBusConnection

  • name – the well-known name to own

  • flags – a set of flags from the BusNameOwnerFlags enumeration

  • name_acquired_closure

  • name_lost_closure

Returns:

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

bus_unown_name(owner_id: int) → None#

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 MainContext after this function has returned. You should continue to iterate the MainContext until the DestroyNotify function passed to bus_own_name() is called, in order to avoid memory leaks through callbacks queued on the MainContext after it’s stopped being iterated.

Added in version 2.26.

Parameters:

owner_id – an identifier obtained from bus_own_name()

bus_unwatch_name(watcher_id: int) → None#

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 MainContext after this function has returned. You should continue to iterate the MainContext until the DestroyNotify function passed to bus_watch_name() is called, in order to avoid memory leaks through callbacks queued on the MainContext after it’s stopped being iterated.

Added in version 2.26.

Parameters:

watcher_id – An identifier obtained from bus_watch_name()

bus_watch_name(bus_type: BusType, name: str, flags: BusNameWatcherFlags, name_appeared_closure: Closure | None = None, name_vanished_closure: Closure | None = None) → int#

Starts watching name on the bus specified by bus_type and calls name_appeared_handler and name_vanished_handler when the name is known to have an owner respectively known to lose its owner. Callbacks will be invoked in the [thread-default main context][g-main-context-push-thread-default] of the thread you are calling this function from.

You are guaranteed that one of the handlers will be invoked after calling this function. When you are done watching the name, just call bus_unwatch_name() with the watcher id this function returns.

If the name vanishes or appears (for example the application owning the name could restart), the handlers are also invoked. If the DBusConnection that is used for watching the name disconnects, then name_vanished_handler is invoked since it is no longer possible to access the name.

Another guarantee is that invocations of name_appeared_handler and name_vanished_handler are guaranteed to alternate; that is, if name_appeared_handler is invoked then you are guaranteed that the next time one of the handlers is invoked, it will be name_vanished_handler. The reverse is also true.

This behavior makes it very simple to write applications that want to take action when a certain [name exists][gdbus-watching-names]. Basically, the application should create object proxies in name_appeared_handler and destroy them again (if any) in name_vanished_handler.

Added in version 2.26.

Parameters:

  • bus_type – The type of bus to watch a name on.

  • name – The name (well-known or unique) to watch.

  • flags – Flags from the BusNameWatcherFlags enumeration.

  • name_appeared_closure

  • name_vanished_closure

Returns:

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

bus_watch_name_on_connection(connection: DBusConnection, name: str, flags: BusNameWatcherFlags, name_appeared_closure: Closure | None = None, name_vanished_closure: Closure | None = None) → int#

Like bus_watch_name() but takes a DBusConnection instead of a BusType.

Added in version 2.26.

Parameters:

  • connection – A DBusConnection.

  • name – The name (well-known or unique) to watch.

  • flags – Flags from the BusNameWatcherFlags enumeration.

  • name_appeared_closure

  • name_vanished_closure

Returns:

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

content_type_can_be_executable(type: str) → 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).

Parameters:

type – a content type string

Returns:

True if the file type corresponds to a type that can be executable, False otherwise.

content_type_equals(type1: str, type2: str) → bool#

Compares two content types for equality.

Parameters:

  • type1 – a content type string

  • type2 – a content type string

Returns:

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

content_type_from_mime_type(mime_type: str) → str | None#

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

Added in version 2.18.

Parameters:

mime_type – a mime type string

Returns:

Newly allocated string with content type or None. Free with free()

content_type_get_description(type: str) → str#

Gets the human readable description of the content type.

Parameters:

type – a content type string

Returns:

a short description of the content type type. Free the returned string with free()

content_type_get_generic_icon_name(type: str) → str | None#

Gets the generic icon name for a content type.

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

Added in version 2.34.

Parameters:

type – a content type string

Returns:

the registered generic icon name for the given type, or None if unknown. Free with free()

content_type_get_icon(type: str) → Icon#

Gets the icon for a content type.

Parameters:

type – a content type string

Returns:

Icon corresponding to the content type. Free the returned object with unref()

content_type_get_mime_dirs() → list[str]#

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

Added in version 2.60.

Returns:

None-terminated list of directories to load MIME data from, including any mime/ subdirectory, and with the first directory to try listed first

content_type_get_mime_type(type: str) → str | None#

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

Parameters:

type – a content type string

Returns:

the registered mime type for the given type, or None if unknown; free with free().

content_type_get_symbolic_icon(type: str) → Icon#

Gets the symbolic icon for a content type.

Added in version 2.34.

Parameters:

type – a content type string

Returns:

symbolic Icon corresponding to the content type. Free the returned object with unref()

content_type_guess(filename: str | None = None, data: list[int] | None = None) → tuple[str, 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.

Parameters:

  • filename – a path, or None

  • data – a stream of data, or None

Returns:

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

content_type_guess_for_tree(root: File) → list[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 guess_content_type().

Added in version 2.18.

Parameters:

root – the root of the tree to guess a type for

Returns:

an None-terminated array of zero or more content types. Free with strfreev()

content_type_is_a(type: str, supertype: str) → bool#

Determines if type is a subset of supertype.

Parameters:

  • type – a content type string

  • supertype – a content type string

Returns:

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

content_type_is_mime_type(type: str, mime_type: str) → bool#

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

Added in version 2.52.

Parameters:

  • type – a content type string

  • mime_type – a mime type string

Returns:

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

content_type_is_unknown(type: str) → 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.

Parameters:

type – a content type string

Returns:

True if the type is the unknown type.

content_type_set_mime_dirs(dirs: list[str] | None = None) → None#

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 %G_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 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 ();

Added in version 2.60.

Parameters:

dirs – None-terminated list of directories to load MIME data from, including any mime/ subdirectory, and with the first directory to try listed first

content_types_get_registered() → list[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).

Returns:

list of the registered content types

dbus_address_escape_value(string: str) → 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.

Added in version 2.36.

Parameters:

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

dbus_address_get_for_bus_sync(bus_type: BusType, cancellable: Cancellable | None = None) → 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.

Added in version 2.26.

Parameters:
Returns:

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

dbus_address_get_stream(address: str, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None#

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 dbus_address_get_stream_finish() to get the result of the operation.

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

Added in version 2.26.

Parameters:

  • address – A valid D-Bus address.

  • cancellable – A Cancellable or None.

  • callback – A AsyncReadyCallback to call when the request is satisfied.

  • user_data – Data to pass to callback.

dbus_address_get_stream_finish(res: AsyncResult) → tuple[IOStream, str | None]#

Finishes an operation started with dbus_address_get_stream().

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

Added in version 2.26.

Parameters:

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

Returns:

A IOStream or None if error is set.

dbus_address_get_stream_sync(address: str, cancellable: Cancellable | None = None) → tuple[IOStream, str | 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 dbus_address_get_stream() for the asynchronous version.

Added in version 2.26.

Parameters:

  • address – A valid D-Bus address.

  • cancellable – A Cancellable or None.

Returns:

A IOStream or None if error is set.

dbus_annotation_info_lookup(annotations: list[DBusAnnotationInfo] | None, name: str) → str | None#
Parameters:

  • annotations

  • name

dbus_error_encode_gerror(error: GError) → str#
Parameters:

error

dbus_error_get_remote_error(error: GError) → str | None#
Parameters:

error

dbus_error_is_remote_error(error: GError) → bool#
Parameters:

error

dbus_error_new_for_dbus_error(dbus_error_name: str, dbus_error_message: str) → GError#
Parameters:

  • dbus_error_name

  • dbus_error_message

dbus_error_quark() → int#
dbus_error_register_error(error_domain: int, error_code: int, dbus_error_name: str) → bool#
Parameters:

  • error_domain

  • error_code

  • dbus_error_name

dbus_error_register_error_domain(error_domain_quark_name: str, quark_volatile: int, entries: list[DBusErrorEntry]) → None#
Parameters:

  • error_domain_quark_name

  • quark_volatile

  • entries

dbus_error_strip_remote_error(error: GError) → bool#
Parameters:

error

dbus_error_unregister_error(error_domain: int, error_code: int, dbus_error_name: str) → bool#
Parameters:

  • error_domain

  • error_code

  • dbus_error_name

dbus_escape_object_path(s: str) → str#

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

Added in version 2.68.

Parameters:

s – the string to escape

Returns:

an escaped version of s. Free with free().

dbus_escape_object_path_bytestring(bytes: list[int]) → 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 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 dbus_unescape_object_path().

Added in version 2.68.

Parameters:

bytes – the string of bytes to escape

Returns:

an escaped version of bytes. Free with free().

dbus_generate_guid() → str#

Generate a D-Bus GUID that can be used with e.g. 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.

Added in version 2.26.

Returns:

A valid D-Bus GUID. Free with free().

dbus_gvalue_to_gvariant(gvalue: Value, type: VariantType) → Variant#

Converts a Value to a 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 VariantType

This can fail if e.g. gvalue is of type str and type is ‘i’, i.e. %G_VARIANT_TYPE_INT32. It will also fail for any Type (including e.g. object and Boxed derived-types) not in the table above.

Note that if gvalue is of type %G_TYPE_VARIANT and its value is None, the empty 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 dbus_gvariant_to_gvalue() function for how to convert a Variant to a Value.

Added in version 2.30.

Parameters:
Returns:

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

dbus_gvariant_to_gvalue(value: Variant) → Value#

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

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

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

Added in version 2.30.

Parameters:

value – A Variant.

dbus_is_address(string: str) → bool#

Checks if string is a D-Bus address.

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

Added in version 2.26.

Parameters:

string – A string.

Returns:

True if string is a valid D-Bus address, False otherwise.

dbus_is_error_name(string: str) → bool#

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

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

Added in version 2.70.

Parameters:

string – The string to check.

Returns:

True if valid, False otherwise.

dbus_is_guid(string: str) → bool#

Checks if string is a D-Bus GUID.

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

Added in version 2.26.

Parameters:

string – The string to check.

Returns:

True if string is a GUID, False otherwise.

dbus_is_interface_name(string: str) → bool#

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

Added in version 2.26.

Parameters:

string – The string to check.

Returns:

True if valid, False otherwise.

dbus_is_member_name(string: str) → bool#

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

Added in version 2.26.

Parameters:

string – The string to check.

Returns:

True if valid, False otherwise.

dbus_is_name(string: str) → bool#

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

Added in version 2.26.

Parameters:

string – The string to check.

Returns:

True if valid, False otherwise.

dbus_is_supported_address(string: str) → bool#

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

Added in version 2.26.

Parameters:

string – A string.

Returns:

True if string is a valid D-Bus address that is supported by this library, False if error is set.

dbus_is_unique_name(string: str) → bool#

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

Added in version 2.26.

Parameters:

string – The string to check.

Returns:

True if valid, False otherwise.

dbus_unescape_object_path(s: str) → list[int] | None#

Unescapes an string that was previously escaped with dbus_escape_object_path(). If the string is in a format that could not have been returned by 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).

Added in version 2.68.

Parameters:

s – the string to unescape

Returns:

an unescaped version of s, or None if s is not a string returned from dbus_escape_object_path(). Free with free().

dtls_client_connection_new(base_socket: DatagramBased, server_identity: SocketConnectable | None = None) → DtlsClientConnection#
Parameters:

  • base_socket

  • server_identity

dtls_server_connection_new(base_socket: DatagramBased, certificate: TlsCertificate | None = None) → DtlsServerConnection#
Parameters:

  • base_socket

  • certificate

file_new_build_filenamev(args: list[str]) → File#
Parameters:

args

file_new_for_commandline_arg(arg: str) → File#
Parameters:

arg

file_new_for_commandline_arg_and_cwd(arg: str, cwd: str) → File#
Parameters:

  • arg

  • cwd

file_new_for_path(path: str) → File#
Parameters:

path

file_new_for_uri(uri: str) → File#
Parameters:

uri

file_new_tmp(tmpl: str | None = None) → tuple[File, FileIOStream]#
Parameters:

tmpl

file_new_tmp_async(tmpl: str | None, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None#
Parameters:

  • tmpl

  • io_priority

  • cancellable

  • callback

  • user_data

file_new_tmp_dir_async(tmpl: str | None, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None#
Parameters:

  • tmpl

  • io_priority

  • cancellable

  • callback

  • user_data

file_new_tmp_dir_finish(result: AsyncResult) → File#
Parameters:

result

file_new_tmp_finish(result: AsyncResult) → tuple[File, FileIOStream]#
Parameters:

result

file_parse_name(parse_name: str) → File#
Parameters:

parse_name

icon_deserialize(value: Variant) → Icon | None#
Parameters:

value

icon_new_for_string(str: str) → Icon#
Parameters:

str

initable_newv(object_type: GType, parameters: list[Parameter], cancellable: Cancellable | None = None) → Object#
Parameters:

  • object_type

  • parameters

  • cancellable

io_error_from_errno(err_no: int) → IOErrorEnum#

Converts errno.h error codes into GIO error codes.

The fallback value 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);
Parameters:

err_no – Error number as defined in errno.h.

Returns:

IOErrorEnum value for the given errno.h error number

io_error_from_file_error(file_error: FileError) → IOErrorEnum#

Converts FileError error codes into GIO error codes.

Added in version 2.74.

Parameters:

file_error – a FileError.

Returns:

IOErrorEnum value for the given FileError error value.

io_error_quark() → int#

Gets the GIO Error Quark.

Returns:

a Quark.

io_extension_point_implement(extension_point_name: str, type: GType, extension_name: str, priority: int) → IOExtension#
Parameters:

  • extension_point_name

  • type

  • extension_name

  • priority

io_extension_point_lookup(name: str) → IOExtensionPoint#
Parameters:

name

io_extension_point_register(name: str) → IOExtensionPoint#
Parameters:

name

io_modules_load_all_in_directory(dirname: str) → list[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 io_modules_scan_all_in_directory() which allows delayed/lazy loading of modules.

Parameters:

dirname – pathname for a directory containing modules to load.

Returns:

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

io_modules_load_all_in_directory_with_scope(dirname: str, scope: IOModuleScope) → list[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 io_modules_scan_all_in_directory() which allows delayed/lazy loading of modules.

Added in version 2.30.

Parameters:

  • dirname – pathname for a directory containing modules to load.

  • scope – a scope to use when scanning the modules.

Returns:

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

io_modules_scan_all_in_directory(dirname: str) → None#

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. get_extensions() or get_extension_by_name().

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

Added in version 2.24.

Parameters:

dirname – pathname for a directory containing modules to scan.

io_modules_scan_all_in_directory_with_scope(dirname: str, scope: IOModuleScope) → None#

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. get_extensions() or get_extension_by_name().

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

Added in version 2.30.

Parameters:

  • dirname – pathname for a directory containing modules to scan.

  • scope – a scope to use when scanning the modules

io_scheduler_cancel_all_jobs() → None#

Cancels all cancellable I/O jobs.

A job is cancellable if a Cancellable was passed into 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.

io_scheduler_push_job(job_func: Callable[[IOSchedulerJob, Cancellable | None, Any], bool], user_data: Any, io_priority: int, cancellable: Cancellable | None = None) → None#

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 cancel() or by calling io_scheduler_cancel_all_jobs().

Deprecated since version 2.36: use ThreadPool or run_in_thread()

Parameters:

  • job_func – a IOSchedulerJobFunc.

  • user_data – data to pass to job_func

  • io_priority – the I/O priority of the request.

  • cancellable – optional Cancellable object, None to ignore.

keyfile_settings_backend_new(filename: str, root_path: str, root_group: str | None = None) → SettingsBackend#

Creates a keyfile-backed 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.

Parameters:

  • filename – the filename of the keyfile

  • root_path – the path under which all settings keys appear

  • root_group – the group name corresponding to root_path, or None

Returns:

a keyfile-backed SettingsBackend

memory_monitor_dup_default() → MemoryMonitor#
memory_settings_backend_new() → SettingsBackend#

Creates a memory-backed 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.

Added in version 2.28.

Returns:

a newly created SettingsBackend

network_monitor_get_default() → NetworkMonitor#
networking_init() → None#

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

Added in version 2.36.

null_settings_backend_new() → SettingsBackend#

Creates a readonly SettingsBackend.

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

Added in version 2.28.

Returns:

a newly created SettingsBackend

pollable_source_new(pollable_stream: Object) → Source#

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

Added in version 2.28.

Parameters:

pollable_stream – the stream associated with the new source

Returns:

the new Source.

pollable_source_new_full(pollable_stream: Object, child_source: Source | None = None, cancellable: Cancellable | None = None) → Source#

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

Added in version 2.34.

Parameters:

  • pollable_stream – the stream associated with the new source

  • child_source – optional child source to attach

  • cancellable – optional Cancellable to attach

Returns:

the new Source.

pollable_stream_read(stream: InputStream, buffer: list[int], blocking: bool, cancellable: Cancellable | None = None) → int#

Tries to read from stream, as with read() (if blocking is True) or 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 PollableInputStream for which can_poll() returns True, or else the behavior is undefined. If blocking is True, then stream does not need to be a PollableInputStream.

Added in version 2.34.

Parameters:

  • stream – a InputStream

  • buffer – a buffer to read data into

  • blocking – whether to do blocking I/O

  • cancellable – optional Cancellable object, None to ignore.

Returns:

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

pollable_stream_write(stream: OutputStream, buffer: list[int], blocking: bool, cancellable: Cancellable | None = None) → int#

Tries to write to stream, as with write() (if blocking is True) or 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 PollableOutputStream for which can_poll() returns True or else the behavior is undefined. If blocking is True, then stream does not need to be a PollableOutputStream.

Added in version 2.34.

Parameters:

  • stream – a OutputStream.

  • buffer – the buffer containing the data to write.

  • blocking – whether to do blocking I/O

  • cancellable – optional Cancellable object, None to ignore.

Returns:

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

pollable_stream_write_all(stream: OutputStream, buffer: list[int], blocking: bool, cancellable: Cancellable | None = None) → tuple[bool, int]#

Tries to write count bytes to stream, as with write_all(), but using pollable_stream_write() rather than 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 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 pollable_stream_write(), if blocking is False, then stream must be a PollableOutputStream for which can_poll() returns True or else the behavior is undefined. If blocking is True, then stream does not need to be a PollableOutputStream.

Added in version 2.34.

Parameters:

  • stream – a OutputStream.

  • buffer – the buffer containing the data to write.

  • blocking – whether to do blocking I/O

  • cancellable – optional Cancellable object, None to ignore.

Returns:

True on success, False if there was an error

power_profile_monitor_dup_default() → PowerProfileMonitor#
proxy_get_default_for_protocol(protocol: str) → Proxy | None#
Parameters:

protocol

proxy_resolver_get_default() → ProxyResolver#
resolver_error_quark() → int#
resource_error_quark() → int#
resource_load(filename: str) → Resource#
Parameters:

filename

resources_enumerate_children(path: str, lookup_flags: ResourceLookupFlags) → list[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 strfreev().

lookup_flags controls the behaviour of the lookup.

Added in version 2.32.

Parameters:
Returns:

an array of constant strings

resources_get_info(path: str, lookup_flags: ResourceLookupFlags) → tuple[bool, int, 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.

Added in version 2.32.

Parameters:
Returns:

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

resources_lookup_data(path: str, lookup_flags: ResourceLookupFlags) → Bytes#

Looks for a file at the specified path in the set of globally registered resources and returns a 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 GBytes.

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

lookup_flags controls the behaviour of the lookup.

Added in version 2.32.

Parameters:
Returns:

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

resources_open_stream(path: str, lookup_flags: ResourceLookupFlags) → InputStream#

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

lookup_flags controls the behaviour of the lookup.

Added in version 2.32.

Parameters:
Returns:

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

resources_register(resource: Resource) → None#

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

Added in version 2.32.

Parameters:

resource – A Resource

resources_unregister(resource: Resource) → None#

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

Added in version 2.32.

Parameters:

resource – A Resource

settings_schema_source_get_default() → SettingsSchemaSource | None#
simple_async_report_gerror_in_idle(object: Object | None, callback: Callable[[Object | None, AsyncResult, Any], None] | None, user_data: Any, error: GError) → None#

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

Deprecated since version 2.46: Use report_error().

Parameters:

  • object – a Object, or None

  • callback – a AsyncReadyCallback.

  • user_data – user data passed to callback.

  • error – the Error to report

tls_backend_get_default() → TlsBackend#
tls_channel_binding_error_quark() → int#
tls_client_connection_new(base_io_stream: IOStream, server_identity: SocketConnectable | None = None) → TlsClientConnection#
Parameters:

  • base_io_stream

  • server_identity

tls_error_quark() → int#
tls_file_database_new(anchors: str) → TlsFileDatabase#
Parameters:

anchors

tls_server_connection_new(base_io_stream: IOStream, certificate: TlsCertificate | None = None) → TlsServerConnection#
Parameters:

  • base_io_stream

  • certificate

unix_is_mount_path_system_internal(mount_path: str) → 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.

Parameters:

mount_path – a mount path, e.g. /media/disk or /usr

Returns:

True if mount_path is considered an implementation detail of the OS.

unix_is_system_device_path(device_path: str) → 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.

Added in version 2.56.

Parameters:

device_path – a device path, e.g. /dev/loop0 or nfsd

Returns:

True if device_path is considered an implementation detail of the OS.

unix_is_system_fs_type(fs_type: str) → 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.

Added in version 2.56.

Parameters:

fs_type – a file system type, e.g. procfs or tmpfs

Returns:

True if fs_type is considered an implementation detail of the OS.

unix_mount_at(mount_path: str) → tuple[UnixMountEntry | None, int]#

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

Parameters:

mount_path – path for a possible unix mount.

Returns:

a UnixMountEntry.

unix_mount_compare(mount1: UnixMountEntry, mount2: UnixMountEntry) → int#

Compares two unix mounts.

Parameters:
Returns:

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

unix_mount_for(file_path: str) → tuple[UnixMountEntry | None, int]#

Gets a 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 unix_mounts_changed_since().

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

This will return None if looking up the mount entry fails, if file_path doesn’t exist or there is an I/O error.

Added in version 2.52.

Parameters:

file_path – file path on some unix mount.

Returns:

a UnixMountEntry.

unix_mount_free(mount_entry: UnixMountEntry) → None#

Frees a unix mount.

Parameters:

mount_entry – a UnixMountEntry.

unix_mount_get_device_path(mount_entry: UnixMountEntry) → str#

Gets the device path for a unix mount.

Parameters:

mount_entry – a GUnixMount.

Returns:

a string containing the device path.

unix_mount_get_fs_type(mount_entry: UnixMountEntry) → str#

Gets the filesystem type for the unix mount.

Parameters:

mount_entry – a GUnixMount.

Returns:

a string containing the file system type.

unix_mount_get_mount_path(mount_entry: UnixMountEntry) → str#

Gets the mount path for a unix mount.

Parameters:

mount_entry – input UnixMountEntry to get the mount path for.

Returns:

the mount path for mount_entry.

unix_mount_get_options(mount_entry: UnixMountEntry) → str | None#

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

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

Added in version 2.58.

Parameters:

mount_entry – a UnixMountEntry.

Returns:

a string containing the options, or None if not available.

unix_mount_get_root_path(mount_entry: UnixMountEntry) → str | 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”.

Added in version 2.60.

Parameters:

mount_entry – a UnixMountEntry.

Returns:

a string containing the root, or None if not supported.

unix_mount_guess_can_eject(mount_entry: UnixMountEntry) → bool#

Guesses whether a Unix mount can be ejected.

Parameters:

mount_entry – a UnixMountEntry

Returns:

True if mount_entry is deemed to be ejectable.

unix_mount_guess_icon(mount_entry: UnixMountEntry) → Icon#

Guesses the icon of a Unix mount.

Parameters:

mount_entry – a UnixMountEntry

Returns:

a Icon

unix_mount_guess_name(mount_entry: UnixMountEntry) → str#

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

Parameters:

mount_entry – a UnixMountEntry

Returns:

A newly allocated string that must be freed with free()

unix_mount_guess_should_display(mount_entry: UnixMountEntry) → bool#

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

Parameters:

mount_entry – a UnixMountEntry

Returns:

True if mount_entry is deemed to be displayable.

unix_mount_guess_symbolic_icon(mount_entry: UnixMountEntry) → Icon#

Guesses the symbolic icon of a Unix mount.

Added in version 2.34.

Parameters:

mount_entry – a UnixMountEntry

Returns:

a Icon

unix_mount_is_readonly(mount_entry: UnixMountEntry) → bool#

Checks if a unix mount is mounted read only.

Parameters:

mount_entry – a GUnixMount.

Returns:

True if mount_entry is read only.

unix_mount_is_system_internal(mount_entry: UnixMountEntry) → bool#

Checks if a Unix mount is a system mount. This is the Boolean OR of unix_is_system_fs_type(), unix_is_system_device_path() and 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.

Parameters:

mount_entry – a GUnixMount.

Returns:

True if the unix mount is for a system path.

unix_mount_point_at(mount_path: str) → tuple[UnixMountPoint | None, int]#
Parameters:

mount_path

unix_mount_points_changed_since(time: int) → bool#

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

Parameters:

time – guint64 to contain a timestamp.

Returns:

True if the mount points have changed since time.

unix_mount_points_get() → tuple[list[UnixMountPoint], int]#

Gets a List of 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 unix_mount_points_changed_since().

Returns:

a List of the UNIX mountpoints.

unix_mount_points_get_from_file(table_path: str) → tuple[list[UnixMountPoint] | None, int]#

Gets an array of UnixMountPoints containing the Unix mount points listed in table_path.

This is a generalized version of unix_mount_points_get(), mainly intended for internal testing use. Note that unix_mount_points_get() may parse multiple hierarchical table files, so this function is not a direct superset of its functionality.

If there is an error reading or parsing the file, NULL will be returned and both out parameters will be set to 0.

Added in version 2.82.

Parameters:

table_path – path to the mount points table file (for example /etc/fstab)

Returns:

mount points, or NULL if there was an error loading them

unix_mounts_changed_since(time: int) → bool#

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

Parameters:

time – guint64 to contain a timestamp.

Returns:

True if the mounts have changed since time.

unix_mounts_get() → tuple[list[UnixMountEntry], int]#

Gets a List of 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 unix_mounts_changed_since().

Returns:

a List of the UNIX mounts.

unix_mounts_get_from_file(table_path: str) → tuple[list[UnixMountEntry] | None, int]#

Gets an array of UnixMountEntrys containing the Unix mounts listed in table_path.

This is a generalized version of unix_mounts_get(), mainly intended for internal testing use. Note that unix_mounts_get() may parse multiple hierarchical table files, so this function is not a direct superset of its functionality.

If there is an error reading or parsing the file, NULL will be returned and both out parameters will be set to 0.

Added in version 2.82.

Parameters:

table_path – path to the mounts table file (for example /proc/self/mountinfo)

Returns:

mount entries, or NULL if there was an error loading them

On this page

This Page