expose CONNACK properties

Summary: resolves T13155

Reviewers: ivica

Reviewed By: ivica

Subscribers: miljen, iljazovic

Maniphest Tasks: T13155

Differential Revision: https://repo.mireo.local/D26681

doc/qbk/reference/properties/auth_props.qbk

@@ -28,9 +28,23 @@ The Identifiers listed in the table above are available within the `async_mqtt5:
 
 [h4 Example]
 
+The following example shows how to set a Property value:
+
 [!c++]
 	async_mqtt5::auth_props props;
 	props[async_mqtt5::prop::authentication_method] = "SCRAM-SHA-1";
 	props[async_mqtt5::prop::authentication_data] = "data";
 
+The following example shows how to retrieve a Property value:
+
+[note When retrieving a property value, the subscript operator will consistently return a `std::optional` of the value type for all properties,
+except for `async_mqtt5::prop::user_property`, where it will return an instance of its value type, `std::vector<std::string>`.]
+
+[!c++]
+	std::optional<std::string> auth_data = props[async_mqtt5::prop::authentication_data];
+	if (auth_data.has_value())
+		// authentication data property was previously set
+	else
+		// authentication data property was not set
+
 [endsect]

doc/qbk/reference/properties/connack_props.qbk

@@ -22,9 +22,14 @@ This section lists all possible __CONNACK__ Properties and describes their usage
 	[[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.]]
+	[[wildcard_subscription_available] [`uint8_t`] [A value of 0 means that Wildcard Subscriptions are not supported. 
+		A value of 1 means they are supported. If not present, they are supported.]]
+	[[subscription_identifier_available] [`uint8_t`] [A value of 0 means that Subscriptions Identifiers are not supported. 
+		A value of 1 means they are supported. If not present, they are supported.]]
+	[[shared_subscription_available] [`uint8_t`] [A value of 0 means that Shared Subscriptions are not supported. 
+		A value of 1 means they are supported. If not present, they are supported.]]
 	[[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.]]
@@ -39,9 +44,23 @@ The Identifiers listed in the table above are available within the `async_mqtt5:
 
 [h4 Example]
 
+The following example shows how to set a Property value:
+
 [!c++]
 	async_mqtt5::connack_props props;
 	props[async_mqtt5::prop::maximum_packet_size] = 65535;
 	props[async_mqtt5::prop::assigned_client_identifier] = "ClientID";
+	
+The following example shows how to retrieve a Property value:
+
+[note When retrieving a property value, the subscript operator will consistently return a `std::optional` of the value type for all properties,
+except for `async_mqtt5::prop::user_property`, where it will return an instance of its value type, `std::vector<std::string>`.]
+
+[!c++]
+	std::optional<std::string> auth_method = props[async_mqtt5::prop::authentication_method];
+	if (auth_method.has_value())
+		// authentication method property was previously set
+	else
+		// authentication method property was not set
 
 [endsect]

doc/qbk/reference/properties/connect_props.qbk

@@ -35,9 +35,23 @@ The Identifiers listed in the table above are available within the `async_mqtt5:
 
 [h4 Example]
 
+The following example shows how to set a Property value:
+
 [!c++]
 	async_mqtt5::connect_props props;
 	props[async_mqtt5::prop::session_expiry_interval] = 1200;
 	props[async_mqtt5::prop::receive_maximum] = int16_t(100);
 
+The following example shows how to retrieve a Property value:
+
+[note When retrieving a property value, the subscript operator will consistently return a `std::optional` of the value type for all properties,
+except for `async_mqtt5::prop::user_property`, where it will return an instance of its value type, `std::vector<std::string>`.]
+
+[!c++]
+	std::optional<std::string> auth_method = props[async_mqtt5::prop::authentication_method];
+	if (auth_method.has_value())
+		// authentication method property was previously set
+	else
+		// authentication method property was not set
+
 [endsect]

doc/qbk/reference/properties/disconnect_props.qbk

@@ -18,6 +18,7 @@ This section lists all possible __DISCONNECT__ Properties and describes their us
 	[[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. ]]
+	[[server_reference] [`std::string`] [A UTF-8 Encoded String which can be used by the Client to identfy another Server to use.]]
 ]
 
 [h4 Usage]
@@ -27,8 +28,22 @@ The Identifiers listed in the table above are available within the `async_mqtt5:
 
 [h4 Example]
 
+The following example shows how to set a Property value:
+
 [!c++]
 	async_mqtt5::disconnect_props props;
 	props[async_mqtt5::prop::reason_string] = "Lost connection!";
 
+The following example shows how to retrieve a Property value:
+
+[note When retrieving a property value, the subscript operator will consistently return a `std::optional` of the value type for all properties,
+except for `async_mqtt5::prop::user_property`, where it will return an instance of its value type, `std::vector<std::string>`.]
+
+[!c++]
+	std::optional<std::string> reason_string = props[async_mqtt5::prop::reason_string];
+	if (reason_string.has_value())
+		// reason string property was previously set
+	else
+		// reason string property was not set
+
 [endsect]

doc/qbk/reference/properties/puback_props.qbk

@@ -26,8 +26,22 @@ The Identifiers listed in the table above are available within the `async_mqtt5:
 
 [h4 Example]
 
+The following example shows how to set a Property value:
+
 [!c++]
 	async_mqtt5::puback_props props;
 	props[async_mqtt5::prop::reason_string] = "Some reason...";
 
+The following example shows how to retrieve a Property value:
+
+[note When retrieving a property value, the subscript operator will consistently return a `std::optional` of the value type for all properties,
+except for `async_mqtt5::prop::user_property`, where it will return an instance of its value type, `std::vector<std::string>`.]
+
+[!c++]
+	std::optional<std::string> reason_string = props[async_mqtt5::prop::reason_string];
+	if (reason_string.has_value())
+		// reason string property was previously set
+	else
+		// reason string property was not set
+
 [endsect]

doc/qbk/reference/properties/pubcomp_props.qbk

@@ -12,7 +12,7 @@ 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
+[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. 
@@ -26,8 +26,22 @@ The Identifiers listed in the table above are available within the `async_mqtt5:
 
 [h4 Example]
 
+The following example shows how to set a Property value:
+
 [!c++]
 	async_mqtt5::pubcomp_props props;
 	props[async_mqtt5::prop::reason_string] = "Some reason...";
 
+The following example shows how to retrieve a Property value:
+
+[note When retrieving a property value, the subscript operator will consistently return a `std::optional` of the value type for all properties,
+except for `async_mqtt5::prop::user_property`, where it will return an instance of its value type, `std::vector<std::string>`.]
+
+[!c++]
+	std::optional<std::string> reason_string = props[async_mqtt5::prop::reason_string];
+	if (reason_string.has_value())
+		// reason string property was previously set
+	else
+		// reason string property was not set
+
 [endsect]

doc/qbk/reference/properties/publish_props.qbk

@@ -32,10 +32,24 @@ The Identifiers listed in the table above are available within the `async_mqtt5:
 
 [h4 Example]
 
+The following example shows how to set a Property value:
+
 [!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";
 
+The following example shows how to retrieve a Property value:
+
+[note When retrieving a property value, the subscript operator will consistently return a `std::optional` of the value type for all properties,
+except for `async_mqtt5::prop::user_property`, where it will return an instance of its value type, `std::vector<std::string>`.]
+
+[!c++]
+	std::optional<int16_t> topic_alias = props[async_mqtt5::prop::topic_alias];
+	if (topic_alias.has_value())
+		// topic alias property was previously set
+	else
+		// topic alias property was not set
+
 [endsect]

doc/qbk/reference/properties/pubrec_props.qbk

@@ -26,8 +26,22 @@ The Identifiers listed in the table above are available within the `async_mqtt5:
 
 [h4 Example]
 
+The following example shows how to set a Property value:
+
 [!c++]
 	async_mqtt5::pubrec_props props;
 	props[async_mqtt5::prop::reason_string] = "Some reason...";
 
+The following example shows how to retrieve a Property value:
+
+[note When retrieving a property value, the subscript operator will consistently return a `std::optional` of the value type for all properties,
+except for `async_mqtt5::prop::user_property`, where it will return an instance of its value type, `std::vector<std::string>`.]
+
+[!c++]
+	std::optional<std::string> reason_string = props[async_mqtt5::prop::reason_string];
+	if (reason_string.has_value())
+		// reason string property was previously set
+	else
+		// reason string property was not set
+
 [endsect]

doc/qbk/reference/properties/pubrel_props.qbk

@@ -12,7 +12,7 @@ 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
+[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. 
@@ -25,9 +25,22 @@ After obtaining an instance of `async_mqtt5::pubrel_props`, the subscript operat
 The Identifiers listed in the table above are available within the `async_mqtt5::prop` namespace for Property access.
 
 [h4 Example]
+The following example shows how to set a Property value:
 
 [!c++]
 	async_mqtt5::pubrel_props props;
 	props[async_mqtt5::prop::reason_string] = "Some reason...";
 
+The following example shows how to retrieve a Property value:
+
+[note When retrieving a property value, the subscript operator will consistently return a `std::optional` of the value type for all properties,
+except for `async_mqtt5::prop::user_property`, where it will return an instance of its value type, `std::vector<std::string>`.]
+
+[!c++]
+	std::optional<std::string> reason_string = props[async_mqtt5::prop::reason_string];
+	if (reason_string.has_value())
+		// reason string property was previously set
+	else
+		// reason string property was not set
+
 [endsect]

doc/qbk/reference/properties/suback_props.qbk

@@ -26,8 +26,22 @@ The Identifiers listed in the table above are available within the `async_mqtt5:
 
 [h4 Example]
 
+The following example shows how to set a Property value:
+
 [!c++]
 	async_mqtt5::suback_props props;
 	props[async_mqtt5::prop::reason_string] = "Some reason...";
 
+The following example shows how to retrieve a Property value:
+
+[note When retrieving a property value, the subscript operator will consistently return a `std::optional` of the value type for all properties,
+except for `async_mqtt5::prop::user_property`, where it will return an instance of its value type, `std::vector<std::string>`.]
+
+[!c++]
+	std::optional<std::string> reason_string = props[async_mqtt5::prop::reason_string];
+	if (reason_string.has_value())
+		// reason string property was previously set
+	else
+		// reason string property was not set
+
 [endsect]

doc/qbk/reference/properties/subscribe_props.qbk

@@ -27,8 +27,22 @@ The Identifiers listed in the table above are available within the `async_mqtt5:
 
 [h4 Example]
 
+The following example shows how to set a Property value:
+
 [!c++]
 	async_mqtt5::subscribe_props props;
 	props[async_mqtt5::prop::subscription_identifier] = 1234u;
 
+The following example shows how to retrieve a Property value:
+
+[note When retrieving a property value, the subscript operator will consistently return a `std::optional` of the value type for all properties,
+except for `async_mqtt5::prop::user_property`, where it will return an instance of its value type, `std::vector<std::string>`.]
+
+[!c++]
+	std::optional<uint32_t> sub_id = props[async_mqtt5::prop::subscription_identifier];
+	if (sub_id.has_value())
+		// subscription identifier property was previously set
+	else
+		// subscription identifier property was not set
+
 [endsect]

doc/qbk/reference/properties/unsuback_props.qbk

@@ -26,8 +26,22 @@ The Identifiers listed in the table above are available within the `async_mqtt5:
 
 [h4 Example]
 
+The following example shows how to set a Property value:
+
 [!c++]
 	async_mqtt5::unsuback_props props;
 	props[async_mqtt5::prop::reason_string] = "Some reason...";
 
+The following example shows how to retrieve a Property value:
+
+[note When retrieving a property value, the subscript operator will consistently return a `std::optional` of the value type for all properties,
+except for `async_mqtt5::prop::user_property`, where it will return an instance of its value type, `std::vector<std::string>`.]
+
+[!c++]
+	std::optional<std::string> reason_string = props[async_mqtt5::prop::reason_string];
+	if (reason_string.has_value())
+		// reason string property was previously set
+	else
+		// reason string property was not set
+
 [endsect]

doc/qbk/reference/properties/unsubscribe_props.qbk

@@ -26,9 +26,20 @@ The Identifiers listed in the table above are available within the `async_mqtt5:
 
 [h4 Example]
 
+The following example shows how to set a Property value:
+
 [!c++]
 	async_mqtt5::unsubscribe_props props;
-	props[async_mqtt5::prop::subscription_identifier] = 1234u;
+	props[async_mqtt5::prop::user_property].push_back("key");
+	props[async_mqtt5::prop::user_property].push_back("value");
+
+The following example shows how to retrieve a Property value:
+
+[note When retrieving a property value, the subscript operator will consistently return a `std::optional` of the value type for all properties,
+except for `async_mqtt5::prop::user_property`, where it will return an instance of its value type, `std::vector<std::string>`.]
+
+[!c++]
+	std::vector<std::string> user_props = props[async_mqtt5::prop::user_property];
 
 
 [endsect]

doc/qbk/reference/properties/will_props.qbk

@@ -32,9 +32,23 @@ The Identifiers listed in the table above are available within the `async_mqtt5:
 
 [h4 Example]
 
+The following example shows how to set a Property value:
+
 [!c++]
 	async_mqtt5::will will;
 	will[async_mqtt5::prop::message_expiry_interval] = 90;
 	will[async_mqtt5::prop::content_type] = "Notification";
 
+The following example shows how to retrieve a Property value:
+
+[note When retrieving a property value, the subscript operator will consistently return a `std::optional` of the value type for all properties,
+except for `async_mqtt5::prop::user_property`, where it will return an instance of its value type, `std::vector<std::string>`.]
+
+[!c++]
+	std::optional<std::string> c_type = will[async_mqtt5::prop::content_type];
+	if (c_type.has_value())
+		// content type property was previously set
+	else
+		// content type property was not set
+
 [endsect]

include/async_mqtt5/impl/client_service.hpp

@@ -45,7 +45,7 @@ public:
 	}
 
 	template <typename Prop>
-	auto connack_prop(Prop p) {
+	decltype(auto) connack_prop(Prop p) {
 		return _mqtt_context.ca_props[p];
 	}
 
@@ -83,7 +83,7 @@ public:
 	}
 
 	template <typename Prop>
-	auto connack_prop(Prop p) {
+	decltype(auto) connack_prop(Prop p) {
 		return _mqtt_context.ca_props[p];
 	}
 
@@ -207,7 +207,7 @@ public:
 	}
 
 	template <typename Prop>
-	auto connack_prop(Prop p) {
+	decltype(auto) connack_prop(Prop p) {
 		return _stream_context.connack_prop(p);
 	}
 

include/async_mqtt5/mqtt_client.hpp

@@ -165,6 +165,28 @@ public:
 		});
 	}
 
+	/**
+	 * \brief Retrieves the value of a specific property from the last \__CONNACK\__ packet received.
+	 *
+	 * \details The return type varies according to the property requested.
+	 * For all properties, the return type will be `std::optional` of their respective value type.
+	 * For `async_mqtt5::prop::user_property`, the return type is `std::vector<std::string>`.
+	 *
+	 * \param prop The \__CONNACK\__ property value to retrieve.
+	 *
+	 * \par Example
+	 * \code
+	 *	std::optional<std::string> auth_method = client.connection_property(async_mqtt5::prop::authentication_method); // ok
+	 *	std::optional<std::string> c_type = client.connection_property(async_mqtt5::prop::content_type); // does not compile!
+	 * \endcode
+	 *
+	 * \see See \__CONNACK_PROPS\__ for all eligible properties.
+	 */
+	template <uint8_t p>
+	decltype(auto) connection_property(std::integral_constant<uint8_t, p> prop) {
+		return _svc_ptr->connack_prop(prop);
+	}
+
 	/**
 	 * \brief Assign a \ref will Message.
 	 *

include/async_mqtt5/types.hpp

@@ -285,7 +285,7 @@ class suback_props : public prop::properties<
 > {};
 
 class unsubscribe_props : public prop::properties<
-	prop::subscription_identifier
+	prop::user_property
 > {};
 
 class unsuback_props : public prop::properties<