Qpid Proton C++ API  0.38.0
connection_options

Options for creating a connection. More...

#include <connection_options.hpp>

Public Member Functions

 connection_options ()
 Create an empty set of options.
 
 connection_options (class messaging_handler &h)
 Shorthand for connection_options().handler(h).
 
 connection_options (const connection_options &)
 Copy options.
 
connection_optionsoperator= (const connection_options &)
 Copy options.
 
connection_optionshandler (class messaging_handler &)
 Set a connection handler. More...
 
connection_optionsmax_frame_size (uint32_t max)
 Set the maximum frame size. It is unlimited by default.
 
connection_optionsmax_sessions (uint16_t max)
 Set the maximum number of open sessions. The default is 32767.
 
connection_optionsidle_timeout (duration)
 Set the idle timeout. More...
 
connection_optionscontainer_id (const std::string &id)
 Set the container ID.
 
connection_optionsvirtual_host (const std::string &name)
 Set the virtual host name for the connection. More...
 
connection_optionsuser (const std::string &)
 Set the user name used to authenticate the connection. More...
 
connection_optionspassword (const std::string &)
 Set the password used to authenticate the connection. More...
 
connection_optionsssl_client_options (const class ssl_client_options &)
 Set SSL client options.
 
connection_optionsssl_server_options (const class ssl_server_options &)
 Set SSL server options.
 
connection_optionssasl_enabled (bool)
 Enable or disable SASL.
 
connection_optionssasl_allow_insecure_mechs (bool)
 Force the enabling of SASL mechanisms that disclose cleartext passwords over the connection. More...
 
connection_optionssasl_allowed_mechs (const std::string &)
 Specify the SASL mechanisms allowed for this connection. More...
 
connection_optionsoffered_capabilities (const std::vector< symbol > &)
 Unsettled API - Extension capabilities offered to the remote peer.
 
connection_optionsdesired_capabilities (const std::vector< symbol > &)
 Unsettled API - Extension capabilities desired from the remote peer.
 
connection_optionsproperties (const std::map< symbol, value > &)
 Unsettled API - Connection properties.
 
connection_optionssasl_config_name (const std::string &)
 Unsettled API - Set the SASL configuration name.
 
connection_optionssasl_config_path (const std::string &)
 Unsettled API - Set the SASL configuration path.
 
connection_optionsreconnect (const reconnect_options &)
 Unsettled API - Set reconnect timing options. More...
 
connection_optionsreconnect_url (const std::string &)
 Unsettled API - Set reconnect URL. More...
 
connection_optionsfailover_urls (const std::vector< std::string > &)
 Unsettled API - Set Fail-over URLs. More...
 
connection_optionsupdate (const connection_options &other)
 Update option values from values set in other.
 

Detailed Description

Options for creating a connection.

Options can be "chained" like this:

c = container.connect(url, connection_options().handler(h).max_frame_size(1234));
connection_options & handler(class messaging_handler &)
Set a connection handler.
connection_options()
Create an empty set of options.
connection_options & max_frame_size(uint32_t max)
Set the maximum frame size. It is unlimited by default.

You can also create an options object with common settings and use it as a base for different connections that have mostly the same settings:

opts.idle_timeout(1000).max_frame_size(10000);
c1 = container.connect(url1, opts.handler(h1));
c2 = container.connect(url2, opts.handler(h2));

Normal value semantics: copy or assign creates a separate copy of the options.

Examples
broker.cpp, multithreaded_client_flow_control.cpp, service_bus.cpp, simple_recv.cpp, and simple_send.cpp.

Member Function Documentation

◆ handler()

connection_options& handler ( class messaging_handler )

Set a connection handler.

The handler must not be deleted until messaging_handler::on_transport_close() is called.

Examples
broker.cpp.

◆ idle_timeout()

connection_options& idle_timeout ( duration  )

Set the idle timeout.

The default is no timeout.

If set, the local peer will disconnect if it receives no AMQP frames for an interval longer than duration. Also known as "heartbeating", this is a way to detect dead peers even in the presence of a live TCP connection.

◆ virtual_host()

connection_options& virtual_host ( const std::string &  name)

Set the virtual host name for the connection.

For client connections, it defaults to the host name used to set up the connection. For server connections, it is unset by default.

If making a client connection by SSL/TLS, this name is also used for certificate verification and Server Name Indication.

◆ user()

connection_options& user ( const std::string &  )

Set the user name used to authenticate the connection.

It is unset by default.

This value overrides any user name that is specified in the URL used for container::connect. It is ignored if the connection is created by container::listen because a listening connection's identity is provided by the remote client.

Examples
simple_recv.cpp, and simple_send.cpp.

◆ password()

connection_options& password ( const std::string &  )

Set the password used to authenticate the connection.

This value is ignored if the connection is created by container::listen.

Examples
simple_recv.cpp, and simple_send.cpp.

◆ sasl_allow_insecure_mechs()

connection_options& sasl_allow_insecure_mechs ( bool  )

Force the enabling of SASL mechanisms that disclose cleartext passwords over the connection.

By default, such mechanisms are disabled.

◆ sasl_allowed_mechs()

connection_options& sasl_allowed_mechs ( const std::string &  )

Specify the SASL mechanisms allowed for this connection.

The value is a space-separated list of mechanism names.

The mechanisms allowed by default are determined by your SASL library and system configuration, with two exceptions: GSSAPI and GSS-SPNEGO are disabled by default. To enable them, you must explicitly add them using this option.

Clients must set the allowed mechanisms before the the outgoing connection is attempted. Servers must set them before the listening connection is setup.

◆ reconnect()

connection_options& reconnect ( const reconnect_options )

Unsettled API - Set reconnect timing options.

If reconnect timing options are set, but no specific reconnect or failover urls are set then the original url used for the connection will be used as the reconnect url.

Examples
simple_send.cpp.

◆ reconnect_url()

connection_options& reconnect_url ( const std::string &  )

Unsettled API - Set reconnect URL.

If the connection to the primary connection url fails then try to reconnect using the reconnect url.

If this option is set then it will by default set the default reconnect timing options.

If this option is changed using connection::update_options before a reconnection attempt (for example in the messaging_handler::on_transport_error callback) then the new value of the reconnect url will be used for the reconnect attempt rather then any previous value.

If both the failover_urls and reconnect_url options are set then the behavior is not defined.

◆ failover_urls()

connection_options& failover_urls ( const std::vector< std::string > &  )

Unsettled API - Set Fail-over URLs.

If the connection to the primary connection url fails then try each of the fail-over connection urls in turn.

If this option is set then it will by default set the default reconnect timing options.

If this option is changed using connection::update_options before a reconnection attempt (for example in the messaging_handler::on_transport_error callback) then the new values of the failover urls will be used for the reconnect attempt rather then any previous value.

If both the failover_urls and reconnect_url options are set then the behavior is not defined.


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