qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From acon...@apache.org
Subject [6/7] qpid-proton git commit: PROTON-1288: c++ documentation for maps and type conversions
Date Wed, 24 May 2017 19:44:36 GMT
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 <aconway@redhat.com>
Authored: Wed May 24 14:32:11 2017 -0400
Committer: Alan Conway <aconway@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


Mime
View raw message