T-Box D-Bus 客户端 More...

Data Structures
struct	tbox_dbus_param_t
	D-Bus 消息参数 More...
struct	tbox_dbus_handle_map_t
	消息处理映射表项 More...
struct	tbox_dbus_send_info_t
	发送消息描述 More...
struct	tbox_dbus_recv_info_t
	接收消息描述 More...

Macros
#define	TBOX_DBUS_METHOD_RETURN_TIMEOUT_SEC 2U
	方法返回超时时间，单位：秒
#define	DBUS_CHECK_OR_RESULT_WITH_ERROR(tag, expr, result, message, error)
	条件为假时记录错误日志并设置结果后返回。
#define	DBUS_CHECK_RET_OR_RESULT_WITH_MESSAGE(tag, ret, result, message)
	检查返回值是否为 TBOX_OK 并设置结果后返回。
#define	DBUS_CHECK_TYPE_OR_RESULT_WITH_MESSAGE(tag, etype, param, result, message)
	检查类型是否匹配并设置结果后返回。
#define	DBUS_CHECK_TYPE_OR_RETURN_WITH_ERROR(tag, etype, param, message, error)
	检查类型是否匹配并返回错误码。

Typedefs
typedef void(*	tbox_dbus_handler_t) (tbox_dbus_param_t msg_param, tbox_dbus_param_t return_param)
	接收消息处理回调

Enumerations
enum	tbox_dbus_type_t { TBOX_DBUS_TYPE_STRING = DBUS_TYPE_STRING , TBOX_DBUS_TYPE_UINT32 = DBUS_TYPE_UINT32 , TBOX_DBUS_TYPE_INT32 = DBUS_TYPE_INT32 , TBOX_DBUS_TYPE_UINT16 = DBUS_TYPE_UINT16 , TBOX_DBUS_TYPE_INT16 = DBUS_TYPE_INT16 , TBOX_DBUS_TYPE_UINT8 = DBUS_TYPE_BYTE , TBOX_DBUS_TYPE_BOOL = DBUS_TYPE_BOOLEAN , TBOX_DBUS_TYPE_ARRAY = DBUS_TYPE_ARRAY , TBOX_DBUS_TYPE_INVALID = DBUS_TYPE_INVALID }
	D-Bus 参数类型 More...

Functions
int	tbox_dbus_connect (const char *app_name)
	连接 D-Bus 服务
void	tbox_dbus_disconnect (void)
	断开 D-Bus 服务连接
const char *	tbox_dbus_get_connection_name (void)
	获取当前连接的唯一名称
int	tbox_dbus_set_message (DBusMessageIter iter, const tbox_dbus_param_t param)
	向消息迭代器写入一个参数
int	tbox_dbus_send_message_begin (const tbox_dbus_send_info_t send_info, DBusMessage msg, DBusMessageIter iter)
	开始构造并发送 D-Bus 消息（首参数）
int	tbox_dbus_send_message_end (bool is_signal, DBusMessage msg, tbox_dbus_param_t return_param, int32_t timeout)
	完成 D-Bus 消息发送并等待回复
int	tbox_dbus_get_message_begin (DBusMessageIter iter, DBusMessage msg, tbox_dbus_recv_info_t recv_info, int32_t timeout)
	开始接收 D-Bus 消息（首参数）
bool	tbox_dbus_check_next_message (DBusMessageIter *iter)
	检查消息迭代器是否还有下一个参数
int	tbox_dbus_get_message (DBusMessageIter iter, tbox_dbus_param_t param)
	从消息迭代器读取一个参数
int	tbox_dbus_get_message_end (DBusMessage msg, tbox_dbus_param_t return_param)
	完成 D-Bus 消息接收并发送方法返回
int	tbox_dbus_send_message (const tbox_dbus_send_info_t send_info, tbox_dbus_param_t return_param, int32_t timeout)
	发送 D-Bus 消息并等待回复
int	tbox_dbus_set_receive_match (const char *filter)
	添加接收消息匹配规则
int	tbox_dbus_delete_receive_match (const char *filter)
	删除接收消息匹配规则
