aiot_mqtt_api.h 文件参考

MQTT模块头文件, 提供用MQTT协议连接阿里云物联网平台的能力 更多...

#include <stdint.h>

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

此图展示该文件直接或间接的被哪些文件引用了:

浏览源代码.

类
struct	len_value_t
	value-length 结构体. 更多...
struct	user_property_t
	MQTT 5.0协议中用户属性 更多...
struct	connack_property_t
	MQTT 5.0协议中, 下行的conack报文conack中的属性 更多...
struct	pub_property_t
	MQTT 5.0协议中, 上行和下行pub报文中的属性. 更多...
struct	conn_property_t
	MQTT 5.0协议中, 上行的connect报文中的属性. 更多...
struct	disconn_property_t
	MQTT 5.0协议中, 上行的disconnect报文中的属性. 更多...
struct	sub_property_t
	MQTT 5.0协议中, 上行的subscribe报文中的属性. 更多...
struct	unsub_property_t
	MQTT 5.0协议中, 上行的subscribe报文中的属性. 更多...
struct	aiot_mqtt_recv_t
struct	aiot_mqtt_event_t
	MQTT内部事件 更多...
struct	aiot_mqtt_topic_map_t
	使用 aiot_mqtt_setopt 配置 AIOT_MQTTOPT_APPEND_TOPIC_MAP 时的数据 更多...

宏定义
#define	USER_PROPERTY_MAX   (20)

类型定义
typedef void(*	aiot_mqtt_recv_handler_t) (void *handle, const aiot_mqtt_recv_t *packet, void *userdata)
	MQTT报文接收回调函数原型 更多...
typedef void(*	aiot_mqtt_event_handler_t) (void *handle, const aiot_mqtt_event_t *event, void *userdata)
	MQTT事件回调函数 更多...

枚举
enum	aiot_mqtt_recv_type_t {   AIOT_MQTTRECV_PUB, AIOT_MQTTRECV_HEARTBEAT_RESPONSE, AIOT_MQTTRECV_SUB_ACK, AIOT_MQTTRECV_UNSUB_ACK,   AIOT_MQTTRECV_PUB_ACK, AIOT_MQTTRECV_CON_ACK, AIOT_MQTTRECV_DISCONNECT }
	MQTT报文类型 更多...
enum	aiot_mqtt_protocol_version { AIOT_MQTT_VERSION_3_1, AIOT_MQTT_VERSION_5_0 }
	MQTT协议版本 更多...
enum	aiot_mqtt_event_type_t { AIOT_MQTTEVT_CONNECT, AIOT_MQTTEVT_RECONNECT, AIOT_MQTTEVT_DISCONNECT }
	MQTT内部事件类型 更多...
enum	aiot_mqtt_disconnect_event_type_t { AIOT_MQTTDISCONNEVT_NETWORK_DISCONNECT, AIOT_MQTTDISCONNEVT_HEARTBEAT_DISCONNECT }
enum	aiot_mqtt_option_t {   AIOT_MQTTOPT_HOST, AIOT_MQTTOPT_PORT, AIOT_MQTTOPT_PRODUCT_KEY, AIOT_MQTTOPT_DEVICE_NAME,   AIOT_MQTTOPT_DEVICE_SECRET, AIOT_MQTTOPT_EXTEND_CLIENTID, AIOT_MQTTOPT_SECURITY_MODE, AIOT_MQTTOPT_USERNAME,   AIOT_MQTTOPT_PASSWORD, AIOT_MQTTOPT_CLIENTID, AIOT_MQTTOPT_KEEPALIVE_SEC, AIOT_MQTTOPT_CLEAN_SESSION,   AIOT_MQTTOPT_NETWORK_CRED, AIOT_MQTTOPT_CONNECT_TIMEOUT_MS, AIOT_MQTTOPT_HEARTBEAT_INTERVAL_MS, AIOT_MQTTOPT_HEARTBEAT_MAX_LOST,   AIOT_MQTTOPT_RECONN_ENABLED, AIOT_MQTTOPT_RECONN_INTERVAL_MS, AIOT_MQTTOPT_SEND_TIMEOUT_MS, AIOT_MQTTOPT_RECV_TIMEOUT_MS,   AIOT_MQTTOPT_REPUB_TIMEOUT_MS, AIOT_MQTTOPT_DEINIT_TIMEOUT_MS, AIOT_MQTTOPT_RECV_HANDLER, AIOT_MQTTOPT_EVENT_HANDLER,   AIOT_MQTTOPT_APPEND_TOPIC_MAP, AIOT_MQTTOPT_REMOVE_TOPIC_MAP, AIOT_MQTTOPT_APPEND_REQUESTID, AIOT_MQTTOPT_USERDATA,   AIOT_MQTTOPT_VERSION, AIOT_MQTTOPT_ASSIGNED_CLIENTID, AIOT_MQTTOPT_FLOW_CONTROL_ENABLED, AIOT_MQTTOPT_MAX }
	aiot_mqtt_setopt 函数的option参数. 对于下文每一个选项中的数据类型, 指的是aiot_mqtt_setopt 中的data参数的数据类型 更多...

