You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by ac...@apache.org on 2017/05/24 19:44:36 UTC
[6/7] qpid-proton git commit: PROTON-1288: c++ documentation for maps
and type conversions
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/master
Commit: 16147e9318a90d8411ee3758418ff60d2dcb8356
Parents: 864519d
Author: Alan Conway <ac...@redhat.com>
Authored: Wed May 24 14:32:11 2017 -0400
Committer: Alan Conway <ac...@redhat.com>
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: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org