void	tbox_dbus_free_param (tbox_dbus_param_t *param)
	释放参数中动态分配的内存
void	tbox_dbus_free_message (DBusMessage *msg)
	释放 D-Bus 消息对象
bool	tbox_dbus_check_message_match (DBusMessage msg, bool is_signal, const char module, const char *action)
	检查消息是否匹配指定模块和动作
int	tbox_dbus_send_signal (const char module, const char action, tbox_dbus_param_t *param)
	发送 D-Bus 信号
int	tbox_dbus_call_set (const char dest, const char module, const char action, tbox_dbus_param_t param, uint32_t timeout)
	通过 D-Bus 方法调用执行 set 操作
int	tbox_dbus_call_get (const char dest, const char module, const char action, tbox_dbus_param_t return_param, uint32_t timeout)
	通过 D-Bus 方法调用执行 get 操作
void	tbox_dbus_send_no_reply (const char dest, const char module, const char action, tbox_dbus_param_t param)
	发送无需回复的 D-Bus 方法调用
int	tbox_dbus_recv_no_reply (const char need_module, int32_t timeout, bool need_signal, tbox_dbus_param_t msg_param, char *recv_action, uint32_t recv_action_len)
	接收无需回复的 D-Bus 消息
void	tbox_dbus_handle_message (const tbox_dbus_handle_map_t handle_map, const char need_module, int32_t timeout)
	根据映射表分发并处理接收到的 D-Bus 消息

Detailed Description

T-Box D-Bus 客户端

Macro Definition Documentation

◆ DBUS_CHECK_OR_RESULT_WITH_ERROR

#define DBUS_CHECK_OR_RESULT_WITH_ERROR	(	tag,
		expr,
		result,
		message,
		error )

Value:

    do                                                                                                                 \
    {                                                                                                                  \
        if (!(expr))                                                                                                   \
        {                                                                                                              \
            TBOX_LOGE(tag, message ", check failed: %s in %s at %d", #expr, __FILE__, __LINE__);                       \
            (result)->type          = TBOX_DBUS_TYPE_INT32;                                                            \
            (result)->type_info.i32 = (error);                                                                         \
            return;                                                                                                    \
        }                                                                                                              \
    } while (0)

条件为假时记录错误日志并设置结果后返回。

Parameters

[in]	tag	日志标签。
[in]	expr	待检查的条件表达式。
[in]	result	结果指针。
[in]	message	错误消息。
[in]	error	错误码。

void foo(tbox_dbus_param_t* result)
{
    DBUS_CHECK_OR_RESULT_WITH_ERROR("foo", result != NULL, result, "message", TBOX_ERROR);
    ...
}

◆ DBUS_CHECK_RET_OR_RESULT_WITH_MESSAGE

#define DBUS_CHECK_RET_OR_RESULT_WITH_MESSAGE	(	tag,
		ret,
		result,
		message )

Value:

DBUS_CHECK_OR_RESULT_WITH_ERROR(tag, TBOX_OK == (ret), result, message, (ret))

TBOX_OK

#define TBOX_OK

通用错误码

Definition error.h:22

检查返回值是否为 TBOX_OK 并设置结果后返回。

Parameters

[in]	tag	日志标签。
[in]	ret	返回值。
[in]	result	结果指针。
[in]	message	错误消息。

void foo(tbox_dbus_param_t* result)
{
    DBUS_CHECK_RET_OR_RESULT_WITH_MESSAGE("foo", ret, result, "message");
    ...
}

◆ DBUS_CHECK_TYPE_OR_RESULT_WITH_MESSAGE

#define DBUS_CHECK_TYPE_OR_RESULT_WITH_MESSAGE	(	tag,
		etype,
		param,
		result,
		message )

Value:

    do                                                                                                                 \
    {                                                                                                                  \
        if ((etype) != (param)->type)                                                                                  \
        {                                                                                                              \
            TBOX_LOGE(tag, message ", wrong type(%c), expected(%c)", (param)->type, (etype));                          \
            (result)->type          = TBOX_DBUS_TYPE_INT32;                                                            \
            (result)->type_info.i32 = DBUS_ERROR_REMOTE_WRONG_TYPE;                                                    \
            return;                                                                                                    \
        }                                                                                                              \
    } while (0)

