# aio.MessageBus

class dbus_fast.aio.MessageBus(bus_address: str | None = None, bus_type: BusType = BusType.SESSION, auth: Authenticator | None = None, negotiate_unix_fd: bool = False)

  Bases: `BaseMessageBus`

  The message bus implementation for use with asyncio.

  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.

  You must call `connect()` before using this message bus.

  Parameters:

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

    - bus_address – A specific bus address to connect to. Should not be used under normal circumstances.

    - auth (`Authenticator`) – The authenticator to use, defaults to an instance of `AuthExternal`.

    - negotiate_unix_fd (bool) – Allow the bus to send and receive Unix file descriptors (DBus type ‘h’). This must be supported by the transport.

  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[[Message], Message | bool | None]) → None

    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.

  async call(msg: Message) → Message

    Send a method call and wait for a reply from the DBus daemon.

    Parameters:

      msg (`Message`) – The method call message to send.

    Returns:

      A message in reply to the method call sent.

    Return type:

      `Message`

    Raises:

      - `Exception` - If a connection error occurred.

    Changed in version 3.1.0: Using this to call methods that do not expect a reply or messages that are not a method call is deprecated. Use `send()` instead for those cases.

  async connect() → MessageBus

    Connect this message bus to the DBus daemon.

    This method must be called before the message bus can be used.

    Returns:

      This message bus for convenience.

    Return type:

      `MessageBus`

    Raises:

      - `AuthError` - If authorization to the DBus daemon failed.

      - `Exception` - If there was a connection error.

  disconnect() → None

    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: ServiceInterface) → None

    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: Node) → ProxyObject

    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:

      - `InvalidBusNameError` - If the given bus name is not valid.

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

      - `InvalidIntrospectionError` - If the introspection data for the node is not valid.

  async introspect(bus_name: str, path: str, timeout: float = 30.0, validate_property_names: bool = True) → Node

    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.

      - timeout (float) – The timeout to introspect.

      - validate_property_names (bool) – Whether to validate property names or not.

    Returns:

      The introspection data for the name at the path.

    Return type:

      `Node`

    Raises:

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

      - `InvalidBusNameError` - If the given bus name is not valid.

      - `DBusError` - If the service threw an error for the method call or returned an invalid result.

      - `Exception` - If a connection error occurred.

      - `asyncio.TimeoutError` - Waited for future but time run out.

  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

  async release_name(name: str) → ReleaseNameReply

    Request that this message bus release the given name.

    Parameters:

      name (str) – The name to release.

    Returns:

      The reply to the release request.

    Return type:

      `ReleaseNameReply`

    Raises:

      - `InvalidBusNameError` - If the given bus name is not valid.

      - `DBusError` - If the service threw an error for the method call or returned an invalid result.

      - `Exception` - If a connection error occurred.

  remove_message_handler(handler: Callable[[Message], Message | bool | None]) → None

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

    Parameters:

      handler (`Callable`) – A message handler.

  async request_name(name: str, flags: ~dbus_fast.constants.NameFlag = <NameFlag.NONE: 0>) → RequestNameReply

    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.

    Returns:

      The reply to the name request.

    Return type:

      `RequestNameReply`

    Raises:

      - `InvalidBusNameError` - If the given bus name is not valid.

      - `DBusError` - If the service threw an error for the method call or returned an invalid result.

      - `Exception` - If a connection error occurred.

  send(msg: Message) → Future

    Asynchronously send a message on the message bus.

    Note

    This method may change to a couroutine function in the 1.0 release of the library.

    Parameters:

      msg (`Message`) – The message to send.

    Returns:

      A future that resolves when the message is sent or a connection error occurs.

    Return type:

      `Future`

  unexport(path: str, interface: ServiceInterface | str | None = None) → 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:

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

  async wait_for_disconnect()

    Wait for the message bus to disconnect.

    Returns:

      `None` when the message bus has disconnected.

    Return type:

      `None`

    Raises:

      - `Exception` - If connection was terminated unexpectedly or an internal error occurred in the library.