C++ 17 添加于 Boost 1.88.0
本次发布
依赖项
已移除
Boost.MQTT5：一个基于 Boost.Asio 的 C++17 MQTT 客户端
| 分支 | Linux 构建 | Windows 构建 | 覆盖率 | 文档 |
|---|---|---|---|---|
master |
 |
 |
 |
文档 |
develop |
 |
 |
 |
文档 |
Boost.MQTT5 是一个专业的、工业级的 C++17 客户端，基于 Boost.Asio 构建。该客户端设计用于向兼容 MQTT 5.0 的 Broker 发布或接收消息。Boost.MQTT5 代表了 MQTT 5.0 协议标准的全面实现，完全支持使用 QoS 0、1 和 2 发布或接收消息。
动机
MQTT 协议广泛用于各种实际场景的通信，主要作为数据传输到物联网设备或从物联网设备传输数据的可靠通信协议。虽然 MQTT 协议相对简单，但将其集成到应用程序中可能很复杂，这主要是由于断开/重连序列后消息重传的实现具有挑战性。为了解决这些挑战并一劳永逸地简化 MQTT 集成，Boost.MQTT5 在设计时考虑了以下核心目标：
| 目标 | 描述 |
|---|---|
| “即插即用”接口，抽象化 MQTT 协议的内部细节、低级网络事件、消息重传和其他复杂性 | 使开发人员只需一行代码即可发布或接收消息，大大降低了学习曲线和开发时间。入门只需要基本的 MQTT 知识，使得该库对所有技能水平的开发人员都易于访问。 |
| 高度可靠和健壮的客户端，可处理网络丢失、不可靠数据传输、网络延迟和其他不可预测的事件 | 该客户端不暴露连接函数（也不暴露异步连接函数）；相反，网络连接、MQTT 握手和消息重传会在客户端内部自动处理，同时严格遵守 MQTT 规范。这种自动化消除了开发人员编写大量易出错的代码来处理这些场景的需求，使他们能够专注于应用程序的核心功能。 |
| 完全符合 Boost.Asio 的通用异步模型 | 接口和实现策略基于 Boost.Asio 的基础。这种兼容性使得与 Boost.Asio 生态系统中的任何其他库能够无缝集成。 |
何时使用
如果以下任一陈述为真，Boost.MQTT5 可能适合您：
- 您的应用程序使用 Boost.Asio 并需要集成 MQTT 客户端。
- 您需要异步访问 MQTT Broker。
- 您正在开发一个需要连接到 MQTT Broker 的更高级别组件。
- 您需要一个可靠且有弹性的 MQTT 客户端来自动处理所有与网络相关的问题。
如果以下情况，它可能不适合您：
- 您仅需要同步访问 MQTT Broker。
- 您连接的 MQTT Broker 不支持 MQTT 5 版本。
功能
Boost.MQTT5 是一个设计理念是用户应仅专注于应用程序逻辑，而非网络复杂性的库。该库试图通过一系列旨在提升开发体验的关键功能来体现这一理念。
| 功能 | 描述 |
|---|---|
| 完整的 TCP、TLS/SSL 和 WebSocket 支持 | MQTT 协议需要一个底层的网络协议，该协议提供有序、无损、双向的连接（流）。用户可以通过模板参数自定义此流。Boost.MQTT5 库已在最常用的传输协议上进行了测试：使用 boost::asio::ip::tcp::socket 的 TCP/IP、使用 boost::asio::ssl::stream 的 TLS/SSL、使用 boost::beast::websocket::stream 的 WebSocket/TCP 和 WebSocket/TLS。 |
| 自动重连和重试机制 | 自动处理连接丢失、回退、重连和消息传输。自动化这些过程使用户能够完全专注于应用程序的功能。请参阅 内置自动重连和重试机制。 |
| 优先考虑效率 | 尽可能高效地利用网络和内存资源。 |
| 最小内存占用 | 确保在物联网设备常见的资源受限环境中实现最佳性能。 |
| 完成令牌 | 所有异步函数都使用 Boost.Asio 的通用异步模型实现，并支持 CompletionToken。这使得其可以与回调、协程和 Futures 进行灵活使用。 |
| 自定义分配器 | 支持自定义分配器，为内存资源提供了额外的灵活性和控制。Boost.MQTT5 将使用与异步函数处理程序关联的分配器来创建库实现所需的对象实例。 |
| 每操作取消 | 所有异步操作均支持按 Asio 的 每操作取消 进行单独、定向的取消。这使得所有异步函数都可以在 并行操作 中使用，这对于执行需要超时机制的操作尤其有利。 |
| MQTT 5.0 规范的完整实现 | 确保与 MQTT 5.0 标准完全兼容。这一最新版本引入了增强系统鲁棒性的关键功能，包括高级错误处理机制、会话和消息过期，以及其他旨在支持现代物联网用例的改进。 |
| 支持 QoS 0、QoS 1 和 QoS 2 | 完全实现 MQTT 协议定义的所有服务质量级别，以匹配消息传递中不同的可靠性需求。 |
| 自定义身份验证 | 定义一个接口供您的自定义身份验证器执行 增强身份验证。除了用户名/密码身份验证外，此自定义点还支持实现 SASL 协议支持的任何身份验证机制，为高级安全需求提供了灵活性。 |
| 高可用性 | 支持列出同一个集群中的多个 Broker，客户端可以连接到这些 Broker。如果与一个 Broker 的连接失败，客户端将切换到列表中的下一个 Broker。 |
| 离线缓冲 | 自动缓冲离线时发出的所有请求，确保在连接重新建立时发送。这使用户可以自由调用任何异步函数，而不管当前的连接状态如何。 |
入门
Boost.MQTT5 是一个仅包含头文件的库。要使用 Boost.MQTT5，需要以下条件：
- C++17 兼容编译器
- Boost 1.82 或更高版本。除了 Asio，我们还使用其他仅包含头文件的库。
- OpenSSL。如果您需要 SSL 连接，请使用 boost::asio::ssl::stream。
Boost.MQTT5 已在以下编译器上进行了测试：
- clang 12.0 - 18.0 (Linux)
- GCC 9 - 14 (Linux)
- MSVC 14.37 - Visual Studio 2022 (Windows)
使用库
- 下载 Boost，并将其添加到您的 include 路径。
- 如果您使用 SSL，请下载 OpenSSL，链接库并将其添加到您的 include 路径。
- 将 Boost.MQTT5 的
include文件夹添加到您的 include 路径。
您可以在 Linux 上使用以下命令行编译下面的示例：
$ clang++ -std=c++17 <source-cpp-file> -o example -I<path-to-boost> -Iinclude -pthread
示例
以下示例说明了配置客户端并发布一个带有 QoS 0 的“Hello World!”应用程序消息的场景。
#include <boost/mqtt5/mqtt_client.hpp>
#include <boost/mqtt5/types.hpp>
#include <boost/asio/io_context.hpp>
#include <boost/asio/detached.hpp>
#include <boost/asio/ip/tcp.hpp>
#include <iostream>
int main() {
boost::asio::io_context ioc;
boost::mqtt5::mqtt_client<boost::asio::ip::tcp::socket> c(ioc);
c.brokers("<your-mqtt-broker>", 1883)
.credentials("<your-client-id>", "<client-username>", "<client-pwd>")
.async_run(boost::asio::detached);
c.async_publish<boost::mqtt5::qos_e::at_most_once>(
"<topic>", "Hello world!",
boost::mqtt5::retain_e::no, boost::mqtt5::publish_props {},
[&c](boost::mqtt5::error_code ec) {
std::cout << ec.message() << std::endl;
c.async_disconnect(boost::asio::detached); // disconnect and close the Client
}
);
ioc.run();
}
要查看更多示例，请访问 示例。
贡献
在贡献此存储库时，请先通过问题、电子邮件或任何其他方式与此存储库的所有者讨论您希望进行的更改，然后再进行更改。
一旦获得其他开发者的签名，您就可以合并一个 Pull Request，或者您可以要求审阅者为您合并。
鸣谢
由 Mireo 维护和创作。
