ACE/protocols/ace/HTBP/HTBP_Stream.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    HTBP_Stream.h
   6  *
   7  *  @author Phil Mesnier, Priyanka Gontla
   8  */
   9 //=============================================================================
  10
  11 #ifndef ACE_HTBP_STREAM_H
  12 #define ACE_HTBP_STREAM_H
  13 #include /**/ "ace/pre.h"
  14
  15 #include "ace/SOCK_Stream.h"
  16 #include "ace/Message_Block.h"
  17
  18 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  19 # pragma once
  20 #endif /* ACE_LACKS_PRAGMA_ONCE */
  21
  22 #include "HTBP_Export.h"
  23 #include "HTBP_Addr.h"
  24 #include "HTBP_Filter.h"
  25 #include "HTBP_Notifier.h"
  26
  27 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  28
  29 namespace ACE
  30 {
  31   namespace HTBP
  32   {
  33     // Forward declarations.
  34     class Session;
  35
  36     /**
  37      * @class Stream
  38      *
  39      * @brief A stream facade for the HTTP Tunneling Bidirectional Protocol
  40      *
  41      * This adds provides the common interface for applications to do
  42      * I/O that ultimately is wrapped in HTTP for tunneling through
  43      * firewalls.
  44      *
  45      * This class is modelled after the ACE_SOCK_Stream class, and
  46      * provides all of the I/O methods available in that class. Since
  47      * this is a facade, it does not derive from ACE_SOCK_Stream. It
  48      * also does not provide the same performance as ACE_SOCK_Stream,
  49      * as some data may have to be stored by the HTBP classes prior to
  50      * transmission.
  51      *
  52      * <buf> is the buffer to write from or receive into.
  53      * <len> is the number of bytes to transfer.
  54      * The <timeout> parameter in the following methods indicates how
  55      * long to blocking trying to transfer data.  If <timeout> == 0,
  56      * then the call behaves as a normal send/recv call, i.e., for
  57      * blocking sockets, the call will block until action is possible;
  58      * for non-blocking sockets, EWOULDBLOCK will be returned if no
  59      * action is immediately possible.
  60      * If <timeout> != 0, the call will wait for data to arrive no longer
  61      * than the relative time specified in *<timeout>.
  62      * The "_n()" I/O methods keep looping until all the data has been
  63      * transferred.  These methods also work for sockets in non-blocking
  64      * mode i.e., they keep looping on EWOULDBLOCK.  <timeout> is used
  65      * to make sure we keep making progress, i.e., the same timeout
  66      * value is used for every I/O operation in the loop and the timeout
  67      * is not counted down.
  68      * The return values for the "*_n()" methods match the return values
  69      * from the non "_n()" methods and are specified as follows:
  70      * - On complete transfer, the number of bytes transferred is returned.
  71      * - On timeout, -1 is returned, errno == ETIME.
  72      * - On error, -1 is returned, errno is set to appropriate error.
  73      * - On EOF, 0 is returned, errno is irrelevant.
  74      *
  75      * On partial transfers, i.e., if any data is transferred before
  76      * timeout/error/EOF, <bytes_transferred> will contain the number of
  77      * bytes transferred.
  78      * Methods with <iovec> parameter are I/O vector variants of the I/O
  79      * operations.
  80      * Methods with the extra <flags> argument will always result in
  81      * <send> getting called. Methods without the extra <flags> argument
  82      * will result in <send> getting called on Win32 platforms, and
  83      * <write> getting called on non-Win32 platforms.
  84      */
  85     class HTBP_Export Stream
  86     {
  87     public:
  88       // Initialization and termination methods.
  89       /// Constructor.
  90       Stream (Session *s = 0);
  91
  92       /// Destructor.
  93       ~Stream ();
  94
  95       // = I/O functions.
  96
  97       /// The Stream is a sibling of the ACE_SOCK_IO class, rather
  98       /// than a decendant. This is due to the requirement to wrap all
  99       /// messages with an HTTP request or reply wrapper, and to send
 100       /// application data in only one direction on one stream.
 101
 102       /// Recv an <n> byte buffer from the connected socket.
 103       ssize_t recv (void *buf,
 104                     size_t n,
 105                     int flags,
 106                     const ACE_Time_Value *timeout = 0) const;
 107
 108       /// Recv an <n> byte buffer from the connected socket.
 109       ssize_t recv (void *buf,
 110                     size_t n,
 111                     const ACE_Time_Value *timeout = 0) const;
 112
 113       /// Recv an <iovec> of size <n> from the connected socket.
 114       ssize_t recvv (iovec iov[],
 115                      int n,
 116                      const ACE_Time_Value *timeout = 0) const;
 117
 118       /// Same as above.  Deprecated.
 119       ssize_t recv (iovec iov[],
 120                     size_t n,
 121                     const ACE_Time_Value *timeout = 0) const;
 122
 123       /**
 124        * Allows a client to read from a socket without having to
 125        * provide a buffer to read.  This method determines how much
 126        * data is in the socket, allocates a buffer of this size, reads
 127        * in the data, and returns the number of bytes read.  The
 128        * caller is responsible for deleting the member in the
 129        * <iov_base> field of <io_vec> using delete []
 130        * io_vec->iov_base.
 131        */
 132       ssize_t recvv (iovec *io_vec,
 133                      const ACE_Time_Value *timeout = 0) const;
 134
 135       /// Recv <n> bytes via Win32 <ReadFile> using overlapped I/O.
 136       ssize_t recv (void *buf,
 137                     size_t n,
 138                     ACE_OVERLAPPED *overlapped) const;
 139
 140       /// Send an <n> byte buffer to the connected socket.
 141       ssize_t send (const void *buf,
 142                     size_t n,
 143                     int flags,
 144                     const ACE_Time_Value *timeout = 0) const;
 145
 146       /// Send an <n> byte buffer to the connected socket.
 147       ssize_t send (const void *buf,
 148                     size_t n,
 149                     const ACE_Time_Value *timeout = 0) const;
 150
 151       /// Send an <iovec> of size <n> to the connected socket.
 152       ssize_t sendv (const iovec iov[],
 153                      int n,
 154                      const ACE_Time_Value *timeout = 0) const;
 155
 156       /// Send <n> bytes via Win32 <WriteFile> using overlapped I/O.
 157       ssize_t send (const void *buf,
 158                     size_t n,
 159                     ACE_OVERLAPPED *overlapped) const;
 160
 161
 162       /// Try to recv exactly <len> bytes into <buf> from the
 163       /// connected socket.
 164       ssize_t recv_n (void *buf,
 165                       size_t len,
 166                       int flags,
 167                       const ACE_Time_Value *timeout = 0,
 168                       size_t *bytes_transferred = 0) const;
 169
 170       /// Try to recv exactly <len> bytes into <buf> from the
 171       /// connected socket.
 172       ssize_t recv_n (void *buf,
 173                       size_t len,
 174                       const ACE_Time_Value *timeout = 0,
 175                       size_t *bytes_transferred = 0) const;
 176
 177       /// Receive an <iovec> of size <iovcnt> from the connected
 178       /// socket.
 179       ssize_t recvv_n (iovec iov[],
 180                        int iovcnt,
 181                        const ACE_Time_Value *timeout = 0,
 182                        size_t *bytes_transferred = 0) const;
 183
 184       /// Try to send exactly <len> bytes from <buf> to the connection
 185       /// socket.
 186       ssize_t send_n (const void *buf,
 187                       size_t len,
 188                       int flags,
 189                       const ACE_Time_Value *timeout = 0,
 190                       size_t *bytes_transferred = 0) const;
 191
 192       /// Try to send exactly <len> bytes from <buf> to the connected
 193       /// socket.
 194       ssize_t send_n (const void *buf,
 195                       size_t len,
 196                       const ACE_Time_Value *timeout = 0,
 197                       size_t *bytes_transferred = 0) const;
 198
 199       /// Send all the <message_block>s chained through their <next>
 200       /// and <cont> pointers.  This call uses the underlying OS
 201       /// gather-write operation to reduce the domain-crossing
 202       /// penalty.
 203       ssize_t send_n (const ACE_Message_Block *message_block,
 204                       const ACE_Time_Value *timeout = 0,
 205                       size_t *bytes_transferred = 0) const;
 206
 207       /// Send an <iovec> of size <iovcnt> to the connected socket.
 208       ssize_t sendv_n (const iovec iov[],
 209                        int iovcnt,
 210                        const ACE_Time_Value *timeout = 0,
 211                        size_t *bytes_transferred = 0) const;
 212
 213       // = Selectively close endpoints.  / Close down the reader.
 214       int close_reader ();
 215
 216       /// Close down the writer.
 217       int close_writer ();
 218
 219       /**
 220        * Close down the socket (we need this to make things work correctly
 221        * on Win32, which requires use to do a <close_writer> before doing
 222        * the close to avoid losing data).
 223        */
 224       int close ();
 225
 226       // = Meta-type info
 227       typedef Addr PEER_ADDR;
 228
 229       /// Dump the state of an object.
 230       void dump () const;
 231
 232       /// Declare the dynamic allocation hooks.
 233       ACE_ALLOC_HOOK_DECLARE;
 234
 235     public:
 236       ///@notes Added the following methods to continue with
 237       /// current compilation of HTIOP. Might not be needed in
 238       /// future. - Priyanka
 239       /// {@
 240       void set_handle (ACE_HANDLE h);
 241       ACE_HANDLE get_handle () const;
 242
 243       Session *session () const;
 244       void session (Session *s);
 245
 246       /**
 247        * Enable asynchronous I/O (ACE_SIGIO), urgent data (ACE_SIGURG),
 248        * non-blocking I/O (ACE_NONBLOCK), or close-on-exec (ACE_CLOEXEC),
 249        * which is passed as the <value>.
 250        */
 251       int enable (int value) const;
 252
 253       /**
 254        * Disable asynchronous I/O (ACE_SIGIO), urgent data (ACE_SIGURG),
 255        * non-blocking I/O (ACE_NONBLOCK), or close-on-exec (ACE_CLOEXEC),
 256        * which is passed as the <value>.
 257        */
 258       int disable (int value) const;
 259
 260       /**
 261        * Return the address of the remotely connected peer (if there is
 262        * one), in the referenced <ACE_Addr>. Returns 0 if successful, else
 263        * -1.
 264        */
 265       int get_remote_addr (Addr &) const;
 266
 267       /**
 268        * Return the address of the remotely connected peer (if there is
 269        * one), in the referenced <ACE_Addr>. Returns 0 if successful, else
 270        * -1.
 271        */
 272       int get_local_addr (Addr &) const;
 273
 274       //@}
 275
 276     private:
 277       /// The session_ is a reference to the persistent session this stream is
 278       /// associated with. On the inside, sessions are created by the Connector,
 279       /// which then create streams on demand.
 280       Session *session_;
 281     };
 282   }
 283 }
 284
 285 ACE_END_VERSIONED_NAMESPACE_DECL
 286
 287 #include /**/ "ace/post.h"
 288 #endif /* ACE_HTBP_STREAM_H */