async_mqtt::client< Version, NextLayer > Class Template Reference

MQTT client for casual usecases. More...

Classes
struct	pubres_type
	publish completion handler parameter class More...
struct	rebind_executor
	rebinds the client type to another executor More...

Public Types
using	endpoint_type = basic_endpoint<role::client, 2, NextLayer>
	type of endpoint
using	next_layer_type = typename endpoint_type::next_layer_type
	type of the given NextLayer
using	lowest_layer_type = typename endpoint_type::lowest_layer_type
	lowest_layer_type of the given NextLayer
using	executor_type = typename endpoint_type::executor_type
	executor_type of the given NextLayer

Public Member Functions
template<typename... Args>
	client (Args &&... args)
	constructor
	client (this_type const &)=delete
	copy constructor deleted
	client (this_type &&)=default
	move constructor
	~client ()=default
	destructor This function destroys the client, cancelling any outstanding asynchronous operations associated with the client.
this_type &	operator= (this_type const &)=delete
	copy assign operator deleted
this_type &	operator= (this_type &&)=default
	move assign operator
template<typename... Args>
auto	async_start (Args &&... args)
	send CONNECT packet and start packet receive loop
template<typename... Args>
auto	async_subscribe (Args &&... args)
	send SUBSCRIBE packet
template<typename... Args>
auto	async_unsubscribe (Args &&... args)
	send UNSUBSCRIBE packet
template<typename... Args>
auto	async_publish (Args &&... args)
	send PUBLISH packet
template<typename... Args>
auto	async_disconnect (Args &&... args)
	send DISCONNECT packet
template<typename... Args>
auto	async_auth (Args &&... args)
	send AUTH packet
template<typename CompletionToken = as::default_completion_token_t<executor_type>>
	async_close (CompletionToken &&token=as::default_completion_token_t< executor_type >{})
	close the underlying connection
template<typename CompletionToken = as::default_completion_token_t<executor_type>>
	async_recv (CompletionToken &&token=as::default_completion_token_t< executor_type >{})
	receive PUBLISH or DISCONNECT packet users CANNOT call recv() before the previous recv()'s CompletionToken is invoked
as::any_io_executor	get_executor ()
	executor getter
next_layer_type const &	next_layer () const
	next_layer getter
next_layer_type &	next_layer ()
	next_layer getter
lowest_layer_type const &	lowest_layer () const
	lowest_layer getter
lowest_layer_type &	lowest_layer ()
	lowest_layer getter
endpoint_type const &	get_endpoint () const
	get endpoint This is for detail operation
endpoint_type &	get_endpoint ()
	get endpoint This is for detail operation
void	set_auto_map_topic_alias_send (bool val)
	auto map (allocate) topic alias on send PUBLISH packet. If all topic aliases are used, then overwrite by LRU algorithm. This function should be called before send() call.
void	set_auto_replace_topic_alias_send (bool val)
	auto replace topic with corresponding topic alias on send PUBLISH packet. Registering topic alias need to do manually. This function should be called before send() call.
void	set_pingresp_recv_timeout (std::chrono::milliseconds duration)
	Set timeout for receiving PINGRESP packet after PINGREQ packet is sent. If the timer is fired, then the underlying layer is closed from the client side. If the protocol_version is v5, then send DISCONNECT packet with the reason code disconnect_reason_code::keep_alive_timeout automatically before underlying layer is closed. This function should be called before send() call.
void	set_bulk_write (bool val)
	Set bulk write mode. If true, then concatenate multiple packets' const buffer sequence when send() is called before the previous send() is not completed. Otherwise, send packet one by one. This function should be called before send() call.
void	set_bulk_read_buffer_size (std::size_t val)
	Set the bulk read buffer size. If bulk read is enabled, the val parameter specifies the size of the internal async_read_some() buffer. Enabling bulk read can improve throughput but may increase latency. Disabling bulk read can reduce latency but may lower throughput. By default, bulk read is disabled.
template<typename CompletionToken = as::default_completion_token_t<executor_type>>
	async_acquire_unique_packet_id (CompletionToken &&token=as::default_completion_token_t< executor_type >{})
	acuire unique packet_id.
