dbus-python 指南

Applications that use D-Bus typically connect to a bus daemon, which forwards messages between the applications. To use D-Bus, you need to create a Bus object representing the connection to the bus daemon.

使用 D-Bus 的应用程序常常连接到一个 bus 服务上，这个服务在应用程序之间传递消息。想要使用 D-Bus ,你需要创建一个 Bus 对象来代表一个到 bus 服务的连接。

There are generally two bus daemons you may be interested in. Each user login session shouldhave a session bus, which is local to that session. It's used to communicate between desktop applications. Connect to the session bus by creating a SessionBus object:

一般你会对两个 bus 服务感兴趣。第一个用户会话 (user login session) 应该有一个会话 bus (session bus)。以那个会话 (session) 来看 session bus 是本地的。想要连接到一个 session bus 可以通过创建一个 SessionBus 对象：

    import dbus

    session_bus = dbus.SessionBus()

The System bus is global and usually started during boot; it's used to communicate with system services like udev, NetworkManager, and the Hardware Abstraction Layer daemon (hald). To connect to the system bus, create a Systembus object:

系统 bus 是全局的，常常在启动 (boot) 的时候运行；它用来与系统服务传递信息，如 udev, NetworkManager 和 the Hardware Abstraction Layer daemon (hald)。想要连接到一个 system bus 可以通过创建一个 SystemBus 对象：

    import dbus

    system_bus = dbus.SystemBus()

Of course, you can connect to both in the same application.

当然，你可以在同一个应用程序里同时连接两个 bus。

D-Bus applications can export objects for other applications'use . To start working with an object in another application, you need to know:

D-Bus 应用程序能够输出对象让其它应用使用。为了能够使用另一个应用程序提供的对象，你需要知道：

To interact with a remote object, you use a proxy object. This is a Python object which acts as a proxy or "stand-in" for the remote object - when you call a method on a proxy object, this causes dbus-python to make a method call on the remote object, passing back any return values from the remote object's method as the return values of the proxy method call.

D-Bus uses interfaces to provide a namespacing mechanism for methods. An interface is a group of related methods and signals (more on signals later), identified by a name which is a series of dot-separated components starting with a reversed domain name. For instance, each NetworkManager object representing a network interface implements the interface org.freedesktop.NetworkManager.Devices, which has methods like getProperties.

Unlike Python, D-Bus is statically typed - each method has a certain signature representing the types of its arguments, and will not accept arguments of other types.

不像 Python , D-Bus 是静态类型 (statically typed) - 每一个方法都有一个代表它们参数类型的标识，并且不接受其它类型的参数。

D-Bus has an introspection mechanism, which dbus-python tries to use to discover the correct argument types. If this succeeds, Python types are converted into the right D-Bus data types automatically, if possible; TypeError is raised if the type is inappropriate.

D-Bus 有一个内省 (introspections) 机省，dbus-python 使用它来发现正确的参数类型。如果内省 (introspections) 成功，Python 类型会被自动的转化成正确的 D-Bus 数据类型，如果可能的话。

