00001 /* -*- C++ -*- */ 00002 00003 //============================================================================= 00004 /** 00005 * @file Asynch_Acceptor.h 00006 * 00007 * $Id: Asynch_Acceptor.h 80826 2008-03-04 14:51:23Z wotte $ 00008 * 00009 * @author Irfan Pyarali (irfan@cs.wustl.edu) 00010 */ 00011 //============================================================================= 00012 00013 #ifndef ACE_ASYNCH_ACCEPTOR_H 00014 #define ACE_ASYNCH_ACCEPTOR_H 00015 #include /**/ "ace/pre.h" 00016 00017 #include /**/ "ace/config-all.h" 00018 00019 #if !defined (ACE_LACKS_PRAGMA_ONCE) 00020 # pragma once 00021 #endif /* ACE_LACKS_PRAGMA_ONCE */ 00022 00023 #if defined (ACE_HAS_WIN32_OVERLAPPED_IO) || defined (ACE_HAS_AIO_CALLS) 00024 // This only works on platforms that support async i/o. 00025 00026 #include "ace/Default_Constants.h" 00027 #include "ace/Asynch_IO.h" 00028 00029 ACE_BEGIN_VERSIONED_NAMESPACE_DECL 00030 00031 // Forward declarations 00032 class ACE_Message_Block; 00033 class ACE_INET_Addr; 00034 00035 /** 00036 * @class ACE_Asynch_Acceptor 00037 * 00038 * @brief This class is an example of the Acceptor Pattern. This class 00039 * will accept new connections and create new HANDLER to handle 00040 * the new connections. 00041 * 00042 * Unlike the ACE_Acceptor, however, this class is designed to 00043 * be used asynchronously. 00044 */ 00045 template <class HANDLER> 00046 class ACE_Asynch_Acceptor : public ACE_Handler 00047 { 00048 public: 00049 /// A do nothing constructor. 00050 ACE_Asynch_Acceptor (void); 00051 00052 /// Virtual destruction 00053 virtual ~ACE_Asynch_Acceptor (void); 00054 00055 /** 00056 * @c open starts one or more asynchronous accept requests on a 00057 * @a address. Each accept operation may optionally read an 00058 * initial buffer from the new connection when accepted. 00059 * 00060 * @param address The address to listen/accept connections on. 00061 * If the address does not specify a port, a random 00062 * port is selected and bound. 00063 * @param bytes_to_read Optional, specifies the maximum number of bytes 00064 * to read with the accept. The buffer for the initial 00065 * data is allocated internally and passed to the 00066 * @c ACE_Service_Handler::open() hook method. It is 00067 * legitimate only during the @c open() method and must 00068 * be copied if required after @c open() returns. 00069 * This pre-read function works only on Windows. 00070 * @param pass_addresses Optional, a non-zero value indicates that 00071 * the local and peer addresses should be passed to the 00072 * associated @c ACE_Service_Handler::addresses() method 00073 * after any call to @c validate_new_connection() and prior 00074 * to the @c open() hook method call. 00075 * @param backlog Optional, defaulting to @c ACE_DEFAULT_ASYNCH_BACKLOG (which 00076 * can be adjusted in your platform's @c config.h file). 00077 * Specifies the listening backlog for the listening socket. 00078 * @param reuse_addr Optional, indicates whether the @c SO_REUSEADDR 00079 * option is set on the listening socket or not. 00080 * @param proactor Optional, pointer to the @c ACE_Proactor to use for 00081 * demultiplexing asynchronous accepts. If 0, the 00082 * process's singleton @c ACE_Proactor is used. 00083 * @param validate_new_connection Optional, if true, this object's 00084 * @c validate_connection() method is called after 00085 * the accept completes, but before the service handler's 00086 * @c open() hook method is called. If @c 00087 * validate_connection() returns -1, the newly-accepted 00088 * socket is immediately closed, and the @c addresses() 00089 * method is not called. 00090 * @param reissue_accept Optional, if non-zero (the default), a new 00091 * asynchronous accept operation is started after each 00092 * completion, whether the completion is for success or 00093 * failure, and whether or not a successfully-accepted 00094 * connection is subsequently refused. 00095 * @param number_of_initial_accepts Optional, the number of asynchronous 00096 * accepts that are started immediately. If -1 (the 00097 * default), the value of @a backlog is used. 00098 * 00099 * @note On Windows, the peer address is only available at the time 00100 * the connection is accepted. Therefore, if you require the peer 00101 * address on Windows, do not rely on the 00102 * @c ACE_SOCK::get_remote_addr() method - it won't work. You must 00103 * supply a non-zero value for @a pass_addresses and obtain the 00104 * peer address in the @c ACE_Service_Handler::addresses() method. 00105 * 00106 * @see ACE_INET_Addr 00107 * @see ACE_Service_Handler 00108 */ 00109 virtual int open (const ACE_INET_Addr &address, 00110 size_t bytes_to_read = 0, 00111 bool pass_addresses = false, 00112 int backlog = ACE_DEFAULT_ASYNCH_BACKLOG, 00113 int reuse_addr = 1, 00114 ACE_Proactor *proactor = 0, 00115 bool validate_new_connection = false, 00116 int reissue_accept = 1, 00117 int number_of_initial_accepts = -1); 00118 00119 /// Get the underlying handle. 00120 virtual ACE_HANDLE get_handle (void) const; 00121 00122 /** 00123 * Set the underlying listen handle. It is the user's responsibility 00124 * to make sure that the old listen handle has been appropriately 00125 * closed and the all outstanding asynchronous operations have 00126 * either completed or have been canceled on the old listen handle. 00127 */ 00128 virtual int set_handle (ACE_HANDLE handle); 00129 00130 /// This initiates a new asynchronous accept operation. 00131 /** 00132 * You need only call this method if the @a reissue_accept argument 00133 * passed to @c open() was 0. 00134 */ 00135 virtual int accept (size_t bytes_to_read = 0, const void *act = 0); 00136 00137 /** 00138 * Cancels all pending accepts operations issued by this object. 00139 * 00140 * @note On Windows, only accept operations initiated by the calling thread 00141 * are canceled. 00142 */ 00143 virtual int cancel (void); 00144 00145 /** 00146 * Template method to validate peer before service is opened. 00147 * This method is called after a new connection is accepted if the 00148 * @a validate_connection argument to @c open() was non-zero or 00149 * the @c validate_new_connection() method is called to turn this 00150 * feature on. The default implementation returns 0. Users can 00151 * reimplement this method to perform validation of the peer 00152 * using it's address, running an authentication procedure (such as 00153 * SSL) or anything else necessary or desireable. The return value 00154 * from this method determines whether or not ACE will continue 00155 * opening the service or abort the connection. 00156 * 00157 * @param result Result of the connection acceptance. 00158 * @param remote Peer's address. 00159 * @param local Local address connection was accepted at. 00160 * 00161 * @retval -1 ACE_Asynch_Acceptor will close the connection, and 00162 * the service will not be opened. 00163 * @retval 0 Service opening will proceeed. 00164 */ 00165 virtual int validate_connection (const ACE_Asynch_Accept::Result& result, 00166 const ACE_INET_Addr &remote, 00167 const ACE_INET_Addr& local); 00168 00169 /** 00170 * Template method for deciding whether to reissue accept. 00171 * 00172 * This hook method is called after each accept completes to decide if 00173 * another accept should be initiated. If the method returns a non-zero 00174 * value, another accept is initiated. 00175 * 00176 * The default implemenation always returns the value passed as the 00177 * @c open() method's @a reissue_accept argument. That value can also 00178 * be changed using the @c reissue_accept() method. 00179 */ 00180 virtual int should_reissue_accept (void); 00181 00182 // 00183 // These are low level tweaking methods 00184 // 00185 00186 /// Get flag that indicates if parsing and passing of addresses to 00187 /// the service_handler is necessary. 00188 virtual bool pass_addresses (void) const; 00189 00190 /// Set flag that indicates if parsing and passing of addresses to 00191 /// the service_handler is necessary. 00192 virtual void pass_addresses (bool new_value); 00193 00194 /// Get flag that indicates if address validation is required. 00195 virtual bool validate_new_connection (void) const; 00196 00197 /// Set flag that indicates if address validation is required. 00198 virtual void validate_new_connection (bool new_value); 00199 00200 /// Get flag that indicates if a new accept should be reissued when a accept 00201 /// completes. 00202 virtual int reissue_accept (void) const; 00203 00204 /// Set flag that indicates if a new accept should be reissued when a accept 00205 /// completes. 00206 virtual void reissue_accept (int new_value); 00207 00208 /// Get bytes to be read with the <accept> call. 00209 virtual size_t bytes_to_read (void) const; 00210 00211 /// Set bytes to be read with the <accept> call. 00212 virtual void bytes_to_read (size_t new_value); 00213 00214 /// @deprecated address_size() assumes IPv4 use, so is not always valid. 00215 /// This method will be removed after ACE 5.5. Internal uses have been 00216 /// changes to base needed sizes on the addr_family_ member. 00217 static size_t address_size (void); 00218 00219 protected: 00220 00221 /// This is called when an outstanding accept completes. 00222 virtual void handle_accept (const ACE_Asynch_Accept::Result &result); 00223 00224 /// Return the listen handle. 00225 ACE_HANDLE handle (void) const; 00226 /// Set the listen handle. 00227 void handle (ACE_HANDLE h); 00228 00229 /// This parses the address from read buffer. 00230 void parse_address (const ACE_Asynch_Accept::Result &result, 00231 ACE_INET_Addr &remote_address, 00232 ACE_INET_Addr &local_address); 00233 00234 /// Return the asynch accept object. 00235 ACE_Asynch_Accept &asynch_accept (void); 00236 00237 /** 00238 * This is the template method used to create new handler. 00239 * Subclasses must overwrite this method if a new handler creation 00240 * strategy is required. 00241 */ 00242 virtual HANDLER *make_handler (void); 00243 00244 private: 00245 /// Handle used to listen for new connections. 00246 ACE_HANDLE listen_handle_; 00247 00248 /// Asynch_Accept used to make life easier :-) 00249 ACE_Asynch_Accept asynch_accept_; 00250 00251 /// Flag that indicates if parsing of addresses is necessary. 00252 bool pass_addresses_; 00253 00254 /// Flag that indicates if address validation is required. 00255 bool validate_new_connection_; 00256 00257 /// Flag that indicates if a new accept should be reissued when a 00258 /// accept completes. 00259 int reissue_accept_; 00260 00261 /// Bytes to be read with the <accept> call. 00262 size_t bytes_to_read_; 00263 00264 /// Address family used to open this object. Obtained from @a address passed 00265 /// to @c open(). 00266 int addr_family_; 00267 }; 00268 00269 ACE_END_VERSIONED_NAMESPACE_DECL 00270 00271 #if defined (ACE_TEMPLATES_REQUIRE_SOURCE) 00272 #include "ace/Asynch_Acceptor.cpp" 00273 #endif /* ACE_TEMPLATES_REQUIRE_SOURCE */ 00274 00275 #if defined (ACE_TEMPLATES_REQUIRE_PRAGMA) 00276 #pragma implementation ("Asynch_Acceptor.cpp") 00277 #endif /* ACE_TEMPLATES_REQUIRE_PRAGMA */ 00278 00279 #endif /* ACE_HAS_WIN32_OVERLAPPED_IO || ACE_HAS_AIO_CALLS */ 00280 #include /**/ "ace/post.h" 00281 #endif /* ACE_ASYNCH_ACCEPTOR_H */