feedc0de/boost_mqtt5
1
0
Fork 0
forked from boostorg/mqtt5
Code Pull Requests Activity

Update documentation

Browse Source 
Summary:
related to T12804
- fixes in publisher and receiver examples
- update year to 2024
- remove extra documentation link in README
- remove unnecessary copyright & license section, it is automatically generated from 00_main.qbk

Reviewers: ivica

Reviewed By: ivica

Subscribers: miljen, iljazovic

Differential Revision: https://repo.mireo.local/D27889
This commit is contained in:
Korina Šimičević
2024-02-13 10:22:39 +01:00
parent 19aaba3cdc
commit aeab5f9665
31 changed files with 26 additions and 222 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@ -51,8 +51,6 @@ You can compile the example below with the following command line on Linux:
Usage and API
---------
Detailed documentation is available [here](https://spacetime.mireo.com/async-mqtt5/).
The following example illustrates a simple scenario of configuring a Client and publishing a
"Hello World!" Application Message with `QoS` 0.

4
doc/qbk/00_main.qbk
View File

@ -1,8 +1,8 @@
[library Async.MQTT5: a C++17 MQTT client
[quickbook 1.7]
[copyright 2023 Mireo]
[copyright 2023-2024 Mireo]
[id async_mqtt5]
[purpose C++20 MQTT client]
[purpose C++17 MQTT client]
[license
Distributed under the Boost Software License, Version 1.0.
(See accompanying file LICENSE_1_0.txt or copy at

7
doc/qbk/02_examples.qbk
View File

@ -1,10 +1,3 @@
[/
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)
]
[section:examples Examples]
The main class in __Self__ is __Client__, and the upcoming examples will briefly explain how to use it.

7
doc/qbk/examples/Completion_tokens.qbk
View File

@ -1,10 +1,3 @@
[/
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)
]
[section:completion_tokens Completion tokens]
The __Client__ is built upon __Asio__ and thus follows the same principles.
This section illustrates the usage of __Client__ async

7
doc/qbk/examples/Network_connection.qbk
View File

@ -1,10 +1,3 @@
[/
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)
]
[section:network_connection Establishing a network connection with different protocols ]
The __MQTT__ protocol requires the underlying transport protocol that ensures
orderly, lossless transmission of byte streams between the Client and Server in both directions.

7
doc/qbk/examples/Tutorial.qbk
View File

@ -1,10 +1,3 @@
[/
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)
]
[section:publisher The publisher]
This example will show how to use __Client__ as a publisher.
The __Client__ will use TCP to connect to the Broker, and __USE_AWAITABLE__ as the completion token.

7
doc/qbk/reference/Error_handling.qbk
View File

@ -1,10 +1,3 @@
[/
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)
]
[section:Error_handling Error handling]
The table below provides a reference of all __ERROR_CODE__ instances that asynchronous operations

7
doc/qbk/reference/concepts/ExecutionContext.qbk
View File

@ -1,10 +1,3 @@
[/
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)
]
[section:ExecutionContext ExecutionContext concept]
`ExecutionContext` represents a place where function objects will be executed.

7
doc/qbk/reference/concepts/StreamType.qbk
View File

@ -1,10 +1,3 @@
[/
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)
]
[section:StreamType StreamType concept]
`StreamType` represents the transport protocol type used to transfer stream of bytes.

7
doc/qbk/reference/concepts/TlsContext.qbk
View File

@ -1,10 +1,3 @@
[/
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)
]
[section:TlsContext TlsContext concept]
`TlsContext` represents an object that defines user's configuration

7
doc/qbk/reference/concepts/is_authenticator.qbk
View File

@ -1,10 +1,3 @@
[/
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)
]
[section:is_authenticator is_authenticator concept]
A type `Authenticator` satisfies `is_authenticator` concept if it satisifes the requirements listed below.

9
doc/qbk/reference/properties/auth_props.qbk
View File