函数
void *	aiot_mqtt_init (void)
	初始化mqtt实例并设置默认参数 更多...
int32_t	aiot_mqtt_setopt (void *handle, aiot_mqtt_option_t option, void *data)
	设置mqtt参数 更多...
int32_t	aiot_mqtt_deinit (void **handle)
	释放mqtt实例句柄的资源 更多...
int32_t	aiot_mqtt_connect (void *handle)
	与MQTT服务器建立连接 更多...
int32_t	aiot_mqtt_disconnect (void *handle)
	与MQTT服务器断开连接 更多...
int32_t	aiot_mqtt_heartbeat (void *handle)
	发送MQTT PINGREQ报文, 用于维持心跳 更多...
int32_t	aiot_mqtt_process (void *handle)
	此函数用于处理定时心跳发送和qos1消息的重传逻辑 更多...
int32_t	aiot_mqtt_pub (void *handle, char *topic, uint8_t *payload, uint32_t payload_len, uint8_t qos)
	发送一条PUBLISH报文到MQTT服务器, QoS为0, 用于发布指定的消息 更多...
int32_t	aiot_mqtt_sub (void *handle, char *topic, aiot_mqtt_recv_handler_t handler, uint8_t qos, void *userdata)
	发送一条mqtt SUBSCRIBE报文到MQTT服务器, 用于订阅指定的topic 更多...
int32_t	aiot_mqtt_unsub (void *handle, char *topic)
	发送一条mqtt UNSUBSCRIBE报文到MQTT服务器, 用于取消订阅指定的topic 更多...
int32_t	aiot_mqtt_recv (void *handle)
	尝试从网络上接收MQTT报文 更多...
int32_t	aiot_mqtt_connect_with_prop (void *handle, conn_property_t *conn_prop)
	与MQTT服务器建立连接. 以MQTT 5.0协议的方式接入, 支持5.0的特性. 在调用这个接口前, 需要确保已经通过AIOT_MQTTOPT_VERSION的方式, 设置过版本号为AIOT_MQTT_VERSION_5_0 更多...
int32_t	aiot_mqtt_pub_with_prop (void *handle, char *topic, uint8_t *payload, uint32_t payload_len, uint8_t qos, pub_property_t *pub_prop)
	发送一条PUBLISH报文到MQTT服务器, QoS为0, 用于发布指定的消息 以MQTT 5.0协议的方式接入, 支持5.0的特性. 在调用这个接口前, 需要确保已经通过AIOT_MQTTOPT_VERSION的方式, 设置过版本号为AIOT_MQTT_VERSION_5_0 更多...
int32_t	aiot_mqtt_disconnect_with_prop (void *handle, uint8_t reason_code, disconn_property_t *disconn_property)
	与MQTT服务器断开连接 以MQTT 5.0协议的方式接入, 支持5.0的特性. 在调用这个接口前, 需要确保已经通过AIOT_MQTTOPT_VERSION的方式, 设置过版本号为AIOT_MQTT_VERSION_5_0 更多...
int32_t	aiot_mqtt_sub_with_prop (void *handle, char *topic, aiot_mqtt_recv_handler_t handler, uint8_t qos, void *userdata, sub_property_t *sub_prop)
	发送一条mqtt SUBSCRIBE报文到MQTT服务器, 用于订阅指定的topic 以MQTT 5.0协议的方式接入, 支持5.0的特性. 在调用这个接口前, 需要确保已经通过AIOT_MQTTOPT_VERSION的方式, 设置过版本号为AIOT_MQTT_VERSION_5_0 更多...
int32_t	aiot_mqtt_unsub_with_prop (void *handle, char *topic, unsub_property_t *unsub_prop)
	发送一条mqtt UNSUBSCRIBE报文到MQTT服务器, 用于取消订阅指定的topic 以MQTT 5.0协议的方式接入, 支持5.0的特性. 在调用这个接口前, 需要确保已经通过AIOT_MQTTOPT_VERSION的方式, 设置过版本号为AIOT_MQTT_VERSION_5_0 更多...

详细描述

MQTT模块头文件, 提供用MQTT协议连接阿里云物联网平台的能力

日期

2019-12-27

版权所有

Copyright (C) 2015-2018 Alibaba Group Holding Limited

MQTT模块用于建立与阿里云物联网平台的连接, API使用流程如下:

1. 调用 aiot_mqtt_init 初始化MQTT会话, 获取会话句柄
2. 调用 aiot_mqtt_setopt 配置MQTT会话的参数, 常用配置项见 aiot_mqtt_setopt 的说明
3. 调用 aiot_mqtt_connect 建立与阿里云物联网平台的连接
4. 启动一个线程, 线程中间歇性调用 aiot_mqtt_process 处理心跳和QoS1的消息
5. 启动一个线程, 线程中持续调用 aiot_mqtt_recv 接收网络上的MQTT报文
   • 当接收到一条报文时, 按以下顺序检查当前MQTT会话的参数, 当满足某条的描述时, 会通过对应的回调函数进行通知, 并停止检查
     • 检查收到的报文topic是否已经通过 aiot_mqtt_setopt 的 AIOT_MQTTOPT_APPEND_TOPIC_MAP 参数配置回调函数
     • 检查收到的报文topic是否已经通过 aiot_mqtt_sub API配置回调函数
     • 检查是否通过 aiot_mqtt_setopt 的 AIOT_MQTTOPT_RECV_HANDLER 参数配置默认回调函数
6. 经过以上步骤后, MQTT连接已建立并能保持与物联网平台的连接, 接下来按自己的场景用 aiot_mqtt_sub 和 aiot_mqtt_pub 等API实现业务逻辑即可

宏定义说明

#define USER_PROPERTY_MAX   (20)

类型定义说明

typedef void(* aiot_mqtt_recv_handler_t) (void *handle, const aiot_mqtt_recv_t *packet, void *userdata)

MQTT报文接收回调函数原型

参数

[in]	handle	MQTT实例句柄
[in]	packet	MQTT报文结构体, 存放收到的MQTT报文
[in]	userdata	用户上下文

返回

void

typedef void(* aiot_mqtt_event_handler_t) (void *handle, const aiot_mqtt_event_t *event, void *userdata)

MQTT事件回调函数

当MQTT内部事件被触发时, 调用此函数. 如连接成功/断开连接/重连成功

枚举类型说明

enum aiot_mqtt_recv_type_t

MQTT报文类型

传入aiot_mqtt_recv_handler_t 的MQTT报文类型

枚举值
AIOT_MQTTRECV_PUB	MQTT PUBLISH报文
AIOT_MQTTRECV_HEARTBEAT_RESPONSE	MQTT PINGRESP报文
AIOT_MQTTRECV_SUB_ACK	MQTT SUBACK报文
AIOT_MQTTRECV_UNSUB_ACK	MQTT UNSUB报文
AIOT_MQTTRECV_PUB_ACK	MQTT PUBACK报文
AIOT_MQTTRECV_CON_ACK	MQTT CONACK报文
AIOT_MQTTRECV_DISCONNECT	MQTT SERVER DISCONNECT报文

enum aiot_mqtt_protocol_version

MQTT协议版本

传入aiot_mqtt_setopt 的MQTT协议版本号

枚举值
AIOT_MQTT_VERSION_3_1
AIOT_MQTT_VERSION_5_0

enum aiot_mqtt_event_type_t

MQTT内部事件类型

枚举值
AIOT_MQTTEVT_CONNECT	当MQTT实例第一次连接网络成功时, 触发此事件
AIOT_MQTTEVT_RECONNECT	当MQTT实例断开网络连接后重连成功时, 触发此事件
AIOT_MQTTEVT_DISCONNECT	当MQTT实例断开网络连接时, 触发此事件

enum aiot_mqtt_disconnect_event_type_t

枚举值
AIOT_MQTTDISCONNEVT_NETWORK_DISCONNECT	MQTT实例网络连接由于网络故障而断开
AIOT_MQTTDISCONNEVT_HEARTBEAT_DISCONNECT	MQTT实例网络连接由于心跳丢失超过指定次数(AIOT_MQTTOPT_HEARTBEAT_MAX_LOST )而断开

enum aiot_mqtt_option_t

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

1. data的数据类型是char *时, 以配置AIOT_MQTTOPT_HOST 为例:

   char *host = "xxx";

   aiot_mqtt_setopt(mqtt_handle, AIOT_MQTTOPT_HOST, host);

2. data的数据类型是其他数据类型时, 以配置AIOT_MQTTOPT_PORT 为例:

   uint16_t port = 443;

   aiot_mqtt_setopt(mqtt_handle, AIOT_MQTTOPT_PORT, (void *)&port);

枚举值
AIOT_MQTTOPT_HOST	MQTT 服务器的域名地址或者ip地址 阿里云物联网平台域名地址列表(必须使用自己的product key替换${pk}): 使用tcp或tls证书方式建联: 域名地址 区域 端口号 ${pk}.iot-as-mqtt.cn-shanghai.aliyuncs.com 上海 443 ${pk}.iot-as-mqtt.ap-southeast-1.aliyuncs.com 新加坡 443 ${pk}.iot-as-mqtt.ap-northeast-1.aliyuncs.com 日本 443 ${pk}.iot-as-mqtt.us-west-1.aliyuncs.com 美西 443 ${pk}.iot-as-mqtt.eu-central-1.aliyuncs.com 德国 443 使用tls psk方式建联: 域名地址 区域 端口号 ${pk}.itls.cn-shanghai.aliyuncs.com 上海 1883 使用tls x509客户端证书方式建联: 域名地址 区域 端口号 x509.itls.cn-shanghai.aliyuncs.com 上海 1883 数据类型: (char *)
AIOT_MQTTOPT_PORT	MQTT 服务器的端口号 连接阿里云物联网平台时: 如果使用的是tcp或者tls证书方式, 端口号设置为443 如果使用的是tls psk和tls x509客户端证书方式, 端口号设置为1883 数据类型: (uint16_t *)
AIOT_MQTTOPT_PRODUCT_KEY	设备的product key, 可从阿里云物联网平台控制台获取 数据类型: (char *)
AIOT_MQTTOPT_DEVICE_NAME	设备的device name, 可从阿里云物联网平台控制台获取 数据类型: (char *)
AIOT_MQTTOPT_DEVICE_SECRET	设备的device secret, 可从阿里云物联网平台控制台获取 数据类型: (char *)
AIOT_MQTTOPT_EXTEND_CLIENTID	设备连接阿里云物联网平台时的扩展clientid 若需要上报模组商id和模组id以及os信息, 按以下格式填写: "mid=<模组ID>,pid=<模组商ID>,os=<操作系统>" 数据类型: (char *)
AIOT_MQTTOPT_SECURITY_MODE	设备连接阿里云物联网平台时的安全模式, 使用标准的tcp或tls时无需配置 数据类型: (char *)
AIOT_MQTTOPT_USERNAME	使用自定义连接凭据连接mqtt服务器时, 凭据的username 数据类型: (char *)
AIOT_MQTTOPT_PASSWORD	使用自定义连接凭据连接mqtt服务器时, 凭据的password 数据类型: (char *)
AIOT_MQTTOPT_CLIENTID	使用自定义连接凭据连接mqtt服务器时, 凭据的clientid 数据类型: (char *)
AIOT_MQTTOPT_KEEPALIVE_SEC	MQTT建联时, CONNECT报文中的心跳间隔参数 受阿里云物联网平台限制, 取值范围为30 ~ 1200s 如果设置的值小于30, mqtt建联会被云端拒绝, aiot_mqtt_connect 函数会返回STATE_MQTT_CONNACK_RCODE_SERVER_UNAVAILABLE 错误 如果设置的值大于1200, mqtt连接仍然可以建立, 但此参数会被服务器覆盖为1200 数据类型: (uint16_t *) 取值范围: 30 ~ 1200s 默认值: 1200s
AIOT_MQTTOPT_CLEAN_SESSION	MQTT建联时, CONNECT报文中的clean session参数 设备上线时如果clean session为0, 那么上线前服务器推送QoS1的消息会在此时推送给设备 设备上线时如果clean session为1, 那么上线前服务器推送的QoS1的消息会被丢弃 数据类型: (uint8_t *) 取值范围: 0, 1 默认值: 1
AIOT_MQTTOPT_NETWORK_CRED	MQTT建联时, 网络使用的安全凭据 该配置项用于为底层网络配置aiot_sysdep_network_cred_t 安全凭据数据 若该选项不配置, 那么MQTT将以tcp方式直接建联 若aiot_sysdep_network_cred_t 中option配置为AIOT_SYSDEP_NETWORK_CRED_NONE , MQTT将以tcp方式直接建联 若aiot_sysdep_network_cred_t 中option配置为AIOT_SYSDEP_NETWORK_CRED_SVRCERT_CA , MQTT将以tls方式建联 若aiot_sysdep_network_cred_t 中option配置为AIOT_SYSDEP_NETWORK_CRED_SVRCERT_PSK , MQTT将以tls psk方式建联 数据类型: (aiot_sysdep_network_cred_t *)
AIOT_MQTTOPT_CONNECT_TIMEOUT_MS	MQTT建联时, 建立网络连接的超时时间 指建立socket连接的超时时间 数据类型: (uint32_t *) 默认值: (5 *1000) ms
AIOT_MQTTOPT_HEARTBEAT_INTERVAL_MS	配置MQTT PINGREQ报文发送时间间隔. (心跳发送间隔) 数据类型: (uint32_t *) 默认值: (25 * 1000) ms
AIOT_MQTTOPT_HEARTBEAT_MAX_LOST	配置MQTT PINGRESP报文允许连续丢失的最大次数, 当超过这个次数时, 触发重连机制 数据类型: (uint8_t *) 默认值: (2)
AIOT_MQTTOPT_RECONN_ENABLED	打开/关闭MQTT重连机制 数据类型: (uint8_t *) 取值范围: 0, 1 默认值: 1
AIOT_MQTTOPT_RECONN_INTERVAL_MS	当由于心跳丢失或者网络断开触发重连机制时, 尝试重连的时间间隔 数据类型: (uint32_t *) 默认值: (2 * 1000) ms
AIOT_MQTTOPT_SEND_TIMEOUT_MS	MQTT发送数据时, 在协议栈花费的最长时间 数据类型: (uint32_t *) 默认值: (5 * 1000) ms
AIOT_MQTTOPT_RECV_TIMEOUT_MS	MQTT接收数据时, 在协议栈花费的最长时间 数据类型: (uint32_t *) 默认值: (5 * 1000) ms
AIOT_MQTTOPT_REPUB_TIMEOUT_MS	QoS1消息重发间隔 当发送qos1 MQTT PUBLISH报文后, 如果在AIOT_MQTTOPT_REPUB_TIMEOUT_MS 时间内未收到mqtt PUBACK报文, aiot_mqtt_process 会重新发送此qo1 MQTT PUBLISH报文, 直到收到PUBACK报文为止 数据类型: (uint32_t *) 默认值: (3 * 1000) ms
AIOT_MQTTOPT_DEINIT_TIMEOUT_MS	销毁MQTT实例时, 等待其他api执行完毕的时间 当调用aiot_mqtt_deinit 销毁MQTT实例时, 若继续调用其他aiot_mqtt_xxx API, API会返回STATE_USER_INPUT_EXEC_DISABLED 错误 此时, 用户应该停止调用其他aiot_mqtt_xxx API 数据类型: (uint32_t *) 默认值: (2 * 1000) ms
AIOT_MQTTOPT_RECV_HANDLER	从MQTT服务器收取的数据从此默认回调函数进行通知 若没有配置该回调函数, 当有消息到达但找不到对应的已注册topic时, 消息会被丢弃 若已配置该回调函数, 当有消息到达但找不到对应的已注册topic时, 消息从此默认回调函数进行通知 数据类型: ( aiot_mqtt_recv_handler_t )
AIOT_MQTTOPT_EVENT_HANDLER	MQTT客户端内部发生的事件会从此回调函数进行通知, 如上线/断线/重新上线 数据类型: ( aiot_mqtt_event_handler_t )
AIOT_MQTTOPT_APPEND_TOPIC_MAP	可在MQTT建立连接之前配置MQTT topic与其对应的回调函数 数据类型: ( aiot_mqtt_topic_map_t )
AIOT_MQTTOPT_REMOVE_TOPIC_MAP	取消之前建立的MQTT topic与其回调函数的对应关系 数据类型: ( aiot_mqtt_topic_map_t )
AIOT_MQTTOPT_APPEND_REQUESTID	在publish消息的topic上附加请求ID字符串, 用于全链路日志追踪 数据类型: (uint8_t *) 默认值: 0 配置为0则不附加请求ID字符串, 配置为1将附加请求ID字符串
AIOT_MQTTOPT_USERDATA	用户需要SDK暂存的上下文 该上下文会在AIOT_MQTTOPT_RECV_HANDLER 和AIOT_MQTTOPT_EVENT_HANDLER 中传回给用户 当使用AIOT_MQTTOPT_APPEND_TOPIC_MAP 或者aiot_mqtt_sub 时未指定userdata, 该上下文也会传给这些回调函数 数据类型: (void *)
AIOT_MQTTOPT_VERSION	设置MQTT 协议的版本号 默认协议版本号是3.1.1 用户可以使用该选项将版本号设置为AIOT_MQTT_VERSION_5_0 数据类型: (void *)
AIOT_MQTTOPT_ASSIGNED_CLIENTID	MQTT 5.0特性. 设置是否要使能assigned clentid功能 默认不使能 用户可以设置值1将该功能使能 数据类型: (void *)
AIOT_MQTTOPT_FLOW_CONTROL_ENABLED	MQTT 5.0特性. 设置是否要使能设备端流控功能 默认不使能 用户可以设置值1将该功能使能 数据类型: (void *)
AIOT_MQTTOPT_MAX

函数说明

void* aiot_mqtt_init

(

void

)

初始化mqtt实例并设置默认参数

返回

void*

返回值

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

函数调用图:

int32_t aiot_mqtt_setopt	(	void *	handle,
		aiot_mqtt_option_t	option,
		void *	data
	)

设置mqtt参数

下面列出常用的配置选项, 至少需要配置以下选项才可使用MQTT的基本功能

其余配置选项均设有默认值, 可按业务需要进行调整

• AIOT_MQTTOPT_HOST: 配置连接的阿里云MQTT站点地址
• AIOT_MQTTOPT_PORT: 配置连接的阿里云MQTT站点端口号
• AIOT_MQTTOPT_PRODUCT_KEY: 配置设备的 productKey
• AIOT_MQTTOPT_DEVICE_NAME: 配置设备的 deviceName
• AIOT_MQTTOPT_DEVICE_SECRET: 配置设备的 deviceSecret
• AIOT_MQTTOPT_NETWORK_CRED: 配置建立MQTT连接时的安全凭据
• AIOT_MQTTOPT_RECV_HANDLER: 配置默认的数据接收回调函数
• AIOT_MQTTOPT_EVENT_HANDLER: 配置MQTT事件通知回调函数

参数

[in]	handle	mqtt句柄
[in]	option	配置选项, 更多信息请参考aiot_mqtt_option_t
[in]	data	配置选项数据, 更多信息请参考aiot_mqtt_option_t

返回

int32_t

返回值

<STATE_SUCCESS	参数设置失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS	参数设置成功

函数调用图:

int32_t aiot_mqtt_deinit

(

void **

handle

)

释放mqtt实例句柄的资源

参数

[in]

handle

指向mqtt实例句柄的指针

返回

int32_t

返回值

<STATE_SUCCESS	执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS	执行成功

函数调用图:

int32_t aiot_mqtt_connect

(

void *

handle

)

与MQTT服务器建立连接

使用aiot_mqtt_setopt 配置的mqtt连接参数连接mqtt服务器, 使用的建联参数按如下顺序选择

1. 若配置了以下选项, 直接用配置的连接参数连接 AIOT_MQTTOPT_HOST 选项指定的任意MQTT服务器
   • AIOT_MQTTOPT_USERNAME
   • AIOT_MQTTOPT_PASSWORD
   • AIOT_MQTTOPT_CLIENTID
2. 若配置了以下选项, 则强制以阿里云平台的签名算法计算连接参数作为MQTT的用户名/密码, 连接阿里云平台
   • AIOT_MQTTOPT_PRODUCT_KEY
   • AIOT_MQTTOPT_DEVICE_NAME
   • AIOT_MQTTOPT_DEVICE_SECRET

参数

[in]

handle

MQTT实例句柄

返回

int32_t

返回值

<STATE_SUCCESS	执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS	执行成功

注解

当配置AIOT_MQTTOPT_USERNAME , AIOT_MQTTOPT_PASSWORD 和AIOT_MQTTOPT_CLIENTID 配置自定义连接凭据时,

此函数会忽略AIOT_MQTTOPT_PRODUCT_KEY , AIOT_MQTTOPT_DEVICE_NAME 和AIOT_MQTTOPT_DEVICE_SECRET,

直接使用自定义凭据连接指定的MQTT服务器

函数调用图:

int32_t aiot_mqtt_disconnect

(

void *

handle

)

与MQTT服务器断开连接

向MQTT服务器发送MQTT DISCONNECT报文, 然后断开网络连接

如果需要再次与MQTT服务器建立连接, 调用aiot_mqtt_connect 即可

参数

[in]

handle

MQTT实例句柄

返回

int32_t

返回值

<STATE_SUCCESS	执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS	执行成功

函数调用图:

int32_t aiot_mqtt_heartbeat

(

void *

handle

)

发送MQTT PINGREQ报文, 用于维持心跳

aiot_mqtt_process 包含了定时发送心跳的机制, 如果有特殊需要的话, 可以使用此函数直接发送心跳报文

参数

[in]

handle

MQTT实例句柄

返回

int32_t

返回值

<STATE_SUCCESS	执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS	执行成功

函数调用图:

int32_t aiot_mqtt_process

(

void *

handle

)

此函数用于处理定时心跳发送和qos1消息的重传逻辑

1. 发送心跳至mqtt broker以维护mqtt连接, 心跳发送间隔由AIOT_MQTTOPT_HEARTBEAT_INTERVAL_MS 配置项控制
2. 如果一条qos1的mqtt PUBLISH报文在AIOT_MQTTOPT_REPUB_TIMEOUT_MS 时间内没有收到mqtt PUBACK应答报文, 该函数会重发此消息, 直到成功为止

参数

[in]

handle

MQTT实例句柄

返回

int32_t

返回值

<STATE_SUCCESS	执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS	执行成功

注解

该函数为非阻塞, 需要间歇性被调用, 调用间隔应当小于AIOT_MQTTOPT_HEARTBEAT_INTERVAL_MS 和AIOT_MQTTOPT_REPUB_TIMEOUT_MS 时间内没有收到mqtt的最小值,

以确保心跳发送和QoS1消息的重传逻辑正常工作

函数调用图:

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

发送一条PUBLISH报文到MQTT服务器, QoS为0, 用于发布指定的消息

参数

[in]	handle	MQTT实例句柄
[in]	topic	指定MQTT PUBLISH报文的topic
[in]	payload	指定MQTT PUBLISH报文的payload
[in]	payload_len	指定MQTT PUBLISH报文的payload_len
[in]	qos	指定mqtt的qos值, 仅支持qos0和qos1

返回

int32_t

返回值

<STATE_SUCCESS	执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS	执行成功

函数调用图:

int32_t aiot_mqtt_sub	(	void *	handle,
		char *	topic,
		aiot_mqtt_recv_handler_t	handler,
		uint8_t	qos,
		void *	userdata
	)

发送一条mqtt SUBSCRIBE报文到MQTT服务器, 用于订阅指定的topic

参数

