D-Bus的规范中提供了一系列的标准接口，绝大多数有D-Bus接口的系统调用都会实现这些标准接口，这些标准接口中包括D-Bus的自省(Introspection)机制，自省机制可以让我们通过一个标准接口了解一个D-Bus服务的各种方法的调用方法，本文将介绍D-Bus的这些标准接口及实现方式，同时也会介绍如何在D-Bus上提供自有服务，本文附有完整的实例和完整的源代码；本文实例在 Ubuntu 20.04 上编译测试通过，gcc版本号为：9.4.0；本文不适合 Linux 编程的初学者阅读。

1 D-Bus 基本概念

2 D-Bus 的标准接口

  • D-Bus Specification 中定义了一些标准接口(Standard Interface)，有 D-Bus 接口的系统调用都会实现这些标准接口，本节将介绍这些标准接口；

  • 接口：org.freedesktop.DBus.Peer

    • 这个接口下提供两个方法，Ping 和 GetMachineId，定义如下： 
      1
2

      org.freedesktop.DBus.Peer.Ping()
org.freedesktop.DBus.Peer.GetMachineId(out STRING machine_uuid)
    • 调用 Ping 方法没有任何参数，服务端也只需要回复一个空信息(没有参数)即可，不需要添加任何参数；
    • 调用 GetMachineId 方法也没有任何参数，服务端要回复一个字符串参数给客户端，这个字符串应该为当前电脑的 UUID，在 Linux 上，可以使用 /var/lib/dbus/machine-id 或者 /etc/machine-id 文件中的值；
    • 当使用 dbus_connection_register_object_path() 向 D-Bus 注册一个对象路径的消息处理程序时，这两个方法在 D-Bus 中会自动实现，无需自己编程实现；

  • 接口：org.freedesktop.DBus.Introspectable

    • 这个接口下只有一个方法：Introspect，定义如下： 
      1

      org.freedesktop.DBus.Introspectable.Introspect(out STRING xml_data)
    • 调用 Introspect 方法没有任何参数，服务端要返回一个 xml 的字符串，这个字符串定义了对象下所有实现的方法(Method)、属性(Property)和信号(Signal);
    • 这个方法就是 D-Bus 的内省(Introspection)机制，一个对象的实例在实现了这个接口后，客户调用这个接口可以了解这个对象中各个接口的调用方法，调用参数和返回参数；
    • 在 《IPC之十三：使用libdbus通过D-Bus请求系统调用实现域名解析的实例》 和 《IPC之十五：使用libdbus通过D-Bus请求系统调用实现任意DNS记录解析的实例》 都调用了 systemd-resolved 系统调用的 D-Bus 接口，下面命令调用了systemd-resolved 系统调用中内省(Introspection)接口，可以直观地看一下返回的 XML 数据； 
      1
2
3
4

      $ dbus-send --print-reply --system \
> --dest=org.freedesktop.resolve1 \
> /org/freedesktop/resolve1 \
> org.freedesktop.DBus.Introspectable.Introspect
    • dbus-send 是一个非常有用的 D-Bus 命令行工具，使用 man dbus-send 在线手册可以了解其详细使用方法；
    • 这条命令的含义是，在系统总线(--system)上请求一个接口上的方法，总线名称：org.freedesktop.resolve1(--dest)，对象路径：/org/freedesktop/resolve1，接口：org.freedesktop.DBus.Introspectable，方法：Introspect，注意，接口和方法用 “.” 连接；
    • --print-reply 表示需要打印服务端的回复信息；
    • 返回的数据是 XML 格式，在 D-Bus Specification 中，对格式有明确的描述，在刚刚执行的命令中，有两个曾经在前面的文章中使用过的接口，把对这两个方法的定义放在这里； 
       1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

      <node>
    ......
    <interface name="org.freedesktop.resolve1.Manager">
        ......
        <method name="ResolveHostname">
            <arg type="i" direction="in"/>
            <arg type="s" direction="in"/>
            <arg type="i" direction="in"/>
            <arg type="t" direction="in"/>
            <arg type="a(iiay)" direction="out"/>
            <arg type="s" direction="out"/>
            <arg type="t" direction="out"/>
        </method>
        ......
        <method name="ResolveRecord">
            <arg type="i" direction="in"/>
            <arg type="s" direction="in"/>
            <arg type="q" direction="in"/>
            <arg type="q" direction="in"/>
            <arg type="t" direction="in"/>
            <arg type="a(iqqay)" direction="out"/>
            <arg type="t" direction="out"/>
        </method>
        ......
    </interface>
    ......
</node>
    • 其实这个格式很容易理解，不需要更多的解释，“in” 表示输入参数，“out” 表示输出参数，type 后面的字母是 D-Bus 的数据类型定义，在文章 《IPC之十三：使用libdbus通过D-Bus请求系统调用实现域名解析的实例》 中有介绍；
    • 本文的实例中将实现该接口；

  • 接口：org.freedesktop.DBus.Properties

    • 这个接口下有三个方法：Get、Set 和 GetAll：

      1
2
3
4
5
6
7
8

      org.freedesktop.DBus.Properties.Get(in STRING interface_name,
                                    in STRING property_name,
                                    out VARIANT value);
org.freedesktop.DBus.Properties.Set(in STRING interface_name,
                                    in STRING property_name,
                                    in VARIANT value);
org.freedesktop.DBus.Properties.GetAll(in STRING interface_name,
                                       out ARRAY of DICT_ENTRY<STRING,VARIANT> props);

    • 在一个对象实例中，每个接口下可以有一些属性(Properties/Attributes)，这些属性可以是只读的，也可以是可读/写的，这个接口用于操作这些属性；

    • 方法 Get 用于获取单个属性的值，输入参数 interface_name 表示接口名称，property_name表示属性名称，两个参数都是字符串，输出参数为属性值，由于并不清楚该属性值的数据类型，所以其输出参数的数据类型为 VARIANT；

    • 方法 Set 用于设置单个属性的值，这个方法其实就是 Get 方法的逆操作；

    • 方法 GetAll 可以获取某个接口中的所有属性的值，它的输入参数只有一个，interface_name，表示接口名称，因为并不知道会有多少个属性返回，所以输出参数 props 是一个数组，数组中是 DICT_ENTRY，其中的键值对表示属性名称和属性值；

    • 这个接口下还有一个信号：PropertiesChanged：

      1
2
3

      org.freedesktop.DBus.Properties.PropertiesChanged(STRING interface_name,
                                                  ARRAY of DICT_ENTRY<STRING, VARIANT> changed_properties,
                                                  ARRAY<STRING> invalidated_properties);

    • 当一个或者多个属性发生变化时，可以发出这个信号通知连接的客户端；

    • interface_name 为接口名称，changed_properties 为一个 Key-Value 对的数组，每一组 Key-Value 记录着一个变化的属性名称和新的属性值，invalidated_properties 是一个字符串数组，记录已经无效的属性名称；

    • 本文的实例中将实现 Get 和 GetAll 两个方法

  • 接口：org.freedesktop.DBus.ObjectManager

    • 这个接口下有一个方法：GetManagedObjects 
      1
2
3

      org.freedesktop.DBus.ObjectManager.GetManagedObjects(out ARRAY of DICT_ENTRY<OBJPATH, ARRAY 
                                                               of DICT_ENTRY<STRING, ARRAY 
                                                               of DICT_ENTRY<STRING, VARIANT>>> objpath_interfaces_and_properties);
    • 这个方法没有输入参数，输出参数是整个 Objects 树；
    • 本文实例中并没有实现这个方法；

3 D-Bus 注册服务的基本方法

  • 在文章 《IPC之十一：使用D-Bus实现客户端向服务端请求服务的实例》 中的实例，已经可以在 D-Bus 上为客户端提供方法调用的服务，大致的流程如下：

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

    ......
while (dbus_connection_read_write_dispatch(conn, -1)) {
    DBusMessage *message;
    message = dbus_connection_pop_message(conn);
    if (message == NULL) {
        continue;
    }

    ret = dbus_message_get_type(message);
    if (ret != DBUS_MESSAGE_TYPE_METHOD_CALL) {
        dbus_message_unref(message);
        continue;
    }
    if (!dbus_message_is_method_call(message, INTERFACE_NAME, METHOD_NAME)) {
        print_dbus_error(&dbus_error, "Server: dbus_message_is_method_call");
        dbus_message_unref(message);
        continue;
    }
    // codes for providing the service
    ......
}

  • 作为简单的范例，提供一种客户端调用服务端方法的服务当然是可以的，但是在 D-Bus 的编程规范中，发布一个服务应该向 D-Bus 注册一个对象路径(Object Path)的处理程序，其具体步骤如下：

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

    DBusHandlerResult server_message_handler(DBusConnection *conn, DBusMessage *message, void *data) {
    ......
}
const DBusObjectPathVTable server_vtable = {
    .message_function = server_message_handler
};
int main(void) {
    DBusConnection *conn;
    DBusError err;

    dbus_error_init(&err);
    conn = dbus_bus_get(DBUS_BUS_SESSION, &err);
    dbus_bus_request_name(conn, SERVER_BUS_NAME, DBUS_NAME_FLAG_REPLACE_EXISTING , &err);
    // registers the object
    if (!dbus_connection_register_object_path(conn, OBJECT_PATH_NAME, &server_vtable, NULL)) {
        printf("Failed to register an object pth.\n");
        exit(EXIT_FAILURE);
    }
    ......

    return EXIT_SUCCESS;
}

  • 重点是 dbus_connection_register_object_path()，在以前的文章中没有介绍过，其定义如下：

    1
