core_mqtt.h

Go to the documentation of this file.

/*
 * coreMQTT <DEVELOPMENT BRANCH>
 * Copyright (C) 2022 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
 *
 * SPDX-License-Identifier: MIT
 *
 * 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
 
/* *INDENT-OFF* */
#ifdef __cplusplus
    extern "C" {
#endif
/* *INDENT-ON* */
 
/* Include MQTT serializer library. */
#include "core_mqtt_serializer.h"
 
/* Include transport interface. */
#include "transport_interface.h"
 
#define MQTT_LIBRARY_VERSION    "v2.3.1+"
#define MQTT_PACKET_ID_INVALID    ( ( uint16_t ) 0U )
 
/* Structures defined in this file. */
struct MQTTPubAckInfo;
struct MQTTContext;
struct MQTTDeserializedInfo;
 
typedef struct MQTTVec MQTTVec_t;
 
typedef uint32_t (* MQTTGetCurrentTimeFunc_t )( void );
 
typedef void (* MQTTEventCallback_t )( struct MQTTContext * pContext,
                                       struct MQTTPacketInfo * pPacketInfo,
                                       struct MQTTDeserializedInfo * pDeserializedInfo );
 
/* @[define_mqtt_retransmitstorepacket] */
typedef bool ( * MQTTStorePacketForRetransmit)( struct MQTTContext * pContext,
                                                uint16_t packetId,
                                                MQTTVec_t * pMqttVec );
/* @[define_mqtt_retransmitstorepacket] */
 
/* @[define_mqtt_retransmitretrievepacket] */
typedef bool ( * MQTTRetrievePacketForRetransmit)( struct MQTTContext * pContext,
                                                   uint16_t packetId,
                                                   uint8_t ** pSerializedMqttVec,
                                                   size_t * pSerializedMqttVecLen );
/* @[define_mqtt_retransmitretrievepacket] */
 
/* @[define_mqtt_retransmitclearpacket] */
typedef void (* MQTTClearPacketForRetransmit)( struct MQTTContext * pContext,
                                               uint16_t packetId );
/* @[define_mqtt_retransmitclearpacket] */
 
typedef enum MQTTConnectionStatus
{
    MQTTNotConnected,     
    MQTTConnected,        
    MQTTDisconnectPending 
} 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;
 
    MQTTPubAckInfo_t * incomingPublishRecords;
 
    size_t outgoingPublishRecordMaxCount;
 
    size_t incomingPublishRecordMaxCount;
 
    TransportInterface_t transportInterface;
 
    MQTTFixedBuffer_t networkBuffer;
 
    uint16_t nextPacketId;
 
    MQTTConnectionStatus_t connectStatus;
 
    MQTTGetCurrentTimeFunc_t getTime;
 
    MQTTEventCallback_t appCallback;
 
    uint32_t lastPacketTxTime;
 
    uint32_t lastPacketRxTime;
 
    bool controlPacketSent;
 
    size_t index;
 
    /* Keep alive members. */
    uint16_t keepAliveIntervalSec; 
    uint32_t pingReqSendTimeMs;    
    bool waitingForPingResp;       
    MQTTStorePacketForRetransmit storeFunction;
 
    MQTTRetrievePacketForRetransmit retrieveFunction;
 
    MQTTClearPacketForRetransmit clearFunction;
} 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_initstatefulqos] */
MQTTStatus_t MQTT_InitStatefulQoS( MQTTContext_t * pContext,
                                   MQTTPubAckInfo_t * pOutgoingPublishRecords,
                                   size_t outgoingPublishCount,
                                   MQTTPubAckInfo_t * pIncomingPublishRecords,
                                   size_t incomingPublishCount );
/* @[declare_mqtt_initstatefulqos] */
 
/* @[declare_mqtt_initretransmits] */
MQTTStatus_t MQTT_InitRetransmits( MQTTContext_t * pContext,
                                   MQTTStorePacketForRetransmit storeFunction,
                                   MQTTRetrievePacketForRetransmit retrieveFunction,
                                   MQTTClearPacketForRetransmit clearFunction );
/* @[declare_mqtt_initretransmits] */
 
/* @[declare_mqtt_checkconnectstatus] */
MQTTStatus_t MQTT_CheckConnectStatus( const MQTTContext_t * pContext );
/* @[declare_mqtt_checkconnectstatus] */
 
/* @[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_cancelcallback] */
MQTTStatus_t MQTT_CancelCallback( const MQTTContext_t * pContext,
                                  uint16_t packetId );
/* @[declare_mqtt_cancelcallback] */
 
/* @[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 );
/* @[declare_mqtt_processloop] */
 
/* @[declare_mqtt_receiveloop] */
MQTTStatus_t MQTT_ReceiveLoop( MQTTContext_t * pContext );
/* @[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] */
 
/* @[declare_mqtt_getbytesinmqttvec] */
size_t MQTT_GetBytesInMQTTVec( const MQTTVec_t * pVec );
/* @[declare_mqtt_getbytesinmqttvec] */
 
/* @[declare_mqtt_serializemqttvec] */
void MQTT_SerializeMQTTVec( uint8_t * pAllocatedMem,
                            const MQTTVec_t * pVec );
/* @[declare_mqtt_serializemqttvec] */
 
/* *INDENT-OFF* */
#ifdef __cplusplus
    }
#endif
/* *INDENT-ON* */
 
#endif /* ifndef CORE_MQTT_H */