feedc0de/boost_mqtt5
1
0 Fork 0
forked from boostorg/mqtt5
Code Pull Requests Activity

Simplify document generation and replace Async.MQTT5 with Boost.MQTT5 in docs

Browse Source 
Summary:
related to T15996

- docs are now buildable with b2 (in a very simplified way) like mysql docs
- change Async.MQTT5 -> Boost.MQTT5, async_mqtt5 namespace to boost::mqtt5 namespace

- once changes are approved, Ill update all tabs to 4 spaces in .qbk files

Reviewers: ivica

Reviewed By: ivica

Subscribers: iljazovic, miljen

Differential Revision: https://repo.mireo.local/D33373
This commit is contained in:
Korina Šimičević committed 2025-01-27 08:22:13 +01:00
1 parent 9a0d41b7a7
commit b42014f379
48 files changed
+1399 -3320
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

include/boost/mqtt5/error.hpp
+13 -13
View File
@@ -23,10 +23,10 @@ namespace boost::mqtt5 {
* in the \__DISCONNECT\__ packet as the reason for the disconnection.
*/
enum class disconnect_rc_e : uint8_t {
/** Close the connection normally. Do not send the Will Message. */
/** \brief Close the connection normally. Do not send the Will Message. */
normal_disconnection = 0x00,
/** The Client wishes to disconnect but requires that
/** \brief The Client wishes to disconnect but requires that
the Server also publishes its Will Message. */
disconnect_with_will_message = 0x04
};
@@ -61,39 +61,39 @@ namespace client {
* \details Encapsulates errors that occur on the client side.
*/
enum class error : int {
/** The packet is malformed */
/** \brief The packet is malformed */
malformed_packet = 100,
/** The packet has exceeded the Maximum Packet Size the Server is willing to accept */
/** \brief The packet has exceeded the Maximum Packet Size the Server is willing to accept */
packet_too_large,
/** The Client's session does not exist or it has expired */
/** \brief The Client's session does not exist or it has expired */
session_expired,
/** There are no more available Packet Identifiers to use */
/** \brief There are no more available Packet Identifiers to use */
pid_overrun,
/** The Topic is invalid and does not conform to the specification */
/** \brief The Topic is invalid and does not conform to the specification */
invalid_topic,
// publish
/** The Server does not support the specified \ref qos_e */
/** \brief The Server does not support the specified \ref qos_e */
qos_not_supported,
/** The Server does not support retained messages */
/** \brief The Server does not support retained messages */
retain_not_available,
/** The Client attempted to send a Topic Alias that is greater than Topic Alias Maximum */
/** \brief The Client attempted to send a Topic Alias that is greater than Topic Alias Maximum */
topic_alias_maximum_reached,
// subscribe
/** The Server does not support Wildcard Subscriptions */
/** \brief The Server does not support Wildcard Subscriptions */
wildcard_subscription_not_available,
/** The Server does not support this Subscription Identifier */
/** \brief The Server does not support this Subscription Identifier */
subscription_identifier_not_available,
/** The Server does not support Shared Subscriptions */
/** \brief The Server does not support Shared Subscriptions */
shared_subscription_not_available
};
include/boost/mqtt5/impl/codecs/message_decoders.hpp
+2 -2
View File
@@ -83,7 +83,7 @@ inline std::optional<connect_message> decode_connect(
basic::utf8_ >> // client_id
basic::if_(has_will)[prop::props_<will_props>] >>
basic::if_(has_will)[basic::utf8_] >> // will topic
basic::if_(has_will)[basic::binary_] >> // will message
basic::if_(has_will)[basic::binary_] >> // will message
basic::if_(has_uname)[basic::utf8_] >> // username
basic::if_(has_pwd)[basic::utf8_]; // password
@@ -266,7 +266,7 @@ inline std::optional<unsuback_message> decode_unsuback(
uint32_t remain_length, byte_citer& it
) {
auto unsuback_ = basic::scope_limit_(remain_length)[
prop::props_<unsuback_props> >> +x3::byte_
prop::props_<unsuback_props> >> +x3::byte_
];
return type_parse(it, it + remain_length, unsuback_);
}
include/boost/mqtt5/impl/codecs/message_encoders.hpp
+1 -1
View File
@@ -61,7 +61,7 @@ inline std::string encode_connect(
basic::utf8_(client_id) &
prop::props_(w) &
basic::utf8_(w, &will::topic) &
basic::binary_(w, &will::message) &
basic::binary_(w, &will::message) &
basic::utf8_(user_name) &
basic::utf8_(password);
include/boost/mqtt5/impl/connect_op.hpp
+2 -2
View File
@@ -322,9 +322,9 @@ public:
// Unexpected result handling:
// - If we don't have a Session State, and we get session_present = true,
// we must close the network connection (and restart with a clean start)
// we must close the network connection (and restart with a clean start)
// - If we have a Session State, and we get session_present = false,
// we must discard our Session State
// we must discard our Session State
auto rc = to_reason_code<reason_codes::category::connack>(reason_code);
if (!rc.has_value()) // reason code not allowed in CONNACK
include/boost/mqtt5/logger.hpp
+3 -3
View File
@@ -54,9 +54,9 @@ enum class log_level : uint8_t {
* implicit strand, none of the functions will be invoked concurrently.
*
* \par Thread safety
* ['Distinct objects]: unsafe. \n
* ['Shared objects]: unsafe. \n
* This class is [*not thread-safe].
* Distinct objects: usafe. \n
* Shared objects: unsafe. \n
* This class is <b>not thread-safe</b>.
*/
class logger {
constexpr static auto prefix = "[Boost.MQTT5]";
include/boost/mqtt5/mqtt_client.hpp
+241 -241
View File
@@ -45,9 +45,9 @@ namespace asio = boost::asio;
* \tparam \__LoggerType\__ Type of object used to log events within the Client.
*
* \par Thread safety
* ['Distinct objects]: safe. \n
* ['Shared objects]: unsafe. \n
* This class is [*not thread-safe].
* Distinct objects: safe. \n
* Shared objects: unsafe. \n
* This class is <b>not thread-safe</b>.
* The application must also ensure that all asynchronous operations are performed within the same implicit or explicit strand.
*/
template <
@@ -150,7 +150,7 @@ public:
/**
* \brief Destructor.
*
* \details Automatically calls \ref mqtt_client::cancel.
* \details Automatically calls \ref cancel.
*/
~mqtt_client() {
if (_impl)
@@ -192,23 +192,23 @@ public:
*
* \par Handler signature
* The handler signature for this operation:
* \code
* void (__ERROR_CODE__)
* \endcode
* \code
* void (__ERROR_CODE__)
* \endcode
*
* \par Completion condition
* The asynchronous operation will complete with
* `boost::asio::error::operation_aborted` when the client is cancelled by calling
* \ref mqtt_client::async_disconnect, \ref mqtt_client::cancel, destruction or
* \ref async_disconnect, \ref cancel, destruction or
* if a non-recoverable error happens during a connection attempt (e.g. access denied).
*
* \par Error codes
* The list of all possible error codes that this operation can finish with:\n
* - `boost::asio::error::operation_aborted`\n
* \par Error codes
* The list of all possible error codes that this operation can finish with:\n
* - `boost::asio::error::operation_aborted`\n
*
* \par Per-Operation Cancellation
* This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n
* - `cancellation_type::terminal` - invokes \ref mqtt_client::cancel \n
* \par Per-Operation Cancellation
* This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n
* - `cancellation_type::terminal` - invokes \ref cancel \n
*/
template <
typename CompletionToken =
@@ -228,7 +228,7 @@ public:
* with `boost::asio::error::operation_aborted`.
*
* \attention This function has terminal effects and will close the Client.
* The Client cannot be used before calling \ref mqtt_client::async_run again.
* The Client cannot be used before calling \ref async_run again.
*/
void cancel() {
auto impl = _impl;
@@ -297,8 +297,8 @@ public:
* Some valid `hosts` string:
*
* \code
* std::string valid_hosts_1 = "broker1:1883, broker2, broker3:1883";
* std::string valid_hosts_2 = "broker1";
* std::string valid_hosts_1 = "broker1:1883, broker2, broker3:1883";
* std::string valid_hosts_2 = "broker1";
* \endcode
*
*/
@@ -387,7 +387,7 @@ public:
}
/**
* \brief Initiates [mqttlink 3901257 Re-authentication]
* \brief Initiates \__RE_AUTHENTICATION\__
* using the authenticator given in the \ref authenticator method.
*
* \note If \ref authenticator was not called, this method does nothing.
@@ -408,8 +408,8 @@ public:
*
* \par Example
* \code
* std::optional<std::string> auth_method = client.connack_property(boost::mqtt5::prop::authentication_method); // ok
* std::optional<std::string> c_type = client.connack_property(boost::mqtt5::prop::content_type); // does not compile, not a CONNACK prop!
* std::optional<std::string> auth_method = client.connack_property(boost::mqtt5::prop::authentication_method); // ok
* std::optional<std::string> c_type = client.connack_property(boost::mqtt5::prop::content_type); // does not compile, not a CONNACK prop!
* \endcode
*
* \see See \__CONNACK_PROPS\__ for all eligible properties.
@@ -448,61 +448,61 @@ public:
* \par Handler signature
* The handler signature for this operation depends on the \ref qos_e specified:\n
*
* `qos` == `qos_e::at_most_once`:
* \code
* void (
* __ERROR_CODE__ // Result of operation
* )
* \endcode
* `qos` == `qos_e::at_most_once`:
* \code
* void (
* __ERROR_CODE__ // Result of operation
* )
* \endcode
*
* `qos` == `qos_e::at_least_once`:
* \code
* void (
* __ERROR_CODE__, // Result of operation.
* __REASON_CODE__, // Reason Code received from Broker.
* __PUBACK_PROPS__ // Properties received in the PUBACK packet.
* )
* \endcode
* `qos` == `qos_e::at_least_once`:
* \code
* void (
* __ERROR_CODE__, // Result of operation.
* __REASON_CODE__, // Reason Code received from Broker.
* __PUBACK_PROPS__ // Properties received in the PUBACK packet.
* )
* \endcode
*
* `qos` == `qos_e::exactly_once`:
* \code
* void (
* __ERROR_CODE__, // Result of operation.
* __REASON_CODE__, // Reason Code received from Broker.
* __PUBCOMP_PROPS__ // Properties received in the PUBCOMP packet.
* )
* \endcode
* `qos` == `qos_e::exactly_once`:
* \code
* void (
* __ERROR_CODE__, // Result of operation.
* __REASON_CODE__, // Reason Code received from Broker.
* __PUBCOMP_PROPS__ // Properties received in the PUBCOMP packet.
* )
* \endcode
*
* \par Completion condition
* Depending on the \ref qos_e specified, the asynchronous operation will complete
* when one of the following conditions is true:\n
* - If `qos` == `qos_e::at_most_once` and the Client
* has successfully written the packet to the transport. \n
* - If `qos` == `qos_e::at_least_once` and the packet has
* been sent and acknowledged through the reception of a \__PUBACK\__ packet.
* - If `qos` == `qos_e::exactly_once` and the packet has
* been sent and fully acknowledged through the reception of a \__PUBCOMP\__ packet.
* - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n
* \par Completion condition
* Depending on the \ref qos_e specified, the asynchronous operation will complete
* when one of the following conditions is true:\n
* - If `qos` == `qos_e::at_most_once` and the Client
* has successfully written the packet to the transport. \n
* - If `qos` == `qos_e::at_least_once` and the packet has
* been sent and acknowledged through the reception of a \__PUBACK\__ packet.
* - If `qos` == `qos_e::exactly_once` and the packet has
* been sent and fully acknowledged through the reception of a \__PUBCOMP\__ packet.
* - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n
*
* \par Error codes
* The list of all possible error codes that this operation can finish with:\n
* - `boost::system::errc::errc_t::success` \n
* - `boost::asio::error::operation_aborted` \n
* - `boost::asio::error::no_recovery` \n
* - \link boost::mqtt5::client::error::malformed_packet \endlink
* - \link boost::mqtt5::client::error::packet_too_large \endlink
* - \link boost::mqtt5::client::error::pid_overrun \endlink
* - \link boost::mqtt5::client::error::qos_not_supported \endlink
* - \link boost::mqtt5::client::error::retain_not_available \endlink
* - \link boost::mqtt5::client::error::topic_alias_maximum_reached \endlink
* - \link boost::mqtt5::client::error::invalid_topic \endlink
* \par Error codes
* The list of all possible error codes that this operation can finish with:\n
* - `boost::system::errc::errc_t::success` \n
* - `boost::asio::error::operation_aborted` \n
* - `boost::asio::error::no_recovery` \n
* - \ref boost::mqtt5::client::error::malformed_packet
* - \ref boost::mqtt5::client::error::packet_too_large
* - \ref boost::mqtt5::client::error::pid_overrun
* - \ref boost::mqtt5::client::error::qos_not_supported
* - \ref boost::mqtt5::client::error::retain_not_available
* - \ref boost::mqtt5::client::error::topic_alias_maximum_reached
* - \ref boost::mqtt5::client::error::invalid_topic
*
* Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code.
*
* \par Per-Operation Cancellation
* This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n
* - `cancellation_type::terminal` - invokes \ref mqtt_client::cancel \n
* - `cancellation_type::partial` & `cancellation_type::total` - prevents potential resending of the \__PUBLISH\__ packet \n
* \par Per-Operation Cancellation
* This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n
* - `cancellation_type::terminal` - invokes \ref cancel \n
* - `cancellation_type::partial` & `cancellation_type::total` - prevents potential resending of the \__PUBLISH\__ packet \n
*
*/
template <qos_e qos_type,
@@ -540,41 +540,41 @@ public:
*
* \par Handler signature
* The handler signature for this operation:
* \code
* void (
* __ERROR_CODE__, // Result of operation.
* std::vector<__REASON_CODE__>, // Vector of Reason Codes indicating
* // the subscription result for each Topic
* // in the SUBSCRIBE packet.
* __SUBACK_PROPS__, // Properties received in the SUBACK packet.
* )
* \endcode
* \code
* void (
* __ERROR_CODE__, // Result of operation.
* std::vector<__REASON_CODE__>, // Vector of Reason Codes indicating
* // the subscription result for each Topic
* // in the SUBSCRIBE packet.
* __SUBACK_PROPS__, // Properties received in the SUBACK packet.
* )
* \endcode
*
* \par Completion condition
* The asynchronous operation will complete when one of the following conditions is true:\n
* - The Client has successfully sent a \__SUBSCRIBE\__ packet
* and has received a \__SUBACK\__ response from the Broker.\n
* - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n
* \par Completion condition
* The asynchronous operation will complete when one of the following conditions is true:\n
* - The Client has successfully sent a \__SUBSCRIBE\__ packet
* and has received a \__SUBACK\__ response from the Broker.\n
* - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n
*
* \par Error codes
* The list of all possible error codes that this operation can finish with:\n
* - `boost::system::errc::errc_t::success` \n
* - `boost::asio::error::no_recovery` \n
* - `boost::asio::error::operation_aborted` \n
* - \link boost::mqtt5::client::error::malformed_packet \endlink
* - \link boost::mqtt5::client::error::packet_too_large \endlink
* - \link boost::mqtt5::client::error::pid_overrun \endlink
* - \link boost::mqtt5::client::error::invalid_topic \endlink
* - \link boost::mqtt5::client::error::wildcard_subscription_not_available \endlink
* - \link boost::mqtt5::client::error::subscription_identifier_not_available \endlink
* - \link boost::mqtt5::client::error::shared_subscription_not_available \endlink
* \par Error codes
* The list of all possible error codes that this operation can finish with:\n
* - `boost::system::errc::errc_t::success` \n
* - `boost::asio::error::no_recovery` \n
* - `boost::asio::error::operation_aborted` \n
* - \ref boost::mqtt5::client::error::malformed_packet
* - \ref boost::mqtt5::client::error::packet_too_large
* - \ref boost::mqtt5::client::error::pid_overrun
* - \ref boost::mqtt5::client::error::invalid_topic
* - \ref boost::mqtt5::client::error::wildcard_subscription_not_available
* - \ref boost::mqtt5::client::error::subscription_identifier_not_available
* - \ref boost::mqtt5::client::error::shared_subscription_not_available
*
* Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code.
*
* \par Per-Operation Cancellation
* This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n
* - `cancellation_type::terminal` - invokes \ref mqtt_client::cancel \n
* - `cancellation_type::partial` & `cancellation_type::total` - prevents potential resending of the \__SUBSCRIBE\__ packet \n
* \par Per-Operation Cancellation
* This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n
* - `cancellation_type::terminal` - invokes \ref mqtt_client::cancel \n
* - `cancellation_type::partial` & `cancellation_type::total` - prevents potential resending of the \__SUBSCRIBE\__ packet \n
*
*/
template <
@@ -613,41 +613,41 @@ public:
*
* \par Handler signature
* The handler signature for this operation:
* \code
* void (
* __ERROR_CODE__, // Result of operation.
* std::vector<__REASON_CODE__>, // Vector of Reason Codes containing the
* // single subscription result for the Topic
* // in the SUBSCRIBE packet.
* __SUBACK_PROPS__, // Properties received in the SUBACK packet.
* )
* \endcode
* \code
* void (
* __ERROR_CODE__, // Result of operation.
* std::vector<__REASON_CODE__>, // Vector of Reason Codes containing the
* // single subscription result for the Topic
* // in the SUBSCRIBE packet.
* __SUBACK_PROPS__, // Properties received in the SUBACK packet.
* )
* \endcode
*
* \par Completion condition
* The asynchronous operation will complete when one of the following conditions is true:\n
* - The Client has successfully sent a \__SUBSCRIBE\__ packet
* and has received a \__SUBACK\__ response from the Broker.\n
* - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n
* \par Completion condition
* The asynchronous operation will complete when one of the following conditions is true:\n
* - The Client has successfully sent a \__SUBSCRIBE\__ packet
* and has received a \__SUBACK\__ response from the Broker.\n
* - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n
*
* \par Error codes
* The list of all possible error codes that this operation can finish with:\n
* - `boost::system::errc::errc_t::success` \n
* - `boost::asio::error::no_recovery` \n
* - `boost::asio::error::operation_aborted` \n
* - \link boost::mqtt5::client::error::malformed_packet \endlink
* - \link boost::mqtt5::client::error::packet_too_large \endlink
* - \link boost::mqtt5::client::error::pid_overrun \endlink
* - \link boost::mqtt5::client::error::invalid_topic \endlink
* - \link boost::mqtt5::client::error::wildcard_subscription_not_available \endlink
* - \link boost::mqtt5::client::error::subscription_identifier_not_available \endlink
* - \link boost::mqtt5::client::error::shared_subscription_not_available \endlink
* \par Error codes
* The list of all possible error codes that this operation can finish with:\n
* - `boost::system::errc::errc_t::success` \n
* - `boost::asio::error::no_recovery` \n
* - `boost::asio::error::operation_aborted` \n
* - \ref boost::mqtt5::client::error::malformed_packet
* - \ref boost::mqtt5::client::error::packet_too_large
* - \ref boost::mqtt5::client::error::pid_overrun
* - \ref boost::mqtt5::client::error::invalid_topic
* - \ref boost::mqtt5::client::error::wildcard_subscription_not_available
* - \ref boost::mqtt5::client::error::subscription_identifier_not_available
* - \ref boost::mqtt5::client::error::shared_subscription_not_available
*
* Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code.
*
* \par Per-Operation Cancellation
* This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n
* - `cancellation_type::terminal` - invokes \ref mqtt_client::cancel \n
* - `cancellation_type::partial` & `cancellation_type::total` - prevents potential resending of the \__SUBSCRIBE\__ packet \n
* \par Per-Operation Cancellation
* This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n
* - `cancellation_type::terminal` - invokes \ref mqtt_client::cancel \n
* - `cancellation_type::partial` & `cancellation_type::total` - prevents potential resending of the \__SUBSCRIBE\__ packet \n
*
*/
template <
@@ -682,38 +682,38 @@ public:
*
* \par Handler signature
* The handler signature for this operation:
* \code
* void (
* __ERROR_CODE__, // Result of operation.
* std::vector<__REASON_CODE__>, // Vector of Reason Codes indicating
* // the result of unsubscribe operation
* // for each Topic in the UNSUBSCRIBE packet.
* __UNSUBACK_PROPS__, // Properties received in the UNSUBACK packet.
* )
* \endcode
* \code
* void (
* __ERROR_CODE__, // Result of operation.
* std::vector<__REASON_CODE__>, // Vector of Reason Codes indicating
* // the result of unsubscribe operation
* // for each Topic in the UNSUBSCRIBE packet.
* __UNSUBACK_PROPS__, // Properties received in the UNSUBACK packet.
* )
* \endcode
*
* \par Completion condition
* The asynchronous operation will complete when one of the following conditions is true:\n
* - The Client has successfully sent an \__UNSUBSCRIBE\__ packet
* and has received an \__UNSUBACK\__ response from the Broker.\n
* - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n
* \par Completion condition
* The asynchronous operation will complete when one of the following conditions is true:\n
* - The Client has successfully sent an \__UNSUBSCRIBE\__ packet
* and has received an \__UNSUBACK\__ response from the Broker.\n
* - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n
*
* \par Error codes
* The list of all possible error codes that this operation can finish with:\n
* - `boost::system::errc::errc_t::success` \n
* - `boost::asio::error::no_recovery` \n
* - `boost::asio::error::operation_aborted` \n
* - \link boost::mqtt5::client::error::malformed_packet \endlink
* - \link boost::mqtt5::client::error::packet_too_large \endlink
* - \link boost::mqtt5::client::error::pid_overrun \endlink
* - \link boost::mqtt5::client::error::invalid_topic \endlink
* \par Error codes
* The list of all possible error codes that this operation can finish with:\n
* - `boost::system::errc::errc_t::success` \n
* - `boost::asio::error::no_recovery` \n
* - `boost::asio::error::operation_aborted` \n
* - \ref boost::mqtt5::client::error::malformed_packet
* - \ref boost::mqtt5::client::error::packet_too_large
* - \ref boost::mqtt5::client::error::pid_overrun
* - \ref boost::mqtt5::client::error::invalid_topic
*
* Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code.
*
* \par Per-Operation Cancellation
* This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n
* - `cancellation_type::terminal` - invokes \ref mqtt_client::cancel \n
* - `cancellation_type::partial` & `cancellation_type::total` - prevents potential resending of the \__UNSUBSCRIBE\__ packet \n
* \par Per-Operation Cancellation
* This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n
* - `cancellation_type::terminal` - invokes \ref mqtt_client::cancel \n
* - `cancellation_type::partial` & `cancellation_type::total` - prevents potential resending of the \__UNSUBSCRIBE\__ packet \n
*
*/
template <
@@ -721,7 +721,7 @@ public:
typename asio::default_completion_token<executor_type>::type
>
decltype(auto) async_unsubscribe(
const std::vector<std::string>& topics, const unsubscribe_props& props,
const std::vector<std::string>& topics, const unsubscribe_props& props,
CompletionToken&& token = {}
) {
using Signature = void (
@@ -750,38 +750,38 @@ public:
*
* \par Handler signature
* The handler signature for this operation:
* \code
* void (
* __ERROR_CODE__, // Result of operation.
* std::vector<__REASON_CODE__>, // Vector of Reason Codes containing
* // the result of unsubscribe operation
* // for the Topic in the UNSUBSCRIBE packet.
* __UNSUBACK_PROPS__, // Properties received in the UNSUBACK packet.
* )
* \endcode
* \code
* void (
* __ERROR_CODE__, // Result of operation.
* std::vector<__REASON_CODE__>, // Vector of Reason Codes containing
* // the result of unsubscribe operation
* // for the Topic in the UNSUBSCRIBE packet.
* __UNSUBACK_PROPS__, // Properties received in the UNSUBACK packet.
* )
* \endcode
*
* \par Completion condition
* The asynchronous operation will complete when one of the following conditions is true:\n
* - The Client has successfully sent an \__UNSUBSCRIBE\__ packet
* and has received an \__UNSUBACK\__ response from the Broker.\n
* - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n
* \par Completion condition
* The asynchronous operation will complete when one of the following conditions is true:\n
* - The Client has successfully sent an \__UNSUBSCRIBE\__ packet
* and has received an \__UNSUBACK\__ response from the Broker.\n
* - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n
*
* \par Error codes
* The list of all possible error codes that this operation can finish with:\n
* - `boost::system::errc::errc_t::success` \n
* - `boost::asio::error::no_recovery` \n
* - `boost::asio::error::operation_aborted` \n
* - \link boost::mqtt5::client::error::malformed_packet \endlink
* - \link boost::mqtt5::client::error::packet_too_large \endlink
* - \link boost::mqtt5::client::error::pid_overrun \endlink
* - \link boost::mqtt5::client::error::invalid_topic \endlink
* \par Error codes
* The list of all possible error codes that this operation can finish with:\n
* - `boost::system::errc::errc_t::success` \n
* - `boost::asio::error::no_recovery` \n
* - `boost::asio::error::operation_aborted` \n
* - \ref boost::mqtt5::client::error::malformed_packet
* - \ref boost::mqtt5::client::error::packet_too_large
* - \ref boost::mqtt5::client::error::pid_overrun
* - \ref boost::mqtt5::client::error::invalid_topic
*
* Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code.
*
* \par Per-Operation Cancellation
* This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n
* - `cancellation_type::terminal` - invokes \ref mqtt_client::cancel \n
* - `cancellation_type::partial` & `cancellation_type::total` - prevents potential resending of the \__UNSUBSCRIBE\__ packet \n
* \par Per-Operation Cancellation
* This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n
* - `cancellation_type::terminal` - invokes \ref mqtt_client::cancel \n
* - `cancellation_type::partial` & `cancellation_type::total` - prevents potential resending of the \__UNSUBSCRIBE\__ packet \n
*
*/
template <
@@ -818,34 +818,34 @@ public:
*
* \par Handler signature
* The handler signature for this operation:
* \code
* void (
* __ERROR_CODE__, // Result of operation.
* std::string, // Topic, the origin of the Application Message.
* std::string, // Payload, the content of the Application Message.
* __PUBLISH_PROPS__, // Properties received in the PUBLISH packet.
* )
* \endcode
* \code
* void (
* __ERROR_CODE__, // Result of operation.
* std::string, // Topic, the origin of the Application Message.
* std::string, // Payload, the content of the Application Message.
* __PUBLISH_PROPS__, // Properties received in the PUBLISH packet.
* )
* \endcode
*
* \par Completion condition
* The asynchronous operation will complete when one of the following conditions is true:\n
* - The Client has a pending Application Message in its internal storage
* ready to be received.
* - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n
* The asynchronous operation will complete when one of the following conditions is true:\n
* - The Client has a pending Application Message in its internal storage
* ready to be received.
* - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n
*
* \par Error codes
* The list of all possible error codes that this operation can finish with:\n
* - `boost::system::errc::errc_t::success`\n
* - `boost::asio::error::operation_aborted`\n
* - \link boost::mqtt5::client::error::session_expired \endlink
* \par Error codes
* The list of all possible error codes that this operation can finish with:\n
* - `boost::system::errc::errc_t::success`\n
* - `boost::asio::error::operation_aborted`\n
* - \ref boost::mqtt5::client::error::session_expired
*
* Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code.
*
* \par Per-Operation Cancellation
* This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n
* - `cancellation_type::terminal` \n
* - `cancellation_type::partial` \n
* - `cancellation_type::total` \n
* \par Per-Operation Cancellation
* This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n
* - `cancellation_type::terminal` \n
* - `cancellation_type::partial` \n
* - `cancellation_type::total` \n
*/
template <
typename CompletionToken =
@@ -875,32 +875,32 @@ public:
*
* \par Handler signature
* The handler signature for this operation:
* \code
* void (
* __ERROR_CODE__ // Result of operation.
* )
* \endcode
* \code
* void (
* __ERROR_CODE__ // Result of operation.
* )
* \endcode
*
* \par Completion condition
* The asynchronous operation will complete when one of the following conditions is true:\n
* - The Client has sent a \__DISCONNECT\__ packet.\n
* - 5 seconds have elapsed without a successful send.\n
* - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n
* \par Completion condition
* The asynchronous operation will complete when one of the following conditions is true:\n
* - The Client has sent a \__DISCONNECT\__ packet.\n
* - 5 seconds have elapsed without a successful send.\n
* - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n
*
* \par Error codes
* The list of all possible error codes that this operation can finish with:\n
* - `boost::system::errc::errc_t::success`\n
* - `boost::asio::error::operation_aborted`[footnote
* \par Error codes
* The list of all possible error codes that this operation can finish with:\n
* - `boost::system::errc::errc_t::success`\n
* - `boost::asio::error::operation_aborted`[footnote
This error code can appear if the Client fails to send the \__DISCONNECT\__ packet to the Server.
Regardless, the connection to the Server is terminated, and the Client is cancelled.
]\n
* - \link boost::mqtt5::client::error::malformed_packet \endlink
* - \ref boost::mqtt5::client::error::malformed_packet
*
* Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code.
*
* \par Per-Operation Cancellation
* This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n
* - `cancellation_type::terminal` - invokes \ref mqtt_client::cancel \n
* \par Per-Operation Cancellation
* This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n
* - `cancellation_type::terminal` - invokes \ref mqtt_client::cancel \n
*
*/
template <
@@ -937,32 +937,32 @@ public:
*
* \par Handler signature
* The handler signature for this operation:
* \code
* void (
* __ERROR_CODE__ // Result of operation.
* )
* \endcode
* \code
* void (
* __ERROR_CODE__ // Result of operation.
* )
* \endcode
*
* \par Completion condition
* The asynchronous operation will complete when one of the following conditions is true:\n
* - The Client has attempted to send a \__DISCONNECT\__ packet, regardless of whether
* the sending was successful or not.\n
* - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n
* \par Completion condition
* The asynchronous operation will complete when one of the following conditions is true:\n
* - The Client has attempted to send a \__DISCONNECT\__ packet, regardless of whether
* the sending was successful or not.\n
* - An error occurred. This is indicated by an associated \__ERROR_CODE\__ in the handler.\n
*
* \par Error codes
* The list of all possible error codes that this operation can finish with:\n
* - `boost::system::errc::errc_t::success`\n
* - `boost::asio::error::operation_aborted`[footnote
* \par Error codes
* The list of all possible error codes that this operation can finish with:\n
* - `boost::system::errc::errc_t::success`\n
* - `boost::asio::error::operation_aborted`[footnote
This error code can appear if the Client fails to send the \__DISCONNECT\__ packet to the Server.
Regardless, the connection to the Server is terminated, and the Client is cancelled.
]\n
* - \link boost::mqtt5::client::error::malformed_packet \endlink
* - \ref boost::mqtt5::client::error::malformed_packet
*
* Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code.
*
* \par Per-Operation Cancellation
* This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n
* - `cancellation_type::terminal` - invokes \ref mqtt_client::cancel \n
* \par Per-Operation Cancellation
* This asynchronous operation supports cancellation for the following \__CANCELLATION_TYPE\__ values:\n
* - `cancellation_type::terminal` - invokes \ref mqtt_client::cancel \n
*/
template <
typename CompletionToken =
include/boost/mqtt5/reason_codes.hpp
+53 -53
View File
@@ -35,14 +35,14 @@ enum class category : uint8_t {
* \brief A class holding Reason Code values originating from Control Packets.
*
* \details A Reason Code is a one byte unsigned value that indicates the result of an operation.
* Reason Codes less than 0x80 indicate successful completion of an operation.
* The normal Reason Code for success is 0.
* Reason Code values of 0x80 or greater indicate failure.
* The \__CONNACK\__, \__PUBACK\__, \__PUBREC\__, \__PUBREL\__, \__PUBCOMP\__, \__DISCONNECT\__
* and \__AUTH\__ Control Packets have a single Reason Code as part of the Variable Header.
* The \__SUBACK\__ and \__UNSUBACK\__ packets contain a list of one or more Reason Codes in the Payload.
* Reason Codes less than 0x80 indicate successful completion of an operation.
* The normal Reason Code for success is 0.
* Reason Code values of 0x80 or greater indicate failure.
* The \__CONNACK\__, \__PUBACK\__, \__PUBREC\__, \__PUBREL\__, \__PUBCOMP\__, \__DISCONNECT\__
* and \__AUTH\__ Control Packets have a single Reason Code as part of the Variable Header.
* The \__SUBACK\__ and \__UNSUBACK\__ packets contain a list of one or more Reason Codes in the Payload.
*
* \see See \__REASON_CODES\__ for a complete list of all possible instances of this class.
* \see See \__REASON_CODES\__ for a complete list of all possible instances of this class.
*/
class reason_code {
uint8_t _code;
@@ -204,150 +204,150 @@ public:
namespace reason_codes {
/** No Reason Code. A \ref client::error occurred.*/
/** \brief No Reason Code. A \ref client::error occurred.*/
constexpr reason_code empty {};
/** The operation completed successfully. */
/** \brief The operation completed successfully. */
constexpr reason_code success { 0x00 };
/** Close the connection normally. Do not send the Will Message. */
/** \brief Close the connection normally. Do not send the Will Message. */
constexpr reason_code normal_disconnection { 0x00, category::disconnect };
/** The subscription is accepted with maximum QoS sent at 0. */
/** \brief The subscription is accepted with maximum QoS sent at 0. */
constexpr reason_code granted_qos_0 { 0x00, category::suback };
/** The subscription is accepted with maximum QoS sent at 1. */
/** \brief The subscription is accepted with maximum QoS sent at 1. */
constexpr reason_code granted_qos_1 { 0x01 };
/** The subscription is accepted with maximum QoS sent at 2 */
/** \brief The subscription is accepted with maximum QoS sent at 2 */
constexpr reason_code granted_qos_2 { 0x02 };
/** The Client wishes to disconnect but requires that
/** \brief The Client wishes to disconnect but requires that
the Server also publishes its Will Message. */
constexpr reason_code disconnect_with_will_message { 0x04 };
/** The message is accepted but there are no subscribers. */
/** \brief The message is accepted but there are no subscribers. */
constexpr reason_code no_matching_subscribers { 0x10 };
/** No matching Topic Filter is being used by the Client. */
/** \brief No matching Topic Filter is being used by the Client. */
constexpr reason_code no_subscription_existed { 0x11 };
/** Continue the authentication with another step. */
/** \brief Continue the authentication with another step. */
constexpr reason_code continue_authentication { 0x18 };
/** Initiate a re-authentication. */
/** \brief Initiate a re-authentication. */
constexpr reason_code reauthenticate { 0x19 };
/** The Server does not wish to reveal the reason for the
/** \brief The Server does not wish to reveal the reason for the
failure or none of the other Reason Codes apply. */
constexpr reason_code unspecified_error { 0x80 };
/** Data within the packet could not be correctly parsed. */
/** \brief Data within the packet could not be correctly parsed. */
constexpr reason_code malformed_packet { 0x81 };
/** Data in the packet does not conform to this specification. */
/** \brief Data in the packet does not conform to this specification. */
constexpr reason_code protocol_error { 0x82 };
/** The packet is valid but not accepted by this Server. */
/** \brief The packet is valid but not accepted by this Server. */
constexpr reason_code implementation_specific_error { 0x83 };
/** The Server does not support the requested version of the MQTT protocol. */
/** \brief The Server does not support the requested version of the MQTT protocol. */
constexpr reason_code unsupported_protocol_version { 0x84 };
/** The Client ID is valid but not allowed by this Server. */
/** \brief The Client ID is valid but not allowed by this Server. */
constexpr reason_code client_identifier_not_valid { 0x85 };
/** The Server does not accept the User Name or Password provided. */
/** \brief The Server does not accept the User Name or Password provided. */
constexpr reason_code bad_username_or_password { 0x86 };
/** The request is not authorized. */
/** \brief The request is not authorized. */
constexpr reason_code not_authorized { 0x87 };
/** The MQTT Server is not available. */
/** \brief The MQTT Server is not available. */
constexpr reason_code server_unavailable { 0x88 };
/** The MQTT Server is busy, try again later. */
/** \brief The MQTT Server is busy, try again later. */
constexpr reason_code server_busy { 0x89 };
/** The Client has been banned by administrative action. */
/** \brief The Client has been banned by administrative action. */
constexpr reason_code banned { 0x8a };
/** The Server is shutting down. */
/** \brief The Server is shutting down. */
constexpr reason_code server_shutting_down { 0x8b };
/** The authentication method is not supported or
/** \brief The authentication method is not supported or
does not match the method currently in use. */
constexpr reason_code bad_authentication_method { 0x8c };
/** No packet has been received for 1.5 times the Keepalive time. */
/** \brief No packet has been received for 1.5 times the Keepalive time. */
constexpr reason_code keep_alive_timeout { 0x8d };
/** Another Connection using the same ClientID has connected
/** \brief Another Connection using the same ClientID has connected
causing this Connection to be closed. */
constexpr reason_code session_taken_over { 0x8e };
/** The Topic Filter is not malformed, but it is not accepted. */
/** \brief The Topic Filter is not malformed, but it is not accepted. */
constexpr reason_code topic_filter_invalid { 0x8f };
/** The Topic Name is not malformed, but it is not accepted. */
/** \brief The Topic Name is not malformed, but it is not accepted. */
constexpr reason_code topic_name_invalid { 0x90 };
/** The Packet Identifier is already in use. */
/** \brief The Packet Identifier is already in use. */
constexpr reason_code packet_identifier_in_use { 0x91 };
/** The Packet Identifier is not known. */
/** \brief The Packet Identifier is not known. */
constexpr reason_code packet_identifier_not_found { 0x92 };
/** The Client or Server has received more than the Receive
/** \brief The Client or Server has received more than the Receive
Maximum publication for which it has not sent PUBACK or PUBCOMP. */
constexpr reason_code receive_maximum_exceeded { 0x93 };
/** The Client or Server received a PUBLISH packet containing
/** \brief The Client or Server received a PUBLISH packet containing
a Topic Alias greater than the Maximum Topic Alias. */
constexpr reason_code topic_alias_invalid { 0x94 };
/** The packet exceeded the maximum permissible size. */
/** \brief The packet exceeded the maximum permissible size. */
constexpr reason_code packet_too_large { 0x95 };
/** The received data rate is too high. */
/** \brief The received data rate is too high. */
constexpr reason_code message_rate_too_high { 0x96 };
/** An implementation or administrative imposed limit has been exceeded. */
/** \brief An implementation or administrative imposed limit has been exceeded. */
constexpr reason_code quota_exceeded { 0x97 };
/** The Connection is closed due to an administrative action. */
/** \brief The Connection is closed due to an administrative action. */
constexpr reason_code administrative_action { 0x98 };
/** The Payload does not match the specified Payload Format Indicator. */
/** \brief The Payload does not match the specified Payload Format Indicator. */
constexpr reason_code payload_format_invalid { 0x99 };
/** The Server does not support retained messages. */
/** \brief The Server does not support retained messages. */
constexpr reason_code retain_not_supported { 0x9a };
/** The Server does not support the QoS the Client specified or
/** \brief The Server does not support the QoS the Client specified or
it is greater than the Maximum QoS specified. */
constexpr reason_code qos_not_supported { 0x9b };
/** The Client should temporarily use another server. */
/** \brief The Client should temporarily use another server. */
constexpr reason_code use_another_server { 0x9c };
/** The Client should permanently use another server. */
/** \brief The Client should permanently use another server. */
constexpr reason_code server_moved { 0x9d };
/** The Server does not support Shared Subscriptions for this Client. */
/** \brief The Server does not support Shared Subscriptions for this Client. */
constexpr reason_code shared_subscriptions_not_supported { 0x9e };
/** The connection rate limit has been exceeded. */
/** \brief The connection rate limit has been exceeded. */
constexpr reason_code connection_rate_exceeded { 0x9f };
/** The maximum connection time authorized for this
/** \brief The maximum connection time authorized for this
connection has been exceeded. */
constexpr reason_code maximum_connect_time { 0xa0 };
/** The Server does not support Subscription Identifiers. */
/** \brief The Server does not support Subscription Identifiers. */
constexpr reason_code subscription_ids_not_supported { 0xa1 };
/** The Server does not support Wildcard Subscriptions. */
/** \brief The Server does not support Wildcard Subscriptions. */
constexpr reason_code wildcard_subscriptions_not_supported { 0xa2 };
namespace detail {
include/boost/mqtt5/types.hpp
+27 -26
View File
@@ -17,7 +17,7 @@
namespace boost::mqtt5 {
/** An alias for `boost::system::error_code`. */
/// An alias for `boost::system::error_code`.
using error_code = boost::system::error_code;
/**
@@ -25,13 +25,13 @@ using error_code = boost::system::error_code;
* such as the hostname, port, and path.
*/
struct authority_path {
/** The hostname of the authority as a domain name or an IP address. */
/** \brief The hostname of the authority as a domain name or an IP address. */
std::string host;
/** The port number used for communication. */
/** \brief The port number used for communication. */
std::string port;
/** Specifies the endpoint path relevant to WebSocket connections. */
/** \brief Specifies the endpoint path relevant to WebSocket connections. */
std::string path;
};
@@ -43,13 +43,13 @@ struct authority_path {
* from the sender to the receiver.
*/
enum class qos_e : std::uint8_t {
/** The message arrives at the receiver either once or not at all. */
/** \brief The message arrives at the receiver either once or not at all. */
at_most_once = 0b00,
/** Ensures the message arrives at the receiver at least once. */
/** \brief Ensures the message arrives at the receiver at least once. */
at_least_once = 0b01,
/** All messages arrive at the receiver exactly once without
/** \brief All messages arrive at the receiver exactly once without
loss or duplication of the messages. */
exactly_once = 0b10
};
@@ -61,16 +61,15 @@ enum class qos_e : std::uint8_t {
* store the current message.
*/
enum class retain_e : std::uint8_t {
/** The Server will replace any existing retained message for this Topic
/** \brief The Server will replace any existing retained message for this Topic
with this message. */
yes = 0b1,
/** The Server will not store this message and will not remove or replace
/** \brief The Server will not store this message and will not remove or replace
any existing retained message. */
no = 0b0
};
enum class dup_e : std::uint8_t {
yes = 0b1, no = 0b0
};
@@ -79,15 +78,15 @@ enum class dup_e : std::uint8_t {
* \brief Represents the stage of \__ENHANCED_AUTH\__ process.
*/
enum class auth_step_e {
/** The Client needs to send initial authentication data. */
/** \brief The Client needs to send initial authentication data. */
client_initial,
/** Server responded with reason_codes.continue_authentication and possibly
/** \brief Server responded with reason_codes.continue_authentication and possibly
* authentication data, the Client needs to send further authentication data.
*/
server_challenge,
/** Server responded with reason_codes.success and final
/** \brief Server responded with reason_codes.success and final
* authentication data, which the Client validates.
*/
server_final
@@ -101,10 +100,10 @@ enum class auth_step_e {
* publishing connection.
*/
enum class no_local_e : std::uint8_t {
/** Application Messages can be forwarded to a connection with equal ClientID. */
/** \brief Application Messages can be forwarded to a connection with equal ClientID. */
no = 0b0,
/** Application Messages MUST NOT be forwarded to a connection with equal ClientID. */
/** \brief Application Messages MUST NOT be forwarded to a connection with equal ClientID. */
yes = 0b1
};
@@ -115,10 +114,10 @@ enum class no_local_e : std::uint8_t {
* using this subscription keep the \__RETAIN\__ flag they were published with.
*/
enum class retain_as_published_e : std::uint8_t {
/** Application Messages have the \__RETAIN\__ flag set to 0. */
/** \brief Application Messages have the \__RETAIN\__ flag set to 0. */
dont = 0b0,
/** Application Messages keep the \__RETAIN\__ flag they were published with. */
/** \brief Application Messages keep the \__RETAIN\__ flag they were published with. */
retain = 0b1
};
@@ -129,13 +128,13 @@ enum class retain_as_published_e : std::uint8_t {
* when the subscription is established.
*/
enum class retain_handling_e : std::uint8_t {
/** Send retained messages at the time of subscribe. */
/** \brief Send retained messages at the time of subscribe. */
send = 0b00,
/** 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,
/** Do not send retained messages at the time of subscribe. */
/** \brief Do not send retained messages at the time of subscribe. */
not_send = 0b10
};
@@ -143,16 +142,18 @@ enum class retain_handling_e : std::uint8_t {
* \brief Represents the \__SUBSCRIBE_OPTIONS\__ associated with each Subscription.
*/
struct subscribe_options {
/// Maximum \__QOS\__ level at which the Server can send Application Messages to the Client.
/** \brief Maximum \__QOS\__ level at which the Server can send Application Messages to the Client.
qos_e max_qos = qos_e::exactly_once;
/// Option determining if Application Messages will be forwarded to a connection with an equal ClientID.
/** \brief Option determining if Application Messages will be
forwarded to a connection with an equal ClientID. */
no_local_e no_local = no_local_e::yes;
/// Option determining if Application Message will keep their \__RETAIN\__ flag.
/** \brief Option determining if Application Message will keep their \__RETAIN\__ flag. */
retain_as_published_e retain_as_published = retain_as_published_e::retain;
/// Option determining if retained messages are sent when the subscription is established.
/** \brief Option determining if retained messages are sent
when the subscription is established. */
retain_handling_e retain_handling = retain_handling_e::new_subscription_only;
};
@@ -161,10 +162,10 @@ struct subscribe_options {
* Subscribe Options.
*/
struct subscribe_topic {
/// An UTF-8 Encoded String indicating the Topics to which the Client wants to subscribe.
/** \brief An UTF-8 Encoded String indicating the Topics to which the Client wants to subscribe. */
std::string topic_filter;
/// The \ref subscribe_options associated with the subscription.
/** \brief The \ref subscribe_options associated with the subscription. */
subscribe_options sub_opts;
};