IotMqtt_Subscribe

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

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

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]	mqttConnection	The MQTT connection to use for the subscription.
[in]	pSubscriptionList	Pointer to the first element in the array of subscriptions.
[in]	subscriptionCount	The number of elements in pSubscriptionList.
[in]	flags	Flags which modify the behavior of this function. See MQTT Function Flags.
[in]	pCallbackInfo	Asynchronous notification of this function's completion.
[out]	pSubscribeOperation	Set 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:

• IOT_MQTT_SUCCESS
• IOT_MQTT_NETWORK_ERROR
• IOT_MQTT_SCHEDULING_ERROR
• IOT_MQTT_BAD_RESPONSE
• IOT_MQTT_SERVER_REFUSED

If this function fails before queuing a subscribe operation, it will return one of:

• IOT_MQTT_BAD_PARAMETER
• IOT_MQTT_NO_MEMORY

See also

IotMqtt_TimedSubscribe for a blocking variant of this function.

IotMqtt_Unsubscribe 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 };
IotMqttOperation_t lastOperation = IOT_MQTT_OPERATION_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_Subscribe( mqttConnection,
                                           pSubscriptions,
                                           NUMBER_OF_SUBSCRIPTIONS,
                                           IOT_MQTT_FLAG_WAITABLE,
                                           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_Unsubscribe( mqttConnection,
                                  pSubscriptions,
                                  NUMBER_OF_SUBSCRIPTIONS,
                                  IOT_MQTT_FLAG_WAITABLE,
                                  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.
        }
    }
}