MQTTAgent_Terminate

Add a termination command to the command queue.

MQTTStatus_t MQTTAgent_Terminate( const MQTTAgentContext_t * pMqttAgentContext,
                                  const MQTTAgentCommandInfo_t * pCommandInfo );

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]	pMqttAgentContext	The MQTT agent to use.
[in]	pCommandInfo	The 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.
}