aws_mqtt_lib.h

Go to the documentation of this file.

/*
 * FreeRTOS
 * Copyright (C) 2017 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.
 *
 * http://aws.amazon.com/freertos
 * http://www.FreeRTOS.org
 */


#ifndef _AWS_MQTT_LIB_H_
#define _AWS_MQTT_LIB_H_

/* This ifndef enables the core MQTT library to be used without
 * providing MQTTConfig.h. All the config values in this case are
 * taken from MQTTConfigDefaults.h. */
#ifndef mqttDO_NOT_USE_CUSTOM_CONFIG
    #include "aws_mqtt_config.h"
#endif
#include "aws_mqtt_config_defaults.h"

/* MQTT buffer includes. */
#include "aws_mqtt_buffer.h"

#define mqttREMAINING_LENGTH_MAX_BYTES    4 
#define mqttREMAINING_LENGTH_MIN_BYTES    1 
#define mqttFIXED_HEADER_MAX_SIZE         ( 1 + mqttREMAINING_LENGTH_MAX_BYTES )
#define mqttFIXED_HEADER_MIN_SIZE         ( 1 + mqttREMAINING_LENGTH_MIN_BYTES )

typedef enum
{
    eMQTTFalse = 0, 
    eMQTTTrue = 1   
} MQTTBool_t;

typedef enum
{
    eMQTTSuccess = 0,                
    eMQTTFailure,                    
    eMQTTClientAlreadyConnected,     
    eMQTTClientConnectionInProgress, 
    eMQTTClientNotConnected,         
    eMQTTNoFreeBuffer,               
    eMQTTSendFailed,                 
    eMQTTMalformedPacketReceived,    
    eMQTTSubscriptionManagerFull     
} MQTTReturnCode_t;

typedef enum
{
    eMQTTRxNextBytePacketType,   
    eMQTTRxNextBytePacketLength, 
    eMQTTRxNextByteMessage       
} MQTTRxNextByte_t;

typedef enum
{
    eMQTTRxMessageStore, 
    eMQTTRxMessageDrop   
} MQTTRxMessageAction_t;

typedef enum
{
    eMQTTPublish,            
    eMQTTConnACK,            
    eMQTTUnexpectedConnACK,  
    eMQTTPubACK,             
    eMQTTUnexpectedPubACK,   
    eMQTTSubACK,             
    eMQTTUnexpectedSubACK,   
    eMQTTUnSubACK,           
    eMQTTUnexpectedUnSubACK, 
    eMQTTClientDisconnected, 
    eMQTTPacketDropped,      
    eMQTTTimeout,            
    eMQTTPingTimeout         
} MQTTEventType_t;

typedef enum
{
    eMQTTDisconnectReasonMalformedPacket,         
    eMQTTDisconnectReasonBrokerRefusedConnection, 
    eMQTTDisconnectReasonUserRequest,             
    eMQTTDisconnectReasonConnectTimeout           
} MQTTDisconnectReason_t;

typedef enum
{
    eMQTTQoS0 = 0, 
    eMQTTQoS1 = 1, 
    eMQTTQoS2 = 2  
} MQTTQoS_t;

typedef enum
{
    eMQTTNotConnected,         
    eMQTTConnectionInProgress, 
    eMQTTConnected             
} MQTTConnectionState_t;

typedef enum
{
    eMQTTConnACKConnectionAccepted = 0,          
    eMQTTConnACKUnacceptableProtocolVersion = 1, 
    eMQTTConnACKIdentifierRejected = 2,          
    eMQTTConnACKServerUnavailable = 3,           
    eMQTTConnACKBadUsernameOrPassword = 4,       
    eMQTTConnACKUnauthorized = 5                 
} MQTTConnACKReturnCode_t;

typedef enum
{
    eMQTTSubACKSuccessQos0 = 0, 
    eMQTTSubACKSuccessQos1 = 1, 
    eMQTTSubACKSuccessQos2 = 2, 
    eMQTTSubACKFailure = 128    
} MQTTSubACKReturnCode_t;

typedef enum
{
    eMQTTTopicFilterTypeInvalid = 0, 
    eMQTTTopicFilterTypeSimple,      
    eMQTTTopicFilterTypeWildCard     
} MQTTTopicFilterType_t;

typedef struct MQTTConnACKData
{
    MQTTConnACKReturnCode_t xConnACKReturnCode; 
    uint16_t usPacketIdentifier;                
} MQTTConnACKData_t;

typedef struct MQTTSubACKData
{
    MQTTSubACKReturnCode_t xSubACKReturnCode; 
    uint16_t usPacketIdentifier;              
} MQTTSubACKData_t;

typedef struct MQTTUnSubACKData
{
    uint16_t usPacketIdentifier; 
} MQTTUnSubACKData_t;

typedef struct MQTTPubACKData
{
    uint16_t usPacketIdentifier; 
} MQTTPubACKData_t;

typedef struct MQTTPublishData
{
    MQTTQoS_t xQos;             
    const uint8_t * pucTopic;   
    uint16_t usTopicLength;     
    const void * pvData;        
    uint32_t ulDataLength;      
    MQTTBufferHandle_t xBuffer; 
} MQTTPublishData_t;

typedef struct MQTTTimeoutData
{
    uint16_t usPacketIdentifier; 
} MQTTTimeoutData_t;

typedef struct MQTTDisconnectData
{
    MQTTDisconnectReason_t xDisconnectReason; 
} MQTTDisconnectData_t;

typedef struct MQTTCallbackParams
{
    MQTTEventType_t xEventType; 
    /* Only one of the following is meaningful
     * based on the value of xEventType. */
    union
    {
        MQTTConnACKData_t xMQTTConnACKData;   
        MQTTSubACKData_t xMQTTSubACKData;     
        MQTTUnSubACKData_t xMQTTUnSubACKData; 
        MQTTPubACKData_t xMQTTPubACKData;     
        MQTTPublishData_t xPublishData;       
        MQTTTimeoutData_t xTimeoutData;       
        MQTTDisconnectData_t xDisconnectData; 
    } u;
} MQTTEventCallbackParams_t;

typedef MQTTBool_t ( * MQTTEventCallback_t ) ( void * pvCallbackContext,
                                               const MQTTEventCallbackParams_t * const pxParams );

#if ( mqttconfigENABLE_SUBSCRIPTION_MANAGEMENT == 1 )

    typedef MQTTBool_t ( * MQTTPublishCallback_t ) ( void * pvPublishCallbackContext,
                                                     const MQTTPublishData_t * const pxPublishData );

#endif /* mqttconfigENABLE_SUBSCRIPTION_MANAGEMENT */

typedef uint32_t ( * MQTTSend_t ) ( void * pvSendContext,
                                    const uint8_t * const pucData,
                                    uint32_t ulDataLength );

typedef void ( * MQTTGetTicks_t ) ( uint64_t * pxCurrentTickCount );

typedef uint8_t * ( * MQTTGetFreeBuffer_t ) ( uint32_t * pulBufferLength );

typedef void ( * MQTTReturnBuffer_t ) ( uint8_t * pucBuffer );

#if ( mqttconfigENABLE_SUBSCRIPTION_MANAGEMENT == 1 )

    typedef struct MQTTSubscription
    {
        uint8_t ucTopicFilter[ mqttconfigSUBSCRIPTION_MANAGER_MAX_TOPIC_LENGTH ]; 
        uint16_t usTopicFilterLength;                                             
        void * pvPublishCallbackContext;                                          
        MQTTPublishCallback_t pxPublishCallback;                                  
        MQTTBool_t xInUse;                                                        
        MQTTTopicFilterType_t xTopicFilterType;                                   
    } MQTTSubscription_t;

#endif /* mqttconfigENABLE_SUBSCRIPTION_MANAGEMENT */

#if ( mqttconfigENABLE_SUBSCRIPTION_MANAGEMENT == 1 )

    typedef struct MQTTSubscriptionManager
    {
        MQTTSubscription_t xSubscriptions[ mqttconfigSUBSCRIPTION_MANAGER_MAX_SUBSCRIPTIONS ]; 
        uint32_t ulInUseSubscriptions;                                                         
    } MQTTSubscriptionManager_t;

#endif /* mqttconfigENABLE_SUBSCRIPTION_MANAGEMENT */

typedef struct MQTTBufferPoolInterface
{
    MQTTGetFreeBuffer_t pxGetBufferFxn;   
    MQTTReturnBuffer_t pxReturnBufferFxn; 
} MQTTBufferPoolInterface_t;

typedef struct MQTTRxMessageState
{
    MQTTRxNextByte_t xRxNextByte;           
    MQTTRxMessageAction_t xRxMessageAction; 
    uint8_t ucRemaingingLengthFieldBytes;   
    uint32_t ulTotalMessageLength;          
} MQTTRxMessageState_t;

typedef struct MQTTContext
{
    Link_t xTxBufferListHead;                                   
    MQTTBufferHandle_t xRxBuffer;                               
    MQTTRxMessageState_t xRxMessageState;                       
    uint8_t ucRxFixedHeaderBuffer[ mqttFIXED_HEADER_MAX_SIZE ]; 
    uint32_t ulRxMessageReceivedLength;                         
    void * pvCallbackContext;                                   
    MQTTEventCallback_t pxCallback;                             
    void * pvSendContext;                                       
    MQTTSend_t pxMQTTSendFxn;                                   
    MQTTGetTicks_t pxGetTicksFxn;                               
    MQTTBufferPoolInterface_t xBufferPoolInterface;             
    MQTTConnectionState_t xConnectionState;                     
    uint64_t xLastSentMessageTimestamp;                         
    uint32_t ulNextPeriodicInvokeTicks;                         
    uint32_t ulKeepAliveActualIntervalTicks;                    
    uint32_t ulPingRequestTimeoutTicks;                         
    MQTTBool_t xWaitingForPingResp;                             
    #if ( mqttconfigENABLE_SUBSCRIPTION_MANAGEMENT == 1 )
        MQTTSubscriptionManager_t xSubscriptionManager;         
    #endif /* mqttconfigENABLE_SUBSCRIPTION_MANAGEMENT */
} MQTTContext_t;

typedef struct MQTTInitParams
{
    void * pvCallbackContext;                       
    MQTTEventCallback_t pxCallback;                 
    void * pvSendContext;                           
    MQTTSend_t pxMQTTSendFxn;                       
    MQTTGetTicks_t pxGetTicksFxn;                   
    MQTTBufferPoolInterface_t xBufferPoolInterface; 
} MQTTInitParams_t;

typedef struct MQTTConnectParams
{
    uint16_t usKeepAliveIntervalSeconds;     
    uint32_t ulKeepAliveActualIntervalTicks; 
    uint32_t ulPingRequestTimeoutTicks;      
    const uint8_t * pucClientId;             
    uint16_t usClientIdLength;               
    const uint8_t * pucUserName;             
    uint16_t usUserNameLength;               
    uint16_t usPacketIdentifier;             
    uint32_t ulTimeoutTicks;                 
} MQTTConnectParams_t;

typedef struct MQTTSubscribeParams
{
    const uint8_t * pucTopic;                    
    uint16_t usTopicLength;                      
    MQTTQoS_t xQos;                              
    uint16_t usPacketIdentifier;                 
    uint32_t ulTimeoutTicks;                     
    #if ( mqttconfigENABLE_SUBSCRIPTION_MANAGEMENT == 1 )
        void * pvPublishCallbackContext;         
        MQTTPublishCallback_t pxPublishCallback; 
    #endif /* mqttconfigENABLE_SUBSCRIPTION_MANAGEMENT */
} MQTTSubscribeParams_t;

typedef struct MQTTUnsubscribeParams
{
    const uint8_t * pucTopic;    
    uint16_t usTopicLength;      
    uint16_t usPacketIdentifier; 
    uint32_t ulTimeoutTicks;     
} MQTTUnsubscribeParams_t;

typedef struct MQTTPublishParams
{
    const uint8_t * pucTopic;    
    uint16_t usTopicLength;      
    MQTTQoS_t xQos;              
    const void * pvData;         
    uint32_t ulDataLength;       
    uint16_t usPacketIdentifier; 
    uint32_t ulTimeoutTicks;     
} MQTTPublishParams_t;

MQTTReturnCode_t MQTT_Init( MQTTContext_t * pxMQTTContext,
                            const MQTTInitParams_t * const pxInitParams );

MQTTReturnCode_t MQTT_Connect( MQTTContext_t * pxMQTTContext,
                               const MQTTConnectParams_t * const pxConnectParams );

MQTTReturnCode_t MQTT_Disconnect( MQTTContext_t * pxMQTTContext );

MQTTReturnCode_t MQTT_Subscribe( MQTTContext_t * pxMQTTContext,
                                 const MQTTSubscribeParams_t * const pxSubscribeParams );

MQTTReturnCode_t MQTT_Unsubscribe( MQTTContext_t * pxMQTTContext,
                                   const MQTTUnsubscribeParams_t * const pxUnsubscribeParams );

MQTTReturnCode_t MQTT_Publish( MQTTContext_t * pxMQTTContext,
                               const MQTTPublishParams_t * const pxPublishParams );

MQTTReturnCode_t MQTT_ParseReceivedData( MQTTContext_t * pxMQTTContext,
                                         const uint8_t * pucReceivedData,
                                         size_t xReceivedDataLength );

MQTTReturnCode_t MQTT_ReturnBuffer( MQTTContext_t * pxMQTTContext,
                                    MQTTBufferHandle_t xBufferHandle );

uint32_t MQTT_Periodic( MQTTContext_t * pxMQTTContext,
                        uint64_t xCurrentTickCount );

#endif /* _AWS_MQTT_LIB_H_ */