检查类型是否匹配并设置结果后返回。

Parameters

[in]	tag	日志标签。
[in]	etype	期望类型。
[in]	param	参数。
[in]	result	结果指针。
[in]	message	错误消息。

void foo(tbox_dbus_param_t* param, tbox_dbus_param_t* result)
{
    DBUS_CHECK_TYPE_OR_RESULT_WITH_MESSAGE("foo", TBOX_DBUS_TYPE_INT32, param, result, "message");
    ...
}

◆ DBUS_CHECK_TYPE_OR_RETURN_WITH_ERROR

#define DBUS_CHECK_TYPE_OR_RETURN_WITH_ERROR	(	tag,
		etype,
		param,
		message,
		error )

Value:

    do                                                                                                                 \
    {                                                                                                                  \
        if ((etype) != (param)->type)                                                                                  \
        {                                                                                                              \
            TBOX_LOGE(tag, message ", wrong type(%c), expected(%c)", (param)->type, (etype));                          \
            if (TBOX_DBUS_TYPE_STRING == (param)->type)                                                                \
            {                                                                                                          \
                TBOX_LOGE(tag, "error message: %s", (param)->type_info.str);                                           \
                tbox_dbus_free_param(param);                                                                           \
            }                                                                                                          \
            if (TBOX_DBUS_TYPE_ARRAY == (param)->type)                                                                 \
            {                                                                                                          \
                tbox_dbus_free_param(param);                                                                           \
            }                                                                                                          \
            return (error);                                                                                            \
        }                                                                                                              \
    } while (0)

检查类型是否匹配并返回错误码。

Parameters

[in]	tag	日志标签。
[in]	etype	期望类型。
[in]	param	参数。
[in]	message	错误消息。
[in]	error	错误码。

int foo(tbox_dbus_param_t* param)
{
    DBUS_CHECK_TYPE_OR_RETURN_WITH_ERROR("foo", TBOX_DBUS_TYPE_INT32, param, "message", TBOX_ERROR);
    return TBOX_OK;
}

Note: 释放参数中动态分配的内存。

Typedef Documentation

◆ tbox_dbus_handler_t

typedef void(* tbox_dbus_handler_t) (tbox_dbus_param_t *msg_param, tbox_dbus_param_t *return_param)

接收消息处理回调

Parameters

msg_param	接收消息参数
return_param	接收消息返回参数

Enumeration Type Documentation

◆ tbox_dbus_type_t

enum tbox_dbus_type_t

D-Bus 参数类型

Enumerator
TBOX_DBUS_TYPE_STRING	字符串类型
TBOX_DBUS_TYPE_UINT32	无符号 32 位整数类型
TBOX_DBUS_TYPE_INT32	有符号 32 位整数类型
TBOX_DBUS_TYPE_UINT16	无符号 16 位整数类型
TBOX_DBUS_TYPE_INT16	有符号 16 位整数类型
TBOX_DBUS_TYPE_UINT8	无符号 8 位整数类型
TBOX_DBUS_TYPE_BOOL	布尔类型
TBOX_DBUS_TYPE_ARRAY	数组类型
TBOX_DBUS_TYPE_INVALID	无效类型

Function Documentation

◆ tbox_dbus_call_get()

int tbox_dbus_call_get	(	const char *	dest,
		const char *	module,
		const char *	action,
		tbox_dbus_param_t *	return_param,
		uint32_t	timeout )

通过 D-Bus 方法调用执行 get 操作

Parameters

dest	目标服务名
module	模块名
action	动作名
return_param	输出返回参数
timeout	超时时间，单位毫秒

Returns: 0 成功，其他失败

◆ tbox_dbus_call_set()

int tbox_dbus_call_set	(	const char *	dest,
		const char *	module,
		const char *	action,
		tbox_dbus_param_t *	param,
		uint32_t	timeout )

通过 D-Bus 方法调用执行 set 操作

Parameters

