mqtt_client::async

mqtt_client::async_publish

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

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

Description

Template Parameters

Name	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 `async_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 (
  async_mqtt5::error_code  // Result of operation
)

qos == qos_e::at_least_once:

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

qos == qos_e::exactly_once:

void (
  async_mqtt5::error_code, // Result of operation.
  async_mqtt5::reason_code,  // Reason Code received from Broker.
  async_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 async_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
async_mqtt5::client::error::malformed_packet
async_mqtt5::client::error::packet_too_large
async_mqtt5::client::error::pid_overrun
async_mqtt5::client::error::qos_not_supported
async_mqtt5::client::error::retain_not_available
async_mqtt5::client::error::topic_alias_maximum_reached
async_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 mqtt_client::cancel
cancellation_type::partial & cancellation_type::total - prevents potential resending of the PUBLISH packet