ACE/ace/DEV_IO.h

   1 /* -*- C++ -*- */
   2
   3 //=============================================================================
   4 /**
   5  *  @file    DEV_IO.h
   6  *
   7  *  @author Gerhard Lenzer
   8  *  @author Douglas C. Schmidt
   9  */
  10 //=============================================================================
  11
  12 #ifndef ACE_DEV_IO_H
  13 #define ACE_DEV_IO_H
  14 #include /**/ "ace/pre.h"
  15
  16 #include "ace/DEV.h"
  17
  18 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  19 # pragma once
  20 #endif /* ACE_LACKS_PRAGMA_ONCE */
  21
  22 #if defined (ACE_HAS_STREAM_PIPES)
  23 #  include "ace/OS_NS_stropts.h"
  24 #endif /* ACE_HAS_STREAM_PIPES */
  25
  26 #include "ace/os_include/os_stdio.h"
  27 #include "ace/os_include/sys/os_uio.h"
  28
  29 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  30
  31 class ACE_Time_Value;
  32
  33 /**
  34  * @class ACE_DEV_IO
  35  *
  36  * @brief Read/Write operations on Devices.
  37  */
  38 class ACE_Export ACE_DEV_IO : public ACE_DEV
  39 {
  40 public:
  41   friend class ACE_DEV_Connector;
  42
  43   /// Default constructor.
  44   ACE_DEV_IO ();
  45
  46   // = Various send operations.
  47   /// send upto @a n bytes in @a buf.
  48   ssize_t send (const void *buf, size_t n) const;
  49
  50   /// Recv upto @a n bytes in @a buf.
  51   ssize_t recv (void *buf, size_t n) const;
  52
  53   /// Send n bytes, keep trying until n are sent.
  54   ssize_t send_n (const void *buf,
  55                   size_t n) const;
  56
  57   /**
  58    * @name I/O operations
  59    *
  60    * Notes on common parameters:
  61    *
  62    * @a buf is the buffer to write from or receive into.
  63    *
  64    * @a len is the number of bytes to transfer.
  65    *
  66    * The @a timeout parameter in the following methods indicates how
  67    * long to blocking trying to transfer data.  If @a timeout == 0,
  68    * then the call behaves as a normal send/recv call, i.e., for
  69    * blocking sockets, the call will block until action is possible;
  70    * for non-blocking sockets, EWOULDBLOCK will be returned if no
  71    * action is immediately possible.
  72    *
  73    * If @a timeout != 0, the call will wait until the relative time
  74    * specified in *@a timeout elapses.
  75    *
  76    * The "_n()" I/O methods keep looping until all the data has been
  77    * transferred.  These methods also work for sockets in non-blocking
  78    * mode i.e., they keep looping on EWOULDBLOCK.  @a timeout is used
  79    * to make sure we keep making progress, i.e., the same timeout
  80    * value is used for every I/O operation in the loop and the timeout
  81    * is not counted down.
  82    *
  83    * The return values for the "*_n()" methods match the return values
  84    * from the non "_n()" methods and are specified as follows:
  85    *
  86    * - On complete transfer, the number of bytes transferred is returned.
  87    * - On timeout, -1 is returned, errno == ETIME.
  88    * - On error, -1 is returned, errno is set to appropriate error.
  89    * - On EOF, 0 is returned, errno is irrelevant.
  90    *
  91    * On partial transfers, i.e., if any data is transferred before
  92    * timeout/error/EOF, @a bytes_transferred will contain the number of
  93    * bytes transferred.
  94    */
  95   ssize_t recv_n (void *buf,
  96                   size_t n,
  97                   const ACE_Time_Value *timeout = 0,
  98                   size_t *bytes_transferred = 0) const;
  99
 100 #if defined (ACE_HAS_STREAM_PIPES)
 101   /// Recv bytes via STREAM pipes using "band" mode.
 102   ssize_t recv (ACE_Str_Buf *cntl,
 103                 ACE_Str_Buf *data,
 104                 int *band,
 105                 int *flags) const;
 106
 107   /// Send bytes via STREAM pipes using "band" mode.
 108   ssize_t send (const ACE_Str_Buf *cntl,
 109                 const ACE_Str_Buf *data,
 110                 int band,
 111                 int flags) const;
 112
 113   /// Recv @a cntl and @a data via STREAM pipes.
 114   ssize_t recv (ACE_Str_Buf *cntl,
 115                 ACE_Str_Buf *data,
 116                 int *flags) const;
 117
 118   /// Send @a cntl and @a data via STREAM pipes.
 119   ssize_t send (const ACE_Str_Buf *cntl,
 120                 const ACE_Str_Buf *data,
 121                 int flags = 0) const;
 122 #endif /* ACE_HAS_STREAM_PIPES */
 123
 124   /// Send iovecs via <::writev>.
 125   ssize_t send (const iovec iov[], size_t n) const;
 126
 127   /// Recv iovecs via <::readv>.
 128   ssize_t recv (iovec iov[], size_t n) const;
 129
 130   /**
 131    * Send N char *ptrs and int lengths.  Note that the char *'s
 132    * precede the ints (basically, an varargs version of writev).  The
 133    * count N is the *total* number of trailing arguments, *not* a
 134    * couple of the number of tuple pairs!
 135    */
 136   ssize_t send (size_t n, ...) const;
 137
 138   /**
 139    * This is an interface to ::readv, that doesn't use the struct
 140    * iovec explicitly.  The ... can be passed as an arbitrary number
 141    * of (char *ptr, int len) tuples.  However, the count N is the
 142    * *total* number of trailing arguments, *not* a couple of the
 143    * number of tuple pairs!
 144    */
 145   ssize_t recv (size_t n, ...) const;
 146
 147   /// Send @a n bytes via Win32 WriteFile using overlapped I/O.
 148   ssize_t send (const void *buf, size_t n, ACE_OVERLAPPED *overlapped) const;
 149
 150   /// Recv @a n bytes via Win32 ReadFile using overlapped I/O.
 151   ssize_t recv (void *buf, size_t n, ACE_OVERLAPPED *overlapped) const;
 152
 153   /// Dump the state of an object.
 154   void dump () const;
 155
 156   // = The following two methods are no-ops to keep the
 157   // ACE_Connector happy.
 158   /// Return the local endpoint address.
 159   int get_local_addr (ACE_DEV_Addr &) const;
 160
 161   /// Return the address of the remotely connected peer (if there is
 162   /// one).
 163   int get_remote_addr (ACE_DEV_Addr &) const;
 164
 165   /// Declare the dynamic allocation hooks.
 166   ACE_ALLOC_HOOK_DECLARE;
 167
 168   // = Meta-type info
 169   typedef ACE_DEV_Addr PEER_ADDR;
 170
 171 private:
 172   /// Address of device we are connected to.
 173   ACE_DEV_Addr addr_;
 174 };
 175
 176 ACE_END_VERSIONED_NAMESPACE_DECL
 177
 178 #if defined (__ACE_INLINE__)
 179 #include "ace/DEV_IO.inl"
 180 #endif /* __ACE_INLINE__ */
 181
 182 #include /**/ "ace/post.h"
 183 #endif /* ACE_DEV_IO_H */