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

#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_REPLY 或AIOT_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

版权所有: Copyright (C) 2015-2020 Alibaba Group Holding Limited

请按照以下流程使用API

在使用物模型模块前, 用户应首先创建好一个MQTT实例
调用aiot_dm_init创建一个物模型实例, 保存实例句柄
调用aiot_dm_setopt配置AIOT_DMOPT_MQTT_HANDLE选项以设置MQTT句柄, 此选项为强制配置选项
调用aiot_dm_setopt配置AIOT_DMOPT_RECV_HANDLER和AIOT_DMOPT_USERDATA选项以注册数据接受回调函数和用户上下文数据指针
在使用aiot_dm_send发送消息前, 应先完成MQTT实例的建连
调动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_REPLY 或AIOT_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]	handle	data-model实例句柄
[in]	recv	服务下发的消息数据, 消息结构体中的所有数据指针在离开回调函数后将失效, 保存消息数据必须使用内存复制的方式
[in]	userdata	指向用户上下文数据的指针, 这个指针由用户通过调用aiot_dm_setopt 配置AIOT_DMOPT_USERDATA 选项设置

返回: void

枚举类型说明

enum aiot_dm_option_t

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	配置选项数量最大值, 不可用作配置参数

enum aiot_dm_msg_type_t

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	消息数量最大值, 不可用作消息类型

enum aiot_dm_recv_type_t

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*

返回值

非NULL	data-model实例句柄
NULL	初始化失败, 一般是内存分配失败导致

函数调用图:

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

设置data-model参数

参数

[in]	handle	data-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]	handle	data-model实例句柄
[in]	msg	消息结构体, 可指定发送消息的设备productKey, deviceName; 消息类型, 消息数据等, 更多信息请参考aiot_dm_msg_t

返回: int32_t

返回值

>=STATE_SUCCESS	消息发送成功, 对于AIOT_DMMSG_PROPERTY_POST, AIOT_DMMSG_EVENT_POST, AIOT_DMMSG_GET_DESIRED 和AIOT_DMMSG_DELETE_DESIRED 消息, 发送成功返回值为>STATE_SUCCESS的消息标示符msg_id值
STATE_USER_INPUT_NULL_POINTER	入参handle或msg为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.h 或STATE_DM_BASE 中对应的错误码说明

函数调用图:

int32_t aiot_dm_deinit ( void ** p_handle )

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

参数

[in] p_handle 指向data-model实例句柄的指针

返回: int32_t

返回值

STATE_SUCCESS	执行成功
<STATE_SUCCESS	执行失败

函数调用图: