Design

Architecture of the MQTT Agent library.

Thread Safe and Unsafe APIs

The MQTT Agent APIs are designed to be used by two types of tasks:

• An MQTT agent task that manages an MQTT connection and calls coreMQTT APIs. The APIs used by this task are not thread safe, and each agent task should use a unique MQTTAgentContext_t (multiple agent tasks may be used to handle multiple simultaneous MQTT connections, but each must have a unique context). This task is expected to invoke MQTTAgent_CommandLoop to process commands from other tasks to call coreMQTT APIs. The APIs for this task are:
  • MQTTAgent_Init
  • MQTTAgent_CommandLoop
  • MQTTAgent_ResumeSession
  • MQTTAgent_CancelAll
• Application tasks that want to perform MQTT operations with thread safety. These tasks are any task that is not an MQTT agent task. The APIs used by application tasks are thread safe, and send commands that are processed by an MQTT agent task in MQTTAgent_CommandLoop. These APIs can accept several structures used by either the command or completion callback, and these structures MUST remain in scope until the associated command has been completed, including MQTTPublishInfo_t, MQTTAgentSubscribeArgs_t, MQTTAgentConnectArgs_t, and MQTTAgentCommandContext_t. The APIs are asynchronous, so will return as soon as the command has been sent; they will not wait for the command to be processed. These APIs are:
  • MQTTAgent_Publish
  • MQTTAgent_Subscribe
  • MQTTAgent_Unsubscribe
  • MQTTAgent_Ping
  • MQTTAgent_Connect
  • MQTTAgent_Disconnect
  • MQTTAgent_Terminate

Interfaces and Callbacks

Similar to coreMQTT, the MQTT Agent library relies on interfaces to dissociate itself from platform specific functionality. Interfaces used by the MQTT Agent library are simply function pointers with expectations of behavior.

The MQTT Agent library expects the application to provide implementations for the following interfaces:

Function Pointer	Use
MQTTAgentMessageRecv_t	Receiving commands sent to the agent task.
MQTTAgentMessageSend_t	Sending commands to the agent task from the application
MQTTAgentCommandGet_t	Allocating storage for a command to be sent to the agent task.
MQTTAgentCommandRelease_t	Releasing a command obtained from MQTTAgentCommandGet_t.
MQTTAgentIncomingPublishCallback_t	Accepting incoming publish messages, with the possibility of further distributing them to other tasks.

Command Completion

Commands do not have any timeout associated with them. The only way for a task to be aware of a command's completion is through the invocation of an optional MQTTAgentCommandCallback_t completion callback. The completion callback will be invoked with an optional MQTTAgentCommandContext_t, which is the incomplete type struct MQTTAgentCommandContext. This type must be defined by the application, and should contain information that would be useful in distinguishing commands.
Example code:

struct MQTTAgentCommandContext
{
    //Allow the calling thread to view the return code by copying it here.
    MQTTStatus_t returnCode;
    //pthread mutex and condition variables to signal to the thread that created the command.
    pthread_mutex_t lock;
    pthread_cond_t cond;
};

The completion callback using such a context could be:

void commandCompleteCallback( MQTTAgentCommandContext_t * pCmdContext, MQTTAgentReturnInfo_t * pReturnInfo )
{
    pthread_mutex_lock( &( pCmdContext->lock ) );
    //Set return code so the thread that created the command can view.
    pCmdContext->returnCode = pReturnInfo->returnCode;
    pthread_mutex_unlock( &( pCmdContext->lock ) );
    //Signal the thread using the condition variable.
    pthread_cond_broadcast( &( pCmdContext->cond ) );
}

The completion callback and completion context are each optional, and passed at time of command creation in the MQTTAgentCommandInfo_t parameter. If a command completion context is passed, it MUST remain in scope until the completion callback has been invoked.