@ -1,10 +1,3 @@
[/
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)
]
[section:auth_props AUTH properties]
The last field in the Variable header of __AUTH__ packet is a set of Properties.
A set contains a Property Length followed by the Properties.
@ -37,7 +30,7 @@ The following example shows how to set a Property value:
The following example shows how to retrieve a Property value:
[note When retrieving a property value, the subscript operator will consistently return a `std::optional` of the value type for all properties,
[note When retrieving a property value, the subscript operator will return a `std::optional` of the value type for all properties,
except for `async_mqtt5::prop::user_property`, where it will return an instance of its value type, `std::vector<std::string>`.]
[!c++]

9
doc/qbk/reference/properties/connack_props.qbk
View File

@ -1,10 +1,3 @@
[/
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)
]
[section:connack_props CONNACK properties]
The last field in the Variable header of __CONNACK__ packet is a set of Properties.
A set contains a Property Length followed by the Properties.
@ -53,7 +46,7 @@ The following example shows how to set a Property value:
The following example shows how to retrieve a Property value:
[note When retrieving a property value, the subscript operator will consistently return a `std::optional` of the value type for all properties,
[note When retrieving a property value, the subscript operator will return a `std::optional` of the value type for all properties,
except for `async_mqtt5::prop::user_property`, where it will return an instance of its value type, `std::vector<std::string>`.]
[!c++]

9
doc/qbk/reference/properties/connect_props.qbk
View File

@ -1,10 +1,3 @@
[/
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)
]
[section:connect_props CONNECT properties]
The last field in the Variable header of __CONNECT__ packet is a set of Properties.
A set contains a Property Length followed by the Properties.
@ -44,7 +37,7 @@ The following example shows how to set a Property value:
The following example shows how to retrieve a Property value:
[note When retrieving a property value, the subscript operator will consistently return a `std::optional` of the value type for all properties,
[note When retrieving a property value, the subscript operator will return a `std::optional` of the value type for all properties,
except for `async_mqtt5::prop::user_property`, where it will return an instance of its value type, `std::vector<std::string>`.]
[!c++]

9
doc/qbk/reference/properties/disconnect_props.qbk
View File

@ -1,10 +1,3 @@
[/
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)
]
[section:disconnect_props DISCONNECT properties]
The last field in the Variable header of __DISCONNECT__ packet is a set of Properties.
A set contains a Property Length followed by the Properties.
@ -36,7 +29,7 @@ The following example shows how to set a Property value:
The following example shows how to retrieve a Property value:
[note When retrieving a property value, the subscript operator will consistently return a `std::optional` of the value type for all properties,
[note When retrieving a property value, the subscript operator will return a `std::optional` of the value type for all properties,
except for `async_mqtt5::prop::user_property`, where it will return an instance of its value type, `std::vector<std::string>`.]
[!c++]

9
doc/qbk/reference/properties/puback_props.qbk
View File

@ -1,10 +1,3 @@
[/
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)
]
[section:puback_props PUBACK properties]
The last field in the Variable header of __PUBACK__ packet is a set of Properties.
A set contains a Property Length followed by the Properties.
@ -34,7 +27,7 @@ The following example shows how to set a Property value:
The following example shows how to retrieve a Property value:
[note When retrieving a property value, the subscript operator will consistently return a `std::optional` of the value type for all properties,
[note When retrieving a property value, the subscript operator will return a `std::optional` of the value type for all properties,
except for `async_mqtt5::prop::user_property`, where it will return an instance of its value type, `std::vector<std::string>`.]
[!c++]

9
doc/qbk/reference/properties/pubcomp_props.qbk
View File

@ -1,10 +1,3 @@
[/
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)
]
[section:pubcomp_props PUBCOMP properties]
The last field in the Variable header of __PUBCOMP__ packet is a set of Properties.
A set contains a Property Length followed by the Properties.
@ -34,7 +27,7 @@ The following example shows how to set a Property value:
The following example shows how to retrieve a Property value:
[note When retrieving a property value, the subscript operator will consistently return a `std::optional` of the value type for all properties,
[note When retrieving a property value, the subscript operator will return a `std::optional` of the value type for all properties,
except for `async_mqtt5::prop::user_property`, where it will return an instance of its value type, `std::vector<std::string>`.]
[!c++]

9
doc/qbk/reference/properties/publish_props.qbk
View File

@ -1,10 +1,3 @@
[/
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)
]
[section:publish_props PUBLISH properties]
The last field in the Variable header of __PUBLISH__ packet is a set of Properties.
A set contains a Property Length followed by the Properties.
@ -42,7 +35,7 @@ The following example shows how to set a Property value:
The following example shows how to retrieve a Property value:
[note When retrieving a property value, the subscript operator will consistently return a `std::optional` of the value type for all properties,
[note When retrieving a property value, the subscript operator will return a `std::optional` of the value type for all properties,
except for `async_mqtt5::prop::user_property`, where it will return an instance of its value type, `std::vector<std::string>`.]
[!c++]

9
doc/qbk/reference/properties/pubrec_props.qbk
View File

@ -1,10 +1,3 @@
[/
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)
]
[section:pubrec_props PUBREC properties]
The last field in the Variable header of __PUBREC__ packet is a set of Properties.
A set contains a Property Length followed by the Properties.
@ -34,7 +27,7 @@ The following example shows how to set a Property value:
The following example shows how to retrieve a Property value:
[note When retrieving a property value, the subscript operator will consistently return a `std::optional` of the value type for all properties,
[note When retrieving a property value, the subscript operator will return a `std::optional` of the value type for all properties,
except for `async_mqtt5::prop::user_property`, where it will return an instance of its value type, `std::vector<std::string>`.]
[!c++]

9
doc/qbk/reference/properties/pubrel_props.qbk
View File

@ -1,10 +1,3 @@
[/
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)
]
[section:pubrel_props PUBREL properties]
The last field in the Variable header of __PUBREL__ packet is a set of Properties.
A set contains a Property Length followed by the Properties.
@ -33,7 +26,7 @@ The following example shows how to set a Property value:
The following example shows how to retrieve a Property value:
[note When retrieving a property value, the subscript operator will consistently return a `std::optional` of the value type for all properties,
[note When retrieving a property value, the subscript operator will return a `std::optional` of the value type for all properties,
except for `async_mqtt5::prop::user_property`, where it will return an instance of its value type, `std::vector<std::string>`.]
[!c++]

9
doc/qbk/reference/properties/suback_props.qbk
View File

@ -1,10 +1,3 @@
[/
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)
]
[section:suback_props SUBACK properties]
The last field in the Variable header of __SUBACK__ packet is a set of Properties.
A set contains a Property Length followed by the Properties.
@ -34,7 +27,7 @@ The following example shows how to set a Property value:
The following example shows how to retrieve a Property value:
[note When retrieving a property value, the subscript operator will consistently return a `std::optional` of the value type for all properties,
[note When retrieving a property value, the subscript operator will return a `std::optional` of the value type for all properties,
except for `async_mqtt5::prop::user_property`, where it will return an instance of its value type, `std::vector<std::string>`.]
[!c++]

9
doc/qbk/reference/properties/subscribe_props.qbk
View File

@ -1,10 +1,3 @@
[/
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)
]
[section:subscribe_props SUBSCRIBE properties]
The last field in the Variable header of __SUBSCRIBE__ packet is a set of Properties.
A set contains a Property Length followed by the Properties.
@ -35,7 +28,7 @@ The following example shows how to set a Property value:
The following example shows how to retrieve a Property value:
[note When retrieving a property value, the subscript operator will consistently return a `std::optional` of the value type for all properties,
[note When retrieving a property value, the subscript operator will return a `std::optional` of the value type for all properties,
except for `async_mqtt5::prop::user_property`, where it will return an instance of its value type, `std::vector<std::string>`.]
[!c++]

9
doc/qbk/reference/properties/unsuback_props.qbk
View File

@ -1,10 +1,3 @@
[/
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)
]
[section:unsuback_props UNSUBACK properties]
The last field in the Variable header of __UNSUBACK__ packet is a set of Properties.
A set contains a Property Length followed by the Properties.
@ -34,7 +27,7 @@ The following example shows how to set a Property value:
The following example shows how to retrieve a Property value:
[note When retrieving a property value, the subscript operator will consistently return a `std::optional` of the value type for all properties,
[note When retrieving a property value, the subscript operator will return a `std::optional` of the value type for all properties,
except for `async_mqtt5::prop::user_property`, where it will return an instance of its value type, `std::vector<std::string>`.]
[!c++]

9
doc/qbk/reference/properties/unsubscribe_props.qbk
View File

@ -1,10 +1,3 @@
[/
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)
]
[section:unsubscribe_props UNSUBSCRIBE properties]
The last field in the Variable header of __UNSUBSCRIBE__ packet is a set of Properties.
A set contains a Property Length followed by the Properties.
@ -35,7 +28,7 @@ The following example shows how to set a Property value:
The following example shows how to retrieve a Property value:
[note When retrieving a property value, the subscript operator will consistently return a `std::optional` of the value type for all properties,
[note When retrieving a property value, the subscript operator will return a `std::optional` of the value type for all properties,
except for `async_mqtt5::prop::user_property`, where it will return an instance of its value type, `std::vector<std::string>`.]
[!c++]

9
doc/qbk/reference/properties/will_props.qbk
View File

@ -1,10 +1,3 @@
[/
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)
]
[section:will_props Will properties]
The Will Properties consist of the properties that determine when to publish the [reflink2 will Will] Message
and the Application Message properties to be sent with the [reflink2 will Will] Message.
@ -41,7 +34,7 @@ The following example shows how to set a Property value:
The following example shows how to retrieve a Property value:
[note When retrieving a property value, the subscript operator will consistently return a `std::optional` of the value type for all properties,
[note When retrieving a property value, the subscript operator will return a `std::optional` of the value type for all properties,
except for `async_mqtt5::prop::user_property`, where it will return an instance of its value type, `std::vector<std::string>`.]
[!c++]

7
doc/qbk/reference/quickref.xml
View File

@ -1,13 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
<!--
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)
-->
<informaltable frame="all">
<tgroup cols="4">
<colspec colname="a"/><colspec colname="b"/><colspec colname="c"/><colspec colname="d"/>

