ChangeLogTag:Thu Dec 20 15:04:52 2001 Steve Huston <shuston@riverace.com>

1 files changed, 61 insertions, 26 deletions

diff --git a/ace/SSL/SSL_SOCK_Acceptor.h b/ace/SSL/SSL_SOCK_Acceptor.h
index c313d7dd94a..c3d301651ba 100644
--- a/ace/SSL/SSL_SOCK_Acceptor.h
+++ b/ace/SSL/SSL_SOCK_Acceptor.h
@@ -33,20 +33,15 @@
 /**
  * @class ACE_SSL_SOCK_Acceptor
  *
- * @brief Defines a factory that creates new ACE_SSL_SOCK_Stream>s
- * passively.
+ * @brief Defines a factory that creates new @c ACE_SSL_SOCK_Stream
+ * objects passively.
  *
- * The ACE_SSL_SOCK_Acceptor has its own ACE_SOCK_Acceptor
- * which handles virtually all of the socket acceptance.  This
- * class is a wrapper which only adds the SSL acceptance.
- * @par
- * Since SSL is record-oriented, some additional steps must be taken
- * to make the ACE_SSL_SOCK_Acceptor interact properly with the
- * Reactor (if one is used) when performing non-blocking accept()
- * calls.  In particular, the ACE_SSL_SOCK_Acceptor registers an event
- * handler with the Reactor set in the constructor or in the
- * ACE_SSL_SOCK_Acceptor::reactor() method.  If no Reactor is
- * explicitly set, the singleton Reactor instance will be used.
+ * The ACE_SSL_SOCK_Acceptor has its own @c ACE_SOCK_Acceptor
+ * which handles the basic socket acceptance.  This class is a
+ * wrapper which adds the SSL acceptance handshake handling.
+ * Since SSL is record oriented, some additional steps must be taken
+ * after the basic socket acceptance to complete the SSL handshake that
+ * takes place at session establishment.
  *
  * @note The user must currently ensure that only one thread services
  *       a given SSL session at any given time since some underlying
@@ -60,38 +55,59 @@ public:
   /// Default constructor.
   ACE_SSL_SOCK_Acceptor (void);
 
-  /// Default dtor.
+  /// Default destructor.
   ~ACE_SSL_SOCK_Acceptor (void);
 
   /**
    * Initiate a passive mode SSL/BSD-style acceptor socket.
    * @param local_sap  The address that we're going to listen for
-   *                   connections on.
+   *                   connections on. If this is @c ACE_Addr::sap_any,
+   *                   this socket listens on an the "any" IP address
+   *                   and selects an unused port. To find out what port
+   *                   was selected, call this object's
+   *                   @c ACE_SOCK::get_local_addr(ACE_Addr&) method
+   *                   upon return.
    */
   ACE_SSL_SOCK_Acceptor (const ACE_Addr &local_sap,
 			 int reuse_addr = 0,
-			 int protocol_family = PF_INET,
+			 int protocol_family = PF_UNSPEC,
 			 int backlog = ACE_DEFAULT_BACKLOG,
 			 int protocol = 0);
 
-  /// Initiate a passive-mode QoS-enabled acceptor socket.
+  /**
+   * Initiate a passive-mode QoS-enabled acceptor socket.
+   * @param local_sap  The address that we're going to listen for
+   *                   connections on. If this is @c ACE_Addr::sap_any,
+   *                   this socket listens on an the "any" IP address
+   *                   and selects an unused port. To find out what port
+   *                   was selected, call this object's
+   *                   @c ACE_SOCK::get_local_addr(ACE_Addr&) method
+   *                   upon return.
+   */
   ACE_SSL_SOCK_Acceptor (const ACE_Addr &local_sap,
 			 ACE_Protocol_Info *protocolinfo,
 			 ACE_SOCK_GROUP g,
 			 u_long flags,
 			 int reuse_addr,
-			 int protocol_family,
+			 int protocol_family = PF_UNSPEC,
 			 int backlog = ACE_DEFAULT_BACKLOG,
 			 int protocol = 0);
 
   /**
    * Initiate a passive mode SSL/BSD-style acceptor socket.
    * @param local_sap  The address that we're going to listen for
-   *                   connections on.
+   *                   connections on. If this is @c ACE_Addr::sap_any,
+   *                   this socket listens on an the "any" IP address
+   *                   and selects an unused port. To find out what port
+   *                   was selected, call this object's
+   *                   @c ACE_SOCK::get_local_addr(ACE_Addr&) method
+   *                   upon return.
+   *
+   * @return 0 if success; -1 for failure (errno contains error code).
    */
   int open (const ACE_Addr &local_sap,
             int reuse_addr = 0,
-            int protocol_family = PF_INET,
+            int protocol_family = PF_UNSPEC,
             int backlog = ACE_DEFAULT_BACKLOG,
             int protocol = 0);
 
@@ -105,9 +121,19 @@ public:
    */
   //@{
   /**
-   * Accept a new ACE_SSL_SOCK_Stream connection.  A timeout of 0
-   * means block forever, a timeout of {0, 0} means poll.  restart
-   * == 1 means "restart if interrupted," i.e., if errno == EINTR.
+   * Accept a new ACE_SSL_SOCK_Stream connection. On successful return,
+   * the socket has been accepted and the SSL handshake has been completed.
+   * @param new_stream  The @c ACE_SSL_SOCK_Stream object that will receive
+   *                    the new SSL socket.
+   * @param remote_addr Pointer to an @c ACE_INET_Addr object that will
+   *                    receive the address of the peer that connected.
+   * @param timeout     The maximum time to wait for the combined socket
+   *                    acceptance and handshake completion. 0 means
+   *                    block forever, a timeout of {0, 0} means poll.
+   * @param restart     1 means "restart if interrupted," that is,
+   *                    if errno == EINTR.
+   *
+   * @return 0 if success; -1 for failure (errno contains error code).
    */
   int accept (ACE_SSL_SOCK_Stream &new_stream,
               ACE_Addr *remote_addr = 0,
@@ -117,9 +143,18 @@ public:
 
   /**
    * Accept a new ACE_SSL_SOCK_Stream connection using the RVSP QoS
-   * information in qos_params.  A timeout of 0 means block
-   * forever, a timeout of {0, 0} means poll.  restart == 1 means
-   * "restart if interrupted," i.e., if errno == EINTR.
+   * information in qos_params.
+   * @param new_stream  The @c ACE_SSL_SOCK_Stream object that will receive
+   *                    the new SSL socket.
+   * @param remote_addr Pointer to an @c ACE_INET_Addr object that will
+   *                    receive the address of the peer that connected.
+   * @param timeout     The maximum time to wait for the combined socket
+   *                    acceptance and handshake completion. 0 means
+   *                    block forever, a timeout of {0, 0} means poll.
+   * @param restart     1 means "restart if interrupted," that is,
+   *                    if errno == EINTR.
+   *
+   * @return 0 if success; -1 for failure (errno contains error code).
    */
   int accept (ACE_SSL_SOCK_Stream &new_stream,
 	      ACE_Accept_QoS_Params qos_params,