boostorg/mqtt5
1
0
Fork 1
mirror of https://github.com/boostorg/mqtt5.git synced 2025-07-29 12:07:43 +02:00
Code Issues Packages Projects Releases Wiki Activity

Simplify document generation and replace Async.MQTT5 with Boost.MQTT5 in docs

Browse Source 
Summary:
related to T15996

- docs are now buildable with b2 (in a very simplified way) like mysql docs
- change Async.MQTT5 -> Boost.MQTT5, async_mqtt5 namespace to boost::mqtt5 namespace

- once changes are approved, Ill update all tabs to 4 spaces in .qbk files

Reviewers: ivica

Reviewed By: ivica

Subscribers: iljazovic, miljen

Differential Revision: https://repo.mireo.local/D33373
This commit is contained in:
Korina Šimičević
2025-01-24 13:25:16 +01:00
parent 9a0d41b7a7
commit b42014f379
48 changed files with 1399 additions and 3320 deletions
Download Patch File Download Diff File Expand all files Collapse all files

200
doc/Jamfile
View File

@ -5,146 +5,92 @@
# (See accompanying file LICENSE or copy at http://www.boost.org/LICENSE_1_0.txt) # (See accompanying file LICENSE or copy at http://www.boost.org/LICENSE_1_0.txt)
# #
project async_mqtt5/doc ; project mqtt5/doc ;
import os ;
local BOOST_ROOT = [ os.environ DevRoot ] ;
using boostbook
: $(BOOST_ROOT)3rdParty/boost-doc/boostbook/docbook-xsl-1.79.1
: $(BOOST_ROOT)3rdParty/boost-doc/boostbook/docbook-dtd-4.2
: $(BOOST_ROOT)3rdParty/boost-doc/boostbook
;
using xsltproc ;
using doxygen ;
# we shall use os.platform to correctly map quickbook executable
# echo [ os.platform ] ;
if [ os.name ] = MACOSX
{
using quickbook : $(BOOST_ROOT)build/macos-arm64-release/bin/quickbook ;
}
else if [ os.name ] = LINUX
{
using quickbook : $(BOOST_ROOT)build/linux-native-x64-release/bin/quickbook ;
}
import boostbook ; import boostbook ;
import os ;
import path ;
import-search /boost/docca ;
import docca ;
make xml/index.xml local include-prefix = [ path.root $(__file__:D) [ path.pwd ] ] ;
: include-prefix = [ path.native $(include-prefix:D)/include ] ;
reference.dox
# additional dependencies local doxygen_include =
../include/async_mqtt5/error.hpp error.hpp
../include/async_mqtt5/logger.hpp logger.hpp
../include/async_mqtt5/reason_codes.hpp reason_codes.hpp
../include/async_mqtt5/types.hpp types.hpp
../include/async_mqtt5/mqtt_client.hpp mqtt_client.hpp
: ;
@call-doxygen
;
# combine.xslt is generated after using doxygen but bjam is unaware of it docca.pyreference reference.qbk
make xml/combine.xslt :
: [ glob-tree-ex ../include/boost/mqtt5 : $(doxygen_include) : detail impl ]
xml/index.xml :
: <doxygen:param>PROJECT_NAME=MQTT5
@null-action <doxygen:param>PROJECT_BRIEF="C++ MQTT5 Client Library"
; <doxygen:param>DISTRIBUTE_GROUP_DOC=YES
<doxygen:param>ENABLE_PREPROCESSING=YES
<doxygen:param>MACRO_EXPANSION=YES
<doxygen:param>EXPAND_ONLY_PREDEF=YES
<doxygen:param>SEARCH_INCLUDES=NO
<doxygen:param>STRIP_FROM_PATH=$(include-prefix)
make xml/all.xml <doxygen:param>SKIP_FUNCTION_MACROS=NO
: <doxygen:param>OUTPUT_LANGUAGE=English
xml/combine.xslt <doxygen:param>ABBREVIATE_BRIEF=
xml/index.xml <doxygen:param>AUTOLINK_SUPPORT=NO
: <doxygen:param>EXTRACT_ALL=YES
@call-xsltproc <doxygen:param>HIDE_UNDOC_MEMBERS=YES
; <doxygen:param>HIDE_UNDOC_CLASSES=YES
<doxygen:param>HIDE_FRIEND_COMPOUNDS=YES
<doxygen:param>CASE_SENSE_NAMES=YES
<doxygen:param>SHOW_INCLUDE_FILES=NO
<doxygen:param>INLINE_INFO=NO
<doxygen:param>SORT_MEMBER_DOCS=NO
<doxygen:param>SORT_MEMBERS_CTORS_1ST=YES
<doxygen:param>SHOW_USED_FILES=NO
<doxygen:param>SHOW_FILES=NO
<doxygen:param>SHOW_NAMESPACES=NO
make reference.qbk <docca:config>config.json
: ;
reference.xsl
xml/all.xml
:
@call-xsltproc
;
# We have to make a copy of reference.qbk and put it
# in a place where the static .qbk files can find it
install qbk/reference : reference.qbk ;
actions null-action
{
# the action is used with "make" rule to make bjam aware that a file exists
}
actions call-doxygen
{
doxygen $(2)
}
actions call-xsltproc
{
xsltproc $(2) > $(1)
}
install stylesheets
:
$(BOOST_ROOT)3rdParty/boost-doc/style/boostbook.css
:
<location>html/
;
explicit stylesheets ;
install callouts
:
[ glob $(BOOST_ROOT)3rdParty/boost-doc/style/images/callouts/*.png ]
:
<location>html/images/callouts
;
explicit callout ;
install images install images
: :
[ glob $(BOOST_ROOT)3rdParty/boost-doc/style/images/*.png ] [ glob images/*.png ]
: :
<location>html/images <location>html/mqtt5/images
; ;
explicit images ; explicit images ;
xml async_mqtt5_doc xml mqtt5_doc
: :
qbk/00_main.qbk qbk/00_main.qbk
: :
<dependency>reference.qbk <dependency>reference.qbk
<dependency>images <dependency>images
; ;
explicit async_mqtt5_doc ; explicit mqtt5_doc ;
boostbook async_mqtt5
: boostbook mqtt5
async_mqtt5_doc :
: mqtt5_doc
<xsl:param>"boost.root=https://www.boost.org/doc/libs/1_82_0" :
<xsl:param>boost.graphics.root=images/ <xsl:param>boost.root=../../../..
<xsl:param>nav.layout=none <xsl:param>chapter.autolabel=1
<xsl:param>chapter.autolabel=1 <xsl:param>chunk.section.depth=8
<xsl:param>chunk.section.depth=8 <xsl:param>chunk.first.sections=1
<xsl:param>chunk.first.sections=1 <xsl:param>toc.max.depth=2
<xsl:param>toc.max.depth=2 <xsl:param>generate.toc="chapter toc,title section nop reference nop part toc"
<xsl:param>generate.toc="chapter toc,title section nop reference nop part toc" <include>../../../tools/boostbook/dtd
<xsl:param>html.stylesheet=boostbook.css :
: <dependency>images
<dependency>stylesheets ;
<dependency>images
;
# These are used to inform the build system of the # These are used to inform the build system of the
# means to build the integrated and stand-alone docs. # means to build the integrated and stand-alone docs.
@ -152,5 +98,5 @@ boostbook async_mqtt5
alias boostdoc ; alias boostdoc ;
explicit boostdoc ; explicit boostdoc ;
alias boostrelease : async_mqtt5 ; alias boostrelease : mqtt5 ;
explicit boostrelease ; explicit boostrelease ;

17
doc/config.json Normal file
View File

@ -0,0 +1,17 @@
{
"include_private": false,
"legacy_behavior": false,
"external_marker": "!EXTERNAL!",
"link_prefix": "mqtt5.ref.",
"convenience_header": "boost/mqtt5.hpp",
"replace_strings": {
"__see_below__": "``['see-below]``",
"\\btypename CompletionToken\\b": "typename __CompletionToken__",
"\\btypename Executor\\b": "typename __Executor__",
"\\btypename ExecutionContext\\b": "typename __ExecutionContext__",
"\\btypename TlsContext\\b": "typename __TlsContext__",
"\\btypename StreamType\\b": "typename __StreamType__",
"\\bis_authenticator\\b": "__is_authenticator__",
"\\btypename LoggerType\\b": "typename __LoggerType__"
}
}

85
doc/qbk/00_main.qbk
View File

@ -7,7 +7,7 @@
[library Boost.MQTT5: a C++17 MQTT client [library Boost.MQTT5: a C++17 MQTT client
[quickbook 1.7] [quickbook 1.7]
[copyright 2023-2024 Mireo] [copyright 2023-2024 Mireo]
[id async_mqtt5] [id mqtt5]
[purpose C++17 MQTT client] [purpose C++17 MQTT client]
[license [license
Distributed under the Boost Software License, Version 1.0. Distributed under the Boost Software License, Version 1.0.
@ -22,13 +22,14 @@
[template nochunk[] [block '''<?dbhtml stop-chunking?>''']] [template nochunk[] [block '''<?dbhtml stop-chunking?>''']]
[template mdash[] '''&mdash; '''] [template mdash[] '''&mdash; ''']
[template hr[] '''<phrase role="silver">'''[mdash]'''</phrase>'''] [template hr[] '''<phrase role="silver">'''[mdash]'''</phrase>''']
[template include_file[path][^<'''<ulink url="GITHUB_LINK">'''[path]'''</ulink>'''>]] [template link_to_file[path][^'''<ulink url="https://github.com/mireo/async_mqtt5/blob/master/'''[path]'''">'''[path]'''</ulink>''']]
[template include_file[path][^<'''<ulink url="https://github.com/mireo/async_mqtt5/blob/master/include/'''[path]'''">'''[path]'''</ulink>'''>]]
[template indexterm1[term1] '''<indexterm><primary>'''[term1]'''</primary></indexterm>'''] [template indexterm1[term1] '''<indexterm><primary>'''[term1]'''</primary></indexterm>''']
[template indexterm2[term1 term2] '''<indexterm><primary>'''[term1]'''</primary><secondary>'''[term2]'''</secondary></indexterm>'''] [template indexterm2[term1 term2] '''<indexterm><primary>'''[term1]'''</primary><secondary>'''[term2]'''</secondary></indexterm>''']
[template ghreflink[path text] [@https://github.com/mireo/async-mqtt5/blob/master/[path] [text]]] [template ghreflink[path text] [@https://github.com/mireo/async-mqtt5/blob/master/[path] [text]]]
[template reflink2[id text][link async_mqtt5.ref.[id] [^[text]]]] [template reflink2[id text][link mqtt5.ref.boost__mqtt5__[id] [^[text]]]]
[template reflink[id][reflink2 [id] [id]]] [template reflink[id text][link mqtt5.ref.[id] [text]]]
[template refmem[class mem][reflink2 [class].[mem] [class]::[mem]]] [template refmem[class mem][reflink2 [class].[mem] [class]::[mem]]]
[template refmemunq[class mem][reflink2 [class].[mem] [mem]]] [template refmemunq[class mem][reflink2 [class].[mem] [mem]]]
[template asioreflink[id term][@boost:/doc/html/boost_asio/reference/[id].html [^boost::asio::[term]]]] [template asioreflink[id term][@boost:/doc/html/boost_asio/reference/[id].html [^boost::asio::[term]]]]
@ -39,13 +40,13 @@
[def __OPENSSL__ [@https://www.openssl.org/ OpenSSL]] [def __OPENSSL__ [@https://www.openssl.org/ OpenSSL]]
[def __HIVEMQ__ [@https://www.hivemq.com/ HiveMQ]] [def __HIVEMQ__ [@https://www.hivemq.com/ HiveMQ]]
[def __CompletionToken__ [@boost:/doc/html/boost_asio/reference/asynchronous_operations.html#boost_asio.reference.asynchronous_operations.completion_tokens_and_handlers CompletionToken]] [def __CompletionToken__ [@boost:/doc/html/boost_asio/reference/asynchronous_operations.html#boost_asio.reference.asynchronous_operations.completion_tokens_and_handlers ['CompletionToken]]]
[def __Executor__ [@boost:/doc/html/boost_asio/reference/Executor1.html Executor]] [def __Executor__ [@boost:/doc/html/boost_asio/reference/Executor1.html ['Executor]]]
[def __ExecutionContext__ [reflink ExecutionContext]] [def __ExecutionContext__ [reflink ExecutionContext ['ExecutionContext]]]
[def __StreamType__ [reflink StreamType]] [def __StreamType__ [reflink StreamType ['StreamType]]]
[def __TlsContext__ [reflink TlsContext]] [def __TlsContext__ [reflink TlsContext ['TlsContext]]]
[def __is_authenticator__ [reflink is_authenticator]] [def __is_authenticator__ [reflink is_authenticator ['is_authenticator]]]
[def __LoggerType__ [reflink LoggerType]] [def __LoggerType__ [reflink LoggerType ['LoggerType]]]
[def __Boost__ [@https://www.boost.org/ Boost]] [def __Boost__ [@https://www.boost.org/ Boost]]
[def __Asio__ [@boost:/libs/asio/index.html Boost.Asio]] [def __Asio__ [@boost:/libs/asio/index.html Boost.Asio]]
@ -60,7 +61,7 @@
[def __STRAND__ [@boost:doc/html/boost_asio/reference/io_context__strand.html `boost::asio::io_context::strand`]] [def __STRAND__ [@boost:doc/html/boost_asio/reference/io_context__strand.html `boost::asio::io_context::strand`]]
[def __DISPATCH__ [@boost:doc/html/boost_asio/reference/dispatch.html `boost::asio::dispatch`]] [def __DISPATCH__ [@boost:doc/html/boost_asio/reference/dispatch.html `boost::asio::dispatch`]]
[def __POST__ [@boost:doc/html/boost_asio/reference/post.html `boost::asio::post`]] [def __POST__ [@boost:doc/html/boost_asio/reference/post.html `boost::asio::post`]]
[def __ASYNC_IMMEDIATE__ [@https://www.boost.org/doc/libs/1_86_0/doc/html/boost_asio/reference/async_immediate.html `boost::asio::async_immediate`]] [def __ASYNC_IMMEDIATE__ [@boost:doc/html/boost_asio/reference/async_immediate.html `boost::asio::async_immediate`]]
[def __CO_SPAWN__ [@boost:/doc/html/boost_asio/reference/co_spawn.html `boost::asio::co_spawn`]] [def __CO_SPAWN__ [@boost:/doc/html/boost_asio/reference/co_spawn.html `boost::asio::co_spawn`]]
[def __USE_AWAITABLE__ [@boost:/doc/html/boost_asio/reference/use_awaitable.html `boost::asio::use_awaitable`]] [def __USE_AWAITABLE__ [@boost:/doc/html/boost_asio/reference/use_awaitable.html `boost::asio::use_awaitable`]]
[def __USE_FUTURE__ [@boost:/doc/html/boost_asio/reference/use_future.html `boost::asio::use_future`]] [def __USE_FUTURE__ [@boost:/doc/html/boost_asio/reference/use_future.html `boost::asio::use_future`]]
@ -86,6 +87,7 @@
[def __RETAIN__ [mqttlink 3901104 `RETAIN`]] [def __RETAIN__ [mqttlink 3901104 `RETAIN`]]
[def __SUBSCRIBE_OPTIONS__ [mqttlink 3901169 `Subscribe Options`]] [def __SUBSCRIBE_OPTIONS__ [mqttlink 3901169 `Subscribe Options`]]
[def __ENHANCED_AUTH__ [mqttlink 3901256 `Enhanced Authentication`]] [def __ENHANCED_AUTH__ [mqttlink 3901256 `Enhanced Authentication`]]
[def __RE_AUTHENTICATION__ [mqttlink 3901257 `Re-authentication`]]
[def __TOPIC_SEMANTIC_AND_USAGE__ [mqttlink 3901247 `Topic semantic and usage`]] [def __TOPIC_SEMANTIC_AND_USAGE__ [mqttlink 3901247 `Topic semantic and usage`]]
[def __CONNECT__ [mqttlink 3901033 `CONNECT`]] [def __CONNECT__ [mqttlink 3901033 `CONNECT`]]
@ -104,29 +106,29 @@
[def __DISCONNECT__ [mqttlink 3901205 `DISCONNECT`]] [def __DISCONNECT__ [mqttlink 3901205 `DISCONNECT`]]
[def __AUTH__ [mqttlink 3901217 `AUTH`]] [def __AUTH__ [mqttlink 3901217 `AUTH`]]
[def __WILL_PROPS__ [reflink2 will_props async_mqtt5::will_props]] [def __WILL_PROPS__ [reflink will_props `boost::mqtt5::will_props`]]
[def __CONNECT_PROPS__ [reflink2 connect_props async_mqtt5::connect_props]] [def __CONNECT_PROPS__ [reflink connect_props `boost::mqtt5::connect_props`]]
[def __CONNACK_PROPS__ [reflink2 connack_props async_mqtt5::connack_props]] [def __CONNACK_PROPS__ [reflink connack_props `boost::mqtt5::connack_props`]]
[def __PUBLISH_PROPS__ [reflink2 publish_props async_mqtt5::publish_props]] [def __PUBLISH_PROPS__ [reflink publish_props `boost::mqtt5::publish_props`]]
[def __PUBACK_PROPS__ [reflink2 puback_props async_mqtt5::puback_props]] [def __PUBACK_PROPS__ [reflink puback_props `boost::mqtt5::puback_props`]]
[def __PUBREC_PROPS__ [reflink2 pubrec_props async_mqtt5::pubrec_props]] [def __PUBREC_PROPS__ [reflink pubrec_props `boost::mqtt5::pubrec_props`]]
[def __PUBREL_PROPS__ [reflink2 pubrel_props async_mqtt5::pubrel_props]] [def __PUBREL_PROPS__ [reflink pubrel_props `boost::mqtt5::pubrel_props`]]
[def __PUBCOMP_PROPS__ [reflink2 pubcomp_props async_mqtt5::pubcomp_props]] [def __PUBCOMP_PROPS__ [reflink pubcomp_props `boost::mqtt5::pubcomp_props`]]
[def __SUBSCRIBE_PROPS__ [reflink2 subscribe_props async_mqtt5::subscribe_props]] [def __SUBSCRIBE_PROPS__ [reflink subscribe_props `boost::mqtt5::subscribe_props`]]
[def __SUBACK_PROPS__ [reflink2 suback_props async_mqtt5::suback_props]] [def __SUBACK_PROPS__ [reflink suback_props `boost::mqtt5::suback_props`]]
[def __UNSUBSCRIBE_PROPS__ [reflink2 unsubscribe_props async_mqtt5::unsubscribe_props]] [def __UNSUBSCRIBE_PROPS__ [reflink unsubscribe_props `boost::mqtt5::unsubscribe_props`]]
[def __UNSUBACK_PROPS__ [reflink2 unsuback_props async_mqtt5::unsuback_props]] [def __UNSUBACK_PROPS__ [reflink unsuback_props `boost::mqtt5::unsuback_props`]]
[def __DISCONNECT_PROPS__ [reflink2 disconnect_props async_mqtt5::disconnect_props]] [def __DISCONNECT_PROPS__ [reflink disconnect_props `boost::mqtt5::disconnect_props`]]
[def __AUTH_PROPS__ [reflink2 auth_props async_mqtt5::auth_props]] [def __AUTH_PROPS__ [reflink auth_props `boost::mqtt5::auth_props`]]
[def __KEEP_ALIVE__ [mqttlink 3901045 `Keep Alive`]] [def __KEEP_ALIVE__ [mqttlink 3901045 `Keep Alive`]]
[def __SERVER_KEEP_ALIVE__ [mqttlink 3901094 `Server Keep Alive`]] [def __SERVER_KEEP_ALIVE__ [mqttlink 3901094 `Server Keep Alive`]]
[def __ERROR_CODE__ [reflink2 error_code `async_mqtt5::error_code`]] [def __ERROR_CODE__ [reflink2 error_code `boost::mqtt5::error_code`]]
[def __REASON_CODE__ [reflink2 reason_code `async_mqtt5::reason_code`]] [def __REASON_CODE__ [reflink2 reason_code `boost::mqtt5::reason_code`]]
[def __REASON_CODES__ [reflink2 Reason_codes `Reason Codes`]] [def __REASON_CODES__ [reflink Reason_codes `Reason Codes`]]
[def __ERROR_HANDLING__ [reflink2 Error_handling `Error handling`]] [def __ERROR_HANDLING__ [reflink Error_handling `Error handling`]]
[import ../../example/hello_world_over_tcp.cpp] [import ../../example/hello_world_over_tcp.cpp]
[import ../../example/hello_world_over_tls.cpp] [import ../../example/hello_world_over_tls.cpp]
@ -155,6 +157,27 @@
[section:ref Reference] [section:ref Reference]
[xinclude reference/quickref.xml] [xinclude reference/quickref.xml]
[block'''<part label="Two: Reference">'''] [block'''<part label="Two: Reference">''']
[include reference/reference.qbk] [include reference.qbk]
[include reference/Error_handling.qbk]
[include reference/concepts/ExecutionContext.qbk]
[include reference/concepts/StreamType.qbk]
[include reference/concepts/TlsContext.qbk]
[include reference/concepts/is_authenticator.qbk]
[include reference/concepts/LoggerType.qbk]
[include reference/reason_codes/Reason_codes.qbk]
[include reference/properties/will_props.qbk]
[include reference/properties/connect_props.qbk]
[include reference/properties/connack_props.qbk]
[include reference/properties/publish_props.qbk]
[include reference/properties/puback_props.qbk]
[include reference/properties/pubrec_props.qbk]
[include reference/properties/pubrel_props.qbk]
[include reference/properties/pubcomp_props.qbk]
[include reference/properties/subscribe_props.qbk]
[include reference/properties/suback_props.qbk]
[include reference/properties/unsubscribe_props.qbk]
[include reference/properties/unsuback_props.qbk]
[include reference/properties/disconnect_props.qbk]
[include reference/properties/auth_props.qbk]
[block'''</part>'''] [block'''</part>''']
[endsect] [endsect]

258
doc/qbk/01_intro.qbk
View File

@ -20,29 +20,29 @@ primarily due to the challenging implementation of message retransmission after
To address these challenges and simplify MQTT integration once and for all, __Self__ was designed with the following core objectives in mind: To address these challenges and simplify MQTT integration once and for all, __Self__ was designed with the following core objectives in mind:
[table:objectives Core objectives [table:objectives Core objectives
[[Objective] [Description]] [[Objective] [Description]]
[ [
["Plug and play" interface that abstracts away MQTT protocol internals, low-level network events, message retransmission and other complexities] ["Plug and play" interface that abstracts away MQTT protocol internals, low-level network events, message retransmission and other complexities]
[ [
Enables developers to publish or receive messages with just a single line of code, significantly reducing the learning curve and development time. Enables developers to publish or receive messages with just a single line of code, significantly reducing the learning curve and development time.
Getting started requires basic MQTT knowledge, making the library accessible to developers of all skill levels. Getting started requires basic MQTT knowledge, making the library accessible to developers of all skill levels.
] ]
] ]
[ [
[Highly reliable and robust Client that handles network losses, unreliable data transport, network latencies, and other unpredictable events] [Highly reliable and robust Client that handles network losses, unreliable data transport, network latencies, and other unpredictable events]
[ [
The Client does not expose connect functions (nor asynchronous connect functions); instead, network connectivity, MQTT handshake, and message retransmission are automatically The Client does not expose connect functions (nor asynchronous connect functions); instead, network connectivity, MQTT handshake, and message retransmission are automatically
handled within the Client while strictly adhering to the MQTT specification. handled within the Client while strictly adhering to the MQTT specification.
This automation eliminates the need for developers to write extensive and error-prone code to handle these scenarios, allowing them to focus on the application's core functionality. This automation eliminates the need for developers to write extensive and error-prone code to handle these scenarios, allowing them to focus on the application's core functionality.
] ]
] ]
[ [
[Complete adherence to the Boost.Asio's universal asynchronous model] [Complete adherence to the Boost.Asio's universal asynchronous model]
[ [
The interfaces and implementation strategies are built upon the foundations of Boost.Asio. The interfaces and implementation strategies are built upon the foundations of Boost.Asio.
This compatibility enables seamless integration with any other library within the Boost.Asio ecosystem. This compatibility enables seamless integration with any other library within the Boost.Asio ecosystem.
] ]
] ]
] ]
[heading When to Use] [heading When to Use]
@ -64,88 +64,88 @@ __Self__ is a library designed with the core belief that users should focus sole
The library attempts to embody this belief with a range of key features designed to elevate the development experience: The library attempts to embody this belief with a range of key features designed to elevate the development experience:
[table:features Features [table:features Features
[[Feature] [Description]] [[Feature] [Description]]
[ [
[[*Complete TCP, TLS/SSL, and WebSocket support]] [[*Complete TCP, TLS/SSL, and WebSocket support]]
[ [
The MQTT protocol requires an underlying network protocol that provides ordered, lossless, bi-directional connection (stream). The MQTT protocol requires an underlying network protocol that provides ordered, lossless, bi-directional connection (stream).
Users can customize this stream through a template parameter. Users can customize this stream through a template parameter.
The Boost.MQTT5 library has been tested with the most used transport protocols: The Boost.MQTT5 library has been tested with the most used transport protocols:
TCP/IP using `boost::asio::ip::tcp::socket`, TLS/SSL using `boost::asio::ssl::stream`, WebSocket/TCP and WebSocket/TLS using `boost::beast::websocket::stream`). TCP/IP using `boost::asio::ip::tcp::socket`, TLS/SSL using `boost::asio::ssl::stream`, WebSocket/TCP and WebSocket/TLS using `boost::beast::websocket::stream`).
] ]
] ]
[ [
[[*Automatic reconnect and retry mechanism]] [[*Automatic reconnect and retry mechanism]]
[ [
Automatically handles connection loss, backoffs, reconnections, and message transmissions. Automatically handles connection loss, backoffs, reconnections, and message transmissions.
Automating these processes enables users to focus entirely on the application's functionality. Automating these processes enables users to focus entirely on the application's functionality.
See [link async_mqtt5.auto_reconnect Built-in Auto-Reconnect and Retry Mechanism]. See [link mqtt5.auto_reconnect Built-in Auto-Reconnect and Retry Mechanism].
] ]
] ]
[ [
[[*Prioritised efficiency]] [[*Prioritised efficiency]]
[Utilises network and memory resources as efficiently as possible.] [Utilises network and memory resources as efficiently as possible.]
] ]
[ [
[[*Minimal memory footprint]] [[*Minimal memory footprint]]
[Ensures optimal performance in resource-constrained environments typical of IoT devices.] [Ensures optimal performance in resource-constrained environments typical of IoT devices.]
] ]
[ [
[[*Completion token]] [[*Completion token]]
[ [
All asynchronous functions are implemented using Boost.Asio's universal asynchronous model and support CompletionToken. All asynchronous functions are implemented using Boost.Asio's universal asynchronous model and support CompletionToken.
This allows versatile usage with callbacks, coroutines, and futures. This allows versatile usage with callbacks, coroutines, and futures.
] ]
] ]
[ [
[[*Custom allocators]] [[*Custom allocators]]
[ [
Support for custom allocators allows extra flexibility and control over the memory resources. Support for custom allocators allows extra flexibility and control over the memory resources.
Boost.MQTT5 will use allocators associated with handlers from asynchronous functions to create instances of objects needed in the library implementation. Boost.MQTT5 will use allocators associated with handlers from asynchronous functions to create instances of objects needed in the library implementation.
] ]
] ]
[ [
[[*Per-operation cancellation]] [[*Per-operation cancellation]]
[ [
All asynchronous operations support individual, targeted cancellation as per Asio's __ASIO_PER_OP_CANCELLATION__. All asynchronous operations support individual, targeted cancellation as per Asio's __ASIO_PER_OP_CANCELLATION__.
This enables all asynchronous functions to be used in [@boost:/doc/html/boost_asio/overview/composition/parallel_group.html Parallel Operations], This enables all asynchronous functions to be used in [@boost:/doc/html/boost_asio/overview/composition/parallel_group.html Parallel Operations],
which is especially beneficial for executing operations that require a timeout mechanism. which is especially beneficial for executing operations that require a timeout mechanism.
] ]
] ]
[ [
[[*Full implementation of MQTT 5.0 specification]] [[*Full implementation of MQTT 5.0 specification]]
[ [
Ensures full compatibility with [@https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html MQTT 5.0 standard]. Ensures full compatibility with [@https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html MQTT 5.0 standard].
This latest version introduces essential features that enhance system robustness, including advanced error-handling mechanisms, This latest version introduces essential features that enhance system robustness, including advanced error-handling mechanisms,
session and message expiry, and other improvements designed to support modern IoT use cases. session and message expiry, and other improvements designed to support modern IoT use cases.
] ]
] ]
[ [
[[*Support for QoS 0, QoS 1, and QoS 2]] [[*Support for QoS 0, QoS 1, and QoS 2]]
[Fully implements all quality-of-service levels defined by the MQTT protocol to match different reliability needs in message delivery.] [Fully implements all quality-of-service levels defined by the MQTT protocol to match different reliability needs in message delivery.]
] ]
[ [
[[*Custom authentication]] [[*Custom authentication]]
[ [
Defines an interface for your custom authenticators to perform __ENHANCED_AUTH__. Defines an interface for your custom authenticators to perform __ENHANCED_AUTH__.
In addition to username/password authentication, this customization point enables the implementation of any authentication mechanism supported by the SASL protocol, In addition to username/password authentication, this customization point enables the implementation of any authentication mechanism supported by the SASL protocol,
offering flexibility for advanced security requirements. offering flexibility for advanced security requirements.
] ]
] ]
[ [
[[*High availability]] [[*High availability]]
[ [
Supports listing multiple Brokers within the same cluster to which the Client can connect. Supports listing multiple Brokers within the same cluster to which the Client can connect.
In the event of a connection failure with one Broker, the Client switches to the next in the list. In the event of a connection failure with one Broker, the Client switches to the next in the list.
] ]
] ]
[ [
[[*Offline buffering]] [[*Offline buffering]]
[ [
Automatically buffers all requests made while offline, ensuring they are sent when the connection is re-established. Automatically buffers all requests made while offline, ensuring they are sent when the connection is re-established.
This allows users to call any asynchronous function freely, regardless of current connection status. This allows users to call any asynchronous function freely, regardless of current connection status.
] ]
] ]
] ]
[heading Getting Started] [heading Getting Started]
@ -170,44 +170,44 @@ __Self__ has been tested with the following compilers:
You can compile the example below with the following command line on Linux: You can compile the example below with the following command line on Linux:
clang++ -std=c++17 <source-cpp-file> -o example -I<path-to-boost> -Iinclude -pthread clang++ -std=c++17 <source-cpp-file> -o example -I<path-to-boost> -Iinclude -pthread
[heading Example] [heading Example]
The following example illustrates a scenario of configuring a Client and publishing a The following example illustrates a scenario of configuring a Client and publishing a
"Hello World!" Application Message with `QoS` 0. "Hello World!" Application Message with `QoS` 0.
[!c++] [!c++]
#include <boost/mqtt5/mqtt_client.hpp> #include <boost/mqtt5/mqtt_client.hpp>
#include <boost/mqtt5/types.hpp> #include <boost/mqtt5/types.hpp>
#include <boost/asio/io_context.hpp> #include <boost/asio/io_context.hpp>
#include <boost/asio/detached.hpp> #include <boost/asio/detached.hpp>
#include <boost/asio/ip/tcp.hpp> #include <boost/asio/ip/tcp.hpp>
#include <iostream> #include <iostream>
int main() { int main() {
boost::asio::io_context ioc; boost::asio::io_context ioc;
boost::mqtt5::mqtt_client<boost::asio::ip::tcp::socket> c(ioc); boost::mqtt5::mqtt_client<boost::asio::ip::tcp::socket> c(ioc);
c.brokers("<your-mqtt-broker>", 1883) c.brokers("<your-mqtt-broker>", 1883)
.credentials("<your-client-id>", "<client-username>", "<client-pwd>") .credentials("<your-client-id>", "<client-username>", "<client-pwd>")
.async_run(boost::asio::detached); .async_run(boost::asio::detached);
c.async_publish<boost::mqtt5::qos_e::at_most_once>( c.async_publish<boost::mqtt5::qos_e::at_most_once>(
"<topic>", "Hello world!", "<topic>", "Hello world!",
boost::mqtt5::retain_e::no, boost::mqtt5::publish_props {}, boost::mqtt5::retain_e::no, boost::mqtt5::publish_props {},
[&c](boost::mqtt5::error_code ec) { [&c](boost::mqtt5::error_code ec) {
std::cout << ec.message() << std::endl; std::cout << ec.message() << std::endl;
c.async_disconnect(boost::asio::detached); // disconnect and close the Client c.async_disconnect(boost::asio::detached); // disconnect and close the Client
} }
); );
ioc.run(); ioc.run();
} }
To see more examples, visit [link async_mqtt5.examples Examples]. To see more examples, visit [link mqtt5.examples Examples].
[heading Acknowledgements] [heading Acknowledgements]
We thank [@https://github.com/chriskohlhoff Christopher Kohlhoff] for his outstanding __Asio__ library, We thank [@https://github.com/chriskohlhoff Christopher Kohlhoff] for his outstanding __Asio__ library,

20
doc/qbk/02_getting_started.qbk
View File

@ -31,11 +31,11 @@ which might be required for establishing a secure connection.
In this example, we choose TCP/IP as the underlying protocol to initialize the __Client__. In this example, we choose TCP/IP as the underlying protocol to initialize the __Client__.
[!c++] [!c++]
// Initialize the execution context required to run I/O operations. // Initialize the execution context required to run I/O operations.
boost::asio::io_context ioc; boost::asio::io_context ioc;
// Construct the Client with ``__TCP_SOCKET__`` as the underlying stream. // Construct the Client with ``__TCP_SOCKET__`` as the underlying stream.
async_mqtt5::mqtt_client<boost::asio::ip::tcp::socket> client(ioc); boost::mqtt5::mqtt_client<boost::asio::ip::tcp::socket> client(ioc);
[endsect] [/transport_protocol] [endsect] [/transport_protocol]
@ -90,7 +90,7 @@ If this connection attempt is unsuccessful, it proceeds to the next Broker in or
Upon reaching the end of the list without a successful connection, the __Client__ enters a backoff period before making another round of attempts with the entire list. Upon reaching the end of the list without a successful connection, the __Client__ enters a backoff period before making another round of attempts with the entire list.
The duration of this backoff period in milliseconds is determined by the formula: The duration of this backoff period in milliseconds is determined by the formula:
2^(min(retry_count, 4)) * 1000 + jitter 2^(min(retry_count, 4)) * 1000 + jitter
In this formula, `retry_count` represents the number of complete cycles through the list without a successful connection, In this formula, `retry_count` represents the number of complete cycles through the list without a successful connection,
and `jitter` is a randomly chosen value between `-500ms` to `500ms`, intended to prevent synchronised reconnection attempts in scenarios with multiple clients. and `jitter` is a randomly chosen value between `-500ms` to `500ms`, intended to prevent synchronised reconnection attempts in scenarios with multiple clients.
@ -106,13 +106,13 @@ In this case, we will publish a "Hello World!" message to `async-mqtt5/test` top
You can find the full program listing for this chapter at the link below: You can find the full program listing for this chapter at the link below:
* [link async_mqtt5.hello_world_over_tcp hello_world_over_tcp.cpp] * [link mqtt5.hello_world_over_tcp hello_world_over_tcp.cpp]
Additional "Hello World!" examples for different underlying transport protocols can be found here: Additional "Hello World!" examples for different underlying transport protocols can be found here:
* [link async_mqtt5.hello_world_over_tls hello_world_over_tls.cpp] * [link mqtt5.hello_world_over_tls hello_world_over_tls.cpp]
* [link async_mqtt5.hello_world_over_websocket_tcp hello_world_over_websocket_tcp.cpp] * [link mqtt5.hello_world_over_websocket_tcp hello_world_over_websocket_tcp.cpp]
* [link async_mqtt5.hello_world_over_websocket_tls hello_world_over_websocket_tls.cpp] * [link mqtt5.hello_world_over_websocket_tls hello_world_over_websocket_tls.cpp]
[endsect] [/using_the_client] [endsect] [/using_the_client]
@ -121,7 +121,7 @@ Additional "Hello World!" examples for different underlying transport protocols
If you encounter configuration or connection issues, you can use our logging mechanism to debug problems. If you encounter configuration or connection issues, you can use our logging mechanism to debug problems.
The __Client__ introduces a __LoggerType__ as its third template parameter, which specifies the type used for logging events within the __Client__. The __Client__ introduces a __LoggerType__ as its third template parameter, which specifies the type used for logging events within the __Client__.
The __Self__ library provides a built-in [ghreflink include/async_mqtt5/logger.hpp logger] implementation that outputs operation results to stderr. The __Self__ library provides a built-in [ghreflink include/boost/mqtt5/logger.hpp logger] implementation that outputs operation results to stderr.
This logger outputs detailed information about each step in the connection process, including DNS resolution, TCP connection, TLS handshake, WebSocket handshake, and MQTT handshake. This logger outputs detailed information about each step in the connection process, including DNS resolution, TCP connection, TLS handshake, WebSocket handshake, and MQTT handshake.
To enable this functionality, construct the __Client__ with an instance of this logger class: To enable this functionality, construct the __Client__ with an instance of this logger class:

48
doc/qbk/03_auto_reconnect.qbk
View File

@ -24,30 +24,30 @@ Note that the same principle applies to all other asynchronous functions within
(see /Completion condition/ under [refmem mqtt_client async_publish], [refmem mqtt_client async_subscribe], [refmem mqtt_client async_unsubscribe], (see /Completion condition/ under [refmem mqtt_client async_publish], [refmem mqtt_client async_subscribe], [refmem mqtt_client async_unsubscribe],
and [refmem mqtt_client async_disconnect]). and [refmem mqtt_client async_disconnect]).
// Publishing with QoS 1 involves a two-step process: sending a PUBLISH message to the Broker and awaiting a PUBACK (acknowledgement) response. // Publishing with QoS 1 involves a two-step process: sending a PUBLISH message to the Broker and awaiting a PUBACK (acknowledgement) response.
// The scenarios that might happen are: // The scenarios that might happen are:
// 1) The Client will immediately send the PUBLISH message and start to wait for the PUBACK reply. // 1) The Client will immediately send the PUBLISH message and start to wait for the PUBACK reply.
// The user's completion handler will not be invoked yet, regardless of whether the Client successfully sent the message. // The user's completion handler will not be invoked yet, regardless of whether the Client successfully sent the message.
// 2) When the Client fails to send the message, it will try to reconnect to the Broker automatically. // 2) When the Client fails to send the message, it will try to reconnect to the Broker automatically.
// If it succeeds, it will resend the message. If reconnect fails, the Client will try to connect again until it succeeds. // If it succeeds, it will resend the message. If reconnect fails, the Client will try to connect again until it succeeds.
// Meanwhile, the user's completion handler will NOT be invoked except when the Client detects an unrecoverable error (for example, when the list of configured brokers is empty). // Meanwhile, the user's completion handler will NOT be invoked except when the Client detects an unrecoverable error (for example, when the list of configured brokers is empty).
// Note that the Client will try to connect indefinitely, meaning the user's completion handler may never be invoked. // Note that the Client will try to connect indefinitely, meaning the user's completion handler may never be invoked.
// 3) When the Client successfully sends the PUBLISH message, the Broker is required to respond with a PUBACK message. // 3) When the Client successfully sends the PUBLISH message, the Broker is required to respond with a PUBACK message.
// The reply message may indicate success or an MQTT error (for example, signalling that the message is not accepted due to implementation or administrative limits). // The reply message may indicate success or an MQTT error (for example, signalling that the message is not accepted due to implementation or administrative limits).
// The Client will read the PUBACK message and call the user's completion handler with the appropriate arguments. // The Client will read the PUBACK message and call the user's completion handler with the appropriate arguments.
// 4) The PUBACK message should arrive within 20 seconds of the PUBLISH message being successfully sent. // 4) The PUBACK message should arrive within 20 seconds of the PUBLISH message being successfully sent.
// If it does not, the PUBLISH message will be sent again. In the meantime, the user's callback will not be invoked. // If it does not, the PUBLISH message will be sent again. In the meantime, the user's callback will not be invoked.
client.async_publish<async_mqtt5::qos_e::at_least_once>( client.async_publish<boost::mqtt5::qos_e::at_least_once>(
"my-topic", "Hello world!", "my-topic", "Hello world!",
async_mqtt5::retain_e::no, async_mqtt5::publish_props {}, boost::mqtt5::retain_e::no, boost::mqtt5::publish_props {},
[](async_mqtt5::error_code ec, async_mqtt5::reason_code rc, async_mqtt5::puback_props props) { [](boost::mqtt5::error_code ec, boost::mqtt5::reason_code rc, boost::mqtt5::puback_props props) {
// This callback is invoked under any of the following circumstances: // This callback is invoked under any of the following circumstances:
// a) The Client successfully sends the PUBLISH packet and receives a PUBACK from the Broker. // a) The Client successfully sends the PUBLISH packet and receives a PUBACK from the Broker.
// b) The Client encounters a non-recoverable error, such as a cancellation or providing invalid parameters // b) The Client encounters a non-recoverable error, such as a cancellation or providing invalid parameters
// to async_publish, which prevents the message from being sent. // to async_publish, which prevents the message from being sent.
} }
); );
[section:sentry ] [section:sentry ]
@ -94,7 +94,7 @@ If the decision for reconnection were left to the user, then the user would need
which would dramatically increase the complexity of the user's code, not to mention how difficult it would be to cover all possible error states. which would dramatically increase the complexity of the user's code, not to mention how difficult it would be to cover all possible error states.
The proposed approach for detecting configuration errors in the __Client__ is to use our logging mechanism as described The proposed approach for detecting configuration errors in the __Client__ is to use our logging mechanism as described
in [link async_mqtt5.getting_started.debugging Debugging the Client] in [link mqtt5.getting_started.debugging Debugging the Client]
[heading Increased Resource Consumption] [heading Increased Resource Consumption]

8
doc/qbk/04_maintaining_a_stable_connection.qbk
View File

@ -33,9 +33,9 @@ Use [refmem mqtt_client keep_alive] function during the __Client__ configuration
Otherwise, the __Client__ defaults to a `Keep Alive` period of `60 seconds`. Otherwise, the __Client__ defaults to a `Keep Alive` period of `60 seconds`.
[note [note
The MQTT protocol does not use the TCP's built-in keep-alive mechanism as it is inflexible and limited in that it can be configured solely at the operating system level. The MQTT protocol does not use the TCP's built-in keep-alive mechanism as it is inflexible and limited in that it can be configured solely at the operating system level.
The default time a connection must be idle before sending the first keep-alive packet is typically set to 2 hours, The default time a connection must be idle before sending the first keep-alive packet is typically set to 2 hours,
exceeding the tolerances of most MQTT applications. exceeding the tolerances of most MQTT applications.
] ]
[endsect] [/keep_alive] [endsect] [/keep_alive]
@ -80,7 +80,7 @@ to receive some data
[footnote The __Client__ is not required to specifically receive __PINGRESP__ to its __PINGREQ__. Any data from the Broker will suffice to confirm its status.] [footnote The __Client__ is not required to specifically receive __PINGRESP__ to its __PINGREQ__. Any data from the Broker will suffice to confirm its status.]
from the Broker within `1.5` times the negotiated `Keep Alive` seconds. from the Broker within `1.5` times the negotiated `Keep Alive` seconds.
If no data is received within this time, the __Client__ will assume a half-open state and initiate a reconnect procedure If no data is received within this time, the __Client__ will assume a half-open state and initiate a reconnect procedure
described in the [link async_mqtt5.auto_reconnect Built-in auto-reconnect and retry mechanism]. described in the [link mqtt5.auto_reconnect Built-in auto-reconnect and retry mechanism].
[important If the negotiated `Keep Alive` value is set to `0`, the timeout mechanism to detect a half-open connection [important If the negotiated `Keep Alive` value is set to `0`, the timeout mechanism to detect a half-open connection
is disabled. As a result, the __Client__ loses its capability to identify and adequately respond to half-open scenarios.] is disabled. As a result, the __Client__ loses its capability to identify and adequately respond to half-open scenarios.]

6
doc/qbk/05_optimising_communication.qbk
View File

@ -35,7 +35,7 @@ It is important to note that there is no guarantee that the final handlers will
in the same order as the corresponding `async_xxx` calls were initiated. in the same order as the corresponding `async_xxx` calls were initiated.
[import ../../example/multiflight_client.cpp] [import ../../example/multiflight_client.cpp]
Source: [link async_mqtt5.multiflight_client multiflight_client.cpp] Source: [link mqtt5.multiflight_client multiflight_client.cpp]
[multiflight_client] [multiflight_client]
[endsect] [/multiflight] [endsect] [/multiflight]
@ -56,7 +56,7 @@ __Client__ evaluates the current count of unacknowledged __PUBLISH__ packets aga
If the count is below this threshold, __Client__ dispatches the __PUBLISH__ packet. If the count is below this threshold, __Client__ dispatches the __PUBLISH__ packet.
Otherwise, it remains in the queue until the count decreases below the threshold. Otherwise, it remains in the queue until the count decreases below the threshold.
As a result, in the [link async_mqtt5.multiflight_client multiflight_client.cpp] example, As a result, in the [link mqtt5.multiflight_client multiflight_client.cpp] example,
the __Client__ will transmit all `5` __PUBLISH__ packets in a single TCP packet the __Client__ will transmit all `5` __PUBLISH__ packets in a single TCP packet
if possible [footnote The Broker's `Receive Maximum` is equal to or greater than `5`.]. if possible [footnote The Broker's `Receive Maximum` is equal to or greater than `5`.].
@ -75,7 +75,7 @@ A Broker can set this value to limit the number of simultaneous QoS > 0 messages
potentially causing QoS 0 messages to be transmitted ahead of QoS > 0 messages in the delivery order. potentially causing QoS 0 messages to be transmitted ahead of QoS > 0 messages in the delivery order.
- The __DISCONNECT__ packet is sent *in a single TCP packet before any other packets* in the queue. - The __DISCONNECT__ packet is sent *in a single TCP packet before any other packets* in the queue.
See [link async_mqtt5.disconnecting_the_client Disconnecting the client] for more information about disconnecting. See [link mqtt5.disconnecting_the_client Disconnecting the client] for more information about disconnecting.
[endsect] [/packet_ordering] [endsect] [/packet_ordering]

68
doc/qbk/06_disconnecting_the_client.qbk
View File

@ -38,23 +38,23 @@ followed by the request to disconnect the __Client__.
``` ```
int main() { int main() {
boost::asio::io_context ioc; boost::asio::io_context ioc;
async_mqtt5::mqtt_client<boost::asio::ip::tcp::socket> client(ioc); boost::mqtt5::mqtt_client<boost::asio::ip::tcp::socket> client(ioc);
client.brokers("<your-mqtt-broker>", 1883) client.brokers("<your-mqtt-broker>", 1883)
.async_run(boost::asio::detached); .async_run(boost::asio::detached);
client.async_publish<async_mqtt5::qos_e::at_most_once>( client.async_publish<boost::mqtt5::qos_e::at_most_once>(
"<topic>", "Hello world!", "<topic>", "Hello world!",
async_mqtt5::retain_e::no, async_mqtt5::publish_props {}, boost::mqtt5::retain_e::no, boost::mqtt5::publish_props {},
[](async_mqtt5::error_code ec) { [](boost::mqtt5::error_code ec) {
std::cout << ec.message() << std::endl; std::cout << ec.message() << std::endl;
} }
); );
client.async_disconnect(boost::asio::detached); client.async_disconnect(boost::asio::detached);
ioc.run(); ioc.run();
} }
``` ```
@ -65,7 +65,7 @@ order of events will unfold:
# The Client will send a __DISCONNECT__ packet with Reason Code `0x00` (`Normal Disconnection`). # The Client will send a __DISCONNECT__ packet with Reason Code `0x00` (`Normal Disconnection`).
It is important to note that the __PUBLISH__ packet containing the "Hello World!" message will not be transmitted. It is important to note that the __PUBLISH__ packet containing the "Hello World!" message will not be transmitted.
As outlined in the `Packet Ordering` in [link async_mqtt5.optimising_communication Optimising communication] section, As outlined in the `Packet Ordering` in [link mqtt5.optimising_communication Optimising communication] section,
[refmem mqtt_client async_publish] and [refmem mqtt_client async_disconnect] will place their corresponding [refmem mqtt_client async_publish] and [refmem mqtt_client async_disconnect] will place their corresponding
packets in the queue. However, __DISCONNECT__ packets are prioritised and sent exclusively, ahead of other queued packets. packets in the queue. However, __DISCONNECT__ packets are prioritised and sent exclusively, ahead of other queued packets.
Therefore, the connection will terminate immediately. Therefore, the connection will terminate immediately.
@ -80,14 +80,14 @@ In this case, the proper way to disconnect would be to call [refmem mqtt_client
[refmem mqtt_client async_publish] has been completed. [refmem mqtt_client async_publish] has been completed.
``` ```
client.async_publish<async_mqtt5::qos_e::at_most_once>( client.async_publish<boost::mqtt5::qos_e::at_most_once>(
"<topic>", "Hello world!", "<topic>", "Hello world!",
async_mqtt5::retain_e::no, async_mqtt5::publish_props {}, boost::mqtt5::retain_e::no, boost::mqtt5::publish_props {},
[&client](async_mqtt5::error_code ec) { [&client](boost::mqtt5::error_code ec) {
std::cout << ec.message() << std::endl; std::cout << ec.message() << std::endl;
client.async_disconnect(boost::asio::detached); client.async_disconnect(boost::asio::detached);
} }
); );
``` ```
[section:reusing_the_client Restarting the Client After Disconnection] [section:reusing_the_client Restarting the Client After Disconnection]
@ -96,26 +96,26 @@ Once the __Client__ has been successfully stopped, reactivating it is straightfo
This method can be called right after initiating [refmem mqtt_client async_disconnect], without waiting for it to complete. This method can be called right after initiating [refmem mqtt_client async_disconnect], without waiting for it to complete.
The __Client__ is configurable again in the interval between stopping and restarting. The __Client__ is configurable again in the interval between stopping and restarting.
See [link async_mqtt5.getting_started.configuration Configuring Your MQTT Connection] for more information. See [link mqtt5.getting_started.configuration Configuring Your MQTT Connection] for more information.
``` ```
int main() { int main() {
boost::asio::io_context ioc; boost::asio::io_context ioc;
async_mqtt5::mqtt_client<boost::asio::ip::tcp::socket> client(ioc); boost::mqtt5::mqtt_client<boost::asio::ip::tcp::socket> client(ioc);
client.brokers("<your-mqtt-broker>", 1883) client.brokers("<your-mqtt-broker>", 1883)
.async_run(boost::asio::detached); .async_run(boost::asio::detached);
client.async_disconnect(boost::asio::detached); client.async_disconnect(boost::asio::detached);
// The Client can be reconfigured again. // The Client can be reconfigured again.
client.connect_property(async_mqtt5::prop::session_expiry_interval, 120) client.connect_property(boost::mqtt5::prop::session_expiry_interval, 120)
.keep_alive(30) .keep_alive(30)
.async_run(boost::asio::detached); // Restart the Client again. .async_run(boost::asio::detached); // Restart the Client again.
// Use the Client... // Use the Client...
ioc.run(); ioc.run();
} }
``` ```

6
doc/qbk/07_asio_compliance.qbk
View File

@ -15,11 +15,11 @@ Every asynchronous operation in __Asio__ has associated characteristics that spe
This section expands further into the roles of allocators, This section expands further into the roles of allocators,
cancellation slots, and executors, highlighting their integration and usage within the __Client__. cancellation slots, and executors, highlighting their integration and usage within the __Client__.
* See [link async_mqtt5.asio_compliance.allocators Allocators] for more information about how the * See [link mqtt5.asio_compliance.allocators Allocators] for more information about how the
__Client__ supports and uses associated allocators. __Client__ supports and uses associated allocators.
* See [link async_mqtt5.asio_compliance.per_op_cancellation Per-Operation Cancellation] for more information about how * See [link mqtt5.asio_compliance.per_op_cancellation Per-Operation Cancellation] for more information about how
asynchronous operations within the __Client__ support cancellation. asynchronous operations within the __Client__ support cancellation.
* See [link async_mqtt5.asio_compliance.executors Executors] for more information about executors. * See [link mqtt5.asio_compliance.executors Executors] for more information about executors.
[include 08_allocators.qbk] [include 08_allocators.qbk]
[include 09_per_op_cancellation.qbk] [include 09_per_op_cancellation.qbk]

2
doc/qbk/08_allocators.qbk
View File

@ -18,7 +18,7 @@ to store the state associated with the operation.
Specifically, the allocator is used to reserve memory for MQTT Control Packet bytes Specifically, the allocator is used to reserve memory for MQTT Control Packet bytes
(__PUBLISH__, __SUBSCRIBE__,...) created by each `async_xxx` operation request. (__PUBLISH__, __SUBSCRIBE__,...) created by each `async_xxx` operation request.
Moreover, the __Client__'s internal packet queue Moreover, the __Client__'s internal packet queue
(described in the section ['Efficient bandwidth usage with packet queuing] in [link async_mqtt5.optimising_communication Optimising communication]) (described in the section ['Efficient bandwidth usage with packet queuing] in [link mqtt5.optimising_communication Optimising communication])
associates the allocator of the first packet in the queue to the low-level __Asio__ function associates the allocator of the first packet in the queue to the low-level __Asio__ function
`async_write` on the transport layer. `async_write` on the transport layer.

34
doc/qbk/09_per_op_cancellation.qbk
View File

@ -42,25 +42,25 @@ In such cases, the cancellation would specifically target resending the __PUBLIS
preventing it from being retransmitted should the client reconnect during the ongoing operation. preventing it from being retransmitted should the client reconnect during the ongoing operation.
``` ```
async_mqtt5::mqtt_client<boost::asio::ip::tcp::socket> client(ioc); boost::mqtt5::mqtt_client<boost::asio::ip::tcp::socket> client(ioc);
client.brokers("<your-mqtt-broker>", 1883) client.brokers("<your-mqtt-broker>", 1883)
.async_run(boost::asio::detached); .async_run(boost::asio::detached);
boost::asio::cancellation_signal signal; boost::asio::cancellation_signal signal;
client.async_publish<async_mqtt5::qos_e::at_least_once>( client.async_publish<boost::mqtt5::qos_e::at_least_once>(
"<topic>", "Hello world!", "<topic>", "Hello world!",
async_mqtt5::retain_e::no, async_mqtt5::publish_props {}, boost::mqtt5::retain_e::no, boost::mqtt5::publish_props {},
boost::asio::bind_cancellation_slot( boost::asio::bind_cancellation_slot(
signal.slot(), signal.slot(),
[&client](async_mqtt5::error_code ec, async_mqtt5::reason_code rc, async_mqtt5::puback_props props ) { [&client](boost::mqtt5::error_code ec, boost::mqtt5::reason_code rc, boost::mqtt5::puback_props props ) {
std::cout << ec.message() << std::endl; std::cout << ec.message() << std::endl;
} }
) )
); );
signal.emit(boost::asio::cancellation_type_t::terminal); signal.emit(boost::asio::cancellation_type_t::terminal);
``` ```
[section:parallel_group parallel_group/operator || and asynchronous functions in the mqtt_client] [section:parallel_group parallel_group/operator || and asynchronous functions in the mqtt_client]
@ -70,8 +70,8 @@ This feature is especially beneficial for executing operations that require a ti
Below are two examples illustrating how to implement a timeout: Below are two examples illustrating how to implement a timeout:
* [link async_mqtt5.timeout_with_parallel_group timeout_with_parallel_group.cpp] * [link mqtt5.timeout_with_parallel_group timeout_with_parallel_group.cpp]
* [link async_mqtt5.timeout_with_awaitable_operators timeout_with_awaitable_operators.cpp] * [link mqtt5.timeout_with_awaitable_operators timeout_with_awaitable_operators.cpp]
[endsect] [/parallel_group] [endsect] [/parallel_group]

34
doc/qbk/10_executors.qbk
View File

@ -31,27 +31,27 @@ which is used to execute the [refmem mqtt_client async_publish] operation.
``` ```
int main() { int main() {
boost::asio::io_context ioc; boost::asio::io_context ioc;
// Construct the Client with a strand. // Construct the Client with a strand.
auto strand = boost::asio::make_strand(ioc.get_executor()); auto strand = boost::asio::make_strand(ioc.get_executor());
async_mqtt5::mqtt_client<boost::asio::ip::tcp::socket> client(strand); boost::mqtt5::mqtt_client<boost::asio::ip::tcp::socket> client(strand);
client.brokers("<your-mqtt-broker>", 1883) client.brokers("<your-mqtt-broker>", 1883)
.async_run(boost::asio::detached); .async_run(boost::asio::detached);
// This asynchronous operation will use the default associated executor, // This asynchronous operation will use the default associated executor,
// which is the strand with which the Client is constructed. // which is the strand with which the Client is constructed.
client.async_publish<async_mqtt5::qos_e::at_most_once>( client.async_publish<boost::mqtt5::qos_e::at_most_once>(
"<topic>", "Hello world!", "<topic>", "Hello world!",
async_mqtt5::retain_e::no, async_mqtt5::publish_props {}, boost::mqtt5::retain_e::no, boost::mqtt5::publish_props {},
[&client, &strand](async_mqtt5::error_code /* ec */) { [&client, &strand](boost::mqtt5::error_code /* ec */) {
assert(strand.running_in_this_thread()); assert(strand.running_in_this_thread());
client.cancel(); client.cancel();
} }
); );
ioc.run(); ioc.run();
} }
``` ```

