gruvi.dbus
– D-BUS Client and Server¶
The gruvi.dbus
module implements a D-BUS client and server.
The implementation uses parts of the txdbus project. A cut down copy of txdbus,
containing only those parts needed by Gruvi, is available as gruvi.txdbus
.
You need this if you are providing a message handler (see below).
Both a client and a server/bus-side implementation are provided. The bus-side implementation is very bare bones and apart from the “Hello” message it does not implement any of the “org.freedestkop.DBus” interface. It also does not implement any message routing. The server side is provided mostly for testing purposes (but it could serve as the basis for a real D-BUS server).
The client side of a D-BUS connection is implemented by DbusClient
and
the server/bus-side by DbusServer
. Both implement a procedural
interface. Messages can be send using e.g. DbusClient.send_message()
or
DbusClient.call_method()
. An object-oriented interface that represents
D-BUS objects as Python objects, like the one txdbus provides, is currently not
available. The procedural interface can be used as a basis for your own
object-oriented interface though.
To receive notifications or to respond to method calls, you need to provide a
message handler to the client or the server constructor. The signature of the
message handler is: message_handler(message, protocol)
. Here, the message
argument is an instance of gruvi.txdbus.DbusMessages
, and the
protocol will be the DbusProtocol
instance for the current
connection.
Message handlers runs in their own fiber, which allows them to call into switchpoints. There is one fiber for every connection.
Usage example:
client = gruvi.DbusClient()
client.connect('session')
result = client.call_method('org.freedesktop.DBus', '/org/freedesktop/DBus',
'org.freedesktop.DBus', 'ListNames')
for name in result[0]:
print('Name: {}'.format(name))
-
exception
DbusError
¶ Exception that is raised in case of D-BUS protocol errors.
-
exception
DbusMethodCallError
(method, reply)¶ Exception that is raised when a error reply is received for a D-BUS method call.
-
class
DbusProtocol
(message_handler=None, server_side=False, server_guid=None, timeout=None)¶ D-BUS Protocol.
-
switchpoint
get_unique_name
()¶ Return the unique name of the D-BUS connection.
-
switchpoint
send_message
(message)¶ Send a D-BUS message.
The message argument must be
gruvi.txdbus.DbusMessage
instance.
-
switchpoint
call_method
(service, path, interface, method, signature=None, args=None, no_reply=False, auto_start=False, timeout=-1)¶ Call a D-BUS method and wait for its reply.
This method calls the D-BUS method with name method that resides on the object at bus address service, at path path, on interface interface.
The signature and args are optional arguments that can be used to add parameters to the method call. The signature is a D-BUS signature string, while args must be a sequence of python types that can be converted into the types specified by the signature. See the D-BUS specification for a reference on signature strings.
The flags no_reply and auto_start control the NO_REPLY_EXPECTED and NO_AUTO_START flags on the D-BUS message.
The return value is the result of the D-BUS method call. This will be a possibly empty sequence of values.
-
switchpoint
-
class
DbusClient
(message_handler=None, timeout=30)¶ A D-BUS client.
The message_handler argument specifies an optional message handler.
The optional timeout argument specifies a default timeout for protocol operations in seconds.
-
switchpoint
connect
(address='session')¶ Connect to address and wait until the connection is established.
The address argument must be a D-BUS server address, in the format described in the D-BUS specification. It may also be one of the special addresses
'session'
or'system'
, to connect to the D-BUS session and system bus, respectively.
-
protocol
¶ Return the protocol, or
None
if not connected.
-
switchpoint
call_method
(service, path, interface, method, signature=None, args=None, no_reply=False, auto_start=False, timeout=-1)¶ A shorthand for
self.protocol.call_method()
.
-
switchpoint
get_unique_name
()¶ A shorthand for
self.protocol.get_unique_name()
.
-
switchpoint
send_message
(message)¶ A shorthand for
self.protocol.send_message()
.
-
switchpoint
-
class
DbusServer
(message_handler, timeout=30)¶ A D-BUS server.
The message_handler argument specifies the message handler.
The optional timeout argument specifies a default timeout for protocol operations in seconds.
-
switchpoint
listen
(address='session')¶ Start listening on address for new connection.
The address argument must be a D-BUS server address, in the format described in the D-BUS specification. It may also be one of the special addresses
'session'
or'system'
, to connect to the D-BUS session and system bus, respectively.
-
switchpoint