DBusConnection

Added in version 2.26.

class DBusConnection(**properties: Any)

Superclasses: Object

Implemented Interfaces: AsyncInitable, Initable

The GDBusConnection type is used for D-Bus connections to remote peers such as a message buses.

It is a low-level API that offers a lot of flexibility. For instance, it lets you establish a connection over any transport that can by represented as a IOStream.

This class is rarely used directly in D-Bus clients. If you are writing a D-Bus client, it is often easier to use the bus_own_name, bus_watch_name or new_for_bus APIs.

As an exception to the usual GLib rule that a particular object must not be used by two threads at the same time, GDBusConnection’s methods may be called from any thread. This is so that bus_get and bus_get_sync can safely return the same GDBusConnection when called from any thread.

Most of the ways to obtain a GDBusConnection automatically initialize it (i.e. connect to D-Bus): for instance, new and bus_get, and the synchronous versions of those methods, give you an initialized connection. Language bindings for GIO should use new or new_async, which also initialize the connection.

If you construct an uninitialized GDBusConnection, such as via new, you must initialize it via init or init_async before using its methods or properties. Calling methods or accessing properties on a GDBusConnection that has not completed initialization successfully is considered to be invalid, and leads to undefined behaviour. In particular, if initialization fails with a GError, the only valid thing you can do with that GDBusConnection is to free it with unref.

An example D-Bus server

Here is an example for a D-Bus server: gdbus-example-server.c

An example for exporting a subtree

Here is an example for exporting a subtree: gdbus-example-subtree.c

An example for file descriptor passing

Here is an example for passing UNIX file descriptors: gdbus-unix-fd-client.c

An example for exporting a GObject

Here is an example for exporting a Object: gdbus-example-export.c

Constructors

class DBusConnection

classmethod new_finish(res: AsyncResult) → DBusConnection

Finishes an operation started with new().

Added in version 2.26.

Parameters:: res – a AsyncResult obtained from the AsyncReadyCallback passed to new().

classmethod new_for_address_finish(res: AsyncResult) → DBusConnection

Finishes an operation started with new_for_address().

Added in version 2.26.

Parameters:: res – a AsyncResult obtained from the AsyncReadyCallback passed to new()

classmethod new_for_address_sync(address: str, flags: DBusConnectionFlags, observer: DBusAuthObserver | None = None, cancellable: Cancellable | None = None) → DBusConnection

Synchronously connects and sets up a D-Bus client connection for exchanging D-Bus messages with an endpoint specified by address which must be in the D-Bus address format.

This constructor can only be used to initiate client-side connections - use new_sync() if you need to act as the server. In particular, flags cannot contain the AUTHENTICATION_SERVER, AUTHENTICATION_ALLOW_ANONYMOUS or AUTHENTICATION_REQUIRE_SAME_USER flags.

This is a synchronous failable constructor. See new_for_address() for the asynchronous version.

If observer is not None it may be used to control the authentication process.

Added in version 2.26.

Parameters:

address – a D-Bus address
flags – flags describing how to make the connection
observer – a DBusAuthObserver or None
cancellable – a Cancellable or None

classmethod new_sync(stream: IOStream, guid: str | None, flags: DBusConnectionFlags, observer: DBusAuthObserver | None = None, cancellable: Cancellable | None = None) → DBusConnection

Synchronously sets up a D-Bus connection for exchanging D-Bus messages with the end represented by stream.

If stream is a SocketConnection, then the corresponding Socket will be put into non-blocking mode.

The D-Bus connection will interact with stream from a worker thread. As a result, the caller should not interact with stream after this method has been called, except by calling unref() on it.

If observer is not None it may be used to control the authentication process.

This is a synchronous failable constructor. See new() for the asynchronous version.

Added in version 2.26.

Parameters:

stream – a IOStream
guid – the GUID to use if authenticating as a server or None
flags – flags describing how to make the connection
observer – a DBusAuthObserver or None
cancellable – a Cancellable or None

Methods

class DBusConnection

add_filter(filter_function: Callable[[...], DBusMessage | None], *user_data: Any) → int

Adds a message filter. Filters are handlers that are run on all incoming and outgoing messages, prior to standard dispatch. Filters are run in the order that they were added. The same handler can be added as a filter more than once, in which case it will be run more than once. Filters added during a filter callback won’t be run on the message being processed. Filter functions are allowed to modify and even drop messages.

