From 47ef696779cab6dc1ecb8d2d50875c19574c06c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Korina=20=C5=A0imi=C4=8Devi=C4=87?= Date: Wed, 15 Nov 2023 09:20:59 +0100 Subject: [PATCH] [mqtt-client] introduction v1 Summary: related to T12804 Reviewers: ivica Reviewed By: ivica Subscribers: miljen, iljazovic Differential Revision: https://repo.mireo.local/D26513 --- doc/qbk/00_main.qbk | 4 +- doc/qbk/02_examples.qbk | 18 ++++++--- doc/qbk/examples/Basic_examples.qbk | 17 ++++++++ doc/qbk/examples/Network_connection.qbk | 6 +-- example/basic_examples.cpp | 53 +++++++++++++++++++++++++ 5 files changed, 88 insertions(+), 10 deletions(-) create mode 100644 doc/qbk/examples/Basic_examples.qbk create mode 100644 example/basic_examples.cpp diff --git a/doc/qbk/00_main.qbk b/doc/qbk/00_main.qbk index d730661..4aa0884 100644 --- a/doc/qbk/00_main.qbk +++ b/doc/qbk/00_main.qbk @@ -51,10 +51,10 @@ [def __SSL_STREAM__ [asioreflink ssl__stream ssl::stream<__TCP_SOCKET__>]] [def __WEBSOCKET_STREAM__ [beastreflink boost__beast__websocket__stream websocket::stream]] -[def __Self__ [reflink2 mqtt_client `mqtt_client`]] - [/ MQTT ] [def __MQTT__ [@https://mqtt.org/ MQTT]] +[def __Self__ Async.MQTT5] +[def __Client__ [reflink2 mqtt_client `mqtt_client`]] [def __UTF8_STRING_PAIR__ [mqttlink 3901013 `UTF-8 String Pair`]] [def __PACKET_SIZE__ [mqttlink 3901024 `packet size`]] diff --git a/doc/qbk/02_examples.qbk b/doc/qbk/02_examples.qbk index 14ad3e4..77f7305 100644 --- a/doc/qbk/02_examples.qbk +++ b/doc/qbk/02_examples.qbk @@ -6,21 +6,29 @@ ] [section:examples Examples] -The following examples demonstrate how to use __Self__ in different scenarios. +The main class in __Self__ is __Client__, and the upcoming sections will briefly explain how to use it. +The first two examples will demonstrate using __Client__ as a publisher and receiver. + +* [link async_mqtt5.examples.publisher The publisher] +* [link async_mqtt5.examples.receiver The receiver] + +The following two sections serve as reference. The first section will show how to use different underlying transport protocols (such as TCP, SSL and WebSocket) -to establish a connection to a MQTT Broker. +to establish a connection to an MQTT Broker. * [link async_mqtt5.examples.network_connection Establishing a network connection with different protocols] -The second section will showcase how to use asynchronous functions in __Self__ -with different __CompletionToken__. +The second section will showcase how to use asynchronous functions in __Client__ +with different completion tokens. * [link async_mqtt5.examples.asio Compatibility with Boost.Asio] * [link async_mqtt5.examples.asio.callbacks Async functions with callbacks] * [link async_mqtt5.examples.asio.cpp20_coroutines Async functions with C++20 coroutines] * [link async_mqtt5.examples.asio.futures Async functions with futures] - + + +[include examples/Basic_examples.qbk] [include examples/Network_connection.qbk] [include examples/Asio_compatibility.qbk] diff --git a/doc/qbk/examples/Basic_examples.qbk b/doc/qbk/examples/Basic_examples.qbk new file mode 100644 index 0000000..23f4166 --- /dev/null +++ b/doc/qbk/examples/Basic_examples.qbk @@ -0,0 +1,17 @@ +[/ + Copyright (c) 2023 Mireo + + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +] + +[import ../../../example/basic_examples.cpp] + +[section:publisher The publisher] +[publisher] +[endsect] + +[section:receiver The receiver] + +[endsect] + diff --git a/doc/qbk/examples/Network_connection.qbk b/doc/qbk/examples/Network_connection.qbk index 54344da..4039b32 100644 --- a/doc/qbk/examples/Network_connection.qbk +++ b/doc/qbk/examples/Network_connection.qbk @@ -15,12 +15,12 @@ transport protocols such as TCP/IP, TLS/SSL, and WebSocket. [import ../../../example/network_connection.cpp] [h3 TCP/IP connection] -To create a TCP/IP connection with a Broker, initialize __Self__ with __TCP_SOCKET__ as the __StreamType__. +To create a TCP/IP connection with a Broker, initialise __Self__ with __TCP_SOCKET__ as the __StreamType__. [tcp] [h3 TLS/SSL connection] To establish a secure and encrypted connection using the TLS/SSL protocol, supply a context object that meets the __TlsContext__ requirements. -Additionally, initialize __Self__ with an underlying stream that implements TLS/SSL protocol as the __StreamType__. +Additionally, initialise __Self__ with an underlying stream that implements TLS/SSL protocol as the __StreamType__. This example will demonstrate how to set up an SSL connection using __SSL_CONTEXT__ and __SSL_STREAM__. To use SSL support in __Asio__, __OPENSSL__ is required. @@ -38,6 +38,6 @@ __WEBSOCKET_STREAM__. [h4 WebSocket over TLS/SSL] [websocket_tls] -Once the __Self__ has been initialized with a suitable __StreamType__, it is prepared for configuration and utilization. +Once the __Client___ has been initialised with a suitable __StreamType__, it is prepared for configuration and utilisation. [endsect] diff --git a/example/basic_examples.cpp b/example/basic_examples.cpp new file mode 100644 index 0000000..9a4313a --- /dev/null +++ b/example/basic_examples.cpp @@ -0,0 +1,53 @@ +//[basic_examples + + +//[publisher +#include + +#include +#include + +#include + +namespace asio = boost::asio; + +void client_publisher() { + // Initialise execution context. + asio::io_context ioc; + + // Initialise the ``__Client__``, establish connection to the Broker over TCP. + async_mqtt5::mqtt_client client (ioc.get_executor(), ""); + client.brokers("mqtt.broker", 1883) // Broker that we want to connect to. 1883 is the default TCP port. + .run(); // Start the client. + + client.async_publish( + "topic", "my application message", + async_mqtt5::retain_e::yes, async_mqtt5::publish_props {}, + [](async_mqtt5::error_code ec, async_mqtt5::reason_code rc, async_mqtt5::puback_props props) { + if (ec) + std::cout << "An application error occurred: " << ec.message() << std::endl; + if (rc) + std::cout << "MQTT protocol error occurred: " << rc.message() << std::endl; + } + ); + + // Publish some more messages... + + // After we are done with publishing all the messages, disconnect the client. + // You can also use mqtt_client::cancel. + // Either way, you should make sure all the operations completed before disconnecting the client! + client.async_disconnect( + async_mqtt5::disconnect_rc_e::normal_disconnection, async_mqtt5::disconnect_props {}, + [](async_mqtt5::error_code ec) { + if (ec) + std::cout << "An error during disconnect occurred: " << ec.message() << std::endl; + }); + + // Start the execution. + ioc.run(); +} + +//] + + +//] \ No newline at end of file