[mqtt-client] added chapter on different ways to establish network connection

Summary:
related to T12804
	- added chapter on network connection
	- added code examples
	- remove any_authenticator from doc targets
	- manually create table of contents

Reviewers: ivica

Reviewed By: ivica

Subscribers: miljen, iljazovic

Differential Revision: https://repo.mireo.local/D26401

example/cpp20_coroutines.cpp

@@ -20,7 +20,7 @@ using client_type = async_mqtt5::mqtt_client<stream_type>;
  * When an asynchronous function is called, the coroutine is suspended.
  * After the asynchronous operation finishes, the coroutine resumes from the point it was suspended.
  *
- * In this example, each asynchronous function is invoked with boost::asio::use_awaitable completion token.
+ * In this example, each asynchronous function is invoked with ``__USE_AWAITABLE__`` completion token.
  * When using this completion token, co_await will throw exceptions instead of returning an error code.
  * If you do not wish to throw exceptions, refer to the following use_nothrow_awaitable and nothrow_coroutine() example.
  */
@@ -100,7 +100,7 @@ asio::awaitable<void> coroutine(client_type& client) {
 }
 
 /**
- * A modified completion token. Using this completion token instead of asio::use_awaitable
+ * A modified completion token. Using this completion token instead of ``__USE_AWAITABLE__``
  * will prevent co_await from throwing exceptions. Instead, co_await will return the error code
  * along with other values specified in the handler signature.
  */

example/futures.cpp

@@ -70,7 +70,7 @@ void run_with_future(client_type& client) {
 	std::cout << "Subscribe Reason Code: " << sub_rcs[0].message() << std::endl;
 
 	// Note: the get() call on async_receive future could block indefinitely if the mqtt_client
-	// failed to subscribe or there are no Application Messages to be received from the subcribed Topic!
+	// failed to subscribe or there are no Application Messages to be received from the subscribed Topic!
 	if (!sub_rcs[0]) {
 		using rec_fut_type = std::tuple<std::string, std::string, async_mqtt5::publish_props>;
 		std::future<rec_fut_type> rec_fut = client.async_receive(asio::use_future);

example/network_connection.cpp

@@ -0,0 +1,164 @@
+//[network_connectiong
+
+
+//[tcp
+#include <boost/asio/io_context.hpp>
+
+#include <boost/asio/ip/tcp.hpp>
+
+#include <async_mqtt5.hpp>
+
+void tcp_setup() {
+	boost::asio::io_context ioc;
+
+	// Use ``__TCP_SOCKET__`` as the underlying stream.
+	async_mqtt5::mqtt_client<boost::asio::ip::tcp::socket> client(ioc, "");
+}
+
+//]
+
+
+//[tls
+#include <boost/asio/io_context.hpp>
+#include <boost/asio/ssl.hpp>
+
+#include <boost/asio/ip/tcp.hpp>
+
+#include <async_mqtt5.hpp>
+
+
+// External customization point.
+namespace async_mqtt5 {
+
+// This client uses this funcction to indicate which hostname it is
+// attempting to connect to at the start of the handshaking process.
+template <typename StreamBase>
+void assign_tls_sni(
+	const authority_path& ap,
+	boost::asio::ssl::context& ctx,
+	boost::asio::ssl::stream<StreamBase>& stream
+) {
+	SSL_set_tlsext_host_name(stream.native_handle(), ap.host.c_str());
+}
+
+} // end namespace async_mqtt5
+
+// The certificate file in PEM format.
+constexpr char certificate[] =
+"-----BEGIN CERTIFICATE-----\n"
+"...........................\n"
+"-----END CERTIFICATE-----\n"
+;
+
+void ssl_setup() {
+	boost::asio::io_context ioc;
+
+	// Context satisfying ``__TlsContext__`` requirements that the underlying SSL stream will use.
+	// The purpose of the context is to allow us to set up TLS/SSL-related options. 
+	// See ``__SSL__`` for more information and options.
+	boost::asio::ssl::context context(boost::asio::ssl::context::tls_client);
+
+	async_mqtt5::error_code ec;
+
+	// Add the trusted certificate authority for performing verification.
+	context.add_certificate_authority(boost::asio::buffer(certificate), ec);
+
+	// Set peer verification mode used by the context.
+	// This will verify that the server's certificate is valid and signed by a trusted certificate authority.
+	context.set_verify_mode(boost::asio::ssl::verify_peer, ec);
+
+	// Use ``__SSL_STREAM__`` as the ``__StreamType__`` with ``__SSL_CONTEXT__`` as the ``__TlsContext__``.
+	async_mqtt5::mqtt_client<
+		boost::asio::ssl::stream<boost::asio::ip::tcp::socket>,
+		boost::asio::ssl::context
+	> client(ioc, "", std::move(context));
+}
+//]
+
+//[websocket_tcp
+#include <boost/asio/io_context.hpp>
+
+#include <boost/asio/ip/tcp.hpp>
+
+#include <boost/beast/websocket.hpp>
+
+#include <async_mqtt5.hpp>
+
+void websocket_tcp_setup() {
+	boost::asio::io_context ioc;
+
+	// Use ``[beastreflink boost__beast__websocket__stream websocket::stream<__TCP_SOCKET__>]`` as the underlying stream.
+	async_mqtt5::mqtt_client<
+		boost::beast::websocket::stream<boost::asio::ip::tcp::socket>
+	> client(ioc, "");
+}
+
+//]
+
+//[websocket_tls
+#include <boost/asio/io_context.hpp>
+#include <boost/asio/ssl.hpp>
+
+#include <boost/asio/ip/tcp.hpp>
+
+#include <boost/beast/websocket.hpp>
+
+#include <async_mqtt5.hpp>
+
+constexpr char ca[] =
+"-----BEGIN CERTIFICATE-----\n"
+"...........................\n"
+"-----END CERTIFICATE-----\n"
+;
+
+namespace boost::beast::websocket {
+
+// ``[beastreflink boost__beast__websocket__async_teardown boost::beast::websocket::async_teardown]`` is a free function
+// designed to initiate the asynchronous teardown of a connection.
+// The specific behaviour of this function is based on the NextLayer type (Socket type) used to create the ``__WEBSOCKET_STREAM__``.
+// ``__Beast__`` library includes an implementation of this function for ``__TCP_SOCKET__``.
+// However, the callers are responsible for providing a suitable overload of this function for any other type,
+// such as ``__SSL_STREAM__`` as shown in this example.
+template <typename TeardownHandler>
+void async_teardown(
+	boost::beast::role_type role,
+	asio::ssl::stream<asio::ip::tcp::socket>& stream,
+	TeardownHandler&& handler
+) {
+	return stream.async_shutdown(std::forward<TeardownHandler>(handler));
+}
+
+} // end namespace boost::beast::websocket
+
+namespace async_mqtt5 {
+
+template <typename streambase>
+void assign_tls_sni(
+	const authority_path& ap,
+	asio::ssl::context& ctx,
+	asio::ssl::stream<streambase>& stream
+) {
+	ssl_set_tlsext_host_name(stream.native_handle(), ap.host.c_str());
+}
+
+} // end namespace async_mqtt5
+
+void websocket_tls_setup() {
+	boost::asio::io_context ioc;
+
+	boost::asio::ssl::context context(boost::asio::ssl::context::tls_client);
+
+	async_mqtt5::error_code ec;
+	context.add_certificate_authority(boost::asio::buffer(ca), ec);
+	context.set_verify_mode(boost::asio::ssl::verify_peer, ec);
+
+	async_mqtt5::mqtt_client<
+		boost::beast::websocket::stream<boost::asio::ssl::stream<boost::asio::ip::tcp::socket>>,
+		boost::asio::ssl::context
+	> client(ioc, "", std::move(context));
+}
+
+//]
+
+
+//]