coreMQTT Agent v1.1.0
Thread safe MQTT 3.1.1 Client
core_mqtt_agent.h
Go to the documentation of this file.
1/*
2 * coreMQTT Agent v1.1.0
3 * Copyright (C) 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
4 *
5 * Permission is hereby granted, free of charge, to any person obtaining a copy of
6 * this software and associated documentation files (the "Software"), to deal in
7 * the Software without restriction, including without limitation the rights to
8 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
9 * the Software, and to permit persons to whom the Software is furnished to do so,
10 * subject to the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be included in all
13 * copies or substantial portions of the Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
17 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
18 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
19 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
20 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
21 */
22
27#ifndef CORE_MQTT_AGENT_H
28#define CORE_MQTT_AGENT_H
29
30/* *INDENT-OFF* */
31#ifdef __cplusplus
32 extern "C" {
33#endif
34/* *INDENT-ON* */
35
36/* MQTT library includes. */
37#include "core_mqtt.h"
38#include "core_mqtt_state.h"
39
40/* Command messaging interface include. */
42
55#ifndef MQTT_AGENT_MAX_OUTSTANDING_ACKS
56 #define MQTT_AGENT_MAX_OUTSTANDING_ACKS ( 20U )
57#endif
58
71#ifndef MQTT_AGENT_MAX_EVENT_QUEUE_WAIT_TIME
72 #define MQTT_AGENT_MAX_EVENT_QUEUE_WAIT_TIME ( 1000U )
73#endif
74
75/*-----------------------------------------------------------*/
76
81typedef enum MQTTCommandType
82{
83 NONE = 0,
94
95struct MQTTAgentContext;
96struct MQTTAgentCommandContext;
97
102typedef struct MQTTAgentReturnInfo
103{
105 uint8_t * pSubackCodes;
107
115typedef struct MQTTAgentCommandContext MQTTAgentCommandContext_t;
116
133typedef void (* MQTTAgentCommandCallback_t )( MQTTAgentCommandContext_t * pCmdCallbackContext,
134 MQTTAgentReturnInfo_t * pReturnInfo );
135
143{
145 void * pArgs;
148};
149
154typedef struct MQTTAckInfo
155{
156 uint16_t packetId;
157 MQTTAgentCommand_t * pOriginalCommand;
159
174typedef void (* MQTTAgentIncomingPublishCallback_t )( struct MQTTAgentContext * pMqttAgentContext,
175 uint16_t packetId,
176 MQTTPublishInfo_t * pPublishInfo );
177
184typedef struct MQTTAgentContext
185{
193
198typedef struct MQTTAgentSubscribeArgs
199{
203
208typedef struct MQTTAgentConnectArgs
209{
212 uint32_t timeoutMs;
215
220typedef struct MQTTAgentCommandInfo
221{
224 uint32_t blockTimeMs;
226
227/*-----------------------------------------------------------*/
228
318/* @[declare_mqtt_agent_init] */
320 const MQTTAgentMessageInterface_t * pMsgInterface,
321 const MQTTFixedBuffer_t * pNetworkBuffer,
322 const TransportInterface_t * pTransportInterface,
323 MQTTGetCurrentTimeFunc_t getCurrentTimeMs,
324 MQTTAgentIncomingPublishCallback_t incomingCallback,
325 void * pIncomingPacketContext );
326/* @[declare_mqtt_agent_init] */
327
368/* @[declare_mqtt_agent_commandloop] */
370/* @[declare_mqtt_agent_commandloop] */
371
409/* @[declare_mqtt_agent_resumesession] */
411 bool sessionPresent );
412/* @[declare_mqtt_agent_resumesession] */
413
448/* @[declare_mqtt_agent_cancelall] */
450/* @[declare_mqtt_agent_cancelall] */
451
507/* @[declare_mqtt_agent_subscribe] */
508MQTTStatus_t MQTTAgent_Subscribe( const MQTTAgentContext_t * pMqttAgentContext,
509 MQTTAgentSubscribeArgs_t * pSubscriptionArgs,
510 const MQTTAgentCommandInfo_t * pCommandInfo );
511/* @[declare_mqtt_agent_subscribe] */
512
567/* @[declare_mqtt_agent_unsubscribe] */
568MQTTStatus_t MQTTAgent_Unsubscribe( const MQTTAgentContext_t * pMqttAgentContext,
569 MQTTAgentSubscribeArgs_t * pSubscriptionArgs,
570 const MQTTAgentCommandInfo_t * pCommandInfo );
571/* @[declare_mqtt_agent_unsubscribe] */
572
627/* @[declare_mqtt_agent_publish] */
628MQTTStatus_t MQTTAgent_Publish( const MQTTAgentContext_t * pMqttAgentContext,
629 MQTTPublishInfo_t * pPublishInfo,
630 const MQTTAgentCommandInfo_t * pCommandInfo );
631/* @[declare_mqtt_agent_publish] */
632
678/* @[declare_mqtt_agent_processloop] */
679MQTTStatus_t MQTTAgent_ProcessLoop( const MQTTAgentContext_t * pMqttAgentContext,
680 const MQTTAgentCommandInfo_t * pCommandInfo );
681/* @[declare_mqtt_agent_processloop] */
682
734/* @[declare_mqtt_agent_ping] */
735MQTTStatus_t MQTTAgent_Ping( const MQTTAgentContext_t * pMqttAgentContext,
736 const MQTTAgentCommandInfo_t * pCommandInfo );
737/* @[declare_mqtt_agent_ping] */
738
827/* @[declare_mqtt_agent_connect] */
828MQTTStatus_t MQTTAgent_Connect( const MQTTAgentContext_t * pMqttAgentContext,
829 MQTTAgentConnectArgs_t * pConnectArgs,
830 const MQTTAgentCommandInfo_t * pCommandInfo );
831/* @[declare_mqtt_agent_connect] */
832
890/* @[declare_mqtt_agent_disconnect] */
891MQTTStatus_t MQTTAgent_Disconnect( const MQTTAgentContext_t * pMqttAgentContext,
892 const MQTTAgentCommandInfo_t * pCommandInfo );
893/* @[declare_mqtt_agent_disconnect] */
894
953/* @[declare_mqtt_agent_terminate] */
954MQTTStatus_t MQTTAgent_Terminate( const MQTTAgentContext_t * pMqttAgentContext,
955 const MQTTAgentCommandInfo_t * pCommandInfo );
956/* @[declare_mqtt_agent_terminate] */
957
958/* *INDENT-OFF* */
959#ifdef __cplusplus
960 }
961#endif
962/* *INDENT-ON* */
963
964#endif /* CORE_MQTT_AGENT_H */
MQTTStatus_t MQTTAgent_CancelAll(MQTTAgentContext_t *pMqttAgentContext)
Cancel all enqueued commands and those awaiting acknowledgment while the command loop is not running.
Definition: core_mqtt_agent.c:1081
MQTTStatus_t MQTTAgent_Disconnect(const MQTTAgentContext_t *pMqttAgentContext, const MQTTAgentCommandInfo_t *pCommandInfo)
Add a command to disconnect an MQTT connection.
Definition: core_mqtt_agent.c:1253
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)
Perform any initialization the MQTT agent requires before it can be used. Must be called before any o...
Definition: core_mqtt_agent.c:946
MQTTStatus_t MQTTAgent_Subscribe(const MQTTAgentContext_t *pMqttAgentContext, MQTTAgentSubscribeArgs_t *pSubscriptionArgs, const MQTTAgentCommandInfo_t *pCommandInfo)
Add a command to call MQTT_Subscribe() for an MQTT connection.
Definition: core_mqtt_agent.c:1130
MQTTStatus_t MQTTAgent_ResumeSession(MQTTAgentContext_t *pMqttAgentContext, bool sessionPresent)
Resume a session by resending publishes if a session is present in the broker, or clear state informa...
Definition: core_mqtt_agent.c:1038
MQTTStatus_t MQTTAgent_Connect(const MQTTAgentContext_t *pMqttAgentContext, MQTTAgentConnectArgs_t *pConnectArgs, const MQTTAgentCommandInfo_t *pCommandInfo)
Add a command to call MQTT_Connect() for an MQTT connection. If a session is resumed with the broker,...
Definition: core_mqtt_agent.c:1228
MQTTStatus_t MQTTAgent_CommandLoop(MQTTAgentContext_t *pMqttAgentContext)
Process commands from the command queue in a loop.
Definition: core_mqtt_agent.c:996
MQTTStatus_t MQTTAgent_ProcessLoop(const MQTTAgentContext_t *pMqttAgentContext, const MQTTAgentCommandInfo_t *pCommandInfo)
Send a message to the MQTT agent purely to trigger an iteration of its loop, which will result in a c...
Definition: core_mqtt_agent.c:1205
MQTTStatus_t MQTTAgent_Unsubscribe(const MQTTAgentContext_t *pMqttAgentContext, MQTTAgentSubscribeArgs_t *pSubscriptionArgs, const MQTTAgentCommandInfo_t *pCommandInfo)
Add a command to call MQTT_Unsubscribe() for an MQTT connection.
Definition: core_mqtt_agent.c:1155
MQTTStatus_t MQTTAgent_Terminate(const MQTTAgentContext_t *pMqttAgentContext, const MQTTAgentCommandInfo_t *pCommandInfo)
Add a termination command to the command queue.
Definition: core_mqtt_agent.c:1299
MQTTStatus_t MQTTAgent_Ping(const MQTTAgentContext_t *pMqttAgentContext, const MQTTAgentCommandInfo_t *pCommandInfo)
Add a command to call MQTT_Ping() for an MQTT connection.
Definition: core_mqtt_agent.c:1276
#define MQTT_AGENT_MAX_OUTSTANDING_ACKS
The maximum number of pending acknowledgments to track for a single connection.
Definition: core_mqtt_agent.h:56
MQTTStatus_t MQTTAgent_Publish(const MQTTAgentContext_t *pMqttAgentContext, MQTTPublishInfo_t *pPublishInfo, const MQTTAgentCommandInfo_t *pCommandInfo)
Add a command to call MQTT_Publish() for an MQTT connection.
Definition: core_mqtt_agent.c:1180
Functions to interact with queues.
void(* MQTTAgentCommandCallback_t)(MQTTAgentCommandContext_t *pCmdCallbackContext, MQTTAgentReturnInfo_t *pReturnInfo)
Callback function called when a command completes.
Definition: core_mqtt_agent.h:133
void(* MQTTAgentIncomingPublishCallback_t)(struct MQTTAgentContext *pMqttAgentContext, uint16_t packetId, MQTTPublishInfo_t *pPublishInfo)
Callback function called when receiving a publish.
Definition: core_mqtt_agent.h:174
MQTTAgentCommandType_t
A type of command for interacting with the MQTT API.
Definition: core_mqtt_agent.h:82
@ NUM_COMMANDS
The number of command types handled by the agent.
Definition: core_mqtt_agent.h:92
@ CONNECT
Call MQTT_Connect().
Definition: core_mqtt_agent.h:89
@ DISCONNECT
Call MQTT_Disconnect().
Definition: core_mqtt_agent.h:90
@ PING
Call MQTT_Ping().
Definition: core_mqtt_agent.h:88
@ UNSUBSCRIBE
Call MQTT_Unsubscribe().
Definition: core_mqtt_agent.h:87
@ PROCESSLOOP
Call MQTT_ProcessLoop().
Definition: core_mqtt_agent.h:84
@ TERMINATE
Exit the command loop and stop processing commands.
Definition: core_mqtt_agent.h:91
@ SUBSCRIBE
Call MQTT_Subscribe().
Definition: core_mqtt_agent.h:86
@ PUBLISH
Call MQTT_Publish().
Definition: core_mqtt_agent.h:85
@ NONE
No command received. Must be zero (its memset() value).
Definition: core_mqtt_agent.h:83
struct MQTTAgentCommandContext MQTTAgentCommandContext_t
Struct containing context for a specific command.
Definition: core_mqtt_agent.h:115
uint32_t(* MQTTGetCurrentTimeFunc_t)(void)
MQTTStatus_t
Information for a pending MQTT ack packet expected by the agent.
Definition: core_mqtt_agent.h:155
MQTTAgentCommand_t * pOriginalCommand
Definition: core_mqtt_agent.h:157
uint16_t packetId
Definition: core_mqtt_agent.h:156
The commands sent from the APIs to the MQTT agent task.
Definition: core_mqtt_agent.h:143
void * pArgs
Arguments of command.
Definition: core_mqtt_agent.h:145
MQTTAgentCommandCallback_t pCommandCompleteCallback
Callback to invoke upon completion.
Definition: core_mqtt_agent.h:146
MQTTAgentCommandContext_t * pCmdContext
Context for completion callback.
Definition: core_mqtt_agent.h:147
MQTTAgentCommandType_t commandType
Type of command.
Definition: core_mqtt_agent.h:144
Struct holding arguments that are common to every command.
Definition: core_mqtt_agent.h:221
MQTTAgentCommandContext_t * pCmdCompleteCallbackContext
Context for completion callback.
Definition: core_mqtt_agent.h:223
MQTTAgentCommandCallback_t cmdCompleteCallback
Callback to invoke upon completion.
Definition: core_mqtt_agent.h:222
uint32_t blockTimeMs
Maximum block time for enqueueing the command.
Definition: core_mqtt_agent.h:224
Struct holding arguments for a CONNECT call.
Definition: core_mqtt_agent.h:209
bool sessionPresent
Output flag set if a previous session was present.
Definition: core_mqtt_agent.h:213
MQTTPublishInfo_t * pWillInfo
Optional Last Will and Testament.
Definition: core_mqtt_agent.h:211
uint32_t timeoutMs
Maximum timeout for a CONNACK packet.
Definition: core_mqtt_agent.h:212
MQTTConnectInfo_t * pConnectInfo
MQTT CONNECT packet information.
Definition: core_mqtt_agent.h:210
Information used by each MQTT agent. A context will be initialized by MQTTAgent_Init(),...
Definition: core_mqtt_agent.h:185
void * pIncomingCallbackContext
Definition: core_mqtt_agent.h:190
MQTTAgentIncomingPublishCallback_t pIncomingCallback
Definition: core_mqtt_agent.h:189
MQTTAgentMessageInterface_t agentInterface
Definition: core_mqtt_agent.h:187
MQTTContext_t mqttContext
Definition: core_mqtt_agent.h:186
bool packetReceivedInLoop
Definition: core_mqtt_agent.h:191
Function pointers and contexts used for sending and receiving commands, and allocating memory for the...
Definition: core_mqtt_agent_message_interface.h:133
Struct holding return codes and outputs from a command.
Definition: core_mqtt_agent.h:103
MQTTStatus_t returnCode
Definition: core_mqtt_agent.h:104
uint8_t * pSubackCodes
Definition: core_mqtt_agent.h:105
Struct holding arguments for a SUBSCRIBE or UNSUBSCRIBE call.
Definition: core_mqtt_agent.h:199
MQTTSubscribeInfo_t * pSubscribeInfo
List of MQTT subscriptions.
Definition: core_mqtt_agent.h:200
size_t numSubscriptions
Number of elements in pSubscribeInfo.
Definition: core_mqtt_agent.h:201