10
doc/qbk/11_multithreading.qbk
View File

@ -74,16 +74,16 @@ This will guarantee that the entire sequence of operations
is carried out within the strand, thereby ensuring thread safety. is carried out within the strand, thereby ensuring thread safety.
[important [important
To conclude, to achieve thread safety, To conclude, to achieve thread safety,
all the member functions of the __Client__ *must* be executed in *the same strand*. all the member functions of the __Client__ *must* be executed in *the same strand*.
This strand must be given in the __Client__ constructor. This strand must be given in the __Client__ constructor.
] ]
The examples below demonstrate how to publish a "Hello World" Application Message The examples below demonstrate how to publish a "Hello World" Application Message
in a multithreaded setting using callbacks (`post`/`dispatch`) and coroutines (`co_spawn`): in a multithreaded setting using callbacks (`post`/`dispatch`) and coroutines (`co_spawn`):
* [link async_mqtt5.hello_world_in_multithreaded_env hello_world_in_multithreaded_env.cpp] * [link mqtt5.hello_world_in_multithreaded_env hello_world_in_multithreaded_env.cpp]
* [link async_mqtt5.hello_world_in_coro_multithreaded_env hello_world_in_coro_multithreaded_env.cpp] * [link mqtt5.hello_world_in_coro_multithreaded_env hello_world_in_coro_multithreaded_env.cpp]
[endsect] [/thread_safe_code] [endsect] [/thread_safe_code]

100
doc/qbk/12_examples.qbk
View File

@ -10,56 +10,56 @@
The following list contains all the examples that showcase how to use the __Client__: The following list contains all the examples that showcase how to use the __Client__:
[variablelist [variablelist
[ [
[[link async_mqtt5.publisher publisher.cpp]] [[link mqtt5.publisher publisher.cpp]]
[Shows how to use the __Client__ as a publisher. The __Client__ publishes sensor readings every `5 seconds`.] [Shows how to use the __Client__ as a publisher. The __Client__ publishes sensor readings every `5 seconds`.]
] ]
[ [
[[link async_mqtt5.receiver receiver.cpp]] [[link mqtt5.receiver receiver.cpp]]
[Shows how to use the __Client__ as a receiver. The __Client__ subscribes and indefinitely receives Application Messages from the Broker.] [Shows how to use the __Client__ as a receiver. The __Client__ subscribes and indefinitely receives Application Messages from the Broker.]
] ]
[ [
[[link async_mqtt5.hello_world_over_tcp hello_world_over_tcp.cpp]] [[link mqtt5.hello_world_over_tcp hello_world_over_tcp.cpp]]
[Publishes a "Hello World" message via TCP/IP.] [Publishes a "Hello World" message via TCP/IP.]
] ]
[ [
[[link async_mqtt5.hello_world_over_tls hello_world_over_tls.cpp]] [[link mqtt5.hello_world_over_tls hello_world_over_tls.cpp]]
[Publishes a "Hello World" message via TLS/SSL.] [Publishes a "Hello World" message via TLS/SSL.]
] ]
[ [
[[link async_mqtt5.hello_world_over_websocket_tcp hello_world_over_websocket_tcp.cpp]] [[link mqtt5.hello_world_over_websocket_tcp hello_world_over_websocket_tcp.cpp]]
[Publishes a "Hello World" message via Websocket/TLS.] [Publishes a "Hello World" message via Websocket/TLS.]
] ]
[ [
[[link async_mqtt5.hello_world_over_websocket_tls hello_world_over_websocket_tls.cpp]] [[link mqtt5.hello_world_over_websocket_tls hello_world_over_websocket_tls.cpp]]
[Publishes a "Hello World" message via Websocket/TLS.] [Publishes a "Hello World" message via Websocket/TLS.]
] ]
[ [
[[link async_mqtt5.multiflight_client multiflight_client.cpp]] [[link mqtt5.multiflight_client multiflight_client.cpp]]
[Shows how to use the __Client__ to simultaneously dispatch multiple requests.] [Shows how to use the __Client__ to simultaneously dispatch multiple requests.]
] ]
[ [
[[link async_mqtt5.timeout_with_parallel_group timeout_with_parallel_group.cpp]] [[link mqtt5.timeout_with_parallel_group timeout_with_parallel_group.cpp]]
[ [
Shows how to use the __Client__ with its support for per-operation cancellation to perform operations under a time constraint Shows how to use the __Client__ with its support for per-operation cancellation to perform operations under a time constraint
using a parallel group. using a parallel group.
] ]
] ]
[ [
[[link async_mqtt5.timeout_with_awaitable_operators timeout_with_awaitable_operators.cpp]] [[link mqtt5.timeout_with_awaitable_operators timeout_with_awaitable_operators.cpp]]
[ [
Shows how to use the __Client__ with its support for per-operation cancellation to perform operations under a time constraint Shows how to use the __Client__ with its support for per-operation cancellation to perform operations under a time constraint
using awaitable operators. using awaitable operators.
] ]
] ]
[ [
[[link async_mqtt5.hello_world_in_multithreaded_env hello_world_in_multithreaded_env.cpp]] [[link mqtt5.hello_world_in_multithreaded_env hello_world_in_multithreaded_env.cpp]]
[Shows how to publish a "Hello World" message in a multithreaded environment using callbacks (`post`/`dispatch`).] [Shows how to publish a "Hello World" message in a multithreaded environment using callbacks (`post`/`dispatch`).]
] ]
[ [
[[link async_mqtt5.hello_world_in_coro_multithreaded_env hello_world_in_coro_multithreaded_env.cpp]] [[link mqtt5.hello_world_in_coro_multithreaded_env hello_world_in_coro_multithreaded_env.cpp]]
[Shows how to publish a "Hello World" message in a multithreaded environment using coroutines (`co_spawn`).] [Shows how to publish a "Hello World" message in a multithreaded environment using coroutines (`co_spawn`).]
] ]
] ]
[endsect][/examples] [endsect][/examples]

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

@ -10,82 +10,82 @@ The table below provides a reference of all __ERROR_CODE__ instances that asynch
may complete with, along with the reasons for their occurrence. may complete with, along with the reasons for their occurrence.
[table:error_codes Error codes [table:error_codes Error codes
[[Error code] [Cause]] [[Error code] [Cause]]
[[`boost::system::errc::errc_t::success`] [The operation completed successfully.]] [[`boost::system::errc::errc_t::success`] [The operation completed successfully.]]
[[`boost::asio::error::opreation_aborted`] [ [[`boost::asio::error::opreation_aborted`] [
The operation has been cancelled. The operation has been cancelled.
The cancellation of the operation can be triggered by invoking either [refmem mqtt_client cancel] The cancellation of the operation can be triggered by invoking either [refmem mqtt_client cancel]
or [refmem mqtt_client async_disconnect]. Furthermore, if a cancellation slot has been associated or [refmem mqtt_client async_disconnect]. Furthermore, if a cancellation slot has been associated
with the __CompletionToken__ provided and the corresponding cancellation signal is emitted, with the __CompletionToken__ provided and the corresponding cancellation signal is emitted,
the operation will also finish with this error code (see __ASIO_PER_OP_CANCELLATION__). the operation will also finish with this error code (see __ASIO_PER_OP_CANCELLATION__).
]] ]]
[[`boost::asio::no_recovery`] [ [[`boost::asio::no_recovery`] [
An non-recoverable error occurred during the attempt by the [reflink2 mqtt_client `mqtt_client`] An non-recoverable error occurred during the attempt by the [reflink2 mqtt_client `mqtt_client`]
to establish a connection with the Server. The cause of this error may be attributed to the connection to establish a connection with the Server. The cause of this error may be attributed to the connection
related parameters used during the initialization of the [reflink2 mqtt_client `mqtt_client`]. related parameters used during the initialization of the [reflink2 mqtt_client `mqtt_client`].
]] ]]
[[`async_mqtt5::client::error::malformed_packet`][ [[`boost::mqtt5::client::error::malformed_packet`][
The Client has attempted to send a packet that does not conform to the specification. The Client has attempted to send a packet that does not conform to the specification.
This issue can arise from improperly formed UTF-8 encoded strings. This issue can arise from improperly formed UTF-8 encoded strings.
Additionally, this error can be caused by providing out-of-range values. Additionally, this error can be caused by providing out-of-range values.
]] ]]
[[`async_mqtt5::client::error::packet_too_large`][ [[`boost::mqtt5::client::error::packet_too_large`][
The Client has attempted to send a packet larger than the Maximum Packet Size the Server The Client has attempted to send a packet larger than the Maximum Packet Size the Server
is willing to process. is willing to process.
]] ]]
[[`async_mqtt5::client::error::session_expired`][ [[`boost::mqtt5::client::error::session_expired`][
The Client has established a successful connection with a Server, but either the session does not exist or has expired. The Client has established a successful connection with a Server, but either the session does not exist or has expired.
In cases where the Client had previously set up subscriptions to Topics, these subscriptions are also expired. In cases where the Client had previously set up subscriptions to Topics, these subscriptions are also expired.
Therefore, the Client should re-subscribe. Therefore, the Client should re-subscribe.
This error code is exclusive to completion handlers associated with [refmem mqtt_client async_receive] calls. This error code is exclusive to completion handlers associated with [refmem mqtt_client async_receive] calls.
]] ]]
[[`async_mqtt5::client::error::pid_overrun`] [ [[`boost::mqtt5::client::error::pid_overrun`] [
This error code signifies that the Client was unable to allocate a Packet Identifier for This error code signifies that the Client was unable to allocate a Packet Identifier for
the current operation due to the exhaustion of the available identifiers. the current operation due to the exhaustion of the available identifiers.
This occurs when there are 65535 outgoing Packets awaiting their responses. This occurs when there are 65535 outgoing Packets awaiting their responses.
]] ]]
[[`async_mqtt5::client::error::invalid_topic`] [ [[`boost::mqtt5::client::error::invalid_topic`] [
The Client has attempted to perform an action (publish, subscribe or unsubscribe) on an invalid Topic. The Client has attempted to perform an action (publish, subscribe or unsubscribe) on an invalid Topic.
See __TOPIC_SEMANTIC_AND_USAGE__ for information on properly formed Topics. See __TOPIC_SEMANTIC_AND_USAGE__ for information on properly formed Topics.
This error code is exclusive to completion handlers associated with [refmem mqtt_client async_publish], This error code is exclusive to completion handlers associated with [refmem mqtt_client async_publish],
[refmem mqtt_client async_subscribe], and [refmem mqtt_client async_unsubscribe] calls. [refmem mqtt_client async_subscribe], and [refmem mqtt_client async_unsubscribe] calls.
In the case of [refmem mqtt_client async_subscribe] and [refmem mqtt_client async_unsubscribe], this error code In the case of [refmem mqtt_client async_subscribe] and [refmem mqtt_client async_unsubscribe], this error code
occurs if at least one Topic provided is malformed. occurs if at least one Topic provided is malformed.
]] ]]
[[`async_mqtt5::client::error::qos_not_supported`] [ [[`boost::mqtt5::client::error::qos_not_supported`] [
The Client has attempted to publish an Application Message with __QOS__ higher The Client has attempted to publish an Application Message with __QOS__ higher
than the Maximum __QOS__ specified by the Server. than the Maximum __QOS__ specified by the Server.
The Server does not support this __QOS__ (see __MAXIMUM_QOS__). The Server does not support this __QOS__ (see __MAXIMUM_QOS__).
This error code is exclusive to completion handlers associated with [refmem mqtt_client async_publish] calls. This error code is exclusive to completion handlers associated with [refmem mqtt_client async_publish] calls.
]] ]]
[[`async_mqtt5::client::error::retain_not_available`] [ [[`boost::mqtt5::client::error::retain_not_available`] [
The Client has attempted to publish an Application Message with the __RETAIN__ flag set to 1. The Client has attempted to publish an Application Message with the __RETAIN__ flag set to 1.
However, the Server does not support retained messages (see __RETAIN_AVAILABLE__). However, the Server does not support retained messages (see __RETAIN_AVAILABLE__).
This error code is exclusive to completion handlers associated with [refmem mqtt_client async_publish] calls. This error code is exclusive to completion handlers associated with [refmem mqtt_client async_publish] calls.
]] ]]
[[`async_mqtt5::client::error::topic_alias_maximum`] [ [[`boost::mqtt5::client::error::topic_alias_maximum`] [
The Client has attempted to publish an Application Message with the Topic Alias The Client has attempted to publish an Application Message with the Topic Alias
exceeding the Server's supported Topic Alias Maximum. Additionally, this error code exceeding the Server's supported Topic Alias Maximum. Additionally, this error code
will arise in instances when the Server does NOT support Topic Aliases, and the will arise in instances when the Server does NOT support Topic Aliases, and the
Client has attempted to use them. See __TOPIC_ALIAS_MAX__. Client has attempted to use them. See __TOPIC_ALIAS_MAX__.
This error code is exclusive to completion handlers associated with [refmem mqtt_client async_publish] calls. This error code is exclusive to completion handlers associated with [refmem mqtt_client async_publish] calls.
]] ]]
[[`async_mqtt5::client::error::wildcard_subscription_not_available`] [ [[`boost::mqtt5::client::error::wildcard_subscription_not_available`] [
The Client has attempted to subscribe to multiple Topics using Wildcard Character (`+` and/or `#`). The Client has attempted to subscribe to multiple Topics using Wildcard Character (`+` and/or `#`).
However, the Server does not support Wildcard Subscriptions. However, the Server does not support Wildcard Subscriptions.
This error code is exclusive to completion handlers associated with [refmem mqtt_client async_subscribe] calls. This error code is exclusive to completion handlers associated with [refmem mqtt_client async_subscribe] calls.
]] ]]
[[`async_mqtt5::client::error::subscription_identifier_not_available`] [ [[`boost::mqtt5::client::error::subscription_identifier_not_available`] [
The Client has attempted to associate a subscription with a Subscription Identifier. The Client has attempted to associate a subscription with a Subscription Identifier.
However, the Server either does not support Subscription Identifiers or the Subscription Identifier provided However, the Server either does not support Subscription Identifiers or the Subscription Identifier provided
is out of range (the Subscription Identifier can have a value of 1 to 268,435,455). is out of range (the Subscription Identifier can have a value of 1 to 268,435,455).
This error code is exclusive to completion handlers associated with [refmem mqtt_client async_subscribe] calls. This error code is exclusive to completion handlers associated with [refmem mqtt_client async_subscribe] calls.
]] ]]
[[`async_mqtt5::client::error::shared_subscription_not_available`] [ [[`boost::mqtt5::client::error::shared_subscription_not_available`] [
The Client has attempted to establish a Shared Subscription. The Client has attempted to establish a Shared Subscription.
However, the Server does not support Shared Subscriptions. However, the Server does not support Shared Subscriptions.
This error code is exclusive to completion handlers associated with [refmem mqtt_client async_subscribe] calls. This error code is exclusive to completion handlers associated with [refmem mqtt_client async_subscribe] calls.
]] ]]
] ]
[endsect] [endsect]

106
doc/qbk/reference/concepts/LoggerType.qbk
View File

@ -11,67 +11,67 @@
A type satisfies the `LoggerType` concept if it defines [*any number (including zero)] of the following functions: A type satisfies the `LoggerType` concept if it defines [*any number (including zero)] of the following functions:
[table:log_functions [table:log_functions
[[Function signature] [Arguments] [Description]] [[Function signature] [Arguments] [Description]]
[ [
[`void at_resolve(error_code ec, std::string_view host, std::string_view port, const asio::ip::tcp::resolver::results_type& eps);`] [`void at_resolve(error_code ec, std::string_view host, std::string_view port, const asio::ip::tcp::resolver::results_type& eps);`]
[ [
[*`ec`] is the `error_code` returned by the resolve operation. [*`ec`] is the `error_code` returned by the resolve operation.
[*`host`] is the hostname used in the resolve. [*`host`] is the hostname used in the resolve.
[*`port`] is the port used in the resolve. [*`port`] is the port used in the resolve.
[*`eps`] is a list of endpoints returned by the resolve operation. [*`eps`] is a list of endpoints returned by the resolve operation.
] ]
[Invoked when the resolve operation is complete.] [Invoked when the resolve operation is complete.]
] ]
[ [
[`void at_tcp_connect(error_code ec, asio::ip::tcp::endpoint ep);`] [`void at_tcp_connect(error_code ec, asio::ip::tcp::endpoint ep);`]
[ [
[*`ec`] is the `error_code` returned by the TCP connect operation. [*`ec`] is the `error_code` returned by the TCP connect operation.
[*`ep`] is a TCP endpoint used to establish the TCP connection. [*`ep`] is a TCP endpoint used to establish the TCP connection.
] ]
[Invoked when the TCP connect operation is complete.] [Invoked when the TCP connect operation is complete.]
] ]
[ [
[`void at_tls_handshake(error_code ec, asio::ip::tcp::endpoint ep);`] [`void at_tls_handshake(error_code ec, asio::ip::tcp::endpoint ep);`]
[ [
[*`ec`] is the `error_code` returned by the the TLS handshake operation. [*`ec`] is the `error_code` returned by the the TLS handshake operation.
[*`ep`] is a TCP endpoint used to establish the TLS handshake. [*`ep`] is a TCP endpoint used to establish the TLS handshake.
] ]
[Invoked when the TLS handshake operation is complete.] [Invoked when the TLS handshake operation is complete.]
] ]
[ [
[`void at_ws_handshake(error_code ec, asio::ip::tcp::endpoint ep);`] [`void at_ws_handshake(error_code ec, asio::ip::tcp::endpoint ep);`]
[ [
[*`ec`] is the `error_code` returned by the the WebSocket handshake operation. [*`ec`] is the `error_code` returned by the the WebSocket handshake operation.
[*`ep`] is a TCP endpoint used to establish the WebSocket handshake. [*`ep`] is a TCP endpoint used to establish the WebSocket handshake.
] ]
[Invoked when the WebSocket handshake operation is complete.] [Invoked when the WebSocket handshake operation is complete.]
] ]
[ [
[`void at_connack(reason_code rc, bool session_present, const connack_props& ca_props);`] [`void at_connack(reason_code rc, bool session_present, const connack_props& ca_props);`]
[ [
[*`rc`] is the `reason_code` received in the __CONNACK__ packet indicating the result of the MQTT handshake. [*`rc`] is the `reason_code` received in the __CONNACK__ packet indicating the result of the MQTT handshake.
[*`session_present`] A flag indicating whether the Broker already has a session associated with this connection. [*`session_present`] A flag indicating whether the Broker already has a session associated with this connection.
[*`ca_props`] __CONNACK_PROPS__ received in the __CONNACK__ packet. [*`ca_props`] __CONNACK_PROPS__ received in the __CONNACK__ packet.
] ]
[Invoked when the __CONNACK__ packet is received, marking the completion of the MQTT handshake. ] [Invoked when the __CONNACK__ packet is received, marking the completion of the MQTT handshake. ]
] ]
[ [
[`void at_disconnect(reason_code rc, const disconnect_props& dc_props);`] [`void at_disconnect(reason_code rc, const disconnect_props& dc_props);`]
[ [
[*`rc`] is the `reason_code` received in the __DISCONNECT__ packet specifying the reason behind the disconnection. [*`rc`] is the `reason_code` received in the __DISCONNECT__ packet specifying the reason behind the disconnection.
[*`dc_props`] __DISCONNECT_PROPS__ received in the __DISCONNECT__ packet. [*`dc_props`] __DISCONNECT_PROPS__ received in the __DISCONNECT__ packet.
] ]
[Invoked when the __DISCONNECT__ packet is received, indicating that the Broker wants to close this connection. ] [Invoked when the __DISCONNECT__ packet is received, indicating that the Broker wants to close this connection. ]
] ]
] ]
For example, a type `T` that defines `at_connack` and `at_disconnect` functions with their respective arguments is considered a valid `LoggerType`. For example, a type `T` that defines `at_connack` and `at_disconnect` functions with their respective arguments is considered a valid `LoggerType`.
@ -82,6 +82,6 @@ If the __Client__ is initialized with an explicit or implicit strand, none of th
[warning Defined functions should not block and stop the __Client__ from doing work. ] [warning Defined functions should not block and stop the __Client__ from doing work. ]
A class that satifies this concept is [ghreflink include/async_mqtt5/logger.hpp logger]. A class that satifies this concept is [ghreflink include/boost/mqtt5/logger.hpp logger].
[endsect] [endsect]

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

@ -9,23 +9,23 @@
A type `Authenticator` satisfies `is_authenticator` concept if it satisifes the requirements listed below. A type `Authenticator` satisfies `is_authenticator` concept if it satisifes the requirements listed below.
[table [table
[[operation] [type] [arguments]] [[operation] [type] [arguments]]
[ [
[```a.async_auth(step, data, h)```] [```a.async_auth(step, data, h)```]
[`void`] [`void`]
[ [
[*`step`] is [reflink2 auth_step_e async_mqtt5::auth_step_e] that specifies current authentication stage. [*`step`] is [reflink2 auth_step_e boost::mqtt5::auth_step_e] that specifies current authentication stage.
[*`data`] is `std::string`, server's authentication data. [*`data`] is `std::string`, server's authentication data.
[*`h`] is [asioreflink any_completion_handler any_completion_handler] with signature `void(__ERROR_CODE__ ec, std::string client_data)`. If `ec` is non-trivial, authentication is aborted. [*`h`] is [asioreflink any_completion_handler any_completion_handler] with signature `void(__ERROR_CODE__ ec, std::string client_data)`. If `ec` is non-trivial, authentication is aborted.
] ]
] ]
[ [
[```a.method()```] [```a.method()```]
[`std::string_view`, authentication method] [`std::string_view`, authentication method]
[] []
] ]
] ]

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

@ -12,45 +12,45 @@ A Property consists of an Identifier and a value.
This section lists all possible __AUTH__ Properties and describes their usage: This section lists all possible __AUTH__ Properties and describes their usage:
[table:auth_props AUTH properties [table:auth_props AUTH properties
[[Identifier] [Value type] [Description]] [[Identifier] [Value type] [Description]]
[[authentication_method] [`std::string`] [A UTF-8 Encoded String containing the name of the authentication method used for extended authentication.]] [[authentication_method] [`std::string`] [A UTF-8 Encoded String containing the name of the authentication method used for extended authentication.]]
[[authentication_data] [`std::string`] [Binary Data containing authentication data. The contents of the data are defined by the authentication method.]] [[authentication_data] [`std::string`] [Binary Data containing authentication data. The contents of the data are defined by the authentication method.]]
[[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]] [[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]]
[[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. [[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet.
This property may be used to provide additional diagnostic or other information. ]] This property may be used to provide additional diagnostic or other information. ]]
] ]
[h4 Usage] [h4 Usage]
After obtaining an instance of `async_mqtt5::auth_props`, the subscript operator can be used to access a Property. After obtaining an instance of `boost::mqtt5::auth_props`, the subscript operator can be used to access a Property.
The Identifiers listed in the table above are available within the `async_mqtt5::prop` namespace for Property access. The Identifiers listed in the table above are available within the `boost::mqtt5::prop` namespace for Property access.
[note When accessing a property value, the subscript operator will return a `std::optional` of the value type for all properties, [note When accessing 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 `std::vector<std::pair<std::string, std::string>>`.] except for `boost::mqtt5::prop::user_property`, where it will return an instance of `std::vector<std::pair<std::string, std::string>>`.]
[h4 Example] [h4 Example]
The following example shows how to set a Property value: The following example shows how to set a Property value:
[!c++] [!c++]
async_mqtt5::auth_props props; boost::mqtt5::auth_props props;
props[async_mqtt5::prop::authentication_method] = "SCRAM-SHA-1"; props[boost::mqtt5::prop::authentication_method] = "SCRAM-SHA-1";
props[async_mqtt5::prop::authentication_data] = "data"; props[boost::mqtt5::prop::authentication_data] = "data";
props[async_mqtt5::prop::user_property].emplace_back("name", "value"); props[boost::mqtt5::prop::user_property].emplace_back("name", "value");
The following example shows how to retrieve a Property value: The following example shows how to retrieve a Property value:
[!c++] [!c++]
std::optional<std::string> auth_data = props[async_mqtt5::prop::authentication_data]; std::optional<std::string> auth_data = props[boost::mqtt5::prop::authentication_data];
if (auth_data.has_value()) if (auth_data.has_value())
// authentication data property was previously set // authentication data property was previously set
else else
// authentication data property was not set // authentication data property was not set
std::vector<std::pair<std::string, std::string>>& user_props = props[async_mqtt5::prop::user_property]; std::vector<std::pair<std::string, std::string>>& user_props = props[boost::mqtt5::prop::user_property];
if (!user_props.empty()) if (!user_props.empty())
// user property was previously set // user property was previously set
else else
// user property was not set // user property was not set
[endsect] [endsect]

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

@ -12,61 +12,61 @@ A Property consists of an Identifier and a value.
This section lists all possible __CONNACK__ Properties and describes their usage: This section lists all possible __CONNACK__ Properties and describes their usage:
[table:connack_props CONNACK properties [table:connack_props CONNACK properties
[[Identifier] [Value type] [Description]] [[Identifier] [Value type] [Description]]
[[session_expiry_interval] [`uint32_t`] [Represents the Session Expiry Internal in seconds.]] [[session_expiry_interval] [`uint32_t`] [Represents the Session Expiry Internal in seconds.]]
[[receive_maximum] [`uint16_t`] [The maximum number of QoS 1 and QoS 2 publications that the Server is willing to process concurrently.]] [[receive_maximum] [`uint16_t`] [The maximum number of QoS 1 and QoS 2 publications that the Server is willing to process concurrently.]]
[[maximum_qos] [`uint8_t`] [The highest QoS the Server supports.]] [[maximum_qos] [`uint8_t`] [The highest QoS the Server supports.]]
[[retain_available] [`uint8_t`] [A value of 0 means that retained message are not supported. A value of 1 means they are supported.]] [[retain_available] [`uint8_t`] [A value of 0 means that retained message are not supported. A value of 1 means they are supported.]]
[[maximum_packet_size] [`uint32_t`] [The maximum __PACKET_SIZE__ in bytes as defined by the specification that the Server is willing to accept.]] [[maximum_packet_size] [`uint32_t`] [The maximum __PACKET_SIZE__ in bytes as defined by the specification that the Server is willing to accept.]]
[[assigned_client_identifier] [`std::string`] [The Client Identifier which was assigned by the Server because a zero length Client Identifier was found in the __CONNECT__ packet]] [[assigned_client_identifier] [`std::string`] [The Client Identifier which was assigned by the Server because a zero length Client Identifier was found in the __CONNECT__ packet]]
[[topic_alias_maximum] [`uint16_t`] [The highest value that the Server will accept as a Topic Alias sent by the Client.]] [[topic_alias_maximum] [`uint16_t`] [The highest value that the Server will accept as a Topic Alias sent by the Client.]]
[[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]] [[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]]
[[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. [[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet.
The meaning of these properties is not defined by the specification.]] The meaning of these properties is not defined by the specification.]]
[[wildcard_subscription_available] [`uint8_t`] [A value of 0 means that Wildcard Subscriptions are not supported. [[wildcard_subscription_available] [`uint8_t`] [A value of 0 means that Wildcard Subscriptions are not supported.
A value of 1 means they are supported. If not present, they are supported.]] A value of 1 means they are supported. If not present, they are supported.]]
[[subscription_identifier_available] [`uint8_t`] [A value of 0 means that Subscriptions Identifiers are not supported. [[subscription_identifier_available] [`uint8_t`] [A value of 0 means that Subscriptions Identifiers are not supported.
A value of 1 means they are supported. If not present, they are supported.]] A value of 1 means they are supported. If not present, they are supported.]]
[[shared_subscription_available] [`uint8_t`] [A value of 0 means that Shared Subscriptions are not supported. [[shared_subscription_available] [`uint8_t`] [A value of 0 means that Shared Subscriptions are not supported.
A value of 1 means they are supported. If not present, they are supported.]] A value of 1 means they are supported. If not present, they are supported.]]
[[server_keep_alive] [`uint16_t`] [The Keep Alive time assigned by the Server.]] [[server_keep_alive] [`uint16_t`] [The Keep Alive time assigned by the Server.]]
[[response_information] [`std::string`] [A UTF-8 Encoded String which is used as the basis for creating a Response Topic.]] [[response_information] [`std::string`] [A UTF-8 Encoded String which is used as the basis for creating a Response Topic.]]
[[server_reference] [`std::string`] [A UTF-8 Encoded String which can be used by the Client to identfy another Server to use.]] [[server_reference] [`std::string`] [A UTF-8 Encoded String which can be used by the Client to identfy another Server to use.]]
[[authentication_method] [`std::string`] [A UTF-8 Encoded String containing the name of the authentication method used for extended authentication.]] [[authentication_method] [`std::string`] [A UTF-8 Encoded String containing the name of the authentication method used for extended authentication.]]
[[authentication_data] [`std::string`] [Binary Data containing authentication data. The contents of the data are defined by the authentication method.]] [[authentication_data] [`std::string`] [Binary Data containing authentication data. The contents of the data are defined by the authentication method.]]
] ]
[h4 Usage] [h4 Usage]
After obtaining an instance of `async_mqtt5::connack_props`, the subscript operator can be used to access a Property. After obtaining an instance of `boost::mqtt5::connack_props`, the subscript operator can be used to access a Property.
The Identifiers listed in the table above are available within the `async_mqtt5::prop` namespace for Property access. The Identifiers listed in the table above are available within the `boost::mqtt5::prop` namespace for Property access.
[note When accessing a property value, the subscript operator will return a `std::optional` of the value type for all properties, [note When accessing 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 `std::vector<std::pair<std::string, std::string>>`.] except for `boost::mqtt5::prop::user_property`, where it will return an instance of `std::vector<std::pair<std::string, std::string>>`.]
[h4 Example] [h4 Example]
The following example shows how to set a Property value: The following example shows how to set a Property value:
[!c++] [!c++]
async_mqtt5::connack_props props; boost::mqtt5::connack_props props;
props[async_mqtt5::prop::maximum_packet_size] = 65535; props[boost::mqtt5::prop::maximum_packet_size] = 65535;
props[async_mqtt5::prop::assigned_client_identifier] = "ClientID"; props[boost::mqtt5::prop::assigned_client_identifier] = "ClientID";
props[async_mqtt5::prop::user_property].emplace_back("name", "value"); props[boost::mqtt5::prop::user_property].emplace_back("name", "value");
The following example shows how to retrieve a Property value: The following example shows how to retrieve a Property value:
[!c++] [!c++]
std::optional<std::string> auth_method = props[async_mqtt5::prop::authentication_method]; std::optional<std::string> auth_method = props[boost::mqtt5::prop::authentication_method];
if (auth_method.has_value()) if (auth_method.has_value())
// authentication method property was previously set // authentication method property was previously set
else else
// authentication method property was not set // authentication method property was not set
std::vector<std::pair<std::string, std::string>>& user_props = props[async_mqtt5::prop::user_property]; std::vector<std::pair<std::string, std::string>>& user_props = props[boost::mqtt5::prop::user_property];
if (!user_props.empty()) if (!user_props.empty())
// user property was previously set // user property was previously set
else else
// user property was not set // user property was not set
[endsect] [endsect]

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

@ -12,52 +12,52 @@ A Property consists of an Identifier and a value.
This section lists all possible __CONNECT__ Properties and describes their usage: This section lists all possible __CONNECT__ Properties and describes their usage:
[table:connect_props CONNECT properties [table:connect_props CONNECT properties
[[Identifier] [Value type] [Description]] [[Identifier] [Value type] [Description]]
[[session_expiry_interval] [`uint32_t`] [Represents the Session Expiry Internal in seconds.]] [[session_expiry_interval] [`uint32_t`] [Represents the Session Expiry Internal in seconds.]]
[[receive_maximum] [`uint16_t`] [The maximum number of QoS 1 and QoS 2 publications that the Client is willing to process concurrently.]] [[receive_maximum] [`uint16_t`] [The maximum number of QoS 1 and QoS 2 publications that the Client is willing to process concurrently.]]
[[maximum_packet_size] [`uint32_t`] [The maximum __PACKET_SIZE__ in bytes as defined by the specification that the Client is willing to process.]] [[maximum_packet_size] [`uint32_t`] [The maximum __PACKET_SIZE__ in bytes as defined by the specification that the Client is willing to process.]]
[[topic_alias_maximum] [`uint16_t`] [The highest value that the Client will accept as a Topic Alias sent by the Server.]] [[topic_alias_maximum] [`uint16_t`] [The highest value that the Client will accept as a Topic Alias sent by the Server.]]
[[request_response_information] [`uint8_t`] [The value of 0 signals that the Server MUST NOT return Response Information in __CONNACK__. If the value if 1, it MAY return it.]] [[request_response_information] [`uint8_t`] [The value of 0 signals that the Server MUST NOT return Response Information in __CONNACK__. If the value if 1, it MAY return it.]]
[[request_problem_information] [`uint8_t`] [The value of 0 signals that the Server MAY return a Reason String or User Properties on a __CONNACK__ or __DISCONNECT__ packet, [[request_problem_information] [`uint8_t`] [The value of 0 signals that the Server MAY return a Reason String or User Properties on a __CONNACK__ or __DISCONNECT__ packet,
but MUST NOT send them on any packet other than __PUBLISH__, __CONNACK__, or __DISCONNECT__. but MUST NOT send them on any packet other than __PUBLISH__, __CONNACK__, or __DISCONNECT__.
If the value is 1, the Server MAY return a Reason String or User Properties where it is allowed.]] If the value is 1, the Server MAY return a Reason String or User Properties where it is allowed.]]
[[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. [[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet.
The meaning of these properties is not defined by the specification.]] The meaning of these properties is not defined by the specification.]]
[[authentication_method] [`std::string`] [A UTF-8 Encoded String containing the name of the authentication method used for extended authentication.]] [[authentication_method] [`std::string`] [A UTF-8 Encoded String containing the name of the authentication method used for extended authentication.]]
[[authentication_data] [`std::string`] [Binary Data containing authentication data. The contents of the data are defined by the authentication method.]] [[authentication_data] [`std::string`] [Binary Data containing authentication data. The contents of the data are defined by the authentication method.]]
] ]
[h4 Usage] [h4 Usage]
After obtaining an instance of `async_mqtt5::connect_props`, the subscript operator can be used to access a Property. After obtaining an instance of `boost::mqtt5::connect_props`, the subscript operator can be used to access a Property.
The Identifiers listed in the table above are available within the `async_mqtt5::prop` namespace for Property access. The Identifiers listed in the table above are available within the `boost::mqtt5::prop` namespace for Property access.
[note When accessing a property value, the subscript operator will return a `std::optional` of the value type for all properties, [note When accessing 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 `std::vector<std::pair<std::string, std::string>>`.] except for `boost::mqtt5::prop::user_property`, where it will return an instance of `std::vector<std::pair<std::string, std::string>>`.]
[h4 Example] [h4 Example]
The following example shows how to set a Property value: The following example shows how to set a Property value:
[!c++] [!c++]
async_mqtt5::connect_props props; boost::mqtt5::connect_props props;
props[async_mqtt5::prop::session_expiry_interval] = 1200; props[boost::mqtt5::prop::session_expiry_interval] = 1200;
props[async_mqtt5::prop::receive_maximum] = uint16_t(100); props[boost::mqtt5::prop::receive_maximum] = uint16_t(100);
props[async_mqtt5::prop::user_property].emplace_back("name", "value"); props[boost::mqtt5::prop::user_property].emplace_back("name", "value");
The following example shows how to retrieve a Property value: The following example shows how to retrieve a Property value:
[!c++] [!c++]
std::optional<std::string> auth_method = props[async_mqtt5::prop::authentication_method]; std::optional<std::string> auth_method = props[boost::mqtt5::prop::authentication_method];
if (auth_method.has_value()) if (auth_method.has_value())
// authentication method property was previously set // authentication method property was previously set
else else
// authentication method property was not set // authentication method property was not set
std::vector<std::pair<std::string, std::string>>& user_props = props[async_mqtt5::prop::user_property]; std::vector<std::pair<std::string, std::string>>& user_props = props[boost::mqtt5::prop::user_property];
if (!user_props.empty()) if (!user_props.empty())
// user property was previously set // user property was previously set
else else
// user property was not set // user property was not set
[endsect] [endsect]

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

@ -12,44 +12,44 @@ A Property consists of an Identifier and a value.
This section lists all possible __DISCONNECT__ Properties and describes their usage: This section lists all possible __DISCONNECT__ Properties and describes their usage:
[table:disconnect_props DISCONNECT properties [table:disconnect_props DISCONNECT properties
[[Identifier] [Value type] [Description]] [[Identifier] [Value type] [Description]]
[[session_expiry_interval] [`uint32_t`] [Represents the Session Expiry Internal in seconds. Can only be sent by the Client.]] [[session_expiry_interval] [`uint32_t`] [Represents the Session Expiry Internal in seconds. Can only be sent by the Client.]]
[[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]] [[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]]
[[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. [[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet.
This property may be used to provide additional diagnostic or other information. ]] This property may be used to provide additional diagnostic or other information. ]]
[[server_reference] [`std::string`] [A UTF-8 Encoded String which can be used by the Client to identfy another Server to use.]] [[server_reference] [`std::string`] [A UTF-8 Encoded String which can be used by the Client to identfy another Server to use.]]
] ]
[h4 Usage] [h4 Usage]
After obtaining an instance of `async_mqtt5::disconnect_props`, the subscript operator can be used to access a Property. After obtaining an instance of `boost::mqtt5::disconnect_props`, the subscript operator can be used to access a Property.
The Identifiers listed in the table above are available within the `async_mqtt5::prop` namespace for Property access. The Identifiers listed in the table above are available within the `boost::mqtt5::prop` namespace for Property access.
[note When accessing a property value, the subscript operator will return a `std::optional` of the value type for all properties, [note When accessing 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 `std::vector<std::pair<std::string, std::string>>`.] except for `boost::mqtt5::prop::user_property`, where it will return an instance of `std::vector<std::pair<std::string, std::string>>`.]
[h4 Example] [h4 Example]
The following example shows how to set a Property value: The following example shows how to set a Property value:
[!c++] [!c++]
async_mqtt5::disconnect_props props; boost::mqtt5::disconnect_props props;
props[async_mqtt5::prop::reason_string] = "Lost connection!"; props[boost::mqtt5::prop::reason_string] = "Lost connection!";
props[async_mqtt5::prop::user_property].emplace_back("name", "value"); props[boost::mqtt5::prop::user_property].emplace_back("name", "value");
The following example shows how to retrieve a Property value: The following example shows how to retrieve a Property value:
[!c++] [!c++]
std::optional<std::string> reason_string = props[async_mqtt5::prop::reason_string]; std::optional<std::string> reason_string = props[boost::mqtt5::prop::reason_string];
if (reason_string.has_value()) if (reason_string.has_value())
// reason string property was previously set // reason string property was previously set
else else
// reason string property was not set // reason string property was not set
std::vector<std::pair<std::string, std::string>>& user_props = props[async_mqtt5::prop::user_property]; std::vector<std::pair<std::string, std::string>>& user_props = props[boost::mqtt5::prop::user_property];
if (!user_props.empty()) if (!user_props.empty())
// user property was previously set // user property was previously set
else else
// user property was not set // user property was not set
[endsect] [endsect]

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

@ -12,42 +12,42 @@ A Property consists of an Identifier and a value.
This section lists all possible __PUBACK__ Properties and describes their usage: This section lists all possible __PUBACK__ Properties and describes their usage:
[table:puback_props PUBACK properties [table:puback_props PUBACK properties
[[Identifier] [Value type] [Description]] [[Identifier] [Value type] [Description]]
[[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]] [[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]]
[[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. [[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet.
This property may be used to provide additional diagnostic or other information. ]] This property may be used to provide additional diagnostic or other information. ]]
] ]
[h4 Usage] [h4 Usage]
After obtaining an instance of `async_mqtt5::puback_props`, the subscript operator can be used to access a Property. After obtaining an instance of `boost::mqtt5::puback_props`, the subscript operator can be used to access a Property.
The Identifiers listed in the table above are available within the `async_mqtt5::prop` namespace for Property access. The Identifiers listed in the table above are available within the `boost::mqtt5::prop` namespace for Property access.
[note When accessing a property value, the subscript operator will return a `std::optional` of the value type for all properties, [note When accessing 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 `std::vector<std::pair<std::string, std::string>>`.] except for `boost::mqtt5::prop::user_property`, where it will return an instance of `std::vector<std::pair<std::string, std::string>>`.]
[h4 Example] [h4 Example]
The following example shows how to set a Property value: The following example shows how to set a Property value:
[!c++] [!c++]
async_mqtt5::puback_props props; boost::mqtt5::puback_props props;
props[async_mqtt5::prop::reason_string] = "Some reason..."; props[boost::mqtt5::prop::reason_string] = "Some reason...";
props[async_mqtt5::prop::user_property].emplace_back("name", "value"); props[boost::mqtt5::prop::user_property].emplace_back("name", "value");
The following example shows how to retrieve a Property value: The following example shows how to retrieve a Property value:
[!c++] [!c++]
std::optional<std::string> reason_string = props[async_mqtt5::prop::reason_string]; std::optional<std::string> reason_string = props[boost::mqtt5::prop::reason_string];
if (reason_string.has_value()) if (reason_string.has_value())
// reason string property was previously set // reason string property was previously set
else else
// reason string property was not set // reason string property was not set
std::vector<std::pair<std::string, std::string>>& user_props = props[async_mqtt5::prop::user_property]; std::vector<std::pair<std::string, std::string>>& user_props = props[boost::mqtt5::prop::user_property];
if (!user_props.empty()) if (!user_props.empty())
// user property was previously set // user property was previously set
else else
// user property was not set // user property was not set
[endsect] [endsect]

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

@ -12,42 +12,42 @@ A Property consists of an Identifier and a value.
This section lists all possible __PUBCOMP__ Properties and describes their usage: This section lists all possible __PUBCOMP__ Properties and describes their usage:
[table:pubcomp_props PUBCOMP properties [table:pubcomp_props PUBCOMP properties
[[Identifier] [Value type] [Description]] [[Identifier] [Value type] [Description]]
[[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]] [[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]]
[[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. [[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet.
This property may be used to provide additional diagnostic or other information. ]] This property may be used to provide additional diagnostic or other information. ]]
] ]
[h4 Usage] [h4 Usage]
After obtaining an instance of `async_mqtt5::pubcomp_props`, the subscript operator can be used to access a Property. After obtaining an instance of `boost::mqtt5::pubcomp_props`, the subscript operator can be used to access a Property.
The Identifiers listed in the table above are available within the `async_mqtt5::prop` namespace for Property access. The Identifiers listed in the table above are available within the `boost::mqtt5::prop` namespace for Property access.
[note When accessing a property value, the subscript operator will return a `std::optional` of the value type for all properties, [note When accessing 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 `std::vector<std::pair<std::string, std::string>>`.] except for `boost::mqtt5::prop::user_property`, where it will return an instance of `std::vector<std::pair<std::string, std::string>>`.]
[h4 Example] [h4 Example]
The following example shows how to set a Property value: The following example shows how to set a Property value:
[!c++] [!c++]
async_mqtt5::pubcomp_props props; boost::mqtt5::pubcomp_props props;
props[async_mqtt5::prop::reason_string] = "Some reason..."; props[boost::mqtt5::prop::reason_string] = "Some reason...";
props[async_mqtt5::prop::user_property].emplace_back("name", "value"); props[boost::mqtt5::prop::user_property].emplace_back("name", "value");
The following example shows how to retrieve a Property value: The following example shows how to retrieve a Property value:
[!c++] [!c++]
std::optional<std::string> reason_string = props[async_mqtt5::prop::reason_string]; std::optional<std::string> reason_string = props[boost::mqtt5::prop::reason_string];
if (reason_string.has_value()) if (reason_string.has_value())
// reason string property was previously set // reason string property was previously set
else else
// reason string property was not set // reason string property was not set
std::vector<std::pair<std::string, std::string>>& user_props = props[async_mqtt5::prop::user_property]; std::vector<std::pair<std::string, std::string>>& user_props = props[boost::mqtt5::prop::user_property];
if (!user_props.empty()) if (!user_props.empty())
// user property was previously set // user property was previously set
else else
// user property was not set // user property was not set
[endsect] [endsect]

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

