coreMQTT Agent v1.2.0
Thread safe MQTT 3.1.1 Client
core_mqtt_agent.h File Reference

Functions for running a coreMQTT client in a dedicated thread. More...

Go to the source code of this file.

Data Structures

struct  MQTTAgentReturnInfo_t
 Struct holding return codes and outputs from a command. More...
 
struct  MQTTAgentCommand_t
 The commands sent from the APIs to the MQTT agent task. More...
 
struct  MQTTAgentAckInfo_t
 Information for a pending MQTT ack packet expected by the agent. More...
 
struct  MQTTAgentContext_t
 Information used by each MQTT agent. A context will be initialized by MQTTAgent_Init(), and every API function will accept a pointer to the initalized struct. More...
 
struct  MQTTAgentSubscribeArgs_t
 Struct holding arguments for a SUBSCRIBE or UNSUBSCRIBE call. More...
 
struct  MQTTAgentConnectArgs_t
 Struct holding arguments for a CONNECT call. More...
 
struct  MQTTAgentCommandInfo_t
 Struct holding arguments that are common to every command. More...
 

Typedefs

typedef struct MQTTAgentCommandContext MQTTAgentCommandContext_t
 Struct containing context for a specific command. More...
 
typedef void(* MQTTAgentCommandCallback_t) (MQTTAgentCommandContext_t *pCmdCallbackContext, MQTTAgentReturnInfo_t *pReturnInfo)
 Callback function called when a command completes. More...
 
typedef void(* MQTTAgentIncomingPublishCallback_t) (struct MQTTAgentContext *pMqttAgentContext, uint16_t packetId, MQTTPublishInfo_t *pPublishInfo)
 Callback function called when receiving a publish. More...
 

Enumerations

enum  MQTTAgentCommandType_t {
  NONE = 0 , PROCESSLOOP , PUBLISH , SUBSCRIBE ,
  UNSUBSCRIBE , PING , CONNECT , DISCONNECT ,
  TERMINATE , NUM_COMMANDS
}
 A type of command for interacting with the MQTT API. More...
 

Functions

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 other function. More...
 
MQTTStatus_t MQTTAgent_CommandLoop (MQTTAgentContext_t *pMqttAgentContext)
 Process commands from the command queue in a loop. More...
 
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 information if not. More...
 
MQTTStatus_t MQTTAgent_CancelAll (MQTTAgentContext_t *pMqttAgentContext)
 Cancel all enqueued commands and those awaiting acknowledgment while the command loop is not running. More...
 
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. More...
 
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. More...
 
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. More...
 
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 call to MQTT_ProcessLoop(). This function can be used to wake the MQTT agent task when it is known data may be available on the connected socket. More...
 
MQTTStatus_t MQTTAgent_Ping (const MQTTAgentContext_t *pMqttAgentContext, const MQTTAgentCommandInfo_t *pCommandInfo)
 Add a command to call MQTT_Ping() for an MQTT connection. More...
 
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, it will also resend the necessary QoS1/2 publishes. More...
 
MQTTStatus_t MQTTAgent_Disconnect (const MQTTAgentContext_t *pMqttAgentContext, const MQTTAgentCommandInfo_t *pCommandInfo)
 Add a command to disconnect an MQTT connection. More...
 
MQTTStatus_t MQTTAgent_Terminate (const MQTTAgentContext_t *pMqttAgentContext, const MQTTAgentCommandInfo_t *pCommandInfo)
 Add a termination command to the command queue. More...
 

Detailed Description

Functions for running a coreMQTT client in a dedicated thread.

Function Documentation

◆ MQTTAgent_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 
)

Perform any initialization the MQTT agent requires before it can be used. Must be called before any other function.

Parameters
[in]pMqttAgentContextPointer to struct to initialize.
[in]pMsgInterfaceCommand interface to use for allocating and sending commands.
[in]pNetworkBufferPointer to network buffer to use.
[in]pTransportInterfaceTransport interface to use with the MQTT library. See https://www.freertos.org/network-interface.html
[in]getCurrentTimeMsPointer to a function that returns a count value that increments every millisecond.
[in]incomingCallbackThe callback to execute when receiving publishes.
[in]pIncomingPacketContextA pointer to a context structure defined by the application writer.
Note
The pIncomingPacketContext context provided for the incoming publish callback MUST remain in scope throughout the period that the agent task is running.
Returns
Appropriate status code from MQTT_Init().

Example

// Function for obtaining a timestamp.
uint32_t getTimeStampMs();
// Callback function for receiving packets.
void incomingPublishCallback( MQTTAgentContext_t * pMqttAgentContext,
uint16_t packetId,
MQTTPublishInfo_t * pPublishInfo );
// Platform function for network send interface.
int32_t networkSend( NetworkContext_t * pContext, const void * pBuffer, size_t bytes );
// Platform for network receive interface.
int32_t networkRecv( NetworkContext_t * pContext, void * pBuffer, size_t bytes );
// Platform function for Agent Message Send.
bool agentSendMessage( MQTTAgentMessageContext_t * pMsgCtx,
MQTTAgentCommand_t * const * pCommandToSend,
uint32_t blockTimeMs );
// Platform function for Agent Message Receive.
bool agentReceiveMessage( MQTTAgentMessageContext_t * pMsgCtx,
MQTTAgentCommand_t ** pCommandToSend,
uint32_t blockTimeMs );
// Platform function to Get Agent Command.
MQTTAgentCommand_t * getCommand( uint32_t blockTimeMs );
// Platform function to Release Agent Command.
bool releaseCommand( MQTTAgentCommand_t * pCommandToRelease );
// Variables used in this example.
MQTTAgentMessageInterface_t messageInterface;
MQTTAgentContext_t agentContext;
// Buffer for storing outgoing and incoming MQTT packets.
MQTTFixedBuffer_t fixedBuffer;
uint8_t buffer[ 1024 ];
MQTTStatus_t status;
// Set transport interface members.
transport.pNetworkContext = &someTransportContext;
transport.send = networkSend;
transport.recv = networkRecv;
// Set agent message interface members.
messageInterface.pMsgCtx = &messageContext;
messageInterface.send = agentSendMessage;
messageInterface.recv = agentReceiveMessage;
messageInterface.getCommand = getCommand;
messageInterface.releaseCommand = releaseCommand;
// Set buffer members.
fixedBuffer.pBuffer = buffer;
fixedBuffer.size = 1024;
status = MQTTAgent_Init( &agentContext,
&messageInterface,
&networkBuffer,
&transportInterface,
stubGetTime,
stubPublishCallback,
incomingPacketContext );
if( status == MQTTSuccess )
{
// Do something with agentContext. The transport and message interfaces, and
// fixedBuffer structs were copied into the context, so the original structs
// do not need to stay in scope.
}
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:974
struct MQTTAgentMessageContext MQTTAgentMessageContext_t
Context with which tasks may deliver messages to the agent.
Definition: core_mqtt_agent_message_interface.h:54
MQTTStatus_t
MQTTSuccess
struct NetworkContext NetworkContext_t
Information used by each MQTT agent. A context will be initialized by MQTTAgent_Init(),...
Definition: core_mqtt_agent.h:153
Function pointers and contexts used for sending and receiving commands, and allocating memory for the...
Definition: core_mqtt_agent_message_interface.h:133
MQTTAgentMessageContext_t * pMsgCtx
Definition: core_mqtt_agent_message_interface.h:134
MQTTAgentMessageRecv_t recv
Definition: core_mqtt_agent_message_interface.h:136
MQTTAgentCommandGet_t getCommand
Definition: core_mqtt_agent_message_interface.h:137
MQTTAgentMessageSend_t send
Definition: core_mqtt_agent_message_interface.h:135
MQTTAgentCommandRelease_t releaseCommand
Definition: core_mqtt_agent_message_interface.h:138
TransportSend_t send
TransportRecv_t recv
NetworkContext_t * pNetworkContext

