Paho MQTT C 开发者快速入门

精简版快速入门，只保留核心概念与上手步骤。安装与从源码构建、同步/异步 API 详解、持久化、SSL/TLS、连接选项、性能优化等详见 Paho_MQTT_C完整文档.md。

1. 一句话了解 Paho MQTT C

Paho MQTT C 是 Eclipse 官方的 C 语言 MQTT 客户端库 ：支持 MQTT v3.1.1 与 v5.0，提供同步 (MQTTClient) 和异步 (MQTTAsync) 两套 API，可连接任意 MQTT 代理进行发布/订阅，带持久化、SSL/TLS、WebSocket 等，适合嵌入式、Linux/Windows/macOS 及 Android。

为什么用？

官方维护、协议支持全（含 MQTT 5 特性）
同步 API 简单阻塞，异步 API 回调驱动不卡主线程
四种库变体（同步/异步 × 是否 SSL）按需选择
跨平台：Linux、Windows、macOS、嵌入式、Android NDK

2. 两种 API：同步 vs 异步

类型	头文件/库	特点	适用场景
同步	MQTTClient.h / paho-mqtt3c	阻塞调用，写法简单	脚本、简单工具、可阻塞场景
异步	MQTTAsync.h / paho-mqtt3a	非阻塞、回调	GUI、移动端、高并发

同步：MQTTClient_connect()、MQTTClient_publishMessage() 等会阻塞直到完成或超时。
异步：MQTTAsync_connect()、MQTTAsync_sendMessage() 立即返回，结果通过 onSuccess/onFailure 等回调通知，主线程可保持响应。

3. 库变体怎么选

库名	API	SSL/TLS	说明
paho-mqtt3c	同步	否	普通 TCP
paho-mqtt3cs	同步	是	需加密时用
paho-mqtt3a	异步	否	非阻塞普通连接
paho-mqtt3as	异步	是	非阻塞 + 加密

按「是否要阻塞」和「是否要 SSL」选一个即可。

4. 5 分钟上手

4.1 安装

bash 复制代码

# Debian/Ubuntu
sudo apt-get install libpaho-mqtt-dev

# macOS
brew install paho-mqtt

或从源码构建（需 SSL 时加 -DPAHO_WITH_SSL=TRUE）：

bash 复制代码

git clone https://github.com/eclipse-paho/paho.mqtt.c.git
cd paho.mqtt.c && mkdir build && cd build
cmake .. -DPAHO_BUILD_SHARED=TRUE -DPAHO_WITH_SSL=TRUE
make && sudo make install

4.2 最简发布（同步）

c 复制代码

#include "MQTTClient.h"
#define ADDRESS "tcp://mqtt.eclipseprojects.io:1883"
#define CLIENTID "ExampleClientPub"
#define TOPIC   "MQTT Examples"

// 创建 → 连接 → 发消息 → 等待完成 → 断开
MQTTClient client;
MQTTClient_connectOptions conn_opts = MQTTClient_connectOptions_initializer;
MQTTClient_message pubmsg = MQTTClient_message_initializer;
MQTTClient_deliveryToken token;

MQTTClient_create(&client, ADDRESS, CLIENTID, MQTTCLIENT_PERSISTENCE_NONE, NULL);
conn_opts.keepAliveInterval = 20;
conn_opts.cleansession = 1;
MQTTClient_connect(client, &conn_opts);

pubmsg.payload = "Hello World!";
pubmsg.payloadlen = (int)strlen("Hello World!");
pubmsg.qos = 1;
pubmsg.retained = 0;
MQTTClient_publishMessage(client, TOPIC, &pubmsg, &token);
MQTTClient_waitForCompletion(client, token, 10000);

MQTTClient_disconnect(client, 10000);
MQTTClient_destroy(&client);

4.3 订阅（同步）

MQTTClient_setCallbacks 注册 connlost、msgarrvd、delivered，然后 MQTTClient_connect、MQTTClient_subscribe，在 msgarrvd 里处理收到的消息。

4.4 命令行测试

bash 复制代码

# 订阅
paho_c_sub -t "test/topic" -h mqtt.eclipseprojects.io

# 发布（另开终端）
paho_c_pub -t "test/topic" -m "Hello" -h mqtt.eclipseprojects.io

5. 编译与链接

使用 API	链接库
同步	`-lpaho-mqtt3c`（SSL 版用 paho-mqtt3cs）
异步	`-lpaho-mqtt3a`（SSL 版用 paho-mqtt3as）

bash 复制代码

gcc -o pub MQTTClient_publish.c -lpaho-mqtt3c
gcc -o sub MQTTClient_subscribe.c -lpaho-mqtt3c
gcc -o async_pub MQTTAsync_publish.c -lpaho-mqtt3a

6. 常用 API 速览

同步 (MQTTClient)
MQTTClient_create → MQTTClient_connect → MQTTClient_publishMessage / MQTTClient_subscribe → MQTTClient_waitForCompletion（发布时）→ MQTTClient_disconnect → MQTTClient_destroy。订阅时用 MQTTClient_setCallbacks 注册消息与连接丢失回调。

异步 (MQTTAsync)
MQTTAsync_create → MQTTAsync_setCallbacks（可选）→ MQTTAsync_connect（带 onSuccess/onFailure）→ 在回调里 MQTTAsync_sendMessage 或 MQTTAsync_subscribe → 最后 MQTTAsync_destroy。

7. QoS 与传输选项

QoS 0：最多一次（发完即忘）
QoS 1：至少一次（需 ACK）
QoS 2：恰好一次（四步握手）

URI 方案 ：tcp:// / mqtt://（明文）、ssl:// / mqtts://（TLS）、ws:// / wss://（WebSocket）、unix://（本机 Unix 套接字）。

8. 下一步

完整文档：Paho_MQTT_C完整文档.md（安装、从源码构建、发布/订阅详解、同步/异步 API、持久化、SSL/TLS、连接选项、性能优化等）
官方仓库：eclipse-paho/paho.mqtt.c，示例在 src/samples。

9. 常见问题

现象	可能原因	处理
链接错误	未链接对应库	同步用 `-lpaho-mqtt3c`，异步用 `-lpaho-mqtt3a`，SSL 用 3cs/3as
连接失败	地址/端口/网络错误	检查 broker 地址与防火墙，可用 `paho_c_pub/sub` 先测
收不到消息	未订阅或主题不对	确认 `subscribe` 的 topic 与发布一致，注意通配符
SSL 编译失败	未装 OpenSSL 或未开选项	安装 openssl-dev，CMake 加 `-DPAHO_WITH_SSL=TRUE`

提示：同步 API 在回调里不要做耗时操作，以免阻塞库线程；异步 API 适合 GUI 或需要高并发的场景。

Paho MQTT C 开发者快速入门