MQTTAgent_Ping

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

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

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]	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 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.
}