Changes to attempt to silence bcc64x
[ACE_TAO.git] / ACE / ace / Asynch_Acceptor.h
blob16f4edb0dc3cf760c71cf81403770f3f9d0f179a
1 /* -*- C++ -*- */
3 //=============================================================================
4 /**
5 * @file Asynch_Acceptor.h
7 * @author Irfan Pyarali (irfan@cs.wustl.edu)
8 */
9 //=============================================================================
11 #ifndef ACE_ASYNCH_ACCEPTOR_H
12 #define ACE_ASYNCH_ACCEPTOR_H
13 #include /**/ "ace/pre.h"
15 #include /**/ "ace/config-all.h"
17 #if !defined (ACE_LACKS_PRAGMA_ONCE)
18 # pragma once
19 #endif /* ACE_LACKS_PRAGMA_ONCE */
21 #if defined (ACE_HAS_WIN32_OVERLAPPED_IO) || defined (ACE_HAS_AIO_CALLS)
22 // This only works on platforms that support async i/o.
24 #include "ace/Default_Constants.h"
25 #include "ace/Asynch_IO.h"
27 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
29 // Forward declarations
30 class ACE_Message_Block;
31 class ACE_INET_Addr;
33 /**
34 * @class ACE_Asynch_Acceptor
36 * @brief This class is an example of the Acceptor Pattern. This class
37 * will accept new connections and create new HANDLER to handle
38 * the new connections.
40 * Unlike the ACE_Acceptor, however, this class is designed to
41 * be used asynchronously.
43 template <class HANDLER>
44 class ACE_Asynch_Acceptor : public ACE_Handler
46 public:
47 /// A do nothing constructor.
48 ACE_Asynch_Acceptor ();
50 /// Virtual destruction
51 virtual ~ACE_Asynch_Acceptor ();
53 /**
54 * @c open starts one or more asynchronous accept requests on a
55 * @a address. Each accept operation may optionally read an
56 * initial buffer from the new connection when accepted.
58 * @param address The address to listen/accept connections on.
59 * If the address does not specify a port, a random
60 * port is selected and bound.
61 * @param bytes_to_read Optional, specifies the maximum number of bytes
62 * to read with the accept. The buffer for the initial
63 * data is allocated internally and passed to the
64 * @c ACE_Service_Handler::open() hook method. It is
65 * legitimate only during the @c open() method and must
66 * be copied if required after @c open() returns.
67 * This pre-read function works only on Windows.
68 * @param pass_addresses Optional, a non-zero value indicates that
69 * the local and peer addresses should be passed to the
70 * associated @c ACE_Service_Handler::addresses() method
71 * after any call to @c validate_new_connection() and prior
72 * to the @c open() hook method call.
73 * @param backlog Optional, defaulting to @c ACE_DEFAULT_ASYNCH_BACKLOG (which
74 * can be adjusted in your platform's @c config.h file).
75 * Specifies the listening backlog for the listening socket.
76 * @param reuse_addr Optional, indicates whether the @c SO_REUSEADDR
77 * option is set on the listening socket or not.
78 * @param proactor Optional, pointer to the @c ACE_Proactor to use for
79 * demultiplexing asynchronous accepts. If 0, the
80 * process's singleton @c ACE_Proactor is used.
81 * @param validate_new_connection Optional, if true, this object's
82 * @c validate_connection() method is called after
83 * the accept completes, but before the service handler's
84 * @c open() hook method is called. If @c
85 * validate_connection() returns -1, the newly-accepted
86 * socket is immediately closed, and the @c addresses()
87 * method is not called.
88 * @param reissue_accept Optional, if non-zero (the default), a new
89 * asynchronous accept operation is started after each
90 * completion, whether the completion is for success or
91 * failure, and whether or not a successfully-accepted
92 * connection is subsequently refused.
93 * @param number_of_initial_accepts Optional, the number of asynchronous
94 * accepts that are started immediately. If -1 (the
95 * default), the value of @a backlog is used.
97 * @note On Windows, the peer address is only available at the time
98 * the connection is accepted. Therefore, if you require the peer
99 * address on Windows, do not rely on the
100 * @c ACE_SOCK::get_remote_addr() method - it won't work. You must
101 * supply a non-zero value for @a pass_addresses and obtain the
102 * peer address in the @c ACE_Service_Handler::addresses() method.
104 * @see ACE_INET_Addr
105 * @see ACE_Service_Handler
107 virtual int open (const ACE_INET_Addr &address,
108 size_t bytes_to_read = 0,
109 bool pass_addresses = false,
110 int backlog = ACE_DEFAULT_ASYNCH_BACKLOG,
111 int reuse_addr = 1,
112 ACE_Proactor *proactor = 0,
113 bool validate_new_connection = false,
114 int reissue_accept = 1,
115 int number_of_initial_accepts = -1);
117 /// Get the underlying handle.
118 virtual ACE_HANDLE get_handle () const;
121 * Set the underlying listen handle. It is the user's responsibility
122 * to make sure that the old listen handle has been appropriately
123 * closed and the all outstanding asynchronous operations have
124 * either completed or have been canceled on the old listen handle.
126 virtual int set_handle (ACE_HANDLE handle);
128 /// This initiates a new asynchronous accept operation.
130 * You need only call this method if the @a reissue_accept argument
131 * passed to @c open() was 0.
133 virtual int accept (size_t bytes_to_read = 0, const void *act = 0);
136 * Cancels all pending accepts operations issued by this object.
138 * @note On Windows, only accept operations initiated by the calling thread
139 * are canceled.
141 virtual int cancel ();
144 * Template method to validate peer before service is opened.
145 * This method is called after a new connection is accepted if the
146 * @a validate_connection argument to @c open() was non-zero or
147 * the @c validate_new_connection() method is called to turn this
148 * feature on. The default implementation returns 0. Users can
149 * reimplement this method to perform validation of the peer
150 * using it's address, running an authentication procedure (such as
151 * SSL) or anything else necessary or desireable. The return value
152 * from this method determines whether or not ACE will continue
153 * opening the service or abort the connection.
155 * @param result Result of the connection acceptance.
156 * @param remote Peer's address.
157 * @param local Local address connection was accepted at.
159 * @retval -1 ACE_Asynch_Acceptor will close the connection, and
160 * the service will not be opened.
161 * @retval 0 Service opening will proceeed.
163 virtual int validate_connection (const ACE_Asynch_Accept::Result& result,
164 const ACE_INET_Addr &remote,
165 const ACE_INET_Addr& local);
168 * Template method for deciding whether to reissue accept.
170 * This hook method is called after each accept completes to decide if
171 * another accept should be initiated. If the method returns a non-zero
172 * value, another accept is initiated.
174 * The default implementation always returns the value passed as the
175 * @c open() method's @a reissue_accept argument. That value can also
176 * be changed using the @c reissue_accept() method.
178 virtual int should_reissue_accept ();
181 // These are low level tweaking methods
184 /// Get flag that indicates if parsing and passing of addresses to
185 /// the service_handler is necessary.
186 virtual bool pass_addresses () const;
188 /// Set flag that indicates if parsing and passing of addresses to
189 /// the service_handler is necessary.
190 virtual void pass_addresses (bool new_value);
192 /// Get flag that indicates if address validation is required.
193 virtual bool validate_new_connection () const;
195 /// Set flag that indicates if address validation is required.
196 virtual void validate_new_connection (bool new_value);
198 /// Get flag that indicates if a new accept should be reissued when a accept
199 /// completes.
200 virtual int reissue_accept () const;
202 /// Set flag that indicates if a new accept should be reissued when a accept
203 /// completes.
204 virtual void reissue_accept (int new_value);
206 /// Get bytes to be read with the <accept> call.
207 virtual size_t bytes_to_read () const;
209 /// Set bytes to be read with the <accept> call.
210 virtual void bytes_to_read (size_t new_value);
212 protected:
213 /// This is called when an outstanding accept completes.
214 virtual void handle_accept (const ACE_Asynch_Accept::Result &result);
216 /// Return the listen handle.
217 ACE_HANDLE handle () const;
218 /// Set the listen handle.
219 void handle (ACE_HANDLE h);
221 /// This parses the address from read buffer.
222 void parse_address (const ACE_Asynch_Accept::Result &result,
223 ACE_INET_Addr &remote_address,
224 ACE_INET_Addr &local_address);
226 /// Return the asynch accept object.
227 ACE_Asynch_Accept &asynch_accept ();
230 * This is the template method used to create new handler.
231 * Subclasses must overwrite this method if a new handler creation
232 * strategy is required.
234 virtual HANDLER *make_handler ();
236 /// Address family used to open this object. Obtained from @a address passed
237 /// to @c open().
238 int addr_family_;
240 private:
241 /// Handle used to listen for new connections.
242 ACE_HANDLE listen_handle_;
244 /// Asynch_Accept used to make life easier :-)
245 ACE_Asynch_Accept asynch_accept_;
247 /// Flag that indicates if parsing of addresses is necessary.
248 bool pass_addresses_;
250 /// Flag that indicates if address validation is required.
251 bool validate_new_connection_;
253 /// Flag that indicates if a new accept should be reissued when a
254 /// accept completes.
255 int reissue_accept_;
257 /// Bytes to be read with the <accept> call.
258 size_t bytes_to_read_;
261 ACE_END_VERSIONED_NAMESPACE_DECL
263 #include "ace/Asynch_Acceptor.cpp"
265 #endif /* ACE_HAS_WIN32_OVERLAPPED_IO || ACE_HAS_AIO_CALLS */
266 #include /**/ "ace/post.h"
267 #endif /* ACE_ASYNCH_ACCEPTOR_H */