[/
    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: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 class extends [reflink2 prop__properties prop::properties], which provides common functionalities for all property classes.
Below is a list of possible __PUBLISH__ Properties, along with descriptions of 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] [`uint32_t`] [The lifetime of the Application Message in seconds.]]
    [[topic_alias] [`uint16_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::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.]]
    [[subscription_identifier] [`boost::mqtt5::prop::subscription_identifiers`] [Identifier of the matching subscription. If there are multiple matching subscriptions, multiple identifiers may be included.]]
    [[content_type] [`std::string`] [A UTF-8 Encoded String describing the content of the Application Message.]]
]

[h4 Usage]
After obtaining an instance of `boost::mqtt5::publish_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` and `boost::mqtt5::prop::subscription_identifier`, where it will return an instance of
`std::vector<std::pair<std::string, std::string>>` and [reflink2 prop__subscription_identifiers prop::subscription_identifiers] respectively.
[reflink2 prop__subscription_identifiers prop::subscription_identifiers] has the interface of `boost::container::small_vector`.]

[h4 Example]

The following example shows how to set a Property value:

[!c++]
    boost::mqtt5::publish_props props;
    props[boost::mqtt5::prop::payload_format_indicator] = uint8_t(1);
    props[boost::mqtt5::prop::topic_alias] = uint16_t(12);
    props[boost::mqtt5::prop::response_topic] = "response_topic";
    props[boost::mqtt5::prop::subscription_identifier].push_back(40);

The following example shows how to retrieve a Property value:

[!c++]
    std::optional<uint16_t> topic_alias = props[boost::mqtt5::prop::topic_alias];
    if (topic_alias.has_value())
        // topic alias property was previously set
    else
        // topic alias property was not set
    
    boost::mqtt5::prop::subscription_identifiers& sub_ids = props[boost::mqtt5::prop::subscription_identifier];
    if (!sub_ids.empty())
        // subscription identifier property was previously set
    else
        // subscription identifier property was not set

[endsect]
