Loading...
Searching...
No Matches
mqtt::iasync_client Class Referenceabstract

`#include <iasync_client.h>`

Inheritance diagram for mqtt::iasync_client:

## Public Types

using | qos_collection = std::vector<int>

## Public Member Functions

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, const properties &props=properties())=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, const properties &props=properties())=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 void | clear_consumer ()
virtual bool | consumer_closed () noexcept
virtual bool | consumer_done () noexcept
virtual std::size_t | consumer_queue_size () const
virtual const_message_ptr | consume_message ()=0
virtual bool | try_consume_message (const_message_ptr *msg)=0
virtual event | consume_event ()
virtual bool | try_consume_event (event *evt)

## Friends

class | token

## Detailed Description

Enables an application to communicate with an MQTT server using non-blocking methods.

It provides applications a simple programming interface to all features of the MQTT version 3.1 specification including:

- connect
- publish
- subscribe
- unsubscribe
- disconnect

## Member Typedef Documentation

## qos_collection

using mqtt::iasync_client::qos_collection = std::vector<int>

Type for a collection of QOS values

## Constructor & Destructor Documentation

## ~iasync_client()

virtual mqtt::iasync_client::~iasync_client | ( |  | ) |

inline virtual

Virtual destructor

## Member Function Documentation

## connect() [1/4]

virtual token_ptr mqtt::iasync_client::connect | ( |  | ) |

pure 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

Implemented in mqtt::async_client.

## connect() [2/4]

virtual token_ptr mqtt::iasync_client::connect | ( | connect_options | options | ) |

pure 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

Implemented in mqtt::async_client.

## connect() [3/4]

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

pure 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

Implemented in mqtt::async_client.

## connect() [4/4]

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

pure virtual

Parameters

  userContext | optional object used to pass context to the callback. Use nullptr if not required.
  cb | 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

Implemented in mqtt::async_client.

## reconnect()

virtual token_ptr mqtt::iasync_client::reconnect | ( |  | ) |

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

Implemented in mqtt::async_client.

## disconnect() [1/5]

virtual token_ptr mqtt::iasync_client::disconnect | ( |  | ) |

pure 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

Implemented in mqtt::async_client.

## disconnect() [2/5]

virtual token_ptr mqtt::iasync_client::disconnect | ( | disconnect_options | opts | ) |

pure 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

Implemented in mqtt::async_client.

## disconnect() [3/5]

virtual token_ptr mqtt::iasync_client::disconnect | ( | int | timeout | ) |

pure 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 the disconnect to complete. The token will be passed to any callback that has been set.

Exceptions

  exception | for problems encountered while disconnecting

Implemented in mqtt::async_client.

## disconnect() [4/5]

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

pure 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 | listener that will be notified when the disconnect completes.

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

Implemented in mqtt::async_client.

## disconnect() [5/5]

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

pure virtual

Disconnects from the server.

Parameters

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

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

Implemented in mqtt::async_client.

## get_pending_delivery_token()

virtual delivery_token_ptr mqtt::iasync_client::get_pending_delivery_token | ( | int | msgID | ) | const

pure virtual

Returns the delivery token for the specified message ID.

Returns
  delivery_token

Implemented in mqtt::async_client.

## get_pending_delivery_tokens()

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

pure virtual

Returns the delivery tokens for any outstanding publish operations.

Returns
  delivery_token[]

Implemented in mqtt::async_client.

## get_client_id()

virtual string mqtt::iasync_client::get_client_id | ( |  | ) | const

pure virtual

Returns the client ID used by this client.

Returns
  string

Implemented in mqtt::async_client.

## get_server_uri()

virtual string mqtt::iasync_client::get_server_uri | ( |  | ) | const

pure virtual

Returns the address of the server used by this client.

Implemented in mqtt::async_client.

## is_connected()

virtual bool mqtt::iasync_client::is_connected | ( |  | ) | const

pure virtual

Determines if this client is currently connected to the server.

Implemented in mqtt::async_client.

## publish() [1/7]

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

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

Implemented in mqtt::async_client.

## publish() [2/7]

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

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

Implemented in mqtt::async_client.

## publish() [3/7]

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

pure 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 | The 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.

Implemented in mqtt::async_client.

## publish() [4/7]

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

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

Implemented in mqtt::async_client.

## publish() [5/7]

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

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

Implemented in mqtt::async_client.

## publish() [6/7]

virtual delivery_token_ptr mqtt::iasync_client::publish | ( | const_message_ptr | msg | ) |

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

Implemented in mqtt::async_client.

## publish() [7/7]

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

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

Implemented in mqtt::async_client.

## set_callback()

virtual void mqtt::iasync_client::set_callback | ( | callback & | cb | ) |

pure virtual

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

Parameters

  cb | callback which will be invoked for certain asynchronous events

Implemented in mqtt::async_client.

## disable_callbacks()

virtual void mqtt::iasync_client::disable_callbacks | ( |  | ) |

pure virtual

Stops the callbacks.

Implemented in mqtt::async_client.

## subscribe() [1/4]

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

pure 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.
  opts | The options for the subscription.
  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.

Implemented in mqtt::async_client.

## subscribe() [2/4]

virtual token_ptr mqtt::iasync_client::subscribe | ( | const string & | topicFilter,
|  | int | qos,
|  | void * | userContext,
|  | iaction_listener & | callback,
|  | const subscribe_options & | opts = subscribe_options(),
|  | const properties & | props = properties() )

pure 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.
  callback | listener that will be notified when subscribe has completed
  opts | The options for the subscription.
  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.

Implemented in mqtt::async_client.

## subscribe() [3/4]

virtual token_ptr mqtt::iasync_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() )

pure virtual

Subscribe to multiple topics, each of which may include wildcards. Provides an optimized way to subscribe to multiple topics compared to subscribing to each one individually.

Parameters

  topicFilters | one or more topics 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.
  opts | A collection of subscription 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.

Implemented in mqtt::async_client.

## subscribe() [4/4]

virtual token_ptr mqtt::iasync_client::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() )

pure virtual

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

Parameters

  topicFilters | one or more topics 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.
  callback | listener that will be notified when subscribe has completed
  opts | A collection of subscription 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.

Implemented in mqtt::async_client.

## unsubscribe() [1/4]

virtual token_ptr mqtt::iasync_client::unsubscribe | ( | const string & | topicFilter,
|  | const properties & | props = properties() )

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

Implemented in mqtt::async_client.

## unsubscribe() [2/4]

virtual token_ptr mqtt::iasync_client::unsubscribe | ( | const_string_collection_ptr | topicFilters,
|  | const properties & | props = properties() )

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

Implemented in mqtt::async_client.

## unsubscribe() [3/4]

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

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

Implemented in mqtt::async_client.

## unsubscribe() [4/4]

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

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

Implemented in mqtt::async_client.

## start_consuming()

virtual void mqtt::iasync_client::start_consuming | ( |  | ) |

pure virtual

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

Implemented in mqtt::async_client.

## stop_consuming()

virtual void mqtt::iasync_client::stop_consuming | ( |  | ) |

pure virtual

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

Implemented in mqtt::async_client.

## clear_consumer()

virtual void mqtt::iasync_client::clear_consumer | ( |  | ) |

inline virtual

This clears the consumer queue, discarding any pending event.

Reimplemented in mqtt::async_client.

## consumer_closed()

virtual bool mqtt::iasync_client::consumer_closed | ( |  | ) |

inline 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 in mqtt::async_client.

## consumer_done()

virtual bool mqtt::iasync_client::consumer_done | ( |  | ) |

inline 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 from the queue.

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

Reimplemented in mqtt::async_client.

## consumer_queue_size()

virtual std::size_t mqtt::iasync_client::consumer_queue_size | ( |  | ) | const

inline 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 in mqtt::async_client.

## consume_message()

virtual const_message_ptr mqtt::iasync_client::consume_message | ( |  | ) |

pure virtual

Read the next message from the queue. This blocks until a new message arrives.

Returns
  The message and topic.

Implemented in mqtt::async_client.

## try_consume_message()

virtual bool mqtt::iasync_client::try_consume_message | ( | const_message_ptr * | msg | ) |

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

Implemented in mqtt::async_client.

## consume_event()

virtual event mqtt::iasync_client::consume_event | ( |  | ) |

inline virtual

Read the next event from the queue. This blocks until a new message arrives.

Returns
  The message and topic.

Reimplemented in mqtt::async_client.

## try_consume_event()

virtual bool mqtt::iasync_client::try_consume_event | ( | event * | evt | ) |

inline virtual

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

Parameters

  evt | Pointer to the value to receive the event

Returns
  true is an event was received, false if no event was available.

Reimplemented in mqtt::async_client.

## Friends And Related Symbol Documentation

## token

friend class token

friend

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

- iasync_client.h