diff --git a/doc/qbk/00_main.qbk b/doc/qbk/00_main.qbk index 5f7690d..e1d7796 100644 --- a/doc/qbk/00_main.qbk +++ b/doc/qbk/00_main.qbk @@ -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''''''] [endsect] diff --git a/doc/qbk/reference/properties/AUTH_props.qbk b/doc/qbk/reference/properties/AUTH_props.qbk new file mode 100644 index 0000000..aadf10f --- /dev/null +++ b/doc/qbk/reference/properties/AUTH_props.qbk @@ -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`] [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] diff --git a/doc/qbk/reference/properties/CONNACK_props.qbk b/doc/qbk/reference/properties/CONNACK_props.qbk new file mode 100644 index 0000000..5b4195d --- /dev/null +++ b/doc/qbk/reference/properties/CONNACK_props.qbk @@ -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`] [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] diff --git a/doc/qbk/reference/properties/CONNECT_props.qbk b/doc/qbk/reference/properties/CONNECT_props.qbk new file mode 100644 index 0000000..5d17493 --- /dev/null +++ b/doc/qbk/reference/properties/CONNECT_props.qbk @@ -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`] [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] diff --git a/doc/qbk/reference/properties/DISCONNECT_props.qbk b/doc/qbk/reference/properties/DISCONNECT_props.qbk new file mode 100644 index 0000000..527a9b3 --- /dev/null +++ b/doc/qbk/reference/properties/DISCONNECT_props.qbk @@ -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`] [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] diff --git a/doc/qbk/reference/properties/PUBACK_props.qbk b/doc/qbk/reference/properties/PUBACK_props.qbk new file mode 100644 index 0000000..d28ddde --- /dev/null +++ b/doc/qbk/reference/properties/PUBACK_props.qbk @@ -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`] [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] diff --git a/doc/qbk/reference/properties/PUBCOMP_props.qbk b/doc/qbk/reference/properties/PUBCOMP_props.qbk new file mode 100644 index 0000000..39ab919 --- /dev/null +++ b/doc/qbk/reference/properties/PUBCOMP_props.qbk @@ -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`] [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] diff --git a/doc/qbk/reference/properties/PUBLISH_props.qbk b/doc/qbk/reference/properties/PUBLISH_props.qbk new file mode 100644 index 0000000..a9fb335 --- /dev/null +++ b/doc/qbk/reference/properties/PUBLISH_props.qbk @@ -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`] [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] diff --git a/doc/qbk/reference/properties/PUBREC_props.qbk b/doc/qbk/reference/properties/PUBREC_props.qbk new file mode 100644 index 0000000..27008ab --- /dev/null +++ b/doc/qbk/reference/properties/PUBREC_props.qbk @@ -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`] [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] diff --git a/doc/qbk/reference/properties/PUBREL_props.qbk b/doc/qbk/reference/properties/PUBREL_props.qbk new file mode 100644 index 0000000..8605c08 --- /dev/null +++ b/doc/qbk/reference/properties/PUBREL_props.qbk @@ -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`] [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] diff --git a/doc/qbk/reference/properties/Properties.qbk b/doc/qbk/reference/properties/Properties.qbk deleted file mode 100644 index 748fd11..0000000 --- a/doc/qbk/reference/properties/Properties.qbk +++ /dev/null @@ -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`] [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`] [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`] [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`] [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`] [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`] [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`] [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`] [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`] [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`] [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`] [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`] [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`] [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`] [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] \ No newline at end of file diff --git a/doc/qbk/reference/properties/SUBACK_props.qbk b/doc/qbk/reference/properties/SUBACK_props.qbk new file mode 100644 index 0000000..40e7c27 --- /dev/null +++ b/doc/qbk/reference/properties/SUBACK_props.qbk @@ -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`] [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] diff --git a/doc/qbk/reference/properties/SUBSCRIBE_props.qbk b/doc/qbk/reference/properties/SUBSCRIBE_props.qbk new file mode 100644 index 0000000..2c222be --- /dev/null +++ b/doc/qbk/reference/properties/SUBSCRIBE_props.qbk @@ -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`] [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] diff --git a/doc/qbk/reference/properties/UNSUBACK_props.qbk b/doc/qbk/reference/properties/UNSUBACK_props.qbk new file mode 100644 index 0000000..62b80eb --- /dev/null +++ b/doc/qbk/reference/properties/UNSUBACK_props.qbk @@ -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`] [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] diff --git a/doc/qbk/reference/properties/UNSUBSCRIBE_props.qbk b/doc/qbk/reference/properties/UNSUBSCRIBE_props.qbk new file mode 100644 index 0000000..4b816d7 --- /dev/null +++ b/doc/qbk/reference/properties/UNSUBSCRIBE_props.qbk @@ -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`] [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] diff --git a/doc/qbk/reference/properties/Will_props.qbk b/doc/qbk/reference/properties/Will_props.qbk new file mode 100644 index 0000000..57a5ffa --- /dev/null +++ b/doc/qbk/reference/properties/Will_props.qbk @@ -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`] [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] diff --git a/doc/qbk/reference/quickref.xml b/doc/qbk/reference/quickref.xml index a1c1882..dc3c4ef 100644 --- a/doc/qbk/reference/quickref.xml +++ b/doc/qbk/reference/quickref.xml @@ -22,12 +22,6 @@ subscribe_topic will - - - Type aliases - - error_code - Concepts ExecutionContext @@ -36,6 +30,10 @@ + Type aliases + + error_code + Enumerations client_error @@ -43,22 +41,37 @@ qos_e retain_e + + Constants Reason codes - - - Properties - - Properties - Functions get_error_code_category make_error_code + + Properties + + Will properties + CONNECT properties + CONNACK properties + PUBLISH properties + PUBACK properties + PUBREC properties + PUBREL properties + PUBCOMP properties + SUBSCRIBE properties + SUBACK properties + UNSUBSCRIBE properties + UNSUBACK properties + DISCONNECT properties + AUTH properties + + diff --git a/include/async_mqtt5/types.hpp b/include/async_mqtt5/types.hpp index 9c322a2..f5b408d 100644 --- a/include/async_mqtt5/types.hpp +++ b/include/async_mqtt5/types.hpp @@ -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; };