BaseMessageBus

class dbus_next.message_bus.BaseMessageBus(bus_address: Optional[str] = None, bus_type: dbus_next.constants.BusType = <BusType.SESSION: 1>, ProxyObject: Optional[Type[dbus_next.proxy_object.BaseProxyObject]] = None)

An abstract class to manage a connection to a DBus message bus.

The message bus class is the entry point into all the features of the library. It sets up a connection to the DBus daemon and exposes an interface to send and receive messages and expose services.

This class is not meant to be used directly by users. For more information, see the documentation for the implementation of the message bus you plan to use.

Parameters

  • bus_type (BusType) – The type of bus to connect to. Affects the search path for the bus address.

  • bus_address (str) – A specific bus address to connect to. Should not be used under normal circumstances.

  • ProxyObject (Type[BaseProxyObject]) – The proxy object implementation for this message bus. Must be passed in by an implementation that supports the high-level client.

Variables

  • unique_name (str) – The unique name of the message bus connection. It will be None until the message bus connects.

  • connected (bool) – True if this message bus is expected to be able to send and receive messages.

add_message_handler(handler: Callable[[dbus_next.message.Message], Optional[Union[dbus_next.message.Message, bool]]])

Add a custom message handler for incoming messages.

The handler should be a callable that takes a Message. If the message is a method call, you may return another Message as a reply and it will be marked as handled. You may also return True to mark the message as handled without sending a reply.

Parameters

handler (Callable or None) – A handler that will be run for every message the bus connection received.

disconnect()

Disconnect the message bus by closing the underlying connection asynchronously.

All pending and future calls will error with a connection error.

export(path: str, interface: dbus_next.service.ServiceInterface)

Export the service interface on this message bus to make it available to other clients.

Parameters

  • path (str) – The object path to export this interface on.

  • interface (ServiceInterface) – The service interface to export.

Raises

  • InvalidObjectPathError - If the given object path is not valid.

  • ValueError - If an interface with this name is already exported on the message bus at this path

get_proxy_object(bus_name: str, path: str, introspection: Union[dbus_next.introspection.Node, str, xml.etree.ElementTree.Element]) → dbus_next.proxy_object.BaseProxyObject

Get a proxy object for the path exported on the bus that owns the name. The object is expected to export the interfaces and nodes specified in the introspection data.

This is the entry point into the high-level client.

Parameters

  • bus_name (str) – The name on the bus to get the proxy object for.

  • path (str) – The path on the client for the proxy object.

  • introspection (Node or str or ElementTree) – XML introspection data used to build the interfaces on the proxy object.

Returns

A proxy object for the given path on the given name.

Return type

BaseProxyObject

Raises
introspect(bus_name: str, path: str, callback: Callable[[Optional[dbus_next.introspection.Node], Optional[Exception]], None])

Get introspection data for the node at the given path from the given bus name.

Calls the standard org.freedesktop.DBus.Introspectable.Introspect on the bus for the path.

Parameters

  • bus_name (str) – The name to introspect.

  • path (str) – The path to introspect.

  • callback (Callable) – A callback that will be called with the introspection data as a Node.

Raises
next_serial() → int

Get the next serial for this bus. This can be used as the serial attribute of a Message to manually handle the serial of messages.

Returns

The next serial for the bus.

Return type

int

release_name(name: str, callback: Optional[Callable[[Optional[dbus_next.constants.ReleaseNameReply], Optional[Exception]], None]] = None)

Request that this message bus release the given name.

Parameters

  • name (str) – The name to release.

  • callback (Callable) – A callback that will be called with the reply of the release request as a ReleaseNameReply.

Raises
remove_message_handler(handler: Callable[[dbus_next.message.Message], Optional[Union[dbus_next.message.Message, bool]]])

Remove a message handler that was previously added by add_message_handler().

Parameters

handler (Callable) – A message handler.

request_name(name: str, flags: dbus_next.constants.NameFlag = <NameFlag.NONE: 0>, callback: Optional[Callable[[Optional[dbus_next.constants.RequestNameReply], Optional[Exception]], None]] = None)

Request that this message bus owns the given name.

Parameters

  • name (str) – The name to request.

  • flags (NameFlag) – Name flags that affect the behavior of the name request.

  • callback (Callable) – A callback that will be called with the reply of the request as a RequestNameReply.

Raises
send(msg: dbus_next.message.Message) → None

Asynchronously send a message on the message bus.

Parameters

msg (Message) – The message to send.

unexport(path: str, interface: Optional[Union[dbus_next.service.ServiceInterface, str]] = None)

Unexport the path or service interface to make it no longer available to clients.

Parameters

  • path (str) – The object path to unexport.

  • interface (ServiceInterface or str or None) – The interface instance or the name of the interface to unexport. If None, unexport every interface on the path.

Raises