Loading...
Searching...
No Matches
mqtt::async_client Class Reference

`#include <async_client.h>`

Inheritance diagram for mqtt::async_client:

## Public Types

using | ptr_t = std::shared_ptr< async_client >
using | consumer_queue_type = std::unique_ptr< thread_queue< event > >
using | message_handler = std::function< void(const_message_ptr)>
using | connection_handler = std::function< void(const string &cause)>
using | disconnected_handler = std::function< void(const properties &, ReasonCode)>
using | update_connection_handler = std::function< bool(connect_data &)>
Public Types inherited from mqtt::iasync_client
using | qos_collection = std::vector< int >

## Public Member Functions

| async_client (const string &serverURI, const string &clientId=string{})
| async_client (const string &serverURI, const string &clientId, const persistence_type &persistence)
| async_client (const string &serverURI, const string &clientId, int maxBufferedMessages, const persistence_type &persistence=persistence_type{})
| async_client (const string &serverURI, const string &clientId, const create_options &opts, const persistence_type &persistence)
| async_client (const create_options &opts)
| ~async_client () override
void | set_callback (callback &cb) override
void | disable_callbacks () override
void | set_connected_handler (connection_handler cb)
void | set_connection_lost_handler (connection_handler cb)
void | set_disconnected_handler (disconnected_handler cb)
void | set_message_callback (message_handler cb)
void | set_update_connection_handler (update_connection_handler cb)
token_ptr | connect () override
token_ptr | connect (connect_options options) override
token_ptr | connect (connect_options options, void *userContext, iaction_listener &cb) override
token_ptr | connect (void *userContext, iaction_listener &cb) override
token_ptr | reconnect () override
token_ptr | disconnect () override
token_ptr | disconnect (disconnect_options opts) override
token_ptr | disconnect (int timeout) override
template<class Rep , class Period >
token_ptr | disconnect (const std::chrono::duration< Rep, Period > &timeout)
token_ptr | disconnect (int timeout, void *userContext, iaction_listener &cb) override
template<class Rep , class Period >
token_ptr | disconnect (const std::chrono::duration< Rep, Period > &timeout, void *userContext, iaction_listener &cb)
token_ptr | disconnect (void *userContext, iaction_listener &cb) override
delivery_token_ptr | get_pending_delivery_token (int msgID) const override
std::vector< delivery_token_ptr > | get_pending_delivery_tokens () const override
string | get_client_id () const override
string | get_server_uri () const override
int | mqtt_version () const noexcept
connect_options | get_connect_options () const
bool | is_connected () const override
delivery_token_ptr | publish (string_ref topic, const void *payload, size_t n, int qos, bool retained, const properties &props=properties()) override
delivery_token_ptr | publish (string_ref topic, const void *payload, size_t n) override
delivery_token_ptr | publish (string_ref topic, binary_ref payload, int qos, bool retained, const properties &props=properties()) override
delivery_token_ptr | publish (string_ref topic, binary_ref payload) override
delivery_token_ptr | publish (string_ref topic, const void *payload, size_t n, int qos, bool retained, void *userContext, iaction_listener &cb) override
delivery_token_ptr | publish (const_message_ptr msg) override
delivery_token_ptr | publish (const_message_ptr msg, void *userContext, iaction_listener &cb) override
token_ptr | subscribe (const string &topicFilter, int qos, const subscribe_options &opts=subscribe_options(), const properties &props=properties()) override
token_ptr | subscribe (const string &topicFilter, int qos, void *userContext, iaction_listener &cb, const subscribe_options &opts=subscribe_options(), const properties &props=properties()) override
token_ptr | subscribe (const_string_collection_ptr topicFilters, const qos_collection &qos, const std::vector< subscribe_options > &opts=std::vector< subscribe_options >(), const properties &props=properties()) override
token_ptr | subscribe (const_string_collection_ptr topicFilters, const qos_collection &qos, void *userContext, iaction_listener &cb, const std::vector< subscribe_options > &opts=std::vector< subscribe_options >(), const properties &props=properties()) override
token_ptr | unsubscribe (const string &topicFilter, const properties &props=properties()) override
token_ptr | unsubscribe (const_string_collection_ptr topicFilters, const properties &props=properties()) override
token_ptr | unsubscribe (const_string_collection_ptr topicFilters, void *userContext, iaction_listener &cb, const properties &props=properties()) override
token_ptr | unsubscribe (const string &topicFilter, void *userContext, iaction_listener &cb, const properties &props=properties()) override
void | start_consuming () override
void | stop_consuming () override
void | clear_consumer () override
bool | consumer_closed () noexcept override
bool | consumer_done () noexcept override
std::size_t | consumer_queue_size () const override
event | consume_event () override
bool | try_consume_event (event *evt) override
template<typename Rep , class Period >
bool | try_consume_event_for (event *evt, const std::chrono::duration< Rep, Period > &relTime)
template<typename Rep , class Period >
event | try_consume_event_for (const std::chrono::duration< Rep, Period > &relTime)
template<class Clock , class Duration >
bool | try_consume_event_until (event *evt, const std::chrono::time_point< Clock, Duration > &absTime)
template<class Clock , class Duration >
event | try_consume_event_until (const std::chrono::time_point< Clock, Duration > &absTime)
const_message_ptr | consume_message () override
bool | try_consume_message (const_message_ptr *msg) override
template<typename Rep , class Period >
bool | try_consume_message_for (const_message_ptr *msg, const std::chrono::duration< Rep, Period > &relTime)
template<typename Rep , class Period >
const_message_ptr | try_consume_message_for (const std::chrono::duration< Rep, Period > &relTime)
template<class Clock , class Duration >
bool | try_consume_message_until (const_message_ptr *msg, const std::chrono::time_point< Clock, Duration > &absTime)
template<class Clock , class Duration >
const_message_ptr | try_consume_message_until (const std::chrono::time_point< Clock, Duration > &absTime)
Public Member Functions inherited from mqtt::iasync_client
virtual | ~iasync_client ()

