Link Kit C-SDK  4.0.0
| 宏定义 | 类型定义 | 枚举 | 函数
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_DESIREDAIOT_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_UPDATEAIOT_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模块头文件, 提供更新, 删除, 获取设备影子的能力

请按照以下流程使用API

  1. 在使用设备影子模块前, 用户应首先创建好一个MQTT实例
  2. 调用aiot_shadow_init创建一个设备影子实例, 保存实例句柄
  3. 调用aiot_shadow_setopt配置AIOT_SHADOWOPT_MQTT_HANDLE选项以设置MQTT句柄, 此选项为强制配置选项
  4. 调用aiot_shadow_setopt配置AIOT_SHADOWOPT_RECV_HANDLERAIOT_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_UPDATEAIOT_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]handleshadow会话句柄
[in]recvshadow接受消息结构体, 存放收到的shadow报文内容
[in]userdata指向用户上下文数据的指针, 这个指针由用户通过调用aiot_shadow_setopt 配置AIOT_SHADOWOPT_USERDATA 选项设置
返回
void

枚举类型说明

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 

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

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 

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

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

枚举值
AIOT_SHADOWRECV_GENERIC_REPLY 

设备发送 AIOT_SHADOWMSG_UPDATE, AIOT_SHADOWMSG_CLEAN_DESIREDAIOT_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 *
返回值
非NULLshadow实例的句柄
NULL初始化失败, 一般是内存分配失败导致

函数调用图:

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

配置shadow会话

参数
[in]handleshadow会话句柄
[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]handleshadow会话句柄
[in]msg消息结构体, 可指定发送消息的设备productKey, deviceName; 消息类型, 消息数据等, 更多信息请参考aiot_shadow_msg_t
返回
int32_t
返回值
STATE_SUCCESS请求发送成功
STATE_USER_INPUT_NULL_POINTER入参handlemsg为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.hSTATE_SHADOW_BASE 中对应的错误码说明

函数调用图:

int32_t aiot_shadow_deinit ( void **  handle)

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

参数
[in]handle指向shadow会话句柄的指针
返回
int32_t
返回值
STATE_SUCCESS执行成功
<STATE_SUCCESS执行失败

函数调用图: