blob: a4d35d53cdc5678e43758034110bac6c6d621503 [file] [log] [blame]
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
#include "./duration.hpp"
#include "./fwd.hpp"
#include "./internal/export.hpp"
#include "./internal/pn_unique_ptr.hpp"
#include "./symbol.hpp"
#include "./types_fwd.hpp"
#include <proton/type_compat.h>
#include <map>
#include <vector>
#include <string>
/// @file
/// @copybrief proton::connection_options
struct pn_connection_t;
struct pn_transport_t;
namespace proton {
/// Options for creating a connection.
/// Options can be "chained" like this:
/// @code
/// c = container.connect(url, connection_options().handler(h).max_frame_size(1234));
/// @endcode
/// 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:
/// @code
/// connection_options opts;
/// opts.idle_timeout(1000).max_frame_size(10000);
/// c1 = container.connect(url1, opts.handler(h1));
/// c2 = container.connect(url2, opts.handler(h2));
/// @endcode
/// Normal value semantics: copy or assign creates a separate copy of
/// the options.
class connection_options {
/// Create an empty set of options.
PN_CPP_EXTERN connection_options();
/// Shorthand for `connection_options().handler(h)`.
PN_CPP_EXTERN connection_options(class messaging_handler& h);
/// Copy options.
PN_CPP_EXTERN connection_options(const connection_options&);
PN_CPP_EXTERN ~connection_options();
/// Copy options.
PN_CPP_EXTERN connection_options& operator=(const connection_options&);
// XXX add C++11 move operations - Still relevant, and applies to all options
/// Set a connection handler.
/// The handler must not be deleted until
/// messaging_handler::on_transport_close() is called.
PN_CPP_EXTERN connection_options& handler(class messaging_handler&);
/// Set the maximum frame size. It is unlimited by default.
PN_CPP_EXTERN connection_options& max_frame_size(uint32_t max);
/// Set the maximum number of open sessions. The default is 32767.
PN_CPP_EXTERN connection_options& max_sessions(uint16_t max);
/// 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.
PN_CPP_EXTERN connection_options& idle_timeout(duration);
/// Set the container ID.
PN_CPP_EXTERN connection_options& container_id(const std::string& id);
/// 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.
PN_CPP_EXTERN connection_options& virtual_host(const std::string& name);
/// 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.
PN_CPP_EXTERN connection_options& user(const std::string&);
/// Set the password used to authenticate the connection.
/// This value is ignored if the connection is created by
/// `container::listen`.
PN_CPP_EXTERN connection_options& password(const std::string&);
/// Set SSL client options.
PN_CPP_EXTERN connection_options& ssl_client_options(const class ssl_client_options&);
/// Set SSL server options.
PN_CPP_EXTERN connection_options& ssl_server_options(const class ssl_server_options&);
/// Enable or disable SASL.
PN_CPP_EXTERN connection_options& sasl_enabled(bool);
/// Force the enabling of SASL mechanisms that disclose cleartext
/// passwords over the connection. By default, such mechanisms
/// are disabled.
PN_CPP_EXTERN connection_options& sasl_allow_insecure_mechs(bool);
/// 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.
PN_CPP_EXTERN connection_options& sasl_allowed_mechs(const std::string&);
/// **Unsettled API** - Extension capabilities offered to the remote peer.
PN_CPP_EXTERN connection_options& offered_capabilities(const std::vector<symbol>&);
/// **Unsettled API** - Extension capabilities desired from the remote peer.
PN_CPP_EXTERN connection_options& desired_capabilities(const std::vector<symbol>&);
/// **Unsettled API** - Connection properties.
PN_CPP_EXTERN connection_options& properties(const std::map<symbol, value>&);
/// **Unsettled API** - Set the SASL configuration name.
PN_CPP_EXTERN connection_options& sasl_config_name(const std::string&);
/// **Unsettled API** - Set the SASL configuration path.
PN_CPP_EXTERN connection_options& sasl_config_path(const std::string&);
/// **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.
PN_CPP_EXTERN connection_options& reconnect(const reconnect_options&);
/// **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 @ref connection::update_options before a reconnection
/// attempt (for example in the @ref 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.
PN_CPP_EXTERN connection_options& reconnect_url(const 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 both the failover_urls and reconnect_url options are set then the behavior is not defined.
PN_CPP_EXTERN connection_options& failover_urls(const std::vector<std::string>&);
/// Update option values from values set in other.
PN_CPP_EXTERN connection_options& update(const connection_options& other);
void apply_unbound(connection&) const;
void apply_reconnect_urls(pn_connection_t* pnc) const;
void apply_unbound_client(pn_transport_t*) const;
void apply_unbound_server(pn_transport_t*) const;
messaging_handler* handler() const;
class impl;
internal::pn_unique_ptr<impl> impl_;
/// @cond INTERNAL
friend class container;
friend class io::connection_driver;
friend class connection;
/// @endcond
} // proton