## Friends

class | token

## Detailed Description

Client for talking to an MQTT server using non-blocking methods that allow an operation to run in the background.

The location of the server is specified as a URI string with the following schemas supported to specify the type and security used for the connection:

- "mqtt://" - A standard (insecure) connection over TCP. (Also, "tcp://")
- "mqtts://" - A secure connection using SSL/TLS sockets. (Also "ssl://")
- "ws://" - A standard (insecure) WebSocket connection.
- "wss:// - A secure websocket connection using SSL/TLS. @li @em "unix://" - A UNIX-domain connection on the local machine. (*nix systems, only)

The secure connection types assume that the library was built with SSL/TLS support, otherwise requesting a secure connection will result in an error.

The communication methods of this class - `connect()`, `publish()`, `subscribe()`, etc. - are all asynchronous. They create the request for the server, but return immediately, before a response is received back from the server.

These methods return a `Token` to the caller which is akin to a C++ std::future. The caller can keep the Token, then use it later to block until the asynchronous operation is complete and retrieve the result of the operation, including any response from the server.

Alternately, the application can choose to set callbacks to be fired when each operation completes. This can be used to create an event-driven architecture, but is more complex in that it forces the user to avoid any blocking operations and manually handle thread synchronization (since the callbacks run in a separate thread managed by the library).

## Member Typedef Documentation

## ptr_t

using mqtt::async_client::ptr_t = std::shared_ptr<async_client>

Smart/shared pointer for an object of this class

## consumer_queue_type

using mqtt::async_client::consumer_queue_type = std::unique_ptr<thread_queue<event> >

Type for a thread-safe queue to consume events synchronously

## message_handler

using mqtt::async_client::message_handler = std::function<void(const_message_ptr)>

Handler type for registering an individual message callback

## connection_handler

using mqtt::async_client::connection_handler = std::function<void(const string& cause)>

Handler type for when a connection is made or lost

## disconnected_handler

using mqtt::async_client::disconnected_handler = std::function<void(const properties&, ReasonCode)>

Handler type for when a disconnect packet is received

## update_connection_handler

using mqtt::async_client::update_connection_handler = std::function<bool(connect_data&)>

Handler for updating connection data before an auto-reconnect.

## Constructor & Destructor Documentation

## async_client() [1/5]

mqtt::async_client::async_client | ( | const string & | serverURI,
|  | const string & | clientId = `string{}`
| ) |  |

inline explicit

Create an async_client that can be used to communicate with an MQTT server. This uses file-based persistence in the specified directory.

Parameters

  serverURI | the address of the server to connect to, specified as a URI.
  clientId | a client identifier that is unique on the server being connected to

Exceptions

  exception | if an argument is invalid

## async_client() [2/5]

mqtt::async_client::async_client | ( | const string & | serverURI,
|  | const string & | clientId,
|  | const persistence_type & | persistence
| ) |  |

inline

Create an async_client that can be used to communicate with an MQTT server. This allows the caller to specify a user-defined persistence object, or use no persistence.

Parameters

  serverURI | the address of the server to connect to, specified as a URI.
  clientId | a client identifier that is unique on the server being connected to
  persistence | The persistence that the client should use.

Exceptions

  exception | if an argument is invalid

## async_client() [3/5]

mqtt::async_client::async_client | ( | const string & | serverURI,
|  | const string & | clientId,
|  | int | maxBufferedMessages,
|  | const persistence_type & | persistence = `persistence_type{}`
| ) |  |

