diff options
144 files changed, 11885 insertions, 2353 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(); } diff --git a/cpp/src/Slice/Parser.cpp b/cpp/src/Slice/Parser.cpp index 3b5cb054be2..ec9496f705d 100644 --- a/cpp/src/Slice/Parser.cpp +++ b/cpp/src/Slice/Parser.cpp @@ -280,6 +280,62 @@ Slice::DefinitionContext::initSuppressedWarnings() } // ---------------------------------------------------------------------- +// Comment +// ---------------------------------------------------------------------- + +bool +Slice::Comment::isDeprecated() const +{ + return _isDeprecated; +} + +StringList +Slice::Comment::deprecated() const +{ + return _deprecated; +} + +StringList +Slice::Comment::overview() const +{ + return _overview; +} + +StringList +Slice::Comment::misc() const +{ + return _misc; +} + +StringList +Slice::Comment::seeAlso() const +{ + return _seeAlso; +} + +StringList +Slice::Comment::returns() const +{ + return _returns; +} + +map<string, StringList> +Slice::Comment::parameters() const +{ + return _parameters; +} + +map<string, StringList> +Slice::Comment::exceptions() const +{ + return _exceptions; +} + +Slice::Comment::Comment() +{ +} + +// ---------------------------------------------------------------------- // SyntaxTreeBase // ---------------------------------------------------------------------- @@ -538,6 +594,330 @@ Slice::Contained::comment() const return _comment; } +namespace +{ + +void +trimLines(StringList& l) +{ + // + // Remove empty trailing lines. + // + while(!l.empty() && l.back().empty()) + { + l.pop_back(); + } +} + +StringList +splitComment(const string& c, bool stripMarkup) +{ + string comment = c; + + if(stripMarkup) + { + // + // Strip HTML markup and javadoc links. + // + string::size_type pos = 0; + do + { + pos = comment.find('<', pos); + if(pos != string::npos) + { + string::size_type endpos = comment.find('>', pos); + if(endpos == string::npos) + { + break; + } + comment.erase(pos, endpos - pos + 1); + } + } + while(pos != string::npos); + + const string link = "{@link"; + pos = 0; + do + { + pos = comment.find(link, pos); + if(pos != string::npos) + { + comment.erase(pos, link.size() + 1); // Erase trailing white space too. + string::size_type endpos = comment.find('}', pos); + if(endpos != string::npos) + { + string ident = comment.substr(pos, endpos - pos); + comment.erase(pos, endpos - pos + 1); + + // + // Replace links of the form {@link Type#member} with "Type.member". + // + string::size_type hash = ident.find('#'); + string rest; + if(hash != string::npos) + { + rest = ident.substr(hash + 1); + ident = ident.substr(0, hash); + if(!ident.empty()) + { + if(!rest.empty()) + { + ident += "." + rest; + } + } + else if(!rest.empty()) + { + ident = rest; + } + } + + comment.insert(pos, ident); + } + } + } + while(pos != string::npos); + } + + StringList result; + + string::size_type pos = 0; + string::size_type nextPos; + while((nextPos = comment.find_first_of('\n', pos)) != string::npos) + { + result.push_back(IceUtilInternal::trim(string(comment, pos, nextPos - pos))); + pos = nextPos + 1; + } + string lastLine = IceUtilInternal::trim(string(comment, pos)); + if(!lastLine.empty()) + { + result.push_back(lastLine); + } + + trimLines(result); + + return result; +} + +bool +parseCommentLine(const string& l, const string& tag, bool namedTag, string& name, string& doc) +{ + doc.clear(); + + if(l.find(tag) == 0) + { + const string ws = " \t"; + + if(namedTag) + { + string::size_type n = l.find_first_not_of(ws, tag.size()); + if(n == string::npos) + { + return false; // Malformed line, ignore it. + } + string::size_type end = l.find_first_of(ws, n); + if(end == string::npos) + { + return false; // Malformed line, ignore it. + } + name = l.substr(n, end - n); + n = l.find_first_not_of(ws, end); + if(n != string::npos) + { + doc = l.substr(n); + } + } + else + { + name.clear(); + + string::size_type n = l.find_first_not_of(ws, tag.size()); + if(n == string::npos) + { + return false; // Malformed line, ignore it. + } + doc = l.substr(n); + } + + return true; + } + + return false; +} + +} + +CommentPtr +Slice::Contained::parseComment(bool stripMarkup) const +{ + CommentPtr comment = new Comment; + + comment->_isDeprecated = false; + + // + // First check metadata for a deprecated tag. + // + string deprecateMetadata; + if(findMetaData("deprecate", deprecateMetadata)) + { + comment->_isDeprecated = true; + if(deprecateMetadata.find("deprecate:") == 0 && deprecateMetadata.size() > 10) + { + comment->_deprecated.push_back(IceUtilInternal::trim(deprecateMetadata.substr(10))); + } + } + + if(!comment->_isDeprecated && _comment.empty()) + { + return 0; + } + + // + // Split up the comment into lines. + // + StringList lines = splitComment(_comment, stripMarkup); + + StringList::const_iterator i; + for(i = lines.begin(); i != lines.end(); ++i) + { + const string l = *i; + if(l[0] == '@') + { + break; + } + comment->_overview.push_back(l); + } + + enum State { StateMisc, StateParam, StateThrows, StateReturn, StateDeprecated }; + State state = StateMisc; + string name; + const string ws = " \t"; + const string paramTag = "@param"; + const string throwsTag = "@throws"; + const string exceptionTag = "@exception"; + const string returnTag = "@return"; + const string deprecatedTag = "@deprecated"; + const string seeTag = "@see"; + for(; i != lines.end(); ++i) + { + const string l = IceUtilInternal::trim(*i); + string line; + if(parseCommentLine(l, paramTag, true, name, line)) + { + if(!line.empty()) + { + state = StateParam; + StringList sl; + sl.push_back(line); // The first line of the description. + comment->_parameters[name] = sl; + } + } + else if(parseCommentLine(l, throwsTag, true, name, line)) + { + if(!line.empty()) + { + state = StateThrows; + StringList sl; + sl.push_back(line); // The first line of the description. + comment->_exceptions[name] = sl; + } + } + else if(parseCommentLine(l, exceptionTag, true, name, line)) + { + if(!line.empty()) + { + state = StateThrows; + StringList sl; + sl.push_back(line); // The first line of the description. + comment->_exceptions[name] = sl; + } + } + else if(parseCommentLine(l, seeTag, false, name, line)) + { + if(!line.empty()) + { + comment->_seeAlso.push_back(line); + } + } + else if(parseCommentLine(l, returnTag, false, name, line)) + { + if(!line.empty()) + { + state = StateReturn; + comment->_returns.push_back(line); // The first line of the description. + } + } + else if(parseCommentLine(l, deprecatedTag, false, name, line)) + { + comment->_isDeprecated = true; + if(!line.empty()) + { + state = StateDeprecated; + comment->_deprecated.push_back(line); // The first line of the description. + } + } + else if(!l.empty()) + { + if(l[0] == '@') + { + // + // Treat all other tags as miscellaneous comments. + // + state = StateMisc; + } + + switch(state) + { + case StateMisc: + { + comment->_misc.push_back(l); + break; + } + case StateParam: + { + assert(!name.empty()); + StringList sl; + if(comment->_parameters.find(name) != comment->_parameters.end()) + { + sl = comment->_parameters[name]; + } + sl.push_back(l); + comment->_parameters[name] = sl; + break; + } + case StateThrows: + { + assert(!name.empty()); + StringList sl; + if(comment->_exceptions.find(name) != comment->_exceptions.end()) + { + sl = comment->_exceptions[name]; + } + sl.push_back(l); + comment->_exceptions[name] = sl; + break; + } + case StateReturn: + { + comment->_returns.push_back(l); + break; + } + case StateDeprecated: + { + comment->_deprecated.push_back(l); + break; + } + } + } + } + + trimLines(comment->_overview); + trimLines(comment->_deprecated); + trimLines(comment->_misc); + trimLines(comment->_returns); + + return comment; +} + int Slice::Contained::includeLevel() const { diff --git a/cpp/src/Slice/Parser.h b/cpp/src/Slice/Parser.h index 11cff96866e..b061c42fe2d 100644 --- a/cpp/src/Slice/Parser.h +++ b/cpp/src/Slice/Parser.h @@ -260,6 +260,43 @@ private: typedef ::IceUtil::Handle<DefinitionContext> DefinitionContextPtr; // ---------------------------------------------------------------------- +// Comment +// ---------------------------------------------------------------------- + +class Comment : public ::IceUtil::SimpleShared +{ +public: + + bool isDeprecated() const; + StringList deprecated() const; + + StringList overview() const; // Contains all introductory lines up to the first tag. + StringList misc() const; // Contains unrecognized tags. + StringList seeAlso() const; // Targets of @see tags. + + StringList returns() const; // Description of an operation's return value. + std::map<std::string, StringList> parameters() const; // Parameter descriptions for an op. Key is parameter name. + std::map<std::string, StringList> exceptions() const; // Exception descriptions for an op. Key is exception name. + +private: + + Comment(); + + bool _isDeprecated; + StringList _deprecated; + StringList _overview; + StringList _misc; + StringList _seeAlso; + + StringList _returns; + std::map<std::string, StringList> _parameters; + std::map<std::string, StringList> _exceptions; + + friend class Contained; +}; +typedef ::IceUtil::Handle<Comment> CommentPtr; + +// ---------------------------------------------------------------------- // GrammarBase // ---------------------------------------------------------------------- @@ -366,6 +403,7 @@ public: std::string file() const; std::string line() const; std::string comment() const; + CommentPtr parseComment(bool) const; int includeLevel() const; void updateIncludeLevel(); diff --git a/cpp/src/slice2cpp/Gen.cpp b/cpp/src/slice2cpp/Gen.cpp index 94a3bd16f21..6631a261e1c 100644 --- a/cpp/src/slice2cpp/Gen.cpp +++ b/cpp/src/slice2cpp/Gen.cpp @@ -311,6 +311,293 @@ resultStructName(const string& name, const string& scope = "", bool marshaledRes return stName; } +string +condMove(bool moveIt, const string& str) +{ + return moveIt ? string("::std::move(") + str + ")" : str; +} + +string +escapeParam(const ParamDeclList& params, const string& name) +{ + string r = name; + for(ParamDeclList::const_iterator p = params.begin(); p != params.end(); ++p) + { + if(fixKwd((*p)->name()) == name) + { + r = name + "_"; + break; + } + } + return r; +} + +void +writeDocLines(Output& out, const StringList& lines, bool commentFirst, const string& space = " ") +{ + StringList l = lines; + if(!commentFirst) + { + out << l.front(); + l.pop_front(); + } + for(StringList::const_iterator i = l.begin(); i != l.end(); ++i) + { + out << nl << " *"; + if(!i->empty()) + { + out << space << *i; + } + } +} + +void +writeSeeAlso(Output& out, const StringList& lines, const string& space = " ") +{ + for(StringList::const_iterator i = lines.begin(); i != lines.end(); ++i) + { + out << nl << " *"; + if(!i->empty()) + { + out << space << "@see " << *i; + } + } +} + +string +getDocSentence(const StringList& lines) +{ + // + // Extract the first sentence. + // + ostringstream ostr; + for(StringList::const_iterator i = lines.begin(); i != lines.end(); ++i) + { + const string ws = " \t"; + + if(i->empty()) + { + break; + } + if(i != lines.begin() && i->find_first_not_of(ws) == 0) + { + ostr << " "; + } + string::size_type pos = i->find('.'); + if(pos == string::npos) + { + ostr << *i; + } + else if(pos == i->size() - 1) + { + ostr << *i; + break; + } + else + { + // + // Assume a period followed by whitespace indicates the end of the sentence. + // + while(pos != string::npos) + { + if(ws.find((*i)[pos + 1]) != string::npos) + { + break; + } + pos = i->find('.', pos + 1); + } + if(pos != string::npos) + { + ostr << i->substr(0, pos + 1); + break; + } + else + { + ostr << *i; + } + } + } + + return ostr.str(); +} + +void +writeDocSummary(Output& out, const ContainedPtr& p) +{ + if(p->comment().empty()) + { + return; + } + + CommentPtr doc = p->parseComment(false); + + out << nl << "/**"; + + if(!doc->overview().empty()) + { + writeDocLines(out, doc->overview(), true); + } + + if(!doc->misc().empty()) + { + writeDocLines(out, doc->misc(), true); + } + + if(!doc->seeAlso().empty()) + { + writeSeeAlso(out, doc->seeAlso()); + } + + if(!doc->deprecated().empty()) + { + out << nl << " *"; + out << nl << " * @deprecated "; + writeDocLines(out, doc->deprecated(), false); + } + else if(doc->isDeprecated()) + { + out << nl << " *"; + out << nl << " * @deprecated"; + } + + switch(p->containedType()) + { + case Contained::ContainedTypeClass: + case Contained::ContainedTypeStruct: + case Contained::ContainedTypeException: + { + UnitPtr unit = p->container()->unit(); + string file = p->file(); + assert(!file.empty()); + static const string prefix = "cpp:doxygen:include:"; + DefinitionContextPtr dc = unit->findDefinitionContext(file); + assert(dc); + string q = dc->findMetaData(prefix); + if(!q.empty()) + { + out << nl << " * \\headerfile " << q.substr(prefix.size()); + } + break; + } + default: + break; + } + + out << nl << " */"; +} + +enum OpDocParamType { OpDocInParams, OpDocOutParams, OpDocAllParams }; + +void +writeOpDocParams(Output& out, const OperationPtr& op, const CommentPtr& doc, OpDocParamType type, + const StringList& preParams = StringList(), const StringList& postParams = StringList()) +{ + ParamDeclList params; + switch(type) + { + case OpDocInParams: + params = op->inParameters(); + break; + case OpDocOutParams: + params = op->outParameters(); + break; + case OpDocAllParams: + params = op->parameters(); + break; + } + + if(!preParams.empty()) + { + writeDocLines(out, preParams, true); + } + + map<string, StringList> paramDoc = doc->parameters(); + for(ParamDeclList::iterator p = params.begin(); p != params.end(); ++p) + { + map<string, StringList>::iterator q = paramDoc.find((*p)->name()); + if(q != paramDoc.end()) + { + out << nl << " * @param " << fixKwd(q->first) << " "; + writeDocLines(out, q->second, false); + } + } + + if(!postParams.empty()) + { + writeDocLines(out, postParams, true); + } +} + +void +writeOpDocExceptions(Output& out, const OperationPtr& op, const CommentPtr& doc) +{ + map<string, StringList> exDoc = doc->exceptions(); + for(map<string, StringList>::iterator p = exDoc.begin(); p != exDoc.end(); ++p) + { + // + // Try to locate the exception's definition using the name given in the comment. + // + string name = p->first; + ExceptionPtr ex = op->container()->lookupException(name, false); + if(ex) + { + name = ex->scoped().substr(2); + } + out << nl << " * @throws " << name << " "; + writeDocLines(out, p->second, false); + } +} + +void +writeOpDocSummary(Output& out, const OperationPtr& op, const CommentPtr& doc, OpDocParamType type, bool showExceptions, + const StringList& preParams = StringList(), const StringList& postParams = StringList(), + const StringList& returns = StringList()) +{ + out << nl << "/**"; + + if(!doc->overview().empty()) + { + writeDocLines(out, doc->overview(), true); + } + + writeOpDocParams(out, op, doc, type, preParams, postParams); + + if(!returns.empty()) + { + out << nl << " * @return "; + writeDocLines(out, returns, false); + } + + if(showExceptions) + { + writeOpDocExceptions(out, op, doc); + } + + if(!doc->misc().empty()) + { + writeDocLines(out, doc->misc(), true); + } + + if(!doc->seeAlso().empty()) + { + writeSeeAlso(out, doc->seeAlso()); + } + + if(!doc->deprecated().empty()) + { + out << nl << " *"; + out << nl << " * @deprecated "; + writeDocLines(out, doc->deprecated(), false); + } + else if(doc->isDeprecated()) + { + out << nl << " *"; + out << nl << " * @deprecated"; + } + + out << nl << " */"; +} + void emitOpNameResult(IceUtilInternal::Output& H, const OperationPtr& p, int useWstring) { @@ -324,60 +611,59 @@ emitOpNameResult(IceUtilInternal::Output& H, const OperationPtr& p, int useWstri string retS = returnTypeToString(ret, p->returnIsOptional(), clScope, p->getMetaData(), useWstring | TypeContextCpp11); - ParamDeclList outParams; - ParamDeclList paramList = p->parameters(); - - for(ParamDeclList::iterator q = paramList.begin(); q != paramList.end(); ++q) - { - if((*q)->isOutParam()) - { - outParams.push_back(*q); - } - } + ParamDeclList outParams = p->outParameters(); if((outParams.size() > 1) || (ret && outParams.size() > 0)) { // // Generate OpNameResult struct // - list<string> dataMembers; string returnValueS = "returnValue"; for(ParamDeclList::iterator q = outParams.begin(); q != outParams.end(); ++q) { - string typeString = typeToString((*q)->type(), (*q)->optional(), clScope, (*q)->getMetaData(), - useWstring | TypeContextCpp11); - - dataMembers.push_back(typeString + " " + fixKwd((*q)->name())); - if((*q)->name() == "returnValue") { returnValueS = "_returnValue"; } } - if(ret) - { - dataMembers.push_front(retS + " " + returnValueS); - } - H << sp; + H << nl << "/**"; + H << nl << " * Encapsulates the results of a call to " << fixKwd(name) << "."; + H << nl << " */"; H << nl << "struct " << resultStructName(name); H << sb; - for(list<string>::const_iterator q = dataMembers.begin(); q != dataMembers.end(); ++q) + CommentPtr comment = p->parseComment(false); + map<string, StringList> paramComments; + if(comment) + { + paramComments = comment->parameters(); + } + if(ret) { - H << nl << *q << ";"; + if(comment && !comment->returns().empty()) + { + H << nl << "/** " << getDocSentence(comment->returns()) << " */"; + } + H << nl << retS << " " << returnValueS << ";"; + } + for(ParamDeclList::iterator q = outParams.begin(); q != outParams.end(); ++q) + { + string typeString = typeToString((*q)->type(), (*q)->optional(), clScope, (*q)->getMetaData(), + useWstring | TypeContextCpp11); + + map<string, StringList>::iterator r = paramComments.find((*q)->name()); + if(r != paramComments.end()) + { + H << nl << "/** " << getDocSentence(r->second) << " */"; + } + H << nl << typeString << " " << fixKwd((*q)->name()) << ";"; } H << eb << ";"; } } -string -condMove(bool moveIt, const string& str) -{ - return moveIt ? string("::std::move(") + str + ")" : str; -} - } Slice::Gen::Gen(const string& base, const string& headerExtension, const string& sourceExtension, @@ -971,15 +1257,31 @@ Slice::Gen::TypesVisitor::visitExceptionStart(const ExceptionPtr& p) DataMemberList allDataMembers = p->allDataMembers(); bool hasDefaultValues = p->hasDefaultValues(); - vector<string> allTypes; vector<string> allParamDecls; vector<string> baseParams; + map<string, CommentPtr> allComments; + + string fileParam = "file"; + string lineParam = "line"; for(DataMemberList::const_iterator q = allDataMembers.begin(); q != allDataMembers.end(); ++q) { string typeName = inputTypeToString((*q)->type(), (*q)->optional(), scope, (*q)->getMetaData(), _useWstring); - allTypes.push_back(typeName); - allParamDecls.push_back(typeName + " iceP_" + (*q)->name()); + allParamDecls.push_back(typeName + " " + fixKwd((*q)->name())); + CommentPtr comment = (*q)->parseComment(false); + if(comment) + { + allComments[(*q)->name()] = comment; + } + + if((*q)->name() == "file") + { + fileParam = "file_"; + } + else if((*q)->name() == "line") + { + fileParam = "line_"; + } } if(base) @@ -987,11 +1289,13 @@ Slice::Gen::TypesVisitor::visitExceptionStart(const ExceptionPtr& p) DataMemberList baseDataMembers = base->allDataMembers(); for(DataMemberList::const_iterator q = baseDataMembers.begin(); q != baseDataMembers.end(); ++q) { - baseParams.push_back("iceP_" + (*q)->name()); + baseParams.push_back(fixKwd((*q)->name())); } } - H << sp << nl << "class " << _dllExport << name << " : "; + H << sp; + writeDocSummary(H, p); + H << nl << "class " << _dllExport << name << " : "; H.useCurrentPosAsIndent(); H << "public "; if(base) @@ -1009,10 +1313,27 @@ Slice::Gen::TypesVisitor::visitExceptionStart(const ExceptionPtr& p) H << nl << "public:"; H.inc(); - H << sp << nl << name << spar; + H << sp; if(p->isLocal()) { - H << "const char*" << "int"; + H << nl << "/**"; + H << nl << " * The file and line number are required for all local exceptions."; + H << nl << " * @param " << fileParam + << " The file name in which the exception was raised, typically __FILE__."; + H << nl << " * @param " << lineParam + << " The line number at which the exception was raised, typically __LINE__."; + H << nl << " */"; + } + else if(hasDefaultValues) + { + H << nl << "/** Default constructor that assigns default values to members as specified in the " + "Slice definition. */"; + } + + H << nl << name << spar; + if(p->isLocal()) + { + H << "const char* " + fileParam << "int " + lineParam; } H << epar; if(!p->isLocal() && !hasDefaultValues) @@ -1023,19 +1344,38 @@ Slice::Gen::TypesVisitor::visitExceptionStart(const ExceptionPtr& p) { H << ';'; } - if(!allTypes.empty()) + if(!allParamDecls.empty()) { + H << nl << "/**"; + H << nl << " * One-shot constructor to initialize all data members."; + if(p->isLocal()) + { + H << nl << " * The file and line number are required for all local exceptions."; + H << nl << " * @param " << fileParam + << " The file name in which the exception was raised, typically __FILE__."; + H << nl << " * @param " << lineParam + << " The line number at which the exception was raised, typically __LINE__."; + } + for(DataMemberList::const_iterator q = allDataMembers.begin(); q != allDataMembers.end(); ++q) + { + map<string, CommentPtr>::iterator r = allComments.find((*q)->name()); + if(r != allComments.end()) + { + H << nl << " * @param " << fixKwd(r->first) << " " << getDocSentence(r->second->overview()); + } + } + H << nl << " */"; H << nl; - if(!p->isLocal() && allTypes.size() == 1) + if(!p->isLocal() && allParamDecls.size() == 1) { H << "explicit "; } H << name << spar; if(p->isLocal()) { - H << "const char*" << "int"; + H << "const char* " + fileParam << "int " + lineParam; } - H << allTypes << epar << ';'; + H << allParamDecls << epar << ';'; } H << nl << "virtual ~" << name << "() throw();"; H << sp; @@ -1055,10 +1395,10 @@ Slice::Gen::TypesVisitor::visitExceptionStart(const ExceptionPtr& p) if(p->isLocal()) { - C << sp << nl << scoped.substr(2) << "::" << name << spar << "const char* file_" << "int line_" << epar - << " :"; + C << sp << nl << scoped.substr(2) << "::" << name << spar << "const char* " + fileParam + << "int " + lineParam << epar << " :"; C.inc(); - emitUpcall(base, "(file_, line_)", scope, true); + emitUpcall(base, "(" + fileParam + ", " + lineParam + ")", scope, true); if(p->hasDefaultValues()) { C << ","; @@ -1078,13 +1418,13 @@ Slice::Gen::TypesVisitor::visitExceptionStart(const ExceptionPtr& p) C << eb; } - if(!allTypes.empty()) + if(!allParamDecls.empty()) { C << sp << nl; C << scoped.substr(2) << "::" << name << spar; if(p->isLocal()) { - C << "const char* file_" << "int line_"; + C << "const char* " + fileParam << "int " + lineParam; } C << allParamDecls << epar; if(p->isLocal() || !baseParams.empty() || !dataMembers.empty()) @@ -1097,7 +1437,7 @@ Slice::Gen::TypesVisitor::visitExceptionStart(const ExceptionPtr& p) upcall = "("; if(p->isLocal()) { - upcall += "file_, line_"; + upcall += fileParam + ", " + lineParam; } for(vector<string>::const_iterator pi = baseParams.begin(); pi != baseParams.end(); ++pi) { @@ -1121,7 +1461,8 @@ Slice::Gen::TypesVisitor::visitExceptionStart(const ExceptionPtr& p) { C << ","; } - C << nl << fixKwd((*d)->name()) << "(iceP_" << (*d)->name() << ')'; + string memberName = fixKwd((*d)->name()); + C << nl << memberName << "(" << memberName << ")"; } if(p->isLocal() || !baseParams.empty() || !dataMembers.empty()) { @@ -1136,6 +1477,10 @@ Slice::Gen::TypesVisitor::visitExceptionStart(const ExceptionPtr& p) C << sb; C << eb; + H << nl << "/**"; + H << nl << " * Obtains the Slice type ID of this exception."; + H << nl << " * @return The fully-scoped type ID."; + H << nl << " */"; H << nl << "virtual ::std::string ice_id() const;"; C << sp << nl << "::std::string" << nl << scoped.substr(2) << "::ice_id() const"; C << sb; @@ -1145,15 +1490,26 @@ Slice::Gen::TypesVisitor::visitExceptionStart(const ExceptionPtr& p) StringList metaData = p->getMetaData(); if(find(metaData.begin(), metaData.end(), "cpp:ice_print") != metaData.end()) { - H << nl << "virtual void ice_print(::std::ostream&) const;"; + H << nl << "/**"; + H << nl << " * Prints this exception to the given stream."; + H << nl << " * @param stream The target stream."; + H << nl << " */"; + H << nl << "virtual void ice_print(::std::ostream& stream) const;"; } + H << nl << "/**"; + H << nl << " * Polymporphically clones this exception."; + H << nl << " * @return A shallow copy of this exception."; + H << nl << " */"; H << nl << "virtual " << name << "* ice_clone() const;"; C << sp << nl << scoped.substr(2) << "*" << nl << scoped.substr(2) << "::ice_clone() const"; C << sb; C << nl << "return new " << name << "(*this);"; C << eb; + H << nl << "/**"; + H << nl << " * Throws this exception."; + H << nl << " */"; H << nl << "virtual void ice_throw() const;"; C << sp << nl << "void" << nl << scoped.substr(2) << "::ice_throw() const"; C << sb; @@ -1164,7 +1520,10 @@ Slice::Gen::TypesVisitor::visitExceptionStart(const ExceptionPtr& p) { if(!base || (base && !base->usesClasses(false))) { - H << sp << nl << "virtual bool _usesClasses() const;"; + H << sp; + H << nl << "/// \\cond STREAM"; + H << nl << "virtual bool _usesClasses() const;"; + H << nl << "/// \\endcond"; C << sp << nl << "bool"; C << nl << scoped.substr(2) << "::_usesClasses() const"; @@ -1198,30 +1557,43 @@ Slice::Gen::TypesVisitor::visitExceptionEnd(const ExceptionPtr& p) if(preserved && !basePreserved) { H << sp; + H << nl << "/**"; + H << nl << " * Obtains the SlicedData object created when an unknown exception type was marshaled"; + H << nl << " * in the sliced format and the Ice run time sliced it to a known type."; + H << nl << " * @return The SlicedData object, or nil if the exception was not sliced or was not"; + H << nl << " * marshaled in the sliced format."; + H << nl << " */"; H << nl << "virtual ::Ice::SlicedDataPtr ice_getSlicedData() const;"; H << sp; + H << nl << "/// \\cond STREAM"; H << nl << "virtual void _write(::Ice::OutputStream*) const;"; H << nl << "virtual void _read(::Ice::InputStream*);"; string baseName = base ? fixKwd(base->scoped()) : string("::Ice::UserException"); H << nl << "using " << baseName << "::_write;"; H << nl << "using " << baseName << "::_read;"; + H << nl << "/// \\endcond"; } H.dec(); H << sp << nl << "protected:"; H.inc(); - H << sp << nl << "virtual void _writeImpl(" << getAbsolute("::Ice::OutputStream*", scope) << ") const;"; + H << sp; + H << nl << "/// \\cond STREAM"; + H << nl << "virtual void _writeImpl(" << getAbsolute("::Ice::OutputStream*", scope) << ") const;"; H << nl << "virtual void _readImpl(" << getAbsolute("::Ice::InputStream*", scope) << ");"; + H << nl << "/// \\endcond"; string baseName = getAbsolute(base ? fixKwd(base->scoped()) : "::Ice::UserException", scope); if(preserved && !basePreserved) { - - H << sp << nl << "::Ice::SlicedDataPtr _slicedData;"; + H << sp; + H << nl << "/// \\cond STREAM"; + H << nl << "::Ice::SlicedDataPtr _slicedData;"; + H << nl << "/// \\endcond"; C << sp; C << nl << "::Ice::SlicedDataPtr" << nl << scoped.substr(2) << "::ice_getSlicedData() const"; @@ -1246,7 +1618,9 @@ Slice::Gen::TypesVisitor::visitExceptionEnd(const ExceptionPtr& p) C << eb; } - C << sp << nl << "void" << nl << scoped.substr(2) << "::_writeImpl(" + C << sp; + C << nl << "/// \\cond STREAM"; + C << nl << "void" << nl << scoped.substr(2) << "::_writeImpl(" << getAbsolute("::Ice::OutputStream*", scope) << " ostr) const"; C << sb; C << nl << "ostr->startSlice(\"" << p->scoped() << "\", -1, " << (!base ? "true" : "false") << ");"; @@ -1271,6 +1645,7 @@ Slice::Gen::TypesVisitor::visitExceptionEnd(const ExceptionPtr& p) emitUpcall(base, "::_readImpl(istr);", scope); } C << eb; + C << nl << "/// \\endcond"; } H << eb << ';'; @@ -1284,7 +1659,10 @@ Slice::Gen::TypesVisitor::visitExceptionEnd(const ExceptionPtr& p) if(!_doneStaticSymbol) { _doneStaticSymbol = true; - H << sp << nl << "static " << name << " _iceS_" << p->name() << "_init;"; + H << sp; + H << nl << "/// \\cond INTERNAL"; + H << nl << "static " << name << " _iceS_" << p->name() << "_init;"; + H << nl << "/// \\endcond"; } } @@ -1299,10 +1677,13 @@ Slice::Gen::TypesVisitor::visitStructStart(const StructPtr& p) string scope = fixKwd(p->scope()); string name = fixKwd(p->name()); + H << sp; + writeDocSummary(H, p); + bool classMetaData = findMetaData(p->getMetaData()) == "%class"; if(classMetaData) { - H << sp << nl << "class " << name << " : public IceUtil::Shared"; + H << nl << "class " << name << " : public IceUtil::Shared"; H << sb; H.dec(); H << nl << "public:"; @@ -1310,6 +1691,8 @@ Slice::Gen::TypesVisitor::visitStructStart(const StructPtr& p) H << nl; if(p->hasDefaultValues()) { + H << nl << "/** Default constructor that assigns default values to members as specified in the " + "Slice definition. */"; H << nl << name << "() :"; H.inc(); writeDataMemberInitializers(H, dataMembers, _useWstring); @@ -1324,12 +1707,13 @@ Slice::Gen::TypesVisitor::visitStructStart(const StructPtr& p) } else { - H << sp << nl << "struct " << name; + H << nl << "struct " << name; H << sb; if(p->hasDefaultValues()) { + H << nl << "/** Default constructor that assigns default values to members as specified in the " + "Slice definition. */"; H << nl << name << "() :"; - H.inc(); writeDataMemberInitializers(H, dataMembers, _useWstring); H.dec(); @@ -1345,12 +1729,32 @@ Slice::Gen::TypesVisitor::visitStructStart(const StructPtr& p) if(!dataMembers.empty() && (findMetaData(p->getMetaData()) == "%class" || p->hasDefaultValues())) { vector<string> paramDecls; - vector<string> types; + map<string, CommentPtr> comments; for(DataMemberList::const_iterator q = dataMembers.begin(); q != dataMembers.end(); ++q) { - string typeName = inputTypeToString((*q)->type(), (*q)->optional(), scope, (*q)->getMetaData(), _useWstring); - types.push_back(typeName); - paramDecls.push_back(typeName + " iceP_" + (*q)->name()); + string typeName = + inputTypeToString((*q)->type(), (*q)->optional(), scope, (*q)->getMetaData(), _useWstring); + paramDecls.push_back(typeName + " " + fixKwd((*q)->name())); + CommentPtr comment = (*q)->parseComment(false); + if(comment && !comment->overview().empty()) + { + comments[(*q)->name()] = comment; + } + } + + if(!comments.empty()) + { + H << nl << "/**"; + H << nl << " * One-shot constructor to initialize all data members."; + for(DataMemberList::const_iterator q = dataMembers.begin(); q != dataMembers.end(); ++q) + { + map<string, CommentPtr>::iterator r = comments.find((*q)->name()); + if(r != comments.end()) + { + H << nl << " * @param " << fixKwd(r->first) << " " << getDocSentence(r->second->overview()); + } + } + H << nl << " */"; } H << nl; @@ -1368,7 +1772,7 @@ Slice::Gen::TypesVisitor::visitStructStart(const StructPtr& p) H << ','; } string memberName = fixKwd((*q)->name()); - H << nl << memberName << '(' << "iceP_" << (*q)->name() << ')'; + H << nl << memberName << '(' << memberName << ')'; } H.dec(); @@ -1482,6 +1886,8 @@ Slice::Gen::TypesVisitor::visitDataMember(const DataMemberPtr& p) { scope = fixKwd(ex->scope()); } + + writeDocSummary(H, p); H << nl << typeToString(p->type(), p->optional(), scope, p->getMetaData(), _useWstring) << ' ' << name << ';'; } @@ -1498,6 +1904,8 @@ Slice::Gen::TypesVisitor::visitSequence(const SequencePtr& p) string seqType = findMetaData(metaData, _useWstring); H << sp; + writeDocSummary(H, p); + if(!seqType.empty()) { H << nl << "typedef " << seqType << ' ' << name << ';'; @@ -1516,6 +1924,9 @@ Slice::Gen::TypesVisitor::visitDictionary(const DictionaryPtr& p) string scope = fixKwd(cont->scope()); string dictType = findMetaData(p->getMetaData()); + H << sp; + writeDocSummary(H, p); + if(dictType.empty()) { // @@ -1531,14 +1942,14 @@ Slice::Gen::TypesVisitor::visitDictionary(const DictionaryPtr& p) } string vs = typeToString(valueType, scope, p->valueMetaData(), _useWstring); - H << sp << nl << "typedef ::std::map<" << ks << ", " << vs << "> " << name << ';'; + H << nl << "typedef ::std::map<" << ks << ", " << vs << "> " << name << ';'; } else { // // A custom dictionary // - H << sp << nl << "typedef " << dictType << ' ' << name << ';'; + H << nl << "typedef " << dictType << ' ' << name << ';'; } } @@ -1555,12 +1966,16 @@ Slice::Gen::TypesVisitor::visitEnum(const EnumPtr& p) // const bool explicitValue = p->explicitValue(); - H << sp << nl << "enum " << name; + H << sp; + writeDocSummary(H, p); + + H << nl << "enum " << name; H << sb; EnumeratorList::const_iterator en = enumerators.begin(); while(en != enumerators.end()) { + writeDocSummary(H, *en); H << nl << fixKwd(enumeratorPrefix + (*en)->name()); // // If any of the enumerators were assigned an explicit value, we emit @@ -1583,6 +1998,7 @@ Slice::Gen::TypesVisitor::visitConst(const ConstPtr& p) { string scope = fixKwd(p->scope()); H << sp; + writeDocSummary(H, p); H << nl << "const " << typeToString(p->type(), scope, p->typeMetaData(), _useWstring) << " " << fixKwd(p->name()) << " = "; writeConstantValue(H, p->type(), p->valueType(), p->value(), _useWstring, p->typeMetaData(), scope); @@ -1666,9 +2082,11 @@ Slice::Gen::ProxyDeclVisitor::visitClassDecl(const ClassDeclPtr& p) // an interface named 'readProxy' // Note that _readProxy is always in the IceProxy::... namespace // + H << nl << "/// \\cond INTERNAL"; H << nl << _dllExport << "void _readProxy(::Ice::InputStream*, ::IceInternal::ProxyHandle< ::IceProxy" << scoped << ">&);"; H << nl << _dllExport << "::IceProxy::Ice::Object* upCast(::IceProxy" << scoped << "*);"; + H << nl << "/// \\endcond"; } Slice::Gen::ProxyVisitor::ProxyVisitor(Output& h, Output& c, const string& dllExport) : @@ -1745,7 +2163,9 @@ Slice::Gen::ProxyVisitor::visitClassDefStart(const ClassDefPtr& p) string baseName = fixKwd("_" + p->name() + "Base"); - H << sp << nl << "class " << _dllClassExport << baseName << " : "; + H << sp; + H << nl << "/// \\cond INTERNAL"; + H << nl << "class " << _dllClassExport << baseName << " : "; H.useCurrentPosAsIndent(); for(ClassList::const_iterator q = bases.begin(); q != bases.end();) { @@ -1775,6 +2195,7 @@ Slice::Gen::ProxyVisitor::visitClassDefStart(const ClassDefPtr& p) H << sp << nl << "virtual Object* _newInstance() const = 0;"; H << eb << ';'; + H << nl << "/// \\endcond"; } H << sp << nl << "class " << _dllClassExport << name << " : "; @@ -1798,6 +2219,8 @@ Slice::Gen::ProxyVisitor::visitClassDefStart(const ClassDefPtr& p) H << nl << "public:"; H.inc(); + C << sp; + C << nl << "/// \\cond INTERNAL"; C << nl << _dllExport << "::IceProxy::Ice::Object* ::IceProxy" << scope << "upCast(" << name << "* p) { return p; }"; @@ -1818,6 +2241,7 @@ Slice::Gen::ProxyVisitor::visitClassDefStart(const ClassDefPtr& p) C << nl << "v->_copyFrom(proxy);"; C << eb; C << eb; + C << nl << "/// \\endcond"; return true; } @@ -1829,20 +2253,30 @@ Slice::Gen::ProxyVisitor::visitClassDefEnd(const ClassDefPtr& p) string scoped = fixKwd(p->scoped()); string scope = fixKwd(p->scope()); - H << sp << nl << _dllMemberExport << "static const ::std::string& ice_staticId();"; + H << sp; + H << nl << "/**"; + H << nl << " * Obtains the Slice type ID corresponding to this " << (p->isInterface() ? "interface" : "class") + << "."; + H << nl << " * @return A fully-scoped type ID."; + H << nl << " */"; + H << nl << _dllMemberExport << "static const ::std::string& ice_staticId();"; H.dec(); H << sp << nl << "protected:"; H.inc(); + H << nl << "/// \\cond INTERNAL"; H << sp << nl << _dllMemberExport << "virtual ::IceProxy::Ice::Object* _newInstance() const;"; + H << nl << "/// \\endcond"; H << eb << ';'; C << sp; + C << nl << "/// \\cond INTERNAL"; C << nl << "::IceProxy::Ice::Object*"; C << nl << "IceProxy" << scoped << "::_newInstance() const"; C << sb; C << nl << "return new " << name << ";"; C << eb; + C << nl << "/// \\endcond"; C << sp; C << nl << "const ::std::string&" << nl << "IceProxy" << scoped << "::ice_staticId()"; @@ -1897,7 +2331,8 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p) bool retIsOpt = p->returnIsOptional(); string retS = returnTypeToString(ret, retIsOpt, "", p->getMetaData(), _useWstring | TypeContextAMIEnd); - string retSEndAMI = returnTypeToString(ret, retIsOpt, "", p->getMetaData(), _useWstring | TypeContextAMIPrivateEnd); + string retSEndAMI = + returnTypeToString(ret, retIsOpt, "", p->getMetaData(), _useWstring | TypeContextAMIPrivateEnd); string retInS = retS != "void" ? inputTypeToString(ret, retIsOpt, "", p->getMetaData(), _useWstring) : ""; ContainerPtr container = p->container(); @@ -1907,35 +2342,42 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p) string delName = "Callback_" + clName + "_" + name; string delNameScoped = clScope + delName; - vector<string> params; vector<string> paramsDecl; vector<string> args; vector<string> paramsAMI; vector<string> paramsDeclAMI; + vector<string> paramsDeclAMIBeginI; vector<string> argsAMI; vector<string> outParamsAMI; vector<string> outParamNamesAMI; vector<string> outParamsDeclAMI; + vector<string> outParamsDeclImplAMI; vector<string> outParamsDeclEndAMI; vector<string> outDecls; ParamDeclList paramList = p->parameters(); - ParamDeclList inParams; - ParamDeclList outParams; + ParamDeclList inParams = p->inParameters(); + ParamDeclList outParams = p->outParameters(); + + const string contextParam = escapeParam(paramList, "context"); + const string cbParam = escapeParam(inParams, "cb"); + const string cookieParam = escapeParam(paramList, "cookie"); + const string resultParam = escapeParam(outParams, "result"); vector<string> outEndArgs; for(ParamDeclList::const_iterator q = paramList.begin(); q != paramList.end(); ++q) { - string paramName = fixKwd(paramPrefix + (*q)->name()); + string paramName = fixKwd((*q)->name()); StringList metaData = (*q)->getMetaData(); string typeString; string typeStringEndAMI; if((*q)->isOutParam()) { - typeString = outputTypeToString((*q)->type(), (*q)->optional(), "", metaData, _useWstring | TypeContextAMIEnd); + typeString = + outputTypeToString((*q)->type(), (*q)->optional(), "", metaData, _useWstring | TypeContextAMIEnd); typeStringEndAMI = outputTypeToString((*q)->type(), (*q)->optional(), "", metaData, _useWstring | TypeContextAMIPrivateEnd); } @@ -1944,7 +2386,6 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p) typeString = inputTypeToString((*q)->type(), (*q)->optional(), "", metaData, _useWstring); } - params.push_back(typeString); paramsDecl.push_back(typeString + ' ' + paramName); args.push_back(paramName); @@ -1952,17 +2393,18 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p) { paramsAMI.push_back(typeString); paramsDeclAMI.push_back(typeString + ' ' + paramName); + paramsDeclAMIBeginI.push_back(typeString + ' ' + paramPrefix + (*q)->name()); argsAMI.push_back(paramName); - inParams.push_back(*q); } else { outParamsAMI.push_back(typeString); outParamNamesAMI.push_back(paramName); outParamsDeclAMI.push_back(typeString + ' ' + paramName); - outParamsDeclEndAMI.push_back(typeStringEndAMI + ' ' + paramName); - outParams.push_back(*q); - outDecls.push_back(inputTypeToString((*q)->type(), (*q)->optional(), "", (*q)->getMetaData(), _useWstring)); + outParamsDeclImplAMI.push_back(typeString + ' ' + paramPrefix + (*q)->name()); + outParamsDeclEndAMI.push_back(typeStringEndAMI + ' ' + paramPrefix + (*q)->name()); + outDecls.push_back( + inputTypeToString((*q)->type(), (*q)->optional(), "", (*q)->getMetaData(), _useWstring)); outEndArgs.push_back(getEndArg((*q)->type(), (*q)->getMetaData(), outParamNamesAMI.back())); } } @@ -1987,61 +2429,147 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p) string thisPointer = fixKwd(scope.substr(0, scope.size() - 2)) + "*"; - string deprecateSymbol = getDeprecateSymbol(p, cl); - H << sp << nl << deprecateSymbol << _dllMemberExport << retS << ' ' << fixKwd(name) << spar << paramsDecl - << "const ::Ice::Context& context = ::Ice::noExplicitContext" << epar; + CommentPtr comment = p->parseComment(false); + const string contextDoc = "@param " + contextParam + " The Context map to send with the invocation."; + const string contextDecl = "const ::Ice::Context& " + contextParam + " = ::Ice::noExplicitContext"; + const string resultDoc = "The asynchronous result object for the invocation."; + const string cbDoc = "@param " + cbParam + " Asynchronous callback object."; + const string cookieDoc = "@param " + cookieParam + " User-defined data to associate with the invocation."; + const string cookieDecl = "const ::Ice::LocalObjectPtr& " + cookieParam + " = 0"; + + const string deprecateSymbol = getDeprecateSymbol(p, cl); + H << sp; + if(comment) + { + StringList postParams; + postParams.push_back(contextDoc); + writeOpDocSummary(H, p, comment, OpDocAllParams, true, StringList(), postParams, comment->returns()); + } + H << nl << deprecateSymbol << _dllMemberExport << retS << ' ' << fixKwd(name) << spar << paramsDecl + << contextDecl << epar; H << sb << nl; if(ret) { H << "return "; } H << "end_" << name << spar << outParamNamesAMI << "_iceI_begin_" + name << spar << argsAMI; - H << "context" << "::IceInternal::dummyCallback" << "0" << "true" << epar << epar << ';'; + H << contextParam << "::IceInternal::dummyCallback" << "0" << "true" << epar << epar << ';'; H << eb; - H << sp << nl << "::Ice::AsyncResultPtr begin_" << name << spar << paramsDeclAMI - << "const ::Ice::Context& context = ::Ice::noExplicitContext" << epar; + H << sp; + if(comment) + { + StringList postParams, returns; + postParams.push_back(contextDoc); + returns.push_back(resultDoc); + writeOpDocSummary(H, p, comment, OpDocInParams, false, StringList(), postParams, returns); + } + H << nl << "::Ice::AsyncResultPtr begin_" << name << spar << paramsDeclAMI << contextDecl << epar; H << sb; - H << nl << "return _iceI_begin_" << name << spar << argsAMI << "context" << "::IceInternal::dummyCallback" << "0" + H << nl << "return _iceI_begin_" << name << spar << argsAMI << contextParam << "::IceInternal::dummyCallback" + << "0" << epar << ';'; H << eb; - H << sp << nl << "::Ice::AsyncResultPtr begin_" << name << spar << paramsDeclAMI - << "const ::Ice::CallbackPtr& del" - << "const ::Ice::LocalObjectPtr& cookie = 0" << epar; + H << sp; + if(comment) + { + StringList postParams, returns; + postParams.push_back(cbDoc); + postParams.push_back(cookieDoc); + returns.push_back(resultDoc); + writeOpDocSummary(H, p, comment, OpDocInParams, false, StringList(), postParams, returns); + } + H << nl << "::Ice::AsyncResultPtr begin_" << name << spar << paramsDeclAMI + << "const ::Ice::CallbackPtr& " + cbParam + << cookieDecl << epar; H << sb; - H << nl << "return _iceI_begin_" << name << spar << argsAMI << "::Ice::noExplicitContext" << "del" << "cookie" << epar << ';'; + H << nl << "return _iceI_begin_" << name << spar << argsAMI << "::Ice::noExplicitContext" << cbParam << cookieParam + << epar << ';'; H << eb; - H << sp << nl << "::Ice::AsyncResultPtr begin_" << name << spar << paramsDeclAMI - << "const ::Ice::Context& context" - << "const ::Ice::CallbackPtr& del" - << "const ::Ice::LocalObjectPtr& cookie = 0" << epar; + H << sp; + if(comment) + { + StringList postParams, returns; + postParams.push_back(contextDoc); + postParams.push_back(cbDoc); + postParams.push_back(cookieDoc); + returns.push_back(resultDoc); + writeOpDocSummary(H, p, comment, OpDocInParams, false, StringList(), postParams, returns); + } + H << nl << "::Ice::AsyncResultPtr begin_" << name << spar << paramsDeclAMI + << "const ::Ice::Context& " + contextParam + << "const ::Ice::CallbackPtr& " + cbParam + << cookieDecl << epar; H << sb; - H << nl << "return _iceI_begin_" << name << spar << argsAMI << "context" << "del" << "cookie" << epar << ';'; + H << nl << "return _iceI_begin_" << name << spar << argsAMI << contextParam << cbParam << cookieParam << epar + << ';'; H << eb; - H << sp << nl << "::Ice::AsyncResultPtr begin_" << name << spar << paramsDeclAMI - << "const " + delNameScoped + "Ptr& del" - << "const ::Ice::LocalObjectPtr& cookie = 0" << epar; + H << sp; + if(comment) + { + StringList postParams, returns; + postParams.push_back(cbDoc); + postParams.push_back(cookieDoc); + returns.push_back(resultDoc); + writeOpDocSummary(H, p, comment, OpDocInParams, false, StringList(), postParams, returns); + } + H << nl << "::Ice::AsyncResultPtr begin_" << name << spar << paramsDeclAMI + << "const " + delNameScoped + "Ptr& " + cbParam + << cookieDecl << epar; H << sb; - H << nl << "return _iceI_begin_" << name << spar << argsAMI << "::Ice::noExplicitContext" << "del" << "cookie" << epar << ';'; + H << nl << "return _iceI_begin_" << name << spar << argsAMI << "::Ice::noExplicitContext" << cbParam << cookieParam + << epar << ';'; H << eb; - H << sp << nl << "::Ice::AsyncResultPtr begin_" << name << spar << paramsDeclAMI - << "const ::Ice::Context& context" - << "const " + delNameScoped + "Ptr& del" - << "const ::Ice::LocalObjectPtr& cookie = 0" << epar; + H << sp; + if(comment) + { + StringList postParams, returns; + postParams.push_back(contextDoc); + postParams.push_back(cbDoc); + postParams.push_back(cookieDoc); + returns.push_back(resultDoc); + writeOpDocSummary(H, p, comment, OpDocInParams, false, StringList(), postParams, returns); + } + H << nl << "::Ice::AsyncResultPtr begin_" << name << spar << paramsDeclAMI + << "const ::Ice::Context& " + contextParam + << "const " + delNameScoped + "Ptr& " + cbParam + << cookieDecl << epar; H << sb; - H << nl << "return _iceI_begin_" << name << spar << argsAMI << "context" << "del" << "cookie" << epar << ';'; + H << nl << "return _iceI_begin_" << name << spar << argsAMI << contextParam << cbParam << cookieParam << epar + << ';'; H << eb; - H << sp << nl << _dllMemberExport << retS << " end_" << name << spar << outParamsDeclAMI - << "const ::Ice::AsyncResultPtr&" << epar << ';'; + H << sp; + if(comment) + { + H << nl << "/**"; + H << nl << " * Completes an invocation of begin_" << name << "."; + StringList postParams; + postParams.push_back("@param " + resultParam + " " + resultDoc); + writeOpDocParams(H, p, comment, OpDocOutParams, StringList(), postParams); + if(!comment->returns().empty()) + { + H << nl << " * @return "; + writeDocLines(H, comment->returns(), false); + } + if(!comment->exceptions().empty()) + { + writeOpDocExceptions(H, p, comment); + } + H << nl << " */"; + } + H << nl << _dllMemberExport << retS << " end_" << name << spar << outParamsDeclAMI + << "const ::Ice::AsyncResultPtr& " + resultParam << epar << ';'; if(generatePrivateEnd) { + H << nl << "/// \\cond INTERNAL"; H << sp << nl << _dllMemberExport << "void _iceI_end_" << name << spar << outParamsDeclEndAMI; H << "const ::Ice::AsyncResultPtr&" << epar << ';'; + H << nl << "/// \\endcond"; } H.dec(); @@ -2058,7 +2586,8 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p) H << nl << "public:"; H.inc(); - C << sp << nl << "::Ice::AsyncResultPtr" << nl << "IceProxy" << scope << "_iceI_begin_" << name << spar << paramsDeclAMI + C << sp << nl << "::Ice::AsyncResultPtr" << nl << "IceProxy" << scope << "_iceI_begin_" << name << spar + << paramsDeclAMIBeginI << "const ::Ice::Context& context" << "const ::IceInternal::CallbackBasePtr& del" << "const ::Ice::LocalObjectPtr& cookie" << "bool sync" << epar; C << sb; @@ -2094,7 +2623,7 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p) C << nl << "return result;"; C << eb; - C << sp << nl << retS << nl << "IceProxy" << scope << "end_" << name << spar << outParamsDeclAMI + C << sp << nl << retS << nl << "IceProxy" << scope << "end_" << name << spar << outParamsDeclImplAMI << "const ::Ice::AsyncResultPtr& result" << epar; C << sb; if(p->returnsData()) @@ -2261,7 +2790,9 @@ Slice::Gen::ObjectDeclVisitor::visitClassDecl(const ClassDeclPtr& p) // upCast is not _upCast nor _iceUpCast for historical reasons. IceInternal::Handle // depends on this name // + H << nl << "/// \\cond INTERNAL"; H << nl << _dllExport << getAbsolute("::Ice::Object*", scope) << " upCast(" << name << "*);"; + H << nl << "/// \\endcond"; H << nl << "typedef ::IceInternal::Handle< " << name << "> " << p->name() << "Ptr;"; H << nl << "typedef ::IceInternal::ProxyHandle< ::IceProxy" << scoped << "> " << p->name() << "Prx;"; H << nl << "typedef " << p->name() << "Prx " << p->name() << "PrxPtr;"; @@ -2270,13 +2801,17 @@ Slice::Gen::ObjectDeclVisitor::visitClassDecl(const ClassDeclPtr& p) // _ice prefix because this function is in the Slice module namespace, where the user // is allowed to define classes, functions etc. that start with _. // + H << nl << "/// \\cond INTERNAL"; H << nl << _dllExport << "void _icePatchObjectPtr(" << p->name() << "Ptr&, const " << getAbsolute("::Ice::ObjectPtr&", scope) << ");"; + H << nl << "/// \\endcond"; } else { + H << nl << "/// \\cond INTERNAL"; H << nl << _dllExport << getAbsolute("::Ice::LocalObject*", scope) << " upCast(" << getAbsolute(scoped, scope) << "*);"; + H << nl << "/// \\endcond"; H << nl << "typedef ::IceInternal::Handle< " << name << "> " << p->name() << "Ptr;"; } } @@ -2342,7 +2877,9 @@ Slice::Gen::ObjectVisitor::visitClassDefStart(const ClassDefPtr& p) bool basePreserved = p->inheritsMetaData("preserve-slice"); bool preserved = basePreserved || p->hasMetaData("preserve-slice"); - H << sp << nl << "class " << _dllExport << name << " : "; + H << sp; + writeDocSummary(H, p); + H << nl << "class " << _dllExport << name << " : "; H.useCurrentPosAsIndent(); if(bases.empty()) { @@ -2401,7 +2938,6 @@ Slice::Gen::ObjectVisitor::visitClassDefStart(const ClassDefPtr& p) C << eb; vector<string> params; - vector<string> allTypes; vector<string> allParamDecls; for(DataMemberList::const_iterator q = dataMembers.begin(); q != dataMembers.end(); ++q) @@ -2412,15 +2948,17 @@ Slice::Gen::ObjectVisitor::visitClassDefStart(const ClassDefPtr& p) for(DataMemberList::const_iterator q = allDataMembers.begin(); q != allDataMembers.end(); ++q) { string typeName = inputTypeToString((*q)->type(), (*q)->optional(), scope, (*q)->getMetaData(), _useWstring); - allTypes.push_back(typeName); - allParamDecls.push_back(typeName + " iceP_" + (*q)->name()); + allParamDecls.push_back(typeName + " " + fixKwd((*q)->name())); } if(!p->isInterface()) { if(p->hasDefaultValues()) { - H << sp << nl << name << "() :"; + H << sp; + H << nl << "/** Default constructor that assigns default values to members as specified in the " + "Slice definition. */"; + H << nl << name << "() :"; H.inc(); writeDataMemberInitializers(H, dataMembers, _useWstring); H.dec(); @@ -2438,10 +2976,13 @@ Slice::Gen::ObjectVisitor::visitClassDefStart(const ClassDefPtr& p) if(!p->isLocal()) { - C << sp << nl + C << sp; + C << nl << "/// \\cond INTERNAL"; + C << nl << _dllExport << "::Ice::Object* " << scope.substr(2) << "upCast(" << name << "* p) { return p; }" << nl; + C << nl << "/// \\endcond"; // // It would make sense to provide a covariant ice_clone(); unfortunately many compilers @@ -2450,9 +2991,14 @@ Slice::Gen::ObjectVisitor::visitClassDefStart(const ClassDefPtr& p) if(!p->isInterface()) { - H << sp << nl << "virtual " << getAbsolute("::Ice::ObjectPtr", scope) << " ice_clone() const;"; + H << sp; + H << nl << "/**"; + H << nl << " * Polymporphically clones this object."; + H << nl << " * @return A shallow copy of this object."; + H << nl << " */"; + H << nl << "virtual " << getAbsolute("::Ice::ObjectPtr", scope) << " ice_clone() const;"; - if(hasGCObjectBaseClass) + if(hasGCObjectBaseClass) { C.zeroIndent(); C << sp; @@ -2504,13 +3050,36 @@ Slice::Gen::ObjectVisitor::visitClassDefStart(const ClassDefPtr& p) StringList::difference_type scopedPos = IceUtilInternal::distance(firstIter, scopedIter); H << sp; - H << nl << "virtual bool ice_isA(const ::std::string&, const " << getAbsolute("::Ice::Current&", scope) - << " = " << getAbsolute("::Ice::emptyCurrent", scope) << ") const;"; + H << nl << "/**"; + H << nl << " * Determines whether this object supports an interface with the given Slice type ID."; + H << nl << " * @param id The fully-scoped Slice type ID."; + H << nl << " * @param current The Current object for the invocation."; + H << nl << " * @return True if this object supports the interface, false, otherwise."; + H << nl << " */"; + H << nl << "virtual bool ice_isA(const ::std::string& id, const " << getAbsolute("::Ice::Current&", scope) + << " current = " << getAbsolute("::Ice::emptyCurrent", scope) << ") const;"; + H << sp; + H << nl << "/**"; + H << nl << " * Obtains a list of the Slice type IDs representing the interfaces supported by this object."; + H << nl << " * @param current The Current object for the invocation."; + H << nl << " * @return A list of fully-scoped type IDs."; + H << nl << " */"; H << nl << "virtual ::std::vector< ::std::string> ice_ids(const " << getAbsolute("::Ice::Current&", scope) - << " = " << getAbsolute("::Ice::emptyCurrent", scope) << ") const;"; + << " current = " << getAbsolute("::Ice::emptyCurrent", scope) << ") const;"; + H << sp; + H << nl << "/**"; + H << nl << " * Obtains a Slice type ID representing the most-derived interface supported by this object."; + H << nl << " * @param current The Current object for the invocation."; + H << nl << " * @return A fully-scoped type ID."; + H << nl << " */"; H << nl << "virtual const ::std::string& ice_id(const " << getAbsolute("::Ice::Current&", scope) - << " = " << getAbsolute("::Ice::emptyCurrent", scope) << ") const;"; - H << sp << nl << "static const ::std::string& ice_staticId();"; + << " current = " << getAbsolute("::Ice::emptyCurrent", scope) << ") const;"; + H << sp; + H << nl << "/**"; + H << nl << " * Obtains the Slice type ID corresponding to this class."; + H << nl << " * @return A fully-scoped type ID."; + H << nl << " */"; + H << nl << "static const ::std::string& ice_staticId();"; string flatName = "iceC" + p->flattenedScope() + p->name() + "_ids"; @@ -2573,9 +3142,13 @@ Slice::Gen::ObjectVisitor::visitClassDefStart(const ClassDefPtr& p) } else { - C << sp << nl + C << sp; + C << nl << "/// \\cond INTERNAL"; + C << nl << _dllExport - << "::Ice::LocalObject* " << scope.substr(2) << "upCast(" << getAbsolute(scoped, scope) << "* p) { return p; }"; + << "::Ice::LocalObject* " << scope.substr(2) << "upCast(" << getAbsolute(scoped, scope) + << "* p) { return p; }"; + C << nl << "/// \\endcond"; } return true; @@ -2615,8 +3188,10 @@ Slice::Gen::ObjectVisitor::visitClassDefEnd(const ClassDefPtr& p) allOpNames.unique(); H << sp; + H << nl << "/// \\cond INTERNAL"; H << nl << "virtual bool _iceDispatch(::IceInternal::Incoming&, const " << getAbsolute("::Ice::Current&", scope) << ");"; + H << nl << "/// \\endcond"; string flatName = "iceC" + p->flattenedScope() + p->name() + "_all"; C << sp << nl << "namespace"; @@ -2635,6 +3210,7 @@ Slice::Gen::ObjectVisitor::visitClassDefEnd(const ClassDefPtr& p) C << eb << ';'; C << sp << nl << "}"; C << sp; + C << nl << "/// \\cond INTERNAL"; C << nl << "bool"; C << nl << scoped.substr(2) << "::_iceDispatch(::IceInternal::Incoming& in, const " << getAbsolute("::Ice::Current&", scope) << " current)"; @@ -2667,6 +3243,7 @@ Slice::Gen::ObjectVisitor::visitClassDefEnd(const ClassDefPtr& p) C << eb; C << eb; C << eb; + C << nl << "/// \\endcond"; // // Check if we need to generate ice_operationAttributes() @@ -2684,8 +3261,10 @@ Slice::Gen::ObjectVisitor::visitClassDefEnd(const ClassDefPtr& p) if(!attributesMap.empty()) { H << sp; + H << nl << "/// \\cond INTERNAL"; H << nl << "virtual " << getAbsolute("::Ice::Int", scope) << " ice_operationAttributes(const ::std::string&) const;"; + H << nl << "/// \\endcond"; string opAttrFlatName = "iceC" + p->flattenedScope() + p->name() + "_operationAttributes"; @@ -2736,16 +3315,30 @@ Slice::Gen::ObjectVisitor::visitClassDefEnd(const ClassDefPtr& p) if(!p->isAbstract()) { - H << sp << nl << "static " << getAbsolute("::Ice::ValueFactoryPtr", scope) << " ice_factory();"; + H << sp; + H << nl << "/**"; + H << nl << " * Obtains a value factory that instantiates this class."; + H << nl << " * @return The value factory."; + H << nl << " */"; + H << nl << "static " << getAbsolute("::Ice::ValueFactoryPtr", scope) << " ice_factory();"; } if(preserved && !basePreserved) { - H << sp << nl << "virtual " << getAbsolute("::Ice::SlicedDataPtr", scope) << " ice_getSlicedData() const;"; + H << sp; + H << nl << "/**"; + H << nl << " * Obtains the SlicedData object created when an unknown class type was marshaled"; + H << nl << " * in the sliced format and the Ice run time sliced it to a known type."; + H << nl << " * @return The SlicedData object, or nil if the class was not sliced or was not"; + H << nl << " * marshaled in the sliced format."; + H << nl << " */"; + H << nl << "virtual " << getAbsolute("::Ice::SlicedDataPtr", scope) << " ice_getSlicedData() const;"; H << sp; + H << nl << "/// \\cond STREAM"; H << nl << "virtual void _iceWrite(" << getAbsolute("::Ice::OutputStream*", scope) << ") const;"; H << nl << "virtual void _iceRead(" << getAbsolute("::Ice::InputStream*", scope) << ");"; + H << nl << "/// \\endcond"; } H.dec(); @@ -2753,8 +3346,11 @@ Slice::Gen::ObjectVisitor::visitClassDefEnd(const ClassDefPtr& p) inProtected = true; H.inc(); - H << sp << nl << "virtual void _iceWriteImpl(" << getAbsolute("::Ice::OutputStream*", scope) << ") const;"; + H << sp; + H << nl << "/// \\cond STREAM"; + H << nl << "virtual void _iceWriteImpl(" << getAbsolute("::Ice::OutputStream*", scope) << ") const;"; H << nl << "virtual void _iceReadImpl(" << getAbsolute("::Ice::InputStream*", scope) << ");"; + H << nl << "/// \\endcond"; if(preserved && !basePreserved) { @@ -2784,6 +3380,7 @@ Slice::Gen::ObjectVisitor::visitClassDefEnd(const ClassDefPtr& p) } C << sp; + C << nl << "/// \\cond STREAM"; C << nl << "void" << nl << scoped.substr(2) << "::_iceWriteImpl(" << getAbsolute("::Ice::OutputStream*", scope) << " ostr) const"; C << sb; @@ -2810,6 +3407,7 @@ Slice::Gen::ObjectVisitor::visitClassDefEnd(const ClassDefPtr& p) emitUpcall(base, "::_iceReadImpl(istr);", scope); } C << eb; + C << nl << "/// \\endcond"; if(!p->isAbstract() || p->compactId() >= 0) { @@ -2891,7 +3489,10 @@ Slice::Gen::ObjectVisitor::visitClassDefEnd(const ClassDefPtr& p) H.inc(); inProtected = true; } - H << sp << nl << "::Ice::SlicedDataPtr _iceSlicedData;"; + H << sp; + H << nl << "/// \\cond STREAM"; + H << nl << "::Ice::SlicedDataPtr _iceSlicedData;"; + H << nl << "/// \\endcond"; } if(generateFriend) @@ -2920,27 +3521,36 @@ Slice::Gen::ObjectVisitor::visitClassDefEnd(const ClassDefPtr& p) // But we do this only once per source file, because a single instance is sufficient to initialize // all of the globals in a compilation unit. // - H << nl << "static ::Ice::ValueFactoryPtr _iceS_" << p->name() << "_init = " << fixKwd(p->scoped()) << "::ice_factory();"; + H << nl << "/// \\cond INTERNAL"; + H << nl << "static ::Ice::ValueFactoryPtr _iceS_" << p->name() << "_init = " << fixKwd(p->scoped()) + << "::ice_factory();"; + H << nl << "/// \\endcond"; } if(p->isLocal()) { H << sp; - H << nl << "inline bool operator==(const " << fixKwd(p->name()) << "& lhs, const " << fixKwd(p->name()) << "& rhs)"; + H << nl << "/// \\cond INTERNAL"; + H << nl << "inline bool operator==(const " << fixKwd(p->name()) << "& lhs, const " << fixKwd(p->name()) + << "& rhs)"; H << sb; H << nl << "return static_cast<const " << getAbsolute("::Ice::LocalObject&", scope) << ">(lhs) == static_cast<const " << getAbsolute("::Ice::LocalObject&", scope) << ">(rhs);"; H << eb; H << sp; - H << nl << "inline bool operator<(const " << fixKwd(p->name()) << "& lhs, const " << fixKwd(p->name()) << "& rhs)"; + H << nl << "inline bool operator<(const " << fixKwd(p->name()) << "& lhs, const " << fixKwd(p->name()) + << "& rhs)"; H << sb; H << nl << "return static_cast<const " << getAbsolute("::Ice::LocalObject&", scope) << ">(lhs) < static_cast<const " << getAbsolute("::Ice::LocalObject&", scope) << ">(rhs);"; H << eb; + H << nl << "/// \\endcond"; } else { - C << sp << nl << "void"; + C << sp; + C << nl << "/// \\cond INTERNAL"; + C << nl << "void"; C << nl << scope.substr(2) << "_icePatchObjectPtr(" << p->name() << "Ptr& handle, const " << getAbsolute("::Ice::ObjectPtr&", scope) << " v)"; C << sb; @@ -2950,19 +3560,24 @@ Slice::Gen::ObjectVisitor::visitClassDefEnd(const ClassDefPtr& p) C << nl << "IceInternal::Ex::throwUOE(" << name << "::ice_staticId(), v);"; C << eb; C << eb; + C << nl << "/// \\endcond"; H << sp; - H << nl << "inline bool operator==(const " << fixKwd(p->name()) << "& lhs, const " << fixKwd(p->name()) << "& rhs)"; + H << nl << "/// \\cond INTERNAL"; + H << nl << "inline bool operator==(const " << fixKwd(p->name()) << "& lhs, const " << fixKwd(p->name()) + << "& rhs)"; H << sb; H << nl << "return static_cast<const " << getAbsolute("::Ice::Object&", scope) << ">(lhs) == static_cast<const " << getAbsolute("::Ice::Object&", scope) << ">(rhs);"; H << eb; H << sp; - H << nl << "inline bool operator<(const " << fixKwd(p->name()) << "& lhs, const " << fixKwd(p->name()) << "& rhs)"; + H << nl << "inline bool operator<(const " << fixKwd(p->name()) << "& lhs, const " << fixKwd(p->name()) + << "& rhs)"; H << sb; H << nl << "return static_cast<const " << getAbsolute("::Ice::Object&", scope) << ">(lhs) < static_cast<const " << getAbsolute("::Ice::Object&", scope) << ">(rhs);"; H << eb; + H << nl << "/// \\endcond"; } _useWstring = resetUseWstring(_useWstringHist); @@ -2996,32 +3611,37 @@ Slice::Gen::ObjectVisitor::visitOperation(const OperationPtr& p) TypePtr ret = p->returnType(); string retS = returnTypeToString(ret, p->returnIsOptional(), classScope, p->getMetaData(), _useWstring); + ParamDeclList inParams = p->inParameters(); + ParamDeclList outParams = p->outParameters(); + ParamDeclList paramList = p->parameters(); + + const string cbParam = escapeParam(paramList, "cb"); + const string cookieParam = escapeParam(paramList, "cookie"); + const string resultParam = escapeParam(outParams, "result"); + const string currentParam = escapeParam(paramList, "current"); + string params = "("; string paramsDecl = "("; string args = "("; - string paramsAMD = "(const " + classScopedAMD + '_' + name + "Ptr&, "; + string paramsAMD = "(const " + classScopedAMD + '_' + name + "Ptr& " + cbParam + ", "; string argsAMD = "(new IceAsync" + classScopedAMD + '_' + name + "(inS), "; - ParamDeclList inParams; - ParamDeclList outParams; - ParamDeclList paramList = p->parameters(); vector< string> outDecls; for(ParamDeclList::iterator q = paramList.begin(); q != paramList.end(); ++q) { - string paramName = fixKwd(string(paramPrefix) + (*q)->name()); + string paramName = fixKwd((*q)->name()); TypePtr type = (*q)->type(); bool isOutParam = (*q)->isOutParam(); string typeString; if(isOutParam) { - outParams.push_back(*q); typeString = outputTypeToString(type, (*q)->optional(), classScope, (*q)->getMetaData(), _useWstring); } else { - inParams.push_back(*q); - typeString = inputTypeToString((*q)->type(), (*q)->optional(), classScope, (*q)->getMetaData(), _useWstring); + typeString = + inputTypeToString((*q)->type(), (*q)->optional(), classScope, (*q)->getMetaData(), _useWstring); } if(q != paramList.begin()) @@ -3032,16 +3652,20 @@ Slice::Gen::ObjectVisitor::visitOperation(const OperationPtr& p) } params += typeString; + params += ' '; + params += paramName; paramsDecl += typeString; paramsDecl += ' '; paramsDecl += paramName; - args += paramName; + args += paramPrefix + (*q)->name(); if(!isOutParam) { paramsAMD += typeString; + paramsAMD += " "; + paramsAMD += paramName; paramsAMD += ", "; - argsAMD += paramName; + argsAMD += paramPrefix + (*q)->name(); argsAMD += ", "; } else @@ -3060,9 +3684,9 @@ Slice::Gen::ObjectVisitor::visitOperation(const OperationPtr& p) args += ", "; } - params += "const " + getAbsolute("::Ice::Current&", classScope) + " = " + + params += "const " + getAbsolute("::Ice::Current&", classScope) + " " + currentParam + " = " + getAbsolute("::Ice::emptyCurrent", classScope) + ")"; - paramsDecl += "const " + getAbsolute("::Ice::Current&", classScope) + " current)"; + paramsDecl += "const " + getAbsolute("::Ice::Current&", classScope) + " " + currentParam + ")"; args += "current)"; } else @@ -3072,7 +3696,7 @@ Slice::Gen::ObjectVisitor::visitOperation(const OperationPtr& p) args += ')'; } - paramsAMD += "const " + getAbsolute("::Ice::Current&", classScope) + " = " + + paramsAMD += "const " + getAbsolute("::Ice::Current&", classScope) + " " + currentParam + " = " + getAbsolute("::Ice::emptyCurrent", classScope) + ")"; argsAMD += "current)"; @@ -3082,27 +3706,55 @@ Slice::Gen::ObjectVisitor::visitOperation(const OperationPtr& p) string deprecateSymbol = getDeprecateSymbol(p, cl); + CommentPtr comment = p->parseComment(false); + const string cbDoc = "@param " + cbParam + " The AMD callback object for the invocation."; + const string currentDoc = "@param " + currentParam + " The Current object for the invocation."; + const string cookieDoc = "@param " + cookieParam + " Extra data to associate with the invocation."; + const string returnDoc = "The asynchronous result object for the invocation."; + H << sp; if(!amd) { + if(comment) + { + StringList postParams; + if(!cl->isLocal()) + { + postParams.push_back(currentDoc); + } + writeOpDocSummary(H, p, comment, OpDocAllParams, true, StringList(), postParams, comment->returns()); + } + H << nl << deprecateSymbol << "virtual " << retS << ' ' << fixKwd(name) << params << isConst << noExcept << " = 0;"; } else { + if(comment) + { + StringList preParams, postParams; + preParams.push_back(cbDoc); + postParams.push_back(currentDoc); + StringList noReturns; // Leave empty - the AMD method has a void return type. + writeOpDocSummary(H, p, comment, OpDocInParams, true, preParams, postParams, noReturns); + } + H << nl << deprecateSymbol << "virtual void " << name << "_async" << paramsAMD << isConst << noExcept << " = 0;"; } if(!cl->isLocal()) { + H << nl << "/// \\cond INTERNAL"; H << nl << "bool _iceD_" << name << "(::IceInternal::Incoming&, const " << getAbsolute("::Ice::Current&", scope) << ")" << isConst << ';'; + H << nl << "/// \\endcond"; C << sp; // // inS, ret, current etc. may shadow class-with-operations data members in C++98 // + C << nl << "/// \\cond INTERNAL"; C << nl << "bool" << nl << scope.substr(2) << "_iceD_" << name << "(::IceInternal::Incoming& inS" << ", const " << getAbsolute("::Ice::Current&", classScope) << " current)" << isConst; C << sb; @@ -3159,6 +3811,7 @@ Slice::Gen::ObjectVisitor::visitOperation(const OperationPtr& p) C << nl << "return false;"; } C << eb; + C << nl << "/// \\endcond"; } if(cl->isLocal() && (cl->hasMetaData("async-oneway") || p->hasMetaData("async-oneway"))) @@ -3193,24 +3846,58 @@ Slice::Gen::ObjectVisitor::visitOperation(const OperationPtr& p) } } - H << sp << nl << "virtual " << getAbsolute("::Ice::AsyncResultPtr", classScope) << " begin_" << name << spar + H << sp; + if(comment) + { + StringList returns; + returns.push_back(returnDoc); + writeOpDocSummary(H, p, comment, OpDocInParams, false, StringList(), StringList(), returns); + } + H << nl << "virtual " << getAbsolute("::Ice::AsyncResultPtr", classScope) << " begin_" << name << spar << paramsDeclAMI << epar << " = 0;"; - H << sp << nl << "virtual " << getAbsolute("::Ice::AsyncResultPtr", classScope) << " begin_" << name << spar + H << sp; + if(comment) + { + StringList postParams, returns; + postParams.push_back("@param " + cbParam + " Callback to be invoked when the invocation completes"); + postParams.push_back(cookieDoc); + returns.push_back(returnDoc); + writeOpDocSummary(H, p, comment, OpDocInParams, false, StringList(), postParams, returns); + } + H << nl << "virtual " << getAbsolute("::Ice::AsyncResultPtr", classScope) << " begin_" << name << spar << paramsDeclAMI - << ("const " + getAbsolute("::Ice::CallbackPtr&", classScope) + " del") - << ("const " + getAbsolute("::Ice::LocalObjectPtr&", classScope) + " cookie = 0") + << ("const " + getAbsolute("::Ice::CallbackPtr&", classScope) + " " + cbParam) + << ("const " + getAbsolute("::Ice::LocalObjectPtr&", classScope) + " " + cookieParam + " = 0") << epar << " = 0;"; string delName = "Callback_" + cl->name() + "_" + name; - H << sp << nl << "virtual " << getAbsolute("::Ice::AsyncResultPtr", classScope) << " begin_" << name << spar + H << sp; + if(comment) + { + StringList postParams, returns; + postParams.push_back("@param " + cbParam + " Callback to be invoked when the invocation completes"); + postParams.push_back(cookieDoc); + returns.push_back(returnDoc); + writeOpDocSummary(H, p, comment, OpDocInParams, false, StringList(), postParams, returns); + } + H << nl << "virtual " << getAbsolute("::Ice::AsyncResultPtr", classScope) << " begin_" << name << spar << paramsDeclAMI - << ("const " + delName + "Ptr& del") - << ("const " + getAbsolute("::Ice::LocalObjectPtr&", classScope) + " cookie = 0") << epar << " = 0;"; + << ("const " + delName + "Ptr& " + cbParam) + << ("const " + getAbsolute("::Ice::LocalObjectPtr&", classScope) + " " + cookieParam + " = 0") << epar + << " = 0;"; - H << sp << nl << "virtual " << retS << " end_" << name << spar << outParamsDeclAMI - << ("const " + getAbsolute("::Ice::AsyncResultPtr&", classScope)) << epar << " = 0;"; + H << sp; + if(comment) + { + StringList postParams, returns; + postParams.push_back("@param " + resultParam + + " The asynchronous result object returned by the begin_ method."); + writeOpDocSummary(H, p, comment, OpDocOutParams, true, StringList(), postParams, comment->returns()); + } + H << nl << "virtual " << retS << " end_" << name << spar << outParamsDeclAMI + << ("const " + getAbsolute("::Ice::AsyncResultPtr&", classScope) + " " + resultParam) << epar << " = 0;"; } } @@ -3221,6 +3908,7 @@ Slice::Gen::ObjectVisitor::emitDataMember(const DataMemberPtr& p) ContainerPtr container = p->container(); ClassDefPtr cl = ClassDefPtr::dynamicCast(container); int typeContext = cl->isLocal() ? TypeContextLocal | _useWstring : _useWstring; + writeDocSummary(H, p); H << nl << typeToString(p->type(), p->optional(), fixKwd(cl->scope()), p->getMetaData(), typeContext) << ' ' << name << ';'; } @@ -3255,7 +3943,9 @@ Slice::Gen::ObjectVisitor::emitGCFunctions(const ClassDefPtr& p) // if(canBeCyclic || (preserved && !basePreserved)) { + H << nl << "/// \\cond INTERNAL"; H << nl << "virtual void _iceGcVisitMembers(::IceInternal::GCVisitor&);"; + H << nl << "/// \\endcond"; C << sp << nl << "void" << nl << scoped.substr(2) << "::_iceGcVisitMembers(::IceInternal::GCVisitor& v_)"; C << sb; @@ -3397,7 +4087,7 @@ Slice::Gen::ObjectVisitor::emitVirtualBaseInitializers(const ClassDefPtr& p, boo { upcall += ", "; } - upcall += "iceP_" + (*q)->name(); + upcall += fixKwd((*q)->name()); } upcall += ")"; @@ -3415,29 +4105,48 @@ Slice::Gen::ObjectVisitor::emitOneShotConstructor(const ClassDefPtr& p) if(!allDataMembers.empty()) { vector<string> allParamDecls; + map<string, CommentPtr> allComments; bool virtualInheritance = p->hasMetaData("cpp:virtual"); - bool callBaseConstuctors = !(p->isAbstract() && virtualInheritance); + bool callBaseConstructors = !(p->isAbstract() && virtualInheritance); DataMemberList dataMembers = p->dataMembers(); int typeContext = p->isLocal() ? (_useWstring | TypeContextLocal) : _useWstring; for(DataMemberList::const_iterator q = allDataMembers.begin(); q != allDataMembers.end(); ++q) { - - string typeName = inputTypeToString((*q)->type(), (*q)->optional(), scope, (*q)->getMetaData(), typeContext); + string typeName = + inputTypeToString((*q)->type(), (*q)->optional(), scope, (*q)->getMetaData(), typeContext); bool dataMember = std::find(dataMembers.begin(), dataMembers.end(), (*q)) != dataMembers.end(); - allParamDecls.push_back(typeName + ((dataMember || callBaseConstuctors) ? - (" iceP_" + (*q)->name()) : (" /*iceP_" + (*q)->name() + "*/"))); + allParamDecls.push_back(typeName + ((dataMember || callBaseConstructors) ? + (" " + fixKwd((*q)->name())) : + (" /*" + fixKwd((*q)->name()) + "*/"))); + CommentPtr comment = (*q)->parseComment(false); + if(comment) + { + allComments[(*q)->name()] = comment; + } } - H << sp << nl; + H << sp; + H << nl << "/**"; + H << nl << " * One-shot constructor to initialize all data members."; + for(DataMemberList::const_iterator q = allDataMembers.begin(); q != allDataMembers.end(); ++q) + { + map<string, CommentPtr>::iterator r = allComments.find((*q)->name()); + if(r != allComments.end()) + { + H << nl << " * @param " << fixKwd(r->first) << " " << getDocSentence(r->second->overview()); + } + } + H << nl << " */"; + H << nl; if(allParamDecls.size() == 1) { H << "explicit "; } H << fixKwd(p->name()) << spar << allParamDecls << epar; - if(callBaseConstuctors || !dataMembers.empty()) + if(callBaseConstructors || !dataMembers.empty()) { H << " :"; } @@ -3446,7 +4155,7 @@ Slice::Gen::ObjectVisitor::emitOneShotConstructor(const ClassDefPtr& p) ClassList bases = p->bases(); ClassDefPtr base; - if(!bases.empty() && !bases.front()->isInterface() && callBaseConstuctors) + if(!bases.empty() && !bases.front()->isInterface() && callBaseConstructors) { if(emitVirtualBaseInitializers(bases.front(), virtualInheritance, true)) { @@ -3468,7 +4177,7 @@ Slice::Gen::ObjectVisitor::emitOneShotConstructor(const ClassDefPtr& p) H << ',' << nl; } string memberName = fixKwd((*q)->name()); - H << memberName << '(' << "iceP_" << (*q)->name() << ')'; + H << memberName << '(' << memberName << ')'; } H.dec(); @@ -3547,7 +4256,13 @@ Slice::Gen::AsyncCallbackVisitor::visitOperation(const OperationPtr& p) // Write the callback base class and callback smart pointer. // string delName = "Callback_" + cl->name() + "_" + p->name(); - H << sp << nl << "class " << delName << "_Base : public virtual ::IceInternal::CallbackBase { };"; + H << sp; + H << nl << "/**"; + H << nl << " * Base class for asynchronous callback wrapper classes used for calls to"; + H << nl << " * IceProxy" << fixKwd(cl->scoped()) << "::begin_" << p->name() << "."; + H << nl << " * Create a wrapper instance by calling " << fixKwd(cl->scope()) << "new" << delName << "."; + H << nl << " */"; + H << nl << "class " << delName << "_Base : public virtual ::IceInternal::CallbackBase { };"; H << nl << "typedef ::IceUtil::Handle< " << delName << "_Base> " << delName << "Ptr;"; } @@ -3640,22 +4355,34 @@ Slice::Gen::AsyncCallbackTemplateVisitor::generateOperation(const OperationPtr& outParams.push_back(*q); outArgs.push_back("iceP_" + (*q)->name()); outEndArgs.push_back(getEndArg((*q)->type(), (*q)->getMetaData(), outArgs.back())); - outDecls.push_back(inputTypeToString((*q)->type(), (*q)->optional(), clScope, (*q)->getMetaData(), _useWstring)); + outDecls.push_back( + inputTypeToString((*q)->type(), (*q)->optional(), clScope, (*q)->getMetaData(), _useWstring)); } } + H << sp; string baseD; string inheritD; if(withCookie) { baseD = "::IceInternal::Callback<T, CT>"; - H << sp << nl << "template<class T, typename CT>"; + H << nl << "/**"; + H << nl << " * Type-safe asynchronous callback wrapper class with cookie support used for calls to"; + H << nl << " * IceProxy" << fixKwd(cl->scoped()) << "::begin_" << p->name() << "."; + H << nl << " * Create a wrapper instance by calling " << fixKwd(cl->scope()) << "new" << delName << "."; + H << nl << " */"; + H << nl << "template<class T, typename CT>"; inheritD = p->returnsData() ? "::IceInternal::TwowayCallback<T, CT>" : "::IceInternal::OnewayCallback<T, CT>"; } else { baseD = "::IceInternal::CallbackNC<T>"; - H << sp << nl << "template<class T>"; + H << nl << "/**"; + H << nl << " * Type-safe asynchronous callback wrapper class used for calls to"; + H << nl << " * IceProxy" << fixKwd(cl->scoped()) << "::begin_" << p->name() << "."; + H << nl << " * Create a wrapper instance by calling " << fixKwd(cl->scope()) << "new" << delName << "."; + H << nl << " */"; + H << nl << "template<class T>"; inheritD = p->returnsData() ? "::IceInternal::TwowayCallbackNC<T>" : "::IceInternal::OnewayCallbackNC<T>"; } @@ -3725,11 +4452,14 @@ Slice::Gen::AsyncCallbackTemplateVisitor::generateOperation(const OperationPtr& // // completed. // - H << sp << nl << "virtual void completed(const " << getAbsolute("::Ice::AsyncResultPtr&", clScope) + H << sp; + H << nl << "/// \\cond INTERNAL"; + H << nl << "virtual void completed(const " << getAbsolute("::Ice::AsyncResultPtr&", clScope) << " result) const"; H << sb; H << nl << clName << "Prx proxy = " << clName << "Prx::uncheckedCast(result->getProxy());"; - writeAllocateCode(H, outParams, p, true, clScope, _useWstring | TypeContextInParam | TypeContextAMICallPrivateEnd); + writeAllocateCode(H, outParams, p, true, clScope, + _useWstring | TypeContextInParam | TypeContextAMICallPrivateEnd); H << nl << "try"; H << sb; H << nl; @@ -3773,6 +4503,7 @@ Slice::Gen::AsyncCallbackTemplateVisitor::generateOperation(const OperationPtr& H << epar << ';'; H << eb; H << eb; + H << nl << "/// \\endcond"; H.dec(); H << sp << nl << "private:"; H.inc(); @@ -3785,15 +4516,29 @@ Slice::Gen::AsyncCallbackTemplateVisitor::generateOperation(const OperationPtr& { string callbackT = i == 0 ? "const IceUtil::Handle<T>&" : "T*"; + H << sp; + H << nl << "/**"; + H << nl << " * Creates a callback wrapper instance that delegates to your object."; + if(withCookie) + { + H << nl << " * Use this overload when your callback methods receive a cookie value."; + } + H << nl << " * @param instance The callback object."; + H << nl << " * @param cb The success method of the callback object."; + H << nl << " * @param excb The exception method of the callback object."; + H << nl << " * @param sentcb The sent method of the callback object."; + H << nl << " * @return An object that can be passed to an asynchronous invocation of IceProxy" + << clScope << clName << "::begin_" << p->name() << "."; + H << nl << " */"; if(withCookie) { cookieT = "const CT&"; comCookieT = ", const CT&"; - H << sp << nl << "template<class T, typename CT> " << delName << "Ptr"; + H << nl << "template<class T, typename CT> " << delName << "Ptr"; } else { - H << sp << nl << "template<class T> " << delName << "Ptr"; + H << nl << "template<class T> " << delName << "Ptr"; } H << nl << "new" << delName << "(" << callbackT << " instance, "; @@ -3830,13 +4575,26 @@ Slice::Gen::AsyncCallbackTemplateVisitor::generateOperation(const OperationPtr& if(!ret && outParams.empty()) { + H << sp; + H << nl << "/**"; + H << nl << " * Creates a callback wrapper instance that delegates to your object."; if(withCookie) { - H << sp << nl << "template<class T, typename CT> " << delName << "Ptr"; + H << nl << " * Use this overload when your callback methods receive a cookie value."; + } + H << nl << " * @param instance The callback object."; + H << nl << " * @param excb The exception method of the callback object."; + H << nl << " * @param sentcb The sent method of the callback object."; + H << nl << " * @return An object that can be passed to an asynchronous invocation of IceProxy" + << clScope << clName << "::begin_" << p->name() << "."; + H << nl << " */"; + if(withCookie) + { + H << nl << "template<class T, typename CT> " << delName << "Ptr"; } else { - H << sp << nl << "template<class T> " << delName << "Ptr"; + H << nl << "template<class T> " << delName << "Ptr"; } H << nl << "new" << delName << "(" << callbackT << " instance, "; H << "void (T::*excb)(" << "const ::Ice::Exception&" << comCookieT << "), "; @@ -4201,79 +4959,81 @@ Slice::Gen::AsyncVisitor::visitOperation(const OperationPtr& p) string classNameAMD = "AMD_" + className; string classScope = fixKwd(cl->scope()); string classScopedAMD = classScope + classNameAMD; - string proxyName = classScope + className + "Prx"; - - vector<string> params; - vector<string> paramsAMD; - vector<string> paramsDecl; - vector<string> args; - - vector<string> paramsInvoke; - - paramsInvoke.push_back("const " + proxyName + "&"); TypePtr ret = p->returnType(); string retS = inputTypeToString(ret, p->returnIsOptional(), classScope, p->getMetaData(), _useWstring); + string resultParam = "result"; + ParamDeclList paramList = p->outParameters(); + for(ParamDeclList::const_iterator q = paramList.begin(); q != paramList.end(); ++q) + { + if((*q)->name() == "result") + { + resultParam = "result_"; + break; + } + } + + vector<string> paramsAMD; + if(ret) { - params.push_back(retS); - paramsAMD.push_back(inputTypeToString(ret, p->returnIsOptional(), classScope, p->getMetaData(), _useWstring)); - paramsDecl.push_back(retS + " ret"); - args.push_back("ret"); + paramsAMD.push_back(inputTypeToString(ret, p->returnIsOptional(), classScope, p->getMetaData(), _useWstring) + + " " + resultParam); } - ParamDeclList inParams; - ParamDeclList outParams; - ParamDeclList paramList = p->parameters(); for(ParamDeclList::const_iterator q = paramList.begin(); q != paramList.end(); ++q) { string paramName = fixKwd((*q)->name()); TypePtr type = (*q)->type(); string typeString = inputTypeToString(type, (*q)->optional(), classScope, (*q)->getMetaData(), _useWstring); - - if((*q)->isOutParam()) - { - params.push_back(typeString); - paramsAMD.push_back(inputTypeToString(type, (*q)->optional(), classScope, (*q)->getMetaData(), _useWstring)); - paramsDecl.push_back(typeString + ' ' + paramName); - args.push_back(paramName); - - outParams.push_back(*q); - } - else - { - paramsInvoke.push_back(typeString); - inParams.push_back(*q); - } + paramsAMD.push_back(typeString + " " + paramName); } - paramsInvoke.push_back(getAbsolute("const ::Ice::Context&", classScope)); + string cbName = classNameAMD + '_' + name; - if(cl->hasMetaData("amd") || p->hasMetaData("amd")) - { - string cbName = classNameAMD + '_' + name; + CommentPtr comment = p->parseComment(false); - H << sp << nl << "class " << _dllExport << cbName << " : public virtual " - << getAbsolute("::Ice::AMDCallback", classScope); - H << sb; - H.dec(); - H << nl << "public:"; - H.inc(); + H << sp; + H << nl << "/**"; + H << nl << " * AMD callback class for " << fixKwd(p->scoped()).substr(2) << "_async."; + H << nl << " * Call the ice_response method for a successful completion, or the ice_exception"; + H << nl << " * method in the case of an error."; + H << nl << " */"; + H << nl << "class " << _dllExport << cbName << " : public virtual " + << getAbsolute("::Ice::AMDCallback", classScope); + H << sb; + H.dec(); + H << nl << "public:"; + H.inc(); - // Out of line dtor to avoid weak vtable - H << sp << nl << "virtual ~" << cbName << "();"; - C << sp; - C << nl << classScope.substr(2) << cbName << "::~" << cbName << "()"; - C << sb; - C << eb; + // Out of line dtor to avoid weak vtable + H << sp << nl << "virtual ~" << cbName << "();"; + C << sp; + C << nl << classScope.substr(2) << cbName << "::~" << cbName << "()"; + C << sb; + C << eb; - H << sp; - H << nl << "virtual void ice_response" << spar << paramsAMD << epar << " = 0;"; - H << eb << ';'; - H << sp << nl << "typedef ::IceUtil::Handle< " << classScopedAMD << '_' << name << "> " - << classNameAMD << '_' << name << "Ptr;"; + H << sp; + H << nl << "/**"; + H << nl << " * Call ice_response for a successful completion."; + if(comment) + { + StringList preParams; + StringList returns = comment->returns(); + if(ret && !returns.empty()) + { + preParams = returns; + preParams.pop_front(); + preParams.push_front("@param " + resultParam + " " + returns.front()); + } + writeOpDocParams(H, p, comment, OpDocOutParams, preParams); } + H << nl << " */"; + H << nl << "virtual void ice_response" << spar << paramsAMD << epar << " = 0;"; + H << eb << ';'; + H << sp << nl << "typedef ::IceUtil::Handle< " << classScopedAMD << '_' << name << "> " + << classNameAMD << '_' << name << "Ptr;"; } Slice::Gen::AsyncImplVisitor::AsyncImplVisitor(Output& h, Output& c, const string& dllExport) : @@ -4289,7 +5049,9 @@ Slice::Gen::AsyncImplVisitor::visitUnitStart(const UnitPtr& p) return false; } - H << sp << nl << "namespace IceAsync" << nl << '{'; + H << sp; + H << nl << "/// \\cond INTERNAL"; + H << nl << "namespace IceAsync" << nl << '{'; return true; } @@ -4298,6 +5060,7 @@ void Slice::Gen::AsyncImplVisitor::visitUnitEnd(const UnitPtr&) { H << sp << nl << '}'; + H << nl << "/// \\endcond"; } bool @@ -4412,7 +5175,9 @@ Slice::Gen::AsyncImplVisitor::visitOperation(const OperationPtr& p) H << nl << "virtual void ice_response(" << params << ");"; H << eb << ';'; - C << sp << nl << "IceAsync" << classScopedAMD << '_' << name << "::" << classNameAMD << '_' << name + C << sp; + C << nl << "/// \\cond INTERNAL"; + C << nl << "IceAsync" << classScopedAMD << '_' << name << "::" << classNameAMD << '_' << name << "(::IceInternal::Incoming& in) :"; C.inc(); C << nl << "::IceInternal::IncomingAsync(in)"; @@ -4439,6 +5204,7 @@ Slice::Gen::AsyncImplVisitor::visitOperation(const OperationPtr& p) } C << nl << "completed();"; C << eb; + C << nl << "/// \\endcond"; } Slice::Gen::StreamVisitor::StreamVisitor(Output& h, Output& c, const string& dllExport) : @@ -4465,6 +5231,7 @@ Slice::Gen::StreamVisitor::visitModuleStart(const ModulePtr& m) // Only emit this for the top-level module. // H << sp; + H << nl << "/// \\cond STREAM"; H << nl << "namespace Ice" << nl << '{' << sp; C << sp; @@ -4483,6 +5250,7 @@ Slice::Gen::StreamVisitor::visitModuleEnd(const ModulePtr& m) // Only emit this for the top-level module. // H << nl << '}'; + H << nl << "/// \\endcond"; C << nl << '}'; } } @@ -4607,6 +5375,7 @@ Slice::Gen::MetaDataVisitor::visitUnitStart(const UnitPtr& p) static const string cppHeaderExtPrefix = "cpp:header-ext:"; static const string cppSourceExtPrefix = "cpp:source-ext:"; static const string cppDllExportPrefix = "cpp:dll-export:"; + static const string cppDoxygenIncludePrefix = "cpp:doxygen:include:"; if(s.find(cppIncludePrefix) == 0 && s.size() > cppIncludePrefix.size()) { @@ -4652,6 +5421,10 @@ Slice::Gen::MetaDataVisitor::visitUnitStart(const UnitPtr& p) } continue; } + else if(s.find(cppDoxygenIncludePrefix) == 0 && s.size() > cppDoxygenIncludePrefix.size()) + { + continue; + } ostringstream ostr; ostr << "ignoring invalid global metadata `" << s << "'"; @@ -5308,7 +6081,8 @@ Slice::Gen::Cpp11DeclVisitor::visitClassDefStart(const ClassDefPtr& p) if(p->compactId() >= 0) { string n = "iceC" + p->flattenedScope() + p->name() + "_compactIdInit "; - C << "const ::IceInternal::CompactIdInit " << n << "(\"" << p->scoped() << "\", " << p->compactId() << ");"; + C << "const ::IceInternal::CompactIdInit " << n << "(\"" << p->scoped() << "\", " << p->compactId() + << ");"; } } @@ -5444,9 +6218,12 @@ Slice::Gen::Cpp11TypesVisitor::visitExceptionStart(const ExceptionPtr& p) DataMemberList baseDataMembers; vector<string> params; - vector<string> allTypes; vector<string> allParamDecls; vector<string> baseParams; + map<string, CommentPtr> allComments; + + string fileParam = "file"; + string lineParam = "line"; for(DataMemberList::const_iterator q = dataMembers.begin(); q != dataMembers.end(); ++q) { @@ -5457,8 +6234,22 @@ Slice::Gen::Cpp11TypesVisitor::visitExceptionStart(const ExceptionPtr& p) { string typeName = inputTypeToString((*q)->type(), (*q)->optional(), scope, (*q)->getMetaData(), _useWstring | TypeContextCpp11); - allTypes.push_back(typeName); - allParamDecls.push_back(typeName + " iceP_" + (*q)->name()); + allParamDecls.push_back(typeName + " " + fixKwd((*q)->name())); + + CommentPtr comment = (*q)->parseComment(false); + if(comment) + { + allComments[(*q)->name()] = comment; + } + + if((*q)->name() == "file") + { + fileParam = "file_"; + } + else if((*q)->name() == "line") + { + fileParam = "line_"; + } } if(base) @@ -5466,18 +6257,20 @@ Slice::Gen::Cpp11TypesVisitor::visitExceptionStart(const ExceptionPtr& p) baseDataMembers = base->allDataMembers(); for(DataMemberList::const_iterator q = baseDataMembers.begin(); q != baseDataMembers.end(); ++q) { - baseParams.push_back("iceP_" + (*q)->name()); + baseParams.push_back(fixKwd((*q)->name())); } } - string helperClass = getAbsolute(p->isLocal() ? "::Ice::LocalExceptionHelper" : "::Ice::UserExceptionHelper", scope); + string helperClass = + getAbsolute(p->isLocal() ? "::Ice::LocalExceptionHelper" : "::Ice::UserExceptionHelper", scope); string baseClass = base ? getAbsolute(fixKwd(base->scoped()), scope) : getAbsolute(p->isLocal() ? "::Ice::LocalException" : "::Ice::UserException", scope); string templateParameters = name + ", " + baseClass; - H << sp << nl; - H << "class " << _dllClassExport << name << " : public " << helperClass << "<" << templateParameters << ">"; + H << sp; + writeDocSummary(H, p); + H << nl << "class " << _dllClassExport << name << " : public " << helperClass << "<" << templateParameters << ">"; H << sb; H.dec(); @@ -5497,9 +6290,17 @@ Slice::Gen::Cpp11TypesVisitor::visitExceptionStart(const ExceptionPtr& p) if(p->isLocal()) { - H << sp << nl << name << "(const char* file_, int line_) : "; + H << sp; + H << nl << "/**"; + H << nl << " * The file and line number are required for all local exceptions."; + H << nl << " * @param " << fileParam + << " The file name in which the exception was raised, typically __FILE__."; + H << nl << " * @param " << lineParam + << " The line number at which the exception was raised, typically __LINE__."; + H << nl << " */"; + H << nl << name << "(const char* " << fileParam << ", int " << lineParam << ") : "; H << getAbsolute("::Ice::LocalExceptionHelper", scope) << "<" << templateParameters << ">"; - H << "(file_, line_)"; + H << "(" << fileParam << ", " << lineParam << ")"; H << sb; H << eb; } @@ -5510,10 +6311,30 @@ Slice::Gen::Cpp11TypesVisitor::visitExceptionStart(const ExceptionPtr& p) if(!allDataMembers.empty()) { - H << sp << nl << name << "("; + H << sp; + H << nl << "/**"; + H << nl << " * One-shot constructor to initialize all data members."; + if(p->isLocal()) + { + H << nl << " * The file and line number are required for all local exceptions."; + H << nl << " * @param " << fileParam + << " The file name in which the exception was raised, typically __FILE__."; + H << nl << " * @param " << lineParam + << " The line number at which the exception was raised, typically __LINE__."; + } + for(DataMemberList::const_iterator q = allDataMembers.begin(); q != allDataMembers.end(); ++q) + { + map<string, CommentPtr>::iterator r = allComments.find((*q)->name()); + if(r != allComments.end()) + { + H << nl << " * @param " << fixKwd(r->first) << " " << getDocSentence(r->second->overview()); + } + } + H << nl << " */"; + H << nl << name << "("; if(p->isLocal()) { - H << "const char* file_, int line_"; + H << "const char* " << fileParam << ", int " << lineParam; if(!allParamDecls.empty()) { H << ", "; @@ -5535,7 +6356,7 @@ Slice::Gen::Cpp11TypesVisitor::visitExceptionStart(const ExceptionPtr& p) H << nl << helperClass << "<" << templateParameters << ">" << "("; if(p->isLocal()) { - H << "file_, line_"; + H << fileParam << ", " << lineParam; if(!baseDataMembers.empty()) { H << ", "; @@ -5550,11 +6371,11 @@ Slice::Gen::Cpp11TypesVisitor::visitExceptionStart(const ExceptionPtr& p) } if(isMovable((*q)->type())) { - H << "::std::move(iceP_" << (*q)->name() << ")"; + H << "::std::move(" << fixKwd((*q)->name()) << ")"; } else { - H << "iceP_" << (*q)->name(); + H << fixKwd((*q)->name()); } } @@ -5567,7 +6388,7 @@ Slice::Gen::Cpp11TypesVisitor::visitExceptionStart(const ExceptionPtr& p) else if(p->isLocal()) { H << " " << getAbsolute("::Ice::LocalExceptionHelper", scope) << "<" << templateParameters << ">"; - H << "(file_, line_)"; + H << "(" << fileParam << ", " << lineParam << ")"; if(!dataMembers.empty()) { H << ","; @@ -5576,17 +6397,18 @@ Slice::Gen::Cpp11TypesVisitor::visitExceptionStart(const ExceptionPtr& p) for(DataMemberList::const_iterator q = dataMembers.begin(); q != dataMembers.end(); ++q) { + string memberName = fixKwd((*q)->name()); if(q != dataMembers.begin()) { H << ","; } if(isMovable((*q)->type())) { - H << nl << fixKwd((*q)->name()) << "(::std::move(iceP_" << (*q)->name() << "))"; + H << nl << memberName << "(::std::move(" << memberName << "))"; } else { - H << nl << fixKwd((*q)->name()) << "(iceP_" << (*q)->name() << ")"; + H << nl << memberName << "(" << memberName << ")"; } } @@ -5595,9 +6417,18 @@ Slice::Gen::Cpp11TypesVisitor::visitExceptionStart(const ExceptionPtr& p) H << eb; } + H << sp; + H << nl << "/**"; + H << nl << " * Obtains a tuple containing all of the exception's data members."; + H << nl << " * @return The data members in a tuple."; + H << nl << " */"; writeIceTuple(H, scope, p->allDataMembers(), _useWstring); H << sp; + H << nl << "/**"; + H << nl << " * Obtains the Slice type ID of this exception."; + H << nl << " * @return The fully-scoped type ID."; + H << nl << " */"; H << nl << _dllMemberExport << "static const ::std::string& ice_staticId();"; C << sp << nl << "const ::std::string&" << nl << scoped.substr(2) << "::ice_staticId()"; @@ -5612,20 +6443,30 @@ Slice::Gen::Cpp11TypesVisitor::visitExceptionStart(const ExceptionPtr& p) StringList metaData = p->getMetaData(); if(find(metaData.begin(), metaData.end(), "cpp:ice_print") != metaData.end()) { - H << nl << _dllMemberExport << "virtual void ice_print(::std::ostream&) const override;"; + H << nl << "/**"; + H << nl << " * Prints this exception to the given stream."; + H << nl << " * @param stream The target stream."; + H << nl << " */"; + H << nl << _dllMemberExport << "virtual void ice_print(::std::ostream& stream) const override;"; } if(!p->isLocal() && p->usesClasses(false)) { if(!base || (base && !base->usesClasses(false))) { - H << sp << nl << _dllMemberExport << "virtual bool _usesClasses() const override;"; + H << sp; + H << nl << "/// \\cond STREAM"; + H << nl << _dllMemberExport << "virtual bool _usesClasses() const override;"; + H << nl << "/// \\endcond"; - C << sp << nl << "bool"; + C << sp; + C << nl << "/// \\cond STREAM"; + C << nl << "bool"; C << nl << scoped.substr(2) << "::_usesClasses() const"; C << sb; C << nl << "return true;"; C << eb; + C << nl << "/// \\endcond"; } } @@ -5653,23 +6494,34 @@ Slice::Gen::Cpp11TypesVisitor::visitExceptionEnd(const ExceptionPtr& p) if(preserved && !basePreserved) { H << sp; + H << nl << "/**"; + H << nl << " * Obtains the SlicedData object created when an unknown exception type was marshaled"; + H << nl << " * in the sliced format and the Ice run time sliced it to a known type."; + H << nl << " * @return The SlicedData object, or nil if the exception was not sliced or was not"; + H << nl << " * marshaled in the sliced format."; + H << nl << " */"; H << nl << _dllMemberExport << "virtual ::std::shared_ptr<" << getAbsolute("::Ice::SlicedData", scope) << "> ice_getSlicedData() const override;"; H << sp; + H << nl << "/// \\cond STREAM"; H << nl << _dllMemberExport << "virtual void _write(" << getAbsolute("::Ice::OutputStream*", scope) << ") const override;"; H << nl << _dllMemberExport << "virtual void _read(" << getAbsolute("::Ice::InputStream*", scope) << ") override;"; H << sp << nl << "::std::shared_ptr<" << getAbsolute("::Ice::SlicedData", scope) << "> _slicedData;"; + H << nl << "/// \\endcond"; C << sp; - C << nl << "::std::shared_ptr<::Ice::SlicedData>" << nl << scoped.substr(2) << "::ice_getSlicedData() const"; + C << nl << "::std::shared_ptr<::Ice::SlicedData>" << nl << scoped.substr(2) + << "::ice_getSlicedData() const"; C << sb; C << nl << "return _slicedData;"; C << eb; - C << sp << nl << "void" << nl << scoped.substr(2) << "::_write(" + C << sp; + C << nl << "/// \\cond STREAM"; + C << nl << "void" << nl << scoped.substr(2) << "::_write(" << getAbsolute("::Ice::OutputStream*", scope) << " ostr) const"; C << sb; C << nl << "ostr->startException(_slicedData);"; @@ -5677,13 +6529,14 @@ Slice::Gen::Cpp11TypesVisitor::visitExceptionEnd(const ExceptionPtr& p) C << nl << "ostr->endException();"; C << eb; - C << sp << nl << "void" << nl << scoped.substr(2) << "::_read(" << getAbsolute("::Ice::InputStream*", scope) - << " istr)"; + C << sp << nl << "void" << nl << scoped.substr(2) << "::_read(" + << getAbsolute("::Ice::InputStream*", scope) << " istr)"; C << sb; C << nl << "istr->startException();"; C << nl << "_readImpl(istr);"; C << nl << "_slicedData = istr->endException(true);"; C << eb; + C << nl << "/// \\endcond"; } } H << eb << ';'; @@ -5698,7 +6551,10 @@ Slice::Gen::Cpp11TypesVisitor::visitExceptionEnd(const ExceptionPtr& p) if(!_doneStaticSymbol) { _doneStaticSymbol = true; - H << sp << nl << "static " << name << " _iceS_" << p->name() << "_init;"; + H << sp; + H << nl << "/// \\cond INTERNAL"; + H << nl << "static " << name << " _iceS_" << p->name() << "_init;"; + H << nl << "/// \\endcond"; } } @@ -5710,7 +6566,9 @@ Slice::Gen::Cpp11TypesVisitor::visitStructStart(const StructPtr& p) { _useWstring = setUseWstring(p, _useWstringHist, _useWstring); - H << sp << nl << "struct " << fixKwd(p->name()); + H << sp; + writeDocSummary(H, p); + H << nl << "struct " << fixKwd(p->name()); H << sb; return true; @@ -5719,6 +6577,11 @@ Slice::Gen::Cpp11TypesVisitor::visitStructStart(const StructPtr& p) void Slice::Gen::Cpp11TypesVisitor::visitStructEnd(const StructPtr& p) { + H << sp; + H << nl << "/**"; + H << nl << " * Obtains a tuple containing all of the exception's data members."; + H << nl << " * @return The data members in a tuple."; + H << nl << " */"; writeIceTuple(H, fixKwd(p->scope()), p->dataMembers(), _useWstring); H << eb << ';'; _useWstring = resetUseWstring(_useWstringHist); @@ -5729,6 +6592,7 @@ Slice::Gen::Cpp11TypesVisitor::visitDataMember(const DataMemberPtr& p) { string scope = fixKwd(ContainedPtr::dynamicCast(p->container())->scope()); string name = fixKwd(p->name()); + writeDocSummary(H, p); H << nl << typeToString(p->type(), p->optional(), scope, p->getMetaData(), _useWstring | TypeContextCpp11) << ' ' << name; @@ -5769,6 +6633,7 @@ Slice::Gen::Cpp11TypesVisitor::visitSequence(const SequencePtr& p) string seqType = findMetaData(metaData, _useWstring); H << sp; + writeDocSummary(H, p); if(!seqType.empty()) { @@ -5787,6 +6652,10 @@ Slice::Gen::Cpp11TypesVisitor::visitDictionary(const DictionaryPtr& p) string scope = fixKwd(p->scope()); string dictType = findMetaData(p->getMetaData()); int typeCtx = p->isLocal() ? (_useWstring | TypeContextLocal) : _useWstring; + + H << sp; + writeDocSummary(H, p); + if(dictType.empty()) { // @@ -5797,14 +6666,14 @@ Slice::Gen::Cpp11TypesVisitor::visitDictionary(const DictionaryPtr& p) string ks = typeToString(keyType, scope, p->keyMetaData(), typeCtx | TypeContextCpp11); string vs = typeToString(valueType, scope, p->valueMetaData(), typeCtx | TypeContextCpp11); - H << sp << nl << "using " << name << " = ::std::map<" << ks << ", " << vs << ">;"; + H << nl << "using " << name << " = ::std::map<" << ks << ", " << vs << ">;"; } else { // // A custom dictionary // - H << sp << nl << "using " << name << " = " << dictType << ';'; + H << nl << "using " << name << " = " << dictType << ';'; } } @@ -5869,7 +6738,9 @@ Slice::Gen::Cpp11ProxyVisitor::visitClassDefStart(const ClassDefPtr& p) base = bases.front(); } - H << sp << nl << "class " << _dllClassExport << p->name() << "Prx : public virtual " + H << sp; + writeDocSummary(H, p); + H << nl << "class " << _dllClassExport << p->name() << "Prx : public virtual " << getAbsolute("::Ice::Proxy", scope) << "<" << fixKwd(p->name() + "Prx") << ", "; if(bases.empty() || (base && base->allOperations().empty())) { @@ -5904,25 +6775,35 @@ Slice::Gen::Cpp11ProxyVisitor::visitClassDefEnd(const ClassDefPtr& p) const string scoped = fixKwd(p->scoped() + "Prx"); const string scope = fixKwd(p->scope()); - H << sp << nl << _dllMemberExport << "static const ::std::string& ice_staticId();"; + H << sp; + H << nl << "/**"; + H << nl << " * Obtains the Slice type ID of this " << (p->isInterface() ? "interface" : "class") << "."; + H << nl << " * @return The fully-scoped type ID."; + H << nl << " */"; + H << nl << _dllMemberExport << "static const ::std::string& ice_staticId();"; H.dec(); H << sp << nl << "protected:"; H.inc(); - H << sp << nl << getAbsolute(prx, scope) << "() = default;"; + H << sp; + H << nl << "/// \\cond INTERNAL"; + H << nl << getAbsolute(prx, scope) << "() = default;"; H << nl << "friend ::std::shared_ptr<" << getAbsolute(prx, scope) << "> IceInternal::createProxy<" << getAbsolute(prx, scope) << ">();"; H << sp; H << nl << _dllMemberExport << "virtual ::std::shared_ptr<" << getAbsolute("::Ice::ObjectPrx", scope) << "> _newInstance() const override;"; + H << nl << "/// \\endcond"; H << eb << ';'; C << sp; + C << nl << "/// \\cond INTERNAL"; C << nl << "::std::shared_ptr<::Ice::ObjectPrx>"; C << nl << scoped.substr(2) << "::_newInstance() const"; C << sb; C << nl << "return ::IceInternal::createProxy<" << getAbsolute(prx, scope) << ">();"; C << eb; + C << nl << "/// \\endcond"; C << sp; C << nl << "const ::std::string&" << nl << scoped.substr(2) << "::ice_staticId()"; C << sb; @@ -5952,20 +6833,22 @@ Slice::Gen::Cpp11ProxyVisitor::visitOperation(const OperationPtr& p) vector<string> inParamsS; vector<string> inParamsDecl; + vector<string> inParamsImplDecl; vector<string> futureOutParams; vector<string> lambdaOutParams; ParamDeclList paramList = p->parameters(); - ParamDeclList inParams; - ParamDeclList outParams; + ParamDeclList inParams = p->inParameters(); + ParamDeclList outParams = p->outParameters(); string returnValueS = "returnValue"; bool outParamsHasOpt = false; if(ret) { - futureOutParams.push_back(typeToString(ret, retIsOpt, clScope, p->getMetaData(), _useWstring | TypeContextCpp11)); + futureOutParams.push_back(typeToString(ret, retIsOpt, clScope, p->getMetaData(), _useWstring | + TypeContextCpp11)); lambdaOutParams.push_back(typeToString(ret, retIsOpt, clScope, p->getMetaData(), _useWstring | TypeContextInParam | TypeContextCpp11)); @@ -5975,7 +6858,7 @@ Slice::Gen::Cpp11ProxyVisitor::visitOperation(const OperationPtr& p) for(ParamDeclList::const_iterator q = paramList.begin(); q != paramList.end(); ++q) { - string paramName = fixKwd(paramPrefix + (*q)->name()); + string paramName = fixKwd((*q)->name()); StringList metaData = (*q)->getMetaData(); if((*q)->isOutParam()) @@ -5992,7 +6875,6 @@ Slice::Gen::Cpp11ProxyVisitor::visitOperation(const OperationPtr& p) paramsDecl.push_back(outputTypeString + ' ' + paramName); outParamsHasOpt |= (*q)->optional(); - outParams.push_back(*q); if((*q)->name() == "returnValue") { @@ -6009,12 +6891,16 @@ Slice::Gen::Cpp11ProxyVisitor::visitOperation(const OperationPtr& p) inParamsS.push_back(typeString); inParamsDecl.push_back(typeString + ' ' + paramName); - inParams.push_back(*q); + inParamsImplDecl.push_back(typeString + ' ' + paramPrefix + (*q)->name()); } } string scoped = fixKwd(cl->scope() + cl->name() + "Prx" + "::").substr(2); + const string contextParam = escapeParam(paramList, "context"); + const string contextDecl = "const " + getAbsolute("::Ice::Context&", clScope) + " " + contextParam + " = " + + getAbsolute("::Ice::noExplicitContext", clScope); + string futureT; if(futureOutParams.empty()) { @@ -6029,14 +6915,23 @@ Slice::Gen::Cpp11ProxyVisitor::visitOperation(const OperationPtr& p) futureT = resultStructName(name, fixKwd(cl->name())); } - string deprecateSymbol = getDeprecateSymbol(p, cl); + const string deprecateSymbol = getDeprecateSymbol(p, cl); + + CommentPtr comment = p->parseComment(false); + const string contextDoc = "@param " + contextParam + " The Context map to send with the invocation."; + const string futureDoc = "The future object for the invocation."; // // Synchronous operation // - H << sp << nl << deprecateSymbol << retS << ' ' << fixKwd(name) << spar << paramsDecl; - H << ("const " + getAbsolute("::Ice::Context&", clScope) + " context = " - + getAbsolute("Ice::noExplicitContext", clScope.substr(2))) << epar; + H << sp; + if(comment) + { + StringList postParams; + postParams.push_back(contextDoc); + writeOpDocSummary(H, p, comment, OpDocAllParams, true, StringList(), postParams, comment->returns()); + } + H << nl << deprecateSymbol << retS << ' ' << fixKwd(name) << spar << paramsDecl << contextDecl << epar; H << sb; H << nl; if(futureOutParams.size() == 1) @@ -6047,12 +6942,12 @@ Slice::Gen::Cpp11ProxyVisitor::visitOperation(const OperationPtr& p) } else { - H << paramPrefix << (*outParams.begin())->name() << " = "; + H << fixKwd((*outParams.begin())->name()) << " = "; } } else if(futureOutParams.size() > 1) { - H << "auto result = "; + H << "auto _result = "; } H << "_makePromiseOutgoing<" << getAbsolute(futureT, cl->scoped()) << ">"; @@ -6060,19 +6955,19 @@ Slice::Gen::Cpp11ProxyVisitor::visitOperation(const OperationPtr& p) H << spar << "true, this" << "&" + cl->name() + "Prx::_iceI_" + name; for(ParamDeclList::const_iterator q = inParams.begin(); q != inParams.end(); ++q) { - H << fixKwd(paramPrefix + (*q)->name()); + H << fixKwd((*q)->name()); } - H << "context" << epar << ".get();"; + H << contextParam << epar << ".get();"; if(futureOutParams.size() > 1) { for(ParamDeclList::const_iterator q = outParams.begin(); q != outParams.end(); ++q) { - H << nl << paramPrefix << (*q)->name() << " = "; - H << condMove(isMovable((*q)->type()), "result." + fixKwd((*q)->name())) + ";"; + H << nl << fixKwd((*q)->name()) << " = "; + H << condMove(isMovable((*q)->type()), "_result." + fixKwd((*q)->name())) + ";"; } if(ret) { - H << nl << "return " + condMove(isMovable(ret), "result." + returnValueS) + ";"; + H << nl << "return " + condMove(isMovable(ret), "_result." + returnValueS) + ";"; } } H << eb; @@ -6081,10 +6976,15 @@ Slice::Gen::Cpp11ProxyVisitor::visitOperation(const OperationPtr& p) // Promise based asynchronous operation // H << sp; + if(comment) + { + StringList postParams, returns; + postParams.push_back(contextDoc); + returns.push_back(futureDoc); + writeOpDocSummary(H, p, comment, OpDocInParams, false, StringList(), postParams, returns); + } H << nl << "template<template<typename> class P = ::std::promise>"; - H << nl << deprecateSymbol << "auto " << name << "Async" << spar << inParamsDecl; - H << ("const " + getAbsolute("::Ice::Context&", clScope) + " context = " - + getAbsolute("::Ice::noExplicitContext", clScope)) << epar; + H << nl << deprecateSymbol << "auto " << name << "Async" << spar << inParamsDecl << contextDecl << epar; H.inc(); H << nl << "-> decltype(::std::declval<P<" << futureT << ">>().get_future())"; H.dec(); @@ -6095,9 +6995,9 @@ Slice::Gen::Cpp11ProxyVisitor::visitOperation(const OperationPtr& p) H << "false, this" << string("&" + cl->name() + "Prx::_iceI_" + name); for(ParamDeclList::const_iterator q = inParams.begin(); q != inParams.end(); ++q) { - H << fixKwd(paramPrefix + (*q)->name()); + H << fixKwd((*q)->name()); } - H << "context" << epar << ";"; + H << contextParam << epar << ";"; H << eb; // @@ -6105,7 +7005,21 @@ Slice::Gen::Cpp11ProxyVisitor::visitOperation(const OperationPtr& p) // bool lambdaCustomOut = (lambdaOutParams != futureOutParams); + const string responseParam = escapeParam(inParams, "response"); + const string exParam = escapeParam(inParams, "ex"); + const string sentParam = escapeParam(inParams, "sent"); + H << sp; + if(comment) + { + StringList postParams, returns; + postParams.push_back("@param " + responseParam + " The response callback."); + postParams.push_back("@param " + exParam + " The exception callback."); + postParams.push_back("@param " + sentParam + " The sent callback."); + postParams.push_back(contextDoc); + returns.push_back("A function that can be called to cancel the invocation locally."); + writeOpDocSummary(H, p, comment, OpDocInParams, false, StringList(), postParams, returns); + } H << nl; if(lambdaCustomOut) { @@ -6143,15 +7057,10 @@ Slice::Gen::Cpp11ProxyVisitor::visitOperation(const OperationPtr& p) H << nl; } - H << "::std::function<void" << spar << lambdaOutParams << epar << ">" - + string(!lambdaCustomOut ? " response": "") + ","; - H << nl << "::std::function<void(::std::exception_ptr)>" - + string(!lambdaCustomOut ? " ex" : "") + " = nullptr,"; - H << nl << "::std::function<void(bool)>" - + string(!lambdaCustomOut ? " sent" : "") + " = nullptr,"; - H << nl << "const " << getAbsolute("::Ice::Context&", clScope) - + string(!lambdaCustomOut ? " context" : "") + " = " - + getAbsolute("Ice::noExplicitContext", clScope.substr(2)) + ")" + string(lambdaCustomOut ? ";" : ""); + H << "::std::function<void" << spar << lambdaOutParams << epar << "> " << responseParam << ","; + H << nl << "::std::function<void(::std::exception_ptr)> " << exParam << " = nullptr,"; + H << nl << "::std::function<void(bool)> " << sentParam << " = nullptr,"; + H << nl << contextDecl << ")" << string(lambdaCustomOut ? ";" : ""); H.restoreIndent(); if(lambdaCustomOut) @@ -6164,11 +7073,11 @@ Slice::Gen::Cpp11ProxyVisitor::visitOperation(const OperationPtr& p) C << nl << "::std::function<void()>"; C << nl << scoped << name << "Async("; C.useCurrentPosAsIndent(); - if(!inParamsDecl.empty()) + if(!inParamsImplDecl.empty()) { - for(vector<string>::const_iterator q = inParamsDecl.begin(); q != inParamsDecl.end(); ++q) + for(vector<string>::const_iterator q = inParamsImplDecl.begin(); q != inParamsImplDecl.end(); ++q) { - if(q != inParamsDecl.begin()) + if(q != inParamsImplDecl.begin()) { C << " "; } @@ -6246,30 +7155,30 @@ Slice::Gen::Cpp11ProxyVisitor::visitOperation(const OperationPtr& p) H << sb; if(futureOutParams.size() > 1) { - H << nl << "auto responseCb = [response](" << futureT << "&& result)"; + H << nl << "auto _responseCb = [response](" << futureT << "&& _result)"; H << sb; - H << nl << "response" << spar; + H << nl << responseParam << spar; if(ret) { - H << condMove(isMovable(ret), string("result.") + returnValueS); + H << condMove(isMovable(ret), string("_result.") + returnValueS); } for(ParamDeclList::const_iterator q = outParams.begin(); q != outParams.end(); ++q) { - H << condMove(isMovable((*q)->type()), "result." + fixKwd((*q)->name())); + H << condMove(isMovable((*q)->type()), "_result." + fixKwd((*q)->name())); } H << epar << ";" << eb << ";"; } H << nl << "return _makeLamdaOutgoing<" << futureT << ">" << spar; - H << (futureOutParams.size() > 1 ? "responseCb" : "response") << "ex" << "sent" << "this"; + H << (futureOutParams.size() > 1 ? "_responseCb" : responseParam) << exParam << sentParam << "this"; H << string("&" + getAbsolute(scoped, clScope.substr(2)) + "_iceI_" + name); for(ParamDeclList::const_iterator q = inParams.begin(); q != inParams.end(); ++q) { - H << fixKwd(paramPrefix + (*q)->name()); + H << fixKwd((*q)->name()); } - H << "context" << epar << ";"; + H << contextParam << epar << ";"; H << eb; } @@ -6278,16 +7187,19 @@ Slice::Gen::Cpp11ProxyVisitor::visitOperation(const OperationPtr& p) // H << sp; + H << nl << "/// \\cond INTERNAL"; H << nl << _dllMemberExport << "void _iceI_" << name << spar; H << "const ::std::shared_ptr<::IceInternal::OutgoingAsyncT<" + futureT + ">>&"; H << inParamsS; H << ("const " + getAbsolute("::Ice::Context&", clScope)); H << epar << ";"; + H << nl << "/// \\endcond"; C << sp; + C << nl << "/// \\cond INTERNAL"; C << nl << "void" << nl << scoped << "_iceI_" << name << spar; C << "const ::std::shared_ptr<::IceInternal::OutgoingAsyncT<" + futureT + ">>& outAsync"; - C << inParamsDecl << ("const " + getAbsolute("::Ice::Context&", clScope) + " context"); + C << inParamsImplDecl << ("const " + getAbsolute("::Ice::Context&", clScope) + " context"); C << epar; C << sb; if(p->returnsData()) @@ -6354,13 +7266,16 @@ Slice::Gen::Cpp11ProxyVisitor::visitOperation(const OperationPtr& p) C.dec(); C << ");" << eb; + C << nl << "/// \\endcond"; } void Slice::Gen::Cpp11TypesVisitor::visitEnum(const EnumPtr& p) { bool unscoped = findMetaData(p->getMetaData(), TypeContextCpp11) == "%unscoped"; - H << sp << nl << "enum "; + H << sp; + writeDocSummary(H, p); + H << nl << "enum "; if(!unscoped) { H << "class "; @@ -6379,6 +7294,7 @@ Slice::Gen::Cpp11TypesVisitor::visitEnum(const EnumPtr& p) const bool explicitValue = p->explicitValue(); for(EnumeratorList::const_iterator en = enumerators.begin(); en != enumerators.end();) { + writeDocSummary(H, *en); H << nl << fixKwd((*en)->name()); // // If any of the enumerators were assigned an explicit value, we emit @@ -6401,6 +7317,7 @@ Slice::Gen::Cpp11TypesVisitor::visitConst(const ConstPtr& p) { const string scope = fixKwd(p->scope()); H << sp; + writeDocSummary(H, p); H << nl << (isConstexprType(p->type()) ? "constexpr " : "const ") << typeToString(p->type(), scope, p->typeMetaData(), _useWstring | TypeContextCpp11) << " " << fixKwd(p->name()) << " = "; @@ -6409,7 +7326,8 @@ Slice::Gen::Cpp11TypesVisitor::visitConst(const ConstPtr& p) } void -Slice::Gen::Cpp11TypesVisitor::emitUpcall(const ExceptionPtr& base, const string& call, const string& scope, bool isLocal) +Slice::Gen::Cpp11TypesVisitor::emitUpcall(const ExceptionPtr& base, const string& call, const string& scope, + bool isLocal) { C << nl; if(base) @@ -6448,6 +7366,7 @@ Slice::Gen::Cpp11ObjectVisitor::emitDataMember(const DataMemberPtr& p) typeContext |= TypeContextLocal; } + writeDocSummary(H, p); H << nl << typeToString(p->type(), p->optional(), scope, p->getMetaData(), typeContext) << ' ' << name; string defaultValue = p->defaultValue(); @@ -6547,11 +7466,18 @@ Slice::Gen::Cpp11LocalObjectVisitor::visitClassDefStart(const ClassDefPtr& p) { int typeCtx = _useWstring | TypeContextLocal | TypeContextCpp11; - // Generate alias - H << sp << nl << "using " << name << " = "; - // A delegate only has one operation OperationPtr op = p->allOperations().front(); + + // Generate alias + H << sp; + CommentPtr comment = op->parseComment(false); + if(comment) + { + writeOpDocSummary(H, op, comment, OpDocAllParams, true, StringList(), StringList(), comment->returns()); + } + H << nl << "using " << name << " = "; + TypePtr ret = op->returnType(); string retS = returnTypeToString(ret, op->returnIsOptional(), scope, op->getMetaData(), typeCtx); @@ -6568,6 +7494,7 @@ Slice::Gen::Cpp11LocalObjectVisitor::visitClassDefStart(const ClassDefPtr& p) { H << inputTypeToString((*q)->type(), (*q)->optional(), scope, (*q)->getMetaData(), typeCtx); } + H << " " << fixKwd((*q)->name()); H << (IceUtilInternal::distance(q, paramList.end()) == 1 ? "" : ", "); } H << ")>;"; @@ -6585,7 +7512,9 @@ Slice::Gen::Cpp11LocalObjectVisitor::visitClassDefStart(const ClassDefPtr& p) DataMemberList dataMembers = p->dataMembers(); DataMemberList allDataMembers = p->allDataMembers(); - H << sp << nl << "class " << _dllClassExport << name; + H << sp; + writeDocSummary(H, p); + H << nl << "class " << _dllClassExport << name; H.useCurrentPosAsIndent(); if(!bases.empty()) { @@ -6622,22 +7551,6 @@ Slice::Gen::Cpp11LocalObjectVisitor::visitClassDefStart(const ClassDefPtr& p) C << sb; C << eb; - vector<string> params; - vector<string> allTypes; - vector<string> allParamDecls; - - for(DataMemberList::const_iterator q = dataMembers.begin(); q != dataMembers.end(); ++q) - { - params.push_back(fixKwd((*q)->name())); - } - - for(DataMemberList::const_iterator q = allDataMembers.begin(); q != allDataMembers.end(); ++q) - { - string typeName = inputTypeToString((*q)->type(), (*q)->optional(), scope, (*q)->getMetaData(), _useWstring | TypeContextLocal); - allTypes.push_back(typeName); - allParamDecls.push_back(typeName + " iceP_" + (*q)->name()); - } - if(!p->isInterface()) { if(p->hasDefaultValues()) @@ -6748,87 +7661,42 @@ Slice::Gen::Cpp11LocalObjectVisitor::visitOperation(const OperationPtr& p) int typeCtx = _useWstring | TypeContextLocal | TypeContextCpp11; TypePtr ret = p->returnType(); - string retS = returnTypeToString(ret, p->returnIsOptional(), scope, p->getMetaData(), - typeCtx); + string retS = returnTypeToString(ret, p->returnIsOptional(), scope, p->getMetaData(), typeCtx); string params = "("; - string paramsDecl = "("; - string args = "("; ContainerPtr container = p->container(); ClassDefPtr cl = ClassDefPtr::dynamicCast(container); string classScope = fixKwd(cl->scope()); - ParamDeclList inParams; - ParamDeclList outParams; - ParamDeclList paramList = p->parameters(); - vector< string> outDecls; - for(ParamDeclList::iterator q = paramList.begin(); q != paramList.end(); ++q) - { - string paramName = fixKwd(string(paramPrefix) + (*q)->name()); - TypePtr type = (*q)->type(); - bool isOutParam = (*q)->isOutParam(); - string typeString; - if(isOutParam) - { - outParams.push_back(*q); - typeString = outputTypeToString(type, (*q)->optional(), classScope, (*q)->getMetaData(), typeCtx); - } - else - { - inParams.push_back(*q); - typeString = inputTypeToString(type, (*q)->optional(), classScope, (*q)->getMetaData(), typeCtx); - } - - if(q != paramList.begin()) - { - params += ", "; - paramsDecl += ", "; - args += ", "; - } - - params += typeString; - paramsDecl += typeString; - paramsDecl += ' '; - paramsDecl += paramName; - args += paramName; - - if(isOutParam) - { - outDecls.push_back(typeString); - } - } - - params += ')'; - paramsDecl += ')'; - args += ')'; - string isConst = ((p->mode() == Operation::Nonmutating) || p->hasMetaData("cpp:const")) ? " const" : ""; string noExcept = p->hasMetaData("cpp:noexcept") ? " noexcept" : ""; string deprecateSymbol = getDeprecateSymbol(p, cl); + CommentPtr comment = p->parseComment(false); + if(cl->hasMetaData("async-oneway") || p->hasMetaData("async-oneway")) { vector<string> paramsDeclAMI; vector<string> outParamsDeclAMI; vector<string> paramsArgAMI; - ParamDeclList paramList = p->parameters(); + ParamDeclList paramList = p->inParameters(); for(ParamDeclList::const_iterator r = paramList.begin(); r != paramList.end(); ++r) { string paramName = fixKwd((*r)->name()); StringList metaData = (*r)->getMetaData(); - string typeString; - if(!(*r)->isOutParam()) - { - typeString = inputTypeToString((*r)->type(), (*r)->optional(), classScope, metaData, typeCtx); - paramsDeclAMI.push_back(typeString + ' ' + paramName); - paramsArgAMI.push_back(paramName); - } + string typeString = inputTypeToString((*r)->type(), (*r)->optional(), classScope, metaData, typeCtx); + paramsDeclAMI.push_back(typeString + ' ' + paramName); + paramsArgAMI.push_back(paramName); } H << sp; + if(comment) + { + writeOpDocSummary(H, p, comment, OpDocAllParams, true, StringList(), StringList(), comment->returns()); + } H << nl << deprecateSymbol << "virtual " << retS << ' ' << fixKwd(name) << spar << paramsDeclAMI << epar << isConst << noExcept; H << sb; @@ -6836,11 +7704,25 @@ Slice::Gen::Cpp11LocalObjectVisitor::visitOperation(const OperationPtr& p) H << eb; H << sp; + if(comment) + { + string exParam = escapeParam(paramList, "exception"); + string sentParam = escapeParam(paramList, "sent"); + StringList postParams, returns; + postParams.push_back("@param " + exParam + " The exception callback."); + postParams.push_back("@param " + sentParam + " The sent callback."); + returns.push_back("A function that can be called to cancel the invocation locally."); + writeOpDocSummary(H, p, comment, OpDocInParams, false, StringList(), postParams, returns); + } H << nl << "virtual ::std::function<void()>"; H << nl << name << "Async("; H.useCurrentPosAsIndent(); for(vector<string>::const_iterator i = paramsDeclAMI.begin(); i != paramsDeclAMI.end(); ++i) { + if(i != paramsDeclAMI.begin()) + { + H << nl; + } H << *i << ","; } if(!paramsDeclAMI.empty()) @@ -6852,6 +7734,12 @@ Slice::Gen::Cpp11LocalObjectVisitor::visitOperation(const OperationPtr& p) H.restoreIndent(); H << sp; + if(comment) + { + StringList returns; + returns.push_back("The future object for the invocation."); + writeOpDocSummary(H, p, comment, OpDocInParams, false, StringList(), StringList(), returns); + } H << nl << "template<template<typename> class P = ::std::promise>"; H << nl << deprecateSymbol << "auto " << name << "Async" << spar << paramsDeclAMI << epar; H.inc(); @@ -6865,6 +7753,10 @@ Slice::Gen::Cpp11LocalObjectVisitor::visitOperation(const OperationPtr& p) H.useCurrentPosAsIndent(); for(vector<string>::const_iterator i = paramsArgAMI.begin(); i != paramsArgAMI.end(); ++i) { + if(i != paramsArgAMI.begin()) + { + H << " "; + } H << *i << ","; } if(!paramsArgAMI.empty()) @@ -6886,8 +7778,40 @@ Slice::Gen::Cpp11LocalObjectVisitor::visitOperation(const OperationPtr& p) } else { + ParamDeclList paramList = p->parameters(); + for(ParamDeclList::iterator q = paramList.begin(); q != paramList.end(); ++q) + { + string paramName = fixKwd((*q)->name()); + TypePtr type = (*q)->type(); + string typeString; + if((*q)->isOutParam()) + { + typeString = outputTypeToString(type, (*q)->optional(), classScope, (*q)->getMetaData(), typeCtx); + } + else + { + typeString = inputTypeToString(type, (*q)->optional(), classScope, (*q)->getMetaData(), typeCtx); + } + + if(q != paramList.begin()) + { + params += ", "; + } + + params += typeString; + params += ' '; + params += paramName; + } + + params += ')'; + H << sp; - H << nl << deprecateSymbol << "virtual " << retS << ' ' << fixKwd(name) << params << isConst << noExcept << " = 0;"; + if(comment) + { + writeOpDocSummary(H, p, comment, OpDocAllParams, true, StringList(), StringList(), comment->returns()); + } + H << nl << deprecateSymbol << "virtual " << retS << ' ' << fixKwd(name) << params << isConst << noExcept + << " = 0;"; } } @@ -6943,7 +7867,9 @@ Slice::Gen::Cpp11InterfaceVisitor::visitClassDefStart(const ClassDefPtr& p) base = bases.front(); } - H << sp << nl << "class " << _dllExport << name << " : "; + H << sp; + writeDocSummary(H, p); + H << nl << "class " << _dllExport << name << " : "; H.useCurrentPosAsIndent(); if(bases.empty() || (base && base->allOperations().empty())) { @@ -6996,13 +7922,37 @@ Slice::Gen::Cpp11InterfaceVisitor::visitClassDefStart(const ClassDefPtr& p) assert(scopedIter != ids.end()); H << sp; - H << nl << "virtual bool ice_isA(::std::string, const " << getAbsolute("::Ice::Current&", scope) - << ") const override;"; + H << nl << "/**"; + H << nl << " * Determines whether this object supports an interface with the given Slice type ID."; + H << nl << " * @param id The fully-scoped Slice type ID."; + H << nl << " * @param current The Current object for the invocation."; + H << nl << " * @return True if this object supports the interface, false, otherwise."; + H << nl << " */"; + H << nl << "virtual bool ice_isA(::std::string id, const " << getAbsolute("::Ice::Current&", scope) + << " current) const override;"; + H << sp; + H << nl << "/**"; + H << nl << " * Obtains a list of the Slice type IDs representing the interfaces supported by this object."; + H << nl << " * @param current The Current object for the invocation."; + H << nl << " * @return A list of fully-scoped type IDs."; + H << nl << " */"; H << nl << "virtual ::std::vector<::std::string> ice_ids(const " << getAbsolute("::Ice::Current&", scope) - << ") const override;"; - H << nl << "virtual ::std::string ice_id(const " << getAbsolute("::Ice::Current&", scope) << ") const override;"; - H << sp << nl << "static const ::std::string& ice_staticId();"; + << " current) const override;"; + H << sp; + H << nl << "/**"; + H << nl << " * Obtains a Slice type ID representing the most-derived interface supported by this object."; + H << nl << " * @param current The Current object for the invocation."; + H << nl << " * @return A fully-scoped type ID."; + H << nl << " */"; + H << nl << "virtual ::std::string ice_id(const " << getAbsolute("::Ice::Current&", scope) + << " current) const override;"; + H << sp; + H << nl << "/**"; + H << nl << " * Obtains the Slice type ID corresponding to this class."; + H << nl << " * @return A fully-scoped type ID."; + H << nl << " */"; + H << nl << "static const ::std::string& ice_staticId();"; string flatName = "iceC" + p->flattenedScope() + p->name() + "_ids"; @@ -7017,7 +7967,8 @@ Slice::Gen::Cpp11InterfaceVisitor::visitClassDefStart(const ClassDefPtr& p) C << nl << "::std::vector<::std::string>" << nl << scoped.substr(2) << "::ice_ids(const " << getAbsolute("::Ice::Current&", scope) << ") const"; C << sb; - C << nl << "return ::std::vector<::std::string>(&" << flatName << "[0], &" << flatName << '[' << ids.size() << "]);"; + C << nl << "return ::std::vector<::std::string>(&" << flatName << "[0], &" << flatName << '[' << ids.size() + << "]);"; C << eb; C << sp; @@ -7069,17 +8020,21 @@ Slice::Gen::Cpp11InterfaceVisitor::visitClassDefEnd(const ClassDefPtr& p) string flatName = "iceC" + p->flattenedScope() + p->name() + "_ops"; H << sp; - H << nl << "virtual bool _iceDispatch(::IceInternal::Incoming&, const " << getAbsolute("::Ice::Current&", scope) - << ") override;"; + H << nl << "/// \\cond INTERNAL"; + H << nl << "virtual bool _iceDispatch(::IceInternal::Incoming&, const " + << getAbsolute("::Ice::Current&", scope) << ") override;"; + H << nl << "/// \\endcond"; C << sp; + C << nl << "/// \\cond INTERNAL"; C << nl << "bool"; C << nl << scoped.substr(2) << "::_iceDispatch(::IceInternal::Incoming& in, const " << getAbsolute("::Ice::Current&", scope) << " current)"; C << sb; C << nl << "::std::pair<const ::std::string*, const ::std::string*> r = " - << "::std::equal_range(" << flatName << ", " << flatName << " + " << allOpNames.size() << ", current.operation);"; + << "::std::equal_range(" << flatName << ", " << flatName << " + " << allOpNames.size() + << ", current.operation);"; C << nl << "if(r.first == r.second)"; C << sb; C << nl << "throw " << getAbsolute("::Ice::OperationNotExistException", scope) @@ -7104,6 +8059,7 @@ Slice::Gen::Cpp11InterfaceVisitor::visitClassDefEnd(const ClassDefPtr& p) C << eb; C << eb; C << eb; + C << nl << "/// \\endcond"; } H << eb << ';'; @@ -7135,6 +8091,7 @@ Slice::Gen::Cpp11InterfaceVisitor::visitOperation(const OperationPtr& p) vector<string> responseParams; vector<string> responseParamsDecl; + vector<string> responseParamsImplDecl; ContainerPtr container = p->container(); ClassDefPtr cl = ClassDefPtr::dynamicCast(container); @@ -7144,13 +8101,28 @@ Slice::Gen::Cpp11InterfaceVisitor::visitOperation(const OperationPtr& p) string scope = fixKwd(cl->scope() + cl->name() + suffix + "::"); string scoped = fixKwd(cl->scope() + cl->name() + suffix + "::" + p->name()); - bool amd = (cl->hasMetaData("amd") || p->hasMetaData("amd")); + ParamDeclList inParams = p->inParameters(); + ParamDeclList outParams = p->outParameters(); + ParamDeclList paramList = p->parameters(); + + const bool amd = (cl->hasMetaData("amd") || p->hasMetaData("amd")); + + const string returnValueParam = escapeParam(outParams, "returnValue"); + const string responsecbParam = escapeParam(inParams, "response"); + const string excbParam = escapeParam(inParams, "exception"); + const string currentParam = escapeParam(amd ? inParams : paramList, "current"); + const string currentTypeDecl = "const " + getAbsolute("::Ice::Current&", classScope); + const string currentDecl = currentTypeDecl + " " + currentParam; + + CommentPtr comment = p->parseComment(false); + if(ret) { string typeS = inputTypeToString(ret, p->returnIsOptional(), classScope, p->getMetaData(), _useWstring | TypeContextCpp11); - responseParams.push_back(typeS); + responseParams.push_back(typeS + " " + returnValueParam); responseParamsDecl.push_back(typeS + " ret"); + responseParamsImplDecl.push_back(typeS + " ret"); } string retS; @@ -7168,36 +8140,35 @@ Slice::Gen::Cpp11InterfaceVisitor::visitOperation(const OperationPtr& p) _useWstring | TypeContextCpp11); } - ParamDeclList inParams; - ParamDeclList outParams; - ParamDeclList paramList = p->parameters(); for(ParamDeclList::iterator q = paramList.begin(); q != paramList.end(); ++q) { TypePtr type = (*q)->type(); - string paramName = fixKwd(string(paramPrefix) + (*q)->name()); + string paramName = fixKwd((*q)->name()); bool isOutParam = (*q)->isOutParam(); string typeString; int typeCtx = _useWstring | TypeContextCpp11; + if(!isOutParam) { - inParams.push_back(*q); params.push_back(typeToString(type, (*q)->optional(), classScope, (*q)->getMetaData(), - typeCtx | TypeContextInParam)); - args.push_back(condMove(isMovable(type) && !isOutParam, paramName)); + typeCtx | TypeContextInParam) + " " + paramName); + args.push_back(condMove(isMovable(type) && !isOutParam, paramPrefix + (*q)->name())); } else { - outParams.push_back(*q); if(!p->hasMarshaledResult() && !amd) { - params.push_back(outputTypeToString(type, (*q)->optional(), classScope, (*q)->getMetaData(), typeCtx)); - args.push_back(condMove(isMovable(type) && !isOutParam, paramName)); + params.push_back( + outputTypeToString(type, (*q)->optional(), classScope, (*q)->getMetaData(), typeCtx) + " " + + paramName); + args.push_back(condMove(isMovable(type) && !isOutParam, paramPrefix + (*q)->name())); } string responseTypeS = inputTypeToString((*q)->type(), (*q)->optional(), classScope, (*q)->getMetaData(), typeCtx); - responseParams.push_back(responseTypeS); - responseParamsDecl.push_back(responseTypeS + " " + paramName); + responseParams.push_back(responseTypeS + " " + paramName); + responseParamsDecl.push_back(responseTypeS + " " + paramPrefix + (*q)->name()); + responseParamsImplDecl.push_back(responseTypeS + " " + paramPrefix + (*q)->name()); } } if(amd) @@ -7205,18 +8176,18 @@ Slice::Gen::Cpp11InterfaceVisitor::visitOperation(const OperationPtr& p) if(p->hasMarshaledResult()) { string resultName = resultStructName(name, "", true); - params.push_back("::std::function<void(const " + resultName + "&)>"); + params.push_back("::std::function<void(const " + resultName + "&)> " + responsecbParam); args.push_back("inA->response<" + resultName + ">()"); } else { - params.push_back("::std::function<void(" + joinString(responseParams, ",") + ")>"); + params.push_back("::std::function<void(" + joinString(responseParams, ", ") + ")> " + responsecbParam); args.push_back(ret || !outParams.empty() ? "responseCB" : "inA->response()"); } - params.push_back("::std::function<void(::std::exception_ptr)>"); + params.push_back("::std::function<void(::std::exception_ptr)> " + excbParam); args.push_back("inA->exception()"); } - params.push_back("const " + getAbsolute("::Ice::Current&", classScope)); + params.push_back(currentDecl); args.push_back("current"); if(cl->isInterface()) @@ -7228,18 +8199,41 @@ Slice::Gen::Cpp11InterfaceVisitor::visitOperation(const OperationPtr& p) { string resultName = resultStructName(name, "", true); H << sp; + H << nl << "/**"; + H << nl << " * Marshaled result structure for operation " << (amd ? name + "Async" : fixKwd(name)) << "."; + H << nl << " */"; H << nl << "class " << resultName << " : public " << getAbsolute("::Ice::MarshaledResult", classScope); H << sb; H.dec(); H << nl << "public:"; H.inc(); - H << nl << resultName << spar << responseParams << ("const " + getAbsolute("::Ice::Current&", classScope)) - << epar << ";"; + H << nl << "/**"; + H << nl << " * Marshals the results immediately."; + if(ret && comment && !comment->returns().empty()) + { + H << nl << " * @param " << returnValueParam << " " << getDocSentence(comment->returns()); + } + map<string, StringList> paramComments; + if(comment) + { + paramComments = comment->parameters(); + } + const string mrcurrent = escapeParam(outParams, "current"); + for(ParamDeclList::iterator q = outParams.begin(); q != outParams.end(); ++q) + { + map<string, StringList>::iterator r = paramComments.find((*q)->name()); + if(r != paramComments.end()) + { + H << nl << " * @param " << fixKwd(r->first) << " " << getDocSentence(r->second); + } + } + H << nl << " * @param " << mrcurrent << " The Current object for the invocation."; + H << nl << " */"; + H << nl << resultName << spar << responseParams << currentTypeDecl + " " + mrcurrent << epar << ";"; H << eb << ';'; C << sp << nl << scope.substr(2) << resultName << "::" << resultName; - C << spar << responseParamsDecl << ("const " + getAbsolute("::Ice::Current&", classScope) + " current") - << epar << ":"; + C << spar << responseParamsImplDecl << currentTypeDecl + " current" << epar << ":"; C.inc(); C << nl << "MarshaledResult(current)"; C.dec(); @@ -7260,17 +8254,41 @@ Slice::Gen::Cpp11InterfaceVisitor::visitOperation(const OperationPtr& p) string deprecateSymbol = getDeprecateSymbol(p, cl); H << sp; + if(comment) + { + OpDocParamType pt = (amd || p->hasMarshaledResult()) ? OpDocInParams : OpDocAllParams; + StringList postParams, returns; + if(amd) + { + postParams.push_back("@param " + responsecbParam + " The response callback."); + postParams.push_back("@param " + excbParam + " The exception callback."); + } + else if(p->hasMarshaledResult()) + { + returns.push_back("The marshaled result structure."); + } + else if(!amd) + { + returns = comment->returns(); + } + postParams.push_back("@param " + currentParam + " The Current object for the invocation."); + writeOpDocSummary(H, p, comment, pt, true, StringList(), postParams, returns); + } H << nl << deprecateSymbol << "virtual " << retS << ' ' << opName << spar << params << epar << isConst << " = 0;"; + H << nl << "/// \\cond INTERNAL"; H << nl << "bool _iceD_" << name << "(::IceInternal::Incoming&, const " << getAbsolute("::Ice::Current&", classScope) << ")" << isConst << ';'; + H << nl << "/// \\endcond"; C << sp; + C << nl << "/// \\cond INTERNAL"; C << nl << "bool"; C << nl << scope.substr(2); - C << "_iceD_" << name << "(::IceInternal::Incoming& inS" << ", const " << getAbsolute("::Ice::Current&", classScope) - << " current)" << isConst; + C << "_iceD_" << name << "(::IceInternal::Incoming& inS, const " + << getAbsolute("::Ice::Current&", classScope) << " current)" << isConst; C << sb; - C << nl << "_iceCheckMode(" << getAbsolute(operationModeToString(p->mode(), true), classScope) << ", current.mode);"; + C << nl << "_iceCheckMode(" << getAbsolute(operationModeToString(p->mode(), true), classScope) + << ", current.mode);"; if(!inParams.empty()) { @@ -7354,6 +8372,7 @@ Slice::Gen::Cpp11InterfaceVisitor::visitOperation(const OperationPtr& p) C << nl << "return false;"; } C << eb; + C << nl << "/// \\endcond"; } Slice::Gen::Cpp11ValueVisitor::Cpp11ValueVisitor(::IceUtilInternal::Output& h, @@ -7407,7 +8426,9 @@ Slice::Gen::Cpp11ValueVisitor::visitClassDefStart(const ClassDefPtr& p) DataMemberList dataMembers = p->dataMembers(); DataMemberList allDataMembers = p->allDataMembers(); - H << sp << nl << "class " << _dllClassExport << name << " : public " << getAbsolute("::Ice::ValueHelper", scope) + H << sp; + writeDocSummary(H, p); + H << nl << "class " << _dllClassExport << name << " : public " << getAbsolute("::Ice::ValueHelper", scope) << "<" << name << ", "; if(!base || (base && base->isInterface())) @@ -7447,9 +8468,19 @@ Slice::Gen::Cpp11ValueVisitor::visitClassDefStart(const ClassDefPtr& p) emitOneShotConstructor(p); + H << sp; + H << nl << "/**"; + H << nl << " * Obtains a tuple containing all of the value's data members."; + H << nl << " * @return The data members in a tuple."; + H << nl << " */"; writeIceTuple(H, fixKwd(p->scope()), p->allDataMembers(), _useWstring); - H << sp << nl << _dllMemberExport << "static const ::std::string& ice_staticId();"; + H << sp; + H << nl << "/**"; + H << nl << " * Obtains the Slice type ID of this value."; + H << nl << " * @return The fully-scoped type ID."; + H << nl << " */"; + H << nl << _dllMemberExport << "static const ::std::string& ice_staticId();"; return true; } @@ -7470,7 +8501,14 @@ Slice::Gen::Cpp11ValueVisitor::visitClassDefEnd(const ClassDefPtr& p) if(preserved && !basePreserved) { - H << sp << nl << "virtual ::std::shared_ptr<" << getAbsolute("::Ice::SlicedData", scope) + H << sp; + H << nl << "/**"; + H << nl << " * Obtains the SlicedData object created when an unknown value type was marshaled"; + H << nl << " * in the sliced format and the Ice run time sliced it to a known type."; + H << nl << " * @return The SlicedData object, or nil if the value was not sliced or was not"; + H << nl << " * marshaled in the sliced format."; + H << nl << " */"; + H << nl << "virtual ::std::shared_ptr<" << getAbsolute("::Ice::SlicedData", scope) << "> ice_getSlicedData() const override;"; C << sp; @@ -7480,10 +8518,13 @@ Slice::Gen::Cpp11ValueVisitor::visitClassDefEnd(const ClassDefPtr& p) C << eb; H << sp; + H << nl << "/// \\cond STREAM"; H << nl << "virtual void _iceWrite(" << getAbsolute("::Ice::OutputStream*", scope) << ") const override;"; H << nl << "virtual void _iceRead(" << getAbsolute("::Ice::InputStream*", scope) << ") override;"; + H << nl << "/// \\endcond"; C << sp; + C << nl << "/// \\cond STREAM"; C << nl << "void" << nl << scoped.substr(2) << "::_iceWrite(" << getAbsolute("::Ice::OutputStream*", scope) << " ostr) const"; C << sb; @@ -7500,6 +8541,7 @@ Slice::Gen::Cpp11ValueVisitor::visitClassDefEnd(const ClassDefPtr& p) C << nl << "_iceReadImpl(istr);"; C << nl << "_iceSlicedData = istr->endValue(true);"; C << eb; + C << nl << "/// \\endcond"; } C << sp; @@ -7565,7 +8607,10 @@ Slice::Gen::Cpp11ValueVisitor::visitClassDefEnd(const ClassDefPtr& p) H.inc(); inProtected = true; } - H << sp << nl << "::std::shared_ptr<" << getAbsolute("::Ice::SlicedData", scope) << "> _iceSlicedData;"; + H << sp; + H << nl << "/// \\cond STREAM"; + H << nl << "::std::shared_ptr<" << getAbsolute("::Ice::SlicedData", scope) << "> _iceSlicedData;"; + H << nl << "/// \\endcond"; } if(generateFriend) @@ -7595,7 +8640,10 @@ Slice::Gen::Cpp11ValueVisitor::visitClassDefEnd(const ClassDefPtr& p) // all of the globals in a compilation unit. // _doneStaticSymbol = true; - H << sp << nl << "static " << fixKwd(p->name()) << " _iceS_" << p->name() << "_init;"; + H << sp; + H << nl << "/// \\cond INTERNAL"; + H << nl << "static " << fixKwd(p->name()) << " _iceS_" << p->name() << "_init;"; + H << nl << "/// \\endcond"; } _useWstring = resetUseWstring(_useWstringHist); @@ -7638,11 +8686,11 @@ Slice::Gen::Cpp11ObjectVisitor::emitVirtualBaseInitializers(const ClassDefPtr& d } if(isMovable((*q)->type())) { - upcall += "::std::move(iceP_" + (*q)->name() + ")"; + upcall += "::std::move(" + fixKwd((*q)->name()) + ")"; } else { - upcall += "iceP_" + (*q)->name(); + upcall += "" + fixKwd((*q)->name()); } } upcall += ")"; @@ -7668,6 +8716,7 @@ Slice::Gen::Cpp11ObjectVisitor::emitOneShotConstructor(const ClassDefPtr& p) if(!allDataMembers.empty()) { vector<string> allParamDecls; + map<string, CommentPtr> allComments; DataMemberList dataMembers = p->dataMembers(); int typeContext = _useWstring | TypeContextCpp11; @@ -7678,11 +8727,31 @@ Slice::Gen::Cpp11ObjectVisitor::emitOneShotConstructor(const ClassDefPtr& p) for(DataMemberList::const_iterator q = allDataMembers.begin(); q != allDataMembers.end(); ++q) { - string typeName = inputTypeToString((*q)->type(), (*q)->optional(), scope, (*q)->getMetaData(), typeContext); - allParamDecls.push_back(typeName + " iceP_" + (*q)->name()); + string typeName = + inputTypeToString((*q)->type(), (*q)->optional(), scope, (*q)->getMetaData(), typeContext); + allParamDecls.push_back(typeName + " " + fixKwd((*q)->name())); + CommentPtr comment = (*q)->parseComment(false); + if(comment) + { + allComments[(*q)->name()] = comment; + } } - H << sp << nl; + CommentPtr comment = p->parseComment(false); + + H << sp; + H << nl << "/**"; + H << nl << " * One-shot constructor to initialize all data members."; + for(DataMemberList::const_iterator q = allDataMembers.begin(); q != allDataMembers.end(); ++q) + { + map<string, CommentPtr>::iterator r = allComments.find((*q)->name()); + if(r != allComments.end()) + { + H << nl << " * @param " << fixKwd(r->first) << " " << getDocSentence(r->second->overview()); + } + } + H << nl << " */"; + H << nl; if(allParamDecls.size() == 1) { H << "explicit "; @@ -7717,11 +8786,11 @@ Slice::Gen::Cpp11ObjectVisitor::emitOneShotConstructor(const ClassDefPtr& p) string memberName = fixKwd((*q)->name()); if(isMovable((*q)->type())) { - H << memberName << "(::std::move(iceP_" << (*q)->name() << "))"; + H << memberName << "(::std::move(" << memberName << "))"; } else { - H << memberName << "(iceP_" << (*q)->name() << ')'; + H << memberName << "(" << memberName << ')'; } } @@ -7755,6 +8824,7 @@ Slice::Gen::Cpp11StreamVisitor::visitModuleStart(const ModulePtr& m) // Only emit this for the top-level module. // H << sp; + H << nl << "/// \\cond STREAM"; H << nl << "namespace Ice" << nl << '{' << sp; if(m->hasNonLocalContained(Contained::ContainedTypeStruct)) @@ -7775,6 +8845,7 @@ Slice::Gen::Cpp11StreamVisitor::visitModuleEnd(const ModulePtr& m) // Only emit this for the top-level module. // H << nl << '}'; + H << nl << "/// \\endcond"; if(m->hasNonLocalContained(Contained::ContainedTypeStruct)) { C << nl << '}'; @@ -7858,7 +8929,9 @@ Slice::Gen::Cpp11CompatibilityVisitor::visitModuleStart(const ModulePtr& p) string name = fixKwd(p->name()); - H << sp << nl << "namespace " << name << nl << '{'; + H << sp; + H << nl << "/// \\cond INTERNAL"; + H << nl << "namespace " << name << nl << '{'; return true; } @@ -7867,6 +8940,7 @@ Slice::Gen::Cpp11CompatibilityVisitor::visitModuleEnd(const ModulePtr&) { H << sp; H << nl << '}'; + H << nl << "/// \\endcond"; } void diff --git a/cpp/src/slice2cpp/Gen.h b/cpp/src/slice2cpp/Gen.h index 9e8bca138b9..7e55bd3acc9 100644 --- a/cpp/src/slice2cpp/Gen.h +++ b/cpp/src/slice2cpp/Gen.h @@ -342,9 +342,11 @@ private: ::IceUtilInternal::Output& C; std::string _dllExport; }; + // // C++11 Visitors // + class Cpp11DeclVisitor : private ::IceUtil::noncopyable, public ParserVisitor { public: diff --git a/cpp/src/slice2cpp/Main.cpp b/cpp/src/slice2cpp/Main.cpp index 622273e5658..d1482d3cbc0 100644 --- a/cpp/src/slice2cpp/Main.cpp +++ b/cpp/src/slice2cpp/Main.cpp @@ -298,7 +298,7 @@ compile(const vector<string>& argv) else { PreprocessorPtr icecpp = Preprocessor::create(argv[0], *i, cppArgs); - FILE* cppHandle = icecpp->preprocess(false, "-D__SLICE2CPP__"); + FILE* cppHandle = icecpp->preprocess(true, "-D__SLICE2CPP__"); if(cppHandle == 0) { diff --git a/cpp/src/slice2java/Gen.cpp b/cpp/src/slice2java/Gen.cpp index 9f15d3496f9..01d3e752ccb 100644 --- a/cpp/src/slice2java/Gen.cpp +++ b/cpp/src/slice2java/Gen.cpp @@ -220,7 +220,7 @@ Slice::JavaVisitor::getResultType(const OperationPtr& op, const string& package, } void -Slice::JavaVisitor::writeResultType(Output& out, const OperationPtr& op, const string& package, const DocCommentPtr& dc) +Slice::JavaVisitor::writeResultType(Output& out, const OperationPtr& op, const string& package, const CommentPtr& dc) { string opName = op->name(); opName[0] = toupper(static_cast<unsigned char>(opName[0])); @@ -286,16 +286,17 @@ Slice::JavaVisitor::writeResultType(Output& out, const OperationPtr& op, const s out << '.'; } - if(ret && !dc->returns.empty()) + if(ret && !dc->returns().empty()) { out << nl << " * @param " << retval << ' '; - writeDocCommentLines(out, dc->returns); + writeDocCommentLines(out, dc->returns()); } + map<string, StringList> paramDocs = dc->parameters(); for(ParamDeclList::const_iterator p = outParams.begin(); p != outParams.end(); ++p) { const string name = (*p)->name(); - map<string, string>::const_iterator q = dc->params.find(name); - if(q != dc->params.end() && !q->second.empty()) + map<string, StringList>::const_iterator q = paramDocs.find(name); + if(q != paramDocs.end() && !q->second.empty()) { out << nl << " * @param " << fixKwd(q->first) << ' '; writeDocCommentLines(out, q->second); @@ -308,14 +309,15 @@ Slice::JavaVisitor::writeResultType(Output& out, const OperationPtr& op, const s if(ret) { - out << (typeToString(ret, TypeModeIn, package, op->getMetaData(), true, !generateMandatoryOnly && op->returnIsOptional(), - cl->isLocal()) + " " + retval); + out << (typeToString(ret, TypeModeIn, package, op->getMetaData(), true, + !generateMandatoryOnly && op->returnIsOptional(), cl->isLocal()) + " " + retval); needMandatoryOnly = !generateMandatoryOnly && op->returnIsOptional(); } for(ParamDeclList::const_iterator p = outParams.begin(); p != outParams.end(); ++p) { out << (typeToString((*p)->type(), TypeModeIn, package, (*p)->getMetaData(), true, - !generateMandatoryOnly && (*p)->optional(), cl->isLocal()) + " " + fixKwd((*p)->name())); + !generateMandatoryOnly && (*p)->optional(), cl->isLocal()) + " " + + fixKwd((*p)->name())); if(!generateMandatoryOnly) { needMandatoryOnly = needMandatoryOnly || (*p)->optional(); @@ -358,11 +360,11 @@ Slice::JavaVisitor::writeResultType(Output& out, const OperationPtr& op, const s out << sp; if(ret) { - if(dc && !dc->returns.empty()) + if(dc && !dc->returns().empty()) { out << nl << "/**"; out << nl << " * "; - writeDocCommentLines(out, dc->returns); + writeDocCommentLines(out, dc->returns()); out << nl << " **/"; } out << nl << "public " << typeToString(ret, TypeModeIn, package, op->getMetaData(), true, @@ -375,8 +377,9 @@ Slice::JavaVisitor::writeResultType(Output& out, const OperationPtr& op, const s if(dc) { const string name = (*p)->name(); - map<string, string>::const_iterator q = dc->params.find(name); - if(q != dc->params.end() && !q->second.empty()) + map<string, StringList> paramDocs = dc->parameters(); + map<string, StringList>::const_iterator q = paramDocs.find(name); + if(q != paramDocs.end() && !q->second.empty()) { out << nl << "/**"; out << nl << " * "; @@ -401,13 +404,14 @@ Slice::JavaVisitor::writeResultType(Output& out, const OperationPtr& op, const s for(ParamDeclList::const_iterator pli = required.begin(); pli != required.end(); ++pli) { const string paramName = fixKwd((*pli)->name()); - writeMarshalUnmarshalCode(out, package, (*pli)->type(), OptionalNone, false, 0, "this." + paramName, true, iter, "", - (*pli)->getMetaData()); + writeMarshalUnmarshalCode(out, package, (*pli)->type(), OptionalNone, false, 0, "this." + paramName, true, + iter, "", (*pli)->getMetaData()); } if(ret && !op->returnIsOptional()) { - writeMarshalUnmarshalCode(out, package, ret, OptionalNone, false, 0, retval, true, iter, "", op->getMetaData()); + writeMarshalUnmarshalCode(out, package, ret, OptionalNone, false, 0, retval, true, iter, "", + op->getMetaData()); } // @@ -425,8 +429,8 @@ Slice::JavaVisitor::writeResultType(Output& out, const OperationPtr& op, const s } const string paramName = fixKwd((*pli)->name()); - writeMarshalUnmarshalCode(out, package, (*pli)->type(), OptionalOutParam, true, (*pli)->tag(), "this." + paramName, - true, iter, "", (*pli)->getMetaData()); + writeMarshalUnmarshalCode(out, package, (*pli)->type(), OptionalOutParam, true, (*pli)->tag(), + "this." + paramName, true, iter, "", (*pli)->getMetaData()); } if(checkReturnType) @@ -445,15 +449,15 @@ Slice::JavaVisitor::writeResultType(Output& out, const OperationPtr& op, const s { const string paramName = fixKwd((*pli)->name()); const string patchParams = getPatcher((*pli)->type(), package, "this." + paramName); - writeMarshalUnmarshalCode(out, package, (*pli)->type(), OptionalNone, false, 0, "this." + paramName, false, iter, - "", (*pli)->getMetaData(), patchParams); + writeMarshalUnmarshalCode(out, package, (*pli)->type(), OptionalNone, false, 0, "this." + paramName, false, + iter, "", (*pli)->getMetaData(), patchParams); } if(ret && !op->returnIsOptional()) { const string patchParams = getPatcher(ret, package, retval); - writeMarshalUnmarshalCode(out, package, ret, OptionalNone, false, 0, retval, false, iter, "", op->getMetaData(), - patchParams); + writeMarshalUnmarshalCode(out, package, ret, OptionalNone, false, 0, retval, false, iter, "", + op->getMetaData(), patchParams); } // @@ -473,8 +477,8 @@ Slice::JavaVisitor::writeResultType(Output& out, const OperationPtr& op, const s const string paramName = fixKwd((*pli)->name()); const string patchParams = getPatcher((*pli)->type(), package, paramName); - writeMarshalUnmarshalCode(out, package, (*pli)->type(), OptionalOutParam, true, (*pli)->tag(), "this." + paramName, - false, iter, "", (*pli)->getMetaData(), patchParams); + writeMarshalUnmarshalCode(out, package, (*pli)->type(), OptionalOutParam, true, (*pli)->tag(), + "this." + paramName, false, iter, "", (*pli)->getMetaData(), patchParams); } if(checkReturnType) @@ -492,7 +496,7 @@ Slice::JavaVisitor::writeResultType(Output& out, const OperationPtr& op, const s void Slice::JavaVisitor::writeMarshaledResultType(Output& out, const OperationPtr& op, const string& package, - const DocCommentPtr& dc) + const CommentPtr& dc) { string opName = op->name(); const TypePtr ret = op->returnType(); @@ -518,16 +522,17 @@ Slice::JavaVisitor::writeMarshaledResultType(Output& out, const OperationPtr& op out << nl << "/**"; out << nl << " * This constructor marshals the results of operation " << opName << " immediately."; - if(ret && !dc->returns.empty()) + if(ret && !dc->returns().empty()) { out << nl << " * @param " << retval << ' '; - writeDocCommentLines(out, dc->returns); + writeDocCommentLines(out, dc->returns()); } + map<string, StringList> paramDocs = dc->parameters(); for(ParamDeclList::const_iterator p = outParams.begin(); p != outParams.end(); ++p) { const string name = (*p)->name(); - map<string, string>::const_iterator q = dc->params.find(name); - if(q != dc->params.end() && !q->second.empty()) + map<string, StringList>::const_iterator q = paramDocs.find(name); + if(q != paramDocs.end() && !q->second.empty()) { out << nl << " * @param " << fixKwd(q->first) << ' '; writeDocCommentLines(out, q->second); @@ -621,16 +626,17 @@ Slice::JavaVisitor::writeMarshaledResultType(Output& out, const OperationPtr& op out << nl << " * This constructor marshals the results of operation " << opName << " immediately (overload without Optional parameters)."; - if(ret && !dc->returns.empty()) + if(ret && !dc->returns().empty()) { out << nl << " * @param " << retval << ' '; - writeDocCommentLines(out, dc->returns); + writeDocCommentLines(out, dc->returns()); } + map<string, StringList> paramDocs = dc->parameters(); for(ParamDeclList::const_iterator p = outParams.begin(); p != outParams.end(); ++p) { const string name = (*p)->name(); - map<string, string>::const_iterator q = dc->params.find(name); - if(q != dc->params.end() && !q->second.empty()) + map<string, StringList>::const_iterator q = paramDocs.find(name); + if(q != paramDocs.end() && !q->second.empty()) { out << nl << " * @param " << fixKwd(q->first) << ' '; writeDocCommentLines(out, q->second); @@ -1094,7 +1100,7 @@ Slice::JavaVisitor::writeDispatch(Output& out, const ClassDefPtr& p) { OperationPtr op = *r; - DocCommentPtr dc = parseDocComment(op); + CommentPtr dc = op->parseComment(false); // // The "MarshaledResult" type is generated in the servant interface. @@ -1116,7 +1122,7 @@ Slice::JavaVisitor::writeDispatch(Output& out, const ClassDefPtr& p) out << sp; writeServantDocComment(out, op, package, dc, amd); - if(dc && dc->deprecated) + if(dc && dc->isDeprecated()) { out << nl << "@Deprecated"; } @@ -1199,15 +1205,16 @@ Slice::JavaVisitor::writeDispatch(Output& out, const ClassDefPtr& p) OperationPtr op = *r; StringList opMetaData = op->getMetaData(); - DocCommentPtr dc = parseDocComment(op); + CommentPtr dc = op->parseComment(false); string opName = op->name(); out << sp; - if(dc && dc->deprecated) + if(dc && dc->isDeprecated()) { out << nl << "@Deprecated"; } - out << nl << "static java.util.concurrent.CompletionStage<" << getAbsolute("com.zeroc.Ice.OutputStream", package) + out << nl << "static java.util.concurrent.CompletionStage<" + << getAbsolute("com.zeroc.Ice.OutputStream", package) << "> _iceD_" << opName << '('; if(p->isInterface()) { @@ -1735,189 +1742,26 @@ Slice::JavaVisitor::splitComment(const ContainedPtr& p) return result; } -Slice::JavaVisitor::DocCommentPtr -Slice::JavaVisitor::parseDocComment(const ContainedPtr& p) +void +Slice::JavaVisitor::writeDocCommentLines(Output& out, const StringList& lines) { - DocCommentPtr c = new DocComment; - c->deprecated = false; - // - // First check metadata for a deprecated tag. + // This method emits a block of text, prepending a leading " * " to the second and + // subsequent lines. We assume the caller prepended a leading " * " for the first + // line if necessary. // - string deprecateMetadata; - if(p->findMetaData("deprecate", deprecateMetadata)) + assert(!lines.empty()); + StringList l = lines; + out << l.front(); + l.pop_front(); + for(StringList::const_iterator p = l.begin(); p != l.end(); ++p) { - c->deprecated = true; - if(deprecateMetadata.find("deprecate:") == 0 && deprecateMetadata.size() > 10) + out << nl << " *"; + if(!p->empty()) { - c->deprecateReason = IceUtilInternal::trim(deprecateMetadata.substr(10)); + out << " " << *p; } } - - const StringList lines = splitComment(p); - if(lines.empty()) - { - return c->deprecated ? c : DocCommentPtr(0); // Docs exist if it's deprecated. - } - - StringList::const_iterator i; - for(i = lines.begin(); i != lines.end(); ++i) - { - const string l = *i; - if(l[0] == '@') - { - break; - } - if(!c->overview.empty()) - { - c->overview += "\n"; - } - c->overview += l; - } - - enum State { StateMisc, StateParam, StateThrows, StateReturn, StateDeprecated }; - State state = StateMisc; - string name; - const string ws = " \t"; - const string paramTag = "@param"; - const string throwsTag = "@throws"; - const string exceptionTag = "@exception"; - const string returnTag = "@return"; - const string deprecatedTag = "@deprecated"; - for(; i != lines.end(); ++i) - { - const string l = *i; - if(l.find(paramTag) == 0) - { - state = StateMisc; - name.clear(); - string::size_type n = l.find_first_not_of(ws, paramTag.size()); - if(n == string::npos) - { - continue; // Malformed line, ignore it. - } - string::size_type end = l.find_first_of(ws, n); - if(end == string::npos) - { - continue; // Malformed line, ignore it. - } - name = l.substr(n, end - n); - state = StateParam; - n = l.find_first_not_of(ws, end); - if(n != string::npos) - { - c->params[name] = l.substr(n); // The first line of the description. - } - } - else if(l.find(throwsTag) == 0 || l.find(exceptionTag) == 0) - { - state = StateMisc; - name.clear(); - string::size_type n = - l.find_first_not_of(ws, l.find(throwsTag) == 0 ? throwsTag.size() : exceptionTag.size()); - if(n == string::npos) - { - continue; // Malformed line, ignore it. - } - string::size_type end = l.find_first_of(ws, n); - if(end == string::npos) - { - continue; // Malformed line, ignore it. - } - name = l.substr(n, end - n); - state = StateThrows; - n = l.find_first_not_of(ws, end); - if(n != string::npos) - { - c->exceptions[name] = l.substr(n); // The first line of the description. - } - } - else if(l.find(returnTag) == 0) - { - state = StateMisc; - name.clear(); - string::size_type n = l.find_first_not_of(ws, returnTag.size()); - if(n == string::npos) - { - continue; // Malformed line, ignore it. - } - state = StateReturn; - c->returns = l.substr(n); // The first line of the description. - } - else if(l.find(deprecatedTag) == 0) - { - state = StateMisc; - name.clear(); - string::size_type n = l.find_first_not_of(ws, deprecatedTag.size()); - if(n != string::npos) - { - c->deprecateReason = l.substr(n); // The first line of the description. - } - state = StateDeprecated; - c->deprecated = true; - } - else if(!l.empty()) - { - if(l[0] == '@') - { - // - // Treat all other tags as miscellaneous comments. - // - state = StateMisc; - } - - switch(state) - { - case StateMisc: - if(!c->misc.empty()) - { - c->misc += "\n"; - } - c->misc += l; - break; - case StateParam: - assert(!name.empty()); - if(c->params.find(name) == c->params.end()) - { - c->params[name] = ""; - } - if(!c->params[name].empty()) - { - c->params[name] += "\n"; - } - c->params[name] += l; - break; - case StateThrows: - assert(!name.empty()); - if(c->exceptions.find(name) == c->exceptions.end()) - { - c->exceptions[name] = ""; - } - if(!c->exceptions[name].empty()) - { - c->exceptions[name] += "\n"; - } - c->exceptions[name] += l; - break; - case StateReturn: - if(!c->returns.empty()) - { - c->returns += "\n"; - } - c->returns += l; - break; - case StateDeprecated: - if(!c->deprecateReason.empty()) - { - c->deprecateReason += "\n"; - } - c->deprecateReason += l; - break; - } - } - } - - return c; } void @@ -1970,7 +1814,7 @@ Slice::JavaVisitor::writeDocCommentLines(Output& out, const string& text) } void -Slice::JavaVisitor::writeDocComment(Output& out, const DocCommentPtr& dc) +Slice::JavaVisitor::writeDocComment(Output& out, const CommentPtr& dc) { if(!dc) { @@ -1978,22 +1822,36 @@ Slice::JavaVisitor::writeDocComment(Output& out, const DocCommentPtr& dc) } out << nl << "/**"; - if(!dc->overview.empty()) + if(!dc->overview().empty()) { out << nl << " * "; - writeDocCommentLines(out, dc->overview); + writeDocCommentLines(out, dc->overview()); } - if(!dc->misc.empty()) + if(!dc->misc().empty()) { out << nl << " * "; - writeDocCommentLines(out, dc->misc); + writeDocCommentLines(out, dc->misc()); + } + + if(!dc->seeAlso().empty()) + { + out << nl << " *"; + StringList sa = dc->seeAlso(); + for(StringList::iterator p = sa.begin(); p != sa.end(); ++p) + { + out << nl << " * @see " << *p; + } } - if(!dc->deprecateReason.empty()) + if(!dc->deprecated().empty()) { out << nl << " * @deprecated "; - writeDocCommentLines(out, dc->deprecateReason); + writeDocCommentLines(out, dc->deprecated()); + } + else if(dc->isDeprecated()) + { + out << nl << " * @deprecated"; } out << nl << " **/"; @@ -2013,7 +1871,7 @@ Slice::JavaVisitor::writeDocComment(Output& out, const string& text) void Slice::JavaVisitor::writeProxyDocComment(Output& out, const OperationPtr& p, const string& package, - const DocCommentPtr& dc, bool async, bool context) + const CommentPtr& dc, bool async, bool context) { if(!dc) { @@ -2021,12 +1879,13 @@ Slice::JavaVisitor::writeProxyDocComment(Output& out, const OperationPtr& p, con } const string contextParam = " * @param context The Context map to send with the invocation."; + map<string, StringList> paramDocs = dc->parameters(); out << nl << "/**"; - if(!dc->overview.empty()) + if(!dc->overview().empty()) { out << nl << " * "; - writeDocCommentLines(out, dc->overview); + writeDocCommentLines(out, dc->overview()); } // @@ -2036,8 +1895,8 @@ Slice::JavaVisitor::writeProxyDocComment(Output& out, const OperationPtr& p, con for(ParamDeclList::const_iterator i = paramList.begin(); i != paramList.end(); ++i) { const string name = (*i)->name(); - map<string, string>::const_iterator j = dc->params.find(name); - if(j != dc->params.end() && !j->second.empty()) + map<string, StringList>::const_iterator j = paramDocs.find(name); + if(j != paramDocs.end() && !j->second.empty()) { out << nl << " * @param " << fixKwd(j->first) << ' '; writeDocCommentLines(out, j->second); @@ -2065,10 +1924,10 @@ Slice::JavaVisitor::writeProxyDocComment(Output& out, const OperationPtr& p, con } else if(p->returnType()) { - if(!dc->returns.empty()) + if(!dc->returns().empty()) { out << nl << " * @return "; - writeDocCommentLines(out, dc->returns); + writeDocCommentLines(out, dc->returns()); } else if(async) { @@ -2079,8 +1938,8 @@ Slice::JavaVisitor::writeProxyDocComment(Output& out, const OperationPtr& p, con { assert(p->outParameters().size() == 1); const ParamDeclPtr param = p->outParameters().front(); - map<string, string>::const_iterator j = dc->params.find(param->name()); - if(j != dc->params.end() && !j->second.empty()) + map<string, StringList>::const_iterator j = paramDocs.find(param->name()); + if(j != paramDocs.end() && !j->second.empty()) { out << nl << " * @return "; writeDocCommentLines(out, j->second); @@ -2103,23 +1962,38 @@ Slice::JavaVisitor::writeProxyDocComment(Output& out, const OperationPtr& p, con // if(!async) { - for(map<string, string>::const_iterator i = dc->exceptions.begin(); i != dc->exceptions.end(); ++i) + map<string, StringList> exDocs = dc->exceptions(); + for(map<string, StringList>::const_iterator i = exDocs.begin(); i != exDocs.end(); ++i) { out << nl << " * @throws " << fixKwd(i->first) << ' '; writeDocCommentLines(out, i->second); } } - if(!dc->misc.empty()) + if(!dc->misc().empty()) { out << nl << " * "; - writeDocCommentLines(out, dc->misc); + writeDocCommentLines(out, dc->misc()); + } + + if(!dc->seeAlso().empty()) + { + out << nl << " *"; + StringList sa = dc->seeAlso(); + for(StringList::iterator p = sa.begin(); p != sa.end(); ++p) + { + out << nl << " * @see " << *p; + } } - if(!dc->deprecateReason.empty()) + if(!dc->deprecated().empty()) { out << nl << " * @deprecated "; - writeDocCommentLines(out, dc->deprecateReason); + writeDocCommentLines(out, dc->deprecated()); + } + else if(dc->isDeprecated()) + { + out << nl << " * @deprecated"; } out << nl << " **/"; @@ -2127,22 +2001,23 @@ Slice::JavaVisitor::writeProxyDocComment(Output& out, const OperationPtr& p, con void Slice::JavaVisitor::writeServantDocComment(Output& out, const OperationPtr& p, const string& package, - const DocCommentPtr& dc, bool async) + const CommentPtr& dc, bool async) { if(!dc) { return; } + map<string, StringList> paramDocs = dc->parameters(); const ParamDeclList paramList = p->inParameters(); const string currentParamName = getEscapedParamName(p, "current"); const string currentParam = " * @param " + currentParamName + " The Current object for the invocation."; out << nl << "/**"; - if(!dc->overview.empty()) + if(!dc->overview().empty()) { out << nl << " * "; - writeDocCommentLines(out, dc->overview); + writeDocCommentLines(out, dc->overview()); } // @@ -2151,8 +2026,8 @@ Slice::JavaVisitor::writeServantDocComment(Output& out, const OperationPtr& p, c for(ParamDeclList::const_iterator i = paramList.begin(); i != paramList.end(); ++i) { const string name = (*i)->name(); - map<string, string>::const_iterator j = dc->params.find(name); - if(j != dc->params.end() && !j->second.empty()) + map<string, StringList>::const_iterator j = paramDocs.find(name); + if(j != paramDocs.end() && !j->second.empty()) { out << nl << " * @param " << fixKwd(j->first) << ' '; writeDocCommentLines(out, j->second); @@ -2178,10 +2053,10 @@ Slice::JavaVisitor::writeServantDocComment(Output& out, const OperationPtr& p, c } else if(p->returnType()) { - if(!dc->returns.empty()) + if(!dc->returns().empty()) { out << nl << " * @return "; - writeDocCommentLines(out, dc->returns); + writeDocCommentLines(out, dc->returns()); } else if(async) { @@ -2192,8 +2067,8 @@ Slice::JavaVisitor::writeServantDocComment(Output& out, const OperationPtr& p, c { assert(p->outParameters().size() == 1); const ParamDeclPtr param = p->outParameters().front(); - map<string, string>::const_iterator j = dc->params.find(param->name()); - if(j != dc->params.end() && !j->second.empty()) + map<string, StringList>::const_iterator j = paramDocs.find(param->name()); + if(j != paramDocs.end() && !j->second.empty()) { out << nl << " * @return "; writeDocCommentLines(out, j->second); @@ -2217,23 +2092,38 @@ Slice::JavaVisitor::writeServantDocComment(Output& out, const OperationPtr& p, c } else { - for(map<string, string>::const_iterator i = dc->exceptions.begin(); i != dc->exceptions.end(); ++i) + map<string, StringList> exDocs = dc->exceptions(); + for(map<string, StringList>::const_iterator i = exDocs.begin(); i != exDocs.end(); ++i) { out << nl << " * @throws " << fixKwd(i->first) << ' '; writeDocCommentLines(out, i->second); } } - if(!dc->misc.empty()) + if(!dc->misc().empty()) { out << nl << " * "; - writeDocCommentLines(out, dc->misc); + writeDocCommentLines(out, dc->misc()); + } + + if(!dc->seeAlso().empty()) + { + out << nl << " *"; + StringList sa = dc->seeAlso(); + for(StringList::iterator p = sa.begin(); p != sa.end(); ++p) + { + out << nl << " * @see " << *p; + } } - if(!dc->deprecateReason.empty()) + if(!dc->deprecated().empty()) { out << nl << " * @deprecated "; - writeDocCommentLines(out, dc->deprecateReason); + writeDocCommentLines(out, dc->deprecated()); + } + else if(dc->isDeprecated()) + { + out << nl << " * @deprecated"; } out << nl << " **/"; @@ -2400,14 +2290,14 @@ Slice::Gen::TypesVisitor::visitClassDefStart(const ClassDefPtr& p) } } - DocCommentPtr dc = parseDocComment(p); + CommentPtr dc = p->parseComment(false); // // Slice interfaces map to Java interfaces. // out << sp; writeDocComment(out, dc); - if(dc && dc->deprecated) + if(dc && dc->isDeprecated()) { out << nl << "@Deprecated"; } @@ -2778,7 +2668,7 @@ Slice::Gen::TypesVisitor::visitOperation(const OperationPtr& p) Output& out = output(); - DocCommentPtr dc = parseDocComment(p); + CommentPtr dc = p->parseComment(false); // // Generate the "Result" type needed by operations that return multiple values. @@ -2809,7 +2699,7 @@ Slice::Gen::TypesVisitor::visitOperation(const OperationPtr& p) out << sp; writeProxyDocComment(out, p, package, dc, false, false); - if(dc && dc->deprecated) + if(dc && dc->isDeprecated()) { out << nl << "@Deprecated"; } @@ -2829,7 +2719,7 @@ Slice::Gen::TypesVisitor::visitOperation(const OperationPtr& p) { out << sp; writeProxyDocComment(out, p, package, dc, true, false); - if(dc && dc->deprecated) + if(dc && dc->isDeprecated()) { out << nl << "@Deprecated"; } @@ -2860,9 +2750,9 @@ Slice::Gen::TypesVisitor::visitExceptionStart(const ExceptionPtr& p) out << sp; - DocCommentPtr dc = parseDocComment(p); + CommentPtr dc = p->parseComment(false); writeDocComment(out, dc); - if(dc && dc->deprecated) + if(dc && dc->isDeprecated()) { out << nl << "@Deprecated"; } @@ -3313,9 +3203,9 @@ Slice::Gen::TypesVisitor::visitStructStart(const StructPtr& p) out << sp; - DocCommentPtr dc = parseDocComment(p); + CommentPtr dc = p->parseComment(false); writeDocComment(out, dc); - if(dc && dc->deprecated) + if(dc && dc->isDeprecated()) { out << nl << "@Deprecated"; } @@ -3696,9 +3586,9 @@ Slice::Gen::TypesVisitor::visitDataMember(const DataMemberPtr& p) out << sp; - DocCommentPtr dc = parseDocComment(p); + CommentPtr dc = p->parseComment(false); writeDocComment(out, dc); - if(dc && dc->deprecated) + if(dc && dc->isDeprecated()) { out << nl << "@Deprecated"; } @@ -3762,7 +3652,7 @@ Slice::Gen::TypesVisitor::visitDataMember(const DataMemberPtr& p) // out << sp; writeDocComment(out, dc); - if(dc && dc->deprecated) + if(dc && dc->isDeprecated()) { out << nl << "@Deprecated"; } @@ -3783,7 +3673,7 @@ Slice::Gen::TypesVisitor::visitDataMember(const DataMemberPtr& p) // out << sp; writeDocComment(out, dc); - if(dc && dc->deprecated) + if(dc && dc->isDeprecated()) { out << nl << "@Deprecated"; } @@ -3803,7 +3693,7 @@ Slice::Gen::TypesVisitor::visitDataMember(const DataMemberPtr& p) { out << sp; writeDocComment(out, dc); - if(dc && dc->deprecated) + if(dc && dc->isDeprecated()) { out << nl << "@Deprecated"; } @@ -3814,7 +3704,7 @@ Slice::Gen::TypesVisitor::visitDataMember(const DataMemberPtr& p) out << sp; writeDocComment(out, dc); - if(dc && dc->deprecated) + if(dc && dc->isDeprecated()) { out << nl << "@Deprecated"; } @@ -3828,7 +3718,7 @@ Slice::Gen::TypesVisitor::visitDataMember(const DataMemberPtr& p) out << sp; writeDocComment(out, dc); - if(dc && dc->deprecated) + if(dc && dc->isDeprecated()) { out << nl << "@Deprecated"; } @@ -3862,7 +3752,7 @@ Slice::Gen::TypesVisitor::visitDataMember(const DataMemberPtr& p) out << sp; writeDocComment(out, dc); - if(dc && dc->deprecated) + if(dc && dc->isDeprecated()) { out << nl << "@Deprecated"; } @@ -3923,7 +3813,7 @@ Slice::Gen::TypesVisitor::visitDataMember(const DataMemberPtr& p) return; } out << sp; - if(dc && dc->deprecated) + if(dc && dc->isDeprecated()) { out << nl << "@Deprecated"; } @@ -3962,7 +3852,7 @@ Slice::Gen::TypesVisitor::visitDataMember(const DataMemberPtr& p) // Indexed getter. // out << sp; - if(dc && dc->deprecated) + if(dc && dc->isDeprecated()) { out << nl << "@Deprecated"; } @@ -3982,7 +3872,7 @@ Slice::Gen::TypesVisitor::visitDataMember(const DataMemberPtr& p) // Indexed setter. // out << sp; - if(dc && dc->deprecated) + if(dc && dc->isDeprecated()) { out << nl << "@Deprecated"; } @@ -4016,9 +3906,9 @@ Slice::Gen::TypesVisitor::visitEnum(const EnumPtr& p) out << sp; - DocCommentPtr dc = parseDocComment(p); + CommentPtr dc = p->parseComment(false); writeDocComment(out, dc); - if(dc && dc->deprecated) + if(dc && dc->isDeprecated()) { out << nl << "@Deprecated"; } @@ -4036,9 +3926,9 @@ Slice::Gen::TypesVisitor::visitEnum(const EnumPtr& p) { out << ','; } - DocCommentPtr edc = parseDocComment(*en); + CommentPtr edc = (*en)->parseComment(false); writeDocComment(out, edc); - if(edc && edc->deprecated) + if(edc && edc->isDeprecated()) { out << nl << "@Deprecated"; } @@ -4168,9 +4058,9 @@ Slice::Gen::TypesVisitor::visitConst(const ConstPtr& p) out << sp; - DocCommentPtr dc = parseDocComment(p); + CommentPtr dc = p->parseComment(false); writeDocComment(out, dc); - if(dc && dc->deprecated) + if(dc && dc->isDeprecated()) { out << nl << "@Deprecated"; } @@ -4599,14 +4489,14 @@ Slice::Gen::ProxyVisitor::visitClassDefStart(const ClassDefPtr& p) bases.pop_front(); } - DocCommentPtr dc = parseDocComment(p); + CommentPtr dc = p->parseComment(false); // // Generate a Java interface as the user-visible type // out << sp; writeDocComment(out, dc); - if(dc && dc->deprecated) + if(dc && dc->isDeprecated()) { out << nl << "@Deprecated"; } @@ -4639,7 +4529,7 @@ Slice::Gen::ProxyVisitor::visitClassDefEnd(const ClassDefPtr& p) { Output& out = output(); - DocCommentPtr dc = parseDocComment(p); + CommentPtr dc = p->parseComment(false); const string package = getPackage(p); const string contextParam = "java.util.Map<String, String> context"; @@ -4650,7 +4540,8 @@ Slice::Gen::ProxyVisitor::visitClassDefEnd(const ClassDefPtr& p) "Raises a local exception if a communication error occurs.\n" "@param obj The untyped proxy.\n" "@return A proxy for this type, or null if the object does not support this type."); - out << nl << "static " << p->name() << "Prx checkedCast(" << getAbsolute("com.zeroc.Ice.ObjectPrx", package) << " obj)"; + out << nl << "static " << p->name() << "Prx checkedCast(" << getAbsolute("com.zeroc.Ice.ObjectPrx", package) + << " obj)"; out << sb; out << nl << "return " << getAbsolute("com.zeroc.Ice.ObjectPrx", package) << "._checkedCast(obj, ice_staticId(), " << p->name() << "Prx.class, _" << p->name() << "PrxI.class);"; @@ -4976,7 +4867,7 @@ Slice::Gen::ProxyVisitor::visitClassDefEnd(const ClassDefPtr& p) Output& outi = output(); outi << sp; - if(dc && dc->deprecated) + if(dc && dc->isDeprecated()) { outi << nl << "@Deprecated"; } @@ -5031,14 +4922,14 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p) const string contextParam = "java.util.Map<String, String> " + contextParamName; const string noExplicitContextArg = "com.zeroc.Ice.ObjectPrx.noExplicitContext"; - DocCommentPtr dc = parseDocComment(p); + CommentPtr dc = p->parseComment(false); // // Synchronous methods with required parameters. // out << sp; writeProxyDocComment(out, p, package, dc, false, false); - if(dc && dc->deprecated) + if(dc && dc->isDeprecated()) { out << nl << "@Deprecated"; } @@ -5055,7 +4946,7 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p) out << sp; writeProxyDocComment(out, p, package, dc, false, true); - if(dc && dc->deprecated) + if(dc && dc->isDeprecated()) { out << nl << "@Deprecated"; } @@ -5104,7 +4995,7 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p) { out << sp; writeProxyDocComment(out, p, package, dc, false, false); - if(dc && dc->deprecated) + if(dc && dc->isDeprecated()) { out << nl << "@Deprecated"; } @@ -5121,7 +5012,7 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p) out << sp; writeProxyDocComment(out, p, package, dc, false, true); - if(dc && dc->deprecated) + if(dc && dc->isDeprecated()) { out << nl << "@Deprecated"; } @@ -5173,19 +5064,20 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p) const string future = getFutureType(p, package); - if(dc && dc->deprecated) + if(dc && dc->isDeprecated()) { out << nl << "@Deprecated"; } out << nl << "default " << future << ' ' << p->name() << "Async" << spar << params << epar; out << sb; - out << nl << "return _iceI_" << p->name() << "Async" << spar << args << noExplicitContextArg << "false" << epar << ';'; + out << nl << "return _iceI_" << p->name() << "Async" << spar << args << noExplicitContextArg << "false" << epar + << ';'; out << eb; out << sp; writeProxyDocComment(out, p, package, dc, true, true); - if(dc && dc->deprecated) + if(dc && dc->isDeprecated()) { out << nl << "@Deprecated"; } @@ -5261,7 +5153,7 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p) const string future = getFutureType(p, package); - if(dc && dc->deprecated) + if(dc && dc->isDeprecated()) { out << nl << "@Deprecated"; } @@ -5274,7 +5166,7 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p) out << sp; writeProxyDocComment(out, p, package, dc, true, true); - if(dc && dc->deprecated) + if(dc && dc->isDeprecated()) { out << nl << "@Deprecated"; } @@ -5349,9 +5241,9 @@ Slice::Gen::DispatcherVisitor::visitClassDefStart(const ClassDefPtr& p) Output& out = output(); out << sp; - DocCommentPtr dc = parseDocComment(p); + CommentPtr dc = p->parseComment(false); writeDocComment(out, dc); - if(dc && dc->deprecated) + if(dc && dc->isDeprecated()) { out << nl << "@Deprecated"; } diff --git a/cpp/src/slice2java/Gen.h b/cpp/src/slice2java/Gen.h index 1850a3b0dfc..262c90e65b0 100644 --- a/cpp/src/slice2java/Gen.h +++ b/cpp/src/slice2java/Gen.h @@ -29,22 +29,10 @@ protected: enum ParamDir { InParam, OutParam }; - struct DocComment : public IceUtil::SimpleShared - { - std::string overview; - std::map<std::string, std::string> params; - std::map<std::string, std::string> exceptions; - std::string returns; - bool deprecated; - std::string deprecateReason; - std::string misc; - }; - typedef IceUtil::Handle<DocComment> DocCommentPtr; - std::string getResultType(const OperationPtr&, const std::string&, bool, bool); - void writeResultType(::IceUtilInternal::Output&, const OperationPtr&, const std::string&, const DocCommentPtr&); + void writeResultType(::IceUtilInternal::Output&, const OperationPtr&, const std::string&, const CommentPtr&); void writeMarshaledResultType(::IceUtilInternal::Output&, const OperationPtr&, const std::string&, - const DocCommentPtr&); + const CommentPtr&); void allocatePatcher(::IceUtilInternal::Output&, const TypePtr&, const std::string&, const std::string&, bool); std::string getPatcher(const TypePtr&, const std::string&, const std::string&); @@ -112,14 +100,14 @@ protected: // Handle doc comments. // static StringList splitComment(const ContainedPtr&); - DocCommentPtr parseDocComment(const ContainedPtr&); + void writeDocCommentLines(::IceUtilInternal::Output&, const StringList&); void writeDocCommentLines(::IceUtilInternal::Output&, const std::string&); - void writeDocComment(::IceUtilInternal::Output&, const DocCommentPtr&); + void writeDocComment(::IceUtilInternal::Output&, const CommentPtr&); void writeDocComment(::IceUtilInternal::Output&, const std::string&); - void writeProxyDocComment(::IceUtilInternal::Output&, const OperationPtr&, const std::string&, const DocCommentPtr&, + void writeProxyDocComment(::IceUtilInternal::Output&, const OperationPtr&, const std::string&, const CommentPtr&, bool, bool); void writeServantDocComment(::IceUtilInternal::Output&, const OperationPtr&, const std::string&, - const DocCommentPtr&, bool); + const CommentPtr&, bool); }; class Gen : private ::IceUtil::noncopyable diff --git a/cpp/test/Slice/errorDetection/IllegalIdentifier.err b/cpp/test/Slice/errorDetection/IllegalIdentifier.err index d80b068b522..8848faca201 100644 --- a/cpp/test/Slice/errorDetection/IllegalIdentifier.err +++ b/cpp/test/Slice/errorDetection/IllegalIdentifier.err @@ -1,5 +1,8 @@ +IllegalIdentifier.ice:2: illegal input character: '\357' +IllegalIdentifier.ice:2: syntax error +IllegalIdentifier.ice:2: illegal input character: '\273' +IllegalIdentifier.ice:2: illegal input character: '\277' IllegalIdentifier.ice:14: illegal input character: '\357' -IllegalIdentifier.ice:14: syntax error IllegalIdentifier.ice:14: illegal input character: '\273' IllegalIdentifier.ice:14: illegal input character: '\277' IllegalIdentifier.ice:22: illegal input character: '\305' diff --git a/doxygen/.gitignore b/doxygen/.gitignore new file mode 100644 index 00000000000..9f31fac82fa --- /dev/null +++ b/doxygen/.gitignore @@ -0,0 +1,2 @@ +html +slice.tag diff --git a/doxygen/config b/doxygen/config new file mode 100644 index 00000000000..990201e81c7 --- /dev/null +++ b/doxygen/config @@ -0,0 +1,2490 @@ +# Doxyfile 1.8.14 + +# This file describes the settings to be used by the documentation system +# doxygen (www.doxygen.org) for a project. +# +# All text after a double hash (##) is considered a comment and is placed in +# front of the TAG it is preceding. +# +# All text after a single hash (#) is considered a comment and will be ignored. +# The format is: +# TAG = value [value, ...] +# For lists, items can also be appended using: +# TAG += value [value, ...] +# Values that contain spaces should be placed between quotes (\" \"). + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- + +# This tag specifies the encoding used for all characters in the config file +# that follow. The default is UTF-8 which is also the encoding used for all text +# before the first occurrence of this tag. Doxygen uses libiconv (or the iconv +# built into libc) for the transcoding. See +# https://www.gnu.org/software/libiconv/ for the list of possible encodings. +# The default value is: UTF-8. + +DOXYFILE_ENCODING = UTF-8 + +# The PROJECT_NAME tag is a single word (or a sequence of words surrounded by +# double-quotes, unless you are using Doxywizard) that should identify the +# project for which the documentation is generated. This name is used in the +# title of most generated pages and in a few other places. +# The default value is: My Project. + +PROJECT_NAME = "Ice Slice API Reference" + +# The PROJECT_NUMBER tag can be used to enter a project or revision number. This +# could be handy for archiving the generated documentation or if some version +# control system is used. + +PROJECT_NUMBER = + +# Using the PROJECT_BRIEF tag one can provide an optional one line description +# for a project that appears at the top of each page and should give viewer a +# quick idea about the purpose of the project. Keep the description short. + +PROJECT_BRIEF = + +# With the PROJECT_LOGO tag one can specify a logo or an icon that is included +# in the documentation. The maximum height of the logo should not exceed 55 +# pixels and the maximum width should not exceed 200 pixels. Doxygen will copy +# the logo to the output directory. + +PROJECT_LOGO = + +# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path +# into which the generated documentation will be written. If a relative path is +# entered, it will be relative to the location where doxygen was started. If +# left blank the current directory will be used. + +OUTPUT_DIRECTORY = + +# If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- +# directories (in 2 levels) under the output directory of each output format and +# will distribute the generated files over these directories. Enabling this +# option can be useful when feeding doxygen a huge amount of source files, where +# putting all generated files in the same directory would otherwise causes +# performance problems for the file system. +# The default value is: NO. + +CREATE_SUBDIRS = NO + +# If the ALLOW_UNICODE_NAMES tag is set to YES, doxygen will allow non-ASCII +# characters to appear in the names of generated files. If set to NO, non-ASCII +# characters will be escaped, for example _xE3_x81_x84 will be used for Unicode +# U+3044. +# The default value is: NO. + +ALLOW_UNICODE_NAMES = NO + +# The OUTPUT_LANGUAGE tag is used to specify the language in which all +# documentation generated by doxygen is written. Doxygen will use this +# information to generate all constant output in the proper language. +# Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Catalan, Chinese, +# Chinese-Traditional, Croatian, Czech, Danish, Dutch, English (United States), +# Esperanto, Farsi (Persian), Finnish, French, German, Greek, Hungarian, +# Indonesian, Italian, Japanese, Japanese-en (Japanese with English messages), +# Korean, Korean-en (Korean with English messages), Latvian, Lithuanian, +# Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese, Romanian, Russian, +# Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish, Swedish, Turkish, +# Ukrainian and Vietnamese. +# The default value is: English. + +OUTPUT_LANGUAGE = English + +# If the BRIEF_MEMBER_DESC tag is set to YES, doxygen will include brief member +# descriptions after the members that are listed in the file and class +# documentation (similar to Javadoc). Set to NO to disable this. +# The default value is: YES. + +BRIEF_MEMBER_DESC = YES + +# If the REPEAT_BRIEF tag is set to YES, doxygen will prepend the brief +# description of a member or function before the detailed description +# +# Note: If both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the +# brief descriptions will be completely suppressed. +# The default value is: YES. + +REPEAT_BRIEF = YES + +# This tag implements a quasi-intelligent brief description abbreviator that is +# used to form the text in various listings. Each string in this list, if found +# as the leading text of the brief description, will be stripped from the text +# and the result, after processing the whole list, is used as the annotated +# text. Otherwise, the brief description is used as-is. If left blank, the +# following values are used ($name is automatically replaced with the name of +# the entity):The $name class, The $name widget, The $name file, is, provides, +# specifies, contains, represents, a, an and the. + +ABBREVIATE_BRIEF = "The $name class" \ + "The $name widget" \ + "The $name file" \ + is \ + provides \ + specifies \ + contains \ + represents \ + a \ + an \ + the + +# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then +# doxygen will generate a detailed section even if there is only a brief +# description. +# The default value is: NO. + +ALWAYS_DETAILED_SEC = NO + +# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all +# inherited members of a class in the documentation of that class as if those +# members were ordinary class members. Constructors, destructors and assignment +# operators of the base classes will not be shown. +# The default value is: NO. + +INLINE_INHERITED_MEMB = NO + +# If the FULL_PATH_NAMES tag is set to YES, doxygen will prepend the full path +# before files name in the file list and in the header files. If set to NO the +# shortest path that makes the file name unique will be used +# The default value is: YES. + +FULL_PATH_NAMES = YES + +# The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path. +# Stripping is only done if one of the specified strings matches the left-hand +# part of the path. The tag can be used to show relative paths in the file list. +# If left blank the directory from which doxygen is run is used as the path to +# strip. +# +# Note that you can specify absolute paths here, but also relative paths, which +# will be relative from the directory where doxygen is started. +# This tag requires that the tag FULL_PATH_NAMES is set to YES. + +STRIP_FROM_PATH = ../slice/ + +# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the +# path mentioned in the documentation of a class, which tells the reader which +# header file to include in order to use a class. If left blank only the name of +# the header file containing the class definition is used. Otherwise one should +# specify the list of include paths that are normally passed to the compiler +# using the -I flag. + +STRIP_FROM_INC_PATH = + +# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but +# less readable) file names. This can be useful is your file systems doesn't +# support long names like on DOS, Mac, or CD-ROM. +# The default value is: NO. + +SHORT_NAMES = NO + +# If the JAVADOC_AUTOBRIEF tag is set to YES then doxygen will interpret the +# first line (until the first dot) of a Javadoc-style comment as the brief +# description. If set to NO, the Javadoc-style will behave just like regular Qt- +# style comments (thus requiring an explicit @brief command for a brief +# description.) +# The default value is: NO. + +JAVADOC_AUTOBRIEF = YES + +# If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first +# line (until the first dot) of a Qt-style comment as the brief description. If +# set to NO, the Qt-style will behave just like regular Qt-style comments (thus +# requiring an explicit \brief command for a brief description.) +# The default value is: NO. + +QT_AUTOBRIEF = NO + +# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make doxygen treat a +# multi-line C++ special comment block (i.e. a block of //! or /// comments) as +# a brief description. This used to be the default behavior. The new default is +# to treat a multi-line C++ comment block as a detailed description. Set this +# tag to YES if you prefer the old behavior instead. +# +# Note that setting this tag to YES also means that rational rose comments are +# not recognized any more. +# The default value is: NO. + +MULTILINE_CPP_IS_BRIEF = NO + +# If the INHERIT_DOCS tag is set to YES then an undocumented member inherits the +# documentation from any documented member that it re-implements. +# The default value is: YES. + +INHERIT_DOCS = YES + +# If the SEPARATE_MEMBER_PAGES tag is set to YES then doxygen will produce a new +# page for each member. If set to NO, the documentation of a member will be part +# of the file/class/namespace that contains it. +# The default value is: NO. + +SEPARATE_MEMBER_PAGES = NO + +# The TAB_SIZE tag can be used to set the number of spaces in a tab. Doxygen +# uses this value to replace tabs by spaces in code fragments. +# Minimum value: 1, maximum value: 16, default value: 4. + +TAB_SIZE = 4 + +# This tag can be used to specify a number of aliases that act as commands in +# the documentation. An alias has the form: +# name=value +# For example adding +# "sideeffect=@par Side Effects:\n" +# will allow you to put the command \sideeffect (or @sideeffect) in the +# documentation, which will result in a user-defined paragraph with heading +# "Side Effects:". You can put \n's in the value part of an alias to insert +# newlines. + +ALIASES = + +# This tag can be used to specify a number of word-keyword mappings (TCL only). +# A mapping has the form "name=value". For example adding "class=itcl::class" +# will allow you to use the command class in the itcl::class meaning. + +TCL_SUBST = + +# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources +# only. Doxygen will then generate output that is more tailored for C. For +# instance, some of the names that are used will be different. The list of all +# members will be omitted, etc. +# The default value is: NO. + +OPTIMIZE_OUTPUT_FOR_C = NO + +# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or +# Python sources only. Doxygen will then generate output that is more tailored +# for that language. For instance, namespaces will be presented as packages, +# qualified scopes will look different, etc. +# The default value is: NO. + +OPTIMIZE_OUTPUT_JAVA = NO + +# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran +# sources. Doxygen will then generate output that is tailored for Fortran. +# The default value is: NO. + +OPTIMIZE_FOR_FORTRAN = NO + +# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL +# sources. Doxygen will then generate output that is tailored for VHDL. +# The default value is: NO. + +OPTIMIZE_OUTPUT_VHDL = NO + +# Set the OPTIMIZE_OUTPUT_SLICE tag to YES if your project consists of Slice +# sources only. Doxygen will then generate output that is more tailored for that +# language. For instance, namespaces will be presented as modules, types will be +# separated into more groups, etc. +# The default value is: NO. + +OPTIMIZE_OUTPUT_SLICE = YES + +# Doxygen selects the parser to use depending on the extension of the files it +# parses. With this tag you can assign which parser to use for a given +# extension. Doxygen has a built-in mapping, but you can override or extend it +# using this tag. The format is ext=language, where ext is a file extension, and +# language is one of the parsers supported by doxygen: IDL, Java, Javascript, +# C#, C, C++, D, PHP, Objective-C, Python, Slice, Fortran (fixed format Fortran: +# FortranFixed, free formatted Fortran: FortranFree, unknown formatted Fortran: +# Fortran. In the later case the parser tries to guess whether the code is fixed +# or free formatted code, this is the default for Fortran type files), VHDL. For +# instance to make doxygen treat .inc files as Fortran files (default is PHP), +# and .f files as C (default is Fortran), use: inc=Fortran f=C. +# +# Note: For files without extension you can use no_extension as a placeholder. +# +# Note that for custom extensions you also need to set FILE_PATTERNS otherwise +# the files are not read by doxygen. + +EXTENSION_MAPPING = + +# If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments +# according to the Markdown format, which allows for more readable +# documentation. See http://daringfireball.net/projects/markdown/ for details. +# The output of markdown processing is further processed by doxygen, so you can +# mix doxygen, HTML, and XML commands with Markdown formatting. Disable only in +# case of backward compatibilities issues. +# The default value is: YES. + +MARKDOWN_SUPPORT = NO + +# When the TOC_INCLUDE_HEADINGS tag is set to a non-zero value, all headings up +# to that level are automatically included in the table of contents, even if +# they do not have an id attribute. +# Note: This feature currently applies only to Markdown headings. +# Minimum value: 0, maximum value: 99, default value: 0. +# This tag requires that the tag MARKDOWN_SUPPORT is set to YES. + +TOC_INCLUDE_HEADINGS = 0 + +# When enabled doxygen tries to link words that correspond to documented +# classes, or namespaces to their corresponding documentation. Such a link can +# be prevented in individual cases by putting a % sign in front of the word or +# globally by setting AUTOLINK_SUPPORT to NO. +# The default value is: YES. + +AUTOLINK_SUPPORT = YES + +# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want +# to include (a tag file for) the STL sources as input, then you should set this +# tag to YES in order to let doxygen match functions declarations and +# definitions whose arguments contain STL classes (e.g. func(std::string); +# versus func(std::string) {}). This also make the inheritance and collaboration +# diagrams that involve STL classes more complete and accurate. +# The default value is: NO. + +BUILTIN_STL_SUPPORT = NO + +# If you use Microsoft's C++/CLI language, you should set this option to YES to +# enable parsing support. +# The default value is: NO. + +CPP_CLI_SUPPORT = NO + +# Set the SIP_SUPPORT tag to YES if your project consists of sip (see: +# https://www.riverbankcomputing.com/software/sip/intro) sources only. Doxygen +# will parse them like normal C++ but will assume all classes use public instead +# of private inheritance when no explicit protection keyword is present. +# The default value is: NO. + +SIP_SUPPORT = NO + +# For Microsoft's IDL there are propget and propput attributes to indicate +# getter and setter methods for a property. Setting this option to YES will make +# doxygen to replace the get and set methods by a property in the documentation. +# This will only work if the methods are indeed getting or setting a simple +# type. If this is not the case, or you want to show the methods anyway, you +# should set this option to NO. +# The default value is: YES. + +IDL_PROPERTY_SUPPORT = YES + +# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC +# tag is set to YES then doxygen will reuse the documentation of the first +# member in the group (if any) for the other members of the group. By default +# all members of a group must be documented explicitly. +# The default value is: NO. + +DISTRIBUTE_GROUP_DOC = NO + +# If one adds a struct or class to a group and this option is enabled, then also +# any nested class or struct is added to the same group. By default this option +# is disabled and one has to add nested compounds explicitly via \ingroup. +# The default value is: NO. + +GROUP_NESTED_COMPOUNDS = NO + +# Set the SUBGROUPING tag to YES to allow class member groups of the same type +# (for instance a group of public functions) to be put as a subgroup of that +# type (e.g. under the Public Functions section). Set it to NO to prevent +# subgrouping. Alternatively, this can be done per class using the +# \nosubgrouping command. +# The default value is: YES. + +SUBGROUPING = YES + +# When the INLINE_GROUPED_CLASSES tag is set to YES, classes, structs and unions +# are shown inside the group in which they are included (e.g. using \ingroup) +# instead of on a separate page (for HTML and Man pages) or section (for LaTeX +# and RTF). +# +# Note that this feature does not work in combination with +# SEPARATE_MEMBER_PAGES. +# The default value is: NO. + +INLINE_GROUPED_CLASSES = NO + +# When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and unions +# with only public data fields or simple typedef fields will be shown inline in +# the documentation of the scope in which they are defined (i.e. file, +# namespace, or group documentation), provided this scope is documented. If set +# to NO, structs, classes, and unions are shown on a separate page (for HTML and +# Man pages) or section (for LaTeX and RTF). +# The default value is: NO. + +INLINE_SIMPLE_STRUCTS = NO + +# When TYPEDEF_HIDES_STRUCT tag is enabled, a typedef of a struct, union, or +# enum is documented as struct, union, or enum with the name of the typedef. So +# typedef struct TypeS {} TypeT, will appear in the documentation as a struct +# with name TypeT. When disabled the typedef will appear as a member of a file, +# namespace, or class. And the struct will be named TypeS. This can typically be +# useful for C code in case the coding convention dictates that all compound +# types are typedef'ed and only the typedef is referenced, never the tag name. +# The default value is: NO. + +TYPEDEF_HIDES_STRUCT = NO + +# The size of the symbol lookup cache can be set using LOOKUP_CACHE_SIZE. This +# cache is used to resolve symbols given their name and scope. Since this can be +# an expensive process and often the same symbol appears multiple times in the +# code, doxygen keeps a cache of pre-resolved symbols. If the cache is too small +# doxygen will become slower. If the cache is too large, memory is wasted. The +# cache size is given by this formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range +# is 0..9, the default is 0, corresponding to a cache size of 2^16=65536 +# symbols. At the end of a run doxygen will report the cache usage and suggest +# the optimal cache size from a speed point of view. +# Minimum value: 0, maximum value: 9, default value: 0. + +LOOKUP_CACHE_SIZE = 0 + +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- + +# If the EXTRACT_ALL tag is set to YES, doxygen will assume all entities in +# documentation are documented, even if no documentation was available. Private +# class members and static file members will be hidden unless the +# EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES. +# Note: This will also disable the warnings about undocumented members that are +# normally produced when WARNINGS is set to YES. +# The default value is: NO. + +EXTRACT_ALL = YES + +# If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will +# be included in the documentation. +# The default value is: NO. + +EXTRACT_PRIVATE = NO + +# If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal +# scope will be included in the documentation. +# The default value is: NO. + +EXTRACT_PACKAGE = NO + +# If the EXTRACT_STATIC tag is set to YES, all static members of a file will be +# included in the documentation. +# The default value is: NO. + +EXTRACT_STATIC = NO + +# If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined +# locally in source files will be included in the documentation. If set to NO, +# only classes defined in header files are included. Does not have any effect +# for Java sources. +# The default value is: YES. + +EXTRACT_LOCAL_CLASSES = YES + +# This flag is only useful for Objective-C code. If set to YES, local methods, +# which are defined in the implementation section but not in the interface are +# included in the documentation. If set to NO, only methods in the interface are +# included. +# The default value is: NO. + +EXTRACT_LOCAL_METHODS = NO + +# If this flag is set to YES, the members of anonymous namespaces will be +# extracted and appear in the documentation as a namespace called +# 'anonymous_namespace{file}', where file will be replaced with the base name of +# the file that contains the anonymous namespace. By default anonymous namespace +# are hidden. +# The default value is: NO. + +EXTRACT_ANON_NSPACES = NO + +# If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all +# undocumented members inside documented classes or files. If set to NO these +# members will be included in the various overviews, but no documentation +# section is generated. This option has no effect if EXTRACT_ALL is enabled. +# The default value is: NO. + +HIDE_UNDOC_MEMBERS = NO + +# If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all +# undocumented classes that are normally visible in the class hierarchy. If set +# to NO, these classes will be included in the various overviews. This option +# has no effect if EXTRACT_ALL is enabled. +# The default value is: NO. + +HIDE_UNDOC_CLASSES = NO + +# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend +# (class|struct|union) declarations. If set to NO, these declarations will be +# included in the documentation. +# The default value is: NO. + +HIDE_FRIEND_COMPOUNDS = NO + +# If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any +# documentation blocks found inside the body of a function. If set to NO, these +# blocks will be appended to the function's detailed documentation block. +# The default value is: NO. + +HIDE_IN_BODY_DOCS = NO + +# The INTERNAL_DOCS tag determines if documentation that is typed after a +# \internal command is included. If the tag is set to NO then the documentation +# will be excluded. Set it to YES to include the internal documentation. +# The default value is: NO. + +INTERNAL_DOCS = NO + +# If the CASE_SENSE_NAMES tag is set to NO then doxygen will only generate file +# names in lower-case letters. If set to YES, upper-case letters are also +# allowed. This is useful if you have classes or files whose names only differ +# in case and if your file system supports case sensitive file names. Windows +# and Mac users are advised to set this option to NO. +# The default value is: system dependent. + +CASE_SENSE_NAMES = YES + +# If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with +# their full class and namespace scopes in the documentation. If set to YES, the +# scope will be hidden. +# The default value is: NO. + +HIDE_SCOPE_NAMES = NO + +# If the HIDE_COMPOUND_REFERENCE tag is set to NO (default) then doxygen will +# append additional text to a page's title, such as Class Reference. If set to +# YES the compound reference will be hidden. +# The default value is: NO. + +HIDE_COMPOUND_REFERENCE= NO + +# If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of +# the files that are included by a file in the documentation of that file. +# The default value is: YES. + +SHOW_INCLUDE_FILES = YES + +# If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each +# grouped member an include statement to the documentation, telling the reader +# which file to include in order to use the member. +# The default value is: NO. + +SHOW_GROUPED_MEMB_INC = NO + +# If the FORCE_LOCAL_INCLUDES tag is set to YES then doxygen will list include +# files with double quotes in the documentation rather than with sharp brackets. +# The default value is: NO. + +FORCE_LOCAL_INCLUDES = NO + +# If the INLINE_INFO tag is set to YES then a tag [inline] is inserted in the +# documentation for inline members. +# The default value is: YES. + +INLINE_INFO = YES + +# If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the +# (detailed) documentation of file and class members alphabetically by member +# name. If set to NO, the members will appear in declaration order. +# The default value is: YES. + +SORT_MEMBER_DOCS = YES + +# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief +# descriptions of file, namespace and class members alphabetically by member +# name. If set to NO, the members will appear in declaration order. Note that +# this will also influence the order of the classes in the class list. +# The default value is: NO. + +SORT_BRIEF_DOCS = YES + +# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the +# (brief and detailed) documentation of class members so that constructors and +# destructors are listed first. If set to NO the constructors will appear in the +# respective orders defined by SORT_BRIEF_DOCS and SORT_MEMBER_DOCS. +# Note: If SORT_BRIEF_DOCS is set to NO this option is ignored for sorting brief +# member documentation. +# Note: If SORT_MEMBER_DOCS is set to NO this option is ignored for sorting +# detailed member documentation. +# The default value is: NO. + +SORT_MEMBERS_CTORS_1ST = NO + +# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy +# of group names into alphabetical order. If set to NO the group names will +# appear in their defined order. +# The default value is: NO. + +SORT_GROUP_NAMES = NO + +# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by +# fully-qualified names, including namespaces. If set to NO, the class list will +# be sorted only by class name, not including the namespace part. +# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. +# Note: This option applies only to the class list, not to the alphabetical +# list. +# The default value is: NO. + +SORT_BY_SCOPE_NAME = NO + +# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to do proper +# type resolution of all parameters of a function it will reject a match between +# the prototype and the implementation of a member function even if there is +# only one candidate or it is obvious which candidate to choose by doing a +# simple string match. By disabling STRICT_PROTO_MATCHING doxygen will still +# accept a match between prototype and implementation in such cases. +# The default value is: NO. + +STRICT_PROTO_MATCHING = NO + +# The GENERATE_TODOLIST tag can be used to enable (YES) or disable (NO) the todo +# list. This list is created by putting \todo commands in the documentation. +# The default value is: YES. + +GENERATE_TODOLIST = YES + +# The GENERATE_TESTLIST tag can be used to enable (YES) or disable (NO) the test +# list. This list is created by putting \test commands in the documentation. +# The default value is: YES. + +GENERATE_TESTLIST = YES + +# The GENERATE_BUGLIST tag can be used to enable (YES) or disable (NO) the bug +# list. This list is created by putting \bug commands in the documentation. +# The default value is: YES. + +GENERATE_BUGLIST = YES + +# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or disable (NO) +# the deprecated list. This list is created by putting \deprecated commands in +# the documentation. +# The default value is: YES. + +GENERATE_DEPRECATEDLIST= YES + +# The ENABLED_SECTIONS tag can be used to enable conditional documentation +# sections, marked by \if <section_label> ... \endif and \cond <section_label> +# ... \endcond blocks. + +ENABLED_SECTIONS = + +# The MAX_INITIALIZER_LINES tag determines the maximum number of lines that the +# initial value of a variable or macro / define can have for it to appear in the +# documentation. If the initializer consists of more lines than specified here +# it will be hidden. Use a value of 0 to hide initializers completely. The +# appearance of the value of individual variables and macros / defines can be +# controlled using \showinitializer or \hideinitializer command in the +# documentation regardless of this setting. +# Minimum value: 0, maximum value: 10000, default value: 30. + +MAX_INITIALIZER_LINES = 30 + +# Set the SHOW_USED_FILES tag to NO to disable the list of files generated at +# the bottom of the documentation of classes and structs. If set to YES, the +# list will mention the files that were used to generate the documentation. +# The default value is: YES. + +SHOW_USED_FILES = YES + +# Set the SHOW_FILES tag to NO to disable the generation of the Files page. This +# will remove the Files entry from the Quick Index and from the Folder Tree View +# (if specified). +# The default value is: YES. + +SHOW_FILES = YES + +# Set the SHOW_NAMESPACES tag to NO to disable the generation of the Namespaces +# page. This will remove the Namespaces entry from the Quick Index and from the +# Folder Tree View (if specified). +# The default value is: YES. + +SHOW_NAMESPACES = YES + +# The FILE_VERSION_FILTER tag can be used to specify a program or script that +# doxygen should invoke to get the current version for each file (typically from +# the version control system). Doxygen will invoke the program by executing (via +# popen()) the command command input-file, where command is the value of the +# FILE_VERSION_FILTER tag, and input-file is the name of an input file provided +# by doxygen. Whatever the program writes to standard output is used as the file +# version. For an example see the documentation. + +FILE_VERSION_FILTER = + +# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed +# by doxygen. The layout file controls the global structure of the generated +# output files in an output format independent way. To create the layout file +# that represents doxygen's defaults, run doxygen with the -l option. You can +# optionally specify a file name after the option, if omitted DoxygenLayout.xml +# will be used as the name of the layout file. +# +# Note that if you run doxygen from a directory containing a file called +# DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE +# tag is left empty. + +LAYOUT_FILE = + +# The CITE_BIB_FILES tag can be used to specify one or more bib files containing +# the reference definitions. This must be a list of .bib files. The .bib +# extension is automatically appended if omitted. This requires the bibtex tool +# to be installed. See also https://en.wikipedia.org/wiki/BibTeX for more info. +# For LaTeX the style of the bibliography can be controlled using +# LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the +# search path. See also \cite for info how to create references. + +CITE_BIB_FILES = + +#--------------------------------------------------------------------------- +# Configuration options related to warning and progress messages +#--------------------------------------------------------------------------- + +# The QUIET tag can be used to turn on/off the messages that are generated to +# standard output by doxygen. If QUIET is set to YES this implies that the +# messages are off. +# The default value is: NO. + +QUIET = NO + +# The WARNINGS tag can be used to turn on/off the warning messages that are +# generated to standard error (stderr) by doxygen. If WARNINGS is set to YES +# this implies that the warnings are on. +# +# Tip: Turn warnings on while writing the documentation. +# The default value is: YES. + +WARNINGS = YES + +# If the WARN_IF_UNDOCUMENTED tag is set to YES then doxygen will generate +# warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag +# will automatically be disabled. +# The default value is: YES. + +WARN_IF_UNDOCUMENTED = YES + +# If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for +# potential errors in the documentation, such as not documenting some parameters +# in a documented function, or documenting parameters that don't exist or using +# markup commands wrongly. +# The default value is: YES. + +WARN_IF_DOC_ERROR = YES + +# This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that +# are documented, but have no documentation for their parameters or return +# value. If set to NO, doxygen will only warn about wrong or incomplete +# parameter documentation, but not about the absence of documentation. +# The default value is: NO. + +WARN_NO_PARAMDOC = NO + +# If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when +# a warning is encountered. +# The default value is: NO. + +WARN_AS_ERROR = NO + +# The WARN_FORMAT tag determines the format of the warning messages that doxygen +# can produce. The string should contain the $file, $line, and $text tags, which +# will be replaced by the file and line number from which the warning originated +# and the warning text. Optionally the format may contain $version, which will +# be replaced by the version of the file (if it could be obtained via +# FILE_VERSION_FILTER) +# The default value is: $file:$line: $text. + +WARN_FORMAT = "$file:$line: $text" + +# The WARN_LOGFILE tag can be used to specify a file to which warning and error +# messages should be written. If left blank the output is written to standard +# error (stderr). + +WARN_LOGFILE = + +#--------------------------------------------------------------------------- +# Configuration options related to the input files +#--------------------------------------------------------------------------- + +# The INPUT tag is used to specify the files and/or directories that contain +# documented source files. You may enter file names like myfile.cpp or +# directories like /usr/src/myproject. Separate the files or directories with +# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING +# Note: If this tag is empty the current directory is searched. + +INPUT = ../slice mainpage.md + +# This tag can be used to specify the character encoding of the source files +# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses +# libiconv (or the iconv built into libc) for the transcoding. See the libiconv +# documentation (see: https://www.gnu.org/software/libiconv/) for the list of +# possible encodings. +# The default value is: UTF-8. + +INPUT_ENCODING = UTF-8 + +# If the value of the INPUT tag contains directories, you can use the +# FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp and +# *.h) to filter out the source-files in the directories. +# +# Note that for custom extensions or not directly supported extensions you also +# need to set EXTENSION_MAPPING for the extension otherwise the files are not +# read by doxygen. +# +# If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp, +# *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, +# *.hh, *.hxx, *.hpp, *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc, +# *.m, *.markdown, *.md, *.mm, *.dox, *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, +# *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf, *.qsf and *.ice. + +FILE_PATTERNS = *.c \ + *.cc \ + *.cxx \ + *.cpp \ + *.c++ \ + *.java \ + *.ii \ + *.ixx \ + *.ipp \ + *.i++ \ + *.inl \ + *.idl \ + *.ddl \ + *.odl \ + *.h \ + *.hh \ + *.hxx \ + *.hpp \ + *.h++ \ + *.cs \ + *.d \ + *.php \ + *.php4 \ + *.php5 \ + *.phtml \ + *.inc \ + *.m \ + *.markdown \ + *.md \ + *.mm \ + *.dox \ + *.py \ + *.pyw \ + *.f90 \ + *.f95 \ + *.f03 \ + *.f08 \ + *.f \ + *.for \ + *.tcl \ + *.vhd \ + *.vhdl \ + *.ucf \ + *.qsf \ + *.ice + +# The RECURSIVE tag can be used to specify whether or not subdirectories should +# be searched for input files as well. +# The default value is: NO. + +RECURSIVE = YES + +# The EXCLUDE tag can be used to specify files and/or directories that should be +# excluded from the INPUT source files. This way you can easily exclude a +# subdirectory from a directory tree whose root is specified with the INPUT tag. +# +# Note that relative paths are relative to the directory from which doxygen is +# run. + +EXCLUDE = + +# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or +# directories that are symbolic links (a Unix file system feature) are excluded +# from the input. +# The default value is: NO. + +EXCLUDE_SYMLINKS = NO + +# If the value of the INPUT tag contains directories, you can use the +# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude +# certain files from those directories. +# +# Note that the wildcards are matched against the file with absolute path, so to +# exclude all test directories for example use the pattern */test/* + +EXCLUDE_PATTERNS = + +# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names +# (namespaces, classes, functions, etc.) that should be excluded from the +# output. The symbol name can be a fully qualified name, a word, or if the +# wildcard * is used, a substring. Examples: ANamespace, AClass, +# AClass::ANamespace, ANamespace::*Test +# +# Note that the wildcards are matched against the file with absolute path, so to +# exclude all test directories use the pattern */test/* + +EXCLUDE_SYMBOLS = IceDiscovery IceLocatorDiscovery + +# The EXAMPLE_PATH tag can be used to specify one or more files or directories +# that contain example code fragments that are included (see the \include +# command). + +EXAMPLE_PATH = + +# If the value of the EXAMPLE_PATH tag contains directories, you can use the +# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and +# *.h) to filter out the source-files in the directories. If left blank all +# files are included. + +EXAMPLE_PATTERNS = * + +# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be +# searched for input files to be used with the \include or \dontinclude commands +# irrespective of the value of the RECURSIVE tag. +# The default value is: NO. + +EXAMPLE_RECURSIVE = NO + +# The IMAGE_PATH tag can be used to specify one or more files or directories +# that contain images that are to be included in the documentation (see the +# \image command). + +IMAGE_PATH = + +# The INPUT_FILTER tag can be used to specify a program that doxygen should +# invoke to filter for each input file. Doxygen will invoke the filter program +# by executing (via popen()) the command: +# +# <filter> <input-file> +# +# where <filter> is the value of the INPUT_FILTER tag, and <input-file> is the +# name of an input file. Doxygen will then use the output that the filter +# program writes to standard output. If FILTER_PATTERNS is specified, this tag +# will be ignored. +# +# Note that the filter must not add or remove lines; it is applied before the +# code is scanned, but not when the output code is generated. If lines are added +# or removed, the anchors will not be placed correctly. +# +# Note that for custom extensions or not directly supported extensions you also +# need to set EXTENSION_MAPPING for the extension otherwise the files are not +# properly processed by doxygen. + +INPUT_FILTER = + +# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern +# basis. Doxygen will compare the file name with each pattern and apply the +# filter if there is a match. The filters are a list of the form: pattern=filter +# (like *.cpp=my_cpp_filter). See INPUT_FILTER for further information on how +# filters are used. If the FILTER_PATTERNS tag is empty or if none of the +# patterns match the file name, INPUT_FILTER is applied. +# +# Note that for custom extensions or not directly supported extensions you also +# need to set EXTENSION_MAPPING for the extension otherwise the files are not +# properly processed by doxygen. + +FILTER_PATTERNS = + +# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using +# INPUT_FILTER) will also be used to filter the input files that are used for +# producing the source files to browse (i.e. when SOURCE_BROWSER is set to YES). +# The default value is: NO. + +FILTER_SOURCE_FILES = NO + +# The FILTER_SOURCE_PATTERNS tag can be used to specify source filters per file +# pattern. A pattern will override the setting for FILTER_PATTERN (if any) and +# it is also possible to disable source filtering for a specific pattern using +# *.ext= (so without naming a filter). +# This tag requires that the tag FILTER_SOURCE_FILES is set to YES. + +FILTER_SOURCE_PATTERNS = + +# If the USE_MDFILE_AS_MAINPAGE tag refers to the name of a markdown file that +# is part of the input, its contents will be placed on the main page +# (index.html). This can be useful if you have a project on for instance GitHub +# and want to reuse the introduction page also for the doxygen output. + +USE_MDFILE_AS_MAINPAGE = mainpage.md + +#--------------------------------------------------------------------------- +# Configuration options related to source browsing +#--------------------------------------------------------------------------- + +# If the SOURCE_BROWSER tag is set to YES then a list of source files will be +# generated. Documented entities will be cross-referenced with these sources. +# +# Note: To get rid of all source code in the generated output, make sure that +# also VERBATIM_HEADERS is set to NO. +# The default value is: NO. + +SOURCE_BROWSER = NO + +# Setting the INLINE_SOURCES tag to YES will include the body of functions, +# classes and enums directly into the documentation. +# The default value is: NO. + +INLINE_SOURCES = NO + +# Setting the STRIP_CODE_COMMENTS tag to YES will instruct doxygen to hide any +# special comment blocks from generated source code fragments. Normal C, C++ and +# Fortran comments will always remain visible. +# The default value is: YES. + +STRIP_CODE_COMMENTS = YES + +# If the REFERENCED_BY_RELATION tag is set to YES then for each documented +# function all documented functions referencing it will be listed. +# The default value is: NO. + +REFERENCED_BY_RELATION = NO + +# If the REFERENCES_RELATION tag is set to YES then for each documented function +# all documented entities called/used by that function will be listed. +# The default value is: NO. + +REFERENCES_RELATION = NO + +# If the REFERENCES_LINK_SOURCE tag is set to YES and SOURCE_BROWSER tag is set +# to YES then the hyperlinks from functions in REFERENCES_RELATION and +# REFERENCED_BY_RELATION lists will link to the source code. Otherwise they will +# link to the documentation. +# The default value is: YES. + +REFERENCES_LINK_SOURCE = YES + +# If SOURCE_TOOLTIPS is enabled (the default) then hovering a hyperlink in the +# source code will show a tooltip with additional information such as prototype, +# brief description and links to the definition and documentation. Since this +# will make the HTML file larger and loading of large files a bit slower, you +# can opt to disable this feature. +# The default value is: YES. +# This tag requires that the tag SOURCE_BROWSER is set to YES. + +SOURCE_TOOLTIPS = YES + +# If the USE_HTAGS tag is set to YES then the references to source code will +# point to the HTML generated by the htags(1) tool instead of doxygen built-in +# source browser. The htags tool is part of GNU's global source tagging system +# (see https://www.gnu.org/software/global/global.html). You will need version +# 4.8.6 or higher. +# +# To use it do the following: +# - Install the latest version of global +# - Enable SOURCE_BROWSER and USE_HTAGS in the config file +# - Make sure the INPUT points to the root of the source tree +# - Run doxygen as normal +# +# Doxygen will invoke htags (and that will in turn invoke gtags), so these +# tools must be available from the command line (i.e. in the search path). +# +# The result: instead of the source browser generated by doxygen, the links to +# source code will now point to the output of htags. +# The default value is: NO. +# This tag requires that the tag SOURCE_BROWSER is set to YES. + +USE_HTAGS = NO + +# If the VERBATIM_HEADERS tag is set the YES then doxygen will generate a +# verbatim copy of the header file for each class for which an include is +# specified. Set to NO to disable this. +# See also: Section \class. +# The default value is: YES. + +VERBATIM_HEADERS = YES + +#--------------------------------------------------------------------------- +# Configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- + +# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index of all +# compounds will be generated. Enable this if the project contains a lot of +# classes, structs, unions or interfaces. +# The default value is: YES. + +ALPHABETICAL_INDEX = YES + +# The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in +# which the alphabetical index list will be split. +# Minimum value: 1, maximum value: 20, default value: 5. +# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. + +COLS_IN_ALPHA_INDEX = 3 + +# In case all classes in a project start with a common prefix, all classes will +# be put under the same header in the alphabetical index. The IGNORE_PREFIX tag +# can be used to specify a prefix (or a list of prefixes) that should be ignored +# while generating the index headers. +# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. + +IGNORE_PREFIX = + +#--------------------------------------------------------------------------- +# Configuration options related to the HTML output +#--------------------------------------------------------------------------- + +# If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output +# The default value is: YES. + +GENERATE_HTML = YES + +# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. +# The default directory is: html. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_OUTPUT = html + +# The HTML_FILE_EXTENSION tag can be used to specify the file extension for each +# generated HTML page (for example: .htm, .php, .asp). +# The default value is: .html. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_FILE_EXTENSION = .html + +# The HTML_HEADER tag can be used to specify a user-defined HTML header file for +# each generated HTML page. If the tag is left blank doxygen will generate a +# standard header. +# +# To get valid HTML the header file that includes any scripts and style sheets +# that doxygen needs, which is dependent on the configuration options used (e.g. +# the setting GENERATE_TREEVIEW). It is highly recommended to start with a +# default header using +# doxygen -w html new_header.html new_footer.html new_stylesheet.css +# YourConfigFile +# and then modify the file new_header.html. See also section "Doxygen usage" +# for information on how to generate the default header that doxygen normally +# uses. +# Note: The header is subject to change so you typically have to regenerate the +# default header when upgrading to a newer version of doxygen. For a description +# of the possible markers and block names see the documentation. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_HEADER = + +# The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each +# generated HTML page. If the tag is left blank doxygen will generate a standard +# footer. See HTML_HEADER for more information on how to generate a default +# footer and what special commands can be used inside the footer. See also +# section "Doxygen usage" for information on how to generate the default footer +# that doxygen normally uses. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_FOOTER = + +# The HTML_STYLESHEET tag can be used to specify a user-defined cascading style +# sheet that is used by each HTML page. It can be used to fine-tune the look of +# the HTML output. If left blank doxygen will generate a default style sheet. +# See also section "Doxygen usage" for information on how to generate the style +# sheet that doxygen normally uses. +# Note: It is recommended to use HTML_EXTRA_STYLESHEET instead of this tag, as +# it is more robust and this tag (HTML_STYLESHEET) will in the future become +# obsolete. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_STYLESHEET = + +# The HTML_EXTRA_STYLESHEET tag can be used to specify additional user-defined +# cascading style sheets that are included after the standard style sheets +# created by doxygen. Using this option one can overrule certain style aspects. +# This is preferred over using HTML_STYLESHEET since it does not replace the +# standard style sheet and is therefore more robust against future updates. +# Doxygen will copy the style sheet files to the output directory. +# Note: The order of the extra style sheet files is of importance (e.g. the last +# style sheet in the list overrules the setting of the previous ones in the +# list). For an example see the documentation. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_EXTRA_STYLESHEET = + +# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or +# other source files which should be copied to the HTML output directory. Note +# that these files will be copied to the base HTML output directory. Use the +# $relpath^ marker in the HTML_HEADER and/or HTML_FOOTER files to load these +# files. In the HTML_STYLESHEET file, use the file name only. Also note that the +# files will be copied as-is; there are no commands or markers available. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_EXTRA_FILES = + +# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen +# will adjust the colors in the style sheet and background images according to +# this color. Hue is specified as an angle on a colorwheel, see +# https://en.wikipedia.org/wiki/Hue for more information. For instance the value +# 0 represents red, 60 is yellow, 120 is green, 180 is cyan, 240 is blue, 300 +# purple, and 360 is red again. +# Minimum value: 0, maximum value: 359, default value: 220. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE_HUE = 220 + +# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors +# in the HTML output. For a value of 0 the output will use grayscales only. A +# value of 255 will produce the most vivid colors. +# Minimum value: 0, maximum value: 255, default value: 100. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE_SAT = 100 + +# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to the +# luminance component of the colors in the HTML output. Values below 100 +# gradually make the output lighter, whereas values above 100 make the output +# darker. The value divided by 100 is the actual gamma applied, so 80 represents +# a gamma of 0.8, The value 220 represents a gamma of 2.2, and 100 does not +# change the gamma. +# Minimum value: 40, maximum value: 240, default value: 80. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE_GAMMA = 80 + +# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML +# page will contain the date and time when the page was generated. Setting this +# to YES can help to show when doxygen was last run and thus if the +# documentation is up to date. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_TIMESTAMP = NO + +# If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML +# documentation will contain a main index with vertical navigation menus that +# are dynamically created via Javascript. If disabled, the navigation index will +# consists of multiple levels of tabs that are statically embedded in every HTML +# page. Disable this option to support browsers that do not have Javascript, +# like the Qt help browser. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_DYNAMIC_MENUS = YES + +# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML +# documentation will contain sections that can be hidden and shown after the +# page has loaded. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_DYNAMIC_SECTIONS = NO + +# With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries +# shown in the various tree structured indices initially; the user can expand +# and collapse entries dynamically later on. Doxygen will expand the tree to +# such a level that at most the specified number of entries are visible (unless +# a fully collapsed tree already exceeds this amount). So setting the number of +# entries 1 will produce a full collapsed tree by default. 0 is a special value +# representing an infinite number of entries and will result in a full expanded +# tree by default. +# Minimum value: 0, maximum value: 9999, default value: 100. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_INDEX_NUM_ENTRIES = 100 + +# If the GENERATE_DOCSET tag is set to YES, additional index files will be +# generated that can be used as input for Apple's Xcode 3 integrated development +# environment (see: https://developer.apple.com/tools/xcode/), introduced with +# OSX 10.5 (Leopard). To create a documentation set, doxygen will generate a +# Makefile in the HTML output directory. Running make will produce the docset in +# that directory and running make install will install the docset in +# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find it at +# startup. See https://developer.apple.com/tools/creatingdocsetswithdoxygen.html +# for more information. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_DOCSET = NO + +# This tag determines the name of the docset feed. A documentation feed provides +# an umbrella under which multiple documentation sets from a single provider +# (such as a company or product suite) can be grouped. +# The default value is: Doxygen generated docs. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_FEEDNAME = "Doxygen generated docs" + +# This tag specifies a string that should uniquely identify the documentation +# set bundle. This should be a reverse domain-name style string, e.g. +# com.mycompany.MyDocSet. Doxygen will append .docset to the name. +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_BUNDLE_ID = org.doxygen.Project + +# The DOCSET_PUBLISHER_ID tag specifies a string that should uniquely identify +# the documentation publisher. This should be a reverse domain-name style +# string, e.g. com.mycompany.MyDocSet.documentation. +# The default value is: org.doxygen.Publisher. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_PUBLISHER_ID = org.doxygen.Publisher + +# The DOCSET_PUBLISHER_NAME tag identifies the documentation publisher. +# The default value is: Publisher. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_PUBLISHER_NAME = Publisher + +# If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three +# additional HTML index files: index.hhp, index.hhc, and index.hhk. The +# index.hhp is a project file that can be read by Microsoft's HTML Help Workshop +# (see: http://www.microsoft.com/en-us/download/details.aspx?id=21138) on +# Windows. +# +# The HTML Help Workshop contains a compiler that can convert all HTML output +# generated by doxygen into a single compiled HTML file (.chm). Compiled HTML +# files are now used as the Windows 98 help format, and will replace the old +# Windows help format (.hlp) on all Windows platforms in the future. Compressed +# HTML files also contain an index, a table of contents, and you can search for +# words in the documentation. The HTML workshop also contains a viewer for +# compressed HTML files. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_HTMLHELP = NO + +# The CHM_FILE tag can be used to specify the file name of the resulting .chm +# file. You can add a path in front of the file if the result should not be +# written to the html output directory. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +CHM_FILE = + +# The HHC_LOCATION tag can be used to specify the location (absolute path +# including file name) of the HTML help compiler (hhc.exe). If non-empty, +# doxygen will try to run the HTML help compiler on the generated index.hhp. +# The file has to be specified with full path. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +HHC_LOCATION = + +# The GENERATE_CHI flag controls if a separate .chi index file is generated +# (YES) or that it should be included in the master .chm file (NO). +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +GENERATE_CHI = NO + +# The CHM_INDEX_ENCODING is used to encode HtmlHelp index (hhk), content (hhc) +# and project file content. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +CHM_INDEX_ENCODING = + +# The BINARY_TOC flag controls whether a binary table of contents is generated +# (YES) or a normal table of contents (NO) in the .chm file. Furthermore it +# enables the Previous and Next buttons. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +BINARY_TOC = NO + +# The TOC_EXPAND flag can be set to YES to add extra items for group members to +# the table of contents of the HTML help documentation and to the tree view. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +TOC_EXPAND = NO + +# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and +# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated that +# can be used as input for Qt's qhelpgenerator to generate a Qt Compressed Help +# (.qch) of the generated HTML documentation. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_QHP = NO + +# If the QHG_LOCATION tag is specified, the QCH_FILE tag can be used to specify +# the file name of the resulting .qch file. The path specified is relative to +# the HTML output folder. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QCH_FILE = + +# The QHP_NAMESPACE tag specifies the namespace to use when generating Qt Help +# Project output. For more information please see Qt Help Project / Namespace +# (see: http://doc.qt.io/qt-4.8/qthelpproject.html#namespace). +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_NAMESPACE = org.doxygen.Project + +# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating Qt +# Help Project output. For more information please see Qt Help Project / Virtual +# Folders (see: http://doc.qt.io/qt-4.8/qthelpproject.html#virtual-folders). +# The default value is: doc. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_VIRTUAL_FOLDER = doc + +# If the QHP_CUST_FILTER_NAME tag is set, it specifies the name of a custom +# filter to add. For more information please see Qt Help Project / Custom +# Filters (see: http://doc.qt.io/qt-4.8/qthelpproject.html#custom-filters). +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_CUST_FILTER_NAME = + +# The QHP_CUST_FILTER_ATTRS tag specifies the list of the attributes of the +# custom filter to add. For more information please see Qt Help Project / Custom +# Filters (see: http://doc.qt.io/qt-4.8/qthelpproject.html#custom-filters). +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_CUST_FILTER_ATTRS = + +# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this +# project's filter section matches. Qt Help Project / Filter Attributes (see: +# http://doc.qt.io/qt-4.8/qthelpproject.html#filter-attributes). +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_SECT_FILTER_ATTRS = + +# The QHG_LOCATION tag can be used to specify the location of Qt's +# qhelpgenerator. If non-empty doxygen will try to run qhelpgenerator on the +# generated .qhp file. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHG_LOCATION = + +# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files will be +# generated, together with the HTML files, they form an Eclipse help plugin. To +# install this plugin and make it available under the help contents menu in +# Eclipse, the contents of the directory containing the HTML and XML files needs +# to be copied into the plugins directory of eclipse. The name of the directory +# within the plugins directory should be the same as the ECLIPSE_DOC_ID value. +# After copying Eclipse needs to be restarted before the help appears. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_ECLIPSEHELP = NO + +# A unique identifier for the Eclipse help plugin. When installing the plugin +# the directory name containing the HTML and XML files should also have this +# name. Each documentation set should have its own identifier. +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_ECLIPSEHELP is set to YES. + +ECLIPSE_DOC_ID = org.doxygen.Project + +# If you want full control over the layout of the generated HTML pages it might +# be necessary to disable the index and replace it with your own. The +# DISABLE_INDEX tag can be used to turn on/off the condensed index (tabs) at top +# of each HTML page. A value of NO enables the index and the value YES disables +# it. Since the tabs in the index contain the same information as the navigation +# tree, you can set this option to YES if you also set GENERATE_TREEVIEW to YES. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +DISABLE_INDEX = NO + +# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index +# structure should be generated to display hierarchical information. If the tag +# value is set to YES, a side panel will be generated containing a tree-like +# index structure (just like the one that is generated for HTML Help). For this +# to work a browser that supports JavaScript, DHTML, CSS and frames is required +# (i.e. any modern browser). Windows users are probably better off using the +# HTML help feature. Via custom style sheets (see HTML_EXTRA_STYLESHEET) one can +# further fine-tune the look of the index. As an example, the default style +# sheet generated by doxygen has an example that shows how to put an image at +# the root of the tree instead of the PROJECT_NAME. Since the tree basically has +# the same information as the tab index, you could consider setting +# DISABLE_INDEX to YES when enabling this option. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_TREEVIEW = NO + +# The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that +# doxygen will group on one line in the generated HTML documentation. +# +# Note that a value of 0 will completely suppress the enum values from appearing +# in the overview section. +# Minimum value: 0, maximum value: 20, default value: 4. +# This tag requires that the tag GENERATE_HTML is set to YES. + +ENUM_VALUES_PER_LINE = 4 + +# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be used +# to set the initial width (in pixels) of the frame in which the tree is shown. +# Minimum value: 0, maximum value: 1500, default value: 250. +# This tag requires that the tag GENERATE_HTML is set to YES. + +TREEVIEW_WIDTH = 250 + +# If the EXT_LINKS_IN_WINDOW option is set to YES, doxygen will open links to +# external symbols imported via tag files in a separate window. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +EXT_LINKS_IN_WINDOW = NO + +# Use this tag to change the font size of LaTeX formulas included as images in +# the HTML documentation. When you change the font size after a successful +# doxygen run you need to manually remove any form_*.png images from the HTML +# output directory to force them to be regenerated. +# Minimum value: 8, maximum value: 50, default value: 10. +# This tag requires that the tag GENERATE_HTML is set to YES. + +FORMULA_FONTSIZE = 10 + +# Use the FORMULA_TRANSPARENT tag to determine whether or not the images +# generated for formulas are transparent PNGs. Transparent PNGs are not +# supported properly for IE 6.0, but are supported on all modern browsers. +# +# Note that when changing this option you need to delete any form_*.png files in +# the HTML output directory before the changes have effect. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +FORMULA_TRANSPARENT = YES + +# Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see +# https://www.mathjax.org) which uses client side Javascript for the rendering +# instead of using pre-rendered bitmaps. Use this if you do not have LaTeX +# installed or if you want to formulas look prettier in the HTML output. When +# enabled you may also need to install MathJax separately and configure the path +# to it using the MATHJAX_RELPATH option. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +USE_MATHJAX = NO + +# When MathJax is enabled you can set the default output format to be used for +# the MathJax output. See the MathJax site (see: +# http://docs.mathjax.org/en/latest/output.html) for more details. +# Possible values are: HTML-CSS (which is slower, but has the best +# compatibility), NativeMML (i.e. MathML) and SVG. +# The default value is: HTML-CSS. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_FORMAT = HTML-CSS + +# When MathJax is enabled you need to specify the location relative to the HTML +# output directory using the MATHJAX_RELPATH option. The destination directory +# should contain the MathJax.js script. For instance, if the mathjax directory +# is located at the same level as the HTML output directory, then +# MATHJAX_RELPATH should be ../mathjax. The default value points to the MathJax +# Content Delivery Network so you can quickly see the result without installing +# MathJax. However, it is strongly recommended to install a local copy of +# MathJax from https://www.mathjax.org before deployment. +# The default value is: https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_RELPATH = https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/ + +# The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax +# extension names that should be enabled during MathJax rendering. For example +# MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_EXTENSIONS = + +# The MATHJAX_CODEFILE tag can be used to specify a file with javascript pieces +# of code that will be used on startup of the MathJax code. See the MathJax site +# (see: http://docs.mathjax.org/en/latest/output.html) for more details. For an +# example see the documentation. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_CODEFILE = + +# When the SEARCHENGINE tag is enabled doxygen will generate a search box for +# the HTML output. The underlying search engine uses javascript and DHTML and +# should work on any modern browser. Note that when using HTML help +# (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets (GENERATE_DOCSET) +# there is already a search function so this one should typically be disabled. +# For large projects the javascript based search engine can be slow, then +# enabling SERVER_BASED_SEARCH may provide a better solution. It is possible to +# search using the keyboard; to jump to the search box use <access key> + S +# (what the <access key> is depends on the OS and browser, but it is typically +# <CTRL>, <ALT>/<option>, or both). Inside the search box use the <cursor down +# key> to jump into the search results window, the results can be navigated +# using the <cursor keys>. Press <Enter> to select an item or <escape> to cancel +# the search. The filter options can be selected when the cursor is inside the +# search box by pressing <Shift>+<cursor down>. Also here use the <cursor keys> +# to select a filter and <Enter> or <escape> to activate or cancel the filter +# option. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +SEARCHENGINE = YES + +# When the SERVER_BASED_SEARCH tag is enabled the search engine will be +# implemented using a web server instead of a web client using Javascript. There +# are two flavors of web server based searching depending on the EXTERNAL_SEARCH +# setting. When disabled, doxygen will generate a PHP script for searching and +# an index file used by the script. When EXTERNAL_SEARCH is enabled the indexing +# and searching needs to be provided by external tools. See the section +# "External Indexing and Searching" for details. +# The default value is: NO. +# This tag requires that the tag SEARCHENGINE is set to YES. + +SERVER_BASED_SEARCH = NO + +# When EXTERNAL_SEARCH tag is enabled doxygen will no longer generate the PHP +# script for searching. Instead the search results are written to an XML file +# which needs to be processed by an external indexer. Doxygen will invoke an +# external search engine pointed to by the SEARCHENGINE_URL option to obtain the +# search results. +# +# Doxygen ships with an example indexer (doxyindexer) and search engine +# (doxysearch.cgi) which are based on the open source search engine library +# Xapian (see: https://xapian.org/). +# +# See the section "External Indexing and Searching" for details. +# The default value is: NO. +# This tag requires that the tag SEARCHENGINE is set to YES. + +EXTERNAL_SEARCH = NO + +# The SEARCHENGINE_URL should point to a search engine hosted by a web server +# which will return the search results when EXTERNAL_SEARCH is enabled. +# +# Doxygen ships with an example indexer (doxyindexer) and search engine +# (doxysearch.cgi) which are based on the open source search engine library +# Xapian (see: https://xapian.org/). See the section "External Indexing and +# Searching" for details. +# This tag requires that the tag SEARCHENGINE is set to YES. + +SEARCHENGINE_URL = + +# When SERVER_BASED_SEARCH and EXTERNAL_SEARCH are both enabled the unindexed +# search data is written to a file for indexing by an external tool. With the +# SEARCHDATA_FILE tag the name of this file can be specified. +# The default file is: searchdata.xml. +# This tag requires that the tag SEARCHENGINE is set to YES. + +SEARCHDATA_FILE = searchdata.xml + +# When SERVER_BASED_SEARCH and EXTERNAL_SEARCH are both enabled the +# EXTERNAL_SEARCH_ID tag can be used as an identifier for the project. This is +# useful in combination with EXTRA_SEARCH_MAPPINGS to search through multiple +# projects and redirect the results back to the right project. +# This tag requires that the tag SEARCHENGINE is set to YES. + +EXTERNAL_SEARCH_ID = + +# The EXTRA_SEARCH_MAPPINGS tag can be used to enable searching through doxygen +# projects other than the one defined by this configuration file, but that are +# all added to the same external search index. Each project needs to have a +# unique id set via EXTERNAL_SEARCH_ID. The search mapping then maps the id of +# to a relative location where the documentation can be found. The format is: +# EXTRA_SEARCH_MAPPINGS = tagname1=loc1 tagname2=loc2 ... +# This tag requires that the tag SEARCHENGINE is set to YES. + +EXTRA_SEARCH_MAPPINGS = + +#--------------------------------------------------------------------------- +# Configuration options related to the LaTeX output +#--------------------------------------------------------------------------- + +# If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output. +# The default value is: YES. + +GENERATE_LATEX = NO + +# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. +# The default directory is: latex. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_OUTPUT = latex + +# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be +# invoked. +# +# Note that when enabling USE_PDFLATEX this option is only used for generating +# bitmaps for formulas in the HTML output, but not in the Makefile that is +# written to the output directory. +# The default file is: latex. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_CMD_NAME = latex + +# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to generate +# index for LaTeX. +# The default file is: makeindex. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +MAKEINDEX_CMD_NAME = makeindex + +# If the COMPACT_LATEX tag is set to YES, doxygen generates more compact LaTeX +# documents. This may be useful for small projects and may help to save some +# trees in general. +# The default value is: NO. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +COMPACT_LATEX = NO + +# The PAPER_TYPE tag can be used to set the paper type that is used by the +# printer. +# Possible values are: a4 (210 x 297 mm), letter (8.5 x 11 inches), legal (8.5 x +# 14 inches) and executive (7.25 x 10.5 inches). +# The default value is: a4. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +PAPER_TYPE = a4 + +# The EXTRA_PACKAGES tag can be used to specify one or more LaTeX package names +# that should be included in the LaTeX output. The package can be specified just +# by its name or with the correct syntax as to be used with the LaTeX +# \usepackage command. To get the times font for instance you can specify : +# EXTRA_PACKAGES=times or EXTRA_PACKAGES={times} +# To use the option intlimits with the amsmath package you can specify: +# EXTRA_PACKAGES=[intlimits]{amsmath} +# If left blank no extra packages will be included. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +EXTRA_PACKAGES = + +# The LATEX_HEADER tag can be used to specify a personal LaTeX header for the +# generated LaTeX document. The header should contain everything until the first +# chapter. If it is left blank doxygen will generate a standard header. See +# section "Doxygen usage" for information on how to let doxygen write the +# default header to a separate file. +# +# Note: Only use a user-defined header if you know what you are doing! The +# following commands have a special meaning inside the header: $title, +# $datetime, $date, $doxygenversion, $projectname, $projectnumber, +# $projectbrief, $projectlogo. Doxygen will replace $title with the empty +# string, for the replacement values of the other commands the user is referred +# to HTML_HEADER. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_HEADER = + +# The LATEX_FOOTER tag can be used to specify a personal LaTeX footer for the +# generated LaTeX document. The footer should contain everything after the last +# chapter. If it is left blank doxygen will generate a standard footer. See +# LATEX_HEADER for more information on how to generate a default footer and what +# special commands can be used inside the footer. +# +# Note: Only use a user-defined footer if you know what you are doing! +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_FOOTER = + +# The LATEX_EXTRA_STYLESHEET tag can be used to specify additional user-defined +# LaTeX style sheets that are included after the standard style sheets created +# by doxygen. Using this option one can overrule certain style aspects. Doxygen +# will copy the style sheet files to the output directory. +# Note: The order of the extra style sheet files is of importance (e.g. the last +# style sheet in the list overrules the setting of the previous ones in the +# list). +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_EXTRA_STYLESHEET = + +# The LATEX_EXTRA_FILES tag can be used to specify one or more extra images or +# other source files which should be copied to the LATEX_OUTPUT output +# directory. Note that the files will be copied as-is; there are no commands or +# markers available. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_EXTRA_FILES = + +# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated is +# prepared for conversion to PDF (using ps2pdf or pdflatex). The PDF file will +# contain links (just like the HTML output) instead of page references. This +# makes the output suitable for online browsing using a PDF viewer. +# The default value is: YES. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +PDF_HYPERLINKS = YES + +# If the USE_PDFLATEX tag is set to YES, doxygen will use pdflatex to generate +# the PDF file directly from the LaTeX files. Set this option to YES, to get a +# higher quality PDF documentation. +# The default value is: YES. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +USE_PDFLATEX = YES + +# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \batchmode +# command to the generated LaTeX files. This will instruct LaTeX to keep running +# if errors occur, instead of asking the user for help. This option is also used +# when generating formulas in HTML. +# The default value is: NO. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_BATCHMODE = NO + +# If the LATEX_HIDE_INDICES tag is set to YES then doxygen will not include the +# index chapters (such as File Index, Compound Index, etc.) in the output. +# The default value is: NO. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_HIDE_INDICES = NO + +# If the LATEX_SOURCE_CODE tag is set to YES then doxygen will include source +# code with syntax highlighting in the LaTeX output. +# +# Note that which sources are shown also depends on other settings such as +# SOURCE_BROWSER. +# The default value is: NO. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_SOURCE_CODE = NO + +# The LATEX_BIB_STYLE tag can be used to specify the style to use for the +# bibliography, e.g. plainnat, or ieeetr. See +# https://en.wikipedia.org/wiki/BibTeX and \cite for more info. +# The default value is: plain. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_BIB_STYLE = plain + +# If the LATEX_TIMESTAMP tag is set to YES then the footer of each generated +# page will contain the date and time when the page was generated. Setting this +# to NO can help when comparing the output of multiple runs. +# The default value is: NO. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_TIMESTAMP = NO + +#--------------------------------------------------------------------------- +# Configuration options related to the RTF output +#--------------------------------------------------------------------------- + +# If the GENERATE_RTF tag is set to YES, doxygen will generate RTF output. The +# RTF output is optimized for Word 97 and may not look too pretty with other RTF +# readers/editors. +# The default value is: NO. + +GENERATE_RTF = NO + +# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. +# The default directory is: rtf. +# This tag requires that the tag GENERATE_RTF is set to YES. + +RTF_OUTPUT = rtf + +# If the COMPACT_RTF tag is set to YES, doxygen generates more compact RTF +# documents. This may be useful for small projects and may help to save some +# trees in general. +# The default value is: NO. +# This tag requires that the tag GENERATE_RTF is set to YES. + +COMPACT_RTF = NO + +# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated will +# contain hyperlink fields. The RTF file will contain links (just like the HTML +# output) instead of page references. This makes the output suitable for online +# browsing using Word or some other Word compatible readers that support those +# fields. +# +# Note: WordPad (write) and others do not support links. +# The default value is: NO. +# This tag requires that the tag GENERATE_RTF is set to YES. + +RTF_HYPERLINKS = NO + +# Load stylesheet definitions from file. Syntax is similar to doxygen's config +# file, i.e. a series of assignments. You only have to provide replacements, +# missing definitions are set to their default value. +# +# See also section "Doxygen usage" for information on how to generate the +# default style sheet that doxygen normally uses. +# This tag requires that the tag GENERATE_RTF is set to YES. + +RTF_STYLESHEET_FILE = + +# Set optional variables used in the generation of an RTF document. Syntax is +# similar to doxygen's config file. A template extensions file can be generated +# using doxygen -e rtf extensionFile. +# This tag requires that the tag GENERATE_RTF is set to YES. + +RTF_EXTENSIONS_FILE = + +# If the RTF_SOURCE_CODE tag is set to YES then doxygen will include source code +# with syntax highlighting in the RTF output. +# +# Note that which sources are shown also depends on other settings such as +# SOURCE_BROWSER. +# The default value is: NO. +# This tag requires that the tag GENERATE_RTF is set to YES. + +RTF_SOURCE_CODE = NO + +#--------------------------------------------------------------------------- +# Configuration options related to the man page output +#--------------------------------------------------------------------------- + +# If the GENERATE_MAN tag is set to YES, doxygen will generate man pages for +# classes and files. +# The default value is: NO. + +GENERATE_MAN = NO + +# The MAN_OUTPUT tag is used to specify where the man pages will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. A directory man3 will be created inside the directory specified by +# MAN_OUTPUT. +# The default directory is: man. +# This tag requires that the tag GENERATE_MAN is set to YES. + +MAN_OUTPUT = man + +# The MAN_EXTENSION tag determines the extension that is added to the generated +# man pages. In case the manual section does not start with a number, the number +# 3 is prepended. The dot (.) at the beginning of the MAN_EXTENSION tag is +# optional. +# The default value is: .3. +# This tag requires that the tag GENERATE_MAN is set to YES. + +MAN_EXTENSION = .3 + +# The MAN_SUBDIR tag determines the name of the directory created within +# MAN_OUTPUT in which the man pages are placed. If defaults to man followed by +# MAN_EXTENSION with the initial . removed. +# This tag requires that the tag GENERATE_MAN is set to YES. + +MAN_SUBDIR = + +# If the MAN_LINKS tag is set to YES and doxygen generates man output, then it +# will generate one additional man file for each entity documented in the real +# man page(s). These additional files only source the real man page, but without +# them the man command would be unable to find the correct page. +# The default value is: NO. +# This tag requires that the tag GENERATE_MAN is set to YES. + +MAN_LINKS = NO + +#--------------------------------------------------------------------------- +# Configuration options related to the XML output +#--------------------------------------------------------------------------- + +# If the GENERATE_XML tag is set to YES, doxygen will generate an XML file that +# captures the structure of the code including all documentation. +# The default value is: NO. + +GENERATE_XML = NO + +# The XML_OUTPUT tag is used to specify where the XML pages will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. +# The default directory is: xml. +# This tag requires that the tag GENERATE_XML is set to YES. + +XML_OUTPUT = xml + +# If the XML_PROGRAMLISTING tag is set to YES, doxygen will dump the program +# listings (including syntax highlighting and cross-referencing information) to +# the XML output. Note that enabling this will significantly increase the size +# of the XML output. +# The default value is: YES. +# This tag requires that the tag GENERATE_XML is set to YES. + +XML_PROGRAMLISTING = YES + +#--------------------------------------------------------------------------- +# Configuration options related to the DOCBOOK output +#--------------------------------------------------------------------------- + +# If the GENERATE_DOCBOOK tag is set to YES, doxygen will generate Docbook files +# that can be used to generate PDF. +# The default value is: NO. + +GENERATE_DOCBOOK = NO + +# The DOCBOOK_OUTPUT tag is used to specify where the Docbook pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be put in +# front of it. +# The default directory is: docbook. +# This tag requires that the tag GENERATE_DOCBOOK is set to YES. + +DOCBOOK_OUTPUT = docbook + +# If the DOCBOOK_PROGRAMLISTING tag is set to YES, doxygen will include the +# program listings (including syntax highlighting and cross-referencing +# information) to the DOCBOOK output. Note that enabling this will significantly +# increase the size of the DOCBOOK output. +# The default value is: NO. +# This tag requires that the tag GENERATE_DOCBOOK is set to YES. + +DOCBOOK_PROGRAMLISTING = NO + +#--------------------------------------------------------------------------- +# Configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- + +# If the GENERATE_AUTOGEN_DEF tag is set to YES, doxygen will generate an +# AutoGen Definitions (see http://autogen.sourceforge.net/) file that captures +# the structure of the code including all documentation. Note that this feature +# is still experimental and incomplete at the moment. +# The default value is: NO. + +GENERATE_AUTOGEN_DEF = NO + +#--------------------------------------------------------------------------- +# Configuration options related to the Perl module output +#--------------------------------------------------------------------------- + +# If the GENERATE_PERLMOD tag is set to YES, doxygen will generate a Perl module +# file that captures the structure of the code including all documentation. +# +# Note that this feature is still experimental and incomplete at the moment. +# The default value is: NO. + +GENERATE_PERLMOD = NO + +# If the PERLMOD_LATEX tag is set to YES, doxygen will generate the necessary +# Makefile rules, Perl scripts and LaTeX code to be able to generate PDF and DVI +# output from the Perl module output. +# The default value is: NO. +# This tag requires that the tag GENERATE_PERLMOD is set to YES. + +PERLMOD_LATEX = NO + +# If the PERLMOD_PRETTY tag is set to YES, the Perl module output will be nicely +# formatted so it can be parsed by a human reader. This is useful if you want to +# understand what is going on. On the other hand, if this tag is set to NO, the +# size of the Perl module output will be much smaller and Perl will parse it +# just the same. +# The default value is: YES. +# This tag requires that the tag GENERATE_PERLMOD is set to YES. + +PERLMOD_PRETTY = YES + +# The names of the make variables in the generated doxyrules.make file are +# prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. This is useful +# so different doxyrules.make files included by the same Makefile don't +# overwrite each other's variables. +# This tag requires that the tag GENERATE_PERLMOD is set to YES. + +PERLMOD_MAKEVAR_PREFIX = + +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- + +# If the ENABLE_PREPROCESSING tag is set to YES, doxygen will evaluate all +# C-preprocessor directives found in the sources and include files. +# The default value is: YES. + +ENABLE_PREPROCESSING = YES + +# If the MACRO_EXPANSION tag is set to YES, doxygen will expand all macro names +# in the source code. If set to NO, only conditional compilation will be +# performed. Macro expansion can be done in a controlled way by setting +# EXPAND_ONLY_PREDEF to YES. +# The default value is: NO. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. + +MACRO_EXPANSION = NO + +# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then +# the macro expansion is limited to the macros specified with the PREDEFINED and +# EXPAND_AS_DEFINED tags. +# The default value is: NO. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. + +EXPAND_ONLY_PREDEF = NO + +# If the SEARCH_INCLUDES tag is set to YES, the include files in the +# INCLUDE_PATH will be searched if a #include is found. +# The default value is: YES. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. + +SEARCH_INCLUDES = YES + +# The INCLUDE_PATH tag can be used to specify one or more directories that +# contain include files that are not input files but should be processed by the +# preprocessor. +# This tag requires that the tag SEARCH_INCLUDES is set to YES. + +INCLUDE_PATH = ../slice/ + +# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard +# patterns (like *.h and *.hpp) to filter out the header-files in the +# directories. If left blank, the patterns specified with FILE_PATTERNS will be +# used. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. + +INCLUDE_FILE_PATTERNS = + +# The PREDEFINED tag can be used to specify one or more macro names that are +# defined before the preprocessor is started (similar to the -D option of e.g. +# gcc). The argument of the tag is a list of macros of the form: name or +# name=definition (no spaces). If the definition and the "=" are omitted, "=1" +# is assumed. To prevent a macro definition from being undefined via #undef or +# recursively expanded use the := operator instead of the = operator. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. + +PREDEFINED = + +# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this +# tag can be used to specify a list of macro names that should be expanded. The +# macro definition that is found in the sources will be used. Use the PREDEFINED +# tag if you want to use a different macro definition that overrules the +# definition found in the source code. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. + +EXPAND_AS_DEFINED = + +# If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will +# remove all references to function-like macros that are alone on a line, have +# an all uppercase name, and do not end with a semicolon. Such function macros +# are typically used for boiler-plate code, and will confuse the parser if not +# removed. +# The default value is: YES. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. + +SKIP_FUNCTION_MACROS = YES + +#--------------------------------------------------------------------------- +# Configuration options related to external references +#--------------------------------------------------------------------------- + +# The TAGFILES tag can be used to specify one or more tag files. For each tag +# file the location of the external documentation should be added. The format of +# a tag file without this location is as follows: +# TAGFILES = file1 file2 ... +# Adding location for the tag files is done as follows: +# TAGFILES = file1=loc1 "file2 = loc2" ... +# where loc1 and loc2 can be relative or absolute paths or URLs. See the +# section "Linking to external documentation" for more information about the use +# of tag files. +# Note: Each tag file must have a unique name (where the name does NOT include +# the path). If a tag file is not located in the directory in which doxygen is +# run, you must also specify the path to the tagfile here. + +TAGFILES = + +# When a file name is specified after GENERATE_TAGFILE, doxygen will create a +# tag file that is based on the input files it reads. See section "Linking to +# external documentation" for more information about the usage of tag files. + +GENERATE_TAGFILE = slice.tag + +# If the ALLEXTERNALS tag is set to YES, all external class will be listed in +# the class index. If set to NO, only the inherited external classes will be +# listed. +# The default value is: NO. + +ALLEXTERNALS = NO + +# If the EXTERNAL_GROUPS tag is set to YES, all external groups will be listed +# in the modules index. If set to NO, only the current project's groups will be +# listed. +# The default value is: YES. + +EXTERNAL_GROUPS = YES + +# If the EXTERNAL_PAGES tag is set to YES, all external pages will be listed in +# the related pages index. If set to NO, only the current project's pages will +# be listed. +# The default value is: YES. + +EXTERNAL_PAGES = YES + +# The PERL_PATH should be the absolute path and name of the perl script +# interpreter (i.e. the result of 'which perl'). +# The default file (with absolute path) is: /usr/bin/perl. + +PERL_PATH = /usr/bin/perl + +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- + +# If the CLASS_DIAGRAMS tag is set to YES, doxygen will generate a class diagram +# (in HTML and LaTeX) for classes with base or super classes. Setting the tag to +# NO turns the diagrams off. Note that this option also works with HAVE_DOT +# disabled, but it is recommended to install and use dot, since it yields more +# powerful graphs. +# The default value is: YES. + +CLASS_DIAGRAMS = YES + +# You can define message sequence charts within doxygen comments using the \msc +# command. Doxygen will then run the mscgen tool (see: +# http://www.mcternan.me.uk/mscgen/)) to produce the chart and insert it in the +# documentation. The MSCGEN_PATH tag allows you to specify the directory where +# the mscgen tool resides. If left empty the tool is assumed to be found in the +# default search path. + +MSCGEN_PATH = + +# You can include diagrams made with dia in doxygen documentation. Doxygen will +# then run dia to produce the diagram and insert it in the documentation. The +# DIA_PATH tag allows you to specify the directory where the dia binary resides. +# If left empty dia is assumed to be found in the default search path. + +DIA_PATH = + +# If set to YES the inheritance and collaboration graphs will hide inheritance +# and usage relations if the target is undocumented or is not a class. +# The default value is: YES. + +HIDE_UNDOC_RELATIONS = YES + +# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is +# available from the path. This tool is part of Graphviz (see: +# http://www.graphviz.org/), a graph visualization toolkit from AT&T and Lucent +# Bell Labs. The other options in this section have no effect if this option is +# set to NO +# The default value is: NO. + +HAVE_DOT = YES + +# The DOT_NUM_THREADS specifies the number of dot invocations doxygen is allowed +# to run in parallel. When set to 0 doxygen will base this on the number of +# processors available in the system. You can set it explicitly to a value +# larger than 0 to get control over the balance between CPU load and processing +# speed. +# Minimum value: 0, maximum value: 32, default value: 0. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_NUM_THREADS = 0 + +# When you want a differently looking font in the dot files that doxygen +# generates you can specify the font name using DOT_FONTNAME. You need to make +# sure dot is able to find the font, which can be done by putting it in a +# standard location or by setting the DOTFONTPATH environment variable or by +# setting DOT_FONTPATH to the directory containing the font. +# The default value is: Helvetica. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_FONTNAME = Helvetica + +# The DOT_FONTSIZE tag can be used to set the size (in points) of the font of +# dot graphs. +# Minimum value: 4, maximum value: 24, default value: 10. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_FONTSIZE = 10 + +# By default doxygen will tell dot to use the default font as specified with +# DOT_FONTNAME. If you specify a different font using DOT_FONTNAME you can set +# the path where dot can find it using this tag. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_FONTPATH = + +# If the CLASS_GRAPH tag is set to YES then doxygen will generate a graph for +# each documented class showing the direct and indirect inheritance relations. +# Setting this tag to YES will force the CLASS_DIAGRAMS tag to NO. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + +CLASS_GRAPH = YES + +# If the COLLABORATION_GRAPH tag is set to YES then doxygen will generate a +# graph for each documented class showing the direct and indirect implementation +# dependencies (inheritance, containment, and class references variables) of the +# class with other documented classes. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + +COLLABORATION_GRAPH = YES + +# If the GROUP_GRAPHS tag is set to YES then doxygen will generate a graph for +# groups, showing the direct groups dependencies. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + +GROUP_GRAPHS = YES + +# If the UML_LOOK tag is set to YES, doxygen will generate inheritance and +# collaboration diagrams in a style similar to the OMG's Unified Modeling +# Language. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + +UML_LOOK = NO + +# If the UML_LOOK tag is enabled, the fields and methods are shown inside the +# class node. If there are many fields or methods and many nodes the graph may +# become too big to be useful. The UML_LIMIT_NUM_FIELDS threshold limits the +# number of items for each type to make the size more manageable. Set this to 0 +# for no limit. Note that the threshold may be exceeded by 50% before the limit +# is enforced. So when you set the threshold to 10, up to 15 fields may appear, +# but if the number exceeds 15, the total amount of fields shown is limited to +# 10. +# Minimum value: 0, maximum value: 100, default value: 10. +# This tag requires that the tag HAVE_DOT is set to YES. + +UML_LIMIT_NUM_FIELDS = 10 + +# If the TEMPLATE_RELATIONS tag is set to YES then the inheritance and +# collaboration graphs will show the relations between templates and their +# instances. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + +TEMPLATE_RELATIONS = NO + +# If the INCLUDE_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are set to +# YES then doxygen will generate a graph for each documented file showing the +# direct and indirect include dependencies of the file with other documented +# files. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + +INCLUDE_GRAPH = YES + +# If the INCLUDED_BY_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are +# set to YES then doxygen will generate a graph for each documented file showing +# the direct and indirect include dependencies of the file with other documented +# files. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + +INCLUDED_BY_GRAPH = YES + +# If the CALL_GRAPH tag is set to YES then doxygen will generate a call +# dependency graph for every global function or class method. +# +# Note that enabling this option will significantly increase the time of a run. +# So in most cases it will be better to enable call graphs for selected +# functions only using the \callgraph command. Disabling a call graph can be +# accomplished by means of the command \hidecallgraph. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + +CALL_GRAPH = NO + +# If the CALLER_GRAPH tag is set to YES then doxygen will generate a caller +# dependency graph for every global function or class method. +# +# Note that enabling this option will significantly increase the time of a run. +# So in most cases it will be better to enable caller graphs for selected +# functions only using the \callergraph command. Disabling a caller graph can be +# accomplished by means of the command \hidecallergraph. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + +CALLER_GRAPH = NO + +# If the GRAPHICAL_HIERARCHY tag is set to YES then doxygen will graphical +# hierarchy of all classes instead of a textual one. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + +GRAPHICAL_HIERARCHY = YES + +# If the DIRECTORY_GRAPH tag is set to YES then doxygen will show the +# dependencies a directory has on other directories in a graphical way. The +# dependency relations are determined by the #include relations between the +# files in the directories. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + +DIRECTORY_GRAPH = YES + +# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images +# generated by dot. For an explanation of the image formats see the section +# output formats in the documentation of the dot tool (Graphviz (see: +# http://www.graphviz.org/)). +# Note: If you choose svg you need to set HTML_FILE_EXTENSION to xhtml in order +# to make the SVG files visible in IE 9+ (other browsers do not have this +# requirement). +# Possible values are: png, jpg, gif, svg, png:gd, png:gd:gd, png:cairo, +# png:cairo:gd, png:cairo:cairo, png:cairo:gdiplus, png:gdiplus and +# png:gdiplus:gdiplus. +# The default value is: png. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_IMAGE_FORMAT = png + +# If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to +# enable generation of interactive SVG images that allow zooming and panning. +# +# Note that this requires a modern browser other than Internet Explorer. Tested +# and working are Firefox, Chrome, Safari, and Opera. +# Note: For IE 9+ you need to set HTML_FILE_EXTENSION to xhtml in order to make +# the SVG files visible. Older versions of IE do not have SVG support. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + +INTERACTIVE_SVG = NO + +# The DOT_PATH tag can be used to specify the path where the dot tool can be +# found. If left blank, it is assumed the dot tool can be found in the path. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_PATH = + +# The DOTFILE_DIRS tag can be used to specify one or more directories that +# contain dot files that are included in the documentation (see the \dotfile +# command). +# This tag requires that the tag HAVE_DOT is set to YES. + +DOTFILE_DIRS = + +# The MSCFILE_DIRS tag can be used to specify one or more directories that +# contain msc files that are included in the documentation (see the \mscfile +# command). + +MSCFILE_DIRS = + +# The DIAFILE_DIRS tag can be used to specify one or more directories that +# contain dia files that are included in the documentation (see the \diafile +# command). + +DIAFILE_DIRS = + +# When using plantuml, the PLANTUML_JAR_PATH tag should be used to specify the +# path where java can find the plantuml.jar file. If left blank, it is assumed +# PlantUML is not used or called during a preprocessing step. Doxygen will +# generate a warning when it encounters a \startuml command in this case and +# will not generate output for the diagram. + +PLANTUML_JAR_PATH = + +# When using plantuml, the PLANTUML_CFG_FILE tag can be used to specify a +# configuration file for plantuml. + +PLANTUML_CFG_FILE = + +# When using plantuml, the specified paths are searched for files specified by +# the !include statement in a plantuml block. + +PLANTUML_INCLUDE_PATH = + +# The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of nodes +# that will be shown in the graph. If the number of nodes in a graph becomes +# larger than this value, doxygen will truncate the graph, which is visualized +# by representing a node as a red box. Note that doxygen if the number of direct +# children of the root node in a graph is already larger than +# DOT_GRAPH_MAX_NODES then the graph will not be shown at all. Also note that +# the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH. +# Minimum value: 0, maximum value: 10000, default value: 50. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_GRAPH_MAX_NODES = 50 + +# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the graphs +# generated by dot. A depth value of 3 means that only nodes reachable from the +# root by following a path via at most 3 edges will be shown. Nodes that lay +# further from the root node will be omitted. Note that setting this option to 1 +# or 2 may greatly reduce the computation time needed for large code bases. Also +# note that the size of a graph can be further restricted by +# DOT_GRAPH_MAX_NODES. Using a depth of 0 means no depth restriction. +# Minimum value: 0, maximum value: 1000, default value: 0. +# This tag requires that the tag HAVE_DOT is set to YES. + +MAX_DOT_GRAPH_DEPTH = 0 + +# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent +# background. This is disabled by default, because dot on Windows does not seem +# to support this out of the box. +# +# Warning: Depending on the platform used, enabling this option may lead to +# badly anti-aliased labels on the edges of a graph (i.e. they become hard to +# read). +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_TRANSPARENT = NO + +# Set the DOT_MULTI_TARGETS tag to YES to allow dot to generate multiple output +# files in one run (i.e. multiple -o and -T options on the command line). This +# makes dot run faster, but since only newer versions of dot (>1.8.10) support +# this, this feature is disabled by default. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_MULTI_TARGETS = NO + +# If the GENERATE_LEGEND tag is set to YES doxygen will generate a legend page +# explaining the meaning of the various boxes and arrows in the dot generated +# graphs. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + +GENERATE_LEGEND = YES + +# If the DOT_CLEANUP tag is set to YES, doxygen will remove the intermediate dot +# files that are used to generate the various graphs. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_CLEANUP = YES diff --git a/doxygen/mainpage.md b/doxygen/mainpage.md new file mode 100644 index 00000000000..80cdb753fe5 --- /dev/null +++ b/doxygen/mainpage.md @@ -0,0 +1,9 @@ +Overview +== + +This Slice API reference was generated from the Slice files in the +[zeroc-ice/ice GitHub repository](https://github.com/zeroc-ice/ice/tree/3.7/slice). + +The [language mapping chapters](https://doc.zeroc.com/display/Ice37/Language+Mappings) +in the [Ice Manual](https://doc.zeroc.com/display/Ice37/Ice+Manual) describe how Slice +APIs map to programming language APIs. diff --git a/java/src/Ice/src/main/java/com/zeroc/Ice/InputStream.java b/java/src/Ice/src/main/java/com/zeroc/Ice/InputStream.java index 548db62b8ac..d37e34f4bcd 100644 --- a/java/src/Ice/src/main/java/com/zeroc/Ice/InputStream.java +++ b/java/src/Ice/src/main/java/com/zeroc/Ice/InputStream.java @@ -320,7 +320,7 @@ public class InputStream } /** - * Sets the value factory manager to use when marshaling value instances. If the stream + * 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. * @@ -592,7 +592,7 @@ public class InputStream } /** - * Ends the previous encapsulation. + * Ends the current encapsulation. **/ public void endEncapsulation() { @@ -679,7 +679,7 @@ public class InputStream * is returned in the argument. * * @param encoding The encapsulation's encoding version. - * @return The encoded encapuslation. + * @return The encoded encapsulation. **/ public byte[] readEncapsulation(EncodingVersion encoding) { diff --git a/java/src/Ice/src/main/java/com/zeroc/Ice/ObjectPrx.java b/java/src/Ice/src/main/java/com/zeroc/Ice/ObjectPrx.java index 734ba6a4610..5996072233d 100644 --- a/java/src/Ice/src/main/java/com/zeroc/Ice/ObjectPrx.java +++ b/java/src/Ice/src/main/java/com/zeroc/Ice/ObjectPrx.java @@ -310,7 +310,7 @@ public interface ObjectPrx /** * Returns the invocation timeout of this proxy. * - * @return The invocation timeout value (in seconds). + * @return The invocation timeout value (in milliseconds). **/ int ice_getInvocationTimeout(); @@ -338,7 +338,7 @@ public interface ObjectPrx /** * Returns a proxy that is identical to this proxy, except for the invocation timeout. * - * @param newTimeout The new invocation timeout (in seconds). + * @param newTimeout The new invocation timeout (in milliseconds). * @return The proxy with the new timeout. * **/ @@ -420,7 +420,7 @@ public interface ObjectPrx } /** - * Returns the encoding version used to marshal requests parameters. + * Returns the encoding version used to marshal request parameters. * * @return The encoding version. **/ @@ -495,7 +495,7 @@ public interface ObjectPrx * Returns a proxy that is identical to this proxy, except for collocation optimization. * * @param b <code>true</code> if the new proxy enables collocation optimization; <code>false</code> otherwise. - * @return The proxy the specified collocation optimization. + * @return The proxy with the specified collocation optimization. **/ default ObjectPrx ice_collocationOptimized(boolean b) { diff --git a/slice/Glacier2/Metrics.ice b/slice/Glacier2/Metrics.ice index 62181d61076..53a79344b2f 100644 --- a/slice/Glacier2/Metrics.ice +++ b/slice/Glacier2/Metrics.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:GLACIER2_API", "objc:header-dir:objc", "objc:dll-export:GLACIER2_API", "js:ice-build", "python:pkgdir:Glacier2"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:GLACIER2_API", "cpp:doxygen:include:Glacier2/Glacier2.h", "objc:header-dir:objc", "objc:dll-export:GLACIER2_API", "js:ice-build", "python:pkgdir:Glacier2"]] [["cpp:include:Glacier2/Config.h"]] #include <Ice/Metrics.ice> diff --git a/slice/Glacier2/PermissionsVerifier.ice b/slice/Glacier2/PermissionsVerifier.ice index 23cb992322d..02136a3a11f 100644 --- a/slice/Glacier2/PermissionsVerifier.ice +++ b/slice/Glacier2/PermissionsVerifier.ice @@ -9,7 +9,7 @@ #pragma once -[["cpp:header-ext:h", "cpp:dll-export:GLACIER2_API", "objc:header-dir:objc", "objc:dll-export:GLACIER2_API", "js:ice-build", "python:pkgdir:Glacier2"]] +[["cpp:header-ext:h", "cpp:dll-export:GLACIER2_API", "cpp:doxygen:include:Glacier2/Glacier2.h", "objc:header-dir:objc", "objc:dll-export:GLACIER2_API", "js:ice-build", "python:pkgdir:Glacier2"]] [["cpp:include:Glacier2/Config.h"]] #include <Glacier2/SSLInfo.ice> diff --git a/slice/Glacier2/PermissionsVerifierF.ice b/slice/Glacier2/PermissionsVerifierF.ice index dd7f05926c8..16581f8c915 100644 --- a/slice/Glacier2/PermissionsVerifierF.ice +++ b/slice/Glacier2/PermissionsVerifierF.ice @@ -9,7 +9,7 @@ #pragma once -[["cpp:header-ext:h", "cpp:dll-export:GLACIER2_API", "objc:header-dir:objc", "objc:dll-export:GLACIER2_API", "js:ice-build", "python:pkgdir:Glacier2"]] +[["cpp:header-ext:h", "cpp:dll-export:GLACIER2_API", "cpp:doxygen:include:Glacier2/Glacier2.h", "objc:header-dir:objc", "objc:dll-export:GLACIER2_API", "js:ice-build", "python:pkgdir:Glacier2"]] #ifndef __SLICE2JAVA_COMPAT__ [["java:package:com.zeroc"]] diff --git a/slice/Glacier2/Router.ice b/slice/Glacier2/Router.ice index 7a945dc7158..2df04a2cad9 100644 --- a/slice/Glacier2/Router.ice +++ b/slice/Glacier2/Router.ice @@ -9,7 +9,7 @@ #pragma once -[["cpp:header-ext:h", "cpp:dll-export:GLACIER2_API", "objc:header-dir:objc", "objc:dll-export:GLACIER2_API", "js:ice-build", "python:pkgdir:Glacier2"]] +[["cpp:header-ext:h", "cpp:dll-export:GLACIER2_API", "cpp:doxygen:include:Glacier2/Glacier2.h", "objc:header-dir:objc", "objc:dll-export:GLACIER2_API", "js:ice-build", "python:pkgdir:Glacier2"]] [["cpp:include:Glacier2/Config.h"]] #include <Ice/Router.ice> diff --git a/slice/Glacier2/RouterF.ice b/slice/Glacier2/RouterF.ice index 2d2898cb034..b96e68592b9 100644 --- a/slice/Glacier2/RouterF.ice +++ b/slice/Glacier2/RouterF.ice @@ -9,7 +9,7 @@ #pragma once -[["cpp:header-ext:h", "cpp:dll-export:GLACIER2_API", "objc:header-dir:objc", "objc:dll-export:GLACIER2_API", "js:ice-build", "python:pkgdir:Glacier2"]] +[["cpp:header-ext:h", "cpp:dll-export:GLACIER2_API", "cpp:doxygen:include:Glacier2/Glacier2.h", "objc:header-dir:objc", "objc:dll-export:GLACIER2_API", "js:ice-build", "python:pkgdir:Glacier2"]] #ifndef __SLICE2JAVA_COMPAT__ [["java:package:com.zeroc"]] diff --git a/slice/Glacier2/SSLInfo.ice b/slice/Glacier2/SSLInfo.ice index 05cbe00e66d..a4bc9d3f042 100644 --- a/slice/Glacier2/SSLInfo.ice +++ b/slice/Glacier2/SSLInfo.ice @@ -9,7 +9,7 @@ #pragma once -[["cpp:header-ext:h", "cpp:dll-export:GLACIER2_API", "objc:header-dir:objc", "objc:dll-export:GLACIER2_API", "js:ice-build", "python:pkgdir:Glacier2"]] +[["cpp:header-ext:h", "cpp:dll-export:GLACIER2_API", "cpp:doxygen:include:Glacier2/Glacier2.h", "objc:header-dir:objc", "objc:dll-export:GLACIER2_API", "js:ice-build", "python:pkgdir:Glacier2"]] [["cpp:include:Glacier2/Config.h"]] #include <Ice/BuiltinSequences.ice> diff --git a/slice/Glacier2/Session.ice b/slice/Glacier2/Session.ice index 9946541daf5..d706ddfc628 100644 --- a/slice/Glacier2/Session.ice +++ b/slice/Glacier2/Session.ice @@ -9,7 +9,7 @@ #pragma once -[["cpp:header-ext:h", "cpp:dll-export:GLACIER2_API", "objc:header-dir:objc", "objc:dll-export:GLACIER2_API", "js:ice-build", "python:pkgdir:Glacier2"]] +[["cpp:header-ext:h", "cpp:dll-export:GLACIER2_API", "cpp:doxygen:include:Glacier2/Glacier2.h", "objc:header-dir:objc", "objc:dll-export:GLACIER2_API", "js:ice-build", "python:pkgdir:Glacier2"]] [["cpp:include:Glacier2/Config.h"]] #include <Ice/BuiltinSequences.ice> diff --git a/slice/Ice/BuiltinSequences.ice b/slice/Ice/BuiltinSequences.ice index 41c39c23647..bb94ad8eed4 100644 --- a/slice/Ice/BuiltinSequences.ice +++ b/slice/Ice/BuiltinSequences.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] #ifndef __SLICE2JAVA_COMPAT__ [["java:package:com.zeroc"]] diff --git a/slice/Ice/Communicator.ice b/slice/Ice/Communicator.ice index cbe269420c8..d14b100f593 100644 --- a/slice/Ice/Communicator.ice +++ b/slice/Ice/Communicator.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] #include <Ice/LoggerF.ice> #include <Ice/InstrumentationF.ice> @@ -51,7 +51,6 @@ module Ice * @see Logger * @see ObjectAdapter * @see Properties - * @see ObjectFactory * @see ValueFactory * **/ diff --git a/slice/Ice/CommunicatorF.ice b/slice/Ice/CommunicatorF.ice index 0575c7be455..825f0af1fce 100644 --- a/slice/Ice/CommunicatorF.ice +++ b/slice/Ice/CommunicatorF.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] #ifndef __SLICE2JAVA_COMPAT__ [["java:package:com.zeroc"]] diff --git a/slice/Ice/Connection.ice b/slice/Ice/Connection.ice index fc48f8d159f..5170a4ce32c 100644 --- a/slice/Ice/Connection.ice +++ b/slice/Ice/Connection.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] #include <Ice/ObjectAdapterF.ice> #include <Ice/Identity.ice> @@ -130,27 +130,54 @@ local interface HeartbeatCallback void heartbeat(Connection con); } +/** + * Specifies the close semantics for Active Connection Management. + */ local enum ACMClose { + /** Disables automatic connection closure. */ CloseOff, + /** Gracefully closes a connection that has been idle for the configured timeout period. */ CloseOnIdle, + /** + * Forcefully closes a connection that has been idle for the configured timeout period, + * but only if the connection has pending invocations. + */ CloseOnInvocation, + /** Combines the behaviors of CloseOnIdle and CloseOnInvocation. */ CloseOnInvocationAndIdle, + /** + * Forcefully closes a connection that has been idle for the configured timeout period, + * regardless of whether the connection has pending invocations or dispatch. + */ CloseOnIdleForceful } +/** + * Specifies the heartbeat semantics for Active Connection Management. + */ local enum ACMHeartbeat { + /** Disables heartbeats. */ HeartbeatOff, + /** Send a heartbeat at regular intervals if the connection is idle and only if there are pending dispatch. */ HeartbeatOnDispatch, + /** Send a heartbeat at regular intervals when the connection is idle. */ HeartbeatOnIdle, + /** Send a heartbeat at regular intervals until the connection is closed. */ HeartbeatAlways } +/** + * A collection of Active Connection Management configuration settings. + */ local struct ACM { + /** A timeout value in seconds. */ int timeout; + /** The close semantics. */ ACMClose close; + /** The heartbeat semantics. */ ACMHeartbeat heartbeat; } @@ -462,6 +489,7 @@ local class UDPConnectionInfo extends IPConnectionInfo int sndSize = 0; } +/** A collection of HTTP headers. */ dictionary<string, string> HeaderDict; /** diff --git a/slice/Ice/ConnectionF.ice b/slice/Ice/ConnectionF.ice index 9332deaf0d5..67e4e89ef41 100644 --- a/slice/Ice/ConnectionF.ice +++ b/slice/Ice/ConnectionF.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] #ifndef __SLICE2JAVA_COMPAT__ [["java:package:com.zeroc"]] diff --git a/slice/Ice/Current.ice b/slice/Ice/Current.ice index f9c920c1dc8..bab61529e0d 100644 --- a/slice/Ice/Current.ice +++ b/slice/Ice/Current.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] #include <Ice/ObjectAdapterF.ice> #include <Ice/ConnectionF.ice> @@ -36,8 +36,7 @@ dictionary<string, string> Context; /** * - * The {@link OperationMode} determines the retry behavior an - * invocation in case of a (potentially) recoverable error. + * Determines the retry behavior an invocation in case of a (potentially) recoverable error. * **/ // diff --git a/slice/Ice/Endpoint.ice b/slice/Ice/Endpoint.ice index 00996557ec2..e6a05dc629c 100644 --- a/slice/Ice/Endpoint.ice +++ b/slice/Ice/Endpoint.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] #include <Ice/Version.ice> #include <Ice/BuiltinSequences.ice> diff --git a/slice/Ice/EndpointF.ice b/slice/Ice/EndpointF.ice index 1b9b2f07347..c3ec09af54f 100644 --- a/slice/Ice/EndpointF.ice +++ b/slice/Ice/EndpointF.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] #ifndef __SLICE2JAVA_COMPAT__ [["java:package:com.zeroc"]] diff --git a/slice/Ice/EndpointTypes.ice b/slice/Ice/EndpointTypes.ice index 35a0a1f8f01..e33308a099e 100644 --- a/slice/Ice/EndpointTypes.ice +++ b/slice/Ice/EndpointTypes.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] #ifndef __SLICE2JAVA_COMPAT__ [["java:package:com.zeroc"]] diff --git a/slice/Ice/FacetMap.ice b/slice/Ice/FacetMap.ice index 664e14dedc1..eee7c2d8bb8 100644 --- a/slice/Ice/FacetMap.ice +++ b/slice/Ice/FacetMap.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] #ifndef __SLICE2JAVA_COMPAT__ [["java:package:com.zeroc"]] diff --git a/slice/Ice/Identity.ice b/slice/Ice/Identity.ice index b650ad7c2db..f956e80d873 100644 --- a/slice/Ice/Identity.ice +++ b/slice/Ice/Identity.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] #ifndef __SLICE2JAVA_COMPAT__ [["java:package:com.zeroc"]] diff --git a/slice/Ice/ImplicitContext.ice b/slice/Ice/ImplicitContext.ice index 61fedcfe255..db5153a21ac 100644 --- a/slice/Ice/ImplicitContext.ice +++ b/slice/Ice/ImplicitContext.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] #include <Ice/LocalException.ice> #include <Ice/Current.ice> diff --git a/slice/Ice/ImplicitContextF.ice b/slice/Ice/ImplicitContextF.ice index 104cf34ef00..45b4d255892 100644 --- a/slice/Ice/ImplicitContextF.ice +++ b/slice/Ice/ImplicitContextF.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] #ifndef __SLICE2JAVA_COMPAT__ [["java:package:com.zeroc"]] diff --git a/slice/Ice/Instrumentation.ice b/slice/Ice/Instrumentation.ice index 09c478fe2f7..63f39a379e4 100644 --- a/slice/Ice/Instrumentation.ice +++ b/slice/Ice/Instrumentation.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] #include <Ice/EndpointF.ice> #include <Ice/ConnectionF.ice> diff --git a/slice/Ice/InstrumentationF.ice b/slice/Ice/InstrumentationF.ice index 03bd355ea4d..b1bd24fa157 100644 --- a/slice/Ice/InstrumentationF.ice +++ b/slice/Ice/InstrumentationF.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] #ifndef __SLICE2JAVA_COMPAT__ [["java:package:com.zeroc"]] diff --git a/slice/Ice/LocalException.ice b/slice/Ice/LocalException.ice index e74e69887ed..993b4356d0b 100644 --- a/slice/Ice/LocalException.ice +++ b/slice/Ice/LocalException.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] #include <Ice/Identity.ice> #include <Ice/Version.ice> diff --git a/slice/Ice/Locator.ice b/slice/Ice/Locator.ice index ee274f2fb73..1edaf874dc4 100644 --- a/slice/Ice/Locator.ice +++ b/slice/Ice/Locator.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] #include <Ice/Identity.ice> #include <Ice/Process.ice> diff --git a/slice/Ice/LocatorF.ice b/slice/Ice/LocatorF.ice index b82ac90fa56..59410ac1301 100644 --- a/slice/Ice/LocatorF.ice +++ b/slice/Ice/LocatorF.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] #ifndef __SLICE2JAVA_COMPAT__ [["java:package:com.zeroc"]] diff --git a/slice/Ice/Logger.ice b/slice/Ice/Logger.ice index 4ea8bae1114..b1d3a77f027 100644 --- a/slice/Ice/Logger.ice +++ b/slice/Ice/Logger.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] #ifndef __SLICE2JAVA_COMPAT__ [["java:package:com.zeroc"]] diff --git a/slice/Ice/LoggerF.ice b/slice/Ice/LoggerF.ice index a3ef1fec89b..8a9df1432f7 100644 --- a/slice/Ice/LoggerF.ice +++ b/slice/Ice/LoggerF.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] #ifndef __SLICE2JAVA_COMPAT__ [["java:package:com.zeroc"]] diff --git a/slice/Ice/Metrics.ice b/slice/Ice/Metrics.ice index 534dca93ca4..27e4933afa4 100644 --- a/slice/Ice/Metrics.ice +++ b/slice/Ice/Metrics.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] #include <Ice/BuiltinSequences.ice> diff --git a/slice/Ice/ObjectAdapter.ice b/slice/Ice/ObjectAdapter.ice index 2baf7109a31..af2dc407b3f 100644 --- a/slice/Ice/ObjectAdapter.ice +++ b/slice/Ice/ObjectAdapter.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] #include <Ice/CommunicatorF.ice> #include <Ice/ServantLocatorF.ice> diff --git a/slice/Ice/ObjectAdapterF.ice b/slice/Ice/ObjectAdapterF.ice index 314bcf9f31c..8746cd52057 100644 --- a/slice/Ice/ObjectAdapterF.ice +++ b/slice/Ice/ObjectAdapterF.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] #ifndef __SLICE2JAVA_COMPAT__ [["java:package:com.zeroc"]] diff --git a/slice/Ice/ObjectFactory.ice b/slice/Ice/ObjectFactory.ice index 68028d63194..10599624752 100644 --- a/slice/Ice/ObjectFactory.ice +++ b/slice/Ice/ObjectFactory.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] #ifndef __SLICE2JAVA_COMPAT__ [["java:package:com.zeroc"]] @@ -36,7 +36,7 @@ local interface ObjectFactory * absolute Slice type id, i.e., the id relative to the * unnamed top-level Slice module. For example, the absolute * Slice type id for interfaces of type <tt>Bar</tt> in the module - * <tt>Foo</tt> is <tt>::Foo::Bar</tt>. + * <tt>Foo</tt> is <tt>"::Foo::Bar"</tt>. * * <p class="Note">The leading "<tt>::</tt>" is required. * diff --git a/slice/Ice/Plugin.ice b/slice/Ice/Plugin.ice index d143b0f71eb..cca5745a954 100644 --- a/slice/Ice/Plugin.ice +++ b/slice/Ice/Plugin.ice @@ -10,7 +10,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] #include <Ice/LoggerF.ice> #include <Ice/BuiltinSequences.ice> diff --git a/slice/Ice/PluginF.ice b/slice/Ice/PluginF.ice index 1b69e102f53..b865492b819 100644 --- a/slice/Ice/PluginF.ice +++ b/slice/Ice/PluginF.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] #ifndef __SLICE2JAVA_COMPAT__ [["java:package:com.zeroc"]] diff --git a/slice/Ice/Process.ice b/slice/Ice/Process.ice index 3779ff1c6e0..7d6f8041e69 100644 --- a/slice/Ice/Process.ice +++ b/slice/Ice/Process.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] #ifndef __SLICE2JAVA_COMPAT__ [["java:package:com.zeroc"]] diff --git a/slice/Ice/ProcessF.ice b/slice/Ice/ProcessF.ice index 1f1f6804fe1..13fd0b5ae19 100644 --- a/slice/Ice/ProcessF.ice +++ b/slice/Ice/ProcessF.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] #ifndef __SLICE2JAVA_COMPAT__ [["java:package:com.zeroc"]] diff --git a/slice/Ice/Properties.ice b/slice/Ice/Properties.ice index 4cdb67b0a05..9355ce9024a 100644 --- a/slice/Ice/Properties.ice +++ b/slice/Ice/Properties.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] #include <Ice/PropertiesAdmin.ice> diff --git a/slice/Ice/PropertiesAdmin.ice b/slice/Ice/PropertiesAdmin.ice index 77340cf9019..942414124a5 100644 --- a/slice/Ice/PropertiesAdmin.ice +++ b/slice/Ice/PropertiesAdmin.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] #include <Ice/BuiltinSequences.ice> diff --git a/slice/Ice/PropertiesF.ice b/slice/Ice/PropertiesF.ice index dd97d0d8a3c..4472208a5cd 100644 --- a/slice/Ice/PropertiesF.ice +++ b/slice/Ice/PropertiesF.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] #ifndef __SLICE2JAVA_COMPAT__ [["java:package:com.zeroc"]] diff --git a/slice/Ice/RemoteLogger.ice b/slice/Ice/RemoteLogger.ice index 8fe2ea17ea6..b7b1ebf7a16 100644 --- a/slice/Ice/RemoteLogger.ice +++ b/slice/Ice/RemoteLogger.ice @@ -11,7 +11,7 @@ #include <Ice/BuiltinSequences.ice> -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] [["cpp:include:list"]] #ifndef __SLICE2JAVA_COMPAT__ @@ -122,37 +122,28 @@ interface RemoteLogger { /** * - * init is called by {@link LoggerAdmin#attachRemoteLogger} when a - * RemoteLogger proxy is attached. + * init is called by attachRemoteLogger when a RemoteLogger proxy is attached. * - * @param prefix The prefix of the associated local {@link Logger} + * @param prefix The prefix of the associated local Logger. * * @param logMessages Old log messages generated before "now". * - * @see LoggerAdmin#attachRemoteLogger - * - * **/ void init(string prefix, LogMessageSeq logMessages); /** * - * Log a {@link LogMessage}. Note that log may be called by {@link LoggerAdmin} - * before {@link RemoteLogger#init}. + * Log a LogMessage. Note that log may be called by LoggerAdmin before init. * * @param message The message to log. * - * @see Logger - * **/ void log(LogMessage message); } /** * - * An exception thrown by {@link LoggerAdmin#attachRemoteLogger} to report - * that the provided {@link RemoteLogger} was previously attached to this - * {@link LoggerAdmin}. + * Thrown when the provided RemoteLogger was previously attached to a LoggerAdmin. * **/ exception RemoteLoggerAlreadyAttachedException @@ -169,9 +160,8 @@ interface LoggerAdmin { /** * - * attachRemoteLogger is called to attach a {@link RemoteLogger} object to - * the local {@link Logger}. - * attachRemoteLogger calls init on the provided {@link RemoteLogger} proxy. + * Attaches a RemoteLogger object to the local logger. + * attachRemoteLogger calls init on the provided RemoteLogger proxy. * * @param prx A proxy to the remote logger. * @@ -183,7 +173,7 @@ interface LoggerAdmin * An empty list means no filtering (send all trace categories). * * @param messageMax The maximum number of log messages (of all types) to be provided - * to {@link RemoteLogger#init}. A negative value requests all messages available. + * to init. A negative value requests all messages available. * * @throws RemoteLoggerAlreadyAttachedException Raised if this remote logger is already * attached to this admin object. @@ -195,8 +185,7 @@ interface LoggerAdmin /** * - * detachRemoteLogger is called to detach a {@link RemoteLogger} object from - * the local {@link Logger}. + * Detaches a RemoteLogger object from the local logger. * * @param prx A proxy to the remote logger. * @@ -207,7 +196,7 @@ interface LoggerAdmin /** * - * getLog retrieves log messages recently logged. + * Retrieves log messages recently logged. * * @param messageTypes The list of message types that the caller wishes to receive. * An empty list means no filtering (send all message types). @@ -219,7 +208,7 @@ interface LoggerAdmin * @param messageMax The maximum number of log messages (of all types) to be returned. * A negative value requests all messages available. * - * @param prefix The prefix of the associated local {@link Logger}. + * @param prefix The prefix of the associated local logger. * * @return The Log messages. * diff --git a/slice/Ice/Router.ice b/slice/Ice/Router.ice index f9cd4b0bc18..e7bbddaa110 100644 --- a/slice/Ice/Router.ice +++ b/slice/Ice/Router.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] #include <Ice/BuiltinSequences.ice> diff --git a/slice/Ice/RouterF.ice b/slice/Ice/RouterF.ice index 08efd92d449..7571fa327d4 100644 --- a/slice/Ice/RouterF.ice +++ b/slice/Ice/RouterF.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] #ifndef __SLICE2JAVA_COMPAT__ [["java:package:com.zeroc"]] diff --git a/slice/Ice/ServantLocator.ice b/slice/Ice/ServantLocator.ice index 931a012c837..6e0d3a842a2 100644 --- a/slice/Ice/ServantLocator.ice +++ b/slice/Ice/ServantLocator.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] #include <Ice/ObjectAdapterF.ice> #include <Ice/Current.ice> diff --git a/slice/Ice/ServantLocatorF.ice b/slice/Ice/ServantLocatorF.ice index a112a9797eb..9ec2bd0658e 100644 --- a/slice/Ice/ServantLocatorF.ice +++ b/slice/Ice/ServantLocatorF.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] #ifndef __SLICE2JAVA_COMPAT__ [["java:package:com.zeroc"]] diff --git a/slice/Ice/SliceChecksumDict.ice b/slice/Ice/SliceChecksumDict.ice index 8061287b8b7..718601972e1 100644 --- a/slice/Ice/SliceChecksumDict.ice +++ b/slice/Ice/SliceChecksumDict.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] #ifndef __SLICE2JAVA_COMPAT__ [["java:package:com.zeroc"]] diff --git a/slice/Ice/ValueFactory.ice b/slice/Ice/ValueFactory.ice index 54de5c213e4..c31fb40185b 100644 --- a/slice/Ice/ValueFactory.ice +++ b/slice/Ice/ValueFactory.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "python:pkgdir:Ice"]] #ifndef __SLICE2JAVA_COMPAT__ [["java:package:com.zeroc"]] @@ -37,7 +37,7 @@ local interface ValueFactory * absolute Slice type id, i.e., the id relative to the * unnamed top-level Slice module. For example, the absolute * Slice type id for an interface <tt>Bar</tt> in the module - * <tt>Foo</tt> is <tt>::Foo::Bar</tt>. + * <tt>Foo</tt> is <tt>"::Foo::Bar"</tt>. * * <p class="Note">The leading "<tt>::</tt>" is required. * diff --git a/slice/Ice/Version.ice b/slice/Ice/Version.ice index 87bbcd974ba..195a2943c36 100644 --- a/slice/Ice/Version.ice +++ b/slice/Ice/Version.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICE_API", "cpp:doxygen:include:Ice/Ice.h", "objc:header-dir:objc", "objc:dll-export:ICE_API", "js:ice-build", "python:pkgdir:Ice"]] #ifndef __SLICE2JAVA_COMPAT__ [["java:package:com.zeroc"]] diff --git a/slice/IceBT/ConnectionInfo.ice b/slice/IceBT/ConnectionInfo.ice index 64ae497d346..dc0aec33fff 100644 --- a/slice/IceBT/ConnectionInfo.ice +++ b/slice/IceBT/ConnectionInfo.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICEBT_API", "objc:header-dir:objc", "python:pkgdir:IceBT"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICEBT_API", "cpp:doxygen:include:IceBT/IceBT.h", "objc:header-dir:objc", "python:pkgdir:IceBT"]] #include <Ice/Connection.ice> diff --git a/slice/IceBT/EndpointInfo.ice b/slice/IceBT/EndpointInfo.ice index e519e5d064c..984f20c265e 100644 --- a/slice/IceBT/EndpointInfo.ice +++ b/slice/IceBT/EndpointInfo.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICEBT_API", "objc:header-dir:objc", "js:ice-build", "python:pkgdir:IceBT"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICEBT_API", "cpp:doxygen:include:IceBT/IceBT.h", "objc:header-dir:objc", "js:ice-build", "python:pkgdir:IceBT"]] #include <Ice/Endpoint.ice> diff --git a/slice/IceBT/Types.ice b/slice/IceBT/Types.ice index 60d7c2d7edf..21a53c73927 100644 --- a/slice/IceBT/Types.ice +++ b/slice/IceBT/Types.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICEBT_API", "objc:header-dir:objc", "python:pkgdir:IceBT"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICEBT_API", "cpp:doxygen:include:IceBT/IceBT.h", "objc:header-dir:objc", "python:pkgdir:IceBT"]] #ifndef __SLICE2JAVA_COMPAT__ [["java:package:com.zeroc"]] diff --git a/slice/IceBox/IceBox.ice b/slice/IceBox/IceBox.ice index 60fd6db7a17..f12f944b8f4 100644 --- a/slice/IceBox/IceBox.ice +++ b/slice/IceBox/IceBox.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICEBOX_API", "objc:header-dir:objc", "python:pkgdir:IceBox"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICEBOX_API", "cpp:doxygen:include:IceBox/IceBox.h", "objc:header-dir:objc", "python:pkgdir:IceBox"]] [["cpp:include:IceBox/Config.h"]] #include <Ice/BuiltinSequences.ice> @@ -186,8 +186,7 @@ interface ServiceManager /** * - * Shut down all services. This causes {@link Service#stop} to be - * invoked on all configured services. + * Shut down all services. This causes stop to be invoked on all configured services. * **/ void shutdown(); diff --git a/slice/IceDiscovery/IceDiscovery.ice b/slice/IceDiscovery/IceDiscovery.ice index 4a82bfe48b3..8cb3004f470 100644 --- a/slice/IceDiscovery/IceDiscovery.ice +++ b/slice/IceDiscovery/IceDiscovery.ice @@ -8,7 +8,7 @@ // ********************************************************************** #pragma once -[["ice-prefix", "cpp:header-ext:h", "objc:header-dir:objc", "python:pkgdir:IceDiscovery"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:doxygen:include:IceDiscovery/IceDiscovery.h", "objc:header-dir:objc", "python:pkgdir:IceDiscovery"]] #include <Ice/Identity.ice> diff --git a/slice/IceGrid/Admin.ice b/slice/IceGrid/Admin.ice index 854182009c5..76ccce7eecb 100644 --- a/slice/IceGrid/Admin.ice +++ b/slice/IceGrid/Admin.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICEGRID_API", "objc:header-dir:objc", "objc:dll-export:ICEGRID_API", "js:ice-build", "python:pkgdir:IceGrid"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICEGRID_API", "cpp:doxygen:include:IceGrid/IceGrid.h", "objc:header-dir:objc", "objc:dll-export:ICEGRID_API", "js:ice-build", "python:pkgdir:IceGrid"]] [["cpp:include:IceGrid/Config.h"]] #include <Ice/Identity.ice> diff --git a/slice/IceGrid/Descriptor.ice b/slice/IceGrid/Descriptor.ice index dca76142306..835f22ad20b 100644 --- a/slice/IceGrid/Descriptor.ice +++ b/slice/IceGrid/Descriptor.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "objc:header-dir:objc", "js:ice-build", "python:pkgdir:IceGrid"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:doxygen:include:IceGrid/IceGrid.h", "objc:header-dir:objc", "js:ice-build", "python:pkgdir:IceGrid"]] #ifndef ICE_BUILDING_ICEGRIDDB [["cpp:dll-export:ICEGRID_API", "objc:dll-export:ICEGRID_API"]] diff --git a/slice/IceGrid/Exception.ice b/slice/IceGrid/Exception.ice index 4b6e91f6b41..1ec511a8d7f 100644 --- a/slice/IceGrid/Exception.ice +++ b/slice/IceGrid/Exception.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "objc:header-dir:objc", "js:ice-build", "python:pkgdir:IceGrid"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:doxygen:include:IceGrid/IceGrid.h", "objc:header-dir:objc", "js:ice-build", "python:pkgdir:IceGrid"]] #ifndef ICE_BUILDING_ICEGRIDDB [["cpp:dll-export:ICEGRID_API", "objc:dll-export:ICEGRID_API"]] diff --git a/slice/IceGrid/FileParser.ice b/slice/IceGrid/FileParser.ice index e1b5caf90d6..36ff3f3bae3 100644 --- a/slice/IceGrid/FileParser.ice +++ b/slice/IceGrid/FileParser.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICEGRID_API", "objc:header-dir:objc", "objc:dll-export:ICEGRID_API", "js:ice-build", "python:pkgdir:IceGrid"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICEGRID_API", "cpp:doxygen:include:IceGrid/IceGrid.h", "objc:header-dir:objc", "objc:dll-export:ICEGRID_API", "js:ice-build", "python:pkgdir:IceGrid"]] [["cpp:include:IceGrid/Config.h"]] #include <IceGrid/Admin.ice> diff --git a/slice/IceGrid/PluginFacade.ice b/slice/IceGrid/PluginFacade.ice index 97f1103f937..94b21bfae8c 100644 --- a/slice/IceGrid/PluginFacade.ice +++ b/slice/IceGrid/PluginFacade.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICEGRID_API", "objc:header-dir:objc", "objc:dll-export:ICEGRID_API", "python:pkgdir:IceGrid"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICEGRID_API", "cpp:doxygen:include:IceGrid/IceGrid.h", "objc:header-dir:objc", "objc:dll-export:ICEGRID_API", "python:pkgdir:IceGrid"]] [["cpp:include:IceGrid/Config.h"]] #include <Ice/BuiltinSequences.ice> diff --git a/slice/IceGrid/Registry.ice b/slice/IceGrid/Registry.ice index d6370dcba40..757dbf8e2e4 100644 --- a/slice/IceGrid/Registry.ice +++ b/slice/IceGrid/Registry.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICEGRID_API", "objc:header-dir:objc", "objc:dll-export:ICEGRID_API", "js:ice-build", "python:pkgdir:IceGrid"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICEGRID_API", "cpp:doxygen:include:IceGrid/IceGrid.h", "objc:header-dir:objc", "objc:dll-export:ICEGRID_API", "js:ice-build", "python:pkgdir:IceGrid"]] [["cpp:include:IceGrid/Config.h"]] #include <IceGrid/Exception.ice> diff --git a/slice/IceGrid/Session.ice b/slice/IceGrid/Session.ice index 43f935d4778..094037d8222 100644 --- a/slice/IceGrid/Session.ice +++ b/slice/IceGrid/Session.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICEGRID_API", "objc:header-dir:objc", "objc:dll-export:ICEGRID_API", "js:ice-build", "python:pkgdir:IceGrid"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICEGRID_API", "cpp:doxygen:include:IceGrid/IceGrid.h", "objc:header-dir:objc", "objc:dll-export:ICEGRID_API", "js:ice-build", "python:pkgdir:IceGrid"]] [["cpp:include:IceGrid/Config.h"]] #include <Glacier2/Session.ice> diff --git a/slice/IceGrid/UserAccountMapper.ice b/slice/IceGrid/UserAccountMapper.ice index e3ddc087c6f..3d633a5edea 100644 --- a/slice/IceGrid/UserAccountMapper.ice +++ b/slice/IceGrid/UserAccountMapper.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICEGRID_API", "objc:header-dir:objc", "objc:dll-export:ICEGRID_API", "js:ice-build", "python:pkgdir:IceGrid"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICEGRID_API", "cpp:doxygen:include:IceGrid/IceGrid.h", "objc:header-dir:objc", "objc:dll-export:ICEGRID_API", "js:ice-build", "python:pkgdir:IceGrid"]] [["cpp:include:IceGrid/Config.h"]] #ifndef __SLICE2JAVA_COMPAT__ diff --git a/slice/IceIAP/ConnectionInfo.ice b/slice/IceIAP/ConnectionInfo.ice index 2aa5a7e251a..e4ac5f63eec 100644 --- a/slice/IceIAP/ConnectionInfo.ice +++ b/slice/IceIAP/ConnectionInfo.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICEIAP_API", "objc:header-dir:objc", "js:ice-build"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICEIAP_API", "cpp:doxygen:include:IceIAP/IceIAP.h", "objc:header-dir:objc", "js:ice-build"]] #include <Ice/Connection.ice> diff --git a/slice/IceIAP/EndpointInfo.ice b/slice/IceIAP/EndpointInfo.ice index ed9e2ebb5d0..aed3d4ddda3 100644 --- a/slice/IceIAP/EndpointInfo.ice +++ b/slice/IceIAP/EndpointInfo.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICEIAP_API", "objc:header-dir:objc", "js:ice-build"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICEIAP_API", "cpp:doxygen:include:IceIAP/IceIAP.h", "objc:header-dir:objc", "js:ice-build"]] #include <Ice/Endpoint.ice> diff --git a/slice/IceLocatorDiscovery/IceLocatorDiscovery.ice b/slice/IceLocatorDiscovery/IceLocatorDiscovery.ice index 52b0361f83e..715d602e881 100644 --- a/slice/IceLocatorDiscovery/IceLocatorDiscovery.ice +++ b/slice/IceLocatorDiscovery/IceLocatorDiscovery.ice @@ -8,7 +8,7 @@ // ********************************************************************** #pragma once -[["ice-prefix", "cpp:header-ext:h", "objc:header-dir:objc", "python:pkgdir:IceLocatorDiscovery"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:doxygen:include:IceLocatorDiscovery/IceLocatorDiscovery.h", "objc:header-dir:objc", "python:pkgdir:IceLocatorDiscovery"]] #include <Ice/Locator.ice> diff --git a/slice/IcePatch2/FileInfo.ice b/slice/IcePatch2/FileInfo.ice index 822e6f69bda..654e82fd2ce 100644 --- a/slice/IcePatch2/FileInfo.ice +++ b/slice/IcePatch2/FileInfo.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICEPATCH2_API", "objc:header-dir:objc", "python:pkgdir:IcePatch2"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICEPATCH2_API", "cpp:doxygen:include:IcePatch2/IcePatch2.h", "objc:header-dir:objc", "python:pkgdir:IcePatch2"]] [["cpp:include:IcePatch2/Config.h"]] #include <Ice/BuiltinSequences.ice> diff --git a/slice/IcePatch2/FileServer.ice b/slice/IcePatch2/FileServer.ice index e4e5aa45489..5f304dd7887 100644 --- a/slice/IcePatch2/FileServer.ice +++ b/slice/IcePatch2/FileServer.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICEPATCH2_API", "objc:header-dir:objc", "python:pkgdir:IcePatch2"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICEPATCH2_API", "cpp:doxygen:include:IcePatch2/IcePatch2.h", "objc:header-dir:objc", "python:pkgdir:IcePatch2"]] [["cpp:include:IcePatch2/Config.h"]] #include <IcePatch2/FileInfo.ice> diff --git a/slice/IceSSL/ConnectionInfo.ice b/slice/IceSSL/ConnectionInfo.ice index 6152fd31437..b955e5e33bc 100644 --- a/slice/IceSSL/ConnectionInfo.ice +++ b/slice/IceSSL/ConnectionInfo.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICESSL_API", "objc:header-dir:objc", "objc:dll-export:ICESSL_API", "js:ice-build", "python:pkgdir:IceSSL"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICESSL_API", "cpp:doxygen:include:IceSSL/IceSSL.h", "objc:header-dir:objc", "objc:dll-export:ICESSL_API", "js:ice-build", "python:pkgdir:IceSSL"]] [["cpp:include:IceSSL/Plugin.h"]] diff --git a/slice/IceSSL/ConnectionInfoF.ice b/slice/IceSSL/ConnectionInfoF.ice index 772e5f0d36a..531bc1b82ce 100644 --- a/slice/IceSSL/ConnectionInfoF.ice +++ b/slice/IceSSL/ConnectionInfoF.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICESSL_API", "objc:header-dir:objc", "objc:dll-export:ICESSL_API", "js:ice-build", "python:pkgdir:IceSSL"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICESSL_API", "cpp:doxygen:include:IceSSL/IceSSL.h", "objc:header-dir:objc", "objc:dll-export:ICESSL_API", "js:ice-build", "python:pkgdir:IceSSL"]] #ifndef __SLICE2JAVA_COMPAT__ [["java:package:com.zeroc"]] diff --git a/slice/IceSSL/EndpointInfo.ice b/slice/IceSSL/EndpointInfo.ice index 1456571e1d2..550b48caa74 100644 --- a/slice/IceSSL/EndpointInfo.ice +++ b/slice/IceSSL/EndpointInfo.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICESSL_API", "objc:header-dir:objc", "objc:dll-export:ICESSL_API", "js:ice-build", "python:pkgdir:IceSSL"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICESSL_API", "cpp:doxygen:include:IceSSL/IceSSL.h", "objc:header-dir:objc", "objc:dll-export:ICESSL_API", "js:ice-build", "python:pkgdir:IceSSL"]] #include <Ice/Endpoint.ice> diff --git a/slice/IceStorm/IceStorm.ice b/slice/IceStorm/IceStorm.ice index 6a4769345c6..21e29450d56 100644 --- a/slice/IceStorm/IceStorm.ice +++ b/slice/IceStorm/IceStorm.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICESTORM_API", "objc:header-dir:objc", "objc:dll-export:ICESTORM_API", "js:ice-build", "python:pkgdir:IceStorm"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICESTORM_API", "cpp:doxygen:include:IceStorm/IceStorm.h", "objc:header-dir:objc", "objc:dll-export:ICESTORM_API", "js:ice-build", "python:pkgdir:IceStorm"]] [["cpp:include:IceStorm/Config.h"]] #include <Ice/Identity.ice> @@ -178,7 +178,7 @@ interface Topic /** * * Get a proxy to a publisher object for this topic. To publish - * data to a topic, the publisher calls {@link Topic#getPublisher} and then + * data to a topic, the publisher calls getPublisher and then * casts to the topic type. An unchecked cast must be used on this * proxy. If a replicated IceStorm deployment is used this call * may return a replicated proxy. @@ -192,7 +192,7 @@ interface Topic * * Get a non-replicated proxy to a publisher object for this * topic. To publish data to a topic, the publisher calls - * {@link Topic#getPublisher} and then casts to the topic type. An unchecked + * getPublisher and then casts to the topic type. An unchecked * cast must be used on this proxy. * * @return A proxy to publish data on this topic. @@ -339,8 +339,7 @@ interface TopicManager { /** * - * Create a new topic. The topic name must be unique, otherwise - * {@link TopicExists} is raised. + * Create a new topic. The topic name must be unique. * * @param name The name of the topic. * diff --git a/slice/IceStorm/Metrics.ice b/slice/IceStorm/Metrics.ice index 580b39f93f1..fc9095449d5 100644 --- a/slice/IceStorm/Metrics.ice +++ b/slice/IceStorm/Metrics.ice @@ -9,7 +9,7 @@ #pragma once -[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICESTORM_API", "objc:header-dir:objc", "objc:dll-export:ICESTORM_API", "js:ice-build", "python:pkgdir:IceStorm"]] +[["ice-prefix", "cpp:header-ext:h", "cpp:dll-export:ICESTORM_API", "cpp:doxygen:include:IceStorm/IceStorm.h", "objc:header-dir:objc", "objc:dll-export:ICESTORM_API", "js:ice-build", "python:pkgdir:IceStorm"]] [["cpp:include:IceStorm/Config.h"]] #include <Ice/Metrics.ice> |