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]	pMqttAgentContext	The MQTT agent to use.
[in,out]	pConnectArgs	Struct 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]	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;
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().
}