aiot_shadow_api.h 文件参考

shadow模块头文件, 提供更新, 删除, 获取设备影子的能力 更多...

#include <stdint.h>

aiot_shadow_api.h 的引用(Include)关系图:

浏览源代码.

类
struct	aiot_shadow_msg_update_t
	用于更新设备影子中的reported数据的消息结构体 更多...
struct	aiot_shadow_msg_clean_desired_t
	用于清除设备影子中的desired数据的消息结构体 更多...
struct	aiot_shadow_msg_get_t
	用于获取设备影子的消息结构体, 更多...
struct	aiot_shadow_msg_delete_reported_t
	用于删除设备影子中的reported数据的消息结构体 更多...
struct	aiot_shadow_msg_t
	data-model模块发送消息的消息结构体 更多...
struct	aiot_shadow_recv_generic_reply_t
	设备发送 AIOT_SHADOWMSG_UPDATE, AIOT_SHADOWMSG_CLEAN_DESIRED 或 AIOT_SHADOWMSG_DELETE_REPORTED 类型消息后, 云端返回的应答消息 更多...
struct	aiot_shadow_recv_control_t
	如果设备在线, 用户应用调用云端APIUpdateDeviceShadow后云端下推的消息 更多...
struct	aiot_shadow_recv_get_reply_t
	设备发送 AIOT_SHADOWMSG_GET 类型消息后, 云端返回的设备影子数据 更多...
struct	aiot_shadow_recv_t
	shadow模块收到从网络上来的报文时, 通知用户的报文内容 更多...

宏定义
#define	STATE_SHADOW_BASE   (-0x1300)
	-0x1300~-0x13FF表达SDK在data-model模块内的状态码 更多...
#define	STATE_SHADOW_MQTT_HANDLE_IS_NULL   (-0x1301)
	用户未调用aiot_shadow_setopt 配置MQTT句柄 更多...
#define	STATE_SHADOW_REPORTED_DATA_IS_NULL   (-0x1302)
	用户上报AIOT_SHADOWMSG_UPDATE 或 AIOT_SHADOWMSG_DELETE_REPORTED 消息时, 消息结构体中的reported为NULL 更多...
#define	STATE_SHADOW_INTERNAL_TOPIC_ERROR   (-0x1303)
	解析下行数据对应的topic时发生错误 更多...
#define	STATE_SHADOW_LOG_RECV   (-0x1304)
	接收到服务器下行消息时的日志状态码 更多...
#define	SATAE_SHADOW_LOG_PARSE_RECV_MSG_FAILED   (-0x1305)
	解析服务器下行消息失败时的日志状态码 更多...

类型定义
typedef void(*	aiot_shadow_recv_handler_t) (void *handle, const aiot_shadow_recv_t *recv, void *userdata)
	shadow模块收到从网络上来的报文时, 通知用户所调用的数据回调函数 更多...

枚举
enum	aiot_shadow_option_t { AIOT_SHADOWOPT_MQTT_HANDLE, AIOT_SHADOWOPT_RECV_HANDLER, AIOT_SHADOWOPT_USERDATA, AIOT_SHADOWOPT_MAX }
	aiot_shadow_setopt 接口的option参数可选值. 更多...
enum	aiot_shadow_msg_type_t {   AIOT_SHADOWMSG_UPDATE, AIOT_SHADOWMSG_CLEAN_DESIRED, AIOT_SHADOWMSG_GET, AIOT_SHADOWMSG_DELETE_REPORTED,   AIOT_SHADOWMSG_MAX }
	shadow模块发送消息类型 更多...
enum	aiot_shadow_recv_type_t { AIOT_SHADOWRECV_GENERIC_REPLY, AIOT_SHADOWRECV_CONTROL, AIOT_SHADOWRECV_GET_REPLY }
	shadow模块收到从网络上来的报文时, 通知用户的报文类型 更多...

函数
void *	aiot_shadow_init (void)
	创建shadow会话实例, 并以默认值配置会话参数 更多...
int32_t	aiot_shadow_setopt (void *handle, aiot_shadow_option_t option, void *data)
	配置shadow会话 更多...
int32_t	aiot_shadow_send (void *handle, aiot_shadow_msg_t *msg)
	向服务器发送shadow消息请求 更多...
int32_t	aiot_shadow_deinit (void **handle)
	结束shadow会话, 销毁实例并回收资源 更多...

详细描述

shadow模块头文件, 提供更新, 删除, 获取设备影子的能力

版权所有

Copyright (C) 2015-2020 Alibaba Group Holding Limited

请按照以下流程使用API

1. 在使用设备影子模块前, 用户应首先创建好一个MQTT实例
2. 调用aiot_shadow_init创建一个设备影子实例, 保存实例句柄
3. 调用aiot_shadow_setopt配置AIOT_SHADOWOPT_MQTT_HANDLE选项以设置MQTT句柄, 此选项为强制配置选项
4. 调用aiot_shadow_setopt配置AIOT_SHADOWOPT_RECV_HANDLER和AIOT_SHADOWOPT_USERDATA选项以注册数据接受回调函数和用户上下文数据指针
5. 在使用aiot_shadow_send发送消息前, 应先完成MQTT实例的建连
6. 调动aiot_shadow_send发送更新设备影子, 获取设备影子或删除设备等消息到云平台, 在注册的回调函数中处理各种类型的云端应答消息或主动下推消息

宏定义说明

#define STATE_SHADOW_BASE   (-0x1300)

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

#define STATE_SHADOW_MQTT_HANDLE_IS_NULL   (-0x1301)

用户未调用aiot_shadow_setopt 配置MQTT句柄

#define STATE_SHADOW_REPORTED_DATA_IS_NULL   (-0x1302)

用户上报AIOT_SHADOWMSG_UPDATE 或 AIOT_SHADOWMSG_DELETE_REPORTED 消息时, 消息结构体中的reported为NULL

#define STATE_SHADOW_INTERNAL_TOPIC_ERROR   (-0x1303)

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

#define STATE_SHADOW_LOG_RECV   (-0x1304)

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

#define SATAE_SHADOW_LOG_PARSE_RECV_MSG_FAILED   (-0x1305)

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

类型定义说明

typedef void(* aiot_shadow_recv_handler_t) (void *handle, const aiot_shadow_recv_t *recv, void *userdata)

shadow模块收到从网络上来的报文时, 通知用户所调用的数据回调函数

参数

[in]	handle	shadow会话句柄
[in]	recv	shadow接受消息结构体, 存放收到的shadow报文内容
[in]	userdata	指向用户上下文数据的指针, 这个指针由用户通过调用aiot_shadow_setopt 配置AIOT_SHADOWOPT_USERDATA 选项设置

返回

void

枚举类型说明

enum aiot_shadow_option_t

aiot_shadow_setopt 接口的option参数可选值.

下文每个选项中的数据类型, 指的是aiot_shadow_setopt 中, data参数的数据类型

当data的数据类型是char *时, 以配置AIOT_SHADOWOPT_PRODUCT_KEY 为例:

char *product_key = "xxx"; aiot_shadow_setopt(shadow_handle, AIOT_SHADOWOPT_PRODUCT_KEY, product_key);

枚举值
AIOT_SHADOWOPT_MQTT_HANDLE	模块依赖的MQTT句柄 shadow模块依赖底层的MQTT模块, 用户必需配置正确的MQTT句柄, 否则无法正常工作, 数据类型为(void *)
AIOT_SHADOWOPT_RECV_HANDLER	设置回调, 它在SDK收到网络报文的时候被调用, 告知用户, 数据类型为(aiot_shadow_recv_handler_t)
AIOT_SHADOWOPT_USERDATA	用户需要SDK暂存的上下文, 数据类型为(void *) 这个上下文指针会在 AIOT_SHADOWOPT_RECV_HANDLER 设置的回调被调用时, 由SDK传给用户
AIOT_SHADOWOPT_MAX	配置选项数量最大值, 不可用作配置参数

enum aiot_shadow_msg_type_t

shadow模块发送消息类型

这个枚举类型包括了shadow模块支持发送的所有数据类型, 不同的消息类型将对于不同的消息结构体

枚举值
AIOT_SHADOWMSG_UPDATE	更新设备影子中的reported值, 消息结构体参考aiot_shadow_msg_update_t
AIOT_SHADOWMSG_CLEAN_DESIRED	清空设备影子的desired值, 消息结构体参考aiot_shadow_msg_clean_desired_t
AIOT_SHADOWMSG_GET	获取设备影子, 消息结构体参考aiot_shadow_msg_get_t
AIOT_SHADOWMSG_DELETE_REPORTED	删除设备影子的部分或全部reported值, 消息结构体参考aiot_shadow_msg_delete_reported_t
AIOT_SHADOWMSG_MAX	消息数量最大值, 不可用作消息类型

enum aiot_shadow_recv_type_t

shadow模块收到从网络上来的报文时, 通知用户的报文类型

枚举值
AIOT_SHADOWRECV_GENERIC_REPLY	设备发送 AIOT_SHADOWMSG_UPDATE, AIOT_SHADOWMSG_CLEAN_DESIRED 或 AIOT_SHADOWMSG_DELETE_REPORTED 这3这类型消息后, 云端返回的应答消息, 消息数据结构体参考 aiot_shadow_recv_generic_reply_t
AIOT_SHADOWRECV_CONTROL	设备在线时, 云端自动下发的影子内容, 消息数据结构体参考 aiot_shadow_recv_control_t
AIOT_SHADOWRECV_GET_REPLY	主动获取设备影子内容云端返回的影子内容, 消息数据结构体参考 aiot_shadow_recv_get_reply_t

函数说明

void* aiot_shadow_init

(

void

)

创建shadow会话实例, 并以默认值配置会话参数

返回

void *

返回值

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

函数调用图:

int32_t aiot_shadow_setopt	(	void *	handle,
		aiot_shadow_option_t	option,
		void *	data
	)

配置shadow会话

参数

[in]	handle	shadow会话句柄
[in]	option	配置选项, 更多信息请参考aiot_shadow_option_t
[in]	data	配置选项数据, 更多信息请参考aiot_shadow_option_t

返回

int32_t

返回值

STATE_SUCCESS	参数配置成功
STATE_USER_INPUT_NULL_POINTER	入参handle或data为NULL
STATE_USER_INPUT_OUT_RANGE	入参optioin的枚举值>=AIOT_SHADOWOPT_MAX
others	参考aiot_state_api.h

函数调用图:

int32_t aiot_shadow_send	(	void *	handle,
		aiot_shadow_msg_t *	msg
	)

向服务器发送shadow消息请求

参数

[in]	handle	shadow会话句柄
[in]	msg	消息结构体, 可指定发送消息的设备productKey, deviceName; 消息类型, 消息数据等, 更多信息请参考aiot_shadow_msg_t

返回

int32_t

返回值

STATE_SUCCESS	请求发送成功
STATE_USER_INPUT_NULL_POINTER	入参handle或msg为NULL
STATE_USER_INPUT_OUT_RANGE	入参msg的结构体成员type >= AIOT_SHADOWMSG_MAX
STATE_SYS_DEPEND_MALLOC_FAILED	内存分配失败
STATE_SHADOW_MQTT_HANDLE_IS_NULL	用户未调用aiot_shadow_setopt 配置MQTT句柄
others	参考aiot_state_api.h 或STATE_SHADOW_BASE 中对应的错误码说明

函数调用图:

int32_t aiot_shadow_deinit

(

void **

handle

)

结束shadow会话, 销毁实例并回收资源

参数

[in]

handle

指向shadow会话句柄的指针

返回

int32_t

返回值

STATE_SUCCESS	执行成功
<STATE_SUCCESS	执行失败

函数调用图: