1 /** 2 * @file aiot_dynreg_api.h 3 * @brief dynreg模块头文件, 提供获取设备信息的能力 4 * 5 * @copyright Copyright (C) 2015-2020 Alibaba Group Holding Limited 6 * 7 */ 8 #ifndef __AIOT_DYNREG_API_H__ 9 #define __AIOT_DYNREG_API_H__ 10 11 #if defined(__cplusplus) 12 extern "C" { 13 #endif 14 15 #include <stdint.h> 16 17 /** 18 * @brief -0x0600~-0x06FF表达SDK在dynreg模块内的状态码 19 */ 20 #define STATE_DYNREG_BASE (-0x0600) 21 22 /** 23 * @brief 执行@ref aiot_dynreg_deinit 时, 等待其他API执行结束的超过设定的超时时间, MQTT实例销毁失败 24 */ 25 #define STATE_DYNREG_DEINIT_TIMEOUT (-0x0601) 26 27 /** 28 * @brief 需要首先执行@ref aiot_dynreg_send_request 发送dynreg请求 29 */ 30 #define STATE_DYNREG_NEED_SEND_REQUEST (-0x0602) 31 32 /** 33 * @brief dynreg模块返回了错误的http status code 34 */ 35 #define STATE_DYNREG_INVALID_STATUS_CODE (-0x0603) 36 37 /** 38 * @brief 收到非法的device secret 39 */ 40 #define STATE_DYNREG_INVALID_DEVICE_SECRET (-0x0604) 41 42 /** 43 * @brief dynreg模块收到从网络上来的报文时, 通知用户的报文类型 44 */ 45 typedef enum { 46 /** 47 * @brief dynreg模块返回的http status code 48 */ 49 AIOT_DYNREGRECV_STATUS_CODE, 50 /** 51 * @brief dynreg模块返回的设备信息 52 */ 53 AIOT_DYNREGRECV_DEVICE_INFO, 54 } aiot_dynreg_recv_type_t; 55 56 /** 57 * @brief dynreg模块收到从网络上来的报文时, 通知用户的报文内容 58 */ 59 typedef struct { 60 /** 61 * @brief 报文内容所对应的报文类型, 更多信息请参考@ref aiot_dynreg_recv_type_t 62 */ 63 aiot_dynreg_recv_type_t type; 64 union { 65 /** 66 * @brief dynreg模块返回的http status code 67 */ 68 struct { 69 uint32_t code; 70 } status_code; 71 /** 72 * @brief dynreg模块返回的设备信息 73 */ 74 struct { 75 char *device_secret; 76 } device_info; 77 } data; 78 } aiot_dynreg_recv_t; 79 80 /** 81 * @brief dynreg模块收到从网络上来的报文时, 通知用户所调用的数据回调函数 82 * 83 * @param[in] handle dynreg会话句柄 84 * @param[in] packet dynreg消息结构体, 存放收到的dynreg报文内容 85 * @param[in] userdata 用户上下文 86 * 87 * @return void 88 */ 89 typedef void (* aiot_dynreg_recv_handler_t)(void *handle, 90 const aiot_dynreg_recv_t *packet, void *userdata); 91 92 /** 93 * @brief @ref aiot_dynreg_setopt 接口的option参数可选值. 94 * 95 * @details 下文每个选项中的数据类型, 指的是@ref aiot_dynreg_setopt 中, data参数的数据类型 96 * 97 * 1. data的数据类型是char *时, 以配置@ref AIOT_DYNREGOPT_HOST 为例: 98 * 99 * char *host = "xxx"; 100 * aiot_dynreg_setopt(dynreg_handle, AIOT_DYNREGOPT_HOST, host); 101 * 102 * 2. data的数据类型是其他数据类型时, 以配置@ref AIOT_DYNREGOPT_PORT 为例: 103 * 104 * uint16_t port = 443; 105 * aiot_mqtt_setopt(dynreg_handle, AIOT_DYNREGOPT_PORT, (void *)&port); 106 */ 107 typedef enum { 108 /** 109 * @brief http动态注册 服务器建联时, 网络使用的安全凭据 110 * 111 * @details 112 * 113 * 该配置项用于为底层网络配置@ref aiot_sysdep_network_cred_t 安全凭据数据 114 * 115 * 应当把 @ref aiot_sysdep_network_cred_t 中option配置为@ref AIOT_SYSDEP_NETWORK_CRED_SVRCERT_CA , 以tls方式建联 116 * 117 * 数据类型: (aiot_sysdep_network_cred_t *) 118 */ 119 AIOT_DYNREGOPT_NETWORK_CRED, 120 121 /** 122 * @brief http动态注册 服务器的域名地址或者ip地址 123 * 124 * @details 125 * 126 * 阿里云物联网平台 http动态注册 服务器域名地址列表: 127 * 128 * | 域名地址 | 区域 | 端口号 129 * |-------------------------------------------------|---------|--------- 130 * | iot-auth.cn-shanghai.aliyuncs.com | 国内 | 443 131 * | iot-auth.ap-southeast-1.aliyuncs.com | 海外 | 443 132 * 133 * 数据类型: (char *) 134 */ 135 AIOT_DYNREGOPT_HOST, 136 137 /** 138 * @brief http动态注册 服务器的端口号 139 * 140 * @details 141 * 142 * 连接阿里云物联网平台 http动态注册 服务器时: 143 * 144 * 必须使用tls方式建联, 端口号设置为443 145 * 146 * 数据类型: (uint16_t *) 147 */ 148 AIOT_DYNREGOPT_PORT, 149 150 /** 151 * @brief 设备的productKey, 可从<a href="http://iot.console.aliyun.com/">阿里云物联网平台控制台</a>获取 152 * 153 * @details 154 * 155 * 数据类型: (char *) 156 */ 157 AIOT_DYNREGOPT_PRODUCT_KEY, 158 159 /** 160 * @brief 设备的productSecret, 可从<a href="http://iot.console.aliyun.com/">阿里云物联网平台控制台</a>获取 161 * 162 * @details 163 * 164 * 数据类型: (char *) 165 */ 166 AIOT_DYNREGOPT_PRODUCT_SECRET, 167 168 /** 169 * @brief 设备的deviceName, 可从<a href="http://iot.console.aliyun.com/">阿里云物联网平台控制台</a>获取 170 * 171 * @details 172 * 173 * 数据类型: (char *) 174 */ 175 AIOT_DYNREGOPT_DEVICE_NAME, 176 177 /** 178 * @brief dynreg会话发送消息时可消费的最长时间间隔 179 * 180 * @details 181 * 182 * 数据类型: (uint32_t) 默认值: (5 * 1000) ms 183 */ 184 AIOT_DYNREGOPT_SEND_TIMEOUT_MS, 185 186 /** 187 * @brief dynreg会话接收消息时可消费的最长时间间隔 188 * 189 * @details 190 * 191 * 数据类型: (uint32_t) 默认值: (5 * 1000) ms 192 */ 193 AIOT_DYNREGOPT_RECV_TIMEOUT_MS, 194 195 /** 196 * @brief 设置回调, 它在SDK收到网络报文的时候被调用, 告知用户 197 * 198 * @details 199 * 200 * 数据类型: (aiot_dynreg_http_recv_handler_t) 201 */ 202 AIOT_DYNREGOPT_RECV_HANDLER, 203 204 /** 205 * @brief 用户需要SDK暂存的上下文 206 * 207 * @details 208 * 209 * 这个上下文指针会在 AIOT_DYNREGOPT_RECV_HANDLER 和 AIOT_DYNREGOPT_EVENT_HANDLER 设置的回调被调用时, 由SDK传给用户 210 * 211 * 数据类型: (void *) 212 */ 213 AIOT_DYNREGOPT_USERDATA, 214 215 /** 216 * @brief dynreg模块接收消息的超时时间 217 * 218 * @details 219 * 220 * 数据类型: (uint32_t) 默认值: (5 * 1000) ms 221 */ 222 AIOT_DYNREGOPT_TIMEOUT_MS, 223 224 /** 225 * @brief 销毁dynreg实例时, 等待其他api执行完毕的时间 226 * 227 * @details 228 * 229 * 当调用@ref aiot_dynreg_deinit 销毁MQTT实例时, 若继续调用其他aiot_dynreg_xxx API, API会返回@ref STATE_USER_INPUT_EXEC_DISABLED 错误 230 * 231 * 此时, 用户应该停止调用其他aiot_dynreg_xxx API 232 * 233 * 数据类型: (uint32_t *) 默认值: (2 * 1000) ms 234 */ 235 AIOT_DYNREGOPT_DEINIT_TIMEOUT_MS, 236 AIOT_DYNREGOPT_MAX 237 } aiot_dynreg_option_t; 238 239 /** 240 * @brief 创建dynreg会话实例, 并以默认值配置会话参数 241 * 242 * @return void * 243 * @retval 非NULL dynreg实例的句柄 244 * @retval NULL 初始化失败, 一般是内存分配失败导致 245 * 246 */ 247 void *aiot_dynreg_init(void); 248 249 /** 250 * @brief 配置dynreg会话 251 * 252 * @param[in] handle dynreg会话句柄 253 * @param[in] option 配置选项, 更多信息请参考@ref aiot_dynreg_option_t 254 * @param[in] data 配置选项数据, 更多信息请参考@ref aiot_dynreg_option_t 255 * 256 * @return int32_t 257 * @retval <STATE_SUCCESS 参数配置失败 258 * @retval >=STATE_SUCCESS 参数配置成功 259 * 260 */ 261 int32_t aiot_dynreg_setopt(void *handle, aiot_dynreg_option_t option, void *data); 262 263 /** 264 * @brief 结束dynreg会话, 销毁实例并回收资源 265 * 266 * @param[in] handle 指向dynreg会话句柄的指针 267 * 268 * @return int32_t 269 * @retval <STATE_SUCCESS 执行失败 270 * @retval >=STATE_SUCCESS 执行成功 271 * 272 */ 273 int32_t aiot_dynreg_deinit(void **handle); 274 275 /** 276 * @brief 向dynreg服务器发送dynreg消息请求 277 * 278 * @param handle dynreg会话句柄 279 * 280 * @return int32_t 281 * @retval <STATE_SUCCESS 请求发送失败 282 * @retval >=STATE_SUCCESS 请求发送成功 283 */ 284 int32_t aiot_dynreg_send_request(void *handle); 285 286 /** 287 * @brief 从网络上收取dynreg消息 288 * 289 * @param handle dynreg会话句柄 290 * 291 * @return int32_t 292 * @retval <STATE_SUCCESS 数据接收失败 293 * @retval >=STATE_SUCCESS 数据接收成功 294 */ 295 int32_t aiot_dynreg_recv(void *handle); 296 297 #if defined(__cplusplus) 298 } 299 #endif 300 301 #endif /* __AIOT_DYNREG_API_H__ */ 302 303