http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/container.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/container.hpp b/proton-c/bindings/cpp/include/proton/container.hpp index 8e907b7..8b33ca4 100644 --- a/proton-c/bindings/cpp/include/proton/container.hpp +++ b/proton-c/bindings/cpp/include/proton/container.hpp @@ -21,6 +21,7 @@ * under the License. * */ + #include "proton/duration.hpp" #include "proton/export.hpp" #include "proton/pn_unique_ptr.hpp" @@ -43,76 +44,99 @@ class handler; class task; class container_impl; -/** - * Top level container for connections and other objects, runs the event loop. - * - * Note that by default, links belonging to the container have generated link-names - * of the form - */ +/// A top-level container of connections, sessions, and links. +/// +/// A container gives a unique identity to each communicating peer. It +/// is often a process-level object. + +/// It serves as an entry point to the API, allowing connections and +/// links to be established. It can be supplied with an event handler +/// in order to intercept important messaging events, such as newly +/// received messages or newly issued link credit for sending +/// messages. class container { public: - /// Container ID should be unique within your system. - /// By default a random ID is generated. + /// Create a container. + /// + /// Container ID should be unique within your system. By default a + /// random ID is generated. PN_CPP_EXTERN container(const std::string& id=""); - /// Container ID should be unique within your system. By default a random ID is generated. + /// Create a container with an event handler. + /// + /// Container ID should be unique within your system. By default a + /// random ID is generated. PN_CPP_EXTERN container(handler& mhandler, const std::string& id=std::string()); PN_CPP_EXTERN ~container(); - /** Locally open a connection @see connection::open */ - PN_CPP_EXTERN connection connect(const proton::url&, const connection_options &opts = connection_options()); + /// Open a connection to `url`. + PN_CPP_EXTERN connection connect(const proton::url&, + const connection_options &opts = connection_options()); - /** Listen on url host and port for incoming connections. */ - PN_CPP_EXTERN acceptor listen(const proton::url&, const connection_options &opts = connection_options()); + /// Listen on `url` for incoming connections. + PN_CPP_EXTERN acceptor listen(const proton::url&, + const connection_options &opts = connection_options()); - /** Run the event loop, return when all connections and acceptors are closed. */ + /// Start processing events. It returns when all connections and + /// acceptors are closed. PN_CPP_EXTERN void run(); - /** Open a new connection to url and create a sender with target=url.path(). - Any supplied link or connection options will override the container's - template options. */ - PN_CPP_EXTERN sender open_sender(const proton::url &, const proton::link_options &l = proton::link_options(), + /// Open a connection to `url` and open a sender for `url.path()`. + /// Any supplied link or connection options will override the + /// container's template options. + PN_CPP_EXTERN sender open_sender(const proton::url &, + const proton::link_options &l = proton::link_options(), const connection_options &c = connection_options()); - /** Create a receiver on a new connection with source=url.path(). Any - supplied link or connection options will override the container's - template options. */ - PN_CPP_EXTERN receiver open_receiver(const url &, const proton::link_options &l = proton::link_options(), + /// Open a connection to `url` and open a receiver for + /// `url.path()`. Any supplied link or connection options will + /// override the container's template options. + PN_CPP_EXTERN receiver open_receiver(const url &, + const proton::link_options &l = proton::link_options(), const connection_options &c = connection_options()); - /// Identifier for the container + /// A unique identifier for the container. PN_CPP_EXTERN std::string id() const; + /// @cond INTERNAL + + /// XXX remove /// The reactor associated with this container. PN_CPP_EXTERN class reactor reactor() const; - // Schedule a timer task event in delay milliseconds. + /// XXX settle some API questions + /// Schedule a timer task event in delay milliseconds. PN_CPP_EXTERN task schedule(int delay, handler *h = 0); - /** Copy the connection options to a template which will be - applied to subsequent outgoing connections. These are applied first - and overriden by additional connection options provided in - other methods */ + /// @endcond + + /// Copy the connection options to a template which will be + /// applied to subsequent outgoing connections. These are applied + /// first and overriden by additional connection options provided + /// in other methods. PN_CPP_EXTERN void client_connection_options(const connection_options &); - /** Copy the connection options to a template which will be - applied to incoming connections. These are applied before the - first open event on the connection. */ + /// Copy the connection options to a template which will be + /// applied to incoming connections. These are applied before the + /// first open event on the connection. PN_CPP_EXTERN void server_connection_options(const connection_options &); - /** Copy the link options to a template applied to new links created and - opened by this container. They are applied before the open event on the - link and may be overriden by link options in other methods. */ + /// Copy the link options to a template applied to new links + /// created and opened by this container. They are applied before + /// the open event on the link and may be overriden by link + /// options in other methods. PN_CPP_EXTERN void link_options(const link_options &); - private: pn_unique_ptr<container_impl> impl_; + + /// @cond INTERNAL friend class connector; - friend class link; + friend class link; + /// @endcond }; } -#endif /*!PROTON_CPP_CONTAINER_H*/ +#endif // PROTON_CPP_CONTAINER_H
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/data.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/data.hpp b/proton-c/bindings/cpp/include/proton/data.hpp index c9f0a08..09cca58 100644 --- a/proton-c/bindings/cpp/include/proton/data.hpp +++ b/proton-c/bindings/cpp/include/proton/data.hpp @@ -1,5 +1,6 @@ #ifndef DATA_H #define DATA_H + /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file @@ -19,7 +20,8 @@ * under the License. */ -///@cond INTERNAL +/// @cond INTERNAL +/// XXX remove #include "proton/decoder.hpp" #include "proton/encoder.hpp" @@ -34,10 +36,9 @@ namespace proton { class data; -/**@internal - * Holds a sequence of AMQP values, allows inserting and extracting via encoder() and decoder(). - * Cannot be directly instantiated, use `value` - */ +/// Holds a sequence of AMQP values, allows inserting and extracting +/// via encoder() and decoder(). Cannot be directly instantiated, use +/// `value`. class data : public object<pn_data_t> { public: data(pn_data_t* d=0) : object<pn_data_t>(d) {} @@ -98,6 +99,6 @@ class data : public object<pn_data_t> { } -///@endcond +/// @endcond #endif // DATA_H http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/decoder.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/decoder.hpp b/proton-c/bindings/cpp/include/proton/decoder.hpp index fdd2f22..3dab9c9 100644 --- a/proton-c/bindings/cpp/include/proton/decoder.hpp +++ b/proton-c/bindings/cpp/include/proton/decoder.hpp @@ -19,7 +19,8 @@ * under the License. */ -///@cond INTERNAL +/// @cond INTERNAL +/// XXX change namespace, review better #include "proton/error.hpp" #include "proton/type_traits.hpp" @@ -396,6 +397,7 @@ template <class K, class T, class C, class A> decoder operator>>(decoder d, std: #endif // PN_NO_CONTAINER_CONVERT } -///@endcond + +/// @endcond #endif // DECODER_H http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/delivery.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/delivery.hpp b/proton-c/bindings/cpp/include/proton/delivery.hpp index a05347b..c4e6243 100644 --- a/proton-c/bindings/cpp/include/proton/delivery.hpp +++ b/proton-c/bindings/cpp/include/proton/delivery.hpp @@ -1,4 +1,3 @@ - #ifndef PROTON_CPP_DELIVERY_H #define PROTON_CPP_DELIVERY_H @@ -22,6 +21,7 @@ * under the License. * */ + #include "proton/export.hpp" #include "proton/object.hpp" @@ -30,94 +30,95 @@ namespace proton { -/** delivery status of a message */ +/// A message transfer. Every delivery exists within the context of a +/// proton::link. A delivery attempt can fail. As a result, a +/// particular message may correspond to multiple deliveries. class delivery : public object<pn_delivery_t> { public: + /// @cond INTERNAL delivery(pn_delivery_t* d=0) : object<pn_delivery_t>(d) {} + /// @endcond - /** Delivery state of a message */ + /// Delivery state values. enum state { - NONE = 0, ///< Unknown state + NONE = 0, ///< Unknown state RECEIVED = PN_RECEIVED, ///< Received but not yet settled ACCEPTED = PN_ACCEPTED, ///< Settled as accepted REJECTED = PN_REJECTED, ///< Settled as rejected RELEASED = PN_RELEASED, ///< Settled as released MODIFIED = PN_MODIFIED ///< Settled as modified - }; // AMQP spec 3.4 delivery State + }; // AMQP spec 3.4 delivery State - /** Return true if the delivery has been settled. */ + /// @cond INTERNAL + /// XXX settle how much of this we need to expose + + /// Return true if the delivery has been settled. PN_CPP_EXTERN bool settled() const; - /** Settle the delivery, informs the remote end. */ + /// Settle the delivery; informs the remote end. PN_CPP_EXTERN void settle(); - /** Set the local state of the delivery. */ + /// Set the local state of the delivery. PN_CPP_EXTERN void update(delivery::state state); - /** update and settle a delivery with the given delivery::state */ + /// Update and settle a delivery with the given delivery::state PN_CPP_EXTERN void settle(delivery::state s); - /** settle with ACCEPTED state */ + /// @endcond + + /// Settle with ACCEPTED state PN_CPP_EXTERN void accept() { settle(ACCEPTED); } - /** settle with REJECTED state */ + /// Settle with REJECTED state PN_CPP_EXTERN void reject() { settle(REJECTED); } - /** settle with REJECTED state */ + /// Settle with RELEASED state PN_CPP_EXTERN void release() { settle(RELEASED); } - /** settle with MODIFIED state */ + /// Settle with MODIFIED state PN_CPP_EXTERN void modify() { settle(MODIFIED); } - /** - * Check if a delivery is readable. - * - * A delivery is considered readable if it is the current delivery on - * an incoming link. - */ + /// @cond INTERNAL + /// XXX who needs this? + + /// Check if a delivery is readable. + /// + /// A delivery is considered readable if it is the current delivery on + /// an incoming link. PN_CPP_EXTERN bool partial() const; - /** - * Check if a delivery is writable. - * - * A delivery is considered writable if it is the current delivery on - * an outgoing link, and the link has positive credit. - */ + /// Check if a delivery is writable. + /// + /// A delivery is considered writable if it is the current delivery on + /// an outgoing link, and the link has positive credit. PN_CPP_EXTERN bool writable() const; - /** - * Check if a delivery is readable. - * - * A delivery is considered readable if it is the current delivery on - * an incoming link. - */ + /// Check if a delivery is readable. + /// + /// A delivery is considered readable if it is the current + /// delivery on an incoming link. PN_CPP_EXTERN bool readable() const; - /** - * Check if a delivery is updated. - * - * A delivery is considered updated whenever the peer communicates a - * new disposition for the delivery. Once a delivery becomes updated, - * it will remain so until clear() is called. - */ + /// Check if a delivery is updated. + /// + /// A delivery is considered updated whenever the peer + /// communicates a new disposition for the delivery. Once a + /// delivery becomes updated, it will remain so until clear() is + /// called. PN_CPP_EXTERN bool updated() const; - /** - * Clear the updated flag for a delivery. - */ + /// Clear the updated flag for a delivery. PN_CPP_EXTERN void clear(); - /** - * Get the remote disposition state for a delivery. - */ - PN_CPP_EXTERN state remote_state() const; - - /** - * Get the size of the current delivery - */ + /// Get the size of the current delivery. PN_CPP_EXTERN size_t pending() const; + + /// @endcond + + /// Get the remote state for a delivery. + PN_CPP_EXTERN state remote_state() const; }; } -#endif /*!PROTON_CPP_DELIVERY_H*/ +#endif // PROTON_CPP_DELIVERY_H http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/duration.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/duration.hpp b/proton-c/bindings/cpp/include/proton/duration.hpp index 1726701..200064d 100644 --- a/proton-c/bindings/cpp/include/proton/duration.hpp +++ b/proton-c/bindings/cpp/include/proton/duration.hpp @@ -28,17 +28,21 @@ namespace proton { -/** Duration in milliseconds. */ -class duration : public comparable<duration> -{ +/// A span of time in milliseconds. +class duration : public comparable<duration> { public: + /// @cond INTERNAL + /// XXX public and mutable? uint64_t milliseconds; + /// @endcond + + /// Create a duration. explicit duration(uint64_t ms = 0) : milliseconds(ms) {} - PN_CPP_EXTERN static const duration FOREVER; ///< Wait for ever + PN_CPP_EXTERN static const duration FOREVER; ///< Wait for ever PN_CPP_EXTERN static const duration IMMEDIATE; ///< Don't wait at all - PN_CPP_EXTERN static const duration SECOND; ///< One second - PN_CPP_EXTERN static const duration MINUTE; ///< One minute + PN_CPP_EXTERN static const duration SECOND; ///< One second + PN_CPP_EXTERN static const duration MINUTE; ///< One minute }; inline bool operator<(duration x, duration y) { return x.milliseconds < y.milliseconds; } @@ -49,6 +53,7 @@ inline duration operator*(amqp_ulong n, duration d) { return d * n; } inline amqp_timestamp operator+(amqp_timestamp ts, duration d) { return amqp_timestamp(ts.milliseconds+d.milliseconds); } inline amqp_timestamp operator+(duration d, amqp_timestamp ts) { return ts + d; } + } -#endif /*!PROTON_CPP_DURATION_H*/ +#endif // PROTON_CPP_DURATION_H http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/encoder.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/encoder.hpp b/proton-c/bindings/cpp/include/proton/encoder.hpp index c2d683e..1876412 100644 --- a/proton-c/bindings/cpp/include/proton/encoder.hpp +++ b/proton-c/bindings/cpp/include/proton/encoder.hpp @@ -1,5 +1,6 @@ #ifndef ENCODER_H #define ENCODER_H + /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file @@ -19,7 +20,8 @@ * under the License. */ -///@cond INTERNAL +/// @cond INTERNAL +/// XXX change namespace, review better #include "proton/error.hpp" #include "proton/types.hpp" @@ -42,8 +44,8 @@ #endif // PN_NO_CONTAINER_CONVERT -///@file -///@internal +/// @file +/// @internal struct pn_data_t; @@ -62,6 +64,7 @@ template<class T, type_id A> struct cref { cref(const T& v) : value(v) {} const T& value; }; + template <class T, type_id A> const type_id cref<T, A>::type = A; /** @@ -264,8 +267,9 @@ template <class K, class T, class C, class A> encoder operator<<(encoder e, cons #endif // PN_HAS_CPP11 #endif // PN_NO_CONTAINER_CONVERT + } -///@endcond +/// @endcond #endif // ENCODER_H http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/endpoint.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/endpoint.hpp b/proton-c/bindings/cpp/include/proton/endpoint.hpp index 832548a..fd698b0 100644 --- a/proton-c/bindings/cpp/include/proton/endpoint.hpp +++ b/proton-c/bindings/cpp/include/proton/endpoint.hpp @@ -27,42 +27,42 @@ namespace proton { -/** endpoint is a base class for session, connection and link */ -class endpoint -{ +/// The base class for session, connection, and link. +class endpoint { public: - /** state is a bit mask of state_bit values. - * - * A state mask is matched against an endpoint as follows: If the state mask - * contains both local and remote flags, then an exact match against those - * flags is performed. If state contains only local or only remote flags, - * then a match occurs if any of the local or remote flags are set - * respectively. - * - * @see connection::links, connection::sessions - */ + /// A bit mask of state bit values. + /// + /// A state mask is matched against an endpoint as follows: If the + /// state mask contains both local and remote flags, then an exact + /// match against those flags is performed. If state contains only + /// local or only remote flags, then a match occurs if any of the + /// local or remote flags are set respectively. + /// + /// @see connection::find_links, connection::find_sessions typedef int state; - /// endpoint state bit values @{ - PN_CPP_EXTERN static const state LOCAL_UNINIT; ///< Local endpoint is un-initialized - PN_CPP_EXTERN static const state REMOTE_UNINIT; ///< Remote endpoint is un-initialized - PN_CPP_EXTERN static const state LOCAL_ACTIVE; ///< Local endpoint is active - PN_CPP_EXTERN static const state REMOTE_ACTIVE; ///< Remote endpoint is active - PN_CPP_EXTERN static const state LOCAL_CLOSED; ///< Local endpoint has been closed - PN_CPP_EXTERN static const state REMOTE_CLOSED; ///< Remote endpoint has been closed - PN_CPP_EXTERN static const state LOCAL_MASK; ///< Mask including all LOCAL_ bits (UNINIT, ACTIVE, CLOSED) - PN_CPP_EXTERN static const state REMOTE_MASK; ///< Mask including all REMOTE_ bits (UNINIT, ACTIVE, CLOSED) - ///@} + PN_CPP_EXTERN static const state LOCAL_UNINIT; ///< Local endpoint is uninitialized + PN_CPP_EXTERN static const state REMOTE_UNINIT; ///< Remote endpoint is uninitialized + PN_CPP_EXTERN static const state LOCAL_ACTIVE; ///< Local endpoint is active + PN_CPP_EXTERN static const state REMOTE_ACTIVE; ///< Remote endpoint is active + PN_CPP_EXTERN static const state LOCAL_CLOSED; ///< Local endpoint has been closed + PN_CPP_EXTERN static const state REMOTE_CLOSED; ///< Remote endpoint has been closed + PN_CPP_EXTERN static const state LOCAL_MASK; ///< Mask including all LOCAL_ bits (UNINIT, ACTIVE, CLOSED) + PN_CPP_EXTERN static const state REMOTE_MASK; ///< Mask including all REMOTE_ bits (UNINIT, ACTIVE, CLOSED) + /// Get the local error condition. virtual condition local_condition() const = 0; + + /// Get the error condition of the remote endpoint. virtual condition remote_condition() const = 0; virtual ~endpoint() {} }; -///@cond INTERNAL - +/// @cond INTERNAL +/// XXX important to expose? + template <class T> class iter_base : public comparable<iter_base<T> > { public: typedef T value_type; @@ -79,7 +79,6 @@ template <class T> class iter_base : public comparable<iter_base<T> > { T ptr_; endpoint::state state_; }; -///@endcond INTERNAL /// An iterator range. template<class I> class range { @@ -92,7 +91,9 @@ template<class I> class range { private: I begin_, end_; }; + +/// @endcond } -#endif /*!PROTON_CPP_H*/ +#endif // PROTON_CPP_H http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/error.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/error.hpp b/proton-c/bindings/cpp/include/proton/error.hpp index 3083406..d4d5622 100644 --- a/proton-c/bindings/cpp/include/proton/error.hpp +++ b/proton-c/bindings/cpp/include/proton/error.hpp @@ -21,6 +21,7 @@ * under the License. * */ + #include "proton/config.hpp" #include "proton/export.hpp" @@ -29,26 +30,55 @@ namespace proton { -/** Functions in the proton namespace throw a subclass of proton::error on error. */ -struct error : public std::runtime_error { PN_CPP_EXTERN explicit error(const std::string&); }; +/// The base proton error. +/// +/// All exceptions thrown from functions in the proton namespace are +/// subclasses of proton::error. +struct error : public std::runtime_error { + /// @cond INTERNAL + /// XXX do we intend users to construct these (and subclasses)? + PN_CPP_EXTERN explicit error(const std::string&); + /// @endcond +}; -/** Raised if timeout expires */ -struct timeout_error : public error { PN_CPP_EXTERN explicit timeout_error(const std::string&); }; +/// Raised if a timeout expires. +struct timeout_error : public error { + /// @cond INTERNAL + PN_CPP_EXTERN explicit timeout_error(const std::string&); + /// @endcond +}; -/** Raised if there is an error decoding AMQP data as a C++ value. */ -struct decode_error : public error { PN_CPP_EXTERN explicit decode_error(const std::string&); }; +/// @cond INTERNAL +/// XXX change namespace + +/// Raised if there is an error decoding AMQP data as a C++ value. +struct decode_error : public error { + PN_CPP_EXTERN explicit decode_error(const std::string&); +}; -/** Raised if there is an error encoding a C++ value as AMQP data. */ -struct encode_error : public error { PN_CPP_EXTERN explicit encode_error(const std::string&); }; +/// Raised if there is an error encoding a C++ value as AMQP data. +struct encode_error : public error { + PN_CPP_EXTERN explicit encode_error(const std::string&); +}; -/** Error reading or writing external IO. */ -struct io_error : public error { PN_CPP_EXTERN explicit io_error(const std::string&); }; +/// @endcond -/** Attempt to use a closed resource (connnection, session or link). */ +/// @cond INTERNAL +/// XXX need to discuss + +/// Error reading or writing external IO. +struct io_error : public error { + PN_CPP_EXTERN explicit io_error(const std::string&); +}; + +/// Attempt to use a closed resource (connnection, session, or link). struct closed_error : public io_error { PN_CPP_EXTERN explicit closed_error(const std::string& = default_msg); static const std::string default_msg; }; +/// @endcond + } -#endif /*!PROTON_CPP_EXCEPTIONS_H*/ + +#endif // PROTON_CPP_EXCEPTIONS_H http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/event.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/event.hpp b/proton-c/bindings/cpp/include/proton/event.hpp index 641d553..844fcab 100644 --- a/proton-c/bindings/cpp/include/proton/event.hpp +++ b/proton-c/bindings/cpp/include/proton/event.hpp @@ -21,6 +21,7 @@ * under the License. * */ + #include "proton/export.hpp" #include "proton/link.hpp" #include "proton/connection.hpp" @@ -34,15 +35,20 @@ class handler; class container; class connection; -/** Context information about a proton event */ +/// A context for a proton event. +/// +/// @see proton::handler class event { public: virtual PN_CPP_EXTERN ~event(); - /// Return the name of the event type + /// Return the name of the event type. virtual PN_CPP_EXTERN std::string name() const = 0; - /// Get the container, throw an exception this event was not generated by a container. + /// Get the container. + /// + /// @throw proton::error if this event was not generated by a + /// container virtual PN_CPP_EXTERN class container& container() const; /// Get transport @@ -51,15 +57,30 @@ class event { virtual PN_CPP_EXTERN class connection connection() const; /// Get session. virtual PN_CPP_EXTERN class session session() const; - /// Get sender @throws error if no sender. + + /// Get sender. + /// + /// @throw proton::error if no sender virtual PN_CPP_EXTERN class sender sender() const; - /// Get receiver @throws error if no receiver. + + /// Get receiver. + /// + /// @throw proton::error if no receiver virtual PN_CPP_EXTERN class receiver receiver() const; - /// Get link @throws error if no link. + + /// Get link. + /// + /// @throw proton::error if no link virtual PN_CPP_EXTERN class link link() const; - /// Get delivery @throws error if no delivery. + + /// Get delivery. + /// + /// @throw proton::error if no delivery virtual PN_CPP_EXTERN class delivery delivery() const; - /** Get message @throws error if no message. */ + + /// Get message. + /// + /// @throw proton::error if no message virtual PN_CPP_EXTERN class message &message() const; protected: @@ -70,7 +91,6 @@ class event { event& operator=(const event&); }; - } -#endif /*!PROTON_CPP_EVENT_H*/ +#endif // PROTON_CPP_EVENT_H http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/export.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/export.hpp b/proton-c/bindings/cpp/include/proton/export.hpp index fdebc6f..2eb330c 100644 --- a/proton-c/bindings/cpp/include/proton/export.hpp +++ b/proton-c/bindings/cpp/include/proton/export.hpp @@ -23,6 +23,7 @@ */ /// @cond INTERNAL + /// import/export macros #if defined(WIN32) && !defined(PN_CPP_DECLARE_STATIC) // @@ -44,6 +45,7 @@ #else # define PN_CPP_EXTERN PN_CPP_IMPORT #endif -///@endcond -#endif /*!PN_CPP_IMPORTEXPORT_H*/ +/// @endcond + +#endif // PN_CPP_IMPORTEXPORT_H http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/handler.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/handler.hpp b/proton-c/bindings/cpp/include/proton/handler.hpp index a681cff..44fad03 100644 --- a/proton-c/bindings/cpp/include/proton/handler.hpp +++ b/proton-c/bindings/cpp/include/proton/handler.hpp @@ -21,6 +21,7 @@ * under the License. * */ + #include "proton/export.hpp" #include "proton/pn_unique_ptr.hpp" @@ -31,69 +32,118 @@ class condition; class event; class messaging_adapter; -/** messaging_handler base class. Provides a simpler set of events than - * proton::proton_handler and automates some common tasks. Subclass and - * over-ride event handling member functions. - * @see proton::messaging_event for meaning of events. - */ +/// Callback functions for handling proton events. +/// +/// Subclass and override event-handling member functions. +/// +/// @see proton::event class handler { public: - /** Create a messaging_handler - *@param prefetch set flow control to automatically pre-fetch this many messages - *@param auto_accept automatically accept received messages after on_message() - *@param auto_settle automatically settle on receipt of delivery for sent messages. - *@param peer_close_is_error treat orderly remote connection close as error. - */ - PN_CPP_EXTERN handler(int prefetch=10, bool auto_accept=true, bool auto_settle=true, + /// @cond INTERNAL + /// XXX move configuration to connection or container + + /// Create a handler. + /// + /// @param prefetch set flow control to automatically pre-fetch + /// this many messages + /// + /// @param auto_accept automatically accept received messages + /// after on_message() + /// + /// @param auto_settle automatically settle on receipt of delivery + /// for sent messages + /// + /// @param peer_close_is_error treat orderly remote connection + /// close as error + PN_CPP_EXTERN handler(int prefetch=10, bool auto_accept=true, + bool auto_settle=true, bool peer_close_is_error=false); + /// @endcond + PN_CPP_EXTERN virtual ~handler(); - ///@name Over-ride these member functions to handle events - ///@{ + /// @name Event callbacks + /// + /// Override these member functions to handle events. + /// + /// @{ + + /// The event loop is starting. PN_CPP_EXTERN virtual void on_start(event &e); + /// A message is received. PN_CPP_EXTERN virtual void on_message(event &e); + /// A message can be sent. PN_CPP_EXTERN virtual void on_sendable(event &e); + /// The underlying network transport has closed. PN_CPP_EXTERN virtual void on_transport_close(event &e); + /// The underlying network transport has closed with an error + /// condition. PN_CPP_EXTERN virtual void on_transport_error(event &e); + /// The remote peer opened the connection. PN_CPP_EXTERN virtual void on_connection_open(event &e); + /// The remote peer closed the connection. PN_CPP_EXTERN virtual void on_connection_close(event &e); + /// The remote peer closed the connection with an error condition. PN_CPP_EXTERN virtual void on_connection_error(event &e); + /// The remote peer opened the session. PN_CPP_EXTERN virtual void on_session_open(event &e); + /// The remote peer closed the session. PN_CPP_EXTERN virtual void on_session_close(event &e); + /// The remote peer closed the session with an error condition. PN_CPP_EXTERN virtual void on_session_error(event &e); + /// The remote peer opened the link. PN_CPP_EXTERN virtual void on_link_open(event &e); + /// The remote peer closed the link. PN_CPP_EXTERN virtual void on_link_close(event &e); + /// The remote peer closed the link with an error condition. PN_CPP_EXTERN virtual void on_link_error(event &e); + /// The remote peer accepted an outgoing message. PN_CPP_EXTERN virtual void on_delivery_accept(event &e); + /// The remote peer rejected an outgoing message. PN_CPP_EXTERN virtual void on_delivery_reject(event &e); + /// The remote peer released an outgoing message. PN_CPP_EXTERN virtual void on_delivery_release(event &e); + /// The remote peer settled an outgoing message. PN_CPP_EXTERN virtual void on_delivery_settle(event &e); + /// The remote peer declared a transaction. PN_CPP_EXTERN virtual void on_transaction_declare(event &e); + /// The remote peer committed a transaction. PN_CPP_EXTERN virtual void on_transaction_commit(event &e); + /// The remote peer aborted a transaction. PN_CPP_EXTERN virtual void on_transaction_abort(event &e); + /// @cond INTERNAL + /// XXX settle API questions around task + /// A timer fired. PN_CPP_EXTERN virtual void on_timer(event &e); + /// @endcond + /// Fallback event handling. PN_CPP_EXTERN virtual void on_unhandled(event &e); + /// Fallback error handling. PN_CPP_EXTERN virtual void on_unhandled_error(event &e, const condition &c); - ///@} + + /// @} private: pn_unique_ptr<messaging_adapter> messaging_adapter_; + + /// @cond INTERNAL friend class container; friend class connection_engine; friend class connection_options; friend class link_options; + /// @endcond }; } -#endif /*!PROTON_CPP_MESSAGING_HANDLER_H*/ +#endif // PROTON_CPP_MESSAGING_HANDLER_H http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/io.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/io.hpp b/proton-c/bindings/cpp/include/proton/io.hpp index c4a3aa4..cf97f3b 100644 --- a/proton-c/bindings/cpp/include/proton/io.hpp +++ b/proton-c/bindings/cpp/include/proton/io.hpp @@ -1,6 +1,6 @@ - #ifndef SOCKET_IO_HPP #define SOCKET_IO_HPP + /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file @@ -24,42 +24,52 @@ namespace proton { -/** IO using sockets, file descriptors or handles. - * - * Note that you can use proton::connection_engine to communicate using AMQP - * over your own IO implementation or to integrate an existing IO framework of - * your choice. - */ +/// IO using sockets, file descriptors, or handles. + +/// Note that you can use proton::connection_engine to communicate +/// using AMQP over your own IO implementation or to integrate an +/// existing IO framework of your choice. + namespace io { -///@name Setup and tear-down IO functionality. -/// -/// Call proton::io::initialize before using any functions in the proton::io namespace. -/// Call proton::io::finalize when you are done. +/// @name Setup and teardown /// -/// You can call initialize/finalize more than once as long as they are in -/// matching pairs. Use proton::io::guard to call initialize/finalize around a scope. +/// Call proton::io::initialize before using any functions in the +/// proton::io namespace. Call proton::io::finalize when you are +/// done. /// -/// Note on POSIX systems these are no-ops, but they are required for Windows. +/// You can call initialize/finalize more than once as long as they +/// are in matching pairs. Use proton::io::guard to call +/// initialize/finalize around a scope. /// -///@{ +/// Note that on POSIX systems these are no-ops, but they are required +/// for Windows. /// -/// Initialize the proton::io subsystem +/// @{ + +/// Initialize the proton::io subsystem. PN_CPP_EXTERN void initialize(); -/// Finalize the proton::io subsystem -PN_CPP_EXTERN void finalize(); //nothrow +/// Finalize the proton::io subsystem. +PN_CPP_EXTERN void finalize(); // nothrow + +/// Use to call io::initialize and io::finalize around a scope. struct guard { guard() { initialize(); } ~guard() { finalize(); } }; -///@} +/// @} + +/// An IO resource. typedef int64_t descriptor; +/// @cond INTERNAL +/// don't know what it is PN_CPP_EXTERN extern const descriptor INVALID_DESCRIPTOR; +/// @endcond -// Return the string describing the most recent IO error. +/// Return a string describing the most recent IO error. PN_CPP_EXTERN std::string error_str(); /// Open a TCP connection to the host:port (port can be a service name or number) from a proton::url. @@ -90,6 +100,7 @@ class listener { descriptor socket_; }; +/// A connection_engine for socket-based IO. class socket_engine : public connection_engine { public: /// Wrap an open socket. Sets non-blocking mode. @@ -101,6 +112,7 @@ class socket_engine : public connection_engine { /// Get the socket descriptor. descriptor socket() const { return socket_; } + /// Start the engine. PN_CPP_EXTERN void run(); protected: http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/link.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/link.hpp b/proton-c/bindings/cpp/include/proton/link.hpp index f3c62ef..1852c61 100644 --- a/proton-c/bindings/cpp/include/proton/link.hpp +++ b/proton-c/bindings/cpp/include/proton/link.hpp @@ -21,6 +21,7 @@ * under the License. * */ + #include "proton/endpoint.hpp" #include "proton/export.hpp" #include "proton/message.hpp" @@ -37,81 +38,104 @@ class sender; class receiver; class condition; -/** Messages are transferred across a link. Base class for sender, receiver. */ -class link : public object<pn_link_t> , public endpoint -{ +/// A named channel for sending or receiving messages. It is the base +/// class for sender and receiver. +class link : public object<pn_link_t> , public endpoint { public: + /// @cond INTERNAL link(pn_link_t* l=0) : object<pn_link_t>(l) {} + /// @endcond - /* Endpoint behaviours */ + // Endpoint behaviours + /// Get the state of this link. PN_CPP_EXTERN endpoint::state state() const; + PN_CPP_EXTERN condition local_condition() const; PN_CPP_EXTERN condition remote_condition() const; - /** Locally open the link, not complete till messaging_handler::on_link_opened or - * proton_handler::link_remote_open - */ + /// Locally open the link. The operation is not complete till + /// handler::on_link_open. PN_CPP_EXTERN void open(const link_options &opts = link_options()); - /** Locally close the link, not complete till messaging_handler::on_link_closed or - * proton_handler::link_remote_close - */ + /// Locally close the link. The operation is not complete till + /// handler::on_link_close. PN_CPP_EXTERN void close(); - /** Return sender if this link is a sender, 0 if not. */ + /// Return sender if this link is a sender, 0 if not. PN_CPP_EXTERN class sender sender(); + + /// Return sender if this link is a sender, 0 if not. PN_CPP_EXTERN const class sender sender() const; - /** Return receiver if this link is a receiver, 0 if not. */ + /// Return receiver if this link is a receiver, 0 if not. PN_CPP_EXTERN class receiver receiver(); + + /// Return receiver if this link is a receiver, 0 if not. PN_CPP_EXTERN const class receiver receiver() const; - /** Credit available on the link */ + /// Credit available on the link. PN_CPP_EXTERN int credit() const; - /** The number of queued deliveries for the link */ + /// The number of deliveries queued on the link. PN_CPP_EXTERN int queued(); - /** The number of unsettled deliveries on the link */ + /// @cond INTERNAL + /// XXX ask about when this is used + /// The number of unsettled deliveries on the link. PN_CPP_EXTERN int unsettled(); + /// @endcond - /** The count of credit returned. */ + /// @cond INTERNAL + /// XXX revisit mind-melting API inherited from C PN_CPP_EXTERN int drained(); + /// @endcond - /** Local source of the link. */ + /// Local source of the link. PN_CPP_EXTERN terminus local_source() const; - /** Local target of the link. */ + + /// Local target of the link. PN_CPP_EXTERN terminus local_target() const; - /** Remote source of the link. */ + + /// Remote source of the link. PN_CPP_EXTERN terminus remote_source() const; - /** Remote target of the link. */ + + /// Remote target of the link. PN_CPP_EXTERN terminus remote_target() const; - /** Link name */ + /// Get the link name. PN_CPP_EXTERN std::string name() const; - /** Connection that owns this link */ + /// Connection that owns this link. PN_CPP_EXTERN class connection connection() const; - /** Session that owns this link */ + /// Session that owns this link. PN_CPP_EXTERN class session session() const; - /** Set a custom handler for this link. */ + /// @cond INTERNAL + /// XXX settle open questions + + /// Set a custom handler for this link. PN_CPP_EXTERN void handler(proton_handler &); - /** Unset any custom handler */ + /// Unset any custom handler. PN_CPP_EXTERN void detach_handler(); - /** Get message data from current delivery on link */ + /// @cond INTERNAL + + /// XXX ask about use case, revisit names + /// Get message data from current delivery on link. PN_CPP_EXTERN ssize_t recv(char* buffer, size_t size); - /** Advance the link one delivery */ + /// XXX ask about use case, revisit names + /// Advance the link one delivery. PN_CPP_EXTERN bool advance(); - /** Navigate the links in a connection - get next link with state */ + /// XXX remove + /// Navigate the links in a connection - get next link with state. PN_CPP_EXTERN link next(endpoint::state) const; + /// XXX local versus remote, mutability PN_CPP_EXTERN link_options::sender_settle_mode sender_settle_mode(); PN_CPP_EXTERN void sender_settle_mode(link_options::sender_settle_mode); PN_CPP_EXTERN link_options::receiver_settle_mode receiver_settle_mode(); @@ -119,8 +143,11 @@ class link : public object<pn_link_t> , public endpoint PN_CPP_EXTERN link_options::sender_settle_mode remote_sender_settle_mode(); PN_CPP_EXTERN link_options::receiver_settle_mode remote_receiver_settle_mode(); + /// @endcond }; +/// @cond INTERNAL +/// XXX important to expose? /// An iterator for links. class link_iterator : public iter_base<link> { public: @@ -134,12 +161,14 @@ class link_iterator : public iter_base<link> { private: const session* session_; }; +/// @endcond /// A range of links. typedef range<link_iterator> link_range; + } #include "proton/sender.hpp" #include "proton/receiver.hpp" -#endif /*!PROTON_CPP_LINK_H*/ +#endif // PROTON_CPP_LINK_H http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/link_options.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/link_options.hpp b/proton-c/bindings/cpp/include/proton/link_options.hpp index 085d512..932e8b3 100644 --- a/proton-c/bindings/cpp/include/proton/link_options.hpp +++ b/proton-c/bindings/cpp/include/proton/link_options.hpp @@ -21,6 +21,7 @@ * under the License. * */ + #include "proton/config.hpp" #include "proton/export.hpp" #include "proton/pn_unique_ptr.hpp" @@ -35,106 +36,146 @@ namespace proton { class proton_handler; class link; -/** Options for creating a link. - * - * Options can be "chained" like this: - * - * l = container.create_sender(url, link_options().handler(h).browsing(true)); - * - * 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: - * - * link_options opts; - * opts.browsing(true); - * l1 = container.open_sender(url1, opts.handler(h1)); - * c2 = container.open_receiver(url2, opts.handler(h2)); - * - * Normal value semantics, copy or assign creates a separate copy of the options. - */ +/// Options for creating a link. +/// +/// Options can be "chained" like this: +/// +/// @code +/// l = container.create_sender(url, link_options().handler(h).browsing(true)); +/// @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 +/// link_options opts; +/// opts.browsing(true); +/// l1 = container.open_sender(url1, opts.handler(h1)); +/// c2 = container.open_receiver(url2, opts.handler(h2)); +/// @endcode +/// +/// Normal value semantics: copy or assign creates a separate copy of +/// the options. class link_options { public: - /** The message delivery policy to establish when opening a link. */ + /// The message delivery policy to establish when opening a link. enum delivery_mode { - // No set policy. The application must settle messages itself according to its own policy. + // No set policy. The application must settle messages itself + // according to its own policy. DELIVERY_MODE_NONE = 0, - // Outgoing messages are settled immediately by the link. There are no duplicates. + // Outgoing messages are settled immediately by the link. + // There are no duplicates. AT_MOST_ONCE, - // The receiver settles the delivery first with an accept/reject/release disposition. - // The sender waits to settle until after the disposition notification is received. + // The receiver settles the delivery first with an + // accept/reject/release disposition. The sender waits to + // settle until after the disposition notification is + // received. AT_LEAST_ONCE }; - /// Sender settlement behaviour for a link + /// Sender settlement behaviour for a link. enum sender_settle_mode { UNSETTLED = PN_SND_UNSETTLED, SETTLED = PN_SND_SETTLED, MIXED = PN_SND_MIXED }; - /// Receiver settlement behaviour for a link + /// @cond INTERNAL + /// XXX discuss the names + /// Receiver settlement behaviour for a link. enum receiver_settle_mode { SETTLE_ALWAYS = PN_RCV_FIRST, SETTLE_SECOND= PN_RCV_SECOND }; + /// @endcond - /** The lifetime of dynamically created nodes. */ + /// The lifetime of dynamically created nodes. enum lifetime_policy { // The policy is unspecified. LIFETIME_UNSPECIFIED = 0, - // The lifetime of the dynamic node is scoped to lifetime of the creating link. + // The lifetime of the dynamic node is scoped to lifetime of + // the creating link. DELETE_ON_CLOSE = 0x2B, - // The node will be deleted when it is neither the source nor the target of any link. + // The node will be deleted when it is neither the source nor + // the target of any link. DELETE_ON_NO_LINKS = 0x2C, - // The node will be deleted when the creating link no longer exists and no messages remain at the node. + // The node will be deleted when the creating link no longer + // exists and no messages remain at the node. DELETE_ON_NO_MESSAGES = 0x2D, - // The node will be deleted when there are no links which have this node as - // their source or target, and there remain no messages at the node. + // The node will be deleted when there are no links which have + // this node as their source or target, and there remain no + // messages at the node. DELETE_ON_NO_LINKS_OR_MESSAGES = 0x2E }; - + /// Create an empty set of options. PN_CPP_EXTERN link_options(); + + /// Copy options. PN_CPP_EXTERN link_options(const link_options&); + PN_CPP_EXTERN ~link_options(); + + /// Copy options. PN_CPP_EXTERN link_options& operator=(const link_options&); /// Override with options from other. PN_CPP_EXTERN void override(const link_options& other); - /** Set a handler for events scoped to the link. If NULL, link-scoped events on the link are discarded. */ + /// Set a handler for events scoped to the link. If NULL, + /// link-scoped events on the link are discarded. PN_CPP_EXTERN link_options& handler(class handler *); - /** Receiver-only option to specify whether messages are browsed or - consumed. Setting browsing to true is Equivalent to setting - distribution_mode(COPY). Setting browsing to false is equivalent to - setting distribution_mode(MOVE). */ + + /// Receiver-only option to specify whether messages are browsed + /// or consumed. Setting browsing to true is equivalent to + /// setting distribution_mode(COPY). Setting browsing to false is + /// equivalent to setting distribution_mode(MOVE). PN_CPP_EXTERN link_options& browsing(bool); - /** Set the distribution mode for message transfer. See terminus::distribution_mode. */ + + /// Set the distribution mode for message transfer. PN_CPP_EXTERN link_options& distribution_mode(enum terminus::distribution_mode); - /* Receiver-only option to create a durable subsription on the receiver. - Equivalent to setting the terminus durability to termins::DELIVERIES and - the expiry policy to terminus::EXPIRE_NEVER. */ + + /// Receiver-only option to create a durable subsription on the + /// receiver. Equivalent to setting the terminus durability to + /// terminus::DELIVERIES and the expiry policy to + /// terminus::EXPIRE_NEVER. PN_CPP_EXTERN link_options& durable_subscription(bool); - /* Set the delivery mode on the link. */ + + /// Set the delivery mode on the link. PN_CPP_EXTERN link_options& delivery_mode(delivery_mode); - /* Request a dynamically generated node at the peer. */ + + /// Request a dynamically generated node at the peer. PN_CPP_EXTERN link_options& dynamic_address(bool); - /* Set the lifetime policy for a receiver to a dynamically created node. */ + + /// Set the lifetime policy for a receiver to a dynamically + /// created node. PN_CPP_EXTERN link_options& lifetime_policy(lifetime_policy); - /* Set the local address for the link. */ + + /// Set the local address for the link. PN_CPP_EXTERN link_options& local_address(const std::string &addr); - /* Set a selector on the receiver to str. This sets a single registered filter on the link of - type apache.org:selector-filter with value str. */ + + /// @cond INTERNAL + /// XXX need to discuss spec issues, jms versus amqp filters + /// + /// Set a selector on the receiver to str. This sets a single + /// registered filter on the link of type + /// apache.org:selector-filter with value str. PN_CPP_EXTERN link_options& selector(const std::string &str); + /// @endcond private: - friend class link; void apply(link&) const; proton_handler* handler() const; class impl; pn_unique_ptr<impl> impl_; + + /// @cond INTERNAL + friend class link; + /// @endcond }; -} // namespace +} -#endif /*!PROTON_CPP_LINK_OPTIONS_H*/ +#endif // PROTON_CPP_LINK_OPTIONS_H http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/message.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/message.hpp b/proton-c/bindings/cpp/include/proton/message.hpp index aeabbcb..645da86 100644 --- a/proton-c/bindings/cpp/include/proton/message.hpp +++ b/proton-c/bindings/cpp/include/proton/message.hpp @@ -42,198 +42,222 @@ class delivery; class message_id; class annotation_key; -/** An AMQP message. Value semantics, can be copied or assigned to make a new message. */ -class message -{ +/// An AMQP message. +/// +/// Value semantics: can be copied or assigned to make a new message. +class message { public: + /// A map of string keys and AMQP scalar values. typedef std::map<std::string, scalar> property_map; + + /// A map of AMQP annotation keys and AMQP values. typedef std::map<annotation_key, value> annotation_map; + /// Create an empty message. PN_CPP_EXTERN message(); + + /// Copy a message. PN_CPP_EXTERN message(const message&); + #if PN_HAS_CPP11 PN_CPP_EXTERN message(message&&); #endif - /// Construct a message from any value that can be assigned to a proton::value - template <class T> message(const T& x) : pn_msg_(0) { body() = x; } + /// Create a message with its body set from any value that can be + /// assigned to a proton::value. + template <class T> message(const T& x) : pn_msg_(0) { body() = x; } PN_CPP_EXTERN ~message(); + /// Copy a message. PN_CPP_EXTERN message& operator=(const message&); - /** Clear the message content and properties. */ - PN_CPP_EXTERN void clear(); + /// @name Basic properties and methods + /// @{ - ///@name Standard AMQP message properties - ///@{ + /// Clear the message content and properties. + PN_CPP_EXTERN void clear(); PN_CPP_EXTERN void id(const message_id& id); PN_CPP_EXTERN message_id id() const; + /// @cond INTERNAL + /// XXX consider just user, in order to be consistent with similar + /// fields elsewhere in the API PN_CPP_EXTERN void user_id(const std::string &user); PN_CPP_EXTERN std::string user_id() const; + /// @endcond - PN_CPP_EXTERN void address(const std::string &addr); - PN_CPP_EXTERN std::string address() const; - - PN_CPP_EXTERN void subject(const std::string &s); - PN_CPP_EXTERN std::string subject() const; + /// Encode entire message into a byte vector, growing it if + /// necessary. + PN_CPP_EXTERN void encode(std::vector<char> &bytes) const; - PN_CPP_EXTERN void reply_to(const std::string &s); - PN_CPP_EXTERN std::string reply_to() const; + /// Return encoded message as a byte vector. + PN_CPP_EXTERN std::vector<char> encode() const; - PN_CPP_EXTERN void correlation_id(const message_id&); - PN_CPP_EXTERN message_id correlation_id() const; + /// Decode from string data into the message. + PN_CPP_EXTERN void decode(const std::vector<char> &bytes); - PN_CPP_EXTERN void content_type(const std::string &s); - PN_CPP_EXTERN std::string content_type() const; + /// @cond INTERNAL + /// XXX should a delivery know its own link already? + /// + /// Decode the message corresponding to a delivery from a link. + PN_CPP_EXTERN void decode(proton::link, proton::delivery); + /// @endcond - PN_CPP_EXTERN void content_encoding(const std::string &s); - PN_CPP_EXTERN std::string content_encoding() const; + /// @} - PN_CPP_EXTERN void expiry_time(amqp_timestamp t); - PN_CPP_EXTERN amqp_timestamp expiry_time() const; + /// @name Routing + /// @{ - PN_CPP_EXTERN void creation_time(amqp_timestamp t); - PN_CPP_EXTERN amqp_timestamp creation_time() const; + PN_CPP_EXTERN void address(const std::string &addr); + PN_CPP_EXTERN std::string address() const; + + PN_CPP_EXTERN void reply_to(const std::string &addr); + PN_CPP_EXTERN std::string reply_to() const; - PN_CPP_EXTERN void group_id(const std::string &s); - PN_CPP_EXTERN std::string group_id() const; + PN_CPP_EXTERN void correlation_id(const message_id&); + PN_CPP_EXTERN message_id correlation_id() const; - PN_CPP_EXTERN void reply_to_group_id(const std::string &s); - PN_CPP_EXTERN std::string reply_to_group_id() const; + /// @} - ///@} + /// @name Content + /// @{ - /** Set the body, equivalent to body() = v */ + /// Set the body, equivalent to body() = v template<class T> void body(const T& v) { body() = v; } - /** Get the body. */ + /// Get the body. PN_CPP_EXTERN const value& body() const; - /** Get a reference to the body that can be modified in-place. */ + /// Get a reference to the body that can be modified in-place. PN_CPP_EXTERN value& body(); - /** Application properties map, can be modified in place. */ - PN_CPP_EXTERN property_map& application_properties(); - PN_CPP_EXTERN const property_map& application_properties() const; - - /** Message annotations map, can be modified in place. */ - PN_CPP_EXTERN annotation_map& message_annotations(); - PN_CPP_EXTERN const annotation_map& message_annotations() const; - - /** Delivery annotations map, can be modified in place. */ - PN_CPP_EXTERN annotation_map& delivery_annotations(); - PN_CPP_EXTERN const annotation_map& delivery_annotations() const; + PN_CPP_EXTERN void subject(const std::string &s); + PN_CPP_EXTERN std::string subject() const; - /** Encode entire message into a byte vector, growing it if necessary. */ - PN_CPP_EXTERN void encode(std::vector<char> &bytes) const; + PN_CPP_EXTERN void content_type(const std::string &s); + PN_CPP_EXTERN std::string content_type() const; - /** Return encoded message as a byte vector */ - PN_CPP_EXTERN std::vector<char> encode() const; + PN_CPP_EXTERN void content_encoding(const std::string &s); + PN_CPP_EXTERN std::string content_encoding() const; - /** Decode from string data into the message. */ - PN_CPP_EXTERN void decode(const std::vector<char> &bytes); + PN_CPP_EXTERN void expiry_time(amqp_timestamp t); + PN_CPP_EXTERN amqp_timestamp expiry_time() const; - /** Decode the message corresponding to a delivery from a link. */ - PN_CPP_EXTERN void decode(proton::link, proton::delivery); + PN_CPP_EXTERN void creation_time(amqp_timestamp t); + PN_CPP_EXTERN amqp_timestamp creation_time() const; - /** - * Get the inferred flag for a message. - * - * The inferred flag for a message indicates how the message content - * is encoded into AMQP sections. If inferred is true then binary and - * list values in the body of the message will be encoded as AMQP DATA - * and AMQP SEQUENCE sections, respectively. If inferred is false, - * then all values in the body of the message will be encoded as AMQP - * VALUE sections regardless of their type. - */ + /// Get the inferred flag for a message. + /// + /// The inferred flag for a message indicates how the message + /// content is encoded into AMQP sections. If inferred is true + /// then binary and list values in the body of the message will be + /// encoded as AMQP DATA and AMQP SEQUENCE sections, + /// respectively. If inferred is false, then all values in the + /// body of the message will be encoded as AMQP VALUE sections + /// regardless of their type. PN_CPP_EXTERN bool inferred() const; - /** Get the inferred flag for a message. */ + /// Set the inferred flag for a message. PN_CPP_EXTERN void inferred(bool); - /** - * Get the durable flag for a message. - * - * The durable flag indicates that any parties taking responsibility - * for the message must durably store the content. - * - * @return the value of the durable flag - */ + /// @} + + /// @name Transfer headers + /// @{ + + /// Get the durable flag for a message. + /// + /// The durable flag indicates that any parties taking + /// responsibility for the message must durably store the content. + /// + /// @return the value of the durable flag PN_CPP_EXTERN bool durable() const; - /** Set the durable flag for a message. */ + /// Set the durable flag for a message. PN_CPP_EXTERN void durable(bool); - /** - * Get the ttl for a message. - * - * The ttl for a message determines how long a message is considered - * live. When a message is held for retransmit, the ttl is - * decremented. Once the ttl reaches zero, the message is considered - * dead. Once a message is considered dead it may be dropped. - * - * @return the ttl in milliseconds - */ + /// Get the TTL for a message. + /// + /// The TTL (time to live) for a message determines how long a + /// message is considered live. When a message is held for + /// retransmit, the TTL is decremented. Once the TTL reaches zero, + /// the message is considered dead. Once a message is considered + /// dead it may be dropped. PN_CPP_EXTERN duration ttl() const; - /** Set the ttl for a message */ + + /// Set the TTL for a message. PN_CPP_EXTERN void ttl(duration); - /** - * Get the priority for a message. - * - * The priority of a message impacts ordering guarantees. Within a - * given ordered context, higher priority messages may jump ahead of - * lower priority messages. - * - * @return the message priority - */ + /// Get the priority for a message. + /// + /// The priority of a message impacts ordering guarantees. Within + /// a given ordered context, higher priority messages may jump + /// ahead of lower priority messages. PN_CPP_EXTERN uint8_t priority() const; - /** Set the priority for a message. */ + + /// Set the priority for a message. PN_CPP_EXTERN void priority(uint8_t); - /** - * Get the first acquirer flag for a message. - * - * When set to true, the first acquirer flag for a message indicates - * that the recipient of the message is the first recipient to acquire - * the message, i.e. there have been no failed delivery attempts to - * other acquirers. Note that this does not mean the message has not - * been delivered to, but not acquired, by other recipients. - * - * @return the first acquirer flag for the message - */ + /// Get the first acquirer flag for a message. + /// + /// When set to true, the first acquirer flag for a message + /// indicates that the recipient of the message is the first + /// recipient to acquire the message, i.e. there have been no + /// failed delivery attempts to other acquirers. Note that this + /// does not mean the message has not been delivered to, but not + /// acquired, by other recipients. PN_CPP_EXTERN bool first_acquirer() const; - /** Set the first acquirer flag for a message. */ + + /// Set the first acquirer flag for a message. PN_CPP_EXTERN void first_acquirer(bool); - /** - * Get the delivery count for a message. - * - * The delivery count field tracks how many attempts have been made to - * delivery a message. - * - * @return the delivery count for the message - */ + /// Get the delivery count for a message. + /// + /// The delivery count field tracks how many attempts have been made to + /// delivery a message. PN_CPP_EXTERN uint32_t delivery_count() const; - /** Get the delivery count for a message. */ + + /// Get the delivery count for a message. PN_CPP_EXTERN void delivery_count(uint32_t); - /** - * Get the group sequence for a message. - * - * The group sequence of a message identifies the relative ordering of - * messages within a group. The default value for the group sequence - * of a message is zero. - * - * @return the group sequence for the message - */ + /// @} + + /// @name Message groups + /// @{ + + PN_CPP_EXTERN void group_id(const std::string &s); + PN_CPP_EXTERN std::string group_id() const; + + PN_CPP_EXTERN void reply_to_group_id(const std::string &s); + PN_CPP_EXTERN std::string reply_to_group_id() const; + + /// Get the group sequence for a message. + /// + /// The group sequence of a message identifies the relative + /// ordering of messages within a group. The default value for the + /// group sequence of a message is zero. PN_CPP_EXTERN int32_t group_sequence() const; - /** Set the group sequence for a message. */ + /// Set the group sequence for a message. PN_CPP_EXTERN void group_sequence(int32_t); + /// @} + + /// @name Extended attributes + /// @{ - friend PN_CPP_EXTERN void swap(message&, message&); + /// Application properties map, can be modified in place. + PN_CPP_EXTERN property_map& application_properties(); + PN_CPP_EXTERN const property_map& application_properties() const; + + /// Message annotations map, can be modified in place. + PN_CPP_EXTERN annotation_map& message_annotations(); + PN_CPP_EXTERN const annotation_map& message_annotations() const; + + /// Delivery annotations map, can be modified in place. + PN_CPP_EXTERN annotation_map& delivery_annotations(); + PN_CPP_EXTERN const annotation_map& delivery_annotations() const; + + /// @} private: pn_message_t *pn_msg() const; @@ -243,8 +267,13 @@ class message mutable property_map application_properties_; mutable annotation_map message_annotations_; mutable annotation_map delivery_annotations_; + + /// @cond INTERNAL + /// XXX settle necessity (there were some other options) + friend PN_CPP_EXTERN void swap(message&, message&); + /// @endcond }; } -#endif /*!PROTON_CPP_MESSAGE_H*/ +#endif // PROTON_CPP_MESSAGE_H http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/message_id.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/message_id.hpp b/proton-c/bindings/cpp/include/proton/message_id.hpp index b08482f..0adef07 100644 --- a/proton-c/bindings/cpp/include/proton/message_id.hpp +++ b/proton-c/bindings/cpp/include/proton/message_id.hpp @@ -1,5 +1,6 @@ #ifndef MESSAGE_ID_HPP #define MESSAGE_ID_HPP + /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file @@ -23,18 +24,28 @@ #include "proton/scalar.hpp" namespace proton { + class encoder; class decoder; -/** A message_id can contain one of the following types: - * uint64_t, amqp_uuid, amqp_binary or amqp_string. - */ +/// An AMQP message ID. +/// +/// It can contain one of the following types: +/// +/// - uint64_t +/// - proton::amqp::amqp_uuid +/// - proton::amqp::amqp_binary +/// - proton::amqp::amqp_string class message_id : public restricted_scalar { public: + /// Create an empty (0) message ID. message_id() { scalar_ = uint64_t(0); } - ///@name Assign a C++ value, deduce the AMQP type() - ///@{ + /// @name Assignment operators + /// + /// Assign a C++ value, deduce the AMQP type() + /// + /// @{ message_id& operator=(uint64_t x) { scalar_ = x; return *this; } message_id& operator=(const amqp_uuid& x) { scalar_ = x; return *this; } message_id& operator=(const amqp_binary& x) { scalar_ = x; return *this; } @@ -43,21 +54,31 @@ class message_id : public restricted_scalar { message_id& operator=(const std::string& x) { scalar_ = amqp_string(x); return *this; } /// char* is encoded as amqp_string message_id& operator=(const char *x) { scalar_ = amqp_string(x); return *this; } - ///@} + /// @} - /// Converting constructor from any type that we can assign from. + /// Create a message ID from any type that we can assign from. template <class T> message_id(T x) { *this = x; } + /// @name Get methods + /// + /// get(T&) extracts the value if the types match exactly and + /// throws type_error otherwise. + /// + /// @{ void get(uint64_t& x) const { scalar_.get(x); } void get(amqp_uuid& x) const { scalar_.get(x); } void get(amqp_binary& x) const { scalar_.get(x); } void get(amqp_string& x) const { scalar_.get(x); } + /// @} + /// Return the value as type T. template<class T> T get() const { T x; get(x); return x; } - friend PN_CPP_EXTERN encoder operator<<(encoder, const message_id&); - friend PN_CPP_EXTERN decoder operator>>(decoder, message_id&); - friend class message; + /// @cond INTERNAL + friend PN_CPP_EXTERN encoder operator<<(encoder, const message_id&); + friend PN_CPP_EXTERN decoder operator>>(decoder, message_id&); + friend class message; + /// @endcond }; } http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/object.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/object.hpp b/proton-c/bindings/cpp/include/proton/object.hpp index cc2bd31..4e12e6f 100644 --- a/proton-c/bindings/cpp/include/proton/object.hpp +++ b/proton-c/bindings/cpp/include/proton/object.hpp @@ -1,5 +1,6 @@ #ifndef OBJECT_HPP #define OBJECT_HPP + /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file @@ -19,6 +20,8 @@ * under the License. */ +/// @cond INTERNAL + #include "proton/config.hpp" #include "proton/export.hpp" #include "proton/comparable.hpp" @@ -26,7 +29,6 @@ namespace proton { -///@cond INTERNAL class pn_ptr_base { protected: PN_CPP_EXTERN static void incref(void* p); @@ -51,9 +53,6 @@ template <class T> class pn_ptr : private pn_ptr_base, public comparable<pn_ptr< T* release() { T *p = ptr_; ptr_ = 0; return p; } bool operator!() const { return !ptr_; } - friend bool operator==(const pn_ptr& a, const pn_ptr& b) { return a.ptr_ == b.ptr_; } - friend bool operator<(const pn_ptr& a, const pn_ptr& b) { return a.ptr_ < b.ptr_; } - static pn_ptr take_ownership(T* p) { return pn_ptr<T>(p, true); } private: @@ -62,29 +61,31 @@ template <class T> class pn_ptr : private pn_ptr_base, public comparable<pn_ptr< // Note that it is the presence of the bool in the constructor signature that matters // to get the "transfer ownership" constructor: The value of the bool isn't checked. pn_ptr(T* p, bool) : ptr_(p) {} + + friend bool operator==(const pn_ptr& a, const pn_ptr& b) { return a.ptr_ == b.ptr_; } + friend bool operator<(const pn_ptr& a, const pn_ptr& b) { return a.ptr_ < b.ptr_; } }; template <class T> pn_ptr<T> take_ownership(T* p) { return pn_ptr<T>::take_ownership(p); } -///@endcond INTERNAL - -/** - * Base class for proton object types - */ +/// Base class for proton object types. template <class T> class object : public comparable<object<T> > { public: bool operator!() const { return !object_; } - friend bool operator==(const object& a, const object& b) { return a.object_ == b.object_; } - friend bool operator<(const object& a, const object& b) { return a.object_ < b.object_; } - protected: object(pn_ptr<T> o) : object_(o) {} T* pn_object() const { return object_.get(); } private: pn_ptr<T> object_; + + friend bool operator==(const object& a, const object& b) { return a.object_ == b.object_; } + friend bool operator<(const object& a, const object& b) { return a.object_ < b.object_; } }; } + +/// @endcond + #endif // OBJECT_HPP http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/pn_unique_ptr.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/pn_unique_ptr.hpp b/proton-c/bindings/cpp/include/proton/pn_unique_ptr.hpp index 6533b0b..12636eb 100644 --- a/proton-c/bindings/cpp/include/proton/pn_unique_ptr.hpp +++ b/proton-c/bindings/cpp/include/proton/pn_unique_ptr.hpp @@ -19,21 +19,22 @@ * under the License. */ +/// @cond INTERNAL +/// XXX discuss where this gets exposed + #include "proton/config.hpp" #include <memory> namespace proton { -/** - * A simple unique ownership pointer, used as a return value from functions that - * transfer ownership to the caller. - * - * pn_unique_ptr return values should be converted immediately to - * std::unique_ptr if that is available or std::auto_ptr (by calling release()) - * for older C++. You should not use pn_unique_ptr in your own code, it is a - * limited pointer class designed only to work around differences between C++11 - * and C++03. - */ +/// A simple unique ownership pointer, used as a return value from +/// functions that transfer ownership to the caller. +/// +/// pn_unique_ptr return values should be converted immediately to +/// std::unique_ptr if that is available or std::auto_ptr (by calling +/// release()) for older C++. You should not use pn_unique_ptr in your +/// own code. It is a limited pointer class designed only to work +/// around differences between C++11 and C++03. template <class T> class pn_unique_ptr { public: pn_unique_ptr(T* p=0) : ptr_(p) {} @@ -59,5 +60,8 @@ template <class T> class pn_unique_ptr { T* ptr_; }; +/// @endcond + } + #endif // UNIQUE_PTR_HPP http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/reactor.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/reactor.hpp b/proton-c/bindings/cpp/include/proton/reactor.hpp index 7592a14..8251405 100644 --- a/proton-c/bindings/cpp/include/proton/reactor.hpp +++ b/proton-c/bindings/cpp/include/proton/reactor.hpp @@ -1,5 +1,6 @@ #ifndef REACTOR_HPP #define REACTOR_HPP + /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file @@ -19,6 +20,9 @@ * under the License. */ +/// @cond INTERNAL +/// XXX remove + #include "proton/object.hpp" #include "proton/duration.hpp" @@ -91,4 +95,7 @@ class reactor : public object<pn_reactor_t> { }; } + +/// @endcond + #endif // REACTOR_HPP http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/receiver.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/receiver.hpp b/proton-c/bindings/cpp/include/proton/receiver.hpp index d0df703..11569e4 100644 --- a/proton-c/bindings/cpp/include/proton/receiver.hpp +++ b/proton-c/bindings/cpp/include/proton/receiver.hpp @@ -21,6 +21,7 @@ * under the License. * */ + #include "proton/export.hpp" #include "proton/endpoint.hpp" #include "proton/link.hpp" @@ -31,11 +32,12 @@ struct pn_connection_t; namespace proton { -/// A receiving link -class receiver : public link -{ +/// A link for receiving messages. +class receiver : public link { public: + /// @cond INTERNAL receiver(pn_link_t* r=0) : link(r) {} + /// @endcond /// Add credit to the link PN_CPP_EXTERN void flow(int count); @@ -43,4 +45,4 @@ class receiver : public link } -#endif /*!PROTON_CPP_RECEIVER_H*/ +#endif // PROTON_CPP_RECEIVER_H http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/reconnect_timer.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/reconnect_timer.hpp b/proton-c/bindings/cpp/include/proton/reconnect_timer.hpp index f89f47e..d7b720f 100644 --- a/proton-c/bindings/cpp/include/proton/reconnect_timer.hpp +++ b/proton-c/bindings/cpp/include/proton/reconnect_timer.hpp @@ -22,6 +22,9 @@ * */ +/// @cond INTERNAL +/// XXX more discussion + #include "proton/export.hpp" #include "proton/types.hpp" #include "proton/reactor.hpp" @@ -55,9 +58,12 @@ class reconnect_timer int32_t next_delay_; pn_timestamp_t timeout_deadline_; reactor reactor_; + friend class connector; }; +/// @endcond + } -#endif /*!PROTON_CPP_RECONNECT_H*/ +#endif // PROTON_CPP_RECONNECT_H http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/sasl.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/sasl.hpp b/proton-c/bindings/cpp/include/proton/sasl.hpp index 98cfea7..53052d7 100644 --- a/proton-c/bindings/cpp/include/proton/sasl.hpp +++ b/proton-c/bindings/cpp/include/proton/sasl.hpp @@ -21,40 +21,59 @@ * under the License. * */ + #include "proton/export.hpp" #include "proton/sasl.h" #include <string> namespace proton { +/// SASL information. class sasl { public: - /** The result of the SASL negotiation */ + /// The result of the SASL negotiation. enum outcome { - NONE = PN_SASL_NONE, /** negotiation not completed */ - OK = PN_SASL_OK, /** authentication succeeded */ - AUTH = PN_SASL_AUTH, /** failed due to bad credentials */ - SYS = PN_SASL_SYS, /** failed due to a system error */ - PERM = PN_SASL_PERM, /** failed due to unrecoverable error */ - TEMP = PN_SASL_TEMP /** failed due to transient error */ + NONE = PN_SASL_NONE, ///< Negotiation not completed + OK = PN_SASL_OK, ///< Authentication succeeded + AUTH = PN_SASL_AUTH, ///< Failed due to bad credentials + SYS = PN_SASL_SYS, ///< Failed due to a system error + PERM = PN_SASL_PERM, ///< Failed due to unrecoverable error + TEMP = PN_SASL_TEMP ///< Failed due to transient error }; + /// @cond INTERNAL + /// XXX need to discuss sasl(pn_sasl_t* s) : object_(s) {} PN_CPP_EXTERN static bool extended(); PN_CPP_EXTERN void done(enum outcome); + /// @endcond + + /// Get the outcome. PN_CPP_EXTERN enum outcome outcome() const; + + /// Get the user name. PN_CPP_EXTERN std::string user() const; + + /// Get the mechanism. PN_CPP_EXTERN std::string mech() const; + /// @cond INTERNAL PN_CPP_EXTERN void allow_insecure_mechs(bool); + /// @endcond + + /// True if insecure mechanisms are permitted. PN_CPP_EXTERN bool allow_insecure_mechs(); + + /// @cond INTERNAL + /// XXX setters? versus connection options PN_CPP_EXTERN void allowed_mechs(const std::string &); PN_CPP_EXTERN void config_name(const std::string&); PN_CPP_EXTERN void config_path(const std::string&); + /// @endcond private: pn_sasl_t* object_; }; } -#endif /*!PROTON_CPP_SASL_H*/ +#endif // PROTON_CPP_SASL_H http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/scalar.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/scalar.hpp b/proton-c/bindings/cpp/include/proton/scalar.hpp index c06a675..3975301 100644 --- a/proton-c/bindings/cpp/include/proton/scalar.hpp +++ b/proton-c/bindings/cpp/include/proton/scalar.hpp @@ -1,5 +1,6 @@ #ifndef SCALAR_HPP #define SCALAR_HPP + /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file @@ -30,11 +31,16 @@ namespace proton { class encoder; class decoder; -/** scalar holds an instance of any scalar AMQP type. */ +/// A holder for an instance of any scalar AMQP type. class scalar : public comparable<scalar> { public: + /// Create an empty scalar. PN_CPP_EXTERN scalar(); + + /// Copy a scalar. PN_CPP_EXTERN scalar(const scalar&); + + /// Copy a scalar. PN_CPP_EXTERN scalar& operator=(const scalar&); /// Type for the value in the scalar, NULL_TYPE if empty() @@ -43,8 +49,11 @@ class scalar : public comparable<scalar> { /// True if the scalar is empty. PN_CPP_EXTERN bool empty() const; - ///@name Assign a C++ value, deduce the AMQP type() - ///@{ + /// @name Assignment operators + /// + /// Assign a C++ value and deduce the AMQP type(). + /// + /// @{ PN_CPP_EXTERN scalar& operator=(bool); PN_CPP_EXTERN scalar& operator=(uint8_t); PN_CPP_EXTERN scalar& operator=(int8_t); @@ -67,13 +76,17 @@ class scalar : public comparable<scalar> { PN_CPP_EXTERN scalar& operator=(const amqp_binary&); PN_CPP_EXTERN scalar& operator=(const std::string& s); ///< Treated as an AMQP string PN_CPP_EXTERN scalar& operator=(const char* s); ///< Treated as an AMQP string - ///@} + /// @} - /// Construct from any type that we can assign from. + /// Create a scalar from any type that we can assign from. template <class T> explicit scalar(T x) { *this = x; } - ///@name get(T&) extracts the value if the types match exactly, throws type_error otherwise. - ///@{ + /// @name Get methods + /// + /// get(T&) extracts the value if the types match exactly and + /// throws type_error otherwise. + /// + /// @{ PN_CPP_EXTERN void get(bool&) const; PN_CPP_EXTERN void get(uint8_t&) const; PN_CPP_EXTERN void get(int8_t&) const; @@ -95,25 +108,30 @@ class scalar : public comparable<scalar> { PN_CPP_EXTERN void get(amqp_symbol&) const; PN_CPP_EXTERN void get(amqp_binary&) const; PN_CPP_EXTERN void get(std::string&) const; ///< Treated as an AMQP string - ///@} + /// @} - ///@ get<T>() is like get(T&) but returns the value.. + /// get<T>() is like get(T&) but returns the value. template<class T> T get() const { T x; get(x); return x; } - ///@name as_ methods do "loose" conversion, they will convert the scalar's - ///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()) + /// @name As methods + /// + /// As methods do "loose" conversion. They will convert the + /// scalar's 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 + friend PN_CPP_EXTERN std::ostream& operator<<(std::ostream&, const scalar&); friend PN_CPP_EXTERN encoder operator<<(encoder, const scalar&); friend PN_CPP_EXTERN decoder operator>>(decoder, scalar&); - /// Scalars with different type() are considered unequal even if the values /// are equal as numbers or strings. friend PN_CPP_EXTERN bool operator==(const scalar& x, const scalar& y); @@ -121,6 +139,8 @@ class scalar : public comparable<scalar> { /// For scalars of different type(), operator< sorts by order of type(). friend PN_CPP_EXTERN bool operator<(const scalar& x, const scalar& y); + /// @endcond + private: void ok(pn_type_t) const; void set(const std::string&, pn_type_t); @@ -131,29 +151,39 @@ class scalar : public comparable<scalar> { friend class message; }; -///@internal base for restricted scalar types +/// @cond INTERNAL +/// XXX should it be public? + +/// Base class for restricted scalar types. class restricted_scalar : public comparable<restricted_scalar> { public: operator const scalar&() const { return scalar_; } type_id type() const { return scalar_.type(); } - ///@name as_ methods do "loose" conversion, they will convert the scalar's - ///value to the requested type if possible, else throw type_error - ///@{ + /// @name As methods + /// + /// As methods do "loose" conversion. They will convert the + /// scalar's value to the requested type if possible, else throw + /// type_error. + /// + /// @{ int64_t as_int() const { return scalar_.as_int(); } uint64_t as_uint() const { return scalar_.as_uint(); } double as_double() const { return scalar_.as_double(); } std::string as_string() const { return scalar_.as_string(); } - ///@} - - friend std::ostream& operator<<(std::ostream& o, const restricted_scalar& x) { return o << x.scalar_; } - friend bool operator<(const restricted_scalar& x, const restricted_scalar& y) { return x.scalar_ < y.scalar_; } - friend bool operator==(const restricted_scalar& x, const restricted_scalar& y) { return x.scalar_ == y.scalar_; } + /// @} protected: restricted_scalar() {} scalar scalar_; + + friend std::ostream& operator<<(std::ostream& o, const restricted_scalar& x) { return o << x.scalar_; } + friend bool operator<(const restricted_scalar& x, const restricted_scalar& y) { return x.scalar_ < y.scalar_; } + friend bool operator==(const restricted_scalar& x, const restricted_scalar& y) { return x.scalar_ == y.scalar_; } }; +/// @endcond + } + #endif // SCALAR_HPP http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/sender.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/sender.hpp b/proton-c/bindings/cpp/include/proton/sender.hpp index a5835fd..17849770 100644 --- a/proton-c/bindings/cpp/include/proton/sender.hpp +++ b/proton-c/bindings/cpp/include/proton/sender.hpp @@ -21,6 +21,7 @@ * under the License. * */ + #include "proton/export.hpp" #include "proton/delivery.hpp" #include "proton/link.hpp" @@ -33,26 +34,31 @@ struct pn_connection_t; namespace proton { -/// A sending link +/// A link for sending messages. class sender : public link { public: + /// @cond INTERNAL sender(pn_link_t* s=0) : link(s) {} + /// @endcond /// Send a message on the link. PN_CPP_EXTERN delivery send(const message &m); - /** The number of deliveries that might be able to be sent if sufficient credit were - issued on the link. See sender::offered(). Maintained by the application. */ + /// @cond INTERNAL + /// XXX undiscussed + + /// The number of deliveries that might be able to be sent if + /// sufficient credit were issued on the link. See + /// sender::offered(). Maintained by the application. PN_CPP_EXTERN int available(); - /** Set the availability of deliveries for a sender. */ + /// Set the availability of deliveries for a sender. PN_CPP_EXTERN void offered(int c); - + /// @endcond }; - } -#endif /*!PROTON_CPP_SENDER_H*/ +#endif // PROTON_CPP_SENDER_H --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