◆ MQTTAgent_CommandLoop()

MQTTStatus_t MQTTAgent_CommandLoop ( MQTTAgentContext_t pMqttAgentContext)

Process commands from the command queue in a loop.

Parameters
[in]pMqttAgentContextThe MQTT agent to use.
Returns
appropriate error code, or MQTTSuccess from a successful disconnect or termination.

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTAgentContext_t mqttAgentContext;
status = MQTTAgent_CommandLoop( &mqttAgentContext );
// The function returns on either receiving a terminate command,
// undergoing network disconnection OR encountering an error.
if( ( status == MQTTSuccess ) && ( mqttAgentContext.mqttContext.connectStatus == MQTTNotConnected ) )
{
// A terminate command was processed and MQTT connection was closed.
// Need to close socket connection.
Platform_DisconnectNetwork( mqttAgentContext.mqttContext.transportInterface.pNetworkContext );
}
else if( status == MQTTSuccess )
{
// Terminate command was processed but MQTT connection was not
// closed. Thus, need to close both MQTT and socket connections.
status = MQTT_Disconnect( &( mqttAgentContext.mqttContext ) );
assert( status == MQTTSuccess );
Platform_DisconnectNetwork( mqttAgentContext.mqttContext.transportInterface.pNetworkContext );
}
else
{
// Handle error.
}
MQTTStatus_t MQTT_Disconnect(MQTTContext_t *pContext)
MQTTStatus_t MQTTAgent_CommandLoop(MQTTAgentContext_t *pMqttAgentContext)
Process commands from the command queue in a loop.
Definition: core_mqtt_agent.c:1037
MQTTNotConnected
MQTTContext_t mqttContext
Definition: core_mqtt_agent.h:154
MQTTConnectionStatus_t connectStatus
TransportInterface_t transportInterface

◆ MQTTAgent_ResumeSession()

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 information if not.

Parameters
[in]pMqttAgentContextThe MQTT agent to use.
[in]sessionPresentThe session present flag from the broker.
Note
This function is NOT thread-safe and should only be called from the context of the task responsible for MQTTAgent_CommandLoop.
Returns
MQTTSuccess if it succeeds in resending publishes, else an appropriate error code from MQTT_Publish()

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTAgentContext_t mqttAgentContext;
MQTTConnectInfo_t connectInfo = { 0 };
MQTTPublishInfo_t willInfo = { 0 };
bool sessionPresent;
// The example assumes that all variables have been filled with
// data for the MQTT_Connect call
// Refer to the MQTT_Connect API for a more detailed example.
// Attempt to resume session with the broker.
status = MQTT_Connect( &( mqttAgentContext.mqttContext ), &connectInfo, &willInfo, 100, &sessionPresent )
if( status == MQTTSuccess )
{
// Process the session present status sent by the broker.
status = MQTTAgent_ResumeSession( &mqttAgentContext, sessionPresent );
}
MQTTStatus_t MQTT_Connect(MQTTContext_t *pContext, const MQTTConnectInfo_t *pConnectInfo, const MQTTPublishInfo_t *pWillInfo, uint32_t timeoutMs, bool *pSessionPresent)
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:1079

◆ MQTTAgent_CancelAll()

MQTTStatus_t MQTTAgent_CancelAll ( MQTTAgentContext_t pMqttAgentContext)

Cancel all enqueued commands and those awaiting acknowledgment while the command loop is not running.

Canceled commands will be terminated with return code MQTTRecvFailed.

Parameters
[in]pMqttAgentContextThe MQTT agent to use.
Note
This function is NOT thread-safe and should only be called from the context of the task responsible for MQTTAgent_CommandLoop.
Returns
MQTTBadParameter if an invalid context is given, else MQTTSuccess.

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTAgentContext_t mqttAgentContext;
status = MQTTAgent_CommandLoop( &mqttAgentContext );
//An error was returned, but reconnection is not desired. Cancel all commands
//that are in the queue or awaiting an acknowledgment.
if( status != MQTTSuccess )
{
//Cancel commands so any completion callbacks will be invoked.
status = MQTTAgent_CancelAll( &mqttAgentContext );
}
Platform_DisconnectNetwork( mqttAgentContext.mqttContext.transportInterface.pNetworkContext );
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:1122

