boost::mqtt5::mqtt_client::async

boost::mqtt5::mqtt_client::async_publish

Send a PUBLISH packet to Broker to transport an Application Message.

Synopsis

template<
    boost::mqtt5::qos_e qos_type,
    typename CompletionToken = typename asio::default_completion_token<boost::mqtt5::mqtt_client::executor_type>::type>
decltype(auto)
async_publish(
    std::string topic,
    std::string payload,
    boost::mqtt5::retain_e retain,
    const publish_props& props,
    CompletionToken&& token = {});

Template Parameters

Type	Description
`qos_type`	The `qos_e` level of assurance for delivery.

Parameters

Name	Description
`topic`	Identification of the information channel to which Payload data is published.
`payload`	The Application Message that is being published.
`retain`	The `retain_e` flag.
`props`	An instance of `boost::mqtt5::publish_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 depends on the qos_e specified:

qos == qos_e::at_most_once:

void (
    boost::mqtt5::error_code    // Result of operation
)

qos == qos_e::at_least_once:

void (
    boost::mqtt5::error_code,    // Result of operation.
    boost::mqtt5::reason_code,   // Reason Code received from Broker.
    boost::mqtt5::puback_props   // Properties received in the PUBACK packet.
)

qos == qos_e::exactly_once:

void (
    boost::mqtt5::error_code,    // Result of operation.
    boost::mqtt5::reason_code,   // Reason Code received from Broker.
    boost::mqtt5::pubcomp_props  // Properties received in the PUBCOMP packet.
)

Completion condition

Depending on the qos_e specified, the asynchronous operation will complete when one of the following conditions is true:

If qos == qos_e::at_most_once and the Client has successfully written the packet to the transport.
If qos == qos_e::at_least_once and the packet has been sent and acknowledged through the reception of a PUBACK packet.
If qos == qos_e::exactly_once and the packet has been sent and fully acknowledged through the reception of a PUBCOMP packet.
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::operation_aborted
boost::asio::error::no_recovery
boost::mqtt5::client::error::malformed_packet
boost::mqtt5::client::error::packet_too_large
boost::mqtt5::client::error::pid_overrun
boost::mqtt5::client::error::qos_not_supported
boost::mqtt5::client::error::retain_not_available
boost::mqtt5::client::error::topic_alias_maximum_reached
boost::mqtt5::client::error::invalid_topic

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 cancel
cancellation_type::partial & cancellation_type::total - prevents potential resending of the PUBLISH packet