@ -12,52 +12,52 @@ A Property consists of an Identifier and a value.
This section lists all possible __PUBLISH__ Properties and describes their usage: This section lists all possible __PUBLISH__ Properties and describes their usage:
[table:publish_props PUBLISH properties [table:publish_props PUBLISH properties
[[Identifier] [Value type] [Description]] [[Identifier] [Value type] [Description]]
[[payload_format_indicator] [`uint8_t`] [Value of 0 indicates that the Payload is in unspecified bytes. Value of 1 indicates that the Payload is UTF-8 Encoded Character Data.]] [[payload_format_indicator] [`uint8_t`] [Value of 0 indicates that the Payload is in unspecified bytes. Value of 1 indicates that the Payload is UTF-8 Encoded Character Data.]]
[[message_expiry_interval] [`uint32_t`] [The lifetime of the Application Message in seconds.]] [[message_expiry_interval] [`uint32_t`] [The lifetime of the Application Message in seconds.]]
[[topic_alias] [`uint16_t`] [Two Byte integer representing the Topic Alias, an integer value that is used to identify the Topic instead of using the Topic Name.]] [[topic_alias] [`uint16_t`] [Two Byte integer representing the Topic Alias, an integer value that is used to identify the Topic instead of using the Topic Name.]]
[[response_topic] [`std::string`] [A UTF-8 Encoded String which is used as the Topic Name for a response message.]] [[response_topic] [`std::string`] [A UTF-8 Encoded String which is used as the Topic Name for a response message.]]
[[correlation_data] [`std::string`] [Binary Data used by the sender of the Request Message to identify which request the Response Message is for when it is received.]] [[correlation_data] [`std::string`] [Binary Data used by the sender of the Request Message to identify which request the Response Message is for when it is received.]]
[[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. [[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet.
The meaning of these properties is not defined by the specification.]] The meaning of these properties is not defined by the specification.]]
[[subscription_identifier] [`int32_t`] [Identifier of the matching subscription. If there are multiple matching subscriptions, multiple identifiers may be included.]] [[subscription_identifier] [`int32_t`] [Identifier of the matching subscription. If there are multiple matching subscriptions, multiple identifiers may be included.]]
[[content_type] [`std::string`] [A UTF-8 Encoded String describing the content of the Application Message.]] [[content_type] [`std::string`] [A UTF-8 Encoded String describing the content of the Application Message.]]
] ]
[h4 Usage] [h4 Usage]
After obtaining an instance of `async_mqtt5::publish_props`, the subscript operator can be used to access a Property. After obtaining an instance of `boost::mqtt5::publish_props`, the subscript operator can be used to access a Property.
The Identifiers listed in the table above are available within the `async_mqtt5::prop` namespace for Property access. The Identifiers listed in the table above are available within the `boost::mqtt5::prop` namespace for Property access.
[note When accessing a property value, the subscript operator will return a `std::optional` of the value type for all properties, [note When accessing 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` and `async_mqtt5::prop::subscription_identifier`, where it will return an instance of except for `boost::mqtt5::prop::user_property` and `boost::mqtt5::prop::subscription_identifier`, where it will return an instance of
`std::vector<std::pair<std::string, std::string>>` and `async_mqtt5::prop::subscription_identifiers` respectively. `std::vector<std::pair<std::string, std::string>>` and `boost::mqtt5::prop::subscription_identifiers` respectively.
`async_mqtt5::prop::subscription_identifiers` has the interface of `boost::container::small_vector`.] `boost::mqtt5::prop::subscription_identifiers` has the interface of `boost::container::small_vector`.]
[h4 Example] [h4 Example]
The following example shows how to set a Property value: The following example shows how to set a Property value:
[!c++] [!c++]
async_mqtt5::publish_props props; boost::mqtt5::publish_props props;
props[async_mqtt5::prop::payload_format_indicator] = uint8_t(1); props[boost::mqtt5::prop::payload_format_indicator] = uint8_t(1);
props[async_mqtt5::prop::topic_alias] = uint16_t(12); props[boost::mqtt5::prop::topic_alias] = uint16_t(12);
props[async_mqtt5::prop::response_topic] = "response_topic"; props[boost::mqtt5::prop::response_topic] = "response_topic";
props[async_mqtt5::prop::subscription_identifier].push_back(40); props[boost::mqtt5::prop::subscription_identifier].push_back(40);
The following example shows how to retrieve a Property value: The following example shows how to retrieve a Property value:
[!c++] [!c++]
std::optional<uint16_t> topic_alias = props[async_mqtt5::prop::topic_alias]; std::optional<uint16_t> topic_alias = props[boost::mqtt5::prop::topic_alias];
if (topic_alias.has_value()) if (topic_alias.has_value())
// topic alias property was previously set // topic alias property was previously set
else else
// topic alias property was not set // topic alias property was not set
async_mqtt5::prop::subscription_identifiers& sub_ids = props[async_mqtt5::prop::subscription_identifier]; boost::mqtt5::prop::subscription_identifiers& sub_ids = props[boost::mqtt5::prop::subscription_identifier];
if (!sub_ids.empty()) if (!sub_ids.empty())
// subscription identifier property was previously set // subscription identifier property was previously set
else else
// subscription identifier property was not set // subscription identifier property was not set
[endsect] [endsect]

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

@ -12,42 +12,42 @@ A Property consists of an Identifier and a value.
This section lists all possible __PUBREC__ Properties and describes their usage: This section lists all possible __PUBREC__ Properties and describes their usage:
[table:pubrec_props PUBREC properties [table:pubrec_props PUBREC properties
[[Identifier] [Value type] [Description]] [[Identifier] [Value type] [Description]]
[[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]] [[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]]
[[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. [[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet.
This property may be used to provide additional diagnostic or other information. ]] This property may be used to provide additional diagnostic or other information. ]]
] ]
[h4 Usage] [h4 Usage]
After obtaining an instance of `async_mqtt5::pubrec_props`, the subscript operator can be used to access a Property. After obtaining an instance of `boost::mqtt5::pubrec_props`, the subscript operator can be used to access a Property.
The Identifiers listed in the table above are available within the `async_mqtt5::prop` namespace for Property access. The Identifiers listed in the table above are available within the `boost::mqtt5::prop` namespace for Property access.
[note When accessing a property value, the subscript operator will return a `std::optional` of the value type for all properties, [note When accessing 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 `std::vector<std::pair<std::string, std::string>>`.] except for `boost::mqtt5::prop::user_property`, where it will return an instance of `std::vector<std::pair<std::string, std::string>>`.]
[h4 Example] [h4 Example]
The following example shows how to set a Property value: The following example shows how to set a Property value:
[!c++] [!c++]
async_mqtt5::pubrec_props props; boost::mqtt5::pubrec_props props;
props[async_mqtt5::prop::reason_string] = "Some reason..."; props[boost::mqtt5::prop::reason_string] = "Some reason...";
props[async_mqtt5::prop::user_property].emplace_back("name", "value"); props[boost::mqtt5::prop::user_property].emplace_back("name", "value");
The following example shows how to retrieve a Property value: The following example shows how to retrieve a Property value:
[!c++] [!c++]
std::optional<std::string> reason_string = props[async_mqtt5::prop::reason_string]; std::optional<std::string> reason_string = props[boost::mqtt5::prop::reason_string];
if (reason_string.has_value()) if (reason_string.has_value())
// reason string property was previously set // reason string property was previously set
else else
// reason string property was not set // reason string property was not set
std::vector<std::pair<std::string, std::string>>& user_props = props[async_mqtt5::prop::user_property]; std::vector<std::pair<std::string, std::string>>& user_props = props[boost::mqtt5::prop::user_property];
if (!user_props.empty()) if (!user_props.empty())
// user property was previously set // user property was previously set
else else
// user property was not set // user property was not set
[endsect] [endsect]

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

@ -12,41 +12,41 @@ A Property consists of an Identifier and a value.
This section lists all possible __PUBREL__ Properties and describes their usage: This section lists all possible __PUBREL__ Properties and describes their usage:
[table:pubrel_props PUBREL properties [table:pubrel_props PUBREL properties
[[Identifier] [Value type] [Description]] [[Identifier] [Value type] [Description]]
[[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]] [[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]]
[[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. [[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet.
This property may be used to provide additional diagnostic or other information. ]] This property may be used to provide additional diagnostic or other information. ]]
] ]
[h4 Usage] [h4 Usage]
After obtaining an instance of `async_mqtt5::pubrel_props`, the subscript operator can be used to access a Property. After obtaining an instance of `boost::mqtt5::pubrel_props`, the subscript operator can be used to access a Property.
The Identifiers listed in the table above are available within the `async_mqtt5::prop` namespace for Property access. The Identifiers listed in the table above are available within the `boost::mqtt5::prop` namespace for Property access.
[note When accessing a property value, the subscript operator will return a `std::optional` of the value type for all properties, [note When accessing 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 `std::vector<std::pair<std::string, std::string>>`.] except for `boost::mqtt5::prop::user_property`, where it will return an instance of `std::vector<std::pair<std::string, std::string>>`.]
[h4 Example] [h4 Example]
The following example shows how to set a Property value: The following example shows how to set a Property value:
[!c++] [!c++]
async_mqtt5::pubrel_props props; boost::mqtt5::pubrel_props props;
props[async_mqtt5::prop::reason_string] = "Some reason..."; props[boost::mqtt5::prop::reason_string] = "Some reason...";
props[async_mqtt5::prop::user_property].emplace_back("name", "value"); props[boost::mqtt5::prop::user_property].emplace_back("name", "value");
The following example shows how to retrieve a Property value: The following example shows how to retrieve a Property value:
[!c++] [!c++]
std::optional<std::string> reason_string = props[async_mqtt5::prop::reason_string]; std::optional<std::string> reason_string = props[boost::mqtt5::prop::reason_string];
if (reason_string.has_value()) if (reason_string.has_value())
// reason string property was previously set // reason string property was previously set
else else
// reason string property was not set // reason string property was not set
std::vector<std::pair<std::string, std::string>>& user_props = props[async_mqtt5::prop::user_property]; std::vector<std::pair<std::string, std::string>>& user_props = props[boost::mqtt5::prop::user_property];
if (!user_props.empty()) if (!user_props.empty())
// user property was previously set // user property was previously set
else else
// user property was not set // user property was not set
[endsect] [endsect]

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

@ -12,42 +12,42 @@ A Property consists of an Identifier and a value.
This section lists all possible __SUBACK__ Properties and describes their usage: This section lists all possible __SUBACK__ Properties and describes their usage:
[table:suback_props SUBACK properties [table:suback_props SUBACK properties
[[Identifier] [Value type] [Description]] [[Identifier] [Value type] [Description]]
[[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]] [[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]]
[[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. [[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet.
This property may be used to provide additional diagnostic or other information. ]] This property may be used to provide additional diagnostic or other information. ]]
] ]
[h4 Usage] [h4 Usage]
After obtaining an instance of `async_mqtt5::suback_props`, the subscript operator can be used to access a Property. After obtaining an instance of `boost::mqtt5::suback_props`, the subscript operator can be used to access a Property.
The Identifiers listed in the table above are available within the `async_mqtt5::prop` namespace for Property access. The Identifiers listed in the table above are available within the `boost::mqtt5::prop` namespace for Property access.
[note When accessing a property value, the subscript operator will return a `std::optional` of the value type for all properties, [note When accessing 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 `std::vector<std::pair<std::string, std::string>>`.] except for `boost::mqtt5::prop::user_property`, where it will return an instance of `std::vector<std::pair<std::string, std::string>>`.]
[h4 Example] [h4 Example]
The following example shows how to set a Property value: The following example shows how to set a Property value:
[!c++] [!c++]
async_mqtt5::suback_props props; boost::mqtt5::suback_props props;
props[async_mqtt5::prop::reason_string] = "Some reason..."; props[boost::mqtt5::prop::reason_string] = "Some reason...";
props[async_mqtt5::prop::user_property].emplace_back("name", "value"); props[boost::mqtt5::prop::user_property].emplace_back("name", "value");
The following example shows how to retrieve a Property value: The following example shows how to retrieve a Property value:
[!c++] [!c++]
std::optional<std::string> reason_string = props[async_mqtt5::prop::reason_string]; std::optional<std::string> reason_string = props[boost::mqtt5::prop::reason_string];
if (reason_string.has_value()) if (reason_string.has_value())
// reason string property was previously set // reason string property was previously set
else else
// reason string property was not set // reason string property was not set
std::vector<std::pair<std::string, std::string>>& user_props = props[async_mqtt5::prop::user_property]; std::vector<std::pair<std::string, std::string>>& user_props = props[boost::mqtt5::prop::user_property];
if (!user_props.empty()) if (!user_props.empty())
// user property was previously set // user property was previously set
else else
// user property was not set // user property was not set
[endsect] [endsect]

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

@ -12,45 +12,45 @@ A Property consists of an Identifier and a value.
This section lists all possible __SUBSCRIBE__ Properties and describes their usage: This section lists all possible __SUBSCRIBE__ Properties and describes their usage:
[table:subscribe_props SUBSCRIBE properties [table:subscribe_props SUBSCRIBE properties
[[Identifier] [Value type] [Description]] [[Identifier] [Value type] [Description]]
[[subscription_identifier] [`int32_t`] [Identifier of the Subscription in range of 1 to 268,435,455.]] [[subscription_identifier] [`int32_t`] [Identifier of the Subscription in range of 1 to 268,435,455.]]
[[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. [[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet.
This property can be used to send subscription related properties from the Client to the Server. This property can be used to send subscription related properties from the Client to the Server.
The meaning of these properties is not defined by the specification ]] The meaning of these properties is not defined by the specification ]]
] ]
[h4 Usage] [h4 Usage]
After obtaining an instance of `async_mqtt5::subscribe_props`, the subscript operator can be used to access a Property. After obtaining an instance of `boost::mqtt5::subscribe_props`, the subscript operator can be used to access a Property.
The Identifiers listed in the table above are available within the `async_mqtt5::prop` namespace for Property access. The Identifiers listed in the table above are available within the `boost::mqtt5::prop` namespace for Property access.
[note When accessing a property value, the subscript operator will return a `std::optional` of the value type for all properties, [note When accessing 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` and `async_mqtt5::prop::subscription_identifier`, where it will return an instance of except for `boost::mqtt5::prop::user_property` and `boost::mqtt5::prop::subscription_identifier`, where it will return an instance of
`std::vector<std::pair<std::string, std::string>>` and `async_mqtt5::prop::subscription_identifiers` respectively. `std::vector<std::pair<std::string, std::string>>` and `boost::mqtt5::prop::subscription_identifiers` respectively.
`async_mqtt5::prop::subscription_identifiers` has the interface of `std::optional<int32_t>`.] `boost::mqtt5::prop::subscription_identifiers` has the interface of `std::optional<int32_t>`.]
[h4 Example] [h4 Example]
The following example shows how to set a Property value: The following example shows how to set a Property value:
[!c++] [!c++]
async_mqtt5::subscribe_props props; boost::mqtt5::subscribe_props props;
props[async_mqtt5::prop::subscription_identifier] = 1234; props[boost::mqtt5::prop::subscription_identifier] = 1234;
props[async_mqtt5::prop::user_property].emplace_back("name", "value"); props[boost::mqtt5::prop::user_property].emplace_back("name", "value");
The following example shows how to retrieve a Property value: The following example shows how to retrieve a Property value:
[!c++] [!c++]
async_mqtt5::prop::subscription_identifiers sub_id = props[async_mqtt5::prop::subscription_identifier]; boost::mqtt5::prop::subscription_identifiers sub_id = props[boost::mqtt5::prop::subscription_identifier];
if (sub_id.has_value()) if (sub_id.has_value())
// subscription identifier property was previously set // subscription identifier property was previously set
else else
// subscription identifier property was not set // subscription identifier property was not set
std::vector<std::pair<std::string, std::string>>& user_props = props[async_mqtt5::prop::user_property]; std::vector<std::pair<std::string, std::string>>& user_props = props[boost::mqtt5::prop::user_property];
if (!user_props.empty()) if (!user_props.empty())
// user property was previously set // user property was previously set
else else
// user property was not set // user property was not set
[endsect] [endsect]

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

@ -12,42 +12,42 @@ A Property consists of an Identifier and a value.
This section lists all possible __UNSUBACK__ Properties and describes their usage: This section lists all possible __UNSUBACK__ Properties and describes their usage:
[table:unsuback_props UNSUBACK properties [table:unsuback_props UNSUBACK properties
[[Identifier] [Value type] [Description]] [[Identifier] [Value type] [Description]]
[[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]] [[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]]
[[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. [[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet.
This property may be used to provide additional diagnostic or other information. ]] This property may be used to provide additional diagnostic or other information. ]]
] ]
[h4 Usage] [h4 Usage]
After obtaining an instance of `async_mqtt5::unsuback_props`, the subscript operator can be used to access a Property. After obtaining an instance of `boost::mqtt5::unsuback_props`, the subscript operator can be used to access a Property.
The Identifiers listed in the table above are available within the `async_mqtt5::prop` namespace for Property access. The Identifiers listed in the table above are available within the `boost::mqtt5::prop` namespace for Property access.
[note When accessing a property value, the subscript operator will return a `std::optional` of the value type for all properties, [note When accessing 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 `std::vector<std::pair<std::string, std::string>>`.] except for `boost::mqtt5::prop::user_property`, where it will return an instance of `std::vector<std::pair<std::string, std::string>>`.]
[h4 Example] [h4 Example]
The following example shows how to set a Property value: The following example shows how to set a Property value:
[!c++] [!c++]
async_mqtt5::unsuback_props props; boost::mqtt5::unsuback_props props;
props[async_mqtt5::prop::reason_string] = "Some reason..."; props[boost::mqtt5::prop::reason_string] = "Some reason...";
props[async_mqtt5::prop::user_property].emplace_back("name", "value"); props[boost::mqtt5::prop::user_property].emplace_back("name", "value");
The following example shows how to retrieve a Property value: The following example shows how to retrieve a Property value:
[!c++] [!c++]
std::optional<std::string> reason_string = props[async_mqtt5::prop::reason_string]; std::optional<std::string> reason_string = props[boost::mqtt5::prop::reason_string];
if (reason_string.has_value()) if (reason_string.has_value())
// reason string property was previously set // reason string property was previously set
else else
// reason string property was not set // reason string property was not set
std::vector<std::pair<std::string, std::string>>& user_props = props[async_mqtt5::prop::user_property]; std::vector<std::pair<std::string, std::string>>& user_props = props[boost::mqtt5::prop::user_property];
if (!user_props.empty()) if (!user_props.empty())
// user property was previously set // user property was previously set
else else
// user property was not set // user property was not set
[endsect] [endsect]

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

@ -12,36 +12,36 @@ A Property consists of an Identifier and a value.
This section lists all possible __UNSUBSCRIBE__ Properties and describes their usage: This section lists all possible __UNSUBSCRIBE__ Properties and describes their usage:
[table:unsubscribe_props UNSUBSCRIBE properties [table:unsubscribe_props UNSUBSCRIBE properties
[[Identifier] [Value type] [Description]] [[Identifier] [Value type] [Description]]
[[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. [[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet.
This property can be used to send subscription related properties from the Client to the Server. This property can be used to send subscription related properties from the Client to the Server.
The meaning of these properties is not defined by the specification ]] The meaning of these properties is not defined by the specification ]]
] ]
[h4 Usage] [h4 Usage]
After obtaining an instance of `async_mqtt5::unsubscribe_props`, the subscript operator can be used to access a Property. After obtaining an instance of `boost::mqtt5::unsubscribe_props`, the subscript operator can be used to access a Property.
The Identifiers listed in the table above are available within the `async_mqtt5::prop` namespace for Property access. The Identifiers listed in the table above are available within the `boost::mqtt5::prop` namespace for Property access.
[note When accessing a property value, the subscript operator will return a `std::optional` of the value type for all properties, [note When accessing 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 `std::vector<std::pair<std::string, std::string>>`.] except for `boost::mqtt5::prop::user_property`, where it will return an instance of `std::vector<std::pair<std::string, std::string>>`.]
[h4 Example] [h4 Example]
The following example shows how to set a Property value: The following example shows how to set a Property value:
[!c++] [!c++]
async_mqtt5::unsubscribe_props props; boost::mqtt5::unsubscribe_props props;
props[async_mqtt5::prop::user_property].emplace_back("name", "value"); props[boost::mqtt5::prop::user_property].emplace_back("name", "value");
The following example shows how to retrieve a Property value: The following example shows how to retrieve a Property value:
[!c++] [!c++]
std::vector<std::pair<std::string, std::string>>& user_props = props[async_mqtt5::prop::user_property]; std::vector<std::pair<std::string, std::string>>& user_props = props[boost::mqtt5::prop::user_property];
if (!user_props.empty()) if (!user_props.empty())
// user property was previously set // user property was previously set
else else
// user property was not set // user property was not set
[endsect] [endsect]

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

@ -13,48 +13,48 @@ A Property consists of an Identifier and a value.
This section lists all possible [reflink2 will Will] Properties and describes their usage: This section lists all possible [reflink2 will Will] Properties and describes their usage:
[table:will_props Will properties [table:will_props Will properties
[[Identifier] [Value type] [Description]] [[Identifier] [Value type] [Description]]
[[will_delay_interval] [`uint32_t`] [The delay in seconds that need to pass before Server publishes the Client's Will Message.]] [[will_delay_interval] [`uint32_t`] [The delay in seconds that need to pass before Server publishes the Client's Will Message.]]
[[payload_format_indicator] [`uint8_t`] [Value of 0 indicates that the Will Message is in unspecified bytes. Value of 1 indicates that the Will Message is UTF-8 Encoded Character Data.]] [[payload_format_indicator] [`uint8_t`] [Value of 0 indicates that the Will Message is in unspecified bytes. Value of 1 indicates that the Will Message is UTF-8 Encoded Character Data.]]
[[message_expiry_interval] [`uint32_t`] [The lifetime of the Will Message in seconds. It is send as Publication Expiry Interval when it is published.]] [[message_expiry_interval] [`uint32_t`] [The lifetime of the Will Message in seconds. It is send as Publication Expiry Interval when it is published.]]
[[content_type] [`std::string`] [A UTF-8 Encoded String describing the content of the Will Message.]] [[content_type] [`std::string`] [A UTF-8 Encoded String describing the content of the Will Message.]]
[[response_topic] [`std::string`] [A UTF-8 Encoded String which is used as the Topic Name for a response message.]] [[response_topic] [`std::string`] [A UTF-8 Encoded String which is used as the Topic Name for a response message.]]
[[correlation_data] [`std::string`] [Binary Data used by the sender of the Request Message to identify which request the Response Message is for when it is received.]] [[correlation_data] [`std::string`] [Binary Data used by the sender of the Request Message to identify which request the Response Message is for when it is received.]]
[[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. [[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet.
The meaning of these properties is not defined by the specification.]] The meaning of these properties is not defined by the specification.]]
] ]
[h4 Usage] [h4 Usage]
After creating an instance of [reflink2 will `async_mqtt5::will`], the subscript operator can be used to access a Property. After creating an instance of [reflink2 will `boost::mqtt5::will`], the subscript operator can be used to access a Property.
The Identifiers listed in the table above are available within the `async_mqtt5::prop` namespace for Property access. The Identifiers listed in the table above are available within the `boost::mqtt5::prop` namespace for Property access.
[note When accessing a property value, the subscript operator will return a `std::optional` of the value type for all properties, [note When accessing 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 `std::vector<std::pair<std::string, std::string>>`.] except for `boost::mqtt5::prop::user_property`, where it will return an instance of `std::vector<std::pair<std::string, std::string>>`.]
[h4 Example] [h4 Example]
The following example shows how to set a Property value: The following example shows how to set a Property value:
[!c++] [!c++]
async_mqtt5::will will; boost::mqtt5::will will;
will[async_mqtt5::prop::message_expiry_interval] = 90; will[boost::mqtt5::prop::message_expiry_interval] = 90;
will[async_mqtt5::prop::content_type] = "Notification"; will[boost::mqtt5::prop::content_type] = "Notification";
props[async_mqtt5::prop::user_property].emplace_back("name", "value"); props[boost::mqtt5::prop::user_property].emplace_back("name", "value");
The following example shows how to retrieve a Property value: The following example shows how to retrieve a Property value:
[!c++] [!c++]
std::optional<std::string> c_type = will[async_mqtt5::prop::content_type]; std::optional<std::string> c_type = will[boost::mqtt5::prop::content_type];
if (c_type.has_value()) if (c_type.has_value())
// content type property was previously set // content type property was previously set
else else
// content type property was not set // content type property was not set
std::vector<std::pair<std::string, std::string>>& user_props = props[async_mqtt5::prop::user_property]; std::vector<std::pair<std::string, std::string>>& user_props = props[boost::mqtt5::prop::user_property];
if (!user_props.empty()) if (!user_props.empty())
// user property was previously set // user property was previously set
else else
// user property was not set // user property was not set
[endsect] [endsect]

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