◆ MQTTAgent_Subscribe()

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.

Parameters
[in]pMqttAgentContextThe MQTT agent to use.
[in]pSubscriptionArgsStruct describing topic to subscribe to.
[in]pCommandInfoThe information pertaining to the command, including:
  • cmdCompleteCallback Optional callback to invoke when the command completes.
  • pCmdCompleteCallbackContext Optional completion callback context.
  • blockTimeMs The maximum amount of time in milliseconds to wait for the command to be posted to the MQTT agent, should the agent's event queue be full. Tasks wait in the Blocked state so don't use any CPU time.
Note
The context passed to the callback through pCmdContext member of pCommandInfo parameter MUST remain in scope at least until the callback has been executed by the agent task.
Returns
MQTTSuccess if the command was posted to the MQTT agent's event queue. Otherwise an enumerated error code.

Example

// Variables used in this example.
MQTTAgentContext_t agentContext;
MQTTStatus_t status;
MQTTAgentCommandInfo_t commandInfo = { 0 };
MQTTSubscribeInfo_t subscribeInfo = { 0 };
MQTTAgentSubscribeArgs_t subscribeArgs = { 0 };
// Function for command complete callback.
void subscribeCmdCompleteCb( MQTTAgentCommandContext_t * pCmdCallbackContext,
MQTTAgentReturnInfo_t * pReturnInfo );
// Fill the command information.
commandInfo.CmdCompleteCallback = subscribeCmdCompleteCb;
commandInfo.blockTimeMs = 500;
// Fill the information for topic filters to subscribe to.
subscribeInfo.qos = Qos1;
subscribeInfo.pTopicFilter = "/foo/bar";
subscribeInfo.topicFilterLength = strlen("/foo/bar");
subscribeArgs.pSubscribeInfo = &subscribeInfo;
subscribeArgs.numSubscriptions = 1U;
status = MQTTAgent_Subscribe( &agentContext, &subscribeArgs, &commandInfo );
if( status == MQTTSuccess )
{
// Command to send subscribe request to the server has been queued. Notification
// about completion of the subscribe operation will be notified to application
// through invocation of subscribeCmdCompleteCb().
}
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:1171
struct MQTTAgentCommandContext MQTTAgentCommandContext_t
Struct containing context for a specific command.
Definition: core_mqtt_agent.h:83
Struct holding arguments that are common to every command.
Definition: core_mqtt_agent.h:189
uint32_t blockTimeMs
Maximum block time for enqueueing the command.
Definition: core_mqtt_agent.h:192
Struct holding return codes and outputs from a command.
Definition: core_mqtt_agent.h:71
Struct holding arguments for a SUBSCRIBE or UNSUBSCRIBE call.
Definition: core_mqtt_agent.h:167
MQTTSubscribeInfo_t * pSubscribeInfo
List of MQTT subscriptions.
Definition: core_mqtt_agent.h:168
size_t numSubscriptions
Number of elements in pSubscribeInfo.
Definition: core_mqtt_agent.h:169
uint16_t topicFilterLength
const char * pTopicFilter

◆ MQTTAgent_Unsubscribe()

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.

Parameters
[in]pMqttAgentContextThe MQTT agent to use.
[in]pSubscriptionArgsList of topics to unsubscribe from.
[in]pCommandInfoThe information pertaining to the command, including:
  • cmdCompleteCallback Optional callback to invoke when the command completes.
  • pCmdCompleteCallbackContext Optional completion callback context.
  • blockTimeMs The maximum amount of time in milliseconds to wait for the command to be posted to the MQTT agent, should the agent's event queue be full. Tasks wait in the Blocked state so don't use any CPU time.
Note
The context passed to the callback through pCmdContext member of pCommandInfo parameter MUST remain in scope at least until the callback has been executed by the agent task.
Returns
MQTTSuccess if the command was posted to the MQTT agent's event queue. Otherwise an enumerated error code.

Example

// Variables used in this example.
MQTTAgentContext_t agentContext;
MQTTStatus_t status;
MQTTAgentCommandInfo_t commandInfo = { 0 };
MQTTSubscribeInfo_t unsubscribeInfo = { 0 };
MQTTAgentSubscribeArgs_t unsubscribeArgs = { 0 };
// Function for command complete callback.
void unsubscribeCmdCompleteCb( MQTTAgentCommandContext_t * pCmdCallbackContext,
MQTTAgentReturnInfo_t * pReturnInfo );
// Fill the command information.
commandInfo.cmdCompleteCallback = unsubscribeCmdCompleteCb;
commandInfo.blockTimeMs = 500;
// Fill the information for topics to unsubscribe from.
unsubscribeInfo.pTopicFilter = "/foo/bar";
unsubscribeInfo.topicFilterLength = strlen("/foo/bar");
unsubscribeArgs.pSubscribeInfo = &unsubscribeInfo;
unsubscribeArgs.numSubscriptions = 1U;
status = MQTTAgent_Unsubscribe( &agentContext, &unsubscribeArgs, &commandInfo );
if( status == MQTTSuccess )
{
// Command to send Unsubscribe request to the server has been queued. Notification
// about completion of the Unsubscribe operation will be notified to application
// through invocation of unsubscribeCompleteCb().
}
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:1196
MQTTAgentCommandCallback_t cmdCompleteCallback
Callback to invoke upon completion.
Definition: core_mqtt_agent.h:190

◆ MQTTAgent_Publish()

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.

Parameters
[in]pMqttAgentContextThe MQTT agent to use.
[in]pPublishInfoMQTT PUBLISH information.
[in]pCommandInfoThe information pertaining to the command, including:
  • cmdCompleteCallback Optional callback to invoke when the command completes.
  • pCmdCompleteCallbackContext Optional completion callback context.
  • blockTimeMs The maximum amount of time in milliseconds to wait for the command to be posted to the MQTT agent, should the agent's event queue be full. Tasks wait in the Blocked state so don't use any CPU time.
Note
The context passed to the callback through pCmdContext member of pCommandInfo parameter MUST remain in scope at least until the callback has been executed by the agent task.
Returns
MQTTSuccess if the command was posted to the MQTT agent's event queue. Otherwise an enumerated error code.

Example

// Variables used in this example.
MQTTAgentContext_t agentContext;
MQTTStatus_t status;
MQTTAgentCommandInfo_t commandInfo = { 0 };
MQTTPublishInfo_t publishInfo = { 0 };
// Function for command complete callback.
void publishCmdCompleteCb( MQTTAgentCommandContext_t * pCmdCallbackContext,
MQTTAgentReturnInfo_t * pReturnInfo );
// Fill the command information.
commandInfo.cmdCompleteCallback = publishCmdCompleteCb;
commandInfo.blockTimeMs = 500;
// Fill the information for publish operation.
publishInfo.qos = MQTTQoS1;
publishInfo.pTopicName = "/some/topic/name";
publishInfo.topicNameLength = strlen( publishInfo.pTopicName );
publishInfo.pPayload = "Hello World!";
publishInfo.payloadLength = strlen( "Hello World!" );
status = MQTTAgent_Publish( &agentContext, &publishInfo, &commandInfo );
if( status == MQTTSuccess )
{
// Command to publish message to broker has been queued.
// The event of publish operation completion will be notified with
// the invocation of the publishCmdCompleteCb().
}
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:1221
MQTTQoS1
uint16_t topicNameLength
const char * pTopicName
const void * pPayload

◆ MQTTAgent_ProcessLoop()

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 call to MQTT_ProcessLoop(). This function can be used to wake the MQTT agent task when it is known data may be available on the connected socket.

