ACE/ace/SOCK_Stream.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    SOCK_Stream.h
   6  *
   7  *  @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
   8  */
   9 //=============================================================================
  10
  11 #ifndef ACE_SOCK_STREAM_H
  12 #define ACE_SOCK_STREAM_H
  13 #include /**/ "ace/pre.h"
  14
  15 #include "ace/SOCK_IO.h"
  16
  17 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  18 # pragma once
  19 #endif /* ACE_LACKS_PRAGMA_ONCE */
  20
  21 #include "ace/INET_Addr.h"
  22
  23 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  24
  25 // Forward declarations.
  26 class ACE_Message_Block;
  27
  28 /**
  29  * @class ACE_SOCK_Stream
  30  *
  31  * @brief Defines the methods in the ACE_SOCK_Stream abstraction.
  32  *
  33  * This adds additional wrapper methods atop the ACE_SOCK_IO
  34  * class.
  35  *
  36  * @sa ACE_SOCK_IO
  37  */
  38 class ACE_Export ACE_SOCK_Stream : public ACE_SOCK_IO
  39 {
  40 public:
  41   // Initialization and termination methods.
  42   /// Constructor.
  43   ACE_SOCK_Stream ();
  44
  45   /// Constructor (sets the underlying ACE_HANDLE with @a h).
  46   ACE_SOCK_Stream (ACE_HANDLE h);
  47
  48   /// Destructor.
  49   ~ACE_SOCK_Stream ();
  50
  51   /** @name Counted send/receive methods
  52    *
  53    * The counted send/receive methods attempt to transfer a specified number
  54    * of bytes even if they must block and retry the operation in order to
  55    * transfer the entire amount. The time spent blocking for the entire
  56    * transfer can be limited by a specified ACE_Time_Value object which is
  57    * a relative time (i.e., a fixed amount of time, not an absolute time
  58    * of day). These methods return the count of transferred bytes, or -1
  59    * if an error occurs or the operation times out before the entire requested
  60    * amount of data has been transferred. In error or timeout situations it's
  61    * possible that some data was transferred before the error
  62    * or timeout. The @c bytes_transferred parameter is used to obtain the
  63    * count of bytes transferred before the error or timeout occurred. If the
  64    * total specified number of bytes is transferred without error, the
  65    * method return value should equal the value of @c bytes_transferred.
  66    *
  67    * @param buf      The buffer to write from or receive into.
  68    * @param iov      An I/O vector containing a specified number of
  69    *                 count/pointer pairs directing the data to be transferred.
  70    * @param iovcnt   The number of I/O vectors to be used from @a iov.
  71    * @param len      The number of bytes to transfer.
  72    * @param flags    Flags that will be passed through to the @c recv()
  73    *                 system call.
  74    * @param timeout  Indicates how long to blocking trying to transfer data.
  75    *                 If no timeout is supplied (timeout == 0) the method will
  76    *                 wait indefinitely or until an error occurs for the
  77    *                 specified number of bytes to be transferred.
  78    *                 To avoid any waiting, specify a timeout value with
  79    *                 0 seconds. Note that the timeout period restarts on
  80    *                 each retried operation issued; therefore, an operation
  81    *                 that requires multiples retries may take longer than the
  82    *                 specified timeout to complete.
  83    * @param bytes_transferred If non-0, points to a location which receives
  84    *                 the total number of bytes transferred before the method
  85    *                 returns, even if it's less than the number requested.
  86    *
  87    * @retval      len, the complete number of bytes transferred.
  88    * @retval      0  EOF, i.e., the peer closed the connection.
  89    * @retval      -1 an error occurred before the entire amount was
  90    *                 transferred. Check @c errno for more information.
  91    *                 If the @a timeout period is reached, errno is ETIME.
  92    *
  93    * On partial transfers, i.e., if any data is transferred before
  94    * timeout/error/EOF, *@a bytes_transferred will contain the number of
  95    * bytes transferred.
  96    */
  97   //@{
  98   /// Try to recv exactly @a len bytes into @a buf from the connected socket.
  99   ssize_t recv_n (void *buf,
 100                   size_t len,
 101                   int flags,
 102                   const ACE_Time_Value *timeout = 0,
 103                   size_t *bytes_transferred = 0) const;
 104
 105   /// Try to recv exactly @a len bytes into @a buf from the connected socket.
 106   ssize_t recv_n (void *buf,
 107                   size_t len,
 108                   const ACE_Time_Value *timeout = 0,
 109                   size_t *bytes_transferred = 0) const;
 110
 111   /// Receive an @c iovec of size @a iovcnt from the connected socket.
 112   ssize_t recvv_n (iovec iov[],
 113                    int iovcnt,
 114                    const ACE_Time_Value *timeout = 0,
 115                    size_t *bytes_transferred = 0) const;
 116
 117   /// Try to send exactly @a len bytes from @a buf to the connection socket.
 118   ssize_t send_n (const void *buf,
 119                   size_t len,
 120                   int flags,
 121                   const ACE_Time_Value *timeout = 0,
 122                   size_t *bytes_transferred = 0) const;
 123
 124   /// Try to send exactly @a len bytes from @a buf to the connected socket.
 125   ssize_t send_n (const void *buf,
 126                   size_t len,
 127                   const ACE_Time_Value *timeout = 0,
 128                   size_t *bytes_transferred = 0) const;
 129
 130   /// Send all the message blocks chained through their @c next and
 131   /// @c cont pointers.  This call uses the underlying OS gather-write
 132   /// operation to reduce the domain-crossing penalty.
 133   ssize_t send_n (const ACE_Message_Block *message_block,
 134                   const ACE_Time_Value *timeout = 0,
 135                   size_t *bytes_transferred = 0) const;
 136
 137   /// Send an @c iovec of size @a iovcnt to the connected socket.
 138   ssize_t sendv_n (const iovec iov[],
 139                    int iovcnt,
 140                    const ACE_Time_Value *timeout = 0,
 141                    size_t *bytes_transferred = 0) const;
 142
 143   //@}
 144
 145   // = Send/receive ``urgent'' data (see TCP specs...).
 146   ssize_t send_urg (const void *ptr,
 147                     size_t len = sizeof (char),
 148                     const ACE_Time_Value *timeout = 0) const;
 149
 150   ssize_t recv_urg (void *ptr,
 151                     size_t len = sizeof (char),
 152                     const ACE_Time_Value *timeout = 0) const;
 153
 154   // = Selectively close endpoints.
 155   /// Close down the reader.
 156   int close_reader ();
 157
 158   /// Close down the writer.
 159   int close_writer ();
 160
 161   /**
 162    * Close down the socket (we need this to make things work correctly
 163    * on Win32, which requires use to do a close_writer() before doing
 164    * the close to avoid losing data).
 165    */
 166   int close ();
 167
 168   // = Meta-type info
 169   typedef ACE_INET_Addr PEER_ADDR;
 170
 171   /// Dump the state of an object.
 172   void dump () const;
 173
 174   /// Declare the dynamic allocation hooks.
 175   ACE_ALLOC_HOOK_DECLARE;
 176 };
 177
 178 ACE_END_VERSIONED_NAMESPACE_DECL
 179
 180 #if defined (__ACE_INLINE__)
 181 #include "ace/SOCK_Stream.inl"
 182 #endif /* __ACE_INLINE__ */
 183
 184 #include /**/ "ace/post.h"
 185 #endif /* ACE_SOCK_STREAM_H */