[in]	handle	MQTT实例句柄
[in]	topic	指定MQTT SUBSCRIBE报文的topic
[in]	handler	与topic对应的MQTT PUBLISH报文回调函数, 当有消息发布到topic时, 该回调函数被调用 若handler为NULL传入, 则SDK调用AIOT_MQTTOPT_RECV_HANDLER 配置的回调函数 若多次调用aiot_mqtt_sub()并对同一topic指定不同的handler, 有消息到达时不同handler都会被调用到
[in]	qos	指定topic期望mqtt服务器支持的最大qos值, 仅支持qos0和qos1
[in]	userdata	可让SDK代为保存的用户上下文, 当回调函数被调用时, 此上下文会通过handler传回给用户 若未指定该上下文, 那么通过AIOT_MQTTOPT_USERDATA 配置的上下文会通过handler传回给用户

返回

int32_t

返回值

<STATE_SUCCESS	执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS	执行成功

函数调用图:

int32_t aiot_mqtt_unsub	(	void *	handle,
		char *	topic
	)

发送一条mqtt UNSUBSCRIBE报文到MQTT服务器, 用于取消订阅指定的topic

参数

[in]	handle	MQTT实例句柄
[in]	topic	指定MQTT UNSUBSCRIBE报文的topic

返回

int32_t

返回值

<STATE_SUCCESS	执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS	执行成功

函数调用图:

int32_t aiot_mqtt_recv

(

void *

handle

)

尝试从网络上接收MQTT报文

除了从网络上接收MQTT报文之外, 本函数也包含了重连机制

1. 当MQTT心跳丢失超过AIOT_MQTTOPT_HEARTBEAT_MAX_LOST 配置的次数时, 触发重连机制
   • 重连间隔由 AIOT_MQTTOPT_RECONN_INTERVAL_MS 指定
2. 当SDK检测到网络断开时, 触发重连机制
   • 重连间隔由 AIOT_MQTTOPT_RECONN_INTERVAL_MS 指定

参数

[in]

handle

返回值

STATE_SYS_DEPEND_NWK_READ_LESSDATA	执行成功, 此时网络上暂无可以收取的MQTT报文
>=STATE_SUCCESS	执行成功
其他返回值	执行失败, 更多信息请参考aiot_state_api.h

注解

当网络连接正常并且aiot_mqtt_deinit 未被调用时, 该函数为阻塞, 需要持续被调用

1. 当网络连接断开时, 该函数会立即返回, 此时返回值为STATE_SYS_DEPEND_NWK_CLOSED
2. 当aiot_mqtt_deinit 被调用时, 该函数会立即返回, 此时返回值为STATE_USER_INPUT_EXEC_DISABLED

函数调用图:

int32_t aiot_mqtt_connect_with_prop	(	void *	handle,
		conn_property_t *	conn_prop
	)

与MQTT服务器建立连接. 以MQTT 5.0协议的方式接入, 支持5.0的特性. 在调用这个接口前, 需要确保已经通过AIOT_MQTTOPT_VERSION的方式, 设置过版本号为AIOT_MQTT_VERSION_5_0

使用aiot_mqtt_setopt 配置的mqtt连接参数连接mqtt服务器, 使用的建联参数按如下顺序选择

1. 若配置了以下选项, 直接用配置的连接参数连接 AIOT_MQTTOPT_HOST 选项指定的任意MQTT服务器
   • AIOT_MQTTOPT_USERNAME
   • AIOT_MQTTOPT_PASSWORD
   • AIOT_MQTTOPT_CLIENTID
2. 若配置了以下选项, 则强制以阿里云平台的签名算法计算连接参数作为MQTT的用户名/密码, 连接阿里云平台
   • AIOT_MQTTOPT_PRODUCT_KEY
   • AIOT_MQTTOPT_DEVICE_NAME
   • AIOT_MQTTOPT_DEVICE_SECRET

参数

[in]	handle	MQTT实例句柄
[in]	conn_prop	指定MQTT CONNECT报文的属性

返回

int32_t

返回值

STATE_MQTT_INVALID_PROTOCOL_VERSION	mqtt协议的版本号不对, 没有通过AIOT_MQTTOPT_VERSION将版本号将设置为5.0
<STATE_SUCCESS	执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS	执行成功

注解

当配置AIOT_MQTTOPT_USERNAME , AIOT_MQTTOPT_PASSWORD 和AIOT_MQTTOPT_CLIENTID 配置自定义连接凭据时,

此函数会忽略AIOT_MQTTOPT_PRODUCT_KEY , AIOT_MQTTOPT_DEVICE_NAME 和AIOT_MQTTOPT_DEVICE_SECRET,

直接使用自定义凭据连接指定的MQTT服务器

函数调用图:

int32_t aiot_mqtt_pub_with_prop	(	void *	handle,
		char *	topic,
		uint8_t *	payload,
		uint32_t	payload_len,
		uint8_t	qos,
		pub_property_t *	pub_prop
	)