Parameters
[in]pMqttAgentContextThe MQTT agent to use.
[in]pCommandInfoThe information pertaining to the command, including:
  • cmdCompleteCallback Optional callback to invoke when the command completes.
  • pCmdCompleteCallbackContext Optional completion callback context.
  • blockTimeMs The maximum amount of time in milliseconds to wait for the command to be posted to the MQTT agent, should the agent's event queue be full. Tasks wait in the Blocked state so don't use any CPU time.
Returns
MQTTSuccess if the command was posted to the MQTT agent's event queue. Otherwise an enumerated error code.

Example

// Variables used in this example.
MQTTAgentContext_t agentContext;
MQTTStatus_t status;
MQTTAgentCommandInfo_t commandInfo = { 0 };
// Function for command complete callback.
void cmdCompleteCb( MQTTAgentCommandContext_t * pCmdCallbackContext,
MQTTAgentReturnInfo_t * pReturnInfo );
// Fill the command information.
commandInfo.cmdCompleteCallback = cmdCompleteCb;
commandInfo.blockTimeMs = 500;
status = MQTTAgent_ProcessLoop( &agentContext, &commandInfo );
if( status == MQTTSuccess )
{
// Command to call MQTT_ProcessLoop() has been queued.
// After processing the command, if an incoming publish is received,
// the event will be notified with invocation of the incoming publish
// callback configured in the agent context.
}
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:1246

◆ MQTTAgent_Ping()

MQTTStatus_t MQTTAgent_Ping ( const MQTTAgentContext_t pMqttAgentContext,
const MQTTAgentCommandInfo_t pCommandInfo 
)

Add a command to call MQTT_Ping() for an MQTT connection.

Note
This API function ONLY enqueues a command to send a ping request to the server, and DOES NOT wait for a ping response to be received from the server. To detect whether a Ping Response, has not been received from the server, the MQTTAgent_CommandLoop function SHOULD be used, which returns the MQTTKeepAliveTimeout return code on a ping response (or keep-alive) timeout.
Parameters
[in]pMqttAgentContextThe MQTT agent to use.
[in]pCommandInfoThe information pertaining to the command, including:
  • cmdCompleteCallback Optional callback to invoke when the command completes.
  • pCmdCompleteCallbackContext Optional completion callback context.
  • blockTimeMs The maximum amount of time in milliseconds to wait for the command to be posted to the MQTT agent, should the agent's event queue be full. Tasks wait in the Blocked state so don't use any CPU time.
Note
The context passed to the callback through pCmdContext member of pCommandInfo parameter MUST remain in scope at least until the callback has been executed by the agent task.
Returns
MQTTSuccess if the command was posted to the MQTT agent's event queue. Otherwise an enumerated error code.

Example

// Variables used in this example.
MQTTAgentContext_t agentContext;
MQTTStatus_t status;
MQTTAgentCommandInfo_t commandInfo = { 0 };
// Function for command complete callback.
void pingRequestCompleteCb( MQTTAgentCommandContext_t * pCmdCallbackContext,
MQTTAgentReturnInfo_t * pReturnInfo );
// Fill the command information.
commandInfo.cmdCompleteCallback = pingRequestCompleteCb;
commandInfo.blockTimeMs = 500;
status = MQTTAgent_Ping( &agentContext, &commandInfo );
if( status == MQTTSuccess )
{
// Command for sending request has been queued. Application can
// handle keep-alive timeout if detected through return value of
// MQTTAgent_CommandLoop in the task running the agent.
}
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:1317

◆ MQTTAgent_Connect()

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, it will also resend the necessary QoS1/2 publishes.

Note
The MQTTAgent_Connect function is provided to give a thread safe equivalent to the MQTT_Connect API. However, it is RECOMMENDED that instead of the application tasks (i.e. tasks other than the agent task), the agent be responsible for creating the MQTT connection (by calling MQTT_Connect) before starting the command loop (with the MQTTAgent_CommandLoop() call). In that case, the agent SHOULD also be responsible for disconnecting the MQTT connection after the command loop has terminated (through an MQTTAgent_Terminate() call from an application task).
Parameters
[in]pMqttAgentContextThe MQTT agent to use.
[in,out]pConnectArgsStruct holding args for MQTT_Connect(). On a successful connection after the command is processed, the sessionPresent member will be filled to indicate whether the broker resumed an existing session.
[in]pCommandInfoThe information pertaining to the command, including:
  • cmdCompleteCallback Optional callback to invoke when the command completes.
  • pCmdCompleteCallbackContext Optional completion callback context.
  • blockTimeMs The maximum amount of time in milliseconds to wait for the command to be posted to the MQTT agent, should the agent's event queue be full. Tasks wait in the Blocked state so don't use any CPU time.
Note
The context passed to the callback through pCmdContext member of pCommandInfo parameter MUST remain in scope at least until the callback has been executed by the agent task.
Returns
MQTTSuccess if the command was posted to the MQTT agent's event queue. Otherwise an enumerated error code.

Example

// Variables used in this example.
MQTTAgentContext_t agentContext;
MQTTStatus_t status;
MQTTConnectInfo_t connectInfo = { 0 };
MQTTPublishInfo_t willInfo = { 0 };
MQTTAgentConnectArgs_t connectionArgs;
MQTTAgentCommandInfo_t commandInfo = { 0 };
// True for creating a new session with broker, false if we want to resume an old one.
connectInfo.cleanSession = true;
// Client ID must be unique to broker. This field is required.
connectInfo.pClientIdentifier = "someClientID";
connectInfo.clientIdentifierLength = strlen( connectInfo.pClientIdentifier );
// Value for keep alive.
connectInfo.keepAliveSeconds = 60;
// The following fields are optional.
// Optional username and password.
connectInfo.pUserName = "someUserName";
connectInfo.userNameLength = strlen( connectInfo.pUserName );
connectInfo.pPassword = "somePassword";
connectInfo.passwordLength = strlen( connectInfo.pPassword );
// The last will and testament is optional, it will be published by the broker
// should this client disconnect without sending a DISCONNECT packet.
willInfo.qos = MQTTQoS0;
willInfo.pTopicName = "/lwt/topic/name";
willInfo.topicNameLength = strlen( willInfo.pTopicName );
willInfo.pPayload = "LWT Message";
willInfo.payloadLength = strlen( "LWT Message" );
// Fill the MQTTAgentConnectArgs_t structure.
connectArgs.pConnectInfo = &connectInfo;
connectArgs.pWillInfo = &willInfo;
// Time to block for CONNACK response when command is processed.
connectArgs.timeoutMs = 500;
// Function for command complete callback.
void connectCmdCallback( MQTTAgentCommandContext_t * pCmdCallbackContext,
MQTTAgentReturnInfo_t * pReturnInfo );
// Fill the command information.
commandInfo.cmdCompleteCallback = connectCmdCallback;
commandInfo.blockTimeMs = 500;
status = MQTTAgent_Connect( &agentContext, &connectArgs, &commandInfo );
if( status == MQTTSuccess )
{
// Command for creating the MQTT connection has been queued.
// The MQTT connection event will be notified through the
// invocation of connectCmdCallback().
}
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:1269
MQTTQoS0
Struct holding arguments for a CONNECT call.
Definition: core_mqtt_agent.h:177
const char * pClientIdentifier
const char * pUserName
uint16_t userNameLength
uint16_t keepAliveSeconds
uint16_t clientIdentifierLength
uint16_t passwordLength
const char * pPassword

◆ MQTTAgent_Disconnect()

MQTTStatus_t MQTTAgent_Disconnect ( const MQTTAgentContext_t pMqttAgentContext,
const MQTTAgentCommandInfo_t pCommandInfo 
)

Add a command to disconnect an MQTT connection.

