ChangeLogTag:Mon Apr 28 21:53:23 UTC 2008 Steve Huston <shuston@riverace.com>

1 files changed, 67 insertions, 2 deletions

diff --git a/ACE/ace/SOCK_CODgram.h b/ACE/ace/SOCK_CODgram.h
index 04f9c55ceb1..c7688c2e805 100644
--- a/ACE/ace/SOCK_CODgram.h
+++ b/ACE/ace/SOCK_CODgram.h
@@ -36,10 +36,43 @@ ACE_BEGIN_VERSIONED_NAMESPACE_DECL
 class ACE_Export ACE_SOCK_CODgram : public ACE_SOCK_IO
 {
 public:
-  // = Initialization methods.
   /// Default constructor.
   ACE_SOCK_CODgram (void);
 
+  /**
+   * Constructor with addresses specified. Calls open().
+   * This constructor binds and/or connects to a specified address,
+   * optionally binding an unused port number.
+   *
+   * @param remote_sap      The remote address.
+   * @param local_sap       The local address.
+   * @param protocol_family The protocol family for the new socket. If
+   *                        either @p remote_sap or @p local_sap is
+   *                        specified (i.e., not ACE_Addr::sap_any) its
+   *                        address type is used instead of this value.
+   *                        If both addresses are specified, their address
+   *                        types must match. If neither address is specified,
+   *                        the platform's default IP address type is used.
+   * @param protocol        Protocol value for the new socket.
+   * @param reuse_addr      Reuse the local address or not.
+   *
+   * There are four possible combinations of remote_sap and local_sap. The
+   * behavior in these combinations is:
+   *
+   * @li <b>remote_addr == ACE_Addr::sap_any && local_addr == ACE_Addr::sap_any:</b>
+   *     If @p protocol_family specifies PF_INET or PF_INET6,
+   *     bind the local address to a randomly generated port number.
+   *
+   * @li <b>remote_addr == ACE_Addr::sap_any && local_addr != ACE_Addr::sap_any:</b>
+   *     Bind the local address (used primarily by servers).
+   *
+   * @li <b>remote_addr != ACE_Addr::sap_any && local_addr == ACE_Addr::sap_any:</b>
+   *     Connect to the remote address without binding a local address
+   *     (used primarily by clients).
+   *
+   * @li <b>remote_addr != ACE_Addr::sap_any && local_addr != ACE_Addr::sap_any:</b>
+   *     Bind to the local address and connect to the remote address.
+   */
   ACE_SOCK_CODgram (const ACE_Addr &remote_sap,
                     const ACE_Addr &local_sap = ACE_Addr::sap_any,
                     int protocol_family = ACE_PROTOCOL_FAMILY_INET,
@@ -51,7 +84,39 @@ public:
 
   // Initiate a connected dgram.
 
-  /// Initiate a connected dgram.
+  /**
+   * Initiate a connected datagram socket, optionally binding an
+   * unused port number.
+   *
+   * @param remote_sap      The remote address.
+   * @param local_sap       The local address.
+   * @param protocol_family The protocol family for the new socket. If
+   *                        either @p remote_sap or @p local_sap is
+   *                        specified (i.e., not ACE_Addr::sap_any) its
+   *                        address type is used instead of this value.
+   *                        If both addresses are specified, their address
+   *                        types must match. If neither address is specified,
+   *                        the platform's default IP address type is used.
+   * @param protocol        Protocol value for the new socket.
+   * @param reuse_addr      Reuse the local address or not.
+   *
+   * There are four possible combinations of remote_sap and local_sap. The
+   * behavior in these combinations is:
+   *
+   * @li <b>remote_addr == ACE_Addr::sap_any && local_addr == ACE_Addr::sap_any:</b>
+   *     If @p protocol_family specifies PF_INET or PF_INET6,
+   *     bind the local address to a randomly generated port number.
+   *
+   * @li <b>remote_addr == ACE_Addr::sap_any && local_addr != ACE_Addr::sap_any:</b>
+   *     Bind the local address (used primarily by servers).
+   *
+   * @li <b>remote_addr != ACE_Addr::sap_any && local_addr == ACE_Addr::sap_any:</b>
+   *     Connect to the remote address without binding a local address
+   *     (used primarily by clients).
+   *
+   * @li <b>remote_addr != ACE_Addr::sap_any && local_addr != ACE_Addr::sap_any:</b>
+   *     Bind to the local address and connect to the remote address.
+   */
   int open (const ACE_Addr &remote_sap,
             const ACE_Addr &local_sap = ACE_Addr::sap_any,
             int protocol_family = ACE_PROTOCOL_FAMILY_INET,