If the introspection mechanism fails (or the argument's type is variant - see below), you have to provide arguments of the correct type. dbus-python provides Python types corresponding to the D-Bus data types, and a few native Python types are also converted to D-Bus data types automatically. If you use a type which isn't among these, a TypeError will be raised telling you that dbus-python was unable to guess the D-Bus signature.

如果 introspections 失败 (或者参数的类行是可变的 - 参考下面)，你将不得不提供正确的类型。 dbus-python 提供 Python 类型相当 D-Bus 数据类型，一些天生的 Python 类型也可以自动的转换为 D-Bus 类型。 如果你使用的类型不在其中，一个 TypeError 将会出现来告诉你， dbus-python 不能猜出 D-Bus 的标识。

The following basic data types are supported.

下面的基本数据类型是支持的：

Types marked (*) may be a subclass of either int or long, depending on platform.

标记为(*)的类型是 int 或 long 的子类，平台相关。

(+): D-Bus proxy objects, exported D-Bus service objects and anything else with the special attribute __dbus_object_path__, which must be a string, are converted to their object-path. This might be useful if you're writing an object-oriented API using dbus-python.

If introspection succeeded, dbus-python will also accept:

如果 introspection 成功， dbus-python 将接受：

• for Boolean parameters, any object (converted as if via int(bool(...)))

  对于 Boolean 参数，任何 object (被转换通过 int(bool(...)))

• for byte parameters, a single-character string (converted as if via ord())

  对于 byte 参数，一个单字符串 (single-character string) (被转换通过 ord())

• for byte and integer parameters, any integer (must be in the correct range)

  对于 byte 和 integer 参数，任何 integer (必须在正确的范围内)

• for object-path and signature parameters, any str or unicode subclass (the value must follow the appropriate syntax)

  对于 object-path 和 signature 参数，任何 str 或 unicode subclass (必须有适当的语义)

D-Bus supports four container types: array (a variable-length sequence of the same type), struct (a fixed-length sequence whose members may have different types), dictionary (a mapping from values of the same basic type to values of the same type), and variant (a container which may hold any D-Bus type, including another variant).

If a D-Bus method returns no value, the Python proxy method will return None.

如果 D-Bus 方法没有返回值，那么 Python 代理方法将会返回 None.

If a D-Bus method returns one value, the Python proxy method will return that value as one of the dbus. types - by default, strings are returned as dbus.String (a subclass of Unicode) and byte arrays are returned as a dbus.Array of dbus.Byte.

如果 D-Bus 方法返回一个值，那么 Python 代理方法将会以 dbus.types 之一返回那个值 - 默认情况下，字符串作为 dbus.String (Unicode 的子类)，字节数组作为 dbus.Array of dbus.Byte 。

If a D-Bus method returns multiple values, the Python proxy method will return a tuple containing those values.

如果 D-Bus 方法返回多个值，那么 Python 代理方法会返回一个元组包含这些值。

If you want strings returned as dbus.UTF8String (a subclass of str) pass the keyword parameter utf8_strings=True to the proxy method.

如果你想要字符串作为 dbus.UTF8String (str 的子类) 传递关键词参数 utf8_strings=True 到代理方法。

If you want byte arrays returned as dbus.ByteArray (also a subclass of str - in practice, this is often what you want) pass the keyword parameter byte_arrays=True to the proxy method.

如果你要字节数组作为 dbus.ByteArray (也是 str 的子类 - 实践中，它常常是你想要的)传递关键词参数 byte_arrays=True 到代理方法。

Asynchronous (non-blocking) method calls allow multiple method calls to be in progress simultaneously, and allow your application to do other work while it's waiting for the results. To make asynchronous calls, you first need an event loop or "main loop".

异步(非阻塞)方法调用允许同时有多个方法正在调用，允许你的应用在等待结果的时候可以做一些其它的工作。为了使用异步调用，你首先需要一个事件循环或 "main loop"。

Currently, the only main loop supported by dbus-python is GLib.

目前，dbus-python 唯一支持的 main loop 是 GLib 。

dbus-python has a global default main loop, which is the easiest way to use this functionality. To arrange for the GLib main loop to be the default, use:

dbus-python 有一个全局默认的 main loop ，它是使用这个功能最容易的方法。把 GLib main loop 设置为默认，使用:

from dbus.mainloop.glib import DBusGMainLoop

DBusGMainLoop(set_as_default=True)

You must do this before connecting to the bus.

你必须要连接 bus 之前做些工作。

Actually starting the main loop is as usual for pygobject:

实际上常常为 pygobject 启动 main loop。

import gobject

loop = gobject.MainLoop()
loop.run()

While loop.run() is executing, GLib will run your callbacks when appropriate. To stop, call loop.quit().

当 loop.run() 在运行， GLib 将会在适当的时候运行你的回调函数。调用 loop.quit() 停止。

You can also set a main loop on a per-connection basis, by passing a main loop to the Bus constructor:

你可以在每一个连接的基础上设置一个 main loop，通过传递一个 main loop 到 Bus 构造函数。

import dbus
from dbus.mainloop.glib import DBusGMainLoop

dbus_loop = DBusGMainLoop()

bus = dbus.SessionBus(mainloop=dbus_loop)

This isn't very useful until we support more than one main loop, though.

这不是非常有用，除非我们支持多个 main loop 。

In versions of dbus-python prior to 0.80, the way to set GLib as the default main loop was:

在 dbus-python 0.80 之前的版本里，设置 GLib 作为默认 main loop 的方法是:

import dbus.glib

Executing that import statement would automatically load the GLib main loop and make this the default. This is now deprecated, since it's highly non-obvious, but may be useful if you want to write or understand backwards-compatible code.

执行那个 import 语句将会自动的加载 GLib main loop 并设置它为默认。不赞成使用它，因为它是高不可见的，但是如果你想写或者理解向后兼容的代码是有用的。

PyQt v4.2 and later includes support for integrating dbus-python with the Qt event loop. To connect D-Bus to this main loop, call dbus.mainloop.qt.DBusQtMainLoop instead of dbus.mainloop.glib.DBusGMainLoop. Otherwise the Qt loop is used in exactly the same way as the GLib loop.

PyQt v4.2 或更新的版本支持 Qt 事情循环。调用 dbus.mainloop.qt.DbusQtMainLoop 代替 dbus.mainloop.glib.DBusGMainLoop 来连接 D-Bus。否则 Qt loop 的使用将与 GLib loop 完全相同。

To make a call asynchronous, pass two callables as keyword arguments reply_handler and error_handler to the proxy method. The proxy method will immediately return None. At some later time, when the event loop is running, one of these will happen: either

通过传递两个可调用 (callables) 的关键词参数 reply_handler 和 error_handler 到 proxy method 来生成一个异步调用。proxy method 将会立即返回 None。一段时间后，当事件循环执行时，它们中的一个将会发生:

• the reply_handler will be called with the method's return values as arguments; or

  reply_handler 将会被调用，它的参数是上面方法的返回值。

• the error_handler will be called with one argument, an instance of DBusException representing a remote exception.

  error_handler 将被调用，它的参数是一个代表远程异常的 DBusException 的一个实例。

examples/example-async-client.py makes asynchronous method calls to the service provided by examples/example-service.py which return either a value or an exception. As for examples/example-client.py, you need to run examples/example-service.py in the background or in another shell first.

examples/example-async-client.py 制作异步方法调用 example-service.py 提供的服务，这个方法返回一值或一个异常。就像 examples/example-client.py，你需要先在后台或另一个 shell 中运行 examples/example-service.py。

To receive signals, the Bus needs to be connected to an event loop - see section Setting up an event loop. Signals will only be received while the event loop is running.

为了收到一个信号，Bus 需要被连接到一个事件循环 - 参考设置事件循环那章。信号只在事件循环运行的时候才能收到。

To respond to signals, you can use the add_signal_receiver method on Bus objects. This arranges for a callback to be called when a matching signal is received, and has the following arguments:

为了对信息产生响应，你要在 Bus object 上使用 add_signal_receiver 方法。当一个匹配的信号收到后，安排好的回调函数将被调用，传入以后参数：

• a callable (the handler_function) which will be called by the event loop when the signal is received - its parameters will be the arguments of the signal

  当收到信号时，一个可调函数 (callable) (the handler_fucntion) 将会被事件循环调用 - 它的参数是信息的参数。

• the signal name, signal_name: here None (the default) matches all names

  信号名称，signal_name: 这里为 None (默认) 则匹配所有名称。

• the D-Bus interface, dbus_interface: again None is the default, and matches all interfaces

  D-Bus 接口， dbus_interface: None 是默认的，匹配所有接口。

• a sender bus name (well-known or unique), bus_name: None is again the default, and matches all senders. Well-known names match signals from whatever application is currently the primary owner of that well-known name.

  发送者的 bus 名称 (well-known 或 unique)，bus_name: None是默认的，匹配所有发送者。Well-known 名称匹配来自当前拥有那个 well-known 名称的应用程序的信号，无论应用程序是谁。

• a sender object path, path: once again None is the default and matches all object paths

  一个发送者的 object path，path: None 是默认的，匹配所有 object paths，

add_signal_receiver also has keyword arguments utf8_strings and byte_arrays which influence the types used when calling the handler function, in the same way as the byte_arrays and utf8_strings options on proxy methods.

add_signal_receiver 也有关键词参数 utf8_strings 和 byte_arrays，当调用 handler fucntion时，它们影响使用的类型。影响的方式与 byte_arrays 和 utf8_strings 选项在 proxy method 上相同。

add_signal_receiver returns a SignalMatch object. Its only useful public API at the moment is a remove method with no arguments, which removes the signal match from the connection.

add_signal_receiver 返回一个 SignalMatch 对像。目前，它唯一有用的公共 API 是一个没有参数移除方法，它用来移除从连接上匹配的连接。

You can also arrange for more information to be passed to the handler function. If you pass the keyword arguments sender_keyword, destination_keyword, interface_keyword, member_keyword or path_keyword to the connect_to_signal method, the appropriate part of the signal message will be passed to the handler function as a keyword argument: for instance if you use

你也可以安排更多的信息传递给处理函数。如果你传递了关键词参数 sender_keyword, destination_keyword, interface_keyword, member_keyword 或 path_keyword 到 connect_to_signal 方法，信号消息适当的部分将会作为关键词参数被传递给处理函数:例如，如果你

def handler(sender=None):
    print "got signal from %r" % sender

iface.connect_to_signal("Hello", handler, sender_keyword='sender')

and a signal Hello with no arguments is received from com.example.Foo, the handler function will be called with sender='com.example.Foo'.

一个来自 com.example.Foo 的没有参数的 Hello 信号将会被收到，处理函数将会被调用，它的参数 sender='com.example.Foo'。

If there are keyword parameters for the form argn where n is a small non-negative number, their values must be unicode objects or UTF-8 strings. The handler will only be called if that argument of the signal (numbered from zero) is a D-Bus string (in particular, not an object-path or a signature) with that value.

如果有关键词的格式是 argn，其中 n 是一个小的非负数，它们的值必须是 unicode 对象 或 UTF-8 字符串。(后面理不清)

Proxy objects have a special method connect_to_signal which arranges for a callback to be called when a signal is received from the corresponding remote object. The parameters are:

Proxy 对象有一个特殊的方法 connect_to_signal ，当收到一个来自相应远程对象的信号时， connect_to_signal 将安排一个回调函数被调用。

• the name of the signal

  信号名称

• a callable (the handler function) which will be called by the event loop when the signal is received - its parameters will be the arguments of the signal

  当收到信号时，一个可调函数 (callable) (the handler_fucntion) 将会被事件循环调用 - 它的参数是信息的参数。

• the handler function, a callable: the same as for add_signal_receiver

  处理函数 (callable): 与 add_signal_receiver 相同

• the keyword argument dbus_interface qualifies the name with its interface

  关键词参数 dbus_interface 限定接口的名称。

dbus.Interface objects have a similar connect_to_signal method, but in this case you don't need the dbus_interface keyword argument since the interface to use is already known.

dbus.Interface 对象有一个相似的 connect_to_signal 方法，但这种情况下，你不需要 dbus_interface 关键词参数，因为使用的接口已经知道了。

The same extra keyword arguments as for add_signal_receiver are also available, and just like add_signal_receiver, it returns a SignalMatch.

对于 add_signal_receiver 而言，同样的关键词参数也是可用的，就像 add_signal_receiver ， 它返回一个 SignalMatch 。

You shouldn't use proxy objects just to listen to signals, since they might activate the relevant service when created, but if you already have a proxy object in order to call methods, it's often convenient to use it to add signal matches too.

你不应该只用 proxy 对象来监听信号，因为当他们创建的时候也许会激活相关的服务，但如果你为了调用方法已经有一个 proxy 对象，使用它添加信号匹配常常很方便。

examples/signal-recipient.py receives signals - it demonstrates general signal matching as well as connect_to_signal. Before running it, you'll need to run examples/signal-emitter.py in the background or in another shell.

examples/signal-recipient.py 接收信号 - 它示范了通用信号的匹配以及 connect_to_signal 。你需要先在后台或另一个 shell 中运行 examples/signal-emitter.py。

FIXME describe BusName - perhaps fix its API first?

FIXME provide exemplary code, put it in examples

Objects made available to other applications over D-Bus are said to be exported. All subclasses of dbus.service.Object are automatically exported.

在 D-Bus 上让另外一个应用程序可用的对像称作导出 (exported)。所有的 dbus.service.Object 的子类是自动被 exported。

To export objects, the Bus needs to be connected to an event loop - see section Setting up an event loop. Exported methods will only be called, and queued signals will only be sent, while the event loop is running.

为了 export 对象， Bus 需要连接到事件循环 - 参考设置事件循环那章。只有在事件循环运行时，导出方法也才会被调用，队列中的信号才会被传递。

To export an object onto the Bus, just subclass dbus.service.Object. Object expects either a BusName or a Bus object, and an object-path, to be passed to its constructor: arrange for this information to be available. For example:

在 Bus 导出一个对象，它仅是 dbus.service.Object 的子集。这个对象期待一个 BusName 或 Bus 对象以及 object-path ，来传递给它的构造函数：为这些要使用的信息做准备。例如：

class Example(dbus.service.Object):
    def __init__(self, object_path):
        dbus.service.Object.__init__(self, dbus.SessionBus(), path)

This object will automatically support introspection, but won't do anything particularly interesting. To fix that, you'll need to export some methods and signals too.

这个对象会自动支持 introspection ，但不做任何特别的事情。为了修正它，你需要导出一些方法和信号。

FIXME also mention dbus.gobject.ExportedGObject once I've written it

To export a method, use the decorator dbus.service.method. For example:

为了导出方法，使用 dbus.service.method 操作，例如:

class Example(dbus.service.Object):
    def __init__(self, object_path):
        dbus.service.Object.__init__(self, dbus.SessionBus(), path)

    @dbus.service.method(dbus_interface='com.example.Sample',
                         in_signature='v', out_signature='s')
    def StringifyVariant(self, variant):
        return str(variant)

The in_signature and out_signature are D-Bus signature strings as described in Data Types.

in_signature 和 out_signature 是 D-Bus 的标识字符串，描述数据的类型。

As well as the keywords shown, you can pass utf8_strings and byte_arrays keyword arguments, which influence the types which will be passed to the decorated method when it's called via D-Bus, in the same way that the byte_arrays and utf8_strings options affect the return value of a proxy method.

像关键词显示的，你可以传递 utf8_string 和 byte_arrays 关键词参数，当你通过 D-Bus 调用方法时，它将影响传递参数的类型。 byte_arrays 和 utf8_strings 选项以同样的方式影响返回值。

You can find a simple example in examples/example-service.py, which we used earlier to demonstrate examples/example-client.py.

你可以找到一个简单的例子 examples/example-service.py ，我们先前用来它来示范 examples/example-client.py 。

The method decorator accepts a sender_keyword keyword argument. If you set that to a string, the unique bus name of the sender will be passed to the decorated method as a keyword argument of that name:

方法描述接受 sender_keyword 关键词参数。如果你把它设置为一个字符串，发送者的唯一 bus 名称将作为一个关键词参数传递到描述方法。

class Example(dbus.service.Object):
    def __init__(self, object_path):
        dbus.service.Object.__init__(self, dbus.SessionBus(), path)

    @dbus.service.method(dbus_interface='com.example.Sample',
                         in_signature='', out_signature='s',
                         sender_keyword='sender')
    def SayHello(self, sender=None):
        return 'Hello, %s!' % sender
        # -> something like 'Hello, :1.1!'

FIXME and also add an example, perhaps examples/example-async-service.py

To export a signal, use the decorator dbus.service.signal; to emit that signal, call the decorated method. The decorated method can also contain code which will be run when called, as usual. For example:

class Example(dbus.service.Object):
    def __init__(self, object_path):
        dbus.service.Object.__init__(self, dbus.SessionBus(), path)

    @dbus.service.signal(dbus_interface='com.example.Sample',
                         signature='us')
    def NumberOfBottlesChanged(self, number, contents):
        print "%d bottles of %s on the wall" % (number, contents)

e = Example('/bottle-counter')
e.NumberOfBottlesChanged(100, 'beer')
# -> emits com.example.Sample.NumberOfBottlesChanged(100, 'beer')
#    and prints "100 bottles of beer on the wall"

The signal will be queued for sending when the decorated method returns - you can prevent the signal from being sent by raising an exception from the decorated method (for instance, if the parameters are inappropriate). The signal will only actually be sent when the event loop next runs.

examples/example-signal-emitter.py emits some signals on demand when one of its methods is called. (In reality, you'd emit a signal when some sort of internal state changed, which may or may not be triggered by a D-Bus method call.)

当发送信号的方法之一被调用， examples/example-signal-emitter.py 会按要求发送一些信号。

Copyright 2006-2007 Collabora Ltd.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.