[/
    Copyright (c) 2023-2025 Ivica Siladic, Bruno Iljazovic, Korina Simicevic
    Distributed under the Boost Software License, Version 1.0.
    (See accompanying file LICENSE or copy at http://www.boost.org/LICENSE_1_0.txt)
]

[section: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 class extends [reflink2 prop__properties prop::properties], which provides common functionalities for all property classes.
Below is a list of possible __CONNACK__ Properties, along with descriptions of their usage:

[table:connack_props CONNACK properties
    [[Identifier] [Value type] [Description]]
    [[session_expiry_interval] [`uint32_t`] [Represents the Session Expiry Internal in seconds.]]
    [[receive_maximum] [`uint16_t`] [The maximum number of QoS 1 and QoS 2 publications that the Server is willing to process concurrently.]]
    [[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] [`uint32_t`] [The maximum __PACKET_SIZE__ in bytes as defined by the specification that the Server is willing to accept.]]
    [[assigned_client_identifier] [`std::string`] [The Client Identifier which was assigned by the Server because a zero length Client Identifier was found in the __CONNECT__ packet]]
    [[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.]]
    [[user_property] [`std::vector<std::pair<std::string, std::string>>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. 
        The meaning of these properties is not defined by the specification.]]
    [[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] [`uint16_t`] [The Keep Alive time assigned by the Server.]]
    [[response_information] [`std::string`] [A UTF-8 Encoded String which is used as the basis for creating a Response Topic.]]
    [[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 `boost::mqtt5::connack_props`, the subscript operator can be used to access a Property.

The Identifiers listed in the table above are available within the `boost::mqtt5::prop` namespace for Property access.

[note When accessing a property value, the subscript operator will return a `std::optional` of the value type for all properties,
except for `boost::mqtt5::prop::user_property`, where it will return an instance of `std::vector<std::pair<std::string, std::string>>`.]

[h4 Example]

The following example shows how to set a Property value:

[!c++]
    boost::mqtt5::connack_props props;
    props[boost::mqtt5::prop::maximum_packet_size] = 65535;
    props[boost::mqtt5::prop::assigned_client_identifier] = "ClientID";
    props[boost::mqtt5::prop::user_property].emplace_back("name", "value");
    
The following example shows how to retrieve a Property value:

[!c++]
    std::optional<std::string> auth_method = props[boost::mqtt5::prop::authentication_method];
    if (auth_method.has_value())
        // authentication method property was previously set
    else
        // authentication method property was not set
    
    std::vector<std::pair<std::string, std::string>>& user_props = props[boost::mqtt5::prop::user_property];
    if (!user_props.empty())
        // user property was previously set
    else
        // user property was not set

[endsect]
