[mqtt-client] section about packet properties improved

Summary:
related to T12804

	- all properties now have usage & example paragraph
	- each property has its own page

Reviewers: ivica

Reviewed By: ivica

Subscribers: miljen

Differential Revision: https://repo.mireo.local/D26127
This commit is contained in:
Korina Šimičević
2023-10-17 11:51:14 +02:00
parent 22f1330fed
commit 402b8bf0b1
18 changed files with 550 additions and 164 deletions

View File

@ -67,8 +67,23 @@
[include reference/ExecutionContext.qbk]
[include reference/StreamType.qbk]
[include reference/TlsContext.qbk]
[include reference/reason_codes/Reason_codes.qbk]
[include reference/properties/Properties.qbk]
[include reference/properties/CONNECT_props.qbk]
[include reference/properties/CONNACK_props.qbk]
[include reference/properties/Will_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>''']
[endsect]

View File

@ -0,0 +1,36 @@
[/
Copyright (c) 2023 Mireo
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
]
[section:async_mqtt5__AUTH_props AUTH properties]
The last field in the Variable header of AUTH packet is a set of Properties.
A set contains a Property Length followed by the Properties.
A Property consists of an Identifier and a value.
This section lists all possible AUTH Properties and describes their usage:
[table:auth_props AUTH properties
[[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_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.]]
[[user_property] [`std::vector<std::string>`] [A list of name, value pairs (__UTF8_STRING_PAIR__) defining User Properties.
This property may be used to provide additional diagnostic or other information. ]]
]
[h4 Usage]
After obtaining an instance of `async_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.
[h4 Example]
[!c++]
async_mqtt5::auth_props props;
props[async_mqtt5::prop::authentication_method] = "SCRAM-SHA-1";
props[async_mqtt5::prop::authentication_data] = "data";
[endsect]

View File

@ -0,0 +1,47 @@
[/
Copyright (c) 2023 Mireo
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
]
[section:async_mqtt5__CONNACK_props CONNACK properties]
The last field in the Variable header of CONNACK packet is a set of Properties.
A set contains a Property Length followed by the Properties.
A Property consists of an Identifier and a value.
This section lists all possible CONNACK Properties and describes their usage:
[table:connack_props CONNACK properties
[[Identifier] [Value type] [Description]]
[[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 Server is willing to process concurrently.]]
[[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.]]
[[maximum_packet_size] [`int32_t`] [The maximum __PACKET_SIZE__ in bytes 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]]
[[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.]]
[[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::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.]]
[[server_keep_alive] [`int16_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.]]
[[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_data] [`std::string`] [Binary Data containing authentication data. The contents of the data are defined by the authentication method.]]
]
[h4 Usage]
After obtaining an instance of `async_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.
[h4 Example]
[!c++]
async_mqtt5::connack_props props;
props[async_mqtt5::prop::maximum_packet_size] = 65535;
props[async_mqtt5::prop::assigned_client_identifier] = "ClientID";
[endsect]

View File

@ -0,0 +1,42 @@
[/
Copyright (c) 2023 Mireo
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
]
[section:async_mqtt5__CONNECT_props CONNECT properties]
The last field in the Variable header of CONNECT packet is a set of Properties.
A set contains a Property Length followed by the Properties.
A Property consists of an Identifier and a value.
This section lists all possible CONNECT Properties and describes their usage:
[table:connect_props CONNECT properties
[[Identifier] [Value type] [Description]]
[[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.]]
[[maximum_packet_size] [`int32_t`] [The maximum __PACKET_SIZE__ in bytes 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.]]
[[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,
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.
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_data] [`std::string`] [Binary Data containing authentication data. The contents of the data are defined by the authentication method.]]
]
[h4 Usage]
After obtaining an instance of `async_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.
[h4 Example]
[!c++]
async_mqtt5::connect_props props;
props[async_mqtt5::prop::session_expiry_interval] = 1200;
props[async_mqtt5::prop::receive_maximum] = int16_t(100);
[endsect]

View File

@ -0,0 +1,34 @@
[/
Copyright (c) 2023 Mireo
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
]
[section:async_mqtt5__DISCONNECT_props DISCONNECT properties]
The last field in the Variable header of DISCONNECT packet is a set of Properties.
A set contains a Property Length followed by the Properties.
A Property consists of an Identifier and a value.
This section lists all possible DISCONNECT Properties and describes their usage:
[table:disconnect_props DISCONNECT properties
[[Identifier] [Value type] [Description]]
[[session_expiry_interval] [`int32_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.]]
[[user_property] [`std::vector<std::string>`] [A list of name, value pairs (__UTF8_STRING_PAIR__) defining User Properties.
This property may be used to provide additional diagnostic or other information. ]]
]
[h4 Usage]
After obtaining an instance of `async_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.
[h4 Example]
[!c++]
async_mqtt5::disconnect_props props;
props[async_mqtt5::prop::reason_string] = "Lost connection!";
[endsect]

View File

@ -0,0 +1,33 @@
[/
Copyright (c) 2023 Mireo
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
]
[section:async_mqtt5__PUBACK_props PUBACK properties]
The last field in the Variable header of PUBACK packet is a set of Properties.
A set contains a Property Length followed by the Properties.
A Property consists of an Identifier and a value.
This section lists all possible PUBACK Properties and describes their usage:
[table:puback_props PUBACK properties
[[Identifier] [Value type] [Description]]
[[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]]
[[user_property] [`std::vector<std::string>`] [A list of name, value pairs (__UTF8_STRING_PAIR__) defining User Properties.
This property may be used to provide additional diagnostic or other information. ]]
]
[h4 Usage]
After obtaining an instance of `async_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.
[h4 Example]
[!c++]
async_mqtt5::puback_props props;
props[async_mqtt5::prop::reason_string] = "Some reason...";
[endsect]

View File

@ -0,0 +1,33 @@
[/
Copyright (c) 2023 Mireo
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
]
[section:async_mqtt5__PUBCOMP_props PUBCOMP properties]
The last field in the Variable header of PUBCOMP packet is a set of Properties.
A set contains a Property Length followed by the Properties.
A Property consists of an Identifier and a value.
This section lists all possible PUBCOMP Properties and describes their usage:
[table:pubrec_props PUBCOMP properties
[[Identifier] [Value type] [Description]]
[[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]]
[[user_property] [`std::vector<std::string>`] [A list of name, value pairs (__UTF8_STRING_PAIR__) defining User Properties.
This property may be used to provide additional diagnostic or other information. ]]
]
[h4 Usage]
After obtaining an instance of `async_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.
[h4 Example]
[!c++]
async_mqtt5::pubcomp_props props;
props[async_mqtt5::prop::reason_string] = "Some reason...";
[endsect]

View File

@ -0,0 +1,41 @@
[/
Copyright (c) 2023 Mireo
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
]
[section:async_mqtt5__PUBLISH_props PUBLISH properties]
The last field in the Variable header of PUBLISH packet is a set of Properties.
A set contains a Property Length followed by the Properties.
A Property consists of an Identifier and a value.
This section lists all possible PUBLISH Properties and describes their usage:
[table:publish_props PUBLISH properties
[[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.]]
[[message_expiry_interval] [`int32_t`] [The lifetime of the Application Message in seconds.]]
[[topic_alias] [`int16_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.]]
[[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::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.]]
[[subscription_identifier] [`uint32_t`] [Identifier of the Subscription in range of 1 to 268,435,455.]]
[[content_type] [`std::string`] [A UTF-8 Encoded String describing the content of the Application Message.]]
]
[h4 Usage]
After obtaining an instance of `async_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.
[h4 Example]
[!c++]
async_mqtt5::publish_props props;
props[async_mqtt5::prop::payload_format_indicator] = uint8_t(1);
props[async_mqtt5::prop::topic_alias] = uint16_t(12);
props[async_mqtt5::prop::response_topic] = "response_topic";
[endsect]

View File

@ -0,0 +1,33 @@
[/
Copyright (c) 2023 Mireo
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
]
[section:async_mqtt5__PUBREC_props PUBREC properties]
The last field in the Variable header of PUBREC packet is a set of Properties.
A set contains a Property Length followed by the Properties.
A Property consists of an Identifier and a value.
This section lists all possible PUBREC Properties and describes their usage:
[table:pubrec_props PUBREC properties
[[Identifier] [Value type] [Description]]
[[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]]
[[user_property] [`std::vector<std::string>`] [A list of name, value pairs (__UTF8_STRING_PAIR__) defining User Properties.
This property may be used to provide additional diagnostic or other information. ]]
]
[h4 Usage]
After obtaining an instance of `async_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.
[h4 Example]
[!c++]
async_mqtt5::pubrec_props props;
props[async_mqtt5::prop::reason_string] = "Some reason...";
[endsect]

View File

@ -0,0 +1,33 @@
[/
Copyright (c) 2023 Mireo
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
]
[section:async_mqtt5__PUBREL_props PUBREL properties]
The last field in the Variable header of PUBREL packet is a set of Properties.
A set contains a Property Length followed by the Properties.
A Property consists of an Identifier and a value.
This section lists all possible PUBREL Properties and describes their usage:
[table:pubrec_props PUBREL properties
[[Identifier] [Value type] [Description]]
[[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]]
[[user_property] [`std::vector<std::string>`] [A list of name, value pairs (__UTF8_STRING_PAIR__) defining User Properties.
This property may be used to provide additional diagnostic or other information. ]]
]
[h4 Usage]
After obtaining an instance of `async_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.
[h4 Example]
[!c++]
async_mqtt5::pubrel_props props;
props[async_mqtt5::prop::reason_string] = "Some reason...";
[endsect]

View File

@ -1,151 +0,0 @@
[/
Copyright (c) 2023 Mireo
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
]
[section:async_mqtt5__Properties Properties]
The last field in the Variable header of packets CONNECT, CONNACK, PUBLISH, PUBACK, PUBREC,PUBREL, PUBCOMP, SUBSCRIBE, SUBACK, UNSUBSCRIBE, UNSUBACK, DISCONNECT, and AUTH
is a set of Properties. A set contains a Property Length followed by the Properties. A Property consists of an Identifier and a value.
This section lists all possible Properties and describes their usage:
[table:connect_props CONNECT properties
[[Identifier] [Value type] [Description]]
[[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.]]
[[maximum_packet_size] [`int32_t`] [The maximum __PACKET_SIZE__ in bytes 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.]]
[[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,
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.
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_data] [`std::string`] [Binary Data containing authentication data. The contents of the data are defined by the authentication method.]]
]
[table:will_props Will properties
[[Identifier] [Value type] [Description]]
[[will_delay_interval] [`int32_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.]]
[[message_expiry_interval] [`int32_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.]]
[[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::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.]]
]
[table:connack_props CONNACK properties
[[Identifier] [Value type] [Description]]
[[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 Server is willing to process concurrently.]]
[[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.]]
[[maximum_packet_size] [`int32_t`] [The maximum __PACKET_SIZE__ in bytes 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]]
[[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.]]
[[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::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.]]
[[server_keep_alive] [`int16_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.]]
[[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_data] [`std::string`] [Binary Data containing authentication data. The contents of the data are defined by the authentication method.]]
]
[table:publish_props PUBLISH properties
[[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.]]
[[message_expiry_interval] [`int32_t`] [The lifetime of the Application Message in seconds.]]
[[topic_alias] [`int16_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.]]
[[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::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.]]
[[subscription_identifier] [`uint32_t`] [Identifier of the Subscription in range of 1 to 268,435,455.]]
[[content_type] [`std::string`] [A UTF-8 Encoded String describing the content of the Application Message.]]
]
[table:puback_props PUBACK properties
[[Identifier] [Value type] [Description]]
[[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]]
[[user_property] [`std::vector<std::string>`] [A list of name, value pairs (__UTF8_STRING_PAIR__) defining User Properties.
This property may be used to provide additional diagnostic or other information. ]]
]
[table:pubrec_props PUBREC properties
[[Identifier] [Value type] [Description]]
[[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]]
[[user_property] [`std::vector<std::string>`] [A list of name, value pairs (__UTF8_STRING_PAIR__) defining User Properties.
This property may be used to provide additional diagnostic or other information. ]]
]
[table:pubrel_props PUBREL properties
[[Identifier] [Value type] [Description]]
[[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]]
[[user_property] [`std::vector<std::string>`] [A list of name, value pairs (__UTF8_STRING_PAIR__) defining User Properties.
This property may be used to provide additional diagnostic or other information. ]]
]
[table:pubcomp_props PUBCOMP properties
[[Identifier] [Value type] [Description]]
[[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]]
[[user_property] [`std::vector<std::string>`] [A list of name, value pairs (__UTF8_STRING_PAIR__) defining User Properties.
This property may be used to provide additional diagnostic or other information. ]]
]
[table:subscribe_props SUBSCRIBE properties
[[Identifier] [Value type] [Description]]
[[subscription_identifier] [`uint32_t`] [Identifier of the Subscription in range of 1 to 268,435,455.]]
[[user_property] [`std::vector<std::string>`] [A list of name, value pairs (__UTF8_STRING_PAIR__) defining User Properties.
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 ]]
]
[table:suback_props SUBACK properties
[[Identifier] [Value type] [Description]]
[[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]]
[[user_property] [`std::vector<std::string>`] [A list of name, value pairs (__UTF8_STRING_PAIR__) defining User Properties.
This property may be used to provide additional diagnostic or other information. ]]
]
[table:unsubscribe_props UNSUBSCRIBE properties
[[Identifier] [Value type] [Description]]
[[user_property] [`std::vector<std::string>`] [A list of name, value pairs (__UTF8_STRING_PAIR__) defining User Properties.
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 ]]
]
[table:unsuback_props UNSUBACK properties
[[Identifier] [Value type] [Description]]
[[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]]
[[user_property] [`std::vector<std::string>`] [A list of name, value pairs (__UTF8_STRING_PAIR__) defining User Properties.
This property may be used to provide additional diagnostic or other information. ]]
]
[table:disconnect_props DISCONNECT properties
[[Identifier] [Value type] [Description]]
[[session_expiry_interval] [`int32_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.]]
[[user_property] [`std::vector<std::string>`] [A list of name, value pairs (__UTF8_STRING_PAIR__) defining User Properties.
This property may be used to provide additional diagnostic or other information. ]]
]
[table:auth_props AUTH properties
[[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_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.]]
[[user_property] [`std::vector<std::string>`] [A list of name, value pairs (__UTF8_STRING_PAIR__) defining User Properties.
This property may be used to provide additional diagnostic or other information. ]]
]
[endsect]

View File

@ -0,0 +1,33 @@
[/
Copyright (c) 2023 Mireo
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
]
[section:async_mqtt5__SUBACK_props SUBACK properties]
The last field in the Variable header of SUBACK packet is a set of Properties.
A set contains a Property Length followed by the Properties.
A Property consists of an Identifier and a value.
This section lists all possible SUBACK Properties and describes their usage:
[table:suback_props SUBACK properties
[[Identifier] [Value type] [Description]]
[[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]]
[[user_property] [`std::vector<std::string>`] [A list of name, value pairs (__UTF8_STRING_PAIR__) defining User Properties.
This property may be used to provide additional diagnostic or other information. ]]
]
[h4 Usage]
After obtaining an instance of `async_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.
[h4 Example]
[!c++]
async_mqtt5::suback_props props;
props[async_mqtt5::prop::reason_string] = "Some reason...";
[endsect]

View File

@ -0,0 +1,34 @@
[/
Copyright (c) 2023 Mireo
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
]
[section:async_mqtt5__SUBSCRIBE_props SUBSCRIBE properties]
The last field in the Variable header of SUBSCRIBE packet is a set of Properties.
A set contains a Property Length followed by the Properties.
A Property consists of an Identifier and a value.
This section lists all possible SUBSCRIBE Properties and describes their usage:
[table:subscribe_props SUBSCRIBE properties
[[Identifier] [Value type] [Description]]
[[subscription_identifier] [`uint32_t`] [Identifier of the Subscription in range of 1 to 268,435,455.]]
[[user_property] [`std::vector<std::string>`] [A list of name, value pairs (__UTF8_STRING_PAIR__) defining User Properties.
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 ]]
]
[h4 Usage]
After obtaining an instance of `async_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.
[h4 Example]
[!c++]
async_mqtt5::subscribe_props props;
props[async_mqtt5::prop::subscription_identifier] = 1234u;
[endsect]

View File

@ -0,0 +1,33 @@
[/
Copyright (c) 2023 Mireo
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
]
[section:async_mqtt5__UNSUBACK_props UNSUBACK properties]
The last field in the Variable header of UNSUBACK packet is a set of Properties.
A set contains a Property Length followed by the Properties.
A Property consists of an Identifier and a value.
This section lists all possible UNSUBACK Properties and describes their usage:
[table:unsuback_props UNSUBACK properties
[[Identifier] [Value type] [Description]]
[[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]]
[[user_property] [`std::vector<std::string>`] [A list of name, value pairs (__UTF8_STRING_PAIR__) defining User Properties.
This property may be used to provide additional diagnostic or other information. ]]
]
[h4 Usage]
After obtaining an instance of `async_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.
[h4 Example]
[!c++]
async_mqtt5::unsuback_props props;
props[async_mqtt5::prop::reason_string] = "Some reason...";
[endsect]

View File

@ -0,0 +1,34 @@
[/
Copyright (c) 2023 Mireo
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
]
[section:async_mqtt5__UNSUBSCRIBE_props UNSUBSCRIBE properties]
The last field in the Variable header of UNSUBSCRIBE packet is a set of Properties.
A set contains a Property Length followed by the Properties.
A Property consists of an Identifier and a value.
This section lists all possible UNSUBSCRIBE Properties and describes their usage:
[table:unsubscribe_props UNSUBSCRIBE properties
[[Identifier] [Value type] [Description]]
[[user_property] [`std::vector<std::string>`] [A list of name, value pairs (__UTF8_STRING_PAIR__) defining User Properties.
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 ]]
]
[h4 Usage]
After obtaining an instance of `async_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.
[h4 Example]
[!c++]
async_mqtt5::unsubscribe_props props;
props[async_mqtt5::prop::subscription_identifier] = 1234u;
[endsect]

View File

@ -0,0 +1,39 @@
[/
Copyright (c) 2023 Mireo
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
]
[section:async_mqtt5__Will_props [reflink2 will 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 consists of a Property Length and the Properties.
A Property consists of an Identifier and a value.
This section lists all possible Will Properties and describes their usage:
[table:will_props Will properties
[[Identifier] [Value type] [Description]]
[[will_delay_interval] [`int32_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.]]
[[message_expiry_interval] [`int32_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.]]
[[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.]]
[[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.]]
]
[h4 Usage]
After creating an instance of [reflink2 will `async_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.
[h4 Example]
[!c++]
async_mqtt5::will will;
will[async_mqtt5::prop::message_expiry_interval] = 90;
will[async_mqtt5::prop::content_type] = "Notification";
[endsect]

View File

@ -22,12 +22,6 @@
<member><link linkend="async_mqtt5.ref.async_mqtt5__subscribe_topic">subscribe_topic</link></member>
<member><link linkend="async_mqtt5.ref.async_mqtt5__will">will</link></member>
</simplelist>
</entry>
<entry valign="top">
<bridgehead renderas="sect3">Type aliases</bridgehead>
<simplelist type="vert" columns="1">
<member><link linkend="async_mqtt5.ref.async_mqtt5__error_code">error_code</link></member>
</simplelist>
<bridgehead renderas="sect3">Concepts</bridgehead>
<simplelist type="vert" columns="1">
<member><link linkend="async_mqtt5.ref.async_mqtt5__ExecutionContext">ExecutionContext</link></member>
@ -36,6 +30,10 @@
</simplelist>
</entry>
<entry valign="top">
<bridgehead renderas="sect3">Type aliases</bridgehead>
<simplelist type="vert" columns="1">
<member><link linkend="async_mqtt5.ref.async_mqtt5__error_code">error_code</link></member>
</simplelist>
<bridgehead renderas="sect3">Enumerations</bridgehead>
<simplelist type="vert" columns="1">
<member><link linkend="async_mqtt5.ref.async_mqtt5__client__error">client_error</link></member>
@ -43,22 +41,37 @@
<member><link linkend="async_mqtt5.ref.async_mqtt5__qos_e">qos_e</link></member>
<member><link linkend="async_mqtt5.ref.async_mqtt5__retain_e">retain_e</link></member>
</simplelist>
</entry>
<entry valign="top">
<bridgehead renderas="sect3">Constants</bridgehead>
<member><link linkend="async_mqtt5.ref.async_mqtt5__Reason_codes">Reason codes</link></member>
<simplelist type="vert" columns="1">
</simplelist>
</entry>
<entry valign="top">
<bridgehead renderas="sect3">Properties</bridgehead>
<simplelist type="vert" columns="1">
<member><link linkend="async_mqtt5.ref.async_mqtt5__Properties">Properties</link></member>
</simplelist>
<bridgehead renderas="sect3">Functions</bridgehead>
<simplelist type="vert" columns="1">
<member><link linkend="async_mqtt5.ref.async_mqtt5__client__get_error_code_category">get_error_code_category</link></member>
<member><link linkend="async_mqtt5.ref.async_mqtt5__client__make_error_code">make_error_code</link></member>
</simplelist>
</entry>
<entry valign="top">
<bridgehead renderas="sect3">Properties</bridgehead>
<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__CONNECT_props">CONNECT properties</link></member>
<member><link linkend="async_mqtt5.ref.async_mqtt5__CONNACK_props">CONNACK properties</link></member>
<member><link linkend="async_mqtt5.ref.async_mqtt5__PUBLISH_props">PUBLISH properties</link></member>
<member><link linkend="async_mqtt5.ref.async_mqtt5__PUBACK_props">PUBACK properties</link></member>
<member><link linkend="async_mqtt5.ref.async_mqtt5__PUBREC_props">PUBREC properties</link></member>
<member><link linkend="async_mqtt5.ref.async_mqtt5__PUBREL_props">PUBREL properties</link></member>
<member><link linkend="async_mqtt5.ref.async_mqtt5__PUBCOMP_props">PUBCOMP properties</link></member>
<member><link linkend="async_mqtt5.ref.async_mqtt5__SUBSCRIBE_props">SUBSCRIBE properties</link></member>
<member><link linkend="async_mqtt5.ref.async_mqtt5__SUBACK_props">SUBACK properties</link></member>
<member><link linkend="async_mqtt5.ref.async_mqtt5__UNSUBSCRIBE_props">UNSUBSCRIBE properties</link></member>
<member><link linkend="async_mqtt5.ref.async_mqtt5__UNSUBACK_props">UNSUBACK properties</link></member>
<member><link linkend="async_mqtt5.ref.async_mqtt5__DISCONNECT_props">DISCONNECT properties</link></member>
<member><link linkend="async_mqtt5.ref.async_mqtt5__AUTH_props">AUTH properties</link></member>
</simplelist>
</entry>
</row></tbody>
</tgroup>
</informaltable>

View File

@ -13,6 +13,10 @@ namespace async_mqtt5 {
/** An alias for `boost::system::error_code`; */
using error_code = boost::system::error_code;
/**
* \brief A data structure used to store information related to an authority
* such as the host name, port, and path.
*/
struct authority_path {
std::string host, port, path;
};