@ -14,70 +14,65 @@
<entry valign="top"> <entry valign="top">
<bridgehead renderas="sect3">Classes</bridgehead> <bridgehead renderas="sect3">Classes</bridgehead>
<simplelist type="vert" columns="1"> <simplelist type="vert" columns="1">
<member><link linkend="async_mqtt5.ref.authority_path">authority_path</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__authority_path">authority_path</link></member>
<member><link linkend="async_mqtt5.ref.mqtt_client">mqtt_client</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__mqtt_client">mqtt_client</link></member>
<member><link linkend="async_mqtt5.ref.reason_code">reason_code</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_code">reason_code</link></member>
<member><link linkend="async_mqtt5.ref.subscribe_options">subscribe_options</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__subscribe_options">subscribe_options</link></member>
<member><link linkend="async_mqtt5.ref.subscribe_topic">subscribe_topic</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__subscribe_topic">subscribe_topic</link></member>
<member><link linkend="async_mqtt5.ref.will">will</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__will">will</link></member>
</simplelist> </simplelist>
<bridgehead renderas="sect3">Concepts</bridgehead> <bridgehead renderas="sect3">Concepts</bridgehead>
<simplelist type="vert" columns="1"> <simplelist type="vert" columns="1">
<member><link linkend="async_mqtt5.ref.ExecutionContext">ExecutionContext</link></member> <member><link linkend="mqtt5.ref.ExecutionContext">ExecutionContext</link></member>
<member><link linkend="async_mqtt5.ref.StreamType">StreamType</link></member> <member><link linkend="mqtt5.ref.StreamType">StreamType</link></member>
<member><link linkend="async_mqtt5.ref.TlsContext">TlsContext</link></member> <member><link linkend="mqtt5.ref.TlsContext">TlsContext</link></member>
<member><link linkend="async_mqtt5.ref.is_authenticator">is_authenticator</link></member> <member><link linkend="mqtt5.ref.is_authenticator">is_authenticator</link></member>
</simplelist> </simplelist>
</entry> </entry>
<entry valign="top"> <entry valign="top">
<bridgehead renderas="sect3">Type aliases</bridgehead> <bridgehead renderas="sect3">Type aliases</bridgehead>
<simplelist type="vert" columns="1"> <simplelist type="vert" columns="1">
<member><link linkend="async_mqtt5.ref.error_code">error_code</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__error_code">error_code</link></member>
</simplelist> </simplelist>
<bridgehead renderas="sect3">Enumerations</bridgehead> <bridgehead renderas="sect3">Enumerations</bridgehead>
<simplelist type="vert" columns="1"> <simplelist type="vert" columns="1">
<member><link linkend="async_mqtt5.ref.auth_step_e">auth_step_e</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__auth_step_e">auth_step_e</link></member>
<member><link linkend="async_mqtt5.ref.client.error">client::error</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__client__error">client::error</link></member>
<member><link linkend="async_mqtt5.ref.disconnect_rc_e">disconnect_rc_e</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__disconnect_rc_e">disconnect_rc_e</link></member>
<member><link linkend="async_mqtt5.ref.qos_e">qos_e</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__qos_e">qos_e</link></member>
<member><link linkend="async_mqtt5.ref.retain_e">retain_e</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__retain_e">retain_e</link></member>
</simplelist>
<bridgehead renderas="sect3">Functions</bridgehead>
<simplelist type="vert" columns="1">
<member><link linkend="async_mqtt5.ref.client.get_error_code_category">get_error_code_category</link></member>
<member><link linkend="async_mqtt5.ref.client.make_error_code">make_error_code</link></member>
</simplelist> </simplelist>
</entry> </entry>
<entry valign="top"> <entry valign="top">
<bridgehead renderas="sect3">Properties</bridgehead> <bridgehead renderas="sect3">Properties</bridgehead>
<simplelist type="vert" columns="1"> <simplelist type="vert" columns="1">
<member><link linkend="async_mqtt5.ref.will_props">will_props</link></member> <member><link linkend="mqtt5.ref.will_props">will_props</link></member>
<member><link linkend="async_mqtt5.ref.connect_props">connect_props</link></member> <member><link linkend="mqtt5.ref.connect_props">connect_props</link></member>
<member><link linkend="async_mqtt5.ref.connack_props">connack_props</link></member> <member><link linkend="mqtt5.ref.connack_props">connack_props</link></member>
<member><link linkend="async_mqtt5.ref.publish_props">publish_props</link></member> <member><link linkend="mqtt5.ref.publish_props">publish_props</link></member>
<member><link linkend="async_mqtt5.ref.puback_props">puback_props</link></member> <member><link linkend="mqtt5.ref.puback_props">puback_props</link></member>
<member><link linkend="async_mqtt5.ref.pubrec_props">pubrec_props</link></member> <member><link linkend="mqtt5.ref.pubrec_props">pubrec_props</link></member>
<member><link linkend="async_mqtt5.ref.pubrel_props">pubrel_props</link></member> <member><link linkend="mqtt5.ref.pubrel_props">pubrel_props</link></member>
<member><link linkend="async_mqtt5.ref.pubcomp_props">pubcomp_props</link></member> <member><link linkend="mqtt5.ref.pubcomp_props">pubcomp_props</link></member>
<member><link linkend="async_mqtt5.ref.subscribe_props">subscribe_props</link></member> <member><link linkend="mqtt5.ref.subscribe_props">subscribe_props</link></member>
<member><link linkend="async_mqtt5.ref.suback_props">suback_props</link></member> <member><link linkend="mqtt5.ref.suback_props">suback_props</link></member>
<member><link linkend="async_mqtt5.ref.unsubscribe_props">unsubscribe_props</link></member> <member><link linkend="mqtt5.ref.unsubscribe_props">unsubscribe_props</link></member>
<member><link linkend="async_mqtt5.ref.unsuback_props">unsuback_props</link></member> <member><link linkend="mqtt5.ref.unsuback_props">unsuback_props</link></member>
<member><link linkend="async_mqtt5.ref.disconnect_props">disconnect_props</link></member> <member><link linkend="mqtt5.ref.disconnect_props">disconnect_props</link></member>
<member><link linkend="async_mqtt5.ref.auth_props">auth_props</link></member> <member><link linkend="mqtt5.ref.auth_props">auth_props</link></member>
</simplelist> </simplelist>
</entry> </entry>
<entry valign="top"> <entry valign="top">
<bridgehead renderas="sect3">Reference tables</bridgehead> <bridgehead renderas="sect3">Reference tables</bridgehead>
<simplelist type="vert" columns="1"> <simplelist type="vert" columns="1">
<member><link linkend="async_mqtt5.ref.Reason_codes">Reason codes</link></member> <member><link linkend="mqtt5.ref.Reason_codes">Reason codes</link></member>
<member><link linkend="async_mqtt5.ref.Error_handling">Error handling</link></member> <member><link linkend="mqtt5.ref.Error_handling">Error handling</link></member>
</simplelist> </simplelist>
<bridgehead renderas="sect3">Logging</bridgehead> <bridgehead renderas="sect3">Logging</bridgehead>
<simplelist type="vert" columns="1"> <simplelist type="vert" columns="1">
<member><link linkend="async_mqtt5.ref.LoggerType">LoggerType</link></member> <member><link linkend="mqtt5.ref.LoggerType">LoggerType</link></member>
<member><link linkend="async_mqtt5.ref.logger">logger</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__logger">logger</link></member>
<member><link linkend="async_mqtt5.ref.log_level">log_level</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__log_level">log_level</link></member>
</simplelist> </simplelist>
</entry> </entry>
</row></tbody> </row></tbody>

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

@ -14,59 +14,59 @@
<entry valign="top"> <entry valign="top">
<bridgehead renderas="sect3">Success</bridgehead> <bridgehead renderas="sect3">Success</bridgehead>
<simplelist type="vert" columns="1"> <simplelist type="vert" columns="1">
<member><link linkend="async_mqtt5.ref.reason_codes.continue_authentication">continue_authentication</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__continue_authentication">continue_authentication</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.disconnect_with_will_message">disconnect_with_will_message</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__disconnect_with_will_message">disconnect_with_will_message</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.granted_qos_0">granted_qos_0</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__granted_qos_0">granted_qos_0</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.granted_qos_1">granted_qos_1</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__granted_qos_1">granted_qos_1</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.granted_qos_2">granted_qos_2</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__granted_qos_2">granted_qos_2</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.no_matching_subscribers">no_matching_subscribers</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__no_matching_subscribers">no_matching_subscribers</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.no_subscription_existed">no_subscription_existed</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__no_subscription_existed">no_subscription_existed</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.normal_disconnection">normal_disconnection</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__normal_disconnection">normal_disconnection</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.reauthenticate">reauthenticate</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__reauthenticate">reauthenticate</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.success">success</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__success">success</link></member>
</simplelist> </simplelist>
</entry> </entry>
<entry valign="top"> <entry valign="top">
<bridgehead renderas="sect3">Error</bridgehead> <bridgehead renderas="sect3">Error</bridgehead>
<simplelist type="vert" columns="1"> <simplelist type="vert" columns="1">
<member><link linkend="async_mqtt5.ref.reason_codes.administrative_action">administrative_action</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__administrative_action">administrative_action</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.bad_authentication_method">bad_authentication_method</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__bad_authentication_method">bad_authentication_method</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.bad_username_or_password">bad_username_or_password</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__bad_username_or_password">bad_username_or_password</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.banned">banned</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__banned">banned</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.client_identifier_not_valid">client_identifier_not_valid</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__client_identifier_not_valid">client_identifier_not_valid</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.connection_rate_exceeded">connection_rate_exceeded</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__connection_rate_exceeded">connection_rate_exceeded</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.implementation_specific_error">implementation_specific_error</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__implementation_specific_error">implementation_specific_error</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.keep_alive_timeout">keep_alive_timeout</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__keep_alive_timeout">keep_alive_timeout</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.maximum_connect_time">maximum_connect_time</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__maximum_connect_time">maximum_connect_time</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.message_rate_too_high">message_rate_too_high</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__message_rate_too_high">message_rate_too_high</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.not_authorized">not_authorized</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__not_authorized">not_authorized</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.packet_identifier_in_use">packet_identifier_in_use</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__packet_identifier_in_use">packet_identifier_in_use</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.packet_identifier_not_found">packet_identifier_not_found</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__packet_identifier_not_found">packet_identifier_not_found</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.packet_too_large">packet_too_large</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__packet_too_large">packet_too_large</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.payload_format_invalid">payload_format_invalid</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__payload_format_invalid">payload_format_invalid</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.qos_not_supported">qos_not_supported</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__qos_not_supported">qos_not_supported</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.quota_exceeded">quota_exceeded</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__quota_exceeded">quota_exceeded</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.receive_maximum_exceeded">receive_maximum_exceeded</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__receive_maximum_exceeded">receive_maximum_exceeded</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.retain_not_supported">retain_not_supported</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__retain_not_supported">retain_not_supported</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.server_busy">server_busy</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__server_busy">server_busy</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.server_moved">server_moved</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__server_moved">server_moved</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.server_shutting_down">server_shutting_down</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__server_shutting_down">server_shutting_down</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.server_unavailable">server_unavailable</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__server_unavailable">server_unavailable</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.session_taken_over">session_taken_over</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__session_taken_over">session_taken_over</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.shared_subscriptions_not_supported">shared_subscriptions_not_supported</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__shared_subscriptions_not_supported">shared_subscriptions_not_supported</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.subscription_ids_not_supported">subscription_ids_not_supported</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__subscription_ids_not_supported">subscription_ids_not_supported</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.topic_alias_invalid">topic_alias_invalid</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__topic_alias_invalid">topic_alias_invalid</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.topic_filter_invalid">topic_filter_invalid</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__topic_filter_invalid">topic_filter_invalid</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.topic_name_invalid">topic_name_invalid</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__topic_name_invalid">topic_name_invalid</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.unsupported_protocol_version">unsupported_protocol_version</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__unsupported_protocol_version">unsupported_protocol_version</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.use_another_server">use_another_server</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__use_another_server">use_another_server</link></member>
<member><link linkend="async_mqtt5.ref.reason_codes.wildcard_subscriptions_not_supported">wildcard_subscriptions_not_supported</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__wildcard_subscriptions_not_supported">wildcard_subscriptions_not_supported</link></member>
</simplelist> </simplelist>
</entry> </entry>
<entry valign="top"> <entry valign="top">
<bridgehead renderas="sect3">Special</bridgehead> <bridgehead renderas="sect3">Special</bridgehead>
<simplelist type="vert" columns="1"> <simplelist type="vert" columns="1">
<member><link linkend="async_mqtt5.ref.reason_codes.empty">empty</link></member> <member><link linkend="mqtt5.ref.boost__mqtt5__reason_codes__empty">empty</link></member>
</simplelist> </simplelist>
</entry> </entry>
</row></tbody> </row></tbody>

214
doc/reference.dox
View File

@ -1,214 +0,0 @@
# Doxyfile 1.9.8
#---------------------------------------------------------------------------
# Project related configuration options
#---------------------------------------------------------------------------
PROJECT_NAME = "async_mqtt5 reference"
PROJECT_NUMBER =
OUTPUT_DIRECTORY = ./bin
CREATE_SUBDIRS = NO
OUTPUT_LANGUAGE = English
BRIEF_MEMBER_DESC = YES
REPEAT_BRIEF = YES
ABBREVIATE_BRIEF =
ALWAYS_DETAILED_SEC = YES
INLINE_INHERITED_MEMB = YES
FULL_PATH_NAMES = YES
STRIP_FROM_PATH = ./../../../
STRIP_FROM_INC_PATH =
SHORT_NAMES = NO
JAVADOC_AUTOBRIEF = NO
MULTILINE_CPP_IS_BRIEF = YES
INHERIT_DOCS = NO
SEPARATE_MEMBER_PAGES = NO
TAB_SIZE = 2
ALIASES =
OPTIMIZE_OUTPUT_FOR_C = NO
OPTIMIZE_OUTPUT_JAVA = NO
BUILTIN_STL_SUPPORT = NO
DISTRIBUTE_GROUP_DOC = NO
SUBGROUPING = YES
#---------------------------------------------------------------------------
# Build related configuration options
#---------------------------------------------------------------------------
EXTRACT_ALL = YES
EXTRACT_PRIVATE = NO
EXTRACT_STATIC = YES
EXTRACT_LOCAL_CLASSES = NO
EXTRACT_LOCAL_METHODS = NO
HIDE_UNDOC_MEMBERS = YES
HIDE_UNDOC_CLASSES = YES
HIDE_FRIEND_COMPOUNDS = NO
HIDE_IN_BODY_DOCS = NO
INTERNAL_DOCS = NO
CASE_SENSE_NAMES = YES
HIDE_SCOPE_NAMES = NO
SHOW_INCLUDE_FILES = NO
INLINE_INFO = NO
SORT_MEMBER_DOCS = NO
SORT_BRIEF_DOCS = NO
SORT_BY_SCOPE_NAME = NO
GENERATE_TODOLIST = NO
GENERATE_TESTLIST = NO
GENERATE_BUGLIST = NO
GENERATE_DEPRECATEDLIST= NO
ENABLED_SECTIONS =
MAX_INITIALIZER_LINES = 30
SHOW_USED_FILES = NO
FILE_VERSION_FILTER =
#---------------------------------------------------------------------------
# configuration options related to warning and progress messages
#---------------------------------------------------------------------------
QUIET = NO
WARNINGS = YES
WARN_IF_UNDOCUMENTED = YES
WARN_IF_DOC_ERROR = YES
WARN_NO_PARAMDOC = NO
WARN_FORMAT = "$file:$line: $text"
WARN_LOGFILE =
#---------------------------------------------------------------------------
# configuration options related to the input files
#---------------------------------------------------------------------------
INPUT = ../include/async_mqtt5/error.hpp \
../include/async_mqtt5/logger.hpp \
../include/async_mqtt5/reason_codes.hpp \
../include/async_mqtt5/types.hpp \
../include/async_mqtt5/mqtt_client.hpp
FILE_PATTERNS =
RECURSIVE = NO
EXCLUDE =
EXCLUDE_SYMLINKS = NO
EXCLUDE_PATTERNS =
EXAMPLE_PATH =
EXAMPLE_PATTERNS =
EXAMPLE_RECURSIVE = YES
IMAGE_PATH =
INPUT_FILTER =
FILTER_PATTERNS =
FILTER_SOURCE_FILES = NO
#---------------------------------------------------------------------------
# configuration options related to source browsing
#---------------------------------------------------------------------------
SOURCE_BROWSER = NO
INLINE_SOURCES = NO
STRIP_CODE_COMMENTS = YES
REFERENCED_BY_RELATION = NO
REFERENCES_RELATION = NO
USE_HTAGS = NO
VERBATIM_HEADERS = NO
#---------------------------------------------------------------------------
# configuration options related to the alphabetical class index
#---------------------------------------------------------------------------
ALPHABETICAL_INDEX = YES
IGNORE_PREFIX =
#---------------------------------------------------------------------------
# configuration options related to the HTML output
#---------------------------------------------------------------------------
GENERATE_HTML = NO
HTML_OUTPUT = .
HTML_FILE_EXTENSION = .html
HTML_HEADER =
HTML_FOOTER =
HTML_STYLESHEET =
GENERATE_HTMLHELP = NO
CHM_FILE =
HHC_LOCATION =
GENERATE_CHI = NO
BINARY_TOC = NO
TOC_EXPAND = NO
DISABLE_INDEX = YES
ENUM_VALUES_PER_LINE = 1
GENERATE_TREEVIEW = NO
TREEVIEW_WIDTH = 250
#---------------------------------------------------------------------------
# configuration options related to the LaTeX output
#---------------------------------------------------------------------------
GENERATE_LATEX = NO
LATEX_OUTPUT = latex
LATEX_CMD_NAME = latex
MAKEINDEX_CMD_NAME = makeindex
COMPACT_LATEX = NO
EXTRA_PACKAGES =
LATEX_HEADER =
PDF_HYPERLINKS = NO
USE_PDFLATEX = NO
LATEX_BATCHMODE = NO
LATEX_HIDE_INDICES = NO
#---------------------------------------------------------------------------
# configuration options related to the RTF output
#---------------------------------------------------------------------------
GENERATE_RTF = NO
RTF_OUTPUT = rtf
COMPACT_RTF = NO
RTF_HYPERLINKS = NO
RTF_STYLESHEET_FILE =
RTF_EXTENSIONS_FILE =
#---------------------------------------------------------------------------
# configuration options related to the man page output
#---------------------------------------------------------------------------
GENERATE_MAN = NO
MAN_OUTPUT = man
MAN_EXTENSION = .3
MAN_LINKS = NO
#---------------------------------------------------------------------------
# configuration options related to the XML output
#---------------------------------------------------------------------------
GENERATE_XML = YES
XML_OUTPUT = xml
XML_PROGRAMLISTING = NO
#---------------------------------------------------------------------------
# configuration options for the AutoGen Definitions output
#---------------------------------------------------------------------------
GENERATE_AUTOGEN_DEF = NO
#---------------------------------------------------------------------------
# configuration options related to the Perl module output
#---------------------------------------------------------------------------
GENERATE_PERLMOD = NO
PERLMOD_LATEX = NO
PERLMOD_PRETTY = YES
PERLMOD_MAKEVAR_PREFIX =
#---------------------------------------------------------------------------
# Configuration options related to the preprocessor
#---------------------------------------------------------------------------
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
SEARCH_INCLUDES = YES
INCLUDE_PATH =
INCLUDE_FILE_PATTERNS =
PREDEFINED =
EXPAND_AS_DEFINED =
SKIP_FUNCTION_MACROS = YES
#---------------------------------------------------------------------------
# Configuration::additions related to external references
#---------------------------------------------------------------------------
TAGFILES =
GENERATE_TAGFILE =
ALLEXTERNALS = NO
EXTERNAL_GROUPS = YES
#---------------------------------------------------------------------------
# Configuration options related to the dot tool
#---------------------------------------------------------------------------
HIDE_UNDOC_RELATIONS = YES
HAVE_DOT = YES
CLASS_GRAPH = YES
COLLABORATION_GRAPH = NO
GROUP_GRAPHS = NO
UML_LOOK = NO
TEMPLATE_RELATIONS = YES
INCLUDE_GRAPH = NO
INCLUDED_BY_GRAPH = NO
CALL_GRAPH = NO
GRAPHICAL_HIERARCHY = NO
DIRECTORY_GRAPH = NO
DOT_IMAGE_FORMAT = png
DOT_PATH =
DOTFILE_DIRS =
MAX_DOT_GRAPH_DEPTH = 0
DOT_MULTI_TARGETS = NO
GENERATE_LEGEND = NO
DOT_CLEANUP = YES
#---------------------------------------------------------------------------
# Configuration::additions related to the search engine
#---------------------------------------------------------------------------
SEARCHENGINE = NO

1726
doc/reference.xsl
View File

File diff suppressed because it is too large Load Diff

2
example/timeout_with_awaitable_operators.cpp
View File

@ -25,8 +25,6 @@
#include <boost/asio/ip/tcp.hpp> #include <boost/asio/ip/tcp.hpp>
#include <boost/asio/steady_timer.hpp> #include <boost/asio/steady_timer.hpp>
#include <boost/mysql/any_connection.hpp>
#include <chrono> #include <chrono>
#include <iostream> #include <iostream>
#include <string> #include <string>

26
include/boost/mqtt5/error.hpp
View File

@ -23,10 +23,10 @@ namespace boost::mqtt5 {
* in the \__DISCONNECT\__ packet as the reason for the disconnection. * in the \__DISCONNECT\__ packet as the reason for the disconnection.
*/ */
enum class disconnect_rc_e : uint8_t { enum class disconnect_rc_e : uint8_t {
/** Close the connection normally. Do not send the Will Message. */ /** \brief Close the connection normally. Do not send the Will Message. */
normal_disconnection = 0x00, normal_disconnection = 0x00,
/** The Client wishes to disconnect but requires that /** \brief The Client wishes to disconnect but requires that
the Server also publishes its Will Message. */ the Server also publishes its Will Message. */
disconnect_with_will_message = 0x04 disconnect_with_will_message = 0x04
}; };
@ -61,39 +61,39 @@ namespace client {
* \details Encapsulates errors that occur on the client side. * \details Encapsulates errors that occur on the client side.
*/ */
enum class error : int { enum class error : int {
/** The packet is malformed */ /** \brief The packet is malformed */
malformed_packet = 100, malformed_packet = 100,
/** The packet has exceeded the Maximum Packet Size the Server is willing to accept */ /** \brief The packet has exceeded the Maximum Packet Size the Server is willing to accept */
packet_too_large, packet_too_large,
/** The Client's session does not exist or it has expired */ /** \brief The Client's session does not exist or it has expired */
session_expired, session_expired,
/** There are no more available Packet Identifiers to use */ /** \brief There are no more available Packet Identifiers to use */
pid_overrun, pid_overrun,
/** The Topic is invalid and does not conform to the specification */ /** \brief The Topic is invalid and does not conform to the specification */
invalid_topic, invalid_topic,
// publish // publish
/** The Server does not support the specified \ref qos_e */ /** \brief The Server does not support the specified \ref qos_e */
qos_not_supported, qos_not_supported,
/** The Server does not support retained messages */ /** \brief The Server does not support retained messages */
retain_not_available, retain_not_available,
/** The Client attempted to send a Topic Alias that is greater than Topic Alias Maximum */ /** \brief The Client attempted to send a Topic Alias that is greater than Topic Alias Maximum */
topic_alias_maximum_reached, topic_alias_maximum_reached,
// subscribe // subscribe
/** The Server does not support Wildcard Subscriptions */ /** \brief The Server does not support Wildcard Subscriptions */
wildcard_subscription_not_available, wildcard_subscription_not_available,
/** The Server does not support this Subscription Identifier */ /** \brief The Server does not support this Subscription Identifier */
subscription_identifier_not_available, subscription_identifier_not_available,
/** The Server does not support Shared Subscriptions */ /** \brief The Server does not support Shared Subscriptions */
shared_subscription_not_available shared_subscription_not_available
}; };

4
include/boost/mqtt5/impl/codecs/message_decoders.hpp
View File

@ -83,7 +83,7 @@ inline std::optional<connect_message> decode_connect(
basic::utf8_ >> // client_id basic::utf8_ >> // client_id
basic::if_(has_will)[prop::props_<will_props>] >> basic::if_(has_will)[prop::props_<will_props>] >>
basic::if_(has_will)[basic::utf8_] >> // will topic basic::if_(has_will)[basic::utf8_] >> // will topic
basic::if_(has_will)[basic::binary_] >> // will message basic::if_(has_will)[basic::binary_] >> // will message
basic::if_(has_uname)[basic::utf8_] >> // username basic::if_(has_uname)[basic::utf8_] >> // username
basic::if_(has_pwd)[basic::utf8_]; // password basic::if_(has_pwd)[basic::utf8_]; // password
@ -266,7 +266,7 @@ inline std::optional<unsuback_message> decode_unsuback(
uint32_t remain_length, byte_citer& it uint32_t remain_length, byte_citer& it
) { ) {
auto unsuback_ = basic::scope_limit_(remain_length)[ auto unsuback_ = basic::scope_limit_(remain_length)[
prop::props_<unsuback_props> >> +x3::byte_ prop::props_<unsuback_props> >> +x3::byte_
]; ];
return type_parse(it, it + remain_length, unsuback_); return type_parse(it, it + remain_length, unsuback_);
} }

2
include/boost/mqtt5/impl/codecs/message_encoders.hpp
View File

@ -61,7 +61,7 @@ inline std::string encode_connect(
basic::utf8_(client_id) & basic::utf8_(client_id) &
prop::props_(w) & prop::props_(w) &
basic::utf8_(w, &will::topic) & basic::utf8_(w, &will::topic) &
basic::binary_(w, &will::message) & basic::binary_(w, &will::message) &
basic::utf8_(user_name) & basic::utf8_(user_name) &
basic::utf8_(password); basic::utf8_(password);

4
include/boost/mqtt5/impl/connect_op.hpp
View File

@ -322,9 +322,9 @@ public:
// Unexpected result handling: // Unexpected result handling:
// - If we don't have a Session State, and we get session_present = true, // - If we don't have a Session State, and we get session_present = true,
// we must close the network connection (and restart with a clean start) // we must close the network connection (and restart with a clean start)
// - If we have a Session State, and we get session_present = false, // - If we have a Session State, and we get session_present = false,
// we must discard our Session State // we must discard our Session State
auto rc = to_reason_code<reason_codes::category::connack>(reason_code); auto rc = to_reason_code<reason_codes::category::connack>(reason_code);
if (!rc.has_value()) // reason code not allowed in CONNACK if (!rc.has_value()) // reason code not allowed in CONNACK

6
include/boost/mqtt5/logger.hpp
View File

@ -54,9 +54,9 @@ enum class log_level : uint8_t {
* implicit strand, none of the functions will be invoked concurrently. * implicit strand, none of the functions will be invoked concurrently.
* *
* \par Thread safety * \par Thread safety
* ['Distinct objects]: unsafe. \n * Distinct objects: usafe. \n
* ['Shared objects]: unsafe. \n * Shared objects: unsafe. \n
* This class is [*not thread-safe]. * This class is <b>not thread-safe</b>.
*/ */
class logger { class logger {
constexpr static auto prefix = "[Boost.MQTT5]"; constexpr static auto prefix = "[Boost.MQTT5]";

482
include/boost/mqtt5/mqtt_client.hpp
View File

@ -45,9 +45,9 @@ namespace asio = boost::asio;
* \tparam \__LoggerType\__ Type of object used to log events within the Client. * \tparam \__LoggerType\__ Type of object used to log events within the Client.
* *
* \par Thread safety * \par Thread safety
* ['Distinct objects]: safe. \n * Distinct objects: safe. \n
* ['Shared objects]: unsafe. \n * Shared objects: unsafe. \n
* This class is [*not thread-safe]. * This class is <b>not thread-safe</b>.
* The application must also ensure that all asynchronous operations are performed within the same implicit or explicit strand. * The application must also ensure that all asynchronous operations are performed within the same implicit or explicit strand.
*/ */
template < template <
@ -150,7 +150,7 @@ public:
/** /**
* \brief Destructor. * \brief Destructor.
* *
* \details Automatically calls \ref mqtt_client::cancel. * \details Automatically calls \ref cancel.
*/ */
~mqtt_client() { ~mqtt_client() {
if (_impl) if (_impl)
@ -192,23 +192,23 @@ public:
* *
* \par Handler signature * \par Handler signature
* The handler signature for this operation: * The handler signature for this operation:
* \code * \code
* void (__ERROR_CODE__) * void (__ERROR_CODE__)
* \endcode * \endcode
* *
* \par Completion condition * \par Completion condition
* The asynchronous operation will complete with * The asynchronous operation will complete with
* `boost::asio::error::operation_aborted` when the client is cancelled by calling * `boost::asio::error::operation_aborted` when the client is cancelled by calling
* \ref mqtt_client::async_disconnect, \ref mqtt_client::cancel, destruction or * \ref async_disconnect, \ref cancel, destruction or
* if a non-recoverable error happens during a connection attempt (e.g. access denied). * if a non-recoverable error happens during a connection attempt (e.g. access denied).
* *
* \par Error codes * \par Error codes
* The list of all possible error codes that this operation can finish with:\n * The list of all possible error codes that this operation can finish with:\n
* - `boost::asio::error::operation_aborted`\n * - `boost::asio::error::operation_aborted`\n
* *
* \par Per-Operation Cancellation * \par Per-Operation Cancellation
* This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n * This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n
* - `cancellation_type::terminal` - invokes \ref mqtt_client::cancel \n * - `cancellation_type::terminal` - invokes \ref cancel \n
*/ */
template < template <
typename CompletionToken = typename CompletionToken =
@ -228,7 +228,7 @@ public:
* with `boost::asio::error::operation_aborted`. * with `boost::asio::error::operation_aborted`.
* *
* \attention This function has terminal effects and will close the Client. * \attention This function has terminal effects and will close the Client.
* The Client cannot be used before calling \ref mqtt_client::async_run again. * The Client cannot be used before calling \ref async_run again.
*/ */
void cancel() { void cancel() {
auto impl = _impl; auto impl = _impl;
@ -297,8 +297,8 @@ public:
* Some valid `hosts` string: * Some valid `hosts` string:
* *
* \code * \code
* std::string valid_hosts_1 = "broker1:1883, broker2, broker3:1883"; * std::string valid_hosts_1 = "broker1:1883, broker2, broker3:1883";
* std::string valid_hosts_2 = "broker1"; * std::string valid_hosts_2 = "broker1";
* \endcode * \endcode
* *
*/ */
@ -387,7 +387,7 @@ public:
} }
/** /**
* \brief Initiates [mqttlink 3901257 Re-authentication] * \brief Initiates \__RE_AUTHENTICATION\__
* using the authenticator given in the \ref authenticator method. * using the authenticator given in the \ref authenticator method.
* *
* \note If \ref authenticator was not called, this method does nothing. * \note If \ref authenticator was not called, this method does nothing.
@ -408,8 +408,8 @@ public:
* *
* \par Example * \par Example
* \code * \code
* std::optional<std::string> auth_method = client.connack_property(boost::mqtt5::prop::authentication_method); // ok * std::optional<std::string> auth_method = client.connack_property(boost::mqtt5::prop::authentication_method); // ok
* std::optional<std::string> c_type = client.connack_property(boost::mqtt5::prop::content_type); // does not compile, not a CONNACK prop! * std::optional<std::string> c_type = client.connack_property(boost::mqtt5::prop::content_type); // does not compile, not a CONNACK prop!
* \endcode * \endcode
* *
* \see See \__CONNACK_PROPS\__ for all eligible properties. * \see See \__CONNACK_PROPS\__ for all eligible properties.
@ -448,61 +448,61 @@ public:
* \par Handler signature * \par Handler signature
* The handler signature for this operation depends on the \ref qos_e specified:\n * The handler signature for this operation depends on the \ref qos_e specified:\n
* *
* `qos` == `qos_e::at_most_once`: * `qos` == `qos_e::at_most_once`:
* \code * \code
* void ( * void (
* __ERROR_CODE__ // Result of operation * __ERROR_CODE__ // Result of operation
* ) * )
* \endcode * \endcode
* *
* `qos` == `qos_e::at_least_once`: * `qos` == `qos_e::at_least_once`:
* \code * \code
* void ( * void (
* __ERROR_CODE__, // Result of operation. * __ERROR_CODE__, // Result of operation.
* __REASON_CODE__, // Reason Code received from Broker. * __REASON_CODE__, // Reason Code received from Broker.
* __PUBACK_PROPS__ // Properties received in the PUBACK packet. * __PUBACK_PROPS__ // Properties received in the PUBACK packet.
* ) * )
* \endcode * \endcode
* *
* `qos` == `qos_e::exactly_once`: * `qos` == `qos_e::exactly_once`:
* \code * \code
* void ( * void (
* __ERROR_CODE__, // Result of operation. * __ERROR_CODE__, // Result of operation.
* __REASON_CODE__, // Reason Code received from Broker. * __REASON_CODE__, // Reason Code received from Broker.
* __PUBCOMP_PROPS__ // Properties received in the PUBCOMP packet. * __PUBCOMP_PROPS__ // Properties received in the PUBCOMP packet.
* ) * )
* \endcode * \endcode
* *
* \par Completion condition * \par Completion condition
* Depending on the \ref qos_e specified, the asynchronous operation will complete * Depending on the \ref qos_e specified, the asynchronous operation will complete
* when one of the following conditions is true:\n * when one of the following conditions is true:\n
* - If `qos` == `qos_e::at_most_once` and the Client * - If `qos` == `qos_e::at_most_once` and the Client
* has successfully written the packet to the transport. \n * has successfully written the packet to the transport. \n
* - If `qos` == `qos_e::at_least_once` and the packet has * - If `qos` == `qos_e::at_least_once` and the packet has
* been sent and acknowledged through the reception of a \__PUBACK\__ packet. * been sent and acknowledged through the reception of a \__PUBACK\__ packet.
* - If `qos` == `qos_e::exactly_once` and the packet has * - If `qos` == `qos_e::exactly_once` and the packet has
* been sent and fully acknowledged through the reception of a \__PUBCOMP\__ packet. * been sent and fully acknowledged through the reception of a \__PUBCOMP\__ packet.
* - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n * - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n
* *
* \par Error codes * \par Error codes
* The list of all possible error codes that this operation can finish with:\n * The list of all possible error codes that this operation can finish with:\n
* - `boost::system::errc::errc_t::success` \n * - `boost::system::errc::errc_t::success` \n
* - `boost::asio::error::operation_aborted` \n * - `boost::asio::error::operation_aborted` \n
* - `boost::asio::error::no_recovery` \n * - `boost::asio::error::no_recovery` \n
* - \link boost::mqtt5::client::error::malformed_packet \endlink * - \ref boost::mqtt5::client::error::malformed_packet
* - \link boost::mqtt5::client::error::packet_too_large \endlink * - \ref boost::mqtt5::client::error::packet_too_large
* - \link boost::mqtt5::client::error::pid_overrun \endlink * - \ref boost::mqtt5::client::error::pid_overrun
* - \link boost::mqtt5::client::error::qos_not_supported \endlink * - \ref boost::mqtt5::client::error::qos_not_supported
* - \link boost::mqtt5::client::error::retain_not_available \endlink * - \ref boost::mqtt5::client::error::retain_not_available
* - \link boost::mqtt5::client::error::topic_alias_maximum_reached \endlink * - \ref boost::mqtt5::client::error::topic_alias_maximum_reached
* - \link boost::mqtt5::client::error::invalid_topic \endlink * - \ref boost::mqtt5::client::error::invalid_topic
* *
* Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code. * Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code.
* *
* \par Per-Operation Cancellation * \par Per-Operation Cancellation
* This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n * This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n
* - `cancellation_type::terminal` - invokes \ref mqtt_client::cancel \n * - `cancellation_type::terminal` - invokes \ref cancel \n
* - `cancellation_type::partial` & `cancellation_type::total` - prevents potential resending of the \__PUBLISH\__ packet \n * - `cancellation_type::partial` & `cancellation_type::total` - prevents potential resending of the \__PUBLISH\__ packet \n
* *
*/ */
template <qos_e qos_type, template <qos_e qos_type,
@ -540,41 +540,41 @@ public:
* *
* \par Handler signature * \par Handler signature
* The handler signature for this operation: * The handler signature for this operation:
* \code * \code
* void ( * void (
* __ERROR_CODE__, // Result of operation. * __ERROR_CODE__, // Result of operation.
* std::vector<__REASON_CODE__>, // Vector of Reason Codes indicating * std::vector<__REASON_CODE__>, // Vector of Reason Codes indicating
* // the subscription result for each Topic * // the subscription result for each Topic
* // in the SUBSCRIBE packet. * // in the SUBSCRIBE packet.
* __SUBACK_PROPS__, // Properties received in the SUBACK packet. * __SUBACK_PROPS__, // Properties received in the SUBACK packet.
* ) * )
* \endcode * \endcode
* *
* \par Completion condition * \par Completion condition
* The asynchronous operation will complete when one of the following conditions is true:\n * The asynchronous operation will complete when one of the following conditions is true:\n
* - The Client has successfully sent a \__SUBSCRIBE\__ packet * - The Client has successfully sent a \__SUBSCRIBE\__ packet
* and has received a \__SUBACK\__ response from the Broker.\n * and has received a \__SUBACK\__ response from the Broker.\n
* - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n * - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n
* *
* \par Error codes * \par Error codes
* The list of all possible error codes that this operation can finish with:\n * The list of all possible error codes that this operation can finish with:\n
* - `boost::system::errc::errc_t::success` \n * - `boost::system::errc::errc_t::success` \n
* - `boost::asio::error::no_recovery` \n * - `boost::asio::error::no_recovery` \n
* - `boost::asio::error::operation_aborted` \n * - `boost::asio::error::operation_aborted` \n
* - \link boost::mqtt5::client::error::malformed_packet \endlink * - \ref boost::mqtt5::client::error::malformed_packet
* - \link boost::mqtt5::client::error::packet_too_large \endlink * - \ref boost::mqtt5::client::error::packet_too_large
* - \link boost::mqtt5::client::error::pid_overrun \endlink * - \ref boost::mqtt5::client::error::pid_overrun
* - \link boost::mqtt5::client::error::invalid_topic \endlink * - \ref boost::mqtt5::client::error::invalid_topic
* - \link boost::mqtt5::client::error::wildcard_subscription_not_available \endlink * - \ref boost::mqtt5::client::error::wildcard_subscription_not_available
* - \link boost::mqtt5::client::error::subscription_identifier_not_available \endlink * - \ref boost::mqtt5::client::error::subscription_identifier_not_available
* - \link boost::mqtt5::client::error::shared_subscription_not_available \endlink * - \ref boost::mqtt5::client::error::shared_subscription_not_available
* *
* Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code. * Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code.
* *
* \par Per-Operation Cancellation * \par Per-Operation Cancellation
* This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n * This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n
* - `cancellation_type::terminal` - invokes \ref mqtt_client::cancel \n * - `cancellation_type::terminal` - invokes \ref mqtt_client::cancel \n
* - `cancellation_type::partial` & `cancellation_type::total` - prevents potential resending of the \__SUBSCRIBE\__ packet \n * - `cancellation_type::partial` & `cancellation_type::total` - prevents potential resending of the \__SUBSCRIBE\__ packet \n
* *
*/ */
template < template <
@ -613,41 +613,41 @@ public:
* *
* \par Handler signature * \par Handler signature
* The handler signature for this operation: * The handler signature for this operation:
* \code * \code
* void ( * void (
* __ERROR_CODE__, // Result of operation. * __ERROR_CODE__, // Result of operation.
* std::vector<__REASON_CODE__>, // Vector of Reason Codes containing the * std::vector<__REASON_CODE__>, // Vector of Reason Codes containing the
* // single subscription result for the Topic * // single subscription result for the Topic
* // in the SUBSCRIBE packet. * // in the SUBSCRIBE packet.
* __SUBACK_PROPS__, // Properties received in the SUBACK packet. * __SUBACK_PROPS__, // Properties received in the SUBACK packet.
* ) * )
* \endcode * \endcode
* *
* \par Completion condition * \par Completion condition
* The asynchronous operation will complete when one of the following conditions is true:\n * The asynchronous operation will complete when one of the following conditions is true:\n
* - The Client has successfully sent a \__SUBSCRIBE\__ packet * - The Client has successfully sent a \__SUBSCRIBE\__ packet
* and has received a \__SUBACK\__ response from the Broker.\n * and has received a \__SUBACK\__ response from the Broker.\n
* - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n * - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n
* *
* \par Error codes * \par Error codes
* The list of all possible error codes that this operation can finish with:\n * The list of all possible error codes that this operation can finish with:\n
* - `boost::system::errc::errc_t::success` \n * - `boost::system::errc::errc_t::success` \n
* - `boost::asio::error::no_recovery` \n * - `boost::asio::error::no_recovery` \n
* - `boost::asio::error::operation_aborted` \n * - `boost::asio::error::operation_aborted` \n
* - \link boost::mqtt5::client::error::malformed_packet \endlink * - \ref boost::mqtt5::client::error::malformed_packet
* - \link boost::mqtt5::client::error::packet_too_large \endlink * - \ref boost::mqtt5::client::error::packet_too_large
* - \link boost::mqtt5::client::error::pid_overrun \endlink * - \ref boost::mqtt5::client::error::pid_overrun
* - \link boost::mqtt5::client::error::invalid_topic \endlink * - \ref boost::mqtt5::client::error::invalid_topic
* - \link boost::mqtt5::client::error::wildcard_subscription_not_available \endlink * - \ref boost::mqtt5::client::error::wildcard_subscription_not_available
* - \link boost::mqtt5::client::error::subscription_identifier_not_available \endlink * - \ref boost::mqtt5::client::error::subscription_identifier_not_available
* - \link boost::mqtt5::client::error::shared_subscription_not_available \endlink * - \ref boost::mqtt5::client::error::shared_subscription_not_available
* *
* Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code. * Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code.
* *
* \par Per-Operation Cancellation * \par Per-Operation Cancellation
* This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n * This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n
* - `cancellation_type::terminal` - invokes \ref mqtt_client::cancel \n * - `cancellation_type::terminal` - invokes \ref mqtt_client::cancel \n
* - `cancellation_type::partial` & `cancellation_type::total` - prevents potential resending of the \__SUBSCRIBE\__ packet \n * - `cancellation_type::partial` & `cancellation_type::total` - prevents potential resending of the \__SUBSCRIBE\__ packet \n
* *
*/ */
template < template <
@ -682,38 +682,38 @@ public:
* *
* \par Handler signature * \par Handler signature
* The handler signature for this operation: * The handler signature for this operation:
* \code * \code
* void ( * void (
* __ERROR_CODE__, // Result of operation. * __ERROR_CODE__, // Result of operation.
* std::vector<__REASON_CODE__>, // Vector of Reason Codes indicating * std::vector<__REASON_CODE__>, // Vector of Reason Codes indicating
* // the result of unsubscribe operation * // the result of unsubscribe operation
* // for each Topic in the UNSUBSCRIBE packet. * // for each Topic in the UNSUBSCRIBE packet.
* __UNSUBACK_PROPS__, // Properties received in the UNSUBACK packet. * __UNSUBACK_PROPS__, // Properties received in the UNSUBACK packet.
* ) * )
* \endcode * \endcode
* *
* \par Completion condition * \par Completion condition
* The asynchronous operation will complete when one of the following conditions is true:\n * The asynchronous operation will complete when one of the following conditions is true:\n
* - The Client has successfully sent an \__UNSUBSCRIBE\__ packet * - The Client has successfully sent an \__UNSUBSCRIBE\__ packet
* and has received an \__UNSUBACK\__ response from the Broker.\n * and has received an \__UNSUBACK\__ response from the Broker.\n
* - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n * - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n
* *
* \par Error codes * \par Error codes
* The list of all possible error codes that this operation can finish with:\n * The list of all possible error codes that this operation can finish with:\n
* - `boost::system::errc::errc_t::success` \n * - `boost::system::errc::errc_t::success` \n
* - `boost::asio::error::no_recovery` \n * - `boost::asio::error::no_recovery` \n
* - `boost::asio::error::operation_aborted` \n * - `boost::asio::error::operation_aborted` \n
* - \link boost::mqtt5::client::error::malformed_packet \endlink * - \ref boost::mqtt5::client::error::malformed_packet
* - \link boost::mqtt5::client::error::packet_too_large \endlink * - \ref boost::mqtt5::client::error::packet_too_large
* - \link boost::mqtt5::client::error::pid_overrun \endlink * - \ref boost::mqtt5::client::error::pid_overrun
* - \link boost::mqtt5::client::error::invalid_topic \endlink * - \ref boost::mqtt5::client::error::invalid_topic
* *
* Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code. * Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code.
* *
* \par Per-Operation Cancellation * \par Per-Operation Cancellation
* This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n * This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n
* - `cancellation_type::terminal` - invokes \ref mqtt_client::cancel \n * - `cancellation_type::terminal` - invokes \ref mqtt_client::cancel \n
* - `cancellation_type::partial` & `cancellation_type::total` - prevents potential resending of the \__UNSUBSCRIBE\__ packet \n * - `cancellation_type::partial` & `cancellation_type::total` - prevents potential resending of the \__UNSUBSCRIBE\__ packet \n
* *
*/ */
template < template <
@ -721,7 +721,7 @@ public:
typename asio::default_completion_token<executor_type>::type typename asio::default_completion_token<executor_type>::type
> >
decltype(auto) async_unsubscribe( decltype(auto) async_unsubscribe(
const std::vector<std::string>& topics, const unsubscribe_props& props, const std::vector<std::string>& topics, const unsubscribe_props& props,
CompletionToken&& token = {} CompletionToken&& token = {}
) { ) {
using Signature = void ( using Signature = void (
@ -750,38 +750,38 @@ public:
* *
* \par Handler signature * \par Handler signature
* The handler signature for this operation: * The handler signature for this operation:
* \code * \code
* void ( * void (
* __ERROR_CODE__, // Result of operation. * __ERROR_CODE__, // Result of operation.
* std::vector<__REASON_CODE__>, // Vector of Reason Codes containing * std::vector<__REASON_CODE__>, // Vector of Reason Codes containing
* // the result of unsubscribe operation * // the result of unsubscribe operation
* // for the Topic in the UNSUBSCRIBE packet. * // for the Topic in the UNSUBSCRIBE packet.
* __UNSUBACK_PROPS__, // Properties received in the UNSUBACK packet. * __UNSUBACK_PROPS__, // Properties received in the UNSUBACK packet.
* ) * )
* \endcode * \endcode
* *
* \par Completion condition * \par Completion condition
* The asynchronous operation will complete when one of the following conditions is true:\n * The asynchronous operation will complete when one of the following conditions is true:\n
* - The Client has successfully sent an \__UNSUBSCRIBE\__ packet * - The Client has successfully sent an \__UNSUBSCRIBE\__ packet
* and has received an \__UNSUBACK\__ response from the Broker.\n * and has received an \__UNSUBACK\__ response from the Broker.\n
* - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n * - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n
* *
* \par Error codes * \par Error codes
* The list of all possible error codes that this operation can finish with:\n * The list of all possible error codes that this operation can finish with:\n
* - `boost::system::errc::errc_t::success` \n * - `boost::system::errc::errc_t::success` \n
* - `boost::asio::error::no_recovery` \n * - `boost::asio::error::no_recovery` \n
* - `boost::asio::error::operation_aborted` \n * - `boost::asio::error::operation_aborted` \n
* - \link boost::mqtt5::client::error::malformed_packet \endlink * - \ref boost::mqtt5::client::error::malformed_packet
* - \link boost::mqtt5::client::error::packet_too_large \endlink * - \ref boost::mqtt5::client::error::packet_too_large
* - \link boost::mqtt5::client::error::pid_overrun \endlink * - \ref boost::mqtt5::client::error::pid_overrun
* - \link boost::mqtt5::client::error::invalid_topic \endlink * - \ref boost::mqtt5::client::error::invalid_topic
* *
* Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code. * Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code.
* *
* \par Per-Operation Cancellation * \par Per-Operation Cancellation
* This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n * This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n
* - `cancellation_type::terminal` - invokes \ref mqtt_client::cancel \n * - `cancellation_type::terminal` - invokes \ref mqtt_client::cancel \n
* - `cancellation_type::partial` & `cancellation_type::total` - prevents potential resending of the \__UNSUBSCRIBE\__ packet \n * - `cancellation_type::partial` & `cancellation_type::total` - prevents potential resending of the \__UNSUBSCRIBE\__ packet \n
* *
*/ */
template < template <
@ -818,34 +818,34 @@ public:
* *
* \par Handler signature * \par Handler signature
* The handler signature for this operation: * The handler signature for this operation:
* \code * \code
* void ( * void (
* __ERROR_CODE__, // Result of operation. * __ERROR_CODE__, // Result of operation.
* std::string, // Topic, the origin of the Application Message. * std::string, // Topic, the origin of the Application Message.
* std::string, // Payload, the content of the Application Message. * std::string, // Payload, the content of the Application Message.
* __PUBLISH_PROPS__, // Properties received in the PUBLISH packet. * __PUBLISH_PROPS__, // Properties received in the PUBLISH packet.
* ) * )
* \endcode * \endcode
* *
* \par Completion condition * \par Completion condition
* The asynchronous operation will complete when one of the following conditions is true:\n * The asynchronous operation will complete when one of the following conditions is true:\n
* - The Client has a pending Application Message in its internal storage * - The Client has a pending Application Message in its internal storage
* ready to be received. * ready to be received.
* - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n * - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n
* *
* \par Error codes * \par Error codes
* The list of all possible error codes that this operation can finish with:\n * The list of all possible error codes that this operation can finish with:\n
* - `boost::system::errc::errc_t::success`\n * - `boost::system::errc::errc_t::success`\n
* - `boost::asio::error::operation_aborted`\n * - `boost::asio::error::operation_aborted`\n
* - \link boost::mqtt5::client::error::session_expired \endlink * - \ref boost::mqtt5::client::error::session_expired
* *
* Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code. * Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code.
* *
* \par Per-Operation Cancellation * \par Per-Operation Cancellation
* This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n * This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n
* - `cancellation_type::terminal` \n * - `cancellation_type::terminal` \n
* - `cancellation_type::partial` \n * - `cancellation_type::partial` \n
* - `cancellation_type::total` \n * - `cancellation_type::total` \n
*/ */
template < template <
typename CompletionToken = typename CompletionToken =
@ -875,32 +875,32 @@ public:
* *
* \par Handler signature * \par Handler signature
* The handler signature for this operation: * The handler signature for this operation:
* \code * \code
* void ( * void (
* __ERROR_CODE__ // Result of operation. * __ERROR_CODE__ // Result of operation.
* ) * )
* \endcode * \endcode
* *
* \par Completion condition * \par Completion condition
* The asynchronous operation will complete when one of the following conditions is true:\n * The asynchronous operation will complete when one of the following conditions is true:\n
* - The Client has sent a \__DISCONNECT\__ packet.\n * - The Client has sent a \__DISCONNECT\__ packet.\n
* - 5 seconds have elapsed without a successful send.\n * - 5 seconds have elapsed without a successful send.\n
* - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n * - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n
* *
* \par Error codes * \par Error codes
* The list of all possible error codes that this operation can finish with:\n * The list of all possible error codes that this operation can finish with:\n
* - `boost::system::errc::errc_t::success`\n * - `boost::system::errc::errc_t::success`\n
* - `boost::asio::error::operation_aborted`[footnote * - `boost::asio::error::operation_aborted`[footnote
This error code can appear if the Client fails to send the \__DISCONNECT\__ packet to the Server. This error code can appear if the Client fails to send the \__DISCONNECT\__ packet to the Server.
Regardless, the connection to the Server is terminated, and the Client is cancelled. Regardless, the connection to the Server is terminated, and the Client is cancelled.
]\n ]\n
* - \link boost::mqtt5::client::error::malformed_packet \endlink * - \ref boost::mqtt5::client::error::malformed_packet
* *
* Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code. * Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code.
* *
* \par Per-Operation Cancellation * \par Per-Operation Cancellation
* This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n * This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n
* - `cancellation_type::terminal` - invokes \ref mqtt_client::cancel \n * - `cancellation_type::terminal` - invokes \ref mqtt_client::cancel \n
* *
*/ */
template < template <
@ -937,32 +937,32 @@ public:
* *
* \par Handler signature * \par Handler signature
* The handler signature for this operation: * The handler signature for this operation:
* \code * \code
* void ( * void (
* __ERROR_CODE__ // Result of operation. * __ERROR_CODE__ // Result of operation.
* ) * )
* \endcode * \endcode
* *
* \par Completion condition * \par Completion condition
* The asynchronous operation will complete when one of the following conditions is true:\n * The asynchronous operation will complete when one of the following conditions is true:\n
* - The Client has attempted to send a \__DISCONNECT\__ packet, regardless of whether * - The Client has attempted to send a \__DISCONNECT\__ packet, regardless of whether
* the sending was successful or not.\n * the sending was successful or not.\n
* - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n * - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n
* *
* \par Error codes * \par Error codes
* The list of all possible error codes that this operation can finish with:\n * The list of all possible error codes that this operation can finish with:\n
* - `boost::system::errc::errc_t::success`\n * - `boost::system::errc::errc_t::success`\n
* - `boost::asio::error::operation_aborted`[footnote * - `boost::asio::error::operation_aborted`[footnote
This error code can appear if the Client fails to send the \__DISCONNECT\__ packet to the Server. This error code can appear if the Client fails to send the \__DISCONNECT\__ packet to the Server.
Regardless, the connection to the Server is terminated, and the Client is cancelled. Regardless, the connection to the Server is terminated, and the Client is cancelled.
]\n ]\n
* - \link boost::mqtt5::client::error::malformed_packet \endlink * - \ref boost::mqtt5::client::error::malformed_packet
* *
* Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code. * Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code.
* *
* \par Per-Operation Cancellation * \par Per-Operation Cancellation
* This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n * This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n
* - `cancellation_type::terminal` - invokes \ref mqtt_client::cancel \n * - `cancellation_type::terminal` - invokes \ref mqtt_client::cancel \n
*/ */
template < template <
typename CompletionToken = typename CompletionToken =

106
include/boost/mqtt5/reason_codes.hpp
View File

@ -35,14 +35,14 @@ enum class category : uint8_t {
* \brief A class holding Reason Code values originating from Control Packets. * \brief A class holding Reason Code values originating from Control Packets.
* *
* \details A Reason Code is a one byte unsigned value that indicates the result of an operation. * \details A Reason Code is a one byte unsigned value that indicates the result of an operation.
* Reason Codes less than 0x80 indicate successful completion of an operation. * Reason Codes less than 0x80 indicate successful completion of an operation.
* The normal Reason Code for success is 0. * The normal Reason Code for success is 0.
* Reason Code values of 0x80 or greater indicate failure. * Reason Code values of 0x80 or greater indicate failure.
* The \__CONNACK\__, \__PUBACK\__, \__PUBREC\__, \__PUBREL\__, \__PUBCOMP\__, \__DISCONNECT\__ * The \__CONNACK\__, \__PUBACK\__, \__PUBREC\__, \__PUBREL\__, \__PUBCOMP\__, \__DISCONNECT\__
* and \__AUTH\__ Control Packets have a single Reason Code as part of the Variable Header. * and \__AUTH\__ Control Packets have a single Reason Code as part of the Variable Header.
* The \__SUBACK\__ and \__UNSUBACK\__ packets contain a list of one or more Reason Codes in the Payload. * The \__SUBACK\__ and \__UNSUBACK\__ packets contain a list of one or more Reason Codes in the Payload.
* *
* \see See \__REASON_CODES\__ for a complete list of all possible instances of this class. * \see See \__REASON_CODES\__ for a complete list of all possible instances of this class.
*/ */
class reason_code { class reason_code {
uint8_t _code; uint8_t _code;
@ -204,150 +204,150 @@ public:
namespace reason_codes { namespace reason_codes {
/** No Reason Code. A \ref client::error occurred.*/ /** \brief No Reason Code. A \ref client::error occurred.*/
constexpr reason_code empty {}; constexpr reason_code empty {};
/** The operation completed successfully. */ /** \brief The operation completed successfully. */
constexpr reason_code success { 0x00 }; constexpr reason_code success { 0x00 };
/** Close the connection normally. Do not send the Will Message. */ /** \brief Close the connection normally. Do not send the Will Message. */
constexpr reason_code normal_disconnection { 0x00, category::disconnect }; constexpr reason_code normal_disconnection { 0x00, category::disconnect };
/** The subscription is accepted with maximum QoS sent at 0. */ /** \brief The subscription is accepted with maximum QoS sent at 0. */
constexpr reason_code granted_qos_0 { 0x00, category::suback }; constexpr reason_code granted_qos_0 { 0x00, category::suback };
/** The subscription is accepted with maximum QoS sent at 1. */ /** \brief The subscription is accepted with maximum QoS sent at 1. */
constexpr reason_code granted_qos_1 { 0x01 }; constexpr reason_code granted_qos_1 { 0x01 };
/** The subscription is accepted with maximum QoS sent at 2 */ /** \brief The subscription is accepted with maximum QoS sent at 2 */
constexpr reason_code granted_qos_2 { 0x02 }; constexpr reason_code granted_qos_2 { 0x02 };
/** The Client wishes to disconnect but requires that /** \brief The Client wishes to disconnect but requires that
the Server also publishes its Will Message. */ the Server also publishes its Will Message. */
constexpr reason_code disconnect_with_will_message { 0x04 }; constexpr reason_code disconnect_with_will_message { 0x04 };
/** The message is accepted but there are no subscribers. */ /** \brief The message is accepted but there are no subscribers. */
constexpr reason_code no_matching_subscribers { 0x10 }; constexpr reason_code no_matching_subscribers { 0x10 };
/** No matching Topic Filter is being used by the Client. */ /** \brief No matching Topic Filter is being used by the Client. */
constexpr reason_code no_subscription_existed { 0x11 }; constexpr reason_code no_subscription_existed { 0x11 };
/** Continue the authentication with another step. */ /** \brief Continue the authentication with another step. */
constexpr reason_code continue_authentication { 0x18 }; constexpr reason_code continue_authentication { 0x18 };
/** Initiate a re-authentication. */ /** \brief Initiate a re-authentication. */
constexpr reason_code reauthenticate { 0x19 }; constexpr reason_code reauthenticate { 0x19 };
/** The Server does not wish to reveal the reason for the /** \brief The Server does not wish to reveal the reason for the
failure or none of the other Reason Codes apply. */ failure or none of the other Reason Codes apply. */
constexpr reason_code unspecified_error { 0x80 }; constexpr reason_code unspecified_error { 0x80 };
/** Data within the packet could not be correctly parsed. */ /** \brief Data within the packet could not be correctly parsed. */
constexpr reason_code malformed_packet { 0x81 }; constexpr reason_code malformed_packet { 0x81 };
/** Data in the packet does not conform to this specification. */ /** \brief Data in the packet does not conform to this specification. */
constexpr reason_code protocol_error { 0x82 }; constexpr reason_code protocol_error { 0x82 };
/** The packet is valid but not accepted by this Server. */ /** \brief The packet is valid but not accepted by this Server. */
constexpr reason_code implementation_specific_error { 0x83 }; constexpr reason_code implementation_specific_error { 0x83 };
/** The Server does not support the requested version of the MQTT protocol. */ /** \brief The Server does not support the requested version of the MQTT protocol. */
constexpr reason_code unsupported_protocol_version { 0x84 }; constexpr reason_code unsupported_protocol_version { 0x84 };
/** The Client ID is valid but not allowed by this Server. */ /** \brief The Client ID is valid but not allowed by this Server. */
constexpr reason_code client_identifier_not_valid { 0x85 }; constexpr reason_code client_identifier_not_valid { 0x85 };
/** The Server does not accept the User Name or Password provided. */ /** \brief The Server does not accept the User Name or Password provided. */
constexpr reason_code bad_username_or_password { 0x86 }; constexpr reason_code bad_username_or_password { 0x86 };
/** The request is not authorized. */ /** \brief The request is not authorized. */
constexpr reason_code not_authorized { 0x87 }; constexpr reason_code not_authorized { 0x87 };
/** The MQTT Server is not available. */ /** \brief The MQTT Server is not available. */
constexpr reason_code server_unavailable { 0x88 }; constexpr reason_code server_unavailable { 0x88 };
/** The MQTT Server is busy, try again later. */ /** \brief The MQTT Server is busy, try again later. */
constexpr reason_code server_busy { 0x89 }; constexpr reason_code server_busy { 0x89 };
/** The Client has been banned by administrative action. */ /** \brief The Client has been banned by administrative action. */
constexpr reason_code banned { 0x8a }; constexpr reason_code banned { 0x8a };
/** The Server is shutting down. */ /** \brief The Server is shutting down. */
constexpr reason_code server_shutting_down { 0x8b }; constexpr reason_code server_shutting_down { 0x8b };
/** The authentication method is not supported or /** \brief The authentication method is not supported or
does not match the method currently in use. */ does not match the method currently in use. */
constexpr reason_code bad_authentication_method { 0x8c }; constexpr reason_code bad_authentication_method { 0x8c };
/** No packet has been received for 1.5 times the Keepalive time. */ /** \brief No packet has been received for 1.5 times the Keepalive time. */
constexpr reason_code keep_alive_timeout { 0x8d }; constexpr reason_code keep_alive_timeout { 0x8d };
/** Another Connection using the same ClientID has connected /** \brief Another Connection using the same ClientID has connected
causing this Connection to be closed. */ causing this Connection to be closed. */
constexpr reason_code session_taken_over { 0x8e }; constexpr reason_code session_taken_over { 0x8e };
/** The Topic Filter is not malformed, but it is not accepted. */ /** \brief The Topic Filter is not malformed, but it is not accepted. */
constexpr reason_code topic_filter_invalid { 0x8f }; constexpr reason_code topic_filter_invalid { 0x8f };
/** The Topic Name is not malformed, but it is not accepted. */ /** \brief The Topic Name is not malformed, but it is not accepted. */
constexpr reason_code topic_name_invalid { 0x90 }; constexpr reason_code topic_name_invalid { 0x90 };
/** The Packet Identifier is already in use. */ /** \brief The Packet Identifier is already in use. */
constexpr reason_code packet_identifier_in_use { 0x91 }; constexpr reason_code packet_identifier_in_use { 0x91 };
/** The Packet Identifier is not known. */ /** \brief The Packet Identifier is not known. */
constexpr reason_code packet_identifier_not_found { 0x92 }; constexpr reason_code packet_identifier_not_found { 0x92 };
/** The Client or Server has received more than the Receive /** \brief The Client or Server has received more than the Receive
Maximum publication for which it has not sent PUBACK or PUBCOMP. */ Maximum publication for which it has not sent PUBACK or PUBCOMP. */
constexpr reason_code receive_maximum_exceeded { 0x93 }; constexpr reason_code receive_maximum_exceeded { 0x93 };
/** The Client or Server received a PUBLISH packet containing /** \brief The Client or Server received a PUBLISH packet containing
a Topic Alias greater than the Maximum Topic Alias. */ a Topic Alias greater than the Maximum Topic Alias. */
constexpr reason_code topic_alias_invalid { 0x94 }; constexpr reason_code topic_alias_invalid { 0x94 };
/** The packet exceeded the maximum permissible size. */ /** \brief The packet exceeded the maximum permissible size. */
constexpr reason_code packet_too_large { 0x95 }; constexpr reason_code packet_too_large { 0x95 };
/** The received data rate is too high. */ /** \brief The received data rate is too high. */
constexpr reason_code message_rate_too_high { 0x96 }; constexpr reason_code message_rate_too_high { 0x96 };
/** An implementation or administrative imposed limit has been exceeded. */ /** \brief An implementation or administrative imposed limit has been exceeded. */
constexpr reason_code quota_exceeded { 0x97 }; constexpr reason_code quota_exceeded { 0x97 };
/** The Connection is closed due to an administrative action. */ /** \brief The Connection is closed due to an administrative action. */
constexpr reason_code administrative_action { 0x98 }; constexpr reason_code administrative_action { 0x98 };
/** The Payload does not match the specified Payload Format Indicator. */ /** \brief The Payload does not match the specified Payload Format Indicator. */
constexpr reason_code payload_format_invalid { 0x99 }; constexpr reason_code payload_format_invalid { 0x99 };
/** The Server does not support retained messages. */ /** \brief The Server does not support retained messages. */
constexpr reason_code retain_not_supported { 0x9a }; constexpr reason_code retain_not_supported { 0x9a };
/** The Server does not support the QoS the Client specified or /** \brief The Server does not support the QoS the Client specified or
it is greater than the Maximum QoS specified. */ it is greater than the Maximum QoS specified. */
constexpr reason_code qos_not_supported { 0x9b }; constexpr reason_code qos_not_supported { 0x9b };
/** The Client should temporarily use another server. */ /** \brief The Client should temporarily use another server. */
constexpr reason_code use_another_server { 0x9c }; constexpr reason_code use_another_server { 0x9c };
/** The Client should permanently use another server. */ /** \brief The Client should permanently use another server. */
constexpr reason_code server_moved { 0x9d }; constexpr reason_code server_moved { 0x9d };
/** The Server does not support Shared Subscriptions for this Client. */ /** \brief The Server does not support Shared Subscriptions for this Client. */
constexpr reason_code shared_subscriptions_not_supported { 0x9e }; constexpr reason_code shared_subscriptions_not_supported { 0x9e };
/** The connection rate limit has been exceeded. */ /** \brief The connection rate limit has been exceeded. */
constexpr reason_code connection_rate_exceeded { 0x9f }; constexpr reason_code connection_rate_exceeded { 0x9f };
/** The maximum connection time authorized for this /** \brief The maximum connection time authorized for this
connection has been exceeded. */ connection has been exceeded. */
constexpr reason_code maximum_connect_time { 0xa0 }; constexpr reason_code maximum_connect_time { 0xa0 };
/** The Server does not support Subscription Identifiers. */ /** \brief The Server does not support Subscription Identifiers. */
constexpr reason_code subscription_ids_not_supported { 0xa1 }; constexpr reason_code subscription_ids_not_supported { 0xa1 };
/** The Server does not support Wildcard Subscriptions. */ /** \brief The Server does not support Wildcard Subscriptions. */
constexpr reason_code wildcard_subscriptions_not_supported { 0xa2 }; constexpr reason_code wildcard_subscriptions_not_supported { 0xa2 };
namespace detail { namespace detail {

53
include/boost/mqtt5/types.hpp
View File

@ -17,7 +17,7 @@
namespace boost::mqtt5 { namespace boost::mqtt5 {
/** An alias for `boost::system::error_code`. */ /// An alias for `boost::system::error_code`.
using error_code = boost::system::error_code; using error_code = boost::system::error_code;
/** /**
@ -25,13 +25,13 @@ using error_code = boost::system::error_code;
* such as the hostname, port, and path. * such as the hostname, port, and path.
*/ */
struct authority_path { struct authority_path {
/** The hostname of the authority as a domain name or an IP address. */ /** \brief The hostname of the authority as a domain name or an IP address. */
std::string host; std::string host;
/** The port number used for communication. */ /** \brief The port number used for communication. */
std::string port; std::string port;
/** Specifies the endpoint path relevant to WebSocket connections. */ /** \brief Specifies the endpoint path relevant to WebSocket connections. */
std::string path; std::string path;
}; };
@ -43,13 +43,13 @@ struct authority_path {
* from the sender to the receiver. * from the sender to the receiver.
*/ */
enum class qos_e : std::uint8_t { enum class qos_e : std::uint8_t {
/** The message arrives at the receiver either once or not at all. */ /** \brief The message arrives at the receiver either once or not at all. */
at_most_once = 0b00, at_most_once = 0b00,
/** Ensures the message arrives at the receiver at least once. */ /** \brief Ensures the message arrives at the receiver at least once. */
at_least_once = 0b01, at_least_once = 0b01,
/** All messages arrive at the receiver exactly once without /** \brief All messages arrive at the receiver exactly once without
loss or duplication of the messages. */ loss or duplication of the messages. */
exactly_once = 0b10 exactly_once = 0b10
}; };
@ -61,16 +61,15 @@ enum class qos_e : std::uint8_t {
* store the current message. * store the current message.
*/ */
enum class retain_e : std::uint8_t { enum class retain_e : std::uint8_t {
/** The Server will replace any existing retained message for this Topic /** \brief The Server will replace any existing retained message for this Topic
with this message. */ with this message. */
yes = 0b1, yes = 0b1,
/** The Server will not store this message and will not remove or replace /** \brief The Server will not store this message and will not remove or replace
any existing retained message. */ any existing retained message. */
no = 0b0 no = 0b0
}; };
enum class dup_e : std::uint8_t { enum class dup_e : std::uint8_t {
yes = 0b1, no = 0b0 yes = 0b1, no = 0b0
}; };
@ -79,15 +78,15 @@ enum class dup_e : std::uint8_t {
* \brief Represents the stage of \__ENHANCED_AUTH\__ process. * \brief Represents the stage of \__ENHANCED_AUTH\__ process.
*/ */
enum class auth_step_e { enum class auth_step_e {
/** The Client needs to send initial authentication data. */ /** \brief The Client needs to send initial authentication data. */
client_initial, client_initial,
/** Server responded with reason_codes.continue_authentication and possibly /** \brief Server responded with reason_codes.continue_authentication and possibly
* authentication data, the Client needs to send further authentication data. * authentication data, the Client needs to send further authentication data.
*/ */
server_challenge, server_challenge,
/** Server responded with reason_codes.success and final /** \brief Server responded with reason_codes.success and final
* authentication data, which the Client validates. * authentication data, which the Client validates.
*/ */
server_final server_final
@ -101,10 +100,10 @@ enum class auth_step_e {
* publishing connection. * publishing connection.
*/ */
enum class no_local_e : std::uint8_t { enum class no_local_e : std::uint8_t {
/** Application Messages can be forwarded to a connection with equal ClientID. */ /** \brief Application Messages can be forwarded to a connection with equal ClientID. */
no = 0b0, no = 0b0,
/** Application Messages MUST NOT be forwarded to a connection with equal ClientID. */ /** \brief Application Messages MUST NOT be forwarded to a connection with equal ClientID. */
yes = 0b1 yes = 0b1
}; };
@ -115,10 +114,10 @@ enum class no_local_e : std::uint8_t {
* using this subscription keep the \__RETAIN\__ flag they were published with. * using this subscription keep the \__RETAIN\__ flag they were published with.
*/ */
enum class retain_as_published_e : std::uint8_t { enum class retain_as_published_e : std::uint8_t {
/** Application Messages have the \__RETAIN\__ flag set to 0. */ /** \brief Application Messages have the \__RETAIN\__ flag set to 0. */
dont = 0b0, dont = 0b0,
/** Application Messages keep the \__RETAIN\__ flag they were published with. */ /** \brief Application Messages keep the \__RETAIN\__ flag they were published with. */
retain = 0b1 retain = 0b1
}; };
@ -129,13 +128,13 @@ enum class retain_as_published_e : std::uint8_t {
* when the subscription is established. * when the subscription is established.
*/ */
enum class retain_handling_e : std::uint8_t { enum class retain_handling_e : std::uint8_t {
/** Send retained messages at the time of subscribe. */ /** \brief Send retained messages at the time of subscribe. */
send = 0b00, send = 0b00,
/** Send retained message only if the subscription does not currently exist. */ /** \brief Send retained message only if the subscription does not currently exist. */
new_subscription_only = 0b01, new_subscription_only = 0b01,
/** Do not send retained messages at the time of subscribe. */ /** \brief Do not send retained messages at the time of subscribe. */
not_send = 0b10 not_send = 0b10
}; };
@ -143,16 +142,18 @@ enum class retain_handling_e : std::uint8_t {
* \brief Represents the \__SUBSCRIBE_OPTIONS\__ associated with each Subscription. * \brief Represents the \__SUBSCRIBE_OPTIONS\__ associated with each Subscription.
*/ */
struct subscribe_options { struct subscribe_options {
/// Maximum \__QOS\__ level at which the Server can send Application Messages to the Client. /** \brief Maximum \__QOS\__ level at which the Server can send Application Messages to the Client.
qos_e max_qos = qos_e::exactly_once; qos_e max_qos = qos_e::exactly_once;
/// Option determining if Application Messages will be forwarded to a connection with an equal ClientID. /** \brief Option determining if Application Messages will be
forwarded to a connection with an equal ClientID. */
no_local_e no_local = no_local_e::yes; no_local_e no_local = no_local_e::yes;
/// Option determining if Application Message will keep their \__RETAIN\__ flag. /** \brief Option determining if Application Message will keep their \__RETAIN\__ flag. */
retain_as_published_e retain_as_published = retain_as_published_e::retain; retain_as_published_e retain_as_published = retain_as_published_e::retain;
/// Option determining if retained messages are sent when the subscription is established. /** \brief Option determining if retained messages are sent
when the subscription is established. */
retain_handling_e retain_handling = retain_handling_e::new_subscription_only; retain_handling_e retain_handling = retain_handling_e::new_subscription_only;
}; };
@ -161,10 +162,10 @@ struct subscribe_options {
* Subscribe Options. * Subscribe Options.
*/ */
struct subscribe_topic { struct subscribe_topic {
/// An UTF-8 Encoded String indicating the Topics to which the Client wants to subscribe. /** \brief An UTF-8 Encoded String indicating the Topics to which the Client wants to subscribe. */
std::string topic_filter; std::string topic_filter;
/// The \ref subscribe_options associated with the subscription. /** \brief The \ref subscribe_options associated with the subscription. */
subscribe_options sub_opts; subscribe_options sub_opts;
}; };

24
index.html Normal file
View File

@ -0,0 +1,24 @@
<html>
<head>
<title>Boost.MQTT5</title>
<meta http-equiv="refresh" content="0; URL=./doc/html/index.html">
</head>
<body>
Automatic redirection failed, please go to
<a href="./doc/html/index.html">./doc/html/index.html</a>
<hr>
<tt>
Boost.MQTT5<br>
<br>
Copyright&nbsp;(C)&nbsp;2025&nbsp;Ivica&nbsp;Siladic,&nbsp;Bruno&nbsp;Iljazovic,&nbsp;Korina&nbsp;Simicevic<br>
<br>
Distributed under the Boost Software License, Version 1.0.
(See accompanying file LICENSE_1_0.txt or copy at
<a href=http://www.boost.org/LICENSE_1_0.txt>http://www.boost.org/LICENSE_1_0.txt</a>) <br>
<br>
</tt>
</body>
</html>

15
meta/libraries.json Normal file
View File

@ -0,0 +1,15 @@
{
"key": "mqtt5",
"name": "MQTT5",
"authors": [
"Ivica Siladić",
"Bruno Iljazović",
"Korina Šimičević"
],
"description": "MQTT5 client library built on top of Boost.Asio.",
"category": [
"Concurrent",
"IO"
],
"cxxstd": "17"
}

6
test/include/test_common/test_broker.hpp
View File

@ -195,7 +195,7 @@ public:
delayed_op<error_code>(ex, 0ms, error_code {}); delayed_op<error_code>(ex, 0ms, error_code {});
async_delay( async_delay(
make_cancel_slot(), std::move(complete_op), make_cancel_slot(), std::move(complete_op),
asio::prepend( asio::prepend(
std::ref(*this), on_delayed_complete {}, std::ref(*this), on_delayed_complete {},
std::move(handler), bytes_written std::move(handler), bytes_written
@ -207,7 +207,7 @@ public:
for (auto& op : reply_action->pop_reply_ops(ex)) for (auto& op : reply_action->pop_reply_ops(ex))
async_delay( async_delay(
make_cancel_slot(), std::move(op), make_cancel_slot(), std::move(op),
asio::prepend(std::ref(*this), on_receive {}) asio::prepend(std::ref(*this), on_receive {})
); );
}; };
@ -314,7 +314,7 @@ private:
_cancel_signals.erase( _cancel_signals.erase(
std::remove_if( std::remove_if(
_cancel_signals.begin(), _cancel_signals.end(), _cancel_signals.begin(), _cancel_signals.end(),
[](auto& sig_ptr) { return !sig_ptr->slot().has_handler(); } [](auto& sig_ptr) { return !sig_ptr->slot().has_handler(); }
), ),
_cancel_signals.end() _cancel_signals.end()
); );