Sync MQTT files with 71df018b of CSDK (#205)

* Sync MQTT files with CSDK commit 71df018badd91f92b51f8923b820af9cc3567a23 * Update demos to use new callback signature
2026-10-02 16:24:45 +08:00 · 2020-08-19 16:30:59 -07:00
parent 6dda6d84f5
commit 262cdd9ae5
9 changed files with 1889 additions and 269 deletions
@@ -239,14 +239,11 @@ static void prvMQTTProcessIncomingPublish( MQTTPublishInfo_t * pxPublishInfo );
 *
 * @param[in] pxMQTTContext MQTT context pointer.
 * @param[in] pxPacketInfo Packet Info pointer for the incoming packet.
- * @param[in] usPacketIdentifier Packet identifier of the incoming packet.
- * @param[in] pxPublishInfo Deserialized publish info for the incoming packet if
- * there is an incoming PUBLISH; NULL otherwise
+ * @param[in] pxDeserializedInfo Deserialized information from the incoming packet.
 */
 static void prvEventCallback( MQTTContext_t * pxMQTTContext,
                              MQTTPacketInfo_t * pxPacketInfo,
-                              uint16_t usPacketIdentifier,
-                              MQTTPublishInfo_t * pxPublishInfo );
+                              MQTTDeserializedInfo_t * pxDeserializedInfo );

 /**
 * @brief TLS connect to endpoint democonfigMQTT_BROKER_ENDPOINT.
@@ -673,19 +670,18 @@ static void prvMQTTProcessIncomingPublish( MQTTPublishInfo_t * pxPublishInfo )

 static void prvEventCallback( MQTTContext_t * pxMQTTContext,
                              MQTTPacketInfo_t * pxPacketInfo,
-                              uint16_t usPacketIdentifier,
-                              MQTTPublishInfo_t * pxPublishInfo )
+                              MQTTDeserializedInfo_t * pxDeserializedInfo )
 {
    /* The MQTT context is not used for this demo. */
    ( void ) pxMQTTContext;

    if( ( pxPacketInfo->type & 0xF0U ) == MQTT_PACKET_TYPE_PUBLISH )
    {
-        prvMQTTProcessIncomingPublish( pxPublishInfo );
+        prvMQTTProcessIncomingPublish( pxDeserializedInfo->pPublishInfo );
    }
    else
    {
-        prvMQTTProcessResponse( pxPacketInfo, usPacketIdentifier );
+        prvMQTTProcessResponse( pxPacketInfo, pxDeserializedInfo->packetIdentifier );
    }
 }

@@ -228,14 +228,11 @@ static void prvMQTTProcessIncomingPublish( MQTTPublishInfo_t * pxPublishInfo );
 *
 * @param pxMQTTContext MQTT context pointer.
 * @param pxPacketInfo Packet Info pointer for the incoming packet.
- * @param usPacketIdentifier Packet identifier of the incoming packet.
- * @param pxPublishInfo Deserialized publish info pointer for the incoming
- * packet.
+ * @param pxDeserializedInfo Deserialized information from the incoming packet.
 */
 static void prvEventCallback( MQTTContext_t * pxMQTTContext,
                              MQTTPacketInfo_t * pxPacketInfo,
-                              uint16_t usPacketIdentifier,
-                              MQTTPublishInfo_t * pxPublishInfo );
+                              MQTTDeserializedInfo_t * pxDeserializedInfo );

 /*-----------------------------------------------------------*/

@@ -600,19 +597,18 @@ static void prvMQTTProcessIncomingPublish( MQTTPublishInfo_t * pxPublishInfo )

 static void prvEventCallback( MQTTContext_t * pxMQTTContext,
                              MQTTPacketInfo_t * pxPacketInfo,
-                              uint16_t usPacketIdentifier,
-                              MQTTPublishInfo_t * pxPublishInfo )
+                              MQTTDeserializedInfo_t * pxDeserializedInfo )
 {
    /* The MQTT context is not used for this demo. */
    ( void ) pxMQTTContext;

    if( ( pxPacketInfo->type & 0xF0U ) == MQTT_PACKET_TYPE_PUBLISH )
    {
-        prvMQTTProcessIncomingPublish( pxPublishInfo );
+        prvMQTTProcessIncomingPublish( pxDeserializedInfo->pPublishInfo );
    }
    else
    {
-        prvMQTTProcessResponse( pxPacketInfo, usPacketIdentifier );
+        prvMQTTProcessResponse( pxPacketInfo, pxDeserializedInfo->packetIdentifier );
    }
 }

@@ -19,14 +19,25 @@
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */

+/**
+ * @file mqtt_state.h
+ * @brief Function to keep state of MQTT PUBLISH packet deliveries.
+ */
 #ifndef MQTT_STATE_H
 #define MQTT_STATE_H

 #include "mqtt.h"

+/**
+ * @brief Initializer value for an #MQTTStateCursor_t, indicating a search
+ * should start at the beginning of a state record array
+ */
 #define MQTT_STATE_CURSOR_INITIALIZER    ( size_t ) 0

 /**
+ * @cond DOXYGEN_IGNORE
+ * Doxygen should ignore this section, this enum is private.
+ *
 * @brief Value indicating either send or receive.
 */
 typedef enum MQTTStateOperation
@@ -34,6 +45,7 @@ typedef enum MQTTStateOperation
    MQTT_SEND,
    MQTT_RECEIVE
 } MQTTStateOperation_t;
+/** @endcond */

 /**
 * @brief Cursor for iterating through state records.
@@ -41,7 +53,10 @@ typedef enum MQTTStateOperation
 typedef size_t MQTTStateCursor_t;

 /**
- * @brief Reserve an entry for an outgoing QoS 1/2 publish.
+ * @cond DOXYGEN_IGNORE
+ * Doxygen should ignore this section, this function is private.
+ *
+ * @brief Reserve an entry for an outgoing QoS 1 or Qos 2 publish.
 *
 * @param[in] pMqttContext Initialized MQTT context.
 * @param[in] packetId The ID of the publish packet.
@@ -52,8 +67,12 @@ typedef size_t MQTTStateCursor_t;
 MQTTStatus_t MQTT_ReserveState( MQTTContext_t * pMqttContext,
                                uint16_t packetId,
                                MQTTQoS_t qos );
+/** @endcond */

 /**
+ * @cond DOXYGEN_IGNORE
+ * Doxygen should ignore this section, this function is private.
+ *
 * @brief Calculate the new state for a publish from its qos and operation type.
 *
 * @param[in] opType Send or Receive.
@@ -63,8 +82,12 @@ MQTTStatus_t MQTT_ReserveState( MQTTContext_t * pMqttContext,
 */
 MQTTPublishState_t MQTT_CalculateStatePublish( MQTTStateOperation_t opType,
                                               MQTTQoS_t qos );
+/** @endcond */

 /**
+ * @cond DOXYGEN_IGNORE
+ * Doxygen should ignore this section, this function is private.
+ *
 * @brief Update the state record for a PUBLISH packet.
 *
 * @param[in] pMqttContext Initialized MQTT context.
@@ -81,8 +104,12 @@ MQTTStatus_t MQTT_UpdateStatePublish( MQTTContext_t * pMqttContext,
                                      MQTTStateOperation_t opType,
                                      MQTTQoS_t qos,
                                      MQTTPublishState_t * pNewState );
+/** @endcond */

 /**
+ * @cond DOXYGEN_IGNORE
+ * Doxygen should ignore this section, this function is private.
+ *
 * @brief Calculate the state from a PUBACK, PUBREC, PUBREL, or PUBCOMP.
 *
 * @param[in] packetType PUBACK, PUBREC, PUBREL, or PUBCOMP.
@@ -94,8 +121,12 @@ MQTTStatus_t MQTT_UpdateStatePublish( MQTTContext_t * pMqttContext,
 MQTTPublishState_t MQTT_CalculateStateAck( MQTTPubAckType_t packetType,
                                           MQTTStateOperation_t opType,
                                           MQTTQoS_t qos );
+/** @endcond */

 /**
+ * @cond DOXYGEN_IGNORE
+ * Doxygen should ignore this section, this function is private.
+ *
 * @brief Update the state record for an ACKed publish.
 *
 * @param[in] pMqttContext Initialized MQTT context.
@@ -111,8 +142,12 @@ MQTTStatus_t MQTT_UpdateStateAck( MQTTContext_t * pMqttContext,
                                  MQTTPubAckType_t packetType,
                                  MQTTStateOperation_t opType,
                                  MQTTPublishState_t * pNewState );
+/** @endcond */

 /**
+ * @cond DOXYGEN_IGNORE
+ * Doxygen should ignore this section, this function is private.
+ *
 * @brief Get the packet ID of next pending PUBREL ack to be resent.
 *
 * This function will need to be called to get the packet for which a PUBREL
@@ -127,6 +162,7 @@ MQTTStatus_t MQTT_UpdateStateAck( MQTTContext_t * pMqttContext,
 uint16_t MQTT_PubrelToResend( const MQTTContext_t * pMqttContext,
                              MQTTStateCursor_t * pCursor,
                              MQTTPublishState_t * pState );
+/** @endcond */

 /**
 * @brief Get the packet ID of next pending publish to be resent.
@@ -143,6 +179,9 @@ uint16_t MQTT_PublishToResend( const MQTTContext_t * pMqttContext,
                               MQTTStateCursor_t * pCursor );

 /**
+ * @cond DOXYGEN_IGNORE
+ * Doxygen should ignore this section, this function is private.
+ *
 * @brief State to string conversion for state engine.
 *
 * @param[in] state The state to convert to a string.
@@ -150,5 +189,6 @@ uint16_t MQTT_PublishToResend( const MQTTContext_t * pMqttContext,
 * @return The string representation of the state.
 */
 const char * MQTT_State_strerror( MQTTPublishState_t state );
+/** @endcond */

 #endif /* ifndef MQTT_STATE_H */
@@ -19,6 +19,10 @@
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */

+/**
+ * @file mqtt_state.c
+ * @brief Implements the functions in mqtt_state.h.
+ */
 #include <assert.h>
 #include <string.h>
 #include "mqtt_state.h"
@@ -127,11 +131,11 @@ static void compactRecords( MQTTPubAckInfo_t * records,
 *
 * @param[in] records State record array.
 * @param[in] recordCount Length of record array.
- * @param[in] packetId, packet ID of new entry.
+ * @param[in] packetId Packet ID of new entry.
 * @param[in] qos QoS of new entry.
- * @param[in] publishState state of new entry.
+ * @param[in] publishState State of new entry.
 *
- * @return MQTTSuccess, MQTTNoMemory, MQTTStateCollision.
+ * @return #MQTTSuccess, #MQTTNoMemory, or #MQTTStateCollision.
 */
 static MQTTStatus_t addRecord( MQTTPubAckInfo_t * records,
                               size_t recordCount,
@@ -159,6 +163,8 @@ static void updateRecord( MQTTPubAckInfo_t * records,
 * @param[in] pMqttContext Initialized MQTT context.
 * @param[in] searchStates The states to search for in 2-byte bit map.
 * @param[in,out] pCursor Index at which to start searching.
+ *
+ * @return Packet ID of the outgoing publish.
 */
 static uint16_t stateSelect( const MQTTContext_t * pMqttContext,
                             uint16_t searchStates,
@@ -615,6 +621,15 @@ static uint16_t stateSelect( const MQTTContext_t * pMqttContext,

 /*-----------------------------------------------------------*/

+/**
+ * @brief Calculate the state from a PUBACK, PUBREC, PUBREL, or PUBCOMP.
+ *
+ * @param[in] packetType PUBACK, PUBREC, PUBREL, or PUBCOMP.
+ * @param[in] opType Send or Receive.
+ * @param[in] qos 1 or 2.
+ *
+ * @return The calculated state.
+ */
 MQTTPublishState_t MQTT_CalculateStateAck( MQTTPubAckType_t packetType,
                                           MQTTStateOperation_t opType,
                                           MQTTQoS_t qos )
@@ -779,6 +794,15 @@ static MQTTStatus_t updateStatePublish( MQTTContext_t * pMqttContext,

 /*-----------------------------------------------------------*/

+/**
+ * @brief Reserve an entry for an outgoing QoS 1 or Qos 2 publish.
+ *
+ * @param[in] pMqttContext Initialized MQTT context.
+ * @param[in] packetId The ID of the publish packet.
+ * @param[in] qos 1 or 2.
+ *
+ * @return MQTTSuccess, MQTTNoMemory, or MQTTStateCollision.
+ */
 MQTTStatus_t MQTT_ReserveState( MQTTContext_t * pMqttContext,
                                uint16_t packetId,
                                MQTTQoS_t qos )
@@ -808,6 +832,14 @@ MQTTStatus_t MQTT_ReserveState( MQTTContext_t * pMqttContext,

 /*-----------------------------------------------------------*/

+/**
+ * @brief Calculate the new state for a publish from its qos and operation type.
+ *
+ * @param[in] opType Send or Receive.
+ * @param[in] qos 0, 1, or 2.
+ *
+ * @return The calculated state.
+ */
 MQTTPublishState_t MQTT_CalculateStatePublish( MQTTStateOperation_t opType,
                                               MQTTQoS_t qos )
 {
@@ -837,6 +869,18 @@ MQTTPublishState_t MQTT_CalculateStatePublish( MQTTStateOperation_t opType,

 /*-----------------------------------------------------------*/

+/**
+ * @brief Update the state record for a PUBLISH packet.
+ *
+ * @param[in] pMqttContext Initialized MQTT context.
+ * @param[in] packetId ID of the PUBLISH packet.
+ * @param[in] opType Send or Receive.
+ * @param[in] qos 0, 1, or 2.
+ * @param[out] pNewState Updated state of the publish.
+ *
+ * @return #MQTTBadParameter, #MQTTIllegalState, #MQTTStateCollision or
+ * #MQTTSuccess.
+ */
 MQTTStatus_t MQTT_UpdateStatePublish( MQTTContext_t * pMqttContext,
                                      uint16_t packetId,
                                      MQTTStateOperation_t opType,
@@ -852,8 +896,8 @@ MQTTStatus_t MQTT_UpdateStatePublish( MQTTContext_t * pMqttContext,
    if( ( pMqttContext == NULL ) || ( pNewState == NULL ) )
    {
        LogError( ( "Argument cannot be NULL: pMqttContext=%p, pNewState=%p",
-                    pMqttContext,
-                    pNewState ) );
+                    ( void * ) pMqttContext,
+                    ( void * ) pNewState ) );

        mqttStatus = MQTTBadParameter;
    }
@@ -911,6 +955,17 @@ MQTTStatus_t MQTT_UpdateStatePublish( MQTTContext_t * pMqttContext,

 /*-----------------------------------------------------------*/

+/**
+ * @brief Update the state record for an ACKed publish.
+ *
+ * @param[in] pMqttContext Initialized MQTT context.
+ * @param[in] packetId ID of the ack packet.
+ * @param[in] packetType PUBACK, PUBREC, PUBREL, or PUBCOMP.
+ * @param[in] opType Send or Receive.
+ * @param[out] pNewState Updated state of the publish.
+ *
+ * @return #MQTTBadParameter, #MQTTIllegalState, or #MQTTSuccess.
+ */
 MQTTStatus_t MQTT_UpdateStateAck( MQTTContext_t * pMqttContext,
                                  uint16_t packetId,
                                  MQTTPubAckType_t packetType,
@@ -928,8 +983,8 @@ MQTTStatus_t MQTT_UpdateStateAck( MQTTContext_t * pMqttContext,
    if( ( pMqttContext == NULL ) || ( pNewState == NULL ) )
    {
        LogError( ( "Argument cannot be NULL: pMqttContext=%p, pNewState=%p.",
-                    pMqttContext,
-                    pNewState ) );
+                    ( void * ) pMqttContext,
+                    ( void * ) pNewState ) );
    }
    else
    {
@@ -972,6 +1027,18 @@ MQTTStatus_t MQTT_UpdateStateAck( MQTTContext_t * pMqttContext,

 /*-----------------------------------------------------------*/

+/**
+ * @brief Get the packet ID of next pending PUBREL ack to be resent.
+ *
+ * This function will need to be called to get the packet for which a PUBREL
+ * need to be sent when a session is reestablished. Calling this function
+ * repeatedly until packet id is 0 will give all the packets for which
+ * a PUBREL need to be resent in the correct order.
+ *
+ * @param[in] pMqttContext Initialized MQTT context.
+ * @param[in,out] pCursor Index at which to start searching.
+ * @param[out] pState State indicating that PUBREL packet need to be sent.
+ */
 uint16_t MQTT_PubrelToResend( const MQTTContext_t * pMqttContext,
                              MQTTStateCursor_t * pCursor,
                              MQTTPublishState_t * pState )
@@ -982,11 +1049,11 @@ uint16_t MQTT_PubrelToResend( const MQTTContext_t * pMqttContext,
    /* Validate arguments. */
    if( ( pMqttContext == NULL ) || ( pCursor == NULL ) || ( pState == NULL ) )
    {
-        LogError( ( "Arguments cannot be NULL pMqttContext =%p, pCursor=%p"
+        LogError( ( "Arguments cannot be NULL pMqttContext=%p, pCursor=%p"
                    " pState=%p.",
-                    pMqttContext,
-                    pCursor,
-                    pState ) );
+                    ( void * ) pMqttContext,
+                    ( void * ) pCursor,
+                    ( void * ) pState ) );
    }
    else
    {
@@ -1018,8 +1085,8 @@ uint16_t MQTT_PublishToResend( const MQTTContext_t * pMqttContext,
    if( ( pMqttContext == NULL ) || ( pCursor == NULL ) )
    {
        LogError( ( "Arguments cannot be NULL pMqttContext =%p, pCursor=%p",
-                    pMqttContext,
-                    pCursor ) );
+                    ( void * ) pMqttContext,
+                    ( void * ) pCursor ) );
    }
    else
    {
@@ -1038,6 +1105,13 @@ uint16_t MQTT_PublishToResend( const MQTTContext_t * pMqttContext,

 /*-----------------------------------------------------------*/

+/**
+ * @brief State to string conversion for state engine.
+ *
+ * @param[in] state The state to convert to a string.
+ *
+ * @return The string representation of the state.
+ */
 const char * MQTT_State_strerror( MQTTPublishState_t state )
 {
    const char * str = NULL;
@@ -1,9 +1,41 @@
+/*
+ * Copyright (C) 2020 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+/**
+ * @file mqtt_internal.h
+ * @brief Internal header of the MQTT library. This header should not be
+ * included in typical application code.
+ */
 #ifndef MQTT_INTERNAL_H_
 #define MQTT_INTERNAL_H_

 /* Include config file before other headers. */
 #include "mqtt_config.h"

+/**
+ * @cond DOXYGEN_IGNORE
+ * Doxygen should ignore this section.
+ *
+ * Configure logs for MQTT functions.
+ */
 #ifndef LogError
    #define LogError( message )
 #endif
@@ -19,5 +51,6 @@
 #ifndef LogDebug
    #define LogDebug( message )
 #endif
+/** @endcond */

 #endif /* ifndef MQTT_INTERNAL_H_ */