[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

@@ -51,10 +51,10 @@
 [def __SSL_STREAM__ [asioreflink ssl__stream ssl::stream<__TCP_SOCKET__>]]
 [def __WEBSOCKET_STREAM__ [beastreflink boost__beast__websocket__stream websocket::stream<NextLayer>]]
 
-[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`]]

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__ 
+The second section will showcase how to use asynchronous functions in __Client__
-with different __CompletionToken__. 
+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]
 

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]
+

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]

example/basic_examples.cpp

@@ -0,0 +1,53 @@
+//[basic_examples
+
+
+//[publisher
+#include <iostream>
+
+#include <boost/asio/io_context.hpp>
+#include <boost/asio/ip/tcp.hpp>
+
+#include <async_mqtt5.hpp>
+
+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<asio::ip::tcp::socket> 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<async_mqtt5::qos_e::at_least_once>(
+		"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();
+}
+
+//]
+
+
+//]