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）。这允许与回调、协程和 Future 进行灵活的使用。 |
| 自定义分配器 | 支持自定义分配器，为内存资源提供了额外的灵活性和控制。Boost.MQTT5 将使用与异步函数处理程序关联的分配器来创建库实现所需的对象实例。 |
| 每次操作的取消 | 所有异步操作均支持根据 Asio 的 每次操作取消 进行单独、有针对性的取消。这使得所有异步函数都可以用于 并行操作，这对于执行需要超时机制的操作尤其有利。 |
| MQTT 5.0 规范的完整实现 | 确保与 MQTT 5.0 标准 完全兼容。最新版本引入了增强系统鲁棒性的关键功能，包括高级错误处理机制、会话和消息过期，以及旨在支持现代物联网用例的其他改进。 |
| 支持 QoS 0、QoS 1 和 QoS 2 | 全面实现 MQTT 协议定义的所有服务质量级别，以匹配消息传递中不同的可靠性需求。 |
| 自定义身份验证 | 定义了一个接口供您的自定义身份验证器执行 增强型身份验证。除了用户名/密码身份验证外，此自定义点还允许实现 SASL 协议支持的任何身份验证机制，为高级安全需求提供了灵活性。 |
| 高可用性 | 支持列出同一集群中的多个 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，并将其添加到您的包含路径。
- 如果您使用 SSL，请下载 OpenSSL，链接该库并将其添加到您的包含路径。
- 将 Boost.MQTT5 的
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();
}
要查看更多示例，请访问 示例。
贡献
当您向此存储库贡献代码时，请先通过 issue、电子邮件或任何其他方式与此存储库的负责人讨论您希望进行的更改，然后再进行更改。
在获得其他开发人员的签名后，您可以合并一个 Pull Request，或者您可以要求审阅者为您合并。
鸣谢
由 Mireo 维护和创作。
