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

HTTP模块头文件, 提供用HTTP协议向阿里云物联网平台上报数据的能力 更多...

#include "core_stdinc.h"
aiot_http_api.h 的引用(Include)关系图:

浏览源代码.

struct  aiot_http_recv_t
 SDK收到HTTP报文, 传递给用户数据回调函数时, 对报文内容的描述 更多...
 
struct  aiot_http_event_t
 SDK内部发生状态变化, 通过用户事件回调函数通知用户时, 对事件内容的描述 更多...
 

类型定义

typedef void(* aiot_http_recv_handler_t) (void *handle, const aiot_http_recv_t *packet, void *userdata)
 HTTP 消息接收回调函数原型, 可以通过 aiot_http_setopt 接口的 AIOT_HTTPOPT_RECV_HANDLER 参数指定 更多...
 
typedef void(* aiot_http_event_handler_t) (void *handle, const aiot_http_event_t *event, void *userdata)
 HTTP 事件回调函数原型, 可以通过 aiot_http_setopt 接口的 AIOT_HTTPOPT_EVENT_HANDLER 参数指定 更多...
 

枚举

enum  aiot_http_response_code_t {
  AIOT_HTTP_RSPCODE_SUCCESS = 0, AIOT_HTTP_RSPCODE_COMMON_ERROR = 10000, AIOT_HTTP_RSPCODE_PARAM_ERROR = 10001, AIOT_HTTP_RSPCODE_TOKEN_EXPIRED = 20001,
  AIOT_HTTP_RSPCODE_TOKEN_NULL = 20002, AIOT_HTTP_RSPCODE_TOKEN_CHECK_ERROR = 20003, AIOT_HTTP_RSPCODE_PUBLISH_MESSAGE_ERROR = 30001, AIOT_HTTP_RSPCODE_REQUEST_TOO_MANY = 40000
}
 服务器返回的业务错误码 更多...
 
enum  aiot_http_option_t {
  AIOT_HTTPOPT_HOST, AIOT_HTTPOPT_PORT, AIOT_HTTPOPT_NETWORK_CRED, AIOT_HTTPOPT_CONNECT_TIMEOUT_MS,
  AIOT_HTTPOPT_SEND_TIMEOUT_MS, AIOT_HTTPOPT_RECV_TIMEOUT_MS, AIOT_HTTPOPT_DEINIT_TIMEOUT_MS, AIOT_HTTPOPT_HEADER_BUFFER_LEN,
  AIOT_HTTPOPT_BODY_BUFFER_LEN, AIOT_HTTPOPT_EVENT_HANDLER, AIOT_HTTPOPT_USERDATA, AIOT_HTTPOPT_RECV_HANDLER,
  AIOT_HTTPOPT_PRODUCT_KEY, AIOT_HTTPOPT_DEVICE_NAME, AIOT_HTTPOPT_DEVICE_SECRET, AIOT_HTTPOPT_EXTEND_DEVINFO,
  AIOT_HTTPOPT_AUTH_TIMEOUT_MS, AIOT_HTTPOPT_LONG_CONNECTION, AIOT_HTTPOPT_MAX
}
 aiot_http_setopt 函数的 option 参数, 对于下文每一个选项中的数据类型, 指的是 aiot_mqtt_setopt 中的data参数的数据类型 更多...
 
enum  aiot_http_recv_type_t { AIOT_HTTPRECV_STATUS_CODE, AIOT_HTTPRECV_HEADER, AIOT_HTTPRECV_BODY }
 SDK收到HTTP报文, 传递给用户数据回调函数时, 对报文类型的描述 更多...
 
enum  aiot_http_event_type_t { AIOT_HTTPEVT_TOKEN_INVALID }
 SDK内部发生状态变化, 通过用户事件回调函数通知用户时, 对事件类型的描述 更多...
 

函数

void * aiot_http_init (void)
 创建一个HTTP上云实例 更多...
 
int32_t aiot_http_setopt (void *handle, aiot_http_option_t option, void *data)
 设置HTTP实例参数 更多...
 
int32_t aiot_http_auth (void *handle)
 向服务器发送认证请求, 获取token 更多...
 
int32_t aiot_http_send (void *handle, char *topic, uint8_t *payload, uint32_t payload_len)
 上报数据到物联网平台 更多...
 
int32_t aiot_http_recv (void *handle)
 接受HTTP应答数据, 数据会从用户设置的 aiot_http_event_handler_t 回调函数输出 更多...
 
int32_t aiot_http_deinit (void **p_handle)
 销毁参数p_handle所指定的HTTP实例 更多...
 

详细描述

HTTP模块头文件, 提供用HTTP协议向阿里云物联网平台上报数据的能力

日期
2019-12-27

类型定义说明

typedef void(* aiot_http_recv_handler_t) (void *handle, const aiot_http_recv_t *packet, void *userdata)

HTTP 消息接收回调函数原型, 可以通过 aiot_http_setopt 接口的 AIOT_HTTPOPT_RECV_HANDLER 参数指定

当SDK收到 HTTP 服务器的应答数据时, 通过此回调函数输出

参数
[out]handleHTTP 句柄
[out]packet从 HTTP 服务器接收到的数据
[out]userdata用户通过 AIOT_HTTPOPT_USERDATA 交由SDK暂存的上下文
返回
void
typedef void(* aiot_http_event_handler_t) (void *handle, const aiot_http_event_t *event, void *userdata)

HTTP 事件回调函数原型, 可以通过 aiot_http_setopt 接口的 AIOT_HTTPOPT_EVENT_HANDLER 参数指定

参数
[out]handleHTTP句柄
[out]event事件结构体
[out]user_data指向用户上下文数据的指针, 由 aiot_http_setoptAIOT_HTTPOPT_USERDATA 选项设置

枚举类型说明

服务器返回的业务错误码

从云平台对上报消息回应的报文JSON中解析

枚举值
AIOT_HTTP_RSPCODE_SUCCESS 

0, 服务端成功接收到上报的消息

AIOT_HTTP_RSPCODE_COMMON_ERROR 

10000, 服务端返回未知错误

AIOT_HTTP_RSPCODE_PARAM_ERROR 

10001, 请求参数错误

AIOT_HTTP_RSPCODE_TOKEN_EXPIRED 

20001, token过期, 请调用 aiot_http_auth 进行鉴权, 获取新token

AIOT_HTTP_RSPCODE_TOKEN_NULL 

20002, 请求的header中无token可表明设备端合法, 请调用 aiot_http_auth 进行鉴权, 获取新token

AIOT_HTTP_RSPCODE_TOKEN_CHECK_ERROR 

20003, token错误, 请调用 aiot_http_auth 进行鉴权, 获取新token

AIOT_HTTP_RSPCODE_PUBLISH_MESSAGE_ERROR 

30001, 消息上报失败

AIOT_HTTP_RSPCODE_REQUEST_TOO_MANY 

40000, 设备端上报过于频繁, 触发服务端限流

aiot_http_setopt 函数的 option 参数, 对于下文每一个选项中的数据类型, 指的是 aiot_mqtt_setopt 中的data参数的数据类型

枚举值
AIOT_HTTPOPT_HOST 

HTTP 服务器的域名地址或者ip地址

阿里云物联网平台域名地址列表: (tcp使用80端口, tls使用443端口)

域名地址 区域 端口号
iot-as-http.cn-shanghai.aliyuncs.com 上海 443

数据类型: (char *)

AIOT_HTTPOPT_PORT 

HTTP 服务器的端口号

连接阿里云物联网平台时:

1.如果使用的是tcp, 端口号设置为80

  1. 如果使用的是tls, 端口号设置为443

数据类型: (uint16_t *)

AIOT_HTTPOPT_NETWORK_CRED 

HTTP建联时, 网络使用的安全凭据

该配置项用于为底层网络配置 aiot_sysdep_network_cred_t 安全凭据数据

  1. 若该选项不配置, 那么MQTT将以tcp方式直接建联
  2. aiot_sysdep_network_cred_t 中option配置为 AIOT_SYSDEP_NETWORK_CRED_NONE , HTTP将以tcp方式直接建联
  3. aiot_sysdep_network_cred_t 中option配置为 AIOT_SYSDEP_NETWORK_CRED_SVRCERT_CA , HTTP将以tls方式建联

数据类型: (aiot_sysdep_network_cred_t *)

AIOT_HTTPOPT_CONNECT_TIMEOUT_MS 

HTTP建联时, 建立网络连接的超时时间

指建立socket连接的超时时间

数据类型: (uint32_t *) 默认值: (5 *1000) ms

AIOT_HTTPOPT_SEND_TIMEOUT_MS 

HTTP发送数据时, 在协议栈花费的最长时间

数据类型: (uint32_t *) 默认值: (5 * 1000) ms

AIOT_HTTPOPT_RECV_TIMEOUT_MS 

HTTP接收数据时, 在协议栈花费的最长时间

数据类型: (uint32_t *) 默认值: (5 * 1000) ms

AIOT_HTTPOPT_DEINIT_TIMEOUT_MS 

销毁HTTP实例时, 等待其他api执行完毕的时间

当调用 aiot_http_deinit 销毁HTTP实例时, 若继续调用其他 aiot_http_xxx API, API会返回STATE_USER_INPUT_EXEC_DISABLED 错误

此时, 用户应该停止调用其他 aiot_http_xxx API

数据类型: (uint32_t *) 默认值: (2 * 1000) ms

AIOT_HTTPOPT_HEADER_BUFFER_LEN 

当接收服务器返回的http报文时, 单行http header的最大长度

当单行http header设置过短时, aiot_http_recv 会返回 STATE_HTTP_HEADER_BUFFER_TOO_SHORT 状态码

数据类型: (uint32_t *) 默认值: 128

AIOT_HTTPOPT_BODY_BUFFER_LEN 

当接收服务器返回的http报文时, 每次从 aiot_http_recv_handler_t 回调函数中给出的body最大长度

数据类型: (uint32_t *) 默认值: 128

AIOT_HTTPOPT_EVENT_HANDLER 

HTTP 内部事件回调函数

数据类型: (aiot_http_event_handler_t)

AIOT_HTTPOPT_USERDATA 

用户需要SDK暂存的上下文

  1. 当接收到HTTP数据时, 该上下文会从 aiot_http_recv_handler_t 的 userdata 参数给出
  2. 当HTTP内部有事件发生时, 该上下文会从 aiot_http_event_handler_t 的 userdata 参数给出

数据类型: (void *)

AIOT_HTTPOPT_RECV_HANDLER 

HTTP 数据接收回调函数

数据类型: (aiot_http_recv_handler_t)

AIOT_HTTPOPT_PRODUCT_KEY 

设备的product key, 可从阿里云物联网平台控制台获取

数据类型: (char *)

AIOT_HTTPOPT_DEVICE_NAME 

设备的device name, 可从阿里云物联网平台控制台获取

数据类型: (char *)

AIOT_HTTPOPT_DEVICE_SECRET 

设备的device secret, 可从阿里云物联网平台控制台获取

数据类型: (char *)

AIOT_HTTPOPT_EXTEND_DEVINFO 

上报设备的扩展信息, 比如模组商ID和模组ID

  1. 模组商ID: 格式为pid=xxx
  2. 模组ID: 格式为mid=xxx

如果需要同时上报多个信息, 那么它们之间用&连接, 例如: pid=xxx&mid=xxx

数据类型: (char *)

AIOT_HTTPOPT_AUTH_TIMEOUT_MS 

使用 aiot_http_auth 进行认证并获取token的超时时间

数据类型: (uint32_t *) 默认值: (5 * 1000) ms

AIOT_HTTPOPT_LONG_CONNECTION 

是否使用http长连接

若该配置的值为0, 则每次使用 aiot_http_authaiot_http_send 时, SDK会重新与 HTTP 服务器建立简介

数据类型: (uint8_t *) 默认值: (5 * 1000) ms

AIOT_HTTPOPT_MAX 

SDK收到HTTP报文, 传递给用户数据回调函数时, 对报文类型的描述

枚举值
AIOT_HTTPRECV_STATUS_CODE 

获取到HTTP Status Code

AIOT_HTTPRECV_HEADER 

获取到HTTP Header, 每次返回Header中的一组键值对

AIOT_HTTPRECV_BODY 

获取到HTTP Body, 返回完整的Body内容

SDK内部发生状态变化, 通过用户事件回调函数通知用户时, 对事件类型的描述

枚举值
AIOT_HTTPEVT_TOKEN_INVALID 

token无效事件, 此时用户应该调用 aiot_http_auth 获取新的token

函数说明

void* aiot_http_init ( void  )

创建一个HTTP上云实例

返回
void*
返回值
非NULL,HTTP实例句柄
NULL,初始化HTTP 实例失败
int32_t aiot_http_setopt ( void *  handle,
aiot_http_option_t  option,
void *  data 
)

设置HTTP实例参数

参数
[in]handleHTTP句柄
[in]option配置选项, 更多信息请参考 aiot_http_option_t
[in]data配置数据, 更多信息请参考 aiot_http_option_t
返回
int32_t
返回值
STATE_SUCCESS,成功
STATE_HTTP_HANDLE_IS_NULL,HTTP句柄为NULL
STATE_USER_INPUT_OUT_RANGE,用户输入参数无效
STATE_SYS_DEPEND_MALLOC_FAILED,内存分配失败

函数调用图:

int32_t aiot_http_auth ( void *  handle)

向服务器发送认证请求, 获取token

参数
[in]handleHTTP句柄
返回
int32_t
返回值
STATE_SUCCESS,认证成功
STATE_HTTP_HANDLE_IS_NULL,HTTP句柄为NULL
STATE_USER_INPUT_MISSING_PRODUCT_KEY,未设置必要选项ProductKey
STATE_USER_INPUT_MISSING_DEVICE_NAME,未设置必要选项DeviceName
STATE_USER_INPUT_MISSING_DEVICE_SECRET,未设置必要选项DeviceSecret
STATE_HTTP_TOKEN_LEN_ERROR,token长度错误
STATE_HTTP_GET_TOKEN_FAILED,获取token失败

函数调用图:

int32_t aiot_http_send ( void *  handle,
char *  topic,
uint8_t *  payload,
uint32_t  payload_len 
)

上报数据到物联网平台

参数
[in]handleHTTP句柄
[in]topic上报的目标topic, 在物联网平台控制的产品详情页面有设备的完整topic列表
[in]payload指向上报数据的指针
[in]payload_len上报数据的长度
返回
int32_t
返回值
STATE_SUCCESS,上报成功
STATE_HTTP_HANDLE_IS_NULL,HTTP句柄为NULL
STATE_USER_INPUT_OUT_RANGE,用户输入参数无效
STATE_HTTP_NOT_AUTH,设备未认证

函数调用图:

int32_t aiot_http_recv ( void *  handle)

接受HTTP应答数据, 数据会从用户设置的 aiot_http_event_handler_t 回调函数输出

服务器响应数据格式为 { "code": 0, // 业务状态码 "message": "success", // 业务信息 "info": { "messageId": 892687627916247040, } }

参数
[in]handleHTTP句柄
返回
int32_t
返回值
>=0, 接受到的HTTP body数据长度
STATE_HTTP_HANDLE_IS_NULL,HTTP句柄为NULL
STATE_USER_INPUT_NULL_POINTER,用户输入参数为NULL
STATE_USER_INPUT_OUT_RANGE,buffer_len为0
STATE_HTTP_RSP_MSG_ERROR,服务器应答消息错误
STATE_SYS_DEPEND_NWK_CLOSED,网络连接已关闭
STATE_SYS_DEPEND_NWK_READ_OVERTIME,网络接收超时
STATE_HTTP_RECV_LINE_TOO_LONG,HTTP单行数据过长,内部无法解析
STATE_HTTP_PARSE_STATUS_LINE_FAILED,无法解析状态码
STATE_HTTP_GET_CONTENT_LEN_FAILED,获取Content-Length失败

函数调用图:

int32_t aiot_http_deinit ( void **  p_handle)

销毁参数p_handle所指定的HTTP实例

参数
[in]p_handle指向HTTP句柄的指针
返回
int32_t
返回值
STATE_SUCCESS成功
STATE_USER_INPUT_NULL_POINTER参数p_handle为NULL或者p_handle指向的句柄为NULL