zeroc-ice 3.7.0 → 3.7.1

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

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.
@@ -18,7 +18,9 @@ namespace Ice
 {
 
 class ObjectPrx;
+/// \cond INTERNAL
 using ObjectPrxPtr = ::std::shared_ptr<ObjectPrx>;
+/// \endcond
 
 }
 

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

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

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

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.
@@ -38,12 +38,21 @@ class Object;
 namespace Ice
 {
 
+/** Smart pointer for an object proxy. */
 typedef ::IceInternal::ProxyHandle< ::IceProxy::Ice::Object> ObjectPrx;
 
 class ObjectAdapter;
 typedef ::IceInternal::Handle< ::Ice::ObjectAdapter> ObjectAdapterPtr;
 
+/**
+ * A request context. Context is used to transmit metadata about a
+ * request from the server to the client, such as Quality-of-Service
+ * (QoS) parameters. Each remote operation on a proxy optionally
+ * accepts a Context parameter.
+ **/
 typedef ::std::map< ::std::string, ::std::string> Context;
+
+/** Sentinel value indicating that no explicit context argument was passed to a remote invocation. */
 ICE_API extern const Context noExplicitContext;
 
 }

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

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

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

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.
@@ -35,32 +35,90 @@ namespace Ice
 //
 
 #ifndef ICE_API_EXPORTS
-ICE_PLUGIN_REGISTER_DECLSPEC_IMPORT void registerIceStringConverter(bool = true);
-ICE_PLUGIN_REGISTER_DECLSPEC_IMPORT void registerIceUDP(bool = true);
-ICE_PLUGIN_REGISTER_DECLSPEC_IMPORT void registerIceWS(bool = true);
+/**
+ * When using static libraries, calling this function ensures the string converter 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 registerIceStringConverter(bool loadOnInitialize = true);
+
+/**
+ * When using static libraries, calling this function ensures the UDP transport 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 registerIceUDP(bool loadOnInitialize = true);
+
+/**
+ * When using static libraries, calling this function ensures the WebSocket transport 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 registerIceWS(bool loadOnInitialize = true);
 #endif
 
 #ifndef ICESSL_API_EXPORTS
-ICE_PLUGIN_REGISTER_DECLSPEC_IMPORT void registerIceSSL(bool = true);
+/**
+ * When using static libraries, calling this function ensures the SSL transport 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 registerIceSSL(bool loadOnInitialize = true);
 #endif
 
 #ifndef ICE_DISCOVERY_API_EXPORTS
-ICE_PLUGIN_REGISTER_DECLSPEC_IMPORT void registerIceDiscovery(bool = true);
+/**
+ * When using static libraries, calling this function ensures the IceDiscovery 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 registerIceDiscovery(bool loadOnInitialize = true);
 #endif
 
 #ifndef ICE_LOCATOR_DISCOVERY_API_EXPORTS
-ICE_PLUGIN_REGISTER_DECLSPEC_IMPORT void registerIceLocatorDiscovery(bool = true);
+/**
+ * When using static libraries, calling this function ensures the IceLocatorDiscovery 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 registerIceLocatorDiscovery(bool loadOnInitialize = true);
 #endif
 
 #if !defined(_WIN32) && !defined(__APPLE__)
 #   ifndef ICEBT_API_EXPORTS
-ICE_PLUGIN_REGISTER_DECLSPEC_IMPORT void registerIceBT(bool = true);
+/**
+ * When using static libraries, calling this function ensures the IceBT 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 registerIceBT(bool loadOnInitialize = true);
 #   endif
 #endif
 
 #if defined(__APPLE__) && TARGET_OS_IPHONE != 0
 #   ifndef ICEIAP_API_EXPORTS
-ICE_PLUGIN_REGISTER_DECLSPEC_IMPORT void registerIceIAP(bool = true);
+/**
+ * When using static libraries, calling this function ensures the iAP 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 registerIceIAP(bool loadOnInitialize = true);
 #   endif
 #endif
 

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

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

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

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

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

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

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

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

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

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.
@@ -20,6 +20,11 @@
 namespace Ice
 {
 
+/**
+ * A singleton class comparable to Ice::Application but also provides the low-level, platform-specific
+ * initialization and shutdown procedures common to system services.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API Service
 {
 public:
@@ -27,190 +32,312 @@ public:
     Service();
     virtual ~Service();
 
-    //
-    // Shutdown the service. The default implementation invokes shutdown()
-    // on the communicator.
-    //
+    /**
+     * Shutdown the service. The default implementation invokes shutdown()
+     * on the communicator.
+     */
     virtual bool shutdown();
 
-    //
-    // Notify the service about a signal interrupt. The default
-    // implementation invokes shutdown().
-    //
+    /**
+     * Notify the service about a signal interrupt. The default
+     * implementation invokes shutdown().
+     */
     virtual void interrupt();
 
-    //
-    // The primary entry point for services. This function examines
-    // the given argument vector for reserved options and takes the
-    // appropriate action. The reserved options are shown below.
-    //
-    // Win32:
-    //
-    // --service NAME
-    //
-    // Unix:
-    //
-    // --daemon [--nochdir] [--noclose]
-    //
-    // If --service or --daemon are specified, the program runs as
-    // a service, otherwise the program runs as a regular foreground
-    // process. Any service-specific (and Ice-specific) options
-    // are stripped from argv (just as for Ice::initialize()).
-    //
-    // The return value is an exit status code: EXIT_FAILURE or
-    // EXIT_SUCCESS.
-    //
-    int main(int, const char* const[], const InitializationData& = InitializationData(), int = ICE_INT_VERSION);
+    /**
+     * The primary entry point for services. This function examines
+     * the given argument vector for reserved options and takes the
+     * appropriate action. The reserved options are shown below.
+     *
+     * Win32:
+     *
+     * --service NAME
+     *
+     * Unix:
+     *
+     * --daemon [--nochdir] [--noclose]
+     *
+     * If --service or --daemon are specified, the program runs as
+     * a service, otherwise the program runs as a regular foreground
+     * process. Any service-specific (and Ice-specific) options
+     * are stripped from argv (just as for Ice::initialize()).
+     *
+     * @param argc Specifies the number of arguments in argv.
+     * @param argv The command-line arguments.
+     * @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 application's exit status: EXIT_FAILURE or EXIT_SUCCESS.
+     */
+    int main(int argc, const char* const argv[], const InitializationData& initData = InitializationData(),
+             int version = ICE_INT_VERSION);
 
 #ifdef _WIN32
-    int main(int, const wchar_t* const[], const InitializationData& = InitializationData(), int = ICE_INT_VERSION);
+    /**
+     * The primary entry point for services. This function examines
+     * the given argument vector for reserved options and takes the
+     * appropriate action. The reserved options are shown below.
+     *
+     * Win32:
+     *
+     * --service NAME
+     *
+     * Unix:
+     *
+     * --daemon [--nochdir] [--noclose]
+     *
+     * If --service or --daemon are specified, the program runs as
+     * a service, otherwise the program runs as a regular foreground
+     * process. Any service-specific (and Ice-specific) options
+     * are stripped from argv (just as for Ice::initialize()).
+     *
+     * @param argc Specifies the number of arguments in argv.
+     * @param argv The command-line arguments.
+     * @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 application's exit status: EXIT_FAILURE or EXIT_SUCCESS.
+     */
+    int main(int argc, const wchar_t* const argv[], const InitializationData& initData = InitializationData(),
+             int version = ICE_INT_VERSION);
 #endif
 
-    int main(const StringSeq&, const InitializationData& = InitializationData(), int = ICE_INT_VERSION);
-
-    //
-    // Returns the communicator created by the service.
-    //
+    /**
+     * The primary entry point for services. This function examines
+     * the given argument vector for reserved options and takes the
+     * appropriate action. The reserved options are shown below.
+     *
+     * Win32:
+     *
+     * --service NAME
+     *
+     * Unix:
+     *
+     * --daemon [--nochdir] [--noclose]
+     *
+     * If --service or --daemon are specified, the program runs as
+     * a service, otherwise the program runs as a regular foreground
+     * process. Any service-specific (and Ice-specific) options
+     * are stripped from argv (just as for Ice::initialize()).
+     *
+     * @param args The command-line arguments.
+     * @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 application's exit status: EXIT_FAILURE or EXIT_SUCCESS.
+     */
+    int main(const StringSeq& args, const InitializationData& initData = InitializationData(),
+             int version = ICE_INT_VERSION);
+
+    /**
+     * Obtains the communicator created by the service.
+     * @return The service's communicator.
+     */
     Ice::CommunicatorPtr communicator() const;
 
-    //
-    // Returns the Service singleton.
-    //
+    /**
+     * Obtains the Service singleton.
+     * @return A pointer to this service.
+     */
     static Service* instance();
 
-    //
-    // Indicates whether the program is running as a Win32 service or
-    // Unix daemon.
-    //
+    /**
+     * Indicates whether the program is running as a Win32 service or Unix daemon.
+     * @return True if the program is running as a service, false otherwise.
+     */
     bool service() const;
 
-    //
-    // Returns the program name. If the program is running as a Win32
-    // service, the return value is the service name. Otherwise the
-    // return value is the executable name (i.e., argv[0]).
-    //
+    /**
+     * Obtains the program name. If the program is running as a Win32
+     * service, the return value is the service name. Otherwise the
+     * return value is the executable name (i.e., argv[0]).
+     * @return The service name.
+     */
     std::string name() const;
 
-    //
-    // Returns true if the operating system supports running the
-    // program as a Win32 service or Unix daemon.
-    //
+    /**
+     * Determines whether the operating system supports running the
+     * program as a Win32 service or Unix daemon.
+     * @return True if the system supports services, false otherwise.
+     */
     bool checkSystem() const;
 
-    //
-    // Alternative entry point for services that use their own
-    // command-line options. Instead of invoking main(), the
-    // program processes its command-line options and invokes
-    // run(). To run as a Win32 service or Unix daemon, the
-    // program must first invoke configureService() or
-    // configureDaemon(), respectively.
-    //
-    // The return value is an exit status code: EXIT_FAILURE or
-    // EXIT_SUCCESS.
-    //
+    /**
+     * Alternative entry point for services that use their own
+     * command-line options. Instead of invoking main(), the
+     * program processes its command-line options and invokes
+     * run(). To run as a Win32 service or Unix daemon, the
+     * program must first invoke configureService() or
+     * configureDaemon(), respectively.
+     *
+     * @param argc Specifies the number of arguments in argv.
+     * @param argv The command-line arguments.
+     * @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 application's exit status: EXIT_FAILURE or EXIT_SUCCESS.
+     */
 #ifdef _WIN32
-    int run(int, const wchar_t* const[], const InitializationData& = InitializationData(), int = ICE_INT_VERSION);
+    int run(int argc, const wchar_t* const argv[], const InitializationData& initData = InitializationData(),
+            int version = ICE_INT_VERSION);
 #endif
 
-    int run(int, const char* const[], const InitializationData& = InitializationData(), int = ICE_INT_VERSION);
+    /**
+     * Alternative entry point for services that use their own
+     * command-line options. Instead of invoking main(), the
+     * program processes its command-line options and invokes
+     * run(). To run as a Win32 service or Unix daemon, the
+     * program must first invoke configureService() or
+     * configureDaemon(), respectively.
+     *
+     * @param argc Specifies the number of arguments in argv.
+     * @param argv The command-line arguments.
+     * @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 application's exit status: EXIT_FAILURE or EXIT_SUCCESS.
+     */
+    int run(int argc, const char* const argv[], const InitializationData& initData = InitializationData(),
+            int version = ICE_INT_VERSION);
 
 #ifdef _WIN32
 
-    //
-    // Configures the program to run as a Win32 service with the
-    // given name.
-    //
-    void configureService(const std::string&);
+    /**
+     * Configures the program to run as a Win32 service with the given name.
+     * @param name The service name.
+     */
+    void configureService(const std::string& name);
 
+    /// \cond INTERNAL
     static void setModuleHandle(HMODULE);
+    /// \endcond
 
 #else
 
-    //
-    // Configures the program to run as a Unix daemon. The first
-    // argument indicates whether the daemon should change its
-    // working directory to the root directory. The second
-    // argument indicates whether extraneous file descriptors are
-    // closed. If the value of the last argument is not an empty
-    // string, the daemon writes its process ID to the given
-    // filename.
-    //
-    void configureDaemon(bool, bool, const std::string&);
+    /**
+     * Configures the program to run as a Unix daemon. The first
+     * argument indicates whether the daemon should change its
+     * working directory to the root directory. The second
+     * argument indicates whether extraneous file descriptors are
+     * closed. If the value of the last argument is not an empty
+     * string, the daemon writes its process ID to the given
+     * filename.
+     *
+     * @param changeDirectory True if the daemon should change its working directory to the root directory,
+     * false otherwise.
+     * @param closeFiles True if the daemon should close unnecessary file descriptors (i.e., stdin, stdout, etc.),
+     * false otherwise.
+     * @param pidFile If a non-empty string is provided, the daemon writes its process ID to the given file.
+     */
+    void configureDaemon(bool changeDirectory, bool closeFiles, const std::string& pidFile);
 
 #endif
 
-    //
-    // Invoked by the CtrlCHandler.
-    //
-    virtual void handleInterrupt(int);
+    /**
+     * Invoked by the signal handler when it catches a signal.
+     * @param sig The signal that was caught.
+     */
+    virtual void handleInterrupt(int sig);
 
 protected:
 
-    //
-    // Prepare a service for execution, including the creation and
-    // activation of object adapters and servants.
-    //
-    virtual bool start(int, char*[], int&) = 0;
-
-    //
-    // Blocks until the service shuts down. The default implementation
-    // invokes waitForShutdown() on the communicator.
-    //
+    /**
+     * Prepares a service for execution, including the creation and
+     * activation of object adapters and servants.
+     * @param argc Specifies the number of arguments in argv.
+     * @param argv The command-line arguments.
+     * @param status The exit status, which is returned by main
+     * @return True if startup was successful, false otherwise.
+     */
+    virtual bool start(int argc, char* argv[], int& status) = 0;
+
+    /**
+     * Blocks until the service shuts down. The default implementation
+     * invokes waitForShutdown() on the communicator.
+     */
     virtual void waitForShutdown();
 
-    //
-    // Clean up resources after shutting down.
-    //
+    /**
+     * Cleans up resources after shutting down.
+     */
     virtual bool stop();
 
-    //
-    // Initialize a communicator.
-    //
-    virtual Ice::CommunicatorPtr initializeCommunicator(int&, char*[], const InitializationData&, int);
-
-    //
-    // Log a system error, which includes a description of the
-    // current system error code.
-    //
-    virtual void syserror(const std::string&);
-
-    //
-    // Log an error.
-    //
-    virtual void error(const std::string&);
-
-    //
-    // Log a warning.
-    //
-    virtual void warning(const std::string&);
-
-    //
-    // Log trace information.
-    //
-    virtual void trace(const std::string&);
-
-    //
-    // Log a literal message.
-    //
-    virtual void print(const std::string&);
-
-    //
-    // Enable the CtrlCHandler to invoke interrupt() when a signal occurs.
-    //
+    /**
+     * Initializes a communicator.
+     * @param argc Specifies the number of arguments in argv.
+     * @param argv The command-line arguments.
+     * @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 instance.
+     */
+    virtual Ice::CommunicatorPtr initializeCommunicator(int& argc, char* argv[], const InitializationData& initData,
+                                                        int version);
+
+    /**
+     * Logs a system error, which includes a description of the
+     * current system error code.
+     * @param msg The log message.
+     */
+    virtual void syserror(const std::string& msg);
+
+    /**
+     * Logs an error.
+     * @param msg The log message.
+     */
+    virtual void error(const std::string& msg);
+
+    /**
+     * Logs a warning.
+     * @param msg The log message.
+     */
+    virtual void warning(const std::string& msg);
+
+    /**
+     * Logs trace information.
+     * @param msg The log message.
+     */
+    virtual void trace(const std::string& msg);
+
+    /**
+     * Logs a literal message.
+     * @param msg The log message.
+     */
+    virtual void print(const std::string& msg);
+
+    /**
+     * Enables the signal handler to invoke interrupt() when a signal occurs.
+     */
     void enableInterrupt();
 
-    //
-    // Ignore signals.
-    //
+    /**
+     * Ignore signals.
+     */
     void disableInterrupt();
 
-    //
-    // Log Helpers
-    //
+    /**
+     * Logger utility class for a system error.
+     */
     typedef LoggerOutput<Service, Service*, &Service::syserror> ServiceSysError;
+
+    /**
+     * Logger utility class for an error.
+     */
     typedef LoggerOutput<Service, Service*, &Service::error> ServiceError;
+
+    /**
+     * Logger utility class for a warning.
+     */
     typedef LoggerOutput<Service, Service*, &Service::warning> ServiceWarning;
+
+    /**
+     * Logger utility class for a trace message.
+     */
     typedef LoggerOutput<Service, Service*, &Service::trace> ServiceTrace;
+
+    /**
+     * Logger utility class for a literal message.
+     */
     typedef LoggerOutput<Service, Service*, &Service::print> ServicePrint;
 
 private:
@@ -236,8 +363,10 @@ private:
 
 public:
 
+    /// \cond INTERNAL
     void serviceMain(int, const wchar_t* const[]);
     void control(int);
+    /// \endcond
 
 #else