| Home | Libraries | People | FAQ | More

###### boost::mqtt5::mqtt_client::async_subscribe (1 of 2 overloads)

Send a `SUBSCRIBE` packet to Broker to create a Subscription to one or more Topics of interest.

###### Synopsis

    template<
        typename CompletionToken = typename asio::default_completion_token<boost::mqtt5::mqtt_client::executor_type>::type>
    decltype(auto)
    async_subscribe(
        const std::vector< boost::mqtt5::subscribe_topic >& topics,
        const subscribe_props& props,
        CompletionToken&& token = {});

###### Description

After the Subscription has been established, the Broker will send PUBLISH packets to the Client to forward Application Messages that were published to Topics that the Client subscribed to. The Application Messages can be received with `mqtt_client::async_receive` function.

###### Parameters

Name | Description
--- | ---
`topics` | A list of `subscribe_topic` of interest.
`props` | An instance of `boost::mqtt5::subscribe_props`.
`token` | Completion token that will be used to produce a completion handler. The handler will be invoked when the operation completes. On immediate completion, invocation of the handler will be performed in a manner equivalent to using `boost::asio::async_immediate`.

###### Handler signature

The handler signature for this operation:

    void (
        boost::mqtt5::error_code,    // Result of operation.
        std::vector<boost::mqtt5::reason_code>,  // Vector of Reason Codes indicating
                                       // the Subscription result for each Topic
                                       // in the SUBSCRIBE packet.
        boost::mqtt5::suback_props,  // Properties received in the SUBACK packet.
    )

###### Completion condition

The asynchronous operation will complete when one of the following conditions is true:

- The Client has successfully sent a `SUBSCRIBE` packet and has received a `SUBACK` response from the Broker.
- An error occurred. This is indicated by an associated ``boost::mqtt5::error_code`` in the handler.

###### Error codes

The list of all possible error codes that this operation can finish with:

- `boost::system::errc::errc_t::success`
- `boost::asio::error::no_recovery`
- `boost::asio::error::operation_aborted`
- `boost::mqtt5::client::error::malformed_packet`
- `boost::mqtt5::client::error::packet_too_large`
- `boost::mqtt5::client::error::pid_overrun`
- `boost::mqtt5::client::error::invalid_topic`
- `boost::mqtt5::client::error::wildcard_subscription_not_available`
- `boost::mqtt5::client::error::subscription_identifier_not_available`
- `boost::mqtt5::client::error::shared_subscription_not_available`

Refer to the section on `Error handling` to find the underlying causes for each error code.

###### Per-Operation Cancellation

This asynchronous operation supports cancellation for the following `boost::asio::cancellation_type` values:

- `cancellation_type::terminal` - invokes `mqtt_client::cancel`
- `cancellation_type::partial` & `cancellation_type::total` - prevents potential resending of the `SUBSCRIBE` packet