Link Kit C-SDK  4.0.0
| 宏定义 | 类型定义 | 枚举 | 函数
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_ZIPPER,
  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

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报文
  6. 经过以上步骤后, MQTT连接已建立并能保持与物联网平台的连接, 接下来按自己的场景用 aiot_mqtt_subaiot_mqtt_pub 等API实现业务逻辑即可

宏定义说明

◆ USER_PROPERTY_MAX

#define USER_PROPERTY_MAX   (20)

类型定义说明

◆ aiot_mqtt_recv_handler_t

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

MQTT报文接收回调函数原型

参数
[in]handleMQTT实例句柄
[in]packetMQTT报文结构体, 存放收到的MQTT报文
[in]userdata用户上下文
返回
void

◆ aiot_mqtt_event_handler_t

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

MQTT事件回调函数

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

枚举类型说明

◆ 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报文

◆ aiot_mqtt_protocol_version

MQTT协议版本

传入aiot_mqtt_setopt 的MQTT协议版本号

枚举值
AIOT_MQTT_VERSION_3_1 
AIOT_MQTT_VERSION_5_0 

◆ aiot_mqtt_event_type_t

MQTT内部事件类型

枚举值
AIOT_MQTTEVT_CONNECT 

当MQTT实例第一次连接网络成功时, 触发此事件

AIOT_MQTTEVT_RECONNECT 

当MQTT实例断开网络连接后重连成功时, 触发此事件

AIOT_MQTTEVT_DISCONNECT 

当MQTT实例断开网络连接时, 触发此事件

◆ aiot_mqtt_disconnect_event_type_t

枚举值
AIOT_MQTTDISCONNEVT_NETWORK_DISCONNECT 

MQTT实例网络连接由于网络故障而断开

AIOT_MQTTDISCONNEVT_HEARTBEAT_DISCONNECT 

MQTT实例网络连接由于心跳丢失超过指定次数(AIOT_MQTTOPT_HEARTBEAT_MAX_LOST )而断开

◆ 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 服务器的端口号

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

  1. 如果使用的是tcp或者tls证书方式, 端口号设置为443
  2. 如果使用的是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

  1. 如果设置的值小于30, mqtt建联会被云端拒绝, aiot_mqtt_connect 函数会返回STATE_MQTT_CONNACK_RCODE_SERVER_UNAVAILABLE 错误
  2. 如果设置的值大于1200, mqtt连接仍然可以建立, 但此参数会被服务器覆盖为1200

数据类型: (uint16_t *) 取值范围: 30 ~ 1200s 默认值: 1200s

AIOT_MQTTOPT_CLEAN_SESSION 

MQTT建联时, CONNECT报文中的clean session参数

  1. 设备上线时如果clean session为0, 那么上线前服务器推送QoS1的消息会在此时推送给设备
  2. 设备上线时如果clean session为1, 那么上线前服务器推送的QoS1的消息会被丢弃

数据类型: (uint8_t *) 取值范围: 0, 1 默认值: 1

AIOT_MQTTOPT_NETWORK_CRED 

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

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

  1. 若该选项不配置, 那么MQTT将以tcp方式直接建联
  2. aiot_sysdep_network_cred_t 中option配置为AIOT_SYSDEP_NETWORK_CRED_NONE , MQTT将以tcp方式直接建联
  3. aiot_sysdep_network_cred_t 中option配置为AIOT_SYSDEP_NETWORK_CRED_SVRCERT_CA , MQTT将以tls方式建联
  4. 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服务器收取的数据从此默认回调函数进行通知

  1. 若没有配置该回调函数, 当有消息到达但找不到对应的已注册topic时, 消息会被丢弃
  2. 若已配置该回调函数, 当有消息到达但找不到对应的已注册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暂存的上下文

  1. 该上下文会在AIOT_MQTTOPT_RECV_HANDLERAIOT_MQTTOPT_EVENT_HANDLER 中传回给用户
  2. 当使用AIOT_MQTTOPT_APPEND_TOPIC_MAP 或者aiot_mqtt_sub 时未指定userdata, 该上下文也会传给这些回调函数

数据类型: (void *)

AIOT_MQTTOPT_VERSION 

设置MQTT 协议的版本号

  1. 默认协议版本号是3.1.1
  2. 用户可以使用该选项将版本号设置为AIOT_MQTT_VERSION_5_0

数据类型: (void *)

AIOT_MQTTOPT_ASSIGNED_CLIENTID 

MQTT 5.0特性. 设置是否要使能assigned clentid功能

  1. 默认不使能
  2. 用户可以设置值1将该功能使能

数据类型: (void *)

AIOT_MQTTOPT_FLOW_CONTROL_ENABLED 

MQTT 5.0特性. 设置是否要使能设备端流控功能

  1. 默认不使能
  2. 用户可以设置值1将该功能使能

数据类型: (void *)

AIOT_MQTTOPT_ZIPPER 

MQTT 压缩特性.

AIOT_MQTTOPT_MAX 

函数说明

◆ aiot_mqtt_init()

void* aiot_mqtt_init ( void  )

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

返回
void*
返回值
非NULLMQTT实例句柄
NULL初始化失败, 一般是内存分配失败导致
函数调用图:

◆ aiot_mqtt_setopt()

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]handlemqtt句柄
[in]option配置选项, 更多信息请参考aiot_mqtt_option_t
[in]data配置选项数据, 更多信息请参考aiot_mqtt_option_t
返回
int32_t
返回值
<STATE_SUCCESS参数设置失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS参数设置成功
函数调用图:

◆ aiot_mqtt_deinit()

int32_t aiot_mqtt_deinit ( void **  handle)

释放mqtt实例句柄的资源

参数
[in]handle指向mqtt实例句柄的指针
返回
int32_t
返回值
<STATE_SUCCESS执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS执行成功
函数调用图:

◆ aiot_mqtt_connect()

int32_t aiot_mqtt_connect ( void *  handle)

与MQTT服务器建立连接

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

  1. 若配置了以下选项, 直接用配置的连接参数连接 AIOT_MQTTOPT_HOST 选项指定的任意MQTT服务器
  2. 若配置了以下选项, 则强制以阿里云平台的签名算法计算连接参数作为MQTT的用户名/密码, 连接阿里云平台
参数
[in]handleMQTT实例句柄
返回
int32_t
返回值
<STATE_SUCCESS执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS执行成功
注解

当配置AIOT_MQTTOPT_USERNAME , AIOT_MQTTOPT_PASSWORDAIOT_MQTTOPT_CLIENTID 配置自定义连接凭据时,

此函数会忽略AIOT_MQTTOPT_PRODUCT_KEY , AIOT_MQTTOPT_DEVICE_NAMEAIOT_MQTTOPT_DEVICE_SECRET,

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

函数调用图:

◆ aiot_mqtt_disconnect()

int32_t aiot_mqtt_disconnect ( void *  handle)

与MQTT服务器断开连接

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

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

参数
[in]handleMQTT实例句柄
返回
int32_t
返回值
<STATE_SUCCESS执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS执行成功
函数调用图:

◆ aiot_mqtt_heartbeat()

int32_t aiot_mqtt_heartbeat ( void *  handle)

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

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

参数
[in]handleMQTT实例句柄
返回
int32_t
返回值
<STATE_SUCCESS执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS执行成功
函数调用图:

◆ aiot_mqtt_process()

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]handleMQTT实例句柄
返回
int32_t
返回值
<STATE_SUCCESS执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS执行成功
注解

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

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

函数调用图:

◆ aiot_mqtt_pub()

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

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

参数
[in]handleMQTT实例句柄
[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执行成功
函数调用图:

◆ aiot_mqtt_sub()

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]handleMQTT实例句柄
[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执行成功
函数调用图:

◆ aiot_mqtt_unsub()

int32_t aiot_mqtt_unsub ( void *  handle,
char *  topic 
)

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

参数
[in]handleMQTT实例句柄
[in]topic指定MQTT UNSUBSCRIBE报文的topic
返回
int32_t
返回值
<STATE_SUCCESS执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS执行成功
函数调用图:

◆ aiot_mqtt_recv()

int32_t aiot_mqtt_recv ( void *  handle)

尝试从网络上接收MQTT报文

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

  1. 当MQTT心跳丢失超过AIOT_MQTTOPT_HEARTBEAT_MAX_LOST 配置的次数时, 触发重连机制
  2. 当SDK检测到网络断开时, 触发重连机制
参数
[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
函数调用图:

◆ aiot_mqtt_connect_with_prop()

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服务器
  2. 若配置了以下选项, 则强制以阿里云平台的签名算法计算连接参数作为MQTT的用户名/密码, 连接阿里云平台
参数
[in]handleMQTT实例句柄
[in]conn_prop指定MQTT CONNECT报文的属性
返回
int32_t
返回值
STATE_MQTT_INVALID_PROTOCOL_VERSIONmqtt协议的版本号不对, 没有通过AIOT_MQTTOPT_VERSION将版本号将设置为5.0
<STATE_SUCCESS执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS执行成功
注解

当配置AIOT_MQTTOPT_USERNAME , AIOT_MQTTOPT_PASSWORDAIOT_MQTTOPT_CLIENTID 配置自定义连接凭据时,

此函数会忽略AIOT_MQTTOPT_PRODUCT_KEY , AIOT_MQTTOPT_DEVICE_NAMEAIOT_MQTTOPT_DEVICE_SECRET,

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

函数调用图:

◆ aiot_mqtt_pub_with_prop()

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]handleMQTT实例句柄
[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_VERSIONmqtt协议的版本号不对, 没有通过AIOT_MQTTOPT_VERSION将版本号将设置为5.0
<STATE_SUCCESS执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS执行成功
函数调用图:

◆ aiot_mqtt_disconnect_with_prop()

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]handleMQTT实例句柄
[in]reason_code指定MQTT DISCONNECT的原因
[in]disconn_property指定MQTT DISCONNECT报文的属性
返回
int32_t
返回值
STATE_MQTT_INVALID_PROTOCOL_VERSIONmqtt协议的版本号不对, 没有通过AIOT_MQTTOPT_VERSION将版本号将设置为5.0
<STATE_SUCCESS执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS执行成功
函数调用图:

◆ aiot_mqtt_sub_with_prop()

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]handleMQTT实例句柄
[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_VERSIONmqtt协议的版本号不对, 没有通过AIOT_MQTTOPT_VERSION将版本号将设置为5.0
<STATE_SUCCESS执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS执行成功
函数调用图:

◆ aiot_mqtt_unsub_with_prop()

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]handleMQTT实例句柄
[in]topic指定MQTT UNSUBSCRIBE报文的topic
[in]unsub_prop指定MQTT UNSUBSCRIBE报文的属性
返回
int32_t
返回值
STATE_MQTT_INVALID_PROTOCOL_VERSIONmqtt协议的版本号不对, 没有通过AIOT_MQTTOPT_VERSION将版本号将设置为5.0
<STATE_SUCCESS执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS执行成功
函数调用图: