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

#include <connect_options.h>

Public Types

using ptr_t = std::shared_ptr< connect_options >
 
using const_ptr_t = std::shared_ptr< const connect_options >
 

Public Member Functions

 connect_options (int ver=MQTTVERSION_DEFAULT)
 
 connect_options (string_ref userName, binary_ref password, int ver=MQTTVERSION_DEFAULT)
 
 connect_options (const connect_options &opt)
 
 connect_options (connect_options &&opt)
 
connect_optionsoperator= (const connect_options &opt)
 
connect_optionsoperator= (connect_options &&opt)
 
std::chrono::seconds get_keep_alive_interval () const
 
std::chrono::seconds get_connect_timeout () const
 
string get_user_name () const
 
binary_ref get_password () const
 
string get_password_str () const
 
int get_max_inflight () const
 
string get_will_topic () const
 
const_message_ptr get_will_message () const
 
const will_optionsget_will_options () const
 
const ssl_optionsget_ssl_options () const
 
void set_ssl (const ssl_options &ssl)
 
void set_ssl (ssl_options &&ssl)
 
bool is_clean_session () const
 
bool is_clean_start () const
 
token_ptr get_token () const
 
const_string_collection_ptr get_servers () const
 
int get_mqtt_version () const
 
bool get_automatic_reconnect () const
 
std::chrono::seconds get_min_retry_interval () const
 
std::chrono::seconds get_max_retry_interval () const
 
void set_clean_session (bool cleanSession)
 
void set_clean_start (bool cleanStart)
 
void set_keep_alive_interval (int keepAliveInterval)
 
template<class Rep , class Period >
void set_keep_alive_interval (const std::chrono::duration< Rep, Period > &interval)
 
void set_connect_timeout (int timeout)
 
template<class Rep , class Period >
void set_connect_timeout (const std::chrono::duration< Rep, Period > &timeout)
 
void set_user_name (string_ref userName)
 
void set_password (binary_ref password)
 
void set_max_inflight (int n)
 
void set_will (const will_options &will)
 
void set_will (will_options &&will)
 
void set_will_message (const message &msg)
 
void set_will_message (const_message_ptr msg)
 
void set_token (const token_ptr &tok)
 
void set_servers (const_string_collection_ptr serverURIs)
 
void set_mqtt_version (int mqttVersion)
 
void set_automatic_reconnect (bool on)
 
void set_automatic_reconnect (int minRetryInterval, int maxRetryInterval)
 
template<class Rep1 , class Period1 , class Rep2 , class Period2 >
void set_automatic_reconnect (const std::chrono::duration< Rep1, Period1 > &minRetryInterval, const std::chrono::duration< Rep2, Period2 > &maxRetryInterval)
 
const propertiesget_properties () const
 
propertiesget_properties ()
 
void set_properties (const properties &props)
 
void set_properties (properties &&props)
 
const name_value_collectionget_http_headers () const
 
void set_http_headers (const name_value_collection &httpHeaders)
 
void set_http_headers (name_value_collection &&httpHeaders)
 
string get_http_proxy () const
 
void set_http_proxy (const string &httpProxy)
 
string get_https_proxy () const
 
void set_https_proxy (const string &httpsProxy)
 

Static Public Member Functions

static connect_options v3 ()
 
static connect_options v5 ()
 
static connect_options ws ()
 
static connect_options v5_ws ()
 

Friends

class async_client
 

Detailed Description

Holds the set of options that control how the client connects to a server.

Member Typedef Documentation

◆ ptr_t

Smart/shared pointer to an object of this class.

◆ const_ptr_t

using mqtt::connect_options::const_ptr_t = std::shared_ptr<const connect_options>

Smart/shared pointer to a const object of this class.

Constructor & Destructor Documentation

◆ connect_options() [1/4]

mqtt::connect_options::connect_options ( int  ver = MQTTVERSION_DEFAULT)
explicit

Constructs a new object using the default values.

Parameters
verThe MQTT protocol version.

◆ connect_options() [2/4]

mqtt::connect_options::connect_options ( string_ref  userName,
binary_ref  password,
int  ver = MQTTVERSION_DEFAULT 
)

Constructs a new object using the specified user name and password.

Parameters
userNameThe name of the user for connecting to the server
passwordThe password for connecting to the server
verThe MQTT protocol version.

◆ connect_options() [3/4]

mqtt::connect_options::connect_options ( const connect_options opt)

Copy constructor.

Parameters
optAnother object to copy.

◆ connect_options() [4/4]

mqtt::connect_options::connect_options ( connect_options &&  opt)

Move constructor.

Parameters
optAnother object to move into this new one.

Member Function Documentation

◆ v3()

static connect_options mqtt::connect_options::v3 ( )
static

Creates default options for an MQTT v3.x connection.

Returns
Default options for an MQTT v3.x connection.

◆ v5()

static connect_options mqtt::connect_options::v5 ( )
static

Creates default options for an MQTT v5 connection.

Returns
Default options for an MQTT v5 connection.

◆ ws()

static connect_options mqtt::connect_options::ws ( )
inlinestatic

Creates default options for an MQTT v3.x connection using WebSockets.

The keepalive interval is set to 45 seconds to avoid webserver 60 second inactivity timeouts.

Returns
Default options for an MQTT v3.x connection using websockets.

◆ v5_ws()

static connect_options mqtt::connect_options::v5_ws ( )
inlinestatic

Creates default options for an MQTT v5 connection using WebSockets.

The keepalive interval is set to 45 seconds to avoid webserver 60 second inactivity timeouts.

Returns
Default options for an MQTT v5 connection using websockets.

◆ operator=() [1/2]

connect_options & mqtt::connect_options::operator= ( const connect_options opt)

Copy assignment.

Parameters
optAnother object to copy.

◆ operator=() [2/2]

connect_options & mqtt::connect_options::operator= ( connect_options &&  opt)

Move assignment.

Parameters
optAnother object to move into this new one.

◆ get_keep_alive_interval()

std::chrono::seconds mqtt::connect_options::get_keep_alive_interval ( ) const
inline

Expose the underlying C struct for the unit tests. Gets the "keep alive" interval.

Returns
The keep alive interval in seconds.

◆ get_connect_timeout()

std::chrono::seconds mqtt::connect_options::get_connect_timeout ( ) const
inline

Gets the connection timeout. This is the amount of time the underlying library will wait for a timeout before failing.

Returns
The connect timeout in seconds.

◆ get_user_name()

string mqtt::connect_options::get_user_name ( ) const
inline

Gets the user name to use for the connection.

Returns
The user name to use for the connection.

◆ get_password()

binary_ref mqtt::connect_options::get_password ( ) const
inline

Gets the password to use for the connection.

Returns
The password to use for the connection.

◆ get_password_str()

string mqtt::connect_options::get_password_str ( ) const
inline

Gets the password to use for the connection.

Returns
The password to use for the connection.

◆ get_max_inflight()

int mqtt::connect_options::get_max_inflight ( ) const
inline

Gets the maximum number of messages that can be in-flight simultaneously.

Returns
The maximum number of inflight messages.

◆ get_will_topic()

string mqtt::connect_options::get_will_topic ( ) const
inline

Gets the topic to be used for last will and testament (LWT).

Returns
The topic to be used for last will and testament (LWT).

◆ get_will_message()

const_message_ptr mqtt::connect_options::get_will_message ( ) const
inline

Gets the message to be sent as last will and testament (LWT).

Returns
The message to be sent as last will and testament (LWT).

◆ get_will_options()

const will_options & mqtt::connect_options::get_will_options ( ) const
inline

Get the LWT options to use for the connection.

Returns
The LWT options to use for the connection.

◆ get_ssl_options()

const ssl_options & mqtt::connect_options::get_ssl_options ( ) const
inline

Get the SSL options to use for the connection.

Returns
The SSL options to use for the connection.

◆ set_ssl() [1/2]

void mqtt::connect_options::set_ssl ( const ssl_options ssl)

Sets the SSL for the connection. These will only have an effect if compiled against the SSL version of the Paho C library, and using a secure connection, "ssl://" or "wss://".

Parameters
sslThe SSL options.

◆ set_ssl() [2/2]

void mqtt::connect_options::set_ssl ( ssl_options &&  ssl)

Sets the SSL for the connection. These will only have an effect if compiled against the SSL version of the Paho C library, and using a secure connection, "ssl://" or "wss://".

Parameters
sslThe SSL options.

◆ is_clean_session()

bool mqtt::connect_options::is_clean_session ( ) const
inline

Returns whether the server should remember state for the client across reconnects. This only applies to MQTT v3.x connections.

Returns
true if requesting a clean session, false if not.

◆ is_clean_start()

bool mqtt::connect_options::is_clean_start ( ) const
inline

Returns whether the server should remember state for the client across reconnects. This only applies to MQTT v5 connections.

Returns
true if requesting a clean start, false if not.

◆ get_token()

token_ptr mqtt::connect_options::get_token ( ) const
inline

Gets the token used as the callback context.

Returns
The delivery token used as the callback context.

◆ get_servers()

const_string_collection_ptr mqtt::connect_options::get_servers ( ) const
inline

Gets the list of servers to which the client will connect.

Returns
A collection of server URI's. Each entry should be of the form protocol://host:port where protocol must be tcp or ssl. For host, you can specify either an IP address or a domain name.

◆ get_mqtt_version()

int mqtt::connect_options::get_mqtt_version ( ) const
inline

Gets the version of MQTT to be used on the connect.

Returns
  • MQTTVERSION_DEFAULT (0) = default: start with 3.1.1, and if that fails, fall back to 3.1
  • MQTTVERSION_3_1 (3) = only try version 3.1
  • MQTTVERSION_3_1_1 (4) = only try version 3.1.1

◆ get_automatic_reconnect()

bool mqtt::connect_options::get_automatic_reconnect ( ) const
inline

Determines if the options have been configured for automatic reconnect.

Returns
true if configured for automatic reconnect, false if not.

◆ get_min_retry_interval()

std::chrono::seconds mqtt::connect_options::get_min_retry_interval ( ) const
inline

Gets the minimum retry interval for automatic reconnect.

Returns
The minimum retry interval for automatic reconnect, in seconds.

◆ get_max_retry_interval()

std::chrono::seconds mqtt::connect_options::get_max_retry_interval ( ) const
inline

Gets the maximum retry interval for automatic reconnect.

Returns
The maximum retry interval for automatic reconnect, in seconds.

◆ set_clean_session()

void mqtt::connect_options::set_clean_session ( bool  cleanSession)

Sets whether the server should remember state for the client across reconnects. (MQTT v3.x only)

This will only take effect if the version is already set to v3.x (not v5).

Parameters
cleantrue if the server should NOT remember state for the client across reconnects, false otherwise.

◆ set_clean_start()

void mqtt::connect_options::set_clean_start ( bool  cleanStart)

Sets whether the server should remember state for the client across reconnects. (MQTT v5 only)

If a persistent session is desired (turning this off), then the app should also set the Session Expiry Interval property, and add that to the connect options.

This will only take effect if the MQTT version is set to v5

Parameters
cleantrue if the server should NOT remember state for the client across reconnects, false otherwise.

◆ set_keep_alive_interval() [1/2]

void mqtt::connect_options::set_keep_alive_interval ( int  keepAliveInterval)
inline

Sets the "keep alive" interval. This is the maximum time that should pass without communications between client and server. If no messages pass in this time, the client will ping the broker.

Parameters
keepAliveIntervalThe keep alive interval in seconds.

◆ set_keep_alive_interval() [2/2]

template<class Rep , class Period >
void mqtt::connect_options::set_keep_alive_interval ( const std::chrono::duration< Rep, Period > &  interval)
inline

Sets the "keep alive" interval with a chrono duration. This is the maximum time that should pass without communications between client and server. If no messages pass in this time, the client will ping the broker.

Parameters
intervalThe keep alive interval.

◆ set_connect_timeout() [1/2]

void mqtt::connect_options::set_connect_timeout ( int  timeout)
inline

Sets the connect timeout in seconds. This is the maximum time that the underlying library will wait for a connection before failing.

Parameters
timeoutThe connect timeout in seconds.

◆ set_connect_timeout() [2/2]

template<class Rep , class Period >
void mqtt::connect_options::set_connect_timeout ( const std::chrono::duration< Rep, Period > &  timeout)
inline

Sets the connect timeout with a chrono duration. This is the maximum time that the underlying library will wait for a connection before failing.

Parameters
timeoutThe connect timeout in seconds.

◆ set_user_name()

void mqtt::connect_options::set_user_name ( string_ref  userName)

Sets the user name to use for the connection.

Parameters
userNameThe user name for connecting to the MQTT broker.

◆ set_password()

void mqtt::connect_options::set_password ( binary_ref  password)

Sets the password to use for the connection.

Parameters
passwordThe password for connecting to the MQTT broker.

◆ set_max_inflight()

void mqtt::connect_options::set_max_inflight ( int  n)
inline

Sets the maximum number of messages that can be in-flight simultaneously.

Parameters
nThe maximum number of inflight messages.

◆ set_will() [1/2]

void mqtt::connect_options::set_will ( const will_options will)

Sets the "Last Will and Testament" (LWT) for the connection.

Parameters
willThe LWT options.

◆ set_will() [2/2]

void mqtt::connect_options::set_will ( will_options &&  will)

Sets the "Last Will and Testament" (LWT) for the connection.

Parameters
willThe LWT options.

◆ set_will_message() [1/2]

void mqtt::connect_options::set_will_message ( const message msg)
inline

Sets the "Last Will and Testament" (LWT) as a message

Parameters
msgThe LWT message

◆ set_will_message() [2/2]

void mqtt::connect_options::set_will_message ( const_message_ptr  msg)
inline

Sets the "Last Will and Testament" (LWT) as a message

Parameters
msgPointer to a LWT message

◆ set_token()

void mqtt::connect_options::set_token ( const token_ptr tok)

Sets the callback context to a delivery token.

Parameters
tokThe delivery token to be used as the callback context.

◆ set_servers()

void mqtt::connect_options::set_servers ( const_string_collection_ptr  serverURIs)

Sets the list of servers to which the client will connect.

Parameters
serverURIsA pointer to a collection of server URI's. Each entry should be of the form protocol://host:port where protocol must be tcp or ssl. For host, you can specify either an IP address or a domain name.

◆ set_mqtt_version()

void mqtt::connect_options::set_mqtt_version ( int  mqttVersion)

Sets the version of MQTT to be used on the connect.

This will also set other connect options to legal values dependent on the selected version.

Parameters
mqttVersionThe MQTT version to use for the connection:
  • MQTTVERSION_DEFAULT (0) = default: start with 3.1.1, and if that fails, fall back to 3.1
  • MQTTVERSION_3_1 (3) = only try version 3.1
  • MQTTVERSION_3_1_1 (4) = only try version 3.1.1
  • MQTTVERSION_5 (5) = only try version 5
Deprecated:
It is preferable to create the options for the desired version rather than using this function to change the version after some parameters have already been set. If you do use this function, call it before setting any other version-specific options.
See also
connect_options::v5()

◆ set_automatic_reconnect() [1/3]

void mqtt::connect_options::set_automatic_reconnect ( bool  on)
inline

Enable or disable automatic reconnects. The retry intervals are not affected.

Parameters
onWhether to turn reconnects on or off

◆ set_automatic_reconnect() [2/3]

void mqtt::connect_options::set_automatic_reconnect ( int  minRetryInterval,
int  maxRetryInterval 
)

Enable or disable automatic reconnects.

Parameters
minRetryIntervalMinimum retry interval in seconds. Doubled on each failed retry.
maxRetryIntervalMaximum retry interval in seconds. The doubling stops here on failed retries.

◆ set_automatic_reconnect() [3/3]

template<class Rep1 , class Period1 , class Rep2 , class Period2 >
void mqtt::connect_options::set_automatic_reconnect ( const std::chrono::duration< Rep1, Period1 > &  minRetryInterval,
const std::chrono::duration< Rep2, Period2 > &  maxRetryInterval 
)
inline

Enable or disable automatic reconnects.

Parameters
minRetryIntervalMinimum retry interval. Doubled on each failed retry.
maxRetryIntervalMaximum retry interval. The doubling stops here on failed retries.

◆ get_properties() [1/2]

const properties & mqtt::connect_options::get_properties ( ) const
inline

Gets the connect properties.

Returns
A const reference to the properties for the connect.

◆ get_properties() [2/2]

properties & mqtt::connect_options::get_properties ( )
inline

Gets a mutable reference to the connect properties.

Returns
A reference to the properties for the connect.

◆ set_properties() [1/2]

void mqtt::connect_options::set_properties ( const properties props)

Sets the properties for the connect.

Parameters
propsThe properties to place into the message.

◆ set_properties() [2/2]

void mqtt::connect_options::set_properties ( properties &&  props)

Moves the properties for the connect.

Parameters
propsThe properties to move into the connect object.

◆ get_http_headers()

const name_value_collection & mqtt::connect_options::get_http_headers ( ) const
inline

Gets the HTTP headers

Returns
A const reference to the HTTP headers name/value collection.

◆ set_http_headers() [1/2]

void mqtt::connect_options::set_http_headers ( const name_value_collection httpHeaders)
inline

Sets the HTTP headers for the connection.

Parameters
httpHeadersThe header nam/value collection.

◆ set_http_headers() [2/2]

void mqtt::connect_options::set_http_headers ( name_value_collection &&  httpHeaders)
inline

Sets the HTTP headers for the connection.

Parameters
httpHeadersThe header nam/value collection.

◆ get_http_proxy()

string mqtt::connect_options::get_http_proxy ( ) const
inline

Gets the HTTP proxy setting.

Returns
The HTTP proxy setting. An empty string means no proxy.

◆ set_http_proxy()

void mqtt::connect_options::set_http_proxy ( const string httpProxy)

Sets the HTTP proxy setting.

Parameters
httpProxyThe HTTP proxy setting. An empty string means no proxy.

◆ get_https_proxy()

string mqtt::connect_options::get_https_proxy ( ) const
inline

Gets the secure HTTPS proxy setting.

Returns
The HTTPS proxy setting. An empty string means no proxy.

◆ set_https_proxy()

void mqtt::connect_options::set_https_proxy ( const string httpsProxy)

Sets the secure HTTPS proxy setting.

Parameters
httpsProxyThe HTTPS proxy setting. An empty string means no proxy.

Friends And Related Symbol Documentation

◆ async_client

friend class async_client
friend

The client has special access


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