00001 // -*- C++ -*- 00002 00003 //============================================================================= 00004 /** 00005 * @file SOCK_Stream.h 00006 * 00007 * SOCK_Stream.h,v 4.34 2006/04/14 16:15:58 shuston Exp 00008 * 00009 * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> 00010 */ 00011 //============================================================================= 00012 00013 #ifndef ACE_SOCK_STREAM_H 00014 #define ACE_SOCK_STREAM_H 00015 #include /**/ "ace/pre.h" 00016 00017 #include "ace/SOCK_IO.h" 00018 00019 #if !defined (ACE_LACKS_PRAGMA_ONCE) 00020 # pragma once 00021 #endif /* ACE_LACKS_PRAGMA_ONCE */ 00022 00023 #include "ace/INET_Addr.h" 00024 00025 ACE_BEGIN_VERSIONED_NAMESPACE_DECL 00026 00027 // Forward declarations. 00028 class ACE_Message_Block; 00029 00030 /** 00031 * @class ACE_SOCK_Stream 00032 * 00033 * @brief Defines the methods in the ACE_SOCK_Stream abstraction. 00034 * 00035 * This adds additional wrapper methods atop the ACE_SOCK_IO 00036 * class. 00037 * 00038 * <buf> is the buffer to write from or receive into. 00039 * <len> is the number of bytes to transfer. 00040 * The <timeout> parameter in the following methods indicates how 00041 * long to blocking trying to transfer data. If <timeout> == 0, 00042 * then the call behaves as a normal send/recv call, i.e., for 00043 * blocking sockets, the call will block until action is possible; 00044 * for non-blocking sockets, EWOULDBLOCK will be returned if no 00045 * action is immediately possible. 00046 * If <timeout> != 0, the call will wait for data to arrive no longer 00047 * than the relative time specified in *<timeout>. 00048 * The "_n()" I/O methods keep looping until all the data has been 00049 * transferred. These methods also work for sockets in non-blocking 00050 * mode i.e., they keep looping on EWOULDBLOCK. <timeout> is used 00051 * to make sure we keep making progress, i.e., the same timeout 00052 * value is used for every I/O operation in the loop and the timeout 00053 * is not counted down. 00054 * The return values for the "*_n()" methods match the return values 00055 * from the non "_n()" methods and are specified as follows: 00056 * - On complete transfer, the number of bytes transferred is returned. 00057 * - On timeout, -1 is returned, errno == ETIME. 00058 * - On error, -1 is returned, errno is set to appropriate error. 00059 * - On EOF, 0 is returned, errno is irrelevant. 00060 * 00061 * On partial transfers, i.e., if any data is transferred before 00062 * timeout/error/EOF, <bytes_transferred> will contain the number of 00063 * bytes transferred. 00064 * Methods with <iovec> parameter are I/O vector variants of the I/O 00065 * operations. 00066 * Methods with the extra <flags> argument will always result in 00067 * <send> getting called. Methods without the extra <flags> argument 00068 * will result in <send> getting called on Win32 platforms, and 00069 * <write> getting called on non-Win32 platforms. 00070 */ 00071 class ACE_Export ACE_SOCK_Stream : public ACE_SOCK_IO 00072 { 00073 public: 00074 // Initialization and termination methods. 00075 /// Constructor. 00076 ACE_SOCK_Stream (void); 00077 00078 /// Constructor (sets the underlying ACE_HANDLE with @a h). 00079 ACE_SOCK_Stream (ACE_HANDLE h); 00080 00081 /// Destructor. 00082 ~ACE_SOCK_Stream (void); 00083 00084 /** @name Counted send/receive methods 00085 * 00086 * The counted send/receive methods attempt to send a specified number of 00087 * bytes even if they must block and retry the operation in order to 00088 * transfer the entire amount. The time spent blocking for the entire 00089 * transfer can be limited by a specified ACE_Time_Value object which is 00090 * a relative time (i.e., a fixed amount of time, not an absolute time 00091 * of day). These methods return the count of transferred bytes, or -1 00092 * if an error occurs or the operation times out. In error or timeout 00093 * situations it's possible that some data was transferred before the error 00094 * or timeout. The @c bytes_transferred parameter is used to obtain the 00095 * count of bytes transferred before the error or timeout occurred. If the 00096 * total specified number of bytes is transferred without error, the 00097 * method return value should equal the value of @c bytes_transferred. 00098 */ 00099 //@{ 00100 /// Try to recv exactly @a len bytes into @a buf from the connected socket. 00101 ssize_t recv_n (void *buf, 00102 size_t len, 00103 int flags, 00104 const ACE_Time_Value *timeout = 0, 00105 size_t *bytes_transferred = 0) const; 00106 00107 /// Try to recv exactly @a len bytes into @a buf from the connected socket. 00108 ssize_t recv_n (void *buf, 00109 size_t len, 00110 const ACE_Time_Value *timeout = 0, 00111 size_t *bytes_transferred = 0) const; 00112 00113 /// Receive an @c iovec of size @a iovcnt from the connected socket. 00114 ssize_t recvv_n (iovec iov[], 00115 int iovcnt, 00116 const ACE_Time_Value *timeout = 0, 00117 size_t *bytes_transferred = 0) const; 00118 00119 /// Try to send exactly @a len bytes from @a buf>to the connection socket. 00120 ssize_t send_n (const void *buf, 00121 size_t len, 00122 int flags, 00123 const ACE_Time_Value *timeout = 0, 00124 size_t *bytes_transferred = 0) const; 00125 00126 /// Try to send exactly @a len bytes from @a buf to the connected socket. 00127 ssize_t send_n (const void *buf, 00128 size_t len, 00129 const ACE_Time_Value *timeout = 0, 00130 size_t *bytes_transferred = 0) const; 00131 00132 /// Send all the @c message_block's chained through their @c next and 00133 /// @c cont pointers. This call uses the underlying OS gather-write 00134 /// operation to reduce the domain-crossing penalty. 00135 ssize_t send_n (const ACE_Message_Block *message_block, 00136 const ACE_Time_Value *timeout = 0, 00137 size_t *bytes_transferred = 0) const; 00138 00139 /// Send an @c iovec of size @a iovcnt to the connected socket. 00140 ssize_t sendv_n (const iovec iov[], 00141 int iovcnt, 00142 const ACE_Time_Value *timeout = 0, 00143 size_t *bytes_transferred = 0) const; 00144 00145 //@} 00146 00147 // = Send/receive ``urgent'' data (see TCP specs...). 00148 ssize_t send_urg (const void *ptr, 00149 size_t len = sizeof (char), 00150 const ACE_Time_Value *timeout = 0) const; 00151 00152 ssize_t recv_urg (void *ptr, 00153 size_t len = sizeof (char), 00154 const ACE_Time_Value *timeout = 0) const; 00155 00156 // = Selectively close endpoints. 00157 /// Close down the reader. 00158 int close_reader (void); 00159 00160 /// Close down the writer. 00161 int close_writer (void); 00162 00163 /** 00164 * Close down the socket (we need this to make things work correctly 00165 * on Win32, which requires use to do a close_writer() before doing 00166 * the close to avoid losing data). 00167 */ 00168 int close (void); 00169 00170 // = Meta-type info 00171 typedef ACE_INET_Addr PEER_ADDR; 00172 00173 /// Dump the state of an object. 00174 void dump (void) const; 00175 00176 /// Declare the dynamic allocation hooks. 00177 ACE_ALLOC_HOOK_DECLARE; 00178 }; 00179 00180 ACE_END_VERSIONED_NAMESPACE_DECL 00181 00182 #if defined (__ACE_INLINE__) 00183 #include "ace/SOCK_Stream.inl" 00184 #endif /* __ACE_INLINE__ */ 00185 00186 #include /**/ "ace/post.h" 00187 #endif /* ACE_SOCK_STREAM_H */