ACE/ace/SOCK_Connector.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    SOCK_Connector.h
   6  *
   7  *  @author Doug Schmidt <d.schmidt@vanderbilt.edu>
   8  */
   9 //=============================================================================
  10
  11 #ifndef ACE_SOCK_CONNECTOR_H
  12 #define ACE_SOCK_CONNECTOR_H
  13 #include /**/ "ace/pre.h"
  14
  15 #include "ace/SOCK_Stream.h"
  16
  17 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  18 # pragma once
  19 #endif /* ACE_LACKS_PRAGMA_ONCE */
  20
  21 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  22
  23 class ACE_QoS_Params;
  24 class ACE_Time_Value;
  25
  26 /**
  27  * @class ACE_SOCK_Connector
  28  *
  29  * @brief Defines a factory that actively connects to a remote IP
  30  * address and TCP port, creating a new @c ACE_SOCK_Stream object.
  31  *
  32  * The @c ACE_SOCK_Connector doesn't have a socket of its own,
  33  * i.e., it simply "borrows" the one from the @c ACE_SOCK_Stream
  34  * that's being connected.  The reason for this is that the
  35  * underlying socket API doesn't use a factory socket to connect
  36  * data mode sockets.  Therefore, there's no need to inherit
  37  * @c ACE_SOCK_Connector from @c ACE_SOCK.  A nice side-effect of
  38  * this is that @c ACE_SOCK_Connector objects do not store state so
  39  * they can be used reentrantly in multithreaded programs.
  40  */
  41 class ACE_Export ACE_SOCK_Connector
  42 {
  43 public:
  44   /// Default constructor.
  45   ACE_SOCK_Connector (void);
  46
  47   /**
  48    * Actively connect to a peer, producing a connected @c ACE_SOCK_Stream
  49    * object if the connection succeeds.
  50    *
  51    * @param new_stream  The @c ACE_SOCK_Stream object that will be connected
  52    *                    to the peer.
  53    * @param remote_sap  The address that we are trying to connect to.
  54    *                    The protocol family of @c remote_sap is used for
  55    *                    the connected socket. That is, if @c remote_sap
  56    *                    contains an IPv6 address, a socket with family
  57    *                    PF_INET6 will be used, else it will be PF_INET.
  58    * @param timeout     Pointer to an @c ACE_Time_Value object with amount
  59    *                    of time to wait to connect. If the pointer is 0
  60    *                    then the call blocks until the connection attempt
  61    *                    is complete, whether it succeeds or fails.  If
  62    *                    *timeout == {0, 0} then the connection is done
  63    *                    using nonblocking mode.  In this case, if the
  64    *                    connection can't be made immediately, this method
  65    *                    returns -1 and errno == EWOULDBLOCK.
  66    *                    If *timeout > {0, 0} then this is the maximum amount
  67    *                    of time to wait before timing out; if the specified
  68    *                    amount of time passes before the connection is made,
  69    *                    this method returns -1 and errno == ETIME. Note
  70    *                    the difference between this case and when a blocking
  71    *                    connect is attempted that TCP times out - in the latter
  72    *                    case, errno will be ETIMEDOUT.
  73    * @param local_sap   (optional) The local address to bind to.  If it's
  74    *                    the default value of @c ACE_Addr::sap_any then the
  75    *                    OS will choose an unused port.
  76    * @param reuse_addr  (optional) If the value is 1, the local address
  77    *                    (@c local_sap) is reused, even if it hasn't been
  78    *                    cleaned up yet.
  79    * @param flags       Ignored.
  80    * @param perms       Ignored.
  81    * @param protocol    (optional) If value is 0, default SOCK_STREAM
  82    *                    protocol is selected by kernel (typically TCP).
  83    */
  84   ACE_SOCK_Connector (ACE_SOCK_Stream &new_stream,
  85                       const ACE_Addr &remote_sap,
  86                       const ACE_Time_Value *timeout = 0,
  87                       const ACE_Addr &local_sap = ACE_Addr::sap_any,
  88                       int reuse_addr = 0,
  89                       int flags = 0,
  90                       int perms = 0,
  91                       int protocol = 0);
  92
  93 #if !defined (ACE_HAS_WINCE)
  94   /**
  95    * Actively connect to a peer, producing a connected @c ACE_SOCK_Stream
  96    * object if the connection succeeds.
  97    *
  98    * @param new_stream  The @c ACE_SOCK_Stream object that will be connected
  99    *                    to the peer.
 100    * @param remote_sap  The address that we are trying to connect to.
 101    *                    The protocol family of @c remote_sap is used for
 102    *                    the connected socket. That is, if @c remote_sap
 103    *                    contains an IPv6 address, a socket with family
 104    *                    PF_INET6 will be used, else it will be PF_INET.
 105    * @param qos_params  Contains QoS parameters that are passed to the
 106    *                    IntServ (RSVP) and DiffServ protocols.
 107    *                    @see ACE_QoS_Params.
 108    * @param timeout     Pointer to an @c ACE_Time_Value object with amount
 109    *                    of time to wait to connect. If the pointer is 0
 110    *                    then the call blocks until the connection attempt
 111    *                    is complete, whether it succeeds or fails.  If
 112    *                    *timeout == {0, 0} then the connection is done
 113    *                    using nonblocking mode.  In this case, if the
 114    *                    connection can't be made immediately, this method
 115    *                    returns -1 and errno == EWOULDBLOCK.
 116    *                    If *timeout > {0, 0} then this is the maximum amount
 117    *                    of time to wait before timing out; if the specified
 118    *                    amount of time passes before the connection is made,
 119    *                    this method returns -1 and errno == ETIME. Note
 120    *                    the difference between this case and when a blocking
 121    *                    connect is attempted that TCP times out - in the latter
 122    *                    case, errno will be ETIMEDOUT.
 123    * @param local_sap   (optional) The local address to bind to.  If it's
 124    *                    the default value of @c ACE_Addr::sap_any then the
 125    *                    OS will choose an unused port.
 126    * @param reuse_addr  (optional) If the value is 1, the local address
 127    *                    (@c local_sap) is reused, even if it hasn't been
 128    *                    cleaned up yet.
 129    * @param flags       Ignored.
 130    * @param perms       Ignored.
 131    */
 132   ACE_SOCK_Connector (ACE_SOCK_Stream &new_stream,
 133                       const ACE_Addr &remote_sap,
 134                       ACE_QoS_Params qos_params,
 135                       const ACE_Time_Value *timeout = 0,
 136                       const ACE_Addr &local_sap = ACE_Addr::sap_any,
 137                       ACE_Protocol_Info *protocolinfo = 0,
 138                       ACE_SOCK_GROUP g = 0,
 139                       u_long flags = 0,
 140                       int reuse_addr = 0,
 141                       int perms = 0);
 142 #endif  // ACE_HAS_WINCE
 143
 144   /**
 145    * Actively connect to a peer, producing a connected @c ACE_SOCK_Stream
 146    * object if the connection succeeds.
 147    *
 148    * @param new_stream  The @c ACE_SOCK_Stream object that will be connected
 149    *                    to the peer.
 150    * @param remote_sap  The address that we are trying to connect to.
 151    *                    The protocol family of @c remote_sap is used for
 152    *                    the connected socket. That is, if @c remote_sap
 153    *                    contains an IPv6 address, a socket with family
 154    *                    PF_INET6 will be used, else it will be PF_INET.
 155    * @param timeout     Pointer to an @c ACE_Time_Value object with amount
 156    *                    of time to wait to connect. If the pointer is 0
 157    *                    then the call blocks until the connection attempt
 158    *                    is complete, whether it succeeds or fails.  If
 159    *                    *timeout == {0, 0} then the connection is done
 160    *                    using nonblocking mode.  In this case, if the
 161    *                    connection can't be made immediately, this method
 162    *                    returns -1 and errno == EWOULDBLOCK.
 163    *                    If *timeout > {0, 0} then this is the maximum amount
 164    *                    of time to wait before timing out; if the specified
 165    *                    amount of time passes before the connection is made,
 166    *                    this method returns -1 and errno == ETIME. Note
 167    *                    the difference between this case and when a blocking
 168    *                    connect is attempted that TCP times out - in the latter
 169    *                    case, errno will be ETIMEDOUT.
 170    * @param local_sap   (optional) The local address to bind to.  If it's
 171    *                    the default value of @c ACE_Addr::sap_any then the
 172    *                    OS will choose an unused port.
 173    * @param reuse_addr  (optional) If the value is 1, the local address
 174    *                    (@c local_sap) is reused, even if it hasn't been
 175    *                    cleaned up yet.
 176    * @param flags       Ignored.
 177    * @param perms       Ignored.
 178    * @param protocol    (optional) If value is 0, default SOCK_STREAM
 179    *                    protocol is selected by kernel (typically TCP).
 180    *
 181    * @return            Returns 0 if the connection succeeds. If it fails,
 182    *                    -1 is returned and errno contains a specific error
 183    *                    code.
 184    */
 185   int connect (ACE_SOCK_Stream &new_stream,
 186                const ACE_Addr &remote_sap,
 187                const ACE_Time_Value *timeout = 0,
 188                const ACE_Addr &local_sap = ACE_Addr::sap_any,
 189                int reuse_addr = 0,
 190                int flags = 0,
 191                int perms = 0,
 192                int protocol = 0);
 193
 194 #if !defined (ACE_HAS_WINCE)
 195   /**
 196    * Actively connect to a peer, producing a connected @c ACE_SOCK_Stream
 197    * object if the connection succeeds.
 198    *
 199    * @param new_stream  The @c ACE_SOCK_Stream object that will be connected
 200    *                    to the peer.
 201    * @param remote_sap  The address that we are trying to connect to.
 202    *                    The protocol family of @c remote_sap is used for
 203    *                    the connected socket. That is, if @c remote_sap
 204    *                    contains an IPv6 address, a socket with family
 205    *                    PF_INET6 will be used, else it will be PF_INET.
 206    * @param qos_params  Contains QoS parameters that are passed to the
 207    *                    IntServ (RSVP) and DiffServ protocols.
 208    *                    @see ACE_QoS_Params.
 209    * @param timeout     Pointer to an @c ACE_Time_Value object with amount
 210    *                    of time to wait to connect. If the pointer is 0
 211    *                    then the call blocks until the connection attempt
 212    *                    is complete, whether it succeeds or fails.  If
 213    *                    *timeout == {0, 0} then the connection is done
 214    *                    using nonblocking mode.  In this case, if the
 215    *                    connection can't be made immediately, this method
 216    *                    returns -1 and errno == EWOULDBLOCK.
 217    *                    If *timeout > {0, 0} then this is the maximum amount
 218    *                    of time to wait before timing out; if the specified
 219    *                    amount of time passes before the connection is made,
 220    *                    this method returns -1 and errno == ETIME. Note
 221    *                    the difference between this case and when a blocking
 222    *                    connect is attempted that TCP times out - in the latter
 223    *                    case, errno will be ETIMEDOUT.
 224    * @param local_sap   (optional) The local address to bind to.  If it's
 225    *                    the default value of @c ACE_Addr::sap_any then the
 226    *                    OS will choose an unused port.
 227    * @param reuse_addr  (optional) If the value is 1, the local address
 228    *                    (@c local_sap) is reused, even if it hasn't been
 229    *                    cleaned up yet.
 230    * @param flags       Ignored.
 231    * @param perms       Ignored.
 232    *
 233    * @return            Returns 0 if the connection succeeds. If it fails,
 234    *                    -1 is returned and errno contains a specific error
 235    *                    code.
 236    */
 237   int connect (ACE_SOCK_Stream &new_stream,
 238                const ACE_Addr &remote_sap,
 239                ACE_QoS_Params qos_params,
 240                const ACE_Time_Value *timeout = 0,
 241                const ACE_Addr &local_sap = ACE_Addr::sap_any,
 242                ACE_Protocol_Info *protocolinfo = 0,
 243                ACE_SOCK_GROUP g = 0,
 244                u_long flags = 0,
 245                int reuse_addr = 0,
 246                int perms = 0);
 247 #endif  // ACE_HAS_WINCE
 248
 249   /// Default destructor.
 250   ~ACE_SOCK_Connector (void);
 251
 252   // = Completion routine.
 253   /**
 254    * Try to complete a nonblocking connection that was begun by a
 255    * previous call to connect with a {0, 0} ACE_Time_Value timeout.
 256    * @see connect().
 257    *
 258    * @param new_stream  The @c ACE_SOCK_Stream object that will be connected
 259    *                    to the peer.
 260    * @param remote_sap  If non-0, it points to the @c ACE_INET_Addr object
 261    *                    that will contain the address of the connected peer.
 262    * @param timeout     Same values and return value possibilities as for
 263    *                    connect(). @see connect().
 264    */
 265   int complete (ACE_SOCK_Stream &new_stream,
 266                 ACE_Addr *remote_sap = 0,
 267                 const ACE_Time_Value *timeout = 0);
 268
 269   /// Resets any event associations on this handle
 270   bool reset_new_handle (ACE_HANDLE handle);
 271
 272   // = Meta-type info
 273   typedef ACE_INET_Addr PEER_ADDR;
 274   typedef ACE_SOCK_Stream PEER_STREAM;
 275
 276   /// Dump the state of an object.
 277   void dump (void) const;
 278
 279   /// Declare the dynamic allocation hooks.
 280   ACE_ALLOC_HOOK_DECLARE;
 281
 282 protected:
 283   /// Perform operations that ensure the socket is opened using
 284   /// BSD-style semantics (no QoS).
 285   int shared_open (ACE_SOCK_Stream &new_stream,
 286                    int protocol_family,
 287                    int protocol,
 288                    int reuse_addr);
 289
 290   /// Perform operations that ensure the socket is opened using
 291   /// QoS-enabled semantics.
 292   int shared_open (ACE_SOCK_Stream &new_stream,
 293                    int protocol_family,
 294                    int protocol,
 295                    ACE_Protocol_Info *protocolinfo,
 296                    ACE_SOCK_GROUP g,
 297                    u_long flags,
 298                    int reuse_addr);
 299
 300   /// Perform operations that must be called before <ACE_OS::connect>.
 301   int shared_connect_start (ACE_SOCK_Stream &new_stream,
 302                             const ACE_Time_Value *timeout,
 303                             const ACE_Addr &local_sap);
 304
 305   /// Perform operations that must be called after <ACE_OS::connect>.
 306   int shared_connect_finish (ACE_SOCK_Stream &new_stream,
 307                              const ACE_Time_Value *timeout,
 308                              int result);
 309 };
 310
 311 ACE_END_VERSIONED_NAMESPACE_DECL
 312
 313 #if defined (__ACE_INLINE__)
 314 #include "ace/SOCK_Connector.inl"
 315 #endif /* __ACE_INLINE__ */
 316
 317 #include /**/ "ace/post.h"
 318 #endif /* ACE_SOCK_CONNECTOR_H */