diff options
Diffstat (limited to 'cpp/include')
62 files changed, 7145 insertions, 1504 deletions
diff --git a/cpp/include/Glacier2/Application.h b/cpp/include/Glacier2/Application.h index c29bd70de07..69966953d56 100644 --- a/cpp/include/Glacier2/Application.h +++ b/cpp/include/Glacier2/Application.h @@ -21,6 +21,7 @@ namespace Glacier2 /** * * This exception is raised if the session should be restarted. + * \headerfile Glacier2/Glacier2.h * **/ class GLACIER2_API RestartSessionException : public IceUtil::ExceptionHelper<RestartSessionException> @@ -34,49 +35,41 @@ public: }; /** - * An extension of Ice.Application that makes it easy to write + * An extension of Ice::Application that makes it easy to write * Glacier2 applications. * - * <p> Applications must create a derived class that implements the - * {@link #createSession} and {@link #runWithSession} methods.<p> + * Applications must create a derived class that implements the + * createSession and runWithSession methods. * - * The base class invokes {@link #createSession} to create a new - * Glacier2 session and then invokes {@link #runWithSession} in + * The base class invokes createSession to create a new + * Glacier2 session and then invokes runWithSession in * which the subclass performs its application logic. The base class - * automatically destroys the session when {@link #runWithSession} - * returns. + * automatically destroys the session when runWithSession returns. * - * If {@link #runWithSession} calls {@link #restart} or raises any of - * the exceptions Ice.ConnectionRefusedException, - * Ice.ConnectionLostException, Ice.UnknownLocalException, - * Ice.RequestFailedException, or Ice.TimeoutException, the base + * If runWithSession calls restart or raises any of + * the exceptions Ice::ConnectionRefusedException, + * Ice::ConnectionLostException, Ice::UnknownLocalException, + * Ice::RequestFailedException, or Ice::TimeoutException, the base * class destroys the current session and restarts the application - * with another call to {@link #createSession} followed by - * {@link #runWithSession}. + * with another call to createSession followed by runWithSession. * - * The application can optionally override the {@link #sessionDestroyed} + * The application can optionally override the sessionDestroyed * callback method if it needs to take action when connectivity with * the Glacier2 router is lost. * * A program can contain only one instance of this class. - * - * @see Ice.Application - * @see Glacier2.Router - * @see Glacier2.Session - * @see Ice.Communicator - * @see Ice.Logger - * @see #runWithSession + * \headerfile Glacier2/Glacier2.h **/ - class GLACIER2_API Application : public Ice::Application { +public: + /** - * Initializes an instance that calls {@link Communicator#shutdown} if + * Initializes an instance that calls Ice::Communicator::shutdown if * a signal is received. **/ -public: - Application(Ice::SignalPolicy = Ice::ICE_ENUM(SignalPolicy,HandleSignals)); + #ifdef ICE_CPP11_MAPPING Application(const Application&) = delete; Application& operator=(const Application&) = delete; @@ -85,9 +78,8 @@ public: /** * Creates a new Glacier2 session. A call to * <code>createSession</code> always precedes a call to - * <code>runWithSession</code>. If <code>Ice.LocalException</code> + * <code>runWithSession</code>. If <code>Ice::LocalException</code> * is thrown from this method, the application is terminated. - * @return The Glacier2 session. **/ virtual Glacier2::SessionPrxPtr createSession() = 0; @@ -172,16 +164,19 @@ public: protected: - virtual int doMain(int, char*[], const Ice::InitializationData& initData, int); + /** + * Helper function that implements the application logic. + */ + virtual int doMain(int argc, char* argv[], const Ice::InitializationData& initData, int version); private: bool doMain(Ice::StringSeq&, const Ice::InitializationData&, int&, int); - /** - * Run should not be overridden for Glacier2.Application. Instead - * <code>runWithSession</code> should be used. - */ + // + // Run should not be overridden for Glacier2::Application. Instead + // runWithSession should be used. + // int run(int, char*[]) { // This shouldn't be called. diff --git a/cpp/include/Glacier2/SessionHelper.h b/cpp/include/Glacier2/SessionHelper.h index f4d4ca391ef..732638a0354 100644 --- a/cpp/include/Glacier2/SessionHelper.h +++ b/cpp/include/Glacier2/SessionHelper.h @@ -30,9 +30,16 @@ namespace Glacier2 { +/** The IANA-registered port number for Glacier2 via SSL. */ const int GLACIER2_SSL_PORT = 4064; +/** The IANA-registered port number for Glacier2 via TCP. */ const int GLACIER2_TCP_PORT = 4063; +/** + * Encapsulates a Glacier2 session and provides much of the same functionality as Glacier2::Application + * but better suited for graphical applications. + * \headerfile Glacier2/Glacier2.h + */ class GLACIER2_API SessionHelper #ifndef ICE_CPP11_MAPPING : public virtual IceUtil::Shared @@ -41,12 +48,52 @@ class GLACIER2_API SessionHelper public: virtual ~SessionHelper(); + /** + * Initiates the destruction of the Glacier2 session, including the communicator created by the SessionHelper. + */ virtual void destroy() = 0; + + /** + * Obtains the communicator created by the SessionHelper. + * @return The communicator object. + * @throws SessionNotExistException if no session is currently active. + */ virtual Ice::CommunicatorPtr communicator() const = 0; + + /** + * Obtains the category that must be used in the identities of all callback objects. + * @return The identity category. + * @throws SessionNotExistException if no session is currently active. + */ virtual std::string categoryForClient() const = 0; - virtual Ice::ObjectPrxPtr addWithUUID(const Ice::ObjectPtr&) = 0; + + /** + * Adds a servant to the callback object adapter using a UUID for the identity name. + * Also see Ice::ObjectAdapter::addWithUUID. + * @param servant The servant to add to the callback object adapter's active servant table. + * @return A proxy for the object. + * @throws SessionNotExistException if no session is currently active. + */ + virtual Ice::ObjectPrxPtr addWithUUID(const Ice::ObjectPtr& servant) = 0; + + /** + * Obtains a proxy for the Glacier2 session. + * @return The session proxy, or a nil proxy if no session is currently active. + */ virtual SessionPrxPtr session() const = 0; + + /** + * Determines whether the session is active. + * @return True if the session is currently active, false otherwise. + */ virtual bool isConnected() const = 0; + + /** + * Obtains the callback object adapter. This object adapter is only created if the session factory + * was configured to do so using SessionFactoryHelper::setUseCallbacks. + * @return The object adapter, or nil if no object adapter was created. + * @throws SessionNotExistException if no session is currently active. + */ virtual Ice::ObjectAdapterPtr objectAdapter() = 0; #ifndef ICE_CPP11_MAPPING @@ -57,6 +104,10 @@ public: }; ICE_DEFINE_PTR(SessionHelperPtr, SessionHelper); +/** + * Allows an application to receive notification about events in the lifecycle of a Glacier2 session. + * \headerfile Glacier2/Glacier2.h + */ class GLACIER2_API SessionCallback #ifndef ICE_CPP11_MAPPING : public virtual IceUtil::Shared @@ -65,15 +116,41 @@ class GLACIER2_API SessionCallback public: virtual ~SessionCallback(); + /** + * Called after successfully initializing a communicator. + * @param session The corresponding session helper. + */ virtual void createdCommunicator(const SessionHelperPtr& session) = 0; - virtual void connected(const SessionHelperPtr&) = 0; - virtual void disconnected(const SessionHelperPtr&) = 0; - virtual void connectFailed(const SessionHelperPtr&, const Ice::Exception&) = 0; + + /** + * Called after successfully establishing the Glacier2 session. + * @param session The corresponding session helper. + */ + virtual void connected(const SessionHelperPtr& session) = 0; + + /** + * Called after the Glacier2 session is destroyed. + * @param session The corresponding session helper. + */ + virtual void disconnected(const SessionHelperPtr& session) = 0; + + /** + * Called if a failure occurred while attempting to establish a Glacier2 session. + * @param session The corresponding session helper. + * @param ex The exception that caused the failure. + */ + virtual void connectFailed(const SessionHelperPtr& session, const Ice::Exception& ex) = 0; }; ICE_DEFINE_PTR(SessionCallbackPtr, SessionCallback); +/// \cond INTERNAL class SessionThreadCallback; +/// \endcond +/** + * Facilitates the creation of new Glacier2 sessions. + * \headerfile Glacier2/Glacier2.h + */ class GLACIER2_API SessionFactoryHelper #ifdef ICE_CPP11_MAPPING : public std::enable_shared_from_this<SessionFactoryHelper> @@ -81,47 +158,142 @@ class GLACIER2_API SessionFactoryHelper : public virtual IceUtil::Shared #endif { + /// \cond INTERNAL friend class SessionThreadCallback; // To access thread functions + /// \endcond public: + /** + * This constructor is useful when your application has no other configuration requirements. + * The constructor allocates an InitializationData object and a new property set. + * @param callback The callback object (must not be nil). + */ SessionFactoryHelper(const SessionCallbackPtr& callback); - SessionFactoryHelper(const Ice::InitializationData&, const SessionCallbackPtr&); - SessionFactoryHelper(const Ice::PropertiesPtr&, const SessionCallbackPtr&); + + /** + * Use this constructor when you want to provide your own instance of InitializationData. + * @param initData Initialization data for the communicator. + * @param callback The callback object (must not be nil). + */ + SessionFactoryHelper(const Ice::InitializationData& initData, const SessionCallbackPtr& callback); + + /** + * This constructor is convenient when you want to supply an initial set of properties. + * @param properties Configuration properties for the communicator. + * @param callback The callback object (must not be nil). + */ + SessionFactoryHelper(const Ice::PropertiesPtr& properties, const SessionCallbackPtr& callback); ~SessionFactoryHelper(); + /** + * Blocks until all background threads are terminated. + */ void destroy(); - void setRouterIdentity(const Ice::Identity&); + /** + * Sets the object identity of the Glacier2 router. + * @param identity The router identity. + */ + void setRouterIdentity(const Ice::Identity& identity); + + /** + * Obtains the object identity of the Glacier2 router. + * @return The router identity. + */ Ice::Identity getRouterIdentity() const; - void setRouterHost(const std::string&); + /** + * Sets the host name of the Glacier2 router. + * @param host The router host name. + */ + void setRouterHost(const std::string& host); + + /** + * Obtains the host name of the Glacier2 router. + * @return The router host name. + */ std::string getRouterHost() const; + /// \cond INTERNAL ICE_DEPRECATED_API("is deprecated, use SessionFactoryHelper::setProtocol instead") void setSecure(bool); ICE_DEPRECATED_API("is deprecated, use SessionFactoryHelper::getProtocol instead") bool getSecure() const; - - void setProtocol(const std::string&); + /// \endcond + + /** + * Sets the Ice protocol used for communications with the Glacier2 router. + * @param protocol The protocol name (e.g., "tcp"). + */ + void setProtocol(const std::string& protocol); + + /** + * Obtains the Ice protocol used for communications with the Glacier2 router. + * @return The protocol name. + */ std::string getProtocol() const; - void setTimeout(int); + /** + * Sets the timeout in milliseconds for the connection to the Glacier2 router. + * @param timeout The timeout in milliseconds. + */ + void setTimeout(int timeout); + + /** + * Obtains the timeout in milliseconds for the connection to the Glacier2 router. + * @return The timeout in milliseconds. + */ int getTimeout() const; + /** + * Sets the port on which the Glacier2 router is listening. + * @param port The router port. + */ void setPort(int port); + + /** + * Obtains the port on which the Glacier2 router is listening. + * @return The router port. + */ int getPort() const; + /** + * Returns a copy of the InitializationData object that will be used during communicator initialization. + * @return The communicator initialization data. + */ Ice::InitializationData getInitializationData() const; + /** + * Sets the request context to be used when creating a session. + * @param context The request context. + */ void setConnectContext(const std::map<std::string, std::string>& context); - void setUseCallbacks(bool); + /** + * Determines whether the session helper automatically creates an object adapter for callback servants. + * @param b True if the helper should create an object adapter, false otherwise. + */ + void setUseCallbacks(bool b); + + /** + * Determines whether the session helper automatically creates an object adapter for callback servants. + * @return True if the helper will create an object adapter, false otherwise. + */ bool getUseCallbacks() const; + /** + * Initializes a communicator, creates a Glacier2 session using SSL credentials, and returns a new + * SessionHelper object. + */ SessionHelperPtr connect(); - SessionHelperPtr connect(const std::string&, const std::string&); + + /** + * Initializes a communicator, creates a Glacier2 session using the given username and password, + * and returns a new SessionHelper object. + */ + SessionHelperPtr connect(const std::string& username, const std::string& password); private: diff --git a/cpp/include/Ice/Application.h b/cpp/include/Ice/Application.h index 6843c6a65f4..498b6054c51 100644 --- a/cpp/include/Ice/Application.h +++ b/cpp/include/Ice/Application.h @@ -22,133 +22,291 @@ using IceUtil::CtrlCHandler; using IceUtil::CtrlCHandlerCallback; #ifdef ICE_CPP11_MAPPING +/** + * Determines how the Application class handles signals. + */ enum class SignalPolicy : unsigned char #else enum SignalPolicy #endif -{ HandleSignals, NoSignalHandling }; +{ + /** Enables signal handling. */ + HandleSignals, + /** Disables signal handling, meaning signals retain their default behavior. */ + NoSignalHandling +}; +/** + * Singleton helper class that simplifies Ice initialization, finalization and signal handling. + * An application uses this class by writing a subclass and implementing the run method. + * \headerfile Ice/Ice.h + */ class ICE_API Application { public: - Application(SignalPolicy = ICE_ENUM(SignalPolicy, HandleSignals)); + /** + * The constructor configures the signal handling behavior. + * @param policy Specifies whether to handle signals. If not specified, the default behavior + * is to handle signals. + */ + Application(SignalPolicy policy = ICE_ENUM(SignalPolicy, HandleSignals)); #ifdef ICE_CPP11_MAPPING + /// \cond IGNORE Application(const Application&) = delete; Application& operator=(const Application&) = delete; + /// \endcond #endif virtual ~Application(); - // This main() must be called by the global main(). main() - // initializes the Communicator, calls run() and destroys the - // the Communicator upon return from run(). It handles all - // exceptions properly, i.e., error message are printed if - // exceptions propagate to main(), and the Communicator is always - // destroyed, regardless of exceptions. - // - int main(int, const char* const[], const InitializationData& = InitializationData(), int = ICE_INT_VERSION); - int main(int, const char* const[], ICE_CONFIG_FILE_STRING, int = ICE_INT_VERSION); + /** + * Call this main() from the global main(). main() + * initializes the Communicator, calls run() and destroys the + * the Communicator upon return from run(). It handles all + * exceptions properly, i.e., error message are printed if + * exceptions propagate to main(), and the Communicator is always + * destroyed, regardless of exceptions. + * @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. + */ + int main(int argc, const char* const argv[], const InitializationData& initData = InitializationData(), + int version = ICE_INT_VERSION); + + /** + * Call this main() from the global main(). main() + * initializes the Communicator, calls run() and destroys the + * the Communicator upon return from run(). It handles all + * exceptions properly, i.e., error message are printed if + * exceptions propagate to main(), and the Communicator is always + * destroyed, regardless of exceptions. + * @param argc Specifies the number of arguments in argv. + * @param argv The command-line arguments. + * @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 application's exit status. + */ + int main(int argc, const char* const argv[], ICE_CONFIG_FILE_STRING configFile, int version = ICE_INT_VERSION); #ifdef _WIN32 - int main(int, const wchar_t* const[], const InitializationData& = InitializationData(), int = ICE_INT_VERSION); - int main(int, const wchar_t* const[], ICE_CONFIG_FILE_STRING, int = ICE_INT_VERSION); + /** + * Call this main() from the global main(). main() + * initializes the Communicator, calls run() and destroys the + * the Communicator upon return from run(). It handles all + * exceptions properly, i.e., error message are printed if + * exceptions propagate to main(), and the Communicator is always + * destroyed, regardless of exceptions. + * @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. + */ + int main(int argc, const wchar_t* const argv[], const InitializationData& initData = InitializationData(), + int version = ICE_INT_VERSION); + + /** + * Call this main() from the global main(). main() + * initializes the Communicator, calls run() and destroys the + * the Communicator upon return from run(). It handles all + * exceptions properly, i.e., error message are printed if + * exceptions propagate to main(), and the Communicator is always + * destroyed, regardless of exceptions. + * @param argc Specifies the number of arguments in argv. + * @param argv The command-line arguments. + * @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 application's exit status. + */ + int main(int argc, const wchar_t* const argv[], ICE_CONFIG_FILE_STRING configFile, int version = ICE_INT_VERSION); #endif - int main(const StringSeq&, const InitializationData& = InitializationData(), int = ICE_INT_VERSION); - int main(const StringSeq&, ICE_CONFIG_FILE_STRING, int = ICE_INT_VERSION); + /** + * Call this main() from the global main(). main() + * initializes the Communicator, calls run() and destroys the + * the Communicator upon return from run(). It handles all + * exceptions properly, i.e., error message are printed if + * exceptions propagate to main(), and the Communicator is always + * destroyed, regardless of exceptions. + * @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. + */ + int main(const StringSeq& args, const InitializationData& initData = InitializationData(), + int version = ICE_INT_VERSION); - // - // run is given a copy of the remaining argc/argv arguments, - // after the communicator initialization in the caller (main) - // has removed all Ice-related arguments. - // - virtual int run(int, char*[]) = 0; + /** + * Call this main() from the global main(). main() + * initializes the Communicator, calls run() and destroys the + * the Communicator upon return from run(). It handles all + * exceptions properly, i.e., error message are printed if + * exceptions propagate to main(), and the Communicator is always + * destroyed, regardless of exceptions. + * @param args The command-line arguments. + * @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 application's exit status. + */ + int main(const StringSeq& args, ICE_CONFIG_FILE_STRING configFile, int version = ICE_INT_VERSION); - // - // Override this to provide a custom application interrupt - // hook. You must call callbackOnInterrupt for this method to - // be called. Note that the interruptCallback can be called - // concurrently with any other thread (including main) in your - // application and thus must take appropriate concurrency - // precautions. - // - virtual void interruptCallback(int); + /** + * run is given a copy of the remaining argc/argv arguments, + * after the communicator initialization in the caller (main) + * has removed all Ice-related arguments. + * @param argc Specifies the number of arguments in argv. + * @param argv The command-line arguments. + * @return The application's exit status. + */ + virtual int run(int argc, char* argv[]) = 0; - // - // Return the application name, i.e., argv[0]. - // + /** + * Override this method to provide a custom application interrupt + * hook. You must call callbackOnInterrupt for this method to + * be called. Note that the interruptCallback can be called + * concurrently with any other thread (including main) in your + * application and thus must take appropriate concurrency + * precautions. + * @param signal The signal identifier. + */ + virtual void interruptCallback(int signal); + + /** + * Obtains the application name, i.e., argv[0]. + * @return The application's name. + */ static const char* appName(); - // - // One limitation of this class is that there can only be one - // Application instance, with one global Communicator, accessible - // with this communicator() operation. This limitation is due to - // how the signal handling functions below operate. If you require - // multiple Communicators, then you cannot use this Application - // framework class. - // + /** + * Obtains the application's Communicator instance. + * One limitation of this class is that there can only be one + * Application instance, with one global Communicator, accessible + * with this communicator() operation. This limitation is due to + * how the signal handling functions below operate. If you require + * multiple Communicators, then you cannot use this Application + * framework class. + * @return The application's communicator. + */ static CommunicatorPtr communicator(); - // - // These methods can be used to set a Ctrl+C Handler callback. - // + /** + * Configures the application to destroy the communicator when one of the + * monitored signals is raised. This is the default behavior. + */ static void destroyOnInterrupt(); + + /** + * Configures the application to shut down the communicator when one of the + * monitored signals is raised. + */ static void shutdownOnInterrupt(); + + /** + * Configures the application to ignore signals. + */ static void ignoreInterrupt(); + + /** + * Configures the application to invoke interruptCallback when a signal occurs, + * thereby giving the subclass responsibility for handling the signal. + */ static void callbackOnInterrupt(); - // - // These methods can be used to temporarily block a signal and - // arrange for delivery of a pending signal later. Any signal that - // is received after holdInterrupt() was called is remembered and - // delivered when releaseInterupt() is called. That signal is then - // handled according to the signal disposition established with - // destroyOnInterrupt(), shutdownOnInterrupt() or - // ignoreInterrupt(). - // + /** + * Configures the application to ignore (but remember) a signal. + * A stored signal (if any) can be handled later by calling releaseInterrupt. + */ static void holdInterrupt(); + + /** + * Processes a stored signal (if any) using the current signal handling configuration. + */ static void releaseInterrupt(); - // - // This method returns true if a signal handler was triggered, - // false otherwise. This can be used once - // Communicator::waitForShutdown() returns to test whether the - // shutdown was due to an interrupt (interrupted() returns true in - // that case) or because Communicator::shutdown() was called - // (interrupted() returns false in that case). - // + /** + * Indicates whether a signal handler was triggered. + * This can be used once Communicator::waitForShutdown() returns to + * test whether the shutdown was due to an interrupt (returns true) + * or because Communicator::shutdown() was called (returns false). + * @return True if a signal handler was triggered, false otherwise. + */ static bool interrupted(); protected: + /** + * Helper function that implements the application logic. + */ virtual int doMain(int, char*[], const InitializationData&, Int); - // - // _mutex and _condVar are used to synchronize the main thread and - // the CtrlCHandler thread - // + /** + * Used to synchronize the main thread and the CtrlCHandler thread. + */ static IceUtil::Mutex _mutex; + + /** + * Used to synchronize the main thread and the CtrlCHandler thread. + */ static IceUtil::Cond _condVar; - // - // Variables than can change while run() and communicator->destroy() - // are running! - // + /** + * True if a signal handling callback is currently executing. + * Can change while run() and communicator->destroy() are running! + */ static bool _callbackInProgress; + + /** + * True if the communicator has been destroyed. + * Can change while run() and communicator->destroy() are running! + */ static bool _destroyed; + + /** + * True if an interrupt signal was received. + * Can change while run() and communicator->destroy() are running! + */ static bool _interrupted; - // - // Variables that are immutable during run() and until - // communicator->destroy() has returned, before and after run(), and - // once communicator->destroy() has returned, we assume that - // only the main thread and CtrlCHandler threads are running. - // + /** + * The application's name. + * Immutable during run() and until communicator->destroy() has returned. + * Before and after run(), and once communicator->destroy() has returned, + * we assume that only the main thread and CtrlCHandler threads are running. + */ static std::string _appName; + + /** + * The application's communicator. + * Immutable during run() and until communicator->destroy() has returned. + * Before and after run(), and once communicator->destroy() has returned, + * we assume that only the main thread and CtrlCHandler threads are running. + */ static CommunicatorPtr _communicator; + + /** + * The signal-handling policy specified at construction. + * Immutable during run() and until communicator->destroy() has returned. + * Before and after run(), and once communicator->destroy() has returned, + * we assume that only the main thread and CtrlCHandler threads are running. + */ static SignalPolicy _signalPolicy; + + /** + * The singleton instance. + * Immutable during run() and until communicator->destroy() has returned. + * Before and after run(), and once communicator->destroy() has returned, + * we assume that only the main thread and CtrlCHandler threads are running. + */ static Application* _application; private: diff --git a/cpp/include/Ice/AsyncResult.h b/cpp/include/Ice/AsyncResult.h index 56e53e65213..53cca7775a4 100644 --- a/cpp/include/Ice/AsyncResult.h +++ b/cpp/include/Ice/AsyncResult.h @@ -23,34 +23,107 @@ namespace Ice { +/** + * Represents the result of an asynchronous invocation using the C++98 mapping. + * \headerfile Ice/Ice.h + */ class ICE_API AsyncResult : private IceUtil::noncopyable, public Ice::LocalObject { public: virtual ~AsyncResult(); + /** + * Prevents a queued invocation from being sent or, if the invocation has already been sent, + * ignores a reply if the server sends one. cancel is a local operation and has no effect + * on the server. A canceled invocation is considered to be completed, meaning isCompleted + * returns true, and the result of the invocation is an InvocationCanceledException. + */ virtual void cancel() = 0; + /** + * Allows you to create ordered or hashed collections of pending asynchronous invocations. + * @return A unique hash code for this object. + */ virtual Int getHash() const = 0; + /** + * Obtains the communicator that sent the invocation. + * @return A reference to the communicator. + */ virtual CommunicatorPtr getCommunicator() const = 0; + + /** + * Obtains the connection that was used for the invocation. Note that, for typical asynchronous + * proxy invocations, this method returns a nil value because the possibility of automatic retries + * means the connection that is currently in use could change unexpectedly. The getConnection + * method only returns a non-nil value when the AsyncResult object is obtained by calling + * Connection::begin_flushBatchRequests. + * @return A reference to the connection. + */ virtual ConnectionPtr getConnection() const = 0; + + /** + * Obtains the proxy that was used to call the begin_ method, or nil if the AsyncResult object was + * not obtained via an asynchronous proxy invocation. + * @return A reference to the proxy. + */ virtual ObjectPrxPtr getProxy() const = 0; + /** + * Obtains the completion status of the invocation. + * @return True if, at the time it is called, the result of an invocation is available, indicating + * that a call to the end_ method will not block the caller. Otherwise, if the result is not yet + * available, the method returns false. + */ virtual bool isCompleted() const = 0; + + /** + * Blocks the caller until the result of an invocation becomes available. + */ virtual void waitForCompleted() = 0; + /** + * Obtains the sent status of the invocation. + * @return True if, at the time it is called, the request has been written to the local transport + * (whether it was initially queued or not). Otherwise, if the request is still queued or an + * exception occurred before the request could be sent, this method returns false. + */ virtual bool isSent() const = 0; + + /** + * Blocks the calling thread until a request has been written to the client-side transport, + * or an exception occurs. + */ virtual void waitForSent() = 0; + /** + * Throws the local exception that caused the invocation to fail. If no exception has occurred yet, + * this method does nothing. + */ virtual void throwLocalException() const = 0; + /** + * Determines whether the request was sent synchronously. + * @return True if a request was written to the client-side transport without first being queued. + * If the request was initially queued, sentSynchronously returns false (independent of whether + * the request is still in the queue or has since been written to the client-side transport). + */ virtual bool sentSynchronously() const = 0; + /** + * Obtains the cookie that was passed to the begin_ method. + * @return The cookie, or nil if you did not pass a cookie to the begin_ method. + */ virtual LocalObjectPtr getCookie() const = 0; + /** + * Obtains the name of the operation. + * @return The operation name. + */ virtual const std::string& getOperation() const = 0; + /// \cond INTERNAL virtual bool _waitForResponse() = 0; virtual Ice::InputStream* _startReadParams() = 0; virtual void _endReadParams() = 0; @@ -71,10 +144,13 @@ public: typedef IceUtil::Handle<Callback> CallbackPtr; virtual void _scheduleCallback(const CallbackPtr&) = 0; + /// \endcond protected: + /// \cond INTERNAL static void check(const AsyncResultPtr&, const ::std::string&); + /// \endcond }; } diff --git a/cpp/include/Ice/BatchRequestInterceptor.h b/cpp/include/Ice/BatchRequestInterceptor.h index 70c6a7a8e61..18f445b7e66 100644 --- a/cpp/include/Ice/BatchRequestInterceptor.h +++ b/cpp/include/Ice/BatchRequestInterceptor.h @@ -16,6 +16,10 @@ namespace Ice { +/** + * Represents an invocation on a proxy configured for batch-oneway or batch-datagram. + * \headerfile Ice/Ice.h + */ class BatchRequest { public: @@ -24,19 +28,48 @@ public: { } + /** + * Queues the request for an eventual flush. + */ virtual void enqueue() const = 0; + + /** + * Obtains the size of the request. + * @return The number of bytes consumed by the request. + */ virtual int getSize() const = 0; + + /** + * Obtains the name of the operation. + * @return The operation name. + */ virtual const std::string& getOperation() const = 0; + + /** + * Obtains the proxy on which the batch request was invoked. + * @return The originating proxy. + */ virtual const Ice::ObjectPrxPtr& getProxy() const = 0; }; #ifndef ICE_CPP11_MAPPING +/** + * The base class for a batch request interceptor. Subclasses must implement enqueue. + * The interceptor can be installed via InitializationData. + * \headerfile Ice/Ice.h + */ class BatchRequestInterceptor : public IceUtil::Shared { public: - virtual void enqueue(const BatchRequest&, int, int) = 0; + /** + * Called by the Ice run time to enqueue a batch request. + * @param req An object representing the batch request. + * @param count The number of requests currently in the queue. + * @param size The number of bytes consumed by the requests currently in the queue. + */ + virtual void enqueue(const BatchRequest& req, int count, int size) = 0; }; typedef IceUtil::Handle<BatchRequestInterceptor> BatchRequestInterceptorPtr; diff --git a/cpp/include/Ice/CommunicatorAsync.h b/cpp/include/Ice/CommunicatorAsync.h index 12b5068352e..625a9964c20 100644 --- a/cpp/include/Ice/CommunicatorAsync.h +++ b/cpp/include/Ice/CommunicatorAsync.h @@ -17,6 +17,12 @@ namespace Ice { +/** + * Type-safe asynchronous callback wrapper class used for calls to + * Ice::Communicator::begin_flushBatchRequests. + * Create a wrapper instance by calling ::Ice::newCallback_Communicator_flushBatchRequests. + * \headerfile Ice/Ice.h + */ template<class T> class CallbackNC_Communicator_flushBatchRequests : public Callback_Communicator_flushBatchRequests_Base, public ::IceInternal::OnewayCallbackNC<T> @@ -33,6 +39,7 @@ public: { } + /// \cond INTERNAL virtual void completed(const ::Ice::AsyncResultPtr& result) const { ::Ice::CommunicatorPtr communicator = result->getCommunicator(); @@ -47,8 +54,17 @@ public: ::IceInternal::CallbackNC<T>::exception(result, ex); } } + /// \endcond }; +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of + * Ice::Communicator::begin_flushBatchRequests. + */ template<class T> Callback_Communicator_flushBatchRequestsPtr newCallback_Communicator_flushBatchRequests(const IceUtil::Handle<T>& instance, void (T::*excb)(const ::Ice::Exception&), @@ -57,6 +73,14 @@ newCallback_Communicator_flushBatchRequests(const IceUtil::Handle<T>& instance, return new CallbackNC_Communicator_flushBatchRequests<T>(instance, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of + * Ice::Communicator::begin_flushBatchRequests. + */ template<class T> Callback_Communicator_flushBatchRequestsPtr newCallback_Communicator_flushBatchRequests(T* instance, void (T::*excb)(const ::Ice::Exception&), void (T::*sentcb)(bool) = 0) @@ -64,6 +88,12 @@ newCallback_Communicator_flushBatchRequests(T* instance, void (T::*excb)(const : return new CallbackNC_Communicator_flushBatchRequests<T>(instance, excb, sentcb); } +/** + * Type-safe asynchronous callback wrapper class used for calls to + * Ice::Communicator::begin_flushBatchRequests. + * Create a wrapper instance by calling ::Ice::newCallback_Communicator_flushBatchRequests. + * \headerfile Ice/Ice.h + */ template<class T, typename CT> class Callback_Communicator_flushBatchRequests : public Callback_Communicator_flushBatchRequests_Base, public ::IceInternal::OnewayCallback<T, CT> @@ -80,6 +110,7 @@ public: { } + /// \cond INTERNAL virtual void completed(const ::Ice::AsyncResultPtr& result) const { ::Ice::CommunicatorPtr communicator = result->getCommunicator(); @@ -94,8 +125,14 @@ public: ::IceInternal::Callback<T, CT>::exception(result, ex); } } + /// \endcond }; +/** + * Type-safe asynchronous callback wrapper class used for calls to + * Ice::Communicator::begin_flushBatchRequests. + * Create a wrapper instance by calling ::Ice::newCallback_Communicator_flushBatchRequests. + */ template<class T, typename CT> Callback_Communicator_flushBatchRequestsPtr newCallback_Communicator_flushBatchRequests(const IceUtil::Handle<T>& instance, void (T::*excb)(const ::Ice::Exception&, const CT&), @@ -104,6 +141,11 @@ newCallback_Communicator_flushBatchRequests(const IceUtil::Handle<T>& instance, return new Callback_Communicator_flushBatchRequests<T, CT>(instance, excb, sentcb); } +/** + * Type-safe asynchronous callback wrapper class used for calls to + * Ice::Communicator::begin_flushBatchRequests. + * Create a wrapper instance by calling ::Ice::newCallback_Communicator_flushBatchRequests. + */ template<class T, typename CT> Callback_Communicator_flushBatchRequestsPtr newCallback_Communicator_flushBatchRequests(T* instance, void (T::*excb)(const ::Ice::Exception&, const CT&), void (T::*sentcb)(bool, const CT&) = 0) diff --git a/cpp/include/Ice/Comparable.h b/cpp/include/Ice/Comparable.h index 7ee108c1ad4..469915ff1a9 100644 --- a/cpp/include/Ice/Comparable.h +++ b/cpp/include/Ice/Comparable.h @@ -15,6 +15,12 @@ namespace Ice { +/** + * Compares the contents of two smart pointers. + * @param lhs The left-hand side. + * @param rhs The right-hand side. + * @return True if the contents are equal, false otherwise. + */ template<typename T, typename U> inline bool targetEqualTo(const T& lhs, const U& rhs) { @@ -28,6 +34,12 @@ inline bool targetEqualTo(const T& lhs, const U& rhs) } } +/** + * Compares the contents of two smart pointers. + * @param lhs The left-hand side. + * @param rhs The right-hand side. + * @return True if the left-hand side compares less than the right-hand side, false otherwise. + */ template<typename T, typename U> inline bool targetLess(const T& lhs, const U& rhs) { @@ -41,24 +53,48 @@ inline bool targetLess(const T& lhs, const U& rhs) } } +/** + * Compares the contents of two smart pointers. + * @param lhs The left-hand side. + * @param rhs The right-hand side. + * @return True if the left-hand side compares greater than the right-hand side, false otherwise. + */ template<typename T, typename U> inline bool targetGreater(const T& lhs, const U& rhs) { return targetLess(rhs, lhs); } +/** + * Compares the contents of two smart pointers. + * @param lhs The left-hand side. + * @param rhs The right-hand side. + * @return True if the left-hand side compares less than or equal to the right-hand side, false otherwise. + */ template<typename T, typename U> inline bool targetLessEqual(const T& lhs, const U& rhs) { return !targetGreater(lhs, rhs); } +/** + * Compares the contents of two smart pointers. + * @param lhs The left-hand side. + * @param rhs The right-hand side. + * @return True if the left-hand side compares greater than or equal to the right-hand side, false otherwise. + */ template<typename T, typename U> inline bool targetGreaterEqual(const T& lhs, const U& rhs) { return !targetLess(lhs, rhs); } +/** + * Compares the contents of two smart pointers. + * @param lhs The left-hand side. + * @param rhs The right-hand side. + * @return True if the contents are not equal, false otherwise. + */ template<typename T, typename U> inline bool targetNotEqualTo(const T& lhs, const U& rhs) { @@ -67,9 +103,17 @@ inline bool targetNotEqualTo(const T& lhs, const U& rhs) #ifdef ICE_CPP11_MAPPING +/** + * Functor class that compares the contents of two smart pointers of the given type using the given comparator. + * \headerfile Ice/Ice.h + */ template<typename T, template<typename> class Compare> struct TargetCompare { + /** + * Executes the functor to compare the contents of two smart pointers. + * @return True if the contents satisfy the given comparator, false otherwise. + */ bool operator()(const T& lhs, const T& rhs) const { if(lhs && rhs) @@ -87,36 +131,72 @@ struct TargetCompare // Relational operators for generated structs and classes // +/** + * Relational operator for generated structs and classes. + * @param lhs The left-hand side. + * @param rhs The right-hand side. + * @return True if the left-hand side compares less than the right-hand side, false otherwise. + */ template<class C, typename = std::enable_if<std::is_member_function_pointer<decltype(&C::ice_tuple)>::value>> bool operator<(const C& lhs, const C& rhs) { return lhs.ice_tuple() < rhs.ice_tuple(); } +/** + * Relational operator for generated structs and classes. + * @param lhs The left-hand side. + * @param rhs The right-hand side. + * @return True if the left-hand side compares less than or equal to the right-hand side, false otherwise. + */ template<class C, typename = std::enable_if<std::is_member_function_pointer<decltype(&C::ice_tuple)>::value>> bool operator<=(const C& lhs, const C& rhs) { return lhs.ice_tuple() <= rhs.ice_tuple(); } +/** + * Relational operator for generated structs and classes. + * @param lhs The left-hand side. + * @param rhs The right-hand side. + * @return True if the left-hand side compares greater than the right-hand side, false otherwise. + */ template<class C, typename = std::enable_if<std::is_member_function_pointer<decltype(&C::ice_tuple)>::value>> bool operator>(const C& lhs, const C& rhs) { return lhs.ice_tuple() > rhs.ice_tuple(); } +/** + * Relational operator for generated structs and classes. + * @param lhs The left-hand side. + * @param rhs The right-hand side. + * @return True if the left-hand side compares greater than or equal to the right-hand side, false otherwise. + */ template<class C, typename = std::enable_if<std::is_member_function_pointer<decltype(&C::ice_tuple)>::value>> bool operator>=(const C& lhs, const C& rhs) { return lhs.ice_tuple() >= rhs.ice_tuple(); } +/** + * Relational operator for generated structs and classes. + * @param lhs The left-hand side. + * @param rhs The right-hand side. + * @return True if the left-hand side compares equal to the right-hand side, false otherwise. + */ template<class C, typename = std::enable_if<std::is_member_function_pointer<decltype(&C::ice_tuple)>::value>> bool operator==(const C& lhs, const C& rhs) { return lhs.ice_tuple() == rhs.ice_tuple(); } +/** + * Relational operator for generated structs and classes. + * @param lhs The left-hand side. + * @param rhs The right-hand side. + * @return True if the left-hand side is not equal to the right-hand side, false otherwise. + */ template<class C, typename = std::enable_if<std::is_member_function_pointer<decltype(&C::ice_tuple)>::value>> bool operator!=(const C& lhs, const C& rhs) { diff --git a/cpp/include/Ice/Config.h b/cpp/include/Ice/Config.h index b46b7f785e9..11dba1dce38 100644 --- a/cpp/include/Ice/Config.h +++ b/cpp/include/Ice/Config.h @@ -49,15 +49,22 @@ namespace IceInternal namespace Ice { +/** The mapping for the Slice byte type. */ typedef unsigned char Byte; +/** The mapping for the Slice short type. */ typedef short Short; +/** The mapping for the Slice int type. */ typedef int Int; #ifdef ICE_CPP11_MAPPING +/** The mapping for the Slice long type. */ typedef long long int Long; #else +/** The mapping for the Slice long type. */ typedef IceUtil::Int64 Long; #endif +/** The mapping for the Slice float type. */ typedef float Float; +/** The mapping for the Slice double type. */ typedef double Double; } diff --git a/cpp/include/Ice/ConnectionAsync.h b/cpp/include/Ice/ConnectionAsync.h index efb0bbc3ec6..a6f27a8be41 100644 --- a/cpp/include/Ice/ConnectionAsync.h +++ b/cpp/include/Ice/ConnectionAsync.h @@ -18,6 +18,12 @@ namespace Ice { +/** + * Type-safe asynchronous callback wrapper class used for calls to + * Ice::Connection::begin_flushBatchRequests. + * Create a wrapper instance by calling ::Ice::newCallback_Connection_flushBatchRequests. + * \headerfile Ice/Ice.h + */ template<class T> class CallbackNC_Connection_flushBatchRequests : public Callback_Connection_flushBatchRequests_Base, public ::IceInternal::OnewayCallbackNC<T> @@ -34,6 +40,7 @@ public: { } + /// \cond INTERNAL virtual void completed(const ::Ice::AsyncResultPtr& result) const { ::Ice::ConnectionPtr connection = result->getConnection(); @@ -48,8 +55,17 @@ public: ::IceInternal::CallbackNC<T>::exception(result, ex); } } + /// \endcond }; +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of + * Ice::Connection::begin_flushBatchRequests. + */ template<class T> Callback_Connection_flushBatchRequestsPtr newCallback_Connection_flushBatchRequests(const IceUtil::Handle<T>& instance, void (T::*excb)(const ::Ice::Exception&), @@ -58,6 +74,14 @@ newCallback_Connection_flushBatchRequests(const IceUtil::Handle<T>& instance, return new CallbackNC_Connection_flushBatchRequests<T>(instance, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of + * Ice::Connection::begin_flushBatchRequests. + */ template<class T> Callback_Connection_flushBatchRequestsPtr newCallback_Connection_flushBatchRequests(T* instance, void (T::*excb)(const ::Ice::Exception&), void (T::*sentcb)(bool) = 0) @@ -65,6 +89,12 @@ newCallback_Connection_flushBatchRequests(T* instance, void (T::*excb)(const ::I return new CallbackNC_Connection_flushBatchRequests<T>(instance, excb, sentcb); } +/** + * Type-safe asynchronous callback wrapper class used for calls to + * Ice::Connection::begin_flushBatchRequests. + * Create a wrapper instance by calling ::Ice::newCallback_Connection_flushBatchRequests. + * \headerfile Ice/Ice.h + */ template<class T, typename CT> class Callback_Connection_flushBatchRequests : public Callback_Connection_flushBatchRequests_Base, public ::IceInternal::OnewayCallback<T, CT> @@ -81,6 +111,7 @@ public: { } + /// \cond INTERNAL virtual void completed(const ::Ice::AsyncResultPtr& result) const { ::Ice::ConnectionPtr connection = result->getConnection(); @@ -95,8 +126,17 @@ public: ::IceInternal::Callback<T, CT>::exception(result, ex); } } + /// \endcond }; +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of + * Ice::Connection::begin_flushBatchRequests. + */ template<class T, typename CT> Callback_Connection_flushBatchRequestsPtr newCallback_Connection_flushBatchRequests(const IceUtil::Handle<T>& instance, void (T::*excb)(const ::Ice::Exception&, const CT&), @@ -105,6 +145,14 @@ newCallback_Connection_flushBatchRequests(const IceUtil::Handle<T>& instance, return new Callback_Connection_flushBatchRequests<T, CT>(instance, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of + * Ice::Connection::begin_flushBatchRequests. + */ template<class T, typename CT> Callback_Connection_flushBatchRequestsPtr newCallback_Connection_flushBatchRequests(T* instance, void (T::*excb)(const ::Ice::Exception&, const CT&), void (T::*sentcb)(bool, const CT&) = 0) @@ -112,6 +160,12 @@ newCallback_Connection_flushBatchRequests(T* instance, void (T::*excb)(const ::I return new Callback_Connection_flushBatchRequests<T, CT>(instance, excb, sentcb); } +/** + * Type-safe asynchronous callback wrapper class used for calls to + * Ice::Connection::begin_heartbeat. + * Create a wrapper instance by calling ::Ice::newCallback_Connection_heartbeat. + * \headerfile Ice/Ice.h + */ template<class T> class CallbackNC_Connection_heartbeat : public Callback_Connection_heartbeat_Base, public ::IceInternal::OnewayCallbackNC<T> @@ -128,6 +182,7 @@ public: { } + /// \cond INTERNAL virtual void completed(const ::Ice::AsyncResultPtr& __result) const { ::Ice::ConnectionPtr __con = __result->getConnection(); @@ -142,8 +197,17 @@ public: ::IceInternal::CallbackNC<T>::exception(__result, ex); } } + /// \endcond }; +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of + * Ice::Connection::begin_heartbeat. + */ template<class T> Callback_Connection_heartbeatPtr newCallback_Connection_heartbeat(const IceUtil::Handle<T>& instance, void (T::*excb)(const ::Ice::Exception&), @@ -152,12 +216,26 @@ newCallback_Connection_heartbeat(const IceUtil::Handle<T>& instance, return new CallbackNC_Connection_heartbeat<T>(instance, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of + * Ice::Connection::begin_heartbeat. + */ template<class T> Callback_Connection_heartbeatPtr newCallback_Connection_heartbeat(T* instance, void (T::*excb)(const ::Ice::Exception&), void (T::*sentcb)(bool) = 0) { return new CallbackNC_Connection_heartbeat<T>(instance, excb, sentcb); } +/** + * Type-safe asynchronous callback wrapper class used for calls to + * Ice::Connection::begin_heartbeat. + * Create a wrapper instance by calling ::Ice::newCallback_Connection_heartbeat. + * \headerfile Ice/Ice.h + */ template<class T, typename CT> class Callback_Connection_heartbeat : public Callback_Connection_heartbeat_Base, public ::IceInternal::OnewayCallback<T, CT> @@ -174,6 +252,7 @@ public: { } + /// \cond INTERNAL virtual void completed(const ::Ice::AsyncResultPtr& __result) const { ::Ice::ConnectionPtr __con = __result->getConnection(); @@ -188,8 +267,17 @@ public: ::IceInternal::Callback<T, CT>::exception(__result, ex); } } + /// \endcond }; +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of + * Ice::Connection::begin_heartbeat. + */ template<class T, typename CT> Callback_Connection_heartbeatPtr newCallback_Connection_heartbeat(const IceUtil::Handle<T>& instance, void (T::*excb)(const ::Ice::Exception&, const CT&), @@ -198,6 +286,14 @@ newCallback_Connection_heartbeat(const IceUtil::Handle<T>& instance, return new Callback_Connection_heartbeat<T, CT>(instance, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of + * Ice::Connection::begin_heartbeat. + */ template<class T, typename CT> Callback_Connection_heartbeatPtr newCallback_Connection_heartbeat(T* instance, void (T::*excb)(const ::Ice::Exception&, const CT&), void (T::*sentcb)(bool, const CT&) = 0) diff --git a/cpp/include/Ice/ConnectionIF.h b/cpp/include/Ice/ConnectionIF.h index c783e0d6fa3..0edf931b0f2 100644 --- a/cpp/include/Ice/ConnectionIF.h +++ b/cpp/include/Ice/ConnectionIF.h @@ -16,6 +16,7 @@ namespace Ice { +/// \cond INTERNAL class ConnectionI; #ifdef ICE_CPP11_MAPPING // C++11 mapping using ConnectionIPtr = ::std::shared_ptr<ConnectionI>; @@ -23,6 +24,7 @@ using ConnectionIPtr = ::std::shared_ptr<ConnectionI>; ICE_API Ice::LocalObject* upCast(Ice::ConnectionI*); typedef IceInternal::Handle<ConnectionI> ConnectionIPtr; #endif +/// \endcond } diff --git a/cpp/include/Ice/DispatchInterceptor.h b/cpp/include/Ice/DispatchInterceptor.h index 5233f2fadbb..a2aec7a9450 100644 --- a/cpp/include/Ice/DispatchInterceptor.h +++ b/cpp/include/Ice/DispatchInterceptor.h @@ -15,13 +15,28 @@ namespace Ice { +/** + * Base class for a dispatch interceptor, which is a servant that dispatches requests + * to another servant. A subclass must implement the dispatch method. A dispatch interceptor + * can be registered with an object adapter just like any other servant. + * \headerfile Ice/Ice.h + */ class ICE_API DispatchInterceptor : public virtual Object { public: - virtual bool dispatch(Request&) = 0; + /** + * Called by the Ice run time when a new request needs to be dispatched. The implementation + * must eventually call ice_dispatch on the delegate servant and pass the given request object. + * @param req An opaque object representing the request to be dispatched. + * @return True if the request was dispatched synchronously, or false if the request was + * dispatched asynchronously. + */ + virtual bool dispatch(Request& req) = 0; + /// \cond INTERNAL virtual bool _iceDispatch(IceInternal::Incoming&, const Current&); + /// \endcond }; ICE_DEFINE_PTR(DispatchInterceptorPtr, DispatchInterceptor); diff --git a/cpp/include/Ice/Dispatcher.h b/cpp/include/Ice/Dispatcher.h index c30c240699c..22b1607e4c7 100644 --- a/cpp/include/Ice/Dispatcher.h +++ b/cpp/include/Ice/Dispatcher.h @@ -24,24 +24,44 @@ namespace Ice { +/** + * Encapsulates all the details of a request dispatch or AMI callback. + * The application must eventually invoke run to dispatch the call. + * \headerfile Ice/Ice.h + */ class ICE_API DispatcherCall : public virtual IceUtil::Shared { public: virtual ~DispatcherCall(); + /** + * Dispatches the call. + */ virtual void run() = 0; }; typedef IceUtil::Handle<DispatcherCall> DispatcherCallPtr; +/** + * Base class for a dispatcher. A subclass must define the dispatch method. + * The dispatcher can be installed via InitializationData. + * \headerfile Ice/Ice.h + */ class ICE_API Dispatcher : public virtual IceUtil::Shared { public: virtual ~Dispatcher(); - virtual void dispatch(const DispatcherCallPtr&, const ConnectionPtr&) = 0; + /** + * Called by the Ice run time when an incoming request or an AMI callback needs to + * be dispatched. The implementation must eventually invoke run on the call object. + * @param call An object representing the call that must be dispatched. + * @param connection The connection object associated with the call, or nil if no + * connection is associated with the call. + */ + virtual void dispatch(const DispatcherCallPtr& call, const ConnectionPtr& connection) = 0; }; typedef IceUtil::Handle<Dispatcher> DispatcherPtr; diff --git a/cpp/include/Ice/Exception.h b/cpp/include/Ice/Exception.h index 8c5803b9d24..e2787e33765 100644 --- a/cpp/include/Ice/Exception.h +++ b/cpp/include/Ice/Exception.h @@ -26,14 +26,20 @@ class InputStream; typedef IceUtil::Exception Exception; -// -// Base class for all Ice run-time exceptions -// +/** + * Base class for all Ice run-time exceptions. + * \headerfile Ice/Ice.h + */ class ICE_API LocalException : public IceUtil::Exception { public: - LocalException(const char*, int); + /** + * The file and line number are required for all local exceptions. + * @param file The file name in which the exception was raised, typically __FILE__. + * @param line The line number at which the exception was raised, typically __LINE__. + */ + LocalException(const char* file, int line); #ifdef ICE_CPP11_COMPILER LocalException(const LocalException&) = default; @@ -42,22 +48,35 @@ public: virtual ~LocalException() throw(); #endif + /** + * Polymporphically clones this exception. + * @return A shallow copy of this exception. + */ #ifdef ICE_CPP11_MAPPING std::unique_ptr<LocalException> ice_clone() const; #else virtual LocalException* ice_clone() const = 0; #endif + /** + * Obtains the Slice type ID of this exception. + * @return The fully-scoped type ID. + */ static const std::string& ice_staticId(); }; -// -// Base class for all Ice user exceptions -// +/** + * Base class for all Ice user exceptions. + * \headerfile Ice/Ice.h + */ class ICE_API UserException : public IceUtil::Exception { public: + /** + * Polymporphically clones this exception. + * @return A shallow copy of this exception. + */ #ifdef ICE_CPP11_MAPPING std::unique_ptr<UserException> ice_clone() const; #else @@ -65,30 +84,45 @@ public: #endif virtual Ice::SlicedDataPtr ice_getSlicedData() const; + /** + * Obtains the Slice type ID of this exception. + * @return The fully-scoped type ID. + */ static const std::string& ice_staticId(); + /// \cond STREAM virtual void _write(::Ice::OutputStream*) const; virtual void _read(::Ice::InputStream*); virtual bool _usesClasses() const; + /// \endcond protected: + /// \cond STREAM virtual void _writeImpl(::Ice::OutputStream*) const {} virtual void _readImpl(::Ice::InputStream*) {} + /// \endcond }; -// -// Base class for all Ice system exceptions -// -// System exceptions are currently Ice internal, non-documented -// exceptions. -// +/** + * Base class for all Ice system exceptions. + * + * System exceptions are currently Ice internal, non-documented + * exceptions. + * \headerfile Ice/Ice.h + */ class ICE_API SystemException : public IceUtil::Exception { public: - SystemException(const char*, int); + /** + * The file and line number are required for all local exceptions. + * @param file The file name in which the exception was raised, typically __FILE__. + * @param line The line number at which the exception was raised, typically __LINE__. + */ + SystemException(const char* file, int line); + #ifdef ICE_CPP11_COMPILER SystemException(const SystemException&) = default; virtual ~SystemException(); @@ -96,12 +130,20 @@ public: virtual ~SystemException() throw(); #endif + /** + * Polymporphically clones this exception. + * @return A shallow copy of this exception. + */ #ifdef ICE_CPP11_MAPPING std::unique_ptr<SystemException> ice_clone() const; #else virtual SystemException* ice_clone() const = 0; #endif + /** + * Obtains the Slice type ID of this exception. + * @return The fully-scoped type ID. + */ static const std::string& ice_staticId(); }; diff --git a/cpp/include/Ice/ExceptionHelpers.h b/cpp/include/Ice/ExceptionHelpers.h index 0865fa0f178..e7e44246459 100644 --- a/cpp/include/Ice/ExceptionHelpers.h +++ b/cpp/include/Ice/ExceptionHelpers.h @@ -20,24 +20,40 @@ namespace Ice class LocalException; +/** + * Helper template for local exceptions. + * \headerfile Ice/Ice.h + */ template<typename T, typename B> class LocalExceptionHelper : public IceUtil::ExceptionHelper<T, B> { public: using IceUtil::ExceptionHelper<T, B>::ExceptionHelper; + /** + * Obtains the Slice type ID of this exception. + * @return The fully-scoped type ID. + */ virtual std::string ice_id() const override { return T::ice_staticId(); } }; +/** + * Helper template for user exceptions. + * \headerfile Ice/Ice.h + */ template<typename T, typename B> class UserExceptionHelper : public IceUtil::ExceptionHelper<T, B> { public: using IceUtil::ExceptionHelper<T, B>::ExceptionHelper; + /** + * Obtains the Slice type ID of this exception. + * @return The fully-scoped type ID. + */ virtual std::string ice_id() const override { return T::ice_staticId(); @@ -45,6 +61,7 @@ public: protected: + /// \cond STREAM virtual void _writeImpl(Ice::OutputStream* os) const override { os->startSlice(T::ice_staticId(), -1, std::is_same<B, Ice::LocalException>::value ? true : false); @@ -60,6 +77,7 @@ protected: is->endSlice(); B::_readImpl(is); } + /// \endcond }; } diff --git a/cpp/include/Ice/FactoryTable.h b/cpp/include/Ice/FactoryTable.h index 010d33411d7..6d23b128615 100644 --- a/cpp/include/Ice/FactoryTable.h +++ b/cpp/include/Ice/FactoryTable.h @@ -17,11 +17,21 @@ namespace Ice { +/** + * The base class for a compact ID resolver. Subclasses must implement resolve. + * The resolver can be installed via InitializationData. + * \headerfile Ice/Ice.h + */ class ICE_API CompactIdResolver : public IceUtil::Shared { public: - virtual ::std::string resolve(Ice::Int) const = 0; + /** + * Called by the Ice run time when a compact ID must be translated into a type ID. + * @param id The compact ID. + * @return The fully-scoped Slice type ID, or an empty string if the compact ID is unknown. + */ + virtual ::std::string resolve(Ice::Int id) const = 0; }; typedef IceUtil::Handle<CompactIdResolver> CompactIdResolverPtr; diff --git a/cpp/include/Ice/Format.h b/cpp/include/Ice/Format.h index 4e756fd62ce..6753a98a473 100644 --- a/cpp/include/Ice/Format.h +++ b/cpp/include/Ice/Format.h @@ -15,27 +15,26 @@ namespace Ice { -// -// This enumeration describes the possible formats for classes and exceptions. -// - +/** + * Describes the possible formats for classes and exceptions. + */ #ifdef ICE_CPP11_MAPPING enum class FormatType : unsigned char #else enum FormatType #endif { - // - // Indicates that no preference was specified. - // + /** + * Indicates that no preference was specified. + */ DefaultFormat, - // - // A minimal format that eliminates the possibility for slicing unrecognized types. - // + /** + * A minimal format that eliminates the possibility for slicing unrecognized types. + */ CompactFormat, - // - // Allow slicing and preserve slices for unknown types. - // + /** + * Allow slicing and preserve slices for unknown types. + */ SlicedFormat }; diff --git a/cpp/include/Ice/Functional.h b/cpp/include/Ice/Functional.h index a132c57033b..802c2236c9a 100644 --- a/cpp/include/Ice/Functional.h +++ b/cpp/include/Ice/Functional.h @@ -21,6 +21,7 @@ namespace Ice { +/// \cond INTERNAL template<class R, class T> inline ::IceUtilInternal::MemFun<R, T, ICE_INTERNAL_HANDLE<T> > memFun(R (T::*p)(void)) @@ -132,6 +133,7 @@ secondConstVoidMemFun1(void (T::*p)(A) const) { return ::IceUtilInternal::SecondConstVoidMemFun1<K, T, ICE_INTERNAL_HANDLE<T>, A>(p); } +/// \endcond } diff --git a/cpp/include/Ice/IconvStringConverter.h b/cpp/include/Ice/IconvStringConverter.h index 67bbc6eabd9..0d70c9bc048 100644 --- a/cpp/include/Ice/IconvStringConverter.h +++ b/cpp/include/Ice/IconvStringConverter.h @@ -36,23 +36,50 @@ namespace Ice { +/** + * Indicates that Iconv does not support the code. + * \headerfile Ice/Ice.h + */ class ICE_API IconvInitializationException : public IceUtil::ExceptionHelper<IconvInitializationException> { public: - IconvInitializationException(const char*, int, const std::string&); + /** + * Constructs the exception with a reason. The file and line number are required. + * @param file The file name in which the exception was raised, typically __FILE__. + * @param line The line number at which the exception was raised, typically __LINE__. + * @param reason More detail about the failure. + */ + IconvInitializationException(const char* file, int line, const std::string& reason); #ifndef ICE_CPP11_COMPILER virtual ~IconvInitializationException() throw(); #endif + /** + * Obtains the Slice type ID of this exception. + * @return The fully-scoped type ID. + */ virtual std::string ice_id() const; - virtual void ice_print(std::ostream&) const; + + /** + * Prints a description of this exception to the given stream. + * @param str The output stream. + */ + virtual void ice_print(std::ostream& str) const; #ifndef ICE_CPP11_MAPPING + /** + * Polymporphically clones this exception. + * @return A shallow copy of this exception. + */ virtual IconvInitializationException* ice_clone() const; #endif + /** + * Obtains the reason for the failure. + * @return The reason. + */ std::string reason() const; private: @@ -329,6 +356,13 @@ IconvStringConverter<charT>::fromUTF8(const Ice::Byte* sourceStart, const Ice::B namespace Ice { + +/** + * Creates a string converter for the given code. + * @param internalCodeWithDefault The desired code. If empty or not provided, a default code is used. + * @return The converter object. + * @throws IconvInitializationException If the code is not supported. + */ template<typename charT> ICE_HANDLE<IceUtil::BasicStringConverter<charT> > createIconvStringConverter(const std::string& internalCodeWithDefault = "") @@ -342,6 +376,7 @@ createIconvStringConverter(const std::string& internalCodeWithDefault = "") return ICE_MAKE_SHARED(IceInternal::IconvStringConverter<charT>, internalCode); } + } #endif diff --git a/cpp/include/Ice/Incoming.h b/cpp/include/Ice/Incoming.h index 2da92c8bc5a..83bfdc9842f 100644 --- a/cpp/include/Ice/Incoming.h +++ b/cpp/include/Ice/Incoming.h @@ -29,12 +29,24 @@ namespace Ice { +/** + * Base class for marshaled result structures, which are generated for operations having the + * marshaled-result metadata tag. + * \headerfile Ice/Ice.h + */ class ICE_API MarshaledResult { public: - MarshaledResult(const Current&); + /** + * The constructor requires the Current object that was passed to the servant. + */ + MarshaledResult(const Current& current); + /** + * Obtains the output stream that is used to marshal the results. + * @return The output stream. + */ std::shared_ptr<OutputStream> getOutputStream() const { return ostr; @@ -42,6 +54,7 @@ public: protected: + /** The output stream used to marshal the results. */ std::shared_ptr<OutputStream> ostr; }; diff --git a/cpp/include/Ice/IncomingAsync.h b/cpp/include/Ice/IncomingAsync.h index b9e5d34ba25..8f9a78d8430 100644 --- a/cpp/include/Ice/IncomingAsync.h +++ b/cpp/include/Ice/IncomingAsync.h @@ -17,13 +17,25 @@ namespace Ice { +/** + * Base class for generated AMD callback classes. + * \headerfile Ice/Ice.h + */ class ICE_API AMDCallback : public Ice::LocalObject { public: virtual ~AMDCallback(); - virtual void ice_exception(const ::std::exception&) = 0; + /** + * Completes the asynchronous request with the given exception. + * @param ex The exception that completed the request. + */ + virtual void ice_exception(const ::std::exception& ex) = 0; + + /** + * Completes the asynchronous request with an UnknownException. + */ virtual void ice_exception() = 0; }; @@ -112,18 +124,38 @@ private: namespace Ice { +/** + * Base class for the AMD callback for BlobjectAsync::ice_invoke_async. + * \headerfile Ice/Ice.h + */ class ICE_API AMD_Object_ice_invoke : public virtual Ice::AMDCallback { public: virtual ~AMD_Object_ice_invoke(); - virtual void ice_response(bool, const std::vector<Ice::Byte>&) = 0; - virtual void ice_response(bool, const std::pair<const Ice::Byte*, const Ice::Byte*>&) = 0; + /** + * Completes the request. + * @param ok True if the request completed successfully, in which case bytes contains an encapsulation + * of the marshaled results. False if the request completed with a user exception, in which case bytes + * contains an encapsulation of the marshaled user exception. + * @param bytes An encapsulation of the results or user exception. + */ + virtual void ice_response(bool ok, const std::vector<Ice::Byte>& bytes) = 0; + + /** + * Completes the request. + * @param ok True if the request completed successfully, in which case bytes contains an encapsulation + * of the marshaled results. False if the request completed with a user exception, in which case bytes + * contains an encapsulation of the marshaled user exception. + * @param bytes An encapsulation of the results or user exception. + */ + virtual void ice_response(bool ok, const std::pair<const Ice::Byte*, const Ice::Byte*>& bytes) = 0; }; } +/// \cond INTERNAL namespace IceAsync { @@ -143,6 +175,7 @@ public: } } +/// \endcond #endif #endif 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)); } diff --git a/cpp/include/Ice/InputStream.h b/cpp/include/Ice/InputStream.h index b2cba30b20e..021b12ac58b 100644 --- a/cpp/include/Ice/InputStream.h +++ b/cpp/include/Ice/InputStream.h @@ -29,6 +29,7 @@ namespace Ice class UserException; +/// \cond INTERNAL template<typename T> inline void patchHandle(void* addr, const ValuePtr& v) { @@ -44,49 +45,139 @@ patchHandle(void* addr, const ValuePtr& v) _icePatchObjectPtr(*p, v); // Generated _icePatchObjectPtr function, necessary for forward declarations. #endif } +/// \endcond +/** + * Interface for input streams used to extract Slice types from a sequence of bytes. + * \headerfile Ice/Ice.h + */ class ICE_API InputStream : public IceInternal::Buffer { public: typedef size_t size_type; + + /** + * Signature for a patch function, used to receive an unmarshaled value. + * @param addr The target address. + * @param v The unmarshaled value. + */ typedef void (*PatchFunc)(void*, const ValuePtr&); - // - // These constructors use the latest encoding version. Without a communicator, the stream - // will not be able to unmarshal a proxy. For other unmarshaling tasks, you can provide - // Helpers for objects that are normally provided by a communicator. - // + /** + * Constructs a stream using the latest encoding version but without a communicator. + * This stream will not be able to unmarshal a proxy. For other unmarshaling tasks, + * you can provide Helpers for objects that are normally provided by a communicator. + * You can supply a communicator later by calling initialize(). + */ InputStream(); - InputStream(const std::vector<Byte>&); - InputStream(const std::pair<const Byte*, const Byte*>&); - InputStream(IceInternal::Buffer&, bool = false); - - // - // These constructors use the communicator's default encoding version. - // - InputStream(const CommunicatorPtr&); - InputStream(const CommunicatorPtr&, const std::vector<Byte>&); - InputStream(const CommunicatorPtr&, const std::pair<const Byte*, const Byte*>&); - InputStream(const CommunicatorPtr&, IceInternal::Buffer&, bool = false); - // - // These constructors use the given encoding version. Without a communicator, the stream - // will not be able to unmarshal a proxy. For other unmarshaling tasks, you can provide - // Helpers for objects that are normally provided by a communicator. - // - InputStream(const EncodingVersion&); - InputStream(const EncodingVersion&, const std::vector<Byte>&); - InputStream(const EncodingVersion&, const std::pair<const Byte*, const Byte*>&); + /** + * Constructs a stream using the latest encoding version but without a communicator. + * This stream will not be able to unmarshal a proxy. For other unmarshaling tasks, + * you can provide Helpers for objects that are normally provided by a communicator. + * You can supply a communicator later by calling initialize(). + * @param bytes The encoded data. + */ + InputStream(const std::vector<Byte>& bytes); + + /** + * Constructs a stream using the latest encoding version but without a communicator. + * This stream will not be able to unmarshal a proxy. For other unmarshaling tasks, + * you can provide Helpers for objects that are normally provided by a communicator. + * You can supply a communicator later by calling initialize(). + * @param bytes The encoded data. + */ + InputStream(const std::pair<const Byte*, const Byte*>& bytes); + + /// \cond INTERNAL + InputStream(IceInternal::Buffer&, bool = false); + /// \endcond + + /** + * Constructs a stream using the communicator's default encoding version. + * @param communicator The communicator to use for unmarshaling tasks. + */ + InputStream(const CommunicatorPtr& communicator); + + /** + * Constructs a stream using the communicator's default encoding version. + * @param communicator The communicator to use for unmarshaling tasks. + * @param bytes The encoded data. + */ + InputStream(const CommunicatorPtr& communicator, const std::vector<Byte>& bytes); + + /** + * Constructs a stream using the communicator's default encoding version. + * @param communicator The communicator to use for unmarshaling tasks. + * @param bytes The encoded data. + */ + InputStream(const CommunicatorPtr& communicator, const std::pair<const Byte*, const Byte*>& bytes); + + /// \cond INTERNAL + InputStream(const CommunicatorPtr& communicator, IceInternal::Buffer&, bool = false); + /// \endcond + + /** + * Constructs a stream using the given encoding version but without a communicator. + * This stream will not be able to unmarshal a proxy. For other unmarshaling tasks, + * you can provide Helpers for objects that are normally provided by a communicator. + * You can supply a communicator later by calling initialize(). + * @param version The encoding version used to encode the data to be unmarshaled. + */ + InputStream(const EncodingVersion& version); + + /** + * Constructs a stream using the given encoding version but without a communicator. + * This stream will not be able to unmarshal a proxy. For other unmarshaling tasks, + * you can provide Helpers for objects that are normally provided by a communicator. + * You can supply a communicator later by calling initialize(). + * @param version The encoding version used to encode the data to be unmarshaled. + * @param bytes The encoded data. + */ + InputStream(const EncodingVersion& version, const std::vector<Byte>& bytes); + + /** + * Constructs a stream using the given encoding version but without a communicator. + * This stream will not be able to unmarshal a proxy. For other unmarshaling tasks, + * you can provide Helpers for objects that are normally provided by a communicator. + * You can supply a communicator later by calling initialize(). + * @param version The encoding version used to encode the data to be unmarshaled. + * @param bytes The encoded data. + */ + InputStream(const EncodingVersion& version, const std::pair<const Byte*, const Byte*>& bytes); + + /// \cond INTERNAL InputStream(const EncodingVersion&, IceInternal::Buffer&, bool = false); - - // - // These constructors use the given communicator and encoding version. - // - InputStream(const CommunicatorPtr&, const EncodingVersion&); - InputStream(const CommunicatorPtr&, const EncodingVersion&, const std::vector<Byte>&); - InputStream(const CommunicatorPtr&, const EncodingVersion&, const std::pair<const Byte*, const Byte*>&); + /// \endcond + + /** + * Constructs a stream using the given communicator and encoding version. + * @param communicator The communicator to use for unmarshaling tasks. + * @param version The encoding version used to encode the data to be unmarshaled. + */ + InputStream(const CommunicatorPtr& communicator, const EncodingVersion& version); + + /** + * Constructs a stream using the given communicator and encoding version. + * @param communicator The communicator to use for unmarshaling tasks. + * @param version The encoding version used to encode the data to be unmarshaled. + * @param bytes The encoded data. + */ + InputStream(const CommunicatorPtr& communicator, const EncodingVersion& version, const std::vector<Byte>& bytes); + + /** + * Constructs a stream using the given communicator and encoding version. + * @param communicator The communicator to use for unmarshaling tasks. + * @param version The encoding version used to encode the data to be unmarshaled. + * @param bytes The encoded data. + */ + InputStream(const CommunicatorPtr& communicator, const EncodingVersion& version, + const std::pair<const Byte*, const Byte*>& bytes); + + /// \cond INTERNAL InputStream(const CommunicatorPtr&, const EncodingVersion&, IceInternal::Buffer&, bool = false); + /// \endcond ~InputStream() { @@ -106,75 +197,184 @@ public: #endif } - // - // Use initialize() if you originally constructed the stream without a communicator. - // - void initialize(const CommunicatorPtr&); - void initialize(const CommunicatorPtr&, const EncodingVersion&); - + /** + * Initializes the stream to use the communicator's default encoding version. + * Use initialize() if you originally constructed the stream without a communicator. + * @param communicator The communicator to use for unmarshaling tasks. + */ + void initialize(const CommunicatorPtr& communicator); + + /** + * Initializes the stream to use the given communicator and encoding version. + * Use initialize() if you originally constructed the stream without a communicator. + * @param communicator The communicator to use for unmarshaling tasks. + * @param version The encoding version used to encode the data to be unmarshaled. + */ + void initialize(const CommunicatorPtr& communicator, const EncodingVersion& version); + + /** + * Releases any data retained by encapsulations. + */ void clear(); + /// \cond INTERNAL // // Must return Instance*, because we don't hold an InstancePtr for // optimization reasons (see comments below). // IceInternal::Instance* instance() const { return _instance; } // Inlined for performance reasons. - - void setValueFactoryManager(const ValueFactoryManagerPtr&); - - void setLogger(const LoggerPtr&); - + /// \endcond + + /** + * Sets the value factory manager to use when unmarshaling value instances. If the stream + * was initialized with a communicator, the communicator's value factory manager will + * be used by default. + * + * @param vfm The value factory manager. + */ + void setValueFactoryManager(const ValueFactoryManagerPtr& vfm); + + /** + * Sets the logger to use when logging trace messages. If the stream + * was initialized with a communicator, the communicator's logger will + * be used by default. + * + * @param logger The logger to use for logging trace messages. + */ + void setLogger(const LoggerPtr& logger); + + /** + * Sets the compact ID resolver to use when unmarshaling value and exception + * instances. If the stream was initialized with a communicator, the communicator's + * resolver will be used by default. + * + * @param r The compact ID resolver. + */ #ifdef ICE_CPP11_MAPPING - void setCompactIdResolver(std::function<std::string(int)>); + void setCompactIdResolver(std::function<std::string(int)> r); #else - void setCompactIdResolver(const CompactIdResolverPtr&); + void setCompactIdResolver(const CompactIdResolverPtr& r); #endif #ifndef ICE_CPP11_MAPPING - void setCollectObjects(bool); + /** + * Indicates whether to mark instances of Slice classes as collectable. If the stream is + * initialized with a communicator, this setting defaults to the value of the + * Ice.CollectObjects property, otherwise the setting defaults to false. + * @param b True to mark instances as collectable, false otherwise. + */ + void setCollectObjects(bool b); #endif - void setSliceValues(bool); - - void setTraceSlicing(bool); - - void setClassGraphDepthMax(size_t); - + /** + * Indicates whether to slice instances of Slice classes to a known Slice type when a more + * derived type is unknown. An instance is "sliced" when no static information is available + * for a Slice type ID and no factory can be found for that type, resulting in the creation + * of an instance of a less-derived type. If slicing is disabled in this situation, the + * stream raises the exception NoValueFactoryException. The default behavior is to allow slicing. + * @param b True to enable slicing, false otherwise. + */ + void setSliceValues(bool b); + + /** + * Indicates whether to log messages when instances of Slice classes are sliced. If the stream + * is initialized with a communicator, this setting defaults to the value of the Ice.Trace.Slicing + * property, otherwise the setting defaults to false. + * @param b True to enable logging, false otherwise. + */ + void setTraceSlicing(bool b); + + /** + * Sets an upper limit on the depth of a class graph. If this limit is exceeded during + * unmarshaling, the stream raises MarshalException. + * @param n The maximum depth. + */ + void setClassGraphDepthMax(size_t n); + + /** + * Obtains the closure data associated with this stream. + * @return The data as a void pointer. + */ void* getClosure() const; - void* setClosure(void*); - - void swap(InputStream&); + /** + * Associates closure data with this stream. + * @param p The data as a void pointer. + * @return The previous closure data, or nil. + */ + void* setClosure(void* p); + + /** + * Swaps the contents of one stream with another. + * + * @param other The other stream. + */ + void swap(InputStream& other); + + /// \cond INTERNAL void resetEncapsulation(); + /// \endcond + /** + * Resizes the stream to a new size. + * + * @param sz The new size. + */ void resize(Container::size_type sz) { b.resize(sz); i = b.end(); } + /** + * Marks the start of a class instance. + */ void startValue() { assert(_currentEncaps && _currentEncaps->decoder); _currentEncaps->decoder->startInstance(ValueSlice); } + + /** + * Marks the end of a class instance. + * + * @param preserve Pass true and the stream will preserve the unknown slices of the instance, or false + * to discard the unknown slices. + * @return An object that encapsulates the unknown slice data. + */ SlicedDataPtr endValue(bool preserve) { assert(_currentEncaps && _currentEncaps->decoder); return _currentEncaps->decoder->endInstance(preserve); } + /** + * Marks the start of a user exception. + */ void startException() { assert(_currentEncaps && _currentEncaps->decoder); _currentEncaps->decoder->startInstance(ExceptionSlice); } + + /** + * Marks the end of a user exception. + * + * @param preserve Pass true and the stream will preserve the unknown slices of the exception, or false + * to discard the unknown slices. + * @return An object that encapsulates the unknown slice data. + */ SlicedDataPtr endException(bool preserve) { assert(_currentEncaps && _currentEncaps->decoder); return _currentEncaps->decoder->endInstance(preserve); } + /** + * Reads the start of an encapsulation. + * + * @return The encoding version used by the encapsulation. + */ const EncodingVersion& startEncapsulation() { Encaps* oldEncaps = _currentEncaps; @@ -214,6 +414,9 @@ public: return _currentEncaps->encoding; } + /** + * Ends the current encapsulation. + */ void endEncapsulation() { assert(_currentEncaps); @@ -254,6 +457,11 @@ public: } } + /** + * Skips an empty encapsulation. + * + * @return The encapsulation's encoding version. + */ EncodingVersion skipEmptyEncapsulation() { Ice::Int sz; @@ -286,6 +494,13 @@ public: return encoding; } + /** + * Returns a blob of bytes representing an encapsulation. + * + * @param v A pointer into the internal marshaling buffer representing the start of the encoded encapsulation. + * @param sz The number of bytes in the encapsulation. + * @return encoding The encapsulation's encoding version. + */ EncodingVersion readEncapsulation(const Byte*& v, Int& sz) { EncodingVersion encoding; @@ -305,32 +520,71 @@ public: return encoding; } + /** + * Determines the current encoding version. + * + * @return The encoding version. + */ const EncodingVersion& getEncoding() const { return _currentEncaps ? _currentEncaps->encoding : _encoding; } + /** + * Determines the size of the current encapsulation, excluding the encapsulation header. + * + * @return The size of the encapsulated data. + */ Int getEncapsulationSize(); + + /** + * Skips over an encapsulation. + * + * @return The encoding version of the skipped encapsulation. + */ EncodingVersion skipEncapsulation(); + /** + * Reads the start of a value or exception slice. + * + * @return The Slice type ID for this slice. + */ std::string startSlice() { assert(_currentEncaps && _currentEncaps->decoder); return _currentEncaps->decoder->startSlice(); } + + /** + * Indicates that the end of a value or exception slice has been reached. + */ void endSlice() { assert(_currentEncaps && _currentEncaps->decoder); _currentEncaps->decoder->endSlice(); } + + /** + * Skips over a value or exception slice. + */ void skipSlice() { assert(_currentEncaps && _currentEncaps->decoder); _currentEncaps->decoder->skipSlice(); } + /** + * Indicates that unmarshaling is complete, except for any class instances. The application must call this method + * only if the stream actually contains class instances. Calling readPendingValues triggers the + * patch callbacks to inform the application that unmarshaling of an instance is complete. + */ void readPendingValues(); + /** + * Extracts a size from the stream. + * + * @return The extracted size. + */ Int readSize() // Inlined for performance reasons. { Byte byte; @@ -352,10 +606,28 @@ public: } } - Int readAndCheckSeqSize(int); - - void readBlob(std::vector<Byte>&, Int); - + /** + * Reads and validates a sequence size. + * + * @param minSize The minimum size required by the sequence type. + * @return The extracted size. + */ + Int readAndCheckSeqSize(int minSize); + + /** + * Reads a blob of bytes from the stream. + * + * @param bytes The vector to hold a copy of the bytes from the marshaling buffer. + * @param sz The number of bytes to read. + */ + void readBlob(std::vector<Byte>& bytes, Int sz); + + /** + * Reads a blob of bytes from the stream. + * + * @param v A pointer into the internal marshaling buffer representing the start of the blob. + * @param sz The number of bytes to read. + */ void readBlob(const Byte*& v, Container::size_type sz) { if(sz > 0) @@ -373,11 +645,20 @@ public: } } + /** + * Reads a data value from the stream. + * @param v Holds the extracted data. + */ template<typename T> void read(T& v) { StreamHelper<T, StreamableTraits<T>::helper>::read(this, v); } + /** + * Reads an optional data value from the stream. + * @param tag The tag ID. + * @param v Holds the extracted data (if any). + */ template<typename T> void read(Int tag, IceUtil::Optional<T>& v) { if(readOptional(tag, StreamOptionalHelper<T, @@ -401,6 +682,10 @@ public: #ifdef ICE_CPP11_MAPPING + /** + * Extracts a sequence of data values from the stream. + * @param v A pair of pointers representing the beginning and end of the sequence elements. + */ template<typename T> void read(std::pair<const T*, const T*>& v) { auto holder = new std::vector<T>; @@ -418,23 +703,35 @@ public: } } + /** + * Reads a list of mandatory data values. + */ template<typename T> void readAll(T& v) { read(v); } + /** + * Reads a list of mandatory data values. + */ template<typename T, typename... Te> void readAll(T& v, Te&... ve) { read(v); readAll(ve...); } + /** + * Reads a list of optional data values. + */ template<typename T> void readAll(std::initializer_list<int> tags, IceUtil::Optional<T>& v) { read(*(tags.begin() + tags.size() - 1), v); } + /** + * Reads a list of optional data values. + */ template<typename T, typename... Te> void readAll(std::initializer_list<int> tags, IceUtil::Optional<T>& v, IceUtil::Optional<Te>&... ve) { @@ -445,7 +742,13 @@ public: #endif - // Read type and tag for optionals + /** + * Determine if an optional value is available for reading. + * + * @param tag The tag associated with the value. + * @param expectedFormat The optional format for the value. + * @return True if the value is present, false otherwise. + */ bool readOptional(Int tag, OptionalFormat expectedFormat) { assert(_currentEncaps); @@ -459,7 +762,10 @@ public: } } - // Byte + /** + * Reads a byte from the stream. + * @param v The extracted byte. + */ void read(Byte& v) { if(i >= b.end()) @@ -468,19 +774,38 @@ public: } v = *i++; } - void read(std::vector<Byte>&); - void read(std::pair<const Byte*, const Byte*>&); + + /** + * Reads a sequence of bytes from the stream. + * @param v A vector to hold a copy of the bytes. + */ + void read(std::vector<Byte>& v); + + /** + * Reads a sequence of bytes from the stream. + * @param v A pair of pointers into the internal marshaling buffer representing the start and end of the + * sequence elements. + */ + void read(std::pair<const Byte*, const Byte*>& v); #ifndef ICE_CPP11_MAPPING - // This method is useful for generic stream helpers - void read(std::pair<const Byte*, const Byte*>& p, ::IceUtil::ScopedArray<Byte>& result) + /** + * Reads a sequence of bytes from the stream. + * @param v A pair of pointers into the internal marshaling buffer representing the start and end of the + * sequence elements. + * @param arr A scoped array. + */ + void read(std::pair<const Byte*, const Byte*>& v, ::IceUtil::ScopedArray<Byte>& arr) { - result.reset(); - read(p); + arr.reset(); + read(v); } #endif - // Bool + /** + * Reads a bool from the stream. + * @param v The extracted bool. + */ void read(bool& v) { if(i >= b.end()) @@ -489,24 +814,61 @@ public: } v = (0 != *i++); } - void read(std::vector<bool>&); + + /** + * Reads a sequence of boolean values from the stream. + * @param v A vector to hold a copy of the boolean values. + */ + void read(std::vector<bool>& v); #ifdef ICE_CPP11_MAPPING - void read(std::pair<const bool*, const bool*>&); + /** + * Reads a sequence of boolean values from the stream. + * @param v A pair of pointers into the internal marshaling buffer representing the start and end of the + * sequence elements. + */ + void read(std::pair<const bool*, const bool*>& v); #else - void read(std::pair<const bool*, const bool*>&, ::IceUtil::ScopedArray<bool>&); + /** + * Reads a sequence of boolean values from the stream. + * @param v A pair of pointers into the internal marshaling buffer representing the start and end of the + * sequence elements. + * @param arr A scoped array. + */ + void read(std::pair<const bool*, const bool*>& v, ::IceUtil::ScopedArray<bool>& arr); #endif - // Short - void read(Short&); - void read(std::vector<Short>&); + /** + * Reads a short from the stream. + * @param v The extracted short. + */ + void read(Short& v); + + /** + * Reads a sequence of shorts from the stream. + * @param v A vector to hold a copy of the short values. + */ + void read(std::vector<Short>& v); + #ifdef ICE_CPP11_MAPPING - void read(std::pair<const short*, const short*>&); + /** + * Reads a sequence of boolean values from the stream. + * @param v A pair of pointers representing the start and end of the sequence elements. + */ + void read(std::pair<const short*, const short*>& v); #else - void read(std::pair<const Short*, const Short*>&, ::IceUtil::ScopedArray<Short>&); + /** + * Reads a sequence of shorts from the stream. + * @param v A pair of pointers representing the start and end of the sequence elements. + * @param arr A scoped array. + */ + void read(std::pair<const Short*, const Short*>& v, ::IceUtil::ScopedArray<Short>& arr); #endif - // Int + /** + * Reads an int from the stream. + * @param v The extracted int. + */ void read(Int& v) // Inlined for performance reasons. { if(b.end() - i < static_cast<int>(sizeof(Int))) @@ -530,63 +892,175 @@ public: #endif } - void read(std::vector<Int>&); + /** + * Reads a sequence of ints from the stream. + * @param v A vector to hold a copy of the int values. + */ + void read(std::vector<Int>& v); + #ifdef ICE_CPP11_MAPPING - void read(std::pair<const int*, const int*>&); + /** + * Reads a sequence of ints from the stream. + * @param v A pair of pointers representing the start and end of the sequence elements. + */ + void read(std::pair<const int*, const int*>& v); #else - void read(std::pair<const Int*, const Int*>&, ::IceUtil::ScopedArray<Int>&); + /** + * Reads a sequence of ints from the stream. + * @param v A pair of pointers representing the start and end of the sequence elements. + * @param arr A scoped array. + */ + void read(std::pair<const Int*, const Int*>& v, ::IceUtil::ScopedArray<Int>& arr); #endif - // Long + /** + * Reads a long from the stream. + * @param v The extracted long. + */ + void read(Long& v); + + /** + * Reads a sequence of longs from the stream. + * @param v A vector to hold a copy of the long values. + */ + void read(std::vector<Long>& v); - void read(Long&); - void read(std::vector<Long>&); #ifdef ICE_CPP11_MAPPING - void read(std::pair<const long long*, const long long*>&); + /** + * Reads a sequence of longs from the stream. + * @param v A pair of pointers representing the start and end of the sequence elements. + */ + void read(std::pair<const long long*, const long long*>& v); #else - void read(std::pair<const Long*, const Long*>&, ::IceUtil::ScopedArray<Long>&); + /** + * Reads a sequence of longs from the stream. + * @param v A pair of pointers representing the start and end of the sequence elements. + * @param arr A scoped array. + */ + void read(std::pair<const Long*, const Long*>& v, ::IceUtil::ScopedArray<Long>& arr); #endif - // Float - void read(Float&); - void read(std::vector<Float>&); + /** + * Reads a float from the stream. + * @param v The extracted float. + */ + void read(Float& v); + + /** + * Reads a sequence of floats from the stream. + * @param v A vector to hold a copy of the float values. + */ + void read(std::vector<Float>& v); + #ifdef ICE_CPP11_MAPPING - void read(std::pair<const float*, const float*>&); + /** + * Reads a sequence of floats from the stream. + * @param v A pair of pointers representing the start and end of the sequence elements. + */ + void read(std::pair<const float*, const float*>& v); #else - void read(std::pair<const Float*, const Float*>&, ::IceUtil::ScopedArray<Float>&); + /** + * Reads a sequence of floats from the stream. + * @param v A pair of pointers representing the start and end of the sequence elements. + * @param arr A scoped array. + */ + void read(std::pair<const Float*, const Float*>& v, ::IceUtil::ScopedArray<Float>& arr); #endif - // Double - void read(Double&); - void read(std::vector<Double>&); + /** + * Reads a double from the stream. + * @param v The extracted double. + */ + void read(Double& v); + + /** + * Reads a sequence of doubles from the stream. + * @param v A vector to hold a copy of the double values. + */ + void read(std::vector<Double>& v); + #ifdef ICE_CPP11_MAPPING - void read(std::pair<const double*, const double*>&); + /** + * Reads a sequence of doubles from the stream. + * @param v A pair of pointers representing the start and end of the sequence elements. + */ + void read(std::pair<const double*, const double*>& v); #else - void read(std::pair<const Double*, const Double*>&, ::IceUtil::ScopedArray<Double>&); + /** + * Reads a sequence of doubles from the stream. + * @param v A pair of pointers representing the start and end of the sequence elements. + * @param arr A scoped array. + */ + void read(std::pair<const Double*, const Double*>& v, ::IceUtil::ScopedArray<Double>& arr); #endif - // String + /** + * Reads a string from the stream. + * @param v The extracted string. + * @param convert Determines whether the string is processed by the string converter, if one + * is installed. The default behavior is to convert strings. + */ void read(std::string& v, bool convert = true); #ifdef ICE_CPP11_MAPPING + /** + * Reads a string from the stream. + * @param vdata A pointer to the beginning of the string. + * @param vsize The number of bytes in the string. + * @param convert Determines whether the string is processed by the string converter, if one + * is installed. The default behavior is to convert strings. + */ void read(const char*& vdata, size_t& vsize, bool convert = true); #else // For custom strings, convert = false + /** + * Reads a string from the stream. String conversion is disabled. + * @param vdata A pointer to the beginning of the string. + * @param vsize The number of bytes in the string. + */ void read(const char*& vdata, size_t& vsize); // For custom strings, convert = true + /** + * Reads a string from the stream. String conversion is enabled. + * @param vdata A pointer to the beginning of the string. + * @param vsize The number of bytes in the string. + * @param holder Holds the string contents. + */ void read(const char*& vdata, size_t& vsize, std::string& holder); #endif - void read(std::vector<std::string>&, bool = true); - - void read(std::wstring&); - void read(std::vector<std::wstring>&); + /** + * Reads a sequence of strings from the stream. + * @param v The extracted string sequence. + * @param convert Determines whether strings are processed by the string converter, if one + * is installed. The default behavior is to convert the strings. + */ + void read(std::vector<std::string>& v, bool convert = true); + + /** + * Reads a wide string from the stream. + * @param v The extracted string. + */ + void read(std::wstring& v); + + /** + * Reads a sequence of wide strings from the stream. + * @param v The extracted sequence. + */ + void read(std::vector<std::wstring>& v); - // Proxy #ifdef ICE_CPP11_MAPPING + /** + * Reads a proxy from the stream. + * @return The proxy as the base ObjectPrx type. + */ std::shared_ptr<ObjectPrx> readProxy(); + /** + * Reads a typed proxy from the stream. + * @param v The proxy as a user-defined type. + */ template<typename T, typename ::std::enable_if<::std::is_base_of<ObjectPrx, T>::value>::type* = nullptr> void read(::std::shared_ptr<T>& v) { @@ -602,14 +1076,26 @@ public: } } #else - void read(ObjectPrx&); + /** + * Reads a proxy from the stream. + * @param v The proxy as the base ObjectPrx type. + */ + void read(ObjectPrx& v); + + /** + * Reads a typed proxy from the stream. + * @param v The proxy as a user-defined type. + */ template<typename T> void read(IceInternal::ProxyHandle<T>& v) { _readProxy(this, v); // Generated _readProxy method, necessary for forward declarations. } #endif - // Class + /** + * Reads a value (instance of a Slice class) from the stream. + * @param v The instance. + */ #ifdef ICE_CPP11_MAPPING // C++11 mapping template<typename T, typename ::std::enable_if<::std::is_base_of<Value, T>::value>::type* = nullptr> void read(::std::shared_ptr<T>& v) @@ -623,23 +1109,48 @@ public: } #endif + /** + * Reads a value (instance of a Slice class) from the stream. + * @param patchFunc The patch callback function. + * @param patchAddr Closure data passed to the callback. + */ void read(PatchFunc patchFunc, void* patchAddr) { initEncaps(); _currentEncaps->decoder->read(patchFunc, patchAddr); } - // Enum - Int readEnum(Int); - - // Exception - void throwException(ICE_IN(ICE_DELEGATE(UserExceptionFactory)) = ICE_NULLPTR); - - // Read/write/skip optionals - void skipOptional(OptionalFormat); + /** + * Reads an enumerator from the stream. + * @param maxValue The maximum enumerator value in the definition. + * @return The enumerator value. + */ + Int readEnum(Int maxValue); + + /** + * Extracts a user exception from the stream and throws it. + * @param factory If provided, this factory is given the first opportunity to instantiate + * the exception. If not provided, or if the factory does not throw an exception when invoked, + * the stream will attempt to instantiate the exception using static type information. + * @throws UserException The user exception that was unmarshaled. + */ + void throwException(ICE_IN(ICE_DELEGATE(UserExceptionFactory)) factory = ICE_NULLPTR); + + /** + * Skips one optional value with the given format. + * @param format The expected format of the optional, if present. + */ + void skipOptional(OptionalFormat format); + + /** + * Skips all remaining optional values. + */ void skipOptionals(); - // Skip bytes from the stream + /** + * Advances the current stream position by the given number of bytes. + * @param size The number of bytes to skip. + */ void skip(size_type size) { if(i + size > b.end()) @@ -648,6 +1159,10 @@ public: } i += size; } + + /** + * Reads a size at the current position and skips that number of bytes. + */ void skipSize() { Byte bt; @@ -658,22 +1173,32 @@ public: } } + /** + * Obtains the current position of the stream. + * @return The current position. + */ size_type pos() { return i - b.begin(); } + /** + * Sets a new position for the stream. + * @param p The new position. + */ void pos(size_type p) { i = b.begin() + p; } + /// \cond INTERNAL InputStream(IceInternal::Instance*, const EncodingVersion&); InputStream(IceInternal::Instance*, const EncodingVersion&, IceInternal::Buffer&, bool = false); void initialize(IceInternal::Instance*, const EncodingVersion&); bool readOptImpl(Int, OptionalFormat); + /// \endcond private: diff --git a/cpp/include/Ice/InterfaceByValue.h b/cpp/include/Ice/InterfaceByValue.h index 0ecbd872227..67cff4bc60a 100644 --- a/cpp/include/Ice/InterfaceByValue.h +++ b/cpp/include/Ice/InterfaceByValue.h @@ -19,20 +19,36 @@ namespace Ice { +/** + * Represents an instance of a Slice interface that was marshaled by value. + * \headerfile Ice/Ice.h + */ template<typename T> class InterfaceByValue : public ValueHelper<InterfaceByValue<T>, Value> { public: + /** + * Obtains the Slice type ID of this exception. + * @return The fully-scoped type ID. + */ virtual std::string ice_id() const { return T::ice_staticId(); } + /** + * Obtains the Slice type ID of this exception. + * @return The fully-scoped type ID. + */ static const std::string& ice_staticId() { return T::ice_staticId(); } + /** + * Returns an empty tuple. + * @return The empty tuple. + */ std::tuple<> ice_tuple() const { return std::tie(); diff --git a/cpp/include/Ice/LocalObject.h b/cpp/include/Ice/LocalObject.h index b3c47c225f1..256a8561582 100644 --- a/cpp/include/Ice/LocalObject.h +++ b/cpp/include/Ice/LocalObject.h @@ -22,6 +22,10 @@ namespace Ice { +/** + * Base class for local Slice classes and interfaces. + * \headerfile Ice/Ice.h + */ class ICE_API LocalObject : public virtual ::IceUtil::Shared { public: diff --git a/cpp/include/Ice/LoggerUtil.h b/cpp/include/Ice/LoggerUtil.h index a3cfddc49b2..b2d8c5fbe5c 100644 --- a/cpp/include/Ice/LoggerUtil.h +++ b/cpp/include/Ice/LoggerUtil.h @@ -18,19 +18,27 @@ namespace Ice { +/** + * Base class for logger output utility classes. + * \headerfile Ice/Ice.h + */ class ICE_API LoggerOutputBase : private IceUtil::noncopyable { public: + /** Obtains the collected output. */ std::string str() const; + /// \cond INTERNAL std::ostringstream& _stream(); // For internal use only. Don't use in your code. + /// \endcond private: std::ostringstream _os; }; +/// \cond INTERNAL ICE_API LoggerOutputBase& loggerInsert(LoggerOutputBase& out, const IceUtil::Exception& ex); template<typename T> @@ -92,7 +100,12 @@ operator<<(LoggerOutputBase& out, const ::std::exception& ex) } ICE_API LoggerOutputBase& operator<<(LoggerOutputBase&, std::ios_base& (*)(std::ios_base&)); +/// \endcond +/** + * Collects output and flushes it via a logger method. + * \headerfile Ice/Ice.h + */ template<class L, class LPtr, void (L::*output)(const std::string&)> class LoggerOutput : public LoggerOutputBase { @@ -106,6 +119,7 @@ public: flush(); } + /** Flushes the colleted output to the logger method. */ inline void flush() { std::string s = _stream().str(); @@ -122,10 +136,19 @@ private: LPtr _logger; }; +/** Flushes output to Logger::print. */ typedef LoggerOutput<Logger, LoggerPtr, &Logger::print> Print; + +/** Flushes output to Logger::warning. */ typedef LoggerOutput<Logger, LoggerPtr, &Logger::warning> Warning; + +/** Flushes output to Logger::error. */ typedef LoggerOutput<Logger, LoggerPtr, &Logger::error> Error; +/** + * Flushes output to Logger::trace. + * \headerfile Ice/Ice.h + */ class ICE_API Trace : public LoggerOutputBase { public: @@ -139,18 +162,26 @@ private: std::string _category; }; -// -// A special plug-in that installs a logger during a communicator's initialization. -// Both initialize and destroy are no-op. See Ice::InitializationData. -// +/** + * A special plug-in that installs a logger during a communicator's initialization. + * Both initialize and destroy are no-op. See Ice::InitializationData. + * \headerfile Ice/Ice.h + */ class ICE_API LoggerPlugin : public Ice::Plugin { public: - LoggerPlugin(const CommunicatorPtr& communicator, const LoggerPtr&); + /** + * Constructs the plug-in with a target communicator and a logger. + * @param communicator The communicator in which to install the logger. + * @param logger The logger to be installed. + */ + LoggerPlugin(const CommunicatorPtr& communicator, const LoggerPtr& logger); + /** This method is a no-op. */ virtual void initialize(); + /** This method is a no-op. */ virtual void destroy(); }; diff --git a/cpp/include/Ice/MetricsAdminI.h b/cpp/include/Ice/MetricsAdminI.h index 1ea7fe8d3eb..5973c61ebb4 100644 --- a/cpp/include/Ice/MetricsAdminI.h +++ b/cpp/include/Ice/MetricsAdminI.h @@ -36,8 +36,10 @@ namespace IceMX { +/// \cond INTERNAL class Updater; template<typename T> class MetricsHelperT; +/// \endcond } diff --git a/cpp/include/Ice/MetricsFunctional.h b/cpp/include/Ice/MetricsFunctional.h index 50bb1fe4d10..eb4f64b5e63 100644 --- a/cpp/include/Ice/MetricsFunctional.h +++ b/cpp/include/Ice/MetricsFunctional.h @@ -92,6 +92,7 @@ template<typename R> struct ReferenceWrapper<const R&> namespace IceMX { +/// \cond INTERNAL template<class T, typename Y, typename Func> struct ApplyOnMember { ApplyOnMember(Y T::*m, Func f) : func(f), member(m) @@ -156,6 +157,7 @@ template<class T, typename Y> ApplyOnMember<T, Y, Decrement<Y> > dec(Y T::*membe { return applyOnMember(member, Decrement<Y>()); } +/// \endcond } diff --git a/cpp/include/Ice/MetricsObserverI.h b/cpp/include/Ice/MetricsObserverI.h index 2a610ccb4c7..dfd7e333eec 100644 --- a/cpp/include/Ice/MetricsObserverI.h +++ b/cpp/include/Ice/MetricsObserverI.h @@ -26,6 +26,7 @@ namespace IceMX { +/// \cond INTERNAL template<typename T> class MetricsHelperT { public: @@ -652,6 +653,7 @@ private: }; typedef ObserverT<Metrics> ObserverI; +/// \endcond } diff --git a/cpp/include/Ice/NativePropertiesAdmin.h b/cpp/include/Ice/NativePropertiesAdmin.h index 15bcbb4f9e4..0d1596efc19 100644 --- a/cpp/include/Ice/NativePropertiesAdmin.h +++ b/cpp/include/Ice/NativePropertiesAdmin.h @@ -15,36 +15,47 @@ namespace Ice { -// -// An application can be notified when its configuration properties are modified -// via the Properties admin facet. The application must define a subclass of -// PropertiesAdminUpdateCallback and register it with the facet. The facet -// implements the class NativePropertiesAdmin, so the application needs to -// downcast the facet to this type in order to register the callback. -// -// For example: -// -// Ice::ObjectPtr obj = communicator->findAdminFacet("Properties"); -// assert(obj); // May be null if the facet is not enabled -// NativePropertiesAdminPtr facet = NativePropertiesAdminPtr::dynamicCast(obj); -// PropertiesAdminUpdateCallbackPtr myCallback = ...; -// facet->addUpdateCallback(myCallback); -// -// Ice ignores any exceptions raised by the callback. -// - #ifndef ICE_CPP11_MAPPING +/** + * An application can be notified when its configuration properties are modified + * via the Properties admin facet. The application must define a subclass of + * PropertiesAdminUpdateCallback and register it with the facet. The facet + * implements the class NativePropertiesAdmin, so the application needs to + * downcast the facet to this type in order to register the callback. + * + * For example: + * + * \code + * Ice::ObjectPtr obj = communicator->findAdminFacet("Properties"); + * assert(obj); // May be null if the facet is not enabled + * NativePropertiesAdminPtr facet = NativePropertiesAdminPtr::dynamicCast(obj); + * PropertiesAdminUpdateCallbackPtr myCallback = ...; + * facet->addUpdateCallback(myCallback); + * \endcode + * + * Ice ignores any exceptions raised by the callback. + * \headerfile Ice/Ice.h + */ class ICE_API PropertiesAdminUpdateCallback : public virtual Ice::LocalObject { public: virtual ~PropertiesAdminUpdateCallback(); - virtual void updated(const PropertyDict&) = 0; + /** + * Called when the communicator's properties have been updated. + * @param d A dictionary containing the properties that were added, changed or removed, + * with a removed property denoted by an entry whose value is an empty string. + */ + virtual void updated(const PropertyDict& d) = 0; }; typedef IceUtil::Handle<PropertiesAdminUpdateCallback> PropertiesAdminUpdateCallbackPtr; #endif +/** + * Base class for the Properties admin facet. + * \headerfile Ice/Ice.h + */ class ICE_API NativePropertiesAdmin #ifndef ICE_CPP11_MAPPING : public virtual IceUtil::Shared @@ -55,10 +66,22 @@ public: virtual ~NativePropertiesAdmin(); #ifdef ICE_CPP11_MAPPING - virtual std::function<void()> addUpdateCallback(std::function<void(const PropertyDict&)>) = 0; + /** + * Register an update callback that will be invoked when property updates occur. + * @param cb The callback. + */ + virtual std::function<void()> addUpdateCallback(std::function<void(const PropertyDict&)> cb) = 0; #else - virtual void addUpdateCallback(const PropertiesAdminUpdateCallbackPtr&) = 0; - virtual void removeUpdateCallback(const PropertiesAdminUpdateCallbackPtr&) = 0; + /** + * Register an update callback that will be invoked when property updates occur. + * @param cb The callback. + */ + virtual void addUpdateCallback(const PropertiesAdminUpdateCallbackPtr& cb) = 0; + /** + * Remove an update callback. + * @param cb The callback to be removed. + */ + virtual void removeUpdateCallback(const PropertiesAdminUpdateCallbackPtr& cb) = 0; #endif }; ICE_DEFINE_PTR(NativePropertiesAdminPtr, NativePropertiesAdmin); diff --git a/cpp/include/Ice/Object.h b/cpp/include/Ice/Object.h index b2320d76f0b..0cf099100e5 100644 --- a/cpp/include/Ice/Object.h +++ b/cpp/include/Ice/Object.h @@ -39,68 +39,161 @@ class GCVisitor; namespace Ice { +/** A default-initialized Current instance. */ ICE_API extern const Current emptyCurrent; #ifndef ICE_CPP11_MAPPING +/** + * Abstract callback class for an asynchronous dispatch interceptor. + * \headerfile Ice/Ice.h + */ class ICE_API DispatchInterceptorAsyncCallback : public virtual IceUtil::Shared { public: virtual ~DispatchInterceptorAsyncCallback(); + /** Called when the dispatch completes successfully. */ virtual bool response() = 0; - virtual bool exception(const std::exception&) = 0; + + /** + * Called when the dispatch fails with an exception. + * @param ex The exception that caused the failure. + */ + virtual bool exception(const std::exception& ex) = 0; + + /** + * Called when the dispatch fails with an unknown exception. + */ virtual bool exception() = 0; }; ICE_DEFINE_PTR(DispatchInterceptorAsyncCallbackPtr, DispatchInterceptorAsyncCallback); #endif +/** + * Encapsulates details about a dispatch request. + * \headerfile Ice/Ice.h + */ class ICE_API Request { public: virtual ~Request(); + + /** + * Obtains the Current object associated with the request. + * @return The Current object. + */ virtual const Current& getCurrent() = 0; }; #ifdef ICE_CPP11_MAPPING +/** + * The base class for servants. + * \headerfile Ice/Ice.h + */ class ICE_API Object { public: virtual ~Object() = default; - virtual bool ice_isA(std::string, const Current&) const; + /** + * Tests whether this object supports a specific Slice interface. + * @param s The type ID of the Slice interface to test against. + * @param current The Current object for the invocation. + * @return True if this object has the interface + * specified by s or derives from the interface + * specified by s. + */ + virtual bool ice_isA(std::string s, const Current& current) const; + /// \cond INTERNAL bool _iceD_ice_isA(IceInternal::Incoming&, const Current&); - - virtual void ice_ping(const Current&) const; + /// \endcond + + /** + * Tests whether this object can be reached. + * @param current The Current object for the invocation. + */ + virtual void ice_ping(const Current& current) const; + /// \cond INTERNAL bool _iceD_ice_ping(IceInternal::Incoming&, const Current&); - - virtual std::vector< std::string> ice_ids(const Current&) const; + /// \endcond + + /** + * Returns the Slice type IDs of the interfaces supported by this object. + * @param current The Current object for the invocation. + * @return The Slice type IDs of the interfaces supported by this object, in base-to-derived + * order. The first element of the returned array is always "::Ice::Object". + */ + virtual std::vector< std::string> ice_ids(const Current& current) const; + /// \cond INTERNAL bool _iceD_ice_ids(IceInternal::Incoming&, const Current&); - - virtual std::string ice_id(const Current&) const; + /// \endcond + + /** + * Returns the Slice type ID of the most-derived interface supported by this object. + * @param current The Current object for the invocation. + * @return The Slice type ID of the most-derived interface. + */ + virtual std::string ice_id(const Current& current) const; + /// \cond INTERNAL bool _iceD_ice_id(IceInternal::Incoming&, const Current&); + /// \endcond + /** + * Obtains the Slice type ID of this type. + * @return The return value is always "::Ice::Object". + */ static const std::string& ice_staticId(); - virtual bool ice_dispatch(Ice::Request&, - std::function<bool()> = nullptr, - std::function<bool(std::exception_ptr)> = nullptr); - + /** + * Dispatches an invocation to a servant. This method is used by dispatch interceptors to forward an invocation + * to a servant (or to another interceptor). + * @param request The details of the invocation. + * @param response A function that should return true if Ice should send the response to the client. A null + * value is equivalent to a function that returns true. + * @param error A function that should return true if Ice should send the exception to the client. A null + * value is equivalent to a function that returns true. + * @return True if the request completed synchronously, false if the request will be completed asynchronously. + * @throws UserException A user exception that propagates out of this method will be marshaled as the result. + */ + virtual bool ice_dispatch(Ice::Request& request, + std::function<bool()> response = nullptr, + std::function<bool(std::exception_ptr)> error = nullptr); + + /// \cond INTERNAL virtual bool _iceDispatch(IceInternal::Incoming&, const Current&); + /// \endcond + /** + * Holds the results of a call to ice_invoke. + */ struct Ice_invokeResult { + /** + * Indicates whether the invocation resulted in success (true) or a user exception (false). + */ bool returnValue; + + /** + * Holds an encapsulation of the encoded results. If returnValue is true, this contains the encoded + * out parameters. If returnValue is false, this contains the encoded user exception. + */ std::vector<::Ice::Byte> outParams; }; protected: + /// \cond INTERNAL static void _iceCheckMode(OperationMode, OperationMode); + /// \endcond }; #else +/** + * The base class for servants. + * \headerfile Ice/Ice.h + */ class ICE_API Object : public virtual IceUtil::Shared { public: @@ -108,37 +201,135 @@ public: virtual bool operator==(const Object&) const; virtual bool operator<(const Object&) const; - virtual bool ice_isA(const std::string&, const Current& = Ice::emptyCurrent) const; + /** + * Tests whether this object supports a specific Slice interface. + * @param s The type ID of the Slice interface to test against. + * @param current The Current object for the invocation. + * @return True if this object has the interface + * specified by s or derives from the interface + * specified by s. + */ + virtual bool ice_isA(const std::string& s, const Current& current = Ice::emptyCurrent) const; + /// \cond INTERNAL bool _iceD_ice_isA(IceInternal::Incoming&, const Current&); - - virtual void ice_ping(const Current& = Ice::emptyCurrent) const; + /// \endcond + + /** + * Tests whether this object can be reached. + * @param current The Current object for the invocation. + */ + virtual void ice_ping(const Current& current = Ice::emptyCurrent) const; + /// \cond INTERNAL bool _iceD_ice_ping(IceInternal::Incoming&, const Current&); - - virtual std::vector< std::string> ice_ids(const Current& = Ice::emptyCurrent) const; + /// \endcond + + /** + * Returns the Slice type IDs of the interfaces supported by this object. + * @param current The Current object for the invocation. + * @return The Slice type IDs of the interfaces supported by this object, in base-to-derived + * order. The first element of the returned array is always "::Ice::Object". + */ + virtual std::vector< std::string> ice_ids(const Current& current = Ice::emptyCurrent) const; + /// \cond INTERNAL bool _iceD_ice_ids(IceInternal::Incoming&, const Current&); - - virtual const std::string& ice_id(const Current& = Ice::emptyCurrent) const; + /// \endcond + + /** + * Returns the Slice type ID of the most-derived interface supported by this object. + * @param current The Current object for the invocation. + * @return The Slice type ID of the most-derived interface. + */ + virtual const std::string& ice_id(const Current& current = Ice::emptyCurrent) const; + /// \cond INTERNAL bool _iceD_ice_id(IceInternal::Incoming&, const Current&); - - virtual Int ice_operationAttributes(const std::string&) const; - + /// \endcond + + /** + * Returns the Freeze metadata attributes for an operation. + * + * @param operation The name of the operation. + * @return The least significant bit indicates whether the operation is a read + * or write operation. If the bit is set, the operation is a write operation. + * The expression ice_operationAttributes("op") & 0x1 is true if + * the operation has a <code>["freeze:write"]</code> metadata directive. + * <p> + * The second and third least significant bit indicate the transactional mode + * of the operation. The expression <code>ice_operationAttributes("op") & 0x6 >> 1</code> + * indicates the transactional mode as follows: + * <dl> + * <dt>0</dt> + * <dd><code>["freeze:read:supports"]</code></dd> + * <dt>1</dt> + * <dd><code>["freeze:read:mandatory"]</code> or <code>["freeze:write:mandatory"]</code></dd> + * <dt>2</dt> + * <dd><code>["freeze:read:required"]</code> or <code>["freeze:write:required"]</code></dd> + * <dt>3</dt> + * <dd><code>["freeze:read:never"]</code></dd> + * </dl> + * + * Refer to the Freeze manual for more information on the TransactionalEvictor. + */ + virtual Int ice_operationAttributes(const std::string& operation) const; + + /// \cond STREAM virtual void _iceWrite(Ice::OutputStream*) const; virtual void _iceRead(Ice::InputStream*); + /// \endcond + /// \cond INTERNAL virtual bool _iceGcVisit(IceInternal::GCVisitor&) { return false; } - virtual void ice_collectable(bool) { } - + /// \endcond + + /** + * Determines whether this object, and by extension the graph of all objects reachable from this object, + * are eligible for garbage collection when all external references to the graph have been released. + * @param b True if the object is eligible, false otherwise. + */ + virtual void ice_collectable(bool b) { } + + /** + * The Ice run time invokes this method prior to marshaling an object's data members. This allows a subclass + * to override this method in order to validate its data members. + */ virtual void ice_preMarshal(); + + /** + * The Ice run time invokes this method vafter unmarshaling an object's data members. This allows a + * subclass to override this method in order to perform additional initialization. + */ virtual void ice_postUnmarshal(); + /** + * Obtains the Slice type ID of this type. + * @return The return value is always "::Ice::Object". + */ static const std::string& ice_staticId(); + /** + * Returns a shallow copy of the object. + * @return The cloned object. + */ virtual ObjectPtr ice_clone() const; + /** + * Obtains the sliced data associated with this instance. + * @return The sliced data if the value has a preserved-slice base class and has been sliced during + * unmarshaling of the value, nil otherwise. + */ virtual SlicedDataPtr ice_getSlicedData() const; - virtual bool ice_dispatch(Ice::Request&, const DispatchInterceptorAsyncCallbackPtr& = 0); + /** + * Dispatches an invocation to a servant. This method is used by dispatch interceptors to forward an invocation + * to a servant (or to another interceptor). + * @param request The details of the invocation. + * @param cb The asynchronous callback object. + * @return True if the request completed synchronously, false if the request will be completed asynchronously. + * @throws UserException A user exception that propagates out of this method will be marshaled as the result. + */ + virtual bool ice_dispatch(Ice::Request& request, const DispatchInterceptorAsyncCallbackPtr& cb = 0); + /// \cond INTERNAL virtual bool _iceDispatch(IceInternal::Incoming&, const Current&); + /// \endcond protected: @@ -147,66 +338,166 @@ protected: protected: + /// \cond STREAM virtual void _iceWriteImpl(Ice::OutputStream*) const {} virtual void _iceReadImpl(Ice::InputStream*) {} + /// \endcond + /// \cond INTERNAL static void _iceCheckMode(OperationMode, OperationMode); + /// \endcond }; #endif +/** + * Base class for dynamic dispatch servants. A server application derives a concrete servant class + * from Blobject that implements the ice_invoke method. + * \headerfile Ice/Ice.h + */ class ICE_API Blobject : public virtual Object { public: - // - // Returns true if ok, false if user exception. - // - virtual bool ice_invoke(ICE_IN(std::vector<Byte>), std::vector<Byte>&, const Current&) = 0; - + /** + * Dispatch an incoming request. + * + * @param inEncaps An encapsulation containing the encoded in-parameters for the operation. + * @param outEncaps An encapsulation containing the encoded results for the operation. + * @param current The Current object for the invocation. + * @return True if the operation completed successfully, in which case outEncaps contains + * an encapsulation of the encoded results, or false if the operation raised a user exception, + * in which case outEncaps contains an encapsulation of the encoded user exception. + * @throws UserException A user exception can be raised directly and the + * run time will marshal it. + */ + virtual bool ice_invoke(ICE_IN(std::vector<Byte>) inEncaps, std::vector<Byte>& outEncaps, + const Current& current) = 0; + + /// \cond INTERNAL virtual bool _iceDispatch(IceInternal::Incoming&, const Current&); + /// \endcond }; +/** + * Base class for dynamic dispatch servants that uses the array mapping. A server application + * derives a concrete servant class from Blobject that implements the ice_invoke method. + * \headerfile Ice/Ice.h + */ class ICE_API BlobjectArray : public virtual Object { public: - // - // Returns true if ok, false if user exception. - // - virtual bool ice_invoke(ICE_IN(std::pair<const Byte*, const Byte*>), std::vector<Byte>&, const Current&) = 0; - + /** + * Dispatch an incoming request. + * + * @param inEncaps An encapsulation containing the encoded in-parameters for the operation. + * @param outEncaps An encapsulation containing the encoded results for the operation. + * @param current The Current object for the invocation. + * @return True if the operation completed successfully, in which case outEncaps contains + * an encapsulation of the encoded results, or false if the operation raised a user exception, + * in which case outEncaps contains an encapsulation of the encoded user exception. + * @throws UserException A user exception can be raised directly and the + * run time will marshal it. + */ + virtual bool ice_invoke(ICE_IN(std::pair<const Byte*, const Byte*>) inEncaps, std::vector<Byte>& outEncaps, + const Current& current) = 0; + + /// \cond INTERNAL virtual bool _iceDispatch(IceInternal::Incoming&, const Current&); + /// \endcond }; +/** + * Base class for asynchronous dynamic dispatch servants. A server application derives a concrete + * servant class from Blobject that implements the ice_invokeAsync method. + * \headerfile Ice/Ice.h + */ class ICE_API BlobjectAsync : public virtual Object { public: #ifdef ICE_CPP11_MAPPING - virtual void ice_invokeAsync(std::vector<Byte>, - std::function<void(bool, const std::vector<Byte>&)>, - std::function<void(std::exception_ptr)>, - const Current&) = 0; + /** + * Dispatch an incoming request asynchronously. + * + * @param inEncaps An encapsulation containing the encoded in-parameters for the operation. + * @param response A callback the implementation should invoke when the invocation completes + * successfully or with a user exception. See the description of Blobject::ice_invoke for + * the semantics. + * @param error A callback the implementation should invoke when the invocation completes + * with an exception. + * @param current The Current object for the invocation. + * @throws UserException A user exception can be raised directly and the + * run time will marshal it. + */ + virtual void ice_invokeAsync(std::vector<Byte> inEncaps, + std::function<void(bool, const std::vector<Byte>&)> response, + std::function<void(std::exception_ptr)> error, + const Current& current) = 0; #else - virtual void ice_invoke_async(const AMD_Object_ice_invokePtr&, const std::vector<Byte>&, const Current&) = 0; + /** + * Dispatch an incoming request asynchronously. + * + * @param cb The callback to invoke when the invocation completes. + * @param inEncaps An encapsulation containing the encoded in-parameters for the operation. + * @param current The Current object for the invocation. + * @throws UserException A user exception can be raised directly and the + * run time will marshal it. + */ + virtual void ice_invoke_async(const AMD_Object_ice_invokePtr& cb, const std::vector<Byte>& inEncaps, + const Current& current) = 0; #endif + + /// \cond INTERNAL virtual bool _iceDispatch(IceInternal::Incoming&, const Current&); + /// \endcond }; +/** + * Base class for asynchronous dynamic dispatch servants that uses the array mapping. A server application + * derives a concrete servant class from Blobject that implements the ice_invokeAsync method. + * \headerfile Ice/Ice.h + */ class ICE_API BlobjectArrayAsync : public virtual Object { public: #ifdef ICE_CPP11_MAPPING - virtual void ice_invokeAsync(std::pair<const Byte*, const Byte*>, - std::function<void(bool, const std::pair<const Byte*, const Byte*>&)>, - std::function<void(std::exception_ptr)>, - const Current&) = 0; + /** + * Dispatch an incoming request asynchronously. + * + * @param inEncaps An encapsulation containing the encoded in-parameters for the operation. + * @param response A callback the implementation should invoke when the invocation completes + * successfully or with a user exception. See the description of Blobject::ice_invoke for + * the semantics. + * @param error A callback the implementation should invoke when the invocation completes + * with an exception. + * @param current The Current object for the invocation. + * @throws UserException A user exception can be raised directly and the + * run time will marshal it. + */ + virtual void ice_invokeAsync(std::pair<const Byte*, const Byte*> inEncaps, + std::function<void(bool, const std::pair<const Byte*, const Byte*>&)> response, + std::function<void(std::exception_ptr)> error, + const Current& current) = 0; #else - virtual void ice_invoke_async(const AMD_Object_ice_invokePtr&, const std::pair<const Byte*, const Byte*>&, - const Current&) = 0; + /** + * Dispatch an incoming request asynchronously. + * + * @param cb The callback to invoke when the invocation completes. + * @param inEncaps An encapsulation containing the encoded in-parameters for the operation. + * @param current The Current object for the invocation. + * @throws UserException A user exception can be raised directly and the + * run time will marshal it. + */ + virtual void ice_invoke_async(const AMD_Object_ice_invokePtr& cb, + const std::pair<const Byte*, const Byte*>& inEncaps, + const Current& current) = 0; #endif + + /// \cond INTERNAL virtual bool _iceDispatch(IceInternal::Incoming&, const Current&); + /// \endcond }; } diff --git a/cpp/include/Ice/ObjectF.h b/cpp/include/Ice/ObjectF.h index cd233caeb99..3539448ac2d 100644 --- a/cpp/include/Ice/ObjectF.h +++ b/cpp/include/Ice/ObjectF.h @@ -18,12 +18,16 @@ namespace Ice class Object; #ifdef ICE_CPP11_MAPPING +/// \cond INTERNAL using ObjectPtr = ::std::shared_ptr<Object>; +/// \endcond #else ICE_API Object* upCast(Object*); typedef IceInternal::Handle<Object> ObjectPtr; typedef ObjectPtr ValuePtr; +/// \cond INTERNAL ICE_API void _icePatchObjectPtr(ObjectPtr&, const ObjectPtr&); +/// \endcond #endif } diff --git a/cpp/include/Ice/Optional.h b/cpp/include/Ice/Optional.h index f96405917ea..12e15508e64 100644 --- a/cpp/include/Ice/Optional.h +++ b/cpp/include/Ice/Optional.h @@ -1041,8 +1041,13 @@ namespace std # undef TR2_OPTIONAL_REQUIRES # undef TR2_OPTIONAL_ASSERTED_EXPRESSION -namespace Ice{ +namespace Ice +{ +/** + * Ice::optional is a placeholder for std::optional. + * Refer to http://en.cppreference.com/w/cpp/utility/optional for more information. + */ template<class T> using optional = std::experimental::Ice::optional<T>; using std::experimental::Ice::operator==; @@ -1052,25 +1057,36 @@ using std::experimental::Ice::operator<=; using std::experimental::Ice::operator>; using std::experimental::Ice::operator>=; +/** Creates an optional object. */ using std::experimental::Ice::make_optional; +/** Exchanges the state of an optional object with another one. */ using std::experimental::Ice::swap; +/** This type indicates that no value is provided. */ using nullopt_t = std::experimental::Ice::nullopt_t; +/** An instance of nullopt_t used as a marker value to indicate that no value is provided. */ using std::experimental::Ice::nullopt; +/** Raised when accessing an optional that doesn't contain a value. */ using bad_optional_access = std::experimental::Ice::bad_optional_access; +/** This type indicates that an optional value should be constructed in place. */ using in_place_t = std::experimental::Ice::in_place_t; +/** An instance of in_place_t that indicates that an optional value should be constructed in place. */ using std::experimental::Ice::in_place; } -// -// For compatibility with the Ice C++98 mapping, do not use in new code: -// -namespace IceUtil{ +namespace IceUtil +{ +/** + * For compatibility with the Ice C++98 mapping, do not use in new code: + */ template<class T> using Optional = std::experimental::Ice::optional<T>; +/** + * For compatibility with the Ice C++98 mapping, do not use in new code: + */ constexpr std::experimental::Ice::nullopt_t None{std::experimental::Ice::nullopt_t::init()}; } diff --git a/cpp/include/Ice/OutgoingAsync.h b/cpp/include/Ice/OutgoingAsync.h index b115581e4e9..2cf68ab0698 100644 --- a/cpp/include/Ice/OutgoingAsync.h +++ b/cpp/include/Ice/OutgoingAsync.h @@ -805,6 +805,13 @@ namespace Ice typedef IceUtil::Handle< ::IceInternal::GenericCallbackBase> CallbackPtr; +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param cb The completion callback. + * @param sentcb The sent callback. + * @return A callback object that can be passed to an asynchronous invocation. + */ template<class T> CallbackPtr newCallback(const IceUtil::Handle<T>& instance, void (T::*cb)(const AsyncResultPtr&), @@ -813,6 +820,13 @@ newCallback(const IceUtil::Handle<T>& instance, return new ::IceInternal::AsyncCallback<T>(instance, cb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param cb The completion callback. + * @param sentcb The sent callback. + * @return A callback object that can be passed to an asynchronous invocation. + */ template<class T> CallbackPtr newCallback(T* instance, void (T::*cb)(const AsyncResultPtr&), diff --git a/cpp/include/Ice/OutputStream.h b/cpp/include/Ice/OutputStream.h index 3b849bd5314..6937035045a 100644 --- a/cpp/include/Ice/OutputStream.h +++ b/cpp/include/Ice/OutputStream.h @@ -25,35 +25,45 @@ namespace Ice class UserException; +/** + * Interface for output streams used to create a sequence of bytes from Slice types. + * \headerfile Ice/Ice.h + */ class ICE_API OutputStream : public IceInternal::Buffer { public: typedef size_t size_type; - // - // Constructing an OutputStream without providing a communicator means the stream will - // use the default encoding version, the default format for class encoding, and the - // process string converters. You can supply a communicator later by calling initialize(). - // + /** + * Constructs an OutputStream using the latest encoding version, the default format for + * class encoding, and the process string converters. You can supply a communicator later + * by calling initialize(). + */ OutputStream(); - // - // This constructor uses the communicator's default encoding version. - // - OutputStream(const CommunicatorPtr&); - - // - // This constructor uses the given communicator and encoding version. - // - OutputStream(const CommunicatorPtr&, const EncodingVersion&); - - // - // This constructor uses the given communicator and encoding version. The byte pair denotes - // application-supplied memory that the stream uses as its initial marshaling buffer. The - // stream will reallocate if the size of the marshaled data exceeds the application's buffer. - // - OutputStream(const CommunicatorPtr&, const EncodingVersion&, const std::pair<const Byte*, const Byte*>&); + /** + * Constructs a stream using the communicator's default encoding version. + * @param communicator The communicator to use for marshaling tasks. + */ + OutputStream(const CommunicatorPtr& communicator); + + /** + * Constructs a stream using the given communicator and encoding version. + * @param communicator The communicator to use for marshaling tasks. + * @param version The encoding version used to encode the data. + */ + OutputStream(const CommunicatorPtr& communicator, const EncodingVersion& version); + + /** + * Constructs a stream using the given communicator and encoding version. + * @param communicator The communicator to use for marshaling tasks. + * @param version The encoding version used to encode the data. + * @param bytes Application-supplied memory that the stream uses as its initial marshaling buffer. The + * stream will reallocate if the size of the marshaled data exceeds the application's buffer. + */ + OutputStream(const CommunicatorPtr& communicator, const EncodingVersion& version, + const std::pair<const Byte*, const Byte*>& bytes); ~OutputStream() { @@ -65,63 +75,128 @@ public: } } - // - // Initializes the stream to use the communicator's default encoding version and class - // encoding format - // - void initialize(const CommunicatorPtr&); - - // - // Initializes the stream to use the given encoding version and the communicator's - // default class encoding format and string converters. - // - void initialize(const CommunicatorPtr&, const EncodingVersion&); - + /** + * Initializes the stream to use the communicator's default encoding version, class + * encoding format and string converters. Use this method if you originally constructed + * the stream without a communicator. + * @param communicator The communicator to use for marshaling tasks. + */ + void initialize(const CommunicatorPtr& communicator); + + /** + * Initializes the stream to use the given encoding version and the communicator's + * default class encoding format and string converters. Use this method if you + * originally constructed the stream without a communicator. + * @param communicator The communicator to use for marshaling tasks. + * @param version The encoding version used to encode the data. + */ + void initialize(const CommunicatorPtr& communicator, const EncodingVersion& version); + + /** + * Releases any data retained by encapsulations. + */ void clear(); + /// \cond INTERNAL // // Must return Instance*, because we don't hold an InstancePtr for // optimization reasons (see comments below). // IceInternal::Instance* instance() const { return _instance; } // Inlined for performance reasons. - - void setFormat(FormatType); - + /// \endcond + + /** + * Sets the class encoding format. + * @param format The encoding format. + */ + void setFormat(FormatType format); + + /** + * Obtains the closure data associated with this stream. + * @return The data as a void pointer. + */ void* getClosure() const; - void* setClosure(void*); - void swap(OutputStream&); + /** + * Associates closure data with this stream. + * @param p The data as a void pointer. + * @return The previous closure data, or nil. + */ + void* setClosure(void* p); + + /** + * Swaps the contents of one stream with another. + * + * @param other The other stream. + */ + void swap(OutputStream& other); + + /// \cond INTERNAL void resetEncapsulation(); + /// \endcond + /** + * Resizes the stream to a new size. + * + * @param sz The new size. + */ void resize(Container::size_type sz) { b.resize(sz); } + /** + * Marks the start of a class instance. + * @param data Contains the marshaled form of unknown slices from this instance. If not nil, + * these slices will be marshaled with the instance. + */ void startValue(const SlicedDataPtr& data) { assert(_currentEncaps && _currentEncaps->encoder); _currentEncaps->encoder->startInstance(ValueSlice, data); } + + /** + * Marks the end of a class instance. + */ void endValue() { assert(_currentEncaps && _currentEncaps->encoder); _currentEncaps->encoder->endInstance(); } + /** + * Marks the start of an exception instance. + * @param data Contains the marshaled form of unknown slices from this instance. If not nil, + * these slices will be marshaled with the instance. + */ void startException(const SlicedDataPtr& data) { assert(_currentEncaps && _currentEncaps->encoder); _currentEncaps->encoder->startInstance(ExceptionSlice, data); } + + /** + * Marks the end of an exception instance. + */ void endException() { assert(_currentEncaps && _currentEncaps->encoder); _currentEncaps->encoder->endInstance(); } + /** + * Writes the start of an encapsulation using the default encoding version and + * class encoding format. + */ void startEncapsulation(); + /** + * Writes the start of an encapsulation using the given encoding version and + * class encoding format. + * @param encoding The encoding version to use for the encapsulation. + * @param format The class format to use for the encapsulation. + */ void startEncapsulation(const EncodingVersion& encoding, FormatType format) { IceInternal::checkSupportedEncoding(encoding); @@ -143,6 +218,10 @@ public: write(Int(0)); // Placeholder for the encapsulation length. write(_currentEncaps->encoding); } + + /** + * Ends the current encapsulation. + */ void endEncapsulation() { assert(_currentEncaps); @@ -163,12 +242,22 @@ public: } } + /** + * Writes an empty encapsulation using the given encoding version. + * @param encoding The encoding version to use for the encapsulation. + */ void writeEmptyEncapsulation(const EncodingVersion& encoding) { IceInternal::checkSupportedEncoding(encoding); write(Int(6)); // Size write(encoding); } + + /** + * Copies the marshaled form of an encapsulation to the buffer. + * @param v The start of the buffer. + * @param sz The number of bytes to copy. + */ void writeEncapsulation(const Byte* v, Int sz) { if(sz < 6) @@ -181,24 +270,50 @@ public: memcpy(&b[position], &v[0], sz); } + /** + * Determines the current encoding version. + * + * @return The encoding version. + */ const EncodingVersion& getEncoding() const { return _currentEncaps ? _currentEncaps->encoding : _encoding; } + /** + * Writes the start of a value or exception slice. + * + * @param typeId The Slice type ID for this slice. + * @param compactId The compact ID corresponding to the type, or -1 if no compact ID is used. + * @param last True if this is the last slice, false otherwise. + */ void startSlice(const std::string& typeId, int compactId, bool last) { assert(_currentEncaps && _currentEncaps->encoder); _currentEncaps->encoder->startSlice(typeId, compactId, last); } + + /** + * Marks the end of a value or exception slice. + */ void endSlice() { assert(_currentEncaps && _currentEncaps->encoder); _currentEncaps->encoder->endSlice(); } + /** + * Encodes the state of class instances whose insertion was delayed during a previous + * call to write. This member function must only be called once. For backward + * compatibility with encoding version 1.0, this function must only be called when + * non-optional data members or parameters use class types. + */ void writePendingValues(); + /** + * Writes a size value. + * @param v A non-negative integer. + */ void writeSize(Int v) // Inlined for performance reasons. { assert(v >= 0); @@ -212,6 +327,13 @@ public: write(static_cast<Byte>(v)); } } + + /** + * Replaces a size value at the given destination in the stream. This function + * does not change the stream's current position. + * @param v A non-negative integer representing the size. + * @param dest The buffer destination for the size. + */ void rewriteSize(Int v, Container::iterator dest) { assert(v >= 0); @@ -226,6 +348,12 @@ public: } } + /** + * Writes a placeholder value for the size and returns the starting position of the + * size value; after writing the data, call endSize to patch the placeholder with + * the actual size at the given position. + * @return The starting position of the size value. + */ size_type startSize() { size_type position = b.size(); @@ -233,13 +361,27 @@ public: return position; } + /** + * Updates the size value at the given position to contain a size based on the + * stream's current position. + * @param position The starting position of the size value as returned by startSize. + */ void endSize(size_type position) { rewrite(static_cast<Int>(b.size() - position) - 4, position); } - void writeBlob(const std::vector<Byte>&); - + /** + * Copies the specified blob of bytes to the stream without modification. + * @param v The bytes to be copied. + */ + void writeBlob(const std::vector<Byte>& v); + + /** + * Copies the specified blob of bytes to the stream without modification. + * @param v The start of the buffer to be copied. + * @param sz The number of bytes to be copied. + */ void writeBlob(const Byte* v, Container::size_type sz) { if(sz > 0) @@ -250,11 +392,20 @@ public: } } + /** + * Writes a data value to the stream. + * @param v The data value to be written. + */ template<typename T> void write(const T& v) { StreamHelper<T, StreamableTraits<T>::helper>::write(this, v); } + /** + * Writes an optional data value to the stream. + * @param tag The tag ID. + * @param v The data value to be written (if any). + */ template<typename T> void write(Int tag, const IceUtil::Optional<T>& v) { if(!v) @@ -272,9 +423,10 @@ public: } } - // - // Template functions for sequences and custom sequences - // + /** + * Writes a sequence of data values to the stream. + * @param v The sequence to be written. + */ template<typename T> void write(const std::vector<T>& v) { if(v.empty()) @@ -287,6 +439,11 @@ public: } } + /** + * Writes a sequence of data values to the stream. + * @param begin The beginning of the sequence. + * @param end The end of the sequence. + */ template<typename T> void write(const T* begin, const T* end) { writeSize(static_cast<Int>(end - begin)); @@ -298,17 +455,26 @@ public: #ifdef ICE_CPP11_MAPPING + /** + * Writes a list of mandatory data values. + */ template<typename T> void writeAll(const T& v) { write(v); } + /** + * Writes a list of mandatory data values. + */ template<typename T, typename... Te> void writeAll(const T& v, const Te&... ve) { write(v); writeAll(ve...); } + /** + * Writes a list of mandatory data values. + */ template<size_t I = 0, typename... Te> typename std::enable_if<I == sizeof...(Te), void>::type writeAll(std::tuple<Te...>) @@ -316,6 +482,9 @@ public: // Do nothing. Either tuple is empty or we are at the end. } + /** + * Writes a list of mandatory data values. + */ template<size_t I = 0, typename... Te> typename std::enable_if<I < sizeof...(Te), void>::type writeAll(std::tuple<Te...> tuple) @@ -324,12 +493,18 @@ public: writeAll<I + 1, Te...>(tuple); } + /** + * Writes a list of optional data values. + */ template<typename T> void writeAll(std::initializer_list<int> tags, const IceUtil::Optional<T>& v) { write(*(tags.begin() + tags.size() - 1), v); } + /** + * Writes a list of optional data values. + */ template<typename T, typename... Te> void writeAll(std::initializer_list<int> tags, const IceUtil::Optional<T>& v, const IceUtil::Optional<Te>&... ve) { @@ -340,7 +515,13 @@ public: #endif - // Write type and tag for optionals + /** + * Writes the tag and format of an optional value. + * @param tag The optional tag ID. + * @param format The optional format. + * @return True if the current encoding version supports optional values, false otherwise. + * If true, the data associated with the optional value must be written next. + */ bool writeOptional(Int tag, OptionalFormat format) { assert(_currentEncaps); @@ -354,32 +535,74 @@ public: } } - // Byte + /** + * Writes a byte to the stream. + * @param v The byte to write. + */ void write(Byte v) { b.push_back(v); } - void write(const Byte*, const Byte*); - // Bool + /** + * Writes a byte sequence to the stream. + * @param start The beginning of the sequence. + * @param end The end of the sequence. + */ + void write(const Byte* start, const Byte* end); + + /** + * Writes a boolean to the stream. + * @param v The boolean to write. + */ void write(bool v) { b.push_back(static_cast<Byte>(v)); } - void write(const std::vector<bool>&); - void write(const bool*, const bool*); - - // Short - void write(Short); - void write(const Short*, const Short*); - // Int + /** + * Writes a byte sequence to the stream. + * @param v The sequence to be written. + */ + void write(const std::vector<bool>& v); + + /** + * Writes a byte sequence to the stream. + * @param begin The beginning of the sequence. + * @param end The end of the sequence. + */ + void write(const bool* begin, const bool* end); + + /** + * Writes a short to the stream. + * @param v The short to write. + */ + void write(Short v); + + /** + * Writes a short sequence to the stream. + * @param begin The beginning of the sequence. + * @param end The end of the sequence. + */ + void write(const Short* begin, const Short* end); + + /** + * Writes an int to the stream. + * @param v The int to write. + */ void write(Int v) // Inlined for performance reasons. { Container::size_type position = b.size(); resize(position + sizeof(Int)); write(v, &b[position]); } + + /** + * Overwrites a 32-bit integer value at the given destination in the stream. + * This function does not change the stream's current position. + * @param v The integer value to be written. + * @param dest The buffer destination for the integer value. + */ void write(Int v, Container::iterator dest) { #ifdef ICE_BIG_ENDIAN @@ -397,21 +620,58 @@ public: #endif } - void write(const Int*, const Int*); - - // Long - void write(Long); - void write(const Long*, const Long*); - - // Float - void write(Float); - void write(const Float*, const Float*); - - // Double - void write(Double); - void write(const Double*, const Double*); - - // String + /** + * Writes an int sequence to the stream. + * @param begin The beginning of the sequence. + * @param end The end of the sequence. + */ + void write(const Int* begin, const Int* end); + + /** + * Writes a long to the stream. + * @param v The long to write. + */ + void write(Long v); + + /** + * Writes a long sequence to the stream. + * @param begin The beginning of the sequence. + * @param end The end of the sequence. + */ + void write(const Long* begin, const Long* end); + + /** + * Writes a float to the stream. + * @param v The float to write. + */ + void write(Float v); + + /** + * Writes a float sequence to the stream. + * @param begin The beginning of the sequence. + * @param end The end of the sequence. + */ + void write(const Float* begin, const Float* end); + + /** + * Writes a double to the stream. + * @param v The double to write. + */ + void write(Double v); + + /** + * Writes a double sequence to the stream. + * @param begin The beginning of the sequence. + * @param end The end of the sequence. + */ + void write(const Double* begin, const Double* end); + + /** + * Writes a string to the stream. + * @param v The string to write. + * @param convert Determines whether the string is processed by the narrow string converter, + * if one has been configured. The default behavior is to convert the strings. + */ void write(const std::string& v, bool convert = true) { Int sz = static_cast<Int>(v.size()); @@ -431,7 +691,13 @@ public: } } - // for custom strings + /** + * Writes a string to the stream. + * @param vdata The string to write. + * @param vsize The size of the string. + * @param convert Determines whether the string is processed by the narrow string converter, + * if one has been configured. The default behavior is to convert the strings. + */ void write(const char* vdata, size_t vsize, bool convert = true) { Int sz = static_cast<Int>(vsize); @@ -451,36 +717,77 @@ public: } } - // Null-terminated C string + /** + * Writes a string to the stream. + * @param vdata The null-terminated string to write. + * @param convert Determines whether the string is processed by the narrow string converter, + * if one has been configured. The default behavior is to convert the strings. + */ void write(const char* vdata, bool convert = true) { write(vdata, strlen(vdata), convert); } - void write(const std::string*, const std::string*, bool = true); - + /** + * Writes a string sequence to the stream. + * @param begin The beginning of the sequence. + * @param end The end of the sequence. + * @param convert Determines whether the string is processed by the narrow string converter, + * if one has been configured. The default behavior is to convert the strings. + */ + void write(const std::string* begin, const std::string* end, bool convert = true); + + /** + * Writes a wide string to the stream. + * @param v The wide string to write. + */ void write(const std::wstring& v); - void write(const std::wstring*, const std::wstring*); - // Proxy -#ifdef ICE_CPP11_MAPPING - void writeProxy(const ::std::shared_ptr<ObjectPrx>&); + /** + * Writes a wide string sequence to the stream. + * @param begin The beginning of the sequence. + * @param end The end of the sequence. + */ + void write(const std::wstring* begin, const std::wstring* end); +#ifdef ICE_CPP11_MAPPING + /** + * Writes a proxy to the stream. + * @param v The proxy to be written. + */ + void writeProxy(const ::std::shared_ptr<ObjectPrx>& v); + + /** + * Writes a proxy to the stream. + * @param v The proxy to be written. + */ template<typename T, typename ::std::enable_if<::std::is_base_of<ObjectPrx, T>::value>::type* = nullptr> void write(const ::std::shared_ptr<T>& v) { writeProxy(::std::static_pointer_cast<ObjectPrx>(v)); } #else - void write(const ObjectPrx&); + /** + * Writes a proxy to the stream. + * @param v The proxy to be written. + */ + void write(const ObjectPrx& v); + + /** + * Writes a proxy to the stream. + * @param v The proxy to be written. + */ template<typename T> void write(const IceInternal::ProxyHandle<T>& v) { write(ObjectPrx(upCast(v.get()))); } #endif - // Class #ifdef ICE_CPP11_MAPPING // C++11 mapping + /** + * Writes a value instance to the stream. + * @param v The value to be written. + */ template<typename T, typename ::std::enable_if<::std::is_base_of<Value, T>::value>::type* = nullptr> void write(const ::std::shared_ptr<T>& v) { @@ -488,42 +795,79 @@ public: _currentEncaps->encoder->write(v); } #else // C++98 mapping + /** + * Writes a value instance to the stream. + * @param v The value to be written. + */ void write(const ObjectPtr& v) { initEncaps(); _currentEncaps->encoder->write(v); } + + /** + * Writes a value instance to the stream. + * @param v The value to be written. + */ template<typename T> void write(const IceInternal::Handle<T>& v) { write(ObjectPtr(upCast(v.get()))); } #endif - // Enum - void writeEnum(Int, Int); - - // Exception - void writeException(const UserException&); - + /** + * Writes an enumerator to the stream. + * @param v The enumerator to be written. + * @param maxValue The maximum value of all enumerators in this enumeration. + */ + void writeEnum(Int v, Int maxValue); + + /** + * Writes an exception to the stream. + * @param v The exception to be written. + */ + void writeException(const UserException& v); + + /** + * Obtains the current position of the stream. + * @return The current position. + */ size_type pos() { return b.size(); } - void rewrite(Int value, size_type p) + /** + * Overwrite a 32-bit integer value at the given position in the stream. + * This function does not change the stream's current position. + * @param v The value to be written. + * @param pos The buffer position for the value. + */ + void rewrite(Int v, size_type pos) { - write(value, b.begin() + p); + write(v, b.begin() + pos); } - OutputStream(IceInternal::Instance*, const EncodingVersion&); + /** + * Indicates that marshaling is complete. This function must only be called once. + * @param v Filled with a copy of the encoded data. + */ + void finished(std::vector<Byte>& v); + + /** + * Indicates that marshaling is complete. This function must only be called once. + * @return A pair of pointers into the internal marshaling buffer. These pointers are + * valid for the lifetime of the stream. + */ + std::pair<const Byte*, const Byte*> finished(); + /// \cond INTERNAL + OutputStream(IceInternal::Instance*, const EncodingVersion&); void initialize(IceInternal::Instance*, const EncodingVersion&); - void finished(std::vector<Byte>&); - std::pair<const Byte*, const Byte*> finished(); - // Optionals bool writeOptImpl(Int, OptionalFormat); + /// \endcond private: diff --git a/cpp/include/Ice/Protocol.h b/cpp/include/Ice/Protocol.h index 2d1b87580ad..b4f3630736a 100644 --- a/cpp/include/Ice/Protocol.h +++ b/cpp/include/Ice/Protocol.h @@ -116,34 +116,64 @@ const ::Ice::Byte FLAG_IS_LAST_SLICE = (1<<5); namespace Ice { +/** Identifies protocol version 1.0. */ ICE_API extern const ProtocolVersion Protocol_1_0; +/** Identifies encoding version 1.0. */ ICE_API extern const EncodingVersion Encoding_1_0; + +/** Identifies encoding version 1.1. */ ICE_API extern const EncodingVersion Encoding_1_1; +/** Identifies the latest protocol version. */ ICE_API extern const ProtocolVersion currentProtocol; + +/** Identifies the latest protocol encoding version. */ ICE_API extern const EncodingVersion currentProtocolEncoding; +/** Identifies the latest encoding version. */ ICE_API extern const EncodingVersion currentEncoding; +/** + * Converts a protocol version into a string. + * @param v The protocol version. + * @return A string representing the protocol version. + */ inline ::std::string protocolVersionToString(const Ice::ProtocolVersion& v) { return IceInternal::versionToString<ProtocolVersion>(v); } +/** + * Converts a string into a protocol version. + * @param v The string containing a stringified protocol version. + * @return The protocol version. + * @throws VersionParseException If the given string is not in the X.Y format. + */ inline ::Ice::ProtocolVersion stringToProtocolVersion(const ::std::string& v) { return IceInternal::stringToVersion<ProtocolVersion>(v); } +/** + * Converts an encoding version into a string. + * @param v The encoding version. + * @return A string representing the encoding version. + */ inline ::std::string encodingVersionToString(const Ice::EncodingVersion& v) { return IceInternal::versionToString<EncodingVersion>(v); } +/** + * Converts a string into an encoding version. + * @param v The string containing a stringified encoding version. + * @return The encoding version. + * @throws VersionParseException If the given string is not in the X.Y format. + */ inline ::Ice::EncodingVersion stringToEncodingVersion(const ::std::string& v) { diff --git a/cpp/include/Ice/Proxy.h b/cpp/include/Ice/Proxy.h index ae42ca8d382..58287e0aecc 100644 --- a/cpp/include/Ice/Proxy.h +++ b/cpp/include/Ice/Proxy.h @@ -34,6 +34,7 @@ namespace Ice { +/** Marker value used to indicate that no explicit context was passed to a proxy invocation. */ ICE_API extern const Context noExplicitContext; } @@ -49,6 +50,7 @@ namespace IceProxy namespace Ice { +/** Marker value used to indicate that no explicit context was passed to a proxy invocation. */ ICE_API extern const ::Ice::Context noExplicitContext; } @@ -291,14 +293,22 @@ namespace Ice { class RouterPrx; +/// \cond INTERNAL using RouterPrxPtr = ::std::shared_ptr<::Ice::RouterPrx>; +/// \endcond class LocatorPrx; +/// \cond INTERNAL using LocatorPrxPtr = ::std::shared_ptr<::Ice::LocatorPrx>; +/// \endcond class LocalException; class OutputStream; +/** + * Base class of all object proxies. + * \headerfile Ice/Ice.h + */ class ICE_API ObjectPrx : public ::std::enable_shared_from_this<ObjectPrx> { public: @@ -308,16 +318,40 @@ public: friend ICE_API bool operator<(const ObjectPrx&, const ObjectPrx&); friend ICE_API bool operator==(const ObjectPrx&, const ObjectPrx&); + /** + * Obtains the communicator that created this proxy. + * @return The communicator that created this proxy. + */ ::std::shared_ptr<::Ice::Communicator> ice_getCommunicator() const; + /** + * Obtains a stringified version of this proxy. + * @return A stringified proxy. + */ ::std::string ice_toString() const; + /** + * Tests whether this object supports a specific Slice interface. + * @param typeId The type ID of the Slice interface to test against. + * @param context The context map for the invocation. + * @return true if the target object has the interface + * specified by id or derives from the interface specified by id. + */ bool ice_isA(const ::std::string& typeId, const ::Ice::Context& context = ::Ice::noExplicitContext) { return _makePromiseOutgoing<bool>(true, this, &ObjectPrx::_iceI_isA, typeId, context).get(); } + /** + * Tests whether this object supports a specific Slice interface. + * @param typeId The type ID of the Slice interface to test against. + * @param response The response callback. + * @param ex The exception callback. + * @param sent The sent callback. + * @param context The context map for the invocation. + * @return A function that can be called to cancel the invocation locally. + */ ::std::function<void()> ice_isAAsync(const ::std::string& typeId, ::std::function<void(bool)> response, @@ -328,6 +362,12 @@ public: return _makeLamdaOutgoing<bool>(response, ex, sent, this, &ObjectPrx::_iceI_isA, typeId, context); } + /** + * Tests whether this object supports a specific Slice interface. + * @param typeId The type ID of the Slice interface to test against. + * @param context The context map for the invocation. + * @return The future object for the invocation. + */ template<template<typename> class P = std::promise> auto ice_isAAsync(const ::std::string& typeId, const ::Ice::Context& context = ::Ice::noExplicitContext) -> decltype(std::declval<P<bool>>().get_future()) @@ -335,15 +375,29 @@ public: return _makePromiseOutgoing<bool, P>(false, this, &ObjectPrx::_iceI_isA, typeId, context); } + /// \cond INTERNAL void _iceI_isA(const ::std::shared_ptr<::IceInternal::OutgoingAsyncT<bool>>&, const ::std::string&, const ::Ice::Context&); + /// \endcond + /** + * Tests whether the target object of this proxy can be reached. + * @param context The context map for the invocation. + */ void ice_ping(const ::Ice::Context& context = ::Ice::noExplicitContext) { _makePromiseOutgoing<void>(true, this, &ObjectPrx::_iceI_ping, context).get(); } + /** + * Tests whether the target object of this proxy can be reached. + * @param response The response callback. + * @param ex The exception callback. + * @param sent The sent callback. + * @param context The context map for the invocation. + * @return A function that can be called to cancel the invocation locally. + */ ::std::function<void()> ice_pingAsync(::std::function<void()> response, ::std::function<void(::std::exception_ptr)> ex = nullptr, @@ -353,6 +407,11 @@ public: return _makeLamdaOutgoing<void>(response, ex, sent, this, &ObjectPrx::_iceI_ping, context); } + /** + * Tests whether the target object of this proxy can be reached. + * @param context The context map for the invocation. + * @return The future object for the invocation. + */ template<template<typename> class P = std::promise> auto ice_pingAsync(const ::Ice::Context& context = ::Ice::noExplicitContext) -> decltype(std::declval<P<void>>().get_future()) @@ -360,15 +419,31 @@ public: return _makePromiseOutgoing<void, P>(false, this, &ObjectPrx::_iceI_ping, context); } + /// \cond INTERNAL void _iceI_ping(const ::std::shared_ptr<::IceInternal::OutgoingAsyncT<void>>&, const ::Ice::Context&); - + /// \endcond + + /** + * Returns the Slice type IDs of the interfaces supported by the target object of this proxy. + * @param context The context map for the invocation. + * @return The Slice type IDs of the interfaces supported by the target object, in base-to-derived + * order. The first element of the returned array is always "::Ice::Object". + */ ::std::vector<::std::string> ice_ids(const ::Ice::Context& context = ::Ice::noExplicitContext) { return _makePromiseOutgoing<::std::vector<::std::string>>(true, this, &ObjectPrx::_iceI_ids, context).get(); } + /** + * Returns the Slice type IDs of the interfaces supported by the target object of this proxy. + * @param response The response callback. + * @param ex The exception callback. + * @param sent The sent callback. + * @param context The context map for the invocation. + * @return A function that can be called to cancel the invocation locally. + */ ::std::function<void()> ice_idsAsync(::std::function<void(::std::vector<::std::string>)> response, ::std::function<void(::std::exception_ptr)> ex = nullptr, @@ -378,6 +453,11 @@ public: return _makeLamdaOutgoing<::std::vector<::std::string>>(response, ex, sent, this, &ObjectPrx::_iceI_ids, context); } + /** + * Returns the Slice type IDs of the interfaces supported by the target object of this proxy. + * @param context The context map for the invocation. + * @return The future object for the invocation. + */ template<template<typename> class P = std::promise> auto ice_idsAsync(const ::Ice::Context& context = ::Ice::noExplicitContext) -> decltype(std::declval<P<::std::vector<::std::string>>>().get_future()) @@ -385,15 +465,30 @@ public: return _makePromiseOutgoing<::std::vector<::std::string>, P>(false, this, &ObjectPrx::_iceI_ids, context); } + /// \cond INTERNAL void _iceI_ids(const ::std::shared_ptr<::IceInternal::OutgoingAsyncT<::std::vector<::std::string>>>&, const ::Ice::Context&); + /// \endcond + /** + * Returns the Slice type ID of the most-derived interface supported by the target object of this proxy. + * @param context The context map for the invocation. + * @return The Slice type ID of the most-derived interface. + */ ::std::string ice_id(const ::Ice::Context& context = ::Ice::noExplicitContext) { return _makePromiseOutgoing<::std::string>(true, this, &ObjectPrx::_iceI_id, context).get(); } + /** + * Returns the Slice type ID of the most-derived interface supported by the target object of this proxy. + * @param response The response callback. + * @param ex The exception callback. + * @param sent The sent callback. + * @param context The context map for the invocation. + * @return A function that can be called to cancel the invocation locally. + */ ::std::function<void()> ice_idAsync(::std::function<void(::std::string)> response, ::std::function<void(::std::exception_ptr)> ex = nullptr, @@ -403,6 +498,11 @@ public: return _makeLamdaOutgoing<::std::string>(response, ex, sent, this, &ObjectPrx::_iceI_id, context); } + /** + * Returns the Slice type ID of the most-derived interface supported by the target object of this proxy. + * @param context The context map for the invocation. + * @return The future object for the invocation. + */ template<template<typename> class P = std::promise> auto ice_idAsync(const ::Ice::Context& context = ::Ice::noExplicitContext) -> decltype(std::declval<P<::std::string>>().get_future()) @@ -410,42 +510,75 @@ public: return _makePromiseOutgoing<::std::string, P>(false, this, &ObjectPrx::_iceI_id, context); } + /// \cond INTERNAL void _iceI_id(const ::std::shared_ptr<::IceInternal::OutgoingAsyncT<::std::string>>&, const ::Ice::Context&); + /// \endcond + /** + * Returns the Slice type ID associated with this type. + * @return The Slice type ID. + */ static const ::std::string& ice_staticId() { return ::Ice::Object::ice_staticId(); } - // - // ice_invoke with default vector mapping for byte-sequence parameters - // - + /** + * Invokes an operation dynamically. + * @param operation The name of the operation to invoke. + * @param mode The operation mode (normal or idempotent). + * @param inParams An encapsulation containing the encoded in-parameters for the operation. + * @param outParams An encapsulation containing the encoded results. + * @param context The context map for the invocation. + * @return True if the operation completed successfully, in which case outParams contains + * the encoded out parameters. False if the operation raised a user exception, in which + * case outParams contains the encoded user exception. If the operation raises a run-time + * exception, it throws it directly. + */ bool ice_invoke(const ::std::string& operation, ::Ice::OperationMode mode, - const ::std::vector<Byte>& inP, + const ::std::vector<Byte>& inParams, ::std::vector<::Ice::Byte>& outParams, const ::Ice::Context& context = ::Ice::noExplicitContext) { - return ice_invoke(operation, mode, ::IceInternal::makePair(inP), outParams, context); + return ice_invoke(operation, mode, ::IceInternal::makePair(inParams), outParams, context); } + /** + * Invokes an operation dynamically. + * @param operation The name of the operation to invoke. + * @param mode The operation mode (normal or idempotent). + * @param inParams An encapsulation containing the encoded in-parameters for the operation. + * @param context The context map for the invocation. + * @return The future object for the invocation. + */ template<template<typename> class P = std::promise> auto ice_invokeAsync(const ::std::string& operation, ::Ice::OperationMode mode, - const ::std::vector<Byte>& inP, + const ::std::vector<Byte>& inParams, const ::Ice::Context& context = ::Ice::noExplicitContext) -> decltype(std::declval<P<::Ice::Object::Ice_invokeResult>>().get_future()) { - return ice_invokeAsync<P>(operation, mode, ::IceInternal::makePair(inP), context); + return ice_invokeAsync<P>(operation, mode, ::IceInternal::makePair(inParams), context); } + /** + * Invokes an operation dynamically. + * @param operation The name of the operation to invoke. + * @param mode The operation mode (normal or idempotent). + * @param inParams An encapsulation containing the encoded in-parameters for the operation. + * @param response The response callback. + * @param ex The exception callback. + * @param sent The sent callback. + * @param context The context map for the invocation. + * @return A function that can be called to cancel the invocation locally. + */ ::std::function<void()> ice_invokeAsync(const ::std::string& operation, ::Ice::OperationMode mode, - const ::std::vector<::Ice::Byte>& inP, + const ::std::vector<::Ice::Byte>& inParams, ::std::function<void(bool, ::std::vector<::Ice::Byte>)> response, ::std::function<void(::std::exception_ptr)> ex = nullptr, ::std::function<void(bool)> sent = nullptr, @@ -461,48 +594,75 @@ public: }; } auto outAsync = ::std::make_shared<Outgoing>(shared_from_this(), r, ex, sent); - outAsync->invoke(operation, mode, ::IceInternal::makePair(inP), context); + outAsync->invoke(operation, mode, ::IceInternal::makePair(inParams), context); return [outAsync]() { outAsync->cancel(); }; } - // - // ice_invoke with cpp:array mapping for byte sequence parameters - // - + /** + * Invokes an operation dynamically. + * @param operation The name of the operation to invoke. + * @param mode The operation mode (normal or idempotent). + * @param inParams An encapsulation containing the encoded in-parameters for the operation. + * @param outParams An encapsulation containing the encoded results. + * @param context The context map for the invocation. + * @return True if the operation completed successfully, in which case outParams contains + * the encoded out parameters. False if the operation raised a user exception, in which + * case outParams contains the encoded user exception. If the operation raises a run-time + * exception, it throws it directly. + */ bool ice_invoke(const ::std::string& operation, ::Ice::OperationMode mode, - const ::std::pair<const ::Ice::Byte*, const ::Ice::Byte*>& inP, + const ::std::pair<const ::Ice::Byte*, const ::Ice::Byte*>& inParams, ::std::vector<::Ice::Byte>& outParams, const ::Ice::Context& context = ::Ice::noExplicitContext) { using Outgoing = ::IceInternal::InvokePromiseOutgoing< ::std::promise<::Ice::Object::Ice_invokeResult>, ::Ice::Object::Ice_invokeResult>; auto outAsync = ::std::make_shared<Outgoing>(shared_from_this(), true); - outAsync->invoke(operation, mode, inP, context); + outAsync->invoke(operation, mode, inParams, context); auto result = outAsync->getFuture().get(); outParams.swap(result.outParams); return result.returnValue; } + /** + * Invokes an operation dynamically. + * @param operation The name of the operation to invoke. + * @param mode The operation mode (normal or idempotent). + * @param inParams An encapsulation containing the encoded in-parameters for the operation. + * @param context The context map for the invocation. + * @return The future object for the invocation. + */ template<template<typename> class P = std::promise> auto ice_invokeAsync(const ::std::string& operation, ::Ice::OperationMode mode, - const ::std::pair<const ::Ice::Byte*, const ::Ice::Byte*>& inP, + const ::std::pair<const ::Ice::Byte*, const ::Ice::Byte*>& inParams, const ::Ice::Context& context = ::Ice::noExplicitContext) -> decltype(std::declval<P<::Ice::Object::Ice_invokeResult>>().get_future()) { using Outgoing = ::IceInternal::InvokePromiseOutgoing<P<::Ice::Object::Ice_invokeResult>, ::Ice::Object::Ice_invokeResult>; auto outAsync = ::std::make_shared<Outgoing>(shared_from_this(), false); - outAsync->invoke(operation, mode, inP, context); + outAsync->invoke(operation, mode, inParams, context); return outAsync->getFuture(); } + /** + * Invokes an operation dynamically. + * @param operation The name of the operation to invoke. + * @param mode The operation mode (normal or idempotent). + * @param inParams An encapsulation containing the encoded in-parameters for the operation. + * @param response The response callback. + * @param ex The exception callback. + * @param sent The sent callback. + * @param context The context map for the invocation. + * @return A function that can be called to cancel the invocation locally. + */ ::std::function<void()> ice_invokeAsync(const ::std::string& operation, ::Ice::OperationMode mode, - const ::std::pair<const ::Ice::Byte*, const ::Ice::Byte*>& inP, + const ::std::pair<const ::Ice::Byte*, const ::Ice::Byte*>& inParams, ::std::function<void(bool, ::std::pair<const ::Ice::Byte*, const ::Ice::Byte*>)> response, ::std::function<void(::std::exception_ptr)> ex = nullptr, ::std::function<void(bool)> sent = nullptr, @@ -520,78 +680,318 @@ public: }; } auto outAsync = ::std::make_shared<Outgoing>(shared_from_this(), r, ex, sent); - outAsync->invoke(operation, mode, inP, context); + outAsync->invoke(operation, mode, inParams, context); return [outAsync]() { outAsync->cancel(); }; } + /** + * Obtains the identity embedded in this proxy. + * @return The identity of the target object. + */ ::Ice::Identity ice_getIdentity() const; - ::std::shared_ptr<::Ice::ObjectPrx> ice_identity(const ::Ice::Identity&) const; + /** + * Obtains a proxy that is identical to this proxy, except for the identity. + * @param id The identity for the new proxy. + * @return A proxy with the new identity. + */ + ::std::shared_ptr<::Ice::ObjectPrx> ice_identity(const ::Ice::Identity& id) const; + + /** + * Obtains the per-proxy context for this proxy. + * @return The per-proxy context. + */ ::Ice::Context ice_getContext() const; - ::std::shared_ptr<::Ice::ObjectPrx> ice_context(const ::Ice::Context&) const; + /** + * Obtains a proxy that is identical to this proxy, except for the per-proxy context. + * @param context The context for the new proxy. + * @return A proxy with the new per-proxy context. + */ + ::std::shared_ptr<::Ice::ObjectPrx> ice_context(const ::Ice::Context& context) const; + + /** + * Obtains the facet for this proxy. + * @return The facet for this proxy. If the proxy uses the default facet, the return value is the empty string. + */ const ::std::string& ice_getFacet() const; - ::std::shared_ptr<::Ice::ObjectPrx> ice_facet(const ::std::string&) const; + /** + * Obtains a proxy that is identical to this proxy, except for the facet. + * @param facet The facet for the new proxy. + * @return A proxy with the new facet. + */ + ::std::shared_ptr<::Ice::ObjectPrx> ice_facet(const ::std::string& facet) const; + + /** + * Obtains the adapter ID for this proxy. + * @return The adapter ID. If the proxy does not have an adapter ID, the return value is the empty string. + */ ::std::string ice_getAdapterId() const; - ::std::shared_ptr<::Ice::ObjectPrx> ice_adapterId(const ::std::string&) const; + /** + * Obtains a proxy that is identical to this proxy, except for the adapter ID. + * @param id The adapter ID for the new proxy. + * @return A proxy with the new adapter ID. + */ + ::std::shared_ptr<::Ice::ObjectPrx> ice_adapterId(const ::std::string& id) const; + + /** + * Obtains the endpoints used by this proxy. + * @return The endpoints used by this proxy. + */ ::Ice::EndpointSeq ice_getEndpoints() const; - ::std::shared_ptr<::Ice::ObjectPrx> ice_endpoints(const ::Ice::EndpointSeq&) const; + /** + * Obtains a proxy that is identical to this proxy, except for the endpoints. + * @param endpoints The endpoints for the new proxy. + * @return A proxy with the new endpoints. + */ + ::std::shared_ptr<::Ice::ObjectPrx> ice_endpoints(const ::Ice::EndpointSeq& endpoints) const; + + /** + * Obtains the locator cache timeout of this proxy. + * @return The locator cache timeout value (in seconds). + */ ::Ice::Int ice_getLocatorCacheTimeout() const; - ::std::shared_ptr<::Ice::ObjectPrx> ice_locatorCacheTimeout(::Ice::Int) const; + /** + * Obtains a proxy that is identical to this proxy, except for the locator cache timeout. + * @param timeout The new locator cache timeout (in seconds). + * @return A proxy with the new timeout. + */ + ::std::shared_ptr<::Ice::ObjectPrx> ice_locatorCacheTimeout(::Ice::Int timeout) const; + + /** + * Determines whether this proxy caches connections. + * @return True if this proxy caches connections, false otherwise. + */ bool ice_isConnectionCached() const; - ::std::shared_ptr<::Ice::ObjectPrx> ice_connectionCached(bool) const; + /** + * Obtains a proxy that is identical to this proxy, except for connection caching. + * @param b True if the new proxy should cache connections, false otherwise. + * @return A proxy with the specified caching policy. + */ + ::std::shared_ptr<::Ice::ObjectPrx> ice_connectionCached(bool b) const; + + /** + * Obtains the endpoint selection policy for this proxy (randomly or ordered). + * @return The endpoint selection policy. + */ ::Ice::EndpointSelectionType ice_getEndpointSelection() const; - ::std::shared_ptr<::Ice::ObjectPrx> ice_endpointSelection(::Ice::EndpointSelectionType) const; + /** + * Obtains a proxy that is identical to this proxy, except for the endpoint selection policy. + * @param type The new endpoint selection policy. + * @return A proxy with the specified endpoint selection policy. + */ + ::std::shared_ptr<::Ice::ObjectPrx> ice_endpointSelection(::Ice::EndpointSelectionType type) const; + + /** + * Determines whether this proxy uses only secure endpoints. + * @return True if this proxy communicates only via secure endpoints, false otherwise. + */ bool ice_isSecure() const; - ::std::shared_ptr<::Ice::ObjectPrx> ice_secure(bool) const; + /** + * Obtains a proxy that is identical to this proxy, except for how it selects endpoints. + * @param b If true, only endpoints that use a secure transport are used by the new proxy. + * If false, the returned proxy uses both secure and insecure endpoints. + * @return A proxy with the specified security policy. + */ + ::std::shared_ptr<::Ice::ObjectPrx> ice_secure(bool b) const; + + /** + * Obtains the encoding version used to marshal request parameters. + * @return The encoding version. + */ ::Ice::EncodingVersion ice_getEncodingVersion() const; - ::std::shared_ptr<::Ice::ObjectPrx> ice_encodingVersion(const ::Ice::EncodingVersion&) const; + /** + * Obtains a proxy that is identical to this proxy, except for the encoding used to marshal + * parameters. + * @param version The encoding version to use to marshal request parameters. + * @return A proxy with the specified encoding version. + */ + ::std::shared_ptr<::Ice::ObjectPrx> ice_encodingVersion(const ::Ice::EncodingVersion& version) const; + + /** + * Determines whether this proxy prefers secure endpoints. + * @return True if the proxy always attempts to invoke via secure endpoints before it + * attempts to use insecure endpoints, false otherwise. + */ bool ice_isPreferSecure() const; - ::std::shared_ptr<::Ice::ObjectPrx> ice_preferSecure(bool) const; + /** + * Obtains a proxy that is identical to this proxy, except for its endpoint selection policy. + * @param b If true, the new proxy will use secure endpoints for invocations and only use + * insecure endpoints if an invocation cannot be made via secure endpoints. If false, the + * proxy prefers insecure endpoints to secure ones. + * @return A proxy with the specified selection policy. + */ + ::std::shared_ptr<::Ice::ObjectPrx> ice_preferSecure(bool b) const; + + /** + * Obtains the router for this proxy. + * @return The router for the proxy. If no router is configured for the proxy, the return value + * is nil. + */ ::std::shared_ptr<::Ice::RouterPrx> ice_getRouter() const; - ::std::shared_ptr<::Ice::ObjectPrx> ice_router(const ::std::shared_ptr<::Ice::RouterPrx>&) const; + /** + * Obtains a proxy that is identical to this proxy, except for the router. + * @param router The router for the new proxy. + * @return A proxy with the specified router. + */ + ::std::shared_ptr<::Ice::ObjectPrx> ice_router(const ::std::shared_ptr<::Ice::RouterPrx>& router) const; + + /** + * Obtains the locator for this proxy. + * @return The locator for this proxy. If no locator is configured, the return value is nil. + */ ::std::shared_ptr<::Ice::LocatorPrx> ice_getLocator() const; - ::std::shared_ptr<::Ice::ObjectPrx> ice_locator(const ::std::shared_ptr<::Ice::LocatorPrx>&) const; + /** + * Obtains a proxy that is identical to this proxy, except for the locator. + * @param locator The locator for the new proxy. + * @return A proxy with the specified locator. + */ + ::std::shared_ptr<::Ice::ObjectPrx> ice_locator(const ::std::shared_ptr<::Ice::LocatorPrx>& locator) const; + + /** + * Determines whether this proxy uses collocation optimization. + * @return True if the proxy uses collocation optimization, false otherwise. + */ bool ice_isCollocationOptimized() const; - ::std::shared_ptr<::Ice::ObjectPrx> ice_collocationOptimized(bool) const; + /** + * Obtains a proxy that is identical to this proxy, except for collocation optimization. + * @param b True if the new proxy enables collocation optimization, false otherwise. + * @return A proxy with the specified collocation optimization. + */ + ::std::shared_ptr<::Ice::ObjectPrx> ice_collocationOptimized(bool b) const; + + /** + * Obtains the invocation timeout of this proxy. + * @return The invocation timeout value (in milliseconds). + */ ::Ice::Int ice_getInvocationTimeout() const; - ::std::shared_ptr<::Ice::ObjectPrx> ice_invocationTimeout(::Ice::Int) const; + /** + * Obtains a proxy that is identical to this proxy, except for the invocation timeout. + * @param timeout The new invocation timeout (in milliseconds). + * @return A proxy with the new timeout. + */ + ::std::shared_ptr<::Ice::ObjectPrx> ice_invocationTimeout(::Ice::Int timeout) const; + + /** + * Obtains a proxy that is identical to this proxy, but uses twoway invocations. + * @return A proxy that uses twoway invocations. + */ ::std::shared_ptr<::Ice::ObjectPrx> ice_twoway() const; + + /** + * Determines whether this proxy uses twoway invocations. + * @return True if this proxy uses twoway invocations, false otherwise. + */ bool ice_isTwoway() const; + + /** + * Obtains a proxy that is identical to this proxy, but uses oneway invocations. + * @return A proxy that uses oneway invocations. + */ ::std::shared_ptr<::Ice::ObjectPrx> ice_oneway() const; + + /** + * Determines whether this proxy uses oneway invocations. + * @return True if this proxy uses oneway invocations, false otherwise. + */ bool ice_isOneway() const; + + /** + * Obtains a proxy that is identical to this proxy, but uses batch oneway invocations. + * @return A proxy that uses batch oneway invocations. + */ ::std::shared_ptr<::Ice::ObjectPrx> ice_batchOneway() const; + + /** + * Determines whether this proxy uses batch oneway invocations. + * @return True if this proxy uses batch oneway invocations, false otherwise. + */ bool ice_isBatchOneway() const; + + /** + * Obtains a proxy that is identical to this proxy, but uses datagram invocations. + * @return A proxy that uses datagram invocations. + */ ::std::shared_ptr<::Ice::ObjectPrx> ice_datagram() const; + + /** + * Determines whether this proxy uses datagram invocations. + * @return True if this proxy uses datagram invocations, false otherwise. + */ bool ice_isDatagram() const; + + /** + * Obtains a proxy that is identical to this proxy, but uses batch datagram invocations. + * @return A proxy that uses batch datagram invocations. + */ ::std::shared_ptr<::Ice::ObjectPrx> ice_batchDatagram() const; - bool ice_isBatchDatagram() const; - ::std::shared_ptr<::Ice::ObjectPrx> ice_compress(bool) const; - ::std::shared_ptr<::Ice::ObjectPrx> ice_timeout(int) const; + /** + * Determines whether this proxy uses batch datagram invocations. + * @return True if this proxy uses batch datagram invocations, false otherwise. + */ + bool ice_isBatchDatagram() const; - ::std::shared_ptr<::Ice::ObjectPrx> ice_connectionId(const ::std::string&) const; + /** + * Obtains a proxy that is identical to this proxy, except for compression. + * @param b True enables compression for the new proxy, false disables compression. + * @return A proxy with the specified compression setting. + */ + ::std::shared_ptr<::Ice::ObjectPrx> ice_compress(bool b) const; + + /** + * Obtains a proxy that is identical to this proxy, except for its connection timeout setting. + * @param timeout The connection timeout for the proxy (in milliseconds). + * @return A proxy with the specified timeout. + */ + ::std::shared_ptr<::Ice::ObjectPrx> ice_timeout(int timeout) const; + + /** + * Obtains a proxy that is identical to this proxy, except for its connection ID. + * @param id The connection ID for the new proxy. An empty string removes the + * connection ID. + * @return A proxy with the specified connection ID. + */ + ::std::shared_ptr<::Ice::ObjectPrx> ice_connectionId(const ::std::string& id) const; + + /** + * Obtains the connection ID of this proxy. + * @return The connection ID. + */ ::std::string ice_getConnectionId() const; + /** + * Obtains the Connection for this proxy. If the proxy does not yet have an established connection, + * it first attempts to create a connection. + * @return The connection for this proxy. + */ ::std::shared_ptr<::Ice::Connection> ice_getConnection() { return ice_getConnectionAsync().get(); } + /** + * Obtains the Connection for this proxy. If the proxy does not yet have an established connection, + * it first attempts to create a connection. + * @param response The response callback. + * @param ex The exception callback. + * @param sent The sent callback. + * @return A function that can be called to cancel the invocation locally. + */ ::std::function<void()> ice_getConnectionAsync(::std::function<void(::std::shared_ptr<::Ice::Connection>)> response, ::std::function<void(::std::exception_ptr)> ex = nullptr, @@ -603,6 +1003,11 @@ public: return [outAsync]() { outAsync->cancel(); }; } + /** + * Obtains the Connection for this proxy. If the proxy does not yet have an established connection, + * it first attempts to create a connection. + * @return The future object for the invocation. + */ template<template<typename> class P = std::promise> auto ice_getConnectionAsync() -> decltype(std::declval<P<::std::shared_ptr<::Ice::Connection>>>().get_future()) { @@ -612,15 +1017,32 @@ public: return outAsync->getFuture(); } + /// \cond INTERNAL void _iceI_getConnection(const ::std::shared_ptr<::IceInternal::ProxyGetConnection>&); - + /// \endcond + + /** + * Obtains the cached Connection for this proxy. If the proxy does not yet have an established + * connection, it does not attempt to create a connection. + * @return The cached connection for this proxy, or nil if the proxy does not have + * an established connection. + */ ::std::shared_ptr<::Ice::Connection> ice_getCachedConnection() const; + /** + * Flushes any pending batched requests for this communicator. The call blocks until the flush is complete. + */ void ice_flushBatchRequests() { return ice_flushBatchRequestsAsync().get(); } + /** + * Flushes any pending batched requests for this communicator. The call blocks until the flush is complete. + * @param ex The exception callback. + * @param sent The sent callback. + * @return A function that can be called to cancel the invocation locally. + */ std::function<void()> ice_flushBatchRequestsAsync(::std::function<void(::std::exception_ptr)> ex, ::std::function<void(bool)> sent = nullptr) @@ -631,6 +1053,10 @@ public: return [outAsync]() { outAsync->cancel(); }; } + /** + * Flushes any pending batched requests for this communicator. The call blocks until the flush is complete. + * @return The future object for the invocation. + */ template<template<typename> class P = std::promise> auto ice_flushBatchRequestsAsync() -> decltype(std::declval<P<void>>().get_future()) { @@ -640,6 +1066,7 @@ public: return outAsync->getFuture(); } + /// \cond INTERNAL void _iceI_flushBatchRequests(const ::std::shared_ptr<::IceInternal::ProxyFlushBatchAsync>&); const ::IceInternal::ReferencePtr& _getReference() const { return _reference; } @@ -659,9 +1086,11 @@ public: int _hash() const; void _write(OutputStream&) const; + /// \endcond protected: + /// \cond INTERNAL template<typename R, template<typename> class P = ::std::promise, typename Obj, typename Fn, typename... Args> auto _makePromiseOutgoing(bool sync, Obj obj, Fn fn, Args&&... args) -> decltype(std::declval<P<R>>().get_future()) @@ -682,6 +1111,7 @@ protected: virtual ::std::shared_ptr<ObjectPrx> _newInstance() const; ObjectPrx() = default; friend ::std::shared_ptr<ObjectPrx> IceInternal::createProxy<ObjectPrx>(); + /// \endcond private: @@ -718,111 +1148,220 @@ operator!=(const ObjectPrx& lhs, const ObjectPrx& rhs) return !(lhs == rhs); } +/** + * Helper template that supplies proxy factory functions. + * \headerfile Ice/Ice.h + */ template<typename Prx, typename... Bases> class Proxy : public virtual Bases... { public: + /** + * Obtains a proxy that is identical to this proxy, except for the per-proxy context. + * @param context The context for the new proxy. + * @return A proxy with the new per-proxy context. + */ ::std::shared_ptr<Prx> ice_context(const ::Ice::Context& context) const { return ::std::dynamic_pointer_cast<Prx>(ObjectPrx::ice_context(context)); } + /** + * Obtains a proxy that is identical to this proxy, except for the adapter ID. + * @param id The adapter ID for the new proxy. + * @return A proxy with the new adapter ID. + */ ::std::shared_ptr<Prx> ice_adapterId(const ::std::string& id) const { return ::std::dynamic_pointer_cast<Prx>(ObjectPrx::ice_adapterId(id)); } + /** + * Obtains a proxy that is identical to this proxy, except for the endpoints. + * @param endpoints The endpoints for the new proxy. + * @return A proxy with the new endpoints. + */ ::std::shared_ptr<Prx> ice_endpoints(const ::Ice::EndpointSeq& endpoints) const { return ::std::dynamic_pointer_cast<Prx>(ObjectPrx::ice_endpoints(endpoints)); } + /** + * Obtains a proxy that is identical to this proxy, except for the locator cache timeout. + * @param timeout The new locator cache timeout (in seconds). + * @return A proxy with the new timeout. + */ ::std::shared_ptr<Prx> ice_locatorCacheTimeout(int timeout) const { return ::std::dynamic_pointer_cast<Prx>(ObjectPrx::ice_locatorCacheTimeout(timeout)); } - ::std::shared_ptr<Prx> ice_connectionCached(bool cached) const + /** + * Obtains a proxy that is identical to this proxy, except for connection caching. + * @param b True if the new proxy should cache connections, false otherwise. + * @return A proxy with the specified caching policy. + */ + ::std::shared_ptr<Prx> ice_connectionCached(bool b) const { - return ::std::dynamic_pointer_cast<Prx>(ObjectPrx::ice_connectionCached(cached)); + return ::std::dynamic_pointer_cast<Prx>(ObjectPrx::ice_connectionCached(b)); } - ::std::shared_ptr<Prx> ice_endpointSelection(::Ice::EndpointSelectionType selection) const + /** + * Obtains a proxy that is identical to this proxy, except for the endpoint selection policy. + * @param type The new endpoint selection policy. + * @return A proxy with the specified endpoint selection policy. + */ + ::std::shared_ptr<Prx> ice_endpointSelection(::Ice::EndpointSelectionType type) const { - return ::std::dynamic_pointer_cast<Prx>(ObjectPrx::ice_endpointSelection(selection)); + return ::std::dynamic_pointer_cast<Prx>(ObjectPrx::ice_endpointSelection(type)); } - ::std::shared_ptr<Prx> ice_secure(bool secure) const + /** + * Obtains a proxy that is identical to this proxy, except for how it selects endpoints. + * @param b If true, only endpoints that use a secure transport are used by the new proxy. + * If false, the returned proxy uses both secure and insecure endpoints. + * @return A proxy with the specified security policy. + */ + ::std::shared_ptr<Prx> ice_secure(bool b) const { - return ::std::dynamic_pointer_cast<Prx>(ObjectPrx::ice_secure(secure)); + return ::std::dynamic_pointer_cast<Prx>(ObjectPrx::ice_secure(b)); } - ::std::shared_ptr<Prx> ice_preferSecure(bool preferSecure) const + /** + * Obtains a proxy that is identical to this proxy, except for its endpoint selection policy. + * @param b If true, the new proxy will use secure endpoints for invocations and only use + * insecure endpoints if an invocation cannot be made via secure endpoints. If false, the + * proxy prefers insecure endpoints to secure ones. + * @return A proxy with the specified selection policy. + */ + ::std::shared_ptr<Prx> ice_preferSecure(bool b) const { - return ::std::dynamic_pointer_cast<Prx>(ObjectPrx::ice_preferSecure(preferSecure)); + return ::std::dynamic_pointer_cast<Prx>(ObjectPrx::ice_preferSecure(b)); } + /** + * Obtains a proxy that is identical to this proxy, except for the router. + * @param router The router for the new proxy. + * @return A proxy with the specified router. + */ ::std::shared_ptr<Prx> ice_router(const ::std::shared_ptr<::Ice::RouterPrx>& router) const { return ::std::dynamic_pointer_cast<Prx>(ObjectPrx::ice_router(router)); } + /** + * Obtains a proxy that is identical to this proxy, except for the locator. + * @param locator The locator for the new proxy. + * @return A proxy with the specified locator. + */ ::std::shared_ptr<Prx> ice_locator(const ::std::shared_ptr<::Ice::LocatorPrx>& locator) const { return ::std::dynamic_pointer_cast<Prx>(ObjectPrx::ice_locator(locator)); } - ::std::shared_ptr<Prx> ice_collocationOptimized(bool collocated) const + /** + * Obtains a proxy that is identical to this proxy, except for collocation optimization. + * @param b True if the new proxy enables collocation optimization, false otherwise. + * @return A proxy with the specified collocation optimization. + */ + ::std::shared_ptr<Prx> ice_collocationOptimized(bool b) const { - return ::std::dynamic_pointer_cast<Prx>(ObjectPrx::ice_collocationOptimized(collocated)); + return ::std::dynamic_pointer_cast<Prx>(ObjectPrx::ice_collocationOptimized(b)); } + /** + * Obtains a proxy that is identical to this proxy, except for the invocation timeout. + * @param timeout The new invocation timeout (in milliseconds). + * @return A proxy with the new timeout. + */ ::std::shared_ptr<Prx> ice_invocationTimeout(int timeout) const { return ::std::dynamic_pointer_cast<Prx>(ObjectPrx::ice_invocationTimeout(timeout)); } + /** + * Obtains a proxy that is identical to this proxy, but uses twoway invocations. + * @return A proxy that uses twoway invocations. + */ ::std::shared_ptr<Prx> ice_twoway() const { return ::std::dynamic_pointer_cast<Prx>(ObjectPrx::ice_twoway()); } + /** + * Obtains a proxy that is identical to this proxy, but uses oneway invocations. + * @return A proxy that uses oneway invocations. + */ ::std::shared_ptr<Prx> ice_oneway() const { return ::std::dynamic_pointer_cast<Prx>(ObjectPrx::ice_oneway()); } + /** + * Obtains a proxy that is identical to this proxy, but uses batch oneway invocations. + * @return A proxy that uses batch oneway invocations. + */ ::std::shared_ptr<Prx> ice_batchOneway() const { return ::std::dynamic_pointer_cast<Prx>(ObjectPrx::ice_batchOneway()); } + /** + * Obtains a proxy that is identical to this proxy, but uses datagram invocations. + * @return A proxy that uses datagram invocations. + */ ::std::shared_ptr<Prx> ice_datagram() const { return ::std::dynamic_pointer_cast<Prx>(ObjectPrx::ice_datagram()); } + /** + * Obtains a proxy that is identical to this proxy, but uses batch datagram invocations. + * @return A proxy that uses batch datagram invocations. + */ ::std::shared_ptr<Prx> ice_batchDatagram() const { return ::std::dynamic_pointer_cast<Prx>(ObjectPrx::ice_batchDatagram()); } - ::std::shared_ptr<Prx> ice_compress(bool compress) const + /** + * Obtains a proxy that is identical to this proxy, except for compression. + * @param b True enables compression for the new proxy, false disables compression. + * @return A proxy with the specified compression setting. + */ + ::std::shared_ptr<Prx> ice_compress(bool b) const { - return ::std::dynamic_pointer_cast<Prx>(ObjectPrx::ice_compress(compress)); + return ::std::dynamic_pointer_cast<Prx>(ObjectPrx::ice_compress(b)); } + /** + * Obtains a proxy that is identical to this proxy, except for its connection timeout setting. + * @param timeout The connection timeout for the proxy (in milliseconds). + * @return A proxy with the specified timeout. + */ ::std::shared_ptr<Prx> ice_timeout(int timeout) const { return ::std::dynamic_pointer_cast<Prx>(ObjectPrx::ice_timeout(timeout)); } + /** + * Obtains a proxy that is identical to this proxy, except for its connection ID. + * @param id The connection ID for the new proxy. An empty string removes the + * connection ID. + * @return A proxy with the specified connection ID. + */ ::std::shared_ptr<Prx> ice_connectionId(const ::std::string& id) const { return ::std::dynamic_pointer_cast<Prx>(ObjectPrx::ice_connectionId(id)); } + /** + * Obtains a proxy that is identical to this proxy, except for the encoding used to marshal + * parameters. + * @param version The encoding version to use to marshal request parameters. + * @return A proxy with the specified encoding version. + */ ::std::shared_ptr<Prx> ice_encodingVersion(const ::Ice::EncodingVersion& version) const { return ::std::dynamic_pointer_cast<Prx>(ObjectPrx::ice_encodingVersion(version)); @@ -830,17 +1369,54 @@ public: protected: + /// \cond INTERNAL virtual ::std::shared_ptr<ObjectPrx> _newInstance() const = 0; + /// \endcond }; ICE_API ::std::ostream& operator<<(::std::ostream&, const ::Ice::ObjectPrx&); -ICE_API bool proxyIdentityLess(const ::std::shared_ptr<ObjectPrx>&, const ::std::shared_ptr<ObjectPrx>&); -ICE_API bool proxyIdentityEqual(const ::std::shared_ptr<ObjectPrx>&, const ::std::shared_ptr<ObjectPrx>&); - -ICE_API bool proxyIdentityAndFacetLess(const ::std::shared_ptr<ObjectPrx>&, const ::std::shared_ptr<ObjectPrx>&); -ICE_API bool proxyIdentityAndFacetEqual(const ::std::shared_ptr<ObjectPrx>&, const ::std::shared_ptr<ObjectPrx>&); - +/** + * Compares the object identities of two proxies. + * @param lhs A proxy. + * @param rhs A proxy. + * @return True if the identity in lhs compares less than the identity in rhs, false otherwise. + */ +ICE_API bool proxyIdentityLess(const ::std::shared_ptr<ObjectPrx>& lhs, const ::std::shared_ptr<ObjectPrx>& rhs); + +/** + * Compares the object identities of two proxies. + * @param lhs A proxy. + * @param rhs A proxy. + * @return True if the identity in lhs compares equal to the identity in rhs, false otherwise. + */ +ICE_API bool proxyIdentityEqual(const ::std::shared_ptr<ObjectPrx>& lhs, const ::std::shared_ptr<ObjectPrx>& rhs); + +/** + * Compares the object identities and facets of two proxies. + * @param lhs A proxy. + * @param rhs A proxy. + * @return True if the identity and facet in lhs compare less than the identity and facet + * in rhs, false otherwise. + */ +ICE_API bool proxyIdentityAndFacetLess(const ::std::shared_ptr<ObjectPrx>& lhs, + const ::std::shared_ptr<ObjectPrx>& rhs); + +/** + * Compares the object identities and facets of two proxies. + * @param lhs A proxy. + * @param rhs A proxy. + * @return True if the identity and facet in lhs compare equal to the identity and facet + * in rhs, false otherwise. + */ +ICE_API bool proxyIdentityAndFacetEqual(const ::std::shared_ptr<ObjectPrx>& lhs, + const ::std::shared_ptr<ObjectPrx>& rhs); + +/** + * A functor that compares the object identities of two proxies. Evaluates true if the identity in lhs + * compares less than the identity in rhs, false otherwise. + * \headerfile Ice/Ice.h + */ struct ProxyIdentityLess : std::binary_function<bool, ::std::shared_ptr<ObjectPrx>&, ::std::shared_ptr<ObjectPrx>&> { bool operator()(const ::std::shared_ptr<ObjectPrx>& lhs, const ::std::shared_ptr<ObjectPrx>& rhs) const @@ -849,6 +1425,11 @@ struct ProxyIdentityLess : std::binary_function<bool, ::std::shared_ptr<ObjectPr } }; +/** + * A functor that compares the object identities of two proxies. Evaluates true if the identity in lhs + * compares equal to the identity in rhs, false otherwise. + * \headerfile Ice/Ice.h + */ struct ProxyIdentityEqual : std::binary_function<bool, ::std::shared_ptr<ObjectPrx>&, ::std::shared_ptr<ObjectPrx>&> { bool operator()(const ::std::shared_ptr<ObjectPrx>& lhs, const ::std::shared_ptr<ObjectPrx>& rhs) const @@ -857,6 +1438,11 @@ struct ProxyIdentityEqual : std::binary_function<bool, ::std::shared_ptr<ObjectP } }; +/** + * A functor that compares the object identities and facets of two proxies. Evaluates true if the identity + * and facet in lhs compare less than the identity and facet in rhs, false otherwise. + * \headerfile Ice/Ice.h + */ struct ProxyIdentityAndFacetLess : std::binary_function<bool, ::std::shared_ptr<ObjectPrx>&, ::std::shared_ptr<ObjectPrx>&> { bool operator()(const ::std::shared_ptr<ObjectPrx>& lhs, const ::std::shared_ptr<ObjectPrx>& rhs) const @@ -865,6 +1451,11 @@ struct ProxyIdentityAndFacetLess : std::binary_function<bool, ::std::shared_ptr< } }; +/** + * A functor that compares the object identities and facets of two proxies. Evaluates true if the identity + * and facet in lhs compare equal to the identity and facet in rhs, false otherwise. + * \headerfile Ice/Ice.h + */ struct ProxyIdentityAndFacetEqual : std::binary_function<bool, ::std::shared_ptr<ObjectPrx>&, ::std::shared_ptr<ObjectPrx>&> { bool operator()(const ::std::shared_ptr<ObjectPrx>& lhs, const ::std::shared_ptr<ObjectPrx>& rhs) const @@ -873,6 +1464,11 @@ struct ProxyIdentityAndFacetEqual : std::binary_function<bool, ::std::shared_ptr } }; +/** + * Downcasts a proxy without confirming the target object's type via a remote invocation. + * @param b The target proxy. + * @return A proxy with the requested type. + */ template<typename P, typename T, typename ::std::enable_if<::std::is_base_of<::Ice::ObjectPrx, P>::value>::type* = nullptr, @@ -892,6 +1488,12 @@ uncheckedCast(const ::std::shared_ptr<T>& b) return r; } +/** + * Downcasts a proxy without confirming the target object's type via a remote invocation. + * @param b The target proxy. + * @param f A facet name. + * @return A proxy with the requested type and facet. + */ template<typename P, typename T, typename ::std::enable_if<::std::is_base_of<::Ice::ObjectPrx, P>::value>::type* = nullptr, @@ -907,6 +1509,13 @@ uncheckedCast(const ::std::shared_ptr<T>& b, const std::string& f) return r; } +/** + * Downcasts a proxy after confirming the target object's type via a remote invocation. + * @param b The target proxy. + * @param context The context map for the invocation. + * @return A proxy with the requested type, or nil if the target proxy is nil or the target + * object does not support the requested type. + */ template<typename P, typename T, typename ::std::enable_if<::std::is_base_of<::Ice::ObjectPrx, P>::value>::type* = nullptr, @@ -925,6 +1534,14 @@ checkedCast(const ::std::shared_ptr<T>& b, const ::Ice::Context& context = Ice:: return r; } +/** + * Downcasts a proxy after confirming the target object's type via a remote invocation. + * @param b The target proxy. + * @param f A facet name. + * @param context The context map for the invocation. + * @return A proxy with the requested type and facet, or nil if the target proxy is nil or the target + * object does not support the requested type. + */ template<typename P, typename T, typename ::std::enable_if<::std::is_base_of<::Ice::ObjectPrx, P>::value>::type* = nullptr, @@ -962,11 +1579,13 @@ namespace IceProxy namespace Ice { +/// \cond INTERNAL class Locator; ICE_API ::IceProxy::Ice::Object* upCast(::IceProxy::Ice::Locator*); class Router; ICE_API ::IceProxy::Ice::Object* upCast(::IceProxy::Ice::Router*); +/// \endcond } @@ -983,24 +1602,66 @@ typedef LocatorPrx LocatorPrxPtr; class LocalException; class OutputStream; +/** + * Base class for asynchronous callback wrapper classes used for calls to + * IceProxy::Ice::Object::begin_ice_isA. + * Create a wrapper instance by calling ::Ice::newCallback_Object_ice_isA. + * \headerfile Ice/Ice.h + */ class Callback_Object_ice_isA_Base : public virtual ::IceInternal::CallbackBase { }; typedef ::IceUtil::Handle< Callback_Object_ice_isA_Base> Callback_Object_ice_isAPtr; +/** + * Base class for asynchronous callback wrapper classes used for calls to + * IceProxy::Ice::Object::begin_ice_ping. + * Create a wrapper instance by calling ::Ice::newCallback_Object_ice_ping. + * \headerfile Ice/Ice.h + */ class Callback_Object_ice_ping_Base : public virtual ::IceInternal::CallbackBase { }; typedef ::IceUtil::Handle< Callback_Object_ice_ping_Base> Callback_Object_ice_pingPtr; +/** + * Base class for asynchronous callback wrapper classes used for calls to + * IceProxy::Ice::Object::begin_ice_ids. + * Create a wrapper instance by calling ::Ice::newCallback_Object_ice_ids. + * \headerfile Ice/Ice.h + */ class Callback_Object_ice_ids_Base : public virtual ::IceInternal::CallbackBase { }; typedef ::IceUtil::Handle< Callback_Object_ice_ids_Base> Callback_Object_ice_idsPtr; +/** + * Base class for asynchronous callback wrapper classes used for calls to + * IceProxy::Ice::Object::begin_ice_id. + * Create a wrapper instance by calling ::Ice::newCallback_Object_ice_id. + * \headerfile Ice/Ice.h + */ class Callback_Object_ice_id_Base : public virtual ::IceInternal::CallbackBase { }; typedef ::IceUtil::Handle< Callback_Object_ice_id_Base> Callback_Object_ice_idPtr; +/** + * Base class for asynchronous callback wrapper classes used for calls to + * IceProxy::Ice::Object::begin_ice_invoke. + * Create a wrapper instance by calling ::Ice::newCallback_Object_ice_invoke. + * \headerfile Ice/Ice.h + */ class Callback_Object_ice_invoke_Base : public virtual ::IceInternal::CallbackBase { }; typedef ::IceUtil::Handle< Callback_Object_ice_invoke_Base> Callback_Object_ice_invokePtr; +/** + * Base class for asynchronous callback wrapper classes used for calls to + * IceProxy::Ice::Object::begin_ice_flushBatchRequests. + * Create a wrapper instance by calling ::Ice::newCallback_Object_ice_flushBatchRequests. + * \headerfile Ice/Ice.h + */ class Callback_Object_ice_flushBatchRequests_Base : public virtual ::IceInternal::CallbackBase { }; typedef ::IceUtil::Handle< Callback_Object_ice_flushBatchRequests_Base> Callback_Object_ice_flushBatchRequestsPtr; +/** + * Base class for asynchronous callback wrapper classes used for calls to + * IceProxy::Ice::Object::begin_ice_getConnection. + * Create a wrapper instance by calling ::Ice::newCallback_Object_ice_getConnection. + * \headerfile Ice/Ice.h + */ class Callback_Object_ice_getConnection_Base : public virtual ::IceInternal::CallbackBase { }; typedef ::IceUtil::Handle< Callback_Object_ice_getConnection_Base> Callback_Object_ice_getConnectionPtr; @@ -1009,6 +1670,10 @@ typedef ::IceUtil::Handle< Callback_Object_ice_getConnection_Base> Callback_Obje namespace IceProxy { namespace Ice { +/** + * Base class of all object proxies. + * \headerfile Ice/Ice.h + */ class ICE_API Object : public ::IceUtil::Shared { public: @@ -1016,408 +1681,1023 @@ public: bool operator==(const Object&) const; bool operator<(const Object&) const; + /** + * Obtains the communicator that created this proxy. + * @return The communicator that created this proxy. + */ ::Ice::CommunicatorPtr ice_getCommunicator() const; + /** + * Obtains a stringified version of this proxy. + * @return A stringified proxy. + */ ::std::string ice_toString() const; + /** + * Tests whether this object supports a specific Slice interface. + * @param typeId The type ID of the Slice interface to test against. + * @param context The context map for the invocation. + * @return True if the target object has the interface + * specified by id or derives from the interface specified by id. + */ bool ice_isA(const ::std::string& typeId, const ::Ice::Context& context = ::Ice::noExplicitContext) { return end_ice_isA(_iceI_begin_ice_isA(typeId, context, ::IceInternal::dummyCallback, 0, true)); } + /** + * Tests whether this object supports a specific Slice interface. + * @param typeId The type ID of the Slice interface to test against. + * @param context The context map for the invocation. + * @return The asynchronous result object for the invocation. + */ ::Ice::AsyncResultPtr begin_ice_isA(const ::std::string& typeId, const ::Ice::Context& context = ::Ice::noExplicitContext) { return _iceI_begin_ice_isA(typeId, context, ::IceInternal::dummyCallback, 0); } + /** + * Tests whether this object supports a specific Slice interface. + * @param typeId The type ID of the Slice interface to test against. + * @param cb Asynchronous callback object. + * @param cookie User-defined data to associate with the invocation. + * @return The asynchronous result object for the invocation. + */ ::Ice::AsyncResultPtr begin_ice_isA(const ::std::string& typeId, - const ::Ice::CallbackPtr& del, + const ::Ice::CallbackPtr& cb, const ::Ice::LocalObjectPtr& cookie = 0) { - return _iceI_begin_ice_isA(typeId, ::Ice::noExplicitContext, del, cookie); + return _iceI_begin_ice_isA(typeId, ::Ice::noExplicitContext, cb, cookie); } + /** + * Tests whether this object supports a specific Slice interface. + * @param typeId The type ID of the Slice interface to test against. + * @param context The context map for the invocation. + * @param cb Asynchronous callback object. + * @param cookie User-defined data to associate with the invocation. + * @return The asynchronous result object for the invocation. + */ ::Ice::AsyncResultPtr begin_ice_isA(const ::std::string& typeId, const ::Ice::Context& context, - const ::Ice::CallbackPtr& del, + const ::Ice::CallbackPtr& cb, const ::Ice::LocalObjectPtr& cookie = 0) { - return _iceI_begin_ice_isA(typeId, context, del, cookie); + return _iceI_begin_ice_isA(typeId, context, cb, cookie); } + /** + * Tests whether this object supports a specific Slice interface. + * @param typeId The type ID of the Slice interface to test against. + * @param cb Asynchronous callback object. + * @param cookie User-defined data to associate with the invocation. + * @return The asynchronous result object for the invocation. + */ ::Ice::AsyncResultPtr begin_ice_isA(const ::std::string& typeId, - const ::Ice::Callback_Object_ice_isAPtr& del, + const ::Ice::Callback_Object_ice_isAPtr& cb, const ::Ice::LocalObjectPtr& cookie = 0) { - return _iceI_begin_ice_isA(typeId, ::Ice::noExplicitContext, del, cookie); + return _iceI_begin_ice_isA(typeId, ::Ice::noExplicitContext, cb, cookie); } + /** + * Tests whether this object supports a specific Slice interface. + * @param typeId The type ID of the Slice interface to test against. + * @param context The context map for the invocation. + * @param cb Asynchronous callback object. + * @param cookie User-defined data to associate with the invocation. + * @return The asynchronous result object for the invocation. + */ ::Ice::AsyncResultPtr begin_ice_isA(const ::std::string& typeId, const ::Ice::Context& context, - const ::Ice::Callback_Object_ice_isAPtr& del, + const ::Ice::Callback_Object_ice_isAPtr& cb, const ::Ice::LocalObjectPtr& cookie = 0) { - return _iceI_begin_ice_isA(typeId, context, del, cookie); + return _iceI_begin_ice_isA(typeId, context, cb, cookie); } - bool end_ice_isA(const ::Ice::AsyncResultPtr&); + /** + * Completes an invocation of begin_ice_isA. + * @param result The asynchronous result object for the invocation. + * @return True if the target object has the interface + * specified by id or derives from the interface specified by id. + */ + bool end_ice_isA(const ::Ice::AsyncResultPtr& result); + /** + * Tests whether the target object of this proxy can be reached. + * @param context The context map for the invocation. + */ void ice_ping(const ::Ice::Context& context = ::Ice::noExplicitContext) { end_ice_ping(_iceI_begin_ice_ping(context, ::IceInternal::dummyCallback, 0, true)); } + /** + * Tests whether the target object of this proxy can be reached. + * @param context The context map for the invocation. + * @return The asynchronous result object for the invocation. + */ ::Ice::AsyncResultPtr begin_ice_ping(const ::Ice::Context& context = ::Ice::noExplicitContext) { return _iceI_begin_ice_ping(context, ::IceInternal::dummyCallback, 0); } - ::Ice::AsyncResultPtr begin_ice_ping(const ::Ice::CallbackPtr& del, const ::Ice::LocalObjectPtr& cookie = 0) + /** + * Tests whether the target object of this proxy can be reached. + * @param cb Asynchronous callback object. + * @param cookie User-defined data to associate with the invocation. + * @return The asynchronous result object for the invocation. + */ + ::Ice::AsyncResultPtr begin_ice_ping(const ::Ice::CallbackPtr& cb, const ::Ice::LocalObjectPtr& cookie = 0) { - return _iceI_begin_ice_ping(::Ice::noExplicitContext, del, cookie); + return _iceI_begin_ice_ping(::Ice::noExplicitContext, cb, cookie); } - ::Ice::AsyncResultPtr begin_ice_ping(const ::Ice::Context& context, const ::Ice::CallbackPtr& del, + /** + * Tests whether the target object of this proxy can be reached. + * @param context The context map for the invocation. + * @param cb Asynchronous callback object. + * @param cookie User-defined data to associate with the invocation. + * @return The asynchronous result object for the invocation. + */ + ::Ice::AsyncResultPtr begin_ice_ping(const ::Ice::Context& context, const ::Ice::CallbackPtr& cb, const ::Ice::LocalObjectPtr& cookie = 0) { - return _iceI_begin_ice_ping(context, del, cookie); + return _iceI_begin_ice_ping(context, cb, cookie); } - ::Ice::AsyncResultPtr begin_ice_ping(const ::Ice::Callback_Object_ice_pingPtr& del, + /** + * Tests whether the target object of this proxy can be reached. + * @param cb Asynchronous callback object. + * @param cookie User-defined data to associate with the invocation. + * @return The asynchronous result object for the invocation. + */ + ::Ice::AsyncResultPtr begin_ice_ping(const ::Ice::Callback_Object_ice_pingPtr& cb, const ::Ice::LocalObjectPtr& cookie = 0) { - return _iceI_begin_ice_ping(::Ice::noExplicitContext, del, cookie); + return _iceI_begin_ice_ping(::Ice::noExplicitContext, cb, cookie); } - ::Ice::AsyncResultPtr begin_ice_ping(const ::Ice::Context& context, const ::Ice::Callback_Object_ice_pingPtr& del, + /** + * Tests whether the target object of this proxy can be reached. + * @param context The context map for the invocation. + * @param cb Asynchronous callback object. + * @param cookie User-defined data to associate with the invocation. + * @return The asynchronous result object for the invocation. + */ + ::Ice::AsyncResultPtr begin_ice_ping(const ::Ice::Context& context, const ::Ice::Callback_Object_ice_pingPtr& cb, const ::Ice::LocalObjectPtr& cookie = 0) { - return _iceI_begin_ice_ping(context, del, cookie); + return _iceI_begin_ice_ping(context, cb, cookie); } - void end_ice_ping(const ::Ice::AsyncResultPtr&); + /** + * Completes an invocation of begin_ice_ping. + * @param result The asynchronous result object for the invocation. + */ + void end_ice_ping(const ::Ice::AsyncResultPtr& result); + /** + * Returns the Slice type IDs of the interfaces supported by the target object of this proxy. + * @param context The context map for the invocation. + * @return The Slice type IDs of the interfaces supported by the target object, in base-to-derived + * order. The first element of the returned array is always "::Ice::Object". + */ ::std::vector< ::std::string> ice_ids(const ::Ice::Context& context = ::Ice::noExplicitContext) { return end_ice_ids(_iceI_begin_ice_ids(context, ::IceInternal::dummyCallback, 0, true)); } + /** + * Returns the Slice type IDs of the interfaces supported by the target object of this proxy. + * @param context The context map for the invocation. + * @return The asynchronous result object for the invocation. + */ ::Ice::AsyncResultPtr begin_ice_ids(const ::Ice::Context& context = ::Ice::noExplicitContext) { return _iceI_begin_ice_ids(context, ::IceInternal::dummyCallback, 0); } - ::Ice::AsyncResultPtr begin_ice_ids(const ::Ice::CallbackPtr& del, + /** + * Returns the Slice type IDs of the interfaces supported by the target object of this proxy. + * @param cb Asynchronous callback object. + * @param cookie User-defined data to associate with the invocation. + * @return The asynchronous result object for the invocation. + */ + ::Ice::AsyncResultPtr begin_ice_ids(const ::Ice::CallbackPtr& cb, const ::Ice::LocalObjectPtr& cookie = 0) { - return _iceI_begin_ice_ids(::Ice::noExplicitContext, del, cookie); + return _iceI_begin_ice_ids(::Ice::noExplicitContext, cb, cookie); } + /** + * Returns the Slice type IDs of the interfaces supported by the target object of this proxy. + * @param context The context map for the invocation. + * @param cb Asynchronous callback object. + * @param cookie User-defined data to associate with the invocation. + * @return The asynchronous result object for the invocation. + */ ::Ice::AsyncResultPtr begin_ice_ids(const ::Ice::Context& context, - const ::Ice::CallbackPtr& del, + const ::Ice::CallbackPtr& cb, const ::Ice::LocalObjectPtr& cookie = 0) { - return _iceI_begin_ice_ids(context, del, cookie); + return _iceI_begin_ice_ids(context, cb, cookie); } - ::Ice::AsyncResultPtr begin_ice_ids(const ::Ice::Callback_Object_ice_idsPtr& del, + /** + * Returns the Slice type IDs of the interfaces supported by the target object of this proxy. + * @param cb Asynchronous callback object. + * @param cookie User-defined data to associate with the invocation. + * @return The asynchronous result object for the invocation. + */ + ::Ice::AsyncResultPtr begin_ice_ids(const ::Ice::Callback_Object_ice_idsPtr& cb, const ::Ice::LocalObjectPtr& cookie = 0) { - return _iceI_begin_ice_ids(::Ice::noExplicitContext, del, cookie); + return _iceI_begin_ice_ids(::Ice::noExplicitContext, cb, cookie); } + /** + * Returns the Slice type IDs of the interfaces supported by the target object of this proxy. + * @param context The context map for the invocation. + * @param cb Asynchronous callback object. + * @param cookie User-defined data to associate with the invocation. + * @return The asynchronous result object for the invocation. + */ ::Ice::AsyncResultPtr begin_ice_ids(const ::Ice::Context& context, - const ::Ice::Callback_Object_ice_idsPtr& del, + const ::Ice::Callback_Object_ice_idsPtr& cb, const ::Ice::LocalObjectPtr& cookie = 0) { - return _iceI_begin_ice_ids(context, del, cookie); + return _iceI_begin_ice_ids(context, cb, cookie); } - ::std::vector< ::std::string> end_ice_ids(const ::Ice::AsyncResultPtr&); + /** + * Completes an invocation of begin_ice_ids. + * @param result The asynchronous result object for the invocation. + * @return The Slice type IDs of the interfaces supported by the target object, in base-to-derived + * order. The first element of the returned array is always "::Ice::Object". + */ + ::std::vector< ::std::string> end_ice_ids(const ::Ice::AsyncResultPtr& result); + /** + * Returns the Slice type ID of the most-derived interface supported by the target object of this proxy. + * @param context The context map for the invocation. + * @return The Slice type ID of the most-derived interface. + */ ::std::string ice_id(const ::Ice::Context& context = ::Ice::noExplicitContext) { return end_ice_id(_iceI_begin_ice_id(context, ::IceInternal::dummyCallback, 0, true)); } + /** + * Returns the Slice type ID of the most-derived interface supported by the target object of this proxy. + * @param context The context map for the invocation. + * @return The asynchronous result object for the invocation. + */ ::Ice::AsyncResultPtr begin_ice_id(const ::Ice::Context& context = ::Ice::noExplicitContext) { return _iceI_begin_ice_id(context, ::IceInternal::dummyCallback, 0); } - ::Ice::AsyncResultPtr begin_ice_id(const ::Ice::CallbackPtr& del, + /** + * Returns the Slice type ID of the most-derived interface supported by the target object of this proxy. + * @param cb Asynchronous callback object. + * @param cookie User-defined data to associate with the invocation. + * @return The asynchronous result object for the invocation. + */ + ::Ice::AsyncResultPtr begin_ice_id(const ::Ice::CallbackPtr& cb, const ::Ice::LocalObjectPtr& cookie = 0) { - return _iceI_begin_ice_id(::Ice::noExplicitContext, del, cookie); + return _iceI_begin_ice_id(::Ice::noExplicitContext, cb, cookie); } + /** + * Returns the Slice type ID of the most-derived interface supported by the target object of this proxy. + * @param context The context map for the invocation. + * @param cb Asynchronous callback object. + * @param cookie User-defined data to associate with the invocation. + * @return The asynchronous result object for the invocation. + */ ::Ice::AsyncResultPtr begin_ice_id(const ::Ice::Context& context, - const ::Ice::CallbackPtr& del, + const ::Ice::CallbackPtr& cb, const ::Ice::LocalObjectPtr& cookie = 0) { - return _iceI_begin_ice_id(context, del, cookie); + return _iceI_begin_ice_id(context, cb, cookie); } - ::Ice::AsyncResultPtr begin_ice_id(const ::Ice::Callback_Object_ice_idPtr& del, + /** + * Returns the Slice type ID of the most-derived interface supported by the target object of this proxy. + * @param cb Asynchronous callback object. + * @param cookie User-defined data to associate with the invocation. + * @return The asynchronous result object for the invocation. + */ + ::Ice::AsyncResultPtr begin_ice_id(const ::Ice::Callback_Object_ice_idPtr& cb, const ::Ice::LocalObjectPtr& cookie = 0) { - return _iceI_begin_ice_id(::Ice::noExplicitContext, del, cookie); + return _iceI_begin_ice_id(::Ice::noExplicitContext, cb, cookie); } + /** + * Returns the Slice type ID of the most-derived interface supported by the target object of this proxy. + * @param context The context map for the invocation. + * @param cb Asynchronous callback object. + * @param cookie User-defined data to associate with the invocation. + * @return The asynchronous result object for the invocation. + */ ::Ice::AsyncResultPtr begin_ice_id(const ::Ice::Context& context, - const ::Ice::Callback_Object_ice_idPtr& del, + const ::Ice::Callback_Object_ice_idPtr& cb, const ::Ice::LocalObjectPtr& cookie = 0) { - return _iceI_begin_ice_id(context, del, cookie); + return _iceI_begin_ice_id(context, cb, cookie); } - ::std::string end_ice_id(const ::Ice::AsyncResultPtr&); + /** + * Completes an invocation of begin_ice_id. + * @param result The asynchronous result object for the invocation. + * @return The Slice type ID of the most-derived interface. + */ + ::std::string end_ice_id(const ::Ice::AsyncResultPtr& result); + /** + * Returns the Slice type ID associated with this type. + * @return The Slice type ID. + */ static const ::std::string& ice_staticId() { return ::Ice::Object::ice_staticId(); } - // Returns true if ok, false if user exception. - bool ice_invoke(const ::std::string&, - ::Ice::OperationMode, - const ::std::vector< ::Ice::Byte>&, - ::std::vector< ::Ice::Byte>&, - const ::Ice::Context& = ::Ice::noExplicitContext); - - ::Ice::AsyncResultPtr begin_ice_invoke(const ::std::string& op, + /** + * Invokes an operation dynamically. + * @param operation The name of the operation to invoke. + * @param mode The operation mode (normal or idempotent). + * @param inParams An encapsulation containing the encoded in-parameters for the operation. + * @param outParams An encapsulation containing the encoded results. + * @param context The context map for the invocation. + * @return True if the operation completed successfully, in which case outParams contains + * the encoded out parameters. False if the operation raised a user exception, in which + * case outParams contains the encoded user exception. If the operation raises a run-time + * exception, it throws it directly. + */ + bool ice_invoke(const ::std::string& operation, + ::Ice::OperationMode mode, + const ::std::vector< ::Ice::Byte>& inParams, + ::std::vector< ::Ice::Byte>& outParams, + const ::Ice::Context& context = ::Ice::noExplicitContext); + + /** + * Invokes an operation dynamically. + * @param operation The name of the operation to invoke. + * @param mode The operation mode (normal or idempotent). + * @param inParams An encapsulation containing the encoded in-parameters for the operation. + * @return The asynchronous result object for the invocation. + */ + ::Ice::AsyncResultPtr begin_ice_invoke(const ::std::string& operation, ::Ice::OperationMode mode, const ::std::vector< ::Ice::Byte>& inParams) { - return _iceI_begin_ice_invoke(op, mode, inParams, ::Ice::noExplicitContext, ::IceInternal::dummyCallback, 0); + return _iceI_begin_ice_invoke(operation, mode, inParams, ::Ice::noExplicitContext, + ::IceInternal::dummyCallback, 0); } - ::Ice::AsyncResultPtr begin_ice_invoke(const ::std::string& op, + /** + * Invokes an operation dynamically. + * @param operation The name of the operation to invoke. + * @param mode The operation mode (normal or idempotent). + * @param inParams An encapsulation containing the encoded in-parameters for the operation. + * @param context The context map for the invocation. + * @return The asynchronous result object for the invocation. + */ + ::Ice::AsyncResultPtr begin_ice_invoke(const ::std::string& operation, ::Ice::OperationMode mode, const ::std::vector< ::Ice::Byte>& inParams, const ::Ice::Context& context) { - return _iceI_begin_ice_invoke(op, mode, inParams, context, ::IceInternal::dummyCallback, 0); + return _iceI_begin_ice_invoke(operation, mode, inParams, context, ::IceInternal::dummyCallback, 0); } - ::Ice::AsyncResultPtr begin_ice_invoke(const ::std::string& op, + /** + * Invokes an operation dynamically. + * @param operation The name of the operation to invoke. + * @param mode The operation mode (normal or idempotent). + * @param inParams An encapsulation containing the encoded in-parameters for the operation. + * @param cb Asynchronous callback object. + * @param cookie User-defined data to associate with the invocation. + * @return The asynchronous result object for the invocation. + */ + ::Ice::AsyncResultPtr begin_ice_invoke(const ::std::string& operation, ::Ice::OperationMode mode, const ::std::vector< ::Ice::Byte>& inParams, - const ::Ice::CallbackPtr& del, + const ::Ice::CallbackPtr& cb, const ::Ice::LocalObjectPtr& cookie = 0) { - return _iceI_begin_ice_invoke(op, mode, inParams, ::Ice::noExplicitContext, del, cookie); + return _iceI_begin_ice_invoke(operation, mode, inParams, ::Ice::noExplicitContext, cb, cookie); } - ::Ice::AsyncResultPtr begin_ice_invoke(const ::std::string& op, + /** + * Invokes an operation dynamically. + * @param operation The name of the operation to invoke. + * @param mode The operation mode (normal or idempotent). + * @param inParams An encapsulation containing the encoded in-parameters for the operation. + * @param context The context map for the invocation. + * @param cb Asynchronous callback object. + * @param cookie User-defined data to associate with the invocation. + * @return The asynchronous result object for the invocation. + */ + ::Ice::AsyncResultPtr begin_ice_invoke(const ::std::string& operation, ::Ice::OperationMode mode, const ::std::vector< ::Ice::Byte>& inParams, const ::Ice::Context& context, - const ::Ice::CallbackPtr& del, + const ::Ice::CallbackPtr& cb, const ::Ice::LocalObjectPtr& cookie = 0) { - return _iceI_begin_ice_invoke(op, mode, inParams, context, del, cookie); + return _iceI_begin_ice_invoke(operation, mode, inParams, context, cb, cookie); } - ::Ice::AsyncResultPtr begin_ice_invoke(const ::std::string& op, + /** + * Invokes an operation dynamically. + * @param operation The name of the operation to invoke. + * @param mode The operation mode (normal or idempotent). + * @param inParams An encapsulation containing the encoded in-parameters for the operation. + * @param cb Asynchronous callback object. + * @param cookie User-defined data to associate with the invocation. + * @return The asynchronous result object for the invocation. + */ + ::Ice::AsyncResultPtr begin_ice_invoke(const ::std::string& operation, ::Ice::OperationMode mode, const ::std::vector< ::Ice::Byte>& inParams, - const ::Ice::Callback_Object_ice_invokePtr& del, + const ::Ice::Callback_Object_ice_invokePtr& cb, const ::Ice::LocalObjectPtr& cookie = 0) { - return _iceI_begin_ice_invoke(op, mode, inParams, ::Ice::noExplicitContext, del, cookie); + return _iceI_begin_ice_invoke(operation, mode, inParams, ::Ice::noExplicitContext, cb, cookie); } - ::Ice::AsyncResultPtr begin_ice_invoke(const ::std::string& op, + /** + * Invokes an operation dynamically. + * @param operation The name of the operation to invoke. + * @param mode The operation mode (normal or idempotent). + * @param inParams An encapsulation containing the encoded in-parameters for the operation. + * @param context The context map for the invocation. + * @param cb Asynchronous callback object. + * @param cookie User-defined data to associate with the invocation. + * @return The asynchronous result object for the invocation. + */ + ::Ice::AsyncResultPtr begin_ice_invoke(const ::std::string& operation, ::Ice::OperationMode mode, const ::std::vector< ::Ice::Byte>& inParams, const ::Ice::Context& context, - const ::Ice::Callback_Object_ice_invokePtr& del, + const ::Ice::Callback_Object_ice_invokePtr& cb, const ::Ice::LocalObjectPtr& cookie = 0) { - return _iceI_begin_ice_invoke(op, mode, inParams, context, del, cookie); - } - - bool end_ice_invoke(::std::vector< ::Ice::Byte>&, const ::Ice::AsyncResultPtr&); - - bool ice_invoke(const ::std::string& op, + return _iceI_begin_ice_invoke(operation, mode, inParams, context, cb, cookie); + } + + /** + * Invokes an operation dynamically. + * @param outParams An encapsulation containing the encoded results. + * @param result The asynchronous result object for the invocation. + * @return True if the operation completed successfully, in which case outParams contains + * the encoded out parameters. False if the operation raised a user exception, in which + * case outParams contains the encoded user exception. If the operation raises a run-time + * exception, it throws it directly. + */ + bool end_ice_invoke(::std::vector< ::Ice::Byte>& outParams, const ::Ice::AsyncResultPtr& result); + + /** + * Invokes an operation dynamically. + * @param operation The name of the operation to invoke. + * @param mode The operation mode (normal or idempotent). + * @param inParams An encapsulation containing the encoded in-parameters for the operation. + * @param outParams An encapsulation containing the encoded results. + * @param context The context map for the invocation. + * @return True if the operation completed successfully, in which case outParams contains + * the encoded out parameters. False if the operation raised a user exception, in which + * case outParams contains the encoded user exception. If the operation raises a run-time + * exception, it throws it directly. + */ + bool ice_invoke(const ::std::string& operation, ::Ice::OperationMode mode, - const ::std::pair<const ::Ice::Byte*, const ::Ice::Byte*>& inP, - ::std::vector< ::Ice::Byte>& outP, + const ::std::pair<const ::Ice::Byte*, const ::Ice::Byte*>& inParams, + ::std::vector< ::Ice::Byte>& outParams, const ::Ice::Context& context = ::Ice::noExplicitContext) { - return end_ice_invoke(outP, _iceI_begin_ice_invoke(op, mode, inP, context, ::IceInternal::dummyCallback, 0, true)); + return end_ice_invoke(outParams, _iceI_begin_ice_invoke(operation, mode, inParams, context, + ::IceInternal::dummyCallback, 0, true)); } - ::Ice::AsyncResultPtr begin_ice_invoke(const ::std::string& op, + /** + * Invokes an operation dynamically. + * @param operation The name of the operation to invoke. + * @param mode The operation mode (normal or idempotent). + * @param inParams An encapsulation containing the encoded in-parameters for the operation. + * @return The asynchronous result object for the invocation. + */ + ::Ice::AsyncResultPtr begin_ice_invoke(const ::std::string& operation, ::Ice::OperationMode mode, const ::std::pair<const ::Ice::Byte*, const ::Ice::Byte*>& inParams) { - return _iceI_begin_ice_invoke(op, mode, inParams, ::Ice::noExplicitContext, ::IceInternal::dummyCallback, 0); + return _iceI_begin_ice_invoke(operation, mode, inParams, ::Ice::noExplicitContext, + ::IceInternal::dummyCallback, 0); } - ::Ice::AsyncResultPtr begin_ice_invoke(const ::std::string& op, + /** + * Invokes an operation dynamically. + * @param operation The name of the operation to invoke. + * @param mode The operation mode (normal or idempotent). + * @param inParams An encapsulation containing the encoded in-parameters for the operation. + * @param context The context map for the invocation. + * @param cookie User-defined data to associate with the invocation. + * @return The asynchronous result object for the invocation. + */ + ::Ice::AsyncResultPtr begin_ice_invoke(const ::std::string& operation, ::Ice::OperationMode mode, const ::std::pair<const ::Ice::Byte*, const ::Ice::Byte*>& inParams, const ::Ice::Context& context, const ::Ice::LocalObjectPtr& cookie = 0) { - return _iceI_begin_ice_invoke(op, mode, inParams, context, ::IceInternal::dummyCallback, cookie); + return _iceI_begin_ice_invoke(operation, mode, inParams, context, ::IceInternal::dummyCallback, cookie); } - ::Ice::AsyncResultPtr begin_ice_invoke(const ::std::string& op, + /** + * Invokes an operation dynamically. + * @param operation The name of the operation to invoke. + * @param mode The operation mode (normal or idempotent). + * @param inParams An encapsulation containing the encoded in-parameters for the operation. + * @param cb Asynchronous callback object. + * @param cookie User-defined data to associate with the invocation. + * @return The asynchronous result object for the invocation. + */ + ::Ice::AsyncResultPtr begin_ice_invoke(const ::std::string& operation, ::Ice::OperationMode mode, const ::std::pair<const ::Ice::Byte*, const ::Ice::Byte*>& inParams, - const ::Ice::CallbackPtr& del, + const ::Ice::CallbackPtr& cb, const ::Ice::LocalObjectPtr& cookie = 0) { - return _iceI_begin_ice_invoke(op, mode, inParams, ::Ice::noExplicitContext, del, cookie); + return _iceI_begin_ice_invoke(operation, mode, inParams, ::Ice::noExplicitContext, cb, cookie); } - ::Ice::AsyncResultPtr begin_ice_invoke(const ::std::string& op, + /** + * Invokes an operation dynamically. + * @param operation The name of the operation to invoke. + * @param mode The operation mode (normal or idempotent). + * @param inParams An encapsulation containing the encoded in-parameters for the operation. + * @param context The context map for the invocation. + * @param cb Asynchronous callback object. + * @param cookie User-defined data to associate with the invocation. + * @return The asynchronous result object for the invocation. + */ + ::Ice::AsyncResultPtr begin_ice_invoke(const ::std::string& operation, ::Ice::OperationMode mode, const ::std::pair<const ::Ice::Byte*, const ::Ice::Byte*>& inParams, const ::Ice::Context& context, - const ::Ice::CallbackPtr& del, + const ::Ice::CallbackPtr& cb, const ::Ice::LocalObjectPtr& cookie = 0) { - return _iceI_begin_ice_invoke(op, mode, inParams, context, del, cookie); + return _iceI_begin_ice_invoke(operation, mode, inParams, context, cb, cookie); } - ::Ice::AsyncResultPtr begin_ice_invoke(const ::std::string& op, + /** + * Invokes an operation dynamically. + * @param operation The name of the operation to invoke. + * @param mode The operation mode (normal or idempotent). + * @param inParams An encapsulation containing the encoded in-parameters for the operation. + * @param cb Asynchronous callback object. + * @param cookie User-defined data to associate with the invocation. + * @return The asynchronous result object for the invocation. + */ + ::Ice::AsyncResultPtr begin_ice_invoke(const ::std::string& operation, ::Ice::OperationMode mode, const ::std::pair<const ::Ice::Byte*, const ::Ice::Byte*>& inParams, - const ::Ice::Callback_Object_ice_invokePtr& del, + const ::Ice::Callback_Object_ice_invokePtr& cb, const ::Ice::LocalObjectPtr& cookie = 0) { - return _iceI_begin_ice_invoke(op, mode, inParams, ::Ice::noExplicitContext, del, cookie); + return _iceI_begin_ice_invoke(operation, mode, inParams, ::Ice::noExplicitContext, cb, cookie); } - ::Ice::AsyncResultPtr begin_ice_invoke(const ::std::string& op, + /** + * Invokes an operation dynamically. + * @param operation The name of the operation to invoke. + * @param mode The operation mode (normal or idempotent). + * @param inParams An encapsulation containing the encoded in-parameters for the operation. + * @param context The context map for the invocation. + * @param cb Asynchronous callback object. + * @param cookie User-defined data to associate with the invocation. + * @return The asynchronous result object for the invocation. + */ + ::Ice::AsyncResultPtr begin_ice_invoke(const ::std::string& operation, ::Ice::OperationMode mode, const ::std::pair<const ::Ice::Byte*, const ::Ice::Byte*>& inParams, const ::Ice::Context& context, - const ::Ice::Callback_Object_ice_invokePtr& del, + const ::Ice::Callback_Object_ice_invokePtr& cb, const ::Ice::LocalObjectPtr& cookie = 0) { - return _iceI_begin_ice_invoke(op, mode, inParams, context, del, cookie); + return _iceI_begin_ice_invoke(operation, mode, inParams, context, cb, cookie); } + /// \cond INTERNAL bool _iceI_end_ice_invoke(::std::pair<const ::Ice::Byte*, const ::Ice::Byte*>&, const ::Ice::AsyncResultPtr&); + /// \endcond + /** + * Obtains the identity embedded in this proxy. + * @return The identity of the target object. + */ ::Ice::Identity ice_getIdentity() const; - ::Ice::ObjectPrx ice_identity(const ::Ice::Identity&) const; + /** + * Obtains a proxy that is identical to this proxy, except for the identity. + * @param id The identity for the new proxy. + * @return A proxy with the new identity. + */ + ::Ice::ObjectPrx ice_identity(const ::Ice::Identity& id) const; + + /** + * Obtains the per-proxy context for this proxy. + * @return The per-proxy context. + */ ::Ice::Context ice_getContext() const; - ::Ice::ObjectPrx ice_context(const ::Ice::Context&) const; + /** + * Obtains a proxy that is identical to this proxy, except for the per-proxy context. + * @param context The context for the new proxy. + * @return A proxy with the new per-proxy context. + */ + ::Ice::ObjectPrx ice_context(const ::Ice::Context& context) const; + + /** + * Obtains the facet for this proxy. + * @return The facet for this proxy. If the proxy uses the default facet, the return value is the empty string. + */ const ::std::string& ice_getFacet() const; - ::Ice::ObjectPrx ice_facet(const ::std::string&) const; + /** + * Obtains a proxy that is identical to this proxy, except for the facet. + * @param facet The facet for the new proxy. + * @return A proxy with the new facet. + */ + ::Ice::ObjectPrx ice_facet(const ::std::string& facet) const; + + /** + * Obtains the adapter ID for this proxy. + * @return The adapter ID. If the proxy does not have an adapter ID, the return value is the empty string. + */ ::std::string ice_getAdapterId() const; - ::Ice::ObjectPrx ice_adapterId(const ::std::string&) const; + /** + * Obtains a proxy that is identical to this proxy, except for the adapter ID. + * @param id The adapter ID for the new proxy. + * @return A proxy with the new adapter ID. + */ + ::Ice::ObjectPrx ice_adapterId(const ::std::string& id) const; + + /** + * Obtains the endpoints used by this proxy. + * @return The endpoints used by this proxy. + */ ::Ice::EndpointSeq ice_getEndpoints() const; - ::Ice::ObjectPrx ice_endpoints(const ::Ice::EndpointSeq&) const; + /** + * Obtains a proxy that is identical to this proxy, except for the endpoints. + * @param endpoints The endpoints for the new proxy. + * @return A proxy with the new endpoints. + */ + ::Ice::ObjectPrx ice_endpoints(const ::Ice::EndpointSeq& endpoints) const; + + /** + * Obtains the locator cache timeout of this proxy. + * @return The locator cache timeout value (in seconds). + */ ::Ice::Int ice_getLocatorCacheTimeout() const; - ::Ice::ObjectPrx ice_locatorCacheTimeout(::Ice::Int) const; + /** + * Obtains a proxy that is identical to this proxy, except for the locator cache timeout. + * @param timeout The new locator cache timeout (in seconds). + * @return A proxy with the new timeout. + */ + ::Ice::ObjectPrx ice_locatorCacheTimeout(::Ice::Int timeout) const; + + /** + * Determines whether this proxy caches connections. + * @return True if this proxy caches connections, false otherwise. + */ bool ice_isConnectionCached() const; - ::Ice::ObjectPrx ice_connectionCached(bool) const; + /** + * Obtains a proxy that is identical to this proxy, except for connection caching. + * @param b True if the new proxy should cache connections, false otherwise. + * @return A proxy with the specified caching policy. + */ + ::Ice::ObjectPrx ice_connectionCached(bool b) const; + + /** + * Obtains the endpoint selection policy for this proxy (randomly or ordered). + * @return The endpoint selection policy. + */ ::Ice::EndpointSelectionType ice_getEndpointSelection() const; - ::Ice::ObjectPrx ice_endpointSelection(::Ice::EndpointSelectionType) const; + /** + * Obtains a proxy that is identical to this proxy, except for the endpoint selection policy. + * @param type The new endpoint selection policy. + * @return A proxy with the specified endpoint selection policy. + */ + ::Ice::ObjectPrx ice_endpointSelection(::Ice::EndpointSelectionType type) const; + + /** + * Determines whether this proxy uses only secure endpoints. + * @return True if this proxy communicates only via secure endpoints, false otherwise. + */ bool ice_isSecure() const; - ::Ice::ObjectPrx ice_secure(bool) const; + /** + * Obtains a proxy that is identical to this proxy, except for how it selects endpoints. + * @param b If true, only endpoints that use a secure transport are used by the new proxy. + * If false, the returned proxy uses both secure and insecure endpoints. + * @return A proxy with the specified security policy. + */ + ::Ice::ObjectPrx ice_secure(bool b) const; + + /** + * Obtains the encoding version used to marshal request parameters. + * @return The encoding version. + */ ::Ice::EncodingVersion ice_getEncodingVersion() const; - ::Ice::ObjectPrx ice_encodingVersion(const ::Ice::EncodingVersion&) const; + /** + * Obtains a proxy that is identical to this proxy, except for the encoding used to marshal + * parameters. + * @param version The encoding version to use to marshal request parameters. + * @return A proxy with the specified encoding version. + */ + ::Ice::ObjectPrx ice_encodingVersion(const ::Ice::EncodingVersion& version) const; + + /** + * Determines whether this proxy prefers secure endpoints. + * @return True if the proxy always attempts to invoke via secure endpoints before it + * attempts to use insecure endpoints, false otherwise. + */ bool ice_isPreferSecure() const; - ::Ice::ObjectPrx ice_preferSecure(bool) const; + /** + * Obtains a proxy that is identical to this proxy, except for its endpoint selection policy. + * @param b If true, the new proxy will use secure endpoints for invocations and only use + * insecure endpoints if an invocation cannot be made via secure endpoints. If false, the + * proxy prefers insecure endpoints to secure ones. + * @return A proxy with the specified selection policy. + */ + ::Ice::ObjectPrx ice_preferSecure(bool b) const; + + /** + * Obtains the router for this proxy. + * @return The router for the proxy. If no router is configured for the proxy, the return value + * is nil. + */ ::Ice::RouterPrx ice_getRouter() const; - ::Ice::ObjectPrx ice_router(const ::Ice::RouterPrx&) const; + /** + * Obtains a proxy that is identical to this proxy, except for the router. + * @param router The router for the new proxy. + * @return A proxy with the specified router. + */ + ::Ice::ObjectPrx ice_router(const ::Ice::RouterPrx& router) const; + + /** + * Obtains the locator for this proxy. + * @return The locator for this proxy. If no locator is configured, the return value is nil. + */ ::Ice::LocatorPrx ice_getLocator() const; - ::Ice::ObjectPrx ice_locator(const ::Ice::LocatorPrx&) const; + /** + * Obtains a proxy that is identical to this proxy, except for the locator. + * @param locator The locator for the new proxy. + * @return A proxy with the specified locator. + */ + ::Ice::ObjectPrx ice_locator(const ::Ice::LocatorPrx& locator) const; + + /** + * Determines whether this proxy uses collocation optimization. + * @return True if the proxy uses collocation optimization, false otherwise. + */ bool ice_isCollocationOptimized() const; - ::Ice::ObjectPrx ice_collocationOptimized(bool) const; + /** + * Obtains a proxy that is identical to this proxy, except for collocation optimization. + * @param b True if the new proxy enables collocation optimization, false otherwise. + * @return A proxy with the specified collocation optimization. + */ + ::Ice::ObjectPrx ice_collocationOptimized(bool b) const; + + /** + * Obtains the invocation timeout of this proxy. + * @return The invocation timeout value (in milliseconds). + */ ::Ice::Int ice_getInvocationTimeout() const; - ::Ice::ObjectPrx ice_invocationTimeout(::Ice::Int) const; + /** + * Obtains a proxy that is identical to this proxy, except for the invocation timeout. + * @param timeout The new invocation timeout (in milliseconds). + * @return A proxy with the new timeout. + */ + ::Ice::ObjectPrx ice_invocationTimeout(::Ice::Int timeout) const; + + /** + * Obtains a proxy that is identical to this proxy, but uses twoway invocations. + * @return A proxy that uses twoway invocations. + */ ::Ice::ObjectPrx ice_twoway() const; + + /** + * Determines whether this proxy uses twoway invocations. + * @return True if this proxy uses twoway invocations, false otherwise. + */ bool ice_isTwoway() const; + + /** + * Obtains a proxy that is identical to this proxy, but uses oneway invocations. + * @return A proxy that uses oneway invocations. + */ ::Ice::ObjectPrx ice_oneway() const; + + /** + * Determines whether this proxy uses oneway invocations. + * @return True if this proxy uses oneway invocations, false otherwise. + */ bool ice_isOneway() const; + + /** + * Obtains a proxy that is identical to this proxy, but uses batch oneway invocations. + * @return A proxy that uses batch oneway invocations. + */ ::Ice::ObjectPrx ice_batchOneway() const; + + /** + * Determines whether this proxy uses batch oneway invocations. + * @return True if this proxy uses batch oneway invocations, false otherwise. + */ bool ice_isBatchOneway() const; + + /** + * Obtains a proxy that is identical to this proxy, but uses datagram invocations. + * @return A proxy that uses datagram invocations. + */ ::Ice::ObjectPrx ice_datagram() const; + + /** + * Determines whether this proxy uses datagram invocations. + * @return True if this proxy uses datagram invocations, false otherwise. + */ bool ice_isDatagram() const; + + /** + * Obtains a proxy that is identical to this proxy, but uses batch datagram invocations. + * @return A proxy that uses batch datagram invocations. + */ ::Ice::ObjectPrx ice_batchDatagram() const; - bool ice_isBatchDatagram() const; - ::Ice::ObjectPrx ice_compress(bool) const; - ::Ice::ObjectPrx ice_timeout(int) const; + /** + * Determines whether this proxy uses batch datagram invocations. + * @return True if this proxy uses batch datagram invocations, false otherwise. + */ + bool ice_isBatchDatagram() const; - ::Ice::ObjectPrx ice_connectionId(const ::std::string&) const; + /** + * Obtains a proxy that is identical to this proxy, except for compression. + * @param b True enables compression for the new proxy, false disables compression. + * @return A proxy with the specified compression setting. + */ + ::Ice::ObjectPrx ice_compress(bool b) const; + + /** + * Obtains a proxy that is identical to this proxy, except for its connection timeout setting. + * @param timeout The connection timeout for the proxy (in milliseconds). + * @return A proxy with the specified timeout. + */ + ::Ice::ObjectPrx ice_timeout(int timeout) const; + + /** + * Obtains a proxy that is identical to this proxy, except for its connection ID. + * @param id The connection ID for the new proxy. An empty string removes the + * connection ID. + * @return A proxy with the specified connection ID. + */ + ::Ice::ObjectPrx ice_connectionId(const ::std::string& id) const; + + /** + * Obtains the connection ID of this proxy. + * @return The connection ID. + */ ::std::string ice_getConnectionId() const; + /** + * Obtains the Connection for this proxy. If the proxy does not yet have an established connection, + * it first attempts to create a connection. + * @return The connection for this proxy. + */ ::Ice::ConnectionPtr ice_getConnection() { return end_ice_getConnection(begin_ice_getConnection()); } + /** + * Obtains the Connection for this proxy. If the proxy does not yet have an established connection, + * it first attempts to create a connection. + * @return The asynchronous result object for the invocation. + */ ::Ice::AsyncResultPtr begin_ice_getConnection() { return _iceI_begin_ice_getConnection(::IceInternal::dummyCallback, 0); } - ::Ice::AsyncResultPtr begin_ice_getConnection(const ::Ice::CallbackPtr& del, + /** + * Obtains the Connection for this proxy. If the proxy does not yet have an established connection, + * it first attempts to create a connection. + * @param cb Asynchronous callback object. + * @param cookie User-defined data to associate with the invocation. + * @return The asynchronous result object for the invocation. + */ + ::Ice::AsyncResultPtr begin_ice_getConnection(const ::Ice::CallbackPtr& cb, const ::Ice::LocalObjectPtr& cookie = 0) { - return _iceI_begin_ice_getConnection(del, cookie); + return _iceI_begin_ice_getConnection(cb, cookie); } - ::Ice::AsyncResultPtr begin_ice_getConnection(const ::Ice::Callback_Object_ice_getConnectionPtr& del, + /** + * Obtains the Connection for this proxy. If the proxy does not yet have an established connection, + * it first attempts to create a connection. + * @param cb Asynchronous callback object. + * @param cookie User-defined data to associate with the invocation. + * @return The asynchronous result object for the invocation. + */ + ::Ice::AsyncResultPtr begin_ice_getConnection(const ::Ice::Callback_Object_ice_getConnectionPtr& cb, const ::Ice::LocalObjectPtr& cookie = 0) { - return _iceI_begin_ice_getConnection(del, cookie); + return _iceI_begin_ice_getConnection(cb, cookie); } - ::Ice::ConnectionPtr end_ice_getConnection(const ::Ice::AsyncResultPtr&); + /** + * Completes an invocation of begin_ice_getConnection. + * @param result The asynchronous result object for the invocation. + * @return The connection for this proxy. + */ + ::Ice::ConnectionPtr end_ice_getConnection(const ::Ice::AsyncResultPtr& result); + /** + * Returns the cached connection for this proxy. If the proxy does not yet have an established + * connection, it does not attempt to create a connection. + * + * @return The cached connection for this proxy, or nil if the proxy does not have + * an established connection. + */ ::Ice::ConnectionPtr ice_getCachedConnection() const; + /** + * Flushes any pending batched requests for this proxy. The call blocks until the flush is complete. + */ void ice_flushBatchRequests() { return end_ice_flushBatchRequests(begin_ice_flushBatchRequests()); } + /** + * Flushes any pending batched requests for this proxy. The call blocks until the flush is complete. + * @return The asynchronous result object for the invocation. + */ ::Ice::AsyncResultPtr begin_ice_flushBatchRequests() { return _iceI_begin_ice_flushBatchRequests(::IceInternal::dummyCallback, 0); } - ::Ice::AsyncResultPtr begin_ice_flushBatchRequests(const ::Ice::CallbackPtr& del, + /** + * Flushes any pending batched requests for this proxy. The call blocks until the flush is complete. + * @param cb Asynchronous callback object. + * @param cookie User-defined data to associate with the invocation. + * @return The asynchronous result object for the invocation. + */ + ::Ice::AsyncResultPtr begin_ice_flushBatchRequests(const ::Ice::CallbackPtr& cb, const ::Ice::LocalObjectPtr& cookie = 0) { - return _iceI_begin_ice_flushBatchRequests(del, cookie); + return _iceI_begin_ice_flushBatchRequests(cb, cookie); } - ::Ice::AsyncResultPtr begin_ice_flushBatchRequests(const ::Ice::Callback_Object_ice_flushBatchRequestsPtr& del, + /** + * Flushes any pending batched requests for this proxy. The call blocks until the flush is complete. + * @param cb Asynchronous callback object. + * @param cookie User-defined data to associate with the invocation. + * @return The asynchronous result object for the invocation. + */ + ::Ice::AsyncResultPtr begin_ice_flushBatchRequests(const ::Ice::Callback_Object_ice_flushBatchRequestsPtr& cb, const ::Ice::LocalObjectPtr& cookie = 0) { - return _iceI_begin_ice_flushBatchRequests(del, cookie); + return _iceI_begin_ice_flushBatchRequests(cb, cookie); } - void end_ice_flushBatchRequests(const ::Ice::AsyncResultPtr&); + /** + * Completes an invocation of begin_ice_flushBatchRequests. + * @param result The asynchronous result object for the invocation. + */ + void end_ice_flushBatchRequests(const ::Ice::AsyncResultPtr& result); + /// \cond INTERNAL const ::IceInternal::ReferencePtr& _getReference() const { return _reference; } ::Ice::Int _hash() const; @@ -1437,10 +2717,13 @@ public: void _updateRequestHandler(const ::IceInternal::RequestHandlerPtr&, const ::IceInternal::RequestHandlerPtr&); void _write(::Ice::OutputStream&) const; + /// \endcond protected: + /// \cond INTERNAL virtual Object* _newInstance() const; + /// \endcond private: @@ -1503,111 +2786,220 @@ ICE_API ::std::ostream& operator<<(::std::ostream&, const ::IceProxy::Ice::Objec namespace Ice { +/** + * Helper template that supplies proxy factory functions. + * \headerfile Ice/Ice.h + */ template<typename Prx, typename Base> class Proxy : public virtual Base { public: + /** + * Obtains a proxy that is identical to this proxy, except for the per-proxy context. + * @param context The context for the new proxy. + * @return A proxy with the new per-proxy context. + */ IceInternal::ProxyHandle<Prx> ice_context(const ::Ice::Context& context) const { return dynamic_cast<Prx*>(::IceProxy::Ice::Object::ice_context(context).get()); } + /** + * Obtains a proxy that is identical to this proxy, except for the adapter ID. + * @param id The adapter ID for the new proxy. + * @return A proxy with the new adapter ID. + */ IceInternal::ProxyHandle<Prx> ice_adapterId(const ::std::string& id) const { return dynamic_cast<Prx*>(::IceProxy::Ice::Object::ice_adapterId(id).get()); } + /** + * Obtains a proxy that is identical to this proxy, except for the endpoints. + * @param endpoints The endpoints for the new proxy. + * @return A proxy with the new endpoints. + */ IceInternal::ProxyHandle<Prx> ice_endpoints(const ::Ice::EndpointSeq& endpoints) const { return dynamic_cast<Prx*>(::IceProxy::Ice::Object::ice_endpoints(endpoints).get()); } + /** + * Obtains a proxy that is identical to this proxy, except for the locator cache timeout. + * @param timeout The new locator cache timeout (in seconds). + * @return A proxy with the new timeout. + */ IceInternal::ProxyHandle<Prx> ice_locatorCacheTimeout(int timeout) const { return dynamic_cast<Prx*>(::IceProxy::Ice::Object::ice_locatorCacheTimeout(timeout).get()); } - IceInternal::ProxyHandle<Prx> ice_connectionCached(bool cached) const + /** + * Obtains a proxy that is identical to this proxy, except for connection caching. + * @param b True if the new proxy should cache connections, false otherwise. + * @return A proxy with the specified caching policy. + */ + IceInternal::ProxyHandle<Prx> ice_connectionCached(bool b) const { - return dynamic_cast<Prx*>(::IceProxy::Ice::Object::ice_connectionCached(cached).get()); + return dynamic_cast<Prx*>(::IceProxy::Ice::Object::ice_connectionCached(b).get()); } - IceInternal::ProxyHandle<Prx> ice_endpointSelection(::Ice::EndpointSelectionType selection) const + /** + * Obtains a proxy that is identical to this proxy, except for the endpoint selection policy. + * @param type The new endpoint selection policy. + * @return A proxy with the specified endpoint selection policy. + */ + IceInternal::ProxyHandle<Prx> ice_endpointSelection(::Ice::EndpointSelectionType type) const { - return dynamic_cast<Prx*>(::IceProxy::Ice::Object::ice_endpointSelection(selection).get()); + return dynamic_cast<Prx*>(::IceProxy::Ice::Object::ice_endpointSelection(type).get()); } - IceInternal::ProxyHandle<Prx> ice_secure(bool secure) const + /** + * Obtains a proxy that is identical to this proxy, except for how it selects endpoints. + * @param b If true, only endpoints that use a secure transport are used by the new proxy. + * If false, the returned proxy uses both secure and insecure endpoints. + * @return A proxy with the specified security policy. + */ + IceInternal::ProxyHandle<Prx> ice_secure(bool b) const { - return dynamic_cast<Prx*>(::IceProxy::Ice::Object::ice_secure(secure).get()); + return dynamic_cast<Prx*>(::IceProxy::Ice::Object::ice_secure(b).get()); } - IceInternal::ProxyHandle<Prx> ice_preferSecure(bool preferSecure) const + /** + * Obtains a proxy that is identical to this proxy, except for its endpoint selection policy. + * @param b If true, the new proxy will use secure endpoints for invocations and only use + * insecure endpoints if an invocation cannot be made via secure endpoints. If false, the + * proxy prefers insecure endpoints to secure ones. + * @return A proxy with the specified selection policy. + */ + IceInternal::ProxyHandle<Prx> ice_preferSecure(bool b) const { - return dynamic_cast<Prx*>(::IceProxy::Ice::Object::ice_preferSecure(preferSecure).get()); + return dynamic_cast<Prx*>(::IceProxy::Ice::Object::ice_preferSecure(b).get()); } + /** + * Obtains a proxy that is identical to this proxy, except for the router. + * @param router The router for the new proxy. + * @return A proxy with the specified router. + */ IceInternal::ProxyHandle<Prx> ice_router(const ::Ice::RouterPrx& router) const { return dynamic_cast<Prx*>(::IceProxy::Ice::Object::ice_router(router).get()); } + /** + * Obtains a proxy that is identical to this proxy, except for the locator. + * @param locator The locator for the new proxy. + * @return A proxy with the specified locator. + */ IceInternal::ProxyHandle<Prx> ice_locator(const ::Ice::LocatorPrx& locator) const { return dynamic_cast<Prx*>(::IceProxy::Ice::Object::ice_locator(locator).get()); } - IceInternal::ProxyHandle<Prx> ice_collocationOptimized(bool collocated) const + /** + * Obtains a proxy that is identical to this proxy, except for collocation optimization. + * @param b True if the new proxy enables collocation optimization, false otherwise. + * @return A proxy with the specified collocation optimization. + */ + IceInternal::ProxyHandle<Prx> ice_collocationOptimized(bool b) const { - return dynamic_cast<Prx*>(::IceProxy::Ice::Object::ice_collocationOptimized(collocated).get()); + return dynamic_cast<Prx*>(::IceProxy::Ice::Object::ice_collocationOptimized(b).get()); } + /** + * Obtains a proxy that is identical to this proxy, except for the invocation timeout. + * @param timeout The new invocation timeout (in milliseconds). + * @return A proxy with the new timeout. + */ IceInternal::ProxyHandle<Prx> ice_invocationTimeout(int timeout) const { return dynamic_cast<Prx*>(::IceProxy::Ice::Object::ice_invocationTimeout(timeout).get()); } + /** + * Obtains a proxy that is identical to this proxy, but uses twoway invocations. + * @return A proxy that uses twoway invocations. + */ IceInternal::ProxyHandle<Prx> ice_twoway() const { return dynamic_cast<Prx*>(::IceProxy::Ice::Object::ice_twoway().get()); } + /** + * Obtains a proxy that is identical to this proxy, but uses oneway invocations. + * @return A proxy that uses oneway invocations. + */ IceInternal::ProxyHandle<Prx> ice_oneway() const { return dynamic_cast<Prx*>(::IceProxy::Ice::Object::ice_oneway().get()); } + /** + * Obtains a proxy that is identical to this proxy, but uses batch oneway invocations. + * @return A proxy that uses batch oneway invocations. + */ IceInternal::ProxyHandle<Prx> ice_batchOneway() const { return dynamic_cast<Prx*>(::IceProxy::Ice::Object::ice_batchOneway().get()); } + /** + * Obtains a proxy that is identical to this proxy, but uses datagram invocations. + * @return A proxy that uses datagram invocations. + */ IceInternal::ProxyHandle<Prx> ice_datagram() const { return dynamic_cast<Prx*>(::IceProxy::Ice::Object::ice_datagram().get()); } + /** + * Obtains a proxy that is identical to this proxy, but uses batch datagram invocations. + * @return A proxy that uses batch datagram invocations. + */ IceInternal::ProxyHandle<Prx> ice_batchDatagram() const { return dynamic_cast<Prx*>(::IceProxy::Ice::Object::ice_batchDatagram().get()); } - IceInternal::ProxyHandle<Prx> ice_compress(bool compress) const + /** + * Obtains a proxy that is identical to this proxy, except for compression. + * @param b True enables compression for the new proxy, false disables compression. + * @return A proxy with the specified compression setting. + */ + IceInternal::ProxyHandle<Prx> ice_compress(bool b) const { - return dynamic_cast<Prx*>(::IceProxy::Ice::Object::ice_compress(compress).get()); + return dynamic_cast<Prx*>(::IceProxy::Ice::Object::ice_compress(b).get()); } + /** + * Obtains a proxy that is identical to this proxy, except for its connection timeout setting. + * @param timeout The connection timeout for the proxy (in milliseconds). + * @return A proxy with the specified timeout. + */ IceInternal::ProxyHandle<Prx> ice_timeout(int timeout) const { return dynamic_cast<Prx*>(::IceProxy::Ice::Object::ice_timeout(timeout).get()); } + /** + * Obtains a proxy that is identical to this proxy, except for its connection ID. + * @param id The connection ID for the new proxy. An empty string removes the + * connection ID. + * @return A proxy with the specified connection ID. + */ IceInternal::ProxyHandle<Prx> ice_connectionId(const ::std::string& id) const { return dynamic_cast<Prx*>(::IceProxy::Ice::Object::ice_connectionId(id).get()); } + /** + * Obtains a proxy that is identical to this proxy, except for the encoding used to marshal + * parameters. + * @param version The encoding version to use to marshal request parameters. + * @return A proxy with the specified encoding version. + */ IceInternal::ProxyHandle<Prx> ice_encodingVersion(const ::Ice::EncodingVersion& version) const { return dynamic_cast<Prx*>(::IceProxy::Ice::Object::ice_encodingVersion(version).get()); @@ -1615,15 +3007,50 @@ public: protected: + /// \cond INTERNAL virtual ::IceProxy::Ice::Object* _newInstance() const = 0; + /// \endcond }; -ICE_API bool proxyIdentityLess(const ObjectPrx&, const ObjectPrx&); -ICE_API bool proxyIdentityEqual(const ObjectPrx&, const ObjectPrx&); - -ICE_API bool proxyIdentityAndFacetLess(const ObjectPrx&, const ObjectPrx&); -ICE_API bool proxyIdentityAndFacetEqual(const ObjectPrx&, const ObjectPrx&); - +/** + * Compares the object identities of two proxies. + * @param lhs A proxy. + * @param rhs A proxy. + * @return True if the identity in lhs compares less than the identity in rhs, false otherwise. + */ +ICE_API bool proxyIdentityLess(const ObjectPrx& lhs, const ObjectPrx& rhs); + +/** + * Compares the object identities of two proxies. + * @param lhs A proxy. + * @param rhs A proxy. + * @return True if the identity in lhs compares equal to the identity in rhs, false otherwise. + */ +ICE_API bool proxyIdentityEqual(const ObjectPrx& lhs, const ObjectPrx& rhs); + +/** + * Compares the object identities and facets of two proxies. + * @param lhs A proxy. + * @param rhs A proxy. + * @return True if the identity and facet in lhs compare less than the identity and facet + * in rhs, false otherwise. + */ +ICE_API bool proxyIdentityAndFacetLess(const ObjectPrx& lhs, const ObjectPrx& rhs); + +/** + * Compares the object identities and facets of two proxies. + * @param lhs A proxy. + * @param rhs A proxy. + * @return True if the identity and facet in lhs compare equal to the identity and facet + * in rhs, false otherwise. + */ +ICE_API bool proxyIdentityAndFacetEqual(const ObjectPrx& lhs, const ObjectPrx& rhs); + +/** + * A functor that compares the object identities of two proxies. Evaluates true if the identity in lhs + * compares less than the identity in rhs, false otherwise. + * \headerfile Ice/Ice.h + */ struct ProxyIdentityLess : std::binary_function<bool, ObjectPrx&, ObjectPrx&> { bool operator()(const ObjectPrx& lhs, const ObjectPrx& rhs) const @@ -1632,6 +3059,11 @@ struct ProxyIdentityLess : std::binary_function<bool, ObjectPrx&, ObjectPrx&> } }; +/** + * A functor that compares the object identities of two proxies. Evaluates true if the identity in lhs + * compares equal to the identity in rhs, false otherwise. + * \headerfile Ice/Ice.h + */ struct ProxyIdentityEqual : std::binary_function<bool, ObjectPrx&, ObjectPrx&> { bool operator()(const ObjectPrx& lhs, const ObjectPrx& rhs) const @@ -1640,6 +3072,11 @@ struct ProxyIdentityEqual : std::binary_function<bool, ObjectPrx&, ObjectPrx&> } }; +/** + * A functor that compares the object identities and facets of two proxies. Evaluates true if the identity + * and facet in lhs compare less than the identity and facet in rhs, false otherwise. + * \headerfile Ice/Ice.h + */ struct ProxyIdentityAndFacetLess : std::binary_function<bool, ObjectPrx&, ObjectPrx&> { bool operator()(const ObjectPrx& lhs, const ObjectPrx& rhs) const @@ -1648,6 +3085,11 @@ struct ProxyIdentityAndFacetLess : std::binary_function<bool, ObjectPrx&, Object } }; +/** + * A functor that compares the object identities and facets of two proxies. Evaluates true if the identity + * and facet in lhs compare equal to the identity and facet in rhs, false otherwise. + * \headerfile Ice/Ice.h + */ struct ProxyIdentityAndFacetEqual : std::binary_function<bool, ObjectPrx&, ObjectPrx&> { bool operator()(const ObjectPrx& lhs, const ObjectPrx& rhs) const @@ -1826,6 +3268,13 @@ uncheckedCastImpl(const ::Ice::ObjectPrx& b, const std::string& f) namespace Ice { +/** + * Downcasts a proxy after confirming the target object's type via a remote invocation. + * @param b The target proxy. + * @param context The context map for the invocation. + * @return A proxy with the requested type, or nil if the target proxy is nil or the target + * object does not support the requested type. + */ template<typename P, typename Y> inline P checkedCast(const ::IceInternal::ProxyHandle<Y>& b, const ::Ice::Context& context = ::Ice::noExplicitContext) { @@ -1833,6 +3282,11 @@ checkedCast(const ::IceInternal::ProxyHandle<Y>& b, const ::Ice::Context& contex return ::IceInternal::checkedCastHelper<typename P::element_type>(b, tag, context); } +/** + * Downcasts a proxy without confirming the target object's type via a remote invocation. + * @param b The target proxy. + * @return A proxy with the requested type. + */ template<typename P, typename Y> inline P uncheckedCast(const ::IceInternal::ProxyHandle<Y>& b) { @@ -1840,12 +3294,26 @@ uncheckedCast(const ::IceInternal::ProxyHandle<Y>& b) return ::IceInternal::uncheckedCastHelper<typename P::element_type>(b, tag); } +/** + * Downcasts a proxy after confirming the target object's type via a remote invocation. + * @param b The target proxy. + * @param f A facet name. + * @param context The context map for the invocation. + * @return A proxy with the requested type and facet, or nil if the target proxy is nil or the target + * object does not support the requested type. + */ template<typename P> inline P checkedCast(const ::Ice::ObjectPrx& b, const std::string& f, const ::Ice::Context& context = ::Ice::noExplicitContext) { return ::IceInternal::checkedCastImpl<P>(b, f, context); } +/** + * Downcasts a proxy without confirming the target object's type via a remote invocation. + * @param b The target proxy. + * @param f A facet name. + * @return A proxy with the requested type and facet. + */ template<typename P> inline P uncheckedCast(const ::Ice::ObjectPrx& b, const std::string& f) { @@ -2094,6 +3562,12 @@ private: namespace Ice { +/** + * Type-safe asynchronous callback wrapper class used for calls to + * IceProxy::Ice::Object::begin_ice_isA. + * Create a wrapper instance by calling ::Ice::newCallback_Object_ice_isA. + * \headerfile Ice/Ice.h + */ template<class T> class CallbackNC_Object_ice_isA : public Callback_Object_ice_isA_Base, public ::IceInternal::TwowayCallbackNC<T> { @@ -2110,6 +3584,7 @@ public: { } + /// \cond INTERNAL virtual void completed(const ::Ice::AsyncResultPtr& result) const { bool ret; @@ -2127,12 +3602,19 @@ public: (::IceInternal::CallbackNC<T>::_callback.get()->*_response)(ret); } } + /// \endcond private: Response _response; }; +/** + * Type-safe asynchronous callback wrapper class with cookie support used for calls to + * IceProxy::Ice::Object::begin_ice_isA. + * Create a wrapper instance by calling ::Ice::newCallback_Object_ice_isA. + * \headerfile Ice/Ice.h + */ template<class T, typename CT> class Callback_Object_ice_isA : public Callback_Object_ice_isA_Base, public ::IceInternal::TwowayCallback<T, CT> { @@ -2149,6 +3631,7 @@ public: { } + /// \cond INTERNAL virtual void completed(const ::Ice::AsyncResultPtr& result) const { bool ret; @@ -2167,12 +3650,19 @@ public: CT::dynamicCast(result->getCookie())); } } + /// \endcond private: Response _response; }; +/** + * Type-safe asynchronous callback wrapper class used for calls to + * IceProxy::Ice::Object::begin_ice_ping. + * Create a wrapper instance by calling ::Ice::newCallback_Object_ice_ping. + * \headerfile Ice/Ice.h + */ template<class T> class CallbackNC_Object_ice_ping : public Callback_Object_ice_ping_Base, public ::IceInternal::OnewayCallbackNC<T> { @@ -2190,6 +3680,12 @@ public: } }; +/** + * Type-safe asynchronous callback wrapper class with cookie support used for calls to + * IceProxy::Ice::Object::begin_ice_ping. + * Create a wrapper instance by calling ::Ice::newCallback_Object_ice_ping. + * \headerfile Ice/Ice.h + */ template<class T, typename CT> class Callback_Object_ice_ping : public Callback_Object_ice_ping_Base, public ::IceInternal::OnewayCallback<T, CT> { @@ -2207,6 +3703,12 @@ public: } }; +/** + * Type-safe asynchronous callback wrapper class used for calls to + * IceProxy::Ice::Object::begin_ice_ids. + * Create a wrapper instance by calling ::Ice::newCallback_Object_ice_ids. + * \headerfile Ice/Ice.h + */ template<class T> class CallbackNC_Object_ice_ids : public Callback_Object_ice_ids_Base, public ::IceInternal::TwowayCallbackNC<T> { @@ -2223,6 +3725,7 @@ public: { } + /// \cond INTERNAL virtual void completed(const ::Ice::AsyncResultPtr& result) const { ::std::vector< ::std::string> ret; @@ -2240,12 +3743,19 @@ public: (::IceInternal::CallbackNC<T>::_callback.get()->*_response)(ret); } } + /// \endcond private: Response _response; }; +/** + * Type-safe asynchronous callback wrapper class with cookie support used for calls to + * IceProxy::Ice::Object::begin_ice_ids. + * Create a wrapper instance by calling ::Ice::newCallback_Object_ice_ids. + * \headerfile Ice/Ice.h + */ template<class T, typename CT> class Callback_Object_ice_ids : public Callback_Object_ice_ids_Base, public ::IceInternal::TwowayCallback<T, CT> { @@ -2262,6 +3772,7 @@ public: { } + /// \cond INTERNAL virtual void completed(const ::Ice::AsyncResultPtr& result) const { ::std::vector< ::std::string> ret; @@ -2280,12 +3791,19 @@ public: CT::dynamicCast(result->getCookie())); } } + /// \endcond private: Response _response; }; +/** + * Type-safe asynchronous callback wrapper class used for calls to + * IceProxy::Ice::Object::begin_ice_id. + * Create a wrapper instance by calling ::Ice::newCallback_Object_ice_id. + * \headerfile Ice/Ice.h + */ template<class T> class CallbackNC_Object_ice_id : public Callback_Object_ice_id_Base, public ::IceInternal::TwowayCallbackNC<T> { @@ -2302,6 +3820,7 @@ public: { } + /// \cond INTERNAL virtual void completed(const ::Ice::AsyncResultPtr& result) const { ::std::string ret; @@ -2319,12 +3838,19 @@ public: (::IceInternal::CallbackNC<T>::_callback.get()->*_response)(ret); } } + /// \endcond private: Response _response; }; +/** + * Type-safe asynchronous callback wrapper class with cookie support used for calls to + * IceProxy::Ice::Object::begin_ice_id. + * Create a wrapper instance by calling ::Ice::newCallback_Object_ice_id. + * \headerfile Ice/Ice.h + */ template<class T, typename CT> class Callback_Object_ice_id : public Callback_Object_ice_id_Base, public ::IceInternal::TwowayCallback<T, CT> { @@ -2341,6 +3867,7 @@ public: { } + /// \cond INTERNAL virtual void completed(const ::Ice::AsyncResultPtr& result) const { ::std::string ret; @@ -2359,12 +3886,19 @@ public: CT::dynamicCast(result->getCookie())); } } + /// \endcond private: Response _response; }; +/** + * Type-safe asynchronous callback wrapper class used for calls to + * IceProxy::Ice::Object::begin_ice_invoke. + * Create a wrapper instance by calling ::Ice::newCallback_Object_ice_invoke. + * \headerfile Ice/Ice.h + */ template<class T> class CallbackNC_Object_ice_invoke : public Callback_Object_ice_invoke_Base, public ::IceInternal::TwowayCallbackNC<T> { @@ -2387,6 +3921,7 @@ public: { } + /// \cond INTERNAL virtual void completed(const ::Ice::AsyncResultPtr& result) const { if(_response) @@ -2423,6 +3958,7 @@ public: } } } + /// \endcond private: @@ -2430,6 +3966,12 @@ private: ResponseArray _responseArray; }; +/** + * Type-safe asynchronous callback wrapper class with cookie support used for calls to + * IceProxy::Ice::Object::begin_ice_invoke. + * Create a wrapper instance by calling ::Ice::newCallback_Object_ice_invoke. + * \headerfile Ice/Ice.h + */ template<class T, typename CT> class Callback_Object_ice_invoke : public Callback_Object_ice_invoke_Base, public ::IceInternal::TwowayCallback<T, CT> { @@ -2452,6 +3994,7 @@ public: { } + /// \cond INTERNAL virtual void completed(const ::Ice::AsyncResultPtr& result) const { if(_response) @@ -2493,6 +4036,7 @@ public: } } } + /// \endcond private: @@ -2500,6 +4044,12 @@ private: ResponseArray _responseArray; }; +/** + * Type-safe asynchronous callback wrapper class used for calls to + * IceProxy::Ice::Object::begin_ice_getConnection. + * Create a wrapper instance by calling ::Ice::newCallback_Object_ice_getConnection. + * \headerfile Ice/Ice.h + */ template<class T> class CallbackNC_Object_ice_getConnection : public Callback_Object_ice_getConnection_Base, public ::IceInternal::CallbackNC<T> @@ -2517,6 +4067,7 @@ public: { } + /// \cond INTERNAL virtual void completed(const ::Ice::AsyncResultPtr& result) const { ::Ice::ConnectionPtr ret; @@ -2534,12 +4085,19 @@ public: (::IceInternal::CallbackNC<T>::_callback.get()->*_response)(ret); } } + /// \endcond private: Response _response; }; +/** + * Type-safe asynchronous callback wrapper class with cookie support used for calls to + * IceProxy::Ice::Object::begin_ice_getConnection. + * Create a wrapper instance by calling ::Ice::newCallback_Object_ice_getConnection. + * \headerfile Ice/Ice.h + */ template<class T, typename CT> class Callback_Object_ice_getConnection : public Callback_Object_ice_getConnection_Base, public ::IceInternal::Callback<T, CT> @@ -2557,6 +4115,7 @@ public: { } + /// \cond INTERNAL virtual void completed(const ::Ice::AsyncResultPtr& result) const { ::Ice::ConnectionPtr ret; @@ -2575,12 +4134,19 @@ public: CT::dynamicCast(result->getCookie())); } } + /// \endcond private: Response _response; }; +/** + * Type-safe asynchronous callback wrapper class used for calls to + * IceProxy::Ice::Object::begin_ice_flushBatchRequests. + * Create a wrapper instance by calling ::Ice::newCallback_Object_ice_flushBatchRequests. + * \headerfile Ice/Ice.h + */ template<class T> class CallbackNC_Object_ice_flushBatchRequests : public Callback_Object_ice_flushBatchRequests_Base, public ::IceInternal::OnewayCallbackNC<T> @@ -2598,6 +4164,12 @@ public: } }; +/** + * Type-safe asynchronous callback wrapper class with cookie support used for calls to + * IceProxy::Ice::Object::begin_ice_flushBatchRequests. + * Create a wrapper instance by calling ::Ice::newCallback_Object_ice_flushBatchRequests. + * \headerfile Ice/Ice.h + */ template<class T, typename CT> class Callback_Object_ice_flushBatchRequests : public Callback_Object_ice_flushBatchRequests_Base, public ::IceInternal::OnewayCallback<T, CT> @@ -2615,6 +4187,14 @@ public: } }; +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param cb The success method of the callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_isA. + */ template<class T> Callback_Object_ice_isAPtr newCallback_Object_ice_isA(const IceUtil::Handle<T>& instance, void (T::*cb)(bool), @@ -2624,6 +4204,14 @@ newCallback_Object_ice_isA(const IceUtil::Handle<T>& instance, return new CallbackNC_Object_ice_isA<T>(instance, cb, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param cb The success method of the callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_isA. + */ template<class T, typename CT> Callback_Object_ice_isAPtr newCallback_Object_ice_isA(const IceUtil::Handle<T>& instance, void (T::*cb)(bool, const CT&), @@ -2633,6 +4221,13 @@ newCallback_Object_ice_isA(const IceUtil::Handle<T>& instance, return new Callback_Object_ice_isA<T, CT>(instance, cb, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_isA. + */ template<class T> Callback_Object_ice_isAPtr newCallback_Object_ice_isA(const IceUtil::Handle<T>& instance, void (T::*excb)(const ::Ice::Exception&), @@ -2641,6 +4236,13 @@ newCallback_Object_ice_isA(const IceUtil::Handle<T>& instance, return new CallbackNC_Object_ice_isA<T>(instance, 0, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_isA. + */ template<class T, typename CT> Callback_Object_ice_isAPtr newCallback_Object_ice_isA(const IceUtil::Handle<T>& instance, void (T::*excb)(const ::Ice::Exception&, const CT&), @@ -2649,6 +4251,14 @@ newCallback_Object_ice_isA(const IceUtil::Handle<T>& instance, return new Callback_Object_ice_isA<T, CT>(instance, 0, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param cb The success method of the callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_isA. + */ template<class T> Callback_Object_ice_isAPtr newCallback_Object_ice_isA(T* instance, void (T::*cb)(bool), @@ -2658,6 +4268,14 @@ newCallback_Object_ice_isA(T* instance, return new CallbackNC_Object_ice_isA<T>(instance, cb, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param cb The success method of the callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_isA. + */ template<class T, typename CT> Callback_Object_ice_isAPtr newCallback_Object_ice_isA(T* instance, void (T::*cb)(bool, const CT&), @@ -2667,6 +4285,13 @@ newCallback_Object_ice_isA(T* instance, return new Callback_Object_ice_isA<T, CT>(instance, cb, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_isA. + */ template<class T> Callback_Object_ice_isAPtr newCallback_Object_ice_isA(T* instance, void (T::*excb)(const ::Ice::Exception&), @@ -2675,6 +4300,13 @@ newCallback_Object_ice_isA(T* instance, return new CallbackNC_Object_ice_isA<T>(instance, 0, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_isA. + */ template<class T, typename CT> Callback_Object_ice_isAPtr newCallback_Object_ice_isA(T* instance, void (T::*excb)(const ::Ice::Exception&, const CT&), @@ -2683,6 +4315,14 @@ newCallback_Object_ice_isA(T* instance, return new Callback_Object_ice_isA<T, CT>(instance, 0, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param cb The success method of the callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_ping. + */ template<class T> Callback_Object_ice_pingPtr newCallback_Object_ice_ping(const IceUtil::Handle<T>& instance, void (T::*cb)(), @@ -2692,6 +4332,14 @@ newCallback_Object_ice_ping(const IceUtil::Handle<T>& instance, return new CallbackNC_Object_ice_ping<T>(instance, cb, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param cb The success method of the callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_ping. + */ template<class T, typename CT> Callback_Object_ice_pingPtr newCallback_Object_ice_ping(const IceUtil::Handle<T>& instance, void (T::*cb)(const CT&), @@ -2701,6 +4349,13 @@ newCallback_Object_ice_ping(const IceUtil::Handle<T>& instance, return new Callback_Object_ice_ping<T, CT>(instance, cb, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_ping. + */ template<class T> Callback_Object_ice_pingPtr newCallback_Object_ice_ping(const IceUtil::Handle<T>& instance, void (T::*excb)(const ::Ice::Exception&), @@ -2709,6 +4364,13 @@ newCallback_Object_ice_ping(const IceUtil::Handle<T>& instance, return new CallbackNC_Object_ice_ping<T>(instance, 0, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_ping. + */ template<class T, typename CT> Callback_Object_ice_pingPtr newCallback_Object_ice_ping(const IceUtil::Handle<T>& instance, void (T::*excb)(const ::Ice::Exception&, const CT&), @@ -2717,6 +4379,14 @@ newCallback_Object_ice_ping(const IceUtil::Handle<T>& instance, return new Callback_Object_ice_ping<T, CT>(instance, 0, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param cb The success method of the callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_ping. + */ template<class T> Callback_Object_ice_pingPtr newCallback_Object_ice_ping(T* instance, void (T::*cb)(), @@ -2726,6 +4396,14 @@ newCallback_Object_ice_ping(T* instance, return new CallbackNC_Object_ice_ping<T>(instance, cb, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param cb The success method of the callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_ping. + */ template<class T, typename CT> Callback_Object_ice_pingPtr newCallback_Object_ice_ping(T* instance, void (T::*cb)(const CT&), @@ -2735,6 +4413,13 @@ newCallback_Object_ice_ping(T* instance, return new Callback_Object_ice_ping<T, CT>(instance, cb, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_ping. + */ template<class T> Callback_Object_ice_pingPtr newCallback_Object_ice_ping(T* instance, void (T::*excb)(const ::Ice::Exception&), @@ -2743,6 +4428,13 @@ newCallback_Object_ice_ping(T* instance, return new CallbackNC_Object_ice_ping<T>(instance, 0, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_ping. + */ template<class T, typename CT> Callback_Object_ice_pingPtr newCallback_Object_ice_ping(T* instance, void (T::*excb)(const ::Ice::Exception&, const CT&), @@ -2751,6 +4443,14 @@ newCallback_Object_ice_ping(T* instance, return new Callback_Object_ice_ping<T, CT>(instance, 0, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param cb The success method of the callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_ids. + */ template<class T> Callback_Object_ice_idsPtr newCallback_Object_ice_ids(const IceUtil::Handle<T>& instance, void (T::*cb)(const ::std::vector< ::std::string>&), @@ -2760,6 +4460,14 @@ newCallback_Object_ice_ids(const IceUtil::Handle<T>& instance, return new CallbackNC_Object_ice_ids<T>(instance, cb, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param cb The success method of the callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_ids. + */ template<class T, typename CT> Callback_Object_ice_idsPtr newCallback_Object_ice_ids(const IceUtil::Handle<T>& instance, void (T::*cb)(const ::std::vector< ::std::string>&, const CT&), @@ -2769,6 +4477,13 @@ newCallback_Object_ice_ids(const IceUtil::Handle<T>& instance, return new Callback_Object_ice_ids<T, CT>(instance, cb, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_ids. + */ template<class T> Callback_Object_ice_idsPtr newCallback_Object_ice_ids(const IceUtil::Handle<T>& instance, void (T::*excb)(const ::Ice::Exception&), @@ -2777,6 +4492,13 @@ newCallback_Object_ice_ids(const IceUtil::Handle<T>& instance, return new CallbackNC_Object_ice_ids<T>(instance, 0, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_ids. + */ template<class T, typename CT> Callback_Object_ice_idsPtr newCallback_Object_ice_ids(const IceUtil::Handle<T>& instance, void (T::*excb)(const ::Ice::Exception&, const CT&), @@ -2785,6 +4507,14 @@ newCallback_Object_ice_ids(const IceUtil::Handle<T>& instance, return new Callback_Object_ice_ids<T, CT>(instance, 0, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param cb The success method of the callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_ids. + */ template<class T> Callback_Object_ice_idsPtr newCallback_Object_ice_ids(T* instance, void (T::*cb)(const ::std::vector< ::std::string>&), @@ -2794,6 +4524,14 @@ newCallback_Object_ice_ids(T* instance, return new CallbackNC_Object_ice_ids<T>(instance, cb, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param cb The success method of the callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_ids. + */ template<class T, typename CT> Callback_Object_ice_idsPtr newCallback_Object_ice_ids(T* instance, void (T::*cb)(const ::std::vector< ::std::string>&, const CT&), @@ -2803,6 +4541,13 @@ newCallback_Object_ice_ids(T* instance, return new Callback_Object_ice_ids<T, CT>(instance, cb, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_ids. + */ template<class T> Callback_Object_ice_idsPtr newCallback_Object_ice_ids(T* instance, void (T::*excb)(const ::Ice::Exception&), @@ -2811,6 +4556,13 @@ newCallback_Object_ice_ids(T* instance, return new CallbackNC_Object_ice_ids<T>(instance, 0, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_ids. + */ template<class T, typename CT> Callback_Object_ice_idsPtr newCallback_Object_ice_ids(T* instance, void (T::*excb)(const ::Ice::Exception&, const CT&), @@ -2819,6 +4571,14 @@ newCallback_Object_ice_ids(T* instance, return new Callback_Object_ice_ids<T, CT>(instance, 0, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param cb The success method of the callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_id. + */ template<class T> Callback_Object_ice_idPtr newCallback_Object_ice_id(const IceUtil::Handle<T>& instance, void (T::*cb)(const ::std::string&), @@ -2828,6 +4588,14 @@ newCallback_Object_ice_id(const IceUtil::Handle<T>& instance, return new CallbackNC_Object_ice_id<T>(instance, cb, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param cb The success method of the callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_id. + */ template<class T, typename CT> Callback_Object_ice_idPtr newCallback_Object_ice_id(const IceUtil::Handle<T>& instance, void (T::*cb)(const ::std::string&, const CT&), @@ -2837,6 +4605,13 @@ newCallback_Object_ice_id(const IceUtil::Handle<T>& instance, return new Callback_Object_ice_id<T, CT>(instance, cb, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_id. + */ template<class T> Callback_Object_ice_idPtr newCallback_Object_ice_id(const IceUtil::Handle<T>& instance, void (T::*excb)(const ::Ice::Exception&), @@ -2845,6 +4620,13 @@ newCallback_Object_ice_id(const IceUtil::Handle<T>& instance, return new CallbackNC_Object_ice_id<T>(instance, 0, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_id. + */ template<class T, typename CT> Callback_Object_ice_idPtr newCallback_Object_ice_id(const IceUtil::Handle<T>& instance, void (T::*excb)(const ::Ice::Exception&, const CT&), @@ -2853,6 +4635,14 @@ newCallback_Object_ice_id(const IceUtil::Handle<T>& instance, return new Callback_Object_ice_id<T, CT>(instance, 0, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param cb The success method of the callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_id. + */ template<class T> Callback_Object_ice_idPtr newCallback_Object_ice_id(T* instance, void (T::*cb)(const ::std::string&), @@ -2862,6 +4652,14 @@ newCallback_Object_ice_id(T* instance, return new CallbackNC_Object_ice_id<T>(instance, cb, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param cb The success method of the callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_id. + */ template<class T, typename CT> Callback_Object_ice_idPtr newCallback_Object_ice_id(T* instance, void (T::*cb)(const ::std::string&, const CT&), @@ -2871,6 +4669,13 @@ newCallback_Object_ice_id(T* instance, return new Callback_Object_ice_id<T, CT>(instance, cb, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_id. + */ template<class T> Callback_Object_ice_idPtr newCallback_Object_ice_id(T* instance, void (T::*excb)(const ::Ice::Exception&), @@ -2879,6 +4684,13 @@ newCallback_Object_ice_id(T* instance, return new CallbackNC_Object_ice_id<T>(instance, 0, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_id. + */ template<class T, typename CT> Callback_Object_ice_idPtr newCallback_Object_ice_id(T* instance, void (T::*excb)(const ::Ice::Exception&, const CT&), @@ -2887,6 +4699,14 @@ newCallback_Object_ice_id(T* instance, return new Callback_Object_ice_id<T, CT>(instance, 0, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param cb The success method of the callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_invoke. + */ template<class T> Callback_Object_ice_invokePtr newCallback_Object_ice_invoke(const IceUtil::Handle<T>& instance, void (T::*cb)(bool, const std::vector<Ice::Byte>&), @@ -2896,6 +4716,14 @@ newCallback_Object_ice_invoke(const IceUtil::Handle<T>& instance, return new CallbackNC_Object_ice_invoke<T>(instance, cb, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param cb The success method of the callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_invoke. + */ template<class T> Callback_Object_ice_invokePtr newCallback_Object_ice_invoke(const IceUtil::Handle<T>& instance, void (T::*cb)(bool, const std::pair<const Byte*, const Byte*>&), @@ -2905,6 +4733,14 @@ newCallback_Object_ice_invoke(const IceUtil::Handle<T>& instance, return new CallbackNC_Object_ice_invoke<T>(instance, cb, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param cb The success method of the callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_invoke. + */ template<class T, typename CT> Callback_Object_ice_invokePtr newCallback_Object_ice_invoke(const IceUtil::Handle<T>& instance, void (T::*cb)(bool, const std::vector<Ice::Byte>&, const CT&), @@ -2914,6 +4750,14 @@ newCallback_Object_ice_invoke(const IceUtil::Handle<T>& instance, return new Callback_Object_ice_invoke<T, CT>(instance, cb, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param cb The success method of the callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_invoke. + */ template<class T, typename CT> Callback_Object_ice_invokePtr newCallback_Object_ice_invoke(const IceUtil::Handle<T>& instance, void (T::*cb)(bool, const std::pair<const Byte*, const Byte*>&, @@ -2924,6 +4768,13 @@ newCallback_Object_ice_invoke(const IceUtil::Handle<T>& instance, return new Callback_Object_ice_invoke<T, CT>(instance, cb, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_invoke. + */ template<class T> Callback_Object_ice_invokePtr newCallback_Object_ice_invoke(const IceUtil::Handle<T>& instance, void (T::*excb)(const ::Ice::Exception&), @@ -2932,6 +4783,13 @@ newCallback_Object_ice_invoke(const IceUtil::Handle<T>& instance, return new CallbackNC_Object_ice_invoke<T>(instance, 0, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_invoke. + */ template<class T, typename CT> Callback_Object_ice_invokePtr newCallback_Object_ice_invoke(const IceUtil::Handle<T>& instance, void (T::*excb)(const ::Ice::Exception&, const CT&), @@ -2940,6 +4798,14 @@ newCallback_Object_ice_invoke(const IceUtil::Handle<T>& instance, return new Callback_Object_ice_invoke<T, CT>(instance, 0, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param cb The success method of the callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_invoke. + */ template<class T> Callback_Object_ice_invokePtr newCallback_Object_ice_invoke(T* instance, void (T::*cb)(bool, const std::vector<Ice::Byte>&), @@ -2949,6 +4815,14 @@ newCallback_Object_ice_invoke(T* instance, return new CallbackNC_Object_ice_invoke<T>(instance, cb, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param cb The success method of the callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_invoke. + */ template<class T> Callback_Object_ice_invokePtr newCallback_Object_ice_invoke(T* instance, void (T::*cb)(bool, const std::pair<const Byte*, const Byte*>&), @@ -2958,6 +4832,14 @@ newCallback_Object_ice_invoke(T* instance, return new CallbackNC_Object_ice_invoke<T>(instance, cb, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param cb The success method of the callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_invoke. + */ template<class T, typename CT> Callback_Object_ice_invokePtr newCallback_Object_ice_invoke(T* instance, void (T::*cb)(bool, const std::vector<Ice::Byte>&, const CT&), @@ -2967,6 +4849,14 @@ newCallback_Object_ice_invoke(T* instance, return new Callback_Object_ice_invoke<T, CT>(instance, cb, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param cb The success method of the callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_invoke. + */ template<class T, typename CT> Callback_Object_ice_invokePtr newCallback_Object_ice_invoke(T* instance, void (T::*cb)(bool, const std::pair<const Byte*, const Byte*>&, const CT&), @@ -2976,6 +4866,13 @@ newCallback_Object_ice_invoke(T* instance, return new Callback_Object_ice_invoke<T, CT>(instance, cb, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_invoke. + */ template<class T> Callback_Object_ice_invokePtr newCallback_Object_ice_invoke(T* instance, void (T::*excb)(const ::Ice::Exception&), @@ -2985,6 +4882,13 @@ newCallback_Object_ice_invoke(T* instance, instance, static_cast<void (T::*)(bool, const std::vector<Ice::Byte>&)>(0), excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_invoke. + */ template<class T, typename CT> Callback_Object_ice_invokePtr newCallback_Object_ice_invoke(T* instance, void (T::*excb)(const ::Ice::Exception&, const CT&), @@ -2994,6 +4898,13 @@ newCallback_Object_ice_invoke(T* instance, instance, static_cast<void (T::*)(bool, const std::vector<Ice::Byte>&, const CT&)>(0), excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param cb The success method of the callback object. + * @param excb The exception method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_getConnection. + */ template<class T> Callback_Object_ice_getConnectionPtr newCallback_Object_ice_getConnection(const IceUtil::Handle<T>& instance, void (T::*cb)(const ::Ice::ConnectionPtr&), @@ -3002,6 +4913,13 @@ newCallback_Object_ice_getConnection(const IceUtil::Handle<T>& instance, return new CallbackNC_Object_ice_getConnection<T>(instance, cb, excb, 0); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param cb The success method of the callback object. + * @param excb The exception method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_getConnection. + */ template<class T, typename CT> Callback_Object_ice_getConnectionPtr newCallback_Object_ice_getConnection(const IceUtil::Handle<T>& instance, void (T::*cb)(const ::Ice::ConnectionPtr&, const CT&), @@ -3010,6 +4928,13 @@ newCallback_Object_ice_getConnection(const IceUtil::Handle<T>& instance, return new Callback_Object_ice_getConnection<T, CT>(instance, cb, excb, 0); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param cb The success method of the callback object. + * @param excb The exception method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_getConnection. + */ template<class T> Callback_Object_ice_getConnectionPtr newCallback_Object_ice_getConnection(T* instance, void (T::*cb)(const ::Ice::ConnectionPtr&), @@ -3018,6 +4943,13 @@ newCallback_Object_ice_getConnection(T* instance, return new CallbackNC_Object_ice_getConnection<T>(instance, cb, excb, 0); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param cb The success method of the callback object. + * @param excb The exception method of the callback object. + * @return An object that can be passed to an asynchronous invocation of IceProxy::Ice::Object::begin_ice_getConnection. + */ template<class T, typename CT> Callback_Object_ice_getConnectionPtr newCallback_Object_ice_getConnection(T* instance, void (T::*cb)(const ::Ice::ConnectionPtr&, const CT&), @@ -3026,6 +4958,14 @@ newCallback_Object_ice_getConnection(T* instance, return new Callback_Object_ice_getConnection<T, CT>(instance, cb, excb, 0); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of + * IceProxy::Ice::Object::begin_ice_flushBatchRequests. + */ template<class T> Callback_Object_ice_flushBatchRequestsPtr newCallback_Object_ice_flushBatchRequests(const IceUtil::Handle<T>& instance, void (T::*excb)(const ::Ice::Exception&), @@ -3034,6 +4974,14 @@ newCallback_Object_ice_flushBatchRequests(const IceUtil::Handle<T>& instance, return new CallbackNC_Object_ice_flushBatchRequests<T>(instance, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of + * IceProxy::Ice::Object::begin_ice_flushBatchRequests. + */ template<class T, typename CT> Callback_Object_ice_flushBatchRequestsPtr newCallback_Object_ice_flushBatchRequests(const IceUtil::Handle<T>& instance, void (T::*excb)(const ::Ice::Exception&, const CT&), @@ -3042,6 +4990,14 @@ newCallback_Object_ice_flushBatchRequests(const IceUtil::Handle<T>& instance, return new Callback_Object_ice_flushBatchRequests<T, CT>(instance, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of + * IceProxy::Ice::Object::begin_ice_flushBatchRequests. + */ template<class T> Callback_Object_ice_flushBatchRequestsPtr newCallback_Object_ice_flushBatchRequests(T* instance, void (T::*excb)(const ::Ice::Exception&), @@ -3050,6 +5006,14 @@ newCallback_Object_ice_flushBatchRequests(T* instance, return new CallbackNC_Object_ice_flushBatchRequests<T>(instance, excb, sentcb); } +/** + * Creates a callback wrapper instance that delegates to your object. + * @param instance The callback object. + * @param excb The exception method of the callback object. + * @param sentcb The sent method of the callback object. + * @return An object that can be passed to an asynchronous invocation of + * IceProxy::Ice::Object::begin_ice_flushBatchRequests. + */ template<class T, typename CT> Callback_Object_ice_flushBatchRequestsPtr newCallback_Object_ice_flushBatchRequests(T* instance, void (T::*excb)(const ::Ice::Exception&, const CT&), diff --git a/cpp/include/Ice/ProxyF.h b/cpp/include/Ice/ProxyF.h index 7fcbb158047..52d2d8b0bd4 100644 --- a/cpp/include/Ice/ProxyF.h +++ b/cpp/include/Ice/ProxyF.h @@ -18,7 +18,9 @@ namespace Ice { class ObjectPrx; +/// \cond INTERNAL using ObjectPrxPtr = ::std::shared_ptr<ObjectPrx>; +/// \endcond } diff --git a/cpp/include/Ice/ProxyHandle.h b/cpp/include/Ice/ProxyHandle.h index cff7f47e0c5..ae80bcffddc 100644 --- a/cpp/include/Ice/ProxyHandle.h +++ b/cpp/include/Ice/ProxyHandle.h @@ -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; } diff --git a/cpp/include/Ice/RegisterPlugins.h b/cpp/include/Ice/RegisterPlugins.h index 1a50b70d05d..2b49e8fe0fe 100644 --- a/cpp/include/Ice/RegisterPlugins.h +++ b/cpp/include/Ice/RegisterPlugins.h @@ -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 diff --git a/cpp/include/Ice/Service.h b/cpp/include/Ice/Service.h index c1c3cd02b5a..e7df3e470da 100644 --- a/cpp/include/Ice/Service.h +++ b/cpp/include/Ice/Service.h @@ -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 diff --git a/cpp/include/Ice/SliceChecksums.h b/cpp/include/Ice/SliceChecksums.h index e363f493b02..477b9a20bd7 100644 --- a/cpp/include/Ice/SliceChecksums.h +++ b/cpp/include/Ice/SliceChecksums.h @@ -15,6 +15,10 @@ namespace Ice { +/** + * Obtains the map containing the checksums for Slice definitions. + * @return The checksum map. + */ ICE_API SliceChecksumDict sliceChecksums(); } diff --git a/cpp/include/Ice/SlicedData.h b/cpp/include/Ice/SlicedData.h index b4837274b19..28587e529c3 100644 --- a/cpp/include/Ice/SlicedData.h +++ b/cpp/include/Ice/SlicedData.h @@ -17,48 +17,50 @@ namespace Ice { -// -// SliceInfo encapsulates the details of a slice for an unknown class or exception type. -// +/** + * Encapsulates the details of a slice for an unknown class or exception type. + * \headerfile Ice/Ice.h + */ struct ICE_API SliceInfo #ifndef ICE_CPP11_MAPPING : public ::IceUtil::Shared #endif { - // - // The Slice type ID for this slice. - // + /** + * The Slice type ID for this slice. + */ ::std::string typeId; - // - // The Slice compact type ID for this slice. - // + /** + * The Slice compact type ID for this slice. + */ int compactId; - // - // The encoded bytes for this slice, including the leading size integer. - // + /** + * The encoded bytes for this slice, including the leading size integer. + */ ::std::vector<Byte> bytes; - // - // The class instances referenced by this slice. - // + /** + * The class instances referenced by this slice. + */ ::std::vector<ValuePtr> instances; - // - // Whether or not the slice contains optional members. - // + /** + * Whether or not the slice contains optional members. + */ bool hasOptionalMembers; - // - // Whether or not this is the last slice. - // + /** + * Whether or not this is the last slice. + */ bool isLastSlice; }; -// -// SlicedData holds the slices of unknown types. -// +/** + * Holds the slices of unknown types. + * \headerfile Ice/Ice.h + */ class ICE_API SlicedData #ifndef ICE_CPP11_MAPPING : public ::IceUtil::Shared @@ -72,22 +74,26 @@ public: SlicedData(const SliceInfoSeq&); + /** The slices of unknown types. */ const SliceInfoSeq slices; - // - // Clear the slices to break potential cyclic references. - // + /** + * Clears the slices to break potential cyclic references. + */ void clear(); #ifndef ICE_CPP11_MAPPING + /// \cond INTERNAL void _iceGcVisitMembers(IceInternal::GCVisitor&); + /// \endcond #endif }; -// -// Unknown sliced object holds instance of unknown type. -// +/** + * Represents an instance of an unknown type. + * \headerfile Ice/Ice.h + */ class ICE_API UnknownSlicedValue : #ifdef ICE_CPP11_MAPPING public Value @@ -97,26 +103,67 @@ class ICE_API UnknownSlicedValue : { public: - UnknownSlicedValue(const std::string&); + /** + * Constructs the placeholder instance. + * @param unknownTypeId The Slice type ID of the unknown value. + */ + UnknownSlicedValue(const std::string& unknownTypeId); #ifdef ICE_CPP11_MAPPING + /** + * Obtains the sliced data associated with this instance. + * @return The sliced data if the value has a preserved-slice base class and has been sliced during + * unmarshaling of the value, or nil otherwise. + */ virtual SlicedDataPtr ice_getSlicedData() const override; + + /** + * Determine the Slice type ID associated with this instance. + * @return The type ID supplied to the constructor. + */ virtual std::string ice_id() const override; + + /** + * Clones this object. + * @return A new instance. + */ std::shared_ptr<UnknownSlicedValue> ice_clone() const; + /// \cond STREAM virtual void _iceWrite(::Ice::OutputStream*) const override; virtual void _iceRead(::Ice::InputStream*) override; + /// \endcond protected: + /// \cond INTERNAL virtual std::shared_ptr<Value> _iceCloneImpl() const override; + /// \endcond + #else + + /** + * Obtains the sliced data associated with this instance. + * @return The sliced data if the value has a preserved-slice base class and has been sliced during + * unmarshaling of the value, or nil otherwise. + */ virtual SlicedDataPtr ice_getSlicedData() const; - virtual const std::string& ice_id(const Current& = Ice::emptyCurrent) const; + /** + * Determine the Slice type ID associated with this instance. + * @param current The current object for this invocation. + * @return The type ID supplied to the constructor. + */ + virtual const std::string& ice_id(const Current& current = Ice::emptyCurrent) const; + + /// \cond INTERNAL virtual void _iceGcVisitMembers(IceInternal::GCVisitor&); + /// \endcond + + /// \cond STREAM virtual void _iceWrite(::Ice::OutputStream*) const; virtual void _iceRead(::Ice::InputStream*); + /// \endcond #endif private: diff --git a/cpp/include/Ice/SlicedDataF.h b/cpp/include/Ice/SlicedDataF.h index aa14576ce4a..89138543041 100644 --- a/cpp/include/Ice/SlicedDataF.h +++ b/cpp/include/Ice/SlicedDataF.h @@ -21,9 +21,11 @@ class SlicedData; class UnknownSlicedValue; #ifdef ICE_CPP11_MAPPING +/// \cond INTERNAL using SliceInfoPtr = ::std::shared_ptr<SliceInfo>; using SlicedDataPtr = ::std::shared_ptr<SlicedData>; using UnknownSlicedValuePtr = ::std::shared_ptr<UnknownSlicedValue>; +/// \endcond #else ICE_API IceUtil::Shared* upCast(SliceInfo*); typedef IceInternal::Handle<SliceInfo> SliceInfoPtr; @@ -35,6 +37,7 @@ ICE_API IceUtil::Shared* upCast(UnknownSlicedValue*); typedef IceInternal::Handle<UnknownSlicedValue> UnknownSlicedValuePtr; #endif +/** The slices of unknown types. */ typedef ::std::vector<SliceInfoPtr> SliceInfoSeq; } diff --git a/cpp/include/Ice/StreamHelpers.h b/cpp/include/Ice/StreamHelpers.h index e4ef705b605..0c31dc1399b 100644 --- a/cpp/include/Ice/StreamHelpers.h +++ b/cpp/include/Ice/StreamHelpers.h @@ -20,65 +20,95 @@ namespace Ice { -// The stream helper category -// Allows streams to select the desired StreamHelper for a given streamable object; -// see StreamableTraits below. -// +/// \cond STREAM +/** + * The stream helper category allows streams to select the desired StreamHelper for a given streamable object. + */ typedef int StreamHelperCategory; +/** For types with no specialized trait. */ const StreamHelperCategory StreamHelperCategoryUnknown = 0; +/** For built-in types. */ const StreamHelperCategory StreamHelperCategoryBuiltin = 1; +/** For struct types. */ const StreamHelperCategory StreamHelperCategoryStruct = 2; -const StreamHelperCategory StreamHelperCategoryStructClass = 3; // struct with cpp:class metadata +/** For struct types with cpp:class metadata. */ +const StreamHelperCategory StreamHelperCategoryStructClass = 3; +/** For enum types. */ const StreamHelperCategory StreamHelperCategoryEnum = 4; +/** For sequence types. */ const StreamHelperCategory StreamHelperCategorySequence = 5; +/** For dictionary types. */ const StreamHelperCategory StreamHelperCategoryDictionary = 6; +/** For proxy types. */ const StreamHelperCategory StreamHelperCategoryProxy = 7; +/** For class types. */ const StreamHelperCategory StreamHelperCategoryClass = 8; +/** For exception types. */ const StreamHelperCategory StreamHelperCategoryUserException = 9; -// -// The optional format. -// -// Optional data members and parameters are encoded with a specific -// optional format. This optional format describes how the data is encoded -// and how it can be skipped by the unmarshaling code if the optional -// isn't known to the receiver. -// - +/** + * The optional format. + * + * Optional data members and parameters are encoded with a specific + * optional format. This optional format describes how the data is encoded + * and how it can be skipped by the unmarshaling code if the optional ID + * isn't known to the receiver. + */ #ifdef ICE_CPP11_MAPPING enum class OptionalFormat : unsigned char { - F1 = 0, // Fixed 1-byte encoding - F2 = 1, // Fixed 2 bytes encoding - F4 = 2, // Fixed 4 bytes encoding - F8 = 3, // Fixed 8 bytes encoding - Size = 4, // "Size encoding" on 1 to 5 bytes, e.g. enum, class identifier - VSize = 5, // "Size encoding" on 1 to 5 bytes followed by data, e.g. string, fixed size - // struct, or containers whose size can be computed prior to marshaling - FSize = 6, // Fixed size on 4 bytes followed by data, e.g. variable-size struct, container. + /** Fixed 1-byte encoding. */ + F1 = 0, + /** Fixed 2-byte encoding. */ + F2 = 1, + /** Fixed 4-byte encoding. */ + F4 = 2, + /** Fixed 8-byte encoding. */ + F8 = 3, + /** "Size encoding" using 1 to 5 bytes, e.g., enum, class identifier. */ + Size = 4, + /** + * "Size encoding" using 1 to 5 bytes followed by data, e.g., string, fixed size + * struct, or containers whose size can be computed prior to marshaling. + */ + VSize = 5, + /** Fixed size using 4 bytes followed by data, e.g., variable-size struct, container. */ + FSize = 6, + /** Class instance. */ Class = 7 }; #else enum OptionalFormat { - OptionalFormatF1 = 0, // see above + /** Fixed 1-byte encoding. */ + OptionalFormatF1 = 0, + /** Fixed 2-byte encoding. */ OptionalFormatF2 = 1, + /** Fixed 4-byte encoding. */ OptionalFormatF4 = 2, + /** Fixed 8-byte encoding. */ OptionalFormatF8 = 3, + /** "Size encoding" using 1 to 5 bytes, e.g., enum, class identifier. */ OptionalFormatSize = 4, + /** + * "Size encoding" using 1 to 5 bytes followed by data, e.g., string, fixed size + * struct, or containers whose size can be computed prior to marshaling. + */ OptionalFormatVSize = 5, + /** Fixed size using 4 bytes followed by data, e.g., variable-size struct, container. */ OptionalFormatFSize = 6, + /** Class instance. */ OptionalFormatClass = 7 }; #endif -// -// Is the provided type a container? -// For now, the implementation only checks if there is a T::iterator typedef -// using SFINAE -// +/** + * Determines whether the provided type is a container. For now, the implementation only checks + * if there is a T::iterator typedef using SFINAE. + * \headerfile Ice/Ice.h + */ template<typename T> struct IsContainer { @@ -91,11 +121,11 @@ struct IsContainer static const bool value = sizeof(test<T>(0)) == sizeof(char); }; -// -// Is the provided type a map? -// For now, the implementation only checks if there is a T::mapped_type typedef -// using SFINAE -// +/** + * Determines whether the provided type is a map. For now, the implementation only checks if there + * is a T::mapped_type typedef using SFINAE. + * \headerfile Ice/Ice.h + */ template<typename T> struct IsMap { @@ -110,10 +140,10 @@ struct IsMap #ifdef ICE_CPP11_MAPPING -// -// Base traits template. -// Types with no specialized trait use this trait. -// +/** + * Base traits template. Types with no specialized trait use this trait. + * \headerfile Ice/Ice.h + */ template<typename T, typename Enabler = void> struct StreamableTraits { @@ -133,6 +163,10 @@ struct StreamableTraits //static const bool fixedLength = false; }; +/** + * Specialization for sequence and dictionary types. + * \headerfile Ice/Ice.h + */ template<typename T> struct StreamableTraits<T, typename ::std::enable_if<IsMap<T>::value || IsContainer<T>::value>::type> { @@ -141,6 +175,10 @@ struct StreamableTraits<T, typename ::std::enable_if<IsMap<T>::value || IsContai static const bool fixedLength = false; }; +/** + * Specialization for exceptions. + * \headerfile Ice/Ice.h + */ template<typename T> struct StreamableTraits<T, typename ::std::enable_if<::std::is_base_of<::Ice::UserException, T>::value>::type> { @@ -152,9 +190,10 @@ struct StreamableTraits<T, typename ::std::enable_if<::std::is_base_of<::Ice::Us // }; -// -// StreamableTraits specialization for arrays (std::pair<const T*, const T*>). -// +/** + * Specialization for arrays (std::pair<const T*, const T*>). + * \headerfile Ice/Ice.h + */ template<typename T> struct StreamableTraits<std::pair<T*, T*>> { @@ -165,33 +204,35 @@ struct StreamableTraits<std::pair<T*, T*>> #else -// -// Base traits template. -// Types with no specialized trait use this trait. -// +/** + * Base traits template. Types with no specialized trait use this trait, including sequence and + * dictionary types. + * \headerfile Ice/Ice.h + */ template<typename T, typename Enabler = void> struct StreamableTraits { static const StreamHelperCategory helper = IsMap<T>::value ? StreamHelperCategoryDictionary : (IsContainer<T>::value ? StreamHelperCategorySequence : StreamHelperCategoryUnknown); - // - // When extracting a sequence<T> from a stream, we can ensure the - // stream has at least StreamableTraits<T>::minWireSize * size bytes - // For containers, the minWireSize is 1 (just 1 byte for an empty container). - // + /** + * When extracting a sequence<T> from a stream, we can ensure the + * stream has at least StreamableTraits<T>::minWireSize * size bytes. + * For containers, the minWireSize is 1 (just 1 byte for an empty container). + */ static const int minWireSize = 1; - // - // Is this type encoded on a fixed number of bytes? - // Used only for marshaling/unmarshaling optional data members and parameters. - // + /** + * Is this type encoded on a fixed number of bytes? + * Used only for marshaling/unmarshaling optional data members and parameters. + */ static const bool fixedLength = false; }; -// -// StreamableTraits specialization for user exceptions. -// +/** + * Specialization for exceptions. + * \headerfile Ice/Ice.h + */ template<> struct StreamableTraits<UserException> { @@ -203,11 +244,11 @@ struct StreamableTraits<UserException> // }; -// -// StreamableTraits specialization for array / range mapped sequences -// The type can be a std::pair<T, T> or a -// std::pair<IceUtil::ScopedArray<T>, std::pair<const T*, const T*> > -// +/** + * Specialization for array / range mapped sequences. The type can be a std::pair<T, T> or a + * std::pair<IceUtil::ScopedArray<T>, std::pair<const T*, const T*> >. + * \headerfile Ice/Ice.h + */ template<typename T, typename U> struct StreamableTraits< ::std::pair<T, U> > { @@ -217,10 +258,11 @@ struct StreamableTraits< ::std::pair<T, U> > }; #endif -// -// StreamableTraits specialization for builtins (these are needed for sequence -// marshaling to figure out the minWireSize of each built-in). -// +/** + * Specialization for built-in type (this is needed for sequence + * marshaling to figure out the minWireSize of each type). + * \headerfile Ice/Ice.h + */ template<> struct StreamableTraits<bool> { @@ -229,6 +271,11 @@ struct StreamableTraits<bool> static const bool fixedLength = true; }; +/** + * Specialization for built-in type (this is needed for sequence + * marshaling to figure out the minWireSize of each type). + * \headerfile Ice/Ice.h + */ template<> struct StreamableTraits<Byte> { @@ -237,6 +284,11 @@ struct StreamableTraits<Byte> static const bool fixedLength = true; }; +/** + * Specialization for built-in type (this is needed for sequence + * marshaling to figure out the minWireSize of each type). + * \headerfile Ice/Ice.h + */ template<> struct StreamableTraits<Short> { @@ -245,6 +297,11 @@ struct StreamableTraits<Short> static const bool fixedLength = true; }; +/** + * Specialization for built-in type (this is needed for sequence + * marshaling to figure out the minWireSize of each type). + * \headerfile Ice/Ice.h + */ template<> struct StreamableTraits<Int> { @@ -253,6 +310,11 @@ struct StreamableTraits<Int> static const bool fixedLength = true; }; +/** + * Specialization for built-in type (this is needed for sequence + * marshaling to figure out the minWireSize of each type). + * \headerfile Ice/Ice.h + */ template<> struct StreamableTraits<Long> { @@ -261,6 +323,11 @@ struct StreamableTraits<Long> static const bool fixedLength = true; }; +/** + * Specialization for built-in type (this is needed for sequence + * marshaling to figure out the minWireSize of each type). + * \headerfile Ice/Ice.h + */ template<> struct StreamableTraits<Float> { @@ -269,6 +336,11 @@ struct StreamableTraits<Float> static const bool fixedLength = true; }; +/** + * Specialization for built-in type (this is needed for sequence + * marshaling to figure out the minWireSize of each type). + * \headerfile Ice/Ice.h + */ template<> struct StreamableTraits<Double> { @@ -277,6 +349,11 @@ struct StreamableTraits<Double> static const bool fixedLength = true; }; +/** + * Specialization for built-in type (this is needed for sequence + * marshaling to figure out the minWireSize of each type). + * \headerfile Ice/Ice.h + */ template<> struct StreamableTraits< ::std::string> { @@ -285,6 +362,11 @@ struct StreamableTraits< ::std::string> static const bool fixedLength = false; }; +/** + * Specialization for built-in type (this is needed for sequence + * marshaling to figure out the minWireSize of each type). + * \headerfile Ice/Ice.h + */ template<> struct StreamableTraits< ::std::wstring> { @@ -293,10 +375,10 @@ struct StreamableTraits< ::std::wstring> static const bool fixedLength = false; }; -// -// vector<bool> is a special type in C++: the streams are responsible -// to handle it like a built-in type. -// +/** + * vector<bool> is a special type in C++: the streams handle it like a built-in type. + * \headerfile Ice/Ice.h + */ template<> struct StreamableTraits< ::std::vector<bool> > { @@ -305,6 +387,10 @@ struct StreamableTraits< ::std::vector<bool> > static const bool fixedLength = false; }; +/** + * Specialization for proxy types. + * \headerfile Ice/Ice.h + */ #ifdef ICE_CPP11_MAPPING template<typename T> struct StreamableTraits<::std::shared_ptr<T>, typename ::std::enable_if<::std::is_base_of<::Ice::ObjectPrx, T>::value>::type> @@ -323,6 +409,10 @@ struct StreamableTraits< ::IceInternal::ProxyHandle<T> > }; #endif +/** + * Specialization for class types. + * \headerfile Ice/Ice.h + */ #ifdef ICE_CPP11_MAPPING template<typename T> struct StreamableTraits<::std::shared_ptr<T>, typename ::std::enable_if<::std::is_base_of<::Ice::Value, T>::value>::type> @@ -345,11 +435,14 @@ struct StreamableTraits< ::IceInternal::Handle<T> > // StreamHelper templates used by streams to read and write data. // -// Base StreamHelper template; it must be specialized for each type +/** Base StreamHelper template; it must be specialized for each type. */ template<typename T, StreamHelperCategory st> struct StreamHelper; -// Helper for builtins, delegates read/write to the stream. +/** + * Helper for built-ins, delegates read/write to the stream. + * \headerfile Ice/Ice.h + */ template<typename T> struct StreamHelper<T, StreamHelperCategoryBuiltin> { @@ -371,6 +464,10 @@ struct StreamHelper<T, StreamHelperCategoryBuiltin> // slice2cpp generates specializations as needed // +/** + * General writer. slice2cpp generates specializations as needed. + * \headerfile Ice/Ice.h + */ template<typename T, typename S> struct StreamWriter { @@ -387,6 +484,10 @@ struct StreamWriter #endif }; +/** + * General reader. slice2cpp generates specializations as needed. + * \headerfile Ice/Ice.h + */ template<typename T, typename S> struct StreamReader { @@ -396,7 +497,10 @@ struct StreamReader } }; -// Helper for structs +/** + * Helper for structs. + * \headerfile Ice/Ice.h + */ template<typename T> struct StreamHelper<T, StreamHelperCategoryStruct> { @@ -413,7 +517,10 @@ struct StreamHelper<T, StreamHelperCategoryStruct> } }; -// Helper for class structs +/** + * Helper for class structs. + * \headerfile Ice/Ice.h + */ template<typename T> struct StreamHelper<T, StreamHelperCategoryStructClass> { @@ -431,7 +538,10 @@ struct StreamHelper<T, StreamHelperCategoryStructClass> } }; -// Helper for enums +/** + * Helper for enums. + * \headerfile Ice/Ice.h + */ template<typename T> struct StreamHelper<T, StreamHelperCategoryEnum> { @@ -457,7 +567,10 @@ struct StreamHelper<T, StreamHelperCategoryEnum> } }; -// Helper for sequences +/** + * Helper for sequences. + * \headerfile Ice/Ice.h + */ template<typename T> struct StreamHelper<T, StreamHelperCategorySequence> { @@ -483,7 +596,10 @@ struct StreamHelper<T, StreamHelperCategorySequence> } }; -// Helper for array custom sequence parameters +/** + * Helper for array custom sequence parameters. + * \headerfile Ice/Ice.h + */ template<typename T> struct StreamHelper<std::pair<const T*, const T*>, StreamHelperCategorySequence> { @@ -502,7 +618,10 @@ struct StreamHelper<std::pair<const T*, const T*>, StreamHelperCategorySequence> #ifndef ICE_CPP11_MAPPING -// Helper for range custom sequence parameters +/** + * Helper for range custom sequence parameters. + * \headerfile Ice/Ice.h + */ template<typename T> struct StreamHelper<std::pair<T, T>, StreamHelperCategorySequence> { @@ -523,6 +642,10 @@ struct StreamHelper<std::pair<T, T>, StreamHelperCategorySequence> } }; +/** + * Specialization for sequence<bool>. + * \headerfile Ice/Ice.h + */ template<> struct StreamHelper<std::pair< ::std::vector<bool>::const_iterator, ::std::vector<bool>::const_iterator>, StreamHelperCategorySequence> @@ -539,7 +662,10 @@ struct StreamHelper<std::pair< ::std::vector<bool>::const_iterator, } }; -// Helper for zero-copy array sequence parameters +/** + * Helper for zero-copy array sequence parameters. + * \headerfile Ice/Ice.h + */ template<typename T> struct StreamHelper<std::pair<IceUtil::ScopedArray<T>, std::pair<const T*, const T*> >, StreamHelperCategorySequence> { @@ -553,7 +679,10 @@ struct StreamHelper<std::pair<IceUtil::ScopedArray<T>, std::pair<const T*, const }; #endif -// Helper for dictionaries +/** + * Helper for dictionaries. + * \headerfile Ice/Ice.h + */ template<typename T> struct StreamHelper<T, StreamHelperCategoryDictionary> { @@ -583,7 +712,10 @@ struct StreamHelper<T, StreamHelperCategoryDictionary> } }; -// Helper for user exceptions +/** + * Helper for user exceptions. + * \headerfile Ice/Ice.h + */ template<typename T> struct StreamHelper<T, StreamHelperCategoryUserException> { @@ -596,7 +728,10 @@ struct StreamHelper<T, StreamHelperCategoryUserException> // no read: only used for marshaling }; -// Helper for proxies +/** + * Helper for proxies. + * \headerfile Ice/Ice.h + */ template<typename T> struct StreamHelper<T, StreamHelperCategoryProxy> { @@ -613,7 +748,10 @@ struct StreamHelper<T, StreamHelperCategoryProxy> } }; -// Helper for classes +/** + * Helper for classes. + * \headerfile Ice/Ice.h + */ template<typename T> struct StreamHelper<T, StreamHelperCategoryClass> { @@ -640,52 +778,87 @@ struct StreamHelper<T, StreamHelperCategoryClass> // /!\ Do not use in StreamOptionalHelper specializations, and do // not provide specialization not handled by the base StreamOptionalHelper // +/** + * Extract / compute the optionalFormat. + * \headerfile Ice/Ice.h + */ template<StreamHelperCategory st, int minWireSize, bool fixedLength> struct GetOptionalFormat; +/** + * Specialization for 1-byte built-in fixed-length types. + * \headerfile Ice/Ice.h + */ template<> struct GetOptionalFormat<StreamHelperCategoryBuiltin, 1, true> { static const OptionalFormat value = ICE_SCOPED_ENUM(OptionalFormat, F1); }; +/** + * Specialization for 2-byte built-in fixed-length types. + * \headerfile Ice/Ice.h + */ template<> struct GetOptionalFormat<StreamHelperCategoryBuiltin, 2, true> { static const OptionalFormat value = ICE_SCOPED_ENUM(OptionalFormat, F2); }; +/** + * Specialization for 4-byte built-in fixed-length types. + * \headerfile Ice/Ice.h + */ template<> struct GetOptionalFormat<StreamHelperCategoryBuiltin, 4, true> { static const OptionalFormat value = ICE_SCOPED_ENUM(OptionalFormat, F4); }; +/** + * Specialization for 8-byte built-in fixed-length types. + * \headerfile Ice/Ice.h + */ template<> struct GetOptionalFormat<StreamHelperCategoryBuiltin, 8, true> { static const OptionalFormat value = ICE_SCOPED_ENUM(OptionalFormat, F8); }; +/** + * Specialization for built-in variable-length types. + * \headerfile Ice/Ice.h + */ template<> struct GetOptionalFormat<StreamHelperCategoryBuiltin, 1, false> { static const OptionalFormat value = ICE_SCOPED_ENUM(OptionalFormat, VSize); }; +/** + * Specialization for class types. + * \headerfile Ice/Ice.h + */ template<> struct GetOptionalFormat<StreamHelperCategoryClass, 1, false> { static const OptionalFormat value = ICE_SCOPED_ENUM(OptionalFormat, Class); }; +/** + * Specialization for enum types. + * \headerfile Ice/Ice.h + */ template<int minWireSize> struct GetOptionalFormat<StreamHelperCategoryEnum, minWireSize, false> { static const OptionalFormat value = ICE_SCOPED_ENUM(OptionalFormat, Size); }; -// Base helper: simply read/write the data +/** + * Base helper for optional values: simply read/write the data. + * \headerfile Ice/Ice.h + */ template<typename T, StreamHelperCategory st, bool fixedLength> struct StreamOptionalHelper { @@ -711,7 +884,10 @@ struct StreamOptionalHelper } }; -// Helper to write fixed size structs +/** + * Helper to write fixed-size structs. + * \headerfile Ice/Ice.h + */ template<typename T> struct StreamOptionalHelper<T, StreamHelperCategoryStruct, true> { @@ -732,7 +908,10 @@ struct StreamOptionalHelper<T, StreamHelperCategoryStruct, true> } }; -// Helper to write variable size structs +/** + * Helper to write variable-size structs. + * \headerfile Ice/Ice.h + */ template<typename T> struct StreamOptionalHelper<T, StreamHelperCategoryStruct, false> { @@ -754,30 +933,38 @@ struct StreamOptionalHelper<T, StreamHelperCategoryStruct, false> } }; -// Class structs are encoded like structs +/** + * Class structs are encoded like structs. + * \headerfile Ice/Ice.h + */ template<typename T, bool fixedLength> struct StreamOptionalHelper<T, StreamHelperCategoryStructClass, fixedLength> : StreamOptionalHelper<T, StreamHelperCategoryStruct, fixedLength> { }; -// Optional proxies are encoded like variable size structs, using the FSize encoding +/** + * Optional proxies are encoded like variable size structs, using the FSize encoding. + * \headerfile Ice/Ice.h + */ template<typename T> struct StreamOptionalHelper<T, StreamHelperCategoryProxy, false> : StreamOptionalHelper<T, StreamHelperCategoryStruct, false> { }; -// -// Helpers to read/write optional sequences or dictionaries -// +/** + * Helper to read/write optional sequences or dictionaries. + * \headerfile Ice/Ice.h + */ template<typename T, bool fixedLength, int sz> struct StreamOptionalContainerHelper; -// -// Encode containers of variable size elements with the FSize optional -// type, since we can't easily figure out the size of the container -// before encoding. This is the same encoding as variable size structs -// so we just re-use its implementation. -// +/** + * Encode containers of variable-size elements with the FSize optional + * type, since we can't easily figure out the size of the container + * before encoding. This is the same encoding as variable size structs + * so we just re-use its implementation. + * \headerfile Ice/Ice.h + */ template<typename T, int sz> struct StreamOptionalContainerHelper<T, false, sz> { @@ -796,11 +983,12 @@ struct StreamOptionalContainerHelper<T, false, sz> } }; -// -// Encode containers of fixed size elements with the VSize optional -// type since we can figure out the size of the container before -// encoding. -// +/** + * Encode containers of fixed-size elements with the VSize optional + * type since we can figure out the size of the container before + * encoding. + * \headerfile Ice/Ice.h + */ template<typename T, int sz> struct StreamOptionalContainerHelper<T, true, sz> { @@ -826,12 +1014,13 @@ struct StreamOptionalContainerHelper<T, true, sz> } }; -// -// Optimization: containers of 1 byte elements are encoded with the -// VSize optional type. There's no need to encode an additional size -// for those, the number of elements of the container can be used to -// skip the optional. -// +/** + * Optimization: containers of 1 byte elements are encoded with the + * VSize optional type. There's no need to encode an additional size + * for those, the number of elements of the container can be used to + * skip the optional. + * \headerfile Ice/Ice.h + */ template<typename T> struct StreamOptionalContainerHelper<T, true, 1> { @@ -850,10 +1039,11 @@ struct StreamOptionalContainerHelper<T, true, 1> } }; -// -// Helper to write sequences, delegates to the optional container -// helper template partial specializations. -// +/** + * Helper to write sequences, delegates to the optional container + * helper template partial specializations. + * \headerfile Ice/Ice.h + */ template<typename T> struct StreamOptionalHelper<T, StreamHelperCategorySequence, false> { @@ -878,6 +1068,11 @@ struct StreamOptionalHelper<T, StreamHelperCategorySequence, false> } }; +/** + * Helper to write sequences, delegates to the optional container + * helper template partial specializations. + * \headerfile Ice/Ice.h + */ template<typename T> struct StreamOptionalHelper<std::pair<const T*, const T*>, StreamHelperCategorySequence, false> { @@ -905,6 +1100,11 @@ struct StreamOptionalHelper<std::pair<const T*, const T*>, StreamHelperCategoryS #ifndef ICE_CPP11_MAPPING +/** + * Helper to write sequences, delegates to the optional container + * helper template partial specializations. + * \headerfile Ice/Ice.h + */ template<typename T> struct StreamOptionalHelper<std::pair<T, T>, StreamHelperCategorySequence, false> { @@ -930,6 +1130,11 @@ struct StreamOptionalHelper<std::pair<T, T>, StreamHelperCategorySequence, false } }; +/** + * Helper to write sequences, delegates to the optional container + * helper template partial specializations. + * \headerfile Ice/Ice.h + */ template<typename T> struct StreamOptionalHelper<std::pair<IceUtil::ScopedArray<T>, std::pair<const T*, const T*> >, StreamHelperCategorySequence, false> @@ -952,10 +1157,11 @@ struct StreamOptionalHelper<std::pair<IceUtil::ScopedArray<T>, std::pair<const T }; #endif -// -// Helper to write dictionaries, delegates to the optional container -// helper template partial specializations. -// +/** + * Helper to write dictionaries, delegates to the optional container + * helper template partial specializations. + * \headerfile Ice/Ice.h + */ template<typename T> struct StreamOptionalHelper<T, StreamHelperCategoryDictionary, false> { @@ -982,6 +1188,8 @@ struct StreamOptionalHelper<T, StreamHelperCategoryDictionary, false> } }; +/// \endcond + } #endif diff --git a/cpp/include/Ice/StringConverter.h b/cpp/include/Ice/StringConverter.h index 2012a5173b3..d1b48b97072 100644 --- a/cpp/include/Ice/StringConverter.h +++ b/cpp/include/Ice/StringConverter.h @@ -17,34 +17,65 @@ namespace Ice { +/** Encapsulates bytes in the UTF-8 encoding. */ typedef IceUtil::UTF8Buffer UTF8Buffer; + +/** Narrow string converter. */ typedef IceUtil::StringConverter StringConverter; typedef IceUtil::StringConverterPtr StringConverterPtr; + +/** Wide string converter. */ typedef IceUtil::WstringConverter WstringConverter; typedef IceUtil::WstringConverterPtr WstringConverterPtr; +/** Indicates an error occurred during string conversion. */ typedef IceUtil::IllegalConversionException IllegalConversionException; #ifdef ICE_CPP11_MAPPING +/** Base class for a string converter. */ template<typename charT> using BasicStringConverter = IceUtil::BasicStringConverter<charT>; #endif #ifdef _WIN32 +/** + * Creates a string converter that converts between multi-byte and UTF-8 strings and uses MultiByteToWideChar + * and WideCharToMultiByte for its implementation. + */ using IceUtil::createWindowsStringConverter; #endif +/** Creates a string converter that converts between Unicode wide strings and UTF-8 strings. */ using IceUtil::createUnicodeWstringConverter; +/** Installs a default narrow string converter for the process. */ using IceUtil::setProcessStringConverter; + +/** Obtains the default narrow string converter for the process. */ using IceUtil::getProcessStringConverter; + +/** Installs a default wide string converter for the process. */ using IceUtil::setProcessWstringConverter; + +/** Obtains the default wide string converter for the process. */ using IceUtil::getProcessWstringConverter; +/** Converts a wide string to a narrow string. */ using IceUtil::wstringToString; + +/** Converts a narrow string to a wide string. */ using IceUtil::stringToWstring; +/** + * Converts a narrow string to a UTF-8 encoded string using a string converter. + * No conversion is performed if the string converter is nil. + */ using IceUtil::nativeToUTF8; + +/** + * Converts a UTF-8 encoded string to a narrow string using a string converter. + * No conversion is performed if the string converter is nil. + */ using IceUtil::UTF8ToNative; } diff --git a/cpp/include/Ice/UUID.h b/cpp/include/Ice/UUID.h index bbb8e6527ba..224709c1dc3 100644 --- a/cpp/include/Ice/UUID.h +++ b/cpp/include/Ice/UUID.h @@ -16,6 +16,7 @@ namespace Ice { +/** Generates a UUID. */ using IceUtil::generateUUID; } diff --git a/cpp/include/Ice/UniquePtr.h b/cpp/include/Ice/UniquePtr.h index 081f9650c37..764c4e99339 100644 --- a/cpp/include/Ice/UniquePtr.h +++ b/cpp/include/Ice/UniquePtr.h @@ -95,6 +95,6 @@ private: #endif -} // End of namespace IceUtil +} #endif diff --git a/cpp/include/Ice/UserExceptionFactory.h b/cpp/include/Ice/UserExceptionFactory.h index 8f8baa4f480..877a86f75df 100644 --- a/cpp/include/Ice/UserExceptionFactory.h +++ b/cpp/include/Ice/UserExceptionFactory.h @@ -19,6 +19,7 @@ namespace Ice { +/** Creates and throws a user exception. */ using UserExceptionFactory = std::function<void(const std::string&)>; } @@ -44,6 +45,10 @@ defaultUserExceptionFactory(const std::string& typeId) namespace Ice { +/** + * Creates and throws a user exception. + * \headerfile Ice/Ice.h + */ class ICE_API UserExceptionFactory : public IceUtil::Shared { public: diff --git a/cpp/include/Ice/Value.h b/cpp/include/Ice/Value.h index f4702620d3c..91845202dbe 100644 --- a/cpp/include/Ice/Value.h +++ b/cpp/include/Ice/Value.h @@ -21,6 +21,10 @@ namespace Ice { +/** + * The base class for instances of Slice classes. + * \headerfile Ice/Ice.h + */ class ICE_API Value { public: @@ -36,26 +40,61 @@ public: Value& operator=(Value&&) = default; virtual ~Value() = default; + /** + * The Ice run time invokes this method prior to marshaling an object's data members. This allows a subclass + * to override this method in order to validate its data members. + */ virtual void ice_preMarshal(); + + /** + * The Ice run time invokes this method vafter unmarshaling an object's data members. This allows a + * subclass to override this method in order to perform additional initialization. + */ virtual void ice_postUnmarshal(); + /** + * Obtains the Slice type ID of the most-derived class supported by this object. + * @return The type ID. + */ virtual std::string ice_id() const; + + /** + * Obtains the Slice type ID of this type. + * @return The return value is always "::Ice::Object". + */ static const std::string& ice_staticId(); + /** + * Returns a shallow copy of the object. + * @return The cloned value. + */ std::shared_ptr<Value> ice_clone() const; + /** + * Obtains the sliced data associated with this instance. + * @return The sliced data if the value has a preserved-slice base class and has been sliced during + * unmarshaling of the value, nil otherwise. + */ virtual std::shared_ptr<SlicedData> ice_getSlicedData() const; + /// \cond STREAM virtual void _iceWrite(Ice::OutputStream*) const; virtual void _iceRead(Ice::InputStream*); + /// \endcond protected: + /// \cond INTERNAL virtual std::shared_ptr<Value> _iceCloneImpl() const = 0; + /// \endcond + + /// \cond STREAM virtual void _iceWriteImpl(Ice::OutputStream*) const {} virtual void _iceReadImpl(Ice::InputStream*) {} + /// \endcond }; +/// \cond INTERNAL template<typename T, typename Base> class ValueHelper : public Base { public: @@ -97,6 +136,7 @@ protected: Base::_iceReadImpl(is); } }; +/// \endcond } #endif // C++11 mapping end diff --git a/cpp/include/Ice/ValueF.h b/cpp/include/Ice/ValueF.h index b3e59c72539..fd928d2245a 100644 --- a/cpp/include/Ice/ValueF.h +++ b/cpp/include/Ice/ValueF.h @@ -17,7 +17,9 @@ namespace Ice { class Value; +/// \cond INTERNAL using ValuePtr = ::std::shared_ptr<Value>; +/// \endcond } #endif diff --git a/cpp/include/IceBT/Plugin.h b/cpp/include/IceBT/Plugin.h index 09cf21d0078..c88960b4f4e 100644 --- a/cpp/include/IceBT/Plugin.h +++ b/cpp/include/IceBT/Plugin.h @@ -25,56 +25,66 @@ namespace IceBT { +/** A name-value map. */ typedef std::map<std::string, std::string> PropertyMap; +/** A collection of properties for each device. */ typedef std::map<std::string, PropertyMap> DeviceMap; #ifndef ICE_CPP11_MAPPING -// -// An application can receive discovery notifications -// by implementing the DiscoveryCallback interface. -// +/** + * An application can receive discovery notifications by implementing the DiscoveryCallback interface. + * \headerfile IceBT/IceBT.h + */ class ICEBT_API DiscoveryCallback : public IceUtil::Shared { public: - // - // Called for each discovered device. The same device may be reported multiple times. - // The device's Bluetooth address is provided, along with a map of properties - // supplied by the system's Bluetooth stack. - // + /** + * Called for each discovered device. The same device may be reported multiple times. + * @param addr The discovered device's Bluetooth address. + * @param props A map of device properties supplied by the system's Bluetooth stack. + */ virtual void discovered(const std::string& addr, const PropertyMap& props) = 0; }; typedef IceUtil::Handle<DiscoveryCallback> DiscoveryCallbackPtr; #endif +/** + * Represents the IceBT plug-in object. + * \headerfile IceBT/IceBT.h + */ class ICEBT_API Plugin : public Ice::Plugin { public: - // - // Start Bluetooth device discovery on the adapter with the specified address. - // The given callback will be invoked for each discovered device. The same - // device may be reported more than once. Discovery remains active until - // explicitly stopped by a call to stopDiscovery(), or via other administrative means. - // + /** + * Start Bluetooth device discovery on the adapter with the specified address. + * The given callback will be invoked for each discovered device. The same + * device may be reported more than once. Discovery remains active until + * explicitly stopped by a call to stopDiscovery(), or via other administrative means. + * @param address The address associated with the Bluetooth adapter. + * @param cb The callback to invoke when a device is discovered. + */ #ifdef ICE_CPP11_MAPPING virtual void startDiscovery(const std::string& address, - std::function<void(const std::string& addr, const PropertyMap& props)>) = 0; + std::function<void(const std::string& addr, const PropertyMap& props)> cb) = 0; #else virtual void startDiscovery(const std::string& address, const DiscoveryCallbackPtr& cb) = 0; #endif - // - // Stops Bluetooth device discovery on the adapter with the specified address. - // All discovery callbacks are removed when discovery stops. - // + /** + * Stops Bluetooth device discovery on the adapter with the specified address. + * All discovery callbacks are removed when discovery stops. + * @param address The address associated with the Bluetooth adapter. + */ virtual void stopDiscovery(const std::string& address) = 0; - // - // Retrieve a snapshot of all known remote devices. The plug-in obtains a snapshot of the remote devices at - // startup and then dynamically updates its map as the host adds and removes devices. - // + /** + * Retrieve a snapshot of all known remote devices. The plug-in obtains a snapshot of the remote devices at + * startup and then dynamically updates its map as the host adds and removes devices. + * @return A map containing properties for each known device. + */ virtual DeviceMap getDevices() const = 0; }; ICE_DEFINE_PTR(PluginPtr, Plugin); diff --git a/cpp/include/IceGrid/IceGrid.h b/cpp/include/IceGrid/IceGrid.h index c4b756ec4b3..7e630dd59c1 100644 --- a/cpp/include/IceGrid/IceGrid.h +++ b/cpp/include/IceGrid/IceGrid.h @@ -22,9 +22,10 @@ namespace IceGrid { -// -// Global function to obtain a RegistryPluginFacade -// +/** + * Obtains the plug-in facade for the IceGrid registry. + * @return The plug-in facade. + */ ICEGRID_API RegistryPluginFacadePtr getRegistryPluginFacade(); } diff --git a/cpp/include/IceGrid/ReplicaGroupFilter.h b/cpp/include/IceGrid/ReplicaGroupFilter.h index 418b92a3608..29706bc6841 100644 --- a/cpp/include/IceGrid/ReplicaGroupFilter.h +++ b/cpp/include/IceGrid/ReplicaGroupFilter.h @@ -13,12 +13,25 @@ namespace IceGrid { +/** + * Abstract base class for a replica group filter. + * \headerfile IceGrid/IceGrid.h + */ class ReplicaGroupFilter : public IceUtil::Shared { public: + /** + * Called by the registry to filter a collection of adapters. The implementation must not block. + * @param replicaGroupId The replica group identifier involved in this request. + * @param adapterIds A sequence of object adapter identifiers denoting the object + * adapters participating in the replica group whose nodes are active at the time of the request. + * @param connection The incoming connection from the client to the registry. + * @param context The incoming connection from the client to the registry. + * @return The filtered list of adapter identifiers. + */ virtual Ice::StringSeq filter(const string& replicaGroupId, const Ice::StringSeq& adapterIds, - const Ice::ConnectionPtr&, const Ice::Context&) = 0; + const Ice::ConnectionPtr& connection, const Ice::Context& context) = 0; }; }; diff --git a/cpp/include/IceSSL/OpenSSL.h b/cpp/include/IceSSL/OpenSSL.h index b280387417a..733ec654df7 100644 --- a/cpp/include/IceSSL/OpenSSL.h +++ b/cpp/include/IceSSL/OpenSSL.h @@ -43,7 +43,14 @@ namespace Ice { -ICE_PLUGIN_REGISTER_DECLSPEC_IMPORT void registerIceSSLOpenSSL(bool = true); +/** + * When using static libraries, calling this function ensures the OpenSSL version of the IceSSL plug-in is + * linked with the application. + * @param loadOnInitialize If true, the plug-in is loaded (created) during communicator initialization. + * If false, the plug-in is only loaded during communicator initialization if its corresponding plug-in + * property is set to 1. + */ +ICE_PLUGIN_REGISTER_DECLSPEC_IMPORT void registerIceSSLOpenSSL(bool loadOnInitialize = true); } #endif @@ -57,69 +64,84 @@ namespace OpenSSL class Certificate; ICE_DEFINE_PTR(CertificatePtr, Certificate); +/** + * Encapsulates an OpenSSL X.509 certificate. + * \headerfile IceSSL/IceSSL.h + */ class ICESSL_OPENSSL_API Certificate : public virtual IceSSL::Certificate { public: - // - // Construct a certificate using a native certificate. - // - // The Certificate class assumes ownership of the given native - // certificate. - // - static CertificatePtr create(x509_st*); - - // - // Load the certificate from a file. The certificate must use the - // PEM encoding format. Raises CertificateReadException if the - // file cannot be read. - // - static CertificatePtr load(const std::string&); - - // - // Decode a certificate from a string that uses the PEM encoding - // format. Raises CertificateEncodingException if an error - // occurs. - // - static CertificatePtr decode(const std::string&); - - // - // Retrieve the native X509 certificate value wrapped by this - // object. - // - // The returned reference is only valid for the lifetime of this - // object. you can increment it with X509_dup. - // + /** + * Construct a certificate using a native certificate. + * The Certificate class assumes ownership of the given native + * certificate. + * @param cert The native certificate. + * @return A new certificate object. + */ + static CertificatePtr create(x509_st* cert); + + /** + * Load the certificate from a file. The certificate must use the + * PEM encoding format. + * @param file The certificate file. + * @return A new certificate object. + * @throws CertificateReadException if the file cannot be read. + */ + static CertificatePtr load(const std::string& file); + + /** + * Decode a certificate from a string that uses the PEM encoding format. + * @param cert A string containing the PEM-encoded certificate. + * @return A new certificate object. + * @throws CertificateEncodingException if an error occurs. + */ + static CertificatePtr decode(const std::string& cert); + + /** + * Retrieve the native X509 certificate value wrapped by this object. + * @return The native certificate. The returned reference is only valid for the lifetime of this + * object. You can increment it with X509_dup. + */ virtual x509_st* getCert() const = 0; }; +/** + * Represents the IceSSL plug-in object. + * \headerfile IceSSL/IceSSL.h + */ class ICESSL_OPENSSL_API Plugin : public virtual IceSSL::Plugin { public: - // - // returns OpenSSL version number. - // + + /** + * Obtains the OpenSSL version number. + * @return The version. + */ virtual Ice::Long getOpenSSLVersion() const = 0; - // - // Establish the OpenSSL context. This must be done before the - // plug-in is initialized, therefore the application must define - // the property Ice.InitPlugins=0, set the context, and finally - // invoke initializePlugins on the PluginManager. - // - // When the application supplies its own OpenSSL context, the - // plug-in ignores configuration properties related to certificates, - // keys, and passwords. - // - // Note that the plugin assumes ownership of the given context. - // - virtual void setContext(SSL_CTX*) = 0; - - // - // Obtain the SSL context. Use caution when modifying this value. - // Changes made to this value have no effect on existing connections. - // - virtual SSL_CTX* getContext() = 0; + /** + * Establishes the OpenSSL context. This must be done before the + * plug-in is initialized, therefore the application must define + * the property Ice.InitPlugins=0, set the context, and finally + * invoke Ice::PluginManager::initializePlugins. + * + * When the application supplies its own OpenSSL context, the + * plug-in ignores configuration properties related to certificates, + * keys, and passwords. + * + * Note that the plug-in assumes ownership of the given context. + * + * @param ctx The OpenSSL context. + */ + virtual void setContext(SSL_CTX* ctx) = 0; + + /** + * Obtains the SSL context. Use caution when modifying this value. + * Changes made to this value have no effect on existing connections. + * @return The OpenSSL context. + */ + virtual SSL_CTX* getContext() = 0; }; ICE_DEFINE_PTR(PluginPtr, Plugin); diff --git a/cpp/include/IceSSL/Plugin.h b/cpp/include/IceSSL/Plugin.h index 0bfc483a09a..3215624a830 100644 --- a/cpp/include/IceSSL/Plugin.h +++ b/cpp/include/IceSSL/Plugin.h @@ -36,22 +36,31 @@ namespace IceSSL { -// -// This exception is thrown if the certificate cannot be read. -// +/** + * Thrown if the certificate cannot be read. + * \headerfile IceSSL/IceSSL.h + */ class ICESSL_API CertificateReadException : public IceUtil::ExceptionHelper<CertificateReadException> { public: CertificateReadException(const char*, int, const std::string&); + #ifndef ICE_CPP11_COMPILER virtual ~CertificateReadException() throw(); #endif + virtual std::string ice_id() const; + #ifndef ICE_CPP11_MAPPING + /** + * Creates a shallow copy of this exception. + * @return The new exception instance. + */ virtual CertificateReadException* ice_clone() const; #endif + /** The reason for the exception. */ std::string reason; private: @@ -59,22 +68,31 @@ private: static const char* _name; }; -// -// This exception is thrown if the certificate cannot be encoded. -// +/** + * Thrown if the certificate cannot be encoded. + * \headerfile IceSSL/IceSSL.h + */ class ICESSL_API CertificateEncodingException : public IceUtil::ExceptionHelper<CertificateEncodingException> { public: CertificateEncodingException(const char*, int, const std::string&); + #ifndef ICE_CPP11_COMPILER virtual ~CertificateEncodingException() throw(); #endif + virtual std::string ice_id() const; + #ifndef ICE_CPP11_MAPPING + /** + * Creates a shallow copy of this exception. + * @return The new exception instance. + */ virtual CertificateEncodingException* ice_clone() const; #endif + /** The reason for the exception. */ std::string reason; private: @@ -82,22 +100,31 @@ private: static const char* _name; }; -// -// This exception is thrown if a distinguished name cannot be parsed. -// +/** + * This exception is thrown if a distinguished name cannot be parsed. + * \headerfile IceSSL/IceSSL.h + */ class ICESSL_API ParseException : public IceUtil::ExceptionHelper<ParseException> { public: ParseException(const char*, int, const std::string&); + #ifndef ICE_CPP11_COMPILER virtual ~ParseException() throw(); #endif + virtual std::string ice_id() const; + #ifndef ICE_CPP11_MAPPING + /** + * Creates a shallow copy of this exception. + * @return The new exception instance. + */ virtual ParseException* ice_clone() const; #endif + /** The reason for the exception. */ std::string reason; private: @@ -105,61 +132,76 @@ private: static const char* _name; }; -// -// This class represents a DistinguishedName, similar to the Java -// type X500Principal and the .NET type X500DistinguishedName. -// -// For comparison purposes, the value of a relative distinguished -// name (RDN) component is always unescaped before matching, -// therefore "ZeroC, Inc." will match ZeroC\, Inc. -// -// toString() always returns exactly the same information as was -// provided in the constructor (i.e., "ZeroC, Inc." will not turn -// into ZeroC\, Inc.). -// +/** + * This class represents a DistinguishedName, similar to the Java + * type X500Principal and the .NET type X500DistinguishedName. + * + * For comparison purposes, the value of a relative distinguished + * name (RDN) component is always unescaped before matching, + * therefore "ZeroC, Inc." will match ZeroC\, Inc. + * + * toString() always returns exactly the same information as was + * provided in the constructor (i.e., "ZeroC, Inc." will not turn + * into ZeroC\, Inc.). + * \headerfile IceSSL/IceSSL.h + */ class ICESSL_API DistinguishedName { public: - // - // Create a DistinguishedName from a string encoded using - // the rules in RFC2253. - // - // Throws ParseException if parsing fails. - // - explicit DistinguishedName(const std::string&); - - // - // Create a DistinguishedName from a list of RDN pairs, - // where each pair consists of the RDN's type and value. - // For example, the RDN "O=ZeroC" is represented by the - // pair ("O", "ZeroC"). - // + /** + * Creates a DistinguishedName from a string encoded using the rules in RFC2253. + * @param name The encoded distinguished name. + * @throws ParseException if parsing fails. + */ + explicit DistinguishedName(const std::string& name); + + /** + * Creates a DistinguishedName from a list of RDN pairs, + * where each pair consists of the RDN's type and value. + * For example, the RDN "O=ZeroC" is represented by the + * pair ("O", "ZeroC"). + * @throws ParseException if parsing fails. + */ explicit DistinguishedName(const std::list<std::pair<std::string, std::string> >&); - // - // This is an exact match. The order of the RDN components is - // important. - // + /** + * Performs an exact match. The order of the RDN components is important. + */ friend ICESSL_API bool operator==(const DistinguishedName&, const DistinguishedName&); + + /** + * Performs an exact match. The order of the RDN components is important. + */ friend ICESSL_API bool operator<(const DistinguishedName&, const DistinguishedName&); - // - // Perform a partial match with another DistinguishedName. The function - // returns true if all of the RDNs in the argument are present in this - // DistinguishedName and they have the same values. - // - bool match(const DistinguishedName&) const; - bool match(const std::string&) const; - - // - // Encode the DN in RFC2253 format. - // + /** + * Performs a partial match with another DistinguishedName. + * @param dn The name to be matched. + * @return True if all of the RDNs in the argument are present in this + * DistinguishedName and they have the same values. + */ + bool match(const DistinguishedName& dn) const; + + /** + * Performs a partial match with another DistinguishedName. + * @param dn The name to be matched. + * @return True if all of the RDNs in the argument are present in this + * DistinguishedName and they have the same values. + */ + bool match(const std::string& dn) const; + + /** + * Encodes the DN in RFC2253 format. + * @return An encoded string. + */ operator std::string() const; protected: + /// \cond INTERNAL void unescape(); + /// \endcond private: @@ -167,33 +209,46 @@ private: std::list<std::pair<std::string, std::string> > _unescaped; }; +/** + * Performs an exact match. The order of the RDN components is important. + */ inline bool operator>(const DistinguishedName& lhs, const DistinguishedName& rhs) { return rhs < lhs; } +/** + * Performs an exact match. The order of the RDN components is important. + */ inline bool operator<=(const DistinguishedName& lhs, const DistinguishedName& rhs) { return !(lhs > rhs); } +/** + * Performs an exact match. The order of the RDN components is important. + */ inline bool operator>=(const DistinguishedName& lhs, const DistinguishedName& rhs) { return !(lhs < rhs); } +/** + * Performs an exact match. The order of the RDN components is important. + */ inline bool operator!=(const DistinguishedName& lhs, const DistinguishedName& rhs) { return !(lhs == rhs); } -// -// This class represents an X509 Certificate extension. -// +/** + * Represents an X509 Certificate extension. + * \headerfile IceSSL/IceSSL.h + */ class ICESSL_API X509Extension #ifndef ICE_CPP11_MAPPING : public virtual IceUtil::Shared @@ -201,267 +256,317 @@ class ICESSL_API X509Extension { public: + /** + * Determines whether the information in this extension is important. + * @return True if if information is important, false otherwise. + */ virtual bool isCritical() const = 0; + + /** + * Obtains the object ID of this extension. + * @return The object ID. + */ virtual std::string getOID() const = 0; + + /** + * Obtains the data associated with this extension. + * @return The extension data. + */ virtual std::vector<Ice::Byte> getData() const = 0; }; ICE_DEFINE_PTR(X509ExtensionPtr, X509Extension); -// -// This convenience class is a wrapper around a native certificate. -// The interface is inspired by java.security.cert.X509Certificate. -// - class Certificate; ICE_DEFINE_PTR(CertificatePtr, Certificate); +/** + * This convenience class is a wrapper around a native certificate. + * The interface is inspired by java.security.cert.X509Certificate. + * \headerfile IceSSL/IceSSL.h + */ class ICESSL_API Certificate : #ifdef ICE_CPP11_MAPPING - public std::enable_shared_from_this<Certificate> + public std::enable_shared_from_this<Certificate> #else - public virtual IceUtil::Shared + public virtual IceUtil::Shared #endif { public: - // - // Compare the certificates for equality using the - // native certificate comparison method. - // + /** + * Compares the certificates for equality using the native certificate comparison method. + */ virtual bool operator==(const Certificate&) const = 0; + + /** + * Compares the certificates for equality using the native certificate comparison method. + */ virtual bool operator!=(const Certificate&) const = 0; - // - // Authority key identifier - // + /** + * Obtains the authority key identifier. + * @return The identifier. + */ virtual std::vector<Ice::Byte> getAuthorityKeyIdentifier() const = 0; - // - // Subject key identifier - // + /** + * Obtains the subject key identifier. + * @return The identifier. + */ virtual std::vector<Ice::Byte> getSubjectKeyIdentifier() const = 0; - // - // Verify that this certificate was signed by the given certificate - // public key. Returns true if signed, false otherwise. - // - virtual bool verify(const CertificatePtr&) const = 0; - - // - // Return a string encoding of the certificate in PEM format. - // Raises CertificateEncodingException if an error occurs. - // + /** + * Verifies that this certificate was signed by the given certificate + * public key. + * @param cert A certificate containing the public key. + * @return True if signed, false otherwise. + */ + virtual bool verify(const CertificatePtr& cert) const = 0; + + /** + * Obtains a string encoding of the certificate in PEM format. + * @return The encoded certificate. + * @throws CertificateEncodingException if an error occurs. + */ virtual std::string encode() const = 0; - // - // Checks that the certificate is currently valid, that is, the current - // date falls between the validity period given in the certificate. - // + /** + * Checks that the certificate is currently valid, that is, the current + * date falls between the validity period given in the certificate. + * @return True if the certificate is valid, false otherwise. + */ virtual bool checkValidity() const = 0; - // - // Checks that the certificate is valid at the given time. - // + /** + * Checks that the certificate is valid at the given time. + * @param t The target time. + * @return True if the certificate is valid, false otherwise. + */ #ifdef ICE_CPP11_MAPPING - virtual bool checkValidity(const std::chrono::system_clock::time_point&) const = 0; + virtual bool checkValidity(const std::chrono::system_clock::time_point& t) const = 0; #else - virtual bool checkValidity(const IceUtil::Time&) const = 0; + virtual bool checkValidity(const IceUtil::Time& t) const = 0; #endif - // - // Get the not-after validity time. - // + /** + * Obtains the not-after validity time. + * @return The time after which this certificate is invalid. + */ #ifdef ICE_CPP11_MAPPING virtual std::chrono::system_clock::time_point getNotAfter() const = 0; #else virtual IceUtil::Time getNotAfter() const = 0; #endif - // - // Get the not-before validity time. - // + /** + * Obtains the not-before validity time. + * @return The time at which this certificate is valid. + */ #ifdef ICE_CPP11_MAPPING virtual std::chrono::system_clock::time_point getNotBefore() const = 0; #else virtual IceUtil::Time getNotBefore() const = 0; #endif - // - // Get the serial number. This is an arbitrarily large number. - // + /** + * Obtains the serial number. This is an arbitrarily large number. + * @return The certificate's serial number. + */ virtual std::string getSerialNumber() const = 0; - // - // Get the issuer's distinguished name (DN). - // + /** + * Obtains the issuer's distinguished name (DN). + * @return The distinguished name. + */ virtual DistinguishedName getIssuerDN() const = 0; - // - // Get the values in the issuer's alternative names extension. - // - // The returned list contains a pair of int, string. - // - // otherName [0] OtherName - // rfc822Name [1] IA5String - // dNSName [2] IA5String - // x400Address [3] ORAddress - // directoryName [4] Name - // ediPartyName [5] EDIPartyName - // uniformResourceIdentifier [6] IA5String - // iPAddress [7] OCTET STRING - // registeredID [8] OBJECT IDENTIFIER - // - // rfc822Name, dNSName, directoryName and - // uniformResourceIdentifier data is returned as a string. - // - // iPAddress is returned in dotted quad notation. IPv6 is not - // currently supported. - // - // All distinguished names are encoded in RFC2253 format. - // - // The remainder of the data will result in an empty string. Use the raw - // X509* certificate to obtain these values. - // + /** + * Obtains the values in the issuer's alternative names extension. + * + * The returned list contains a pair of int, string. + * + * otherName [0] OtherName + * rfc822Name [1] IA5String + * dNSName [2] IA5String + * x400Address [3] ORAddress + * directoryName [4] Name + * ediPartyName [5] EDIPartyName + * uniformResourceIdentifier [6] IA5String + * iPAddress [7] OCTET STRING + * registeredID [8] OBJECT IDENTIFIER + * + * rfc822Name, dNSName, directoryName and + * uniformResourceIdentifier data is returned as a string. + * + * iPAddress is returned in dotted quad notation. IPv6 is not + * currently supported. + * + * All distinguished names are encoded in RFC2253 format. + * + * The remainder of the data will result in an empty string. Use the raw + * X509* certificate to obtain these values. + * + * @return The issuer's alternative names. + */ virtual std::vector<std::pair<int, std::string> > getIssuerAlternativeNames() const = 0; - // - // Get the subject's distinguished name (DN). - // + /** + * Obtains the subject's distinguished name (DN). + * @return The distinguished name. + */ virtual DistinguishedName getSubjectDN() const = 0; - // - // See the comment for getIssuerAlternativeNames. - // + /** + * See the comment for Plugin::getIssuerAlternativeNames. + * @return The subject's alternative names. + */ virtual std::vector<std::pair<int, std::string> > getSubjectAlternativeNames() const = 0; - // - // Retrieve the certificate version number. - // + /** + * Obtains the certificate version number. + * @return The version number. + */ virtual int getVersion() const = 0; - // - // Stringify the certificate. This is a human readable version of - // the certificate, not a DER or PEM encoding. - // + /** + * Stringifies the certificate. This is a human readable version of + * the certificate, not a DER or PEM encoding. + * @return A string version of the certificate. + */ virtual std::string toString() const = 0; - // - // Return a list with the X509v3 extensions contained in the - // certificate. - // + /** + * Obtains a list of the X509v3 extensions contained in the certificate. + * @return The extensions. + */ virtual std::vector<X509ExtensionPtr> getX509Extensions() const = 0; - // - // Return the extension with the given OID or null if the certificate - // does not contain a extension with the given OID. - // - virtual X509ExtensionPtr getX509Extension(const std::string&) const = 0; - - // - // Load the certificate from a file. The certificate must use the - // PEM encoding format. Raises CertificateReadException if the - // file cannot be read. - // - static CertificatePtr load(const std::string&); - - // - // Decode a certificate from a string that uses the PEM encoding - // format. Raises CertificateEncodingException if an error - // occurs. - // - static CertificatePtr decode(const std::string&); + /** + * Obtains the extension with the given OID. + * @return The extension, or null if the certificate + * does not contain a extension with the given OID. + */ + virtual X509ExtensionPtr getX509Extension(const std::string& oid) const = 0; + + /** + * Loads the certificate from a file. The certificate must use the + * PEM encoding format. + * @param file The certificate file. + * @return The new certificate instance. + * @throws CertificateReadException if the file cannot be read. + */ + static CertificatePtr load(const std::string& file); + + /** + * Decodes a certificate from a string that uses the PEM encoding format. + * @param str A string containing the encoded certificate. + * @throws CertificateEncodingException if an error occurs. + */ + static CertificatePtr decode(const std::string& str); }; #ifndef ICE_CPP11_MAPPING // C++98 mapping -// -// An application can customize the certificate verification process -// by implementing the CertificateVerifier interface. -// +/** + * An application can customize the certificate verification process + * by implementing the CertificateVerifier interface. + * \headerfile IceSSL/IceSSL.h + */ class ICESSL_API CertificateVerifier : public IceUtil::Shared { public: virtual ~CertificateVerifier(); - // - // Return false if the connection should be rejected, or true to - // allow it. - // - virtual bool verify(const ConnectionInfoPtr&) = 0; + /** + * Determines whether to accept a certificate. + * @param info Information about the connection. + * @return False if the connection should be rejected, or true to allow it. + */ + virtual bool verify(const ConnectionInfoPtr& info) = 0; }; typedef IceUtil::Handle<CertificateVerifier> CertificateVerifierPtr; -// -// In order to read an encrypted file, such as one containing a -// private key, OpenSSL requests a password from IceSSL. The password -// can be defined using an IceSSL configuration property, but a -// plain-text password is a security risk. If a password is not -// supplied via configuration, IceSSL allows OpenSSL to prompt the -// user interactively. This may not be desirable (or even possible), -// so the application can supply an implementation of PasswordPrompt -// to take responsibility for obtaining the password. -// -// Note that the password is needed during plug-in initialization, so -// in general you will need to delay initialization (by defining -// IceSSL.DelayInit=1), configure the PasswordPrompt, then manually -// initialize the plug-in. -// +/** + * In order to read an encrypted file, such as one containing a + * private key, OpenSSL requests a password from IceSSL. The password + * can be defined using an IceSSL configuration property, but a + * plain-text password is a security risk. If a password is not + * supplied via configuration, IceSSL allows OpenSSL to prompt the + * user interactively. This may not be desirable (or even possible), + * so the application can supply an implementation of PasswordPrompt + * to take responsibility for obtaining the password. + * + * Note that the password is needed during plug-in initialization, so + * in general you will need to delay initialization (by defining + * IceSSL.DelayInit=1), configure the PasswordPrompt, then manually + * initialize the plug-in. + * \headerfile IceSSL/IceSSL.h + */ class ICESSL_API PasswordPrompt : public IceUtil::Shared { public: virtual ~PasswordPrompt(); - // - // The getPassword method may be invoked repeatedly, such as when - // several encrypted files are opened, or when multiple password - // attempts are allowed. - // + /** + * Obtains the password. This method may be invoked repeatedly, such as when + * several encrypted files are opened, or when multiple password + * attempts are allowed. + * @return The clear-text password. + */ virtual std::string getPassword() = 0; }; typedef IceUtil::Handle<PasswordPrompt> PasswordPromptPtr; #endif +/** + * Represents the IceSSL plug-in object. + * \headerfile IceSSL/IceSSL.h + */ class ICESSL_API Plugin : public Ice::Plugin { public: virtual ~Plugin(); - // - // Establish the certificate verifier object. This should be done - // before any connections are established. - // + /** + * Establish the certificate verifier object. This should be done + * before any connections are established. + * @param v The verifier. + */ #ifdef ICE_CPP11_MAPPING - virtual void setCertificateVerifier(std::function<bool(const std::shared_ptr<ConnectionInfo>&)>) = 0; + virtual void setCertificateVerifier(std::function<bool(const std::shared_ptr<ConnectionInfo>&)> v) = 0; #else - virtual void setCertificateVerifier(const CertificateVerifierPtr&) = 0; + virtual void setCertificateVerifier(const CertificateVerifierPtr& v) = 0; #endif - // - // Establish the password prompt object. This must be done before - // the plug-in is initialized. - // + /** + * Establish the password prompt object. This must be done before + * the plug-in is initialized. + * @param p The password prompt. + */ #ifdef ICE_CPP11_MAPPING - virtual void setPasswordPrompt(std::function<std::string()>) = 0; + virtual void setPasswordPrompt(std::function<std::string()> p) = 0; #else - virtual void setPasswordPrompt(const PasswordPromptPtr&) = 0; + virtual void setPasswordPrompt(const PasswordPromptPtr& p) = 0; #endif - // - // Load the certificate from a file. The certificate must use the - // PEM encoding format. Raises CertificateReadException if the - // file cannot be read. - // - virtual CertificatePtr load(const std::string&) const = 0; - - // - // Decode a certificate from a string that uses the PEM encoding - // format. Raises CertificateEncodingException if an error - // occurs. - // - virtual CertificatePtr decode(const std::string&) const = 0; + /** + * Load the certificate from a file. The certificate must use the + * PEM encoding format. + * @param file The certificate file. + * @throws CertificateReadException if the file cannot be read. + */ + virtual CertificatePtr load(const std::string& file) const = 0; + + /** + * Decode a certificate from a string that uses the PEM encoding + * format. + * @param str A string containing the encoded certificate. + * @throws CertificateEncodingException if an error occurs. + */ + virtual CertificatePtr decode(const std::string& str) const = 0; }; ICE_DEFINE_PTR(PluginPtr, Plugin); diff --git a/cpp/include/IceSSL/SChannel.h b/cpp/include/IceSSL/SChannel.h index 9ff60700ea7..df4fff6b486 100644 --- a/cpp/include/IceSSL/SChannel.h +++ b/cpp/include/IceSSL/SChannel.h @@ -23,39 +23,46 @@ namespace SChannel class Certificate; ICE_DEFINE_PTR(CertificatePtr, Certificate); +/** + * This convenience class is a wrapper around a native certificate. + * \headerfile IceSSL/IceSSL.h + */ class ICESSL_API Certificate : public virtual IceSSL::Certificate { public: - // - // Construct a certificate using a native certificate. - // - // The Certificate class assumes ownership of the given native - // certificate. - // - static CertificatePtr create(CERT_SIGNED_CONTENT_INFO*); + /** + * Constructs a certificate using a native certificate. + * The Certificate class assumes ownership of the given native + * certificate. + * @param info The certificate data. + * @return The new certificate instance. + */ + static CertificatePtr create(CERT_SIGNED_CONTENT_INFO* info); - // - // Load the certificate from a file. The certificate must use the - // PEM encoding format. Raises CertificateReadException if the - // file cannot be read. - // - static CertificatePtr load(const std::string&); + /** + * Loads the certificate from a file. The certificate must use the + * PEM encoding format. + * @param file The certificate file. + * @return The new certificate instance. + * @throws CertificateReadException if the file cannot be read. + */ + static CertificatePtr load(const std::string& file); - // - // Decode a certificate from a string that uses the PEM encoding - // format. Raises CertificateEncodingException if an error - // occurs. - // - static CertificatePtr decode(const std::string&); + /** + * Decodes a certificate from a string that uses the PEM encoding format. + * @param str A string containing the encoded certificate. + * @return The new certificate instance. + * @throws CertificateEncodingException if an error occurs. + */ + static CertificatePtr decode(const std::string& str); - // - // Retrieve the native X509 certificate value wrapped by this - // object. - // - // The returned reference is only valid for the lifetime of this - // object. The returned reference is a pointer to a struct. - // + /** + * Obtains the native X509 certificate value wrapped by this object. + * @return A reference to the native certificate. + * The returned reference is only valid for the lifetime of this + * object. The returned reference is a pointer to a struct. + */ virtual CERT_SIGNED_CONTENT_INFO* getCert() const = 0; }; diff --git a/cpp/include/IceSSL/SecureTransport.h b/cpp/include/IceSSL/SecureTransport.h index 9be2d30868c..d907064d9c4 100644 --- a/cpp/include/IceSSL/SecureTransport.h +++ b/cpp/include/IceSSL/SecureTransport.h @@ -22,40 +22,47 @@ namespace SecureTransport class Certificate; ICE_DEFINE_PTR(CertificatePtr, Certificate); +/** + * This convenience class is a wrapper around a native certificate. + * \headerfile IceSSL/IceSSL.h + */ class ICESSL_API Certificate : public virtual IceSSL::Certificate { public: - // - // Construct a certificate using a native certificate. - // - // The Certificate class assumes ownership of the given native - // certificate. - // - static CertificatePtr create(SecCertificateRef); + /** + * Constructs a certificate using a native certificate. + * The Certificate class assumes ownership of the given native + * certificate. + * @param cert The certificate cert. + * @return The new certificate instance. + */ + static CertificatePtr create(SecCertificateRef cert); - // - // Load the certificate from a file. The certificate must use the - // PEM encoding format. Raises CertificateReadException if the - // file cannot be read. - // - static CertificatePtr load(const std::string&); + /** + * Loads the certificate from a file. The certificate must use the + * PEM encoding format. + * @param file The certificate file. + * @return The new certificate instance. + * @throws CertificateReadException if the file cannot be read. + */ + static CertificatePtr load(const std::string& file); - // - // Decode a certificate from a string that uses the PEM encoding - // format. Raises CertificateEncodingException if an error - // occurs. - // - static CertificatePtr decode(const std::string&); + /** + * Decodes a certificate from a string that uses the PEM encoding format. + * @param str A string containing the encoded certificate. + * @return The new certificate instance. + * @throws CertificateEncodingException if an error occurs. + */ + static CertificatePtr decode(const std::string& str); - // - // Retrieve the native X509 certificate value wrapped by this - // object. - // - // The returned reference is only valid for the lifetime of this - // object. You can increment the reference count of the returned - // object with CFRetain. - // + /** + * Obtains the native X509 certificate value wrapped by this object. + * @return A reference to the native certificate. + * The returned reference is only valid for the lifetime of this + * object. You can increment the reference count of the returned + * object with CFRetain. + */ virtual SecCertificateRef getCert() const = 0; }; diff --git a/cpp/include/IceSSL/UWP.h b/cpp/include/IceSSL/UWP.h index e131ade6c5b..349323e43b9 100644 --- a/cpp/include/IceSSL/UWP.h +++ b/cpp/include/IceSSL/UWP.h @@ -21,33 +21,42 @@ namespace UWP class Certificate; ICE_DEFINE_PTR(CertificatePtr, Certificate); +/** + * This convenience class is a wrapper around a native certificate. + * \headerfile IceSSL/IceSSL.h + */ class ICESSL_API Certificate : public virtual IceSSL::Certificate { public: - // - // Construct a certificate using a native certificate. - // - static CertificatePtr create(Windows::Security::Cryptography::Certificates::Certificate^); - - // - // Load the certificate from a file. The certificate must use the - // PEM encoding format. Raises CertificateReadException if the - // file cannot be read. - // - static CertificatePtr load(const std::string&); - - // - // Decode a certificate from a string that uses the PEM encoding - // format. Raises CertificateEncodingException if an error - // occurs. - // - static CertificatePtr decode(const std::string&); - - // - // Retrieve the native X509 certificate value wrapped by this - // object. - // + /** + * Constructs a certificate using a native certificate. + * @param cert The native certificate. + * @return The new certificate instance. + */ + static CertificatePtr create(Windows::Security::Cryptography::Certificates::Certificate^ cert); + + /** + * Loads the certificate from a file. The certificate must use the + * PEM encoding format. + * @param file The certificate file. + * @return The new certificate instance. + * @throws CertificateReadException if the file cannot be read. + */ + static CertificatePtr load(const std::string& file); + + /** + * Decodes a certificate from a string that uses the PEM encoding format. + * @param str A string containing the encoded certificate. + * @return The new certificate instance. + * @throws CertificateEncodingException if an error occurs. + */ + static CertificatePtr decode(const std::string& str); + + /** + * Obtains the native X509 certificate value wrapped by this object. + * @return The native certificate. + */ virtual Windows::Security::Cryptography::Certificates::Certificate^ getCert() const = 0; }; diff --git a/cpp/include/IceUtil/CtrlCHandler.h b/cpp/include/IceUtil/CtrlCHandler.h index 1b616894bed..d1dbe382267 100644 --- a/cpp/include/IceUtil/CtrlCHandler.h +++ b/cpp/include/IceUtil/CtrlCHandler.h @@ -16,49 +16,77 @@ namespace IceUtil { -// The CtrlCHandler provides a portable way to handle CTRL+C and -// CTRL+C like signals -// On Unix/POSIX, the CtrlCHandler handles SIGHUP, SIGINT and SIGTERM. -// On Windows, it is essentially a wrapper for SetConsoleCtrlHandler(). -// -// In a process, only one CtrlCHandler can exist at a given time: -// the CtrlCHandler constructor raises CtrlCHandlerException if -// you attempt to create a second CtrlCHandler. -// On Unix/POSIX, it is essential to create the CtrlCHandler before -// creating any thread, as the CtrlCHandler constructor masks (blocks) -// SIGHUP, SIGINT and SIGTERM; by default, threads created later will -// inherit this signal mask. -// -// When a CTRL+C or CTRL+C like signal is sent to the process, the -// user-registered callback is called in a separate thread; it is -// given the signal number. The callback must not raise exceptions. -// On Unix/POSIX, the callback is NOT a signal handler and can call -// functions that are not async-signal safe. -// -// The CtrCHandler destructor "unregisters" the callback. However -// on Unix/POSIX it does not restore the old signal mask in any -// thread, so SIGHUP, SIGINT and SIGTERM remain blocked. -// -// TODO: Maybe the behavior on Windows should be the same? Now we -// just restore the default behavior (TerminateProcess). - +/** + * Invoked when a signal occurs. The callback must not raise exceptions. + * On Unix/POSIX, the callback is NOT a signal handler and can call + * functions that are not async-signal safe. + * @param sig The signal number that occurred. + */ #ifdef ICE_CPP11_MAPPING -using CtrlCHandlerCallback = std::function<void(int)>; +using CtrlCHandlerCallback = std::function<void(int sig)>; #else -typedef void (*CtrlCHandlerCallback)(int); +typedef void (*CtrlCHandlerCallback)(int sig); #endif +/** + * Provides a portable way to handle CTRL+C and CTRL+C like signals. + * On Unix/POSIX, the CtrlCHandler handles SIGHUP, SIGINT and SIGTERM. + * On Windows, it is essentially a wrapper for SetConsoleCtrlHandler(). + * + * In a process, only one CtrlCHandler can exist at a given time: + * the CtrlCHandler constructor raises CtrlCHandlerException if + * you attempt to create a second CtrlCHandler. + * On Unix/POSIX, it is essential to create the CtrlCHandler before + * creating any thread, as the CtrlCHandler constructor masks (blocks) + * SIGHUP, SIGINT and SIGTERM; by default, threads created later will + * inherit this signal mask. + * + * When a CTRL+C or CTRL+C like signal is sent to the process, the + * user-registered callback is called in a separate thread; it is + * given the signal number. The callback must not raise exceptions. + * On Unix/POSIX, the callback is NOT a signal handler and can call + * functions that are not async-signal safe. + * + * The CtrCHandler destructor "unregisters" the callback. However + * on Unix/POSIX it does not restore the old signal mask in any + * thread, so SIGHUP, SIGINT and SIGTERM remain blocked. + * + * \headerfile IceUtil/CtrlCHandler.h + */ +// +// TODO: Maybe the behavior on Windows should be the same? Now we +// just restore the default behavior (TerminateProcess). +// class ICE_API CtrlCHandler { public: - explicit CtrlCHandler(CtrlCHandlerCallback = ICE_NULLPTR); + /** + * Initializes the relevant signals. + * @param cb The signal callback. + */ + explicit CtrlCHandler(CtrlCHandlerCallback cb = ICE_NULLPTR); ~CtrlCHandler(); - CtrlCHandlerCallback setCallback(CtrlCHandlerCallback); + /** + * Replaces the signal callback. + * @param cb The new callback. + * @return The old callback, or nil if no callback is currently set. + */ + CtrlCHandlerCallback setCallback(CtrlCHandlerCallback cb); + + /** + * Obtains the signal callback. + * @return The callback, or nil if no callback is currently set. + */ CtrlCHandlerCallback getCallback() const; }; +/** + * Raised by CtrlCHandler. + * + * \headerfile IceUtil/CtrlCHandler.h + */ class ICE_API CtrlCHandlerException : public ExceptionHelper<CtrlCHandlerException> { public: diff --git a/cpp/include/IceUtil/Optional.h b/cpp/include/IceUtil/Optional.h index edc93c5dcc3..f7995e54a33 100644 --- a/cpp/include/IceUtil/Optional.h +++ b/cpp/include/IceUtil/Optional.h @@ -26,8 +26,10 @@ struct NoneType namespace IceUtil { +/** A sentinel value used to indicate that no optional value was provided. */ const IceUtilInternal::NoneType None = {}; +/** Encapsulates an optional value, which may or may not be present. */ template<typename T> class Optional { @@ -35,19 +37,33 @@ public: typedef T element_type; + /** + * Constructs an empty optional with no value. + */ Optional() : _isSet(false) { } + /** + * Constructs an empty optional with no value. + */ Optional(IceUtilInternal::NoneType) : _isSet(false) { } + /** + * Constructs an optional with the given value. + * @param p The initial value. + */ template<typename Y> Optional(Y p) : _value(p), _isSet(true) { } + /** + * Constructs an optional as a copy of the given optional. + * @param r The source optional. + */ template<typename Y> Optional(const Optional<Y>& r) : _value(r._value), _isSet(r._isSet) { @@ -57,6 +73,9 @@ public: { } + /** + * Resets this optional to have no value. + */ Optional& operator=(IceUtilInternal::NoneType) { _value = T(); @@ -64,6 +83,10 @@ public: return *this; } + /** + * Resets this optional to have the given value. + * @param p The new value. + */ template<typename Y> Optional& operator=(Y p) { @@ -72,6 +95,10 @@ public: return *this; } + /** + * Resets this optional to be a copy of the given optional. + * @param r The source optional. + */ template<typename Y> Optional& operator=(const Optional<Y>& r) { @@ -80,6 +107,10 @@ public: return *this; } + /** + * Resets this optional to be a copy of the given optional. + * @param r The source optional. + */ Optional& operator=(const Optional& r) { _value = r._value; @@ -87,66 +118,122 @@ public: return *this; } + /** + * Obtains the current value. + * @return The current value. + * @throws OptionalNotSetException if this optional has no value. + */ const T& value() const { checkIsSet(); return _value; } + /** + * Obtains the current value. + * @return The current value. + * @throws OptionalNotSetException if this optional has no value. + */ T& value() { checkIsSet(); return _value; } + /** + * Obtains the current value. + * @return The current value. + * @throws OptionalNotSetException if this optional has no value. + */ const T& get() const { return value(); } + /** + * Obtains the current value. + * @return The current value. + * @throws OptionalNotSetException if this optional has no value. + */ T& get() { return value(); } + /** + * Obtains a pointer to the current value. + * @return A pointer to the current value. + * @throws OptionalNotSetException if this optional has no value. + */ const T* operator->() const { return &value(); } + + /** + * Obtains a pointer to the current value. + * @return A pointer to the current value. + * @throws OptionalNotSetException if this optional has no value. + */ T* operator->() { return &value(); } + /** + * Obtains the current value. + * @return The current value. + * @throws OptionalNotSetException if this optional has no value. + */ const T& operator*() const { return value(); } + + /** + * Obtains the current value. + * @return The current value. + * @throws OptionalNotSetException if this optional has no value. + */ T& operator*() { return value(); } + /** + * Determines whether this optional has a value. + * @return True if the optional has a value, false otherwise. + */ operator bool() const { return _isSet; } + /** + * Determines whether this optional has a value. + * @return True if the optional does not have a value, false otherwise. + */ bool operator!() const { return !_isSet; } + /** + * Exchanges the state of this optional with another one. + * @param other The optional value with which to swap. + */ void swap(Optional& other) { std::swap(_isSet, other._isSet); std::swap(_value, other._value); } + /// \cond INTERNAL void __setIsSet() { _isSet = true; } + /// \endcond private: @@ -164,17 +251,24 @@ private: bool _isSet; }; +/** + * Constructs an optional from the given value. + * @param v The optional's initial value. + * @return A new optional object. + */ template<class T> inline Optional<T> makeOptional(const T& v) { return Optional<T>(v); } +/// \cond INTERNAL template<typename T> inline void Optional<T>::throwOptionalNotSetException(const char* file, int line) const { throw OptionalNotSetException(file, line); } +/// \endcond template<typename T, typename U> inline bool operator==(const Optional<T>& lhs, const Optional<U>& rhs) diff --git a/cpp/include/IceUtil/StringConverter.h b/cpp/include/IceUtil/StringConverter.h index c581b5c595d..90330ea8ad0 100644 --- a/cpp/include/IceUtil/StringConverter.h +++ b/cpp/include/IceUtil/StringConverter.h @@ -20,25 +20,33 @@ namespace IceUtil { -// -// Provides bytes to toUTF8. Can raise std::bad_alloc or Ice::MemoryLimitException -// when too many bytes are requested. -// +/** + * Provides bytes to toUTF8. Can raise std::bad_alloc or Ice::MemoryLimitException + * when too many bytes are requested. + * \headerfile Ice/Ice.h + */ class ICE_API UTF8Buffer { public: + + /** + * Obtains more bytes. + * @param howMany The number of bytes requested. + * @param firstUnused A pointer to the first unused byte. + * @return A pointer to the beginning of the buffer. + */ virtual Byte* getMoreBytes(size_t howMany, Byte* firstUnused) = 0; virtual ~UTF8Buffer(); }; -// -// A StringConverter converts narrow or wide-strings to and from UTF-8 byte sequences. -// It's used by the communicator during marshaling (toUTF8) and unmarshaling (fromUTF8). -// It report errors by raising IllegalConversionException or an exception raised -// by UTF8Buffer -// - +/** + * A StringConverter converts narrow or wide-strings to and from UTF-8 byte sequences. + * It's used by the communicator during marshaling (toUTF8) and unmarshaling (fromUTF8). + * It report errors by raising IllegalConversionException or an exception raised + * by UTF8Buffer. + * \headerfile Ice/Ice.h + */ template<typename charT> class BasicStringConverter #ifndef ICE_CPP11_MAPPING @@ -46,18 +54,17 @@ class BasicStringConverter #endif { public: - // - // Returns a pointer to byte after the last written byte (which may be - // past the last byte returned by getMoreBytes). - // - virtual Byte* toUTF8(const charT* sourceStart, const charT* sourceEnd, - UTF8Buffer&) const = 0; - - // - // Unmarshals a UTF-8 sequence into a basic_string - // - virtual void fromUTF8(const Byte* sourceStart, const Byte* sourceEnd, - std::basic_string<charT>& target) const = 0; + + /** + * Returns a pointer to byte after the last written byte (which may be + * past the last byte returned by getMoreBytes). + */ + virtual Byte* toUTF8(const charT* sourceStart, const charT* sourceEnd, UTF8Buffer& buf) const = 0; + + /** + * Unmarshals a UTF-8 sequence into a basic_string. + */ + virtual void fromUTF8(const Byte* sourceStart, const Byte* sourceEnd, std::basic_string<charT>& target) const = 0; virtual ~BasicStringConverter() { @@ -73,85 +80,95 @@ template class ICE_API BasicStringConverter<char>; template class ICE_API BasicStringConverter<wchar_t>; #endif +/** A narrow string converter. */ typedef BasicStringConverter<char> StringConverter; ICE_DEFINE_PTR(StringConverterPtr, StringConverter); +/** A wide string converter. */ typedef BasicStringConverter<wchar_t> WstringConverter; ICE_DEFINE_PTR(WstringConverterPtr, WstringConverter); -// -// Create a WstringConverter that converts to and from UTF-16 or UTF-32 -// depending on sizeof(wchar_t). -// -// +/** + * Creates a WstringConverter that converts to and from UTF-16 or UTF-32 depending on sizeof(wchar_t). + * @return The string converter. + */ ICE_API WstringConverterPtr createUnicodeWstringConverter(); -// -// Retrieve the per process narrow string converter. -// +/** + * Retrieves the per-process narrow string converter. + * @return The string converter. + */ ICE_API StringConverterPtr getProcessStringConverter(); -// -// Set the per process narrow string converter. -// -ICE_API void setProcessStringConverter(const StringConverterPtr&); +/** + * Sets the per-process narrow string converter. + * @param c The string converter. + */ +ICE_API void setProcessStringConverter(const StringConverterPtr& c); -// -// Retrieve the per process wide string converter. -// +/** + * Retrieves the per-process wide string converter. + * @return The string converter. + */ ICE_API WstringConverterPtr getProcessWstringConverter(); -// -// Set the per process wide string converter. -// -ICE_API void setProcessWstringConverter(const WstringConverterPtr&); - -// -// Converts the given wide string to a narrow string -// -// If the StringConverter parameter is null, the result's narrow -// string encoding is UTF-8. -// If the WstringConverter parameter is null, the input's wstring -// encoding is UTF-16 or UTF-32 depending on the size of wchar_t. -// +/** + * Sets the per process wide string converter. + * @param c The string converter. + */ +ICE_API void setProcessWstringConverter(const WstringConverterPtr& c); + +/** + * Converts the given wide string to a narrow string. + * @param str A wide string. + * @param nc The narrow string converter. If null, the result's narrow string encoding is UTF-8. + * @param wc The wide string converter. If null, the input's wstring encoding is UTF-16 or UTF-32 + * depending on the size of wchar_t. + * @return A narrow string. + */ ICE_API std::string -wstringToString(const std::wstring&, - const StringConverterPtr& = 0, - const WstringConverterPtr& = 0); - -// -// Converts the given narrow string to a wide string -// -// If the StringConverter parameter is null, the input's narrow string -// encoding is UTF-8. -// If the WstringConverter parameter is null, the result's wstring -// encoding is UTF-16 or UTF-32 depending on the size of wchar_t. -// +wstringToString(const std::wstring& str, + const StringConverterPtr& nc = 0, + const WstringConverterPtr& wc = 0); + +/** + * Converts the given narrow string to a wide string. + * @param str A narrow string. + * @param nc The narrow string converter. If null, the result's narrow string encoding is UTF-8. + * @param wc The wide string converter. If null, the input's wstring encoding is UTF-16 or UTF-32 + * depending on the size of wchar_t. + * @return A wide string. + */ ICE_API std::wstring -stringToWstring(const std::string&, - const StringConverterPtr& = 0, - const WstringConverterPtr& = 0); - -// -// Converts the given string from the native narrow string encoding to -// UTF-8 using the given converter. If the converter is null, returns -// the given string. -// +stringToWstring(const std::string& str, + const StringConverterPtr& nc = 0, + const WstringConverterPtr& wc = 0); + +/** + * Converts the given string from the native narrow string encoding to + * UTF-8 using the given converter. + * @param str The native narrow string. + * @param nc The narrow string converter. If null, the native string is returned. + * @return A UTF-8 string. + */ ICE_API std::string -nativeToUTF8(const std::string&, const StringConverterPtr&); - -// -// Converts the given string from UTF-8 to the native narrow string -// encoding using the given converter. If the converter is null, -// returns the given string. -// +nativeToUTF8(const std::string& str, const StringConverterPtr& nc); + +/** + * Converts the given string from UTF-8 to the native narrow string + * encoding using the given converter. + * @param str The UTF-8 string. + * @param nc The narrow string converter. If null, the UTF-8 string is returned. + * @return A native narrow string. + */ ICE_API std::string -UTF8ToNative(const std::string&, const StringConverterPtr&); +UTF8ToNative(const std::string& str, const StringConverterPtr& nc); } namespace IceUtilInternal { + // // Convert from UTF-8 to UTF-16/32 // @@ -168,11 +185,14 @@ ICE_API std::vector<IceUtil::Byte> fromUTF32(const std::vector<unsigned int>&); #ifdef _WIN32 namespace IceUtil { -// -// Create a StringConverter that converts to and from narrow chars -// in the given code page, using MultiByteToWideChar and WideCharToMultiByte -// -ICE_API StringConverterPtr createWindowsStringConverter(unsigned int); + +/** + * Creates a StringConverter that converts to and from narrow chars + * in the given code page, using MultiByteToWideChar and WideCharToMultiByte. + * @param page The code page. + * @return The string converter. + */ +ICE_API StringConverterPtr createWindowsStringConverter(unsigned int page); } #endif diff --git a/cpp/include/IceUtil/UUID.h b/cpp/include/IceUtil/UUID.h index 1cf4f397d4e..5c853371933 100644 --- a/cpp/include/IceUtil/UUID.h +++ b/cpp/include/IceUtil/UUID.h @@ -15,6 +15,10 @@ namespace IceUtil { +/** + * Generates a universally unique identifier (UUID). + * @return The UUID. + */ ICE_API std::string generateUUID(); } |