iot_mqtt_types.h

Go to the documentation of this file.

/*
 * IoT MQTT V2.1.0
 * Copyright (C) 2019 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.
 */

#ifndef IOT_MQTT_TYPES_H_
#define IOT_MQTT_TYPES_H_

/* The config header is always included first. */
#include "iot_config.h"

/* Standard includes. */
#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>

/* Type includes. */
#include "types/iot_platform_types.h"

/* Platform network include. */
#include "platform/iot_network.h"

/*---------------------------- MQTT handle types ----------------------------*/

typedef struct _mqttConnection   * IotMqttConnection_t;

typedef struct _mqttOperation    * IotMqttOperation_t;

/*-------------------------- MQTT enumerated types --------------------------*/

typedef enum IotMqttError
{
    IOT_MQTT_SUCCESS = 0,

    IOT_MQTT_STATUS_PENDING = 1,

    IOT_MQTT_INIT_FAILED = 2,

    IOT_MQTT_BAD_PARAMETER = 3,

    IOT_MQTT_NO_MEMORY = 4,

    IOT_MQTT_NETWORK_ERROR = 5,

    IOT_MQTT_SCHEDULING_ERROR = 6,

    IOT_MQTT_BAD_RESPONSE = 7,

    IOT_MQTT_TIMEOUT = 8,

    IOT_MQTT_SERVER_REFUSED = 9,

    IOT_MQTT_RETRY_NO_RESPONSE = 10,

    IOT_MQTT_NOT_INITIALIZED = 11
} IotMqttError_t;

typedef enum IotMqttOperationType
{
    IOT_MQTT_CONNECT,           
    IOT_MQTT_PUBLISH_TO_SERVER, 
    IOT_MQTT_PUBACK,            
    IOT_MQTT_SUBSCRIBE,         
    IOT_MQTT_UNSUBSCRIBE,       
    IOT_MQTT_PINGREQ,           
    IOT_MQTT_DISCONNECT         
} IotMqttOperationType_t;

typedef enum IotMqttQos
{
    IOT_MQTT_QOS_0 = 0, 
    IOT_MQTT_QOS_1 = 1, 
    IOT_MQTT_QOS_2 = 2  
} IotMqttQos_t;

typedef enum IotMqttDisconnectReason
{
    IOT_MQTT_DISCONNECT_CALLED,   
    IOT_MQTT_BAD_PACKET_RECEIVED, 
    IOT_MQTT_KEEP_ALIVE_TIMEOUT   
} IotMqttDisconnectReason_t;

/*------------------------- MQTT parameter structs --------------------------*/

typedef struct IotMqttPublishInfo
{
    IotMqttQos_t qos;         
    bool retain;              
    const char * pTopicName;  
    uint16_t topicNameLength; 
    const void * pPayload;    
    size_t payloadLength;     
    uint32_t retryMs;         
    uint32_t retryLimit;      
} IotMqttPublishInfo_t;

typedef struct IotMqttCallbackParam
{
    IotMqttConnection_t mqttConnection;

    /* MISRA rule 19.2 doesn't allow usage of union
     * but it is intentionally used here to reduce the size of struct. */
    /* coverity[misra_c_2012_rule_19_2_violation] */
    union
    {
        /* Valid for completed operations. */
        struct
        {
            IotMqttOperationType_t type;  
            IotMqttOperation_t reference; 
            IotMqttError_t result;        
        } operation;

        /* Valid for incoming PUBLISH messages. */
        struct
        {
            const char * pTopicFilter;  
            uint16_t topicFilterLength; 
            IotMqttPublishInfo_t info;  
        } message;

        /* Valid when a connection is disconnected. */
        IotMqttDisconnectReason_t disconnectReason; 
    } u;                                            
} IotMqttCallbackParam_t;

typedef struct IotMqttCallbackInfo
{
    void * pCallbackContext; 
    void ( * function )( void * pCallbackContext,
                         IotMqttCallbackParam_t * pCallbackParam );
} IotMqttCallbackInfo_t;

typedef struct IotMqttSubscription
{
    IotMqttQos_t qos;

    const char * pTopicFilter;  
    uint16_t topicFilterLength; 
    IotMqttCallbackInfo_t callback;
} IotMqttSubscription_t;

typedef struct IotMqttConnectInfo
{
    bool awsIotMqttMode;

    bool cleanSession;

    const IotMqttSubscription_t * pPreviousSubscriptions;

    size_t previousSubscriptionCount;

    const IotMqttPublishInfo_t * pWillInfo;

    uint16_t keepAliveSeconds;       
    const char * pClientIdentifier;  
    uint16_t clientIdentifierLength; 
    const char * pUserName;
    uint16_t userNameLength; 
    const char * pPassword;  
    uint16_t passwordLength; 
} IotMqttConnectInfo_t;

typedef struct IotMqttPacketInfo
{
    uint8_t * pRemainingData;     
    size_t remainingLength;       
    uint16_t packetIdentifier;    
    uint8_t type;                 
    IotMqttPublishInfo_t pubInfo; 
} IotMqttPacketInfo_t;

struct _mqttPacket;
typedef uint8_t ( * IotMqttGetPacketType_t )( IotNetworkConnection_t pNetworkConnection,
                                              const IotNetworkInterface_t * pNetworkInterface );

typedef size_t ( * IotMqttGetRemainingLength_t )( IotNetworkConnection_t pNetworkConnection,
                                                  const IotNetworkInterface_t * pNetworkInterface );

typedef void ( * IotMqttFreePacket_t )( uint8_t * pPacket );

typedef IotMqttError_t ( * IotMqttSerializeConnect_t )( const IotMqttConnectInfo_t * pConnectInfo,
                                                        uint8_t ** pConnectPacket,
                                                        size_t * pPacketSize );

typedef IotMqttError_t ( * IotMqttSerializePingreq_t )( uint8_t ** pPingreqPacket,
                                                        size_t * pPacketSize );

typedef IotMqttError_t ( * IotMqtt_SerializePublish_t )( const IotMqttPublishInfo_t * pPublishInfo,
                                                         uint8_t ** pPublishPacket,
                                                         size_t * pPacketSize,
                                                         uint16_t * pPacketIdentifier,
                                                         uint8_t ** pPacketIdentifierHigh );

typedef IotMqttError_t ( * IotMqttSerializeSubscribe_t )( const IotMqttSubscription_t * pSubscriptionList,
                                                          size_t subscriptionCount,
                                                          uint8_t ** pSubscribePacket,
                                                          size_t * pPacketSize,
                                                          uint16_t * pPacketIdentifier );

typedef IotMqttError_t ( * IotMqttSerializeDisconnect_t )( uint8_t ** pDisconnectPacket,
                                                           size_t * pPacketSize );

typedef IotMqttError_t ( * IotMqttDeserialize_t )( struct _mqttPacket * pMqttPacket );

typedef IotMqttError_t ( * IotMqttSerializePuback_t )( uint16_t packetIdentifier,
                                                       uint8_t ** pPubackPacket,
                                                       size_t * pPacketSize );

typedef void ( * IotMqttPublishSetDup_t )( uint8_t * pPublishPacket,
                                           uint8_t * pPacketIdentifierHigh,
                                           uint16_t * pNewPacketIdentifier );

typedef IotMqttError_t (* IotMqttGetNextByte_t)( IotNetworkConnection_t pNetworkContext,
                                                 uint8_t * pNextByte );

#if IOT_MQTT_ENABLE_SERIALIZER_OVERRIDES == 1

    typedef struct IotMqttSerializer
    {
        IotMqttGetPacketType_t getPacketType;

        IotMqttGetRemainingLength_t getRemainingLength;

        IotMqttFreePacket_t freePacket;

        struct
        {
            IotMqttSerializeConnect_t connect;

            IotMqtt_SerializePublish_t publish;

            IotMqttPublishSetDup_t publishSetDup;

            IotMqttSerializePuback_t puback;

            IotMqttSerializeSubscribe_t subscribe;

            IotMqttSerializeSubscribe_t unsubscribe;

            IotMqttSerializePingreq_t pingreq;

            IotMqttSerializeDisconnect_t disconnect;
        } serialize; 
        struct
        {
            IotMqttDeserialize_t connack;

            IotMqttDeserialize_t publish;

            IotMqttDeserialize_t puback;

            IotMqttDeserialize_t suback;

            IotMqttDeserialize_t unsuback;

            IotMqttDeserialize_t pingresp;
        } deserialize; 
    } IotMqttSerializer_t;

#else /* if IOT_MQTT_ENABLE_SERIALIZER_OVERRIDES == 1 */

/* When MQTT packet serializer overrides are disabled, this struct is an
 * incomplete type. */
    typedef struct IotMqttSerializer IotMqttSerializer_t;

#endif /* if IOT_MQTT_ENABLE_SERIALIZER_OVERRIDES == 1 */

typedef struct IotMqttNetworkInfo
{
    bool createNetworkConnection;

    /* MISRA rule 19.2 doesn't allow usage of union
     * but it is intentionally used here to reduce the size of struct. */
    /* coverity[misra_c_2012_rule_19_2_violation] */
    union
    {
        struct
        {
            IotNetworkServerInfo_t pNetworkServerInfo;

            IotNetworkCredentials_t pNetworkCredentialInfo;
        } setup;

        IotNetworkConnection_t pNetworkConnection;
    } u ;

    const IotNetworkInterface_t * pNetworkInterface;

    IotMqttCallbackInfo_t disconnectCallback;

    #if IOT_MQTT_ENABLE_SERIALIZER_OVERRIDES == 1

        const IotMqttSerializer_t * pMqttSerializer;
    #endif
} IotMqttNetworkInfo_t;

/*------------------------- MQTT defined constants --------------------------*/

/* @[define_mqtt_initializers] */
#define IOT_MQTT_NETWORK_INFO_INITIALIZER     { .createNetworkConnection = true }

#define IOT_MQTT_SERIALIZER_INITIALIZER       { 0 }

#define IOT_MQTT_CONNECT_INFO_INITIALIZER     { .cleanSession = true }

#define IOT_MQTT_PUBLISH_INFO_INITIALIZER     { .qos = IOT_MQTT_QOS_0 }

#define IOT_MQTT_SUBSCRIPTION_INITIALIZER     { .qos = IOT_MQTT_QOS_0 }

#define IOT_MQTT_CALLBACK_INFO_INITIALIZER    { 0 }

#define IOT_MQTT_CONNECTION_INITIALIZER       NULL

#define IOT_MQTT_OPERATION_INITIALIZER        NULL

#define IOT_MQTT_PACKET_INFO_INITIALIZER      { .pRemainingData = NULL, remainingLength = 0, packetIdentifier = 0, .type = 0 }
/* @[define_mqtt_initializers] */

#define IOT_MQTT_FLAG_WAITABLE        ( 0x00000001U )

#define IOT_MQTT_FLAG_CLEANUP_ONLY    ( 0x00000001UL )

#endif /* ifndef IOT_MQTT_TYPES_H_ */