From 7cb1a877a3e5f19f0d9fdeb265a8989f6ee07bc5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Korina=20=C5=A0imi=C4=8Devi=C4=87?= Date: Thu, 19 Oct 2023 15:05:22 +0200 Subject: [PATCH] [mqtt-client] slightly better error code documentation Summary: related to T12804 Reviewers: ivica Reviewed By: ivica Subscribers: miljen, iljazovic Differential Revision: https://repo.mireo.local/D26165 --- doc/qbk/00_main.qbk | 20 +++++-- doc/qbk/reference/Error_handling.qbk | 52 +++++++++++++++++++ .../{ => concepts}/ExecutionContext.qbk | 0 .../reference/{ => concepts}/StreamType.qbk | 0 .../reference/{ => concepts}/TlsContext.qbk | 0 doc/qbk/reference/quickref.xml | 13 ++--- .../reference/reason_codes/Reason_codes.qbk | 5 +- include/async_mqtt5/error.hpp | 6 ++- include/async_mqtt5/mqtt_client.hpp | 40 +++++++++----- 9 files changed, 109 insertions(+), 27 deletions(-) create mode 100644 doc/qbk/reference/Error_handling.qbk rename doc/qbk/reference/{ => concepts}/ExecutionContext.qbk (100%) rename doc/qbk/reference/{ => concepts}/StreamType.qbk (100%) rename doc/qbk/reference/{ => concepts}/TlsContext.qbk (100%) diff --git a/doc/qbk/00_main.qbk b/doc/qbk/00_main.qbk index 80b9b6a..11dd39f 100644 --- a/doc/qbk/00_main.qbk +++ b/doc/qbk/00_main.qbk @@ -28,6 +28,8 @@ [template beastconceptslink[id term][@boost:/libs/beast/doc/html/beast/concepts/[id].html [term]]] [template mqttlink[id text][@https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc[id] [text]]] +[def __ASIO_PER_OP_CANCELLATION__ [@boost:/doc/html/boost_asio/overview/core/cancellation.html Per-Operation Cancellation]] + [def __CompletionToken__ [@boost:/doc/html/boost_asio/reference/asynchronous_operations.html#boost_asio.reference.asynchronous_operations.completion_tokens_and_handlers ['CompletionToken]]] [def __ExecutionContext__ [reflink2 ExecutionContext ['ExecutionContext]]] [def __StreamType__ [reflink2 StreamType ['StreamType]]] @@ -42,7 +44,9 @@ [def __UTF8_STRING_PAIR__ [mqttlink 3901013 `UTF-8 String Pair`]] [def __PACKET_SIZE__ [mqttlink 3901024 `packet size`]] - +[def __MAXIMUM_QOS__ [mqttlink 3901084 `Maximum QoS`]] +[def __RETAIN_AVAILABLE__ [mqttlink 3901085 `Retain Available`]] +[def __TOPIC_ALIAS_MAX__ [mqttlink 3901051 `Topic Alias Maximum`]] [def __QOS__ [mqttlink 3901234 `QoS`]] [def __SUBSCRIBE_OPTIONS__ [mqttlink 3901169 `Subscribe Options`]] @@ -78,7 +82,10 @@ [def __AUTH_PROPS__ [reflink2 auth_props async_mqtt5::auth_props]] [def __ERROR_CODE__ [reflink2 error_code `async_mqtt5::error_code`]] -[def __REASON_CODE__ [reflink2 Reason_codes `async_mqtt5::reason_code`]] +[def __REASON_CODE__ [reflink2 reason_code `async_mqtt5::reason_code`]] + +[def __REASON_CODES__ [reflink2 Reason_codes `Reason Codes`]] +[def __ERROR_HANDLING__ [reflink2 Error_handling `Error handling`]] [include 01_intro.qbk] @@ -87,9 +94,12 @@ [block''''''] [include reference.qbk] -[include reference/ExecutionContext.qbk] -[include reference/StreamType.qbk] -[include reference/TlsContext.qbk] + +[include reference/Error_handling.qbk] + +[include reference/concepts/ExecutionContext.qbk] +[include reference/concepts/StreamType.qbk] +[include reference/concepts/TlsContext.qbk] [include reference/reason_codes/Reason_codes.qbk] diff --git a/doc/qbk/reference/Error_handling.qbk b/doc/qbk/reference/Error_handling.qbk new file mode 100644 index 0000000..3b36f6c --- /dev/null +++ b/doc/qbk/reference/Error_handling.qbk @@ -0,0 +1,52 @@ +[/ + Copyright (c) 2023 Mireo + + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +] + +[section:async_mqtt5__Error_handling Error handling] + +The table below provides a reference of all __ERROR_CODE__ instances that asynchronous operations +may complete with, along with the reasons for their occurrence. + +[table:error_codes Error codes + [[Error code] [Cause]] + [[`boost::system::errc::errc_t::success`] [The operation completed successfully.]] + [[`boost::asio::error::opreation_aborted`] [ + The operation has been cancelled. + The cancellation of the operation can be triggered by invoking either [refmem mqtt_client cancel] + or [refmem mqtt_client async_disconnect]. Furthermore, if a cancellation slot has been associated + with the __CompletionToken__ provided and the corresponding cancellation signal is emitted, + the operation will also finish with this error code (see __ASIO_PER_OP_CANCELLATION__). + ]] + [[`boost::asio::experimental::error::channel_cancelled`] [ + This error occurs in scenarios identical to those causing `boost::asio::error::operation_aborted` + error code but it is exclusive to completion handlers associated with [refmem mqtt_client async_receive] calls. + ]] + [[`async_mqtt5::client::error::pid_overrun`] [ + This error code signifies that the Client was unable to allocate a Packet Identifier for + the current operation due to the exhaustion of the available identifiers. + This occurs when there are 65535 outgoing Packets awaiting their responses. + ]] + [[`async_mqtt5::client::error::qos_not_supported`] [ + The Client has attempted to publish an Application Message with __QOS__ higher + than the Maximum __QOS__ specified by the Server. + The Server does not support this __QOS__ (see __MAXIMUM_QOS__). + This error code is exclusive to completion handlers associated with [refmem mqtt_client async_publish] calls. + ]] + [[`async_mqtt5::client::error::retain_not_available`] [ + The Client has attempted to publish an Application Message with the RETAIN flag set to 1. + However, the Server does not support retained messages (see __RETAIN_AVAILABLE__). + This error code is exclusive to completion handlers associated with [refmem mqtt_client async_publish] calls. + ]] + [[`async_mqtt5::client::error::topic_alias_maximum`] [ + The Client has attempted to publish an Application Message with the Topic Alias + exceeding the Server's supported Topic Alias Maximum. Additionally, this error code + will arise in instances when the Server does NOT support Topic Aliases, and the + Client has attempted to use them. See __TOPIC_ALIAS_MAX__. + This error code is exclusive to completion handlers associated with [refmem mqtt_client async_publish] calls. + ]] +] + +[endsect] diff --git a/doc/qbk/reference/ExecutionContext.qbk b/doc/qbk/reference/concepts/ExecutionContext.qbk similarity index 100% rename from doc/qbk/reference/ExecutionContext.qbk rename to doc/qbk/reference/concepts/ExecutionContext.qbk diff --git a/doc/qbk/reference/StreamType.qbk b/doc/qbk/reference/concepts/StreamType.qbk similarity index 100% rename from doc/qbk/reference/StreamType.qbk rename to doc/qbk/reference/concepts/StreamType.qbk diff --git a/doc/qbk/reference/TlsContext.qbk b/doc/qbk/reference/concepts/TlsContext.qbk similarity index 100% rename from doc/qbk/reference/TlsContext.qbk rename to doc/qbk/reference/concepts/TlsContext.qbk diff --git a/doc/qbk/reference/quickref.xml b/doc/qbk/reference/quickref.xml index 5de853a..ef0585a 100644 --- a/doc/qbk/reference/quickref.xml +++ b/doc/qbk/reference/quickref.xml @@ -41,12 +41,6 @@ qos_e retain_e - - - Constants - Reason codes - - Functions get_error_code_category @@ -72,6 +66,13 @@ auth_props + + Reference tables + + Reason codes + Error handling + + diff --git a/doc/qbk/reference/reason_codes/Reason_codes.qbk b/doc/qbk/reference/reason_codes/Reason_codes.qbk index 73cd0d3..2373923 100644 --- a/doc/qbk/reference/reason_codes/Reason_codes.qbk +++ b/doc/qbk/reference/reason_codes/Reason_codes.qbk @@ -5,11 +5,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] - [section:async_mqtt5__Reason_codes Reason codes] -This section lists all possible [reflink2 reason_code reason codes] that can be sent in a -MQTT Control Packet. +This section lists all possible __REASON_CODE__ instances representing +Reason Codes that can be found in MQTT Control Packets. [xinclude rcref.xml] diff --git a/include/async_mqtt5/error.hpp b/include/async_mqtt5/error.hpp index 2b3d34c..1d3516e 100644 --- a/include/async_mqtt5/error.hpp +++ b/include/async_mqtt5/error.hpp @@ -47,8 +47,10 @@ enum class error : int { /** [unused] A fatal error occurred. */ fatal_error = 100, + /// \cond INTERNAL /** Malformed packet has been detected. */ malformed_packet, + /// \endcond /** There are no more available Packet Identifiers to use. */ pid_overrun, @@ -56,7 +58,7 @@ enum class error : int { /** [unused] The Client has reconnected. */ reconnected, - /** The Client has been disconnected. */ + /** [unused] The Client has been disconnected. */ disconnected, // publish @@ -142,6 +144,8 @@ enum class category : uint8_t { * 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. */ class reason_code { uint8_t _code; diff --git a/include/async_mqtt5/mqtt_client.hpp b/include/async_mqtt5/mqtt_client.hpp index d53a1e7..b3c7223 100644 --- a/include/async_mqtt5/mqtt_client.hpp +++ b/include/async_mqtt5/mqtt_client.hpp @@ -184,12 +184,12 @@ public: * \param hosts List of Broker addresses and ports. * Address and ports are separated with a colon `:` while * pairs of addresses and ports are separated with a comma `,`. - * \param default_port Default port to connect to in case the port is not - * explicitly specified in the hosts list. + * \param default_port The default port to connect to in case the port is not + * explicitly specified in the `hosts` list. * * * \par Example - * Some valid hosts string: + * Some valid `hosts` string: * * \code * std::string valid_hosts_1 = "broker1:1883, broker2, broker3:1883"; @@ -247,11 +247,13 @@ public: * \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::operation_aborted` \n + * - `boost::asio::error::operation_aborted` \n * - \link client::error::pid_overrun \endlink * - \link client::error::qos_not_supported \endlink * - \link client::error::retain_not_available \endlink * - \link client::error::topic_alias_maximum_reached \endlink + * + * Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code. */ template decltype(auto) async_publish( @@ -311,8 +313,10 @@ public: * \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::operation_aborted` \n + * - `boost::asio::error::operation_aborted` \n * - \link client::error::pid_overrun \endlink + * + * Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code. */ template decltype(auto) async_subscribe( @@ -366,8 +370,10 @@ public: * \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::operation_aborted` \n + * - `boost::asio::error::operation_aborted` \n * - \link client::error::pid_overrun \endlink + * + * Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code. */ template decltype(auto) async_subscribe( @@ -409,8 +415,10 @@ public: * \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::operation_aborted` \n + * - `boost::asio::error::operation_aborted` \n * - \link client::error::pid_overrun \endlink + * + * Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code. */ template decltype(auto) async_unsubscribe( @@ -453,7 +461,7 @@ public: * \code * void ( * __ERROR_CODE__, // Result of operation. - * std::vector<__REASON__CODE__>, // Vector of Reason Codes containing + * 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. @@ -463,8 +471,10 @@ public: * \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::operation_aborted` \n + * - `boost::asio::error::operation_aborted` \n * - \link client::error::pid_overrun \endlink + * + * Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code. */ template decltype(auto) async_unsubscribe( @@ -508,7 +518,9 @@ public: * \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::experimental::error::channel_cancelled` + * - `boost::asio::experimental::error::channel_cancelled` + * + * Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code. */ template decltype(auto) async_receive(CompletionToken&& token) { @@ -543,8 +555,10 @@ public: * \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::operation_aborted`\n + * - `boost::asio::error::operation_aborted`\n * - `boost::asio::no_recovery`\n + * + * Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code. */ template decltype(auto) async_disconnect( @@ -580,8 +594,10 @@ public: * \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::operation_aborted`\n + * - `boost::asio::error::operation_aborted`\n * - `boost::asio::no_recovery`\n + * + * Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code. */ template decltype(auto) async_disconnect(CompletionToken&& token) {