Note that filters are run in a dedicated message handling thread so they can’t block and, generally, can’t do anything but signal a worker thread. Also note that filters are rarely needed - use API such as send_message_with_reply(), signal_subscribe() or call() instead.

If a filter consumes an incoming message the message is not dispatched anywhere else - not even the standard dispatch machinery (that API such as signal_subscribe() and send_message_with_reply() relies on) will see the message. Similarly, if a filter consumes an outgoing message, the message will not be sent to the other peer.

If user_data_free_func is non-None, it will be called (in the thread-default main context of the thread you are calling this method from) at some point after user_data is no longer needed. (It is not guaranteed to be called synchronously when the filter is removed, and may be called after connection has been destroyed.)

Added in version 2.26.

Parameters:

filter_function – a filter function
user_data – user data to pass to filter_function

call(bus_name: str | None, object_path: str, interface_name: str, method_name: str, parameters: Variant | None, reply_type: VariantType | None, flags: DBusCallFlags, timeout_msec: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

Asynchronously invokes the method_name method on the interface_name D-Bus interface on the remote object at object_path owned by bus_name.

If connection is closed then the operation will fail with CLOSED. If cancellable is canceled, the operation will fail with CANCELLED. If parameters contains a value not compatible with the D-Bus protocol, the operation fails with INVALID_ARGUMENT.

If reply_type is non-None then the reply will be checked for having this type and an error will be raised if it does not match. Said another way, if you give a reply_type then any non-None return value will be of this type. Unless it’s %G_VARIANT_TYPE_UNIT, the reply_type will be a tuple containing one or more values.

If the parameters Variant is floating, it is consumed. This allows convenient ‘inline’ use of new(), e.g.:

g_dbus_connection_call (connection,
                        "org.freedesktop.StringThings",
                        "/org/freedesktop/StringThings",
                        "org.freedesktop.StringThings",
                        "TwoStrings",
                        g_variant_new ("(ss)",
                                       "Thing One",
                                       "Thing Two"),
                        NULL,
                        G_DBUS_CALL_FLAGS_NONE,
                        -1,
                        NULL,
                        (GAsyncReadyCallback) two_strings_done,
                        NULL);

This is an asynchronous method. When the operation is finished, callback will be invoked in the [thread-default main context][g-main-context-push-thread-default] of the thread you are calling this method from. You can then call call_finish() to get the result of the operation. See call_sync() for the synchronous version of this function.

If callback is None then the D-Bus method call message will be sent with the NO_REPLY_EXPECTED flag set.

Added in version 2.26.

Parameters:

bus_name – a unique or well-known bus name or None if connection is not a message bus connection
object_path – path of remote object
interface_name – D-Bus interface to invoke method on
method_name – the name of the method to invoke
parameters – a Variant tuple with parameters for the method or None if not passing parameters
reply_type – the expected type of the reply (which will be a tuple), or None
flags – flags from the DBusCallFlags enumeration
timeout_msec – the timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout
cancellable – a Cancellable or None
callback – a AsyncReadyCallback to call when the request is satisfied or None if you don’t care about the result of the method invocation
user_data – the data to pass to callback

call_finish(res: AsyncResult) → Variant

Finishes an operation started with call().

Added in version 2.26.

Parameters:: res – a AsyncResult obtained from the AsyncReadyCallback passed to call()

call_sync(bus_name: str | None, object_path: str, interface_name: str, method_name: str, parameters: Variant | None, reply_type: VariantType | None, flags: DBusCallFlags, timeout_msec: int, cancellable: Cancellable | None = None) → Variant

Synchronously invokes the method_name method on the interface_name D-Bus interface on the remote object at object_path owned by bus_name.

If the parameters Variant is floating, it is consumed. This allows convenient ‘inline’ use of new(), e.g.:

g_dbus_connection_call_sync (connection,
                             "org.freedesktop.StringThings",
                             "/org/freedesktop/StringThings",
                             "org.freedesktop.StringThings",
                             "TwoStrings",
                             g_variant_new ("(ss)",
                                            "Thing One",
                                            "Thing Two"),
                             NULL,
                             G_DBUS_CALL_FLAGS_NONE,
                             -1,
                             NULL,
                             &error);

The calling thread is blocked until a reply is received. See call() for the asynchronous version of this method.

Added in version 2.26.

Parameters:

bus_name – a unique or well-known bus name or None if connection is not a message bus connection
object_path – path of remote object
interface_name – D-Bus interface to invoke method on
method_name – the name of the method to invoke
parameters – a Variant tuple with parameters for the method or None if not passing parameters
reply_type – the expected type of the reply, or None
flags – flags from the DBusCallFlags enumeration
timeout_msec – the timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout
cancellable – a Cancellable or None

call_with_unix_fd_list(bus_name: str | None, object_path: str, interface_name: str, method_name: str, parameters: Variant | None, reply_type: VariantType | None, flags: DBusCallFlags, timeout_msec: int, fd_list: UnixFDList | None = None, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

Like call() but also takes a UnixFDList object.

The file descriptors normally correspond to %G_VARIANT_TYPE_HANDLE values in the body of the message. For example, if a message contains two file descriptors, fd_list would have length 2, and g_variant_new_handle (0) and g_variant_new_handle (1) would appear somewhere in the body of the message (not necessarily in that order!) to represent the file descriptors at indexes 0 and 1 respectively.

When designing D-Bus APIs that are intended to be interoperable, please note that non-GDBus implementations of D-Bus can usually only access file descriptors if they are referenced in this way by a value of type %G_VARIANT_TYPE_HANDLE in the body of the message.

This method is only available on UNIX.

Added in version 2.30.

Parameters:

bus_name – a unique or well-known bus name or None if connection is not a message bus connection
object_path – path of remote object
interface_name – D-Bus interface to invoke method on
method_name – the name of the method to invoke
parameters – a Variant tuple with parameters for the method or None if not passing parameters
reply_type – the expected type of the reply, or None
flags – flags from the DBusCallFlags enumeration
timeout_msec – the timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout
fd_list – a UnixFDList or None
cancellable – a Cancellable or None
callback – a AsyncReadyCallback to call when the request is satisfied or None if you don’t * care about the result of the method invocation
user_data – The data to pass to callback.

call_with_unix_fd_list_finish(res: AsyncResult) → tuple[Variant, UnixFDList]

Finishes an operation started with call_with_unix_fd_list().

The file descriptors normally correspond to %G_VARIANT_TYPE_HANDLE values in the body of the message. For example, if get_handle() returns 5, that is intended to be a reference to the file descriptor that can be accessed by g_unix_fd_list_get (*out_fd_list, 5, ...).

Added in version 2.30.

Parameters:: res – a AsyncResult obtained from the AsyncReadyCallback passed to call_with_unix_fd_list()

call_with_unix_fd_list_sync(bus_name: str | None, object_path: str, interface_name: str, method_name: str, parameters: Variant | None, reply_type: VariantType | None, flags: DBusCallFlags, timeout_msec: int, fd_list: UnixFDList | None = None, cancellable: Cancellable | None = None) → tuple[Variant, UnixFDList]

Like call_sync() but also takes and returns UnixFDList objects. See call_with_unix_fd_list() and call_with_unix_fd_list_finish() for more details.

This method is only available on UNIX.

Added in version 2.30.

Parameters:

bus_name – a unique or well-known bus name or None if connection is not a message bus connection
object_path – path of remote object
interface_name – D-Bus interface to invoke method on
method_name – the name of the method to invoke
parameters – a Variant tuple with parameters for the method or None if not passing parameters
reply_type – the expected type of the reply, or None
flags – flags from the DBusCallFlags enumeration
timeout_msec – the timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout
fd_list – a UnixFDList or None
cancellable – a Cancellable or None

close(cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

Closes connection. Note that this never causes the process to exit (this might only happen if the other end of a shared message bus connection disconnects, see DBusConnection:exit-on-close).

Once the connection is closed, operations such as sending a message will return with the error CLOSED. Closing a connection will not automatically flush the connection so queued messages may be lost. Use flush() if you need such guarantees.

If connection is already closed, this method fails with CLOSED.

When connection has been closed, the DBusConnection::closed signal is emitted in the [thread-default main context][g-main-context-push-thread-default] of the thread that connection was constructed in.

This is an asynchronous method. When the operation is finished, callback will be invoked in the [thread-default main context][g-main-context-push-thread-default] of the thread you are calling this method from. You can then call close_finish() to get the result of the operation. See close_sync() for the synchronous version.

Added in version 2.26.

Parameters:

cancellable – a Cancellable or None
callback – a AsyncReadyCallback to call when the request is satisfied or None if you don’t care about the result
user_data – The data to pass to callback

close_finish(res: AsyncResult) → bool

Finishes an operation started with close().

Added in version 2.26.

Parameters:: res – a AsyncResult obtained from the AsyncReadyCallback passed to close()

close_sync(cancellable: Cancellable | None = None) → bool

Synchronously closes connection. The calling thread is blocked until this is done. See close() for the asynchronous version of this method and more details about what it does.

Added in version 2.26.

Parameters:: cancellable – a Cancellable or None

emit_signal(destination_bus_name: str | None, object_path: str, interface_name: str, signal_name: str, parameters: Variant | None = None) → bool

Emits a signal.

If the parameters GVariant is floating, it is consumed.

This can only fail if parameters is not compatible with the D-Bus protocol (INVALID_ARGUMENT), or if connection has been closed (CLOSED).

Added in version 2.26.

Parameters:

destination_bus_name – the unique bus name for the destination for the signal or None to emit to all listeners
object_path – path of remote object
interface_name – D-Bus interface to emit a signal on
signal_name – the name of the signal to emit
parameters – a Variant tuple with parameters for the signal or None if not passing parameters

export_action_group(object_path: str, action_group: ActionGroup) → int

Exports action_group on connection at object_path.

The implemented D-Bus API should be considered private. It is subject to change in the future.

A given object path can only have one action group exported on it. If this constraint is violated, the export will fail and 0 will be returned (with error set accordingly).

You can unexport the action group using unexport_action_group() with the return value of this function.

The thread default main context is taken at the time of this call. All incoming action activations and state change requests are reported from this context. Any changes on the action group that cause it to emit signals must also come from this same context. Since incoming action activations and state change requests are rather likely to cause changes on the action group, this effectively limits a given action group to being exported from only one main context.

Added in version 2.32.

Parameters:

object_path – a D-Bus object path
action_group – a ActionGroup

export_menu_model(object_path: str, menu: MenuModel) → int

Exports menu on connection at object_path.

The implemented D-Bus API should be considered private. It is subject to change in the future.

An object path can only have one menu model exported on it. If this constraint is violated, the export will fail and 0 will be returned (with error set accordingly).

Exporting menus with sections containing more than MENU_EXPORTER_MAX_SECTION_SIZE items is not supported and results in undefined behavior.

You can unexport the menu model using unexport_menu_model() with the return value of this function.

Added in version 2.32.

Parameters:

object_path – a D-Bus object path
menu – a MenuModel

flush(cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

Asynchronously flushes connection, that is, writes all queued outgoing message to the transport and then flushes the transport (using flush_async()). This is useful in programs that wants to emit a D-Bus signal and then exit immediately. Without flushing the connection, there is no guaranteed that the message has been sent to the networking buffers in the OS kernel.

This is an asynchronous method. When the operation is finished, callback will be invoked in the [thread-default main context][g-main-context-push-thread-default] of the thread you are calling this method from. You can then call flush_finish() to get the result of the operation. See flush_sync() for the synchronous version.

Added in version 2.26.

Parameters:

cancellable – a Cancellable or None
callback – a AsyncReadyCallback to call when the request is satisfied or None if you don’t care about the result
user_data – The data to pass to callback

flush_finish(res: AsyncResult) → bool

Finishes an operation started with flush().

Added in version 2.26.

Parameters:: res – a AsyncResult obtained from the AsyncReadyCallback passed to flush()

flush_sync(cancellable: Cancellable | None = None) → bool

Synchronously flushes connection. The calling thread is blocked until this is done. See flush() for the asynchronous version of this method and more details about what it does.

Added in version 2.26.

Parameters:: cancellable – a Cancellable or None

get_capabilities() → DBusCapabilityFlags: Gets the capabilities negotiated with the remote peer

Added in version 2.26.

get_exit_on_close() → bool: Gets whether the process is terminated when connection is closed by the remote peer. See DBusConnection:exit-on-close for more details.

Added in version 2.26.

get_flags() → DBusConnectionFlags: Gets the flags used to construct this connection

Added in version 2.60.

get_guid() → str: The GUID of the peer performing the role of server when authenticating. See DBusConnection:guid for more details.

Added in version 2.26.

get_last_serial() → int: Retrieves the last serial number assigned to a DBusMessage on the current thread. This includes messages sent via both low-level API such as send_message() as well as high-level API such as emit_signal(), call() or call().

Added in version 2.34.

get_peer_credentials() → Credentials | None

Gets the credentials of the authenticated peer. This will always return None unless connection acted as a server (e.g. AUTHENTICATION_SERVER was passed) when set up and the client passed credentials as part of the authentication process.

In a message bus setup, the message bus is always the server and each application is a client. So this method will always return None for message bus clients.

Added in version 2.26.

get_stream() → IOStream

Gets the underlying stream used for IO.

While the DBusConnection is active, it will interact with this stream from a worker thread, so it is not safe to interact with the stream directly.

Added in version 2.26.

get_unique_name() → str | None: Gets the unique name of connection as assigned by the message bus. This can also be used to figure out if connection is a message bus connection.

Added in version 2.26.

is_closed() → bool: Gets whether connection is closed.

Added in version 2.26.

new(stream: IOStream, guid: str | None, flags: DBusConnectionFlags, observer: DBusAuthObserver | None = None, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

Asynchronously sets up a D-Bus connection for exchanging D-Bus messages with the end represented by stream.

If stream is a SocketConnection, then the corresponding Socket will be put into non-blocking mode.

The D-Bus connection will interact with stream from a worker thread. As a result, the caller should not interact with stream after this method has been called, except by calling unref() on it.

If observer is not None it may be used to control the authentication process.

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

This is an asynchronous failable constructor. See new_sync() for the synchronous version.

Added in version 2.26.

Parameters:

stream – a IOStream
guid – the GUID to use if authenticating as a server or None
flags – flags describing how to make the connection
observer – a DBusAuthObserver or None
cancellable – a Cancellable or None
callback – a AsyncReadyCallback to call when the request is satisfied
user_data – the data to pass to callback

new_for_address(address: str, flags: DBusConnectionFlags, observer: DBusAuthObserver | None = None, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

Asynchronously connects and sets up a D-Bus client connection for exchanging D-Bus messages with an endpoint specified by address which must be in the D-Bus address format.

This constructor can only be used to initiate client-side connections - use new() if you need to act as the server. In particular, flags cannot contain the AUTHENTICATION_SERVER, AUTHENTICATION_ALLOW_ANONYMOUS or AUTHENTICATION_REQUIRE_SAME_USER flags.

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

If observer is not None it may be used to control the authentication process.

This is an asynchronous failable constructor. See new_for_address_sync() for the synchronous version.

Added in version 2.26.

Parameters:

address – a D-Bus address
flags – flags describing how to make the connection
observer – a DBusAuthObserver or None
cancellable – a Cancellable or None
callback – a AsyncReadyCallback to call when the request is satisfied
user_data – the data to pass to callback

register_object(object_path: str, interface_info: DBusInterfaceInfo, method_call_closure: Callable[[...], Any] | None = None, get_property_closure: Callable[[...], Any] | None = None, set_property_closure: Callable[[...], Any] | None = None) → int

Registers callbacks for exported objects at object_path with the D-Bus interface that is described in interface_info.

Calls to functions in vtable (and user_data_free_func) will happen in the [thread-default main context][g-main-context-push-thread-default] of the thread you are calling this method from.

Note that all Variant values passed to functions in vtable will match the signature given in interface_info - if a remote caller passes incorrect values, the org.freedesktop.DBus.Error.InvalidArgs is returned to the remote caller.

Additionally, if the remote caller attempts to invoke methods or access properties not mentioned in interface_info the org.freedesktop.DBus.Error.UnknownMethod resp. org.freedesktop.DBus.Error.InvalidArgs errors are returned to the caller.

It is considered a programming error if the DBusInterfaceGetPropertyFunc function in vtable returns a Variant of incorrect type.

If an existing callback is already registered at object_path and interface_name, then error is set to EXISTS.

GDBus automatically implements the standard D-Bus interfaces org.freedesktop.DBus.Properties, org.freedesktop.DBus.Introspectable and org.freedesktop.Peer, so you don’t have to implement those for the objects you export. You can implement org.freedesktop.DBus.Properties yourself, e.g. to handle getting and setting of properties asynchronously.

Note that the reference count on interface_info will be incremented by 1 (unless allocated statically, e.g. if the reference count is -1, see ref()) for as long as the object is exported. Also note that vtable will be copied.

See this [server][gdbus-server] for an example of how to use this method.

Added in version 2.26.

Parameters:

object_path – the object path to register at
interface_info – introspection data for the interface
method_call_closure
get_property_closure
set_property_closure

register_subtree(object_path: str, vtable: DBusSubtreeVTable, flags: DBusSubtreeFlags, user_data: None, user_data_free_func: Callable[[None], None]) → int

Registers a whole subtree of dynamic objects.

The enumerate and introspection functions in vtable are used to convey, to remote callers, what nodes exist in the subtree rooted by object_path.

When handling remote calls into any node in the subtree, first the enumerate function is used to check if the node exists. If the node exists or the DISPATCH_TO_UNENUMERATED_NODES flag is set the introspection function is used to check if the node supports the requested method. If so, the dispatch function is used to determine where to dispatch the call. The collected DBusInterfaceVTable and gpointer will be used to call into the interface vtable for processing the request.

All calls into user-provided code will be invoked in the [thread-default main context][g-main-context-push-thread-default] of the thread you are calling this method from.

If an existing subtree is already registered at object_path or then error is set to EXISTS.

Note that it is valid to register regular objects (using register_object()) in a subtree registered with register_subtree() - if so, the subtree handler is tried as the last resort. One way to think about a subtree handler is to consider it a fallback handler for object paths not registered via register_object() or other bindings.

Note that vtable will be copied so you cannot change it after registration.

See this [server][gdbus-subtree-server] for an example of how to use this method.

Added in version 2.26.

Parameters:

object_path – the object path to register the subtree at
vtable – a DBusSubtreeVTable to enumerate, introspect and dispatch nodes in the subtree
flags – flags used to fine tune the behavior of the subtree
user_data – data to pass to functions in vtable
user_data_free_func – function to call when the subtree is unregistered

remove_filter(filter_id: int) → None

Removes a filter.

Note that since filters run in a different thread, there is a race condition where it is possible that the filter will be running even after calling remove_filter(), so you cannot just free data that the filter might be using. Instead, you should pass a DestroyNotify to add_filter(), which will be called when it is guaranteed that the data is no longer needed.

Added in version 2.26.

Parameters:: filter_id – an identifier obtained from add_filter()

send_message(message: DBusMessage, flags: DBusSendMessageFlags) → tuple[bool, int]

Asynchronously sends message to the peer represented by connection.

Unless flags contain the PRESERVE_SERIAL flag, the serial number will be assigned by connection and set on message via set_serial(). If out_serial is not None, then the serial number used will be written to this location prior to submitting the message to the underlying transport. While it has a volatile qualifier, this is a historical artifact and the argument passed to it should not be volatile.

If connection is closed then the operation will fail with CLOSED. If message is not well-formed, the operation fails with INVALID_ARGUMENT.

See this [server][gdbus-server] and [client][gdbus-unix-fd-client] for an example of how to use this low-level API to send and receive UNIX file descriptors.

Note that message must be unlocked, unless flags contain the PRESERVE_SERIAL flag.

Added in version 2.26.

Parameters:

message – a DBusMessage
flags – flags affecting how the message is sent

send_message_with_reply(message: DBusMessage, flags: DBusSendMessageFlags, timeout_msec: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → int

Asynchronously sends message to the peer represented by connection.

If connection is closed then the operation will fail with CLOSED. If cancellable is canceled, the operation will fail with CANCELLED. If message is not well-formed, the operation fails with INVALID_ARGUMENT.

This is an asynchronous method. When the operation is finished, callback will be invoked in the [thread-default main context][g-main-context-push-thread-default] of the thread you are calling this method from. You can then call send_message_with_reply_finish() to get the result of the operation. See send_message_with_reply_sync() for the synchronous version.

Note that message must be unlocked, unless flags contain the PRESERVE_SERIAL flag.

See this [server][gdbus-server] and [client][gdbus-unix-fd-client] for an example of how to use this low-level API to send and receive UNIX file descriptors.

Added in version 2.26.

Parameters:

message – a DBusMessage
flags – flags affecting how the message is sent
timeout_msec – the timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout
cancellable – a Cancellable or None
callback – a AsyncReadyCallback to call when the request is satisfied or None if you don’t care about the result
user_data – The data to pass to callback

send_message_with_reply_finish(res: AsyncResult) → DBusMessage

Finishes an operation started with send_message_with_reply().

Note that error is only set if a local in-process error occurred. That is to say that the returned DBusMessage object may be of type ERROR. Use to_gerror() to transcode this to a Error.

See this [server][gdbus-server] and [client][gdbus-unix-fd-client] for an example of how to use this low-level API to send and receive UNIX file descriptors.

Added in version 2.26.

Parameters:: res – a AsyncResult obtained from the AsyncReadyCallback passed to send_message_with_reply()

send_message_with_reply_sync(message: DBusMessage, flags: DBusSendMessageFlags, timeout_msec: int, cancellable: Cancellable | None = None) → tuple[DBusMessage, int]

Synchronously sends message to the peer represented by connection and blocks the calling thread until a reply is received or the timeout is reached. See send_message_with_reply() for the asynchronous version of this method.

Note that error is only set if a local in-process error occurred. That is to say that the returned DBusMessage object may be of type ERROR. Use to_gerror() to transcode this to a Error.

See this [server][gdbus-server] and [client][gdbus-unix-fd-client] for an example of how to use this low-level API to send and receive UNIX file descriptors.

Note that message must be unlocked, unless flags contain the PRESERVE_SERIAL flag.

Added in version 2.26.

Parameters:

message – a DBusMessage
flags – flags affecting how the message is sent.
timeout_msec – the timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout
cancellable – a Cancellable or None

set_exit_on_close(exit_on_close: bool) → None

Sets whether the process should be terminated when connection is closed by the remote peer. See DBusConnection:exit-on-close for more details.

Note that this function should be used with care. Most modern UNIX desktops tie the notion of a user session with the session bus, and expect all of a user’s applications to quit when their bus connection goes away. If you are setting exit_on_close to False for the shared session bus connection, you should make sure that your application exits when the user session ends.

Added in version 2.26.

Parameters:: exit_on_close – whether the process should be terminated when connection is closed by the remote peer

Subscribes to signals on connection and invokes callback whenever the signal is received. Note that callback will be invoked in the [thread-default main context][g-main-context-push-thread-default] of the thread you are calling this method from.

If connection is not a message bus connection, sender must be None.

If sender is a well-known name note that callback is invoked with the unique name for the owner of sender, not the well-known name as one would expect. This is because the message bus rewrites the name. As such, to avoid certain race conditions, users should be tracking the name owner of the well-known name and use that when processing the received signal.

If one of MATCH_ARG0_NAMESPACE or MATCH_ARG0_PATH are given, arg0 is interpreted as part of a namespace or path. The first argument of a signal is matched against that part as specified by D-Bus.

If user_data_free_func is non-None, it will be called (in the thread-default main context of the thread you are calling this method from) at some point after user_data is no longer needed. (It is not guaranteed to be called synchronously when the signal is unsubscribed from, and may be called after connection has been destroyed.)

As callback is potentially invoked in a different thread from where it’s emitted, it’s possible for this to happen after signal_unsubscribe() has been called in another thread. Due to this, user_data should have a strong reference which is freed with user_data_free_func, rather than pointing to data whose lifecycle is tied to the signal subscription. For example, if a Object is used to store the subscription ID from signal_subscribe(), a strong reference to that Object must be passed to user_data, and unref() passed to user_data_free_func. You are responsible for breaking the resulting reference count cycle by explicitly unsubscribing from the signal when dropping the last external reference to the Object. Alternatively, a weak reference may be used.

It is guaranteed that if you unsubscribe from a signal using signal_unsubscribe() from the same thread which made the corresponding signal_subscribe() call, callback will not be invoked after signal_unsubscribe() returns.

The returned subscription identifier is an opaque value which is guaranteed to never be zero.

This function can never fail.

Added in version 2.26.

Parameters:

sender – sender name to match on (unique or well-known name) or None to listen from all senders
interface_name – D-Bus interface name to match on or None to match on all interfaces
member – D-Bus signal name to match on or None to match on all signals
object_path – object path to match on or None to match on all object paths
arg0 – contents of first string argument to match on or None to match on all kinds of arguments
flags – DBusSignalFlags describing how arg0 is used in subscribing to the signal
callback – callback to invoke when there is a signal matching the requested data
user_data – user data to pass to callback

signal_unsubscribe(subscription_id: int) → None

Unsubscribes from signals.

Note that there may still be D-Bus traffic to process (relating to this signal subscription) in the current thread-default MainContext after this function has returned. You should continue to iterate the MainContext until the DestroyNotify function passed to signal_subscribe() is called, in order to avoid memory leaks through callbacks queued on the MainContext after it’s stopped being iterated. Alternatively, any idle source with a priority lower than %G_PRIORITY_DEFAULT that was scheduled after unsubscription, also indicates that all resources of this subscription are released.

Added in version 2.26.

Parameters:: subscription_id – a subscription id obtained from signal_subscribe()

start_message_processing() → None: If connection was created with DELAY_MESSAGE_PROCESSING, this method starts processing messages. Does nothing on if connection wasn’t created with this flag or if the method has already been called.

Added in version 2.26.

unexport_action_group(export_id: int) → None

Reverses the effect of a previous call to export_action_group().

It is an error to call this function with an ID that wasn’t returned from export_action_group() or to call it with the same ID more than once.

Added in version 2.32.

Parameters:: export_id – the ID from export_action_group()

unexport_menu_model(export_id: int) → None

Reverses the effect of a previous call to export_menu_model().

It is an error to call this function with an ID that wasn’t returned from export_menu_model() or to call it with the same ID more than once.

Added in version 2.32.

Parameters:: export_id – the ID from export_menu_model()

unregister_object(registration_id: int) → bool

Unregisters an object.

Added in version 2.26.

Parameters:: registration_id – a registration id obtained from register_object()

unregister_subtree(registration_id: int) → bool

Unregisters a subtree.

Added in version 2.26.

Parameters:: registration_id – a subtree registration id obtained from register_subtree()

Properties

class DBusConnection

props.address: str: A D-Bus address specifying potential endpoints that can be used when establishing the connection.

Added in version 2.26.

props.authentication_observer: DBusAuthObserver: A DBusAuthObserver object to assist in the authentication process or None.

Added in version 2.26.

props.capabilities: DBusCapabilityFlags: Flags from the DBusCapabilityFlags enumeration representing connection features negotiated with the other peer.

Added in version 2.26.

props.closed: bool: A boolean specifying whether the connection has been closed.

Added in version 2.26.

props.exit_on_close: bool

A boolean specifying whether the process will be terminated (by calling raise(SIGTERM)) if the connection is closed by the remote peer.

Note that DBusConnection objects returned by bus_get_finish() and bus_get_sync() will (usually) have this property set to True.

Added in version 2.26.

props.flags: DBusConnectionFlags: Flags from the DBusConnectionFlags enumeration.

Added in version 2.26.

props.guid: str

The GUID of the peer performing the role of server when authenticating.

If you are constructing a DBusConnection and pass AUTHENTICATION_SERVER in the DBusConnection:flags property then you must also set this property to a valid guid.

If you are constructing a DBusConnection and pass AUTHENTICATION_CLIENT in the DBusConnection:flags property you will be able to read the GUID of the other peer here after the connection has been successfully initialized.

Note that the D-Bus specification uses the term ‘UUID’ to refer to this, whereas GLib consistently uses the term ‘GUID’ for historical reasons.

Despite its name, the format of DBusConnection:guid does not follow RFC 4122 or the Microsoft GUID format.

Added in version 2.26.

props.stream: IOStream

The underlying IOStream used for I/O.

If this is passed on construction and is a SocketConnection, then the corresponding Socket will be put into non-blocking mode.

While the DBusConnection is active, it will interact with this stream from a worker thread, so it is not safe to interact with the stream directly.

Added in version 2.26.

props.unique_name: str: The unique name as assigned by the message bus or None if the connection is not open or not a message bus connection.

Added in version 2.26.

Signals

class DBusConnection.signals

closed(remote_peer_vanished: bool, error: GError | None = None) → None

Emitted when the connection is closed.

The cause of this event can be

If close() is called. In this case remote_peer_vanished is set to False and error is None.
If the remote peer closes the connection. In this case remote_peer_vanished is set to True and error is set.
If the remote peer sends invalid or malformed data. In this case remote_peer_vanished is set to False and error is set.

Upon receiving this signal, you should give up your reference to connection. You are guaranteed that this signal is emitted only once.

Added in version 2.26.

Parameters:

remote_peer_vanished – True if connection is closed because the remote peer closed its end of the connection
error – a Error with more details about the event or None