00001 // -*- C++ -*- 00002 00003 //============================================================================= 00004 /** 00005 * @file SOCK_Stream.h 00006 * 00007 * $Id: SOCK_Stream.h 76478 2007-01-15 21:55:37Z shuston $ 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 * @sa ACE_SOCK_IO 00039 */ 00040 class ACE_Export ACE_SOCK_Stream : public ACE_SOCK_IO 00041 { 00042 public: 00043 // Initialization and termination methods. 00044 /// Constructor. 00045 ACE_SOCK_Stream (void); 00046 00047 /// Constructor (sets the underlying ACE_HANDLE with @a h). 00048 ACE_SOCK_Stream (ACE_HANDLE h); 00049 00050 /// Destructor. 00051 ~ACE_SOCK_Stream (void); 00052 00053 /** @name Counted send/receive methods 00054 * 00055 * The counted send/receive methods attempt to transfer a specified number 00056 * of bytes even if they must block and retry the operation in order to 00057 * transfer the entire amount. The time spent blocking for the entire 00058 * transfer can be limited by a specified ACE_Time_Value object which is 00059 * a relative time (i.e., a fixed amount of time, not an absolute time 00060 * of day). These methods return the count of transferred bytes, or -1 00061 * if an error occurs or the operation times out before the entire requested 00062 * amount of data has been transferred. In error or timeout situations it's 00063 * possible that some data was transferred before the error 00064 * or timeout. The @c bytes_transferred parameter is used to obtain the 00065 * count of bytes transferred before the error or timeout occurred. If the 00066 * total specified number of bytes is transferred without error, the 00067 * method return value should equal the value of @c bytes_transferred. 00068 * 00069 * @param buf The buffer to write from or receive into. 00070 * @param iov An I/O vector containing a specified number of 00071 * count/pointer pairs directing the data to be transferred. 00072 * @param iovcnt The number of I/O vectors to be used from @a iov. 00073 * @param len The number of bytes to transfer. 00074 * @param flags Flags that will be passed through to the @c recv() 00075 * system call. 00076 * @param timeout Indicates how long to blocking trying to transfer data. 00077 * If no timeout is supplied (timeout == 0) the method will 00078 * wait indefinitely or until an error occurs for the 00079 * specified number of bytes to be transferred. 00080 * To avoid any waiting, specify a timeout value with 00081 * 0 seconds. 00082 * @param bytes_transferred If non-0, points to a location which receives 00083 * the total number of bytes transferred before the method 00084 * returns, even if it's less than the number requested. 00085 * 00086 * @retval len, the complete number of bytes transferred. 00087 * @retval 0 EOF, i.e., the peer closed the connection. 00088 * @retval -1 an error occurred before the entire amount was 00089 * transferred. Check @c errno for more information. 00090 * If the @a timeout period is reached, errno is ETIME. 00091 * 00092 * On partial transfers, i.e., if any data is transferred before 00093 * timeout/error/EOF, *@a bytes_transferred will contain the number of 00094 * bytes transferred. 00095 */ 00096 //@{ 00097 /// Try to recv exactly @a len bytes into @a buf from the connected socket. 00098 ssize_t recv_n (void *buf, 00099 size_t len, 00100 int flags, 00101 const ACE_Time_Value *timeout = 0, 00102 size_t *bytes_transferred = 0) const; 00103 00104 /// Try to recv exactly @a len bytes into @a buf from the connected socket. 00105 ssize_t recv_n (void *buf, 00106 size_t len, 00107 const ACE_Time_Value *timeout = 0, 00108 size_t *bytes_transferred = 0) const; 00109 00110 /// Receive an @c iovec of size @a iovcnt from the connected socket. 00111 ssize_t recvv_n (iovec iov[], 00112 int iovcnt, 00113 const ACE_Time_Value *timeout = 0, 00114 size_t *bytes_transferred = 0) const; 00115 00116 /// Try to send exactly @a len bytes from @a buf to the connection socket. 00117 ssize_t send_n (const void *buf, 00118 size_t len, 00119 int flags, 00120 const ACE_Time_Value *timeout = 0, 00121 size_t *bytes_transferred = 0) const; 00122 00123 /// Try to send exactly @a len bytes from @a buf to the connected socket. 00124 ssize_t send_n (const void *buf, 00125 size_t len, 00126 const ACE_Time_Value *timeout = 0, 00127 size_t *bytes_transferred = 0) const; 00128 00129 /// Send all the message blocks chained through their @c next and 00130 /// @c cont pointers. This call uses the underlying OS gather-write 00131 /// operation to reduce the domain-crossing penalty. 00132 ssize_t send_n (const ACE_Message_Block *message_block, 00133 const ACE_Time_Value *timeout = 0, 00134 size_t *bytes_transferred = 0) const; 00135 00136 /// Send an @c iovec of size @a iovcnt to the connected socket. 00137 ssize_t sendv_n (const iovec iov[], 00138 int iovcnt, 00139 const ACE_Time_Value *timeout = 0, 00140 size_t *bytes_transferred = 0) const; 00141 00142 //@} 00143 00144 // = Send/receive ``urgent'' data (see TCP specs...). 00145 ssize_t send_urg (const void *ptr, 00146 size_t len = sizeof (char), 00147 const ACE_Time_Value *timeout = 0) const; 00148 00149 ssize_t recv_urg (void *ptr, 00150 size_t len = sizeof (char), 00151 const ACE_Time_Value *timeout = 0) const; 00152 00153 // = Selectively close endpoints. 00154 /// Close down the reader. 00155 int close_reader (void); 00156 00157 /// Close down the writer. 00158 int close_writer (void); 00159 00160 /** 00161 * Close down the socket (we need this to make things work correctly 00162 * on Win32, which requires use to do a close_writer() before doing 00163 * the close to avoid losing data). 00164 */ 00165 int close (void); 00166 00167 // = Meta-type info 00168 typedef ACE_INET_Addr PEER_ADDR; 00169 00170 /// Dump the state of an object. 00171 void dump (void) const; 00172 00173 /// Declare the dynamic allocation hooks. 00174 ACE_ALLOC_HOOK_DECLARE; 00175 }; 00176 00177 ACE_END_VERSIONED_NAMESPACE_DECL 00178 00179 #if defined (__ACE_INLINE__) 00180 #include "ace/SOCK_Stream.inl" 00181 #endif /* __ACE_INLINE__ */ 00182 00183 #include /**/ "ace/post.h" 00184 #endif /* ACE_SOCK_STREAM_H */