【BlueZ 】dbus 模块入门：D-Bus 通信的核心封装与基础调用

D-Bus 是 Linux 系统上的进程间通信（IPC）机制，BlueZ 选择基于 D-Bus 构建用户态通信架构的核心原因：

|----------|---------------------------------|
| 优势 | 说明 |
| 标准化 | D-Bus 是 freedesktop.org 标准，广泛支持 |
| 安全模型 | 基于总线权限控制，支持 Polkit 授权 |
| 异步通信 | 支持信号/方法调用/属性变更三种模式 |
| 自动发现 | ObjectManager 支持对象自动枚举 |
| 语言中立 | 任何语言都能通过 libdbus/gdbus 访问 |

---

目录

[一、gdbus 模块架构总览](#一、gdbus 模块架构总览)

二、接口注册机制

三、方法表定义与调用

四、信号表与信号发射

五、属性表与属性管理

六、客户端代理机制

七、消息发送与错误处理

[八、完整实战：BlueZ 客户端调用示例](#八、完整实战：BlueZ 客户端调用示例)

[九、原生 DBus vs BlueZ gdbus 对比](#九、原生 DBus vs BlueZ gdbus 对比)

十、开发规范与常见问题

十一、核心函数索引

十二、总结

---

BlueZ 自带的 gdbus 模块是对原生 libdbus 的二次封装，设计目标：

1. 简化接口：将繁琐的原生 D-Bus API 封装为易用的函数

2. 对象管理：内置对象路径树管理，自动处理注册/注销

3. 属性通知：自动封装属性变更信号发射

4. 线程安全：内置主循环集成，支持异步操作

5. 客户端支持：提供 GDBusProxy/GDBusClient 简化客户端开发

---

一、gdbus 模块架构总览

1.1 模块文件结构

gdbus/
├── gdbus.h      # 核心头文件（所有公开接口）
├── object.c     # 服务端对象管理实现
├── client.c     # 客户端代理实现
├── watch.c      # 监听机制实现
├── polkit.c     # Polkit 安全授权集成
└── mainloop.c   # 主循环集成

1.2 核心数据结构

1.2.1 方法表（MethodTable）

// gdbus.h - 方法表结构
struct GDBusMethodTable {
    const char *name;           // 方法名
    GDBusMethodFunction function;  // 回调函数
    GDBusMethodFlags flags;     // 标志位（异步、废弃、实验等）
    unsigned int privilege;     // 所需权限
    const GDBusArgInfo *in_args;   // 输入参数描述
    const GDBusArgInfo *out_args;  // 输出参数描述
};

1.2.2 信号表（SignalTable）

// gdbus.h - 信号表结构
struct GDBusSignalTable {
    const char *name;       // 信号名
    GDBusSignalFlags flags;  // 标志位
    const GDBusArgInfo *args;  // 参数描述
};

1.2.3 属性表（PropertyTable）

// gdbus.h - 属性表结构
struct GDBusPropertyTable {
    const char *name;           // 属性名
    const char *type;           // 数据类型（D-Bus 签名）
    GDBusPropertyGetter get;    // Getter 回调
    GDBusPropertySetter set;    // Setter 回调
    GDBusPropertyExists exists; // 是否存在回调
    GDBusPropertyFlags flags;   // 标志位
};

1.2.4 参数描述

// gdbus.h - 参数信息
struct GDBusArgInfo {
    const char *name;        // 参数名
    const char *signature;   // D-Bus 类型签名
};

1.3 核心 函数指针 类型

// gdbus.h - 方法回调
typedef DBusMessage * (* GDBusMethodFunction) (DBusConnection *connection,
                    DBusMessage *message, void *user_data);

// gdbus.h - 属性 Getter 回调
typedef gboolean (*GDBusPropertyGetter)(const GDBusPropertyTable *property,
                    DBusMessageIter *iter, void *data);

// gdbus.h - 属性 Setter 回调
typedef void (*GDBusPropertySetter)(const GDBusPropertyTable *property,
            DBusMessageIter *value, GDBusPendingPropertySet id,
            void *data);

二、接口注册机制

2.1 接口注册函数

// gdbus.h - 接口注册声明
gboolean g_dbus_register_interface(DBusConnection *connection,
                    const char *path, const char *name,
                    const GDBusMethodTable *methods,
                    const GDBusSignalTable *signals,
                    const GDBusPropertyTable *properties,
                    void *user_data,
                    GDBusDestroyFunction destroy);

2.2 核心实现解析

// object.c - 接口注册核心实现
gboolean g_dbus_register_interface(DBusConnection *connection,
                    const char *path, const char *name,
                    const GDBusMethodTable *methods,
                    const GDBusSignalTable *signals,
                    const GDBusPropertyTable *properties,
                    void *user_data,
                    GDBusDestroyFunction destroy)
{
    struct generic_data *data;
    
    // 1. 验证对象路径
    if (!dbus_validate_path(path, NULL)) {
        error("Invalid object path: %s", path);
        return FALSE;
    }
    
    // 2. 验证接口名
    if (!dbus_validate_interface(name, NULL)) {
        error("Invalid interface: %s", name);
        return FALSE;
    }
    
    // 3. 获取或创建对象路径节点
    data = object_path_ref(connection, path);
    if (data == NULL)
        return FALSE;
    
    // 4. 检查接口是否已存在
    if (find_interface(data->interfaces, name)) {
        object_path_unref(connection, path);
        return FALSE;
    }
    
    // 5. 添加接口到对象
    if (!add_interface(data, name, methods, signals, properties, 
                user_data, destroy)) {
        object_path_unref(connection, path);
        return FALSE;
    }
    
    // 6. 触发 InterfacesAdded 信号
    emit_interfaces_added(data);
    
    object_path_unref(connection, path);
    
    return TRUE;
}

2.3 BlueZ 实际使用示例

Adapter 接口注册

// src/adapter.c - 适配器接口注册
static gboolean register_adapter(struct btd_adapter *adapter)
{
    DBusConnection *conn = btd_get_dbus_connection();
    
    // 注册 org.bluez.Adapter1 接口
    return g_dbus_register_interface(conn,
                adapter->path,           // 对象路径
                ADAPTER_INTERFACE,        // "org.bluez.Adapter1"
                adapter_methods,         // 方法表
                adapter_signals,         // 信号表
                adapter_properties,      // 属性表
                adapter,                 // user_data
                adapter_unref);          // destroy 回调
}

Device 接口注册

// src/device.c - 设备接口注册
static gboolean register_device(struct btd_device *device)
{
    DBusConnection *conn = btd_get_dbus_connection();
    
    return g_dbus_register_interface(conn,
                device->path,            // 对象路径
                DEVICE_INTERFACE,         // "org.bluez.Device1"
                device_methods,          // 方法表
                device_signals,          // 信号表
                device_properties,       // 属性表
                device,                  // user_data
                device_unref);           // destroy 回调
}

三、方法表定义与调用

3.1 方法表定义规范

使用 BlueZ 提供的宏定义简化方法表创建：

// gdbus.h - 方法定义宏
#define GDBUS_METHOD(_name, _in_args, _out_args, _function) \
    .name = _name, \
    .in_args = _in_args, \
    .out_args = _out_args, \
    .function = _function

#define GDBUS_ASYNC_METHOD(_name, _in_args, _out_args, _function) \
    .name = _name, \
    .in_args = _in_args, \
    .out_args = _out_args, \
    .function = _function, \
    .flags = G_DBUS_METHOD_FLAG_ASYNC

#define GDBUS_NOREPLY_METHOD(_name, _in_args, _out_args, _function) \
    .name = _name, \
    .in_args = _in_args, \
    .out_args = _out_args, \
    .function = _function, \
    .flags = G_DBUS_METHOD_FLAG_NOREPLY

3.2 Adapter 方法表示例

// src/adapter.c - 适配器方法表
static const GDBusMethodTable adapter_methods[] = {
    // StartDiscovery 方法
    { GDBUS_METHOD("StartDiscovery", NULL, NULL,
                adapter_start_discovery) },
    
    // StopDiscovery 方法
    { GDBUS_METHOD("StopDiscovery", NULL, NULL,
                adapter_stop_discovery) },
    
    // StartAdvertising 方法（带参数）
    { GDBUS_METHOD("StartAdvertising",
                GDBUS_ARGS({ "application", "s" }, { "options", "a{sv}" }),
                GDBUS_ARGS({ "advertisement_id", "o" }),
                (GDBusMethodFunction) adapter_start_advertising) },
    
    // RemoveAdvertising 方法
    { GDBUS_METHOD("RemoveAdvertising",
                GDBUS_ARGS({ "advertisement_id", "o" }),
                NULL,
                adapter_remove_advertising) },
    
    { }  // 终止标志
};

3.3 方法回调实现

// src/adapter.c - StartDiscovery 方法实现
static DBusMessage *adapter_start_discovery(DBusConnection *conn,
                    DBusMessage *msg, void *user_data)
{
    struct btd_adapter *adapter = user_data;
    int err;
    
    // 获取参数并执行操作
    err = btd_adapter_start_discovery(adapter);
    if (err < 0)
        return btd_error_failed(msg, err);
    
    // 返回成功回复
    return dbus_message_new_method_return(msg);
}

3.4 参数解析辅助函数

// src/adapter.c - 参数解析示例
static DBusMessage *adapter_start_advertising(DBusConnection *conn,
                    DBusMessage *msg, void *user_data)
{
    struct btd_adapter *adapter = user_data;
    struct btd_adv_client *client;
    const char *application;
    DBusMessageIter iter, dict;
    GError *err = NULL;
    
    // 1. 解析第一个参数（application 路径）
    if (!dbus_message_iter_init(msg, &iter))
        return NULL;
    
    if (dbus_message_iter_get_arg_type(&iter) != DBUS_TYPE_STRING)
        return btd_error_invalid_args(msg);
    
    dbus_message_iter_get_basic(&iter, &application);
    
    // 2. 解析第二个参数（选项字典）
    if (!dbus_message_iter_next(&iter))
        return btd_error_invalid_args(msg);
    
    if (dbus_message_iter_get_arg_type(&iter) != DBUS_TYPE_ARRAY)
        return btd_error_invalid_args(msg);
    
    dbus_message_iter_recurse(&iter, &dict);
    
    // 3. 创建广播客户端
    client = btd_adv_manager_client_new(adapter->adv_manager, application);
    if (!client)
        return btd_error_failed(msg, -ENOMEM);
    
    // 4. 返回结果
    return dbus_message_new_method_return(msg);
}

四、信号表与信号发射

4.1 信号表定义

// gdbus.h - 信号定义宏
#define GDBUS_SIGNAL(_name, _args) \
    .name = _name, \
    .args = _args

#define GDBUS_EXPERIMENTAL_SIGNAL(_name, _args) \
    .name = _name, \
    .args = _args, \
    .flags = G_DBUS_SIGNAL_FLAG_EXPERIMENTAL

4.2 信号表示例

// src/adapter.c - 适配器信号表
static const GDBusSignalTable adapter_signals[] = {
    // DeviceFound 信号
    { GDBUS_SIGNAL("DeviceFound",
                GDBUS_ARGS({ "device", "o" }, { "props", "a{sv}" })) },
    
    // DeviceRemoved 信号
    { GDBUS_SIGNAL("DeviceRemoved",
                GDBUS_ARGS({ "device", "o" })) },
    
    // AdapterRemoved 信号
    { GDBUS_SIGNAL("AdapterRemoved", NULL) },
    
    { }  // 终止标志
};

4.3 信号发射函数

// gdbus.h - 信号发射声明
gboolean g_dbus_emit_signal(DBusConnection *connection,
                const char *path, const char *interface,
                const char *name, int type, ...);

4.4 实际使用示例

// src/adapter.c - 发射 DeviceFound 信号
static void device_found(struct btd_adapter *adapter,
                    const bdaddr_t *bdaddr, uint8_t bdaddr_type)
{
    DBusConnection *conn = btd_get_dbus_connection();
    struct btd_device *device;
    DBusMessageIter iter;
    
    device = btd_adapter_find_device(adapter, bdaddr, bdaddr_type);
    if (!device)
        return;
    
    // 构造参数并发射信号
    g_dbus_emit_signal(conn,
                adapter->path,          // 对象路径
                ADAPTER_INTERFACE,       // 接口名
                "DeviceFound",           // 信号名
                DBUS_TYPE_OBJECT_PATH,   // 参数类型
                &device->path,           // 设备路径
                DBUS_TYPE_INVALID);      // 结束标志
}

五、属性表与属性管理

5.1 属性表定义

// src/adapter.c - 适配器属性表
static const GDBusPropertyTable adapter_properties[] = {
    // Address 属性
    { "Address", "s",
        get_adapter_address, NULL, NULL,
        G_DBUS_PROPERTY_FLAG_DEPRECATED },
    
    // Name 属性
    { "Name", "s",
        get_adapter_name, NULL, NULL },
    
    // Class 属性
    { "Class", "u",
        get_adapter_class, NULL, NULL },
    
    // Powered 属性
    { "Powered", "b",
        get_adapter_powered, set_adapter_powered, NULL },
    
    // Discoverable 属性
    { "Discoverable", "b",
        get_adapter_discoverable, set_adapter_discoverable, NULL },
    
    // UUIDs 属性
    { "UUIDs", "as",
        get_adapter_uuids, NULL, NULL },
    
    { }  // 终止标志
};

5.2 Getter 回调实现

// src/adapter.c - 获取 Powered 属性
static gboolean get_adapter_powered(const GDBusPropertyTable *property,
                    DBusMessageIter *iter, void *data)
{
    struct btd_adapter *adapter = data;
    gboolean powered;
    
    powered = btd_adapter_get_powered(adapter);
    
    // 将值写入 D-Bus 迭代器
    dbus_message_iter_append_basic(iter, DBUS_TYPE_BOOLEAN, &powered);
    
    return TRUE;
}

5.3 Setter 回调实现

// src/adapter.c - 设置 Powered 属性
static void set_adapter_powered(const GDBusPropertyTable *property,
            DBusMessageIter *value, GDBusPendingPropertySet id,
            void *data)
{
    struct btd_adapter *adapter = data;
    gboolean powered;
    int err;
    
    // 读取新值
    dbus_message_iter_get_basic(value, &powered);
    
    // 执行操作
    err = btd_adapter_set_powered(adapter, powered);
    
    // 回复结果
    if (err == 0)
        g_dbus_pending_property_success(id);
    else
        g_dbus_pending_property_error(id,
                    BLUEZ_DBUS_ERROR_FAILED,
                    "Failed to set powered: %d", err);
}

5.4 属性变更通知

// gdbus.h - 属性变更发射
void g_dbus_emit_property_changed(DBusConnection *connection,
                const char *path, const char *interface,
                const char *name);

// src/adapter.c - 属性变更通知示例
static void update_adapter_state(struct btd_adapter *adapter)
{
    DBusConnection *conn = btd_get_dbus_connection();
    
    // 发射 Powered 属性变更信号
    g_dbus_emit_property_changed(conn,
                adapter->path,
                ADAPTER_INTERFACE,
                "Powered");
    
    // 发射 Discoverable 属性变更信号
    g_dbus_emit_property_changed(conn,
                adapter->path,
                ADAPTER_INTERFACE,
                "Discoverable");
}

六、客户端代理机制

6.1 GDBusClient 结构

// client.c - 客户端结构
struct GDBusClient {
    int ref_count;
    DBusConnection *dbus_conn;       // DBus 连接
    char *service_name;              // 服务名
    char *base_path;                 // 基础路径
    char *root_path;                 // 根路径
    guint watch;                     // 服务监听 ID
    guint added_watch;               // 对象添加监听
    guint removed_watch;             // 对象移除监听
    GPtrArray *match_rules;          // 匹配规则
    DBusPendingCall *pending_call;   // 待处理调用
    DBusPendingCall *get_objects_call; // 获取对象调用
    GDBusWatchFunction connect_func; // 连接回调
    GDBusWatchFunction disconn_func; // 断开回调
    gboolean connected;             // 是否已连接
    GDBusMessageFunction signal_func; // 信号回调
    GDBusProxyFunction proxy_added;  // 代理添加回调
    GDBusProxyFunction proxy_removed; // 代理移除回调
    GDBusClientFunction ready;       // 就绪回调
    GDBusPropertyFunction property_changed; // 属性变更回调
    GList *proxy_list;              // 代理列表
};

6.2 GDBusProxy 结构

// client.c - 代理结构
struct GDBusProxy {
    int ref_count;
    GDBusClient *client;            // 所属客户端
    char *obj_path;                 // 对象路径
    char *interface;                // 接口名
    GHashTable *prop_list;           // 属性缓存
    guint watch;                    // 属性监听
    GDBusPropertyFunction prop_func; // 属性变更回调
    GDBusProxyFunction removed_func; // 移除回调
    DBusPendingCall *get_all_call;  // 获取全部属性调用
    gboolean pending;               // 是否在等待中
};

6.3 客户端创建

// gdbus.h - 客户端创建
GDBusClient *g_dbus_client_new(DBusConnection *connection,
                const char *service, const char *path);

// gdbus.h - 客户端创建（扩展版）
GDBusClient *g_dbus_client_new_full(DBusConnection *connection,
                const char *service,
                const char *path,
                const char *root_path);

6.4 客户端创建示例

// 客户端使用示例
void bluetooth_client_init(DBusConnection *conn)
{
    GDBusClient *client;
    
    // 1. 创建客户端
    client = g_dbus_client_new(conn, "org.bluez", "/org/bluez");
    if (!client) {
        fprintf(stderr, "Failed to create D-Bus client\n");
        return;
    }
    
    // 2. 设置连接/断开回调
    g_dbus_client_set_connect_watch(client, on_connected, NULL);
    g_dbus_client_set_disconnect_watch(client, on_disconnected, NULL);
    
    // 3. 设置代理处理回调
    g_dbus_client_set_proxy_handlers(client,
                on_proxy_added,      // 对象添加
                on_proxy_removed,    // 对象移除
                on_property_changed, // 属性变更
                NULL);
    
    // 4. 设置就绪回调
    g_dbus_client_set_ready_watch(client, on_ready, NULL);
}

6.5 代理方法调用

// gdbus.h - 代理方法调用
gboolean g_dbus_proxy_method_call(GDBusProxy *proxy, 
            const char *method,
            GDBusSetupFunction setup,
            GDBusReturnFunction function, 
            void *user_data,
            GDBusDestroyFunction destroy);

// client.c 中的方法调用封装
typedef void (* GDBusSetupFunction) (DBusMessageIter *iter, void *user_data);
typedef void (* GDBusReturnFunction) (DBusMessage *message, void *user_data);

6.6 客户端方法调用示例

// 调用 BlueZ 方法示例
void call_device_method(GDBusProxy *device_proxy)
{
    // 准备参数
    auto_setup = (GDBusSetupFunction) [] (DBusMessageIter *iter, void *data) {
        int32_t timeout = 30;
        dbus_message_iter_append_basic(iter, 
                    DBUS_TYPE_INT32, &timeout);
    };
    
    // 处理返回
    auto_reply = (GDBusReturnFunction) [] (DBusMessage *msg, void *data) {
        DBusError error;
        dbus_error_init(&error);
        
        if (dbus_set_error_from_message(&error, msg)) {
            fprintf(stderr, "Error: %s\n", error.message);
            dbus_error_free(&error);
        } else {
            printf("Method call successful\n");
        }
    };
    
    // 发起调用
    g_dbus_proxy_method_call(device_proxy,
                "ConnectProfile",     // 方法名
                auto_setup,           // 参数准备
                auto_reply,           // 结果处理
                NULL,                 // user_data
                NULL);                // destroy 函数
}

6.7 代理属性操作

// gdbus.h - 代理属性读取
gboolean g_dbus_proxy_get_property(GDBusProxy *proxy, 
            const char *name,
            DBusMessageIter *iter);

// gdbus.h - 代理属性设置
gboolean g_dbus_proxy_set_property_basic(GDBusProxy *proxy,
            const char *name, int type, const void *value,
            GDBusResultFunction function, void *user_data,
            GDBusDestroyFunction destroy);

// 属性读取示例
void read_property(GDBusProxy *proxy)
{
    DBusMessageIter iter;
    gchar *name;
    
    if (!g_dbus_proxy_get_property(proxy, "Name", &iter)) {
        fprintf(stderr, "Failed to get property\n");
        return;
    }
    
    dbus_message_iter_get_basic(&iter, &name);
    printf("Device Name: %s\n", name);
    dbus_free(name);
}

// 属性设置示例
void set_property(GDBusProxy *proxy)
{
    gboolean powered = TRUE;
    
    g_dbus_proxy_set_property_basic(proxy,
                "Powered",              // 属性名
                DBUS_TYPE_BOOLEAN,     // 类型
                &powered,               // 值
                on_set_complete,        // 完成回调
                NULL,                   // user_data
                NULL);                  // destroy
}

七、消息发送与错误处理

7.1 消息发送函数

// gdbus.h - 消息发送
gboolean g_dbus_send_message(DBusConnection *connection, 
            DBusMessage *message);

gboolean g_dbus_send_message_with_reply(DBusConnection *connection,
            DBusMessage *message,
            DBusPendingCall **call, int timeout);

7.2 回复创建函数

// gdbus.h - 创建回复消息
DBusMessage *g_dbus_create_reply(DBusMessage *message, 
            int type, ...);

DBusMessage *g_dbus_create_reply_valist(DBusMessage *message,
            int type, va_list args);

7.3 错误处理函数

// gdbus.h - 创建错误消息
DBusMessage *g_dbus_create_error(DBusMessage *message, 
            const char *name,
            const char *format, ...);

// gdbus.h - 发送错误回复
gboolean g_dbus_send_error(DBusConnection *connection, 
            DBusMessage *message,
            const char *name, const char *format, ...);

// gdbus.h - 待处理错误回复
void g_dbus_pending_error(DBusConnection *connection,
            GDBusPendingReply pending,
            const char *name, const char *format, ...);

7.4 实际使用示例

// src/device.c - 错误处理示例
static DBusMessage *pair_device(DBusConnection *conn,
                DBusMessage *msg, void *user_data)
{
    struct btd_device *device = user_data;
    int err;
    
    // 检查状态
    if (device->bonding)
        return btd_error_already_exists(msg);  // 已存在错误
    
    // 执行操作
    err = btd_adapter_create_bonding(adapter, device, msg);
    if (err < 0)
        return btd_error_failed(msg, err);  // 失败错误
    
    // 创建成功回复
    return dbus_message_new_method_return(msg);
}

7.5 BlueZ 错误辅助函数

// src/error.c - 常用错误定义
DBusMessage *btd_error_failed(DBusMessage *msg, int err);
DBusMessage *btd_error_invalid_args(DBusMessage *msg);
DBusMessage *btd_error_already_exists(DBusMessage *msg);
DBusMessage *btd_error_not_supported(DBusMessage *msg);
DBusMessage *btd_error_not_authorized(DBusMessage *msg);
DBusMessage *btd_error_busy(DBusMessage *msg);
DBusMessage *btd_error_not_ready(DBusMessage *msg);

八、完整实战：BlueZ 客户端调用示例

8.1 适配器操作封装

// bluetooth_client.c - 适配器操作
typedef struct {
    GDBusClient *client;
    GDBusProxy *adapter_proxy;
    DBusConnection *conn;
} BluetoothClient;

// 创建客户端
BluetoothClient *bluetooth_client_new(DBusConnection *conn)
{
    BluetoothClient *bc = g_new0(BluetoothClient, 1);
    bc->conn = conn;
    
    // 创建 GDBus 客户端
    bc->client = g_dbus_client_new(conn, 
                "org.bluez", "/org/bluez");
    
    return bc;
}

// 开启适配器
void bluetooth_client_power_on(BluetoothClient *bc)
{
    GDBusResultFunction on_done;
    
    gboolean powered = TRUE;
    
    on_done = (GDBusResultFunction) 
        [] (const DBusError *error, void *data) {
            if (error && dbus_error_is_set(error))
                fprintf(stderr, "Power on failed: %s\n", error->message);
            else
                printf("Adapter powered on\n");
        };
    
    g_dbus_proxy_set_property_basic(bc->adapter_proxy,
                "Powered", DBUS_TYPE_BOOLEAN, &powered,
                on_done, NULL, NULL);
}

// 开始扫描
void bluetooth_client_start_discovery(BluetoothClient *bc)
{
    GDBusSetupFunction setup;
    GDBusReturnFunction reply;
    
    setup = (GDBusSetupFunction) 
        [] (DBusMessageIter *iter, void *data) {
            // StartDiscovery 无参数
        };
    
    reply = (GDBusReturnFunction) 
        [] (DBusMessage *msg, void *data) {
            DBusError error;
            dbus_error_init(&error);
            
            if (dbus_set_error_from_message(&error, msg)) {
                fprintf(stderr, "Discovery failed: %s\n", error.message);
                dbus_error_free(&error);
            } else {
                printf("Discovery started\n");
            }
        };
    
    g_dbus_proxy_method_call(bc->adapter_proxy,
                "StartDiscovery", setup, reply, NULL, NULL);
}

8.2 设备操作封装

// bluetooth_client.c - 设备操作
typedef struct {
    GDBusProxy *proxy;
    char address[18];
} DeviceInfo;

// 解析设备信息
void on_proxy_added(GDBusProxy *proxy, void *user_data)
{
    DeviceInfo *dev = g_new0(DeviceInfo, 1);
    DBusMessageIter iter;
    gchar *address;
    
    dev->proxy = proxy;
    
    // 获取设备地址
    if (g_dbus_proxy_get_property(proxy, "Address", &iter)) {
        dbus_message_iter_get_basic(&iter, &address);
        snprintf(dev->address, sizeof(dev->address), "%s", address);
        dbus_free(address);
    }
    
    printf("Device discovered: %s\n", dev->address);
}

// 连接设备
void connect_device(DeviceInfo *dev)
{
    GDBusSetupFunction setup;
    GDBusReturnFunction reply;
    
    setup = (GDBusSetupFunction) 
        [] (DBusMessageIter *iter, void *data) {
            // Connect 无参数
        };
    
    reply = (GDBusReturnFunction) 
        [] (DBusMessage *msg, void *data) {
            DBusError error;
            dbus_error_init(&error);
            
            if (dbus_set_error_from_message(&error, msg)) {
                fprintf(stderr, "Connect failed: %s\n", error.message);
                dbus_error_free(&error);
            } else {
                printf("Device connected\n");
            }
        };
    
    g_dbus_proxy_method_call(dev->proxy,
                "Connect", setup, reply, NULL, NULL);
}

// 配对设备
void pair_device(DeviceInfo *dev)
{
    GDBusSetupFunction setup;
    GDBusReturnFunction reply;
    
    setup = (GDBusSetupFunction) 
        [] (DBusMessageIter *iter, void *data) {
            // Pair 无参数
        };
    
    reply = (GDBusReturnFunction) 
        [] (DBusMessage *msg, void *data) {
            DBusError error;
            dbus_error_init(&error);
            
            if (dbus_set_error_from_message(&error, msg)) {
                fprintf(stderr, "Pair failed: %s\n", error.message);
                dbus_error_free(&error);
            } else {
                printf("Device paired\n");
            }
        };
    
    g_dbus_proxy_method_call(dev->proxy,
                "Pair", setup, reply, NULL, NULL);
}

九、原生 DBus vs BlueZ gdbus 对比

9.1 对比表

|----------|------------------------|-------------------------------------|
| 特性 | 原生 libdbus | BlueZ gdbus |
| 接口注册 | 手动处理 introspection | g_dbus_register_interface()自动生成 |
| 方法路由 | 手动 if-else 分发 | 方法表自动路由 |
| 属性管理 | 手动实现 Get/Set Property | 属性表自动处理 |
| 信号发射 | 手动构造消息 | g_dbus_emit_signal()一行调用 |
| 对象管理 | 手动路径树 | 内置 generic_data 树 |
| 属性通知 | 手动发送 PropertiesChanged | g_dbus_emit_property_changed() 自动触发 |
| 客户端 | 手动发送消息 | GDBusProxy 封装方法调用 |
| 类型安全 | 弱类型 | 基于签名的类型检查 |

9.2 原生方式代码示例

// 原生 libdbus 方式（繁琐）
static DBusMessage *handle_message(DBusConnection *conn,
                    DBusMessage *msg, void *user_data)
{
    const char *member;
    
    member = dbus_message_get_member(msg);
    
    if (strcmp(member, "StartDiscovery") == 0) {
        // 手动调用
        return handle_start_discovery(conn, msg, user_data);
    } else if (strcmp(member, "StopDiscovery") == 0) {
        return handle_stop_discovery(conn, msg, user_data);
    }
    // ... 更多 if-else
    
    return dbus_message_new_error(msg,
                DBUS_ERROR_UNKNOWN_METHOD, "Unknown method");
}

9.3 gdbus 方式代码示例

// BlueZ gdbus 方式（简洁）
static const GDBusMethodTable methods[] = {
    { GDBUS_METHOD("StartDiscovery", NULL, NULL, handle_start_discovery) },
    { GDBUS_METHOD("StopDiscovery", NULL, NULL, handle_stop_discovery) },
    // ... 自动路由
    { }
};

// 一行注册
g_dbus_register_interface(conn, path, iface, methods, NULL, NULL, 
            user_data, NULL);

十、开发规范与常见问题

10.1 开发规范

|----------|---------------------------------|
| 规范项 | 说明 |
| 路径规范 | 对象路径必须以 /org/bluez/ 开头 |
| 接口命名 | 使用 org.bluez.* 命名空间 |
| 错误处理 | 必须检查 DBusError 并处理失败情况 |
| 内存管理 | 使用 g_free释放，配合 destroy 回调 |
| 异步操作 | 耗时操作使用 G_DBUS_METHOD_FLAG_ASYNC |
| 类型安全 | 参数签名必须与实际类型匹配 |

10.2 常见问题排查

|-----------------------|--------------|------------------------|
| 问题 | 原因 | 解决方案 |
| Invalid object path | 路径格式错误 | 使用 /org/bluez/... 格式 |
| Invalid interface | 接口名格式错误 | 使用 org.bluez.* 格式 |
| Method not found | 方法表未注册 | 检查方法表是否正确定义 |
| Property read-only | 属性未设置 Setter | 添加 Setter 回调 |
| Signature mismatch | 参数类型不匹配 | 检查 GDBUS_ARGS 签名 |
| Permission denied | 权限不足 | 检查 Polkit 配置 |

10.3 调试技巧

# 1. 使用 dbus-monitor 监控消息
dbus-monitor --system | grep bluez

# 2. 启用 BlueZ 调试日志
bluetoothd -d

# 3. 使用 gdbus 工具调用
gdbus call --session \
    --dest org.bluez \
    --object-path /org/bluez/hci0 \
    --method org.bluez.Adapter1.StartDiscovery

# 4. 使用 D-Fuse 查看 D-Bus 对象
d-feet

# 5. 查看 BlueZ 服务配置
cat /etc/dbus-1/system.d/bluetooth.conf

10.4 性能优化建议

1. 批量属性更新：使用 g_dbus_emit_property_changed_full() 配合 flush标志

2. 异步方法：耗时方法使用异步模式避免阻塞

3. 连接复用：共享 DBusConnection 而非频繁创建

4. 代理缓存：重用 GDBusProxy 避免重复创建

5. 信号节流：高频状态变化时使用节流机制

十一、核心函数索引

11.1 接口管理函数

|----------------------------------|------------------|
| 函数 | 功能 |
| g_dbus_register_interface() | 注册接口到对象路径 |
| g_dbus_unregister_interface() | 注销接口 |
| g_dbus_attach_object_manager() | 附加 ObjectManager |
| g_dbus_detach_object_manager() | 分离 ObjectManager |

11.2 消息处理函数

|-------------------------|--------|
| 函数 | 功能 |
| g_dbus_create_reply() | 创建回复消息 |
| g_dbus_create_error() | 创建错误消息 |
| g_dbus_send_message() | 发送消息 |
| g_dbus_send_error() | 发送错误回复 |
| g_dbus_send_reply() | 发送成功回复 |

11.3 信号与属性函数

|----------------------------------|--------|
| 函数 | 功能 |
| g_dbus_emit_signal() | 发射信号 |
| g_dbus_emit_property_changed() | 发射属性变更 |
| g_dbus_get_properties() | 获取全部属性 |

11.4 客户端函数

|--------------------------------------|--------|
| 函数 | 功能 |
| g_dbus_client_new() | 创建客户端 |
| g_dbus_client_set_proxy_handlers() | 设置代理回调 |
| g_dbus_proxy_new() | 创建代理 |
| g_dbus_proxy_method_call() | 方法调用 |
| g_dbus_proxy_get_property() | 属性读取 |
| g_dbus_proxy_set_property_basic() | 属性设置 |

11.5 数据结构

|----------------------|--------|
| 结构 | 功能 |
| GDBusMethodTable | 方法表 |
| GDBusSignalTable | 信号表 |
| GDBusPropertyTable | 属性表 |
| GDBusArgInfo | 参数信息 |
| GDBusClient | 客户端 |
| GDBusProxy | 代理 |

十二、总结

BlueZ gdbus 模块通过以下核心机制实现了对原生 D-Bus 的优雅封装：

12.1 三大核心表驱动

• 方法表：自动路由方法调用，简化分发逻辑

• 信号表：统一信号声明和发射

• 属性表：自动处理 Get/Set/Notify

12.2 对象管理系统

• 内置对象路径树管理

• 自动处理 InterfacesAdded/Removed 信号

• 支持对象嵌套和层级结构

12.3 客户端代理模型

• GDBusClient：封装服务发现和对象管理

• GDBusProxy：简化方法调用和属性访问

• 自动处理属性变更监听

12.4 开发价值

1. 降低复杂度：减少 60% 以上的 D-Bus 样板代码

2. 提升一致性：统一的接口声明和错误处理

3. 增强可维护性：声明式编程，易于扩展

4. 类型安全：基于签名的类型检查

理解和掌握 BlueZ gdbus 模块，是进行蓝牙应用开发的基础。无论是开发自定义蓝牙服务还是客户端应用，这套封装机制都能显著提高开发效率和代码质量。

---