coreMQTT  v1.0.0
MQTT 3.1.1 Client Library
core_mqtt.h File Reference

User-facing functions of the MQTT 3.1.1 library. More...

#include "core_mqtt_config.h"
#include "core_mqtt_config_defaults.h"
#include "core_mqtt_serializer.h"
#include "transport_interface.h"

Go to the source code of this file.

Data Structures

struct  MQTTPubAckInfo_t
 An element of the state engine records for QoS 1 or Qos 2 publishes. More...
 
struct  MQTTContext_t
 A struct representing an MQTT connection. More...
 
struct  MQTTDeserializedInfo_t
 Struct to hold deserialized packet information for an MQTTEventCallback_t callback. More...
 

Macros

#define MQTT_PACKET_ID_INVALID   ( ( uint16_t ) 0U )
 Invalid packet identifier. More...
 

Typedefs

typedef uint32_t(* MQTTGetCurrentTimeFunc_t) (void)
 Application provided callback to retrieve the current time in milliseconds. More...
 
typedef void(* MQTTEventCallback_t) (struct MQTTContext *pContext, struct MQTTPacketInfo *pPacketInfo, struct MQTTDeserializedInfo *pDeserializedInfo)
 Application callback for receiving incoming publishes and incoming acks. More...
 

Enumerations

enum  MQTTConnectionStatus_t { MQTTNotConnected, MQTTConnected }
 Values indicating if an MQTT connection exists. More...
 
enum  MQTTPublishState_t {
  MQTTStateNull = 0, MQTTPublishSend, MQTTPubAckSend, MQTTPubRecSend,
  MQTTPubRelSend, MQTTPubCompSend, MQTTPubAckPending, MQTTPubRecPending,
  MQTTPubRelPending, MQTTPubCompPending, MQTTPublishDone
}
 The state of QoS 1 or QoS 2 MQTT publishes, used in the state engine. More...
 
enum  MQTTPubAckType_t { MQTTPuback, MQTTPubrec, MQTTPubrel, MQTTPubcomp }
 Packet types used in acknowledging QoS 1 or QoS 2 publishes. More...
 
enum  MQTTSubAckStatus_t { MQTTSubAckSuccessQos0 = 0x00, MQTTSubAckSuccessQos1 = 0x01, MQTTSubAckSuccessQos2 = 0x02, MQTTSubAckFailure = 0x80 }
 The status codes in the SUBACK response to a subscription request. More...
 

Functions

MQTTStatus_t MQTT_Init (MQTTContext_t *pContext, const TransportInterface_t *pTransportInterface, MQTTGetCurrentTimeFunc_t getTimeFunction, MQTTEventCallback_t userCallback, const MQTTFixedBuffer_t *pNetworkBuffer)
 Initialize an MQTT context. More...
 
MQTTStatus_t MQTT_Connect (MQTTContext_t *pContext, const MQTTConnectInfo_t *pConnectInfo, const MQTTPublishInfo_t *pWillInfo, uint32_t timeoutMs, bool *pSessionPresent)
 Establish an MQTT session. More...
 
MQTTStatus_t MQTT_Subscribe (MQTTContext_t *pContext, const MQTTSubscribeInfo_t *pSubscriptionList, size_t subscriptionCount, uint16_t packetId)
 Sends MQTT SUBSCRIBE for the given list of topic filters to the broker. More...
 
MQTTStatus_t MQTT_Publish (MQTTContext_t *pContext, const MQTTPublishInfo_t *pPublishInfo, uint16_t packetId)
 Publishes a message to the given topic name. More...
 
MQTTStatus_t MQTT_Ping (MQTTContext_t *pContext)
 Sends an MQTT PINGREQ to broker. More...
 
MQTTStatus_t MQTT_Unsubscribe (MQTTContext_t *pContext, const MQTTSubscribeInfo_t *pSubscriptionList, size_t subscriptionCount, uint16_t packetId)
 Sends MQTT UNSUBSCRIBE for the given list of topic filters to the broker. More...
 
MQTTStatus_t MQTT_Disconnect (MQTTContext_t *pContext)
 Disconnect an MQTT session. More...
 
MQTTStatus_t MQTT_ProcessLoop (MQTTContext_t *pContext, uint32_t timeoutMs)
 Loop to receive packets from the transport interface. Handles keep alive. More...
 
MQTTStatus_t MQTT_ReceiveLoop (MQTTContext_t *pContext, uint32_t timeoutMs)
 Loop to receive packets from the transport interface. Does not handle keep alive. More...
 
uint16_t MQTT_GetPacketId (MQTTContext_t *pContext)
 Get a packet ID that is valid according to the MQTT 3.1.1 spec. More...
 
MQTTStatus_t MQTT_MatchTopic (const char *pTopicName, const uint16_t topicNameLength, const char *pTopicFilter, const uint16_t topicFilterLength, bool *pIsMatch)
 A utility function that determines whether the passed topic filter and topic name match according to the MQTT 3.1.1 protocol specification. More...
 
MQTTStatus_t MQTT_GetSubAckStatusCodes (const MQTTPacketInfo_t *pSubackPacket, uint8_t **pPayloadStart, size_t *pPayloadSize)
 Parses the payload of an MQTT SUBACK packet that contains status codes corresponding to topic filter subscription requests from the original subscribe packet. More...
 
const char * MQTT_Status_strerror (MQTTStatus_t status)
 Error code to string conversion for MQTT statuses. More...
 

Detailed Description

User-facing functions of the MQTT 3.1.1 library.

Function Documentation

◆ MQTT_Init()

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

Initialize an MQTT context.

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

Note
The MQTTGetCurrentTimeFunc_t callback function 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, and provide 0 timeouts for functions. This will ensure all time based functions will run for a single iteration.
Parameters
[in]pContextThe context to initialize.
[in]pTransportInterfaceThe transport interface to use with the context.
[in]getTimeFunctionThe time utility function to use with the context.
[in]userCallbackThe user callback to use with the context to notify about incoming packet events.
[in]pNetworkBufferNetwork buffer provided for the context.
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;
MQTTFixedBuffer_t fixedBuffer;
uint8_t buffer[ 1024 ];
// Clear context.
memset( ( void * ) &mqttContext, 0x00, sizeof( MQTTContext_t ) );
// Set transport interface members.
transport.pNetworkInterface = &someNetworkInterface;
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.
}

◆ MQTT_Connect()

MQTTStatus_t MQTT_Connect ( MQTTContext_t pContext,
const MQTTConnectInfo_t pConnectInfo,
const MQTTPublishInfo_t pWillInfo,
uint32_t  timeoutMs,
bool *  pSessionPresent 
)

Establish an MQTT session.

This function will send MQTT CONNECT packet and receive a CONNACK packet. The send and receive from the network is done through the transport interface.

The maximum time this function waits for a CONNACK is decided in one of the following ways:

  1. If timeoutMs is greater than 0: MQTTContext_t.getTime is used to ensure that the function does not wait more than timeoutMs for CONNACK.
  2. If timeoutMs is 0: The network receive for CONNACK is retried up to the number of times configured by MQTT_MAX_CONNACK_RECEIVE_RETRY_COUNT.
Parameters
[in]pContextInitialized MQTT context.
[in]pConnectInfoMQTT CONNECT packet information.
[in]pWillInfoLast Will and Testament. Pass NULL if Last Will and Testament is not used.
[in]timeoutMsMaximum time in milliseconds to wait for a CONNACK packet. A zero timeout makes use of the retries for receiving CONNACK as configured with MQTT_MAX_CONNACK_RECEIVE_RETRY_COUNT.
[out]pSessionPresentWhether a previous session was present. Only relevant if not establishing a clean session.
Returns
MQTTNoMemory if the MQTTContext_t.networkBuffer is too small to hold the MQTT packet; MQTTBadParameter if invalid parameters are passed; MQTTSendFailed if transport send failed; MQTTRecvFailed if transport receive failed for CONNACK; MQTTNoDataAvailable if no data available to receive in transport until the timeoutMs for CONNACK; MQTTSuccess otherwise.
Note
This API may spend more time than provided in the timeoutMS parameters in certain conditions as listed below:
  1. Timeouts are incorrectly configured - If the timeoutMS is less than the transport receive timeout and if a CONNACK packet is not received within the transport receive timeout, the API will spend the transport receive timeout (which is more time than the timeoutMs). It is the case of incorrect timeout configuration as the timeoutMs parameter passed to this API must be greater than the transport receive timeout. Please refer to the transport interface documentation for more details about timeout configurations.
  2. Partial CONNACK packet is received right before the expiry of the timeout - It is possible that first two bytes of CONNACK packet (packet type and remaining length) are received right before the expiry of the timeoutMS. In that case, the API makes one more network receive call in an attempt to receive the remaining 2 bytes. In the worst case, it can happen that the remaining 2 bytes are never received and this API will end up spending timeoutMs + transport receive timeout.

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTConnectInfo_t connectInfo = { 0 };
MQTTPublishInfo_t willInfo = { 0 };
bool sessionPresent;
// This is assumed to have been initialized before calling this function.
MQTTContext_t * pContext;
// 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 );
// The following fields are optional.
// Value for keep alive.
connectInfo.keepAliveSeconds = 60;
// 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" );
// Send the connect packet. Use 100 ms as the timeout to wait for the CONNACK packet.
status = MQTT_Connect( pContext, &connectInfo, &willInfo, 100, &sessionPresent );
if( status == MQTTSuccess )
{
// Since we requested a clean session, this must be false
assert( sessionPresent == false );
// Do something with the connection.
}

◆ MQTT_Subscribe()

MQTTStatus_t MQTT_Subscribe ( MQTTContext_t pContext,
const MQTTSubscribeInfo_t pSubscriptionList,
size_t  subscriptionCount,
uint16_t  packetId 
)

Sends MQTT SUBSCRIBE for the given list of topic filters to the broker.

Parameters
[in]pContextInitialized MQTT context.
[in]pSubscriptionListList of MQTT subscription info.
[in]subscriptionCountThe number of elements in pSubscriptionList.
[in]packetIdPacket ID generated by MQTT_GetPacketId.
Returns
MQTTNoMemory if the MQTTContext_t.networkBuffer is too small to hold the MQTT packet; MQTTBadParameter if invalid parameters are passed; MQTTSendFailed if transport write failed; MQTTSuccess otherwise.

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTSubscribeInfo_t subscriptionList[ NUMBER_OF_SUBSCRIPTIONS ] = { 0 };
uint16_t packetId;
// This context is assumed to be initialized and connected.
MQTTContext_t * pContext;
// This is assumed to be a list of filters we want to subscribe to.
const char * filters[ NUMBER_OF_SUBSCRIPTIONS ];
// Set each subscription.
for( int i = 0; i < NUMBER_OF_SUBSCRIPTIONS; i++ )
{
subscriptionList[ i ].qos = MQTTQoS0;
// Each subscription needs a topic filter.
subscriptionList[ i ].pTopicFilter = filters[ i ];
subscriptionList[ i ].topicFilterLength = strlen( filters[ i ] );
}
// Obtain a new packet id for the subscription.
packetId = MQTT_GetPacketId( pContext );
status = MQTT_Subscribe( pContext, &subscriptionList[ 0 ], NUMBER_OF_SUBSCRIPTIONS, packetId );
if( status == MQTTSuccess )
{
// We must now call MQTT_ReceiveLoop() or MQTT_ProcessLoop() to receive the SUBACK.
// If the broker accepts the subscription we can now receive publishes
// on the requested topics.
}

◆ MQTT_Publish()

MQTTStatus_t MQTT_Publish ( MQTTContext_t pContext,
const MQTTPublishInfo_t pPublishInfo,
uint16_t  packetId 
)

Publishes a message to the given topic name.

Parameters
[in]pContextInitialized MQTT context.
[in]pPublishInfoMQTT PUBLISH packet parameters.
[in]packetIdpacket ID generated by MQTT_GetPacketId.
Returns
MQTTNoMemory if pBuffer is too small to hold the MQTT packet; MQTTBadParameter if invalid parameters are passed; MQTTSendFailed if transport write failed; MQTTSuccess otherwise.

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTPublishInfo_t publishInfo;
uint16_t packetId;
// This context is assumed to be initialized and connected.
MQTTContext_t * pContext;
// QoS of publish.
publishInfo.qos = MQTTQoS1;
publishInfo.pTopicName = "/some/topic/name";
publishInfo.topicNameLength = strlen( publishInfo.pTopicName );
publishInfo.pPayload = "Hello World!";
publishInfo.payloadLength = strlen( "Hello World!" );
// Packet ID is needed for QoS > 0.
packetId = MQTT_GetPacketId( pContext );
status = MQTT_Publish( pContext, &publishInfo, packetId );
if( status == MQTTSuccess )
{
// Since the QoS is > 0, we will need to call MQTT_ReceiveLoop()
// or MQTT_ProcessLoop() to process the publish acknowledgments.
}

◆ MQTT_Ping()

MQTTStatus_t MQTT_Ping ( MQTTContext_t pContext)

Sends an MQTT PINGREQ to broker.

Parameters
[in]pContextInitialized and connected MQTT context.
Returns
MQTTNoMemory if pBuffer is too small to hold the MQTT packet; MQTTBadParameter if invalid parameters are passed; MQTTSendFailed if transport write failed; MQTTSuccess otherwise.

◆ MQTT_Unsubscribe()

MQTTStatus_t MQTT_Unsubscribe ( MQTTContext_t pContext,
const MQTTSubscribeInfo_t pSubscriptionList,
size_t  subscriptionCount,
uint16_t  packetId 
)

Sends MQTT UNSUBSCRIBE for the given list of topic filters to the broker.

Parameters
[in]pContextInitialized MQTT context.
[in]pSubscriptionListList of MQTT subscription info.
[in]subscriptionCountThe number of elements in pSubscriptionList.
[in]packetIdpacket ID generated by MQTT_GetPacketId.
Returns
MQTTNoMemory if the MQTTContext_t.networkBuffer is too small to hold the MQTT packet; MQTTBadParameter if invalid parameters are passed; MQTTSendFailed if transport write failed; MQTTSuccess otherwise.

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTSubscribeInfo_t unsubscribeList[ NUMBER_OF_SUBSCRIPTIONS ] = { 0 };
uint16_t packetId;
// This context is assumed to be initialized and connected.
MQTTContext_t * pContext;
// This is assumed to be a list of filters we want to unsubscribe from.
const char * filters[ NUMBER_OF_SUBSCRIPTIONS ];
// Set information for each unsubscribe request.
for( int i = 0; i < NUMBER_OF_SUBSCRIPTIONS; i++ )
{
unsubscribeList[ i ].pTopicFilter = filters[ i ];
unsubscribeList[ i ].topicFilterLength = strlen( filters[ i ] );
// The QoS field of MQTT_SubscribeInfo_t is unused for unsubscribing.
}
// Obtain a new packet id for the unsubscribe request.
packetId = MQTT_GetPacketId( pContext );
status = MQTT_Subscribe( pContext, &unsubscribeList[ 0 ], NUMBER_OF_SUBSCRIPTIONS, packetId );
if( status == MQTTSuccess )
{
// We must now call MQTT_ReceiveLoop() or MQTT_ProcessLoop() to receive the UNSUBACK.
// After this the broker should no longer send publishes for these topics.
}

◆ MQTT_Disconnect()

MQTTStatus_t MQTT_Disconnect ( MQTTContext_t pContext)

Disconnect an MQTT session.

Parameters
[in]pContextInitialized and connected MQTT context.
Returns
MQTTNoMemory if the MQTTContext_t.networkBuffer is too small to hold the MQTT packet; MQTTBadParameter if invalid parameters are passed; MQTTSendFailed if transport send failed; MQTTSuccess otherwise.

◆ MQTT_ProcessLoop()

MQTTStatus_t MQTT_ProcessLoop ( MQTTContext_t pContext,
uint32_t  timeoutMs 
)

Loop to receive packets from the transport interface. Handles keep alive.

Parameters
[in]pContextInitialized and connected MQTT context.
[in]timeoutMsMinimum time in milliseconds that the receive loop will run, unless an error occurs.
Returns
MQTTBadParameter if context is NULL; MQTTRecvFailed if a network error occurs during reception; MQTTSendFailed if a network error occurs while sending an ACK or PINGREQ; MQTTBadResponse if an invalid packet is received; MQTTKeepAliveTimeout if the server has not sent a PINGRESP before MQTT_PINGRESP_TIMEOUT_MS milliseconds; MQTTIllegalState if an incoming QoS 1/2 publish or ack causes an invalid transition for the internal state machine; MQTTSuccess on success.

Example

// Variables used in this example.
MQTTStatus_t status;
uint32_t timeoutMs = 100;
// This context is assumed to be initialized and connected.
MQTTContext_t * pContext;
while( true )
{
status = MQTT_ProcessLoop( pContext, timeoutMs );
if( status != MQTTSuccess )
{
// Determine the error. It's possible we might need to disconnect
// the underlying transport connection.
}
else
{
// Other application functions.
}
}

◆ MQTT_ReceiveLoop()

MQTTStatus_t MQTT_ReceiveLoop ( MQTTContext_t pContext,
uint32_t  timeoutMs 
)

Loop to receive packets from the transport interface. Does not handle keep alive.

Note
Passing a timeout value of 0 will run the loop for a single iteration.
Parameters
[in]pContextInitialized and connected MQTT context.
[in]timeoutMsMinimum time in milliseconds that the receive loop will run, unless an error occurs.
Returns
MQTTBadParameter if context is NULL; MQTTRecvFailed if a network error occurs during reception; MQTTSendFailed if a network error occurs while sending an ACK or PINGREQ; MQTTBadResponse if an invalid packet is received; MQTTIllegalState if an incoming QoS 1/2 publish or ack causes an invalid transition for the internal state machine; MQTTSuccess on success.

Example

// Variables used in this example.
MQTTStatus_t status;
uint32_t timeoutMs = 100;
uint32_t keepAliveMs = 60 * 1000;
// This context is assumed to be initialized and connected.
MQTTContext_t * pContext;
while( true )
{
status = MQTT_ReceiveLoop( pContext, timeoutMs );
if( status != MQTTSuccess )
{
// Determine the error. It's possible we might need to disconnect
// the underlying transport connection.
}
else
{
// Since this function does not send pings, the application may need
// to in order to comply with keep alive.
if( ( pContext->getTime() - pContext->lastPacketTime ) > keepAliveMs )
{
status = MQTT_Ping( pContext );
}
// Other application functions.
}
}

◆ MQTT_GetPacketId()

uint16_t MQTT_GetPacketId ( MQTTContext_t pContext)

Get a packet ID that is valid according to the MQTT 3.1.1 spec.

Parameters
[in]pContextInitialized MQTT context.
Returns
A non-zero number.

◆ MQTT_MatchTopic()

MQTTStatus_t MQTT_MatchTopic ( const char *  pTopicName,
const uint16_t  topicNameLength,
const char *  pTopicFilter,
const uint16_t  topicFilterLength,
bool *  pIsMatch 
)

A utility function that determines whether the passed topic filter and topic name match according to the MQTT 3.1.1 protocol specification.

Parameters
[in]pTopicNameThe topic name to check.
[in]topicNameLengthLength of the topic name.
[in]pTopicFilterThe topic filter to check.
[in]topicFilterLengthLength of topic filter.
[out]pIsMatchThis is filled with the whether there exists a match or not.
Note
The API assumes that the passed topic name is valid to meet the requirements of the MQTT 3.1.1 specification. Invalid topic names (for example, containing wildcard characters) should not be passed to the function. Also, the API checks validity of topic filter for wildcard characters ONLY if the passed topic name and topic filter do not have an exact string match.
Returns
Returns one of the following:

Example

// Variables used in this example.
const char * pTopic = "topic/match/1";
const char * pFilter = "topic/#";
bool match = false;
status = MQTT_MatchTopic( pTopic, strlen( pTopic ), pFilter, strlen( pFilter ), &match );
// Our parameters were valid, so this will return success.
assert( status == MQTTSuccess );
// For this specific example, we already know this value is true. This
// check is placed here as an example for use with variable topic names.
if( match )
{
// Application can decide what to do with the matching topic name.
}

◆ MQTT_GetSubAckStatusCodes()

MQTTStatus_t MQTT_GetSubAckStatusCodes ( const MQTTPacketInfo_t pSubackPacket,
uint8_t **  pPayloadStart,
size_t *  pPayloadSize 
)

Parses the payload of an MQTT SUBACK packet that contains status codes corresponding to topic filter subscription requests from the original subscribe packet.

Each return code in the SUBACK packet corresponds to a topic filter in the SUBSCRIBE Packet being acknowledged. The status codes can be one of the following:

  • 0x00 - Success - Maximum QoS 0
  • 0x01 - Success - Maximum QoS 1
  • 0x02 - Success - Maximum QoS 2
  • 0x80 - Failure Refer to MQTTSubAckStatus_t for the status codes.
Parameters
[in]pSubackPacketThe SUBACK packet whose payload is to be parsed.
[out]pPayloadStartThis is populated with the starting address of the payload (or return codes for topic filters) in the SUBACK packet.
[out]pPayloadSizeThis is populated with the size of the payload in the SUBACK packet. It represents the number of topic filters whose SUBACK status is present in the packet.
Returns
Returns one of the following:

Example

// Global variable used in this example.
// This is assumed to be the subscription list in the original SUBSCRIBE packet.
MQTTSubscribeInfo_t pSubscribes[ NUMBER_OF_SUBSCRIPTIONS ];
// MQTT_GetSubAckStatusCodes is intended to be used from the application
// callback that is called by the library in MQTT_ProcessLoop or MQTT_ReceiveLoop.
void eventCallback(
MQTTContext_t * pContext,
MQTTPacketInfo_t * pPacketInfo,
MQTTDeserializedInfo_t * pDeserializedInfo
)
{
uint8_t * pCodes;
size_t numCodes;
if( pPacketInfo->type == MQTT_PACKET_TYPE_SUBACK )
{
status = MQTT_GetSubAckStatusCodes( pPacketInfo, &pCodes, &numCodes );
// Since the pointers to the payload and payload size are not NULL, and
// we use the packet info struct passed to the app callback (verified
// to be valid by the library), this function must return success.
assert( status == MQTTSuccess );
// The server must send a response code for each topic filter in the
// original SUBSCRIBE packet.
assert( numCodes == NUMBER_OF_SUBSCRIPTIONS );
for( int i = 0; i < numCodes; i++ )
{
// The only failure code is 0x80 = MQTTSubAckFailure.
if( pCodes[ i ] == MQTTSubAckFailure )
{
// The subscription failed, we may want to retry the
// subscription in pSubscribes[ i ] outside of this callback.
}
else
{
// The subscription was granted, but the maximum QoS may be
// lower than what was requested. We can verify the granted QoS.
if( pSubscribes[ i ].qos != pCodes[ i ] )
{
"Requested QoS %u, but granted QoS %u for %s",
pSubscribes[ i ].qos, pCodes[ i ], pSubscribes[ i ].pTopicFilter
) );
}
}
}
}
// Handle other packet types.
}

◆ MQTT_Status_strerror()

const char* MQTT_Status_strerror ( MQTTStatus_t  status)

Error code to string conversion for MQTT statuses.

Parameters
[in]statusThe status to convert to a string.
Returns
The string representation of the status.
MQTTSubscribeInfo_t
MQTT SUBSCRIBE packet parameters.
Definition: core_mqtt_serializer.h:195
MQTTPublishInfo_t::topicNameLength
uint16_t topicNameLength
Length of topic name.
Definition: core_mqtt_serializer.h:241
MQTTConnectInfo_t
MQTT CONNECT packet parameters.
Definition: core_mqtt_serializer.h:148
MQTT_Subscribe
MQTTStatus_t MQTT_Subscribe(MQTTContext_t *pContext, const MQTTSubscribeInfo_t *pSubscriptionList, size_t subscriptionCount, uint16_t packetId)
Sends MQTT SUBSCRIBE for the given list of topic filters to the broker.
Definition: core_mqtt.c:1810
MQTTFixedBuffer_t::pBuffer
uint8_t * pBuffer
Pointer to buffer.
Definition: core_mqtt_serializer.h:139
MQTT_ProcessLoop
MQTTStatus_t MQTT_ProcessLoop(MQTTContext_t *pContext, uint32_t timeoutMs)
Loop to receive packets from the transport interface. Handles keep alive.
Definition: core_mqtt.c:2121
MQTT_GetSubAckStatusCodes
MQTTStatus_t MQTT_GetSubAckStatusCodes(const MQTTPacketInfo_t *pSubackPacket, uint8_t **pPayloadStart, size_t *pPayloadSize)
Parses the payload of an MQTT SUBACK packet that contains status codes corresponding to topic filter ...
Definition: core_mqtt.c:2327
MQTTPacketInfo_t
MQTT incoming packet parameters.
Definition: core_mqtt_serializer.h:259
MQTT_Connect
MQTTStatus_t MQTT_Connect(MQTTContext_t *pContext, const MQTTConnectInfo_t *pConnectInfo, const MQTTPublishInfo_t *pWillInfo, uint32_t timeoutMs, bool *pSessionPresent)
Establish an MQTT session.
Definition: core_mqtt.c:1713
MQTTSubscribeInfo_t::pTopicFilter
const char * pTopicFilter
Topic filter to subscribe to.
Definition: core_mqtt_serializer.h:204
NetworkContext_t
struct NetworkContext NetworkContext_t
The NetworkContext is an incomplete type. An implementation of this interface must define struct Netw...
Definition: transport_interface.h:155
MQTTFixedBuffer_t
Buffer passed to MQTT library.
Definition: core_mqtt_serializer.h:138
MQTT_Ping
MQTTStatus_t MQTT_Ping(MQTTContext_t *pContext)
Sends an MQTT PINGREQ to broker.
Definition: core_mqtt.c:1944
MQTT_GetPacketId
uint16_t MQTT_GetPacketId(MQTTContext_t *pContext)
Get a packet ID that is valid according to the MQTT 3.1.1 spec.
Definition: core_mqtt.c:2233
MQTTPublishInfo_t::pPayload
const void * pPayload
Message payload.
Definition: core_mqtt_serializer.h:246
MQTTFixedBuffer_t::size
size_t size
Size of buffer.
Definition: core_mqtt_serializer.h:140
MQTTContext_t::lastPacketTime
uint32_t lastPacketTime
Timestamp of the last packet sent by the library.
Definition: core_mqtt.h:200
LogWarn
#define LogWarn(message)
Macro that is called in the MQTT library for logging "Warning" level messages.
Definition: core_mqtt_config_defaults.h:148
TransportInterface_t::send
TransportSend_t send
Definition: transport_interface.h:198
MQTTConnectInfo_t::pClientIdentifier
const char * pClientIdentifier
MQTT client identifier. Must be unique per client.
Definition: core_mqtt_serializer.h:162
MQTTStatus_t
MQTTStatus_t
Return codes from MQTT functions.
Definition: core_mqtt_serializer.h:105
MQTTConnectInfo_t::keepAliveSeconds
uint16_t keepAliveSeconds
MQTT keep alive period.
Definition: core_mqtt_serializer.h:157
MQTTConnectInfo_t::pPassword
const char * pPassword
MQTT password. Set to NULL if not used.
Definition: core_mqtt_serializer.h:182
MQTT_MatchTopic
MQTTStatus_t MQTT_MatchTopic(const char *pTopicName, const uint16_t topicNameLength, const char *pTopicFilter, const uint16_t topicFilterLength, bool *pIsMatch)
A utility function that determines whether the passed topic filter and topic name match according to ...
Definition: core_mqtt.c:2258
MQTTConnectInfo_t::passwordLength
uint16_t passwordLength
Length of MQTT password. Set to 0 if not used.
Definition: core_mqtt_serializer.h:187
MQTT_ReceiveLoop
MQTTStatus_t MQTT_ReceiveLoop(MQTTContext_t *pContext, uint32_t timeoutMs)
Loop to receive packets from the transport interface. Does not handle keep alive.
Definition: core_mqtt.c:2178
MQTTPublishInfo_t::pTopicName
const char * pTopicName
Topic name on which the message is published.
Definition: core_mqtt_serializer.h:236
MQTTContext_t::getTime
MQTTGetCurrentTimeFunc_t getTime
Function used to get millisecond timestamps.
Definition: core_mqtt.h:190
MQTT_Publish
MQTTStatus_t MQTT_Publish(MQTTContext_t *pContext, const MQTTPublishInfo_t *pPublishInfo, uint16_t packetId)
Publishes a message to the given topic name.
Definition: core_mqtt.c:1870
MQTTContext_t
A struct representing an MQTT connection.
Definition: core_mqtt.h:156
MQTT_Init
MQTTStatus_t MQTT_Init(MQTTContext_t *pContext, const TransportInterface_t *pTransportInterface, MQTTGetCurrentTimeFunc_t getTimeFunction, MQTTEventCallback_t userCallback, const MQTTFixedBuffer_t *pNetworkBuffer)
Initialize an MQTT context.
Definition: core_mqtt.c:1654
MQTTConnectInfo_t::cleanSession
bool cleanSession
Whether to establish a new, clean session or resume a previous session.
Definition: core_mqtt_serializer.h:152
MQTTSubscribeInfo_t::topicFilterLength
uint16_t topicFilterLength
Length of subscription topic filter.
Definition: core_mqtt_serializer.h:209
MQTTSubscribeInfo_t::qos
MQTTQoS_t qos
Quality of Service for subscription.
Definition: core_mqtt_serializer.h:199
MQTTConnectInfo_t::clientIdentifierLength
uint16_t clientIdentifierLength
Length of the client identifier.
Definition: core_mqtt_serializer.h:167
MQTTQoS1
@ MQTTQoS1
Definition: core_mqtt_serializer.h:126
MQTTPacketInfo_t::type
uint8_t type
Type of incoming MQTT packet.
Definition: core_mqtt_serializer.h:263
MQTTPublishInfo_t::qos
MQTTQoS_t qos
Quality of Service for message.
Definition: core_mqtt_serializer.h:221
MQTTSuccess
@ MQTTSuccess
Definition: core_mqtt_serializer.h:106
MQTTPublishInfo_t
MQTT PUBLISH packet parameters.
Definition: core_mqtt_serializer.h:217
MQTT_PACKET_TYPE_SUBACK
#define MQTT_PACKET_TYPE_SUBACK
SUBACK (server-to-client).
Definition: core_mqtt_serializer.h:79
MQTTConnectInfo_t::userNameLength
uint16_t userNameLength
Length of MQTT user name. Set to 0 if not used.
Definition: core_mqtt_serializer.h:177
MQTTPublishInfo_t::payloadLength
size_t payloadLength
Message payload length.
Definition: core_mqtt_serializer.h:251
TransportInterface_t::recv
TransportRecv_t recv
Definition: transport_interface.h:197
MQTTSubAckFailure
@ MQTTSubAckFailure
Failure.
Definition: core_mqtt.h:137
MQTTQoS0
@ MQTTQoS0
Definition: core_mqtt_serializer.h:125
MQTTDeserializedInfo_t
Struct to hold deserialized packet information for an MQTTEventCallback_t callback.
Definition: core_mqtt.h:220
MQTTConnectInfo_t::pUserName
const char * pUserName
MQTT user name. Set to NULL if not used.
Definition: core_mqtt_serializer.h:172
TransportInterface_t
The transport layer interface.
Definition: transport_interface.h:196