00001 // -*- C++ -*- 00002 00003 //============================================================================= 00004 /** 00005 * @file SOCK_Connector.h 00006 * 00007 * $Id: SOCK_Connector.h 80826 2008-03-04 14:51:23Z wotte $ 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 ACE_SOCK_Connector (ACE_SOCK_Stream &new_stream, 00088 const ACE_Addr &remote_sap, 00089 const ACE_Time_Value *timeout = 0, 00090 const ACE_Addr &local_sap = ACE_Addr::sap_any, 00091 int reuse_addr = 0, 00092 int flags = 0, 00093 int perms = 0, 00094 int protocol = 0); 00095 00096 #if !defined (ACE_HAS_WINCE) 00097 /** 00098 * Actively connect to a peer, producing a connected @c ACE_SOCK_Stream 00099 * object if the connection succeeds. 00100 * 00101 * @param new_stream The @c ACE_SOCK_Stream object that will be connected 00102 * to the peer. 00103 * @param remote_sap The address that we are trying to connect to. 00104 * The protocol family of @c remote_sap is used for 00105 * the connected socket. That is, if @c remote_sap 00106 * contains an IPv6 address, a socket with family 00107 * PF_INET6 will be used, else it will be PF_INET. 00108 * @param qos_params Contains QoS parameters that are passed to the 00109 * IntServ (RSVP) and DiffServ protocols. 00110 * @see ACE_QoS_Params. 00111 * @param timeout Pointer to an @c ACE_Time_Value object with amount 00112 * of time to wait to connect. If the pointer is 0 00113 * then the call blocks until the connection attempt 00114 * is complete, whether it succeeds or fails. If 00115 * *timeout == {0, 0} then the connection is done 00116 * using nonblocking mode. In this case, if the 00117 * connection can't be made immediately, this method 00118 * returns -1 and errno == EWOULDBLOCK. 00119 * If *timeout > {0, 0} then this is the maximum amount 00120 * of time to wait before timing out; if the specified 00121 * amount of time passes before the connection is made, 00122 * this method returns -1 and errno == ETIME. Note 00123 * the difference between this case and when a blocking 00124 * connect is attmpted that TCP times out - in the latter 00125 * case, errno will be ETIMEDOUT. 00126 * @param local_sap (optional) The local address to bind to. If it's 00127 * the default value of @c ACE_Addr::sap_any then the 00128 * OS will choose an unused port. 00129 * @param reuse_addr (optional) If the value is 1, the local address 00130 * (@c local_sap) is reused, even if it hasn't been 00131 * cleaned up yet. 00132 * @param flags Ignored. 00133 * @param perms Ignored. 00134 */ 00135 ACE_SOCK_Connector (ACE_SOCK_Stream &new_stream, 00136 const ACE_Addr &remote_sap, 00137 ACE_QoS_Params qos_params, 00138 const ACE_Time_Value *timeout = 0, 00139 const ACE_Addr &local_sap = ACE_Addr::sap_any, 00140 ACE_Protocol_Info *protocolinfo = 0, 00141 ACE_SOCK_GROUP g = 0, 00142 u_long flags = 0, 00143 int reuse_addr = 0, 00144 int perms = 0); 00145 #endif // ACE_HAS_WINCE 00146 00147 /** 00148 * Actively connect to a peer, producing a connected @c ACE_SOCK_Stream 00149 * object if the connection succeeds. 00150 * 00151 * @param new_stream The @c ACE_SOCK_Stream object that will be connected 00152 * to the peer. 00153 * @param remote_sap The address that we are trying to connect to. 00154 * The protocol family of @c remote_sap is used for 00155 * the connected socket. That is, if @c remote_sap 00156 * contains an IPv6 address, a socket with family 00157 * PF_INET6 will be used, else it will be PF_INET. 00158 * @param timeout Pointer to an @c ACE_Time_Value object with amount 00159 * of time to wait to connect. If the pointer is 0 00160 * then the call blocks until the connection attempt 00161 * is complete, whether it succeeds or fails. If 00162 * *timeout == {0, 0} then the connection is done 00163 * using nonblocking mode. In this case, if the 00164 * connection can't be made immediately, this method 00165 * returns -1 and errno == EWOULDBLOCK. 00166 * If *timeout > {0, 0} then this is the maximum amount 00167 * of time to wait before timing out; if the specified 00168 * amount of time passes before the connection is made, 00169 * this method returns -1 and errno == ETIME. Note 00170 * the difference between this case and when a blocking 00171 * connect is attmpted that TCP times out - in the latter 00172 * case, errno will be ETIMEDOUT. 00173 * @param local_sap (optional) The local address to bind to. If it's 00174 * the default value of @c ACE_Addr::sap_any then the 00175 * OS will choose an unused port. 00176 * @param reuse_addr (optional) If the value is 1, the local address 00177 * (@c local_sap) is reused, even if it hasn't been 00178 * cleaned up yet. 00179 * @param flags Ignored. 00180 * @param perms Ignored. 00181 * @param protocol (optional) If value is 0, default SOCK_STREAM 00182 * protocol is selected by kernel (typically TCP). 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 int protocol = 0); 00196 00197 #if !defined (ACE_HAS_WINCE) 00198 /** 00199 * Actively connect to a peer, producing a connected @c ACE_SOCK_Stream 00200 * object if the connection succeeds. 00201 * 00202 * @param new_stream The @c ACE_SOCK_Stream object that will be connected 00203 * to the peer. 00204 * @param remote_sap The address that we are trying to connect to. 00205 * The protocol family of @c remote_sap is used for 00206 * the connected socket. That is, if @c remote_sap 00207 * contains an IPv6 address, a socket with family 00208 * PF_INET6 will be used, else it will be PF_INET. 00209 * @param qos_params Contains QoS parameters that are passed to the 00210 * IntServ (RSVP) and DiffServ protocols. 00211 * @see ACE_QoS_Params. 00212 * @param timeout Pointer to an @c ACE_Time_Value object with amount 00213 * of time to wait to connect. If the pointer is 0 00214 * then the call blocks until the connection attempt 00215 * is complete, whether it succeeds or fails. If 00216 * *timeout == {0, 0} then the connection is done 00217 * using nonblocking mode. In this case, if the 00218 * connection can't be made immediately, this method 00219 * returns -1 and errno == EWOULDBLOCK. 00220 * If *timeout > {0, 0} then this is the maximum amount 00221 * of time to wait before timing out; if the specified 00222 * amount of time passes before the connection is made, 00223 * this method returns -1 and errno == ETIME. Note 00224 * the difference between this case and when a blocking 00225 * connect is attmpted that TCP times out - in the latter 00226 * case, errno will be ETIMEDOUT. 00227 * @param local_sap (optional) The local address to bind to. If it's 00228 * the default value of @c ACE_Addr::sap_any then the 00229 * OS will choose an unused port. 00230 * @param reuse_addr (optional) If the value is 1, the local address 00231 * (@c local_sap) is reused, even if it hasn't been 00232 * cleaned up yet. 00233 * @param flags Ignored. 00234 * @param perms Ignored. 00235 * 00236 * @return Returns 0 if the connection succeeds. If it fails, 00237 * -1 is returned and errno contains a specific error 00238 * code. 00239 */ 00240 int connect (ACE_SOCK_Stream &new_stream, 00241 const ACE_Addr &remote_sap, 00242 ACE_QoS_Params qos_params, 00243 const ACE_Time_Value *timeout = 0, 00244 const ACE_Addr &local_sap = ACE_Addr::sap_any, 00245 ACE_Protocol_Info *protocolinfo = 0, 00246 ACE_SOCK_GROUP g = 0, 00247 u_long flags = 0, 00248 int reuse_addr = 0, 00249 int perms = 0); 00250 #endif // ACE_HAS_WINCE 00251 00252 /// Default dtor. 00253 ~ACE_SOCK_Connector (void); 00254 00255 // = Completion routine. 00256 /** 00257 * Try to complete a nonblocking connection that was begun by a 00258 * previous call to connect with a {0, 0} ACE_Time_Value timeout. 00259 * @see connect(). 00260 * 00261 * @param new_stream The @c ACE_SOCK_Stream object that will be connected 00262 * to the peer. 00263 * @param remote_sap If non-0, it points to the @c ACE_INET_Addr object 00264 * that will contain the address of the connected peer. 00265 * @param timeout Same values and return value possibilites as for 00266 * connect(). @see connect(). 00267 */ 00268 int complete (ACE_SOCK_Stream &new_stream, 00269 ACE_Addr *remote_sap = 0, 00270 const ACE_Time_Value *timeout = 0); 00271 00272 /// Resets any event associations on this handle 00273 int reset_new_handle (ACE_HANDLE handle); 00274 00275 // = Meta-type info 00276 typedef ACE_INET_Addr PEER_ADDR; 00277 typedef ACE_SOCK_Stream PEER_STREAM; 00278 00279 /// Dump the state of an object. 00280 void dump (void) const; 00281 00282 /// Declare the dynamic allocation hooks. 00283 ACE_ALLOC_HOOK_DECLARE; 00284 00285 protected: 00286 /// Perform operations that ensure the socket is opened using 00287 /// BSD-style semantics (no QoS). 00288 int shared_open (ACE_SOCK_Stream &new_stream, 00289 int protocol_family, 00290 int protocol, 00291 int reuse_addr); 00292 00293 /// Perform operations that ensure the socket is opened using 00294 /// QoS-enabled semantics. 00295 int shared_open (ACE_SOCK_Stream &new_stream, 00296 int protocol_family, 00297 int protocol, 00298 ACE_Protocol_Info *protocolinfo, 00299 ACE_SOCK_GROUP g, 00300 u_long flags, 00301 int reuse_addr); 00302 00303 /// Perform operations that must be called before <ACE_OS::connect>. 00304 int shared_connect_start (ACE_SOCK_Stream &new_stream, 00305 const ACE_Time_Value *timeout, 00306 const ACE_Addr &local_sap); 00307 00308 /// Perform operations that must be called after <ACE_OS::connect>. 00309 int shared_connect_finish (ACE_SOCK_Stream &new_stream, 00310 const ACE_Time_Value *timeout, 00311 int result); 00312 }; 00313 00314 ACE_END_VERSIONED_NAMESPACE_DECL 00315 00316 #if defined (__ACE_INLINE__) 00317 #include "ace/SOCK_Connector.inl" 00318 #endif /* __ACE_INLINE__ */ 00319 00320 #include /**/ "ace/post.h" 00321 #endif /* ACE_SOCK_CONNECTOR_H */
1.4.7