template<typename CompletionToken = as::default_completion_token_t<executor_type>>
	async_acquire_unique_packet_id_wait_until (CompletionToken &&token=as::default_completion_token_t< executor_type >{})
	acuire unique packet_id. If packet_id is fully acquired, then wait until released.
template<typename CompletionToken = as::default_completion_token_t<executor_type>>
	async_register_packet_id (packet_id_type packet_id, CompletionToken &&token=as::default_completion_token_t< executor_type >{})
	register packet_id.
template<typename CompletionToken = as::default_completion_token_t<executor_type>>
	async_release_packet_id (packet_id_type packet_id, CompletionToken &&token=as::default_completion_token_t< executor_type >{})
	release packet_id.
std::optional< packet_id_type >	acquire_unique_packet_id ()
	acuire unique packet_id.
bool	register_packet_id (packet_id_type packet_id)
	register packet_id.
void	release_packet_id (packet_id_type packet_id)
	release packet_id.

Detailed Description

template<protocol_version Version, typename NextLayer>
class async_mqtt::client< Version, NextLayer >

MQTT client for casual usecases.

Thread Safety

• Distinct objects: Safe
• Shared objects: Unsafe

Internal type aliases

• connect_packet
  • connect_packet of the Version
    • v3_1_1::connect_packet
    • v5::connect_packet
• connack_packet
  • connack_packet of the Version
    • v3_1_1::connack_packet
    • v5::connack_packet
• subscribe_packet
  • subscribe_packet of the Version
    • v3_1_1::subscribe_packet
    • v5::subscribe_packet
• suback_packet
  • suback_packet of the Version
    • v3_1_1::suback_packet
    • v5::suback_packet
• unsubscribe_packet
  • unsubscribe_packet of the Version
    • v3_1_1::unsubscribe_packet
    • v5::unsubscribe_packet
• unsuback_packet
  • unsuback_packet of the Version
    • v3_1_1::unsuback_packet
    • v5::unsuback_packet
• publish_packet
  • publish_packet of the Version
    • v3_1_1::publish_packet
    • v5::publish_packet
• puback_packet
  • puback_packet of the Version
    • v3_1_1::puback_packet
    • v5::puback_packet
• pubrec_packet
  • pubrec_packet of the Version
    • v3_1_1::pubrec_packet
    • v5::pubrec_packet
• pubrel_packet
  • pubrel_packet of the Version
    • v3_1_1::pubrel_packet
    • v5::pubrel_packet
• pubcomp_packet
  • pubcomp_packet of the Version
    • v3_1_1::pubcomp_packet
    • v5::pubcomp_packet
• disconnect_packet
  • disconnect_packet of the Version
    • v3_1_1::disconnect_packet
    • v5::disconnect_packet

Requirements

• Header: async_mqtt/client.hpp
• Convenience header: async_mqtt/all.hpp

Template Parameters

Version	MQTT protocol version.
NextLayer	Just next layer for basic_endpoint. mqtt, mqtts, ws, and wss are predefined.

Constructor & Destructor Documentation

client()

template<protocol_version Version, typename NextLayer >

template<typename... Args>

async_mqtt::client< Version, NextLayer >::client ( Args &&... args )

explicit

constructor

Template Parameters

Args	Types for the next layer

Parameters

args	args for the next layer. There are predefined next layer types: protocol::mqtt protocol::mqtts protocol::ws protocol::wss

Member Function Documentation

acquire_unique_packet_id()

template<protocol_version Version, typename NextLayer >

std::optional< packet_id_type > async_mqtt::client< Version, NextLayer >::acquire_unique_packet_id

(

)

acuire unique packet_id.

Returns

std::optional<packet_id_type> if acquired return acquired packet id, otherwise std::nullopt

async_acquire_unique_packet_id()

template<protocol_version Version, typename NextLayer >

template<typename CompletionToken = as::default_completion_token_t<executor_type>>

async_mqtt::client< Version, NextLayer >::async_acquire_unique_packet_id

(

CompletionToken &&

token = as::default_completion_token_t< executor_type >{}

)

acuire unique packet_id.

Parameters

token

CompletionToken Signature: void(error_code, packet_id_type) Default Completion Token is supported

Returns

deduced by token

Per-Operation Cancellation

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

• cancellation_type::terminal
• cancellation_type::partial
• cancellation_type::total

async_acquire_unique_packet_id_wait_until()

template<protocol_version Version, typename NextLayer >

template<typename CompletionToken = as::default_completion_token_t<executor_type>>

async_mqtt::client< Version, NextLayer >::async_acquire_unique_packet_id_wait_until

(

CompletionToken &&

token = as::default_completion_token_t< executor_type >{}

)

acuire unique packet_id. If packet_id is fully acquired, then wait until released.

Parameters

token

CompletionToken Signature: void(error_code, packet_id_type) Default Completion Token is supported

Returns

deduced by token

Per-Operation Cancellation

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

• cancellation_type::terminal
• cancellation_type::partial
• cancellation_type::total

async_auth()

template<protocol_version Version, typename NextLayer >

template<typename... Args>

auto async_mqtt::client< Version, NextLayer >::async_auth

(

Args &&...

args

)

send AUTH packet

Parameters

args

the preceding arguments AUTH packet of the Version or its constructor arguments (like std::vector::emplace_back()) v5::auth_packet the last argument CompletionToken Signature: void(error_code) Default Completion Token is supported error_code If an error occurs during packet construction auth_reason_code is set If an error occurs while checking the packet for sending auth_reason_code is set If an error occurs at an underlying layer while sending a packet underlying error is set. e.g. system, asio, beast, ...

Returns

deduced by token

Per-Operation Cancellation

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

• cancellation_type::terminal
• cancellation_type::partial

if they are also supported by the NextLayer type's async_write_some operation.

async_close()

template<protocol_version Version, typename NextLayer >

template<typename CompletionToken = as::default_completion_token_t<executor_type>>

async_mqtt::client< Version, NextLayer >::async_close

(

CompletionToken &&

token = as::default_completion_token_t< executor_type >{}

)

close the underlying connection

Parameters

token

the param is void

Returns

deduced by token

Per-Operation Cancellation

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

• cancellation_type::terminal
• cancellation_type::partial

async_disconnect()

template<protocol_version Version, typename NextLayer >

template<typename... Args>

auto async_mqtt::client< Version, NextLayer >::async_disconnect

(

Args &&...

args

)

send DISCONNECT packet

Parameters

args

the preceding arguments DISCONNECT packet of the Version or its constructor arguments (like std::vector::emplace_back()) v3_1_1::disconnect_packet v5::disconnect_packet the last argument CompletionToken Signature: void(error_code) Default Completion Token is supported error_code If an error occurs during packet construction disconnect_reason_code is set If an error occurs while checking the packet for sending disconnect_reason_code is set If an error occurs at an underlying layer while sending a packet underlying error is set. e.g. system, asio, beast, ...

Returns

deduced by token

Per-Operation Cancellation

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

• cancellation_type::terminal
• cancellation_type::partial

if they are also supported by the NextLayer type's async_write_some operation.

async_publish()

template<protocol_version Version, typename NextLayer >

template<typename... Args>

auto async_mqtt::client< Version, NextLayer >::async_publish

(

Args &&...

args

)

send PUBLISH packet

Parameters

args

the preceding arguments PUBLISH packet of the Version or its constructor arguments (like std::vector::emplace_back()) v3_1_1::publish_packet v5::publish_packet the last argument CompletionToken Signature: void(error_code, pubres_type) Default Completion Token is supported When sending QoS0 packet, all members of pubres_type are std::nullopt. When sending QoS1 packet, only pubres_type::puback_opt is set. When sending QoS2 packet, only pubres_type::pubrec_opt and pubres_type::pubcomp are set. error_code If an error occurs during packet construction disconnect_reason_code is set If an error occurs while checking the packet for sending disconnect_reason_code is set If an error occurs at an underlying layer while sending a packet underlying error is set. e.g. system, asio, beast, ... If sent PUBLISH packet is QoS0 errc::success is set If sent PUBLISH packet is QoS1 or QoS2 If the corresponding response packet is received, you can access the response packet even if an error is set If the protocol version is v3.1.1 (PUBACK, PUBREC, PUBCOMP packet has no error field) errc::success is set If the protocol version is v5 If sent PUBLISH packet is QoS1 puback_reason_code is set If sent PUBLISH packet is QoS2 If PUBREC is error pubrec_reason_code is set Otherwise (after PUBCOMP packet is received) pubcomp_reason_code is set

Returns

deduced by token

Per-Operation Cancellation

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

• cancellation_type::terminal
• cancellation_type::partial

if they are also supported by the NextLayer type's async_read_some and async_write_some operation.

async_recv()

template<protocol_version Version, typename NextLayer >

template<typename CompletionToken = as::default_completion_token_t<executor_type>>

async_mqtt::client< Version, NextLayer >::async_recv

(

CompletionToken &&

token = as::default_completion_token_t< executor_type >{}

)

receive PUBLISH or DISCONNECT packet users CANNOT call recv() before the previous recv()'s CompletionToken is invoked

Parameters

token

the params are CompletionToken Signature: void(error_code, packet_variant) he packet_variant can be one of the following: publish_packet v3_1_1::publish_packet v5::publish_packet disconnect_packet v3_1_1::disconnect_packet v5::disconnect_packet v5::auth_packet

Returns

deduced by token

• cancellation_type::terminal
• cancellation_type::partial

if they are also supported by the NextLayer type's async_read_some operation.

async_register_packet_id()

template<protocol_version Version, typename NextLayer >

template<typename CompletionToken = as::default_completion_token_t<executor_type>>

async_mqtt::client< Version, NextLayer >::async_register_packet_id	(	packet_id_type	packet_id,
		CompletionToken &&	token = as::default_completion_token_t< executor_type >{} )

register packet_id.

Parameters

packet_id	packet_id to register
token	CompletionToken Signature: void(error_code) If true, success, otherwise the packet_id has already been used. Default Completion Token is supported

Returns

deduced by token

Per-Operation Cancellation

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

• cancellation_type::terminal
• cancellation_type::partial
• cancellation_type::total

async_release_packet_id()

template<protocol_version Version, typename NextLayer >

template<typename CompletionToken = as::default_completion_token_t<executor_type>>

async_mqtt::client< Version, NextLayer >::async_release_packet_id	(	packet_id_type	packet_id,
		CompletionToken &&	token = as::default_completion_token_t< executor_type >{} )

release packet_id.

Parameters

packet_id	packet_id to release
token	CompletionToken Signature: void() Default Completion Token is supported

Returns

deduced by token

Per-Operation Cancellation

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

• cancellation_type::terminal
• cancellation_type::partial
• cancellation_type::total

async_start()

template<protocol_version Version, typename NextLayer >

template<typename... Args>

auto async_mqtt::client< Version, NextLayer >::async_start

(

Args &&...

args

)

send CONNECT packet and start packet receive loop

Parameters

args

the preceding arguments CONNECT packet of the Version or its constructor arguments (like std::vector::emplace_back()) v3_1_1::connect_packet v5::connect_packet the last argument CompletionToken Signature: void(error_code, std::optional<connack_packet>) v3_1_1::connack_packet v5::connack_packet error_code If an error occurs during packet construction If the is CONNECT packet specific error connect_reason_code is set Otherwise disconnect_reason_code is set If an error occurs while checking the packet for sending disconnect_reason_code is set If an error occurs at an underlying layer while sending a packet underlying error is set. e.g. system, asio, beast, ... If the corresponding CONNACK packet is received, you can access connack_packet even if an error is set If the protocol version is v3.1.1 connect_return_code is set If the protocol version is v5 connect_reason_code is set Underlying error TCP, TLS, Websocket related errors mqtt_error, connect_reason_code, disconnect_reason_code send packet related errors connect_return_code (v3.1.1), connect_reason_code (v5) CONNACK packet response Default Completion Token is supported

Returns

deduced by token

Per-Operation Cancellation

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

• cancellation_type::terminal
• cancellation_type::partial

if they are also supported by the NextLayer type's async_read_some and async_write_some operation.

async_subscribe()

template<protocol_version Version, typename NextLayer >

template<typename... Args>

auto async_mqtt::client< Version, NextLayer >::async_subscribe

(

Args &&...

args

)

send SUBSCRIBE packet

Parameters

args

the preceding arguments SUBSCRIBE packet of the Version or its constructor arguments (like std::vector::emplace_back()) v3_1_1::subscribe_packet v5::subscribe_packet the last argument CompletionToken Signature: void(error_code, std::optional<suback_packet>) v3_1_1::suback_packet v5::suback_packet error_code If an error occurs during packet construction disconnect_reason_code is set If an error occurs while checking the packet for sending disconnect_reason_code is set If an error occurs at an underlying layer while sending a packet underlying error is set. e.g. system, asio, beast, ... If the corresponding SUBACK packet is received, you can access suback_packet even if an error is set If the sent SUBSCRIBE packet has a single entry If the protocol version is v3.1.1 suback_return_code is set If the protocol version is v5 suback_reason_code is set If the sent SUBSCRIBE packet has multiple entries If all entries of the SUBACK packet are errors mqtt_error::all_error_detected is set If some of the entries in the SUBACK packet are errors mqtt_error::partial_error_detected is set If there are no errors in the SUBACK packet errc::success is set Default Completion Token is supported

Returns

deduced by token

Per-Operation Cancellation

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

• cancellation_type::terminal
• cancellation_type::partial

if they are also supported by the NextLayer type's async_read_some and async_write_some operation.

async_unsubscribe()

template<protocol_version Version, typename NextLayer >

template<typename... Args>

auto async_mqtt::client< Version, NextLayer >::async_unsubscribe

(

Args &&...

args

)

send UNSUBSCRIBE packet

Parameters

args

the preceding arguments UNSUBSCRIBE packet of the Version or its constructor arguments (like std::vector::emplace_back()) v3_1_1::unsubscribe_packet v5::unsubscribe_packet the last argument CompletionToken Signature: void(error_code, std::optional<unsuback_packet>) v3_1_1::unsuback_packet v5::unsuback_packet error_code If an error occurs during packet construction disconnect_reason_code is set If an error occurs while checking the packet for sending disconnect_reason_code is set If an error occurs at an underlying layer while sending a packet underlying error is set. e.g. system, asio, beast, ... If the corresponding UNSUBACK packet is received, you can access unsuback_packet even if an error is set If the protocol version is v3.1.1 (UNSUBACK packet has no error field) errc::success is set If the protocol version is v5 If the sent UNSUBSCRIBE packet has a single entry unsuback_reason_code is set If the sent UNSUBSCRIBE packet has multiple entries If all entries of the UNSUBACK packet are errors mqtt_error::all_error_detected is set If some of the entries in the UNSUBACK packet are errors mqtt_error::partial_error_detected is set If there are no errors in the UNSUBACK packet errc::success is set Default Completion Token is supported

Returns

deduced by token

Per-Operation Cancellation

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

• cancellation_type::terminal
• cancellation_type::partial

if they are also supported by the NextLayer type's async_read_some and async_write_some operation.

get_endpoint() [1/2]

template<protocol_version Version, typename NextLayer >

endpoint_type & async_mqtt::client< Version, NextLayer >::get_endpoint

(

)

get endpoint This is for detail operation

Returns

endpoint

get_endpoint() [2/2]

template<protocol_version Version, typename NextLayer >

endpoint_type const & async_mqtt::client< Version, NextLayer >::get_endpoint

(

)

const

get endpoint This is for detail operation

Returns

endpoint

get_executor()

template<protocol_version Version, typename NextLayer >

as::any_io_executor async_mqtt::client< Version, NextLayer >::get_executor

(

)

executor getter

Returns

return endpoint's executor.

lowest_layer() [1/2]

template<protocol_version Version, typename NextLayer >

lowest_layer_type & async_mqtt::client< Version, NextLayer >::lowest_layer

(

)

lowest_layer getter

Returns

reference of the lowest_layer

lowest_layer() [2/2]

template<protocol_version Version, typename NextLayer >

lowest_layer_type const & async_mqtt::client< Version, NextLayer >::lowest_layer

(

)

const

lowest_layer getter

Returns

const reference of the lowest_layer

next_layer() [1/2]

template<protocol_version Version, typename NextLayer >

next_layer_type & async_mqtt::client< Version, NextLayer >::next_layer

(

)

next_layer getter

Returns

reference of the next_layer

next_layer() [2/2]

template<protocol_version Version, typename NextLayer >

next_layer_type const & async_mqtt::client< Version, NextLayer >::next_layer

(

)

const

next_layer getter

Returns

const reference of the next_layer

register_packet_id()

template<protocol_version Version, typename NextLayer >

bool async_mqtt::client< Version, NextLayer >::register_packet_id

(

packet_id_type

packet_id

)

register packet_id.

Parameters

packet_id

packet_id to register

Returns

If true, success, otherwise the packet_id has already been used.

release_packet_id()

template<protocol_version Version, typename NextLayer >

void async_mqtt::client< Version, NextLayer >::release_packet_id

(

packet_id_type

packet_id

)

release packet_id.

Parameters

packet_id

packet_id to release

set_auto_map_topic_alias_send()

template<protocol_version Version, typename NextLayer >

void async_mqtt::client< Version, NextLayer >::set_auto_map_topic_alias_send

(

bool

val

)

auto map (allocate) topic alias on send PUBLISH packet. If all topic aliases are used, then overwrite by LRU algorithm.
This function should be called before send() call.

Note

By default not automatically mapping.

Parameters

val	if true, enable auto mapping, otherwise disable.

set_auto_replace_topic_alias_send()

template<protocol_version Version, typename NextLayer >

void async_mqtt::client< Version, NextLayer >::set_auto_replace_topic_alias_send

(

bool

val

)

auto replace topic with corresponding topic alias on send PUBLISH packet. Registering topic alias need to do manually.
This function should be called before send() call.

Note

By default not automatically replacing.

Parameters

val	if true, enable auto replacing, otherwise disable.

set_bulk_read_buffer_size()

template<protocol_version Version, typename NextLayer >

void async_mqtt::client< Version, NextLayer >::set_bulk_read_buffer_size

(

std::size_t

val

)

Set the bulk read buffer size. If bulk read is enabled, the val parameter specifies the size of the internal async_read_some() buffer. Enabling bulk read can improve throughput but may increase latency. Disabling bulk read can reduce latency but may lower throughput. By default, bulk read is disabled.

Parameters

val	If set to 0, bulk read is disabled. Otherwise, it specifies the buffer size.

set_bulk_write()

template<protocol_version Version, typename NextLayer >

void async_mqtt::client< Version, NextLayer >::set_bulk_write

(

bool

val

)

Set bulk write mode. If true, then concatenate multiple packets' const buffer sequence when send() is called before the previous send() is not completed. Otherwise, send packet one by one.
This function should be called before send() call.

Note

By default bulk write mode is false (disabled)

Parameters

val	if true, enable bulk write mode, otherwise disable it.

set_pingresp_recv_timeout()

template<protocol_version Version, typename NextLayer >

void async_mqtt::client< Version, NextLayer >::set_pingresp_recv_timeout

(

std::chrono::milliseconds

duration

)

Set timeout for receiving PINGRESP packet after PINGREQ packet is sent. If the timer is fired, then the underlying layer is closed from the client side. If the protocol_version is v5, then send DISCONNECT packet with the reason code disconnect_reason_code::keep_alive_timeout automatically before underlying layer is closed.
This function should be called before send() call.

Note

By default timeout is not set.

Parameters

duration

if zero, timer is not set; otherwise duration is set. The minimum resolution is in milliseconds.

---

The documentation for this class was generated from the following files:

• /home/kondo/work/async_mqtt/include/async_mqtt/client.hpp
• /home/kondo/work/async_mqtt/include/async_mqtt/client_fwd.hpp