Link Kit C-SDK  4.0.0
| 宏定义 | 类型定义 | 枚举 | 函数
aiot_dm_api.h 文件参考

数据模型模块头文件, 提供了物模型数据格式的上云能力, 包括属性, 事件, 服务和物模型二进制格式的数据上下行能力 更多...

#include <stdint.h>
aiot_dm_api.h 的引用(Include)关系图:

浏览源代码.

struct  aiot_dm_msg_property_post_t
 物模型属性上报消息结构体 更多...
 
struct  aiot_dm_msg_event_post_t
 物模型事件上报消息结构体 更多...
 
struct  aiot_dm_msg_property_set_reply_t
 属性设置应答消息结构体, 用户在收到AIOT_DMRECV_PROPERTY_SET 类型的属性设置后, 可发送此消息进行回复 更多...
 
struct  aiot_dm_msg_async_service_reply_t
 异步服务应答消息结构体, 用户在收到AIOT_DMRECV_ASYNC_SERVICE_INVOKE 类型的异步服务调用消息后, 应发送此消息进行应答 更多...
 
struct  aiot_dm_msg_sync_service_reply_t
 同步服务应答消息结构体, 用户在收到AIOT_DMRECV_SYNC_SERVICE_INVOKE 类型的同步服务调用消息后, 应在超时时间(默认7s)内进行应答 更多...
 
struct  aiot_dm_msg_raw_data_t
 物模型二进制数据消息结构体, 发送的二进制数据将通过物联网平台的JavaScript脚本转化为JSON格式数据, 用户发送此消息前应确保已正确启用云端解析脚本 更多...
 
struct  aiot_dm_msg_raw_service_reply_t
 二进制格式的同步服务应答消息结构体, 用户在收到AIOT_DMRECV_RAW_SYNC_SERVICE_INVOKE 类型消息后, 应在超时时间(默认7s)内进行应答
用户在使用此消息前应确保已启用云端解析脚本, 并且脚本工作正常 更多...
 
struct  aiot_dm_msg_get_desired_t
 获取期望属性值消息结构体, 发送 更多...
 
struct  aiot_dm_msg_delete_desired_t
 删除指定期望值消息结构体 更多...
 
struct  aiot_dm_msg_property_batch_post_t
 物模型属性上报消息结构体 更多...
 
struct  aiot_dm_msg_t
 data-model模块发送消息的消息结构体 更多...
 
struct  aiot_dm_recv_generic_reply_t
 云端通用应答消息结构体, 设备端上报AIOT_DMMSG_PROPERTY_POST, AIOT_DMMSG_EVENT_POST 或者AIOT_DMMSG_GET_DESIRED 等消息后, 服务器会应答此消息 更多...
 
struct  aiot_dm_recv_property_set_t
 属性设置消息结构体 更多...
 
struct  aiot_dm_recv_sync_service_invoke_t
 同步服务调用消息结构体, 用户收到同步服务后, 必须在超时时间(默认7s)内进行应答 更多...
 
struct  aiot_dm_recv_async_service_invoke_t
 同步服务调用消息结构体 更多...
 
struct  aiot_dm_recv_raw_data_t
 物模型二进制数据消息结构体, 服务器的JSON格式物模型数据将通过物联网平台的JavaScript脚本转化为二进制数据, 用户在接收此消息前应确保已正确启用云端解析脚本 更多...
 
struct  aiot_dm_recv_raw_service_invoke_t
 二进制数据的同步服务调用消息结构体, 服务器的JSON格式物模型数据将通过物联网平台的JavaScript脚本转化为二进制数据, 用户在接收此消息前应确保已正确启用云端解析脚本 更多...
 
struct  aiot_dm_recv_t
 data-model模块接收消息的结构体 更多...
 

宏定义

#define STATE_DM_BASE   (-0x0A00)
 -0x0A00~-0x0AFF表达SDK在data-model模块内的状态码 更多...
 
#define STATE_DM_EVENT_ID_IS_NULL   (-0x0A01)
 用户发送AIOT_DMMSG_EVENT_POST 消息时, 消息数据中的event_id为NULL 更多...
 
#define STATE_DM_SERVICE_ID_IS_NULL   (-0x0A02)
 用户发送AIOT_DMMSG_ASYNC_SERVICE_REPLYAIOT_DMMSG_SYNC_SERVICE_REPLY 消息时, 消息数据中的event_id为NULL 更多...
 
#define STATE_DM_RRPC_ID_IS_NULL   (-0x0A03)
 用户发送AIOT_DMMSG_SYNC_SERVICE_REPLY 消息时, 消息数据中的rrpc_id为NULL 更多...
 
#define STATE_DM_MSG_PARAMS_IS_NULL   (-0X0A04)
 用户发送请求类消息时, 消息数据中的param为NULL 更多...
 
#define STATE_DM_MSG_DATA_IS_NULL   (-0X0A05)
 用户发送应答类消息时, 消息数据中的data为NULL 更多...
 
#define STATE_DM_INTERNAL_TOPIC_ERROR   (-0x0A06)
 解析下行数据对应的topic时发生错误 更多...
 
#define STATE_DM_MQTT_HANDLE_IS_NULL   (-0x0A07)
 用户未调用aiot_dm_setopt 配置MQTT句柄 更多...
 
#define STATE_DM_LOG_RECV   (-0x0A08)
 接收到服务器下行消息时的日志状态码 更多...
 
#define SATAE_DM_LOG_PARSE_RECV_MSG_FAILED   (-0x0A09)
 解析服务器下行消息失败时的日志状态码 更多...
 

类型定义

typedef void(* aiot_dm_recv_handler_t) (void *handle, const aiot_dm_recv_t *recv, void *userdata)
 data-model模块消息接收回调函数的函数原型定义, 当模块接收到服务器下行数据后将调用此回调函数, 并将消息数据通过recv参数输入给用户,
同时将用户上下文数据指针通过userdata参数返回给用户 更多...
 

枚举

enum  aiot_dm_option_t {
  AIOT_DMOPT_MQTT_HANDLE, AIOT_DMOPT_RECV_HANDLER, AIOT_DMOPT_USERDATA, AIOT_DMOPT_POST_REPLY,
  AIOT_DMOPT_MAX
}
 data-model模块的配置选项枚举类型定义. aiot_dm_setopt 函数入数data的数据类型根据不同的选项而不同 更多...
 
enum  aiot_dm_msg_type_t {
  AIOT_DMMSG_PROPERTY_POST, AIOT_DMMSG_EVENT_POST, AIOT_DMMSG_PROPERTY_SET_REPLY, AIOT_DMMSG_ASYNC_SERVICE_REPLY,
  AIOT_DMMSG_SYNC_SERVICE_REPLY, AIOT_DMMSG_RAW_DATA, AIOT_DMMSG_RAW_SERVICE_REPLY, AIOT_DMMSG_GET_DESIRED,
  AIOT_DMMSG_DELETE_DESIRED, AIOT_DMMSG_PROPERTY_BATCH_POST, AIOT_DMMSG_MAX
}
 data-model模块发送消息类型 更多...
 
enum  aiot_dm_recv_type_t {
  AIOT_DMRECV_GENERIC_REPLY, AIOT_DMRECV_PROPERTY_SET, AIOT_DMRECV_ASYNC_SERVICE_INVOKE, AIOT_DMRECV_SYNC_SERVICE_INVOKE,
  AIOT_DMRECV_RAW_DATA_REPLY, AIOT_DMRECV_RAW_DATA, AIOT_DMRECV_RAW_SYNC_SERVICE_INVOKE, AIOT_DMRECV_MAX
}
 data-model模块接受消息类型枚举 更多...
 

函数

void * aiot_dm_init (void)
 初始化data-model实例 更多...
 
int32_t aiot_dm_setopt (void *handle, aiot_dm_option_t option, void *data)
 设置data-model参数 更多...
 
int32_t aiot_dm_send (void *handle, const aiot_dm_msg_t *msg)
 发送一条data-model消息到物联网平台, 消息类型和消息数据由msg入参决定 更多...
 
int32_t aiot_dm_deinit (void **p_handle)
 销毁data-model实例, 释放资源 更多...
 

详细描述

数据模型模块头文件, 提供了物模型数据格式的上云能力, 包括属性, 事件, 服务和物模型二进制格式的数据上下行能力

日期
2020-01-20

请按照以下流程使用API

  1. 在使用物模型模块前, 用户应首先创建好一个MQTT实例
  2. 调用aiot_dm_init创建一个物模型实例, 保存实例句柄
  3. 调用aiot_dm_setopt配置AIOT_DMOPT_MQTT_HANDLE选项以设置MQTT句柄, 此选项为强制配置选项
  4. 调用aiot_dm_setopt配置AIOT_DMOPT_RECV_HANDLERAIOT_DMOPT_USERDATA选项以注册数据接受回调函数和用户上下文数据指针
  5. 在使用aiot_dm_send发送消息前, 应先完成MQTT实例的建连
  6. 调动aiot_dm_send发送不同类型的消息到云平台, 在注册的回调函数中处理各种类型的云平台下行消息

宏定义说明

#define STATE_DM_BASE   (-0x0A00)

-0x0A00~-0x0AFF表达SDK在data-model模块内的状态码

#define STATE_DM_EVENT_ID_IS_NULL   (-0x0A01)

用户发送AIOT_DMMSG_EVENT_POST 消息时, 消息数据中的event_id为NULL

#define STATE_DM_SERVICE_ID_IS_NULL   (-0x0A02)

用户发送AIOT_DMMSG_ASYNC_SERVICE_REPLYAIOT_DMMSG_SYNC_SERVICE_REPLY 消息时, 消息数据中的event_id为NULL

#define STATE_DM_RRPC_ID_IS_NULL   (-0x0A03)

用户发送AIOT_DMMSG_SYNC_SERVICE_REPLY 消息时, 消息数据中的rrpc_id为NULL

#define STATE_DM_MSG_PARAMS_IS_NULL   (-0X0A04)

用户发送请求类消息时, 消息数据中的param为NULL

#define STATE_DM_MSG_DATA_IS_NULL   (-0X0A05)

用户发送应答类消息时, 消息数据中的data为NULL

#define STATE_DM_INTERNAL_TOPIC_ERROR   (-0x0A06)

解析下行数据对应的topic时发生错误

#define STATE_DM_MQTT_HANDLE_IS_NULL   (-0x0A07)

用户未调用aiot_dm_setopt 配置MQTT句柄

#define STATE_DM_LOG_RECV   (-0x0A08)

接收到服务器下行消息时的日志状态码

#define SATAE_DM_LOG_PARSE_RECV_MSG_FAILED   (-0x0A09)

解析服务器下行消息失败时的日志状态码

类型定义说明

typedef void(* aiot_dm_recv_handler_t) (void *handle, const aiot_dm_recv_t *recv, void *userdata)

data-model模块消息接收回调函数的函数原型定义, 当模块接收到服务器下行数据后将调用此回调函数, 并将消息数据通过recv参数输入给用户,
同时将用户上下文数据指针通过userdata参数返回给用户

参数
[in]handledata-model实例句柄
[in]recv服务下发的消息数据, 消息结构体中的所有数据指针在离开回调函数后将失效, 保存消息数据必须使用内存复制的方式
[in]userdata指向用户上下文数据的指针, 这个指针由用户通过调用aiot_dm_setopt 配置AIOT_DMOPT_USERDATA 选项设置
返回
void

枚举类型说明

data-model模块的配置选项枚举类型定义. aiot_dm_setopt 函数入数data的数据类型根据不同的选项而不同

枚举值
AIOT_DMOPT_MQTT_HANDLE 

模块依赖的MQTT句柄

data-model模块依赖底层的MQTT模块, 用户必需配置正确的MQTT句柄, 否则无法正常工作

数据类型: (void *)

AIOT_DMOPT_RECV_HANDLER 

数据接收回调函数, data-model接收物联网平台的下行消息后调用此回调函数

数据类型: (aiot_dm_recv_handler_t), 详细查看aiot_dm_recv_handler_t 回调函数原型

AIOT_DMOPT_USERDATA 

指向用户上下文数据的指针

在用户注册的aiot_dm_recv_handler_t 数据接收回调函数中会同过userdata参数将此指针返回给用户

数据类型: (void *)

AIOT_DMOPT_POST_REPLY 

用户是否希望接收post消息后的reply

是否要接收云端的reply消息. 1表示要接收, 0表示不要.

数据类型: (uint8_t) *)

AIOT_DMOPT_MAX 

配置选项数量最大值, 不可用作配置参数

data-model模块发送消息类型

这个枚举类型包括了dm模块支持发送的所有数据类型, 不同的消息类型将对于不同的消息结构体 用户可查看网页文档设备属性/事件/服务进一步了解各种数据类型

枚举值
AIOT_DMMSG_PROPERTY_POST 

属性上报, 消息结构体参考aiot_dm_msg_property_post_t
成功发送此消息后, 将会收到AIOT_DMRECV_GENERIC_REPLY 类型的应答消息

AIOT_DMMSG_EVENT_POST 

事件上报, 消息结构体参考aiot_dm_msg_event_post_t
成功发送此消息后, 将会收到AIOT_DMRECV_GENERIC_REPLY 类型的应答消息

AIOT_DMMSG_PROPERTY_SET_REPLY 

属性设置应答, 消息结构体参考aiot_dm_msg_property_set_reply_t

AIOT_DMMSG_ASYNC_SERVICE_REPLY 

异步服务应答, 消息结构体参考aiot_dm_msg_async_service_reply_t

AIOT_DMMSG_SYNC_SERVICE_REPLY 

同步服务应答, 消息结构体参考aiot_dm_msg_sync_service_reply_t

AIOT_DMMSG_RAW_DATA 

二进制格式的物模型上行数据, 消息结构体参考aiot_dm_msg_raw_data_t

AIOT_DMMSG_RAW_SERVICE_REPLY 

二进制格式的同步服务应答, 消息结构体参考aiot_dm_msg_raw_service_reply_t

AIOT_DMMSG_GET_DESIRED 

获取期望属性值, 消息结构体请参考aiot_dm_msg_get_desired_t,
成功发送此消息后, 将会收到AIOT_DMRECV_GENERIC_REPLY 类型的应答消息

AIOT_DMMSG_DELETE_DESIRED 

清除指定的期望值, 消息结构体请参考aiot_dm_msg_delete_desired_t
成功发送此消息后, 将会收到AIOT_DMRECV_GENERIC_REPLY 类型的应答消息

AIOT_DMMSG_PROPERTY_BATCH_POST 

清除指定的期望值, 消息结构体请参考aiot_dm_msg_delete_desired_t
成功发送此消息后, 将会收到AIOT_DMRECV_GENERIC_REPLY 类型的应答消息

AIOT_DMMSG_MAX 

消息数量最大值, 不可用作消息类型

data-model模块接受消息类型枚举

这个枚举类型包括了dm模块支持接收的所有数据类型, 不同的消息类型将对于不同的消息结构体 用户可查看网页文档设备属性/事件/服务进一步了解各种数据类型

枚举值
AIOT_DMRECV_GENERIC_REPLY 

上报属性/实践后服务器返回的应答消息, 消息数据结构体参考aiot_dm_recv_generic_reply_t

AIOT_DMRECV_PROPERTY_SET 

服务器下发的属性设置消息, 消息数据结构体参考aiot_dm_recv_property_set_t

AIOT_DMRECV_ASYNC_SERVICE_INVOKE 

服务器下发的异步服务调用消息, 消息数据结构体参考aiot_dm_recv_async_service_invoke_t

AIOT_DMRECV_SYNC_SERVICE_INVOKE 

服务器下发的同步服务调用消息, 消息数据结构体参考aiot_dm_recv_sync_service_invoke_t

AIOT_DMRECV_RAW_DATA_REPLY 

服务器对设备上报的二进制数据应答, 消息数据结构体参考aiot_dm_recv_raw_data_t

AIOT_DMRECV_RAW_DATA 

服务器下发的物模型二进制数据, 消息数据结构体参考aiot_dm_recv_raw_data_t

AIOT_DMRECV_RAW_SYNC_SERVICE_INVOKE 

服务器下发的二进制格式的同步服务调用消息, 消息数据结构体参考aiot_dm_recv_raw_service_invoke_t

AIOT_DMRECV_MAX 

消息数量最大值, 不可用作消息类型

函数说明

void* aiot_dm_init ( void  )

初始化data-model实例

返回
void*
返回值
非NULLdata-model实例句柄
NULL初始化失败, 一般是内存分配失败导致

函数调用图:

int32_t aiot_dm_setopt ( void *  handle,
aiot_dm_option_t  option,
void *  data 
)

设置data-model参数

参数
[in]handledata-model实例句柄
[in]option配置选项, 更多信息请查看aiot_dm_option_t
[in]data配置数据, 更多信息请查看aiot_dm_option_t
返回
int32_t
返回值
STATE_SUCCESS参数配置成功
STATE_USER_INPUT_NULL_POINTER入参handle或data为NULL
STATE_USER_INPUT_OUT_RANGE入参optioin的枚举值>=AIOT_DMOPT_MAX
others参考aiot_state_api.h

函数调用图:

int32_t aiot_dm_send ( void *  handle,
const aiot_dm_msg_t msg 
)

发送一条data-model消息到物联网平台, 消息类型和消息数据由msg入参决定

参数
[in]handledata-model实例句柄
[in]msg消息结构体, 可指定发送消息的设备productKey, deviceName; 消息类型, 消息数据等, 更多信息请参考aiot_dm_msg_t
返回
int32_t
返回值
>=STATE_SUCCESS消息发送成功, 对于AIOT_DMMSG_PROPERTY_POST, AIOT_DMMSG_EVENT_POST, AIOT_DMMSG_GET_DESIREDAIOT_DMMSG_DELETE_DESIRED 消息,
发送成功返回值为>STATE_SUCCESS的消息标示符msg_id
STATE_USER_INPUT_NULL_POINTER入参handlemsg为NULL
STATE_USER_INPUT_OUT_RANGE入参msg的结构体成员type >= AIOT_DMMSG_MAX
STATE_SYS_DEPEND_MALLOC_FAILED内存分配失败
STATE_DM_MQTT_HANDLE_IS_NULL用户未调用aiot_dm_setopt 配置MQTT句柄
others参考aiot_state_api.hSTATE_DM_BASE 中对应的错误码说明

函数调用图:

int32_t aiot_dm_deinit ( void **  p_handle)

销毁data-model实例, 释放资源

参数
[in]p_handle指向data-model实例句柄的指针
返回
int32_t
返回值
STATE_SUCCESS执行成功
<STATE_SUCCESS执行失败

函数调用图: