boostorg/mqtt5
1
0
Fork 1
mirror of https://github.com/boostorg/mqtt5.git synced 2025-06-24 20:01:31 +02:00
Code Issues Packages Projects Releases Wiki Activity

Document property_types.hpp

Browse Source 
Summary: Resolves T16534

Reviewers: korina

Reviewed By: korina

Subscribers: ivica, miljen

Maniphest Tasks: T16534

Differential Revision: https://repo.mireo.local/D34028
This commit is contained in:
Bruno Iljazovic
2025-03-03 17:09:34 +01:00
parent 1fe10dd6a3
commit 7f4cfc2145
20 changed files with 105 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
doc/Jamfile
View File

@ -19,6 +19,7 @@ include-prefix = [ path.native $(include-prefix:D)/include ] ;
local doxygen_include =
error.hpp
logger.hpp
property_types.hpp
reason_codes.hpp
types.hpp
mqtt_client.hpp

3
doc/qbk/reference/properties/auth_props.qbk
View File

@ -9,7 +9,8 @@ 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:
This class extends [reflink2 prop__properties prop::properties], which provides common functionalities for all property classes.
Below is a list of possible __AUTH__ Properties, along with descriptions of their usage:
[table:auth_props AUTH properties
[[Identifier] [Value type] [Description]]

3
doc/qbk/reference/properties/connack_props.qbk
View File

@ -9,7 +9,8 @@ The last field in the Variable header of __CONNACK__ packet is a set of Properti
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:
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]]

3
doc/qbk/reference/properties/connect_props.qbk
View File

@ -9,7 +9,8 @@ The last field in the Variable header of __CONNECT__ packet is a set of Properti
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:
This class extends [reflink2 prop__properties prop::properties], which provides common functionalities for all property classes.
Below is a list of possible __CONNECT__ Properties, along with descriptions of their usage:
[table:connect_props CONNECT properties
[[Identifier] [Value type] [Description]]

3
doc/qbk/reference/properties/disconnect_props.qbk
View File

@ -9,7 +9,8 @@ The last field in the Variable header of __DISCONNECT__ packet is a set of Prope
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:
This class extends [reflink2 prop__properties prop::properties], which provides common functionalities for all property classes.
Below is a list of possible __DISCONNECT__ Properties, along with descriptions of their usage:
[table:disconnect_props DISCONNECT properties
[[Identifier] [Value type] [Description]]

3
doc/qbk/reference/properties/puback_props.qbk
View File

@ -9,7 +9,8 @@ The last field in the Variable header of __PUBACK__ packet is a set of Propertie
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:
This class extends [reflink2 prop__properties prop::properties], which provides common functionalities for all property classes.
Below is a list of possible __PUBACK__ Properties, along with descriptions of their usage:
[table:puback_props PUBACK properties
[[Identifier] [Value type] [Description]]

3
doc/qbk/reference/properties/pubcomp_props.qbk
View File

@ -9,7 +9,8 @@ The last field in the Variable header of __PUBCOMP__ packet is a set of Properti
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:
This class extends [reflink2 prop__properties prop::properties], which provides common functionalities for all property classes.
Below is a list of possible __PUBCOMP__ Properties, along with descriptions of their usage:
[table:pubcomp_props PUBCOMP properties
[[Identifier] [Value type] [Description]]

7
doc/qbk/reference/properties/publish_props.qbk
View File

@ -9,7 +9,8 @@ The last field in the Variable header of __PUBLISH__ packet is a set of Properti
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:
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]]
@ -31,8 +32,8 @@ The Identifiers listed in the table above are available within the `boost::mqtt5
[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 `boost::mqtt5::prop::subscription_identifiers` respectively.
`boost::mqtt5::prop::subscription_identifiers` has the interface of `boost::container::small_vector`.]
`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]

3
doc/qbk/reference/properties/pubrec_props.qbk
View File

@ -9,7 +9,8 @@ The last field in the Variable header of __PUBREC__ packet is a set of Propertie
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:
This class extends [reflink2 prop__properties prop::properties], which provides common functionalities for all property classes.
Below is a list of possible __PUBREC__ Properties, along with descriptions of their usage:
[table:pubrec_props PUBREC properties
[[Identifier] [Value type] [Description]]

3
doc/qbk/reference/properties/pubrel_props.qbk
View File

@ -9,7 +9,8 @@ The last field in the Variable header of __PUBREL__ packet is a set of Propertie
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:
This class extends [reflink2 prop__properties prop::properties], which provides common functionalities for all property classes.
Below is a list of possible __PUBREL__ Properties, along with descriptions of their usage:
[table:pubrel_props PUBREL properties
[[Identifier] [Value type] [Description]]

3
doc/qbk/reference/properties/suback_props.qbk
View File

@ -9,7 +9,8 @@ The last field in the Variable header of __SUBACK__ packet is a set of Propertie
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:
This class extends [reflink2 prop__properties prop::properties], which provides common functionalities for all property classes.
Below is a list of possible __SUBACK__ Properties, along with descriptions of their usage:
[table:suback_props SUBACK properties
[[Identifier] [Value type] [Description]]

7
doc/qbk/reference/properties/subscribe_props.qbk
View File

@ -9,7 +9,8 @@ The last field in the Variable header of __SUBSCRIBE__ packet is a set of Proper
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:
This class extends [reflink2 prop__properties prop::properties], which provides common functionalities for all property classes.
Below is a list of possible __SUBSCRIBE__ Properties, along with descriptions of their usage:
[table:subscribe_props SUBSCRIBE properties
[[Identifier] [Value type] [Description]]
@ -26,8 +27,8 @@ The Identifiers listed in the table above are available within the `boost::mqtt5
[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 `boost::mqtt5::prop::subscription_identifiers` respectively.
`boost::mqtt5::prop::subscription_identifiers` has the interface of `std::optional<int32_t>`.]
`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 `std::optional<int32_t>`.]
[h4 Example]

3
doc/qbk/reference/properties/unsuback_props.qbk
View File

@ -9,7 +9,8 @@ The last field in the Variable header of __UNSUBACK__ packet is a set of Propert
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:
This class extends [reflink2 prop__properties prop::properties], which provides common functionalities for all property classes.
Below is a list of possible __UNSUBACK__ Properties, along with descriptions of their usage:
[table:unsuback_props UNSUBACK properties
[[Identifier] [Value type] [Description]]

3
doc/qbk/reference/properties/unsubscribe_props.qbk
View File

@ -9,7 +9,8 @@ The last field in the Variable header of __UNSUBSCRIBE__ packet is a set of Prop
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:
This class extends [reflink2 prop__properties prop::properties], which provides common functionalities for all property classes.
Below is a list of possible __UNSUBSCRIBE__ Properties, along with descriptions of their usage:
[table:unsubscribe_props UNSUBSCRIBE properties
[[Identifier] [Value type] [Description]]

3
doc/qbk/reference/properties/will_props.qbk
View File

@ -10,7 +10,8 @@ and the Application Message properties to be sent with the [reflink2 will Will]
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 [reflink2 will Will] Properties and describes their usage:
This class extends [reflink2 prop__properties prop::properties], which provides common functionalities for all property classes.
Below is a list of possible [reflink2 will Will] Properties, along with descriptions of their usage:
[table:will_props Will properties
[[Identifier] [Value type] [Description]]

2
doc/qbk/reference/quickref.xml
View File

@ -20,6 +20,8 @@
<member><link linkend="mqtt5.ref.boost__mqtt5__subscribe_options">subscribe_options</link></member>
<member><link linkend="mqtt5.ref.boost__mqtt5__subscribe_topic">subscribe_topic</link></member>
<member><link linkend="mqtt5.ref.boost__mqtt5__will">will</link></member>
<member><link linkend="mqtt5.ref.boost__mqtt5__prop__subscription_identifiers">subscription_identifiers</link></member>
<member><link linkend="mqtt5.ref.boost__mqtt5__prop__properties">properties</link></member>
</simplelist>
<bridgehead renderas="sect3">Concepts</bridgehead>
<simplelist type="vert" columns="1">

14
include/boost/mqtt5/mqtt_client.hpp
View File

@ -522,10 +522,10 @@ public:
}
/**
* \brief Send a \__SUBSCRIBE\__ packet to Broker to create a subscription
* \brief Send a \__SUBSCRIBE\__ packet to Broker to create a Subscription
* to one or more Topics of interest.
*
* \details After the subscription has been established, the Broker will send
* \details After the Subscription has been established, the Broker will send
* PUBLISH packets to the Client to forward Application Messages that were published
* to Topics that the Client subscribed to. The Application Messages can be received
* with \ref mqtt_client::async_receive function.
@ -543,7 +543,7 @@ public:
* void (
* __ERROR_CODE__, // Result of operation.
* std::vector<__REASON_CODE__>, // Vector of Reason Codes indicating
* // the subscription result for each Topic
* // the Subscription result for each Topic
* // in the SUBSCRIBE packet.
* __SUBACK_PROPS__, // Properties received in the SUBACK packet.
* )
@ -595,10 +595,10 @@ public:
}
/**
* \brief Send a \__SUBSCRIBE\__ packet to Broker to create a subscription
* \brief Send a \__SUBSCRIBE\__ packet to Broker to create a Subscription
* to one Topic of interest.
*
* \details After the subscription has been established, the Broker will send
* \details After the Subscription has been established, the Broker will send
* \__PUBLISH\__ packets to the Client to forward Application Messages that were published
* to Topics that the Client subscribed to. The Application Messages can be received
* with \ref mqtt_client::async_receive function.
@ -616,7 +616,7 @@ public:
* void (
* __ERROR_CODE__, // Result of operation.
* std::vector<__REASON_CODE__>, // Vector of Reason Codes containing the
* // single subscription result for the Topic
* // single Subscription result for the Topic
* // in the SUBSCRIBE packet.
* __SUBACK_PROPS__, // Properties received in the SUBACK packet.
* )
@ -808,7 +808,7 @@ public:
* from internal storage.
*
* \note It is only recommended to call this function if you have established
* a successful subscription to a Topic using the \ref async_subscribe function.
* a successful Subscription to a Topic using the \ref async_subscribe function.
*
* \param token Completion token that will be used to produce a
* completion handler. The handler will be invoked when the operation completes.

59
include/boost/mqtt5/property_types.hpp
View File

@ -21,6 +21,7 @@
namespace boost::mqtt5::prop {
/// \cond internal
enum property_type : uint8_t {
payload_format_indicator_t = 0x01,
message_expiry_interval_t = 0x02,
@ -50,7 +51,16 @@ enum property_type : uint8_t {
subscription_identifier_available_t = 0x29,
shared_subscription_available_t = 0x2a
};
/// \endcond
/**
* \brief A class holding any number of Subscription Identifiers.
*
* \details Subscription Identifier is an integer that can be set in \__SUBSCRIBE_PROPS\__ when subscribing to a Topic.
* Broker will store the mapping between that Subscription and the Subscription Identifier.
* When an incoming \__PUBLISH\__ message matches one or more Subscriptions, respective Subscription
* Identifiers will be forwarded in the \__PUBLISH_PROPS\__ of the received message.
*/
class alignas(8) subscription_identifiers :
public boost::container::small_vector<int32_t, 1>
{
@ -58,8 +68,11 @@ class alignas(8) subscription_identifiers :
public:
using base_type::base_type;
/// Constructs Subscription Identifiers with given parameters.
subscription_identifiers(int32_t val) : base_type { val } {}
/// \{ Checks whether there are any Subscription Identifiers.
bool has_value() const noexcept {
return !empty();
}
@ -67,7 +80,9 @@ public:
explicit operator bool() const noexcept {
return !empty();
}
/// \}
/// \{ Accesses the (first) Subscription Identifier.
int32_t& operator*() noexcept {
return front();
}
@ -75,19 +90,24 @@ public:
int32_t operator*() const noexcept {
return front();
}
/// \}
/// Sets or replaces the (first) Subscription Identifier.
void emplace(int32_t val = 0) {
*this = val;
}
/// Returns the first Subscription Identifier.
int32_t value() const {
return front();
}
/// Returns the first Subscription Identifier if it exists, otherwise returns \p default_val
int32_t value_or(int32_t default_val) const noexcept {
return empty() ? default_val : front();
}
/// Clears the Subscription Identifiers.
void reset() noexcept {
clear();
}
@ -142,6 +162,10 @@ using value_type_t = typename property_traits<p>::type;
template <property_type p>
constexpr std::string_view name_v = property_traits<p>::name;
/**
* \brief Base class for different Property classes that contains common access
and modification functions.
*/
template <property_type ...Ps>
class properties {
@ -155,18 +179,21 @@ class properties {
public:
/// \brief Accesses the value of a Property by its compile-time constant ID.
template <property_type v>
constexpr auto& operator[](std::integral_constant<property_type, v>)
noexcept {
return std::get<property<v>>(_props).value;
}
/// \copydoc operator[]
template <property_type v>
constexpr const auto& operator[](std::integral_constant<property_type, v>)
const noexcept {
return std::get<property<v>>(_props).value;
}
/// \cond internal
template <typename Func>
using is_apply_on = std::conjunction<
std::is_invocable<Func, value_type_t<Ps>&>...
@ -176,7 +203,18 @@ public:
using is_nothrow_apply_on = std::conjunction<
std::is_nothrow_invocable<Func, value_type_t<Ps>&>...
>;
/// \endcond
/**
* \brief Applies a function to a Property identified by its ID.
*
* This function iterates over all Properties and invokes the provided function
* on the value of the Property that matches the given property ID.
*
* \param property_id The ID of the Property to apply the function on.
* \param func The function to invoke on the Property value.
* \return `true` if the function was applied to a Property and `false` otherwise.
*/
template <
typename Func,
std::enable_if_t<is_apply_on<Func>::value, bool> = true
@ -190,14 +228,15 @@ public:
constexpr typename ptype::key prop;
if (prop.value == property_id)
std::invoke(func, px.value);
return prop.value != property_id;
return prop.value == property_id;
};
return (pc(ptype) && ...);
return (pc(ptype) || ...);
},
_props
);
}
/// \cond internal
template <typename Func>
using is_visitor = std::conjunction<
std::is_invocable_r<bool, Func, decltype(Ps), value_type_t<Ps>&>...
@ -207,7 +246,20 @@ public:
using is_nothrow_visitor = std::conjunction<
std::is_nothrow_invocable<Func, decltype(Ps), value_type_t<Ps>&>...
>;
/// \endcond
/**
* \brief Invokes a visitor function on each Property.
*
* This function iterates over Properties and invokes the provided function
* on each Property, passing both the compile-time constant Property ID and its value.
* The visitor function should return a boolean value that determines whether iteration continues.
*
* @param func The visitor function to invoke. It must accept two arguments:
* a Property ID and the corresponding Property value.
* @return `true` if the visitor function returns `true` for all Properties,
* `false` otherwise.
*/
template <
typename Func,
std::enable_if_t<is_visitor<Func>::value, bool> = true
@ -221,12 +273,13 @@ public:
constexpr typename ptype::key prop;
return std::invoke(func, prop, px.value);
};
return (pc(props) &&...);
return (pc(props) && ...);
},
_props
);
}
/// \copydoc visit
template <
typename Func,
std::enable_if_t<is_visitor<Func>::value, bool> = true

2
include/boost/mqtt5/reason_codes.hpp
View File

@ -48,7 +48,7 @@ class reason_code {
uint8_t _code;
reason_codes::category _category { reason_codes::category::none };
public:
/// \cond INTERNAL
/// \cond internal
constexpr reason_code() : _code(0xff) {}
constexpr reason_code(uint8_t code, reason_codes::category cat) :

12
include/boost/mqtt5/types.hpp
View File

@ -111,7 +111,7 @@ enum class no_local_e : std::uint8_t {
* \brief Representation of the Retain As Published Subscribe Option.
*
* \details A Subscribe Option indicating whether or not Application Messages forwarded
* using this subscription keep the \__RETAIN\__ flag they were published with.
* using this Subscription keep the \__RETAIN\__ flag they were published with.
*/
enum class retain_as_published_e : std::uint8_t {
/** \brief Application Messages have the \__RETAIN\__ flag set to 0. */
@ -125,13 +125,13 @@ enum class retain_as_published_e : std::uint8_t {
* \brief Representation of the Retain Handling Subscribe Option.
*
* \details A Subscribe Option specifying whether retained messages are sent
* when the subscription is established.
* when the Subscription is established.
*/
enum class retain_handling_e : std::uint8_t {
/** \brief Send retained messages at the time of subscribe. */
send = 0b00,
/** \brief Send retained message only if the subscription does not currently exist. */
/** \brief Send retained message only if the Subscription does not currently exist. */
new_subscription_only = 0b01,
/** \brief Do not send retained messages at the time of subscribe. */
@ -153,7 +153,7 @@ struct subscribe_options {
retain_as_published_e retain_as_published = retain_as_published_e::retain;
/** \brief Option determining if retained messages are sent
when the subscription is established. */
when the Subscription is established. */
retain_handling_e retain_handling = retain_handling_e::new_subscription_only;
};
@ -165,11 +165,11 @@ struct subscribe_topic {
/** \brief An UTF-8 Encoded String indicating the Topics to which the Client wants to subscribe. */
std::string topic_filter;
/** \brief The \ref subscribe_options associated with the subscription. */
/** \brief The \ref subscribe_options associated with the Subscription. */
subscribe_options sub_opts;
};
/// \cond
/// \cond internal
class connect_props : public prop::properties<
prop::session_expiry_interval_t,