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