zeroc-ice 3.6.5 → 3.7.4

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

@@ -1,11 +1,6 @@
-// **********************************************************************
 //
-// Copyright (c) 2003-2018 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_INCOMING_ASYNC_F_H
 #define ICE_INCOMING_ASYNC_F_H
@@ -18,11 +13,16 @@ namespace IceInternal
 {
 
 class IncomingAsync;
+#ifdef ICE_CPP11_MAPPING
+using IncomingAsyncPtr = ::std::shared_ptr<IncomingAsync>;
+#else
 ICE_API IceUtil::Shared* upCast(IncomingAsync*);
 typedef IceInternal::Handle<IncomingAsync> IncomingAsyncPtr;
+#endif
 
 }
 
+#ifndef ICE_CPP11_MAPPING
 namespace Ice
 {
 
@@ -31,5 +31,6 @@ ICE_API IceUtil::Shared* upCast(::Ice::AMD_Object_ice_invoke*);
 typedef IceInternal::Handle<AMD_Object_ice_invoke> AMD_Object_ice_invokePtr;
 
 }
+#endif
 
 #endif

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

@@ -1,21 +1,15 @@
-// **********************************************************************
 //
-// Copyright (c) 2003-2018 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_INITIALIZE_H
 #define ICE_INITIALIZE_H
 
 #include <IceUtil/Timer.h>
-#include <Ice/CommunicatorF.h>
+#include <Ice/Communicator.h>
 #include <Ice/PropertiesF.h>
 #include <Ice/InstanceF.h>
 #include <Ice/LoggerF.h>
-#include <Ice/StreamF.h>
 #include <Ice/InstrumentationF.h>
 #include <Ice/Dispatcher.h>
 #include <Ice/FactoryTable.h>
@@ -24,109 +18,927 @@
 #include <Ice/Plugin.h>
 #include <Ice/BatchRequestInterceptor.h>
 
+#ifdef ICE_CPP11_MAPPING
+#   define ICE_CONFIG_FILE_STRING const std::string&
+#else
+#   define ICE_CONFIG_FILE_STRING const char*
+#endif
+
 namespace Ice
 {
 
-ICE_API StringSeq argsToStringSeq(int, char*[]);
+/**
+ * Converts an argument vector into a string sequence.
+ * @param argc The number of arguments in argv.
+ * @param argv The arguments.
+ * @return A string sequence containing the arguments.
+ */
+ICE_API StringSeq argsToStringSeq(int argc, const char* const argv[]);
 
 #ifdef _WIN32
+/**
+ * Converts an argument vector into a string sequence.
+ * @param argc The number of arguments in argv.
+ * @param argv The arguments.
+ * @return A string sequence containing the arguments.
+ */
+ICE_API StringSeq argsToStringSeq(int argc, const wchar_t* const argv[]);
+#endif
 
-ICE_API StringSeq argsToStringSeq(int, wchar_t*[]);
+/**
+ * Updates the argument vector to match the contents of the string sequence.
+ * This function assumes that the string sequence only contains
+ * elements of the argument vector. The function shifts the
+ * the argument vector elements so that the vector matches the
+ * contents of the sequence.
+ * @param seq The string sequence returned from a call to argsToStringSeq.
+ * @param argc Updated to reflect the size of the sequence.
+ * @param argv Elements are shifted to match the sequence.
+ */
+ICE_API void stringSeqToArgs(const StringSeq& seq, int& argc, const char* argv[]);
 
-#endif
+/**
+ * Updates the argument vector to match the contents of the string sequence.
+ * This function assumes that the string sequence only contains
+ * elements of the argument vector. The function shifts the
+ * the argument vector elements so that the vector matches the
+ * contents of the sequence.
+ * @param seq The string sequence returned from a call to argsToStringSeq.
+ * @param argc Updated to reflect the size of the sequence.
+ * @param argv Elements are shifted to match the sequence.
+ */
+inline void stringSeqToArgs(const StringSeq& seq, int& argc, char* argv[])
+{
+    return stringSeqToArgs(seq, argc, const_cast<const char**>(argv));
+}
 
-//
-// This function assumes that the string sequence only contains
-// elements of the argument vector. The function shifts the
-// the argument vector elements so that the vector matches the
-// contents of the sequence.
-//
-ICE_API void stringSeqToArgs(const StringSeq&, int&, char*[]);
+#ifdef _WIN32
+/**
+ * Updates the argument vector to match the contents of the string sequence.
+ * This function assumes that the string sequence only contains
+ * elements of the argument vector. The function shifts the
+ * the argument vector elements so that the vector matches the
+ * contents of the sequence.
+ * @param seq The string sequence returned from a call to argsToStringSeq.
+ */
+ICE_API void stringSeqToArgs(const StringSeq& seq, int& argc, const wchar_t* argv[]);
+
+/**
+ * Updates the argument vector to match the contents of the string sequence.
+ * This function assumes that the string sequence only contains
+ * elements of the argument vector. The function shifts the
+ * the argument vector elements so that the vector matches the
+ * contents of the sequence.
+ * @param seq The string sequence returned from a call to argsToStringSeq.
+ */
+inline void stringSeqToArgs(const StringSeq& seq, int& argc, wchar_t* argv[])
+{
+    return stringSeqToArgs(seq, argc, const_cast<const wchar_t**>(argv));
+}
+#endif
 
+/**
+ * Creates a new empty property set.
+ *
+ * @return A new empty property set.
+ */
 ICE_API PropertiesPtr createProperties();
-ICE_API PropertiesPtr createProperties(StringSeq&, const PropertiesPtr& = 0);
-ICE_API PropertiesPtr createProperties(int&, char*[], const PropertiesPtr& = 0);
 
-//
-// This class is used to notify user of when Ice threads are started
-// and stopped.
-//
+/**
+ * Creates a property set initialized from command-line arguments
+ * and a default property set.
+ *
+ * @param seq Command-line arguments, possibly containing
+ * options to set properties. If the arguments include
+ * a <code>--Ice.Config</code> option, the corresponding configuration
+ * files are parsed. If the same property is set in a configuration
+ * file and in the arguments, the arguments take precedence.
+ * Recognized options are removed from this container upon return.
+ *
+ * @param defaults Default values for the property set. Settings in
+ * configuration files and the arguments override these defaults.
+ *
+ * @return A new property set initialized with the property settings
+ * that were removed from the argument vector.
+ */
+ICE_API PropertiesPtr createProperties(StringSeq& seq, const PropertiesPtr& defaults = 0);
+
+/**
+ * Creates a property set initialized from command-line arguments
+ * and a default property set.
+ *
+ * @param argc The number of arguments in argv. Upon return, this argument
+ * is updated to reflect the arguments still remaining in argv.
+ * @param argv Command-line arguments, possibly containing
+ * options to set properties. If the arguments include
+ * a <code>--Ice.Config</code> option, the corresponding configuration
+ * files are parsed. If the same property is set in a configuration
+ * file and in the arguments, the arguments take precedence.
+ * Recognized options are removed from this vector upon return.
+ *
+ * @param defaults Default values for the property set. Settings in
+ * configuration files and the arguments override these defaults.
+ *
+ * @return A new property set initialized with the property settings
+ * that were removed from the argument vector.
+ */
+ICE_API PropertiesPtr createProperties(int& argc, const char* argv[], const PropertiesPtr& defaults = 0);
+
+/**
+ * Creates a property set initialized from command-line arguments
+ * and a default property set.
+ *
+ * @param argc The number of arguments in argv. Upon return, this argument
+ * is updated to reflect the arguments still remaining in argv.
+ * @param argv Command-line arguments, possibly containing
+ * options to set properties. If the arguments include
+ * a <code>--Ice.Config</code> option, the corresponding configuration
+ * files are parsed. If the same property is set in a configuration
+ * file and in the arguments, the arguments take precedence.
+ * Recognized options are removed from this vector upon return.
+ *
+ * @param defaults Default values for the property set. Settings in
+ * configuration files and the arguments override these defaults.
+ *
+ * @return A new property set initialized with the property settings
+ * that were removed from the argument vector.
+ */
+inline PropertiesPtr createProperties(int& argc, char* argv[], const PropertiesPtr& defaults = 0)
+{
+    return createProperties(argc, const_cast<const char**>(argv), defaults);
+}
+
+#ifdef _WIN32
+/**
+ * Creates a property set initialized from command-line arguments
+ * and a default property set.
+ *
+ * @param argc The number of arguments in argv. Upon return, this argument
+ * is updated to reflect the arguments still remaining in argv.
+ * @param argv Command-line arguments, possibly containing
+ * options to set properties. If the arguments include
+ * a <code>--Ice.Config</code> option, the corresponding configuration
+ * files are parsed. If the same property is set in a configuration
+ * file and in the arguments, the arguments take precedence.
+ * Recognized options are removed from this vector upon return.
+ *
+ * @param defaults Default values for the property set. Settings in
+ * configuration files and the arguments override these defaults.
+ *
+ * @return A new property set initialized with the property settings
+ * that were removed from the argument vector.
+ */
+ICE_API PropertiesPtr createProperties(int& argc, const wchar_t* argv[], const PropertiesPtr& defaults = 0);
+
+/**
+ * Creates a property set initialized from command-line arguments
+ * and a default property set.
+ *
+ * @param argc The number of arguments in argv. Upon return, this argument
+ * is updated to reflect the arguments still remaining in argv.
+ * @param argv Command-line arguments, possibly containing
+ * options to set properties. If the arguments include
+ * a <code>--Ice.Config</code> option, the corresponding configuration
+ * files are parsed. If the same property is set in a configuration
+ * file and in the arguments, the arguments take precedence.
+ * Recognized options are removed from this vector upon return.
+ *
+ * @param defaults Default values for the property set. Settings in
+ * configuration files and the arguments override these defaults.
+ *
+ * @return A new property set initialized with the property settings
+ * that were removed from the argument vector.
+ */
+inline PropertiesPtr createProperties(int& argc, wchar_t* argv[], const PropertiesPtr& defaults = 0)
+{
+    return createProperties(argc, const_cast<const wchar_t**>(argv), defaults);
+}
+#endif
+
+/**
+ * Base class for a thread notification hook. An application can subclass this class,
+ * implement start and stop, and install an instance in InitializationData in order
+ * to receive notifications when Ice threads are started and stopped.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API ThreadNotification : public IceUtil::Shared
 {
 public:
 
+    /**
+     * Called from the new Ice thread at startup.
+     */
     virtual void start() = 0;
+
+    /**
+     * Called from an Ice thread that is about to stop.
+     */
     virtual void stop() = 0;
 };
 
 typedef IceUtil::Handle<ThreadNotification> ThreadNotificationPtr;
 
-//
-// A special plug-in that installs thread hook during a communicator's initialization.
-// Both initialize and destroy are no-op. See Ice::InitializationData.
-//
+/**
+ * A special plug-in that installs a thread hook during a communicator's initialization.
+ * Both initialize and destroy are no-op. See InitializationData.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API ThreadHookPlugin : public Ice::Plugin
 {
 public:
 
-    ThreadHookPlugin(const CommunicatorPtr& communicator, const ThreadNotificationPtr&);
+#ifdef ICE_CPP11_MAPPING
+    /**
+     * Installs the thread hooks.
+     * @param communicator The communicator in which to install the thread hooks.
+     * @param start The start callback.
+     * @param stop The stop callback.
+     */
+    ThreadHookPlugin(const CommunicatorPtr& communicator, std::function<void()> start, std::function<void()> stop);
+#else
+    /**
+     * Installs the thread hooks.
+     * @param communicator The communicator in which to install the thread hooks.
+     * @param hook The thread notification callback object.
+     */
+    ThreadHookPlugin(const CommunicatorPtr& communicator, const ThreadNotificationPtr& hook);
+#endif
 
+    /** Not used. */
     virtual void initialize();
 
+    /** Not used. */
     virtual void destroy();
 };
 
-//
-// Communicator initialization info
-//
+/**
+ * Encapsulates data to initialize a communicator.
+ * \headerfile Ice/Ice.h
+ */
 struct InitializationData
 {
+    /**
+     * The properties for the communicator.
+     */
     PropertiesPtr properties;
+
+    /**
+     * The logger for the communicator.
+     */
     LoggerPtr logger;
+
+    /**
+     * The communicator observer used by the Ice run-time.
+     */
     Instrumentation::CommunicatorObserverPtr observer;
+
+#ifdef ICE_CPP11_MAPPING
+
+#if defined(__clang__)
+#   pragma clang diagnostic push
+#   pragma clang diagnostic ignored "-Wdocumentation" // param/return is not recognized for std::function data members
+#endif
+
+    /**
+     * Called whenever the communicator starts a new thread.
+     */
+    std::function<void()> threadStart;
+
+    /**
+     * Called whenever a thread created by the communicator is about to be destroyed.
+     */
+    std::function<void()> threadStop;
+
+    /**
+      * You can control which thread receives operation invocations and AMI
+      * callbacks by supplying a dispatcher.
+      *
+      * For example, you can use this dispatching facility to ensure that
+      * all invocations and callbacks are dispatched in a GUI event loop
+      * thread so that it is safe to invoke directly on GUI objects.
+      *
+      * The dispatcher is responsible for running (dispatching) the
+      * invocation or AMI callback on its favorite thread.
+      * @param call Represents the invocation. The dispatcher must eventually invoke this function.
+      * @param con The connection associated with this dispatch, or nil if no connection is
+      * associated with it.
+      */
+    std::function<void(std::function<void()> call, const std::shared_ptr<Ice::Connection>& con)> dispatcher;
+
+    /**
+     * Applications that make use of compact type IDs to conserve space
+     * when marshaling class instances, and also use the streaming API to
+     * extract such classes, can intercept the translation between compact
+     * type IDs and their corresponding string type IDs by installing a
+     * compact ID resolver.
+     * @param id The compact ID.
+     * @return The fully-scoped type ID such as "::Module::Class", or an empty string if
+     * the compact ID is unknown.
+     */
+    std::function<std::string(int id)> compactIdResolver;
+
+    /**
+     * The batch request interceptor, which is 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.
+     */
+    std::function<void(const Ice::BatchRequest& req, int count, int size)> batchRequestInterceptor;
+
+#if defined(__clang__)
+#   pragma clang diagnostic pop
+#endif
+
+#else
+    /**
+     * The thread hook for the communicator.
+     */
     ThreadNotificationPtr threadHook;
+
+    /**
+      * You can control which thread receives operation invocations and AMI
+      * callbacks by supplying a dispatcher.
+      *
+      * For example, you can use this dispatching facility to ensure that
+      * all invocations and callbacks are dispatched in a GUI event loop
+      * thread so that it is safe to invoke directly on GUI objects.
+      *
+      * The dispatcher is responsible for running (dispatching) the
+      * invocation or AMI callback on its favorite thread. It must eventually
+      * execute the provided call.
+      */
     DispatcherPtr dispatcher;
+
+    /**
+     * Applications that make use of compact type IDs to conserve space
+     * when marshaling class instances, and also use the streaming API to
+     * extract such classes, can intercept the translation between compact
+     * type IDs and their corresponding string type IDs by installing a
+     * compact ID resolver.
+     */
     CompactIdResolverPtr compactIdResolver;
+
+    /**
+     * The batch request interceptor.
+     */
     BatchRequestInterceptorPtr batchRequestInterceptor;
+#endif
+
+    /**
+     * The value factory manager.
+     */
+    ValueFactoryManagerPtr valueFactoryManager;
 };
 
-ICE_API CommunicatorPtr initialize(int&, char*[], const InitializationData& = InitializationData(),
-                                   Int = ICE_INT_VERSION);
+/**
+ * Initializes a new communicator.
+ * @param argc The number of arguments in argv. Upon return, this argument
+ * is updated to reflect the arguments still remaining in argv.
+ * @param argv Command-line arguments, possibly containing
+ * options to set properties. If the arguments include
+ * a <code>--Ice.Config</code> option, the corresponding configuration
+ * files are parsed. If the same property is set in a configuration
+ * file and in the arguments, the arguments take precedence.
+ * Recognized options are removed from this vector upon return.
+ * @param initData Configuration data for the new Communicator.
+ * @param version Indicates the Ice version with which the application is compatible. If not
+ * specified, the version of the Ice installation is used.
+ * @return The new communicator.
+ */
+ICE_API CommunicatorPtr initialize(int& argc, const char* argv[],
+                                   const InitializationData& initData = InitializationData(),
+                                   int version = ICE_INT_VERSION);
+
+/**
+ * Initializes a new communicator.
+ * @param argc The number of arguments in argv. Upon return, this argument
+ * is updated to reflect the arguments still remaining in argv.
+ * @param argv Command-line arguments, possibly containing
+ * options to set properties. If the arguments include
+ * a <code>--Ice.Config</code> option, the corresponding configuration
+ * files are parsed. If the same property is set in a configuration
+ * file and in the arguments, the arguments take precedence.
+ * Recognized options are removed from this vector upon return.
+ * @param initData Configuration data for the new Communicator.
+ * @param version Indicates the Ice version with which the application is compatible. If not
+ * specified, the version of the Ice installation is used.
+ * @return The new communicator.
+ */
+inline CommunicatorPtr initialize(int& argc, char* argv[], const InitializationData& initData = InitializationData(),
+                                   int version = ICE_INT_VERSION)
+{
+    return initialize(argc, const_cast<const char**>(argv), initData, version);
+}
+
+/**
+ * Initializes a new communicator.
+ * @param argc The number of arguments in argv. Upon return, this argument
+ * is updated to reflect the arguments still remaining in argv.
+ * @param argv Command-line arguments, possibly containing
+ * options to set properties. If the arguments include
+ * a <code>--Ice.Config</code> option, the corresponding configuration
+ * files are parsed. If the same property is set in a configuration
+ * file and in the arguments, the arguments take precedence.
+ * Recognized options are removed from this vector upon return.
+ * @param configFile The name of an Ice configuration file.
+ * @param version Indicates the Ice version with which the application is compatible. If not
+ * specified, the version of the Ice installation is used.
+ * @return The new communicator.
+ */
+ICE_API CommunicatorPtr initialize(int& argc, const char* argv[], ICE_CONFIG_FILE_STRING configFile,
+                                   int version = ICE_INT_VERSION);
+
+/**
+ * Initializes a new communicator.
+ * @param argc The number of arguments in argv. Upon return, this argument
+ * is updated to reflect the arguments still remaining in argv.
+ * @param argv Command-line arguments, possibly containing
+ * options to set properties. If the arguments include
+ * a <code>--Ice.Config</code> option, the corresponding configuration
+ * files are parsed. If the same property is set in a configuration
+ * file and in the arguments, the arguments take precedence.
+ * Recognized options are removed from this vector upon return.
+ * @param configFile The name of an Ice configuration file.
+ * @param version Indicates the Ice version with which the application is compatible. If not
+ * specified, the version of the Ice installation is used.
+ * @return The new communicator.
+ */
+inline CommunicatorPtr initialize(int& argc, char* argv[], ICE_CONFIG_FILE_STRING configFile,
+                                  int version = ICE_INT_VERSION)
+{
+    return initialize(argc, const_cast<const char**>(argv), configFile, version);
+}
+
+#ifdef _WIN32
+/**
+ * Initializes a new communicator.
+ * @param argc The number of arguments in argv. Upon return, this argument
+ * is updated to reflect the arguments still remaining in argv.
+ * @param argv Command-line arguments, possibly containing
+ * options to set properties. If the arguments include
+ * a <code>--Ice.Config</code> option, the corresponding configuration
+ * files are parsed. If the same property is set in a configuration
+ * file and in the arguments, the arguments take precedence.
+ * Recognized options are removed from this vector upon return.
+ * @param initData Configuration data for the new Communicator.
+ * @param version Indicates the Ice version with which the application is compatible. If not
+ * specified, the version of the Ice installation is used.
+ * @return The new communicator.
+ */
+ICE_API CommunicatorPtr initialize(int& argc, const wchar_t* argv[],
+                                   const InitializationData& initData = InitializationData(),
+                                   int version = ICE_INT_VERSION);
+
+/**
+ * Initializes a new communicator.
+ * @param argc The number of arguments in argv. Upon return, this argument
+ * is updated to reflect the arguments still remaining in argv.
+ * @param argv Command-line arguments, possibly containing
+ * options to set properties. If the arguments include
+ * a <code>--Ice.Config</code> option, the corresponding configuration
+ * files are parsed. If the same property is set in a configuration
+ * file and in the arguments, the arguments take precedence.
+ * Recognized options are removed from this vector upon return.
+ * @param initData Configuration data for the new Communicator.
+ * @param version Indicates the Ice version with which the application is compatible. If not
+ * specified, the version of the Ice installation is used.
+ * @return The new communicator.
+ */
+inline CommunicatorPtr initialize(int& argc, wchar_t* argv[], const InitializationData& initData = InitializationData(),
+                                   int version = ICE_INT_VERSION)
+{
+    return initialize(argc, const_cast<const wchar_t**>(argv), initData, version);
+}
 
-ICE_API CommunicatorPtr initialize(Ice::StringSeq&, const InitializationData& = InitializationData(),
-                                   Int = ICE_INT_VERSION);
+/**
+ * Initializes a new communicator.
+ * @param argc The number of arguments in argv. Upon return, this argument
+ * is updated to reflect the arguments still remaining in argv.
+ * @param argv Command-line arguments, possibly containing
+ * options to set properties. If the arguments include
+ * a <code>--Ice.Config</code> option, the corresponding configuration
+ * files are parsed. If the same property is set in a configuration
+ * file and in the arguments, the arguments take precedence.
+ * Recognized options are removed from this vector upon return.
+ * @param configFile The name of an Ice configuration file.
+ * @param version Indicates the Ice version with which the application is compatible. If not
+ * specified, the version of the Ice installation is used.
+ * @return The new communicator.
+ */
+ICE_API CommunicatorPtr initialize(int& argc, const wchar_t* argv[], ICE_CONFIG_FILE_STRING configFile,
+                                   int version = ICE_INT_VERSION);
 
-ICE_API CommunicatorPtr initialize(const InitializationData& = InitializationData(),
-                                   Int = ICE_INT_VERSION);
+/**
+ * Initializes a new communicator.
+ * @param argc The number of arguments in argv. Upon return, this argument
+ * is updated to reflect the arguments still remaining in argv.
+ * @param argv Command-line arguments, possibly containing
+ * options to set properties. If the arguments include
+ * a <code>--Ice.Config</code> option, the corresponding configuration
+ * files are parsed. If the same property is set in a configuration
+ * file and in the arguments, the arguments take precedence.
+ * Recognized options are removed from this vector upon return.
+ * @param configFile The name of an Ice configuration file.
+ * @param version Indicates the Ice version with which the application is compatible. If not
+ * specified, the version of the Ice installation is used.
+ * @return The new communicator.
+ */
+inline CommunicatorPtr initialize(int& argc, wchar_t* argv[], ICE_CONFIG_FILE_STRING configFile,
+                                  int version = ICE_INT_VERSION)
+{
+    return initialize(argc, const_cast<const wchar_t**>(argv), configFile, version);
+}
+#endif
+
+/**
+ * Initializes a new communicator.
+ * @param seq Command-line arguments, possibly containing
+ * options to set properties. If the arguments include
+ * a <code>--Ice.Config</code> option, the corresponding configuration
+ * files are parsed. If the same property is set in a configuration
+ * file and in the arguments, the arguments take precedence.
+ * Recognized options are removed from this container upon return.
+ * @param initData Configuration data for the new Communicator.
+ * @param version Indicates the Ice version with which the application is compatible. If not
+ * specified, the version of the Ice installation is used.
+ * @return The new communicator.
+ */
+ICE_API CommunicatorPtr initialize(StringSeq& seq, const InitializationData& initData = InitializationData(),
+                                   int version = ICE_INT_VERSION);
 
+/**
+ * Initializes a new communicator.
+ * @param seq Command-line arguments, possibly containing
+ * options to set properties. If the arguments include
+ * a <code>--Ice.Config</code> option, the corresponding configuration
+ * files are parsed. If the same property is set in a configuration
+ * file and in the arguments, the arguments take precedence.
+ * Recognized options are removed from this container upon return.
+ * @param configFile The name of an Ice configuration file.
+ * @param version Indicates the Ice version with which the application is compatible. If not
+ * specified, the version of the Ice installation is used.
+ * @return The new communicator.
+ */
+ICE_API CommunicatorPtr initialize(StringSeq& seq, ICE_CONFIG_FILE_STRING configFile, int version = ICE_INT_VERSION);
 
-ICE_API InputStreamPtr createInputStream(const CommunicatorPtr&, const ::std::vector< Byte >&);
-ICE_API InputStreamPtr createInputStream(const CommunicatorPtr&, const ::std::vector< Byte >&,
-                                         const EncodingVersion&);
-ICE_API InputStreamPtr wrapInputStream(const CommunicatorPtr&, const ::std::vector< Byte >&);
-ICE_API InputStreamPtr wrapInputStream(const CommunicatorPtr&, const ::std::vector< Byte >&, const EncodingVersion&);
-ICE_API InputStreamPtr createInputStream(const CommunicatorPtr&,
-                                         const ::std::pair< const Ice::Byte*, const Ice::Byte*>&);
-ICE_API InputStreamPtr createInputStream(const CommunicatorPtr&,
-                                         const ::std::pair< const Ice::Byte*, const Ice::Byte*>&,
-                                         const EncodingVersion&);
-ICE_API InputStreamPtr wrapInputStream(const CommunicatorPtr&,
-                                       const ::std::pair< const Ice::Byte*, const Ice::Byte*>&);
-ICE_API InputStreamPtr wrapInputStream(const CommunicatorPtr&,
-                                       const ::std::pair< const Ice::Byte*, const Ice::Byte*>&,
-                                       const EncodingVersion&);
+/**
+ * Initializes a new communicator.
+ * @param initData Configuration data for the new Communicator.
+ * @param version Indicates the Ice version with which the application is compatible. If not
+ * specified, the version of the Ice installation is used.
+ * @return The new communicator.
+ */
+ICE_API CommunicatorPtr initialize(const InitializationData& initData = InitializationData(),
+                                   int version = ICE_INT_VERSION);
 
-ICE_API OutputStreamPtr createOutputStream(const CommunicatorPtr&);
-ICE_API OutputStreamPtr createOutputStream(const CommunicatorPtr&, const EncodingVersion&);
+/**
+ * Initializes a new communicator.
+ * @param configFile The name of an Ice configuration file.
+ * @param version Indicates the Ice version with which the application is compatible. If not
+ * specified, the version of the Ice installation is used.
+ * @return The new communicator.
+ */
+ICE_API CommunicatorPtr initialize(ICE_CONFIG_FILE_STRING configFile, int version = ICE_INT_VERSION);
 
+/**
+ * Obtains the per-process logger. This logger is used by all communicators that do not have their
+ * own specific logger established at the time a communicator is created.
+ * @return The current per-process logger instance.
+ */
 ICE_API LoggerPtr getProcessLogger();
-ICE_API void setProcessLogger(const LoggerPtr&);
 
-typedef Ice::Plugin* (*PLUGIN_FACTORY)(const ::Ice::CommunicatorPtr&, const std::string&, const ::Ice::StringSeq&);
-ICE_API void registerPluginFactory(const std::string&, PLUGIN_FACTORY, bool);
+/**
+ * Sets the per-process logger. This logger is used by all communicators that do not have their
+ * own specific logger established at the time a communicator is created.
+ * @param logger The new per-process logger instance.
+ */
+ICE_API void setProcessLogger(const LoggerPtr& logger);
+
+/**
+ * A plug-in factory function is responsible for creating an Ice plug-in.
+ * @param communicator The communicator in which the plug-in will be installed.
+ * @param name The name assigned to the plug-in.
+ * @param args Additional arguments included in the plug-in's configuration.
+ * @return The new plug-in object. Returning nil will cause the run time to raise PluginInitializationException.
+ */
+typedef Ice::Plugin* (*PluginFactory)(const ::Ice::CommunicatorPtr& communicator, const std::string& name,
+                                      const ::Ice::StringSeq& args);
+
+/**
+ * Manually registers a plug-in factory function.
+ * @param name The name assigned to the plug-in.
+ * @param factory The factory function.
+ * @param loadOnInit If true, the plug-in is always loaded (created) during communicator initialization,
+ * even if Ice.Plugin.name is not set. When false, the plug-in is loaded (created) during communication
+ * initialization only if Ice.Plugin.name  is set to a non-empty value (e.g.: Ice.Plugin.IceSSL=1).
+ */
+ICE_API void registerPluginFactory(const std::string& name, PluginFactory factory, bool loadOnInit);
+
+/**
+ * A helper class that uses Resource Acquisition Is Initialization (RAII) to initialize and hold a
+ * communicator instance, and automatically destroy the communicator when the holder goes out of scope.
+ * \headerfile Ice/Ice.h
+ */
+class ICE_API CommunicatorHolder
+{
+public:
+
+    /**
+     * The holder's initial state is empty.
+     */
+    CommunicatorHolder();
+
+#ifdef ICE_CPP11_MAPPING
+
+    /**
+     * Calls initialize to create a communicator with the provided arguments.
+     * This constructor accepts all of the same overloaded argument styles as
+     * initialize.
+     */
+    template<class... T>
+    explicit CommunicatorHolder(T&&... args) :
+        _communicator(std::move(initialize(std::forward<T>(args)...)))
+    {
+    }
+
+    /**
+     * Adopts the given communicator.
+     * @param communicator The new communicator instance to hold.
+     */
+    CommunicatorHolder(std::shared_ptr<Communicator> communicator);
+
+    /**
+     * Adopts the given communicator. If this holder currently holds a communicator,
+     * it will be destroyed.
+     * @param communicator The new communicator instance to hold.
+     */
+    CommunicatorHolder& operator=(std::shared_ptr<Communicator> communicator);
+
+    CommunicatorHolder(const CommunicatorHolder&) = delete;
+    CommunicatorHolder(CommunicatorHolder&&) = default;
+
+    /**
+     * Adopts the communicator in the given holder. If this holder currently holds a communicator,
+     * it will be destroyed.
+     * @param holder The holder from which to adopt a communicator.
+     */
+    CommunicatorHolder& operator=(CommunicatorHolder&& holder) noexcept;
+
+    /**
+     * Determines whether the holder contains an instance.
+     * @return True if the holder currently holds an instance, false otherwise.
+     */
+    explicit operator bool() const;
+
+#else // C++98 mapping
+
+    /**
+     * Initializes a new communicator.
+     * @param argc The number of arguments in argv. Upon return, this argument
+     * is updated to reflect the arguments still remaining in argv.
+     * @param argv Command-line arguments, possibly containing
+     * options to set properties. If the arguments include
+     * a <code>--Ice.Config</code> option, the corresponding configuration
+     * files are parsed. If the same property is set in a configuration
+     * file and in the arguments, the arguments take precedence.
+     * Recognized options are removed from this vector upon return.
+     * @param initData Configuration data for the new Communicator.
+     * @param version Indicates the Ice version with which the application is compatible. If not
+     * specified, the version of the Ice installation is used.
+     */
+    CommunicatorHolder(int& argc, const char* argv[], const InitializationData& initData = InitializationData(),
+                       int version = ICE_INT_VERSION);
+
+    /**
+     * Initializes a new communicator.
+     * @param argc The number of arguments in argv. Upon return, this argument
+     * is updated to reflect the arguments still remaining in argv.
+     * @param argv Command-line arguments, possibly containing
+     * options to set properties. If the arguments include
+     * a <code>--Ice.Config</code> option, the corresponding configuration
+     * files are parsed. If the same property is set in a configuration
+     * file and in the arguments, the arguments take precedence.
+     * Recognized options are removed from this vector upon return.
+     * @param initData Configuration data for the new Communicator.
+     * @param version Indicates the Ice version with which the application is compatible. If not
+     * specified, the version of the Ice installation is used.
+     */
+    CommunicatorHolder(int& argc, char* argv[], const InitializationData& initData = InitializationData(),
+                       int version = ICE_INT_VERSION);
+
+    /**
+     * Initializes a new communicator.
+     * @param argc The number of arguments in argv. Upon return, this argument
+     * is updated to reflect the arguments still remaining in argv.
+     * @param argv Command-line arguments, possibly containing
+     * options to set properties. If the arguments include
+     * a <code>--Ice.Config</code> option, the corresponding configuration
+     * files are parsed. If the same property is set in a configuration
+     * file and in the arguments, the arguments take precedence.
+     * Recognized options are removed from this vector upon return.
+     * @param configFile The name of an Ice configuration file.
+     * @param version Indicates the Ice version with which the application is compatible. If not
+     * specified, the version of the Ice installation is used.
+     */
+    CommunicatorHolder(int& argc, const char* argv[], const char* configFile, int version = ICE_INT_VERSION);
+
+    /**
+     * Initializes a new communicator.
+     * @param argc The number of arguments in argv. Upon return, this argument
+     * is updated to reflect the arguments still remaining in argv.
+     * @param argv Command-line arguments, possibly containing
+     * options to set properties. If the arguments include
+     * a <code>--Ice.Config</code> option, the corresponding configuration
+     * files are parsed. If the same property is set in a configuration
+     * file and in the arguments, the arguments take precedence.
+     * Recognized options are removed from this vector upon return.
+     * @param configFile The name of an Ice configuration file.
+     * @param version Indicates the Ice version with which the application is compatible. If not
+     * specified, the version of the Ice installation is used.
+     */
+    CommunicatorHolder(int& argc, char* argv[], const char* configFile, int version = ICE_INT_VERSION);
+
+#   ifdef _WIN32
+    /**
+     * Initializes a new communicator.
+     * @param argc The number of arguments in argv. Upon return, this argument
+     * is updated to reflect the arguments still remaining in argv.
+     * @param argv Command-line arguments, possibly containing
+     * options to set properties. If the arguments include
+     * a <code>--Ice.Config</code> option, the corresponding configuration
+     * files are parsed. If the same property is set in a configuration
+     * file and in the arguments, the arguments take precedence.
+     * Recognized options are removed from this vector upon return.
+     * @param initData Configuration data for the new Communicator.
+     * @param version Indicates the Ice version with which the application is compatible. If not
+     * specified, the version of the Ice installation is used.
+     */
+    CommunicatorHolder(int& argc, const wchar_t* argv[], const InitializationData& initData = InitializationData(),
+                       int version = ICE_INT_VERSION);
+
+    /**
+     * Initializes a new communicator.
+     * @param argc The number of arguments in argv. Upon return, this argument
+     * is updated to reflect the arguments still remaining in argv.
+     * @param argv Command-line arguments, possibly containing
+     * options to set properties. If the arguments include
+     * a <code>--Ice.Config</code> option, the corresponding configuration
+     * files are parsed. If the same property is set in a configuration
+     * file and in the arguments, the arguments take precedence.
+     * Recognized options are removed from this vector upon return.
+     * @param initData Configuration data for the new Communicator.
+     * @param version Indicates the Ice version with which the application is compatible. If not
+     * specified, the version of the Ice installation is used.
+     */
+    CommunicatorHolder(int& argc, wchar_t* argv[], const InitializationData& initData = InitializationData(),
+                       int version = ICE_INT_VERSION);
+
+    /**
+     * Initializes a new communicator.
+     * @param argc The number of arguments in argv. Upon return, this argument
+     * is updated to reflect the arguments still remaining in argv.
+     * @param argv Command-line arguments, possibly containing
+     * options to set properties. If the arguments include
+     * a <code>--Ice.Config</code> option, the corresponding configuration
+     * files are parsed. If the same property is set in a configuration
+     * file and in the arguments, the arguments take precedence.
+     * Recognized options are removed from this vector upon return.
+     * @param configFile The name of an Ice configuration file.
+     * @param version Indicates the Ice version with which the application is compatible. If not
+     * specified, the version of the Ice installation is used.
+     */
+    CommunicatorHolder(int& argc, const wchar_t* argv[], const char* configFile, int version = ICE_INT_VERSION);
+
+    /**
+     * Initializes a new communicator.
+     * @param argc The number of arguments in argv. Upon return, this argument
+     * is updated to reflect the arguments still remaining in argv.
+     * @param argv Command-line arguments, possibly containing
+     * options to set properties. If the arguments include
+     * a <code>--Ice.Config</code> option, the corresponding configuration
+     * files are parsed. If the same property is set in a configuration
+     * file and in the arguments, the arguments take precedence.
+     * Recognized options are removed from this vector upon return.
+     * @param configFile The name of an Ice configuration file.
+     * @param version Indicates the Ice version with which the application is compatible. If not
+     * specified, the version of the Ice installation is used.
+     */
+    CommunicatorHolder(int& argc, wchar_t* argv[], const char* configFile, int version = ICE_INT_VERSION);
+#   endif
+
+    /**
+     * Initializes a new communicator.
+     * @param seq Command-line arguments, possibly containing
+     * options to set properties. If the arguments include
+     * a <code>--Ice.Config</code> option, the corresponding configuration
+     * files are parsed. If the same property is set in a configuration
+     * file and in the arguments, the arguments take precedence.
+     * Recognized options are removed from this container upon return.
+     * @param initData Configuration data for the new Communicator.
+     * @param version Indicates the Ice version with which the application is compatible. If not
+     * specified, the version of the Ice installation is used.
+     */
+    explicit CommunicatorHolder(StringSeq& seq, const InitializationData& initData = InitializationData(),
+                                int version = ICE_INT_VERSION);
+
+    /**
+     * Initializes a new communicator.
+     * @param seq Command-line arguments, possibly containing
+     * options to set properties. If the arguments include
+     * a <code>--Ice.Config</code> option, the corresponding configuration
+     * files are parsed. If the same property is set in a configuration
+     * file and in the arguments, the arguments take precedence.
+     * Recognized options are removed from this container upon return.
+     * @param configFile The name of an Ice configuration file.
+     * @param version Indicates the Ice version with which the application is compatible. If not
+     * specified, the version of the Ice installation is used.
+     */
+    CommunicatorHolder(StringSeq& seq, const char* configFile, int version = ICE_INT_VERSION);
+
+    /**
+     * Initializes a new communicator.
+     * @param initData Configuration data for the new Communicator.
+     * @param version Indicates the Ice version with which the application is compatible. If not
+     * specified, the version of the Ice installation is used.
+     */
+    explicit CommunicatorHolder(const InitializationData& initData, int version = ICE_INT_VERSION);
+
+    /**
+     * Initializes a new communicator.
+     * @param configFile The name of an Ice configuration file.
+     * @param version Indicates the Ice version with which the application is compatible. If not
+     * specified, the version of the Ice installation is used.
+     */
+    explicit CommunicatorHolder(const char* configFile, int version = ICE_INT_VERSION);
+
+    /**
+     * Adopts the given communicator.
+     * @param communicator The new communicator instance to hold.
+     */
+    CommunicatorHolder(const CommunicatorPtr& communicator);
+
+    /**
+     * Adopts the given communicator. If this holder currently holds a communicator,
+     * it will be destroyed.
+     * @param communicator The new communicator instance to hold.
+     */
+    CommunicatorHolder& operator=(const CommunicatorPtr& communicator);
+
+    /**
+     * Determines whether the holder contains an instance.
+     * @return True if the holder currently holds an instance, false otherwise.
+     */
+    operator bool() const;
+
+    /// \cond INTERNAL
+    //
+    // Required for successful copy-initialization, but not
+    // defined as it should always be elided by the compiler.
+    CommunicatorHolder(const CommunicatorHolder&);
+    /// \endcond
+
+#endif
+
+    ~CommunicatorHolder();
+
+    /**
+     * Obtains the communicator instance.
+     * @return The communicator held by this holder, or nil if the holder is empty.
+     */
+    const CommunicatorPtr& communicator() const;
+
+    /**
+     * Obtains the communicator instance.
+     * @return The communicator held by this holder, or nil if the holder is empty.
+     */
+    const CommunicatorPtr& operator->() const;
+
+    /**
+     * Obtains the communicator instance and clears the reference held by the holder.
+     * @return The communicator held by this holder, or nil if the holder is empty.
+     */
+    CommunicatorPtr release();
+
+private:
+
+    CommunicatorPtr  _communicator;
+};
+
+/**
+ * Converts a stringified identity into an Identity.
+ * @param str The stringified identity.
+ * @return An Identity structure containing the name and category components.
+ */
+ICE_API Identity stringToIdentity(const std::string& str);
+
+/**
+ * Converts an Identity structure into a string using the specified mode.
+ * @param id The identity structure.
+ * @param mode Affects the handling of non-ASCII characters and non-printable ASCII characters.
+ * @return The stringified identity.
+ */
+ICE_API std::string identityToString(const Identity& id, ToStringMode mode = ICE_ENUM(ToStringMode, Unicode));
 
-ICE_API Identity stringToIdentity(const std::string&);
-ICE_API std::string identityToString(const Identity&);
 }
 
 namespace IceInternal