zeroc-ice 3.7.0 → 3.7.5

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

@@ -1,11 +1,6 @@
-// **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 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.
-//
-// **********************************************************************
 
 #ifndef ICE_STRING_CONVERTER_H
 #define ICE_STRING_CONVERTER_H
@@ -17,34 +12,65 @@
 namespace Ice
 {
 
+/** Encapsulates bytes in the UTF-8 encoding. */
 typedef IceUtil::UTF8Buffer UTF8Buffer;
+
+/** Narrow string converter. */
 typedef IceUtil::StringConverter StringConverter;
 typedef IceUtil::StringConverterPtr StringConverterPtr;
+
+/** Wide string converter. */
 typedef IceUtil::WstringConverter WstringConverter;
 typedef IceUtil::WstringConverterPtr WstringConverterPtr;
 
+/** Indicates an error occurred during string conversion. */
 typedef IceUtil::IllegalConversionException IllegalConversionException;
 
 #ifdef ICE_CPP11_MAPPING
+/** Base class for a string converter. */
 template<typename charT>
 using BasicStringConverter = IceUtil::BasicStringConverter<charT>;
 #endif
 
 #ifdef _WIN32
+/**
+ * Creates a string converter that converts between multi-byte and UTF-8 strings and uses MultiByteToWideChar
+ * and WideCharToMultiByte for its implementation.
+ */
 using IceUtil::createWindowsStringConverter;
 #endif
 
+/** Creates a string converter that converts between Unicode wide strings and UTF-8 strings. */
 using IceUtil::createUnicodeWstringConverter;
 
+/** Installs a default narrow string converter for the process. */
 using IceUtil::setProcessStringConverter;
+
+/** Obtains the default narrow string converter for the process. */
 using IceUtil::getProcessStringConverter;
+
+/** Installs a default wide string converter for the process. */
 using IceUtil::setProcessWstringConverter;
+
+/** Obtains the default wide string converter for the process. */
 using IceUtil::getProcessWstringConverter;
 
+/** Converts a wide string to a narrow string. */
 using IceUtil::wstringToString;
+
+/** Converts a narrow string to a wide string. */
 using IceUtil::stringToWstring;
 
+/**
+ * Converts a narrow string to a UTF-8 encoded string using a string converter.
+ * No conversion is performed if the string converter is nil.
+ */
 using IceUtil::nativeToUTF8;
+
+/**
+ * Converts a UTF-8 encoded string to a narrow string using a string converter.
+ * No conversion is performed if the string converter is nil.
+ */
 using IceUtil::UTF8ToNative;
 
 }

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

@@ -1,11 +1,6 @@
-// **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 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.
-//
-// **********************************************************************
 
 #ifndef ICE_THREAD_POOL_F_H
 #define ICE_THREAD_POOL_F_H

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

@@ -1,11 +1,6 @@
-// **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 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.
-//
-// **********************************************************************
 
 #ifndef ICE_UUID_H
 #define ICE_UUID_H
@@ -16,6 +11,7 @@
 namespace Ice
 {
 
+/** Generates a UUID. */
 using IceUtil::generateUUID;
 
 }

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

@@ -1,11 +1,6 @@
-// **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 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.
-//
-// **********************************************************************
 
 #ifndef ICE_UNIQUE_PTR_H
 #define ICE_UNIQUE_PTR_H
@@ -95,6 +90,6 @@ private:
 
 #endif
 
-} // End of namespace IceUtil
+}
 
 #endif

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

@@ -1,11 +1,6 @@
-// **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 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.
-//
-// **********************************************************************
 
 #ifndef ICE_UNIQUE_REF_H
 #define ICE_UNIQUE_REF_H
@@ -47,7 +42,11 @@ public:
 
     void reset(R ref = 0)
     {
-        assert(ref == 0 || ref != _ref);
+        //
+        // Support "self-reset" for CF objects. This is useful if CF allocation methods return
+        // the same object with an increased reference count.
+        //
+        //assert(ref == 0 || ref != _ref);
 
         if(_ref != 0)
         {

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

@@ -1,11 +1,6 @@
-// **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 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.
-//
-// **********************************************************************
 
 #ifndef ICE_USER_EXCEPTION_FACTORY_H
 #define ICE_USER_EXCEPTION_FACTORY_H
@@ -19,6 +14,7 @@
 namespace Ice
 {
 
+/** Creates and throws a user exception. */
 using UserExceptionFactory = std::function<void(const std::string&)>;
 
 }
@@ -44,6 +40,10 @@ defaultUserExceptionFactory(const std::string& typeId)
 namespace Ice
 {
 
+/**
+ * Creates and throws a user exception.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API UserExceptionFactory : public IceUtil::Shared
 {
 public:

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

@@ -1,11 +1,6 @@
-// **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 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.
-//
-// **********************************************************************
 
 #ifndef ICE_VALUE_H
 #define ICE_VALUE_H
@@ -21,6 +16,10 @@
 namespace Ice
 {
 
+/**
+ * The base class for instances of Slice classes.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API Value
 {
 public:
@@ -36,26 +35,61 @@ public:
     Value& operator=(Value&&) = default;
     virtual ~Value() = default;
 
+    /**
+     * The Ice run time invokes this method prior to marshaling an object's data members. This allows a subclass
+     * to override this method in order to validate its data members.
+     */
     virtual void ice_preMarshal();
+
+    /**
+     * The Ice run time invokes this method after unmarshaling an object's data members. This allows a
+     * subclass to override this method in order to perform additional initialization.
+     */
     virtual void ice_postUnmarshal();
 
+    /**
+     * Obtains the Slice type ID of the most-derived class supported by this object.
+     * @return The type ID.
+     */
     virtual std::string ice_id() const;
+
+    /**
+     * Obtains the Slice type ID of this type.
+     * @return The return value is always "::Ice::Object".
+     */
     static const std::string& ice_staticId();
 
+    /**
+     * Returns a shallow copy of the object.
+     * @return The cloned value.
+     */
     std::shared_ptr<Value> ice_clone() const;
 
+    /**
+     * Obtains the sliced data associated with this instance.
+     * @return The sliced data if the value has a preserved-slice base class and has been sliced during
+     * unmarshaling of the value, nil otherwise.
+     */
     virtual std::shared_ptr<SlicedData> ice_getSlicedData() const;
 
+    /// \cond STREAM
     virtual void _iceWrite(Ice::OutputStream*) const;
     virtual void _iceRead(Ice::InputStream*);
+    /// \endcond
 
 protected:
 
+    /// \cond INTERNAL
     virtual std::shared_ptr<Value> _iceCloneImpl() const = 0;
+    /// \endcond
+
+    /// \cond STREAM
     virtual void _iceWriteImpl(Ice::OutputStream*) const {}
     virtual void _iceReadImpl(Ice::InputStream*) {}
+    /// \endcond
 };
 
+/// \cond INTERNAL
 template<typename T, typename Base> class ValueHelper : public Base
 {
 public:
@@ -97,6 +131,7 @@ protected:
         Base::_iceReadImpl(is);
     }
 };
+/// \endcond
 
 }
 #endif // C++11 mapping end

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

@@ -1,11 +1,6 @@
-// **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 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.
-//
-// **********************************************************************
 
 #ifndef ICE_VALUE_F_H
 #define ICE_VALUE_F_H
@@ -17,7 +12,9 @@ namespace Ice
 {
 
 class Value;
+/// \cond INTERNAL
 using ValuePtr = ::std::shared_ptr<Value>;
+/// \endcond
 
 }
 #endif

data/ext/ice/cpp/include/IceSSL/Config.h

@@ -1,11 +1,6 @@
-// **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 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.
-//
-// **********************************************************************
 
 #ifndef ICESSL_CONFIG_H
 #define ICESSL_CONFIG_H

data/ext/ice/cpp/include/IceSSL/IceSSL.h

@@ -1,11 +1,6 @@
-// **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 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.
-//
-// **********************************************************************
 
 #ifndef ICESSL_ICESSL_H
 #define ICESSL_ICESSL_H

data/ext/ice/cpp/include/IceSSL/OpenSSL.h

@@ -1,11 +1,6 @@
-// **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 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.
-//
-// **********************************************************************
 
 #ifndef ICESSL_OPENSSL_H
 #define ICESSL_OPENSSL_H
@@ -43,7 +38,14 @@
 namespace Ice
 {
 
-ICE_PLUGIN_REGISTER_DECLSPEC_IMPORT void registerIceSSLOpenSSL(bool = true);
+/**
+ * When using static libraries, calling this function ensures the OpenSSL version of the IceSSL plug-in is
+ * linked with the application.
+ * @param loadOnInitialize If true, the plug-in is loaded (created) during communicator initialization.
+ * If false, the plug-in is only loaded during communicator initialization if its corresponding plug-in
+ * property is set to 1.
+ */
+ICE_PLUGIN_REGISTER_DECLSPEC_IMPORT void registerIceSSLOpenSSL(bool loadOnInitialize = true);
 
 }
 #endif
@@ -57,69 +59,84 @@ namespace OpenSSL
 class Certificate;
 ICE_DEFINE_PTR(CertificatePtr, Certificate);
 
+/**
+ * Encapsulates an OpenSSL X.509 certificate.
+ * \headerfile IceSSL/IceSSL.h
+ */
 class ICESSL_OPENSSL_API Certificate : public virtual IceSSL::Certificate
 {
 public:
 
-    //
-    // Construct a certificate using a native certificate.
-    //
-    // The Certificate class assumes ownership of the given native
-    // certificate.
-    //
-    static CertificatePtr create(x509_st*);
-
-    //
-    // Load the certificate from a file. The certificate must use the
-    // PEM encoding format. Raises CertificateReadException if the
-    // file cannot be read.
-    //
-    static CertificatePtr load(const std::string&);
-
-    //
-    // Decode a certificate from a string that uses the PEM encoding
-    // format. Raises CertificateEncodingException if an error
-    // occurs.
-    //
-    static CertificatePtr decode(const std::string&);
-
-    //
-    // Retrieve the native X509 certificate value wrapped by this
-    // object.
-    //
-    // The returned reference is only valid for the lifetime of this
-    // object. you can increment it with X509_dup.
-    //
+    /**
+     * Construct a certificate using a native certificate.
+     * The Certificate class assumes ownership of the given native
+     * certificate.
+     * @param cert The native certificate.
+     * @return A new certificate object.
+     */
+    static CertificatePtr create(x509_st* cert);
+
+    /**
+     * Load the certificate from a file. The certificate must use the
+     * PEM encoding format.
+     * @param file The certificate file.
+     * @return A new certificate object.
+     * @throws CertificateReadException if the file cannot be read.
+     */
+    static CertificatePtr load(const std::string& file);
+
+    /**
+     * Decode a certificate from a string that uses the PEM encoding format.
+     * @param cert A string containing the PEM-encoded certificate.
+     * @return A new certificate object.
+     * @throws CertificateEncodingException if an error occurs.
+     */
+    static CertificatePtr decode(const std::string& cert);
+
+    /**
+     * Retrieve the native X509 certificate value wrapped by this object.
+     * @return The native certificate. The returned reference is only valid for the lifetime of this
+     * object. You can increment it with X509_dup.
+     */
     virtual x509_st* getCert() const = 0;
 };
 
+/**
+ * Represents the IceSSL plug-in object.
+ * \headerfile IceSSL/IceSSL.h
+ */
 class ICESSL_OPENSSL_API Plugin : public virtual IceSSL::Plugin
 {
 public:
-    //
-    // returns OpenSSL version number.
-    //
+
+    /**
+     * Obtains the OpenSSL version number.
+     * @return The version.
+     */
     virtual Ice::Long getOpenSSLVersion() const = 0;
-    //
-    // Establish the OpenSSL context. This must be done before the
-    // plug-in is initialized, therefore the application must define
-    // the property Ice.InitPlugins=0, set the context, and finally
-    // invoke initializePlugins on the PluginManager.
-    //
-    // When the application supplies its own OpenSSL context, the
-    // plug-in ignores configuration properties related to certificates,
-    // keys, and passwords.
-    //
-    // Note that the plugin assumes ownership of the given context.
-    //
-    virtual void setContext(SSL_CTX*) = 0;
-
-    //
-    // Obtain the SSL context. Use caution when modifying this value.
-    // Changes made to this value have no effect on existing connections.
-    //
-    virtual SSL_CTX* getContext() = 0;
 
+    /**
+     * Establishes the OpenSSL context. This must be done before the
+     * plug-in is initialized, therefore the application must define
+     * the property Ice.InitPlugins=0, set the context, and finally
+     * invoke Ice::PluginManager::initializePlugins.
+     *
+     * When the application supplies its own OpenSSL context, the
+     * plug-in ignores configuration properties related to certificates,
+     * keys, and passwords.
+     *
+     * Note that the plug-in assumes ownership of the given context.
+     *
+     * @param ctx The OpenSSL context.
+     */
+    virtual void setContext(SSL_CTX* ctx) = 0;
+
+    /**
+     * Obtains the SSL context. Use caution when modifying this value.
+     * Changes made to this value have no effect on existing connections.
+     * @return The OpenSSL context.
+     */
+    virtual SSL_CTX* getContext() = 0;
 };
 ICE_DEFINE_PTR(PluginPtr, Plugin);