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 ();
  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   /**
  94    * Actively connect to a peer, producing a connected @c ACE_SOCK_Stream
  95    * object if the connection succeeds.
  96    *
  97    * @param new_stream  The @c ACE_SOCK_Stream object that will be connected
  98    *                    to the peer.
  99    * @param remote_sap  The address that we are trying to connect to.
 100    *                    The protocol family of @c remote_sap is used for
 101    *                    the connected socket. That is, if @c remote_sap
 102    *                    contains an IPv6 address, a socket with family
 103    *                    PF_INET6 will be used, else it will be PF_INET.
 104    * @param qos_params  Contains QoS parameters that are passed to the
 105    *                    IntServ (RSVP) and DiffServ protocols.
 106    *                    @see ACE_QoS_Params.
 107    * @param timeout     Pointer to an @c ACE_Time_Value object with amount
 108    *                    of time to wait to connect. If the pointer is 0
 109    *                    then the call blocks until the connection attempt
 110    *                    is complete, whether it succeeds or fails.  If
 111    *                    *timeout == {0, 0} then the connection is done
 112    *                    using nonblocking mode.  In this case, if the
 113    *                    connection can't be made immediately, this method
 114    *                    returns -1 and errno == EWOULDBLOCK.
 115    *                    If *timeout > {0, 0} then this is the maximum amount
 116    *                    of time to wait before timing out; if the specified
 117    *                    amount of time passes before the connection is made,
 118    *                    this method returns -1 and errno == ETIME. Note
 119    *                    the difference between this case and when a blocking
 120    *                    connect is attempted that TCP times out - in the latter
 121    *                    case, errno will be ETIMEDOUT.
 122    * @param local_sap   (optional) The local address to bind to.  If it's
 123    *                    the default value of @c ACE_Addr::sap_any then the
 124    *                    OS will choose an unused port.
 125    * @param reuse_addr  (optional) If the value is 1, the local address
 126    *                    (@c local_sap) is reused, even if it hasn't been
 127    *                    cleaned up yet.
 128    * @param flags       Ignored.
 129    * @param perms       Ignored.
 130    */
 131   ACE_SOCK_Connector (ACE_SOCK_Stream &new_stream,
 132                       const ACE_Addr &remote_sap,
 133                       ACE_QoS_Params qos_params,
 134                       const ACE_Time_Value *timeout = 0,
 135                       const ACE_Addr &local_sap = ACE_Addr::sap_any,
 136                       ACE_Protocol_Info *protocolinfo = 0,
 137                       ACE_SOCK_GROUP g = 0,
 138                       u_long flags = 0,
 139                       int reuse_addr = 0,
 140                       int perms = 0);
 141
 142   /**
 143    * Actively connect to a peer, producing a connected @c ACE_SOCK_Stream
 144    * object if the connection succeeds.
 145    *
 146    * @param new_stream  The @c ACE_SOCK_Stream object that will be connected
 147    *                    to the peer.
 148    * @param remote_sap  The address that we are trying to connect to.
 149    *                    The protocol family of @c remote_sap is used for
 150    *                    the connected socket. That is, if @c remote_sap
 151    *                    contains an IPv6 address, a socket with family
 152    *                    PF_INET6 will be used, else it will be PF_INET.
 153    * @param timeout     Pointer to an @c ACE_Time_Value object with amount
 154    *                    of time to wait to connect. If the pointer is 0
 155    *                    then the call blocks until the connection attempt
 156    *                    is complete, whether it succeeds or fails.  If
 157    *                    *timeout == {0, 0} then the connection is done
 158    *                    using nonblocking mode.  In this case, if the
 159    *                    connection can't be made immediately, this method
 160    *                    returns -1 and errno == EWOULDBLOCK.
 161    *                    If *timeout > {0, 0} then this is the maximum amount
 162    *                    of time to wait before timing out; if the specified
 163    *                    amount of time passes before the connection is made,
 164    *                    this method returns -1 and errno == ETIME. Note
 165    *                    the difference between this case and when a blocking
 166    *                    connect is attempted that TCP times out - in the latter
 167    *                    case, errno will be ETIMEDOUT.
 168    * @param local_sap   (optional) The local address to bind to.  If it's
 169    *                    the default value of @c ACE_Addr::sap_any then the
 170    *                    OS will choose an unused port.
 171    * @param reuse_addr  (optional) If the value is 1, the local address
 172    *                    (@c local_sap) is reused, even if it hasn't been
 173    *                    cleaned up yet.
 174    * @param flags       Ignored.
 175    * @param perms       Ignored.
 176    * @param protocol    (optional) If value is 0, default SOCK_STREAM
 177    *                    protocol is selected by kernel (typically TCP).
 178    *
 179    * @return            Returns 0 if the connection succeeds. If it fails,
 180    *                    -1 is returned and errno contains a specific error
 181    *                    code.
 182    */
 183   int connect (ACE_SOCK_Stream &new_stream,
 184                const ACE_Addr &remote_sap,
 185                const ACE_Time_Value *timeout = 0,
 186                const ACE_Addr &local_sap = ACE_Addr::sap_any,
 187                int reuse_addr = 0,
 188                int flags = 0,
 189                int perms = 0,
 190                int protocol = 0);
 191
 192   /**
 193    * Actively connect to a peer, producing a connected @c ACE_SOCK_Stream
 194    * object if the connection succeeds.
 195    *
 196    * @param new_stream  The @c ACE_SOCK_Stream object that will be connected
 197    *                    to the peer.
 198    * @param remote_sap  The address that we are trying to connect to.
 199    *                    The protocol family of @c remote_sap is used for
 200    *                    the connected socket. That is, if @c remote_sap
 201    *                    contains an IPv6 address, a socket with family
 202    *                    PF_INET6 will be used, else it will be PF_INET.
 203    * @param qos_params  Contains QoS parameters that are passed to the
 204    *                    IntServ (RSVP) and DiffServ protocols.
 205    *                    @see ACE_QoS_Params.
 206    * @param timeout     Pointer to an @c ACE_Time_Value object with amount
 207    *                    of time to wait to connect. If the pointer is 0
 208    *                    then the call blocks until the connection attempt
 209    *                    is complete, whether it succeeds or fails.  If
 210    *                    *timeout == {0, 0} then the connection is done
 211    *                    using nonblocking mode.  In this case, if the
 212    *                    connection can't be made immediately, this method
 213    *                    returns -1 and errno == EWOULDBLOCK.
 214    *                    If *timeout > {0, 0} then this is the maximum amount
 215    *                    of time to wait before timing out; if the specified
 216    *                    amount of time passes before the connection is made,
 217    *                    this method returns -1 and errno == ETIME. Note
 218    *                    the difference between this case and when a blocking
 219    *                    connect is attempted that TCP times out - in the latter
 220    *                    case, errno will be ETIMEDOUT.
 221    * @param local_sap   (optional) The local address to bind to.  If it's
 222    *                    the default value of @c ACE_Addr::sap_any then the
 223    *                    OS will choose an unused port.
 224    * @param reuse_addr  (optional) If the value is 1, the local address
 225    *                    (@c local_sap) is reused, even if it hasn't been
 226    *                    cleaned up yet.
 227    * @param flags       Ignored.
 228    * @param perms       Ignored.
 229    *
 230    * @return            Returns 0 if the connection succeeds. If it fails,
 231    *                    -1 is returned and errno contains a specific error
 232    *                    code.
 233    */
 234   int connect (ACE_SOCK_Stream &new_stream,
 235                const ACE_Addr &remote_sap,
 236                ACE_QoS_Params qos_params,
 237                const ACE_Time_Value *timeout = 0,
 238                const ACE_Addr &local_sap = ACE_Addr::sap_any,
 239                ACE_Protocol_Info *protocolinfo = 0,
 240                ACE_SOCK_GROUP g = 0,
 241                u_long flags = 0,
 242                int reuse_addr = 0,
 243                int perms = 0);
 244
 245   /// Default destructor.
 246   ~ACE_SOCK_Connector ();
 247
 248   // = Completion routine.
 249   /**
 250    * Try to complete a nonblocking connection that was begun by a
 251    * previous call to connect with a {0, 0} ACE_Time_Value timeout.
 252    * @see connect().
 253    *
 254    * @param new_stream  The @c ACE_SOCK_Stream object that will be connected
 255    *                    to the peer.
 256    * @param remote_sap  If non-0, it points to the @c ACE_INET_Addr object
 257    *                    that will contain the address of the connected peer.
 258    * @param timeout     Same values and return value possibilities as for
 259    *                    connect(). @see connect().
 260    */
 261   int complete (ACE_SOCK_Stream &new_stream,
 262                 ACE_Addr *remote_sap = 0,
 263                 const ACE_Time_Value *timeout = 0);
 264
 265   /// Resets any event associations on this handle
 266   bool reset_new_handle (ACE_HANDLE handle);
 267
 268   // = Meta-type info
 269   typedef ACE_INET_Addr PEER_ADDR;
 270   typedef ACE_SOCK_Stream PEER_STREAM;
 271
 272   /// Dump the state of an object.
 273   void dump () const;
 274
 275   /// Declare the dynamic allocation hooks.
 276   ACE_ALLOC_HOOK_DECLARE;
 277
 278 protected:
 279   /// Perform operations that ensure the socket is opened using
 280   /// BSD-style semantics (no QoS).
 281   int shared_open (ACE_SOCK_Stream &new_stream,
 282                    int protocol_family,
 283                    int protocol,
 284                    int reuse_addr);
 285
 286   /// Perform operations that ensure the socket is opened using
 287   /// QoS-enabled semantics.
 288   int shared_open (ACE_SOCK_Stream &new_stream,
 289                    int protocol_family,
 290                    int protocol,
 291                    ACE_Protocol_Info *protocolinfo,
 292                    ACE_SOCK_GROUP g,
 293                    u_long flags,
 294                    int reuse_addr);
 295
 296   /// Perform operations that must be called before <ACE_OS::connect>.
 297   int shared_connect_start (ACE_SOCK_Stream &new_stream,
 298                             const ACE_Time_Value *timeout,
 299                             const ACE_Addr &local_sap);
 300
 301   /// Perform operations that must be called after <ACE_OS::connect>.
 302   int shared_connect_finish (ACE_SOCK_Stream &new_stream,
 303                              const ACE_Time_Value *timeout,
 304                              int result);
 305 };
 306
 307 ACE_END_VERSIONED_NAMESPACE_DECL
 308
 309 #if defined (__ACE_INLINE__)
 310 #include "ace/SOCK_Connector.inl"
 311 #endif /* __ACE_INLINE__ */
 312
 313 #include /**/ "ace/post.h"
 314 #endif /* ACE_SOCK_CONNECTOR_H */