paho-mqtt-cpp
MQTT C++ Client for POSIX and Windows
Loading...
Searching...
No Matches
Public Types | Public Member Functions
mqtt::client Class Reference

#include <client.h>

Inheritance diagram for mqtt::client:
mqtt::callback

Public Types

using ptr_t = std::shared_ptr< client >
 
using qos_collection = async_client::qos_collection
 
using update_connection_handler = async_client::update_connection_handler
 

Public Member Functions

 client (const string &serverURI, const string &clientId, iclient_persistence *persistence=nullptr)
 
 client (const string &serverURI, const string &clientId, const string &persistDir)
 
 client (const string &serverURI, const string &clientId, int maxBufferedMessages, iclient_persistence *persistence=nullptr)
 
 client (const string &serverURI, const string &clientId, int maxBufferedMessages, const string &persistDir)
 
 client (const string &serverURI, const string &clientId, const create_options &opts, iclient_persistence *persistence=nullptr)
 
virtual ~client ()
 
virtual connect_response connect ()
 
virtual connect_response connect (connect_options opts)
 
virtual connect_response reconnect ()
 
virtual void disconnect ()
 
virtual void disconnect (int timeoutMS)
 
template<class Rep , class Period >
void disconnect (const std::chrono::duration< Rep, Period > &to)
 
virtual string get_client_id () const
 
virtual string get_server_uri () const
 
virtual std::chrono::milliseconds get_timeout () const
 
virtual topic get_topic (const string &top, int qos=message::DFLT_QOS, bool retained=message::DFLT_RETAINED)
 
virtual bool is_connected () const
 
void set_update_connection_handler (update_connection_handler cb)
 
virtual void publish (string_ref top, const void *payload, size_t n, int qos, bool retained)
 
virtual void publish (string_ref top, const void *payload, size_t n)
 
virtual void publish (const_message_ptr msg)
 
virtual void publish (const message &msg)
 
virtual void set_callback (callback &cb)
 
virtual void set_timeout (int timeoutMS)
 
template<class Rep , class Period >
void set_timeout (const std::chrono::duration< Rep, Period > &to)
 
virtual subscribe_response subscribe (const string &topicFilter, const subscribe_options &opts=subscribe_options(), const properties &props=properties())
 
virtual subscribe_response subscribe (const string &topicFilter, int qos, const subscribe_options &opts=subscribe_options(), const properties &props=properties())
 
virtual subscribe_response subscribe (const string_collection &topicFilters, const std::vector< subscribe_options > &opts=std::vector< subscribe_options >(), const properties &props=properties())
 
virtual subscribe_response subscribe (const string_collection &topicFilters, const qos_collection &qos, const std::vector< subscribe_options > &opts=std::vector< subscribe_options >(), const properties &props=properties())
 
virtual unsubscribe_response unsubscribe (const string &topicFilter, const properties &props=properties())
 
virtual unsubscribe_response unsubscribe (const string_collection &topicFilters, const properties &props=properties())
 
virtual void start_consuming ()
 
virtual void stop_consuming ()
 
virtual const_message_ptr consume_message ()
 
virtual bool try_consume_message (const_message_ptr *msg)
 
template<typename Rep , class Period >
bool try_consume_message_for (const_message_ptr *msg, 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)
 

Detailed Description

Lightweight client for talking to an MQTT server using methods that block until an operation completes.

Member Typedef Documentation

◆ ptr_t

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

Smart pointer type for this object

◆ qos_collection

Type for a collection of QOS values

◆ update_connection_handler

Handler for updating connection data before an auto-reconnect.

Constructor & Destructor Documentation

◆ client() [1/5]

mqtt::client::client ( const string serverURI,
const string clientId,
iclient_persistence persistence = nullptr 
)

Create a 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
serverURIthe address of the server to connect to, specified as a URI.
clientIda client identifier that is unique on the server being connected to
persistenceThe user persistence structure. If this is null, then no persistence is used.

◆ client() [2/5]

mqtt::client::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
serverURIthe address of the server to connect to, specified as a URI.
clientIda client identifier that is unique on the server being connected to
persistDirThe directory to use for persistence data

◆ client() [3/5]

mqtt::client::client ( const string serverURI,
const string clientId,
int  maxBufferedMessages,
iclient_persistence persistence = nullptr 
)

Create a 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
serverURIthe address of the server to connect to, specified as a URI.
clientIda client identifier that is unique on the server being connected to
maxBufferedMessagesthe maximum number of messages allowed to be buffered while not connected
persistenceThe user persistence structure. If this is null, then no persistence is used.

◆ client() [4/5]

mqtt::client::client ( const string serverURI,
const string clientId,
int  maxBufferedMessages,
const string persistDir 
)

Create a 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
serverURIthe address of the server to connect to, specified as a URI.
clientIda client identifier that is unique on the server being connected to
maxBufferedMessagesthe maximum number of messages allowed to be buffered while not connected
persistDirThe directory to use for persistence data

◆ client() [5/5]

mqtt::client::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.

Parameters
serverURIthe address of the server to connect to, specified as a URI.
clientIda client identifier that is unique on the server being connected to
optsThe create options
persistenceThe user persistence structure. If this is null, then no persistence is used.

◆ ~client()

virtual mqtt::client::~client ( )
inlinevirtual

Virtual destructor

Member Function Documentation

◆ connect() [1/2]

virtual connect_response mqtt::client::connect ( )
virtual

Connects to an MQTT server using the default options.

◆ connect() [2/2]

virtual connect_response mqtt::client::connect ( connect_options  opts)
virtual

Connects to an MQTT server using the specified options.

Parameters
opts

◆ reconnect()

virtual connect_response mqtt::client::reconnect ( )
virtual

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

◆ disconnect() [1/3]

virtual void mqtt::client::disconnect ( )
virtual

Disconnects from the server.

◆ disconnect() [2/3]

virtual void mqtt::client::disconnect ( int  timeoutMS)
virtual

Disconnects from the server.

Parameters
timeoutMSthe 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.

◆ disconnect() [3/3]

template<class Rep , class Period >
void mqtt::client::disconnect ( const std::chrono::duration< Rep, Period > &  to)
inline

Disconnects from the server.

Parameters
tothe 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.

◆ get_client_id()

virtual string mqtt::client::get_client_id ( ) const
inlinevirtual

Gets the client ID used by this client.

Returns
The client ID used by this client.

◆ get_server_uri()

virtual string mqtt::client::get_server_uri ( ) const
inlinevirtual

Gets the address of the server used by this client.

Returns
The address of the server used by this client, as a URI.

◆ get_timeout()

virtual std::chrono::milliseconds mqtt::client::get_timeout ( ) const
inlinevirtual

Return the maximum time to wait for an action to complete.

Returns
int

◆ get_topic()

virtual topic mqtt::client::get_topic ( const string top,
int  qos = message::DFLT_QOS,
bool  retained = message::DFLT_RETAINED 
)
inlinevirtual

Get a topic object which can be used to publish messages on this client.

Parameters
topThe topic name
qosThe Quality of Service for the topic
retainedWhether the published messages set the retain flag.
Returns
A topic attached to this client.

◆ is_connected()

virtual bool mqtt::client::is_connected ( ) const
inlinevirtual

Determines if this client is currently connected to the server.

Returns
true if the client is currently connected, false if not.

◆ set_update_connection_handler()

void mqtt::client::set_update_connection_handler ( update_connection_handler  cb)
inline

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

Parameters
cbThe callback functor to register with the library.

◆ publish() [1/4]

virtual void mqtt::client::publish ( string_ref  top,
const void *  payload,
size_t  n,
int  qos,
bool  retained 
)
inlinevirtual

Publishes a message to a topic on the server and return once it is delivered.

Parameters
topThe topic to publish
payloadThe data to publish
nThe size in bytes of the data
qosThe QoS for message delivery
retainedWhether the broker should retain the message

◆ publish() [2/4]

virtual void mqtt::client::publish ( string_ref  top,
const void *  payload,
size_t  n 
)
inlinevirtual

Publishes a message to a topic on the server and return once it is delivered.

Parameters
topThe topic to publish
payloadThe data to publish
nThe size in bytes of the data

◆ publish() [3/4]

virtual void mqtt::client::publish ( const_message_ptr  msg)
inlinevirtual

Publishes a message to a topic on the server.

Parameters
msgThe message

◆ publish() [4/4]

virtual void mqtt::client::publish ( const message msg)
inlinevirtual

Publishes a message to a topic on the server. This version will not timeout since that could leave the library with a reference to memory that could disappear while the library is still using it.

Parameters
msgThe message

◆ set_callback()

virtual void mqtt::client::set_callback ( callback cb)
virtual

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

Parameters
cbThe callback functions

◆ set_timeout() [1/2]

virtual void mqtt::client::set_timeout ( int  timeoutMS)
inlinevirtual

Set the maximum time to wait for an action to complete.

Parameters
timeoutMSThe timeout in milliseconds

◆ set_timeout() [2/2]

template<class Rep , class Period >
void mqtt::client::set_timeout ( const std::chrono::duration< Rep, Period > &  to)
inline

Set the maximum time to wait for an action to complete.

Parameters
toThe timeout as a std::chrono duration.

◆ subscribe() [1/4]

virtual subscribe_response mqtt::client::subscribe ( const string topicFilter,
const subscribe_options opts = subscribe_options(),
const properties props = properties() 
)
virtual

Subscribe to a topic, which may include wildcards using a QoS of 1.

Parameters
topicFilter
propsThe MQTT v5 properties.
optsThe MQTT v5 subscribe options for the topic
Returns
The "subscribe" response from the server.

◆ subscribe() [2/4]

virtual subscribe_response mqtt::client::subscribe ( const string topicFilter,
int  qos,
const subscribe_options opts = subscribe_options(),
const properties props = properties() 
)
virtual

Subscribe to a topic, which may include wildcards.

Parameters
topicFilterA single topic to subscribe
qosThe QoS of the subscription
optsThe MQTT v5 subscribe options for the topic
propsThe MQTT v5 properties.
Returns
The "subscribe" response from the server.

◆ subscribe() [3/4]

virtual subscribe_response mqtt::client::subscribe ( const string_collection topicFilters,
const std::vector< subscribe_options > &  opts = std::vector< subscribe_options >(),
const properties props = properties() 
)
virtual

Subscribes to a one or more topics, which may include wildcards using a QoS of 1.

Parameters
topicFiltersA set of topics to subscribe
optsThe MQTT v5 subscribe options (one for each topic)
propsThe MQTT v5 properties.
Returns
The "subscribe" response from the server.

◆ subscribe() [4/4]

virtual subscribe_response mqtt::client::subscribe ( const string_collection topicFilters,
const qos_collection qos,
const std::vector< subscribe_options > &  opts = std::vector< subscribe_options >(),
const properties props = properties() 
)
virtual

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

Parameters
topicFiltersA collection of topics to subscribe
qosA collection of QoS for each topic
optsThe MQTT v5 subscribe options (one for each topic)
propsThe MQTT v5 properties.
Returns
The "subscribe" response from the server.

◆ unsubscribe() [1/2]

virtual unsubscribe_response mqtt::client::unsubscribe ( const string topicFilter,
const properties props = properties() 
)
virtual

Requests the server unsubscribe the client from a topic.

Parameters
topicFilterA single topic to unsubscribe.
propsThe MQTT v5 properties.
Returns
The "unsubscribe" response from the server.

◆ unsubscribe() [2/2]

virtual unsubscribe_response mqtt::client::unsubscribe ( const string_collection topicFilters,
const properties props = properties() 
)
virtual

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

Parameters
topicFiltersA collection of topics to unsubscribe.
propsThe MQTT v5 properties.
Returns
The "unsubscribe" response from the server.

◆ start_consuming()

virtual void mqtt::client::start_consuming ( )
inlinevirtual

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

◆ stop_consuming()

virtual void mqtt::client::stop_consuming ( )
inlinevirtual

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

◆ consume_message()

virtual const_message_ptr mqtt::client::consume_message ( )
inlinevirtual

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

Returns
The message and topic.

◆ try_consume_message()

virtual bool mqtt::client::try_consume_message ( const_message_ptr msg)
inlinevirtual

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

Parameters
msgPointer to the value to receive the message
Returns
true is a message was read, false if no message was available.

◆ try_consume_message_for()

template<typename Rep , class Period >
bool mqtt::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
msgPointer to the value to receive the message
relTimeThe maximum amount of time to wait for a message.
Returns
true if a message was read, false if a timeout occurred.

◆ try_consume_message_until()

template<class Clock , class Duration >
bool mqtt::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
msgPointer to the value to receive the message
absTimeThe time point to wait until, before timing out.
Returns
true if a message was read, false if a timeout occurred.

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