glib.MessageBus¶
-
class
dbus_next.glib.
MessageBus
(bus_address: Optional[str] = None, bus_type: dbus_next.constants.BusType = <BusType.SESSION: 1>, auth: Optional[dbus_next.auth.Authenticator] = None)¶ Bases:
dbus_next.message_bus.BaseMessageBus
The message bus implementation for use with the GLib main loop.
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()
orconnect_sync()
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 ofAuthExternal
.
- Variables
connected (bool) – True if this message bus is expected to be able to send and receive messages.
unique_name (str) – The unique name of the message bus connection. It will be
None
until the message bus connects.
-
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 returnTrue
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.
-
call
(msg: dbus_next.message.Message, reply_notify: Optional[Callable[[Optional[dbus_next.message.Message], Optional[Exception]], None]] = None)¶ Send a method call and asynchronously wait for a reply from the DBus daemon.
- Parameters
msg (
Message
) – The method call message to send.reply_notify (Callable) – A callback that will be called with the reply to this message. May return an
Exception
on connection errors.
-
call_sync
(msg: dbus_next.message.Message) → Optional[dbus_next.message.Message]¶ Send a method call and synchronously wait for a reply from the DBus daemon.
- Parameters
msg (
Message
) – The method call message to send.- Returns
A message in reply to the message sent. If the message does not expect a reply based on the message flags or type, returns
None
immediately.- Return type
- Raises
DBusError
- If the service threw an error for the method call or returned an invalid result.Exception
- If a connection error occurred.
-
connect
(connect_notify: Optional[Callable[[dbus_next.glib.message_bus.MessageBus, Optional[Exception]], None]] = None)¶ Connect this message bus to the DBus daemon.
This method or the synchronous version must be called before the message bus can be used.
- Parameters
connect_notify – A callback that will be called with this message bus. May return an
Exception
on connection errors orAuthError
on authorization errors.
-
connect_sync
() → dbus_next.glib.message_bus.MessageBus¶ Connect this message bus to the DBus daemon.
This method or the asynchronous version must be called before the message bus can be used.
- Returns
This message bus for convenience.
- Return type
- Raises
AuthError
- If authorization to the DBus daemon failed.Exception
- If there was a connection error.
-
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: dbus_next.introspection.Node) → dbus_next.glib.proxy_object.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 orElementTree
) – 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
- 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.
-
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 aNode
.
- Raises
InvalidObjectPathError
- If the given object path is not valid.InvalidBusNameError
- If the given bus name is not valid.
-
introspect_sync
(bus_name: str, path: str) → dbus_next.introspection.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.
- Returns
The introspection data for the name at the path.
- Return type
- 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.
-
next_serial
() → int¶ Get the next serial for this bus. This can be used as the
serial
attribute of aMessage
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 aReleaseNameReply
.
- Raises
InvalidBusNameError
- If the given bus name is not valid.
-
release_name_sync
(name: str) → dbus_next.constants.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
- 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[[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 aRequestNameReply
.
- Raises
InvalidBusNameError
- If the given bus name is not valid.
-
request_name_sync
(name: str, flags: dbus_next.constants.NameFlag = <NameFlag.NONE: 0>) → dbus_next.constants.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
- 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: dbus_next.message.Message)¶ 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. IfNone
, unexport every interface on the path.
- Raises
InvalidObjectPathError
- If the given object path is not valid.