Message Interface

Messaging interface used by the MQTT Agent.

.

Message Interface Overview

The message interface is a set of APIs to send MQTT Agent commands from application tasks to the MQTT agent task, as well as functions to allocate and release storage for these commands. It must be implemented with thread safety, as multiple tasks can send commands concurrently. The message interface is defined in core_mqtt_agent_message_interface.h.

The functions that must be implemented are:

• Message Send
• Message Receive
• Get Command
• Release Command

The send and receive functions take in an opaque context MQTTAgentMessageContext_t. The functions above and the context are grouped together in the MQTTAgentMessageInterface_t structure:

typedef struct MQTTAgentMessageInterface
{
    MQTTAgentMessageContext_t * pMsgCtx;      
    MQTTAgentMessageSend_t send;              
    MQTTAgentMessageRecv_t recv;              
    MQTTAgentCommandGet_t getCommand;         
    MQTTAgentCommandRelease_t releaseCommand; 
} MQTTAgentMessageInterface_t;

Implementing the Message Interface

The following steps give guidance on implementing the messaging interface:

1. Implementing MQTTAgentMessageContext_t
   
   

   typedef struct MQTTAgentMessageContext   MQTTAgentMessageContext_t;

   
   MQTTAgentMessageContext_t is the incomplete type struct MQTTAgentMessageContext. The implemented struct MQTTAgentMessageContext must contain all of the information needed to send and receive commands with MQTTAgentMessageSend_t and MQTTAgentMessageRecv_t with thread safety. For example, this may be a handle to a thread safe queue, or a queue along with synchronization primitives. Commands are sent by pointer, so this structure should be able to relay pointers of type MQTTAgentCommand_t.
   
   Example code:

   struct MQTTAgentMessageContext
   {
       //Queue holding MQTTAgentCommand_t * pointers.
       Queue_t queue;
   };

   
   
2. Implementing MQTTAgentMessageSend_t
   
   

   typedef bool ( * MQTTAgentMessageSend_t )( MQTTAgentMessageContext_t * pMsgCtx,
                                              MQTTAgentCommand_t * const * pCommandToSend,
                                              uint32_t blockTimeMs );

   
   This function is expected to send the pointer that is pointed to by pCommandToSend using the message context. It will return true if the send was successful, else false.
   
   Example code:

   bool myMessageSendImplementation( MQTTAgentMessageContext_t * pMsgCtx,
                                     MQTTAgentCommand_t * const * pCommandToSend,
                                     uint32_t blockTimeMs )
   {
       int status = EXIT_FAILURE;
       if( ( pMsgCtx != NULL ) && ( pCommandToSend != NULL ) )
       {
           //A function to send data to via pointer to a queue.
           status = Queue_SendToBack( pMsgCtx->queue, pCommandToSend, blockTimeMs );
       }
       return ( status == EXIT_SUCCESS );
   }

   
   
3. Implementing MQTTAgentMessageRecv_t
   
   

   typedef bool ( * MQTTAgentMessageRecv_t )( MQTTAgentMessageContext_t * pMsgCtx,
                                              MQTTAgentCommand_t ** pReceivedCommand,
                                              uint32_t blockTimeMs );

   
   This function is expected to receive a pointer that has been previously sent to the message context, and return in via the pReceivedCommand parameter. It will return true if the receive was successful, else false.
   
   Example code:

   bool myMessageRecvImplementation( MQTTAgentMessageContext_t * pMsgCtx,
                                     MQTTAgentCommand_t ** pReceivedCommand,
                                     uint32_t blockTimeMs )
   {
       int status = EXIT_FAILURE;
       void * pReceivedPointer;
       if( ( pMsgCtx != NULL ) && ( pReceivedCommand != NULL ) )
       {
           //A function to receive data from a queue.
           status = Queue_Recv( pMsgCtx->queue, &pReceivedPointer, blockTimeMs );
           if( status == EXIT_SUCCESS )
           {
               *pReceivedCommand = ( MQTTAgentCommand_t * ) pReceivedPointer;
           }
       }
       return ( status == EXIT_SUCCESS );
   }

   
   
4. Implementing MQTTAgentCommandGet_t
   
   

   typedef MQTTAgentCommand_t * ( * MQTTAgentCommandGet_t )( uint32_t blockTimeMs );

   
   This function is expected to allocate storage for an MQTTAgentCommand_t struct. This function must be thread safe. It will return a pointer to the allocated command, or NULL if allocation failed.
   
   Example code:

   MQTTAgentCommand_t * myGetCommandImplementation( uint32_t blockTimeMs )
   {
       MQTTAgentCommand_t * ret = ( MQTTAgentCommand_t * ) malloc( sizeof( MQTTAgentCommand_t ) );
       return ret;
   }

   
   
5. Implementing MQTTAgentCommandRelease_t
   
   

   typedef bool ( * MQTTAgentCommandRelease_t )( MQTTAgentCommand_t * pCommandToRelease );

   
   This function will release a MQTTAgentCommand_t struct that had been allocated with MQTTAgentCommandGet_t. It will return a true if the command was release, else false.
   
   Example code:

   bool myReleaseCommandImplementation( MQTTAgentCommand_t * pCommandToRelease )
   {
       free( pCommandToRelease );
       //free() does not have a return value.
       return true;
   }