core_mqtt.h

Go to the documentation of this file.

/*
 * coreMQTT v1.1.0
 * 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.
 */
 
#ifndef CORE_MQTT_H
#define CORE_MQTT_H
 
/* MQTT_DO_NOT_USE_CUSTOM_CONFIG allows building the MQTT library
 * without a custom config. If a custom config is provided, the
 * MQTT_DO_NOT_USE_CUSTOM_CONFIG macro should not be defined. */
#ifndef MQTT_DO_NOT_USE_CUSTOM_CONFIG
    /* Include custom config file before other headers. */
    #include "core_mqtt_config.h"
#endif
 
/* Include config defaults header to get default values of configs not
 * defined in core_mqtt_config.h file. */
#include "core_mqtt_config_defaults.h"
 
/* Include MQTT serializer library. */
#include "core_mqtt_serializer.h"
 
/* Include transport interface. */
#include "transport_interface.h"
 
#define MQTT_LIBRARY_VERSION    "v1.1.0"
 
#define MQTT_PACKET_ID_INVALID    ( ( uint16_t ) 0U )
 
/* Structures defined in this file. */
struct MQTTPubAckInfo;
struct MQTTContext;
struct MQTTDeserializedInfo;
 
typedef uint32_t (* MQTTGetCurrentTimeFunc_t )( void );
 
typedef void (* MQTTEventCallback_t )( struct MQTTContext * pContext,
                                       struct MQTTPacketInfo * pPacketInfo,
                                       struct MQTTDeserializedInfo * pDeserializedInfo );
 
typedef enum MQTTConnectionStatus
{
    MQTTNotConnected, 
    MQTTConnected     
} MQTTConnectionStatus_t;
 
typedef enum MQTTPublishState
{
    MQTTStateNull = 0,  
    MQTTPublishSend,    
    MQTTPubAckSend,     
    MQTTPubRecSend,     
    MQTTPubRelSend,     
    MQTTPubCompSend,    
    MQTTPubAckPending,  
    MQTTPubRecPending,  
    MQTTPubRelPending,  
    MQTTPubCompPending, 
    MQTTPublishDone     
} MQTTPublishState_t;
 
typedef enum MQTTPubAckType
{
    MQTTPuback, 
    MQTTPubrec, 
    MQTTPubrel, 
    MQTTPubcomp 
} MQTTPubAckType_t;
 
typedef enum MQTTSubAckStatus
{
    MQTTSubAckSuccessQos0 = 0x00, 
    MQTTSubAckSuccessQos1 = 0x01, 
    MQTTSubAckSuccessQos2 = 0x02, 
    MQTTSubAckFailure = 0x80      
} MQTTSubAckStatus_t;
 
typedef struct MQTTPubAckInfo
{
    uint16_t packetId;               
    MQTTQoS_t qos;                   
    MQTTPublishState_t publishState; 
} MQTTPubAckInfo_t;
 
typedef struct MQTTContext
{
    MQTTPubAckInfo_t outgoingPublishRecords[ MQTT_STATE_ARRAY_MAX_COUNT ];
 
    MQTTPubAckInfo_t incomingPublishRecords[ MQTT_STATE_ARRAY_MAX_COUNT ];
 
    TransportInterface_t transportInterface;
 
    MQTTFixedBuffer_t networkBuffer;
 
    uint16_t nextPacketId;
 
    MQTTConnectionStatus_t connectStatus;
 
    MQTTGetCurrentTimeFunc_t getTime;
 
    MQTTEventCallback_t appCallback;
 
    uint32_t lastPacketTime;
 
    bool controlPacketSent;
 
    /* Keep alive members. */
    uint16_t keepAliveIntervalSec; 
    uint32_t pingReqSendTimeMs;    
    bool waitingForPingResp;       
} MQTTContext_t;
 
typedef struct MQTTDeserializedInfo
{
    uint16_t packetIdentifier;          
    MQTTPublishInfo_t * pPublishInfo;   
    MQTTStatus_t deserializationResult; 
} MQTTDeserializedInfo_t;
 
/* @[declare_mqtt_init] */
MQTTStatus_t MQTT_Init( MQTTContext_t * pContext,
                        const TransportInterface_t * pTransportInterface,
                        MQTTGetCurrentTimeFunc_t getTimeFunction,
                        MQTTEventCallback_t userCallback,
                        const MQTTFixedBuffer_t * pNetworkBuffer );
/* @[declare_mqtt_init] */
 
/* @[declare_mqtt_connect] */
MQTTStatus_t MQTT_Connect( MQTTContext_t * pContext,
                           const MQTTConnectInfo_t * pConnectInfo,
                           const MQTTPublishInfo_t * pWillInfo,
                           uint32_t timeoutMs,
                           bool * pSessionPresent );
/* @[declare_mqtt_connect] */
 
/* @[declare_mqtt_subscribe] */
MQTTStatus_t MQTT_Subscribe( MQTTContext_t * pContext,
                             const MQTTSubscribeInfo_t * pSubscriptionList,
                             size_t subscriptionCount,
                             uint16_t packetId );
/* @[declare_mqtt_subscribe] */
 
/* @[declare_mqtt_publish] */
MQTTStatus_t MQTT_Publish( MQTTContext_t * pContext,
                           const MQTTPublishInfo_t * pPublishInfo,
                           uint16_t packetId );
/* @[declare_mqtt_publish] */
 
/* @[declare_mqtt_ping] */
MQTTStatus_t MQTT_Ping( MQTTContext_t * pContext );
/* @[declare_mqtt_ping] */
 
/* @[declare_mqtt_unsubscribe] */
MQTTStatus_t MQTT_Unsubscribe( MQTTContext_t * pContext,
                               const MQTTSubscribeInfo_t * pSubscriptionList,
                               size_t subscriptionCount,
                               uint16_t packetId );
/* @[declare_mqtt_unsubscribe] */
 
/* @[declare_mqtt_disconnect] */
MQTTStatus_t MQTT_Disconnect( MQTTContext_t * pContext );
/* @[declare_mqtt_disconnect] */
 
/* @[declare_mqtt_processloop] */
MQTTStatus_t MQTT_ProcessLoop( MQTTContext_t * pContext,
                               uint32_t timeoutMs );
/* @[declare_mqtt_processloop] */
 
/* @[declare_mqtt_receiveloop] */
MQTTStatus_t MQTT_ReceiveLoop( MQTTContext_t * pContext,
                               uint32_t timeoutMs );
/* @[declare_mqtt_receiveloop] */
 
/* @[declare_mqtt_getpacketid] */
uint16_t MQTT_GetPacketId( MQTTContext_t * pContext );
/* @[declare_mqtt_getpacketid] */
 
MQTTStatus_t MQTT_MatchTopic( const char * pTopicName,
                              const uint16_t topicNameLength,
                              const char * pTopicFilter,
                              const uint16_t topicFilterLength,
                              bool * pIsMatch );
 
/* @[declare_mqtt_getsubackstatuscodes] */
MQTTStatus_t MQTT_GetSubAckStatusCodes( const MQTTPacketInfo_t * pSubackPacket,
                                        uint8_t ** pPayloadStart,
                                        size_t * pPayloadSize );
/* @[declare_mqtt_getsubackstatuscodes] */
 
/* @[declare_mqtt_status_strerror] */
const char * MQTT_Status_strerror( MQTTStatus_t status );
/* @[declare_mqtt_status_strerror] */
 
#endif /* ifndef CORE_MQTT_H */