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

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

类型定义说明

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]	handle	HTTP 句柄
[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]	handle	HTTP句柄
[out]	event	事件结构体
[out]	user_data	指向用户上下文数据的指针, 由 aiot_http_setopt 的 AIOT_HTTPOPT_USERDATA 选项设置

枚举类型说明

enum aiot_http_response_code_t

服务器返回的业务错误码

从云平台对上报消息回应的报文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, 设备端上报过于频繁, 触发服务端限流

enum aiot_http_option_t

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

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

数据类型: (uint16_t *)

AIOT_HTTPOPT_NETWORK_CRED

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

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

若该选项不配置, 那么MQTT将以tcp方式直接建联
若 aiot_sysdep_network_cred_t 中option配置为 AIOT_SYSDEP_NETWORK_CRED_NONE , HTTP将以tcp方式直接建联
若 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暂存的上下文

当接收到HTTP数据时, 该上下文会从 aiot_http_recv_handler_t 的 userdata 参数给出
当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

模组商ID: 格式为pid=xxx
模组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_auth 和 aiot_http_send 时, SDK会重新与 HTTP 服务器建立简介

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

AIOT_HTTPOPT_MAX

enum aiot_http_recv_type_t

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

枚举值
AIOT_HTTPRECV_STATUS_CODE	获取到HTTP Status Code
AIOT_HTTPRECV_HEADER	获取到HTTP Header, 每次返回Header中的一组键值对
AIOT_HTTPRECV_BODY	获取到HTTP Body, 返回完整的Body内容

enum aiot_http_event_type_t

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]	handle	HTTP句柄
[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] handle HTTP句柄

返回: 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]	handle	HTTP句柄
[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] handle HTTP句柄

返回: 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