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

Asynch_Acceptor.h

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

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