发送一条PUBLISH报文到MQTT服务器, QoS为0, 用于发布指定的消息 以MQTT 5.0协议的方式接入, 支持5.0的特性. 在调用这个接口前, 需要确保已经通过AIOT_MQTTOPT_VERSION的方式, 设置过版本号为AIOT_MQTT_VERSION_5_0

参数

[in]	handle	MQTT实例句柄
[in]	topic	指定MQTT PUBLISH报文的topic
[in]	payload	指定MQTT PUBLISH报文的payload
[in]	payload_len	指定MQTT PUBLISH报文的payload_len
[in]	qos	指定mqtt的qos值, 仅支持qos0和qos1
[in]	pub_prop	指定MQTT PUB报文的属性

返回

int32_t

返回值

STATE_MQTT_INVALID_PROTOCOL_VERSION	mqtt协议的版本号不对, 没有通过AIOT_MQTTOPT_VERSION将版本号将设置为5.0
<STATE_SUCCESS	执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS	执行成功

函数调用图:

int32_t aiot_mqtt_disconnect_with_prop	(	void *	handle,
		uint8_t	reason_code,
		disconn_property_t *	disconn_property
	)

与MQTT服务器断开连接 以MQTT 5.0协议的方式接入, 支持5.0的特性. 在调用这个接口前, 需要确保已经通过AIOT_MQTTOPT_VERSION的方式, 设置过版本号为AIOT_MQTT_VERSION_5_0

向MQTT服务器发送MQTT DISCONNECT报文, 然后断开网络连接

如果需要再次与MQTT服务器建立连接, 调用aiot_mqtt_connect 即可

参数

[in]	handle	MQTT实例句柄
[in]	reason_code	指定MQTT DISCONNECT的原因
[in]	disconn_property	指定MQTT DISCONNECT报文的属性

返回

int32_t

返回值

STATE_MQTT_INVALID_PROTOCOL_VERSION	mqtt协议的版本号不对, 没有通过AIOT_MQTTOPT_VERSION将版本号将设置为5.0
<STATE_SUCCESS	执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS	执行成功

函数调用图:

int32_t aiot_mqtt_sub_with_prop	(	void *	handle,
		char *	topic,
		aiot_mqtt_recv_handler_t	handler,
		uint8_t	qos,
		void *	userdata,
		sub_property_t *	sub_prop
	)

发送一条mqtt SUBSCRIBE报文到MQTT服务器, 用于订阅指定的topic 以MQTT 5.0协议的方式接入, 支持5.0的特性. 在调用这个接口前, 需要确保已经通过AIOT_MQTTOPT_VERSION的方式, 设置过版本号为AIOT_MQTT_VERSION_5_0

参数

[in]	handle	MQTT实例句柄
[in]	topic	指定MQTT SUBSCRIBE报文的topic
[in]	handler	与topic对应的MQTT PUBLISH报文回调函数, 当有消息发布到topic时, 该回调函数被调用 若handler为NULL传入, 则SDK调用AIOT_MQTTOPT_RECV_HANDLER 配置的回调函数 若多次调用aiot_mqtt_sub()并对同一topic指定不同的handler, 有消息到达时不同handler都会被调用到
[in]	qos	指定topic期望mqtt服务器支持的最大qos值, 仅支持qos0和qos1
[in]	userdata	可让SDK代为保存的用户上下文, 当回调函数被调用时, 此上下文会通过handler传回给用户 若未指定该上下文, 那么通过AIOT_MQTTOPT_USERDATA 配置的上下文会通过handler传回给用户
[in]	sub_prop	指定MQTT SUBSCRIBE报文的属性

返回

int32_t

返回值

STATE_MQTT_INVALID_PROTOCOL_VERSION	mqtt协议的版本号不对, 没有通过AIOT_MQTTOPT_VERSION将版本号将设置为5.0
<STATE_SUCCESS	执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS	执行成功

函数调用图:

int32_t aiot_mqtt_unsub_with_prop	(	void *	handle,
		char *	topic,
		unsub_property_t *	unsub_prop
	)

发送一条mqtt UNSUBSCRIBE报文到MQTT服务器, 用于取消订阅指定的topic 以MQTT 5.0协议的方式接入, 支持5.0的特性. 在调用这个接口前, 需要确保已经通过AIOT_MQTTOPT_VERSION的方式, 设置过版本号为AIOT_MQTT_VERSION_5_0

参数

[in]	handle	MQTT实例句柄
[in]	topic	指定MQTT UNSUBSCRIBE报文的topic
[in]	unsub_prop	指定MQTT UNSUBSCRIBE报文的属性

返回

int32_t

返回值

STATE_MQTT_INVALID_PROTOCOL_VERSION	mqtt协议的版本号不对, 没有通过AIOT_MQTTOPT_VERSION将版本号将设置为5.0
<STATE_SUCCESS	执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS	执行成功

函数调用图: