MQTT API Reference
MQTT 3.1.1 client library
iot_mqtt.h File Reference

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

#include "iot_config.h"
#include "types/iot_mqtt_types.h"

Go to the source code of this file.

Functions

IotMqttError_t IotMqtt_Init (void)
 One-time initialization function for the MQTT library. More...
 
void IotMqtt_Cleanup (void)
 One-time deinitialization function for the MQTT library. More...
 
void IotMqtt_ReceiveCallback (void *pNetworkConnection, void *pReceiveContext)
 Network receive callback for the MQTT library. More...
 
IotMqttError_t IotMqtt_Connect (const IotMqttNetworkInfo_t *pNetworkInfo, const IotMqttConnectInfo_t *pConnectInfo, uint32_t timeoutMs, IotMqttConnection_t *const pMqttConnection)
 Establish a new MQTT connection. More...
 
void IotMqtt_Disconnect (IotMqttConnection_t mqttConnection, uint32_t flags)
 Closes an MQTT connection and frees resources. More...
 
IotMqttError_t IotMqtt_SubscribeAsync (IotMqttConnection_t mqttConnection, const IotMqttSubscription_t *pSubscriptionList, size_t subscriptionCount, uint32_t flags, const IotMqttCallbackInfo_t *pCallbackInfo, IotMqttOperation_t *const pSubscribeOperation)
 Subscribes to the given array of topic filters and receive an asynchronous notification when the subscribe completes. More...
 
IotMqttError_t IotMqtt_SubscribeSync (IotMqttConnection_t mqttConnection, const IotMqttSubscription_t *pSubscriptionList, size_t subscriptionCount, uint32_t flags, uint32_t timeoutMs)
 Subscribes to the given array of topic filters with a timeout. More...
 
IotMqttError_t IotMqtt_UnsubscribeAsync (IotMqttConnection_t mqttConnection, const IotMqttSubscription_t *pSubscriptionList, size_t subscriptionCount, uint32_t flags, const IotMqttCallbackInfo_t *pCallbackInfo, IotMqttOperation_t *const pUnsubscribeOperation)
 Unsubscribes from the given array of topic filters and receive an asynchronous notification when the unsubscribe completes. More...
 
IotMqttError_t IotMqtt_UnsubscribeSync (IotMqttConnection_t mqttConnection, const IotMqttSubscription_t *pSubscriptionList, size_t subscriptionCount, uint32_t flags, uint32_t timeoutMs)
 Unsubscribes from a given array of topic filters with a timeout. More...
 
IotMqttError_t IotMqtt_PublishAsync (IotMqttConnection_t mqttConnection, const IotMqttPublishInfo_t *pPublishInfo, uint32_t flags, const IotMqttCallbackInfo_t *pCallbackInfo, IotMqttOperation_t *const pPublishOperation)
 Publishes a message to the given topic name and receive an asynchronous notification when the publish completes. More...
 
IotMqttError_t IotMqtt_PublishSync (IotMqttConnection_t mqttConnection, const IotMqttPublishInfo_t *pPublishInfo, uint32_t flags, uint32_t timeoutMs)
 Publish a message to the given topic name with a timeout. More...
 
IotMqttError_t IotMqtt_Wait (IotMqttOperation_t operation, uint32_t timeoutMs)
 Waits for an operation to complete. More...
 
const char * IotMqtt_strerror (IotMqttError_t status)
 Returns a string that describes an IotMqttError_t. More...
 
const char * IotMqtt_OperationType (IotMqttOperationType_t operation)
 Returns a string that describes an IotMqttOperationType_t. More...
 
bool IotMqtt_IsSubscribed (IotMqttConnection_t mqttConnection, const char *pTopicFilter, uint16_t topicFilterLength, IotMqttSubscription_t *const pCurrentSubscription)
 Check if an MQTT connection has a subscription for a topic filter. More...
 

Detailed Description

User-facing functions of the MQTT 3.1.1 library.

Function Documentation

◆ IotMqtt_Init()

IotMqttError_t IotMqtt_Init ( void  )

One-time initialization function for the MQTT library.

This function performs setup of the MQTT library. It must be called once (and only once) before calling any other MQTT function. Calling this function more than once without first calling IotMqtt_Cleanup may result in a crash.

Returns
One of the following:
Warning
No thread-safety guarantees are provided for this function.
See also
IotMqtt_Cleanup

◆ IotMqtt_Cleanup()

void IotMqtt_Cleanup ( void  )

One-time deinitialization function for the MQTT library.

This function frees resources taken in IotMqtt_Init. It should be called after closing all MQTT connections to clean up the MQTT library. After this function returns, IotMqtt_Init must be called again before calling any other MQTT function.

Warning
No thread-safety guarantees are provided for this function. Do not call this function if any MQTT connections are open!
See also
IotMqtt_Init

◆ IotMqtt_ReceiveCallback()

void IotMqtt_ReceiveCallback ( void *  pNetworkConnection,
void *  pReceiveContext 
)

Network receive callback for the MQTT library.

This function should be called by the system whenever data is available for the MQTT library.

Parameters
[in]pNetworkConnectionThe network connection associated with the MQTT connection, passed by the network stack.
[in]pReceiveContextA pointer to the MQTT connection handle for which the packet was received.

◆ IotMqtt_Connect()

IotMqttError_t IotMqtt_Connect ( const IotMqttNetworkInfo_t pNetworkInfo,
const IotMqttConnectInfo_t pConnectInfo,
uint32_t  timeoutMs,
IotMqttConnection_t *const  pMqttConnection 
)

Establish a new MQTT connection.

This function opens a connection between a new MQTT client and an MQTT server (also called a broker). MQTT connections are established on top of transport layer protocols (such as TCP/IP), and optionally, application layer security protocols (such as TLS). The MQTT packet that establishes a connection is called the MQTT CONNECT packet. After IotMqtt_Init, this function must be called before any other MQTT library function.

If pConnectInfo->cleanSession is true, this function establishes a clean MQTT session. Subscriptions and unacknowledged PUBLISH messages will be discarded when the connection is closed.

If pConnectInfo->cleanSession is false, this function establishes (or re-establishes) a persistent MQTT session. The parameters pConnectInfo->pPreviousSubscriptions and pConnectInfo->previousSubscriptionCount may be used to restore subscriptions present in a re-established persistent session. Any restored subscriptions MUST have been present in the persistent session; this function does not send an MQTT SUBSCRIBE packet!

This MQTT library is network agnostic, meaning it has no knowledge of the underlying network protocol carrying the MQTT packets. It interacts with the network through a network abstraction layer, allowing it to be used with many different network stacks. The network abstraction layer is established per-connection, allowing every IotMqttConnection_t to use a different network stack. The parameter pNetworkInterface sets up the network abstraction layer for an MQTT connection; see the documentation on IotMqttNetworkInfo_t for details on its members.

The pConnectInfo parameter provides the contents of the MQTT CONNECT packet. Most members are defined by the MQTT spec.. The pConnectInfo->pWillInfo member provides information on a Last Will and Testament (LWT) message to be published if the MQTT connection is closed without sending a DISCONNECT packet. Unlike other PUBLISH messages, a LWT message payload is limited to 65535 bytes in length. Additionally, the retry interval and limit members of IotMqttPublishInfo_t are ignored for LWT messages. The LWT message is optional; pWillInfo may be NULL.

Unlike IotMqtt_PublishAsync, IotMqtt_SubscribeAsync, and IotMqtt_UnsubscribeAsync, this function is always blocking. Additionally, because the MQTT connection acknowledgement packet (CONNACK packet) does not contain any information on which CONNECT packet it acknowledges, only one CONNECT operation may be in progress at any time. This means that parallel threads making calls to IotMqtt_Connect will be serialized to send their CONNECT packets one-by-one.

Parameters
[in]pNetworkInfoInformation on the transport-layer network connection to use with the MQTT connection.
[in]pConnectInfoMQTT connection setup parameters.
[in]timeoutMsIf the MQTT server does not accept the connection within this timeout in milliseconds, this function returns IOT_MQTT_TIMEOUT.
[out]pMqttConnectionSet to a newly-initialized MQTT connection handle if this function succeeds.
Returns
One of the following:

Example

// An initialized and connected network connection.
IotNetworkConnection_t pNetworkConnection;
// Parameters to MQTT connect.
// Example network abstraction types.
IotNetworkServerInfo_t serverInfo = { ... };
IotNetworkCredentials_t credentialInfo = { ... };
IotNetworkInterface_t networkInterface = { ... };
// Example using a generic network implementation.
networkInfo.createNetworkConnection = true;
networkInfo.u.setup.pNetworkServerInfo = &serverInfo;
networkInfo.u.setup.pNetworkCredentialInfo = &credentialInfo;
networkInfo.pNetworkInterface = &networkInterface;
// Set the members of the connection info (password and username not used).
connectInfo.cleanSession = true;
connectInfo.keepAliveSeconds = 30;
connectInfo.pClientIdentifier = "uniqueclientidentifier";
connectInfo.clientIdentifierLength = 22;
// Set the members of the will info (retain and retry not used).
willInfo.qos = IOT_MQTT_QOS_1;
willInfo.pTopicName = "will/topic/name";
willInfo.topicNameLength = 15;
willInfo.pPayload = "MQTT client unexpectedly disconnected.";
willInfo.payloadLength = 38;
// Set the pointer to the will info.
connectInfo.pWillInfo = &willInfo;
// Call CONNECT with a 5 second block time. Should return
// IOT_MQTT_SUCCESS when successful.
IotMqttError_t result = IotMqtt_Connect( &networkInfo,
&connectInfo,
5000,
&mqttConnection );
if( result == IOT_MQTT_SUCCESS )
{
// Do something with the MQTT connection...
// Clean up and close the MQTT connection once it's no longer needed.
IotMqtt_Disconnect( mqttConnection, 0 );
}

