AWS IoT Device SDK C: MQTT
MQTT 3.1.1 client library
Return to main page ↑
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.
}
}
}