![]() |
paho-mqtt-cpp
MQTT C++ Client for POSIX and Windows
|
#include <async_client.h>
Public Types | |
using | ptr_t = std::shared_ptr< async_client > |
using | consumer_queue_type = std::unique_ptr< thread_queue< const_message_ptr > > |
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 &)> |
![]() | |
using | qos_collection = std::vector< int > |
Public Member Functions | |
async_client (const string &serverURI, const string &clientId, const string &persistDir) | |
async_client (const string &serverURI, const string &clientId, iclient_persistence *persistence=nullptr) | |
async_client (const string &serverURI, const string &clientId, int maxBufferedMessages, const string &persistDir) | |
async_client (const string &serverURI, const string &clientId, int maxBufferedMessages, iclient_persistence *persistence=nullptr) | |
async_client (const string &serverURI, const string &clientId, const create_options &opts, const string &persistDir) | |
async_client (const string &serverURI, const string &clientId, const create_options &opts, iclient_persistence *persistence=nullptr) | |
~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 |
bool | is_connected () const override |
delivery_token_ptr | publish (string_ref topic, const void *payload, size_t n, int qos, bool retained) 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) 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 |
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) |
![]() | |
virtual | ~iasync_client () |
virtual token_ptr | connect ()=0 |
virtual token_ptr | connect (connect_options options)=0 |
virtual token_ptr | connect (connect_options options, void *userContext, iaction_listener &cb)=0 |
virtual token_ptr | connect (void *userContext, iaction_listener &cb)=0 |
virtual token_ptr | reconnect ()=0 |
virtual token_ptr | disconnect ()=0 |
virtual token_ptr | disconnect (disconnect_options opts)=0 |
virtual token_ptr | disconnect (int timeout)=0 |
virtual token_ptr | disconnect (int timeout, void *userContext, iaction_listener &cb)=0 |
virtual token_ptr | disconnect (void *userContext, iaction_listener &cb)=0 |
virtual delivery_token_ptr | get_pending_delivery_token (int msgID) const =0 |
virtual std::vector< delivery_token_ptr > | get_pending_delivery_tokens () const =0 |
virtual string | get_client_id () const =0 |
virtual string | get_server_uri () const =0 |
virtual bool | is_connected () const =0 |
virtual delivery_token_ptr | publish (string_ref topic, const void *payload, size_t n, int qos, bool retained)=0 |
virtual delivery_token_ptr | publish (string_ref topic, const void *payload, size_t n)=0 |
virtual delivery_token_ptr | publish (string_ref topic, const void *payload, size_t n, int qos, bool retained, void *userContext, iaction_listener &cb)=0 |
virtual delivery_token_ptr | publish (string_ref topic, binary_ref payload, int qos, bool retained)=0 |
virtual delivery_token_ptr | publish (string_ref topic, binary_ref payload)=0 |
virtual delivery_token_ptr | publish (const_message_ptr msg)=0 |
virtual delivery_token_ptr | publish (const_message_ptr msg, void *userContext, iaction_listener &cb)=0 |
virtual void | set_callback (callback &cb)=0 |
virtual void | disable_callbacks ()=0 |
virtual token_ptr | subscribe (const string &topicFilter, int qos, const subscribe_options &opts=subscribe_options(), const properties &props=properties())=0 |
virtual token_ptr | subscribe (const string &topicFilter, int qos, void *userContext, iaction_listener &callback, const subscribe_options &opts=subscribe_options(), const properties &props=properties())=0 |
virtual 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())=0 |
virtual token_ptr | subscribe (const_string_collection_ptr topicFilters, const qos_collection &qos, void *userContext, iaction_listener &callback, const std::vector< subscribe_options > &opts=std::vector< subscribe_options >(), const properties &props=properties())=0 |
virtual token_ptr | unsubscribe (const string &topicFilter, const properties &props=properties())=0 |
virtual token_ptr | unsubscribe (const_string_collection_ptr topicFilters, const properties &props=properties())=0 |
virtual token_ptr | unsubscribe (const_string_collection_ptr topicFilters, void *userContext, iaction_listener &cb, const properties &props=properties())=0 |
virtual token_ptr | unsubscribe (const string &topicFilter, void *userContext, iaction_listener &cb, const properties &props=properties())=0 |
virtual void | start_consuming ()=0 |
virtual void | stop_consuming ()=0 |
virtual const_message_ptr | consume_message ()=0 |
virtual bool | try_consume_message (const_message_ptr *msg)=0 |
Friends | |
class | token |
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:
The secure connection types assume that the library was built with OpenSSL support, otherwise requesting a secure conection 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 imediately, 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).
using mqtt::async_client::ptr_t = std::shared_ptr<async_client> |
Smart/shared pointer for an object of this class
using mqtt::async_client::consumer_queue_type = std::unique_ptr<thread_queue<const_message_ptr> > |
Type for a thread-safe queue to consume messages synchronously
using mqtt::async_client::message_handler = std::function<void(const_message_ptr)> |
Handler type for registering an individual message callback
using mqtt::async_client::connection_handler = std::function<void(const string& cause)> |
Handler type for when a connecion is made or lost
using mqtt::async_client::disconnected_handler = std::function<void(const properties&, ReasonCode)> |
Handler type for when a disconnect packet is received
using mqtt::async_client::update_connection_handler = std::function<bool(connect_data&)> |
Handler for updaing connection data before an auto-reconnect.
mqtt::async_client::async_client | ( | const string & | serverURI, |
const string & | clientId, | ||
const string & | persistDir | ||
) |
Create an async_client that can be used to communicate with an MQTT server. This uses file-based persistence in the specified directory.
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 |
persistDir | The directory to use for persistence data |
exception | if an argument is invalid |
mqtt::async_client::async_client | ( | const string & | serverURI, |
const string & | clientId, | ||
iclient_persistence * | persistence = nullptr |
||
) |
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.
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 user persistence structure. If this is null, then no persistence is used. |
exception | if an argument is invalid |
mqtt::async_client::async_client | ( | const string & | serverURI, |
const string & | clientId, | ||
int | maxBufferedMessages, | ||
const string & | persistDir | ||
) |
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.
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 |
persistDir | The directory to use for persistence data |
exception | if an argument is invalid |
mqtt::async_client::async_client | ( | const string & | serverURI, |
const string & | clientId, | ||
int | maxBufferedMessages, | ||
iclient_persistence * | persistence = nullptr |
||
) |
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.
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 user persistence structure. If this is null, then no persistence is used. |
exception | if an argument is invalid |
mqtt::async_client::async_client | ( | const string & | serverURI, |
const string & | clientId, | ||
const create_options & | opts, | ||
const string & | persistDir | ||
) |
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.
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 |
persistDir | The directory to use for persistence data |
exception | if an argument is invalid |
mqtt::async_client::async_client | ( | const string & | serverURI, |
const string & | clientId, | ||
const create_options & | opts, | ||
iclient_persistence * | persistence = nullptr |
||
) |
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.
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 user persistence structure. If this is null, then no persistence is used. |
exception | if an argument is invalid |
|
override |
Destructor
|
overridevirtual |
Sets a callback listener to use for events that happen asynchronously.
cb | callback receiver which will be invoked for certain asynchronous events |
Implements mqtt::iasync_client.
|
overridevirtual |
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.
void mqtt::async_client::set_connected_handler | ( | connection_handler | cb | ) |
Callback for when a connection is made.
cb | Callback functor for when the connection is made. |
void mqtt::async_client::set_connection_lost_handler | ( | connection_handler | cb | ) |
Callback for when a connection is lost.
cb | Callback functor for when the connection is lost. |
void mqtt::async_client::set_disconnected_handler | ( | disconnected_handler | cb | ) |
Callback for when a disconnect packet is received from the server.
cb | Callback for when the disconnect packet is received. |
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.
cb | The callback functor to register with the library. |
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.
cb | The callback functor to register with the library. |
|
overridevirtual |
Connects to an MQTT server using the default options.
exception | for non security related problems |
security_exception | for security related problems |
Implements mqtt::iasync_client.
|
overridevirtual |
Connects to an MQTT server using the provided connect options.
options | a set of connection parameters that override the defaults. |
exception | for non security related problems |
security_exception | for security related problems |
Implements mqtt::iasync_client.
|
overridevirtual |
Connects to an MQTT server using the specified options.
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. |
exception | for non security related problems |
security_exception | for security related problems |
Implements mqtt::iasync_client.
|
inlineoverridevirtual |
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. |
exception | for non security related problems |
security_exception | for security related problems |
Implements mqtt::iasync_client.
|
overridevirtual |
Reconnects the client using options from the previous connect. The client must have previously called connect() for this to work.
Implements mqtt::iasync_client.
|
inlineoverridevirtual |
Disconnects from the server.
exception | for problems encountered while disconnecting |
Implements mqtt::iasync_client.
|
overridevirtual |
Disconnects from the server.
opts | Options for disconnecting. |
exception | for problems encountered while disconnecting |
Implements mqtt::iasync_client.
|
inlineoverridevirtual |
Disconnects from the server.
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. |
exception | for problems encountered while disconnecting |
Implements mqtt::iasync_client.
|
inline |
Disconnects from the server.
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. |
exception | for problems encountered while disconnecting |
|
overridevirtual |
Disconnects from the server.
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. |
exception | for problems encountered while disconnecting |
Implements mqtt::iasync_client.
|
inline |
Disconnects from the server.
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. |
exception | for problems encountered while disconnecting |
|
inlineoverridevirtual |
Disconnects from the server.
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. |
exception | for problems encountered while disconnecting |
Implements mqtt::iasync_client.
|
overridevirtual |
Returns the delivery token for the specified message ID.
Implements mqtt::iasync_client.
|
overridevirtual |
Returns the delivery tokens for any outstanding publish operations.
Implements mqtt::iasync_client.
|
inlineoverridevirtual |
Returns the client ID used by this client.
Implements mqtt::iasync_client.
|
inlineoverridevirtual |
Returns the address of the server used by this client.
Implements mqtt::iasync_client.
|
inlinenoexcept |
Gets the MQTT version used by the client.
|
inlineoverridevirtual |
Determines if this client is currently connected to the server.
Implements mqtt::iasync_client.
|
overridevirtual |
Publishes a message to a topic on the server
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. |
Implements mqtt::iasync_client.
|
inlineoverridevirtual |
Publishes a message to a topic on the server
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 |
Implements mqtt::iasync_client.
|
overridevirtual |
Publishes a message to a topic on the server
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. |
Implements mqtt::iasync_client.
|
inlineoverridevirtual |
Publishes a message to a topic on the server
topic | The topic to deliver the message to |
payload | the bytes to use as the message payload |
Implements mqtt::iasync_client.
|
overridevirtual |
Publishes a message to a topic on the server
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 |
Implements mqtt::iasync_client.
|
overridevirtual |
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.
msg | the message to deliver to the server |
Implements mqtt::iasync_client.
|
overridevirtual |
Publishes a message to a topic on the server.
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 |
Implements mqtt::iasync_client.
|
overridevirtual |
Subscribe to a topic, which may include wildcards.
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. |
Implements mqtt::iasync_client.
|
overridevirtual |
Subscribe to a topic, which may include wildcards.
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. |
Implements mqtt::iasync_client.
|
overridevirtual |
Subscribe to multiple topics, each of which may include wildcards.
topicFilters | |
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. |
Implements mqtt::iasync_client.
|
overridevirtual |
Subscribes to multiple topics, each of which may include wildcards.
topicFilters | |
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. |
Implements mqtt::iasync_client.
|
overridevirtual |
Requests the server unsubscribe the client from a topic.
topicFilter | the topic to unsubscribe from. It must match a topicFilter specified on an earlier subscribe. |
props | The MQTT v5 properties. |
Implements mqtt::iasync_client.
|
overridevirtual |
Requests the server unsubscribe the client from one or more topics.
topicFilters | one or more topics to unsubscribe from. Each topicFilter must match one specified on an earlier subscribe. |
props | The MQTT v5 properties. |
Implements mqtt::iasync_client.
|
overridevirtual |
Requests the server unsubscribe the client from one or more topics.
topicFilters | |
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. |
Implements mqtt::iasync_client.
|
overridevirtual |
Requests the server unsubscribe the client from a topics.
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. |
Implements mqtt::iasync_client.
|
overridevirtual |
Start consuming messages. This initializes the client to receive messages through a queue that can be read synchronously.
Implements mqtt::iasync_client.
|
overridevirtual |
Stop consuming messages. This shuts down the internal callback and discards any unread messages.
Implements mqtt::iasync_client.
|
inlineoverridevirtual |
Read the next message from the queue. This blocks until a new message arrives.
Implements mqtt::iasync_client.
|
inlineoverridevirtual |
Try to read the next message from the queue without blocking.
msg | Pointer to the value to receive the message |
Implements mqtt::iasync_client.
|
inline |
Waits a limited time for a message to arrive.
msg | Pointer to the value to receive the message |
relTime | The maximum amount of time to wait for a message. |
|
inline |
Waits a limited time for a message to arrive.
relTime | The maximum amount of time to wait for a message. |
|
inline |
Waits until a specific time for a message to appear.
msg | Pointer to the value to receive the message |
absTime | The time point to wait until, before timing out. |
|
inline |
Waits until a specific time for a message to appear.
absTime | The time point to wait until, before timing out. |
|
friend |
Manage internal list of active tokens