zeroc-ice 3.7.0 → 3.7.1

data/ext/ice/cpp/include/Ice/AsyncResult.h

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.
@@ -23,34 +23,107 @@
 namespace Ice
 {
 
+/**
+ * Represents the result of an asynchronous invocation using the C++98 mapping.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API AsyncResult : private IceUtil::noncopyable, public Ice::LocalObject
 {
 public:
 
     virtual ~AsyncResult();
 
+    /**
+     * Prevents a queued invocation from being sent or, if the invocation has already been sent,
+     * ignores a reply if the server sends one. cancel is a local operation and has no effect
+     * on the server. A canceled invocation is considered to be completed, meaning isCompleted
+     * returns true, and the result of the invocation is an InvocationCanceledException.
+     */
     virtual void cancel() = 0;
 
+    /**
+     * Allows you to create ordered or hashed collections of pending asynchronous invocations.
+     * @return A unique hash code for this object.
+     */
     virtual Int getHash() const = 0;
 
+    /**
+     * Obtains the communicator that sent the invocation.
+     * @return A reference to the communicator.
+     */
     virtual CommunicatorPtr getCommunicator() const = 0;
+
+    /**
+     * Obtains the connection that was used for the invocation. Note that, for typical asynchronous
+     * proxy invocations, this method returns a nil value because the possibility of automatic retries
+     * means the connection that is currently in use could change unexpectedly. The getConnection
+     * method only returns a non-nil value when the AsyncResult object is obtained by calling
+     * Connection::begin_flushBatchRequests.
+     * @return A reference to the connection.
+     */
     virtual ConnectionPtr getConnection() const = 0;
+
+    /**
+     * Obtains the proxy that was used to call the begin_ method, or nil if the AsyncResult object was
+     * not obtained via an asynchronous proxy invocation.
+     * @return A reference to the proxy.
+     */
     virtual ObjectPrxPtr getProxy() const = 0;
 
+    /**
+     * Obtains the completion status of the invocation.
+     * @return True if, at the time it is called, the result of an invocation is available, indicating
+     * that a call to the end_ method will not block the caller. Otherwise, if the result is not yet
+     * available, the method returns false.
+     */
     virtual bool isCompleted() const = 0;
+
+    /**
+     * Blocks the caller until the result of an invocation becomes available.
+     */
     virtual void waitForCompleted() = 0;
 
+    /**
+     * Obtains the sent status of the invocation.
+     * @return True if, at the time it is called, the request has been written to the local transport
+     * (whether it was initially queued or not). Otherwise, if the request is still queued or an
+     * exception occurred before the request could be sent, this method returns false.
+     */
     virtual bool isSent() const = 0;
+
+    /**
+     * Blocks the calling thread until a request has been written to the client-side transport,
+     * or an exception occurs.
+     */
     virtual void waitForSent() = 0;
 
+    /**
+     * Throws the local exception that caused the invocation to fail. If no exception has occurred yet,
+     * this method does nothing.
+     */
     virtual void throwLocalException() const = 0;
 
+    /**
+     * Determines whether the request was sent synchronously.
+     * @return True if a request was written to the client-side transport without first being queued.
+     * If the request was initially queued, sentSynchronously returns false (independent of whether
+     * the request is still in the queue or has since been written to the client-side transport).
+     */
     virtual bool sentSynchronously() const = 0;
 
+    /**
+     * Obtains the cookie that was passed to the begin_ method.
+     * @return The cookie, or nil if you did not pass a cookie to the begin_ method.
+     */
     virtual LocalObjectPtr getCookie() const = 0;
 
+    /**
+     * Obtains the name of the operation.
+     * @return The operation name.
+     */
     virtual const std::string& getOperation() const = 0;
 
+    /// \cond INTERNAL
     virtual bool _waitForResponse() = 0;
     virtual Ice::InputStream* _startReadParams() = 0;
     virtual void _endReadParams() = 0;
@@ -71,10 +144,13 @@ public:
     typedef IceUtil::Handle<Callback> CallbackPtr;
 
     virtual void _scheduleCallback(const CallbackPtr&) = 0;
+    /// \endcond
 
 protected:
 
+    /// \cond INTERNAL
     static void check(const AsyncResultPtr&, const ::std::string&);
+    /// \endcond
 };
 
 }

data/ext/ice/cpp/include/Ice/AsyncResultF.h

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.

data/ext/ice/cpp/include/Ice/BatchRequestInterceptor.h

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.
@@ -16,6 +16,10 @@
 namespace Ice
 {
 
+/**
+ * Represents an invocation on a proxy configured for batch-oneway or batch-datagram.
+ * \headerfile Ice/Ice.h
+ */
 class BatchRequest
 {
 public:
@@ -24,19 +28,48 @@ public:
     {
     }
 
+    /**
+     * Queues the request for an eventual flush.
+     */
     virtual void enqueue() const = 0;
+
+    /**
+     * Obtains the size of the request.
+     * @return The number of bytes consumed by the request.
+     */
     virtual int getSize() const = 0;
+
+    /**
+     * Obtains the name of the operation.
+     * @return The operation name.
+     */
     virtual const std::string& getOperation() const = 0;
+
+    /**
+     * Obtains the proxy on which the batch request was invoked.
+     * @return The originating proxy.
+     */
     virtual const Ice::ObjectPrxPtr& getProxy() const = 0;
 };
 
 #ifndef ICE_CPP11_MAPPING
 
+/**
+ * The base class for a batch request interceptor. Subclasses must implement enqueue.
+ * The interceptor can be installed via InitializationData.
+ * \headerfile Ice/Ice.h
+ */
 class BatchRequestInterceptor : public IceUtil::Shared
 {
 public:
 
-    virtual void enqueue(const BatchRequest&, int, int) = 0;
+    /**
+     * Called by the Ice run time to enqueue a batch request.
+     * @param req An object representing the batch request.
+     * @param count The number of requests currently in the queue.
+     * @param size The number of bytes consumed by the requests currently in the queue.
+     */
+    virtual void enqueue(const BatchRequest& req, int count, int size) = 0;
 };
 typedef IceUtil::Handle<BatchRequestInterceptor> BatchRequestInterceptorPtr;
 

data/ext/ice/cpp/include/Ice/BatchRequestQueueF.h

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.

data/ext/ice/cpp/include/Ice/Buffer.h

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.

data/ext/ice/cpp/include/Ice/CommunicatorAsync.h

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.
@@ -17,6 +17,12 @@
 namespace Ice
 {
 
+/**
+ * Type-safe asynchronous callback wrapper class used for calls to
+ * Ice::Communicator::begin_flushBatchRequests.
+ * Create a wrapper instance by calling ::Ice::newCallback_Communicator_flushBatchRequests.
+ * \headerfile Ice/Ice.h
+ */
 template<class T>
 class CallbackNC_Communicator_flushBatchRequests : public Callback_Communicator_flushBatchRequests_Base,
                                                    public ::IceInternal::OnewayCallbackNC<T>
@@ -33,6 +39,7 @@ public:
     {
     }
 
+    /// \cond INTERNAL
     virtual void completed(const ::Ice::AsyncResultPtr& result) const
     {
         ::Ice::CommunicatorPtr communicator = result->getCommunicator();
@@ -47,8 +54,17 @@ public:
             ::IceInternal::CallbackNC<T>::exception(result, ex);
         }
     }
+    /// \endcond
 };
 
+/**
+ * Creates a callback wrapper instance that delegates to your object.
+ * @param instance The callback object.
+ * @param excb The exception method of the callback object.
+ * @param sentcb The sent method of the callback object.
+ * @return An object that can be passed to an asynchronous invocation of
+ * Ice::Communicator::begin_flushBatchRequests.
+ */
 template<class T> Callback_Communicator_flushBatchRequestsPtr
 newCallback_Communicator_flushBatchRequests(const IceUtil::Handle<T>& instance,
                                             void (T::*excb)(const ::Ice::Exception&),
@@ -57,6 +73,14 @@ newCallback_Communicator_flushBatchRequests(const IceUtil::Handle<T>& instance,
     return new CallbackNC_Communicator_flushBatchRequests<T>(instance, excb, sentcb);
 }
 
+/**
+ * Creates a callback wrapper instance that delegates to your object.
+ * @param instance The callback object.
+ * @param excb The exception method of the callback object.
+ * @param sentcb The sent method of the callback object.
+ * @return An object that can be passed to an asynchronous invocation of
+ * Ice::Communicator::begin_flushBatchRequests.
+ */
 template<class T> Callback_Communicator_flushBatchRequestsPtr
 newCallback_Communicator_flushBatchRequests(T* instance, void (T::*excb)(const ::Ice::Exception&),
                                             void (T::*sentcb)(bool) = 0)
@@ -64,6 +88,12 @@ newCallback_Communicator_flushBatchRequests(T* instance, void (T::*excb)(const :
     return new CallbackNC_Communicator_flushBatchRequests<T>(instance, excb, sentcb);
 }
 
+/**
+ * Type-safe asynchronous callback wrapper class used for calls to
+ * Ice::Communicator::begin_flushBatchRequests.
+ * Create a wrapper instance by calling ::Ice::newCallback_Communicator_flushBatchRequests.
+ * \headerfile Ice/Ice.h
+ */
 template<class T, typename CT>
 class Callback_Communicator_flushBatchRequests : public Callback_Communicator_flushBatchRequests_Base,
                                                  public ::IceInternal::OnewayCallback<T, CT>
@@ -80,6 +110,7 @@ public:
     {
     }
 
+    /// \cond INTERNAL
     virtual void completed(const ::Ice::AsyncResultPtr& result) const
     {
         ::Ice::CommunicatorPtr communicator = result->getCommunicator();
@@ -94,8 +125,14 @@ public:
             ::IceInternal::Callback<T, CT>::exception(result, ex);
         }
     }
+    /// \endcond
 };
 
+/**
+ * Type-safe asynchronous callback wrapper class used for calls to
+ * Ice::Communicator::begin_flushBatchRequests.
+ * Create a wrapper instance by calling ::Ice::newCallback_Communicator_flushBatchRequests.
+ */
 template<class T, typename CT> Callback_Communicator_flushBatchRequestsPtr
 newCallback_Communicator_flushBatchRequests(const IceUtil::Handle<T>& instance,
                                             void (T::*excb)(const ::Ice::Exception&, const CT&),
@@ -104,6 +141,11 @@ newCallback_Communicator_flushBatchRequests(const IceUtil::Handle<T>& instance,
     return new Callback_Communicator_flushBatchRequests<T, CT>(instance, excb, sentcb);
 }
 
+/**
+ * Type-safe asynchronous callback wrapper class used for calls to
+ * Ice::Communicator::begin_flushBatchRequests.
+ * Create a wrapper instance by calling ::Ice::newCallback_Communicator_flushBatchRequests.
+ */
 template<class T, typename CT> Callback_Communicator_flushBatchRequestsPtr
 newCallback_Communicator_flushBatchRequests(T* instance, void (T::*excb)(const ::Ice::Exception&, const CT&),
                                             void (T::*sentcb)(bool, const CT&) = 0)

data/ext/ice/cpp/include/Ice/Comparable.h

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.
@@ -15,6 +15,12 @@
 namespace Ice
 {
 
+/**
+ * Compares the contents of two smart pointers.
+ * @param lhs The left-hand side.
+ * @param rhs The right-hand side.
+ * @return True if the contents are equal, false otherwise.
+ */
 template<typename T, typename U>
 inline bool targetEqualTo(const T& lhs, const U& rhs)
 {
@@ -28,6 +34,12 @@ inline bool targetEqualTo(const T& lhs, const U& rhs)
     }
 }
 
+/**
+ * Compares the contents of two smart pointers.
+ * @param lhs The left-hand side.
+ * @param rhs The right-hand side.
+ * @return True if the left-hand side compares less than the right-hand side, false otherwise.
+ */
 template<typename T, typename U>
 inline bool targetLess(const T& lhs, const U& rhs)
 {
@@ -41,24 +53,48 @@ inline bool targetLess(const T& lhs, const U& rhs)
     }
 }
 
+/**
+ * Compares the contents of two smart pointers.
+ * @param lhs The left-hand side.
+ * @param rhs The right-hand side.
+ * @return True if the left-hand side compares greater than the right-hand side, false otherwise.
+ */
 template<typename T, typename U>
 inline bool targetGreater(const T& lhs, const U& rhs)
 {
     return targetLess(rhs, lhs);
 }
 
+/**
+ * Compares the contents of two smart pointers.
+ * @param lhs The left-hand side.
+ * @param rhs The right-hand side.
+ * @return True if the left-hand side compares less than or equal to the right-hand side, false otherwise.
+ */
 template<typename T, typename U>
 inline bool targetLessEqual(const T& lhs, const U& rhs)
 {
     return !targetGreater(lhs, rhs);
 }
 
+/**
+ * Compares the contents of two smart pointers.
+ * @param lhs The left-hand side.
+ * @param rhs The right-hand side.
+ * @return True if the left-hand side compares greater than or equal to the right-hand side, false otherwise.
+ */
 template<typename T, typename U>
 inline bool targetGreaterEqual(const T& lhs, const U& rhs)
 {
     return !targetLess(lhs, rhs);
 }
 
+/**
+ * Compares the contents of two smart pointers.
+ * @param lhs The left-hand side.
+ * @param rhs The right-hand side.
+ * @return True if the contents are not equal, false otherwise.
+ */
 template<typename T, typename U>
 inline bool targetNotEqualTo(const T& lhs, const U& rhs)
 {
@@ -67,9 +103,17 @@ inline bool targetNotEqualTo(const T& lhs, const U& rhs)
 
 #ifdef ICE_CPP11_MAPPING
 
+/**
+ * Functor class that compares the contents of two smart pointers of the given type using the given comparator.
+ * \headerfile Ice/Ice.h
+ */
 template<typename T, template<typename> class Compare>
 struct TargetCompare
 {
+    /**
+     * Executes the functor to compare the contents of two smart pointers.
+     * @return True if the contents satisfy the given comparator, false otherwise.
+     */
     bool operator()(const T& lhs, const T& rhs) const
     {
         if(lhs && rhs)
@@ -87,36 +131,72 @@ struct TargetCompare
 // Relational operators for generated structs and classes
 //
 
+/**
+ * Relational operator for generated structs and classes.
+ * @param lhs The left-hand side.
+ * @param rhs The right-hand side.
+ * @return True if the left-hand side compares less than the right-hand side, false otherwise.
+ */
 template<class C, typename = std::enable_if<std::is_member_function_pointer<decltype(&C::ice_tuple)>::value>>
 bool operator<(const C& lhs, const C& rhs)
 {
    return lhs.ice_tuple() < rhs.ice_tuple();
 }
 
+/**
+ * Relational operator for generated structs and classes.
+ * @param lhs The left-hand side.
+ * @param rhs The right-hand side.
+ * @return True if the left-hand side compares less than or equal to the right-hand side, false otherwise.
+ */
 template<class C, typename = std::enable_if<std::is_member_function_pointer<decltype(&C::ice_tuple)>::value>>
 bool operator<=(const C& lhs, const C& rhs)
 {
    return lhs.ice_tuple() <= rhs.ice_tuple();
 }
 
+/**
+ * Relational operator for generated structs and classes.
+ * @param lhs The left-hand side.
+ * @param rhs The right-hand side.
+ * @return True if the left-hand side compares greater than the right-hand side, false otherwise.
+ */
 template<class C, typename = std::enable_if<std::is_member_function_pointer<decltype(&C::ice_tuple)>::value>>
 bool operator>(const C& lhs, const C& rhs)
 {
    return lhs.ice_tuple() > rhs.ice_tuple();
 }
 
+/**
+ * Relational operator for generated structs and classes.
+ * @param lhs The left-hand side.
+ * @param rhs The right-hand side.
+ * @return True if the left-hand side compares greater than or equal to the right-hand side, false otherwise.
+ */
 template<class C, typename = std::enable_if<std::is_member_function_pointer<decltype(&C::ice_tuple)>::value>>
 bool operator>=(const C& lhs, const C& rhs)
 {
    return lhs.ice_tuple() >= rhs.ice_tuple();
 }
 
+/**
+ * Relational operator for generated structs and classes.
+ * @param lhs The left-hand side.
+ * @param rhs The right-hand side.
+ * @return True if the left-hand side compares equal to the right-hand side, false otherwise.
+ */
 template<class C, typename = std::enable_if<std::is_member_function_pointer<decltype(&C::ice_tuple)>::value>>
 bool operator==(const C& lhs, const C& rhs)
 {
    return lhs.ice_tuple() == rhs.ice_tuple();
 }
 
+/**
+ * Relational operator for generated structs and classes.
+ * @param lhs The left-hand side.
+ * @param rhs The right-hand side.
+ * @return True if the left-hand side is not equal to the right-hand side, false otherwise.
+ */
 template<class C, typename = std::enable_if<std::is_member_function_pointer<decltype(&C::ice_tuple)>::value>>
 bool operator!=(const C& lhs, const C& rhs)
 {