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

#include <async_client.h>

Inheritance diagram for mqtt::async_client:

Public Types
using	ptr_t = std::shared_ptr< async_client >
	Smart/shared pointer for an object of this class.

using	consumer_queue_type = std::unique_ptr< thread_queue< const_message_ptr >>
	Type for a thread-safe queue to consume messages synchronously.

Public Types inherited from mqtt::iasync_client
using	qos_collection = std::vector< int >
	Type for a collection of QOS values.

Public Member Functions
	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. More...

	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. More...

	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. More...

	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. More...

	~async_client () override
	Destructor.

token_ptr	connect () override
	Connects to an MQTT server using the default options. More...

token_ptr	connect (connect_options options) override
	Connects to an MQTT server using the provided connect options. More...

token_ptr	connect (connect_options options, void *userContext, iaction_listener &cb) override
	Connects to an MQTT server using the specified options. More...

token_ptr	connect (void *userContext, iaction_listener &cb) override

token_ptr	reconnect () override
	Reconnects the client using options from the previous connect. More...

token_ptr	disconnect () override
	Disconnects from the server. More...

token_ptr	disconnect (disconnect_options opts) override
	Disconnects from the server. More...

token_ptr	disconnect (int timeout) override
	Disconnects from the server. More...

template<class Rep , class Period >
token_ptr	disconnect (const std::chrono::duration< Rep, Period > &timeout)
	Disconnects from the server. More...

token_ptr	disconnect (int timeout, void *userContext, iaction_listener &cb) override
	Disconnects from the server. More...

template<class Rep , class Period >
token_ptr	disconnect (const std::chrono::duration< Rep, Period > &timeout, void *userContext, iaction_listener &cb)
	Disconnects from the server. More...

token_ptr	disconnect (void *userContext, iaction_listener &cb) override
	Disconnects from the server. More...

delivery_token_ptr	get_pending_delivery_token (int msgID) const override
	Returns the delivery token for the specified message ID. More...

std::vector< delivery_token_ptr >	get_pending_delivery_tokens () const override
	Returns the delivery tokens for any outstanding publish operations. More...

string	get_client_id () const override
	Returns the client ID used by this client. More...

string	get_server_uri () const override
	Returns the address of the server used by this client. More...

bool	is_connected () const override
	Determines if this client is currently connected to the server. More...

delivery_token_ptr	publish (string_ref topic, const void *payload, size_t n, int qos, bool retained) override
	Publishes a message to a topic on the server. More...

delivery_token_ptr	publish (string_ref topic, const void *payload, size_t n) override
	Publishes a message to a topic on the server. More...

delivery_token_ptr	publish (string_ref topic, binary_ref payload, int qos, bool retained) override
	Publishes a message to a topic on the server. More...

delivery_token_ptr	publish (string_ref topic, binary_ref payload) override
	Publishes a message to a topic on the server. More...

delivery_token_ptr	publish (string_ref topic, const void payload, size_t n, int qos, bool retained, void userContext, iaction_listener &cb) override
	Publishes a message to a topic on the server. More...

delivery_token_ptr	publish (const_message_ptr msg) override
	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. More...

delivery_token_ptr	publish (const_message_ptr msg, void *userContext, iaction_listener &cb) override
	Publishes a message to a topic on the server. More...

void	set_callback (callback &cb) override
	Sets a callback listener to use for events that happen asynchronously. More...

void	disable_callbacks () override
	Stops callbacks. More...

token_ptr	subscribe (const_string_collection_ptr topicFilters, const qos_collection &qos) override
	Subscribe to multiple topics, each of which may include wildcards. More...

token_ptr	subscribe (const_string_collection_ptr topicFilters, const qos_collection &qos, void *userContext, iaction_listener &cb) override
	Subscribes to multiple topics, each of which may include wildcards. More...

token_ptr	subscribe (const string &topicFilter, int qos) override
	Subscribe to a topic, which may include wildcards. More...

token_ptr	subscribe (const string &topicFilter, int qos, void *userContext, iaction_listener &cb) override
	Subscribe to a topic, which may include wildcards. More...

token_ptr	unsubscribe (const string &topicFilter) override
	Requests the server unsubscribe the client from a topic. More...

token_ptr	unsubscribe (const_string_collection_ptr topicFilters) override
	Requests the server unsubscribe the client from one or more topics. More...

token_ptr	unsubscribe (const_string_collection_ptr topicFilters, void *userContext, iaction_listener &cb) override
	Requests the server unsubscribe the client from one or more topics. More...

token_ptr	unsubscribe (const string &topicFilter, void *userContext, iaction_listener &cb) override
	Requests the server unsubscribe the client from a topics. More...

void	start_consuming ()
	Start consuming messages. More...

void	stop_consuming ()
	Stop consuming messages. More...

const_message_ptr	consume_message ()
	Read the next message from the queue. More...

bool	try_consume_message (const_message_ptr *msg)
	Try to read the next message from the queue without blocking. More...

template<typename Rep , class Period >
bool	try_consume_message_for (const_message_ptr *msg, const std::chrono::duration< Rep, Period > &relTime)
	Waits a limited time for a message to arrive. More...

template<class Clock , class Duration >
bool	try_consume_message_until (const_message_ptr *msg, const std::chrono::time_point< Clock, Duration > &absTime)
	Waits until a specific time for a message to occur. More...

Public Member Functions inherited from mqtt::iasync_client
virtual	~iasync_client ()
	Virtual destructor.

Friends
class	token
	Manage internal list of active tokens.

Detailed Description

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

Constructor & Destructor Documentation

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.

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
persistDir	The directory to use for persistence data

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.

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 user persistence structure. If this is null, then no persistence is used.

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.

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
persistDir	The directory to use for persistence data

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.

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 user persistence structure. If this is null, then no persistence is used.

Member Function Documentation

token_ptr mqtt::async_client::connect ( )

overridevirtual

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.

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

overridevirtual

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.

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

overridevirtual

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.

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

inlineoverridevirtual

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.

const_message_ptr mqtt::async_client::consume_message ( )

inline

Read the next message from the queue.

This blocks until a new message arrives.

Returns: The message and topic.

void mqtt::async_client::disable_callbacks ( )

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.

token_ptr mqtt::async_client::disconnect ( )

inlineoverridevirtual

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.

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

overridevirtual

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.

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

overridevirtual

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.

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

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

overridevirtual

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.

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

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

inlineoverridevirtual

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.

string mqtt::async_client::get_client_id ( ) const

inlineoverridevirtual

Returns the client ID used by this client.

Returns: The client ID used by this client.

Implements mqtt::iasync_client.

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

overridevirtual

Returns the delivery token for the specified message ID.

Returns: delivery_token

Implements mqtt::iasync_client.

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

overridevirtual

Returns the delivery tokens for any outstanding publish operations.

Returns: delivery_token[]

Implements mqtt::iasync_client.

string mqtt::async_client::get_server_uri ( ) const

inlineoverridevirtual

Returns the address of the server used by this client.

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

Implements mqtt::iasync_client.

bool mqtt::async_client::is_connected ( ) const

inlineoverridevirtual

Determines if this client is currently connected to the server.

Returns: true if connected, false otherwise.

Implements mqtt::iasync_client.

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

overridevirtual

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.

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

inlineoverridevirtual

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.

delivery_token_ptr mqtt::async_client::publish	(	string_ref	topic,
		binary_ref	payload,
		int	qos,
		bool	retained
	)

overridevirtual

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.

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

inlineoverridevirtual

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.

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
	)

overridevirtual

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

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.

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

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.

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.

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

overridevirtual

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.

token_ptr mqtt::async_client::reconnect ( )

overridevirtual

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.

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

overridevirtual

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.

void mqtt::async_client::start_consuming ( )

Start consuming messages.

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

void mqtt::async_client::stop_consuming ( )

Stop consuming messages.

This shuts down the internal callback and discards any unread messages.

token_ptr mqtt::async_client::subscribe	(	const_string_collection_ptr	topicFilters,
		const qos_collection &	qos
	)

overridevirtual

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

Parameters

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.

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.

token_ptr mqtt::async_client::subscribe	(	const_string_collection_ptr	topicFilters,
		const qos_collection &	qos,
		void *	userContext,
		iaction_listener &	cb
	)

overridevirtual

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

Parameters

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

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.

token_ptr mqtt::async_client::subscribe	(	const string &	topicFilter,
		int	qos
	)

overridevirtual

Subscribe to a topic, which may include wildcards.

Parameters

topicFilter	the topic to subscribe to, which can include wildcards.
qos

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.

token_ptr mqtt::async_client::subscribe	(	const string &	topicFilter,
		int	qos,
		void *	userContext,
		iaction_listener &	cb
	)

overridevirtual

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

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.

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

inline

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.

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.

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 occur.

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.

token_ptr mqtt::async_client::unsubscribe ( const string & topicFilter )

overridevirtual

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.

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.

token_ptr mqtt::async_client::unsubscribe ( const_string_collection_ptr topicFilters )

overridevirtual

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.

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.

token_ptr mqtt::async_client::unsubscribe	(	const_string_collection_ptr	topicFilters,
		void *	userContext,
		iaction_listener &	cb
	)

overridevirtual

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

Parameters

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

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.

token_ptr mqtt::async_client::unsubscribe	(	const string &	topicFilter,
		void *	userContext,
		iaction_listener &	cb
	)

overridevirtual

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

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.

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

src/mqtt/async_client.h

Public Types

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation