PROTON-1288: c++ documentation for maps and type conversions Also filled in some missing doxygen markers for header files.
Project: http://git-wip-us.apache.org/repos/asf/qpid-proton/repo Commit: http://git-wip-us.apache.org/repos/asf/qpid-proton/commit/16147e93 Tree: http://git-wip-us.apache.org/repos/asf/qpid-proton/tree/16147e93 Diff: http://git-wip-us.apache.org/repos/asf/qpid-proton/diff/16147e93 Branch: refs/heads/PROTON-1488 Commit: 16147e9318a90d8411ee3758418ff60d2dcb8356 Parents: 864519d Author: Alan Conway <[email protected]> Authored: Wed May 24 14:32:11 2017 -0400 Committer: Alan Conway <[email protected]> Committed: Wed May 24 15:37:15 2017 -0400 ---------------------------------------------------------------------- proton-c/bindings/cpp/docs/headers.dox | 52 +++++++++ proton-c/bindings/cpp/docs/types.md | 77 ------------- .../cpp/include/proton/annotation_key.hpp | 6 +- .../cpp/include/proton/codec/amqp_types.hpp | 111 ------------------- .../bindings/cpp/include/proton/codec/deque.hpp | 3 + .../cpp/include/proton/codec/forward_list.hpp | 3 + .../bindings/cpp/include/proton/codec/list.hpp | 3 + .../bindings/cpp/include/proton/codec/map.hpp | 3 + .../cpp/include/proton/codec/unordered_map.hpp | 3 + .../cpp/include/proton/codec/vector.hpp | 3 + proton-c/bindings/cpp/include/proton/map.hpp | 13 ++- .../bindings/cpp/include/proton/message_id.hpp | 10 +- proton-c/bindings/cpp/include/proton/scalar.hpp | 10 +- proton-c/bindings/cpp/include/proton/types.hpp | 94 +++++++++++++++- .../bindings/cpp/include/proton/types_fwd.hpp | 4 +- proton-c/bindings/cpp/include/proton/value.hpp | 13 ++- proton-c/bindings/cpp/src/messaging_adapter.cpp | 18 ++- proton-c/include/proton/message.h | 4 +- 18 files changed, 204 insertions(+), 226 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/16147e93/proton-c/bindings/cpp/docs/headers.dox ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/docs/headers.dox b/proton-c/bindings/cpp/docs/headers.dox new file mode 100644 index 0000000..0ff7220 --- /dev/null +++ b/proton-c/bindings/cpp/docs/headers.dox @@ -0,0 +1,52 @@ +/* List headers that lack their own @file marker so doxygen will link them properly. + Ideally the files themselves should have their own @file markup and comment, + if you update files that they can be removed from here. + */ +/// @file proton/annotation_key.hpp Key type for proton::message annotation maps. +/// @file proton/binary.hpp Binary data type +/// @file proton/byte_array.hpp +/// @file proton/connection.hpp AMQP connection +/// @file proton/connection_options.hpp Options to create a proton::connection +/// @file proton/container.hpp AMQP container to manage connections and listeners +/// @file proton/decimal.hpp Placeholder for the AMQP decimal data type. +/// @file proton/delivery.hpp Delivery state of an AQMP messsage +/// @file proton/delivery_mode.hpp Delivery mode of an AMQP message +/// @file proton/duration.hpp Time duration data type +/// @file proton/error_condition.hpp AMQP error condition +/// @file proton/error.hpp Base exception type thrown by proton functions +/// @file proton/event_loop.hpp +/// @file proton/function.hpp +/// @file proton/fwd.hpp +/// @file proton/link.hpp +/// @file proton/listener.hpp +/// @file proton/listen_handler.hpp +/// @file proton/map.hpp Template for AMQP property, annotation and filter maps. +/// @file proton/message.hpp +/// @file proton/message_id.hpp +/// @file proton/messaging_handler.hpp +/// @file proton/namespaces.hpp +/// @file proton/receiver.hpp +/// @file proton/receiver_options.hpp +/// @file proton/reconnect_timer.hpp +/// @file proton/sasl.hpp +/// @file proton/scalar_base.hpp +/// @file proton/scalar.hpp Run-time holder for any AMQP scalar value +/// @file proton/sender.hpp +/// @file proton/sender_options.hpp +/// @file proton/session.hpp +/// @file proton/session_options.hpp +/// @file proton/source.hpp +/// @file proton/source_options.hpp +/// @file proton/ssl.hpp +/// @file proton/symbol.hpp AMQP symbol (ASCII string) data type +/// @file proton/target.hpp +/// @file proton/target_options.hpp +/// @file proton/terminus.hpp +/// @file proton/thread_safe.hpp +/// @file proton/timestamp.hpp +/// @file proton/tracker.hpp +/// @file proton/transfer.hpp +/// @file proton/transport.hpp +/// @file proton/url.hpp +/// @file proton/uuid.hpp +/// @file proton/value.hpp Run-time holder for any AMQP value http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/16147e93/proton-c/bindings/cpp/docs/types.md ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/docs/types.md b/proton-c/bindings/cpp/docs/types.md deleted file mode 100644 index 6a56be0..0000000 --- a/proton-c/bindings/cpp/docs/types.md +++ /dev/null @@ -1,77 +0,0 @@ -# AMQP and C++ types {#types_page} - -An AMQP message body can hold binary data using any encoding you -like. AMQP also defines its own encoding and types. The AMQP encoding -is often used in message bodies because it is supported by AMQP -libraries on many languages and platforms. You also need to use the -AMQP types to set and examine message properties. - -## Scalar types - -Each type is identified by a proton::type_id. - -C++ type | AMQP type_id | Description ---------------------|----------------------|----------------------- -bool | proton::BOOLEAN | Boolean true or false -uint8_t | proton::UBYTE | 8-bit unsigned byte -int8_t | proton::BYTE | 8-bit signed byte -uint16_t | proton::USHORT | 16-bit unsigned integer -int16_t | proton::SHORT | 16-bit signed integer -uint32_t | proton::UINT | 32-bit unsigned integer -int32_t | proton::INT | 32-bit signed integer -uint64_t | proton::ULONG | 64-bit unsigned integer -int64_t | proton::LONG | 64-bit signed integer -wchar_t | proton::CHAR | 32-bit unicode code point -float | proton::FLOAT | 32-bit binary floating point -double | proton::DOUBLE | 64-bit binary floating point -proton::timestamp | proton::TIMESTAMP | 64-bit signed milliseconds since 00:00:00 (UTC), 1 January 1970. -proton::decimal32 | proton::DECIMAL32 | 32-bit decimal floating point -proton::decimal64 | proton::DECIMAL64 | 64-bit decimal floating point -proton::decimal128 | proton::DECIMAL128 | 128-bit decimal floating point -proton::uuid | proton::UUID | 128-bit universally-unique identifier -std::string | proton::STRING | UTF-8 encoded Unicode string -proton::symbol | proton::SYMBOL | 7-bit ASCII encoded string -proton::binary | proton::BINARY | Variable-length binary data - -proton::scalar is a holder that can accept a scalar value of any type. - -## Compound types - -C++ type | AMQP type_id | Description ---------------------|----------------------|----------------------- -See below | proton::ARRAY | Sequence of values of the same type -See below | proton::LIST | Sequence of values of mixed types -See below | proton::MAP | Map of key-value pairs - -proton::value is a holder that can accept any AMQP value, scalar or -compound. - -proton::ARRAY converts to and from C++ sequences: std::vector, -std::deque, std::list, and std::forward_list. - -proton::LIST converts to and from sequences of proton::value or -proton::scalar, which can hold mixed types of data. - -proton::MAP converts to and from std::map, std::unordered_map, and -sequences of std::pair. - -When decoding, the encoded map types must be convertible to the element type of the -C++ sequence or the key-value types of the C++ map. Use proton::value as the -element or key-value type to decode any ARRAY, LIST, or MAP. - -For example you can decode any AMQP MAP into: - - std::map<proton::value, proton::value> - -You can decode any AMQP LIST or ARRAY into: - - std::vector<proton::value> - -## Include files - -You can simply include proton/types.hpp to get all the type -definitions and conversions. Alternatively, you can selectively -include only what you need: - - - Include proton/types_fwd.hpp: forward declarations for all types. - - Include individual `.hpp` files as per the table above. http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/16147e93/proton-c/bindings/cpp/include/proton/annotation_key.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/annotation_key.hpp b/proton-c/bindings/cpp/include/proton/annotation_key.hpp index 4995141..02f5420 100644 --- a/proton-c/bindings/cpp/include/proton/annotation_key.hpp +++ b/proton-c/bindings/cpp/include/proton/annotation_key.hpp @@ -65,18 +65,18 @@ template <class T> T get(const annotation_key& x); /// Get the uint64_t value or throw conversion_error. /// -/// @related annotation_key +/// @relatedalso annotation_key template<> inline uint64_t get<uint64_t>(const annotation_key& x) { return internal::get<uint64_t>(x); } /// Get the @ref symbol value or throw conversion_error. /// -/// @related annotation_key +/// @relatedalso annotation_key template<> inline symbol get<symbol>(const annotation_key& x) { return internal::get<symbol>(x); } /// Get the @ref binary value or throw conversion_error. /// /// @copydoc scalar::coerce -/// @related annotation_key +/// @relatedalso annotation_key template<class T> T coerce(const annotation_key& x) { return internal::coerce<T>(x); } } // proton http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/16147e93/proton-c/bindings/cpp/include/proton/codec/amqp_types.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/codec/amqp_types.hpp b/proton-c/bindings/cpp/include/proton/codec/amqp_types.hpp deleted file mode 100644 index 5456225..0000000 --- a/proton-c/bindings/cpp/include/proton/codec/amqp_types.hpp +++ /dev/null @@ -1,111 +0,0 @@ -#ifndef PROTON_CODEC_AMQP_TYPES_HPP -#define PROTON_CODEC_AMQP_TYPES_HPP - -/* - * - * Licensed to the Apache Software Foundation (ASF) under one - * or more contributor license agreements. See the NOTICE file - * distributed with this work for additional information - * regarding copyright ownership. The ASF licenses this file - * to you under the Apache License, Version 2.0 (the - * "License"); you may not use this file except in compliance - * with the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, - * software distributed under the License is distributed on an - * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - * KIND, either express or implied. See the License for the - * specific language governing permissions and limitations - * under the License. - * - */ - -/// @cond INTERNAL -/// XXX Remove this entirely - -namespace proton { -namespace codec { - -/// @name Experimental - Typedefs for AMQP scalar types. -/// -/// These typedefs associate AMQP scalar type names with the -/// corresponding C++ types. They are provided as a convenience for -/// those familiar with AMQP, but you do not need to use them. You -/// can use the C++ types directly. -/// -/// The typedef names have a `_type` suffix to avoid ambiguity with -/// C++ reserved and std library type names. -/// -/// @{ - -// XXX Consider prefixing these with amqp_ and dropping _type, now -// that they're in the codec namespace - -/// True or false. -typedef bool boolean_type; - -/// 8-bit unsigned byte -typedef uint8_t ubyte_type; - -/// 8-bit signed byte -typedef int8_t byte_type; - -/// 16-bit unsigned short integer -typedef uint16_t ushort_type; - -/// 16-bit signed short integer -typedef int16_t short_type; - -/// 32-bit unsigned integer -typedef uint32_t uint_type; - -/// 32-bit signed integer -typedef int32_t int_type; - -/// 64-bit unsigned long integer -typedef uint64_t ulong_type; - -/// 64-bit signed long integer -typedef int64_t long_type; - -/// 32-bit unicode code point -typedef wchar_t char_type; - -/// 32-bit binary floating point -typedef float float_type; - -/// 64-bit binary floating point -typedef double double_type; - -/// An AMQP string is unicode UTF-8 encoded. -typedef std::string string_type; - -/// An AMQP symbol is ASCII 7-bit encoded. -typedef proton::symbol symbol_type; - -/// An AMQP binary contains variable length raw binary data. -typedef proton::binary binary_type; - -/// A timestamp in milliseconds since the epoch 00:00:00 (UTC), 1 January 1970. -typedef proton::timestamp timestamp_type; - -/// A 16-byte universally unique identifier. -typedef proton::uuid uuid_type; - -/// 32-bit decimal floating point -typedef proton::decimal32 decimal32_type; - -/// 64-bit decimal floating point -typedef proton::decimal64 decimal64_type; - -/// 128-bit decimal floating point -typedef proton::decimal128 decimal128_type; - -} // codec -} // proton - -/// @endcond - -#endif // PROTON_CODEC_AMQP_TYPES_HPP http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/16147e93/proton-c/bindings/cpp/include/proton/codec/deque.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/codec/deque.hpp b/proton-c/bindings/cpp/include/proton/codec/deque.hpp index 2f570a4..188da2a 100644 --- a/proton-c/bindings/cpp/include/proton/codec/deque.hpp +++ b/proton-c/bindings/cpp/include/proton/codec/deque.hpp @@ -20,6 +20,9 @@ * under the License. */ +/// @file +/// Enable conversions between proton::value and std::deque + #include "./encoder.hpp" #include "./decoder.hpp" http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/16147e93/proton-c/bindings/cpp/include/proton/codec/forward_list.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/codec/forward_list.hpp b/proton-c/bindings/cpp/include/proton/codec/forward_list.hpp index 0038b8f..4f09f3e 100644 --- a/proton-c/bindings/cpp/include/proton/codec/forward_list.hpp +++ b/proton-c/bindings/cpp/include/proton/codec/forward_list.hpp @@ -20,6 +20,9 @@ * under the License. */ +/// @file +/// Enable conversions between proton::value and std::forward_list + #include "./encoder.hpp" #include "./decoder.hpp" http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/16147e93/proton-c/bindings/cpp/include/proton/codec/list.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/codec/list.hpp b/proton-c/bindings/cpp/include/proton/codec/list.hpp index a2c71b8..e914a5b 100644 --- a/proton-c/bindings/cpp/include/proton/codec/list.hpp +++ b/proton-c/bindings/cpp/include/proton/codec/list.hpp @@ -22,6 +22,9 @@ * */ +/// @file +/// Enable conversions between proton::value and std::list + #include "./encoder.hpp" #include "./decoder.hpp" http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/16147e93/proton-c/bindings/cpp/include/proton/codec/map.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/codec/map.hpp b/proton-c/bindings/cpp/include/proton/codec/map.hpp index d3b0c4d..45f9df9 100644 --- a/proton-c/bindings/cpp/include/proton/codec/map.hpp +++ b/proton-c/bindings/cpp/include/proton/codec/map.hpp @@ -22,6 +22,9 @@ * */ +/// @file +/// Enable conversions between proton::value and std::map + #include "./encoder.hpp" #include "./decoder.hpp" http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/16147e93/proton-c/bindings/cpp/include/proton/codec/unordered_map.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/codec/unordered_map.hpp b/proton-c/bindings/cpp/include/proton/codec/unordered_map.hpp index b081ff8..d26ec29 100644 --- a/proton-c/bindings/cpp/include/proton/codec/unordered_map.hpp +++ b/proton-c/bindings/cpp/include/proton/codec/unordered_map.hpp @@ -22,6 +22,9 @@ * */ +/// @file +/// Enable conversions between proton::value and std::unordered_map + #include "./encoder.hpp" #include "./decoder.hpp" http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/16147e93/proton-c/bindings/cpp/include/proton/codec/vector.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/codec/vector.hpp b/proton-c/bindings/cpp/include/proton/codec/vector.hpp index 4edae25..8674f56 100644 --- a/proton-c/bindings/cpp/include/proton/codec/vector.hpp +++ b/proton-c/bindings/cpp/include/proton/codec/vector.hpp @@ -22,6 +22,9 @@ * */ +/// @file +/// Enable conversions between proton::value and std::vector + #include "./encoder.hpp" #include "./decoder.hpp" http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/16147e93/proton-c/bindings/cpp/include/proton/map.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/map.hpp b/proton-c/bindings/cpp/include/proton/map.hpp index 8399b16..9798fad 100644 --- a/proton-c/bindings/cpp/include/proton/map.hpp +++ b/proton-c/bindings/cpp/include/proton/map.hpp @@ -41,10 +41,13 @@ class map_type_impl; template <class K, class T> class map; +/// Decode from a proton::map template <class K, class T> PN_CPP_EXTERN proton::codec::decoder& operator>>(proton::codec::decoder& d, map<K,T>& m); +/// Encode to a proton::map template <class K, class T> PN_CPP_EXTERN proton::codec::encoder& operator<<(proton::codec::encoder& e, const map<K,T>& m); +/// Swap proton::map instances template <class K, class T> PN_CPP_EXTERN void swap(map<K,T>&, map<K,T>&); @@ -53,7 +56,7 @@ PN_CPP_EXTERN void swap(map<K,T>&, map<K,T>&); /// /// Provides only basic get()/set() operations for convenience. For more /// complicated use (iteration, preserving order etc.) you should convert to a -/// standard C++ map type such as std::map. See @ref message_propreties.cpp +/// standard C++ map type such as std::map. See @ref message_properties.cpp /// and @ref types_page. /// template <class K, class T> @@ -63,19 +66,19 @@ class PN_CPP_CLASS_EXTERN map { public internal::enable_if<codec::is_encodable_map<M,K,T>::value, U> {}; public: - /// Create an empty map value + /// @name Construct and assign + /// @{ PN_CPP_EXTERN map(); - PN_CPP_EXTERN map(const map& cm); PN_CPP_EXTERN map& operator=(const map& cm); #if PN_CPP_HAS_RVALUE_REFERENCES PN_CPP_EXTERN map(map&&); PN_CPP_EXTERN map& operator=(map&&); #endif - + ///@} PN_CPP_EXTERN ~map(); - /// Type-safe assign from a compatible map type, e.g. std::map<K,T> - see @types_page + /// Type-safe assign from a compatible map, e.g. std::map<K,T> - see @ref types_page template <class M> typename assignable_map<M, map&>::type operator=(const M& x) { value(x); return *this;} http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/16147e93/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 ee12a17..749337c 100644 --- a/proton-c/bindings/cpp/include/proton/message_id.hpp +++ b/proton-c/bindings/cpp/include/proton/message_id.hpp @@ -74,17 +74,17 @@ class message_id : public scalar_base { template <class T> T get(const message_id& x); /// @endcond -/// Get the uint64_t value or throw conversion_error. @related message_id +/// Get the uint64_t value or throw conversion_error. @relatedalso message_id template<> inline uint64_t get<uint64_t>(const message_id& x) { return internal::get<uint64_t>(x); } -/// Get the @ref uuid value or throw conversion_error. @related message_id +/// Get the @ref uuid value or throw conversion_error. @relatedalso message_id template<> inline uuid get<uuid>(const message_id& x) { return internal::get<uuid>(x); } -/// Get the @ref binary value or throw conversion_error. @related message_id +/// Get the @ref binary value or throw conversion_error. @relatedalso message_id template<> inline binary get<binary>(const message_id& x) { return internal::get<binary>(x); } -/// Get the std::string value or throw conversion_error. @related message_id +/// Get the std::string value or throw conversion_error. @relatedalso message_id template<> inline std::string get<std::string>(const message_id& x) { return internal::get<std::string>(x); } /// @copydoc scalar::coerce -/// @related message_id +/// @relatedalso message_id template<class T> T coerce(const message_id& x) { return internal::coerce<T>(x); } } // proton http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/16147e93/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 0559dd9..99236c3 100644 --- a/proton-c/bindings/cpp/include/proton/scalar.hpp +++ b/proton-c/bindings/cpp/include/proton/scalar.hpp @@ -51,32 +51,32 @@ class scalar : public scalar_base { /// This will succeed if and only if x contains a uint64_t value. /// /// @throw conversion_error if contained value is not of type T. -/// @related scalar +/// @relatedalso scalar template<class T> T get(const scalar& s) { return internal::get<T>(s); } /// Coerce the contained value to type T. For example: /// -/// uint64_t i = get<uint64_t>(x) +/// uint64_t i = coerce<uint64_t>(x) /// /// This will succeed if x contains any numeric value, but may lose /// precision if it contains a float or double value. /// /// @throw conversion_error if the value cannot be converted to T /// according to `std::is_convertible` -/// @related scalar +/// @relatedalso scalar template<class T> T coerce(const scalar& x) { return internal::coerce<T>(x); } /// Coerce the contained value to type T. For example: /// -/// uint64_t i = get<uint64_t>(x) +/// uint64_t i = coerce<uint64_t>(x) /// /// This will succeed if x contains any numeric value, but may lose /// precision if it contains a float or double value. /// /// @throw conversion_error if the value cannot be converted to T /// according to `std::is_convertible` -/// @related scalar +/// @relatedalso scalar template<class T> T coerce(scalar& x) { return internal::coerce<T>(x); } } // proton http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/16147e93/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 d21cb8f..f541b13 100644 --- a/proton-c/bindings/cpp/include/proton/types.hpp +++ b/proton-c/bindings/cpp/include/proton/types.hpp @@ -29,14 +29,96 @@ // TODO aconway 2016-03-15: described types, described arrays. +/** @page types_page AMQP and C++ types + +An AMQP message body can hold binary data using any encoding you +like. AMQP also defines its own encoding and types. The AMQP encoding +is often used in message bodies because it is supported by AMQP +libraries on many languages and platforms. You also need to use the +AMQP types to set and examine message properties. + +## Scalar types + +Each type is identified by a proton::type_id. + +C++ type | AMQP type_id | Description +--------------------|----------------------|----------------------- +bool | proton::BOOLEAN | Boolean true or false +uint8_t | proton::UBYTE | 8-bit unsigned byte +int8_t | proton::BYTE | 8-bit signed byte +uint16_t | proton::USHORT | 16-bit unsigned integer +int16_t | proton::SHORT | 16-bit signed integer +uint32_t | proton::UINT | 32-bit unsigned integer +int32_t | proton::INT | 32-bit signed integer +uint64_t | proton::ULONG | 64-bit unsigned integer +int64_t | proton::LONG | 64-bit signed integer +wchar_t | proton::CHAR | 32-bit unicode code point +float | proton::FLOAT | 32-bit binary floating point +double | proton::DOUBLE | 64-bit binary floating point +proton::timestamp | proton::TIMESTAMP | 64-bit signed milliseconds since 00:00:00 (UTC), 1 January 1970. +proton::decimal32 | proton::DECIMAL32 | 32-bit decimal floating point +proton::decimal64 | proton::DECIMAL64 | 64-bit decimal floating point +proton::decimal128 | proton::DECIMAL128 | 128-bit decimal floating point +proton::uuid | proton::UUID | 128-bit universally-unique identifier +std::string | proton::STRING | UTF-8 encoded Unicode string +proton::symbol | proton::SYMBOL | 7-bit ASCII encoded string +proton::binary | proton::BINARY | Variable-length binary data + +## Holder types + +proton::message::body() and other message-related data can contain different +types of data at run-time. There are two "holder" types provided to hold +run-time typed data: + +- proton::scalar can hold a scalar value of any type. +- proton::value can hold any AMQP value, scalar or compound. + +You can set the value in a holder by assignment, and use the proton::get() and +proton::coerce() templates extract data in a type-safe way. Holders also provide +functions to query the type of value they contain. + +## Compound types + +C++ type | AMQP type_id | Description +--------------------|----------------------|----------------------- +See below | proton::ARRAY | Sequence of values of the same type +See below | proton::LIST | Sequence of values of mixed types +See below | proton::MAP | Map of key-value pairs + +A proton::value containing a proton::ARRAY can convert to and from C++ sequences +of the corresponding C++ type: std::vector, std::deque, std::list, and +std::forward_list. + +proton::LIST converts to and from sequences of proton::value or +proton::scalar, which can hold mixed types of data. + +proton::MAP converts to and from std::map, std::unordered_map, and +sequences of std::pair. + +For example you can decode a message body with any AMQP MAP as follows: + + proton::message m = ...; + std::map<proton::value, proton::value> map; + proton::get(m.body(), map); + +You can encode a message body with a map of string to uint64_t like this: + + std::unordered_map<std::string, uint64_t> map; + map["foo"] = 123; + m.body() = map; + +## Include files + +`proton/types.hpp` includes all available type definitions and +conversions. Alternatively, you can selectively include the .hpp files you +want, see @ref types.hpp. + +*/ + #include "./internal/config.hpp" #include "./annotation_key.hpp" #include "./binary.hpp" -#include "./codec/deque.hpp" -#include "./codec/list.hpp" -#include "./codec/map.hpp" -#include "./codec/vector.hpp" #include "./decimal.hpp" #include "./duration.hpp" #include "./message_id.hpp" @@ -47,6 +129,10 @@ #include "./uuid.hpp" #include "./value.hpp" +#include "./codec/deque.hpp" +#include "./codec/list.hpp" +#include "./codec/map.hpp" +#include "./codec/vector.hpp" #if PN_CPP_HAS_CPP11 #include "./codec/forward_list.hpp" #include "./codec/unordered_map.hpp" http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/16147e93/proton-c/bindings/cpp/include/proton/types_fwd.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/types_fwd.hpp b/proton-c/bindings/cpp/include/proton/types_fwd.hpp index ff53b0c..a2d2508 100644 --- a/proton-c/bindings/cpp/include/proton/types_fwd.hpp +++ b/proton-c/bindings/cpp/include/proton/types_fwd.hpp @@ -23,9 +23,7 @@ */ /// @file -/// -/// Forward declarations for all the C++ types used by Proton to -/// represent AMQP types. +/// Forward declarations for all C++ types used by Proton to represent AMQP types. #include "./internal/config.hpp" http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/16147e93/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 bc7ed86..c1c0835 100644 --- a/proton-c/bindings/cpp/include/proton/value.hpp +++ b/proton-c/bindings/cpp/include/proton/value.hpp @@ -115,35 +115,36 @@ class value : public internal::value_base, private internal::comparable<value> { /// that may change in future so should not be parsed. friend PN_CPP_EXTERN std::ostream& operator<<(std::ostream&, const value&); - ///@cond INTERNAL - used to refer to existing pn_data_t* values as proton::value + ///@cond INTERNAL + /// Used to refer to existing pn_data_t* values as proton::value value(pn_data_t* d); // Refer to existing pn_data_t void reset(pn_data_t* d = 0); // Refer to a new pn_data_t ///@endcond }; /// @copydoc scalar::get -/// @related proton::value +/// @relatedalso proton::value template<class T> T get(const value& v) { T x; get(v, x); return x; } /// Like get(const value&) but assigns the value to a reference /// instead of returning it. May be more efficient for complex values /// (arrays, maps, etc.) /// -/// @related proton::value +/// @relatedalso proton::value template<class T> void get(const value& v, T& x) { codec::decoder d(v, true); d >> x; } -/// @related proton::value +/// @relatedalso proton::value template<class T, class U> inline void get(const U& u, T& x) { const value v(u); get(v, x); } /// @copydoc scalar::coerce -/// @related proton::value +/// @relatedalso proton::value template<class T> T coerce(const value& v) { T x; coerce(v, x); return x; } /// Like coerce(const value&) but assigns the value to a reference /// instead of returning it. May be more efficient for complex values /// (arrays, maps, etc.) /// -/// @related proton::value +/// @relatedalso proton::value template<class T> void coerce(const value& v, T& x) { codec::decoder d(v, false); if (type_id_is_scalar(v.type())) { http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/16147e93/proton-c/bindings/cpp/src/messaging_adapter.cpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/src/messaging_adapter.cpp b/proton-c/bindings/cpp/src/messaging_adapter.cpp index de35989..a70703e 100644 --- a/proton-c/bindings/cpp/src/messaging_adapter.cpp +++ b/proton-c/bindings/cpp/src/messaging_adapter.cpp @@ -59,11 +59,13 @@ void credit_topup(pn_link_t *link) { } void messaging_adapter::on_reactor_init(proton_event &pe) { - delegate_.on_container_start(pe.container()); + container* c = pe.container_ptr(); + if (c) delegate_.on_container_start(*c); } void messaging_adapter::on_reactor_final(proton_event &pe) { - delegate_.on_container_stop(pe.container()); + container* c = pe.container_ptr(); + if (c) delegate_.on_container_stop(*c); } void messaging_adapter::on_link_flow(proton_event &pe) { @@ -279,18 +281,24 @@ void messaging_adapter::on_link_local_open(proton_event &pe) { void messaging_adapter::on_link_remote_open(proton_event &pe) { pn_link_t *lnk = pn_event_link(pe.pn_event()); - container& c = pe.container(); + container* c = pe.container_ptr(); if (pn_link_is_receiver(lnk)) { receiver r(make_wrapper<receiver>(lnk)); delegate_.on_receiver_open(r); if (is_local_unititialised(pn_link_state(lnk))) { - r.open(c.receiver_options()); + if (c) + r.open(c->receiver_options()); + else + r.open(); } } else { sender s(make_wrapper<sender>(lnk)); delegate_.on_sender_open(s); if (is_local_unititialised(pn_link_state(lnk))) { - s.open(c.sender_options()); + if (c) + s.open(c->sender_options()); + else + s.open(); } } credit_topup(lnk); http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/16147e93/proton-c/include/proton/message.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/message.h b/proton-c/include/proton/message.h index 4f71db2..b27ebcb 100644 --- a/proton-c/include/proton/message.h +++ b/proton-c/include/proton/message.h @@ -744,7 +744,7 @@ PN_EXTERN int pn_message_encode(pn_message_t *msg, char *bytes, size_t *size); */ PN_EXTERN int pn_message_data(pn_message_t *msg, pn_data_t *data); -/** @cond INTERNAL @{ */ +/** @cond INTERNAL */ /** Construct a message with extra storage */ PN_EXTERN pn_message_t * pn_message_with_extra(size_t extra); @@ -752,7 +752,7 @@ PN_EXTERN pn_message_t * pn_message_with_extra(size_t extra); /** Pointer to extra space allocated by pn_message_with_extra(). */ PN_EXTERN void* pn_message_get_extra(pn_message_t *msg); -/** @} */ +/** @endcond */ /** @} --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
