Functions
- action_parse_detailed_name(detailed_name: str) tuple[bool, str, Variant]
- 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_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[[...], None] | None = None, *user_data: Any) 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_async(uri_scheme: str, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None
- Parameters:
uri_scheme
cancellable
callback
user_data
- app_info_get_default_for_uri_scheme_finish(result: AsyncResult) AppInfo
- Parameters:
result
- 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[[...], None] | None = None, *user_data: Any) None
- Parameters:
uri
context
cancellable
callback
user_data
- app_info_launch_default_for_uri_finish(result: AsyncResult) bool
- Parameters:
result
- async_initable_newv_async(object_type: type, n_parameters: int, parameters: Parameter, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None
- Parameters:
object_type
n_parameters
parameters
io_priority
cancellable
callback
user_data
- bus_get(bus_type: BusType, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None
Asynchronously connects to the message bus specified by
bus_type
.When the operation is finished,
callback
will be invoked. You can then callbus_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
orNone
callback – a
AsyncReadyCallback
to call when the request is satisfieduser_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()
andbus_get_sync()
forbus_type
. In the event that you need a private message bus connection, usedbus_address_get_for_bus_sync()
andnew_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 theDBusConnection
:exit-on-close property set toTrue
.Added in version 2.26.
- Parameters:
res – a
AsyncResult
obtained from theAsyncReadyCallback
passed tobus_get()
- Returns:
a
DBusConnection
orNone
iferror
is set. Free withunref()
.
- 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 samebus_type
, they will share the same object.This is a synchronous failable function. See
bus_get()
andbus_get_finish()
for the asynchronous version.The returned object is a singleton, that is, shared with other callers of
bus_get()
andbus_get_sync()
forbus_type
. In the event that you need a private message bus connection, usedbus_address_get_for_bus_sync()
andnew_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 theDBusConnection
:exit-on-close property set toTrue
.Added in version 2.26.
- Parameters:
bus_type – a
BusType
cancellable – a
Cancellable
orNone
- Returns:
a
DBusConnection
orNone
iferror
is set. Free withunref()
.
- bus_own_name(bus_type: BusType, name: str, flags: BusNameOwnerFlags, bus_acquired_closure: Callable[[...], Any] | None = None, name_acquired_closure: Callable[[...], Any] | None = None, name_lost_closure: Callable[[...], Any] | None = None) int
Starts acquiring
name
on the bus specified bybus_type
and callsname_acquired_handler
andname_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
andname_lost_handler
callbacks will be invoked after calling this function - there are three possible cases:name_lost_handler
with aNone
connection (if a connection to the bus can’t be made).bus_acquired_handler
thenname_lost_handler
(if the name can’t be obtained)bus_acquired_handler
thenname_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, thenname_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 tobus_unown_name()
) - only the first call will work.Another guarantee is that invocations of
name_acquired_handler
andname_lost_handler
are guaranteed to alternate; that is, ifname_acquired_handler
is invoked then you are guaranteed that the next time one of the handlers is invoked, it will bename_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 inname_acquired_handler
. Instead, you can do this inbus_acquired_handler
since you are guaranteed that this will run beforename
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) inname_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
enumerationbus_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: Callable[[...], Any] | None = None, name_lost_closure: Callable[[...], Any] | None = None) int
Like
bus_own_name()
but takes aDBusConnection
instead of aBusType
.Added in version 2.26.
- Parameters:
connection – a
DBusConnection
name – the well-known name to own
flags – a set of flags from the
BusNameOwnerFlags
enumerationname_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 theMainContext
until theDestroyNotify
function passed tobus_own_name()
is called, in order to avoid memory leaks through callbacks queued on theMainContext
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 theMainContext
until theDestroyNotify
function passed tobus_watch_name()
is called, in order to avoid memory leaks through callbacks queued on theMainContext
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: Callable[[...], Any] | None = None, name_vanished_closure: Callable[[...], Any] | None = None) int
Starts watching
name
on the bus specified bybus_type
and callsname_appeared_handler
andname_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, thenname_vanished_handler
is invoked since it is no longer possible to access the name.Another guarantee is that invocations of
name_appeared_handler
andname_vanished_handler
are guaranteed to alternate; that is, ifname_appeared_handler
is invoked then you are guaranteed that the next time one of the handlers is invoked, it will bename_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) inname_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: Callable[[...], Any] | None = None, name_vanished_closure: Callable[[...], Any] | None = None) int
Like
bus_watch_name()
but takes aDBusConnection
instead of aBusType
.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 withfree()
- 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 withfree()
- 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
, orNone
if unknown. Free withfree()
- 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 withunref()
- 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 anymime/
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
, orNone
if unknown; free withfree()
.
- 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 withunref()
- content_type_guess(filename: str | None = None, data: Sequence[int] | None = None) tuple[str, bool]
Guesses the content type based on example data. If the function is uncertain,
result_uncertain
will be set toTrue
. Eitherfilename
ordata
may beNone
, 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 withstrfreev()
- content_type_is_a(type: str, supertype: str) bool
Determines if
type
is a subset ofsupertype
.- Parameters:
type – a content type string
supertype – a content type string
- Returns:
True
iftype
is a kind ofsupertype
,False
otherwise.
- content_type_is_mime_type(type: str, mime_type: str) bool
Determines if
type
is a subset ofmime_type
. Convenience wrapper aroundcontent_type_is_a()
.Added in version 2.52.
- Parameters:
type – a content type string
mime_type – a mime type string
- Returns:
True
iftype
is a kind ofmime_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: Sequence[str] | None = None) None
Set the list of directories used by GIO to load the MIME database. If
dirs
isNone
, 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 withdirs
set toNone
before callingtest_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 anymime/
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 likeunix: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:
bus_type – a
BusType
cancellable – a
Cancellable
orNone
- Returns:
a valid D-Bus address string for
bus_type
orNone
iferror
is set
- dbus_address_get_stream(address: str, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) 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 calldbus_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
orNone
.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]
Finishes an operation started with
dbus_address_get_stream()
.A server is not required to set a GUID, so
out_guid
may be set toNone
even on success.Added in version 2.26.
- Parameters:
res – A
AsyncResult
obtained from the GAsyncReadyCallback passed todbus_address_get_stream()
.- Returns:
A
IOStream
orNone
iferror
is set.
- dbus_address_get_stream_sync(address: str, cancellable: Cancellable | None = None) tuple[IOStream, 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.A server is not required to set a GUID, so
out_guid
may be set toNone
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
orNone
.
- Returns:
A
IOStream
orNone
iferror
is set.
- dbus_annotation_info_lookup(annotations: Sequence[DBusAnnotationInfo] | None, name: str) str | None
- Parameters:
annotations
name
- dbus_error_new_for_dbus_error(dbus_error_name: str, dbus_error_message: str) GError
- Parameters:
dbus_error_name
dbus_error_message
- 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: Sequence[DBusErrorEntry]) None
- Parameters:
error_domain_quark_name
quark_volatile
entries
- 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 withfree()
.
- dbus_escape_object_path_bytestring(bytes: Sequence[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 becomefoo_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 withfree()
.
- 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: Any, type: VariantType) Variant
Converts a
Value
to aVariant
of the type indicated by thetype
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
: AnyVariantType
This can fail if e.g.
gvalue
is of typestr
andtype
is ‘i’, i.e.%G_VARIANT_TYPE_INT32
. It will also fail for anyType
(including e.g.object
andBoxed
derived-types) not in the table above.Note that if
gvalue
is of type%G_TYPE_VARIANT
and its value isNone
, the emptyVariant
instance (neverNone
) fortype
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 aVariant
to aValue
.Added in version 2.30.
- Parameters:
type – A
VariantType
- Returns:
A
Variant
(never floating) ofVariantType
type
holding the data fromgvalue
or an emptyVariant
in case of failure. Free withunref()
.
- dbus_gvariant_to_gvalue(value: Variant) Any
Converts a
Variant
to aValue
. Ifvalue
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, aVariant
containing any basic or string array type will be converted to aValue
containing a basic value or string array. Any otherVariant
(handle, variant, tuple, dict entry) will be converted to aValue
containing thatVariant
.The conversion never fails - a valid
Value
is always returned inout_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 byDBusServer
orDBusConnection
- usedbus_is_supported_address()
to do more checks.Added in version 2.26.
- Parameters:
string – A string.
- Returns:
True
ifstring
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
ifstring
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 instring
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
ifstring
is a valid D-Bus address that is supported by this library,False
iferror
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) bytes | 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 bydbus_escape_object_path()
, this function returnsNone
.Encoding alphanumeric characters which do not need to be encoded is not allowed (e.g
_63
is not valid, the string should containc
instead).Added in version 2.68.
- Parameters:
s – the string to unescape
- Returns:
an unescaped version of
's
, orNone
if's
is not a string returned fromdbus_escape_object_path()
. Free withfree()
.
- 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_tmp_async(tmpl: str | None, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) 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[[...], None] | None = None, *user_data: Any) 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
- initable_newv(object_type: type, parameters: Sequence[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 oferrno
: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 givenerrno.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 givenFileError
error value.
- io_extension_point_implement(extension_point_name: str, type: type, 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 callunuse()
on all the modules. Free the list withfree()
.
- 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 callunuse()
on all the modules. Free the list withfree()
.
- 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()
orget_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()
orget_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 intoio_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[[...], bool], io_priority: int, cancellable: Cancellable | None = None, *user_data: Any) None
Schedules the I/O job to run in another thread.
notify
will be called onuser_data
afterjob_func
has returned, regardless whether the job was cancelled or has run to completion.If
cancellable
is notNone
, it can be used to cancel the I/O job by callingcancel()
or by callingio_scheduler_cancel_all_jobs()
.Deprecated since version 2.36: use
ThreadPool
orrun_in_thread()
- Parameters:
job_func – a
IOSchedulerJobFunc
.io_priority – the I/O priority of the request.
cancellable – optional
Cancellable
object,None
to ignore.user_data – data to pass to
job_func
- 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 belowroot_path
. For example, ifroot_path
is “/apps/example/” androot_group
is “toplevel”, then settings the key “/apps/example/enabled” to a value ofTrue
will cause the following to appear in the keyfile:[toplevel] enabled=true
If
root_group
isNone
then it is not permitted to store keys directly below theroot_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 ofroot_path
and, in the event thatroot_group
isNone
, also for keys directly underroot_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 theGKeyfileSettingsBackend
:defaults-dir property, and a list of locked keys from a text file with the namelocks
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
, orNone
- 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
andPollableOutputStream
implementations. Creates a newSource
that expects a callback of typeGPollableSourceFunc
. The new source does not actually do anything on its own; useadd_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
andPollableOutputStream
implementations. Creates a newSource
, as withpollable_source_new()
, but also attachingchild_source
(with a dummy callback), andcancellable
, 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: Sequence[int], blocking: bool, cancellable: Cancellable | None = None) int
Tries to read from
stream
, as withread()
(ifblocking
isTrue
) orread_nonblocking()
(ifblocking
isFalse
). This can be used to more easily share code between blocking and non-blocking implementations of a method.If
blocking
isFalse
, thenstream
must be aPollableInputStream
for whichcan_poll()
returnsTrue
, or else the behavior is undefined. Ifblocking
isTrue
, thenstream
does not need to be aPollableInputStream
.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: Sequence[int], blocking: bool, cancellable: Cancellable | None = None) int
Tries to write to
stream
, as withwrite()
(ifblocking
isTrue
) orwrite_nonblocking()
(ifblocking
isFalse
). This can be used to more easily share code between blocking and non-blocking implementations of a method.If
blocking
isFalse
, thenstream
must be aPollableOutputStream
for whichcan_poll()
returnsTrue
or else the behavior is undefined. Ifblocking
isTrue
, thenstream
does not need to be aPollableOutputStream
.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: Sequence[int], blocking: bool, cancellable: Cancellable | None = None) tuple[bool, int]
Tries to write
count
bytes tostream
, as withwrite_all()
, but usingpollable_stream_write()
rather thanwrite()
.On a successful write of
count
bytes,True
is returned, andbytes_written
is set tocount
.If there is an error during the operation (including
WOULD_BLOCK
in the non-blocking case),False
is returned anderror
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()
, ifblocking
isFalse
, thenstream
must be aPollableOutputStream
for whichcan_poll()
returnsTrue
or else the behavior is undefined. Ifblocking
isTrue
, thenstream
does not need to be aPollableOutputStream
.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_resolver_get_default() ProxyResolver
- 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 aNone
terminated list of strings which should be released withstrfreev()
.lookup_flags
controls the behaviour of the lookup.Added in version 2.32.
- Parameters:
path – A pathname inside the resource
lookup_flags – A
ResourceLookupFlags
- 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:
path – A pathname inside the resource
lookup_flags – A
ResourceLookupFlags
- 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 aBytes
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:
path – A pathname inside the resource
lookup_flags – A
ResourceLookupFlags
- Returns:
Bytes
orNone
on error. Free the returned object withunref()
- 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 aInputStream
that lets you read the data.lookup_flags
controls the behaviour of the lookup.Added in version 2.32.
- Parameters:
path – A pathname inside the resource
lookup_flags – A
ResourceLookupFlags
- Returns:
InputStream
orNone
on error. Free the returned object withunref()
- 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[[...], None] | None, error: GError, *user_data: Any) None
Reports an error in an idle function. Similar to
simple_async_report_error_in_idle()
, but takes aError
rather than building a new one.Deprecated since version 2.46: Use
report_error()
.
- tls_backend_get_default() TlsBackend
- tls_client_connection_new(base_io_stream: IOStream, server_identity: SocketConnectable | None = None) TlsClientConnection
- Parameters:
base_io_stream
server_identity
- 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
ifmount_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
ornfsd
- Returns:
True
ifdevice_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
ortmpfs
- Returns:
True
iffs_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. Iftime_read
is set, it will be filled with a unix timestamp for checking if the mounts have changed since withunix_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 atmount_path
.- Parameters:
mount_path – path for a possible unix mount.
- Returns:
- unix_mount_compare(mount1: UnixMountEntry, mount2: UnixMountEntry) int
Compares two unix mounts.
- Parameters:
mount1 – first
UnixMountEntry
to compare.mount2 – second
UnixMountEntry
to compare.
- Returns:
1, 0 or -1 if
mount1
is greater than, equal to, or less thanmount2
, respectively.
- unix_mount_for(file_path: str) tuple[UnixMountEntry | None, int]
Gets a
UnixMountEntry
for a given file path. Iftime_read
is set, it will be filled with a unix timestamp for checking if the mounts have changed since withunix_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, iffile_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:
- 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 aUnixMountEntry
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
ifmount_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
ifmount_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
ifmount_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()
andunix_is_mount_path_system_internal()
onmount_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_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 sincetime
.
- unix_mount_points_get() tuple[list[UnixMountPoint], int]
Gets a
List
ofUnixMountPoint
containing the unix mount points. Iftime_read
is set, it will be filled with the mount timestamp, allowing for checking if the mounts have changed withunix_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
UnixMountPoint
’s containing the Unix mount points listed intable_path
.This is a generalized version of
unix_mount_points_get()
, mainly intended for internal testing use. Note thatunix_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 to0
.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 sincetime
.
- unix_mounts_get() tuple[list[UnixMountEntry], int]
Gets a
List
ofUnixMountEntry
containing the unix mounts. Iftime_read
is set, it will be filled with the mount timestamp, allowing for checking if the mounts have changed withunix_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
UnixMountEntry
’s containing the Unix mounts listed intable_path
.This is a generalized version of
unix_mounts_get()
, mainly intended for internal testing use. Note thatunix_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 to0
.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