dest	目标服务名
module	模块名
action	动作名
param	请求参数
timeout	超时时间，单位毫秒

Returns: 远端返回的 int32 值，负值为错误码

◆ tbox_dbus_check_message_match()

bool tbox_dbus_check_message_match	(	DBusMessage *	msg,
		bool	is_signal,
		const char *	module,
		const char *	action )

检查消息是否匹配指定模块和动作

Parameters

msg	消息对象
is_signal	true 匹配信号，false 匹配方法调用
module	模块名
action	动作名

Returns: true 匹配，false 不匹配

◆ tbox_dbus_check_next_message()

bool tbox_dbus_check_next_message ( DBusMessageIter * iter )

检查消息迭代器是否还有下一个参数

Parameters

iter 消息迭代器

Returns: true 有下一个参数，false 无

◆ tbox_dbus_connect()

int tbox_dbus_connect ( const char * app_name )

连接 D-Bus 服务

Parameters

app_name 应用服务名

Returns: 0 成功，其他失败

◆ tbox_dbus_delete_receive_match()

int tbox_dbus_delete_receive_match ( const char * filter )

删除接收消息匹配规则

Parameters

filter D-Bus 匹配规则字符串

Returns: 0 成功，其他失败

◆ tbox_dbus_disconnect()

void tbox_dbus_disconnect ( void )

断开 D-Bus 服务连接

Precondition: 仅在程序退出阶段调用，且不得并发调用本接口。

◆ tbox_dbus_free_message()

void tbox_dbus_free_message ( DBusMessage * msg )

释放 D-Bus 消息对象

Parameters

msg 消息对象

◆ tbox_dbus_free_param()

void tbox_dbus_free_param ( tbox_dbus_param_t * param )

释放参数中动态分配的内存

Parameters

param 待释放参数

◆ tbox_dbus_get_connection_name()

const char * tbox_dbus_get_connection_name ( void )

获取当前连接的唯一名称

Returns: 连接唯一名称，未连接时返回空字符串

◆ tbox_dbus_get_message()

int tbox_dbus_get_message	(	DBusMessageIter *	iter,
		tbox_dbus_param_t *	param )

从消息迭代器读取一个参数

Parameters

iter	消息迭代器
param	输出参数

Returns: 0 成功，其他失败

◆ tbox_dbus_get_message_begin()

int tbox_dbus_get_message_begin	(	DBusMessageIter *	iter,
		DBusMessage **	msg,
		tbox_dbus_recv_info_t *	recv_info,
		int32_t	timeout )

开始接收 D-Bus 消息（首参数）

Parameters

iter	输出消息迭代器
msg	输出消息对象
recv_info	接收消息描述
timeout	超时时间，单位毫秒，-1 表示一直等待

Returns: 0 成功，其他失败

◆ tbox_dbus_get_message_end()

int tbox_dbus_get_message_end	(	DBusMessage *	msg,
		tbox_dbus_param_t *	return_param )

完成 D-Bus 消息接收并发送方法返回

Parameters

msg	消息对象
return_param	方法返回参数，无需回复时可传 NULL

Returns: 0 成功，其他失败

◆ tbox_dbus_handle_message()

void tbox_dbus_handle_message	(	const tbox_dbus_handle_map_t *	handle_map,
		const char *	need_module,
		int32_t	timeout )

根据映射表分发并处理接收到的 D-Bus 消息

Parameters

handle_map	消息处理映射表，以空项结尾
need_module	期望模块名，可为 NULL 表示不限制
timeout	超时时间，单位毫秒，-1 表示一直等待

◆ tbox_dbus_recv_no_reply()

int tbox_dbus_recv_no_reply	(	const char *	need_module,
		int32_t	timeout,
		bool	need_signal,
		tbox_dbus_param_t *	msg_param,
		char *	recv_action,
		uint32_t	recv_action_len )

接收无需回复的 D-Bus 消息

Parameters

need_module	期望模块名，可为 NULL 表示不限制
timeout	超时时间，单位毫秒，-1 表示一直等待
need_signal	是否接收信号
msg_param	输出消息参数
recv_action	输出动作名缓冲区，可为 NULL
recv_action_len	recv_action 缓冲区长度，recv_action 为 NULL 时可传 0

Returns: 0 成功，其他失败

◆ tbox_dbus_send_message()

int tbox_dbus_send_message	(	const tbox_dbus_send_info_t *	send_info,
		tbox_dbus_param_t *	return_param,
		int32_t	timeout )

发送 D-Bus 消息并等待回复

Parameters

send_info	发送消息描述
return_param	方法调用返回参数，发送信号时可传 NULL
timeout	超时时间，单位毫秒，-1 表示一直等待

Returns: 0 成功，其他失败

◆ tbox_dbus_send_message_begin()

int tbox_dbus_send_message_begin	(	const tbox_dbus_send_info_t *	send_info,
		DBusMessage **	msg,
		DBusMessageIter *	iter )

开始构造并发送 D-Bus 消息（首参数）

Parameters

send_info	发送消息描述
msg	输出消息对象
iter	输出消息迭代器

Returns: 0 成功，其他失败

◆ tbox_dbus_send_message_end()

int tbox_dbus_send_message_end	(	bool	is_signal,
		DBusMessage *	msg,
		tbox_dbus_param_t *	return_param,
		int32_t	timeout )

完成 D-Bus 消息发送并等待回复

Parameters

is_signal	是否为信号
msg	消息对象
return_param	方法调用返回参数，信号发送时可传 NULL
timeout	超时时间，单位毫秒，-1 表示一直等待

Returns: 0 成功，其他失败

◆ tbox_dbus_send_no_reply()

void tbox_dbus_send_no_reply	(	const char *	dest,
		const char *	module,
		const char *	action,
		tbox_dbus_param_t *	param )

发送无需回复的 D-Bus 方法调用

Parameters

dest	目标服务名
module	模块名
action	动作名
param	请求参数

◆ tbox_dbus_send_signal()

int tbox_dbus_send_signal	(	const char *	module,
		const char *	action,
		tbox_dbus_param_t *	param )

发送 D-Bus 信号

Parameters

module	模块名
action	动作名
param	信号参数，可为 NULL

Returns: 0 成功，其他失败

◆ tbox_dbus_set_message()

int tbox_dbus_set_message	(	DBusMessageIter *	iter,
		const tbox_dbus_param_t *	param )

向消息迭代器写入一个参数

Parameters

iter	消息迭代器
param	待写入参数

Returns: 0 成功，其他失败

◆ tbox_dbus_set_receive_match()

int tbox_dbus_set_receive_match ( const char * filter )

添加接收消息匹配规则

Parameters

filter D-Bus 匹配规则字符串

Returns: 0 成功，其他失败

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ DBUS_CHECK_OR_RESULT_WITH_ERROR

◆ DBUS_CHECK_RET_OR_RESULT_WITH_MESSAGE

◆ DBUS_CHECK_TYPE_OR_RESULT_WITH_MESSAGE

◆ DBUS_CHECK_TYPE_OR_RETURN_WITH_ERROR

Typedef Documentation

◆ tbox_dbus_handler_t

Enumeration Type Documentation

◆ tbox_dbus_type_t

Function Documentation

◆ tbox_dbus_call_get()

◆ tbox_dbus_call_set()

◆ tbox_dbus_check_message_match()

◆ tbox_dbus_check_next_message()

◆ tbox_dbus_connect()

◆ tbox_dbus_delete_receive_match()

◆ tbox_dbus_disconnect()

◆ tbox_dbus_free_message()

◆ tbox_dbus_free_param()

◆ tbox_dbus_get_connection_name()

◆ tbox_dbus_get_message()

◆ tbox_dbus_get_message_begin()

◆ tbox_dbus_get_message_end()

◆ tbox_dbus_handle_message()

◆ tbox_dbus_recv_no_reply()

◆ tbox_dbus_send_message()

◆ tbox_dbus_send_message_begin()

◆ tbox_dbus_send_message_end()

◆ tbox_dbus_send_no_reply()

◆ tbox_dbus_send_signal()

◆ tbox_dbus_set_message()

◆ tbox_dbus_set_receive_match()