Note
MQTTAgent_CommandLoop will return after processing a DISCONNECT command to allow the network connection to be disconnected. However, any pending commands in the queue, as well as those waiting for an acknowledgment, will NOT be terminated.
The MQTTAgent_Disconnect function is provided to give a thread safe equivalent to the MQTT_Disconnect API. However, if the agent task is responsible for creating the MQTT connection (before calling MQTTAgent_CommandLoop()), then it is RECOMMENDED that an application task (i.e. a task other than the agent task) use MQTTAgent_Terminate to terminate the command loop in the agent, and the agent task be responsible for disconnecting the MQTT connection.
Parameters
[in]pMqttAgentContextThe MQTT agent to use.
[in]pCommandInfoThe information pertaining to the command, including:
  • cmdCompleteCallback Optional callback to invoke when the command completes.
  • pCmdCompleteCallbackContext Optional completion callback context.
  • blockTimeMs The maximum amount of time in milliseconds to wait for the command to be posted to the MQTT agent, should the agent's event queue be full. Tasks wait in the Blocked state so don't use any CPU time.
Note
The context passed to the callback through pCmdContext member of pCommandInfo parameter MUST remain in scope at least until the callback has been executed by the agent task.
Returns
MQTTSuccess if the command was posted to the MQTT agent's event queue. Otherwise an enumerated error code.

Example

// Variables used in this example.
MQTTAgentContext_t agentContext;
MQTTStatus_t status;
MQTTAgentCommandInfo_t commandInfo = { 0 };
// Function for command complete callback.
void disconnectCmdCallback( MQTTAgentCommandContext_t * pCmdCallbackContext,
MQTTAgentReturnInfo_t * pReturnInfo );
// Fill the command information.
commandInfo.cmdCompleteCallback = disconnectCmdCallback;
commandInfo.blockTimeMs = 500;
status = MQTTAgent_Disconnect( &agentContext, &commandInfo );
if( status == MQTTSuccess )
{
// Command for closing the MQTT connection has been queued.
// The MQTT disconnection event will be notified through the
// invocation of disconnectCmdCallback().
}
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:1294

◆ MQTTAgent_Terminate()

MQTTStatus_t MQTTAgent_Terminate ( const MQTTAgentContext_t pMqttAgentContext,
const MQTTAgentCommandInfo_t pCommandInfo 
)

Add a termination command to the command queue.

On command loop termination, all pending commands in the queue, as well as those waiting for an acknowledgment, will be terminated with error code MQTTRecvFailed.

Note
Commands may still be posted to the command queue after MQTTAgent_CommandLoop has returned. It is the responsibility of the application to cancel any commands that are posted while the command loop is not running, such as by invoking MQTTAgent_CancelAll.
We RECOMMEND that this function is used from application task(s), that is a task not running the agent, to terminate the agent loop instead of calling MQTTAgent_Disconnect, so that the logic for creating and closing MQTT connection is owned by the agent task.
Parameters
[in]pMqttAgentContextThe MQTT agent to use.
[in]pCommandInfoThe information pertaining to the command, including:
  • cmdCompleteCallback Optional callback to invoke when the command completes.
  • pCmdCompleteCallbackContext Optional completion callback context.
  • blockTimeMs The maximum amount of time in milliseconds to wait for the command to be posted to the MQTT agent, should the agent's event queue be full. Tasks wait in the Blocked state so don't use any CPU time.
Note
The context passed to the callback through pCmdContext member of pCommandInfo parameter MUST remain in scope at least until the callback has been executed by the agent task.
Returns
MQTTSuccess if the command was posted to the MQTT agent's event queue. Otherwise an enumerated error code.

Example

// Variables used in this example.
MQTTAgentContext_t agentContext;
MQTTStatus_t status;
MQTTAgentCommandInfo_t commandInfo = { 0 };
// Function for command complete callback.
void terminateCallback( MQTTAgentCommandContext_t * pCmdCallbackContext,
MQTTAgentReturnInfo_t * pReturnInfo );
// Fill the command information.
commandInfo.cmdCompleteCallback = terminateCallback;
commandInfo.blockTimeMs = 500;
status = MQTTAgent_Terminate( &agentContext, &commandInfo );
if( status == MQTTSuccess )
{
// Command to terminate the agent loop has been queued.
}
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:1340