1 files changed, 185 insertions, 13 deletions
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: