# agora_iot_dp.h (/zh-CN/api-reference/iot-apaas/device-sdk/full/dp) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 本页提供声网灵隼设备端 SDK 的 `agora_iot_dp.h` 文件的 API 参考。 ## 引用文件 [#引用文件] ```c #include "agora_iot_base.h" ``` ## 函数 [#函数] ### agora_iot_dp_register_dp_query_handler [#agora_iot_dp_register_dp_query_handler] ```c agora_iot_dp_result_e agora_iot_dp_register_dp_query_handler(agora_iot_handle_t handle, int dp_id, agora_dp_type_e dp_type, on_dp_query_callback callback, void *args); ``` 注册属性查询回调。 你需要确保已经在控制台通过**功能定义**页面新增了相应功能。详见[开通灵隼服务](/zh-CN/solutions/iot-apaas/build/setup-and-access/enable-service)。 #### 参数 [#参数] | 参数 | 描述 | | --- | --- | | [in] `handle` | [agora_iot_init](/zh-CN/api-reference/iot-apaas/device-sdk/full/config#agoraiotinit) 返回的 SDK 句柄。详见 [agora_iot_handle_t](/zh-CN/api-reference/iot-apaas/device-sdk/full/base#agoraiothandlet)。 | | [in] `dp_id` | 属性 ID。即控制台**功能定义**页面的功能标识符。详见[开通灵隼服务](/zh-CN/solutions/iot-apaas/build/setup-and-access/enable-service)。 | | [in] `dp_type` | 属性的数据类型。详见 [agora_dp_type_e](#agoradptypee)。 | | [in] `callback` | 属性查询回调。详见 [on_dp_query_callback](#ondpquerycallback)。 | | [in] `args` | 回调参数。 | #### 返回 [#返回] [agora_iot_dp_result_e](#agoraiotdpresulte) 结构体中的枚举。 ### agora_iot_dp_register_dp_cmd_handler [#agora_iot_dp_register_dp_cmd_handler] ```c agora_iot_dp_result_e agora_iot_dp_register_dp_cmd_handler(agora_iot_handle_t handle, int dp_id, agora_dp_type_e dp_type, on_dp_cmd_callback callback, void *args); ``` 注册属性命令回调。 你需要确保已经在控制台通过**功能定义**页面新增了相应功能。详见[开通灵隼服务](/zh-CN/solutions/iot-apaas/build/setup-and-access/enable-service)。 #### 参数 [#参数-1] | 参数 | 描述 | | --- | --- | | [in] `handle` | [agora_iot_init](/zh-CN/api-reference/iot-apaas/device-sdk/full/config#agoraiotinit) 返回的 SDK 句柄。详见 [agora_iot_handle_t](/zh-CN/api-reference/iot-apaas/device-sdk/full/base#agoraiothandlet)。 | | [in] `dp_id` | 属性 ID。即控制台**属性定义**页面的属性标识符。参考[开通灵隼服务](/zh-CN/solutions/iot-apaas/build/setup-and-access/enable-service)在控制台创建属性。 | | [in] `dp_type` | 属性的数据类型。详见 [agora_dp_type_e](#agoradptypee)。 | | [in] `callback` | 属性命令回调。详见 [on_dp_cmd_callback](#ondpquerycallback)。 | | [in] `args` | 回调参数。 | #### 返回 [#返回-1] [agora_iot_dp_result_e](#agoraiotdpresulte) 结构体中的枚举。 ### agora_iot_dp_publish [#agora_iot_dp_publish] ```c agora_iot_dp_result_e agora_iot_dp_publish(agora_iot_handle_t handle, agora_dp_info_t *info); ``` 发布一个属性。 你需要确保已经在控制台通过**功能定义**页面新增了相应属性。详见[开通灵隼服务](/zh-CN/solutions/iot-apaas/build/setup-and-access/enable-service)。 #### 参数 [#参数-2] | 参数 | 描述 | | --- | --- | | [in] `handle` | [agora_iot_init](/zh-CN/api-reference/iot-apaas/device-sdk/full/config#agoraiotinit) 返回的 SDK 句柄。详见 [agora_iot_handle_t](/zh-CN/api-reference/iot-apaas/device-sdk/full/base#agoraiothandlet)。 | | [in] `info` | 属性信息。详见 [agora_dp_info_t](#agoradpinfot)。 | #### 返回 [#返回-2] [agora_iot_dp_result_e](#agoraiotdpresulte) 结构体中的枚举。 ### agora_iot_dp_publish_all [#agora_iot_dp_publish_all] ```c agora_iot_dp_result_e agora_iot_dp_publish_all(agora_iot_handle_t handle); ``` 发布全部属性。你需要确保已经在控制台通过**功能定义**页面新增了相应属性。详见[开通灵隼服务](/zh-CN/solutions/iot-apaas/build/setup-and-access/enable-service)。 在发布全部属性之前,确保你已经调用 [agora_iot_dp_register_dp_query_handler](#agoraiotdpregisterdpqueryhandler) 注册了属性回调。 #### 参数 [#参数-3] | 参数 | 描述 | | --- | --- | | [in] `handle` | [agora_iot_init](/zh-CN/api-reference/iot-apaas/device-sdk/full/config#agoraiotinit) 返回的 SDK 句柄。详见 [agora_iot_handle_t](/zh-CN/api-reference/iot-apaas/device-sdk/full/base#agoraiothandlet)。 | #### 返回 [#返回-3] [agora_iot_dp_result_e](#agoraiotdpresulte) 结构体中的枚举。 ## 常量 [#常量] ### AGORA_DP_USER_LEN [#agora_dp_user_len] ```c #define AGORA_DP_USER_LEN 64 ``` 属性用户名长度。 ### AGORA_DP_ID_MIN [#agora_dp_id_min] ```c #define AGORA_DP_ID_MIN 100 ``` 属性 ID 长度的最小值。 ## 类型定义 [#类型定义] ### agora_iot_dp_result_e [#agora_iot_dp_result_e] ```c typedef enum { ERR_AG_DP_SUCCESS = ERR_SUCCESS, ERR_AG_DP_FAILED = ERR_FAILED, ERR_AG_DP_INVALID_ARGUMENT = ERR_INVALID_ARGUMENT, } agora_iot_dp_result_e; ``` 属性函数调用结果。 | 参数 | 描述 | | --- | --- | | `ERR_AG_DP_SUCCESS` | 0:方法调用成功。 | | `ERR_AG_DP_FAILED` | -1:方法调用失败。 | | `ERR_AG_DP_INVALID_ARGUMENT` | -2:参数无效。 | ### agora_dp_type_e [#agora_dp_type_e] ```c typedef enum agora_dp_type { AGORA_DP_TYPE_INT = 0, AGORA_DP_TYPE_BOOL = 1, AGORA_DP_TYPE_ENUM = 2, AGORA_DP_TYPE_STR = 3, } agora_dp_type_e; ``` 属性类型。 | 参数 | 描述 | | --- | --- | | `AGORA_DP_TYPE_INT` | 0:整数类型。 | | `AGORA_DP_TYPE_BOOL` | 1:布尔类型。 | | `AGORA_DP_TYPE_ENUM` | 2:枚举类型。 | | `AGORA_DP_TYPE_STR` | 3:字符串类型。 | ### agora_dp_value_t [#agora_dp_value_t] ```c typedef union { int dp_int; bool dp_bool; unsigned int dp_enum; char *dp_str; } agora_dp_value_t; ``` 属性的值。 | 参数 | 描述 | | --- | --- | | `dp_int` | 整数类型的值。 | | `dp_bool` | 布尔类型的值。 | | `dp_enum` | 枚举类型的值。 | | `dp_str` | 字符串类型的值。 SDK 不会自动释放该参数分配的内存。为避免内存泄露,你需要手动管理内存。| ### agora_dp_info_t [#agora_dp_info_t] ```c typedef struct agora_dp_info { unsigned int dp_id; agora_dp_type_e dp_type; agora_dp_value_t dp_value; } agora_dp_info_t; ``` 属性信息。 | 参数 | 描述 | | --- | --- | | `dp_id` | 属性 ID。即控制台**功能定义**页面的属性标识符。详见[开通灵隼服务](/zh-CN/solutions/iot-apaas/build/setup-and-access/enable-service)。 | | `dp_type` | 属性的数据类型。详见 [agora_dp_type_e](#agoradptypee)。 | | `dp_value` | 属性的值。详见 [agora_dp_value_t](#agoradpvaluet)。 | ### on_dp_query_callback [#on_dp_query_callback] ```c typedef void (*on_dp_query_callback)(agora_dp_info_t *info, void *args); ``` 客户端 SDK 通过设备属性方法查询本地属性时触发。 #### 参数 [#参数-4] | 参数 | 描述 | | --- | --- | | [in] `info` | 属性信息。详见 [agora_dp_info_t](#agoradpinfot)。你需要在此参数中传入本地属性的信息。 | | [in] `args` | 回调参数。通过 [agora_iot_dp_register_dp_query_handler](#agoraiotdpregisterdpqueryhandler) 传入。 | ### on_dp_cmd_callback [#on_dp_cmd_callback] ```c typedef void (*on_dp_cmd_callback)(const agora_dp_info_t *info, void *args); ``` 接收到客户端 SDK 通过设备属性方法发送的命令时触发。 #### 参数 [#参数-5] | 参数 | 描述 | | --- | --- | | [in] `info` | 属性信息。详见 [agora_dp_info_t](#agoradpinfot)。你可以在此参数中传入本地属性或远端属性的信息。 | | [in] `args` | 回调参数。通过 [agora_iot_dp_register_dp_cmd_handler](#agoraiotdpregisterdpcmdhandler) 传入。 |