Paho MQTT C—MQTTAsync 库接口

26 天前 · 来自专栏 MQTT

不会卷的C哥

技术栈是C++，爱好是打篮球

MQTTAsync 库接口

MQTTAsync 是一个用于 C/C++ 的 MQTT 客户端库，用于实现 MQTT 协议的异步通信。它基于 Eclipse Paho 的 MQTT C 客户端库，提供了一种异步的、非阻塞的方式来实现与 MQTT 代理通信。

使用 MQTTAsync，你可以轻松地创建 MQTT 客户端应用程序并连接到 MQTT 代理（也称为 MQTT 服务器）。它支持发布（publish）和订阅（subscribe）消息的操作，可以在应用程序之间进行可靠的消息传递。

1、MQTTAsync_create() : MQTTAsync.h

MQTTAsync_create() 是 MQTTAsync 库中用于创建 MQTT 客户端的函数。它接受五个参数和一个返回值，用于创建并初始化 MQTTAsync 客户端对象。

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

以下是 MQTTAsync_create() 函数的详细说明：

MQTTAsync_create(client, serverURI, clientId, persistence_type, persistence_context)

client: 指向 MQTTAsync 客户端指针的指针，用于存储创建的 MQTT 客户端实例的地址。
serverURI: 以 null 结尾的字符串，指定客户端将连接的服务器。它应该遵循 protocol://host:port 的格式，其中 protocol 可以是 tcp:// 或 mqtt://（用于非安全的 TCP 连接），ssl:// 或 mqtts://（用于加密的 SSL/TLS 连接），ws://（用于非安全的 WebSockets）或 wss://（用于安全的 WebSockets）。如果所链接的库未连接到 TLS 版本，则仅支持启用了 TLS 的前缀（ssl、mqtts、wss）。host 可以是 IP 地址或主机名。例如，tcp://localhost:1883 表示连接到默认 MQTT 端口上运行的本地服务器。
clientId: 客户端连接到服务器时传递给服务器的客户端标识符。它应该是以 null 结尾的 UTF-8 编码的字符串。，用于在 MQTT 代理中识别客户端。
persistence_type: 持久化类型，指定客户端的持久化方式。常用的类型有 MQTTCLIENT_PERSISTENCE_NONE（无持久化）、MQTTCLIENT_PERSISTENCE_DEFAULT（默认持久化，使用文件系统）等。MQTTAsync 库提供了几种持久化类型（persistence_type）供选择，常用的类型包括：

MQTTCLIENT_PERSISTENCE_NONE: 表示不使用持久化。在客户端断开连接时，未传递到代理的消息会丢失。
MQTTCLIENT_PERSISTENCE_DEFAULT: 表示使用默认的持久化方式。在 MQTTAsync_create() 中指定该选项后，库将使用文件系统进行持久化。消息将在客户端断开连接时保存到文件系统，并在重新连接时恢复。
MQTTCLIENT_PERSISTENCE_USER: MQTTAsync 库还支持用户自定义持久化方式。你可以实现自己的持久化逻辑，并将其作为 persistence_type 参数传递给 MQTTAsync_create() 函数。

persistence_context: 如果使用 MQTTCLIENT_PERSISTENCE_NONE 持久化，则此参数未使用，应设置为 NULL。对于 MQTTCLIENT_PERSISTENCE_DEFAULT 持久化，它应该指向持久化目录的位置（如果设置为 NULL，则使用工作目录作为持久化目录）。对于使用 MQTTCLIENT_PERSISTENCE_USER 持久化的应用程序，设置此参数以指向有效的 MQTTClient_persistence 结构。

示例用法：

MQTTAsync_create(&client, serverURI, clientId, MQTTCLIENT_PERSISTENCE_DEFAULT, NULL);

以上示例创建了一个 MQTTAsync 客户端，使用默认的持久化方式进行消息持久化。这意味着在客户端断开连接时，未传递到代理的消息将保存在文件系统中，在重新连接时会进行恢复。具体要根据你的需求选择适当的持久化类型。如果需要保证消息的持久性，可以选择使用默认的持久化方式或自定义持久化方式。如果不需要持久化，可以选择 MQTTCLIENT_PERSISTENCE_NONE。

2、MQTTAsync_createWithOptions() : MQTTAsync.h

int MQTTAsync_createWithOptions (   MQTTAsync *     handle,
const char *    serverURI,
const char *    clientId,
int     persistence_type,
void *  persistence_context,
MQTTAsync_createOptions *   options

MQTTAsync_createWithOptions用于创建一个基于给定选项的 MQTT 客户端。

该函数参数前几项与MQTTAsync_create相同，

MQTTAsync_createOptions 结构是在 MQTTAsync.h 头文件中定义的一个数据结构。它包含以下字段：

struct MQTTAsync_createOptions {
    char struct_id[4];
    int struct_version;
    int sendWhileDisconnected;
    int maxBufferedMessages;
    int MQTTVersion;
    int allowDisconnectedSendAtAnyTime;
    int deleteOldestMessages;
    int restoreMessages;
    int persistQoS0;

struct_id ：一个长度为4的字符数组，用于标识结构。
struct_version ：一个整数，表示结构的版本。
sendWhileDisconnected ：一个整数，指定是否可以在断开连接时发送消息。
maxBufferedMessages ：一个整数，表示可以缓冲的最大消息数量。
MQTTVersion ：一个整数，表示要使用的 MQTT 版本。
allowDisconnectedSendAtAnyTime ：一个整数，指定是否允许在任何时候进行断开连接发送。
deleteOldestMessages ：一个整数，指示当缓冲区已满时是否删除最旧的消息。
restoreMessages ：一个整数，指定是否在重新连接时恢复消息。
persistQoS0 ：一个整数，指定是否持久化 Quality of Service (QoS) 0 消息。

该结构的目的是提供异步创建 MQTT 客户端的选项和配置。

返回值:

整数类型的返回值，表示函数执行的状态。如果成功创建了 MQTT 客户端，则返回 MQTTASYNC_SUCCESS （等于0），否则返回其他错误代码。

3、MQTTAsync_connect() : MQTTAsync.h

int MQTTAsync_connect   (   MQTTAsync   handle,
const MQTTAsync_connectOptions *    options

MQTTAsync_connect() 是 MQTTAsync 库中用于建立与 MQTT 代理（服务器）连接的函数。它接受两个参数： MQTTAsync 客户端对象和 MQTTAsync_connectOptions 结构体对象，用于指定连接的选项。

以下是 MQTTAsync_connect() 函数的详细说明：

MQTTAsync_connect(client, connectOptions)

参数：

client: MQTTAsync 客户端对象，即通过 MQTTAsync_create() 创建的 MQTT 客户端实例。
connectOptions: MQTTAsync_connectOptions 结构体对象，用于设置连接的选项。

MQTTAsync_connectOptions 结构体包含了多个字段，常用的字段包括：

structVersion: 结构体的版本号。
clientId: 客户端标识符，用于在 MQTT 代理中识别客户端。
serverURI: MQTT 代理的 URI 地址。
username: 可选的用户名，用于连接认证。
password: 可选的密码，用于连接认证。
keepAliveInterval: 心跳包发送间隔时间。
cleanSession: 连接标识，为 1 时表示启用“干净会话”。
will: 遗嘱消息的相关设置，如 willFlag、willQoS、willTopic 和 willMessage。

MQTTAsync_connect() 函数的返回值是 MQTTAsync_token，它是与连接操作关联的令牌（token）。你可以使用该令牌来跟踪连接操作的状态，或在异步操作完成时处理回调函数。

MQTTAsync_connect() 是一个函数，它使用指定的选项尝试将之前创建的客户端连接到 MQTT 服务器。它属于 MQTTAsync 库的一部分，提供了一个异步的 MQTT 客户端实现。

函数签名:

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

返回值:

如果客户端的连接请求被接受，则返回 MQTTASYNC_SUCCESS 。
大于 0 的错误代码由 MQTT 协议返回：

1：连接被拒绝 - 不可接受的协议版本。
2：连接被拒绝 - 标识符被拒绝。
3：连接被拒绝 - 服务器不可用。
4：连接被拒绝 - 用户名或密码错误。
5：连接被拒绝 - 未经授权。
6-255：保留供将来使用。

该函数尝试基于提供的选项建立 MQTT 客户端与 MQTT 服务器之间的连接。如果连接请求被接受，客户端将成功连接到服务器。如果有任何错误或连接失败，将通过返回值或设置的失败回调函数进行指示。

注意：在调用 MQTTAsync_connect() 之前，推荐使用 MQTTAsync_setCallbacks() 设置所需的回调函数，以启用异步的消息和状态通知。

示例用法：

MQTTAsync client;
MQTTAsync_connectOptions conn_opts = MQTTAsync_connectOptions_initializer;
MQTTAsync_token token;
// 创建 MQTTAsync 客户端
MQTTAsync_create(&client, ADDRESS, CLIENTID, MQTTCLIENT_PERSISTENCE_NONE, NULL);
// 设置连接参数
conn_opts.keepAliveInterval = 20;
conn_opts.cleansession = 1;