boost/mqtt5/types.hpp

0001 //
0002 // Copyright (c) 2023-2025 Ivica Siladic, Bruno Iljazovic, Korina Simicevic
0003 //
0004 // Distributed under the Boost Software License, Version 1.0.
0005 // (See accompanying file LICENSE or copy at http://www.boost.org/LICENSE_1_0.txt)
0006 //
0007
0008 #ifndef BOOST_MQTT5_TYPES_HPP
0009 #define BOOST_MQTT5_TYPES_HPP
0010
0011 #include <boost/mqtt5/property_types.hpp>
0012
0013 #include <boost/system/error_code.hpp>
0014
0015 #include <cstdint>
0016 #include <string>
0017
0018 namespace boost::mqtt5 {
0019
0020 /// An alias for `boost::system::error_code`.
0021 using error_code = boost::system::error_code;
0022
0023 /**
0024  * \brief A data structure used to store information related to an authority
0025  * such as the hostname, port, and path.
0026  */
0027 struct authority_path {
0028     /** \brief The hostname of the authority as a domain name or an IP address. */
0029     std::string host;
0030
0031     /** \brief The port number used for communication. */
0032     std::string port;
0033
0034     /** \brief Specifies the endpoint path relevant to WebSocket connections. */
0035     std::string path;
0036 };
0037
0038 /**
0039  * \brief Represents the Quality of Service (\__QOS__\)
0040  * property of the \__PUBLISH\__ packets.
0041  *
0042  * \details Determines how the \__PUBLISH\__ packets are delivered
0043  * from the sender to the receiver.
0044  */
0045 enum class qos_e : std::uint8_t {
0046     /** \brief The message arrives at the receiver either once or not at all. */
0047     at_most_once = 0b00,
0048
0049     /** \brief Ensures the message arrives at the receiver at least once. */
0050     at_least_once = 0b01,
0051
0052     /** \brief All messages arrive at the receiver exactly once without
0053      loss or duplication of the messages. */
0054     exactly_once = 0b10
0055 };
0056
0057 /**
0058  * \brief Represents the \__RETAIN\__ flag in the \__PUBLISH\__ packets.
0059  *
0060  * \details This flag informs the Server about whether or not it should
0061  * store the current message.
0062  */
0063 enum class retain_e : std::uint8_t {
0064     /** \brief The Server will replace any existing retained message for this Topic
0065      with this message. */
0066     yes = 0b1,
0067
0068     /** \brief The Server will not store this message and will not remove or replace
0069      any existing retained message. */
0070     no = 0b0
0071 };
0072
0073 enum class dup_e : std::uint8_t {
0074     yes = 0b1, no = 0b0
0075 };
0076
0077 /**
0078  * \brief Represents the stage of \__ENHANCED_AUTH\__ process.
0079  */
0080 enum class auth_step_e {
0081     /** \brief The Client needs to send initial authentication data. */
0082     client_initial,
0083
0084     /** \brief Server responded with \ref reason_codes::continue_authentication and possibly
0085      * authentication data, the Client needs to send further authentication data.
0086      */
0087     server_challenge,
0088
0089     /** \brief Server responded with \ref reason_codes::success and final
0090      * authentication data, which the Client validates.
0091      */
0092     server_final
0093 };
0094
0095 /**
0096  * \brief Representation of the No Local Subscribe Option.
0097  *
0098  * \details A Subscribe Option indicating whether or not Application Messages
0099  * will be forwarded to a connection with a ClientID equal to the ClientID of the
0100  * publishing connection.
0101  */
0102 enum class no_local_e : std::uint8_t {
0103     /** \brief Application Messages can be forwarded to a connection with equal ClientID. */
0104     no = 0b0,
0105
0106     /** \brief  Application Messages MUST NOT be forwarded to a connection with equal ClientID. */
0107     yes = 0b1
0108 };
0109
0110 /**
0111  * \brief Representation of the Retain As Published Subscribe Option.
0112  *
0113  * \details A Subscribe Option indicating whether or not Application Messages forwarded
0114  * using this Subscription keep the \__RETAIN\__ flag they were published with.
0115  */
0116 enum class retain_as_published_e : std::uint8_t {
0117     /** \brief Application Messages have the \__RETAIN\__ flag set to 0. */
0118     dont = 0b0,
0119
0120     /** \brief Application Messages keep the \__RETAIN\__ flag they were published with. */
0121     retain = 0b1
0122 };
0123
0124 /**
0125  * \brief Representation of the Retain Handling Subscribe Option.
0126  *
0127  * \details A Subscribe Option specifying whether retained messages are sent
0128  * when the Subscription is established.
0129  */
0130 enum class retain_handling_e : std::uint8_t {
0131     /** \brief Send retained messages at the time of subscribe. */
0132     send = 0b00,
0133
0134     /** \brief Send retained message only if the Subscription does not currently exist. */
0135     new_subscription_only = 0b01,
0136
0137     /** \brief Do not send retained messages at the time of subscribe. */
0138     not_send = 0b10
0139 };
0140
0141 /**
0142  * \brief Represents the \__SUBSCRIBE_OPTIONS\__ associated with each Subscription.
0143  */
0144 struct subscribe_options {
0145     /** \brief Maximum \__QOS\__ level at which the Server can send Application Messages to the Client. */
0146     qos_e max_qos = qos_e::exactly_once;
0147
0148     /** \brief Option determining if Application Messages will be
0149     forwarded to a connection with an equal ClientID. */
0150     no_local_e no_local = no_local_e::yes;
0151
0152     /** \brief Option determining if Application Message will keep their \__RETAIN\__ flag. */
0153     retain_as_published_e retain_as_published = retain_as_published_e::retain;
0154
0155     /** \brief Option determining if retained messages are sent
0156     when the Subscription is established. */
0157     retain_handling_e retain_handling = retain_handling_e::new_subscription_only;
0158 };
0159
0160 /**
0161  * \brief A representation of a Topic Subscription consisting of a Topic Filter and
0162  * Subscribe Options.
0163  */
0164 struct subscribe_topic {
0165     /** \brief An UTF-8 Encoded String indicating the Topics to which the Client wants to subscribe. */
0166     std::string topic_filter;
0167
0168     /** \brief The \ref subscribe_options associated with the Subscription. */
0169     subscribe_options sub_opts;
0170 };
0171
0172 /// \cond internal
0173
0174 class connect_props : public prop::properties<
0175     prop::session_expiry_interval_t,
0176     prop::receive_maximum_t,
0177     prop::maximum_packet_size_t,
0178     prop::topic_alias_maximum_t,
0179     prop::request_response_information_t,
0180     prop::request_problem_information_t,
0181     prop::user_property_t,
0182     prop::authentication_method_t,
0183     prop::authentication_data_t
0184 > {};
0185
0186 class connack_props : public prop::properties<
0187     prop::session_expiry_interval_t,
0188     prop::receive_maximum_t,
0189     prop::maximum_qos_t,
0190     prop::retain_available_t,
0191     prop::maximum_packet_size_t,
0192     prop::assigned_client_identifier_t,
0193     prop::topic_alias_maximum_t,
0194     prop::reason_string_t,
0195     prop::user_property_t,
0196     prop::wildcard_subscription_available_t,
0197     prop::subscription_identifier_available_t,
0198     prop::shared_subscription_available_t,
0199     prop::server_keep_alive_t,
0200     prop::response_information_t,
0201     prop::server_reference_t,
0202     prop::authentication_method_t,
0203     prop::authentication_data_t
0204 > {};
0205
0206 class publish_props : public prop::properties<
0207     prop::payload_format_indicator_t,
0208     prop::message_expiry_interval_t,
0209     prop::content_type_t,
0210     prop::response_topic_t,
0211     prop::correlation_data_t,
0212     prop::subscription_identifier_t,
0213     prop::topic_alias_t,
0214     prop::user_property_t
0215 > {};
0216
0217 // puback, pubcomp
0218 class puback_props : public prop::properties<
0219     prop::reason_string_t,
0220     prop::user_property_t
0221 > {};
0222
0223 class pubcomp_props : public prop::properties<
0224     prop::reason_string_t,
0225     prop::user_property_t
0226 > {};
0227
0228 class pubrec_props : public prop::properties<
0229     prop::reason_string_t,
0230     prop::user_property_t
0231 > {};
0232
0233 class pubrel_props : public prop::properties<
0234     prop::reason_string_t,
0235     prop::user_property_t
0236 > {};
0237
0238
0239 class subscribe_props : public prop::properties<
0240     prop::subscription_identifier_t,
0241     prop::user_property_t
0242 > {};
0243
0244 class suback_props : public prop::properties<
0245     prop::reason_string_t,
0246     prop::user_property_t
0247 > {};
0248
0249 class unsubscribe_props : public prop::properties<
0250     prop::user_property_t
0251 > {};
0252
0253 class unsuback_props : public prop::properties<
0254     prop::reason_string_t,
0255     prop::user_property_t
0256 > {};
0257
0258 class disconnect_props : public prop::properties<
0259     prop::session_expiry_interval_t,
0260     prop::reason_string_t,
0261     prop::user_property_t,
0262     prop::server_reference_t
0263 > {};
0264
0265 class auth_props : public prop::properties<
0266     prop::authentication_method_t,
0267     prop::authentication_data_t,
0268     prop::reason_string_t,
0269     prop::user_property_t
0270 > {};
0271
0272
0273 class will_props : public prop::properties<
0274     prop::will_delay_interval_t,
0275     prop::payload_format_indicator_t,
0276     prop::message_expiry_interval_t,
0277     prop::content_type_t,
0278     prop::response_topic_t,
0279     prop::correlation_data_t,
0280     prop::user_property_t
0281 >{};
0282
0283 /// \endcond
0284
0285 /**
0286  * \brief Represents the Will Message.
0287  *
0288  * \details A Will Message is an Application Message that
0289  * the Broker should publish after the Network Connection is closed
0290  * in cases where the Network Connection is not closed normally.
0291  */
0292 class will : public will_props {
0293     std::string _topic;
0294     std::string _message;
0295     qos_e _qos; retain_e _retain;
0296
0297 public:
0298     /**
0299      * \brief Constructs an empty Will Message.
0300      *
0301      * \attention Do not use!
0302      * An empty Will Message results in an empty Topic Name which is not valid.
0303      * Internal uses only.
0304      */
0305     will() = default;
0306
0307     /**
0308      * \brief Construct a Will Message.
0309      *
0310      * \param topic Topic, identification of the information channel to which
0311      * the Will Message will be published.
0312      * \param message The message that will be published.
0313      * \param qos The \ref qos_e level used when publishing the Will Message.
0314      * \param retain The \ref retain_e flag specifying if the Will Message
0315      * is to be retained when it is published.
0316      */
0317     will(
0318         std::string topic, std::string message,
0319         qos_e qos = qos_e::at_most_once, retain_e retain = retain_e::no
0320     ) :
0321         _topic(std::move(topic)), _message(std::move(message)),
0322         _qos(qos), _retain(retain)
0323     {}
0324
0325     /**
0326      * \brief Construct a Will Message.
0327      *
0328      * \param topic Topic name, identification of the information channel to which
0329      * the Will Message will be published.
0330      * \param message The message that will be published.
0331      * \param qos The \ref qos_e level used when publishing the Will Message.
0332      * \param retain The \ref retain_e flag specifying if the Will Message
0333      * is to be retained when it is published.
0334      * \param props Will properties.
0335      */
0336     will(
0337         std::string topic, std::string message,
0338         qos_e qos, retain_e retain, will_props props
0339     ) :
0340         will_props(std::move(props)),
0341         _topic(std::move(topic)), _message(std::move(message)),
0342         _qos(qos), _retain(retain)
0343     {}
0344
0345     /// Get the Topic Name.
0346     std::string_view topic() const {
0347         return _topic;
0348     }
0349
0350     /// Get the Application Message.
0351     std::string_view message() const {
0352         return _message;
0353     }
0354
0355     /// Get the \ref qos_e.
0356     constexpr qos_e qos() const {
0357         return _qos;
0358     }
0359
0360     /// Get the \ref retain_e.
0361     constexpr retain_e retain() const {
0362         return _retain;
0363     }
0364 };
0365
0366
0367 } // end namespace boost::mqtt5
0368
0369 #endif // !BOOST_MQTT5_TYPES_HPP