paho MQTT C API接口描述

韦衡

2023-12-01

通信模式分类:

包含同步客户端/异步客户端两种

同步/异步通信接口命名规范:

同步客户端API命名:
MQTTClient*****

异步客户端API命名:
MQTTAsync*****

常用同步API解释:

MQTTClient_create()

该函数创建了一个用于连接到特定服务器，使用特定持久存储的MQTT客户端。

int MQTTClient_create(MQTTClient* handle, const char* serverURI, const char* clientId,
		int persistence_type, void* persistence_context)

参数:
handle：指向MQTT客户端句柄的指针。句柄被成功从函数中返回的客户端引用所填充
serverURI：以空结尾的字符串，其指定客户端将连接到的服务器。其格式为protocol://host:port。现在的（protocol）协议必须是tcp或ssl，而host可以指定为IP地址或域名。例如, 要使用默认 MQTT 端口连接到本地计算机上运行的服务器, 请指定为 tcp://localhost:1883。localhost:主机名,可通过命令行,hostname 获取.
clientId：客户端标识符（clientId）是一个以空结尾的 UTF-8 编码字符串，客户端连接到服务器时将它传递过去。
persistence_type：客户端所使用的持久类型。
MQTTCLIENT_PERSISTENCE_NONE-使用内存持久化。如果客户端运行的设备或系统出故障或关闭, 则任何正在运行的消息的当前状态都将丢失, 甚至在 QoS1 和 QoS2 中也可能无法传递某些消息;
MQTTCLIENT_PERSISTENCE_DEFAULT-使用默认的持久化机制（文件系统）。正在运行消息的状态被保存在持久存储中，以便在意外出现时对消息的丢失提供一些保护;
MQTTCLIENT_PERSISTENCE_USER-使用程序指定的持久化实现。使用这种类型，应用程序可对持久化机制进行控制，应用程序必须实现MQTTClient_persistence 接口。
persistence_context：如果应用程序使用的是MQTTCLIENT_PERSISTENCE_NONE持久化，该参数不使用，而且值应该设置为NULL。
对于MQTTCLIENT_PERSISTENCE_DEFAULT持久化，应该设置持久化目录的位置（如果设置为NULL，则使用工作目录作为持久化目录）。
使用MQTTCLIENT_PERSISTENCE_USER持久化，则将此参数指向有效的MQTTClient_persistence结构。

MQTTClient_setCallbacks()

该函数为特定的客户端创建回调函数。如果您的客户端应用程序不使用特定的回调函数，请将相关参数设置为NULL。调用MQTTClient_setCallbacks（）使客户端进入多线程模式。任何必要的消息确认和状态通信都在后台处理，而不需要客户端应用程序的任何干预。
注意：在调用该函数时，MQTT客户端必须断开连接。（即先要调用该函数再连接客户端）。

int MQTTClient_setCallbacks(MQTTClient handle, void* context, MQTTClient_connectionLost* cl,
									MQTTClient_messageArrived* ma, MQTTClient_deliveryComplete* dc);

参数：
handle ：指向MQTT客户端句柄的指针。句柄被成功从函数中返回的客户端引用所填充
context：指向任何应用程序特定上下文的指针。上下文指针被传递给每个回调函数，以提供对回调中的上下文信息的访问。
cl：指向MQTTClient_connectionLost()回调函数的指针。如果您的应用程序不处理断开连接，您可以将其设置为NULL。
ma：指向MQTTClient_messageArrived()回调函数的指针。当您调用MQTTClient_setCallbacks()时，必须指定此回调函数。
dc：指向MQTTClient_deliveryComplete()回调函数的指针。如果您的应用程序同步发布，或者您不想检查是否成功发送，则可以将其设置为NULL。

MQTTClient_connect()

此函数尝试使用指定的选项将先前创建的客户端连接到MQTT服务器。

int MQTTClient_connect(MQTTClient handle, MQTTClient_connectOptions* options);

参数：
handle：指向MQTT客户端句柄的指针。句柄被成功从函数中返回的客户端引用所填充
options：指向有效的MQTTClient_connectOptions结构的指针。

MQTTClient_subscribe()

此功能尝试将客户订阅到单个主题，该主题可能包含通配符。此函数还指定服务质量。

int MQTTClient_subscribe(MQTTClient handle, const char* topic, int qos);

参数
handle 指向MQTT客户端句柄的指针。句柄被成功从函数中返回的客户端引用所填充
topic 订阅的主题，可使用通配符。
qos 订阅的请求服务质量

MQTTClient_publishMessage()

此函数尝试发布一个消息到指定的主题，该主题可能包含通配符。

int MQTTClient_publishMessage(MQTTClient handle, const char* topicName, MQTTClient_message* message,
															 MQTTClient_deliveryToken* deliveryToken)

handle 指向MQTT客户端句柄的指针。句柄被成功从函数中返回的客户端引用所填充
topicName 与信息相关的主题。
message 指向有效的 MQTTClient_message 结构的指针, 其中包含要发布消息的有效负载和属性
deliveryToken 指向MQTTClient_deliveryToken的指针。当函数成功返回时，dt会被赋值为代表消息的token。如果程序中没有使用传递token，将其设置为NULL。

MQTTClient_waitForCompletion()

客户端应用程序调用此函数来将主线程的执行与消息的完成发布同步。被调用时，MQTTClient_waitForCompletion()阻塞执行，直到消息成功传递或已超过指定的时间。

int MQTTClient_waitForCompletion(MQTTClient handle, MQTTClient_deliveryToken dt, unsigned long timeout);

handle 指向MQTT客户端句柄的指针。句柄被成功从函数中返回的客户端引用所填充
dt 代表消息的MQTTClient_deliveryToken用来检测是否成功传递。传递token由发布函数MQTTClient_publish () 和 MQTTClient_publishMessage ()所产生。
timeout 等待的最大毫秒数。

常用异步API解释:

MQTTAsync_create()

异步方式创建MQTT客户端,参数与同步API相似,这里略过

int MQTTAsync_create(MQTTAsync* handle, const char* serverURI, const char* clientId,
		int persistence_type, void* persistence_context);

MQTTAsync_setCallbacks()

设置相关回调函数,准备连接MQTT代理

int MQTTAsync_setCallbacks(MQTTAsync handle, void* context, MQTTAsync_connectionLost* cl,
									MQTTAsync_messageArrived* ma, MQTTAsync_deliveryComplete* dc);

MQTTAsync_connect()

连接到消息代理.

int MQTTAsync_connect(MQTTAsync handle, const MQTTAsync_connectOptions* options);

MQTTAsync_subscribe()

从MQTT代理处,订阅主题.

int MQTTAsync_subscribe(MQTTAsync handle, const char* topic, int qos, MQTTAsync_responseOptions* response);

参数:
response: 响应参数结构,结构中包含相关的成功/失败回调函数,

MQTTAsync_sendMessage()

int MQTTAsync_sendMessage(MQTTAsync handle, const char* destinationName, const MQTTAsync_message* msg, MQTTAsync_responseOptions* response);

参数:
response,消息发布响应结构体,包含:成/败回调函数指针,用户参数传递

同步错误代码(异步类似)：

//成功
#define MQTTCLIENT_SUCCESS 0
 //失败,通用
#define MQTTCLIENT_FAILURE -1
 //客户端未连接,未连接,先使用引起
#define MQTTCLIENT_DISCONNECTED -3
 //已达到允许同时处理的最大消息数(#define MAX_MSG_ID 65535)
#define MQTTCLIENT_MAX_MESSAGES_INFLIGHT -4
 //UTF-8字符串无效
#define MQTTCLIENT_BAD_UTF8_STRING -5
 //A NULL parameter has been supplied when this is invalid.
#define MQTTCLIENT_NULL_PARAMETER -6
 //主题名包含中间NULL,被截断
#define MQTTCLIENT_TOPICNAME_TRUNCATED -7
 //结构参数不正确,关注版本信息, 发送过库版本与头文件不匹配,导致此异常
#define MQTTCLIENT_BAD_STRUCTURE -8 
//QOS传入异常参数
#define MQTTCLIENT_BAD_QOS -9
 //库版本不支持SSL功能
#define MQTTCLIENT_SSL_NOT_SUPPORTED -10
 //无法识别的MQTT版本
 #define MQTTCLIENT_BAD_MQTT_VERSION -11
 //服务器地址格式错误,协议字首== tcp:// or ssl://
#define MQTTCLIENT_BAD_PROTOCOL -14
 //选项不适用于请求的MQTT版本
 #define MQTTCLIENT_BAD_MQTT_OPTION -15
 //使用的调用 不适用于请求的MQTT版本
 #define MQTTCLIENT_WRONG_MQTT_VERSION -16

参考:
Paho -物联网 MQTT C Cient的实现和详解