core_mqtt_agent.h

Go to the documentation of this file.

/*
 * coreMQTT Agent v1.0.0
 * Copyright (C) 2021 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_AGENT_H
#define CORE_MQTT_AGENT_H
 
/* MQTT library includes. */
#include "core_mqtt.h"
#include "core_mqtt_state.h"
 
/* Command messaging interface include. */
#include "core_mqtt_agent_message_interface.h"
 
#ifndef MQTT_AGENT_MAX_OUTSTANDING_ACKS
    #define MQTT_AGENT_MAX_OUTSTANDING_ACKS    ( 20U )
#endif
 
#ifndef MQTT_AGENT_MAX_EVENT_QUEUE_WAIT_TIME
    #define MQTT_AGENT_MAX_EVENT_QUEUE_WAIT_TIME    ( 1000U )
#endif
 
/*-----------------------------------------------------------*/
 
typedef enum MQTTCommandType
{
    NONE = 0,    
    PROCESSLOOP, 
    PUBLISH,     
    SUBSCRIBE,   
    UNSUBSCRIBE, 
    PING,        
    CONNECT,     
    DISCONNECT,  
    TERMINATE,   
    NUM_COMMANDS 
} MQTTAgentCommandType_t;
 
struct MQTTAgentContext;
struct MQTTAgentCommandContext;
 
typedef struct MQTTAgentReturnInfo
{
    MQTTStatus_t returnCode; 
    uint8_t * pSubackCodes;  
} MQTTAgentReturnInfo_t;
 
typedef struct MQTTAgentCommandContext MQTTAgentCommandContext_t;
 
typedef void (* MQTTAgentCommandCallback_t )( MQTTAgentCommandContext_t * pCmdCallbackContext,
                                              MQTTAgentReturnInfo_t * pReturnInfo );
 
struct MQTTAgentCommand
{
    MQTTAgentCommandType_t commandType;                  
    void * pArgs;                                        
    MQTTAgentCommandCallback_t pCommandCompleteCallback; 
    MQTTAgentCommandContext_t * pCmdContext;             
};
 
typedef struct MQTTAckInfo
{
    uint16_t packetId;                     
    MQTTAgentCommand_t * pOriginalCommand; 
} MQTTAgentAckInfo_t;
 
typedef void (* MQTTAgentIncomingPublishCallback_t )( struct MQTTAgentContext * pMqttAgentContext,
                                                      uint16_t packetId,
                                                      MQTTPublishInfo_t * pPublishInfo );
 
typedef struct MQTTAgentContext
{
    MQTTContext_t mqttContext;                                          
    MQTTAgentMessageInterface_t agentInterface;                         
    MQTTAgentAckInfo_t pPendingAcks[ MQTT_AGENT_MAX_OUTSTANDING_ACKS ]; 
    MQTTAgentIncomingPublishCallback_t pIncomingCallback;               
    void * pIncomingCallbackContext;                                    
    bool packetReceivedInLoop;                                          
} MQTTAgentContext_t;
 
typedef struct MQTTAgentSubscribeArgs
{
    MQTTSubscribeInfo_t * pSubscribeInfo; 
    size_t numSubscriptions;              
} MQTTAgentSubscribeArgs_t;
 
typedef struct MQTTAgentConnectArgs
{
    MQTTConnectInfo_t * pConnectInfo; 
    MQTTPublishInfo_t * pWillInfo;    
    uint32_t timeoutMs;               
    bool sessionPresent;              
} MQTTAgentConnectArgs_t;
 
typedef struct MQTTAgentCommandInfo
{
    MQTTAgentCommandCallback_t cmdCompleteCallback;          
    MQTTAgentCommandContext_t * pCmdCompleteCallbackContext; 
    uint32_t blockTimeMs;                                    
} MQTTAgentCommandInfo_t;
 
/*-----------------------------------------------------------*/
 
/* @[declare_mqtt_agent_init] */
MQTTStatus_t MQTTAgent_Init( MQTTAgentContext_t * pMqttAgentContext,
                             const MQTTAgentMessageInterface_t * pMsgInterface,
                             const MQTTFixedBuffer_t * pNetworkBuffer,
                             const TransportInterface_t * pTransportInterface,
                             MQTTGetCurrentTimeFunc_t getCurrentTimeMs,
                             MQTTAgentIncomingPublishCallback_t incomingCallback,
                             void * pIncomingPacketContext );
/* @[declare_mqtt_agent_init] */
 
/* @[declare_mqtt_agent_commandloop] */
MQTTStatus_t MQTTAgent_CommandLoop( MQTTAgentContext_t * pMqttAgentContext );
/* @[declare_mqtt_agent_commandloop] */
 
/* @[declare_mqtt_agent_resumesession] */
MQTTStatus_t MQTTAgent_ResumeSession( MQTTAgentContext_t * pMqttAgentContext,
                                      bool sessionPresent );
/* @[declare_mqtt_agent_resumesession] */
 
/* @[declare_mqtt_agent_cancelall] */
MQTTStatus_t MQTTAgent_CancelAll( MQTTAgentContext_t * pMqttAgentContext );
/* @[declare_mqtt_agent_cancelall] */
 
/* @[declare_mqtt_agent_subscribe] */
MQTTStatus_t MQTTAgent_Subscribe( const MQTTAgentContext_t * pMqttAgentContext,
                                  MQTTAgentSubscribeArgs_t * pSubscriptionArgs,
                                  const MQTTAgentCommandInfo_t * pCommandInfo );
/* @[declare_mqtt_agent_subscribe] */
 
/* @[declare_mqtt_agent_unsubscribe] */
MQTTStatus_t MQTTAgent_Unsubscribe( const MQTTAgentContext_t * pMqttAgentContext,
                                    MQTTAgentSubscribeArgs_t * pSubscriptionArgs,
                                    const MQTTAgentCommandInfo_t * pCommandInfo );
/* @[declare_mqtt_agent_unsubscribe] */
 
/* @[declare_mqtt_agent_publish] */
MQTTStatus_t MQTTAgent_Publish( const MQTTAgentContext_t * pMqttAgentContext,
                                MQTTPublishInfo_t * pPublishInfo,
                                const MQTTAgentCommandInfo_t * pCommandInfo );
/* @[declare_mqtt_agent_publish] */
 
/* @[declare_mqtt_agent_processloop] */
MQTTStatus_t MQTTAgent_ProcessLoop( const MQTTAgentContext_t * pMqttAgentContext,
                                    const MQTTAgentCommandInfo_t * pCommandInfo );
/* @[declare_mqtt_agent_processloop] */
 
/* @[declare_mqtt_agent_ping] */
MQTTStatus_t MQTTAgent_Ping( const MQTTAgentContext_t * pMqttAgentContext,
                             const MQTTAgentCommandInfo_t * pCommandInfo );
/* @[declare_mqtt_agent_ping] */
 
/* @[declare_mqtt_agent_connect] */
MQTTStatus_t MQTTAgent_Connect( const MQTTAgentContext_t * pMqttAgentContext,
                                MQTTAgentConnectArgs_t * pConnectArgs,
                                const MQTTAgentCommandInfo_t * pCommandInfo );
/* @[declare_mqtt_agent_connect] */
 
/* @[declare_mqtt_agent_disconnect] */
MQTTStatus_t MQTTAgent_Disconnect( const MQTTAgentContext_t * pMqttAgentContext,
                                   const MQTTAgentCommandInfo_t * pCommandInfo );
/* @[declare_mqtt_agent_disconnect] */
 
/* @[declare_mqtt_agent_terminate] */
MQTTStatus_t MQTTAgent_Terminate( const MQTTAgentContext_t * pMqttAgentContext,
                                  const MQTTAgentCommandInfo_t * pCommandInfo );
/* @[declare_mqtt_agent_terminate] */
 
#endif /* CORE_MQTT_AGENT_H */