◆ IotMqtt_Disconnect()

void IotMqtt_Disconnect ( IotMqttConnection_t  mqttConnection,
uint32_t  flags 
)

Closes an MQTT connection and frees resources.

This function closes an MQTT connection and should only be called once the MQTT connection is no longer needed. Its exact behavior depends on the flags parameter.

Normally, flags should be 0. This gracefully shuts down an MQTT connection by sending an MQTT DISCONNECT packet. Any network close function provided when the connection was established will also be called. Note that because the MQTT server will not acknowledge a DISCONNECT packet, the client has no way of knowing if the server received the DISCONNECT packet. In the case where the DISCONNECT packet is lost in transport, any Last Will and Testament (LWT) message established with the connection may be published. However, if the DISCONNECT reaches the MQTT server, the LWT message will be discarded and not published.

Should the underlying network connection become unusable, this function should be called with flags set to IOT_MQTT_FLAG_CLEANUP_ONLY. In this case, no DISCONNECT packet will be sent, though the network close function will still be called. This function will only free the resources used by the MQTT connection; it still must be called even if the network is offline to avoid leaking resources.

Once this function is called, its parameter mqttConnection should no longer be used.

Parameters
[in]mqttConnectionThe MQTT connection to close and clean up.
[in]flagsFlags which modify the behavior of this function. See MQTT Function Flags.

◆ IotMqtt_SubscribeAsync()

IotMqttError_t IotMqtt_SubscribeAsync ( IotMqttConnection_t  mqttConnection,
const IotMqttSubscription_t pSubscriptionList,
size_t  subscriptionCount,
uint32_t  flags,
const IotMqttCallbackInfo_t pCallbackInfo,
IotMqttOperation_t *const  pSubscribeOperation 
)

Subscribes to the given array of topic filters and receive an asynchronous notification when the subscribe completes.

This function transmits an MQTT SUBSCRIBE packet to the server. A SUBSCRIBE packet notifies the server to send any matching PUBLISH messages to this client. A single SUBSCRIBE packet may carry more than one topic filter, hence the parameters to this function include an array of subscriptions.

An MQTT subscription has two pieces:

  1. The subscription topic filter registered with the MQTT server. The MQTT SUBSCRIBE packet sent from this client to server notifies the server to send messages matching the given topic filters to this client.
  2. The callback function that this client will invoke when an incoming message is received. The callback function notifies applications of an incoming PUBLISH message.

The helper function IotMqtt_IsSubscribed can be used to check if a callback function is registered for a particular topic filter.

To modify an already-registered subscription callback, call this function with a new pSubscriptionList. Any topic filters in pSubscriptionList that already have a registered callback will be replaced with the new values in pSubscriptionList.

Attention
QoS 2 subscriptions are currently unsupported. Only 0 or 1 are valid for subscription QoS.
Parameters
[in]mqttConnectionThe MQTT connection to use for the subscription.
[in]pSubscriptionListPointer to the first element in the array of subscriptions.
[in]subscriptionCountThe number of elements in pSubscriptionList.
[in]flagsFlags which modify the behavior of this function. See MQTT Function Flags.
[in]pCallbackInfoAsynchronous notification of this function's completion.
[out]pSubscribeOperationSet to a handle by which this operation may be referenced after this function returns. This reference is invalidated once the subscription operation completes.
Returns
This function will return IOT_MQTT_STATUS_PENDING upon success.
Upon completion of the subscription (either through an IotMqttCallbackInfo_t or IotMqtt_Wait), the status will be one of:
If this function fails before queuing a subscribe operation, it will return one of:
See also
IotMqtt_SubscribeSync for a blocking variant of this function.
IotMqtt_UnsubscribeAsync for the function that removes subscriptions.

Example

#define NUMBER_OF_SUBSCRIPTIONS ...
// Subscription callback function.
void subscriptionCallback( void * pArgument, IotMqttCallbackParam_t * pPublish );
// An initialized and connected MQTT connection.
IotMqttConnection_t mqttConnection;
// Subscription information.
pSubscriptions[ NUMBER_OF_SUBSCRIPTIONS ] = { IOT_MQTT_SUBSCRIPTION_INITIALIZER };
// Set the subscription information.
for( int i = 0; i < NUMBER_OF_SUBSCRIPTIONS; i++ )
{
pSubscriptions[ i ].qos = IOT_MQTT_QOS_1;
pSubscriptions[ i ].pTopicFilter = "some/topic/filter";
pSubscriptions[ i ].topicLength = ( uint16_t ) strlen( pSubscriptions[ i ].pTopicFilter );
pSubscriptions[ i ].callback.function = subscriptionCallback;
}
IotMqttError_t result = IotMqtt_SubscribeAsync( mqttConnection,
pSubscriptions,
NUMBER_OF_SUBSCRIPTIONS,
NULL,
&lastOperation );
// Subscribe returns IOT_MQTT_STATUS_PENDING when successful. Wait up to
// 5 seconds for the operation to complete.
if( result == IOT_MQTT_STATUS_PENDING )
{
result = IotMqtt_Wait( subscriptionRef, 5000 );
}
// Check that the subscriptions were successful.
if( result == IOT_MQTT_SUCCESS )
{
// Wait for messages on the subscription topic filters...
// Unsubscribe once the subscriptions are no longer needed.
result = IotMqtt_UnsubscribeAsync( mqttConnection,
pSubscriptions,
NUMBER_OF_SUBSCRIPTIONS,
NULL,
&lastOperation );
// UNSUBSCRIBE returns IOT_MQTT_STATUS_PENDING when successful.
// Wait up to 5 seconds for the operation to complete.
if( result == IOT_MQTT_STATUS_PENDING )
{
result = IotMqtt_Wait( lastOperation, 5000 );
}
}
// Check which subscriptions were rejected by the server.
else if( result == IOT_MQTT_SERVER_REFUSED )
{
for( int i = 0; i < NUMBER_OF_SUBSCRIPTIONS; i++ )
{
if( IotMqtt_IsSubscribed( mqttConnection,
pSubscriptions[ i ].pTopicFilter,
pSubscriptions[ i ].topicFilterLength,
NULL ) == false )
{
// This subscription was rejected.
}
}
}

◆ IotMqtt_SubscribeSync()

IotMqttError_t IotMqtt_SubscribeSync ( IotMqttConnection_t  mqttConnection,
const IotMqttSubscription_t pSubscriptionList,
size_t  subscriptionCount,
uint32_t  flags,
uint32_t  timeoutMs 
)

Subscribes to the given array of topic filters with a timeout.

This function transmits an MQTT SUBSCRIBE packet to the server, then waits for a server response to the packet. Internally, this function is a call to IotMqtt_SubscribeAsync followed by IotMqtt_Wait. See IotMqtt_SubscribeAsync for more information about the MQTT SUBSCRIBE operation.

Attention
QoS 2 subscriptions are currently unsupported. Only 0 or 1 are valid for subscription QoS.
Parameters
[in]mqttConnectionThe MQTT connection to use for the subscription.
[in]pSubscriptionListPointer to the first element in the array of subscriptions.
[in]subscriptionCountThe number of elements in pSubscriptionList.
[in]flagsFlags which modify the behavior of this function. See MQTT Function Flags. Currently, flags are ignored by this function; this parameter is for future-compatibility.
[in]timeoutMsIf the MQTT server does not acknowledge the subscriptions within this timeout, this function returns IOT_MQTT_TIMEOUT.
Returns
One of the following:

◆ IotMqtt_UnsubscribeAsync()

IotMqttError_t IotMqtt_UnsubscribeAsync ( IotMqttConnection_t  mqttConnection,
const IotMqttSubscription_t pSubscriptionList,
size_t  subscriptionCount,
uint32_t  flags,
const IotMqttCallbackInfo_t pCallbackInfo,
IotMqttOperation_t *const  pUnsubscribeOperation 
)

Unsubscribes from the given array of topic filters and receive an asynchronous notification when the unsubscribe completes.

This function transmits an MQTT UNSUBSCRIBE packet to the server. An UNSUBSCRIBE packet removes registered topic filters from the server. After unsubscribing, the server will no longer send messages on these topic filters to the client.

Corresponding subscription callback functions are also removed from the MQTT connection. These subscription callback functions will be removed even if the MQTT UNSUBSCRIBE packet fails to send.

Parameters
[in]mqttConnectionThe MQTT connection used for the subscription.
[in]pSubscriptionListPointer to the first element in the array of subscriptions.
[in]subscriptionCountThe number of elements in pSubscriptionList.
[in]flagsFlags which modify the behavior of this function. See MQTT Function Flags.
[in]pCallbackInfoAsynchronous notification of this function's completion.
[out]pUnsubscribeOperationSet to a handle by which this operation may be referenced after this function returns. This reference is invalidated once the unsubscribe operation completes.
Returns
This function will return IOT_MQTT_STATUS_PENDING upon success.
Upon completion of the unsubscribe (either through an IotMqttCallbackInfo_t or IotMqtt_Wait), the status will be one of:
If this function fails before queuing an unsubscribe operation, it will return one of:
See also
IotMqtt_UnsubscribeSync for a blocking variant of this function.
IotMqtt_SubscribeAsync for the function that adds subscriptions.

◆ IotMqtt_UnsubscribeSync()

IotMqttError_t IotMqtt_UnsubscribeSync ( IotMqttConnection_t  mqttConnection,
const IotMqttSubscription_t pSubscriptionList,
size_t  subscriptionCount,
uint32_t  flags,
uint32_t  timeoutMs 
)

Unsubscribes from a given array of topic filters with a timeout.

This function transmits an MQTT UNSUBSCRIBE packet to the server, then waits for a server response to the packet. Internally, this function is a call to IotMqtt_UnsubscribeAsync followed by IotMqtt_Wait. See IotMqtt_UnsubscribeAsync for more information about the MQTT UNSUBSCRIBE operation.

Parameters
[in]mqttConnectionThe MQTT connection used for the subscription.
[in]pSubscriptionListPointer to the first element in the array of subscriptions.
[in]subscriptionCountThe number of elements in pSubscriptionList.
[in]flagsFlags which modify the behavior of this function. See MQTT Function Flags. Currently, flags are ignored by this function; this parameter is for future-compatibility.
[in]timeoutMsIf the MQTT server does not acknowledge the UNSUBSCRIBE within this timeout, this function returns IOT_MQTT_TIMEOUT.
Returns
One of the following:

◆ IotMqtt_PublishAsync()

IotMqttError_t IotMqtt_PublishAsync ( IotMqttConnection_t  mqttConnection,
const IotMqttPublishInfo_t pPublishInfo,
uint32_t  flags,
const IotMqttCallbackInfo_t pCallbackInfo,
IotMqttOperation_t *const  pPublishOperation 
)

Publishes a message to the given topic name and receive an asynchronous notification when the publish completes.

This function transmits an MQTT PUBLISH packet to the server. A PUBLISH packet contains a payload and a topic name. Any clients with a subscription on a topic filter matching the PUBLISH topic name will receive a copy of the PUBLISH packet from the server.

If a PUBLISH packet fails to reach the server and it is not a QoS 0 message, it will be retransmitted. See IotMqttPublishInfo_t for a description of the retransmission strategy.

Attention
QoS 2 messages are currently unsupported. Only 0 or 1 are valid for message QoS.
Parameters
[in]mqttConnectionThe MQTT connection to use for the publish.
[in]pPublishInfoMQTT publish parameters.
[in]flagsFlags which modify the behavior of this function. See MQTT Function Flags.
[in]pCallbackInfoAsynchronous notification of this function's completion.
[out]pPublishOperationSet to a handle by which this operation may be referenced after this function returns. This reference is invalidated once the publish operation completes.
Returns
This function will return IOT_MQTT_STATUS_PENDING upon success for QoS 1 publishes. For a QoS 0 publish it returns IOT_MQTT_SUCCESS upon success.
Upon completion of a QoS 1 publish (either through an IotMqttCallbackInfo_t or IotMqtt_Wait), the status will be one of:
If this function fails before queuing an publish operation (regardless of QoS), it will return one of:
Note
The parameters pCallbackInfo and pPublishOperation should only be used for QoS 1 publishes. For QoS 0, they should both be NULL.
See also
IotMqtt_PublishSync for a blocking variant of this function.

Example

// An initialized and connected MQTT connection.
IotMqttConnection_t mqttConnection;
// Publish information.
// Set the publish information. QoS 0 example (retain not used):
publishInfo.qos = IOT_MQTT_QOS_0;
publishInfo.pTopicName = "some/topic/name";
publishInfo.topicNameLength = 15;
publishInfo.pPayload = "payload";
publishInfo.payloadLength = 8;
// QoS 0 publish should return IOT_MQTT_SUCCESS upon success.
IotMqttError_t qos0Result = IotMqtt_PublishAsync( mqttConnection,
&publishInfo,
0,
NULL,
NULL );
// QoS 1 with retry example (using same topic name and payload as QoS 0 example):
publishInfo.qos = IOT_MQTT_QOS_1;
publishInfo.retryMs = 1000; // Retry if no response is received in 1 second.
publishInfo.retryLimit = 5; // Retry up to 5 times.
// QoS 1 publish should return IOT_MQTT_STATUS_PENDING upon success.
IotMqttError_t qos1Result = IotMqtt_PublishAsync( mqttConnection,
&publishInfo,
NULL,
&qos1Operation );
// Wait up to 5 seconds for the publish to complete.
if( qos1Result == IOT_MQTT_STATUS_PENDING )
{
qos1Result = IotMqtt_Wait( qos1Operation, 5000 );
}

◆ IotMqtt_PublishSync()

IotMqttError_t IotMqtt_PublishSync ( IotMqttConnection_t  mqttConnection,
const IotMqttPublishInfo_t pPublishInfo,
uint32_t  flags,
uint32_t  timeoutMs 
)

Publish a message to the given topic name with a timeout.

This function transmits an MQTT PUBLISH packet to the server, then waits for a server response to the packet. Internally, this function is a call to IotMqtt_PublishAsync followed by IotMqtt_Wait. See IotMqtt_PublishAsync for more information about the MQTT PUBLISH operation.

Attention
QoS 2 messages are currently unsupported. Only 0 or 1 are valid for message QoS.
Parameters
[in]mqttConnectionThe MQTT connection to use for the publish.
[in]pPublishInfoMQTT publish parameters.
[in]flagsFlags which modify the behavior of this function. See MQTT Function Flags. Currently, flags are ignored by this function; this parameter is for future-compatibility.
[in]timeoutMsIf the MQTT server does not acknowledge a QoS 1 PUBLISH within this timeout, this function returns IOT_MQTT_TIMEOUT. This parameter is ignored for QoS 0 PUBLISH messages.
Returns
One of the following:

◆ IotMqtt_Wait()

IotMqttError_t IotMqtt_Wait ( IotMqttOperation_t  operation,
uint32_t  timeoutMs 
)

Waits for an operation to complete.

This function blocks to wait for a subscribe, unsubscribe, or publish to complete. These operations are by default asynchronous; the function calls queue an operation for processing, and a callback is invoked once the operation is complete.

To use this function, the flag IOT_MQTT_FLAG_WAITABLE must have been set in the operation's function call. Additionally, this function must always be called with any waitable operation to clean up resources.

Regardless of its return value, this function always clean up resources used by the waitable operation. This means reference is invalidated as soon as this function returns, even if it returns IOT_MQTT_TIMEOUT or another error.

Parameters
[in]operationReference to the operation to wait for. The flag IOT_MQTT_FLAG_WAITABLE must have been set for this operation.
[in]timeoutMsHow long to wait before returning IOT_MQTT_TIMEOUT.
Returns
The return value of this function depends on the MQTT operation associated with reference. See IotMqttError_t for possible return values.

Example

// Operation reference and timeout.
uint32_t timeoutMs = 5000; // 5 seconds
// MQTT operation to wait for.
IotMqttError_t result = IotMqtt_PublishAsync( mqttConnection,
&publishInfo,
NULL,
&publishOperation );
// Publish should have returned IOT_MQTT_STATUS_PENDING. The call to wait
// returns once the result of the publish is available or the timeout expires.
if( result == IOT_MQTT_STATUS_PENDING )
{
result = IotMqtt_Wait( publishOperation, timeoutMs );
// After the call to wait, the result of the publish is known
// (not IOT_MQTT_STATUS_PENDING).
assert( result != IOT_MQTT_STATUS_PENDING );
}

◆ IotMqtt_strerror()

const char* IotMqtt_strerror ( IotMqttError_t  status)

Returns a string that describes an IotMqttError_t.

Like the POSIX's strerror, this function returns a string describing a return code. In this case, the return code is an MQTT library error code, status.

The string returned by this function MUST be treated as read-only: any attempt to modify its contents may result in a crash. Therefore, this function is limited to usage in logging.

Parameters
[in]statusThe status to describe.
Returns
A read-only string that describes status.
Warning
The string returned by this function must never be modified.

◆ IotMqtt_OperationType()

const char* IotMqtt_OperationType ( IotMqttOperationType_t  operation)

Returns a string that describes an IotMqttOperationType_t.

This function returns a string describing an MQTT operation type, operation.

The string returned by this function MUST be treated as read-only: any attempt to modify its contents may result in a crash. Therefore, this function is limited to usage in logging.

Parameters
[in]operationThe operation to describe.
Returns
A read-only string that describes operation.
Warning
The string returned by this function must never be modified.

◆ IotMqtt_IsSubscribed()

bool IotMqtt_IsSubscribed ( IotMqttConnection_t  mqttConnection,
const char *  pTopicFilter,
uint16_t  topicFilterLength,
IotMqttSubscription_t *const  pCurrentSubscription 
)

Check if an MQTT connection has a subscription for a topic filter.

This function checks whether an MQTT connection mqttConnection has a subscription callback registered for a topic filter pTopicFilter. If a subscription callback is found, its details are copied into the output parameter pCurrentSubscription. This subscription callback will be invoked for incoming PUBLISH messages on pTopicFilter.

The check for a matching subscription is only performed client-side; therefore, this function should not be relied upon for perfect accuracy. For example, this function may return an incorrect result if the MQTT server crashes and drops subscriptions without informing the client.

Note that an MQTT connection's subscriptions might change between the time this function checks the subscription list and its caller tests the return value. This function certainly should not be used concurrently with any pending SUBSCRIBE or UNSUBSCRIBE operations.

One suitable use of this function is to check which subscriptions were rejected if IotMqtt_SubscribeAsync returns IOT_MQTT_SERVER_REFUSED; that return code only means that at least one subscription was rejected.

Parameters
[in]mqttConnectionThe MQTT connection to check.
[in]pTopicFilterThe topic filter to check.
[in]topicFilterLengthLength of pTopicFilter.
[out]pCurrentSubscriptionIf a subscription is found, its details are copied here. This output parameter is only valid if this function returns true. Pass NULL to ignore.
Returns
true if a subscription was found; false otherwise.
Note
The subscription QoS is not stored by the MQTT library; therefore, pCurrentSubscription->qos will always be set to IOT_MQTT_QOS_0.
IOT_MQTT_STATUS_PENDING
MQTT operation queued, awaiting result.
Definition: iot_mqtt_types.h:129
IotMqttNetworkInfo_t::pNetworkInterface
const IotNetworkInterface_t * pNetworkInterface
The network functions used by the new MQTT connection.
Definition: iot_mqtt_types.h:990
IOT_MQTT_CONNECT_INFO_INITIALIZER
#define IOT_MQTT_CONNECT_INFO_INITIALIZER
Initializer for IotMqttConnectInfo_t.
Definition: iot_mqtt_types.h:1061
IotMqttConnectInfo_t::keepAliveSeconds
uint16_t keepAliveSeconds
Period of keep-alive messages. Set to 0 to disable keep-alive.
Definition: iot_mqtt_types.h:674
IotMqttConnectInfo_t::cleanSession
bool cleanSession
Whether this connection is a clean session.
Definition: iot_mqtt_types.h:632
IotMqttPublishInfo_t::retryLimit
uint32_t retryLimit
How many times to attempt retransmission.
Definition: iot_mqtt_types.h:409
IOT_MQTT_SERVER_REFUSED
A CONNECT or at least one subscription was refused by the server.
Definition: iot_mqtt_types.h:238
IotMqtt_Disconnect
void IotMqtt_Disconnect(IotMqttConnection_t mqttConnection, uint32_t flags)
Closes an MQTT connection and frees resources.
Definition: iot_mqtt_api.c:1327
IotMqttError_t
IotMqttError_t
Return codes of MQTT functions.
Definition: iot_mqtt_types.h:103
IotMqtt_PublishAsync
IotMqttError_t IotMqtt_PublishAsync(IotMqttConnection_t mqttConnection, const IotMqttPublishInfo_t *pPublishInfo, uint32_t flags, const IotMqttCallbackInfo_t *pCallbackInfo, IotMqttOperation_t *const pPublishOperation)
Publishes a message to the given topic name and receive an asynchronous notification when the publish...
Definition: iot_mqtt_api.c:1595
IotMqttPublishInfo_t::pPayload
const void * pPayload
Payload of PUBLISH.
Definition: iot_mqtt_types.h:405
IotMqttOperation_t
struct _mqttOperation * IotMqttOperation_t
Opaque handle that references an in-progress MQTT operation.
Definition: iot_mqtt_types.h:88
IOT_MQTT_SUCCESS
MQTT operation completed successfully.
Definition: iot_mqtt_types.h:119
IotMqttPublishInfo_t::topicNameLength
uint16_t topicNameLength
Length of IotMqttPublishInfo_t.pTopicName.
Definition: iot_mqtt_types.h:403
IOT_MQTT_NETWORK_INFO_INITIALIZER
#define IOT_MQTT_NETWORK_INFO_INITIALIZER
Initializer for IotMqttNetworkInfo_t.
Definition: iot_mqtt_types.h:1057
IotMqttPublishInfo_t::pTopicName
const char * pTopicName
Topic name of PUBLISH.
Definition: iot_mqtt_types.h:402
IotMqttPublishInfo_t::retryMs
uint32_t retryMs
If no response is received within this time, the message is retransmitted.
Definition: iot_mqtt_types.h:408
IotMqtt_UnsubscribeAsync
IotMqttError_t IotMqtt_UnsubscribeAsync(IotMqttConnection_t mqttConnection, const IotMqttSubscription_t *pSubscriptionList, size_t subscriptionCount, uint32_t flags, const IotMqttCallbackInfo_t *pCallbackInfo, IotMqttOperation_t *const pUnsubscribeOperation)
Unsubscribes from the given array of topic filters and receive an asynchronous notification when the ...
Definition: iot_mqtt_api.c:1539
IotMqttConnection_t
struct _mqttConnection * IotMqttConnection_t
Opaque handle of an MQTT connection.
Definition: iot_mqtt_types.h:66
IOT_MQTT_CONNECTION_INITIALIZER
#define IOT_MQTT_CONNECTION_INITIALIZER
Initializer for IotMqttConnection_t.
Definition: iot_mqtt_types.h:1069
IotMqttNetworkInfo_t
Infomation on the transport-layer network connection for the new MQTT connection.
Definition: iot_mqtt_types.h:930
IotMqttPublishInfo_t::qos
IotMqttQos_t qos
QoS of message. Must be 0 or 1.
Definition: iot_mqtt_types.h:399
IotMqttNetworkInfo_t::u
union IotMqttNetworkInfo_t::@5 u
Valid member depends of IotMqttNetworkInfo_t.createNetworkConnection.
IotMqtt_IsSubscribed
bool IotMqtt_IsSubscribed(IotMqttConnection_t mqttConnection, const char *pTopicFilter, uint16_t topicFilterLength, IotMqttSubscription_t *const pCurrentSubscription)
Check if an MQTT connection has a subscription for a topic filter.
Definition: iot_mqtt_subscription.c:584
IotNetworkCredentials_t
IotMqttConnectInfo_t::clientIdentifierLength
uint16_t clientIdentifierLength
Length of IotMqttConnectInfo_t.pClientIdentifier.
Definition: iot_mqtt_types.h:677
IOT_MQTT_QOS_0
Definition: iot_mqtt_types.h:305
IotNetworkInterface_t
IotMqttPublishInfo_t::payloadLength
size_t payloadLength
Length of IotMqttPublishInfo_t.pPayload. For LWT messages, this is limited to 65535.
Definition: iot_mqtt_types.h:406
IotNetworkServerInfo_t
IotMqttNetworkInfo_t::createNetworkConnection
bool createNetworkConnection
Whether a new network connection should be created.
Definition: iot_mqtt_types.h:947
IOT_MQTT_QOS_1
Definition: iot_mqtt_types.h:306
IOT_MQTT_SUBSCRIPTION_INITIALIZER
#define IOT_MQTT_SUBSCRIPTION_INITIALIZER
Initializer for IotMqttSubscription_t.
Definition: iot_mqtt_types.h:1065
IotMqtt_Wait
IotMqttError_t IotMqtt_Wait(IotMqttOperation_t operation, uint32_t timeoutMs)
Waits for an operation to complete.
Definition: iot_mqtt_api.c:1918
IotMqttPublishInfo_t
Information on a PUBLISH message.
Definition: iot_mqtt_types.h:397
IotMqtt_SubscribeAsync
IotMqttError_t IotMqtt_SubscribeAsync(IotMqttConnection_t mqttConnection, const IotMqttSubscription_t *pSubscriptionList, size_t subscriptionCount, uint32_t flags, const IotMqttCallbackInfo_t *pCallbackInfo, IotMqttOperation_t *const pSubscribeOperation)
Subscribes to the given array of topic filters and receive an asynchronous notification when the subs...
Definition: iot_mqtt_api.c:1483
IotMqttCallbackParam_t
Parameter to an MQTT callback function.
Definition: iot_mqtt_types.h:443
IOT_MQTT_FLAG_WAITABLE
#define IOT_MQTT_FLAG_WAITABLE
Allows the use of IotMqtt_Wait for blocking until completion.
Definition: iot_mqtt_types.h:1087
IOT_MQTT_PUBLISH_INFO_INITIALIZER
#define IOT_MQTT_PUBLISH_INFO_INITIALIZER
Initializer for IotMqttPublishInfo_t.
Definition: iot_mqtt_types.h:1063
IotMqttConnectInfo_t::pWillInfo
const IotMqttPublishInfo_t * pWillInfo
A message to publish if the new MQTT connection is unexpectedly closed.
Definition: iot_mqtt_types.h:672
IotMqttConnectInfo_t::pClientIdentifier
const char * pClientIdentifier
MQTT client identifier.
Definition: iot_mqtt_types.h:676
IotMqtt_Connect
IotMqttError_t IotMqtt_Connect(const IotMqttNetworkInfo_t *pNetworkInfo, const IotMqttConnectInfo_t *pConnectInfo, uint32_t timeoutMs, IotMqttConnection_t *const pMqttConnection)
Establish a new MQTT connection.
Definition: iot_mqtt_api.c:975
IotMqttConnectInfo_t
Information on a new MQTT connection.
Definition: iot_mqtt_types.h:585
IOT_MQTT_OPERATION_INITIALIZER
#define IOT_MQTT_OPERATION_INITIALIZER
Initializer for IotMqttOperation_t.
Definition: iot_mqtt_types.h:1071