Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

SOCK_Connector.h

Go to the documentation of this file.
00001 /* -*- C++ -*- */
00002 
00003 //=============================================================================
00004 /**
00005  *  @file    SOCK_Connector.h
00006  *
00007  *  $Id: SOCK_Connector.h,v 1.1.1.4 2003/02/21 18:36:32 chad Exp $
00008  *
00009  *  @author Doug Schmidt <schmidt@cs.wustl.edu>
00010  */
00011 //=============================================================================
00012 
00013 #ifndef ACE_SOCK_CONNECTOR_H
00014 #define ACE_SOCK_CONNECTOR_H
00015 #include "ace/pre.h"
00016 
00017 #include "ace/SOCK_Stream.h"
00018 
00019 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00020 # pragma once
00021 #endif /* ACE_LACKS_PRAGMA_ONCE */
00022 
00023 #include "ace/Time_Value.h"
00024 
00025 /**
00026  * @class ACE_SOCK_Connector
00027  *
00028  * @brief Defines a factory that actively connects to a remote IP
00029  * address and TCP port, creating a new @c ACE_SOCK_Stream object.
00030  *
00031  * The @c ACE_SOCK_Connector doesn't have a socket of its own,
00032  * i.e., it simply "borrows" the one from the @c ACE_SOCK_Stream
00033  * that's being connected.  The reason for this is that the
00034  * underlying socket API doesn't use a factory socket to connect
00035  * data mode sockets.  Therefore, there's no need to inherit
00036  * @c ACE_SOCK_Connector from @c ACE_SOCK.  A nice side-effect of
00037  * this is that @c ACE_SOCK_Connector objects do not store state so
00038  * they can be used reentrantly in multithreaded programs.
00039  */
00040 class ACE_Export ACE_SOCK_Connector
00041 {
00042 public:
00043   // = Initialization and termination methods.
00044   /// Default constructor.
00045   ACE_SOCK_Connector (void);
00046 
00047   /**
00048    * Actively connect to a peer, producing a connected @c ACE_SOCK_Stream
00049    * object if the connection succeeds.
00050    *
00051    * @param new_stream  The @c ACE_SOCK_Stream object that will be connected
00052    *                    to the peer.
00053    * @param remote_sap  The address that we are trying to connect to.
00054    *                    The protocol family of @c remote_sap is used for
00055    *                    the connected socket. That is, if @c remote_sap
00056    *                    contains an IPv6 address, a socket with family
00057    *                    PF_INET6 will be used, else it will be PF_INET.
00058    * @param timeout     Pointer to an @c ACE_Time_Value object with amount
00059    *                    of time to wait to connect. If the pointer is 0
00060    *                    then the call blocks until the connection attempt
00061    *                    is complete, whether it succeeds or fails.  If
00062    *                    *timeout == {0, 0} then the connection is done
00063    *                    using nonblocking mode.  In this case, if the
00064    *                    connection can't be made immediately, this method
00065    *                    returns -1 and errno == EWOULDBLOCK.
00066    *                    If *timeout > {0, 0} then this is the maximum amount
00067    *                    of time to wait before timing out; if the specified
00068    *                    amount of time passes before the connection is made,
00069    *                    this method returns -1 and errno == ETIME. Note
00070    *                    the difference between this case and when a blocking
00071    *                    connect is attmpted that TCP times out - in the latter
00072    *                    case, errno will be ETIMEDOUT.
00073    * @param local_sap   (optional) The local address to bind to.  If it's
00074    *                    the default value of @c ACE_Addr::sap_any then the
00075    *                    OS will choose an unused port.
00076    * @param reuse_addr  (optional) If the value is 1, the local address
00077    *                    (@c local_sap) is reused, even if it hasn't been
00078    *                    cleaned up yet.
00079    * @param flags       Ignored.
00080    * @param perms       Ignored.
00081    *
00082    * @return            Returns 0 if the connection succeeds. If it fails,
00083    *                    -1 is returned and errno contains a specific error
00084    *                    code.
00085    */
00086   ACE_SOCK_Connector (ACE_SOCK_Stream &new_stream,
00087                       const ACE_Addr &remote_sap,
00088                       const ACE_Time_Value *timeout = 0,
00089                       const ACE_Addr &local_sap = ACE_Addr::sap_any,
00090                       int reuse_addr = 0,
00091                       int flags = 0,
00092                       int perms = 0);
00093 
00094 #if !defined (ACE_HAS_WINCE)
00095   /**
00096    * Actively connect to a peer, producing a connected @c ACE_SOCK_Stream
00097    * object if the connection succeeds.
00098    *
00099    * @param new_stream  The @c ACE_SOCK_Stream object that will be connected
00100    *                    to the peer.
00101    * @param remote_sap  The address that we are trying to connect to.
00102    *                    The protocol family of @c remote_sap is used for
00103    *                    the connected socket. That is, if @c remote_sap
00104    *                    contains an IPv6 address, a socket with family
00105    *                    PF_INET6 will be used, else it will be PF_INET.
00106    * @param qos_params  Contains QoS parameters that are passed to the
00107    *                    IntServ (RSVP) and DiffServ protocols.
00108    *                    @see ACE_QoS_Params.
00109    * @param timeout     Pointer to an @c ACE_Time_Value object with amount
00110    *                    of time to wait to connect. If the pointer is 0
00111    *                    then the call blocks until the connection attempt
00112    *                    is complete, whether it succeeds or fails.  If
00113    *                    *timeout == {0, 0} then the connection is done
00114    *                    using nonblocking mode.  In this case, if the
00115    *                    connection can't be made immediately, this method
00116    *                    returns -1 and errno == EWOULDBLOCK.
00117    *                    If *timeout > {0, 0} then this is the maximum amount
00118    *                    of time to wait before timing out; if the specified
00119    *                    amount of time passes before the connection is made,
00120    *                    this method returns -1 and errno == ETIME. Note
00121    *                    the difference between this case and when a blocking
00122    *                    connect is attmpted that TCP times out - in the latter
00123    *                    case, errno will be ETIMEDOUT.
00124    * @param local_sap   (optional) The local address to bind to.  If it's
00125    *                    the default value of @c ACE_Addr::sap_any then the
00126    *                    OS will choose an unused port.
00127    * @param reuse_addr  (optional) If the value is 1, the local address
00128    *                    (@c local_sap) is reused, even if it hasn't been
00129    *                    cleaned up yet.
00130    * @param flags       Ignored.
00131    * @param perms       Ignored.
00132    *
00133    * @return            Returns 0 if the connection succeeds. If it fails,
00134    *                    -1 is returned and errno contains a specific error
00135    *                    code.
00136    */
00137   ACE_SOCK_Connector (ACE_SOCK_Stream &new_stream,
00138                       const ACE_Addr &remote_sap,
00139                       ACE_QoS_Params qos_params,
00140                       const ACE_Time_Value *timeout = 0,
00141                       const ACE_Addr &local_sap = ACE_Addr::sap_any,
00142                       ACE_Protocol_Info *protocolinfo = 0,
00143                       ACE_SOCK_GROUP g = 0,
00144                       u_long flags = 0,
00145                       int reuse_addr = 0,
00146                       int perms = 0);
00147 #endif  // ACE_HAS_WINCE
00148 
00149   /**
00150    * Actively connect to a peer, producing a connected @c ACE_SOCK_Stream
00151    * object if the connection succeeds.
00152    *
00153    * @param new_stream  The @c ACE_SOCK_Stream object that will be connected
00154    *                    to the peer.
00155    * @param remote_sap  The address that we are trying to connect to.
00156    *                    The protocol family of @c remote_sap is used for
00157    *                    the connected socket. That is, if @c remote_sap
00158    *                    contains an IPv6 address, a socket with family
00159    *                    PF_INET6 will be used, else it will be PF_INET.
00160    * @param timeout     Pointer to an @c ACE_Time_Value object with amount
00161    *                    of time to wait to connect. If the pointer is 0
00162    *                    then the call blocks until the connection attempt
00163    *                    is complete, whether it succeeds or fails.  If
00164    *                    *timeout == {0, 0} then the connection is done
00165    *                    using nonblocking mode.  In this case, if the
00166    *                    connection can't be made immediately, this method
00167    *                    returns -1 and errno == EWOULDBLOCK.
00168    *                    If *timeout > {0, 0} then this is the maximum amount
00169    *                    of time to wait before timing out; if the specified
00170    *                    amount of time passes before the connection is made,
00171    *                    this method returns -1 and errno == ETIME. Note
00172    *                    the difference between this case and when a blocking
00173    *                    connect is attmpted that TCP times out - in the latter
00174    *                    case, errno will be ETIMEDOUT.
00175    * @param local_sap   (optional) The local address to bind to.  If it's
00176    *                    the default value of @c ACE_Addr::sap_any then the
00177    *                    OS will choose an unused port.
00178    * @param reuse_addr  (optional) If the value is 1, the local address
00179    *                    (@c local_sap) is reused, even if it hasn't been
00180    *                    cleaned up yet.
00181    * @param flags       Ignored.
00182    * @param perms       Ignored.
00183    *
00184    * @return            Returns 0 if the connection succeeds. If it fails,
00185    *                    -1 is returned and errno contains a specific error
00186    *                    code.
00187    */
00188   int connect (ACE_SOCK_Stream &new_stream,
00189                const ACE_Addr &remote_sap,
00190                const ACE_Time_Value *timeout = 0,
00191                const ACE_Addr &local_sap = ACE_Addr::sap_any,
00192                int reuse_addr = 0,
00193                int flags = 0,
00194                int perms = 0);
00195 
00196 #if !defined (ACE_HAS_WINCE)
00197   /**
00198    * Actively connect to a peer, producing a connected @c ACE_SOCK_Stream
00199    * object if the connection succeeds.
00200    *
00201    * @param new_stream  The @c ACE_SOCK_Stream object that will be connected
00202    *                    to the peer.
00203    * @param remote_sap  The address that we are trying to connect to.
00204    *                    The protocol family of @c remote_sap is used for
00205    *                    the connected socket. That is, if @c remote_sap
00206    *                    contains an IPv6 address, a socket with family
00207    *                    PF_INET6 will be used, else it will be PF_INET.
00208    * @param qos_params  Contains QoS parameters that are passed to the
00209    *                    IntServ (RSVP) and DiffServ protocols.
00210    *                    @see ACE_QoS_Params.
00211    * @param timeout     Pointer to an @c ACE_Time_Value object with amount
00212    *                    of time to wait to connect. If the pointer is 0
00213    *                    then the call blocks until the connection attempt
00214    *                    is complete, whether it succeeds or fails.  If
00215    *                    *timeout == {0, 0} then the connection is done
00216    *                    using nonblocking mode.  In this case, if the
00217    *                    connection can't be made immediately, this method
00218    *                    returns -1 and errno == EWOULDBLOCK.
00219    *                    If *timeout > {0, 0} then this is the maximum amount
00220    *                    of time to wait before timing out; if the specified
00221    *                    amount of time passes before the connection is made,
00222    *                    this method returns -1 and errno == ETIME. Note
00223    *                    the difference between this case and when a blocking
00224    *                    connect is attmpted that TCP times out - in the latter
00225    *                    case, errno will be ETIMEDOUT.
00226    * @param local_sap   (optional) The local address to bind to.  If it's
00227    *                    the default value of @c ACE_Addr::sap_any then the
00228    *                    OS will choose an unused port.
00229    * @param reuse_addr  (optional) If the value is 1, the local address
00230    *                    (@c local_sap) is reused, even if it hasn't been
00231    *                    cleaned up yet.
00232    * @param flags       Ignored.
00233    * @param perms       Ignored.
00234    *
00235    * @return            Returns 0 if the connection succeeds. If it fails,
00236    *                    -1 is returned and errno contains a specific error
00237    *                    code.
00238    */
00239   int connect (ACE_SOCK_Stream &new_stream,
00240                const ACE_Addr &remote_sap,
00241                ACE_QoS_Params qos_params,
00242                const ACE_Time_Value *timeout = 0,
00243                const ACE_Addr &local_sap = ACE_Addr::sap_any,
00244                ACE_Protocol_Info *protocolinfo = 0,
00245                ACE_SOCK_GROUP g = 0,
00246                u_long flags = 0,
00247                int reuse_addr = 0,
00248                int perms = 0);
00249 #endif  // ACE_HAS_WINCE
00250 
00251   /// Default dtor.
00252   ~ACE_SOCK_Connector (void);
00253 
00254   // = Completion routine.
00255   /**
00256    * Try to complete a nonblocking connection that was begun by a
00257    * previous call to connect with a {0, 0} ACE_Time_Value timeout.
00258    * @see connect().
00259    *
00260    * @param new_stream  The @c ACE_SOCK_Stream object that will be connected
00261    *                    to the peer.
00262    * @param remote_sap  If non-0, it points to the @c ACE_INET_Addr object
00263    *                    that will contain the address of the connected peer.
00264    * @param timeout     Same values and return value possibilites as for
00265    *                    connect(). @see connect().
00266    */
00267   int complete (ACE_SOCK_Stream &new_stream,
00268                 ACE_Addr *remote_sap = 0,
00269                 const ACE_Time_Value *timeout = 0);
00270 
00271   /// Resets any event associations on this handle
00272   int reset_new_handle (ACE_HANDLE handle);
00273 
00274   // = Meta-type info
00275   typedef ACE_INET_Addr PEER_ADDR;
00276   typedef ACE_SOCK_Stream PEER_STREAM;
00277 
00278   /// Dump the state of an object.
00279   void dump (void) const;
00280 
00281   /// Declare the dynamic allocation hooks.
00282   ACE_ALLOC_HOOK_DECLARE;
00283 
00284 protected:
00285   /// Perform operations that ensure the socket is opened using
00286   /// BSD-style semantics (no QoS).
00287   int shared_open (ACE_SOCK_Stream &new_stream,
00288                    int protocol_family,
00289                    int protocol,
00290                    int reuse_addr);
00291 
00292   /// Perform operations that ensure the socket is opened using
00293   /// QoS-enabled semantics.
00294   int shared_open (ACE_SOCK_Stream &new_stream,
00295                    int protocol_family,
00296                    int protocol,
00297                    ACE_Protocol_Info *protocolinfo,
00298                    ACE_SOCK_GROUP g,
00299                    u_long flags,
00300                    int reuse_addr);
00301 
00302   /// Perform operations that must be called before <ACE_OS::connect>.
00303   int shared_connect_start (ACE_SOCK_Stream &new_stream,
00304                             const ACE_Time_Value *timeout,
00305                             const ACE_Addr &local_sap);
00306 
00307   /// Perform operations that must be called after <ACE_OS::connect>.
00308   int shared_connect_finish (ACE_SOCK_Stream &new_stream,
00309                              const ACE_Time_Value *timeout,
00310                              int result);
00311 };
00312 
00313 #if !defined (ACE_LACKS_INLINE_FUNCTIONS)
00314 #include "ace/SOCK_Connector.i"
00315 #endif
00316 
00317 #include "ace/post.h"
00318 #endif /* ACE_SOCK_CONNECTOR_H */

Generated on Mon Jun 16 11:21:19 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002