Repository: qpid-proton Updated Branches: refs/heads/master 6e3d6ec92 -> 72b5f9532
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/session.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/session.hpp b/proton-c/bindings/cpp/include/proton/session.hpp index e88273e..a16fbe3 100644 --- a/proton-c/bindings/cpp/include/proton/session.hpp +++ b/proton-c/bindings/cpp/include/proton/session.hpp @@ -21,6 +21,7 @@ * under the License. * */ + #include "proton/export.hpp" #include "proton/endpoint.hpp" #include "proton/link.hpp" @@ -37,58 +38,73 @@ namespace proton { class container; class handler; -/** A session is a collection of links */ +/// A container of links. class session : public object<pn_session_t>, public endpoint { public: + /// @cond INTERNAL session(pn_session_t* s=0) : object<pn_session_t>(s) {} + /// @endcond - /* Endpoint behaviours */ + // Endpoint behaviours + /// Get the state of this session. PN_CPP_EXTERN endpoint::state state() const; + PN_CPP_EXTERN condition local_condition() const; PN_CPP_EXTERN condition remote_condition() const; - /** Initiate local open, not complete till messaging_handler::on_session_opened() - * or proton_handler::on_session_remote_open() - */ + /// @cond INTERNAL + /// XXX needs to take connection options + /// Initiate local open. The operation is not complete till + /// handler::on_session_open(). PN_CPP_EXTERN void open(); - - /** Initiate local close, not complete till messaging_handler::on_session_closed() - * or proton_handler::on_session_remote_close() - */ + /// @endcond + + /// Initiate local close. The operation is not complete till + /// handler::on_session_close(). PN_CPP_EXTERN void close(); - /// Get connection + /// Get the connection this session belongs to. PN_CPP_EXTERN class connection connection() const; - /** An un-opened receiver link, you can set link properties before calling open(). - * - *@param name if specified must be unique, by default the container generates a name - * of the form: <hex-digits> + "@" + container.id() - */ + /// @cond INTERNAL + /// XXX consider removing + + /// An unopened receiver link, you can set link properties before calling open(). + /// + /// @param name if specified must be unique, by default the + /// container generates a name of the form: <hex-digits> + "@" + + /// container.id() PN_CPP_EXTERN receiver create_receiver(const std::string& name=""); - /** An un-opened sender link, you can set link properties before calling open(). - * - *@param name if specified must be unique, by default the container generates a name - * of the form: <hex-digits> + "@" + container.id() - */ + /// An unopened sender link, you can set link properties before calling open(). + /// + /// @param name if specified must be unique, by default the + /// container generates a name of the form: <hex-digits> + "@" + + /// container.id() PN_CPP_EXTERN sender create_sender(const std::string& name=""); - /** Create and open a sender with target=addr and optional link options opts*/ + /// @endcond + + /// Open a sender for `addr`. PN_CPP_EXTERN sender open_sender(const std::string &addr, const link_options &opts = link_options()); - /** Create and open a receiver with target=addr and optional link options opts */ + /// Open a receiver for `addr`. PN_CPP_EXTERN receiver open_receiver(const std::string &addr, const link_options &opts = link_options()); - /** Navigate the sessions in a connection - get next session with endpoint state*/ + /// @cond INTERNAL + /// XXX is this or should this be obviated by find functions? + /// Navigate the sessions in a connection - get next session with endpoint state PN_CPP_EXTERN session next(endpoint::state) const; + /// @endcond - /** Return the links on this session matching the state mask. */ + /// Return the links on this session matching the state mask. PN_CPP_EXTERN link_range find_links(endpoint::state mask) const; }; +/// @cond INTERNAL +/// XXX should be exposed? /// An iterator for sessions. class session_iterator : public iter_base<session> { public: @@ -97,10 +113,11 @@ class session_iterator : public iter_base<session> { PN_CPP_EXTERN session_iterator operator++(); session_iterator operator++(int) { session_iterator x(*this); ++(*this); return x; } }; - +/// @endcond + /// A range of sessions. typedef range<session_iterator> session_range; } -#endif /*!PROTON_CPP_SESSION_H*/ +#endif // PROTON_CPP_SESSION_H http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/ssl.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/ssl.hpp b/proton-c/bindings/cpp/include/proton/ssl.hpp index 11ac0a9..d2111c9 100644 --- a/proton-c/bindings/cpp/include/proton/ssl.hpp +++ b/proton-c/bindings/cpp/include/proton/ssl.hpp @@ -21,60 +21,98 @@ * under the License. * */ + #include "proton/export.hpp" -#include "proton/ssl.h" +#include "proton/ssl.h" #include <string> namespace proton { class connection_options; +/// SSL information. class ssl { public: + /// Determines the level of peer validation. enum verify_mode { + /// Require peer to provide a valid identifying certificate VERIFY_PEER = PN_SSL_VERIFY_PEER, + /// Do not require a certificate or cipher authorization ANONYMOUS_PEER = PN_SSL_ANONYMOUS_PEER, + /// Require valid certificate and matching name VERIFY_PEER_NAME = PN_SSL_VERIFY_PEER_NAME }; - /// Outcome specifier for an attempted session resume + + /// Outcome specifier for an attempted session resume. enum resume_status { - UNKNOWN = PN_SSL_RESUME_UNKNOWN, /**< Session resume state unknown/not supported */ - NEW = PN_SSL_RESUME_NEW, /**< Session renegotiated - not resumed */ - REUSED = PN_SSL_RESUME_REUSED /**< Session resumed from previous session. */ + UNKNOWN = PN_SSL_RESUME_UNKNOWN, ///< Session resume state unknown or not supported + NEW = PN_SSL_RESUME_NEW, ///< Session renegotiated, not resumed + REUSED = PN_SSL_RESUME_REUSED ///< Session resumed from previous session }; + + /// @cond INTERNAL ssl(pn_ssl_t* s) : object_(s) {} + /// @endcond + + /// @cond INTERNAL + + /// XXX C API uses cipher_name + /// Get the cipher name. PN_CPP_EXTERN std::string cipher() const; + + /// XXX C API uses protocol_name + /// Get the protocol name. PN_CPP_EXTERN std::string protocol() const; + + /// Get the security strength factor. PN_CPP_EXTERN int ssf() const; + + /// XXX remove PN_CPP_EXTERN void peer_hostname(const std::string &); PN_CPP_EXTERN std::string peer_hostname() const; + + /// XXX discuss, what's the meaning of "remote" here? PN_CPP_EXTERN std::string remote_subject() const; + + /// XXX setters? versus connection options PN_CPP_EXTERN void resume_session_id(const std::string& session_id); + PN_CPP_EXTERN enum resume_status resume_status() const; -private: + /// @endcond + + private: pn_ssl_t* object_; }; - class ssl_certificate { public: + /// Create an SSL certificate. PN_CPP_EXTERN ssl_certificate(const std::string &certdb_main, const std::string &certdb_extra = std::string()); + + /// Create an SSL certificate. + /// + /// @internal + /// XXX what is the difference between these? PN_CPP_EXTERN ssl_certificate(const std::string &certdb_main, const std::string &certdb_extra, const std::string &passwd); + private: std::string certdb_main_; std::string certdb_extra_; std::string passwd_; bool pw_set_; + + /// @cond INTERNAL friend class ssl_client_options; friend class ssl_server_options; + /// @endcond }; - class ssl_domain_impl; namespace internal { + // Base class for SSL configuration class ssl_domain { public: @@ -89,42 +127,64 @@ class ssl_domain { private: ssl_domain_impl *impl_; }; -} +} -/** SSL/TLS configuration for inbound connections created from a listener */ +/// SSL configuration for inbound connections. class ssl_server_options : private internal::ssl_domain { public: - /** SSL options for servers based on the supplied X509 certificate specifier. */ + /// Server SSL options based on the supplied X.509 certificate + /// specifier. PN_CPP_EXTERN ssl_server_options(ssl_certificate &cert); - /** SSL options for servers requiring connecting clients to provide a client certificate. */ + + /// Server SSL options requiring connecting clients to provide a + /// client certificate. PN_CPP_EXTERN ssl_server_options(ssl_certificate &cert, const std::string &trust_db, - const std::string &advertise_db = std::string(), - enum ssl::verify_mode mode = ssl::VERIFY_PEER); - /** SSL options for servers restricted to available anonymous cipher suites on the platform. */ + const std::string &advertise_db = std::string(), + enum ssl::verify_mode mode = ssl::VERIFY_PEER); + + /// Server SSL options restricted to available anonymous cipher + /// suites on the platform. PN_CPP_EXTERN ssl_server_options(); private: - // Bring pn_domain into scope and allow connection_options to use it + // Bring pn_domain into scope and allow connection_options to use + // it. using internal::ssl_domain::pn_domain; + + /// @cond INTERNAL friend class connection_options; + /// @endcond }; - -/** SSL/TLS configuration for outgoing connections */ +/// SSL configuration for outbound connections. class ssl_client_options : private internal::ssl_domain { public: - PN_CPP_EXTERN ssl_client_options(const std::string &trust_db, enum ssl::verify_mode = ssl::VERIFY_PEER_NAME); - PN_CPP_EXTERN ssl_client_options(ssl_certificate&, const std::string &trust_db, enum ssl::verify_mode = ssl::VERIFY_PEER_NAME); - /** A client domain restricted to available anonymous cipher suites on the platform. */ + /// Create SSL client options. + PN_CPP_EXTERN ssl_client_options(const std::string &trust_db, + enum ssl::verify_mode = ssl::VERIFY_PEER_NAME); + + /// Create SSL client options. + /// + /// @internal + /// XXX how is this distinct? + PN_CPP_EXTERN ssl_client_options(ssl_certificate&, const std::string &trust_db, + enum ssl::verify_mode = ssl::VERIFY_PEER_NAME); + + /// Server SSL options restricted to available anonymous cipher + /// suites on the platform. PN_CPP_EXTERN ssl_client_options(); private: - // Bring pn_domain into scope and allow connection_options to use it + // Bring pn_domain into scope and allow connection_options to use + // it. using internal::ssl_domain::pn_domain; + + /// @cond INTERNAL friend class connection_options; + /// @endcond }; } -#endif /*!PROTON_CPP_SSL_H*/ +#endif // PROTON_CPP_SSL_H http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/task.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/task.hpp b/proton-c/bindings/cpp/include/proton/task.hpp index ffa0b11..07b7a5d 100644 --- a/proton-c/bindings/cpp/include/proton/task.hpp +++ b/proton-c/bindings/cpp/include/proton/task.hpp @@ -21,6 +21,10 @@ * under the License. * */ + +/// @cond INTERNAL +/// XXX needs more discussion + #include "proton/export.hpp" #include "proton/object.hpp" @@ -28,15 +32,17 @@ namespace proton { -/** A task for timer events */ +/// A task for timer events. class task : public object<pn_task_t> { public: task(pn_task_t* t) : object<pn_task_t>(t) {} - /** Cancel the scheduled task. */ + /// Cancel the scheduled task. PN_CPP_EXTERN void cancel(); }; } -#endif /*!PROTON_CPP_TASK_H*/ +/// @endcond + +#endif // PROTON_CPP_TASK_H http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/terminus.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/terminus.hpp b/proton-c/bindings/cpp/include/proton/terminus.hpp index ce52360..a10ff9b 100644 --- a/proton-c/bindings/cpp/include/proton/terminus.hpp +++ b/proton-c/bindings/cpp/include/proton/terminus.hpp @@ -21,31 +21,36 @@ * under the License. * */ -#include "proton/export.hpp" -#include "proton/link.h" +#include "proton/export.hpp" #include "proton/object.hpp" #include "proton/value.hpp" + +#include "proton/link.h" #include <string> namespace proton { class link; -/** A terminus represents one end of a link. - * The source terminus is where messages originate, the target terminus is where they go. - */ -class terminus -{ +/// One end of a link, either a source or a target. +/// +/// The source terminus is where messages originate; the target +/// terminus is where they go. +/// +/// @see proton::link +class terminus { public: + /// @cond INTERNAL terminus(pn_terminus_t* t); + /// @endcond /// Type of terminus - enum type{ + enum type { TYPE_UNSPECIFIED = PN_UNSPECIFIED, SOURCE = PN_SOURCE, TARGET = PN_TARGET, - COORDINATOR = PN_COORDINATOR ///< Transaction co-ordinator + COORDINATOR = PN_COORDINATOR ///< Transaction coordinator }; /// Durability @@ -70,37 +75,69 @@ class terminus MOVE = PN_DIST_MODE_MOVE }; + /// Get the terminus type. PN_CPP_EXTERN enum type type() const; + + /// Set the terminus type. PN_CPP_EXTERN void type(enum type); + + /// Get the expiration policy. PN_CPP_EXTERN enum expiry_policy expiry_policy() const; + + /// Set the expiration policy. PN_CPP_EXTERN void expiry_policy(enum expiry_policy); + + /// @cond INTERNAL + /// XXX use duration PN_CPP_EXTERN uint32_t timeout() const; PN_CPP_EXTERN void timeout(uint32_t seconds); + /// @endcond + + /// Get the distribution mode. PN_CPP_EXTERN enum distribution_mode distribution_mode() const; + + /// Set the distribution mode. PN_CPP_EXTERN void distribution_mode(enum distribution_mode); + + /// Get the durability flag. PN_CPP_EXTERN enum durability durability(); + + /// Set the durability flag. PN_CPP_EXTERN void durability(enum durability); + + /// Get the source or target address. PN_CPP_EXTERN std::string address() const; + + /// Set the source or target address. PN_CPP_EXTERN void address(const std::string &); + + /// True if the remote node is created dynamically. PN_CPP_EXTERN bool dynamic() const; + + /// Enable or disable dynamic creation of the remote node. PN_CPP_EXTERN void dynamic(bool); - /** Obtain a reference to the AMQP dynamic node properties for the terminus. - * See also link_options::lifetime_policy. */ + /// Obtain a reference to the AMQP dynamic node properties for the + /// terminus. See also link_options::lifetime_policy. PN_CPP_EXTERN value& node_properties(); + + /// Obtain a reference to the AMQP dynamic node properties for the + /// terminus. See also link_options::lifetime_policy. PN_CPP_EXTERN const value& node_properties() const; - /** Obtain a reference to the AMQP filter set for the terminus. - * See also link_options::selector. */ + /// Obtain a reference to the AMQP filter set for the terminus. + /// See also link_options::selector. PN_CPP_EXTERN value& filter(); + + /// Obtain a reference to the AMQP filter set for the terminus. + /// See also link_options::selector. PN_CPP_EXTERN const value& filter() const; -private: + private: pn_terminus_t* object_; value properties_, filter_; }; - } -#endif /*!PROTON_CPP_TERMINUS_H*/ +#endif // PROTON_CPP_TERMINUS_H http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/transport.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/transport.hpp b/proton-c/bindings/cpp/include/proton/transport.hpp index b3a9c6d..2d84f3d 100644 --- a/proton-c/bindings/cpp/include/proton/transport.hpp +++ b/proton-c/bindings/cpp/include/proton/transport.hpp @@ -34,16 +34,30 @@ class connection; class condition; class sasl; -/** Represents a connection transport */ -class transport : public object<pn_transport_t> -{ +/// A network layer supporting an AMQP connection. +class transport : public object<pn_transport_t> { public: + /// @cond INTERNAL transport(pn_transport_t* t) : object<pn_transport_t>(t) {} + /// @endcond + /// @cond INTERNAL + /// XXX what if a transport is associated with multiple connections? + /// Get the connection associated with this transport. PN_CPP_EXTERN class connection connection() const; + /// @endcond + + /// Get SSL information. PN_CPP_EXTERN class ssl ssl() const; + + /// Get SASL information. PN_CPP_EXTERN class sasl sasl() const; + + /// Get the error condition. PN_CPP_EXTERN class condition condition() const; + + /// @cond INTERNAL + /// XXX need to discuss, local versus remote PN_CPP_EXTERN void unbind(); PN_CPP_EXTERN void bind(class connection &); PN_CPP_EXTERN uint32_t max_frame_size() const; @@ -52,10 +66,13 @@ class transport : public object<pn_transport_t> PN_CPP_EXTERN uint16_t remote_max_channels() const; PN_CPP_EXTERN uint32_t idle_timeout() const; PN_CPP_EXTERN uint32_t remote_idle_timeout() const; + /// @endcond + + /// @cond INTERNAL friend class connection_options; + /// @endcond }; - } -#endif /*!PROTON_CPP_TRANSPORT_H*/ +#endif // PROTON_CPP_TRANSPORT_H http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/type_traits.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/type_traits.hpp b/proton-c/bindings/cpp/include/proton/type_traits.hpp index 8f502a3..56f503c 100644 --- a/proton-c/bindings/cpp/include/proton/type_traits.hpp +++ b/proton-c/bindings/cpp/include/proton/type_traits.hpp @@ -1,5 +1,6 @@ #ifndef TYPE_TRAITS_HPP #define TYPE_TRAITS_HPP + /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file @@ -19,17 +20,20 @@ * under the License. */ -/**@file - * Internal: Type traits for mapping between AMQP and C++ types. - * - * Also provides workarounds for missing type_traits classes on older C++ compilers. - * @cond INTERNAL - */ +/// @cond INTERNAL + +/// @file +/// +/// Internal: Type traits for mapping between AMQP and C++ types. +/// +/// Also provides workarounds for missing type_traits classes on older +/// C++ compilers. #include "proton/config.hpp" #include "proton/types.hpp" namespace proton { + class value; template <bool, class T=void> struct enable_if {}; @@ -121,8 +125,8 @@ template <class T> struct is_unknown_integer { static const bool value = !has_type_id<T>::value && is_integral<T>::value; }; - } -///@endcond + +/// @endcond #endif // TYPE_TRAITS_HPP http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/types.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/types.hpp b/proton-c/bindings/cpp/include/proton/types.hpp index 32a2fca..ee93082 100644 --- a/proton-c/bindings/cpp/include/proton/types.hpp +++ b/proton-c/bindings/cpp/include/proton/types.hpp @@ -1,5 +1,6 @@ #ifndef TYPES_H #define TYPES_H + /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file @@ -19,71 +20,71 @@ * under the License. */ -/**@file - * Defines C++ types representing AMQP types. - */ +/// @file +/// +/// Defines C++ types representing AMQP types. #include "proton/comparable.hpp" #include "proton/export.hpp" #include "proton/error.hpp" -#include <proton/codec.h> +#include <proton/codec.h> // XXX everywhere else folks are using "codec.h" #include <proton/type_compat.h> - #include <algorithm> #include <bitset> #include <string> #include <memory.h> -#include <algorithm> namespace proton { -/** type_id identifies an AMQP type. */ +/// An identifier for AMQP types. enum type_id { - NULL_TYPE=PN_NULL, ///< The null type, contains no data. - BOOLEAN=PN_BOOL, ///< Boolean true or false. - UBYTE=PN_UBYTE, ///< Unsigned 8 bit integer. - BYTE=PN_BYTE, ///< Signed 8 bit integer. - USHORT=PN_USHORT, ///< Unsigned 16 bit integer. - SHORT=PN_SHORT, ///< Signed 16 bit integer. - UINT=PN_UINT, ///< Unsigned 32 bit integer. - INT=PN_INT, ///< Signed 32 bit integer. - CHAR=PN_CHAR, ///< 32 bit unicode character. - ULONG=PN_ULONG, ///< Unsigned 64 bit integer. - LONG=PN_LONG, ///< Signed 64 bit integer. - TIMESTAMP=PN_TIMESTAMP, ///< Signed 64 bit milliseconds since the epoch. - FLOAT=PN_FLOAT, ///< 32 bit binary floating point. - DOUBLE=PN_DOUBLE, ///< 64 bit binary floating point. - DECIMAL32=PN_DECIMAL32, ///< 32 bit decimal floating point. - DECIMAL64=PN_DECIMAL64, ///< 64 bit decimal floating point. - DECIMAL128=PN_DECIMAL128, ///< 128 bit decimal floating point. - UUID=PN_UUID, ///< 16 byte UUID. - BINARY=PN_BINARY, ///< Variable length sequence of bytes. - STRING=PN_STRING, ///< Variable length utf8-encoded string. - SYMBOL=PN_SYMBOL, ///< Variable length encoded string. - DESCRIBED=PN_DESCRIBED, ///< A descriptor and a value. - ARRAY=PN_ARRAY, ///< A sequence of values of the same type. - LIST=PN_LIST, ///< A sequence of values, may be of mixed types. - MAP=PN_MAP ///< A sequence of key:value pairs, may be of mixed types. + NULL_TYPE = PN_NULL, ///< The null type, contains no data. + BOOLEAN = PN_BOOL, ///< Boolean true or false. + UBYTE = PN_UBYTE, ///< Unsigned 8 bit integer. + BYTE = PN_BYTE, ///< Signed 8 bit integer. + USHORT = PN_USHORT, ///< Unsigned 16 bit integer. + SHORT = PN_SHORT, ///< Signed 16 bit integer. + UINT = PN_UINT, ///< Unsigned 32 bit integer. + INT = PN_INT, ///< Signed 32 bit integer. + CHAR = PN_CHAR, ///< 32 bit unicode character. + ULONG = PN_ULONG, ///< Unsigned 64 bit integer. + LONG = PN_LONG, ///< Signed 64 bit integer. + TIMESTAMP = PN_TIMESTAMP, ///< Signed 64 bit milliseconds since the epoch. + FLOAT = PN_FLOAT, ///< 32 bit binary floating point. + DOUBLE = PN_DOUBLE, ///< 64 bit binary floating point. + DECIMAL32 = PN_DECIMAL32, ///< 32 bit decimal floating point. + DECIMAL64 = PN_DECIMAL64, ///< 64 bit decimal floating point. + DECIMAL128 = PN_DECIMAL128, ///< 128 bit decimal floating point. + UUID = PN_UUID, ///< 16 byte UUID. + BINARY = PN_BINARY, ///< Variable length sequence of bytes. + STRING = PN_STRING, ///< Variable length utf8-encoded string. + SYMBOL = PN_SYMBOL, ///< Variable length encoded string. + DESCRIBED = PN_DESCRIBED, ///< A descriptor and a value. + ARRAY = PN_ARRAY, ///< A sequence of values of the same type. + LIST = PN_LIST, ///< A sequence of values, may be of mixed types. + MAP = PN_MAP ///< A sequence of key:value pairs, may be of mixed types. }; -/// Name of the AMQP type +/// Get the name of the AMQP type. PN_CPP_EXTERN std::string type_name(type_id); -/// Print the type_name +/// Print the type name. PN_CPP_EXTERN std::ostream& operator<<(std::ostream&, type_id); -/// Raised when there is a type mismatch, with the expected and actual type ID. +/// @cond INTERNAL + +/// XXX change namespace +/// Raised when there is a type mismatch, with the expected and actual +/// type ID. struct type_error : public decode_error { PN_CPP_EXTERN explicit type_error(type_id want, type_id got, const std::string& =std::string()); type_id want; ///< Expected type_id type_id got; ///< Actual type_id }; -///@cond INTERNAL PN_CPP_EXTERN pn_bytes_t pn_bytes(const std::string&); PN_CPP_EXTERN std::string str(const pn_bytes_t& b); -///@endcond /// AMQP NULL type. struct amqp_null {}; @@ -133,7 +134,8 @@ struct amqp_binary : public std::string { explicit amqp_binary(const pn_bytes_t& b) : std::string(b.start, b.size) {} }; -/// Template for opaque proton proton types that can be treated as byte arrays. +/// Template for opaque proton proton types that can be treated as +/// byte arrays. template <class P> struct opaque : public comparable<opaque<P> > { P value; opaque(const P& p=P()) : value(p) {} @@ -154,12 +156,15 @@ template <class T> bool operator<(const opaque<T>& x, const opaque<T>& y) { retu /// AMQP 16-byte UUID. typedef opaque<pn_uuid_t> amqp_uuid; PN_CPP_EXTERN std::ostream& operator<<(std::ostream&, const amqp_uuid&); + /// AMQP 32-bit decimal floating point (IEEE 854). typedef opaque<pn_decimal32_t> amqp_decimal32; PN_CPP_EXTERN std::ostream& operator<<(std::ostream&, const amqp_decimal32&); + /// AMQP 64-bit decimal floating point (IEEE 854). typedef opaque<pn_decimal64_t> amqp_decimal64; PN_CPP_EXTERN std::ostream& operator<<(std::ostream&, const amqp_decimal64&); + /// AMQP 128-bit decimal floating point (IEEE 854). typedef opaque<pn_decimal128_t> amqp_decimal128; PN_CPP_EXTERN std::ostream& operator<<(std::ostream&, const amqp_decimal128&); @@ -174,11 +179,18 @@ inline bool operator==(amqp_timestamp x, amqp_timestamp y) { return x.millisecon inline bool operator<(amqp_timestamp x, amqp_timestamp y) { return x.milliseconds < y.milliseconds; } PN_CPP_EXTERN std::ostream& operator<<(std::ostream&, const amqp_timestamp&); +/// @endcond + // TODO aconway 2015-06-16: described types. -///@name Attributes of a type_id value, returns same result as the -/// corresponding std::type_traits tests for the corresponding C++ types. -///@{ +/// @name Type test functions +/// +/// Attributes of a type_id value, returns same result as the +/// corresponding std::type_traits tests for the corresponding C++ +/// types. +/// +/// @{ + /// Any scalar type PN_CPP_EXTERN bool type_id_is_scalar(type_id); /// One of the signed integer types: BYTE, SHORT, INT or LONG @@ -197,16 +209,19 @@ PN_CPP_EXTERN bool type_id_is_decimal(type_id); PN_CPP_EXTERN bool type_id_is_string_like(type_id); /// Container types: MAP, LIST, ARRAY or DESCRIBED. PN_CPP_EXTERN bool type_id_is_container(type_id); -///@} -/** Print the name of a type. */ +/// @} + +/// Print the name of a type. PN_CPP_EXTERN std::ostream& operator<<(std::ostream&, type_id); -/** Information needed to start extracting or inserting a container type. - * - * See encoder::operator<<(encoder&, const start&) and decoder::operator>>(decoder&, start&) - * for examples of use. - */ +/// @cond INTERNAL +/// XXX change namespace + +/// Information needed to start extracting or inserting a container type. +/// +/// See encoder::operator<<(encoder&, const start&) and +/// decoder::operator>>(decoder&, start&) for examples of use. struct start { PN_CPP_EXTERN start(type_id type=NULL_TYPE, type_id element=NULL_TYPE, bool described=false, size_t size=0); type_id type; ///< The container type: ARRAY, LIST, MAP or DESCRIBED. @@ -214,19 +229,24 @@ struct start { bool is_described; ///< true if first value is a descriptor. size_t size; ///< the element count excluding the descriptor (if any) - /** Return a start for an array */ + /// Return a start for an array. PN_CPP_EXTERN static start array(type_id element, bool described=false); - /** Return a start for a list */ + + /// Return a start for a list. PN_CPP_EXTERN static start list(); - /** Return a start for a map */ + + /// Return a start for a map. PN_CPP_EXTERN static start map(); - /** Return a start for a described type */ + + /// Return a start for a described type. PN_CPP_EXTERN static start described(); }; -/** Finish inserting or extracting a container value. */ +/// Finish inserting or extracting a container value. struct finish {}; +/// @endcond + } #endif // TYPES_H http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/url.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/url.hpp b/proton-c/bindings/cpp/include/proton/url.hpp index c2d273b..62aa6a0 100644 --- a/proton-c/bindings/cpp/include/proton/url.hpp +++ b/proton-c/bindings/cpp/include/proton/url.hpp @@ -1,5 +1,6 @@ #ifndef URL_HPP #define URL_HPP + /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file @@ -21,110 +22,133 @@ #include "proton/types.hpp" #include "proton/error.hpp" + #include <iosfwd> struct pn_url_t; namespace proton { -/// Thrown if URL parsing fails. +/// Raised if URL parsing fails. struct url_error : public error { + /// @cond INTERNAL PN_CPP_EXTERN explicit url_error(const std::string&); + /// @endcond }; - -/** - * url is a proton URL of the form `<scheme>://<username>:<password>@<host>:<port>/<path>`. - * scheme can be `amqp` or `amqps`. host is a DNS name or IP address (v4 or v6) - * port can be a number or symbolic service name like `amqp`. path is normally used as - * a link source or target address, on a broker it typically it corresponds to a queue or topic name. - */ +/// A proton URL. +/// +/// Proton URLs take the form +/// `<scheme>://<username>:<password>@<host>:<port>/<path>`. +/// +/// - Scheme can be `amqp` or `amqps`. Host is a DNS name or IP +/// address (v4 or v6). +/// +/// - Port can be a number or a symbolic service name such as `amqp`. +/// +/// - Path is normally used as a link source or target address. On a +/// broker it typically corresponds to a queue or topic name. class url { public: static const std::string AMQP; ///< "amqp" prefix static const std::string AMQPS; ///< "amqps" prefix - /** Create an empty url */ + /// Create an empty URL PN_CPP_EXTERN url(); - /** Parse url_str as an AMQP URL. If defaults is true, fill in defaults for missing values - * otherwise return an empty string for missing values. - * Note: converts automatically from string. - *@throw url_error if URL is invalid. - */ + /// Parse `url_str` as an AMQP URL. If defaults is true, fill in + /// defaults for missing values otherwise return an empty string + /// for missing values. + /// + /// @note Converts automatically from string. + /// + /// @throw url_error if URL is invalid. PN_CPP_EXTERN url(const std::string& url_str, bool defaults=true); - /** Parse url_str as an AMQP URL. If defaults is true, fill in defaults for missing values - * otherwise return an empty string for missing values. - * Note: converts automatically from string. - *@throw url_error if URL is invalid. - */ + /// Parse `url_str` as an AMQP URL. If defaults is true, fill in + /// defaults for missing values otherwise return an empty string + /// for missing values. + /// + /// @note Converts automatically from string. + /// + /// @throw url_error if URL is invalid. PN_CPP_EXTERN url(const char* url_str, bool defaults=true); + /// Copy a URL. PN_CPP_EXTERN url(const url&); PN_CPP_EXTERN ~url(); + /// Copy a URL. PN_CPP_EXTERN url& operator=(const url&); - /** Parse a string as a URL - *@throws url_error if URL is invalid. - */ + /// Parse a string as a URL. + /// + /// @throws url_error if URL is invalid. PN_CPP_EXTERN void parse(const std::string&); - /** Parse a string as a URL - *@throws url_error if URL is invalid. - */ + /// Parse a string as a URL. + /// + /// @throws url_error if URL is invalid. PN_CPP_EXTERN void parse(const char*); + /// True if the URL is empty. PN_CPP_EXTERN bool empty() const; - /** str returns the URL as a string string */ + /// `str` returns the URL as a string PN_CPP_EXTERN std::string str() const; - /**@name Get parts of the URL - *@{ - */ + /// @name URL fields + /// + /// @{ + PN_CPP_EXTERN std::string scheme() const; + PN_CPP_EXTERN void scheme(const std::string&); + + /// @cond INTERNAL PN_CPP_EXTERN std::string username() const; + PN_CPP_EXTERN void username(const std::string&); + /// @endcond + PN_CPP_EXTERN std::string password() const; + PN_CPP_EXTERN void password(const std::string&); + PN_CPP_EXTERN std::string host() const; - /** port is a string, it can be a number or a symbolic name like "amqp" */ + PN_CPP_EXTERN void host(const std::string&); + /// `port` can be a number or a symbolic name such as "amqp". + PN_CPP_EXTERN void port(const std::string&); PN_CPP_EXTERN std::string port() const; - /** port_int is the numeric value of the port. */ + /// `port_int` is the numeric value of the port. PN_CPP_EXTERN uint16_t port_int() const; - /** path is everything after the final "/" */ - PN_CPP_EXTERN std::string path() const; - //@} - - /** host_port returns just the host:port part of the URL */ + /// host_port returns just the `host:port` part of the URL PN_CPP_EXTERN std::string host_port() const; - /**@name Set parts of the URL - *@{ - */ - PN_CPP_EXTERN void scheme(const std::string&); - PN_CPP_EXTERN void username(const std::string&); - PN_CPP_EXTERN void password(const std::string&); - PN_CPP_EXTERN void host(const std::string&); - /** port is a string, it can be a number or a symbolic name like "amqp" */ - PN_CPP_EXTERN void port(const std::string&); + /// `path` is everything after the final "/". + PN_CPP_EXTERN std::string path() const; PN_CPP_EXTERN void path(const std::string&); - //@} - /** defaults fills in default values for missing parts of the URL */ - PN_CPP_EXTERN void defaults(); + /// @} - friend PN_CPP_EXTERN std::ostream& operator<<(std::ostream&, const url&); - - /** parse url from istream, automatically fills in defaults for missing values. - * - * Note: an invalid url is indicated by setting std::stream::fail() NOT by throwing url_error. - */ - friend PN_CPP_EXTERN std::istream& operator>>(std::istream&, url&); + /// @cond INTERNAL + /// XXX need to discuss + /// defaults fills in default values for missing parts of the URL. + PN_CPP_EXTERN void defaults(); + /// @endcond private: pn_url_t* url_; -}; + /// @cond INTERNAL + + friend PN_CPP_EXTERN std::ostream& operator<<(std::ostream&, const url&); + + /// Parse `url` from istream. This automatically fills in + /// defaults for missing values. + /// + /// @note An invalid url is indicated by setting + /// std::stream::fail(), NOT by throwing url_error. + friend PN_CPP_EXTERN std::istream& operator>>(std::istream&, url&); + + /// @endcond +}; } http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/value.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/value.hpp b/proton-c/bindings/cpp/include/proton/value.hpp index 732763c..4076e99 100644 --- a/proton-c/bindings/cpp/include/proton/value.hpp +++ b/proton-c/bindings/cpp/include/proton/value.hpp @@ -1,5 +1,6 @@ #ifndef VALUE_H #define VALUE_H + /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file @@ -18,77 +19,103 @@ * specific language governing permissions and limitations * under the License. */ + #include "proton/data.hpp" #include "proton/types.hpp" namespace proton { -/** - * Holder for an AMQP value. - * - * proton::value can hold any AMQP data value, simple or compound. It has - * assignment and conversion operators to convert its contents easily to and - * from native C++ types. - * - */ +/// A holder for an AMQP value. +/// +/// A proton::value can hold any AMQP data value, simple or compound. +/// It has assignment and conversion operators to convert its contents +/// easily to and from native C++ types. class value : public comparable<value> { public: + /// Create an empty value. PN_CPP_EXTERN value(); + + /// Copy a value. PN_CPP_EXTERN value(const value&); + #if PN_HAS_CPP11 PN_CPP_EXTERN value(value&&); #endif + + /// Copy a value. PN_CPP_EXTERN value& operator=(const value&); + /// Create a value from C++ type T. template <class T> value(const T& x) : data_(proton::data::create()) { encode() << x; } + + /// Create a value from C++ type T. template <class T> value& operator=(const T& x) { encode() << x; return *this; } + /// Remove any contained data. PN_CPP_EXTERN void clear(); + + /// True if the value contains no data. PN_CPP_EXTERN bool empty() const; - /** Type of the current value*/ + /// Get the type of the current value. PN_CPP_EXTERN type_id type() const; + /// @name Get methods + /// + /// Extract the value to type T. + /// + /// @{ + /// Get the value. template<class T> void get(T &t) const { decode() >> t; } /// Get an AMQP map as any type T that satisfies the map concept. template<class T> void get_map(T& t) const { decode() >> to_map(t); } + /// Get a map as a as any type T that is a sequence pair-like types with first and second. template<class T> void get_pairs(T& t) const { decode() >> to_pairs(t); } + /// Get an AMQP array or list as type T that satisfies the sequence concept. */ template<class T> void get_sequence(T& t) const { decode() >> to_sequence(t); } + /// @} + /// Get the value as C++ type T. template<class T> T get() const { T t; get(t); return t; } - ///@name as_ methods do "loose" conversion, they will convert the scalar - ///value to the requested type if possible, else throw type_error - ///@{ - PN_CPP_EXTERN int64_t as_int() const; ///< Allowed if type_id_is_integral(type()) - PN_CPP_EXTERN uint64_t as_uint() const; ///< Allowed if type_id_is_integral(type()) - PN_CPP_EXTERN double as_double() const; ///< Allowed if type_id_is_floating_point(type()) - PN_CPP_EXTERN std::string as_string() const; ///< Allowed if type_id_is_string_like(type()) - ///@} - - ///@cond INTERNAL - PN_CPP_EXTERN encoder encode(); ///< Clear and return an encoder for this value. - PN_CPP_EXTERN decoder decode() const; ///< Rewind and return an encoder for this value. - PN_CPP_EXTERN class data& data() const; ///< Return a data reference, no clear or rewind. - ///@endcond - - friend PN_CPP_EXTERN void swap(value&, value&); - friend PN_CPP_EXTERN bool operator==(const value& x, const value& y); - friend PN_CPP_EXTERN bool operator<(const value& x, const value& y); - friend PN_CPP_EXTERN class encoder operator<<(class encoder e, const value& dv); - friend PN_CPP_EXTERN class decoder operator>>(class decoder d, value& dv); - friend PN_CPP_EXTERN std::ostream& operator<<(std::ostream& o, const value& dv); + /// @name As methods + /// + /// As methods do "loose" conversion, they will convert the scalar + /// value to the requested type if possible, else throw type_error. + /// + /// @{ + PN_CPP_EXTERN int64_t as_int() const; ///< Allowed if `type_id_is_integral(type())` + PN_CPP_EXTERN uint64_t as_uint() const; ///< Allowed if `type_id_is_integral(type())` + PN_CPP_EXTERN double as_double() const; ///< Allowed if `type_id_is_floating_point(type())` + PN_CPP_EXTERN std::string as_string() const; ///< Allowed if `type_id_is_string_like(type())` + /// @} + + /// @cond INTERNAL + /// XXX undiscussed + PN_CPP_EXTERN encoder encode(); ///< Clear and return an encoder for this value. + PN_CPP_EXTERN decoder decode() const; ///< Rewind and return an encoder for this value. + PN_CPP_EXTERN class data& data() const; ///< Return a data reference, no clear or rewind. + /// @endcond private: mutable class data data_; - friend class message; -}; + /// @cond INTERNAL + friend PN_CPP_EXTERN void swap(value&, value&); + friend PN_CPP_EXTERN bool operator==(const value& x, const value& y); + friend PN_CPP_EXTERN bool operator<(const value& x, const value& y); + friend PN_CPP_EXTERN class encoder operator<<(class encoder e, const value& dv); + friend PN_CPP_EXTERN class decoder operator>>(class decoder d, value& dv); + friend PN_CPP_EXTERN std::ostream& operator<<(std::ostream& o, const value& dv); + friend class message; + /// @endcond +}; } + #endif // VALUE_H http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/include/proton/ssl.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/ssl.h b/proton-c/include/proton/ssl.h index 6c22014..8fdae08 100644 --- a/proton-c/include/proton/ssl.h +++ b/proton-c/include/proton/ssl.h @@ -364,12 +364,12 @@ typedef enum { * Get the fingerprint of the certificate. The certificate fingerprint (as displayed in the Fingerprints section when * looking at a certificate with say the Firefox browser) is the hexadecimal hash of the entire certificate. * The fingerprint is not part of the certificate, rather it is computed from the certificate and can be used to uniquely identify a certificate. - * @param[in] ssl the ssl client/server to query + * @param[in] ssl0 the ssl client/server to query * @param[in] fingerprint char pointer. The certificate fingerprint (in hex format) will be populated in this array. * If sha1 is the digest name, the fingerprint is 41 characters long (40 + 1 '\0' character), 65 characters long for * sha256 and 129 characters long for sha512 and 33 characters for md5. * @param[in] fingerprint_length - Must be at >= 33 for md5, >= 41 for sha1, >= 65 for sha256 and >=129 for sha512. - * @param[in] the hash algorithm to use. Must be of type pn_ssl_hash_alg (currently supports sha1, sha256, sha512 and md5) + * @param[in] hash_alg the hash algorithm to use. Must be of type pn_ssl_hash_alg (currently supports sha1, sha256, sha512 and md5) * @return error code - Returns 0 on success. Return a value less than zero if there were any errors. Upon execution of this function, * char *fingerprint will contain the appropriate null terminated hex fingerprint */ @@ -386,8 +386,8 @@ PN_EXTERN int pn_ssl_get_cert_fingerprint(pn_ssl_t *ssl0, * O = Organization - Company Name * OU = Organization Unit - division or unit * CN = CommonName - * @param[in] ssl the ssl client/server to query - * @param[in] The enumeration pn_ssl_cert_subject_subfield representing the required sub field. + * @param[in] ssl0 the ssl client/server to query + * @param[in] field The enumeration pn_ssl_cert_subject_subfield representing the required sub field. * @return A null terminated string which contains the requested sub field value which is valid until the ssl object is destroyed. */ PN_EXTERN const char* pn_ssl_get_remote_subject_subfield(pn_ssl_t *ssl0, pn_ssl_cert_subject_subfield field); --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