7
doc/qbk/reference/reason_codes/Reason_codes.qbk
View File

@ -1,10 +1,3 @@
[/
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)
]
[section:Reason_codes Reason codes]
This section lists all possible __REASON_CODE__ instances representing

7
doc/qbk/reference/reason_codes/rcref.xml
View File

@ -1,13 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
<!--
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)
-->
<informaltable frame="all">
<tgroup cols="3">
<colspec colname="a"/><colspec colname="b"/><colspec colname="c"/>

14
doc/reference.xsl
View File

@ -1,13 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<!--
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)
-->
<xsl:output method="text"/>
<xsl:strip-space elements="*"/>
<xsl:preserve-space elements="para"/>
@ -26,12 +19,7 @@
Anything in a "detail" namespace is skipped.
-->
<xsl:template match="/doxygen">
<xsl:text>[/
/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)
/]
<xsl:text>
[section:ref Reference]
[xinclude quickref.xml]

8
example/publisher.cpp
View File

@ -15,10 +15,10 @@
namespace asio = boost::asio;
asio::awaitable<void> client_publisher(asio::io_context& ioc) {
// Initialise the ``__Client__``, establish connection to the Broker over TCP.
// Initialise the Client, establish connection to the Broker over TCP.
async_mqtt5::mqtt_client<asio::ip::tcp::socket> client(ioc, "");
// Configure the ``__Client__``.
// Configure the Client.
// It is mandatory to call brokers() and async_run() to configure the Brokers to connect to and start the Client.
client.brokers("mqtt.broker", 1883) // Broker that we want to connect to. 1883 is the default TCP port.
.async_run(asio::detached); // Start the client.
@ -54,6 +54,6 @@ int main() {
ioc.run();
}
//]
#endif
//]

10
example/receiver.cpp
View File

@ -15,10 +15,10 @@
namespace asio = boost::asio;
asio::awaitable<void> client_receiver(asio::io_context& ioc) {
// Initialise the ``__Client__``, establish connection to the Broker over TCP.
// Initialise the Client, establish connection to the Broker over TCP.
async_mqtt5::mqtt_client<asio::ip::tcp::socket> client(ioc, "");
// Configure the``__Client__``.
// Configure the Client.
// It is mandatory to call brokers() and async_run() to configure the Brokers to connect to and start the Client.
client.brokers("mqtt.broker", 1883) // Broker that we want to connect to. 1883 is the default TCP port.
.async_run(asio::detached); // Start the client.
@ -44,7 +44,7 @@ asio::awaitable<void> client_receiver(asio::io_context& ioc) {
// Before attempting to receive an Application Message from the Topic we just subscribed to,
// it is advisable to verify that the subscription succeeded.
// It is not recommended to call mqtt_client::async_receive if you do not have any
// Subscription established as the corresponding handler will never be invoked.
// subscription established as the corresponding handler will never be invoked.
if (!sub_codes[0])
auto [topic, payload, publish_props] = co_await client.async_receive(asio::use_awaitable);
// Receive more messages...
@ -79,6 +79,6 @@ int main() {
ioc.run();
}
//]
#endif
//]