2
3
4

    dbus_bool_t dbus_connection_register_object_path(DBusConnection *connection,
                                                 const char *path,
                                                 const DBusObjectPathVTable *vtable,
                                                 void *user_data);
    • connection 是 dbus_bus_get() 获得的连接；
    • path 是要在 D-Bus 上注册的对象路径(Object Path)，连接(connection)和对象路径(object path)的概念在以前的文章里都有过介绍；
    • 参数 vtable 是这个函数的重点，这个参数的数据类型是 DBusObjectPathVTable，这是一个结构，其定义如下： 
       1
 2
 3
 4
 5
 6
 7
 8
 9
10

      struct DBusObjectPathVTable
{
    DBusObjectPathUnregisterFunction   unregister_function; /**< Function to unregister this handler */
    DBusObjectPathMessageFunction      message_function; /**< Function to handle messages */

    void (* dbus_internal_pad1) (void *); /**< Reserved for future expansion */
    void (* dbus_internal_pad2) (void *); /**< Reserved for future expansion */
    void (* dbus_internal_pad3) (void *); /**< Reserved for future expansion */
    void (* dbus_internal_pad4) (void *); /**< Reserved for future expansion */
};
    • 可以看到这个结构中有用的只有两个字段，message_function 和 unregister_function；
    • message_function 是一个消息处理函数，准备注册的对象下的消息将全部由这个函数处理，unregister_function 用于在取消注册时需要执行的函数，通常用于释放 message_function 可能占用的资源；
    • 在本文的实例中，我们并没有用到 unregister_function 这个字段，因为取消注册时，我们并不需要释放资源；
    • user_data 是在调用 message_function 时传递给这个函数的用户数据，可以是结构、数组或者字符串等任意数据；
    • 再看看 message_function 是如何定义的，message_function 的类型为 DBusObjectPathMessageFunction，其定义如下： 
      1

      typedef DBusHandlerResult(* DBusObjectPathMessageFunction) (DBusConnection *connection, DBusMessage *message, void *user_data);
    • 所以，这个函数要写成下面的样子： 
      1
2
3
4

      DBusHandlerResult server_message_handler(DBusConnection *connection, DBusMessage *message, void *user_data) {
    // Codes for processing messages
    ......
}
    • 这里面的 user_data 就是在注册对象路径时定义的 user_data，D-Bus 在调用这个函数时会把 connection、收到的消息 message 以及 user_data 传递给函数；

  • 注册好对象路径的消息处理函数后，还需要在主程序中建立一个主循环才可以让这个处理函数发挥作用：

    1
2
3
4

    while (dbus_connection_read_write_dispatch(conn, 100)) {
    // main loop
    ......
}

  • 只有运行这个主循环，D-Bus 才会去分发消息，前面注册的消息处理程序才会被调用；

  • 以前文章实例中在调用 dbus_connection_read_write_dispatch()，都是以阻塞方式，即把超时时间设为 -1，上面的代码片段将超时设置为 100 ms，这是通常的做法，因为通常情况下，程序除了处理消息外还需要处理别的事务，在主循环里可以处理其它事务，而在 message_function 中处理消息；

4 实例

  • 源程序：dbus-service.c (点击文件名下载源程序，建议使用UTF-8字符集)演示了 D-Bus 标准接口和服务接口的实现方法；

  • 该程序实现了两个标准接口中的三个方法，加上 D-Bus 自动实现的两个方法，一共实现了三个标准接口下的五个方法，分别是：

    1. 标准接口 org.freedesktop.DBus.Introspectable 下的 Introspect 方法(D-bus 内省机制)；
    2. 标准接口 org.freedesktop.DBus.Properties 下的 Get 方法；
    3. 标准接口 org.freedesktop.DBus.Properties 下的 GetAll 方法；
    4. 标准接口 org.freedesktop.DBus.Peer 下的 Ping 方法；
    5. 标准接口 org.freedesktop.DBus.Peer 下的 GetMachineId 方法；

  • 该程序在自定义的接口(cn.whowin.TestInterface)上实现了三个方法：

    1. Hello 方法：请求参数为一个字符串，该方法在请求参数前面加上 “Hello “，并作为参数回复给客户端；
    2. EmitSignal 方法：收到请求后，该方法将广播一个 “OnEmitSignal” 信号给订阅该信号的客户端；
    3. quit 方法：收到该请求后，服务程序回复给客户端一个空消息(没有参数)，并主动退出程序；

  • 该程序在自定义的接口(cn.whowin.TestInterface)上实现了两个只读属性：Version 和 Author，可以使用标准接口的 Get 或 GetAll 获取属性值；

  • 该程序在自定义的接口(cn.whowin.TestInterface)上实现了一个信号：OnEmitSignal，在收到 EmitSignal 请求后将发送该信号；

  • 编译：gcc -Wall -g dbus-service.c -o dbus-service `pkg-config --libs --cflags dbus-1`

  • 有关 pkg-config --libs --cflags dbus-1 可以参阅文章 《IPC之十一：使用D-Bus实现客户端向服务端请求服务的实例》 中的简要说明；

  • 运行：./dbus-service

  • 测试方法如下，启动两个终端，一个终端上运行 dbus-service 程序，在另一个终端上输入如下命令可以测试本程序的各个方法和属性：

    • 标准接口测试： 
      1
2
3
4
5
6

      $ dbus-send --print-reply --session --dest=cn.whowin.TestDbus /cn/whowin/TestObject org.freedesktop.DBus.Introspectable.Introspect
$ dbus-send --print-reply --session --dest=cn.whowin.TestDbus /cn/whowin/TestObject org.freedesktop.DBus.Properties.Get string:"cn.whowin.TestInterface" string:"Version"
$ dbus-send --print-reply --session --dest=cn.whowin.TestDbus /cn/whowin/TestObject org.freedesktop.DBus.Properties.Get string:"cn.whowin.TestInterface" string:"Author"
$ dbus-send --print-reply --session --dest=cn.whowin.TestDbus /cn/whowin/TestObject org.freedesktop.DBus.Properties.GetAll
$ dbus-send --print-reply --session --dest=cn.whowin.TestDbus /cn/whowin/TestObject org.freedesktop.DBus.Peer.Ping
$ dbus-send --print-reply --session --dest=cn.whowin.TestDbus /cn/whowin/TestObject org.freedesktop.DBus.Peer.GetMachineId
    • 自定义接口测试： 
      1
2
3

      $ dbus-send --print-reply --session --dest=cn.whowin.TestDbus /cn/whowin/TestObject cn.whowin.TestInterface.Hello string:"whowin"
$ dbus-send --print-reply --session --dest=cn.whowin.TestDbus /cn/whowin/TestObject cn.whowin.TestInterface.EmitSignal
$ dbus-send --print-reply --session --dest=cn.whowin.TestDbus /cn/whowin/TestObject cn.whowin.TestInterface.Quit

  • 在自定义接口中，有一个 EmitSignal 方法，服务端收到该方法的请求时，会广播出一个 OnEmitSignal 信号，测试方法如下：

    • 在 1 号终端上运行服务端程序：$ ./dbus-service
    • 在 2 号终端上订阅自定义接口上的信号： 
      1

      $ dbus-monitor "type='signal',sender='cn.whowin.TestDbus',interface='cn.whowin.TestInterface'"
    • 在 3 号终端上请求服务端的 EmitSignal 方法： 
      1

      $ dbus-send --print-reply --session --dest=cn.whowin.TestDbus /cn/whowin/TestObject cn.whowin.TestInterface.EmitSignal
    • 在 2 号终端上可以看到收到了 OnEmitSignal 信号；

  • 使用 gdbus 命令测试内省(Introspection)机制

    1

    $ gdbus introspect --session --dest cn.whowin.TestDbus --object-path /cn/whowin/TestObject

  • 标准接口测试运行动图：

    GIF of testing for gbus-service

欢迎订阅 『进程间通信专栏』

欢迎访问我的博客：https://whowin.cn

email: hengch@163.com

donation