From 57a4e520d9fdeaae66de4980370466da0c6f4286 Mon Sep 17 00:00:00 2001 From: Gordon Wang <36049150+gordonwang0@users.noreply.github.com> Date: Fri, 3 Apr 2020 10:12:15 -0700 Subject: [PATCH] Fix doxygen errors in v3 MQTT documentation --- doc/config/common | 7 +- doc/config/mqtt | 20 ++++ include/aws_iot_mqtt_client.h | 76 +++++++------ include/aws_iot_mqtt_client_common_internal.h | 10 +- include/aws_iot_mqtt_client_interface.h | 17 +-- src/aws_iot_mqtt_client.c | 29 ++++- src/aws_iot_mqtt_client_common_internal.c | 105 ++++++++++++++---- src/aws_iot_mqtt_client_connect.c | 53 ++++----- src/aws_iot_mqtt_client_publish.c | 19 +--- src/aws_iot_mqtt_client_subscribe.c | 33 ------ src/aws_iot_mqtt_client_unsubscribe.c | 16 --- src/aws_iot_mqtt_client_yield.c | 19 ---- 12 files changed, 215 insertions(+), 189 deletions(-) create mode 100644 doc/config/mqtt diff --git a/doc/config/common b/doc/config/common index 535b5140c8..67181c4197 100644 --- a/doc/config/common +++ b/doc/config/common @@ -19,7 +19,6 @@ QUIET = YES # Configure Doxygen for C. OPTIMIZE_OUTPUT_FOR_C = YES TYPEDEF_HIDES_STRUCT = YES -EXTRACT_STATIC = YES # Disable the tab bar and use treeview instead. DISABLE_INDEX = YES @@ -43,10 +42,8 @@ HTML_EXTRA_STYLESHEET = doc/config/html/style.css EXTERNAL_GROUPS = NO EXTERNAL_PAGES = NO -# Enable expansion of Unity test macros. -ENABLE_PREPROCESSING = YES -MACRO_EXPANSION = YES -EXPAND_ONLY_PREDEF = YES +# Preprocessor defines. +PREDEFINED = _ENABLE_THREAD_SUPPORT_ # Alias for starting a dependencies section. ALIASES += dependencies{2}="@section \1_dependencies Dependencies^^@brief Dependencies of the \2.^^^^" diff --git a/doc/config/mqtt b/doc/config/mqtt new file mode 100644 index 0000000000..d028ecef79 --- /dev/null +++ b/doc/config/mqtt @@ -0,0 +1,20 @@ +# Include common configuration options. +@INCLUDE_PATH = doc/config +@INCLUDE = common + +# Basic project information. +PROJECT_NAME = "MQTT" +PROJECT_BRIEF = "MQTT 3.1.1 client library" + +# Library documentation output directory. +HTML_OUTPUT = mqtt + +# Generate Doxygen tag file for this library. +GENERATE_TAGFILE = doc/tag/mqtt.tag + +# Directories containing library source code. +INPUT = include/ \ + src/ + +# Library file names. +FILE_PATTERNS = *mqtt*.c *mqtt*.h *mqtt*.txt diff --git a/include/aws_iot_mqtt_client.h b/include/aws_iot_mqtt_client.h index d5eb53151a..e5fd1d4f04 100644 --- a/include/aws_iot_mqtt_client.h +++ b/include/aws_iot_mqtt_client.h @@ -61,6 +61,7 @@ extern "C" { #include "threads_interface.h" #endif +/** Greatest packet identifier, per MQTT spec */ #define MAX_PACKET_ID 65535 typedef struct _Client AWS_IoT_Client; @@ -118,8 +119,10 @@ typedef struct { bool isRetained; ///< NOT supported. The retained flag for the LWT message (see MQTTAsync_message.retained) QoS qos; ///< QoS of LWT message } IoT_MQTT_Will_Options; +/** Default initializer for will */ extern const IoT_MQTT_Will_Options iotMqttWillOptionsDefault; +/** Default initializer for will */ #define IoT_MQTT_Will_Options_Initializer { {'M', 'Q', 'T', 'W'}, NULL, 0, NULL, 0, false, QOS0 } /** @@ -142,8 +145,10 @@ typedef struct { char *pPassword; ///< Not used in the AWS IoT Service, will need to be cstring if used uint16_t passwordLen; ///< Password Length. 16 bit unsigned integer } IoT_Client_Connect_Params; +/** Default initializer for connect */ extern const IoT_Client_Connect_Params iotClientConnectParamsDefault; +/** Default initializer for connect */ #define IoT_Client_Connect_Params_initializer { {'M', 'Q', 'T', 'C'}, MQTT_3_1_1, NULL, 0, 60, true, false, \ IoT_MQTT_Will_Options_Initializer, NULL, 0, NULL, 0 } @@ -179,8 +184,10 @@ typedef struct { bool isBlockOnThreadLockEnabled; ///< Timeout for Thread blocking calls. Set to 0 to block until lock is obtained. In milliseconds #endif } IoT_Client_Init_Params; +/** Default initializer for client */ extern const IoT_Client_Init_Params iotClientInitParamsDefault; +/** Default initializer for client */ #ifdef _ENABLE_THREAD_SUPPORT_ #define IoT_Client_Init_Params_initializer { true, NULL, 0, NULL, NULL, NULL, 2000, 20000, 5000, true, NULL, NULL, false } #else @@ -228,12 +235,12 @@ typedef void (*pApplicationHandler_t)(AWS_IoT_Client *pClient, char *pTopicName, * */ typedef struct _MessageHandlers { - const char *topicName; - uint16_t topicNameLen; - char resubscribed; - QoS qos; - pApplicationHandler_t pApplicationHandler; - void *pApplicationHandlerData; + const char *topicName; ///< Topic name of subscription + uint16_t topicNameLen; ///< Length of topic name + char resubscribed; ///< Whether this handler was successfully resubscribed in the reconnect workflow + QoS qos; ///< QoS of subscription + pApplicationHandler_t pApplicationHandler; ///< Application function to invoke + void *pApplicationHandlerData; ///< Context to pass to application handler } MessageHandlers; /* Message handlers are indexed by subscription topic */ /** @@ -244,9 +251,9 @@ typedef struct _MessageHandlers { * */ typedef struct _ClientStatus { - ClientState clientState; - bool isPingOutstanding; - bool isAutoReconnectEnabled; + ClientState clientState; ///< The current state of the client's state machine + bool isPingOutstanding; ///< Whether this client is waiting for a ping response + bool isAutoReconnectEnabled; ///< Whether auto-reconnect is enabled for this client } ClientStatus; /** @@ -257,36 +264,35 @@ typedef struct _ClientStatus { * */ typedef struct _ClientData { - uint16_t nextPacketId; + uint16_t nextPacketId; ///< Packet ID to use for the next generated packet - uint32_t packetTimeoutMs; - uint32_t commandTimeoutMs; - uint16_t keepAliveInterval; - uint32_t currentReconnectWaitInterval; - uint32_t counterNetworkDisconnected; + uint32_t packetTimeoutMs; ///< Timeout for reading incoming packets from the network + uint32_t commandTimeoutMs; ///< Timeout for processing outgoing MQTT packets + uint16_t keepAliveInterval; ///< Maximum interval between control packets + uint32_t currentReconnectWaitInterval; ///< Current backoff period for reconnect + uint32_t counterNetworkDisconnected; ///< How many times this client detected a disconnection /* The below values are initialized with the * lengths of the TX/RX buffers and never modified * afterwards */ - size_t writeBufSize; - size_t readBufSize; - size_t readBufIndex; - unsigned char writeBuf[AWS_IOT_MQTT_TX_BUF_LEN]; - unsigned char readBuf[AWS_IOT_MQTT_RX_BUF_LEN]; + size_t writeBufSize; ///< Size of this client's outgoing data buffer + size_t readBufSize; ///< Size of this client's incoming data buffer + size_t readBufIndex; ///< Current offset into the incoming data buffer + unsigned char writeBuf[AWS_IOT_MQTT_TX_BUF_LEN]; ///< Buffer for outgoing data + unsigned char readBuf[AWS_IOT_MQTT_RX_BUF_LEN]; ///< Buffer for incoming data #ifdef _ENABLE_THREAD_SUPPORT_ - bool isBlockOnThreadLockEnabled; - IoT_Mutex_t state_change_mutex; - IoT_Mutex_t tls_read_mutex; - IoT_Mutex_t tls_write_mutex; + bool isBlockOnThreadLockEnabled; ///< Whether to use nonblocking or blocking mutex APIs + IoT_Mutex_t state_change_mutex; ///< Mutex protecting the client's state machine + IoT_Mutex_t tls_read_mutex; ///< Mutex protecting incoming data + IoT_Mutex_t tls_write_mutex; ///< Mutex protecting outgoing data #endif - IoT_Client_Connect_Params options; + IoT_Client_Connect_Params options; ///< Options passed when the client was initialized - MessageHandlers messageHandlers[AWS_IOT_MQTT_NUM_SUBSCRIBE_HANDLERS]; - iot_disconnect_handler disconnectHandler; - - void *disconnectHandlerData; + MessageHandlers messageHandlers[AWS_IOT_MQTT_NUM_SUBSCRIBE_HANDLERS]; ///< Callbacks for incoming messages + iot_disconnect_handler disconnectHandler; ///< Callback when a disconnection is detected + void *disconnectHandlerData; ///< Context for disconnect handler } ClientData; /** @@ -296,12 +302,12 @@ typedef struct _ClientData { * */ struct _Client { - Timer pingTimer; - Timer reconnectDelayTimer; + Timer pingTimer; ///< Timer for MQTT keep-alive mechanism + Timer reconnectDelayTimer; ///< Timer for backoff on reconnect - ClientStatus clientStatus; - ClientData clientData; - Network networkStack; + ClientStatus clientStatus; ///< Client state information + ClientData clientData; ///< Client context + Network networkStack; ///< Table of network function pointers }; /** @@ -372,7 +378,7 @@ bool aws_iot_is_autoreconnect_enabled(AWS_IoT_Client *pClient); * The disconnect handler is called whenever the client disconnects with error * * @param pClient Reference to the IoT Client - * @param pConnectHandler Reference to the new Disconnect Handler + * @param pDisconnectHandler Reference to the new Disconnect Handler * @param pDisconnectHandlerData Reference to the data to be passed as argument when disconnect handler is called * * @return IoT_Error_t Type defining successful/failed API call diff --git a/include/aws_iot_mqtt_client_common_internal.h b/include/aws_iot_mqtt_client_common_internal.h index 9f4d8125ef..ee8ca023eb 100644 --- a/include/aws_iot_mqtt_client_common_internal.h +++ b/include/aws_iot_mqtt_client_common_internal.h @@ -50,7 +50,7 @@ extern "C" { #include "aws_iot_log.h" #include "aws_iot_mqtt_client_interface.h" -/* Enum order should match the packet ids array defined in MQTTFormat.c */ +/** Types of MQTT messages */ typedef enum msgTypes { UNKNOWN = -1, CONNECT = 1, @@ -70,10 +70,10 @@ typedef enum msgTypes { } MessageTypes; /* Macros for parsing header fields from incoming MQTT frame. */ -#define MQTT_HEADER_FIELD_TYPE(_byte) ((_byte >> 4) & 0x0F) -#define MQTT_HEADER_FIELD_DUP(_byte) ((_byte & (1 << 3)) >> 3) -#define MQTT_HEADER_FIELD_QOS(_byte) ((_byte & (3 << 1)) >> 1) -#define MQTT_HEADER_FIELD_RETAIN(_byte) ((_byte & (1 << 0)) >> 0) +#define MQTT_HEADER_FIELD_TYPE(_byte) ((_byte >> 4) & 0x0F) /**< Message type */ +#define MQTT_HEADER_FIELD_DUP(_byte) ((_byte & (1 << 3)) >> 3) /**< DUP flag */ +#define MQTT_HEADER_FIELD_QOS(_byte) ((_byte & (3 << 1)) >> 1) /**< QoS */ +#define MQTT_HEADER_FIELD_RETAIN(_byte) ((_byte & (1 << 0)) >> 0) /**< Retain flag */ /** * Bitfields for the MQTT header byte. diff --git a/include/aws_iot_mqtt_client_interface.h b/include/aws_iot_mqtt_client_interface.h index e12dbc57c8..d7bde2354a 100644 --- a/include/aws_iot_mqtt_client_interface.h +++ b/include/aws_iot_mqtt_client_interface.h @@ -32,7 +32,7 @@ *******************************************************************************/ /** - * @file aws_iot_mqtt_interface.h + * @file aws_iot_mqtt_client_interface.h * @brief Interface definition for MQTT client. */ @@ -120,12 +120,13 @@ IoT_Error_t aws_iot_mqtt_publish(AWS_IoT_Client *pClient, const char *pTopicName * @warning pTopicName and pApplicationHandlerData need to be static in memory. * * @param pClient Reference to the IoT Client - * @param pTopicName Topic Name to publish to. pTopicName needs to be static in memory since - * no malloc are performed by the SDK + * @param pTopicName Topic Name to publish to. pTopicName needs to be static in memory since + * no malloc is performed by the SDK * @param topicNameLen Length of the topic name - * @param pApplicationHandler_t Reference to the handler function for this subscription - * @param pApplicationHandlerData Point to data passed to the callback. - * pApplicationHandlerData also needs to be static in memory since no malloc are performed by the SDK + * @param qos Quality of service for subscription + * @param pApplicationHandler Reference to the handler function for this subscription + * @param pApplicationHandlerData Point to data passed to the callback. pApplicationHandlerData + * also needs to be static in memory since no malloc is performed by the SDK * * @return An IoT Error Type defining successful/failed subscription */ @@ -154,8 +155,8 @@ IoT_Error_t aws_iot_mqtt_resubscribe(AWS_IoT_Client *pClient); * @note Call is blocking. The call returns after the receipt of the UNSUBACK control packet. * * @param pClient Reference to the IoT Client - * @param pTopicName Topic Name to publish to - * @param topicNameLen Length of the topic name + * @param pTopicFilter Topic filter of subscription + * @param topicFilterLen Length of the topic filter * * @return An IoT Error Type defining successful/failed unsubscribe call */ diff --git a/src/aws_iot_mqtt_client.c b/src/aws_iot_mqtt_client.c index 5c92dd6d3a..2e96f9ae28 100644 --- a/src/aws_iot_mqtt_client.c +++ b/src/aws_iot_mqtt_client.c @@ -47,8 +47,11 @@ extern "C" { #include "aws_iot_version.h" #if !DISABLE_METRICS +/** Length of metrics username */ #define SDK_METRICS_LEN 25 +/** Metrics username for AWS IoT */ #define SDK_METRICS_TEMPLATE "?SDK=C&Version=%d.%d.%d" +/** Buffer for metrics username */ static char pUsernameTemp[SDK_METRICS_LEN] = {0}; #endif @@ -70,6 +73,14 @@ ClientState aws_iot_mqtt_get_client_state(AWS_IoT_Client *pClient) { } #ifdef _ENABLE_THREAD_SUPPORT_ +/** + * @brief Lock a mutex in the MQTT client + * + * @param pClient MQTT client + * @param pMutex Mutex to lock + * + * @return IoT_Error_t of mutex operation + */ IoT_Error_t aws_iot_mqtt_client_lock_mutex(AWS_IoT_Client *pClient, IoT_Mutex_t *pMutex) { FUNC_ENTRY; IoT_Error_t threadRc = FAILURE; @@ -92,6 +103,14 @@ IoT_Error_t aws_iot_mqtt_client_lock_mutex(AWS_IoT_Client *pClient, IoT_Mutex_t FUNC_EXIT_RC(SUCCESS); } +/** + * @brief Unlock a mutex in the MQTT client + * + * @param pClient MQTT client + * @param pMutex Mutex to unlock + * + * @return IoT_Error_t of mutex operation + */ IoT_Error_t aws_iot_mqtt_client_unlock_mutex(AWS_IoT_Client *pClient, IoT_Mutex_t *pMutex) { if(NULL == pClient || NULL == pMutex) { return NULL_VALUE_ERROR; @@ -101,6 +120,15 @@ IoT_Error_t aws_iot_mqtt_client_unlock_mutex(AWS_IoT_Client *pClient, IoT_Mutex_ } #endif +/** + * @brief Change the state in an MQTT client + * + * @param pClient MQTT client + * @param expectedCurrentState What the current state of the client should be + * @param newState What the new state of the client should be + * + * @return IoT_Error_t of state change + */ IoT_Error_t aws_iot_mqtt_set_client_state(AWS_IoT_Client *pClient, ClientState expectedCurrentState, ClientState newState) { IoT_Error_t rc; @@ -366,4 +394,3 @@ void aws_iot_mqtt_reset_network_disconnected_count(AWS_IoT_Client *pClient) { #ifdef __cplusplus } #endif - diff --git a/src/aws_iot_mqtt_client_common_internal.c b/src/aws_iot_mqtt_client_common_internal.c index d0868de49d..cd6964160a 100644 --- a/src/aws_iot_mqtt_client_common_internal.c +++ b/src/aws_iot_mqtt_client_common_internal.c @@ -43,13 +43,15 @@ extern "C" { #include #include "aws_iot_mqtt_client_common_internal.h" -/* Max length of packet header */ +/** Max length of packet header */ #define MAX_NO_OF_REMAINING_LENGTH_BYTES 4 /** - * Encodes the message length according to the MQTT algorithm + * @brief Encodes the message length according to the MQTT algorithm + * * @param buf the buffer into which the encoded data is written * @param length the length to be encoded + * * @return the number of bytes written to buffer */ size_t aws_iot_mqtt_internal_write_len_to_buffer(unsigned char *buf, uint32_t length) { @@ -71,10 +73,13 @@ size_t aws_iot_mqtt_internal_write_len_to_buffer(unsigned char *buf, uint32_t le } /** - * Decodes the message length according to the MQTT algorithm - * @param the buffer containing the message - * @param value the decoded length returned - * @return the number of bytes read from the socket + * @brief Decodes the message length according to the MQTT algorithm + * + * @param buf the buffer containing the message + * @param decodedLen value the decoded length returned + * @param readBytesLen output parameter for the number of bytes read from the socket + * + * @return IoT_Error_t indicating decode status */ IoT_Error_t aws_iot_mqtt_internal_decode_remaining_length_from_buffer(unsigned char *buf, uint32_t *decodedLen, uint32_t *readBytesLen) { @@ -102,6 +107,13 @@ IoT_Error_t aws_iot_mqtt_internal_decode_remaining_length_from_buffer(unsigned c FUNC_EXIT_RC(SUCCESS); } +/** + * @brief Calculates the length of the "remaining length" encoding + * + * @param rem_len "remaining length" to encode + * + * @return length of the remaining length encoding + */ uint32_t aws_iot_mqtt_internal_get_final_packet_length_from_remaining_length(uint32_t rem_len) { rem_len += 1; /* header byte */ /* now remaining_length field (MQTT 3.1.1 - 2.2.3)*/ @@ -118,7 +130,8 @@ uint32_t aws_iot_mqtt_internal_get_final_packet_length_from_remaining_length(uin } /** - * Calculates uint16 packet id from two bytes read from the input buffer + * @brief Calculates uint16 packet id from two bytes read from the input buffer + * * Checks Endianness at runtime * * @param pptr pointer to the input buffer - incremented by the number of bytes used & returned @@ -136,7 +149,8 @@ uint16_t aws_iot_mqtt_internal_read_uint16_t(unsigned char **pptr) { } /** - * Writes an integer as 2 bytes to an output buffer. + * @brief Writes an integer as 2 bytes to an output buffer. + * * @param pptr pointer to the output buffer - incremented by the number of bytes used & returned * @param anInt the integer to write */ @@ -148,7 +162,8 @@ void aws_iot_mqtt_internal_write_uint_16(unsigned char **pptr, uint16_t anInt) { } /** - * Reads one character from the input buffer. + * @brief Reads one character from the input buffer. + * * @param pptr pointer to the input buffer - incremented by the number of bytes used & returned * @return the character read */ @@ -159,7 +174,8 @@ unsigned char aws_iot_mqtt_internal_read_char(unsigned char **pptr) { } /** - * Writes one character to an output buffer. + * @brief Writes one character to an output buffer. + * * @param pptr pointer to the output buffer - incremented by the number of bytes used & returned * @param c the character to write */ @@ -168,6 +184,13 @@ void aws_iot_mqtt_internal_write_char(unsigned char **pptr, unsigned char c) { (*pptr)++; } +/** + * @brief Writes a UTF-8 string into an MQTT packet + * + * @param pptr Where the string should be written + * @param string The string to write + * @param stringLen Length to write + */ void aws_iot_mqtt_internal_write_utf8_string(unsigned char **pptr, const char *string, uint16_t stringLen) { /* Nothing that calls this function will have a stringLen with a size larger than 2 bytes (MQTT 3.1.1 - 1.5.3) */ aws_iot_mqtt_internal_write_uint_16(pptr, stringLen); @@ -178,10 +201,19 @@ void aws_iot_mqtt_internal_write_utf8_string(unsigned char **pptr, const char *s } /** - * Initialize the MQTTHeader structure. Used to ensure that Header bits are - * always initialized using the proper mappings. No Endianness issues here since - * the individual fields are all less than a byte. Also generates no warnings since - * all fields are initialized using hex constants + * @brief Initialize the MQTTHeader structure. + * + * Used to ensure that Header bits are always initialized using the proper mappings. + * No Endianness issues here since the individual fields are all less than a byte. + * Also generates no warnings since all fields are initialized using hex constants. + * + * @param pHeader Header to initialize + * @param message_type MQTT packet type + * @param qos Quality of service for packet + * @param dup DUP flag of a publish + * @param retained RETAIN flag of a publish + * + * @return Returns SUCCESS unless an invalid packet type is given. */ IoT_Error_t aws_iot_mqtt_internal_init_header(MQTTHeader *pHeader, MessageTypes message_type, QoS qos, uint8_t dup, uint8_t retained) { @@ -264,6 +296,15 @@ IoT_Error_t aws_iot_mqtt_internal_init_header(MQTTHeader *pHeader, MessageTypes FUNC_EXIT_RC(SUCCESS); } +/** + * @brief Send an MQTT packet on the network + * + * @param pClient MQTT client which holds packet + * @param length Length of packet to send + * @param pTimer Amount of time allowed to send packet + * + * @return IoT_Error_t of send status + */ IoT_Error_t aws_iot_mqtt_internal_send_packet(AWS_IoT_Client *pClient, size_t length, Timer *pTimer) { size_t sentLen, sent; @@ -583,6 +624,15 @@ static IoT_Error_t _aws_iot_mqtt_internal_handle_publish(AWS_IoT_Client *pClient FUNC_EXIT_RC(SUCCESS); } +/** + * @brief Read an MQTT packet from the network + * + * @param pClient MQTT client + * @param pTimer Amount of time allowed to read packet + * @param pPacketType Output parameter for packet read from network + * + * @return IoT_Error_t of read status + */ IoT_Error_t aws_iot_mqtt_internal_cycle_read(AWS_IoT_Client *pClient, Timer *pTimer, uint8_t *pPacketType) { IoT_Error_t rc; @@ -649,12 +699,29 @@ IoT_Error_t aws_iot_mqtt_internal_cycle_read(AWS_IoT_Client *pClient, Timer *pTi return rc; } +/** + * @brief Flush incoming data from the MQTT client + * + * @param pClient Client with data to flush + * + * @return Always returns SUCCESS + */ IoT_Error_t aws_iot_mqtt_internal_flushBuffers( AWS_IoT_Client *pClient ) { pClient->clientData.readBufIndex = 0; return SUCCESS; } -/* only used in single-threaded mode where one command at a time is in process */ +/** + * @brief Wait until a packet is read from the network + * + * Only used in single-threaded mode where one command at a time is in process + * + * @param pClient MQTT client + * @param packetType MQTT packet to read + * @param pTimer Amount of time allowed to read packet + * + * @return IoT_Error_t of read status + */ IoT_Error_t aws_iot_mqtt_internal_wait_for_read(AWS_IoT_Client *pClient, uint8_t packetType, Timer *pTimer) { IoT_Error_t rc; uint8_t read_packet_type; @@ -681,10 +748,10 @@ IoT_Error_t aws_iot_mqtt_internal_wait_for_read(AWS_IoT_Client *pClient, uint8_t /** * Serializes a 0-length packet into the supplied buffer, ready for writing to a socket - * @param buf the buffer into which the packet will be serialized - * @param buflen the length in bytes of the supplied buffer, to avoid overruns - * @param packettype the message type - * @param serialized length + * @param pTxBuf the buffer into which the packet will be serialized + * @param txBufLen the length in bytes of the supplied buffer, to avoid overruns + * @param packetType the message type + * @param pSerializedLength length * @return IoT_Error_t indicating function execution status */ IoT_Error_t aws_iot_mqtt_internal_serialize_zero(unsigned char *pTxBuf, size_t txBufLen, MessageTypes packetType, diff --git a/src/aws_iot_mqtt_client_connect.c b/src/aws_iot_mqtt_client_connect.c index 6cca96566b..fef5577fb5 100644 --- a/src/aws_iot_mqtt_client_connect.c +++ b/src/aws_iot_mqtt_client_connect.c @@ -45,6 +45,7 @@ extern "C" { #include "aws_iot_mqtt_client_interface.h" #include "aws_iot_mqtt_client_common_internal.h" +/** connect flags byte */ typedef union { uint8_t all; /**< all connect flags */ #if defined(REVERSED) @@ -57,27 +58,21 @@ typedef union { unsigned int will : 1; /**< will flag */ unsigned int cleansession : 1; /**< clean session flag */ unsigned int : 1; /**< unused */ - } bits; + } bits; /**< connect flags byte (reversed order) */ #else struct { - unsigned int : 1; - /**< unused */ - unsigned int cleansession : 1; - /**< cleansession flag */ - unsigned int will : 1; - /**< will flag */ - unsigned int willQoS : 2; - /**< will QoS value */ - unsigned int willRetain : 1; - /**< will retain setting */ - unsigned int password : 1; - /**< 3.1 password */ - unsigned int username : 1; /**< 3.1 user name */ - } bits; + unsigned int : 1; /**< unused */ + unsigned int cleansession : 1; /**< cleansession flag */ + unsigned int will : 1; /**< will flag */ + unsigned int willQoS : 2; /**< will QoS value */ + unsigned int willRetain : 1; /**< will retain setting */ + unsigned int password : 1; /**< 3.1 password */ + unsigned int username : 1; /**< 3.1 user name */ + } bits; /**< connect flags byte (normal order) */ #endif } MQTT_Connect_Header_Flags; -/**< connect flags byte */ +/** connack flags byte */ typedef union { uint8_t all; /**< all connack flags */ #if defined(REVERSED) @@ -85,26 +80,24 @@ typedef union { { unsigned int sessionpresent : 1; /**< session present flag */ unsigned int : 7; /**< unused */ - } bits; + } bits; /**< connect flags byte (reverse order) */ #else struct { - unsigned int : 7; - /**< unused */ - unsigned int sessionpresent : 1; /**< session present flag */ - } bits; + unsigned int : 7; /**< unused */ + unsigned int sessionpresent : 1; /**< session present flag */ + } bits; /**< connect flags byte (normal order) */ #endif } MQTT_Connack_Header_Flags; -/**< connack flags byte */ +/** @brief Connect request response codes from server */ typedef enum { - CONNACK_CONNECTION_ACCEPTED = 0, - CONNACK_UNACCEPTABLE_PROTOCOL_VERSION_ERROR = 1, - CONNACK_IDENTIFIER_REJECTED_ERROR = 2, - CONNACK_SERVER_UNAVAILABLE_ERROR = 3, - CONNACK_BAD_USERDATA_ERROR = 4, - CONNACK_NOT_AUTHORIZED_ERROR = 5 -} MQTT_Connack_Return_Codes; /**< Connect request response codes from server */ - + CONNACK_CONNECTION_ACCEPTED = 0, /**< Connection accepted */ + CONNACK_UNACCEPTABLE_PROTOCOL_VERSION_ERROR = 1, /**< Unacceptable protocol version */ + CONNACK_IDENTIFIER_REJECTED_ERROR = 2, /**< Client identifier rejected */ + CONNACK_SERVER_UNAVAILABLE_ERROR = 3, /**< Server unavailable */ + CONNACK_BAD_USERDATA_ERROR = 4, /**< Bad username */ + CONNACK_NOT_AUTHORIZED_ERROR = 5 /**< Not authorized */ +} MQTT_Connack_Return_Codes; /** * Determines the length of the MQTT connect packet that would be produced using the supplied connect options. diff --git a/src/aws_iot_mqtt_client_publish.c b/src/aws_iot_mqtt_client_publish.c index 081a98c2ba..61822ad4a3 100644 --- a/src/aws_iot_mqtt_client_publish.c +++ b/src/aws_iot_mqtt_client_publish.c @@ -242,23 +242,6 @@ static IoT_Error_t _aws_iot_mqtt_internal_publish(AWS_IoT_Client *pClient, const FUNC_EXIT_RC(SUCCESS); } -/** - * @brief Publish an MQTT message on a topic - * - * Called to publish an MQTT message on a topic. - * @note Call is blocking. In the case of a QoS 0 message the function returns - * after the message was successfully passed to the TLS layer. In the case of QoS 1 - * the function returns after the receipt of the PUBACK control packet. - * This is the outer function which does the validations and calls the internal publish above - * to perform the actual operation. It is also responsible for client state changes - * - * @param pClient Reference to the IoT Client - * @param pTopicName Topic Name to publish to - * @param topicNameLen Length of the topic name - * @param pParams Pointer to Publish Message parameters - * - * @return An IoT Error Type defining successful/failed publish - */ IoT_Error_t aws_iot_mqtt_publish(AWS_IoT_Client *pClient, const char *pTopicName, uint16_t topicNameLen, IoT_Publish_Message_Params *pParams) { IoT_Error_t rc, pubRc; @@ -303,7 +286,7 @@ IoT_Error_t aws_iot_mqtt_publish(AWS_IoT_Client *pClient, const char *pTopicName * @param pTopicName returned String - the MQTT topic in the publish * @param topicNameLen returned uint16_t - the length of the MQTT topic in the publish * @param payload returned byte buffer - the MQTT publish payload - * @param payloadlen returned size_t - the length of the MQTT payload + * @param payloadLen returned size_t - the length of the MQTT payload * @param pRxBuf the raw buffer data, of the correct length determined by the remaining length field * @param rxBufLen the length in bytes of the data in the supplied buffer * diff --git a/src/aws_iot_mqtt_client_subscribe.c b/src/aws_iot_mqtt_client_subscribe.c index 13bae2ca99..00e091709b 100644 --- a/src/aws_iot_mqtt_client_subscribe.c +++ b/src/aws_iot_mqtt_client_subscribe.c @@ -273,26 +273,6 @@ static IoT_Error_t _aws_iot_mqtt_internal_subscribe(AWS_IoT_Client *pClient, con FUNC_EXIT_RC(SUCCESS); } -/** - * @brief Subscribe to an MQTT topic. - * - * Called to send a subscribe message to the broker requesting a subscription - * to an MQTT topic. This is the outer function which does the validations and - * calls the internal subscribe above to perform the actual operation. - * It is also responsible for client state changes - * @note Call is blocking. The call returns after the receipt of the SUBACK control packet. - * @warning pTopicName and pApplicationHandlerData need to be static in memory. - * - * @param pClient Reference to the IoT Client - * @param pTopicName Topic Name to publish to. pTopicName needs to be static in memory since - * no malloc are performed by the SDK - * @param topicNameLen Length of the topic name - * @param pApplicationHandler_t Reference to the handler function for this subscription - * @param pApplicationHandlerData Point to data passed to the callback. - * pApplicationHandlerData also needs to be static in memory since no malloc are performed by the SDK - * - * @return An IoT Error Type defining successful/failed subscription - */ IoT_Error_t aws_iot_mqtt_subscribe(AWS_IoT_Client *pClient, const char *pTopicName, uint16_t topicNameLen, QoS qos, pApplicationHandler_t pApplicationHandler, void *pApplicationHandlerData) { ClientState clientState; @@ -406,19 +386,6 @@ static IoT_Error_t _aws_iot_mqtt_internal_resubscribe(AWS_IoT_Client *pClient) { FUNC_EXIT_RC(SUCCESS); } -/** - * @brief Subscribe to an MQTT topic. - * - * Called to send a subscribe message to the broker requesting a subscription - * to an MQTT topic. - * This is the outer function which does the validations and calls the internal resubscribe above - * to perform the actual operation. It is also responsible for client state changes - * @note Call is blocking. The call returns after the receipt of the SUBACK control packet. - * - * @param pClient Reference to the IoT Client - * - * @return An IoT Error Type defining successful/failed subscription - */ IoT_Error_t aws_iot_mqtt_resubscribe(AWS_IoT_Client *pClient) { IoT_Error_t rc, resubRc; ClientState currentState = aws_iot_mqtt_get_client_state(pClient); diff --git a/src/aws_iot_mqtt_client_unsubscribe.c b/src/aws_iot_mqtt_client_unsubscribe.c index ccde6e9b88..1d78a74775 100644 --- a/src/aws_iot_mqtt_client_unsubscribe.c +++ b/src/aws_iot_mqtt_client_unsubscribe.c @@ -196,21 +196,6 @@ static IoT_Error_t _aws_iot_mqtt_internal_unsubscribe(AWS_IoT_Client *pClient, c FUNC_EXIT_RC(SUCCESS); } -/** - * @brief Unsubscribe to an MQTT topic. - * - * Called to send an unsubscribe message to the broker requesting removal of a subscription - * to an MQTT topic. - * @note Call is blocking. The call returns after the receipt of the UNSUBACK control packet. - * This is the outer function which does the validations and calls the internal unsubscribe above - * to perform the actual operation. It is also responsible for client state changes - * - * @param pClient Reference to the IoT Client - * @param pTopicName Topic Name to publish to - * @param topicNameLen Length of the topic name - * - * @return An IoT Error Type defining successful/failed unsubscribe call - */ IoT_Error_t aws_iot_mqtt_unsubscribe(AWS_IoT_Client *pClient, const char *pTopicFilter, uint16_t topicFilterLen) { IoT_Error_t rc, unsubRc; ClientState clientState; @@ -247,4 +232,3 @@ IoT_Error_t aws_iot_mqtt_unsubscribe(AWS_IoT_Client *pClient, const char *pTopic #ifdef __cplusplus } #endif - diff --git a/src/aws_iot_mqtt_client_yield.c b/src/aws_iot_mqtt_client_yield.c index e77a2ad06f..5818dcdf2a 100644 --- a/src/aws_iot_mqtt_client_yield.c +++ b/src/aws_iot_mqtt_client_yield.c @@ -255,25 +255,6 @@ static IoT_Error_t _aws_iot_mqtt_internal_yield(AWS_IoT_Client *pClient, uint32_ FUNC_EXIT_RC(yieldRc); } -/** - * @brief Yield to the MQTT client - * - * Called to yield the current thread to the underlying MQTT client. This time is used by - * the MQTT client to manage PING requests to monitor the health of the TCP connection as - * well as periodically check the socket receive buffer for subscribe messages. Yield() - * must be called at a rate faster than the keepalive interval. It must also be called - * at a rate faster than the incoming message rate as this is the only way the client receives - * processing time to manage incoming messages. - * This is the outer function which does the validations and calls the internal yield above - * to perform the actual operation. It is also responsible for client state changes - * - * @param pClient Reference to the IoT Client - * @param timeout_ms Maximum number of milliseconds to pass thread execution to the client. - * - * @return An IoT Error Type defining successful/failed client processing. - * If this call results in an error it is likely the MQTT connection has dropped. - * iot_is_mqtt_connected can be called to confirm. - */ IoT_Error_t aws_iot_mqtt_yield(AWS_IoT_Client *pClient, uint32_t timeout_ms) { IoT_Error_t rc, yieldRc; ClientState clientState;