MQTT API Reference
MQTT 3.1.1 client library
IotMqtt_SubscribeAsync

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

const IotMqttSubscription_t * pSubscriptionList,
size_t subscriptionCount,
uint32_t flags,
const IotMqttCallbackInfo_t * pCallbackInfo,
IotMqttOperation_t * const pSubscribeOperation );

This function sends 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 (NULL to disable).
[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.
}
}
}
IOT_MQTT_STATUS_PENDING
MQTT operation queued, awaiting result.
Definition: iot_mqtt_types.h:129
IOT_MQTT_SERVER_REFUSED
A CONNECT or at least one subscription was refused by the server.
Definition: iot_mqtt_types.h:238
IotMqttError_t
IotMqttError_t
Return codes of MQTT functions.
Definition: iot_mqtt_types.h:103
IotMqttCallbackInfo_t
MQTT callback function and context.
Definition: iot_mqtt_types.h:507
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
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 optionally receive an asynchronous notificatio...
Definition: iot_mqtt_api.c:1541
IotMqttConnection_t
struct _mqttConnection * IotMqttConnection_t
Opaque handle of an MQTT connection.
Definition: iot_mqtt_types.h:66
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:585
IotMqttSubscription_t
MQTT subscription.
Definition: iot_mqtt_types.h:541
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:1128
IotMqtt_Wait
IotMqttError_t IotMqtt_Wait(IotMqttOperation_t operation, uint32_t timeoutMs)
Waits for an operation to complete.
Definition: iot_mqtt_api.c:1916
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 optionally receive an asynchronous notification wh...
Definition: iot_mqtt_api.c:1468
IotMqttCallbackParam_t
Parameter to an MQTT callback function.
Definition: iot_mqtt_types.h:434
IOT_MQTT_FLAG_WAITABLE
#define IOT_MQTT_FLAG_WAITABLE
Allows the use of IotMqtt_Wait for blocking until completion.
Definition: iot_mqtt_types.h:1152
IOT_MQTT_OPERATION_INITIALIZER
#define IOT_MQTT_OPERATION_INITIALIZER
Initializer for IotMqttOperation_t.
Definition: iot_mqtt_types.h:1134