diff options
Diffstat (limited to 'cpp/include/Ice/Initialize.h')
| -rw-r--r-- | cpp/include/Ice/Initialize.h | 860 |
1 files changed, 763 insertions, 97 deletions
diff --git a/cpp/include/Ice/Initialize.h b/cpp/include/Ice/Initialize.h index 0c3508823b1..15964d54998 100644 --- a/cpp/include/Ice/Initialize.h +++ b/cpp/include/Ice/Initialize.h @@ -32,112 +32,431 @@ namespace Ice { -ICE_API StringSeq argsToStringSeq(int, const char* const[]); +/** + * 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 -ICE_API StringSeq argsToStringSeq(int, const wchar_t* const[]); +/** + * 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 -// -// 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&, const char*[]); +/** + * 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[]); + +/** + * 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)); } #ifdef _WIN32 -ICE_API void stringSeqToArgs(const StringSeq&, int&, const 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. + */ +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&, const char*[], const PropertiesPtr& = 0); -inline PropertiesPtr createProperties(int& argc, char* argv[], const PropertiesPtr& props = 0) + +/** + * 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), props); + return createProperties(argc, const_cast<const char**>(argv), defaults); } #ifdef _WIN32 -ICE_API PropertiesPtr createProperties(int&, const wchar_t*[], const PropertiesPtr& = 0); -inline PropertiesPtr createProperties(int& argc, wchar_t* argv[], const PropertiesPtr& props = 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 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), props); + return createProperties(argc, const_cast<const wchar_t**>(argv), defaults); } #endif -// -// This class is used to notify user of when Ice threads are started -// and stopped. -// +/** + * 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: #ifdef ICE_CPP11_MAPPING - ThreadHookPlugin(const CommunicatorPtr& communicator, std::function<void()>, std::function<void()>); + /** + * 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 - ThreadHookPlugin(const CommunicatorPtr& communicator, const ThreadNotificationPtr&); + /** + * 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 + /** + * 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; - std::function<void(std::function<void()>, const std::shared_ptr<Ice::Connection>&)> dispatcher; - std::function<std::string(int)> compactIdResolver; - std::function<void(const Ice::BatchRequest&, int, int)> batchRequestInterceptor; + + /** + * 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; #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&, const 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); } -ICE_API CommunicatorPtr initialize(int&, const char*[], ICE_CONFIG_FILE_STRING, 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 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) { @@ -145,15 +464,79 @@ inline CommunicatorPtr initialize(int& argc, char* argv[], ICE_CONFIG_FILE_STRIN } #ifdef _WIN32 -ICE_API CommunicatorPtr initialize(int&, const wchar_t*[], 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 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(int&, const wchar_t*[], ICE_CONFIG_FILE_STRING, 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); + +/** + * 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) { @@ -161,102 +544,373 @@ inline CommunicatorPtr initialize(int& argc, wchar_t* argv[], ICE_CONFIG_FILE_ST } #endif -ICE_API CommunicatorPtr initialize(StringSeq&, const InitializationData& = InitializationData(), - int = ICE_INT_VERSION); - -ICE_API CommunicatorPtr initialize(StringSeq&, ICE_CONFIG_FILE_STRING, int = ICE_INT_VERSION); - -ICE_API CommunicatorPtr initialize(const InitializationData& = InitializationData(), - int = ICE_INT_VERSION); - -ICE_API CommunicatorPtr initialize(ICE_CONFIG_FILE_STRING, int = 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 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); + +/** + * 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); + +/** + * 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* (*PluginFactory)(const ::Ice::CommunicatorPtr&, const std::string&, const ::Ice::StringSeq&); -ICE_API void registerPluginFactory(const std::string&, PluginFactory, bool); -// -// RAII helper class -// +/** + * 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: - // - // Empty holder - // + /** + * The holder's initial state is empty. + */ CommunicatorHolder(); #ifdef ICE_CPP11_MAPPING - // - // Call initialize to create communicator with the provided args - // (all except default ctor above) - // - // + /** + * 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)...))) { } - // - // Adopt communicator - // - explicit CommunicatorHolder(std::shared_ptr<Communicator>); - CommunicatorHolder& operator=(std::shared_ptr<Communicator>); + /** + * Adopts the given communicator. + * @param communicator The new communicator instance to hold. + */ + explicit CommunicatorHolder(std::shared_ptr<Communicator> communicator); - CommunicatorHolder(const CommunicatorHolder&) = delete; + /** + * 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; - CommunicatorHolder& operator=(CommunicatorHolder&&); + /** + * 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); + + /** + * 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 - // - // Call initialize to create communicator with the provided args - // - CommunicatorHolder(int&, const char*[], const InitializationData& = InitializationData(), int = ICE_INT_VERSION); - CommunicatorHolder(int&, char*[], const InitializationData& = InitializationData(), int = ICE_INT_VERSION); - CommunicatorHolder(int&, const char*[], const char*, int = ICE_INT_VERSION); - CommunicatorHolder(int&, char*[], const char*, 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. + */ + 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 - CommunicatorHolder(int&, const wchar_t*[], const InitializationData& = InitializationData(), int = ICE_INT_VERSION); - CommunicatorHolder(int&, wchar_t*[], const InitializationData& = InitializationData(), int = ICE_INT_VERSION); - CommunicatorHolder(int&, const wchar_t*[], const char*, int = ICE_INT_VERSION); - CommunicatorHolder(int&, wchar_t*[], const char*, 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. + */ + 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 - explicit CommunicatorHolder(StringSeq&, const InitializationData& = InitializationData(), int = ICE_INT_VERSION); - CommunicatorHolder(StringSeq&, const char*, int = ICE_INT_VERSION); - - explicit CommunicatorHolder(const InitializationData&, int = ICE_INT_VERSION); - explicit CommunicatorHolder(const char*, int = ICE_INT_VERSION); - - // - // Adopt communicator - // - explicit CommunicatorHolder(const CommunicatorPtr&); - CommunicatorHolder& operator=(const CommunicatorPtr&); - + /** + * 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. + */ + explicit 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 compiler + // 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: @@ -264,8 +918,20 @@ private: CommunicatorPtr _communicator; }; -ICE_API Identity stringToIdentity(const std::string&); -ICE_API std::string identityToString(const Identity&, ToStringMode = ICE_ENUM(ToStringMode, Unicode)); +/** + * 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)); } |