MQTT_Init

Initialize an MQTT context.

MQTTStatus_t MQTT_Init( MQTTContext_t * pContext,
                        const TransportInterface_t * pTransportInterface,
                        MQTTGetCurrentTimeFunc_t getTimeFunction,
                        MQTTEventCallback_t userCallback,
                        const MQTTFixedBuffer_t * pNetworkBuffer );

This function must be called on an MQTTContext_t before any other function.

Note

The MQTTGetCurrentTimeFunc_t function for querying time must be defined. If there is no time implementation, it is the responsibility of the application to provide a dummy function to always return 0, provide 0 timeouts for all calls to MQTT_Connect, MQTT_ProcessLoop, and MQTT_ReceiveLoop and configure the MQTT_RECV_POLLING_TIMEOUT_MS and MQTT_SEND_RETRY_TIMEOUT_MS configurations to be 0. This will result in loop functions running for a single iteration, and MQTT_Connect relying on MQTT_MAX_CONNACK_RECEIVE_RETRY_COUNT to receive the CONNACK packet.

Parameters

[in]	pContext	The context to initialize.
[in]	pTransportInterface	The transport interface to use with the context.
[in]	getTimeFunction	The time utility function which can return the amount of time (in milliseconds) elapsed since a given epoch. This function will be used to ensure that timeouts in the API calls are met and keep-alive messages are sent on time.
[in]	userCallback	The user callback to use with the context to notify about incoming packet events.
[in]	pNetworkBuffer	Network buffer provided for the context. This buffer will be used to receive incoming messages from the broker. This buffer must remain valid and in scope for the entire lifetime of the pContext and must not be used by another context and/or application.

Returns

MQTTBadParameter if invalid parameters are passed; MQTTSuccess otherwise.

Example

// Function for obtaining a timestamp.
uint32_t getTimeStampMs();
// Callback function for receiving packets.
void eventCallback(
     MQTTContext_t * pContext,
     MQTTPacketInfo_t * pPacketInfo,
     MQTTDeserializedInfo_t * pDeserializedInfo
);
// Network send.
int32_t networkSend( NetworkContext_t * pContext, const void * pBuffer, size_t bytes );
// Network receive.
int32_t networkRecv( NetworkContext_t * pContext, void * pBuffer, size_t bytes );
 
MQTTContext_t mqttContext;
TransportInterface_t transport;
MQTTFixedBuffer_t fixedBuffer;
// Create a globally accessible buffer which remains in scope for the entire duration
// of the MQTT context.
uint8_t buffer[ 1024 ];
 
// Clear context.
memset( ( void * ) &mqttContext, 0x00, sizeof( MQTTContext_t ) );
 
// Set transport interface members.
transport.pNetworkContext = &someTransportContext;
transport.send = networkSend;
transport.recv = networkRecv;
 
// Set buffer members.
fixedBuffer.pBuffer = buffer;
fixedBuffer.size = 1024;
 
status = MQTT_Init( &mqttContext, &transport, getTimeStampMs, eventCallback, &fixedBuffer );
 
if( status == MQTTSuccess )
{
     // Do something with mqttContext. The transport and fixedBuffer structs were
     // copied into the context, so the original structs do not need to stay in scope.
     // However, the memory pointed to by the fixedBuffer.pBuffer must remain in scope.
}