Asynch_Acceptor.h

Go to the documentation of this file.
00001 /* -*- C++ -*- */
00002 
00003 //=============================================================================
00004 /**
00005  *  @file    Asynch_Acceptor.h
00006  *
00007  *  Asynch_Acceptor.h,v 4.41 2006/02/21 18:05:29 schmidt 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)) && !defined(ACE_HAS_WINCE)
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 non-zero, 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                     int pass_addresses = 0,
00112                     int backlog = ACE_DEFAULT_ASYNCH_BACKLOG,
00113                     int reuse_addr = 1,
00114                     ACE_Proactor *proactor = 0,
00115                     int validate_new_connection = 0,
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    * @deprecated Use validate_connection() instead. Will be removed after
00171    * ACE 5.3.
00172    *
00173    * Template method for address validation.
00174    *
00175    * This hook method is called after a connection is accepted if
00176    * so specified on the call to the @c open() method. If this
00177    * method returns -1, the connection is immediately closed and
00178    * the service handler is not opened.
00179    *
00180    * The default implemenation always return 0.
00181    */
00182   virtual int validate_new_connection (const ACE_INET_Addr &remote_address);
00183 
00184   /**
00185    * Template method for deciding whether to reissue accept.
00186    *
00187    * This hook method is called after each accept completes to decide if
00188    * another accept should be initiated. If the method returns a non-zero
00189    * value, another accept is initiated.
00190    *
00191    * The default implemenation always returns the value passed as the
00192    * @c open() method's @a reissue_accept argument. That value can also
00193    * be changed using the @c reissue_accept() method.
00194    */
00195   virtual int should_reissue_accept (void);
00196 
00197   //
00198   // These are low level tweaking methods
00199   //
00200 
00201   /// Get flag that indicates if parsing and passing of addresses to
00202   /// the service_handler is necessary.
00203   virtual int pass_addresses (void) const;
00204 
00205   /// Set flag that indicates if parsing and passing of addresses to
00206   /// the service_handler is necessary.
00207   virtual void pass_addresses (int new_value);
00208 
00209   /// Get flag that indicates if address validation is required.
00210   virtual int validate_new_connection (void) const;
00211 
00212   /// Set flag that indicates if address validation is required.
00213   virtual void validate_new_connection (int new_value);
00214 
00215   /// Get flag that indicates if a new accept should be reissued when a accept
00216   /// completes.
00217   virtual int reissue_accept (void) const;
00218 
00219   /// Set flag that indicates if a new accept should be reissued when a accept
00220   /// completes.
00221   virtual void reissue_accept (int new_value);
00222 
00223   /// Get bytes to be read with the <accept> call.
00224   virtual size_t bytes_to_read (void) const;
00225 
00226   /// Set bytes to be read with the <accept> call.
00227   virtual void bytes_to_read (size_t new_value);
00228 
00229   /// @deprecated address_size() assumes IPv4 use, so is not always valid.
00230   /// This method will be removed after ACE 5.5. Internal uses have been
00231   /// changes to base needed sizes on the addr_family_ member.
00232   static size_t address_size (void);
00233 
00234 protected:
00235 
00236   /// This is called when an outstanding accept completes.
00237   virtual void handle_accept (const ACE_Asynch_Accept::Result &result);
00238 
00239   /// Return the listen handle.
00240   ACE_HANDLE handle (void) const;
00241   /// Set the listen handle.
00242   void handle (ACE_HANDLE h);
00243 
00244   /// This parses the address from read buffer.
00245   void parse_address (const ACE_Asynch_Accept::Result &result,
00246                       ACE_INET_Addr &remote_address,
00247                       ACE_INET_Addr &local_address);
00248 
00249   /// Return the asynch accept object.
00250   ACE_Asynch_Accept &asynch_accept (void);
00251 
00252   /**
00253    * This is the template method used to create new handler.
00254    * Subclasses must overwrite this method if a new handler creation
00255    * strategy is required.
00256    */
00257   virtual HANDLER *make_handler (void);
00258 
00259 private:
00260   /// Handle used to listen for new connections.
00261   ACE_HANDLE listen_handle_;
00262 
00263   /// Asynch_Accept used to make life easier :-)
00264   ACE_Asynch_Accept asynch_accept_;
00265 
00266   /// Flag that indicates if parsing of addresses is necessary.
00267   int pass_addresses_;
00268 
00269   /// Flag that indicates if address validation is required.
00270   int validate_new_connection_;
00271 
00272   /// Flag that indicates if a new accept should be reissued when a
00273   /// accept completes.
00274   int reissue_accept_;
00275 
00276   /// Bytes to be read with the <accept> call.
00277   size_t bytes_to_read_;
00278 
00279   /// Address family used to open this object. Obtained from @a address passed
00280   /// to @c open().
00281   int addr_family_;
00282 };
00283 
00284 ACE_END_VERSIONED_NAMESPACE_DECL
00285 
00286 #if defined (ACE_TEMPLATES_REQUIRE_SOURCE)
00287 #include "ace/Asynch_Acceptor.cpp"
00288 #endif /* ACE_TEMPLATES_REQUIRE_SOURCE */
00289 
00290 #if defined (ACE_TEMPLATES_REQUIRE_PRAGMA)
00291 #pragma implementation ("Asynch_Acceptor.cpp")
00292 #endif /* ACE_TEMPLATES_REQUIRE_PRAGMA */
00293 
00294 #endif /* ACE_WIN32 || ACE_HAS_AIO_CALLS */
00295 #include /**/ "ace/post.h"
00296 #endif /* ACE_ASYNCH_ACCEPTOR_H */

Generated on Thu Nov 9 09:41:46 2006 for ACE by doxygen 1.3.6