inline

Create an async_client that can be used to communicate with an MQTT server, which allows for off-line message buffering. This uses file-based persistence in the specified directory.

Parameters

  serverURI | the address of the server to connect to, specified as a URI.
  clientId | a client identifier that is unique on the server being connected to
  maxBufferedMessages | the maximum number of messages allowed to be buffered while not connected
  persistence | The persistence that the client should use.

Exceptions

  exception | if an argument is invalid

## async_client() [4/5]

mqtt::async_client::async_client | ( | const string & | serverURI,
|  | const string & | clientId,
|  | const create_options & | opts,
|  | const persistence_type & | persistence
| ) |  |

inline

Create an async_client that can be used to communicate with an MQTT server, which allows for off-line message buffering. This uses file-based persistence in the specified directory.

Parameters

  serverURI | the address of the server to connect to, specified as a URI.
  clientId | a client identifier that is unique on the server being connected to
  opts | The create options
  persistence | The persistence that the client should use.

Exceptions

  exception | if an argument is invalid

## async_client() [5/5]

mqtt::async_client::async_client | ( | const create_options & | opts | ) |

inline

Create an async_client that can be used to communicate with an MQTT server, which allows for off-line message buffering. This allows the caller to specify a user-defined persistence object, or use no persistence.

Parameters

  opts | The create options

Exceptions

  exception | if an argument is invalid

## ~async_client()

mqtt::async_client::~async_client | ( |  | ) |

override

Destructor

## Member Function Documentation

## set_callback()

void mqtt::async_client::set_callback | ( | callback & | cb | ) |

override virtual

Sets a callback listener to use for events that happen asynchronously.

Parameters

  cb | callback receiver which will be invoked for certain asynchronous events

Implements mqtt::iasync_client.

## disable_callbacks()

void mqtt::async_client::disable_callbacks | ( |  | ) |

override virtual

Stops callbacks. This is not normally called by the application. It should be used cautiously as it may cause the application to lose messages.

Implements mqtt::iasync_client.

## set_connected_handler()

void mqtt::async_client::set_connected_handler | ( | connection_handler | cb | ) |

Callback for when a connection is made.

Parameters

  cb | Callback functor for when the connection is made.

## set_connection_lost_handler()

void mqtt::async_client::set_connection_lost_handler | ( | connection_handler | cb | ) |

Callback for when a connection is lost.

Parameters

  cb | Callback functor for when the connection is lost.

## set_disconnected_handler()

void mqtt::async_client::set_disconnected_handler | ( | disconnected_handler | cb | ) |

Callback for when a disconnect packet is received from the server.

Parameters

  cb | Callback for when the disconnect packet is received.

## set_message_callback()

void mqtt::async_client::set_message_callback | ( | message_handler | cb | ) |

Sets the callback for when a message arrives from the broker. Note that the application can only have one message handler which can be installed individually using this method, or installled as a listener object.

Parameters

  cb | The callback functor to register with the library.

## set_update_connection_handler()

void mqtt::async_client::set_update_connection_handler | ( | update_connection_handler | cb | ) |

Sets a callback to allow the application to update the connection data on automatic reconnects.

Parameters

  cb | The callback functor to register with the library.

## connect() [1/4]

token_ptr mqtt::async_client::connect | ( |  | ) |

override virtual

Connects to an MQTT server using the default options.

Returns
  token used to track and wait for the connect to complete. The token will be passed to any callback that has been set.

Exceptions

  exception | for non security related problems
  security_exception | for security related problems

Implements mqtt::iasync_client.

## connect() [2/4]

token_ptr mqtt::async_client::connect | ( | connect_options | options | ) |

override virtual

Connects to an MQTT server using the provided connect options.

Parameters

  options | a set of connection parameters that override the defaults.

Returns
  token used to track and wait for the connect to complete. The token will be passed to any callback that has been set.

Exceptions

  exception | for non security related problems
  security_exception | for security related problems

Implements mqtt::iasync_client.

## connect() [3/4]

token_ptr mqtt::async_client::connect | ( | connect_options | options,
|  | void * | userContext,
|  | iaction_listener & | cb
| ) |  |

override virtual

Connects to an MQTT server using the specified options.

Parameters

  options | a set of connection parameters that override the defaults.
  userContext | optional object used to pass context to the callback. Use nullptr if not required.
  cb | callback listener that will be notified when the connect completes.

Returns
  token used to track and wait for the connect to complete. The token will be passed to any callback that has been set.

Exceptions

  exception | for non security related problems
  security_exception | for security related problems

Implements mqtt::iasync_client.

## connect() [4/4]

token_ptr mqtt::async_client::connect | ( | void * | userContext,
|  | iaction_listener & | cb
| ) |  |

inline override virtual

Parameters

  userContext | optional object used to pass context to the callback. Use nullptr if not required.
  cb | callback listener that will be notified when the connect completes.

Returns
  token used to track and wait for the connect to complete. The token will be passed to any callback that has been set.

Exceptions

  exception | for non security related problems
  security_exception | for security related problems

Implements mqtt::iasync_client.

## reconnect()

token_ptr mqtt::async_client::reconnect | ( |  | ) |

override virtual

Reconnects the client using options from the previous connect. The client must have previously called connect() for this to work.

Returns
  token used to track the progress of the reconnect.

Implements mqtt::iasync_client.

## disconnect() [1/7]

token_ptr mqtt::async_client::disconnect | ( |  | ) |

inline override virtual

Disconnects from the server.

Returns
  token used to track and wait for the disconnect to complete. The token will be passed to any callback that has been set.

Exceptions

  exception | for problems encountered while disconnecting

Implements mqtt::iasync_client.

## disconnect() [2/7]

token_ptr mqtt::async_client::disconnect | ( | disconnect_options | opts | ) |

override virtual

Disconnects from the server.

Parameters

  opts | Options for disconnecting.

Returns
  token used to track and wait for the disconnect to complete. The token will be passed to any callback that has been set.

Exceptions

  exception | for problems encountered while disconnecting

Implements mqtt::iasync_client.

## disconnect() [3/7]

token_ptr mqtt::async_client::disconnect | ( | int | timeout | ) |

inline override virtual

Disconnects from the server.

Parameters

  timeout | the amount of time in milliseconds to allow for existing work to finish before disconnecting. A value of zero or less means the client will not quiesce.

Returns
  Token used to track and wait for disconnect to complete. The token will be passed to the callback methods if a callback is set.

Exceptions

  exception | for problems encountered while disconnecting

Implements mqtt::iasync_client.

## disconnect() [4/7]

template<class Rep , class Period >

token_ptr mqtt::async_client::disconnect | ( | const std::chrono::duration< Rep, Period > & | timeout | ) |

inline

Disconnects from the server.

Parameters

  timeout | the amount of time in milliseconds to allow for existing work to finish before disconnecting. A value of zero or less means the client will not quiesce.

Returns
  Token used to track and wait for disconnect to complete. The token will be passed to the callback methods if a callback is set.

Exceptions

  exception | for problems encountered while disconnecting

## disconnect() [5/7]

token_ptr mqtt::async_client::disconnect | ( | int | timeout,
|  | void * | userContext,
|  | iaction_listener & | cb
| ) |  |

override virtual

Disconnects from the server.

Parameters

  timeout | the amount of time in milliseconds to allow for existing work to finish before disconnecting. A value of zero or less means the client will not quiesce.
  userContext | optional object used to pass context to the callback. Use nullptr if not required.
  cb | callback listener that will be notified when the disconnect completes.

Returns
  token_ptr Token used to track and wait for disconnect to complete. The token will be passed to the callback methods if a callback is set.

Exceptions

  exception | for problems encountered while disconnecting

Implements mqtt::iasync_client.

## disconnect() [6/7]

template<class Rep , class Period >

token_ptr mqtt::async_client::disconnect | ( | const std::chrono::duration< Rep, Period > & | timeout,
|  | void * | userContext,
|  | iaction_listener & | cb
| ) |  |

inline

Disconnects from the server.

Parameters

  timeout | the amount of time in milliseconds to allow for existing work to finish before disconnecting. A value of zero or less means the client will not quiesce.
  userContext | optional object used to pass context to the callback. Use nullptr if not required.
  cb | callback listener that will be notified when the disconnect completes.

Returns
  token_ptr Token used to track and wait for disconnect to complete. The token will be passed to the callback methods if a callback is set.

Exceptions

  exception | for problems encountered while disconnecting

## disconnect() [7/7]

token_ptr mqtt::async_client::disconnect | ( | void * | userContext,
|  | iaction_listener & | cb
| ) |  |

inline override virtual

Disconnects from the server.

Parameters

  userContext | optional object used to pass context to the callback. Use nullptr if not required.
  cb | callback listener that will be notified when the disconnect completes.

Returns
  token_ptr Token used to track and wait for disconnect to complete. The token will be passed to the callback methods if a callback is set.

Exceptions

  exception | for problems encountered while disconnecting

Implements mqtt::iasync_client.

## get_pending_delivery_token()

delivery_token_ptr mqtt::async_client::get_pending_delivery_token | ( | int | msgID | ) | const

override virtual

Returns the delivery token for the specified message ID.

Returns
  delivery_token

Implements mqtt::iasync_client.

## get_pending_delivery_tokens()

std::vector< delivery_token_ptr > mqtt::async_client::get_pending_delivery_tokens | ( |  | ) | const

override virtual

Returns the delivery tokens for any outstanding publish operations.

Returns
  delivery_token[]

Implements mqtt::iasync_client.

## get_client_id()

string mqtt::async_client::get_client_id | ( |  | ) | const

inline override virtual

Returns the client ID used by this client.

Returns
  The client ID used by this client.

Implements mqtt::iasync_client.

## get_server_uri()

string mqtt::async_client::get_server_uri | ( |  | ) | const

inline override virtual

Returns the address of the server used by this client.

Returns
  The server's address, as a URI String.

Implements mqtt::iasync_client.

## mqtt_version()

int mqtt::async_client::mqtt_version | ( |  | ) | const

inline noexcept

Gets the MQTT version used by the client.

Returns
  The MQTT version used by the client
  - MQTTVERSION_DEFAULT (0) = default: start with 3.1.1, and if that fails, fall back to 3.1
  - MQTTVERSION_3_1 (3) = only try version 3.1
  - MQTTVERSION_3_1_1 (4) = only try version 3.1.1
  - MQTTVERSION_5 (5) = only try version 5

## get_connect_options()

connect_options mqtt::async_client::get_connect_options | ( |  | ) | const

inline

Gets a copy of the connect options that were last used in a request to connect to the broker.

Returns
  The last connect options that were used.

## is_connected()

bool mqtt::async_client::is_connected | ( |  | ) | const

inline override virtual

Determines if this client is currently connected to the server.

Returns
  true if connected, false otherwise.

Implements mqtt::iasync_client.

## publish() [1/7]

delivery_token_ptr mqtt::async_client::publish | ( | string_ref | topic,
|  | const void * | payload,
|  | size_t | n,
|  | int | qos,
|  | bool | retained,
|  | const properties & | props = `properties()`
| ) |  |

override virtual

Publishes a message to a topic on the server

Parameters

  topic | The topic to deliver the message to
  payload | the bytes to use as the message payload
  n | the number of bytes in the payload
  qos | the Quality of Service to deliver the message at. Valid values are 0, 1 or 2.
  retained | whether or not this message should be retained by the server.

Returns
  token used to track and wait for the publish to complete. The token will be passed to callback methods if set.

Implements mqtt::iasync_client.

## publish() [2/7]

delivery_token_ptr mqtt::async_client::publish | ( | string_ref | topic,
|  | const void * | payload,
|  | size_t | n
| ) |  |

inline override virtual

Publishes a message to a topic on the server

Parameters

  topic | The topic to deliver the message to
  payload | the bytes to use as the message payload
  n | the number of bytes in the payload

Returns
  token used to track and wait for the publish to complete. The token will be passed to callback methods if set.

Implements mqtt::iasync_client.

## publish() [3/7]

delivery_token_ptr mqtt::async_client::publish | ( | string_ref | topic,
|  | binary_ref | payload,
|  | int | qos,
|  | bool | retained,
|  | const properties & | props = `properties()`
| ) |  |

override virtual

Publishes a message to a topic on the server

Parameters

  topic | The topic to deliver the message to
  payload | the bytes to use as the message payload
  qos | the Quality of Service to deliver the message at. Valid values are 0, 1 or 2.
  retained | whether or not this message should be retained by the server.

Returns
  token used to track and wait for the publish to complete. The token will be passed to callback methods if set.

Implements mqtt::iasync_client.

## publish() [4/7]

delivery_token_ptr mqtt::async_client::publish | ( | string_ref | topic,
|  | binary_ref | payload
| ) |  |

inline override virtual

Publishes a message to a topic on the server

Parameters

  topic | The topic to deliver the message to
  payload | the bytes to use as the message payload

Returns
  token used to track and wait for the publish to complete. The token will be passed to callback methods if set.

Implements mqtt::iasync_client.

## publish() [5/7]

delivery_token_ptr mqtt::async_client::publish | ( | string_ref | topic,
|  | const void * | payload,
|  | size_t | n,
|  | int | qos,
|  | bool | retained,
|  | void * | userContext,
|  | iaction_listener & | cb
| ) |  |

override virtual

Publishes a message to a topic on the server

Parameters

  topic | The topic to deliver the message to
  payload | the bytes to use as the message payload
  n | the number of bytes in the payload
  qos | the Quality of Service to deliver the message at. Valid values are 0, 1 or 2.
  retained | whether or not this message should be retained by the server.
  userContext | optional object used to pass context to the callback. Use nullptr if not required.
  cb | Listener callback object

Returns
  token used to track and wait for the publish to complete. The token will be passed to callback methods if set.

Implements mqtt::iasync_client.

## publish() [6/7]

delivery_token_ptr mqtt::async_client::publish | ( | const_message_ptr | msg | ) |

override virtual

Publishes a message to a topic on the server Takes an Message message and delivers it to the server at the requested quality of service.

Parameters

  msg | the message to deliver to the server

Returns
  token used to track and wait for the publish to complete. The token will be passed to callback methods if set.

Implements mqtt::iasync_client.

## publish() [7/7]

delivery_token_ptr mqtt::async_client::publish | ( | const_message_ptr | msg,
|  | void * | userContext,
|  | iaction_listener & | cb
| ) |  |

override virtual

Publishes a message to a topic on the server.

Parameters

  msg | the message to deliver to the server
  userContext | optional object used to pass context to the callback. Use nullptr if not required.
  cb | callback optional listener that will be notified when message delivery has completed to the requested quality of service

Returns
  token used to track and wait for the publish to complete. The token will be passed to callback methods if set.

Implements mqtt::iasync_client.

## subscribe() [1/4]

token_ptr mqtt::async_client::subscribe | ( | const string & | topicFilter,
|  | int | qos,
|  | const subscribe_options & | opts = `subscribe_options()`,
|  | const properties & | props = `properties()`
| ) |  |

override virtual

Subscribe to a topic, which may include wildcards.

Parameters

  topicFilter | the topic to subscribe to, which can include wildcards.
  qos | The quality of service for the subscription
  opts | The MQTT v5 subscribe options for the topic
  props | The MQTT v5 properties.

Returns
  token used to track and wait for the subscribe to complete. The token will be passed to callback methods if set.

Implements mqtt::iasync_client.

## subscribe() [2/4]

token_ptr mqtt::async_client::subscribe | ( | const string & | topicFilter,
|  | int | qos,
|  | void * | userContext,
|  | iaction_listener & | cb,
|  | const subscribe_options & | opts = `subscribe_options()`,
|  | const properties & | props = `properties()`
| ) |  |

override virtual

Subscribe to a topic, which may include wildcards.

Parameters

  topicFilter | the topic to subscribe to, which can include wildcards.
  qos | The maximum quality of service at which to subscribe. Messages published at a lower quality of service will be received at the published QoS. Messages published at a higher quality of service will be received using the QoS specified on the subscribe.
  userContext | optional object used to pass context to the callback. Use nullptr if not required.
  cb | listener that will be notified when subscribe has completed
  opts | The MQTT v5 subscribe options for the topic
  props | The MQTT v5 properties.

Returns
  token used to track and wait for the subscribe to complete. The token will be passed to callback methods if set.

Implements mqtt::iasync_client.

## subscribe() [3/4]

token_ptr mqtt::async_client::subscribe | ( | const_string_collection_ptr | topicFilters,
|  | const qos_collection & | qos,
|  | const std::vector< subscribe_options > & | opts = `std::vector< subscribe_options >()`,
|  | const properties & | props = `properties()`
| ) |  |

override virtual

Subscribe to multiple topics, each of which may include wildcards.

Parameters

  topicFilters | The collection of topic filters to subscribe to, any of which can include wildcards
  qos | The maximum quality of service at which to subscribe. Messages published at a lower quality of service will be received at the published QoS. Messages published at a higher quality of service will be received using the QoS specified on the subscribe.
  opts | The MQTT v5 subscribe options (one for each topic)
  props | The MQTT v5 properties.

Returns
  token used to track and wait for the subscribe to complete. The token will be passed to callback methods if set.

Implements mqtt::iasync_client.

## subscribe() [4/4]

token_ptr mqtt::async_client::subscribe | ( | const_string_collection_ptr | topicFilters,
|  | const qos_collection & | qos,
|  | void * | userContext,
|  | iaction_listener & | cb,
|  | const std::vector< subscribe_options > & | opts = `std::vector< subscribe_options >()`,
|  | const properties & | props = `properties()`
| ) |  |

override virtual

Subscribes to multiple topics, each of which may include wildcards.

Parameters

  topicFilters | The collection of topic filters to subscribe to, any of which can include wildcards
  qos | The maximum quality of service at which to subscribe. Messages published at a lower quality of service will be received at the published QoS. Messages published at a higher quality of service will be received using the QoS specified on the subscribe.
  userContext | Optional object used to pass context to the callback. Use nullptr if not required.
  cb | listener that will be notified when subscribe has completed
  opts | The MQTT v5 subscribe options (one for each topic)
  props | The MQTT v5 properties.

Returns
  token used to track and wait for the subscribe to complete. The token will be passed to callback methods if set.

Implements mqtt::iasync_client.

## unsubscribe() [1/4]

token_ptr mqtt::async_client::unsubscribe | ( | const string & | topicFilter,
|  | const properties & | props = `properties()`
| ) |  |

override virtual

Requests the server unsubscribe the client from a topic.

Parameters

  topicFilter | The topic to unsubscribe from. It must match a topicFilter specified on an earlier subscribe.
  props | The MQTT v5 properties.

Returns
  token Used to track and wait for the unsubscribe to complete. The token will be passed to callback methods if set.

Implements mqtt::iasync_client.

## unsubscribe() [2/4]

token_ptr mqtt::async_client::unsubscribe | ( | const_string_collection_ptr | topicFilters,
|  | const properties & | props = `properties()`
| ) |  |

override virtual

Requests the server unsubscribe the client from one or more topics.

Parameters

  topicFilters | One or more topics to unsubscribe from. Each topicFilter must match one specified on an earlier subscribe.
  props | The MQTT v5 properties.

Returns
  token used to track and wait for the unsubscribe to complete. The token will be passed to callback methods if set.

Implements mqtt::iasync_client.

## unsubscribe() [3/4]

token_ptr mqtt::async_client::unsubscribe | ( | const_string_collection_ptr | topicFilters,
|  | void * | userContext,
|  | iaction_listener & | cb,
|  | const properties & | props = `properties()`
| ) |  |

override virtual

Requests the server unsubscribe the client from one or more topics.

Parameters

  topicFilters | One or more topics to unsubscribe from. Each topicFilter must match one specified on an earlier subscribe.
  userContext | optional object used to pass context to the callback. Use nullptr if not required.
  cb | listener that will be notified when unsubscribe has completed
  props | The MQTT v5 properties.

Returns
  token used to track and wait for the unsubscribe to complete. The token will be passed to callback methods if set.

Implements mqtt::iasync_client.

## unsubscribe() [4/4]

token_ptr mqtt::async_client::unsubscribe | ( | const string & | topicFilter,
|  | void * | userContext,
|  | iaction_listener & | cb,
|  | const properties & | props = `properties()`
| ) |  |

override virtual

Requests the server unsubscribe the client from a topics.

Parameters

  topicFilter | the topic to unsubscribe from. It must match a topicFilter specified on an earlier subscribe.
  userContext | optional object used to pass context to the callback. Use nullptr if not required.
  cb | listener that will be notified when unsubscribe has completed
  props | The MQTT v5 properties.

Returns
  token used to track and wait for the unsubscribe to complete. The token will be passed to callback methods if set.

Implements mqtt::iasync_client.

## start_consuming()

void mqtt::async_client::start_consuming | ( |  | ) |

override virtual

Start consuming messages.

This initializes the client to receive messages through a queue that can be read synchronously.

Normally this should be called before connecting the client to the broker, in order to have the consumer queue in place in the event that the immediately starts sending messages (such as any retained messages) while the client is still in the context of the connect call.

This must also be called before calling any 'consume_message' or "'consume_event' methods.

Internally, this just creates a thread-safe queue for `mqtt::event` objects, then hooks into the message and state-change callback to push events into the queue in the order received.

Implements mqtt::iasync_client.

## stop_consuming()

void mqtt::async_client::stop_consuming | ( |  | ) |

override virtual

Stop consuming messages.

This shuts down the internal callback and closes the internal consumer queue. Any remaining messages and events can be read until the queue is emptied, but nothing further will be added to it. This will also wake up any thread waiting on the queue.

Implements mqtt::iasync_client.

## clear_consumer()

void mqtt::async_client::clear_consumer | ( |  | ) |

inline override virtual

This clears the consumer queue, discarding any pending event.

Reimplemented from mqtt::iasync_client.

## consumer_closed()

bool mqtt::async_client::consumer_closed | ( |  | ) |

inline override virtual noexcept

Determines if the consumer queue has been closed. Once closed, any events in the queue can still be read, but no new events can be added to it.

Returns
  @true if the consumer queue has been closed, @false otherwise.

Reimplemented from mqtt::iasync_client.

## consumer_done()

bool mqtt::async_client::consumer_done | ( |  | ) |

inline override virtual noexcept

Determines if the consumer queue is "done" (closed and empty). Once the queue is done, no more events can be added or removed fom the queue.

Returns
  @true if the consumer queue is closed and empty, @false otherwise.

Reimplemented from mqtt::iasync_client.

## consumer_queue_size()

std::size_t mqtt::async_client::consumer_queue_size | ( |  | ) | const

inline override virtual

Gets the number of events available for immediate consumption. Note that this retrieves the number of "raw" events, not messages, e.g. may include a connected_event which is not returned by try_consume_message(). When polling the queue from multiple threads, prefer using try_consume_event(), as the event count may change between checking the size and actual retrieval.

Returns
  the number of events in the queue.

Reimplemented from mqtt::iasync_client.

## consume_event()

event mqtt::async_client::consume_event | ( |  | ) |

override virtual

Read the next client event from the queue. This blocks until a new message arrives. If the consumer queue is closed, this returns a shutdown event.

Returns
  The client event.

Reimplemented from mqtt::iasync_client.

## try_consume_event()

bool mqtt::async_client::try_consume_event | ( | event * | evt | ) |

override virtual

Try to read the next client event without blocking.

Parameters

  evt | Pointer to the value to receive the event

Returns
  true if an event was read, false if no event was available.

Reimplemented from mqtt::iasync_client.

## try_consume_event_for() [1/2]

template<typename Rep , class Period >

bool mqtt::async_client::try_consume_event_for | ( | event * | evt,
|  | const std::chrono::duration< Rep, Period > & | relTime
| ) |  |

inline

Waits a limited time for a client event to appear.

Parameters

  evt | Pointer to the value to receive the event.
  relTime | The maximum amount of time to wait for an event.

Returns
  true if an event was read, false if a timeout occurred.

## try_consume_event_for() [2/2]

template<typename Rep , class Period >

event mqtt::async_client::try_consume_event_for | ( | const std::chrono::duration< Rep, Period > & | relTime | ) |

inline

Waits a limited time for a client event to arrive.

Parameters

  relTime | The maximum amount of time to wait for an event.

Returns
  The event that was received. It will contain empty message on timeout.

## try_consume_event_until() [1/2]

template<class Clock , class Duration >

bool mqtt::async_client::try_consume_event_until | ( | event * | evt,
|  | const std::chrono::time_point< Clock, Duration > & | absTime
| ) |  |

inline

Waits until a specific time for a client event to appear.

Parameters

  evt | Pointer to the value to receive the event.
  absTime | The time point to wait until, before timing out.

Returns
  true if an event was recceived, false if a timeout occurred.

## try_consume_event_until() [2/2]

template<class Clock , class Duration >

event mqtt::async_client::try_consume_event_until | ( | const std::chrono::time_point< Clock, Duration > & | absTime | ) |

inline

Waits until a specific time for a client event to appear.

Parameters

  absTime | The time point to wait until, before timing out.

Returns
  The event that was received. It will contain empty message on timeout.

## consume_message()

const_message_ptr mqtt::async_client::consume_message | ( |  | ) |

override virtual

Read the next message from the queue. This blocks until a new message arrives or until a disconnect or shutdown occurs.

Returns
  The message and topic.

Implements mqtt::iasync_client.

## try_consume_message()

bool mqtt::async_client::try_consume_message | ( | const_message_ptr * | msg | ) |

override virtual

Try to read the next message from the queue without blocking.

Parameters

  msg | Pointer to the value to receive the message

Returns
  true is a message was read, false if no message was available.

Implements mqtt::iasync_client.

## try_consume_message_for() [1/2]

template<typename Rep , class Period >

bool mqtt::async_client::try_consume_message_for | ( | const_message_ptr * | msg,
|  | const std::chrono::duration< Rep, Period > & | relTime
| ) |  |

inline

Waits a limited time for a message to arrive.

Parameters

  msg | Pointer to the value to receive the message
  relTime | The maximum amount of time to wait for a message.

Returns
  true if a message was read, false if a timeout occurred.

## try_consume_message_for() [2/2]

template<typename Rep , class Period >

const_message_ptr mqtt::async_client::try_consume_message_for | ( | const std::chrono::duration< Rep, Period > & | relTime | ) |

inline

Waits a limited time for a message to arrive.

Parameters

  relTime | The maximum amount of time to wait for a message.

Returns
  A shared pointer to the message that was received. It will be empty on timeout.

## try_consume_message_until() [1/2]

template<class Clock , class Duration >

bool mqtt::async_client::try_consume_message_until | ( | const_message_ptr * | msg,
|  | const std::chrono::time_point< Clock, Duration > & | absTime
| ) |  |

inline

Waits until a specific time for a message to appear.

Parameters

  msg | Pointer to the value to receive the message
  absTime | The time point to wait until, before timing out.

Returns
  true if a message was read, false if a timeout occurred.

## try_consume_message_until() [2/2]

template<class Clock , class Duration >

const_message_ptr mqtt::async_client::try_consume_message_until | ( | const std::chrono::time_point< Clock, Duration > & | absTime | ) |

inline

Waits until a specific time for a message to appear.

Parameters

  absTime | The time point to wait until, before timing out.

Returns
  The message, if read, an empty pointer if not.

## Friends And Related Symbol Documentation

## token

friend class token

friend

Manage internal list of active tokens

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

- async_client.h