boostorg/mqtt5
1
0
Fork 1
mirror of https://github.com/boostorg/mqtt5.git synced 2025-08-02 14:04:36 +02:00
Code Issues Packages Projects Releases Wiki Activity

[mqtt-client] A lot of various document changes

Browse Source 
Summary:
related to T12804

- property files are now lowercase and match code names

- properties properly link to their pages

- packet names do not automatically link anymore

- TlsContext documented

- types inside handler signatures properly link to their pages

next up: better error code documentation

Reviewers: ivica

Reviewed By: ivica

Subscribers: miljen, iljazovic

Differential Revision: https://repo.mireo.local/D26155
This commit is contained in:
Korina Šimičević
2023-10-18 12:16:05 +02:00
parent 402b8bf0b1
commit 62d7eb21b2
24 changed files with 248 additions and 189 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
doc/Jamfile
View File

@@ -40,6 +40,7 @@ import ../../../../3rdParty/boost-doc/docca/docca.jam ;
local doxygen_exclussions = local doxygen_exclussions =
detail detail
impl impl
property_types.hpp
; ;
docca.reference reference.qbk docca.reference reference.qbk

83
doc/qbk/00_main.qbk
View File

@@ -37,25 +37,48 @@
[def __Asio__ [@boost:/libs/asio/index.html Boost.Asio]] [def __Asio__ [@boost:/libs/asio/index.html Boost.Asio]]
[def __Self__ [async_mqtt5]] [def __Self__ [async_mqtt5]]
[/ MQTT stuff] [/ MQTT ]
[def __MQTT__ [@https://mqtt.org/ MQTT]] [def __MQTT__ [@https://mqtt.org/ MQTT]]
[def __UTF8_STRING_PAIR__ [mqttlink 3901013 `UTF-8 String Pair`]] [def __UTF8_STRING_PAIR__ [mqttlink 3901013 `UTF-8 String Pair`]]
[def __PACKET_SIZE__ [mqttlink 3901024 `packet size`]] [def __PACKET_SIZE__ [mqttlink 3901024 `packet size`]]
[def CONNECT [mqttlink 3901033 `CONNECT`]]
[def CONNACK [mqttlink 3901074 `CONNACK`]] [def __QOS__ [mqttlink 3901234 `QoS`]]
[def PUBLISH [mqttlink 3901100 `PUBLISH`]] [def __SUBSCRIBE_OPTIONS__ [mqttlink 3901169 `Subscribe Options`]]
[def PUBACK [mqttlink 3901121 `PUBACK`]]
[def PUBREC [mqttlink 3901131 `PUBREC`]] [def __CONNECT__ [mqttlink 3901033 `CONNECT`]]
[def PUBREL [mqttlink 3901141 `PUBREL`]] [def __CONNACK__ [mqttlink 3901074 `CONNACK`]]
[def PUBCOMP [mqttlink 3901151 `PUBCOMP`]] [def __PUBLISH__ [mqttlink 3901100 `PUBLISH`]]
[def SUBSCRIBE [mqttlink 3901161 `SUBSCRIBE`]] [def __PUBACK__ [mqttlink 3901121 `PUBACK`]]
[def SUBACK [mqttlink 3901171 `SUBACK`]] [def __PUBREC__ [mqttlink 3901131 `PUBREC`]]
[def UNSUBSCRIBE [mqttlink 3901179 `UNSUBSCRIBE`]] [def __PUBREL__ [mqttlink 3901141 `PUBREL`]]
[def UNSUBACK [mqttlink 3901187 `UNSUBACK`]] [def __PUBCOMP__ [mqttlink 3901151 `PUBCOMP`]]
[def PINGREQ [mqttlink 3901195 `PINGREQ`]] [def __SUBSCRIBE__ [mqttlink 3901161 `SUBSCRIBE`]]
[def PINGRESP [mqttlink 3901200 `PINGRESP`]] [def __SUBACK__ [mqttlink 3901171 `SUBACK`]]
[def DISCONNECT [mqttlink 3901205 `DISCONNECT`]] [def __UNSUBSCRIBE__ [mqttlink 3901179 `UNSUBSCRIBE`]]
[def AUTH [mqttlink 3901217 `AUTH`]] [def __UNSUBACK__ [mqttlink 3901187 `UNSUBACK`]]
[def __PINGREQ__ [mqttlink 3901195 `PINGREQ`]]
[def __PINGRESP__ [mqttlink 3901200 `PINGRESP`]]
[def __DISCONNECT__ [mqttlink 3901205 `DISCONNECT`]]
[def __AUTH__ [mqttlink 3901217 `AUTH`]]
[def __WILL_PROPS__ [reflink2 will_props async_mqtt5::will_props]]
[def __CONNECT_PROPS__ [reflink2 connect_props async_mqtt5::connect_props]]
[def __CONNACK_PROPS__ [reflink2 connack_props async_mqtt5::connack_props]]
[def __PUBLISH_PROPS__ [reflink2 publish_props async_mqtt5::publish_props]]
[def __PUBACK_PROPS__ [reflink2 puback_props async_mqtt5::puback_props]]
[def __PUBREC_PROPS__ [reflink2 pubrec_props async_mqtt5::pubrec_props]]
[def __PUBREL_PROPS__ [reflink2 pubrel_props async_mqtt5::pubrel_props]]
[def __PUBCOMP_PROPS__ [reflink2 pubcomp_props async_mqtt5::pubcomp_props]]
[def __SUBSCRIBE_PROPS__ [reflink2 subscribe_props async_mqtt5::subscribe_props]]
[def __SUBACK_PROPS__ [reflink2 suback_props async_mqtt5::suback_props]]
[def __UNSUBSCRIBE_PROPS__ [reflink2 unsubscribe_props async_mqtt5::unsubscribe_props]]
[def __UNSUBACK_PROPS__ [reflink2 unsuback_props async_mqtt5::unsuback_props]]
[def __DISCONNECT_PROPS__ [reflink2 disconnect_props async_mqtt5::disconnect_props]]
[def __AUTH_PROPS__ [reflink2 auth_props async_mqtt5::auth_props]]
[def __ERROR_CODE__ [reflink2 error_code `async_mqtt5::error_code`]]
[def __REASON_CODE__ [reflink2 Reason_codes `async_mqtt5::reason_code`]]
[include 01_intro.qbk] [include 01_intro.qbk]
@@ -70,20 +93,20 @@
[include reference/reason_codes/Reason_codes.qbk] [include reference/reason_codes/Reason_codes.qbk]
[include reference/properties/CONNECT_props.qbk] [include reference/properties/will_props.qbk]
[include reference/properties/CONNACK_props.qbk] [include reference/properties/connect_props.qbk]
[include reference/properties/Will_props.qbk] [include reference/properties/connack_props.qbk]
[include reference/properties/PUBLISH_props.qbk] [include reference/properties/publish_props.qbk]
[include reference/properties/PUBACK_props.qbk] [include reference/properties/puback_props.qbk]
[include reference/properties/PUBREC_props.qbk] [include reference/properties/pubrec_props.qbk]
[include reference/properties/PUBREL_props.qbk] [include reference/properties/pubrel_props.qbk]
[include reference/properties/PUBCOMP_props.qbk] [include reference/properties/pubcomp_props.qbk]
[include reference/properties/SUBSCRIBE_props.qbk] [include reference/properties/subscribe_props.qbk]
[include reference/properties/SUBACK_props.qbk] [include reference/properties/suback_props.qbk]
[include reference/properties/UNSUBSCRIBE_props.qbk] [include reference/properties/unsubscribe_props.qbk]
[include reference/properties/UNSUBACK_props.qbk] [include reference/properties/unsuback_props.qbk]
[include reference/properties/DISCONNECT_props.qbk] [include reference/properties/disconnect_props.qbk]
[include reference/properties/AUTH_props.qbk] [include reference/properties/auth_props.qbk]
[block'''</part>'''] [block'''</part>''']
[endsect] [endsect]

3
doc/qbk/reference/TlsContext.qbk
View File

@@ -7,7 +7,8 @@
[section:async_mqtt5__TlsContext TlsContext concept] [section:async_mqtt5__TlsContext TlsContext concept]
// TODO `TlsContext` represents an object that defines user's configuration
for establishing TLS/SSL connections.
The type [asioreflink ssl__context ssl::context] meets these requirements. The type [asioreflink ssl__context ssl::context] meets these requirements.

6
doc/qbk/reference/properties/AUTH_props.qbk → doc/qbk/reference/properties/auth_props.qbk
View File

@@ -5,12 +5,12 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
] ]
[section:async_mqtt5__AUTH_props AUTH properties] [section:async_mqtt5__auth_props AUTH properties]
The last field in the Variable header of AUTH packet is a set of Properties. The last field in the Variable header of __AUTH__ packet is a set of Properties.
A set contains a Property Length followed by the Properties. A set contains a Property Length followed by the Properties.
A Property consists of an Identifier and a value. 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]]

10
doc/qbk/reference/properties/CONNACK_props.qbk → doc/qbk/reference/properties/connack_props.qbk
View File

@@ -5,12 +5,12 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
] ]
[section:async_mqtt5__CONNACK_props CONNACK properties] [section:async_mqtt5__connack_props CONNACK properties]
The last field in the Variable header of CONNACK packet is a set of Properties. The last field in the Variable header of __CONNACK__ packet is a set of Properties.
A set contains a Property Length followed by the Properties. A set contains a Property Length followed by the Properties.
A Property consists of an Identifier and a value. 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]]
@@ -18,8 +18,8 @@ This section lists all possible CONNACK Properties and describes their usage:
[[receive_maximum] [`int16_t`] [The maximum number of QoS 1 and QoS 2 publications that the Server is willing to process concurrently.]] [[receive_maximum] [`int16_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] [`int32_t`] [The maximum __PACKET_SIZE__ in bytes that the Server is willing to accept.]] [[maximum_packet_size] [`int32_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.]]
[[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.]]

15
doc/qbk/reference/properties/CONNECT_props.qbk → doc/qbk/reference/properties/connect_props.qbk
View File

@@ -5,22 +5,23 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
] ]
[section:async_mqtt5__CONNECT_props CONNECT properties] [section:async_mqtt5__connect_props CONNECT properties]
The last field in the Variable header of CONNECT packet is a set of Properties. The last field in the Variable header of __CONNECT__ packet is a set of Properties.
A set contains a Property Length followed by the Properties. A set contains a Property Length followed by the Properties.
A Property consists of an Identifier and a value. 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] [`int32_t`] [Represents the Session Expiry Internal in seconds.]] [[session_expiry_interval] [`int32_t`] [Represents the Session Expiry Internal in seconds.]]
[[receive_maximum] [`int16_t`] [The maximum number of QoS 1 and QoS 2 publications that the Client is willing to process concurrently.]] [[receive_maximum] [`int16_t`] [The maximum number of QoS 1 and QoS 2 publications that the Client is willing to process concurrently.]]
[[maximum_packet_size] [`int32_t`] [The maximum __PACKET_SIZE__ in bytes that the Client is willing to process.]] [[maximum_packet_size] [`int32_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. If the value is 1, the Server MAY return a Reason String or User Properties where it is allowed.]] 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.]]
[[user_property] [`std::vector<std::string>`] [A list of name, value pairs (__UTF8_STRING_PAIR__) defining User Properties. [[user_property] [`std::vector<std::string>`] [A list of name, value pairs (__UTF8_STRING_PAIR__) defining User Properties.
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.]]

6
doc/qbk/reference/properties/DISCONNECT_props.qbk → doc/qbk/reference/properties/disconnect_props.qbk
View File

@@ -5,12 +5,12 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
] ]
[section:async_mqtt5__DISCONNECT_props DISCONNECT properties] [section:async_mqtt5__disconnect_props DISCONNECT properties]
The last field in the Variable header of DISCONNECT packet is a set of Properties. The last field in the Variable header of __DISCONNECT__ packet is a set of Properties.
A set contains a Property Length followed by the Properties. A set contains a Property Length followed by the Properties.
A Property consists of an Identifier and a value. 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]]

6
doc/qbk/reference/properties/PUBACK_props.qbk → doc/qbk/reference/properties/puback_props.qbk
View File

@@ -5,12 +5,12 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
] ]
[section:async_mqtt5__PUBACK_props PUBACK properties] [section:async_mqtt5__puback_props PUBACK properties]
The last field in the Variable header of PUBACK packet is a set of Properties. The last field in the Variable header of __PUBACK__ packet is a set of Properties.
A set contains a Property Length followed by the Properties. A set contains a Property Length followed by the Properties.
A Property consists of an Identifier and a value. 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]]

6
doc/qbk/reference/properties/PUBCOMP_props.qbk → doc/qbk/reference/properties/pubcomp_props.qbk
View File

@@ -5,12 +5,12 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
] ]
[section:async_mqtt5__PUBCOMP_props PUBCOMP properties] [section:async_mqtt5__pubcomp_props PUBCOMP properties]
The last field in the Variable header of PUBCOMP packet is a set of Properties. The last field in the Variable header of __PUBCOMP__ packet is a set of Properties.
A set contains a Property Length followed by the Properties. A set contains a Property Length followed by the Properties.
A Property consists of an Identifier and a value. 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:pubrec_props PUBCOMP properties [table:pubrec_props PUBCOMP properties
[[Identifier] [Value type] [Description]] [[Identifier] [Value type] [Description]]

6
doc/qbk/reference/properties/PUBLISH_props.qbk → doc/qbk/reference/properties/publish_props.qbk
View File

@@ -5,12 +5,12 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
] ]
[section:async_mqtt5__PUBLISH_props PUBLISH properties] [section:async_mqtt5__publish_props PUBLISH properties]
The last field in the Variable header of PUBLISH packet is a set of Properties. The last field in the Variable header of __PUBLISH__ packet is a set of Properties.
A set contains a Property Length followed by the Properties. A set contains a Property Length followed by the Properties.
A Property consists of an Identifier and a value. 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]]

6
doc/qbk/reference/properties/PUBREC_props.qbk → doc/qbk/reference/properties/pubrec_props.qbk
View File

@@ -5,12 +5,12 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
] ]
[section:async_mqtt5__PUBREC_props PUBREC properties] [section:async_mqtt5__pubrec_props PUBREC properties]
The last field in the Variable header of PUBREC packet is a set of Properties. The last field in the Variable header of __PUBREC__ packet is a set of Properties.
A set contains a Property Length followed by the Properties. A set contains a Property Length followed by the Properties.
A Property consists of an Identifier and a value. 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]]

6
doc/qbk/reference/properties/PUBREL_props.qbk → doc/qbk/reference/properties/pubrel_props.qbk
View File

@@ -5,12 +5,12 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
] ]
[section:async_mqtt5__PUBREL_props PUBREL properties] [section:async_mqtt5__pubrel_props PUBREL properties]
The last field in the Variable header of PUBREL packet is a set of Properties. The last field in the Variable header of __PUBREL__ packet is a set of Properties.
A set contains a Property Length followed by the Properties. A set contains a Property Length followed by the Properties.
A Property consists of an Identifier and a value. 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:pubrec_props PUBREL properties [table:pubrec_props PUBREL properties
[[Identifier] [Value type] [Description]] [[Identifier] [Value type] [Description]]

6
doc/qbk/reference/properties/SUBACK_props.qbk → doc/qbk/reference/properties/suback_props.qbk
View File

@@ -5,12 +5,12 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
] ]
[section:async_mqtt5__SUBACK_props SUBACK properties] [section:async_mqtt5__suback_props SUBACK properties]
The last field in the Variable header of SUBACK packet is a set of Properties. The last field in the Variable header of __SUBACK__ packet is a set of Properties.
A set contains a Property Length followed by the Properties. A set contains a Property Length followed by the Properties.
A Property consists of an Identifier and a value. 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]]

6
doc/qbk/reference/properties/SUBSCRIBE_props.qbk → doc/qbk/reference/properties/subscribe_props.qbk
View File

@@ -5,12 +5,12 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
] ]
[section:async_mqtt5__SUBSCRIBE_props SUBSCRIBE properties] [section:async_mqtt5__subscribe_props SUBSCRIBE properties]
The last field in the Variable header of SUBSCRIBE packet is a set of Properties. The last field in the Variable header of __SUBSCRIBE__ packet is a set of Properties.
A set contains a Property Length followed by the Properties. A set contains a Property Length followed by the Properties.
A Property consists of an Identifier and a value. 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]]

6
doc/qbk/reference/properties/UNSUBACK_props.qbk → doc/qbk/reference/properties/unsuback_props.qbk
View File

@@ -5,12 +5,12 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
] ]
[section:async_mqtt5__UNSUBACK_props UNSUBACK properties] [section:async_mqtt5__unsuback_props UNSUBACK properties]
The last field in the Variable header of UNSUBACK packet is a set of Properties. The last field in the Variable header of __UNSUBACK__ packet is a set of Properties.
A set contains a Property Length followed by the Properties. A set contains a Property Length followed by the Properties.
A Property consists of an Identifier and a value. 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]]

6
doc/qbk/reference/properties/UNSUBSCRIBE_props.qbk → doc/qbk/reference/properties/unsubscribe_props.qbk
View File

@@ -5,12 +5,12 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
] ]
[section:async_mqtt5__UNSUBSCRIBE_props UNSUBSCRIBE properties] [section:async_mqtt5__unsubscribe_props UNSUBSCRIBE properties]
The last field in the Variable header of UNSUBSCRIBE packet is a set of Properties. The last field in the Variable header of __UNSUBSCRIBE__ packet is a set of Properties.
A set contains a Property Length followed by the Properties. A set contains a Property Length followed by the Properties.
A Property consists of an Identifier and a value. 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]]

7
doc/qbk/reference/properties/Will_props.qbk → doc/qbk/reference/properties/will_props.qbk
View File

@@ -5,12 +5,13 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
] ]
[section:async_mqtt5__Will_props [reflink2 will Will] properties] [section:async_mqtt5__will_props Will properties]
The Will Properties consist of the properties that determine when to publish the Will Message and the Application Message properties to be sent with the Will Message. The Will Properties consist of the properties that determine when to publish the [reflink2 will Will] Message
and the Application Message properties to be sent with the [reflink2 will Will] Message.
The Will Properties consists of a Property Length and the Properties. The Will Properties consists of a Property Length and the Properties.
A Property consists of an Identifier and a value. A Property consists of an Identifier and a value.
This section lists all possible 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]]

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

@@ -56,20 +56,20 @@
<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.async_mqtt5__Will_props">Will properties</link></member> <member><link linkend="async_mqtt5.ref.async_mqtt5__will_props">will_props</link></member>
<member><link linkend="async_mqtt5.ref.async_mqtt5__CONNECT_props">CONNECT properties</link></member> <member><link linkend="async_mqtt5.ref.async_mqtt5__connect_props">connect_props</link></member>
<member><link linkend="async_mqtt5.ref.async_mqtt5__CONNACK_props">CONNACK properties</link></member> <member><link linkend="async_mqtt5.ref.async_mqtt5__connack_props">connack_props</link></member>
<member><link linkend="async_mqtt5.ref.async_mqtt5__PUBLISH_props">PUBLISH properties</link></member> <member><link linkend="async_mqtt5.ref.async_mqtt5__publish_props">publish_props</link></member>
<member><link linkend="async_mqtt5.ref.async_mqtt5__PUBACK_props">PUBACK properties</link></member> <member><link linkend="async_mqtt5.ref.async_mqtt5__puback_props">puback_props</link></member>
<member><link linkend="async_mqtt5.ref.async_mqtt5__PUBREC_props">PUBREC properties</link></member> <member><link linkend="async_mqtt5.ref.async_mqtt5__pubrec_props">pubrec_props</link></member>
<member><link linkend="async_mqtt5.ref.async_mqtt5__PUBREL_props">PUBREL properties</link></member> <member><link linkend="async_mqtt5.ref.async_mqtt5__pubrel_props">pubrel_props</link></member>
<member><link linkend="async_mqtt5.ref.async_mqtt5__PUBCOMP_props">PUBCOMP properties</link></member> <member><link linkend="async_mqtt5.ref.async_mqtt5__pubcomp_props">pubcomp_props</link></member>
<member><link linkend="async_mqtt5.ref.async_mqtt5__SUBSCRIBE_props">SUBSCRIBE properties</link></member> <member><link linkend="async_mqtt5.ref.async_mqtt5__subscribe_props">subscribe_props</link></member>
<member><link linkend="async_mqtt5.ref.async_mqtt5__SUBACK_props">SUBACK properties</link></member> <member><link linkend="async_mqtt5.ref.async_mqtt5__suback_props">suback_props</link></member>
<member><link linkend="async_mqtt5.ref.async_mqtt5__UNSUBSCRIBE_props">UNSUBSCRIBE properties</link></member> <member><link linkend="async_mqtt5.ref.async_mqtt5__unsubscribe_props">unsubscribe_props</link></member>
<member><link linkend="async_mqtt5.ref.async_mqtt5__UNSUBACK_props">UNSUBACK properties</link></member> <member><link linkend="async_mqtt5.ref.async_mqtt5__unsuback_props">unsuback_props</link></member>
<member><link linkend="async_mqtt5.ref.async_mqtt5__DISCONNECT_props">DISCONNECT properties</link></member> <member><link linkend="async_mqtt5.ref.async_mqtt5__disconnect_props">disconnect_props</link></member>
<member><link linkend="async_mqtt5.ref.async_mqtt5__AUTH_props">AUTH properties</link></member> <member><link linkend="async_mqtt5.ref.async_mqtt5__auth_props">auth_props</link></member>
</simplelist> </simplelist>
</entry> </entry>
</row></tbody> </row></tbody>

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

@@ -8,7 +8,7 @@
[section:async_mqtt5__Reason_codes Reason codes] [section:async_mqtt5__Reason_codes Reason codes]
This section lists all possible reason codes that can be sent in a This section lists all possible [reflink2 reason_code reason codes] that can be sent in a
MQTT Control Packet. MQTT Control Packet.
[xinclude rcref.xml] [xinclude rcref.xml]

1
doc/xsl/custom-overrides.xsl
View File

@@ -28,6 +28,7 @@
<xsl:variable name="emphasized-template-parameter-types" select=" <xsl:variable name="emphasized-template-parameter-types" select="
'CompletionToken',
'ExecutionContext', 'ExecutionContext',
'StreamType', 'StreamType',
'TlsContext' 'TlsContext'

28
include/async_mqtt5/error.hpp
View File

@@ -7,18 +7,19 @@
#include <boost/asio/error.hpp> #include <boost/asio/error.hpp>
namespace async_mqtt5 { namespace async_mqtt5 {
/** /**
* \brief A representation of Disconnect Reason Code. * \brief A representation of Disconnect Reason Code.
* *
* \details Represents all Reason Codes that the Client can send to the Server * \details Represents all Reason Codes that the Client can send to the Server
* 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 : std::uint8_t { enum class disconnect_rc_e : std::uint8_t {
/** Close the connection normally. Do not send the \ref will Message. */ /** Close the connection normally. Do not send the Will Message. */
normal_disconnection = 0x00, normal_disconnection = 0x00,
/** The Client wishes to disconnect but requires that /** The Client wishes to disconnect but requires that
the Server also publishes its \ref will Message. */ the Server also publishes its Will Message. */
disconnect_with_will_message = 0x04, disconnect_with_will_message = 0x04,
// TODO: these reason codes should not be available to the user, only the client // TODO: these reason codes should not be available to the user, only the client
@@ -103,11 +104,13 @@ struct client_ec_category : public boost::system::error_category {
} }
}; };
/// Returns the error category associated with \ref client::error.
inline const client_ec_category& get_error_code_category() { inline const client_ec_category& get_error_code_category() {
static client_ec_category cat; static client_ec_category cat;
return cat; return cat;
} }
/// Creates an \ref error_code from a \ref client::error.
inline boost::system::error_code make_error_code(error r) { inline boost::system::error_code make_error_code(error r) {
return { static_cast<int>(r), get_error_code_category() }; return { static_cast<int>(r), get_error_code_category() };
} }
@@ -115,6 +118,7 @@ inline boost::system::error_code make_error_code(error r) {
} // end namespace client } // end namespace client
/// \cond internal
namespace reason_codes { namespace reason_codes {
enum class category : uint8_t { enum class category : uint8_t {
@@ -124,24 +128,26 @@ enum class category : uint8_t {
unsuback, auth, disconnect unsuback, auth, disconnect
}; };
} // end namespace reason_codes } // end namespace reason_codes
/// \endcond
/** /**
* \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 and AUTH Control Packets have a single Reason Code as part of the Variable Header. * The \__CONNACK\__, \__PUBACK\__, \__PUBREC\__, \__PUBREL\__, \__PUBCOMP\__, \__DISCONNECT\__
* The SUBACK and UNSUBACK packets contain a list of one or more Reason Codes in the Payload. * 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.
*/ */
class reason_code { class reason_code {
uint8_t _code; uint8_t _code;
reason_codes::category _category { reason_codes::category::none }; reason_codes::category _category { reason_codes::category::none };
public: public:
/// @cond INTERNAL /// \cond INTERNAL
constexpr reason_code() : _code(0xff) {} constexpr reason_code() : _code(0xff) {}
constexpr reason_code(uint8_t code, reason_codes::category cat) constexpr reason_code(uint8_t code, reason_codes::category cat)
@@ -149,7 +155,7 @@ public:
{} {}
constexpr reason_code(uint8_t code) : _code(code) {} constexpr reason_code(uint8_t code) : _code(code) {}
/// @endcond /// \endcond
/// Copy constructor. /// Copy constructor.
reason_code(const reason_code&) = default; reason_code(const reason_code&) = default;

1
include/async_mqtt5/impl/disconnect_op.hpp
View File

@@ -86,6 +86,7 @@ public:
ec == asio::error::operation_aborted || ec == asio::error::operation_aborted ||
ec == asio::error::no_recovery ec == asio::error::no_recovery
) )
// TODO: do we need two different errors here?
return complete(ec); return complete(ec);
if (_context.terminal) { if (_context.terminal) {

177
include/async_mqtt5/mqtt_client.hpp
View File

@@ -17,7 +17,7 @@ namespace async_mqtt5 {
namespace asio = boost::asio; namespace asio = boost::asio;
/** /**
* \brief MQTT client used to connect and communicate with a Broker. * \brief \__MQTT\__ client used to connect and communicate with a Broker.
* *
* \tparam StreamType Type of the underlying transport protocol used to transfer * \tparam StreamType Type of the underlying transport protocol used to transfer
* the stream of bytes between the Client and the Broker. The transport must be * the stream of bytes between the Client and the Broker. The transport must be
@@ -71,7 +71,9 @@ public:
* \param tls_context A context object used in TLS/SLL connection. * \param tls_context A context object used in TLS/SLL connection.
* *
* \par Precondition * \par Precondition
* `std::is_convertible_v<ExecutionContext&, asio::execution_context&>` * \code
* std::is_convertible_v<ExecutionContext&, asio::execution_context&>
* \endcode
*/ */
template <typename ExecutionContext> template <typename ExecutionContext>
requires (std::is_convertible_v<ExecutionContext&, asio::execution_context&>) requires (std::is_convertible_v<ExecutionContext&, asio::execution_context&>)
@@ -103,8 +105,14 @@ public:
/** /**
* \brief Get the context object used in TLS/SSL connection. * \brief Get the context object used in TLS/SSL connection.
* *
* \note This function may only be invoked
* when the template parameter \__TlsContext\__ was configured
* with non-default type during the creation of a \ref mqtt_client.
*
* \par Precondition * \par Precondition
* `!std::is_same_v<TlsContext, std::monostate>`. * \code
* !std::is_same_v<TlsContext, std::monostate>
* \endcode
*/ */
decltype(auto) tls_context() decltype(auto) tls_context()
requires (!std::is_same_v<TlsContext, std::monostate>) { requires (!std::is_same_v<TlsContext, std::monostate>) {
@@ -124,10 +132,12 @@ public:
// TODO: channel cancel // TODO: channel cancel
/** /**
* \brief Cancel all asynchronous operations. * \brief Cancel all asynchronous operations. This function has terminal effects.
* *
* \details All outstanding operations will complete * \details All outstanding operations will complete
* with `boost::asio::error::operation_aborted`. * with `boost::asio::error::operation_aborted`.
*
* \note The Client cannot be used before calling \ref mqtt_client::run again.
*/ */
void cancel() { void cancel() {
get_executor().execute([svc_ptr = _svc_ptr]() { get_executor().execute([svc_ptr = _svc_ptr]() {
@@ -167,15 +177,25 @@ public:
/** /**
* \brief Assign a list of Brokers that the Client will attempt to connect to. * \brief Assign a list of Brokers that the Client will attempt to connect to.
* *
* \details The Client will cycle through the list of hosts,
* attempting to establish a connection with each
* until it successfully establishes a connection.
*
* \param hosts List of Broker addresses and ports. * \param hosts List of Broker addresses and ports.
* Address and ports are separated with a colon `:` while * Address and ports are separated with a colon `:` while
* pairs of addresses and ports are separated with a comma `,`. * pairs of addresses and ports are separated with a comma `,`.
* \param default_port Default port to connect to in case the port is not * \param default_port Default port to connect to in case the port is not
* explicitly specified in the hosts list. * explicitly specified in the hosts list.
* *
* \details Examples of a valid hosts string:\n *
* - broker1:1883, broker2, broker3:1883\n * \par Example
* - broker1 * Some valid hosts string:
*
* \code
* std::string valid_hosts_1 = "broker1:1883, broker2, broker3:1883";
* std::string valid_hosts_2 = "broker1";
* \endcode
*
*/ */
mqtt_client& brokers(std::string hosts, uint16_t default_port = 1883) { mqtt_client& brokers(std::string hosts, uint16_t default_port = 1883) {
_svc_ptr->brokers(std::move(hosts), default_port); _svc_ptr->brokers(std::move(hosts), default_port);
@@ -183,9 +203,8 @@ public:
} }
// TODO: doc props
/** /**
* \brief Send a PUBLISH packet to Broker to transport an * \brief Send a \__PUBLISH\__ packet to Broker to transport an
* Application Message. * Application Message.
* *
* \tparam qos_type The \ref qos_e level of assurance for delivery. * \tparam qos_type The \ref qos_e level of assurance for delivery.
@@ -193,35 +212,35 @@ public:
* Payload data is published. * Payload data is published.
* \param payload The Application Message that is being published. * \param payload The Application Message that is being published.
* \param retain The \ref retain_e flag. * \param retain The \ref retain_e flag.
* \param props PUBLISH properties. * \param props An instance of \__PUBLISH_PROPS\__.
* \param token Completion token that will be used to produce a * \param token Completion token that will be used to produce a
* completion handler, which will be called when the operation completed. * completion handler, which will be called when the operation completed.
* *
* \par Completion signature * \par Handler signature
* The completion 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_e::at_most_once`: * - `qos_e::at_most_once`:
* \code * \code
* void ( * void (
* boost::system::error_code // Result of operation * __ERROR_CODE__ // Result of operation
* ) * )
* \endcode * \endcode
* *
* - `qos_e::at_least_once`: * - `qos_e::at_least_once`:
* \code * \code
* void ( * void (
* boost::system::error_code, // Result of operation. * __ERROR_CODE__, // Result of operation.
* async_mqtt5::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_e::exactly_once`: * - `qos_e::exactly_once`:
* \code * \code
* void ( * void (
* boost::system::error_code, // Result of operation. * __ERROR_CODE__, // Result of operation.
* async_mqtt5::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
* *
@@ -264,28 +283,28 @@ public:
// TODO: perhaps there is a way to not copy documentation (\copybrief, \copydetails) // TODO: perhaps there is a way to not copy documentation (\copybrief, \copydetails)
/** /**
* \brief Send a SUBSCRIBE packet to Broker to create a subscription * \brief Send a \__SUBSCRIBE\__ packet to Broker to create a subscription
* to one or more Topics of interest. * to one or more Topics of interest.
* *
* \details After the subscription has been established, the Broker will send * \details After the subscription has been established, the Broker will send
* PUBLISH packets to the Client to forward Application Messages that were published * PUBLISH packets to the Client to forward Application Messages that were published
* to Topics that the Client subscribed to. The PUBLISH packets can be received * to Topics that the Client subscribed to. The \__PUBLISH\__ packets can be received
* with \ref mqtt_client::async_receive function. * with \ref mqtt_client::async_receive function.
* *
* \param topics A list of \ref subscribe_topic of interest. * \param topics A list of \ref subscribe_topic of interest.
* \param props SUBSCRIBE properties. * \param props An instance of \__SUBSCRIBE_PROPS\__.
* \param token Completion token that will be used to produce a * \param token Completion token that will be used to produce a
* completion handler, which will be called when the operation completed. * completion handler, which will be called when the operation completed.
* *
* \par Completion signature * \par Handler signature
* The completion signature for this operation: * The handler signature for this operation:
* \code * \code
* void ( * void (
* boost::system::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
* *
@@ -319,28 +338,28 @@ public:
} }
/** /**
* \brief Send a SUBSCRIBE packet to Broker to create a subscription * \brief Send a \__SUBSCRIBE\__ packet to Broker to create a subscription
* to one Topics of interest. * to one Topics of interest.
* *
* \details After the subscription has been established, the Broker will send * \details After the subscription has been established, the Broker will send
* PUBLISH packets to the Client to forward Application Messages that were published * \__PUBLISH\__ packets to the Client to forward Application Messages that were published
* to Topics that the Client subscribed to. The PUBLISH packets can be received * to Topics that the Client subscribed to. The \__PUBLISH\__ packets can be received
* with \ref mqtt_client::async_receive function. * with \ref mqtt_client::async_receive function.
* *
* \param topic A \ref subscribe_topic of interest. * \param topic A \ref subscribe_topic of interest.
* \param props SUBSCRIBE properties. * \param props An instance of \__SUBSCRIBE_PROPS\__.
* \param token Completion token that will be used to produce a * \param token Completion token that will be used to produce a
* completion handler, which will be called when the operation completed. * completion handler, which will be called when the operation completed.
* *
* \par Completion signature * \par Handler signature
* The completion signature for this operation: * The handler signature for this operation:
* \code * \code
* void ( * void (
* boost::system::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
* *
@@ -363,27 +382,27 @@ public:
/** /**
* \brief Send an UNSUBSCRIBE packet to Broker to unsubscribe from one * \brief Send an \__UNSUBSCRIBE\__ packet to Broker to unsubscribe from one
* or more Topics. * or more Topics.
* *
* \note The Client MAY receive PUBLISH packets with Application * \note The Client MAY receive \__PUBLISH\__ packets with Application
* Messages from Topics the Client just unsubscribed to if * Messages from Topics the Client just unsubscribed to if
* they were buffered for delivery on the Broker side beforehand. * they were buffered for delivery on the Broker side beforehand.
* *
* \param topics List of Topics to unsubscribe from. * \param topics List of Topics to unsubscribe from.
* \param props UNSUBSCRIBE properties. * \param props An instance of \__UNSUBSCRIBE_PROPS\__.
* \param token Completion token that will be used to produce a * \param token Completion token that will be used to produce a
* completion handler, which will be called when the operation completed. * completion handler, which will be called when the operation completed.
* *
* \par Completion signature * \par Handler signature
* The completion signature for this operation: * The handler signature for this operation:
* \code * \code
* void ( * void (
* boost::system::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
* *
@@ -417,27 +436,27 @@ public:
} }
/** /**
* \brief Send an UNSUBSCRIBE packet to Broker to unsubscribe * \brief Send an \__UNSUBSCRIBE\__ packet to Broker to unsubscribe
* from one Topic. * from one Topic.
* *
* \note The Client MAY receive PUBLISH packets with Application * \note The Client MAY receive \__PUBLISH\__ packets with Application
* Messages from Topics the Client just unsubscribed to if * Messages from Topics the Client just unsubscribed to if
* they were buffered for delivery on the Broker side beforehand. * they were buffered for delivery on the Broker side beforehand.
* *
* \param topic Topic to unsubscribe from. * \param topic Topic to unsubscribe from.
* \param props UNSUBSCRIBE properties. * \param props An instance of \__UNSUBSCRIBE_PROPS\__.
* \param token Completion token that will be used to produce a * \param token Completion token that will be used to produce a
* completion handler, which will be called when the operation completed. * completion handler, which will be called when the operation completed.
* *
* \par Completion signature * \par Handler signature
* The completion signature for this operation: * The handler signature for this operation:
* \code * \code
* void ( * void (
* boost::system::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
* *
@@ -458,11 +477,13 @@ public:
); );
} }
// TODO: cancel the channel!
/** /**
* \brief Asynchronously receive an Application Message. * \brief Asynchronously receive an Application Message.
* *
* \details The Client will receive and complete deliveries for all the * \details The Client will receive and complete deliveries for all the
* PUBLISH packets received from the Broker throughout its lifetime. * \__PUBLISH\__ packets received from the Broker throughout its lifetime.
* The Client will store them internally in order they were delivered. * The Client will store them internally in order they were delivered.
* Calling this function will attempt to receive an Application Message * Calling this function will attempt to receive an Application Message
* from internal storage. * from internal storage.
@@ -473,14 +494,14 @@ public:
* \param token Completion token that will be used to produce a * \param token Completion token that will be used to produce a
* completion handler, which will be called when the operation completed. * completion handler, which will be called when the operation completed.
* *
* \par Completion signature * \par Handler signature
* The completion signature for this operation: * The handler signature for this operation:
* \code * \code
* void ( * void (
* boost::system::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
* *
@@ -498,24 +519,24 @@ public:
} }
/** /**
* \brief Disconnect the Client. * \brief Disconnect the Client. This function has terminal effects.
* *
* \details Send a DISCONNECT packet to the Broker with a Reason Code * \details Send a \__DISCONNECT\__ packet to the Broker with a Reason Code
* describing the reason for disconnection. * describing the reason for disconnection.
* *
* \note This function has terminal effects and will close the Client. * \note This function will close the Client. See \ref mqtt_client::cancel.
* *
* \param reason_code Reason Code to notify * \param reason_code Reason Code to notify
* the Broker of the reason for disconnection. * the Broker of the reason for disconnection.
* \param props DISCONNECT properties. * \param props An instance of \__DISCONNECT_PROPS\__.
* \param token Completion token that will be used to produce a * \param token Completion token that will be used to produce a
* completion handler, which will be called when the operation completed. * completion handler, which will be called when the operation completed.
* *
* \par Completion signature * \par Handler signature
* The completion signature for this operation: * The handler signature for this operation:
* \code * \code
* void ( * void (
* boost::system::error_code // Result of operation. * __ERROR_CODE__ // Result of operation.
* ) * )
* \endcode * \endcode
* *
@@ -537,22 +558,22 @@ public:
} }
/** /**
* \brief Disconnect the Client. * \brief Disconnect the Client. This function has terminal effects.
* *
* \details Send a DISCONNECT packet to the Broker with a Reason Code * \details Send a \__DISCONNECT\__ packet to the Broker with a Reason Code
* \ref reason_codes::normal_disconnection describing * \ref reason_codes::normal_disconnection describing
* the reason for disconnection. * the reason for disconnection.
* *
* \note This function has terminal effects and will close the Client. * \note This function will close the Client. See \ref mqtt_client::cancel.
* *
* \param token Completion token that will be used to produce a * \param token Completion token that will be used to produce a
* completion handler, which will be called when the operation completed. * completion handler, which will be called when the operation completed.
* *
* \par Completion signature * \par Handler signature
* The completion signature for this operation: * The handler signature for this operation:
* \code * \code
* void ( * void (
* boost::system::error_code // Result of operation. * __ERROR_CODE__ // Result of operation.
* ) * )
* \endcode * \endcode
* *

15
include/async_mqtt5/types.hpp
View File

@@ -22,10 +22,11 @@ struct authority_path {
}; };
/** /**
* \brief Represents the Quality of Service (QoS) property of the PUBLISH packets. * \brief Represents the Quality of Service (\__QOS__\)
* property of the \__PUBLISH\__ packets.
* *
* \details Determines how the PUBLISH packets are delivered from the sender * \details Determines how the \__PUBLISH\__ packets are delivered
* 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. */ /** The message arrives at the receiver either once or not at all. */
@@ -40,7 +41,7 @@ enum class qos_e : std::uint8_t {
}; };
/** /**
* \brief Represents the RETAIN flag in the PUBLISH packets. * \brief Represents the RETAIN flag in the \__PUBLISH\__ packets.
* *
* \details This flag informs the Server about whether or not it should * \details This flag informs the Server about whether or not it should
* store the current message. * store the current message.
@@ -62,12 +63,11 @@ enum class dup_e : std::uint8_t {
/** /**
* \brief Represents the Options associated with each Subscription. * \brief Represents the \__SUBSCRIBE_OPTIONS\__ associated with each Subscription.
*/ */
struct subscribe_options { struct subscribe_options {
/** /**
*
* \brief Representation of the No Local Subscribe Option. * \brief Representation of the No Local Subscribe Option.
* *
* \details A Subscribe Option indicating whether or not Application Messages * \details A Subscribe Option indicating whether or not Application Messages
@@ -190,6 +190,8 @@ reason codes:
*/ */
/// \cond
class connect_props : public prop::properties< class connect_props : public prop::properties<
prop::session_expiry_interval, prop::session_expiry_interval,
prop::receive_maximum, prop::receive_maximum,
@@ -299,6 +301,7 @@ class will_props : public prop::properties<
prop::user_property prop::user_property
>{}; >{};
/// \endcond
/** /**
* \brief Represents the Will Message. * \brief Represents the Will Message.