ACE/ace/Asynch_Connector.h

   1 /* -*- C++ -*- */
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Asynch_Connector.h
   6  *
   7  *  @author Alexander Libman <alibman@ihug.com.au>
   8  */
   9 //=============================================================================
  10
  11 #ifndef ACE_ASYNCH_CONNECTOR_H
  12 #define ACE_ASYNCH_CONNECTOR_H
  13 #include /**/ "ace/pre.h"
  14
  15 #include /**/ "ace/config-all.h"
  16
  17 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  18 # pragma once
  19 #endif /* ACE_LACKS_PRAGMA_ONCE */
  20
  21 #if (defined (ACE_WIN32) || defined (ACE_HAS_AIO_CALLS)) && !defined(ACE_HAS_WINCE)
  22 // This only works on platforms that support async i/o.
  23
  24 #include "ace/Asynch_IO.h"
  25 #include "ace/INET_Addr.h"
  26
  27 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  28
  29 // Forward declarations
  30 class ACE_Message_Block;
  31
  32 /**
  33  * @class ACE_Asynch_Connector
  34  *
  35  * @brief This class is an example of the Connector pattern.  This class
  36  * will establish new connections and create new HANDLER objects to handle
  37  * the new connections.
  38  *
  39  * Unlike the ACE_Connector, however, this class is designed to
  40  * be used asynchronously with the ACE Proactor framework.
  41  */
  42
  43 template <class HANDLER>
  44 class ACE_Asynch_Connector : public ACE_Handler
  45 {
  46 public:
  47   /// A do nothing constructor.
  48   ACE_Asynch_Connector (void);
  49
  50   /// Virtual destruction
  51   virtual ~ACE_Asynch_Connector (void);
  52
  53   /**
  54    * This opens asynch connector
  55    */
  56   virtual int open (bool pass_addresses = false,
  57                     ACE_Proactor *proactor = 0,
  58                     bool validate_new_connection = true);
  59
  60   /// This initiates a new asynchronous connect
  61   virtual int connect (const ACE_INET_Addr &remote_sap,
  62                        const ACE_INET_Addr &local_sap =
  63                          (const ACE_INET_Addr &)ACE_Addr::sap_any,
  64                        int reuse_addr = 1,
  65                        const void *act = 0);
  66
  67   /**
  68    * This cancels all pending accepts operations that were issued by
  69    * the calling thread.
  70    *
  71    * @note On Windows, this method does not cancel connect operations
  72    *       issued by other threads.
  73    *
  74    * @note On POSIX, delegates cancelation to ACE_POSIX_Asynch_Connect.
  75    */
  76   virtual int cancel (void);
  77
  78
  79   /**
  80    * Template method to validate peer before service is opened.
  81    * This method is called when the connection attempt completes,
  82    * whether it succeeded or failed, if the @a validate_connection
  83    * argument to @c open() was non-zero or the @c validate_new_connection()
  84    * method is called to turn this feature on.  The default implementation
  85    * returns 0.  Users can (and probably should) reimplement this method
  86    * to learn about the success or failure of the connection attempt.
  87    * If the connection completed successfully, this method can be used to
  88    * perform validation of the peer using it's address, running an
  89    * authentication procedure (such as SSL) or anything else necessary or
  90    * desireable. The return value from this method determines whether or
  91    * not ACE will continue opening the service or abort the connection.
  92    *
  93    * @param result  Result of the connection acceptance. Use
  94    *                result.success() to determine success or failure of
  95    *                the connection attempt.
  96    * @param remote  Peer's address. If the connection failed, this object
  97    *                is undefined.
  98    * @param local   Local address connection was completed from. If the
  99    *                connection failed, this object is undefined.
 100    *
 101    * @retval  -1  ACE_Asynch_Connector will close the connection, and
 102    *              the service will not be opened.
 103    * @retval  0   Service opening will proceeed.
 104    * @return  Return value is ignored if the connection attempt failed.
 105    */
 106   virtual int validate_connection (const ACE_Asynch_Connect::Result& result,
 107                                    const ACE_INET_Addr &remote,
 108                                    const ACE_INET_Addr& local);
 109
 110   //
 111   // These are low level tweaking methods
 112   //
 113
 114   /// Set and get flag that indicates if parsing and passing of
 115   /// addresses to the service_handler is necessary.
 116   virtual bool pass_addresses (void) const;
 117   virtual void pass_addresses (bool new_value);
 118
 119   /// Set and get flag that indicates if address validation is
 120   /// required.
 121   virtual bool validate_new_connection (void) const;
 122   virtual void validate_new_connection (bool new_value);
 123
 124 protected:
 125
 126   /// This is called when an outstanding accept completes.
 127   virtual void handle_connect (const ACE_Asynch_Connect::Result &result);
 128
 129
 130   /// This parses the address from read buffer.
 131   void parse_address (const ACE_Asynch_Connect::Result &result,
 132                       ACE_INET_Addr &remote_address,
 133                       ACE_INET_Addr &local_address);
 134
 135   /// Return the asynch Connect object.
 136   ACE_Asynch_Connect & asynch_connect (void);
 137
 138   /**
 139    * This is the template method used to create new handler.
 140    * Subclasses must overwrite this method if a new handler creation
 141    * strategy is required.
 142    */
 143   virtual HANDLER *make_handler (void);
 144
 145 private:
 146   /// Asynch_Connect used to make life easier :-)
 147   ACE_Asynch_Connect asynch_connect_;
 148
 149   /// Flag that indicates if parsing of addresses is necessary.
 150   bool pass_addresses_;
 151
 152   /// Flag that indicates if address validation is required.
 153   bool validate_new_connection_;
 154 };
 155
 156 ACE_END_VERSIONED_NAMESPACE_DECL
 157
 158 #if defined (ACE_TEMPLATES_REQUIRE_SOURCE)
 159 #include "ace/Asynch_Connector.cpp"
 160 #endif /* ACE_TEMPLATES_REQUIRE_SOURCE */
 161
 162 #if defined (ACE_TEMPLATES_REQUIRE_PRAGMA)
 163 #pragma implementation ("Asynch_Connector.cpp")
 164 #endif /* ACE_TEMPLATES_REQUIRE_PRAGMA */
 165
 166 #endif /* ACE_WIN32 || ACE_HAS_AIO_CALLS */
 167 #include /**/ "ace/post.h"
 168 #endif /* ACE_ASYNCH_CONNECTOR_H */