00001 /* -*- C++ -*- */ 00002 00003 //============================================================================= 00004 /** 00005 * @file Asynch_IO.h 00006 * 00007 * $Id: Asynch_IO.h 84837 2009-03-16 13:01:15Z johnnyw $ 00008 * 00009 * This works on Win32 (defined (ACE_WIN32) && !defined 00010 * (ACE_HAS_WINCE)) platforms and on POSIX4 platforms with {aio_*} 00011 * routines (defined (ACE_HAS_AIO_CALLS)) 00012 * 00013 * On Win32 platforms, the implementation of 00014 * {ACE_Asynch_Transmit_File} and {ACE_Asynch_Accept} are only 00015 * supported if ACE_HAS_WINSOCK2 is defined or you are on WinNT 4.0 00016 * or higher. 00017 * 00018 * @author Irfan Pyarali <irfan@cs.wustl.edu> 00019 * @author Tim Harrison <harrison@cs.wustl.edu> 00020 * @author Alexander Babu Arulanthu <alex@cs.wustl.edu> 00021 * @author Roger Tragin <r.tragin@computer.org> 00022 * @author Alexander Libman <alibman@ihug.com.au> 00023 */ 00024 //============================================================================= 00025 00026 #ifndef ACE_ASYNCH_IO_H 00027 #define ACE_ASYNCH_IO_H 00028 #include /**/ "ace/pre.h" 00029 00030 #include /**/ "ace/ACE_export.h" 00031 00032 #if !defined (ACE_LACKS_PRAGMA_ONCE) 00033 #pragma once 00034 #endif /* ACE_LACKS_PRAGMA_ONCE */ 00035 00036 #if defined (ACE_HAS_WIN32_OVERLAPPED_IO) || defined (ACE_HAS_AIO_CALLS) 00037 00038 #include "ace/Synch_Traits.h" 00039 #if defined (ACE_HAS_THREADS) 00040 # include "ace/Thread_Mutex.h" 00041 #else 00042 # include "ace/Null_Mutex.h" 00043 #endif /* ACE_HAS_THREADS */ 00044 #include "ace/Refcounted_Auto_Ptr.h" 00045 00046 #include "ace/os_include/os_signal.h" 00047 #include "ace/os_include/sys/os_socket.h" 00048 #include "ace/os_include/sys/os_types.h" 00049 00050 ACE_BEGIN_VERSIONED_NAMESPACE_DECL 00051 00052 # if defined (ACE_HAS_WIN32_OVERLAPPED_IO) 00053 typedef TRANSMIT_FILE_BUFFERS ACE_TRANSMIT_FILE_BUFFERS; 00054 typedef LPTRANSMIT_FILE_BUFFERS ACE_LPTRANSMIT_FILE_BUFFERS; 00055 typedef PTRANSMIT_FILE_BUFFERS ACE_PTRANSMIT_FILE_BUFFERS; 00056 00057 # define ACE_INFINITE INFINITE 00058 # define ACE_STATUS_TIMEOUT STATUS_TIMEOUT 00059 # define ACE_WAIT_FAILED WAIT_FAILED 00060 # define ACE_WAIT_TIMEOUT WAIT_TIMEOUT 00061 # else /* ACE_HAS_WIN32_OVERLAPPED_IO */ 00062 struct ACE_TRANSMIT_FILE_BUFFERS 00063 { 00064 void *Head; 00065 size_t HeadLength; 00066 void *Tail; 00067 size_t TailLength; 00068 }; 00069 typedef ACE_TRANSMIT_FILE_BUFFERS* ACE_PTRANSMIT_FILE_BUFFERS; 00070 typedef ACE_TRANSMIT_FILE_BUFFERS* ACE_LPTRANSMIT_FILE_BUFFERS; 00071 00072 # if !defined (ACE_INFINITE) 00073 # define ACE_INFINITE LONG_MAX 00074 # endif /* ACE_INFINITE */ 00075 # define ACE_STATUS_TIMEOUT LONG_MAX 00076 # define ACE_WAIT_FAILED LONG_MAX 00077 # define ACE_WAIT_TIMEOUT LONG_MAX 00078 # endif /* ACE_HAS_WIN32_OVERLAPPED_IO */ 00079 00080 // Forward declarations 00081 class ACE_Proactor; 00082 class ACE_Handler; 00083 class ACE_Message_Block; 00084 class ACE_INET_Addr; 00085 class ACE_Addr; 00086 00087 // Forward declarations 00088 class ACE_Asynch_Result_Impl; 00089 class ACE_Time_Value; 00090 00091 /** 00092 * @class ACE_Asynch_Result 00093 * 00094 * @brief An interface base class which allows users access to common 00095 * information related to an asynchronous operation. 00096 * 00097 * An interface base class from which you can obtain some basic 00098 * information like the number of bytes transferred, the ACT 00099 * associated with the asynchronous operation, indication of 00100 * success or failure, etc. Subclasses may want to store more 00101 * information that is particular to the asynchronous operation 00102 * it represents. 00103 */ 00104 class ACE_Export ACE_Asynch_Result 00105 { 00106 00107 public: 00108 /// Number of bytes transferred by the operation. 00109 size_t bytes_transferred (void) const; 00110 00111 /// ACT associated with the operation. 00112 const void *act (void) const; 00113 00114 /// Did the operation succeed? 00115 int success (void) const; 00116 00117 /** 00118 * This is the ACT associated with the handle on which the 00119 * Asynch_Operation takes place. 00120 * 00121 * On WIN32, this returns the ACT associated with the handle when it 00122 * was registered with the I/O completion port. 00123 * 00124 * @@ This is not implemented for POSIX4 platforms. Returns 0. 00125 */ 00126 const void *completion_key (void) const; 00127 00128 /// Error value if the operation fails. 00129 unsigned long error (void) const; 00130 00131 /** 00132 * On WIN32, this returns the event associated with the OVERLAPPED 00133 * structure. 00134 * 00135 * This returns ACE_INVALID_HANDLE on POSIX4-Unix platforms. 00136 */ 00137 ACE_HANDLE event (void) const; 00138 00139 /** 00140 * This really makes sense only when doing file I/O. 00141 * 00142 * On WIN32, these are represented in the OVERLAPPED datastructure. 00143 * 00144 * @@ On POSIX4-Unix, offset_high should be supported using 00145 * aiocb64. 00146 */ 00147 unsigned long offset (void) const; 00148 unsigned long offset_high (void) const; 00149 00150 /** 00151 * Priority of the operation. 00152 * 00153 * On POSIX4-Unix, this is supported. Priority works like {nice} in 00154 * Unix. Negative values are not allowed. 0 means priority of the 00155 * operation same as the process priority. 1 means priority of the 00156 * operation is one less than process. And so forth. 00157 * 00158 * On Win32, this is a no-op. 00159 */ 00160 int priority (void) const; 00161 00162 /** 00163 * POSIX4 real-time signal number to be used for the 00164 * operation. {signal_number} ranges from ACE_SIGRTMIN to ACE_SIGRTMAX. By 00165 * default, ACE_SIGRTMIN is used to issue {aio_} calls. This is a no-op 00166 * on non-POSIX4 systems and returns 0. 00167 */ 00168 int signal_number (void) const; 00169 00170 00171 /// Destructor. 00172 virtual ~ACE_Asynch_Result (void); 00173 00174 protected: 00175 /// Constructor. This implementation will not be deleted. The 00176 /// implementation will be deleted by the Proactor. 00177 ACE_Asynch_Result (ACE_Asynch_Result_Impl *implementation); 00178 00179 /// Get the implementation class. 00180 ACE_Asynch_Result_Impl *implementation (void) const; 00181 00182 /// Implementation class. 00183 ACE_Asynch_Result_Impl *implementation_; 00184 }; 00185 00186 // Forward declarations 00187 class ACE_Asynch_Operation_Impl; 00188 00189 /** 00190 * @class ACE_Asynch_Operation 00191 * 00192 * @brief This is an interface base class for all asynch 00193 * operations. The resposiblility of this class is to forward 00194 * all methods to its delegation/implementation class, e.g., 00195 * ACE_WIN32_Asynch_Operation or ACE_POSIX_Asynch_Operation. 00196 * 00197 * There are some attributes and functionality which is common 00198 * to all asychronous operations. The delegation classes of this 00199 * class will factor out this code. 00200 */ 00201 class ACE_Export ACE_Asynch_Operation 00202 { 00203 00204 public: 00205 /** 00206 * Initializes the factory with information which will be used with 00207 * each asynchronous call. If ({handle} == ACE_INVALID_HANDLE), 00208 * {ACE_Handler::handle} will be called on the {handler} to get the 00209 * correct handle. 00210 */ 00211 int open (ACE_Handler &handler, 00212 ACE_HANDLE handle, 00213 const void *completion_key, 00214 ACE_Proactor *proactor); 00215 00216 /** 00217 * (Attempts to) cancel the asynchronous operation pending against 00218 * the {handle} registered with this Operation. 00219 * 00220 * All completion notifications for the I/O operations will occur 00221 * normally. 00222 * 00223 * = Return Values: 00224 * 00225 * -1 : Operation failed. (can get only in POSIX). 00226 * 0 : All the operations were cancelled. 00227 * 1 : All the operations were already finished in this 00228 * handle. Unable to cancel them. 00229 * 2 : Atleast one of the requested operations cannot be 00230 * cancelled. 00231 * 00232 * There is slight difference in the semantics between NT and POSIX 00233 * platforms which is given below. 00234 * 00235 * = Win32 : 00236 * 00237 * cancels all pending accepts operations that were issued by the 00238 * calling thread. The function does not cancel asynchronous 00239 * operations issued by other threads. 00240 * All I/O operations that are canceled will complete with the 00241 * error ERROR_OPERATION_ABORTED. 00242 * 00243 * = POSIX: 00244 * 00245 * Attempts to cancel one or more asynchronous I/O requests 00246 * currently outstanding against the {handle} registered in this 00247 * operation. 00248 * For requested operations that are successfully canceled, the 00249 * associated error status is set to ECANCELED. 00250 */ 00251 int cancel (void); 00252 00253 00254 // = Access methods. 00255 00256 /// Return the underlying proactor. 00257 ACE_Proactor* proactor (void) const; 00258 00259 /// Destructor. 00260 virtual ~ACE_Asynch_Operation (void); 00261 00262 protected: 00263 /// Constructor. 00264 ACE_Asynch_Operation (void); 00265 00266 /// Return the underlying implementation class. 00267 virtual ACE_Asynch_Operation_Impl *implementation (void) const = 0; 00268 00269 /// Get a proactor for/from the user 00270 ACE_Proactor *get_proactor (ACE_Proactor *user_proactor, 00271 ACE_Handler &handler) const; 00272 }; 00273 00274 // Forward declarations 00275 class ACE_Asynch_Read_Stream_Result_Impl; 00276 class ACE_Asynch_Read_Stream_Impl; 00277 00278 /** 00279 * @class ACE_Asynch_Read_Stream 00280 * 00281 * @brief This class is a factory for starting off asynchronous reads 00282 * on a stream. This class forwards all methods to its 00283 * implementation class. 00284 * 00285 * Once {open} is called, multiple asynchronous {read}s can 00286 * started using this class. An ACE_Asynch_Read_Stream::Result 00287 * will be passed back to the {handler} when the asynchronous 00288 * reads completes through the {ACE_Handler::handle_read_stream} 00289 * callback. 00290 */ 00291 class ACE_Export ACE_Asynch_Read_Stream : public ACE_Asynch_Operation 00292 { 00293 00294 public: 00295 /// A do nothing constructor. 00296 ACE_Asynch_Read_Stream (void); 00297 00298 /// Destructor 00299 virtual ~ACE_Asynch_Read_Stream (void); 00300 00301 /** 00302 * Initializes the factory with information which will be used with 00303 * each asynchronous call. 00304 * 00305 * @param handler The ACE_Handler that will be called to handle completions 00306 * for operations initiated using this factory. 00307 * @param handle The handle that future read operations will use. 00308 * If handle == @c ACE_INVALID_HANDLE, 00309 * ACE_Handler::handle() will be called on @ handler 00310 * to get the correct handle. 00311 * 00312 * @retval 0 for success. 00313 * @retval -1 for failure; consult @c errno for further information. 00314 */ 00315 int open (ACE_Handler &handler, 00316 ACE_HANDLE handle = ACE_INVALID_HANDLE, 00317 const void *completion_key = 0, 00318 ACE_Proactor *proactor = 0); 00319 00320 /** 00321 * Initiate an asynchronous read operation. 00322 * 00323 * @param message_block The ACE_Message_Block to receive the data. 00324 * Received bytes will be placed in the block 00325 * beginning at its current write pointer. 00326 * If data is read, the message block's write 00327 * pointer will be advanced by the number of 00328 * bytes read. 00329 * @param num_bytes_to_read The maximum number of bytes to read. 00330 * @param act Asynchronous Completion Token; passed through to 00331 * the completion handler in the Result object. 00332 * @param priority Priority of the operation. On POSIX4-Unix, 00333 * this is supported. Works like @c nice in Unix. 00334 * Negative values are not allowed. 0 means 00335 * priority of the operation same as the process 00336 * priority. 1 means priority of the operation is 00337 * one less than process priority, etc. 00338 * Ignored on Windows. 00339 * @param signal_number The POSIX4 real-time signal number to be used 00340 * to signal completion of the operation. Values 00341 * range from ACE_SIGRTMIN to ACE_SIGRTMAX. 00342 * This argument is ignored on non-POSIX4 systems. 00343 */ 00344 int read (ACE_Message_Block &message_block, 00345 size_t num_bytes_to_read, 00346 const void *act = 0, 00347 int priority = 0, 00348 int signal_number = ACE_SIGRTMIN); 00349 00350 #if defined (ACE_HAS_WIN32_OVERLAPPED_IO) 00351 /** 00352 * Same as above but with scatter support, through chaining of composite 00353 * message blocks using the continuation field. 00354 */ 00355 int readv (ACE_Message_Block &message_block, 00356 size_t num_bytes_to_read, 00357 const void *act = 0, 00358 int priority = 0, 00359 int signal_number = ACE_SIGRTMIN); 00360 #endif /* defined (ACE_HAS_WIN32_OVERLAPPED_IO) */ 00361 00362 /// Return the underlying implementation class. 00363 // (this should be protected...) 00364 virtual ACE_Asynch_Operation_Impl *implementation (void) const; 00365 00366 protected: 00367 /// Implementation class that all methods will be forwarded to. 00368 ACE_Asynch_Read_Stream_Impl *implementation_; 00369 00370 public: 00371 /** 00372 * @class Result 00373 * 00374 * @brief This is the class which will be passed back to the 00375 * ACE_Handler::handle_read_stream when the asynchronous read completes. 00376 * This class forwards all the methods to the implementation classes. 00377 * 00378 * This class has all the information necessary for the 00379 * handler to uniquiely identify the completion of the 00380 * asynchronous read. 00381 */ 00382 class ACE_Export Result : public ACE_Asynch_Result 00383 { 00384 00385 /// The concrete implementation result classes only construct this 00386 /// class. 00387 friend class ACE_POSIX_Asynch_Read_Stream_Result; 00388 friend class ACE_WIN32_Asynch_Read_Stream_Result; 00389 00390 public: 00391 /// The number of bytes which were requested at the start of the 00392 /// asynchronous read. 00393 size_t bytes_to_read (void) const; 00394 00395 /// Message block which contains the read data. 00396 ACE_Message_Block &message_block (void) const; 00397 00398 /// I/O handle used for reading. 00399 ACE_HANDLE handle (void) const; 00400 00401 /// Get the implementation class. 00402 ACE_Asynch_Read_Stream_Result_Impl *implementation (void) const; 00403 00404 protected: 00405 /// Constructor. 00406 Result (ACE_Asynch_Read_Stream_Result_Impl *implementation); 00407 00408 /// Destructor. 00409 virtual ~Result (void); 00410 00411 /// The implementation class. 00412 ACE_Asynch_Read_Stream_Result_Impl *implementation_; 00413 }; 00414 private: 00415 ACE_UNIMPLEMENTED_FUNC (void operator= (const ACE_Asynch_Read_Stream &)) 00416 ACE_UNIMPLEMENTED_FUNC (ACE_Asynch_Read_Stream (const ACE_Asynch_Read_Stream &)) 00417 }; 00418 00419 // Forward declarations 00420 class ACE_Asynch_Write_Stream_Impl; 00421 class ACE_Asynch_Write_Stream_Result_Impl; 00422 00423 /** 00424 * @class ACE_Asynch_Write_Stream 00425 * 00426 * @brief This class is a factory for initiating asynchronous writes 00427 * on a connected TCP/IP stream. This class forwards all methods to its 00428 * implementation class. 00429 * 00430 * Once open() is called, multiple asynchronous writes can be 00431 * started using this class. An ACE_Asynch_Write_Stream::Result 00432 * will be passed to the ACE_Handler::handle_write_stream() method on the 00433 * opened ACE_Handler object when the asynchronous write completes. 00434 */ 00435 class ACE_Export ACE_Asynch_Write_Stream : public ACE_Asynch_Operation 00436 { 00437 00438 public: 00439 /// A do nothing constructor. 00440 ACE_Asynch_Write_Stream (void); 00441 00442 /// Destructor. 00443 virtual ~ACE_Asynch_Write_Stream (void); 00444 00445 /** 00446 * Initializes the factory with information which will be used with 00447 * each asynchronous operation. 00448 * 00449 * @param handler ACE_Handler to be notified when operations initiated 00450 * via this factory complete. The handle_write_stream() 00451 * method will be called on this object. 00452 * @param handle The socket handle to initiate write operations on. 00453 * If handle is @c ACE_INVALID_HANDLE, 00454 * ACE_Handler::handle() will be called on handler to 00455 * get the handle value. 00456 * @param completion_key A token that is passed to the completion handler. 00457 * @param proactor The ACE_Proactor object which will control operation 00458 * completion and dispatching the results to handler. 00459 * If this is 0, the process's singleton ACE_Proactor 00460 * will be used. 00461 * 00462 * @retval 0 for success. 00463 * @retval -1 for failure; consult @c errno for further information. 00464 */ 00465 int open (ACE_Handler &handler, 00466 ACE_HANDLE handle = ACE_INVALID_HANDLE, 00467 const void *completion_key = 0, 00468 ACE_Proactor *proactor = 0); 00469 00470 /** 00471 * Initiates an asynchronous write on a socket. If the operation completes 00472 * the ACE_Handler object registered in open() will receive a completion 00473 * callback via its handle_write_stream() method. 00474 * 00475 * @param bytes_to_write The number of bytes to write. 00476 * @param message_block The ACE_Message_Block containing data to write. 00477 * Data is written to the socket beginning at the 00478 * block's rd_ptr. Upon successful completion 00479 * of the write operation, the message_block rd_ptr 00480 * is updated to reflect the data that was written. 00481 * @param act Token that is passed through to the completion 00482 * handler. 00483 * @param priority Priority of the operation. This argument only has 00484 * an affect on POSIX4-Unix. Works like @c nice in 00485 * Unix; negative values are not allowed. 0 means 00486 * priority of the operation same as the process 00487 * priority. 1 means priority of the operation is one 00488 * less than the process, and so forth. 00489 * @param signal_number The POSIX4 real-time signal number to be used 00490 * for the operation. signal_number ranges from 00491 * ACE_SIGRTMIN to ACE_SIGRTMAX. This argument is 00492 * not used on other platforms. 00493 * 00494 * @retval 0 for success, and the handle_write_stream associated 00495 * with the opened ACE_Handler will be called. An 00496 * instance of ACE_Asynch_Write_Stream::Result will be 00497 * passed to the completion handler. 00498 * @retval -1 for failure; consult @c errno for further information. 00499 */ 00500 int write (ACE_Message_Block &message_block, 00501 size_t bytes_to_write, 00502 const void *act = 0, 00503 int priority = 0, 00504 int signal_number = ACE_SIGRTMIN); 00505 00506 #if defined (ACE_HAS_WIN32_OVERLAPPED_IO) 00507 /** 00508 * Same as above but with gather support, through chaining of composite 00509 * message blocks using the continuation field. 00510 */ 00511 int writev (ACE_Message_Block &message_block, 00512 size_t bytes_to_write, 00513 const void *act = 0, 00514 int priority = 0, 00515 int signal_number = ACE_SIGRTMIN); 00516 #endif /* defined (ACE_HAS_WIN32_OVERLAPPED_IO) */ 00517 00518 /// Return the underlying implementation class. 00519 /// @todo (this should be protected...) 00520 virtual ACE_Asynch_Operation_Impl *implementation (void) const; 00521 00522 protected: 00523 /// Implementation class that all methods will be forwarded to. 00524 ACE_Asynch_Write_Stream_Impl *implementation_; 00525 00526 public: 00527 /** 00528 * @class Result 00529 * 00530 * @brief This is that class which will be passed back to the 00531 * ACE_Handler when the asynchronous write completes. This class 00532 * forwards all the methods to the implementation class. 00533 * 00534 * This class has all the information necessary for the 00535 * handler to uniquiely identify the completion of the 00536 * asynchronous write. 00537 */ 00538 class ACE_Export Result : public ACE_Asynch_Result 00539 { 00540 00541 /// The concrete implementation result classes only construct this 00542 /// class. 00543 friend class ACE_POSIX_Asynch_Write_Stream_Result; 00544 friend class ACE_WIN32_Asynch_Write_Stream_Result; 00545 00546 public: 00547 /// The number of bytes which were requested at the start of the 00548 /// asynchronous write. 00549 size_t bytes_to_write (void) const; 00550 00551 /// Message block that contains the data to be written. 00552 ACE_Message_Block &message_block (void) const; 00553 00554 /// I/O handle used for writing. 00555 ACE_HANDLE handle (void) const; 00556 00557 /// Get the implementation class. 00558 ACE_Asynch_Write_Stream_Result_Impl *implementation (void) const; 00559 00560 protected: 00561 /// Constructor. 00562 Result (ACE_Asynch_Write_Stream_Result_Impl *implementation); 00563 00564 /// Destructor. 00565 virtual ~Result (void); 00566 00567 /// Implementation class. 00568 ACE_Asynch_Write_Stream_Result_Impl *implementation_; 00569 }; 00570 private: 00571 ACE_UNIMPLEMENTED_FUNC (void operator= (const ACE_Asynch_Write_Stream &)) 00572 ACE_UNIMPLEMENTED_FUNC (ACE_Asynch_Write_Stream (const ACE_Asynch_Write_Stream &)) 00573 }; 00574 00575 // Forward declarations 00576 class ACE_Asynch_Read_File_Impl; 00577 class ACE_Asynch_Read_File_Result_Impl; 00578 00579 /** 00580 * @class ACE_Asynch_Read_File 00581 * 00582 * @brief This class is a factory for starting off asynchronous reads 00583 * on a file. This class forwards all methods to its 00584 * implementation class. 00585 * 00586 * Once open() is called, multiple asynchronous reads can 00587 * started using this class. An ACE_Asynch_Read_File::Result 00588 * will be passed back to the completion handler's 00589 * ACE_Handler::handle_read_file() method when each asynchronous 00590 * read completes. 00591 * This class differs slightly from ACE_Asynch_Read_Stream as it 00592 * allows the user to specify an offset for the read. 00593 */ 00594 class ACE_Export ACE_Asynch_Read_File : public ACE_Asynch_Read_Stream 00595 { 00596 00597 public: 00598 /// A do nothing constructor. 00599 ACE_Asynch_Read_File (void); 00600 00601 /// Destructor. 00602 virtual ~ACE_Asynch_Read_File (void); 00603 00604 /** 00605 * Initializes the factory with information which will be used with 00606 * each asynchronous operation. 00607 * 00608 * @param handler ACE_Handler to be notified when operations initiated 00609 * via this factory complete. The 00610 * ACE_Handler::handle_read_file() method will be 00611 * called on this object. 00612 * @param handle The file handle to initiate read operations on. 00613 * If handle is @c ACE_INVALID_HANDLE, 00614 * ACE_Handler::handle() will be called on handler to 00615 * get the handle value. 00616 * @param completion_key A token that is passed to the completion handler. 00617 * @param proactor The ACE_Proactor object which will control operation 00618 * completion and dispatching the results to handler. 00619 * If this is 0, the process's singleton ACE_Proactor 00620 * will be used. 00621 * 00622 * @retval 0 for success. 00623 * @retval -1 for failure; consult @c errno for further information. 00624 */ 00625 int open (ACE_Handler &handler, 00626 ACE_HANDLE handle = ACE_INVALID_HANDLE, 00627 const void *completion_key = 0, 00628 ACE_Proactor *proactor = 0); 00629 00630 /** 00631 * This starts off an asynchronous read. Upto {bytes_to_read} will 00632 * be read and stored in the {message_block}. The read will start 00633 * at {offset} from the beginning of the file. Priority of the 00634 * operation is specified by {priority}. On POSIX4-Unix, this is 00635 * supported. Works like {nice} in Unix. Negative values are not 00636 * allowed. 0 means priority of the operation same as the process 00637 * priority. 1 means priority of the operation is one less than 00638 * process. And so forth. On Win32, this argument is a no-op. 00639 * {signal_number} is the POSIX4 real-time signal number to be used 00640 * for the operation. {signal_number} ranges from ACE_SIGRTMIN to 00641 * ACE_SIGRTMAX. This argument is a no-op on non-POSIX4 systems. 00642 */ 00643 int read (ACE_Message_Block &message_block, 00644 size_t bytes_to_read, 00645 unsigned long offset = 0, 00646 unsigned long offset_high = 0, 00647 const void *act = 0, 00648 int priority = 0, 00649 int signal_number = ACE_SIGRTMIN); 00650 00651 #if (defined (ACE_WIN32) && !defined (ACE_HAS_WINCE)) 00652 /** 00653 * Same as above but with scatter support, through chaining of composite 00654 * message blocks using the continuation field. 00655 * @note In win32 Each data block payload must be at least the size of a system 00656 * memory page and must be aligned on a system memory page size boundary 00657 */ 00658 int readv (ACE_Message_Block &message_block, 00659 size_t bytes_to_read, 00660 unsigned long offset = 0, 00661 unsigned long offset_high = 0, 00662 const void *act = 0, 00663 int priority = 0, 00664 int signal_number = ACE_SIGRTMIN); 00665 #endif /* (defined (ACE_WIN32) && !defined (ACE_HAS_WINCE)) */ 00666 00667 /// Return the underlying implementation class. 00668 // (this should be protected...) 00669 virtual ACE_Asynch_Operation_Impl *implementation (void) const; 00670 00671 protected: 00672 /// Delegation/implementation class that all methods will be 00673 /// forwarded to. 00674 ACE_Asynch_Read_File_Impl *implementation_; 00675 00676 public: 00677 /** 00678 * @class Result 00679 * 00680 * @brief This is that class which will be passed back to the 00681 * {handler} when the asynchronous read completes. This class 00682 * forwards all the methods to the implementation class. 00683 * 00684 * This class has all the information necessary for the 00685 * {handler} to uniquiely identify the completion of the 00686 * asynchronous read. 00687 * This class differs slightly from 00688 * ACE_Asynch_Read_Stream::Result as it calls back 00689 * {ACE_Handler::handle_read_file} on the {handler} instead of 00690 * {ACE_Handler::handle_read_stream}. No additional state is 00691 * required by this class as ACE_Asynch_Result can store the 00692 * {offset}. 00693 */ 00694 class ACE_Export Result : public ACE_Asynch_Read_Stream::Result 00695 { 00696 00697 /// The concrete implementation result classes only construct this 00698 /// class. 00699 friend class ACE_POSIX_Asynch_Read_File_Result; 00700 friend class ACE_WIN32_Asynch_Read_File_Result; 00701 00702 public: 00703 /// Get the implementation class. 00704 ACE_Asynch_Read_File_Result_Impl *implementation (void) const; 00705 00706 protected: 00707 /// Constructor. This implementation will not be deleted. 00708 Result (ACE_Asynch_Read_File_Result_Impl *implementation); 00709 00710 /// Destructor. 00711 virtual ~Result (void); 00712 00713 /// The implementation class. 00714 ACE_Asynch_Read_File_Result_Impl *implementation_; 00715 00716 private: 00717 /// Here just to provide an dummpy implementation, since the 00718 /// one auto generated by MSVC is flagged as infinitely recursive 00719 void operator= (Result &) {} 00720 }; 00721 private: 00722 ACE_UNIMPLEMENTED_FUNC (void operator= (const ACE_Asynch_Read_File &)) 00723 ACE_UNIMPLEMENTED_FUNC (ACE_Asynch_Read_File (const ACE_Asynch_Read_File &)) 00724 }; 00725 00726 // Forward declarations 00727 class ACE_Asynch_Write_File_Impl; 00728 class ACE_Asynch_Write_File_Result_Impl; 00729 00730 /** 00731 * @class ACE_Asynch_Write_File 00732 * 00733 * @brief This class is a factory for starting off asynchronous writes 00734 * on a file. This class forwards all methods to its 00735 * implementation class. 00736 * 00737 * Once {open} is called, multiple asynchronous {write}s can be 00738 * started using this class. A ACE_Asynch_Write_File::Result 00739 * will be passed back to the {handler} when the asynchronous 00740 * writes completes through the {ACE_Handler::handle_write_file} 00741 * callback. 00742 * This class differs slightly from ACE_Asynch_Write_Stream as 00743 * it allows the user to specify an offset for the write. 00744 */ 00745 class ACE_Export ACE_Asynch_Write_File : public ACE_Asynch_Write_Stream 00746 { 00747 00748 public: 00749 /// A do nothing constructor. 00750 ACE_Asynch_Write_File (void); 00751 00752 /// Destructor. 00753 virtual ~ACE_Asynch_Write_File (void); 00754 00755 /** 00756 * Initializes the factory with information which will be used with 00757 * each asynchronous call. If ({handle} == ACE_INVALID_HANDLE), 00758 * {ACE_Handler::handle} will be called on the {handler} to get the 00759 * correct handle. 00760 */ 00761 int open (ACE_Handler &handler, 00762 ACE_HANDLE handle = ACE_INVALID_HANDLE, 00763 const void *completion_key = 0, 00764 ACE_Proactor *proactor = 0); 00765 00766 /** 00767 * This starts off an asynchronous write. Upto {bytes_to_write} 00768 * will be written from the {message_block}, starting at the 00769 * block's {rd_ptr}. The write will go to the file, starting 00770 * {offset} bytes from the beginning of the file. Priority of the 00771 * operation is specified by {priority}. On POSIX4-Unix, this is 00772 * supported. Works like {nice} in Unix. Negative values are not 00773 * allowed. 0 means priority of the operation same as the process 00774 * priority. 1 means priority of the operation is one less than 00775 * process. And so forth. On Win32, this is a no-op. 00776 * {signal_number} is the POSIX4 real-time signal number to be used 00777 * for the operation. {signal_number} ranges from ACE_SIGRTMIN to 00778 * ACE_SIGRTMAX. This argument is a no-op on non-POSIX4 systems. 00779 */ 00780 int write (ACE_Message_Block &message_block, 00781 size_t bytes_to_write, 00782 unsigned long offset = 0, 00783 unsigned long offset_high = 0, 00784 const void *act = 0, 00785 int priority = 0, 00786 int signal_number = ACE_SIGRTMIN); 00787 00788 #if (defined (ACE_WIN32) && !defined (ACE_HAS_WINCE)) 00789 /** 00790 * Same as above but with gather support, through chaining of composite 00791 * message blocks using the continuation field. 00792 * @note In win32 Each data block payload must be at least the size of a system 00793 * memory page and must be aligned on a system memory page size boundary 00794 */ 00795 int writev (ACE_Message_Block &message_block, 00796 size_t bytes_to_write, 00797 unsigned long offset = 0, 00798 unsigned long offset_high = 0, 00799 const void *act = 0, 00800 int priority = 0, 00801 int signal_number = ACE_SIGRTMIN); 00802 #endif /* (defined (ACE_WIN32) && !defined (ACE_HAS_WINCE)) */ 00803 00804 /// Return the underlying implementation class. 00805 // (this should be protected...) 00806 virtual ACE_Asynch_Operation_Impl *implementation (void) const; 00807 00808 protected: 00809 /// Implementation object. 00810 ACE_Asynch_Write_File_Impl *implementation_; 00811 00812 public: 00813 /** 00814 * @class Result 00815 * 00816 * @brief This is that class which will be passed back to the 00817 * {handler} when the asynchronous write completes. This class 00818 * forwards all the methods to the implementation class. 00819 * 00820 * This class has all the information necessary for the 00821 * {handler} to uniquiely identify the completion of the 00822 * asynchronous write. 00823 * This class differs slightly from 00824 * ACE_Asynch_Write_Stream::Result as it calls back 00825 * {ACE_Handler::handle_write_file} on the {handler} instead 00826 * of {ACE_Handler::handle_write_stream}. No additional state 00827 * is required by this class as ACE_Asynch_Result can store 00828 * the {offset}. 00829 */ 00830 class ACE_Export Result : public ACE_Asynch_Write_Stream::Result 00831 { 00832 00833 /// The concrete implementation result classes only construct this 00834 /// class. 00835 friend class ACE_POSIX_Asynch_Write_File_Result; 00836 friend class ACE_WIN32_Asynch_Write_File_Result; 00837 00838 public: 00839 /// Get the implementation class. 00840 ACE_Asynch_Write_File_Result_Impl *implementation (void) const; 00841 00842 protected: 00843 /// Constructor. This implementation will not be deleted. 00844 Result (ACE_Asynch_Write_File_Result_Impl *implementation); 00845 00846 /// Destructor. 00847 virtual ~Result (void); 00848 00849 /// The implementation class. 00850 ACE_Asynch_Write_File_Result_Impl *implementation_; 00851 00852 private: 00853 /// Here just to provide an dummpy implementation, since the 00854 /// one auto generated by MSVC is flagged as infinitely recursive 00855 void operator= (Result &) {}; 00856 }; 00857 private: 00858 ACE_UNIMPLEMENTED_FUNC (void operator= (const ACE_Asynch_Write_File &)) 00859 ACE_UNIMPLEMENTED_FUNC (ACE_Asynch_Write_File (const ACE_Asynch_Write_File &)) 00860 }; 00861 00862 // Forward declarations 00863 class ACE_Asynch_Accept_Result_Impl; 00864 class ACE_Asynch_Accept_Impl; 00865 00866 /** 00867 * @class ACE_Asynch_Accept 00868 * 00869 * @brief This class is a factory for starting off asynchronous accepts 00870 * on a listen handle. This class forwards all methods to its 00871 * implementation class. 00872 * 00873 * Once {open} is called, multiple asynchronous {accept}s can 00874 * started using this class. A ACE_Asynch_Accept::Result will 00875 * be passed back to the {handler} when the asynchronous accept 00876 * completes through the {ACE_Handler::handle_accept} 00877 * callback. 00878 */ 00879 class ACE_Export ACE_Asynch_Accept : public ACE_Asynch_Operation 00880 { 00881 00882 public: 00883 /// A do nothing constructor. 00884 ACE_Asynch_Accept (void); 00885 00886 /// Destructor. 00887 virtual ~ACE_Asynch_Accept (void); 00888 00889 /** 00890 * Initializes the factory with information which will be used with 00891 * each asynchronous call. If ({handle} == ACE_INVALID_HANDLE), 00892 * {ACE_Handler::handle} will be called on the {handler} to get the 00893 * correct handle. 00894 */ 00895 int open (ACE_Handler &handler, 00896 ACE_HANDLE handle = ACE_INVALID_HANDLE, 00897 const void *completion_key = 0, 00898 ACE_Proactor *proactor = 0); 00899 00900 /** 00901 * This starts off an asynchronous accept. The asynchronous accept 00902 * call also allows any initial data to be returned to the 00903 * handler specified to @c open(). 00904 * @param message_block A message block to receive initial data, as well 00905 * as the local and remote addresses when the 00906 * connection is made. Since the block receives 00907 * the addresses regardless of whether or not 00908 * initial data is available or requested, the 00909 * message block size must be at least 00910 * @a bytes_to_read plus two times the size of 00911 * the addresses used (IPv4 or IPv6). 00912 * @param bytes_to_read The maximum number of bytes of initial data 00913 * to read into @a message_block. 00914 * @param accept_handle The handle that the new connection will be 00915 * accepted on. If @c INVALID_HANDLE, a new 00916 * handle will be created using @a addr_family. 00917 * @param act Value to be passed in result when operation 00918 * completes. 00919 * @param priority Priority of the operation. On POSIX4-Unix, this 00920 * is supported. Works like @c nice in Unix. 00921 * Negative values are not allowed. 0 means 00922 * priority of the operation same as the process 00923 * priority. 1 means priority of the operation is 00924 * one less than process. And so forth. 00925 * On Win32, this argument is ignored. 00926 * @param signal_number The POSIX4 real-time signal number to be used 00927 * for the operation. Value range is from 00928 * @c ACE_SIGRTMIN to @c ACE_SIGRTMAX. 00929 * This argument is ignored on non-POSIX4 systems. 00930 * @param addr_family The address family to use if @a accept_handle 00931 * is @c ACE_INVALID_HANDLE and a new handle must 00932 * be opened. Values are @c AF_INET and @c PF_INET6. 00933 */ 00934 int accept (ACE_Message_Block &message_block, 00935 size_t bytes_to_read, 00936 ACE_HANDLE accept_handle = ACE_INVALID_HANDLE, 00937 const void *act = 0, 00938 int priority = 0, 00939 int signal_number = ACE_SIGRTMIN, 00940 int addr_family = AF_INET); 00941 00942 /// Return the underlying implementation class. 00943 // (this should be protected...) 00944 virtual ACE_Asynch_Operation_Impl *implementation (void) const; 00945 00946 protected: 00947 /// Delegation/implementation class that all methods will be 00948 /// forwarded to. 00949 ACE_Asynch_Accept_Impl *implementation_; 00950 00951 public: 00952 /** 00953 * @class Result 00954 * 00955 * @brief This is that class which will be passed back to the 00956 * {handler} when the asynchronous accept completes. 00957 * 00958 * This class has all the information necessary for the 00959 * {handler} to uniquiely identify the completion of the 00960 * asynchronous accept. 00961 */ 00962 class ACE_Export Result : public ACE_Asynch_Result 00963 { 00964 00965 /// The concrete implementation result classes only construct this 00966 /// class. 00967 friend class ACE_POSIX_Asynch_Accept_Result; 00968 friend class ACE_WIN32_Asynch_Accept_Result; 00969 00970 public: 00971 /// The number of bytes which were requested at the start of the 00972 /// asynchronous accept. 00973 size_t bytes_to_read (void) const; 00974 00975 /// Message block which contains the read data. 00976 ACE_Message_Block &message_block (void) const; 00977 00978 /// I/O handle used for accepting new connections. 00979 ACE_HANDLE listen_handle (void) const; 00980 00981 /// I/O handle for the new connection. 00982 ACE_HANDLE accept_handle (void) const; 00983 00984 /// Get the implementation. 00985 ACE_Asynch_Accept_Result_Impl *implementation (void) const; 00986 00987 protected: 00988 /// Contructor. Implementation will not be deleted. 00989 Result (ACE_Asynch_Accept_Result_Impl *implementation); 00990 00991 /// Destructor. 00992 virtual ~Result (void); 00993 00994 /// Impelmentation class. 00995 ACE_Asynch_Accept_Result_Impl *implementation_; 00996 }; 00997 private: 00998 ACE_UNIMPLEMENTED_FUNC (void operator= (const ACE_Asynch_Accept &)) 00999 ACE_UNIMPLEMENTED_FUNC (ACE_Asynch_Accept (const ACE_Asynch_Accept &)) 01000 }; 01001 // Forward declarations 01002 class ACE_Asynch_Connect_Result_Impl; 01003 class ACE_Asynch_Connect_Impl; 01004 01005 /** 01006 * @class ACE_Asynch_Connect 01007 * 01008 * @brief This class is a factory for starting off asynchronous connects 01009 * This class forwards all methods to its implementation class. 01010 * 01011 * Once @c open is called, multiple asynchronous connect operationss can 01012 * started using this class. A ACE_Asynch_Connect::Result will 01013 * be passed back to the associated ACE_Handler when the asynchronous connect 01014 * completes through the ACE_Handler::handle_connect() callback. 01015 */ 01016 class ACE_Export ACE_Asynch_Connect : public ACE_Asynch_Operation 01017 { 01018 01019 public: 01020 /// A do nothing constructor. 01021 ACE_Asynch_Connect (void); 01022 01023 /// Destructor. 01024 virtual ~ACE_Asynch_Connect (void); 01025 01026 /** 01027 * Initializes the factory with information which will be used with 01028 * each asynchronous call. 01029 * 01030 * @note @arg handle is ignored and should be @c ACE_INVALID_HANDLE. 01031 */ 01032 int open (ACE_Handler &handler, 01033 ACE_HANDLE handle = ACE_INVALID_HANDLE, 01034 const void *completion_key = 0, 01035 ACE_Proactor *proactor = 0); 01036 01037 /** 01038 * This starts off an asynchronous Connect. 01039 */ 01040 int connect (ACE_HANDLE connect_handle, 01041 const ACE_Addr & remote_sap, 01042 const ACE_Addr & local_sap, 01043 int reuse_addr, 01044 const void *act=0, 01045 int priority = 0, 01046 int signal_number = ACE_SIGRTMIN); 01047 01048 /// Return the underlying implementation class. 01049 // (this should be protected...) 01050 virtual ACE_Asynch_Operation_Impl *implementation (void) const; 01051 01052 protected: 01053 /// Delegation/implementation class that all methods will be 01054 /// forwarded to. 01055 ACE_Asynch_Connect_Impl *implementation_; 01056 01057 public: 01058 /** 01059 * @class Result 01060 * 01061 * @brief This is that class which will be passed back to the 01062 * handler when the asynchronous connect completes. 01063 * 01064 * This class has all the information necessary for the 01065 * handler to uniquely identify the completion of the 01066 * asynchronous connect. 01067 */ 01068 class ACE_Export Result : public ACE_Asynch_Result 01069 { 01070 01071 /// The concrete implementation result classes only construct this 01072 /// class. 01073 friend class ACE_POSIX_Asynch_Connect_Result; 01074 friend class ACE_WIN32_Asynch_Connect_Result; 01075 01076 public: 01077 01078 /// I/O handle for the connection. 01079 ACE_HANDLE connect_handle (void) const; 01080 01081 /// Get the implementation. 01082 ACE_Asynch_Connect_Result_Impl *implementation (void) const; 01083 01084 protected: 01085 /// Contructor. Implementation will not be deleted. 01086 Result (ACE_Asynch_Connect_Result_Impl *implementation); 01087 01088 /// Destructor. 01089 virtual ~Result (void); 01090 01091 /// Impelmentation class. 01092 ACE_Asynch_Connect_Result_Impl *implementation_; 01093 }; 01094 private: 01095 ACE_UNIMPLEMENTED_FUNC (void operator= (const ACE_Asynch_Connect &)) 01096 ACE_UNIMPLEMENTED_FUNC (ACE_Asynch_Connect (const ACE_Asynch_Connect &)) 01097 }; 01098 01099 // Forward declarations 01100 class ACE_Asynch_Transmit_File_Result_Impl; 01101 class ACE_Asynch_Transmit_File_Impl; 01102 01103 /** 01104 * @class ACE_Asynch_Transmit_File 01105 * 01106 * @brief This class is a factory for starting off asynchronous 01107 * transmit files on a stream. 01108 * 01109 * Once {open} is called, multiple asynchronous {transmit_file}s 01110 * can started using this class. A 01111 * ACE_Asynch_Transmit_File::Result will be passed back to the 01112 * {handler} when the asynchronous transmit file completes 01113 * through the {ACE_Handler::handle_transmit_file} callback. 01114 * The transmit_file function transmits file data over a 01115 * connected network connection. The function uses the operating 01116 * system's cache manager to retrieve the file data. This 01117 * function provides high-performance file data transfer over 01118 * network connections. This function would be of great use in 01119 * a Web Server, Image Server, etc. 01120 */ 01121 class ACE_Export ACE_Asynch_Transmit_File : public ACE_Asynch_Operation 01122 { 01123 01124 public: 01125 // Forward declarations 01126 class Header_And_Trailer; 01127 01128 /// A do nothing constructor. 01129 ACE_Asynch_Transmit_File (void); 01130 01131 /// Destructor. 01132 virtual ~ACE_Asynch_Transmit_File (void); 01133 01134 /** 01135 * Initializes the factory with information which will be used with 01136 * each asynchronous call. If ({handle} == ACE_INVALID_HANDLE), 01137 * {ACE_Handler::handle} will be called on the {handler} to get the 01138 * correct handle. 01139 */ 01140 int open (ACE_Handler &handler, 01141 ACE_HANDLE handle = ACE_INVALID_HANDLE, 01142 const void *completion_key = 0, 01143 ACE_Proactor *proactor = 0); 01144 01145 /** 01146 * This starts off an asynchronous transmit file. The {file} is a 01147 * handle to an open file. {header_and_trailer} is a pointer to a 01148 * data structure that contains pointers to data to send before and 01149 * after the file data is sent. Set this parameter to 0 if you only 01150 * want to transmit the file data. Upto {bytes_to_write} will be 01151 * written to the {socket}. If you want to send the entire file, 01152 * let {bytes_to_write} = 0. {bytes_per_send} is the size of each 01153 * block of data sent per send operation. Please read the Win32 01154 * documentation on what the flags should be. Priority of the 01155 * operation is specified by {priority}. On POSIX4-Unix, this is 01156 * supported. Works like {nice} in Unix. Negative values are not 01157 * allowed. 0 means priority of the operation same as the process 01158 * priority. 1 means priority of the operation is one less than 01159 * process. And so forth. On Win32, this is a no-op. 01160 * {signal_number} is the POSIX4 real-time signal number to be used 01161 * for the operation. {signal_number} ranges from ACE_SIGRTMIN to 01162 * ACE_SIGRTMAX. This argument is a no-op on non-POSIX4 systems. 01163 */ 01164 int transmit_file (ACE_HANDLE file, 01165 Header_And_Trailer *header_and_trailer = 0, 01166 size_t bytes_to_write = 0, 01167 unsigned long offset = 0, 01168 unsigned long offset_high = 0, 01169 size_t bytes_per_send = 0, 01170 unsigned long flags = 0, 01171 const void *act = 0, 01172 int priority = 0, 01173 int signal_number = ACE_SIGRTMIN); 01174 01175 /// Return the underlying implementation class. 01176 // (this should be protected...) 01177 virtual ACE_Asynch_Operation_Impl *implementation (void) const; 01178 01179 protected: 01180 /// The implementation class. 01181 ACE_Asynch_Transmit_File_Impl *implementation_; 01182 01183 public: 01184 /** 01185 * @class Result 01186 * 01187 * @brief This is that class which will be passed back to the 01188 * {handler} when the asynchronous transmit file completes. 01189 * 01190 * This class has all the information necessary for the 01191 * {handler} to uniquiely identify the completion of the 01192 * asynchronous transmit file. 01193 */ 01194 class ACE_Export Result : public ACE_Asynch_Result 01195 { 01196 01197 /// The concrete implementation result classes only construct this 01198 /// class. 01199 friend class ACE_POSIX_Asynch_Transmit_File_Result; 01200 friend class ACE_WIN32_Asynch_Transmit_File_Result; 01201 01202 public: 01203 /// Socket used for transmitting the file. 01204 ACE_HANDLE socket (void) const; 01205 01206 /// File from which the data is read. 01207 ACE_HANDLE file (void) const; 01208 01209 /// Header and trailer data associated with this transmit file. 01210 Header_And_Trailer *header_and_trailer (void) const; 01211 01212 /// The number of bytes which were requested at the start of the 01213 /// asynchronous transmit file. 01214 size_t bytes_to_write (void) const; 01215 01216 /// Number of bytes per send requested at the start of the transmit 01217 /// file. 01218 size_t bytes_per_send (void) const; 01219 01220 /// Flags which were passed into transmit file. 01221 unsigned long flags (void) const; 01222 01223 /// Get the implementation class. 01224 ACE_Asynch_Transmit_File_Result_Impl *implementation (void) const; 01225 01226 protected: 01227 /// Constructor. 01228 Result (ACE_Asynch_Transmit_File_Result_Impl *implementation); 01229 01230 /// Destructor. 01231 virtual ~Result (void); 01232 01233 /// The implementation class. 01234 ACE_Asynch_Transmit_File_Result_Impl *implementation_; 01235 }; 01236 01237 /** 01238 * @class Header_And_Trailer 01239 * 01240 * @brief The class defines a data structure that contains pointers 01241 * to data to send before and after the file data is sent. 01242 * 01243 * This class provides a wrapper over TRANSMIT_FILE_BUFFERS 01244 * and provided a consistent use of ACE_Message_Blocks. 01245 */ 01246 class ACE_Export Header_And_Trailer 01247 { 01248 01249 public: 01250 /// Constructor. 01251 Header_And_Trailer (ACE_Message_Block *header = 0, 01252 size_t header_bytes = 0, 01253 ACE_Message_Block *trailer = 0, 01254 size_t trailer_bytes = 0); 01255 01256 /// Destructor 01257 virtual ~Header_And_Trailer (void); 01258 01259 /// This method allows all the member to be set in one fell swoop. 01260 void header_and_trailer (ACE_Message_Block *header = 0, 01261 size_t header_bytes = 0, 01262 ACE_Message_Block *trailer = 0, 01263 size_t trailer_bytes = 0); 01264 01265 /// Get header which goes before the file data. 01266 ACE_Message_Block *header (void) const; 01267 01268 /// Set header which goes before the file data. 01269 void header (ACE_Message_Block *message_block); 01270 01271 /// Get size of the header data. 01272 size_t header_bytes (void) const; 01273 01274 /// Set size of the header data. 01275 void header_bytes (size_t bytes); 01276 01277 /// Get trailer which goes after the file data. 01278 ACE_Message_Block *trailer (void) const; 01279 01280 /// Set trailer which goes after the file data. 01281 void trailer (ACE_Message_Block *message_block); 01282 01283 /// Get size of the trailer data. 01284 size_t trailer_bytes (void) const; 01285 01286 /// Set size of the trailer data. 01287 void trailer_bytes (size_t bytes); 01288 01289 /// Conversion routine. 01290 ACE_LPTRANSMIT_FILE_BUFFERS transmit_buffers (void); 01291 01292 protected: 01293 /// Header data. 01294 ACE_Message_Block *header_; 01295 01296 /// Size of header data. 01297 size_t header_bytes_; 01298 01299 /// Trailer data. 01300 ACE_Message_Block *trailer_; 01301 01302 /// Size of trailer data. 01303 size_t trailer_bytes_; 01304 01305 /// Target data structure. 01306 ACE_TRANSMIT_FILE_BUFFERS transmit_buffers_; 01307 }; 01308 private: 01309 ACE_UNIMPLEMENTED_FUNC (void operator= (const ACE_Asynch_Transmit_File &)) 01310 ACE_UNIMPLEMENTED_FUNC (ACE_Asynch_Transmit_File (const ACE_Asynch_Transmit_File &)) 01311 }; 01312 01313 01314 // Forward declarations 01315 class ACE_Asynch_Read_Dgram_Result_Impl; 01316 class ACE_Asynch_Read_Dgram_Impl; 01317 class ACE_Addr; 01318 01319 /** 01320 * @class ACE_Asynch_Read_Dgram 01321 * 01322 * @brief This class is a factory for starting off asynchronous reads 01323 * on a UDP socket. This class forwards all methods to its 01324 * implementation class. 01325 * 01326 * Once {open} is called, multiple asynchronous {read}s can be 01327 * started using this class. An ACE_Asynch_Read_Dgram::Result 01328 * will be passed back to the {handler} when the asynchronous 01329 * reads completes through the {ACE_Handler::handle_read_dgram} 01330 * callback. 01331 */ 01332 class ACE_Export ACE_Asynch_Read_Dgram : public ACE_Asynch_Operation 01333 { 01334 01335 public: 01336 /// A do nothing constructor. 01337 ACE_Asynch_Read_Dgram (void); 01338 01339 /// Destructor 01340 virtual ~ACE_Asynch_Read_Dgram (void); 01341 01342 /** 01343 * Initializes the factory with information which will be used with 01344 * each asynchronous call. If ({handle} == ACE_INVALID_HANDLE), 01345 * {ACE_Handler::handle} will be called on the {handler} to get the 01346 * correct handle. 01347 */ 01348 int open (ACE_Handler &handler, 01349 ACE_HANDLE handle = ACE_INVALID_HANDLE, 01350 const void *completion_key = 0, 01351 ACE_Proactor *proactor = 0); 01352 01353 /** This starts off an asynchronous read. Upto 01354 * {message_block->total_size()} will be read and stored in the 01355 * {message_block}. {message_block}'s {wr_ptr} will be updated to reflect 01356 * the added bytes if the read operation is successfully completed. 01357 * Return code of 1 means immediate success and {number_of_bytes_recvd} 01358 * will contain number of bytes read. The {ACE_Handler::handle_read_dgram} 01359 * method will still be called. Return code of 0 means the IO will 01360 * complete proactively. Return code of -1 means there was an error, use 01361 * errno to get the error code. 01362 * 01363 * Scatter/gather is supported on WIN32 by using the {message_block->cont()} 01364 * method. Up to ACE_IOV_MAX {message_block}'s are supported. Upto 01365 * {message_block->size()} bytes will be read into each {message block} for 01366 * a total of {message_block->total_size()} bytes. All {message_block}'s 01367 * {wr_ptr}'s will be updated to reflect the added bytes for each 01368 * {message_block} 01369 * 01370 * Priority of the operation is specified by {priority}. On POSIX4-Unix, 01371 * this is supported. Works like {nice} in Unix. Negative values are not 01372 * allowed. 0 means priority of the operation same as the process 01373 * priority. 1 means priority of the operation is one less than 01374 * process. And so forth. On Win32, {priority} is a no-op. 01375 * {signal_number} is the POSIX4 real-time signal number to be used 01376 * for the operation. {signal_number} ranges from ACE_SIGRTMIN to 01377 * ACE_SIGRTMAX. This argument is a no-op on non-POSIX4 systems. 01378 */ 01379 ssize_t recv (ACE_Message_Block *message_block, 01380 size_t &number_of_bytes_recvd, 01381 int flags, 01382 int protocol_family = PF_INET, 01383 const void *act = 0, 01384 int priority = 0, 01385 int signal_number = ACE_SIGRTMIN); 01386 01387 /// Return the underlying implementation class. 01388 // (this should be protected...) 01389 virtual ACE_Asynch_Operation_Impl *implementation (void) const; 01390 01391 protected: 01392 /// Implementation class that all methods will be forwarded to. 01393 ACE_Asynch_Read_Dgram_Impl *implementation_; 01394 01395 public: 01396 /** 01397 * @class Result 01398 * 01399 * @brief This is the class which will be passed back to the 01400 * {handler} when the asynchronous read completes. This class 01401 * forwards all the methods to the implementation classes. 01402 * 01403 * This class has all the information necessary for the 01404 * {handler} to uniquiely identify the completion of the 01405 * asynchronous read. 01406 */ 01407 class ACE_Export Result : public ACE_Asynch_Result 01408 { 01409 01410 /// The concrete implementation result classes only construct this 01411 /// class. 01412 friend class ACE_POSIX_Asynch_Read_Dgram_Result; 01413 friend class ACE_WIN32_Asynch_Read_Dgram_Result; 01414 01415 public: 01416 01417 /// The number of bytes which were requested at the start of the 01418 /// asynchronous read. 01419 size_t bytes_to_read (void) const; 01420 01421 /// Message block which contains the read data 01422 ACE_Message_Block *message_block (void) const; 01423 01424 /// The flags used in the read 01425 int flags (void) const; 01426 01427 /// The address of where the packet came from 01428 int remote_address (ACE_Addr& addr) const; 01429 01430 /// I/O handle used for reading. 01431 ACE_HANDLE handle (void) const; 01432 01433 /// Get the implementation class. 01434 ACE_Asynch_Read_Dgram_Result_Impl *implementation (void) const; 01435 01436 protected: 01437 /// Constructor. 01438 Result (ACE_Asynch_Read_Dgram_Result_Impl *implementation); 01439 01440 /// Destructor. 01441 virtual ~Result (void); 01442 01443 /// The implementation class. 01444 ACE_Asynch_Read_Dgram_Result_Impl *implementation_; 01445 }; 01446 private: 01447 ACE_UNIMPLEMENTED_FUNC (void operator= (const ACE_Asynch_Read_Dgram &)) 01448 ACE_UNIMPLEMENTED_FUNC (ACE_Asynch_Read_Dgram (const ACE_Asynch_Read_Dgram &)) 01449 }; 01450 01451 // Forward declarations 01452 class ACE_Asynch_Write_Dgram_Impl; 01453 class ACE_Asynch_Write_Dgram_Result_Impl; 01454 01455 /** 01456 * @class ACE_Asynch_Write_Dgram 01457 * 01458 * @brief This class is a factory for starting off asynchronous writes 01459 * on a UDP socket. This class forwards all methods to its 01460 * implementation class. 01461 * 01462 * Once {open} is called, multiple asynchronous {writes}s can 01463 * started using this class. An ACE_Asynch_Write_Dgram::Result 01464 * will be passed back to the {handler} when the asynchronous 01465 * write completes through the 01466 * {ACE_Handler::handle_write_dgram} callback. 01467 */ 01468 class ACE_Export ACE_Asynch_Write_Dgram : public ACE_Asynch_Operation 01469 { 01470 01471 public: 01472 /// A do nothing constructor. 01473 ACE_Asynch_Write_Dgram (void); 01474 01475 /// Destructor. 01476 virtual ~ACE_Asynch_Write_Dgram (void); 01477 01478 /** 01479 * Initializes the factory with information which will be used with 01480 * each asynchronous call. If ({handle} == ACE_INVALID_HANDLE), 01481 * {ACE_Handler::handle} will be called on the {handler} to get the 01482 * correct handle. 01483 */ 01484 int open (ACE_Handler &handler, 01485 ACE_HANDLE handle = ACE_INVALID_HANDLE, 01486 const void *completion_key = 0, 01487 ACE_Proactor *proactor = 0); 01488 01489 /** This starts off an asynchronous send. Upto 01490 * {message_block->total_length()} will be sent. {message_block}'s 01491 * {rd_ptr} will be updated to reflect the sent bytes if the send operation 01492 * is successfully completed. 01493 * Return code of 1 means immediate success and {number_of_bytes_sent} 01494 * is updated to number of bytes sent. The {ACE_Handler::handle_write_dgram} 01495 * method will still be called. Return code of 0 means the IO will 01496 * complete proactively. Return code of -1 means there was an error, use 01497 * errno to get the error code. 01498 * 01499 * Scatter/gather is supported on WIN32 by using the {message_block->cont()} 01500 * method. Up to ACE_IOV_MAX {message_block}'s are supported. Upto 01501 * {message_block->length()} bytes will be sent from each {message block} 01502 * for a total of {message_block->total_length()} bytes. All 01503 * {message_block}'s {rd_ptr}'s will be updated to reflect the bytes sent 01504 * from each {message_block}. 01505 * 01506 * Priority of the operation is specified by {priority}. On POSIX4-Unix, 01507 * this is supported. Works like {nice} in Unix. Negative values are not 01508 * allowed. 0 means priority of the operation same as the process 01509 * priority. 1 means priority of the operation is one less than 01510 * process. And so forth. On Win32, this argument is a no-op. 01511 * {signal_number} is the POSIX4 real-time signal number to be used 01512 * for the operation. {signal_number} ranges from ACE_SIGRTMIN to 01513 * ACE_SIGRTMAX. This argument is a no-op on non-POSIX4 systems. 01514 */ 01515 ssize_t send (ACE_Message_Block *message_block, 01516 size_t &number_of_bytes_sent, 01517 int flags, 01518 const ACE_Addr& remote_addr, 01519 const void *act = 0, 01520 int priority = 0, 01521 int signal_number = ACE_SIGRTMIN); 01522 01523 /// Return the underlying implementation class. 01524 // (this should be protected...) 01525 virtual ACE_Asynch_Operation_Impl *implementation (void) const; 01526 01527 protected: 01528 /// Implementation class that all methods will be forwarded to. 01529 ACE_Asynch_Write_Dgram_Impl *implementation_; 01530 01531 public: 01532 /** 01533 * @class Result 01534 * 01535 * @brief This is that class which will be passed back to the 01536 * {handler} when the asynchronous write completes. This class 01537 * forwards all the methods to the implementation class. 01538 * 01539 * This class has all the information necessary for the 01540 * {handler} to uniquiely identify the completion of the 01541 * asynchronous write. 01542 */ 01543 class ACE_Export Result : public ACE_Asynch_Result 01544 { 01545 01546 /// The concrete implementation result classes only construct this 01547 /// class. 01548 friend class ACE_POSIX_Asynch_Write_Dgram_Result; 01549 friend class ACE_WIN32_Asynch_Write_Dgram_Result; 01550 01551 public: 01552 01553 /// The number of bytes which were requested at the start of the 01554 /// asynchronous write. 01555 size_t bytes_to_write (void) const; 01556 01557 /// Message block which contains the sent data 01558 ACE_Message_Block *message_block (void) const; 01559 01560 /// The flags using in the write 01561 int flags (void) const; 01562 01563 /// I/O handle used for writing. 01564 ACE_HANDLE handle (void) const; 01565 01566 /// Get the implementation class. 01567 ACE_Asynch_Write_Dgram_Result_Impl *implementation (void) const; 01568 01569 protected: 01570 /// Constructor. 01571 Result (ACE_Asynch_Write_Dgram_Result_Impl *implementation); 01572 01573 /// Destructor. 01574 virtual ~Result (void); 01575 01576 /// Implementation class. 01577 ACE_Asynch_Write_Dgram_Result_Impl *implementation_; 01578 }; 01579 private: 01580 ACE_UNIMPLEMENTED_FUNC (void operator= (const ACE_Asynch_Write_Dgram &)) 01581 ACE_UNIMPLEMENTED_FUNC (ACE_Asynch_Write_Dgram (const ACE_Asynch_Write_Dgram &)) 01582 }; 01583 01584 01585 /** 01586 * @class ACE_Handler 01587 * 01588 * @brief This base class defines the interface for receiving the 01589 * results of asynchronous operations. 01590 * 01591 * Subclasses of this class will fill in appropriate methods. 01592 */ 01593 class ACE_Export ACE_Handler 01594 { 01595 public: 01596 /// A do nothing constructor. 01597 ACE_Handler (void); 01598 01599 /// A do nothing constructor which allows proactor to be set to <p>. 01600 ACE_Handler (ACE_Proactor *p); 01601 01602 /// Virtual destruction. 01603 virtual ~ACE_Handler (void); 01604 01605 /// This method will be called when an asynchronous read completes on 01606 /// a stream. 01607 virtual void handle_read_stream (const ACE_Asynch_Read_Stream::Result &result); 01608 01609 /// This method will be called when an asynchronous write completes 01610 /// on a UDP socket. 01611 virtual void handle_write_dgram (const ACE_Asynch_Write_Dgram::Result &result); 01612 01613 /// This method will be called when an asynchronous read completes on 01614 /// a UDP socket. 01615 virtual void handle_read_dgram (const ACE_Asynch_Read_Dgram::Result &result); 01616 01617 /// This method will be called when an asynchronous write completes 01618 /// on a stream. 01619 virtual void handle_write_stream (const ACE_Asynch_Write_Stream::Result &result); 01620 01621 /// This method will be called when an asynchronous read completes on 01622 /// a file. 01623 virtual void handle_read_file (const ACE_Asynch_Read_File::Result &result); 01624 01625 /// This method will be called when an asynchronous write completes 01626 /// on a file. 01627 virtual void handle_write_file (const ACE_Asynch_Write_File::Result &result); 01628 01629 /// This method will be called when an asynchronous accept completes. 01630 virtual void handle_accept (const ACE_Asynch_Accept::Result &result); 01631 01632 /// This method will be called when an asynchronous connect completes. 01633 virtual void handle_connect (const ACE_Asynch_Connect::Result &result); 01634 01635 /// This method will be called when an asynchronous transmit file 01636 /// completes. 01637 virtual void handle_transmit_file (const ACE_Asynch_Transmit_File::Result &result); 01638 01639 /// Called when timer expires. {tv} was the requested time value and 01640 /// {act} is the ACT passed when scheduling the timer. 01641 virtual void handle_time_out (const ACE_Time_Value &tv, 01642 const void *act = 0); 01643 01644 /** 01645 * This is method works with the {run_event_loop} of the 01646 * ACE_Proactor. A special {Wake_Up_Completion} is used to wake up 01647 * all the threads that are blocking for completions. 01648 */ 01649 virtual void handle_wakeup (void); 01650 01651 /// Get the proactor associated with this handler. 01652 ACE_Proactor *proactor (void); 01653 01654 /// Set the proactor. 01655 void proactor (ACE_Proactor *p); 01656 01657 /** 01658 * Get the I/O handle used by this {handler}. This method will be 01659 * called by the ACE_Asynch_* classes when an ACE_INVALID_HANDLE is 01660 * passed to {open}. 01661 */ 01662 virtual ACE_HANDLE handle (void) const; 01663 01664 /// Set the ACE_HANDLE value for this Handler. 01665 virtual void handle (ACE_HANDLE); 01666 01667 /** 01668 * @class Proxy 01669 * 01670 * @brief The Proxy class acts as a proxy for dispatch of completions 01671 * to operations issued for the associated handler. It allows the handler 01672 * to be deleted while operations are outstanding. The proxy must be used 01673 * to get the ACE_Handler pointer for dispatching, and if it's 0, the 01674 * handler is no longer valid and the result should not be dispatched. 01675 */ 01676 class ACE_Export Proxy 01677 { 01678 public: 01679 Proxy (ACE_Handler *handler) : handler_ (handler) {}; 01680 void reset (void) { this->handler_ = 0; }; 01681 ACE_Handler *handler (void) { return this->handler_; }; 01682 private: 01683 ACE_Handler *handler_; 01684 }; 01685 typedef ACE_Refcounted_Auto_Ptr<Proxy, ACE_SYNCH_MUTEX> 01686 Proxy_Ptr; 01687 01688 Proxy_Ptr &proxy (void); 01689 01690 protected: 01691 /// The proactor associated with this handler. 01692 ACE_Proactor *proactor_; 01693 01694 /// The ACE_HANDLE in use with this handler. 01695 ACE_HANDLE handle_; 01696 01697 /// Refers to proxy for this handler. 01698 ACE_Refcounted_Auto_Ptr<Proxy, ACE_SYNCH_MUTEX> proxy_; 01699 01700 ACE_UNIMPLEMENTED_FUNC (ACE_Handler (const ACE_Handler &)) 01701 ACE_UNIMPLEMENTED_FUNC (ACE_Handler operator= (const ACE_Handler &)) 01702 }; 01703 01704 // Forward declarations 01705 class ACE_INET_Addr; 01706 01707 // Forward declarations 01708 template <class HANDLER> 01709 class ACE_Asynch_Acceptor; 01710 01711 /** 01712 * @class ACE_Service_Handler 01713 * 01714 * @brief This base class defines the interface for the 01715 * ACE_Asynch_Acceptor to call into when new connection are 01716 * accepted. 01717 * 01718 * Subclasses of this class will fill in appropriate methods to 01719 * define application specific behavior. 01720 */ 01721 class ACE_Export ACE_Service_Handler : public ACE_Handler 01722 { 01723 01724 /// The Acceptor is the factory and therefore should have special 01725 /// privileges. 01726 friend class ACE_Asynch_Acceptor<ACE_Service_Handler>; 01727 01728 public: 01729 /// A do nothing constructor. 01730 ACE_Service_Handler (void); 01731 01732 /// Virtual destruction. 01733 virtual ~ACE_Service_Handler (void); 01734 01735 /** 01736 * {open} is called by ACE_Asynch_Acceptor to initialize a new 01737 * instance of ACE_Service_Handler that has been created after the 01738 * new connection is accepted. The handle for the new connection is 01739 * passed along with the initial data that may have shown up. 01740 */ 01741 virtual void open (ACE_HANDLE new_handle, 01742 ACE_Message_Block &message_block); 01743 01744 // protected: 01745 // This should be corrected after the correct semantics of the 01746 // friend has been figured out. 01747 01748 /// Called by ACE_Asynch_Acceptor to pass the addresses of the new 01749 /// connections. 01750 virtual void addresses (const ACE_INET_Addr &remote_address, 01751 const ACE_INET_Addr &local_address); 01752 01753 /// Called by ACE_Asynch_Acceptor to pass the act. 01754 virtual void act (const void *); 01755 }; 01756 01757 ACE_END_VERSIONED_NAMESPACE_DECL 01758 01759 #endif /* ACE_WIN32 || ACE_HAS_AIO_CALLS*/ 01760 #include /**/ "ace/post.h" 01761 #endif /* ACE_ASYNCH_IO_H */