include/wvencoderstream.h

   1 /* -*- Mode: C++ -*-
   2  * Worldvisions Tunnel Vision Software:
   3  *   Copyright (C) 1997-2002 Net Integration Technologies, Inc.
   4  *
   5  * An stream wrapper for encoders.
   6  */
   7 #ifndef __WVENCODERSTREAM_H
   8 #define __WVENCODERSTREAM_H
   9
  10 #include "wvstream.h"
  11 #include "wvstreamclone.h"
  12 #include "wvencoder.h"
  13
  14 /**
  15  * WvEncoderStream chains a series of encoders on the input and
  16  * output ports of the underlying stream to effect on-the-fly data
  17  * transformations.
  18  *
  19  * Notice that the value of WvEncoderStream's auto_flush flag becomes
  20  * important when working with encoders that treat explicit buffer
  21  * flushing in a special manner.  For instance, on flush() the Gzip
  22  * encoder synchronizes its output.  Were auto_flush to remain true,
  23  * each incremental write to the stream would cause the Gzip encoder
  24  * to flush its dictionary thereby resulting in poor compression.
  25  *
  26  * See WvStream::auto_flush(bool).
  27  *
  28  * WARNING: it is possible to add to the readchain and/or writechain in the
  29  * middle of a session, for example to add gzip compression after first
  30  * negotiating it with the remote end.  If you plan to do this, be very
  31  * careful with buffering.  Never read() or getline() more bytes than
  32  * you're sure will exist with the old encoding.  Even then, only ever
  33  * append things to the readchain, not prepend.  (Therefore only prepend
  34  * things to the writechain.) Always flush() or flush_write() before
  35  * adding to the writechain.  See also min_readsize.
  36  */
  37 class WvEncoderStream : public WvStreamClone
  38 {
  39     bool is_closing;
  40     WvDynBuf readinbuf;
  41     WvDynBuf readoutbuf;
  42     WvDynBuf writeinbuf;
  43     //WvDynBuf writeoutbuf;
  44
  45 public:
  46     /** Encoder chain through which input data is passed. */
  47     WvEncoderChain readchain;
  48
  49     /** Encoder chain through which output data is passed. */
  50     WvEncoderChain writechain;
  51
  52     /**
  53      * Controls the minimum number of unencoded bytes the encoder
  54      * should try to read at once from the underlying stream,
  55      * to optimize performance of block-oriented protocols.
  56      * This is not the same as queuemin() which guarantees how much
  57      * encoded input must be generated before select() returns true.
  58      * if 0, the encoder will only read whatever is specified in uread().
  59      *
  60      * NOTE: if you plan to append a new encoder to the readchain after
  61      * doing read(), you should always use read() with only 1 byte at a
  62      * time, or some extra data will end up in inbuf and not pass through
  63      * the newly- added encoder.  Remember that getline() also calls
  64      * read().  The purpose of min_readsize is to make these one-byte
  65      * read() calls more efficient, because the *underlying* stream can
  66      * still read lots of bytes, as long as we only pass single bytes down
  67      * to the WvEncoderStream.
  68      *
  69      * If you don't plan to add new encoders to readchain from now on, you
  70      * can give larger sizes to read() or getline(), and thus min_readsize
  71      * is unnecessary.
  72      */
  73     size_t min_readsize;
  74
  75     /**
  76      * Creates an encoder stream.
  77      *
  78      * "cloned" is the stream to wrap
  79      */
  80     WvEncoderStream(WvStream *cloned);
  81     virtual ~WvEncoderStream();
  82
  83     /**
  84      * Safely shuts down the stream.
  85      *
  86      * Does the following in sequence:
  87      *
  88      *  - Flushes and finishes the read chain
  89      *  - Flushes and finishes the write chain
  90      *  - Flushes the stream output buffers
  91      *  - Closes the underlying stream
  92      */
  93     virtual void close();
  94
  95     /**
  96      * Flushes the read chain through to the stream's input buffer.
  97      *
  98      * The regular stream flush() only operates on the write chain.
  99      *
 100      * Returns: true if the encoder chain returned true
 101      */
 102     bool flush_read();
 103
 104     /**
 105      * Flushes the write chain through to the stream's output buffer.
 106      *
 107      * The regular stream flush() invokes this, then attempts to
 108      * synchronously push the buffered data to the stream, which
 109      * may not always be desirable since it can be quite costly.
 110      *
 111      * To simply cause the write chain to be flushed but allow
 112      * WvStreams to drain the encoded output buffer at its leisure,
 113      * use this function.
 114      *
 115      * Returns: true if the encoder chain returned true
 116      */
 117     bool flush_write();
 118
 119     /**
 120      * Calls flush() then finish() on the read chain of encoders.
 121      *
 122      * Returns: true if the encoder chain returned true
 123      */
 124     bool finish_read();
 125
 126     /**
 127      * Calls flush() then finish() on the write chain of encoders.
 128      *
 129      * Does not flush() the stream.
 130      *
 131      * Returns: true if the encoder chain returned true.
 132      */
 133     bool finish_write();
 134
 135     /**
 136      * Defines isok() semantics for encoders.
 137      *
 138      * Returns false on error or after all data has been read from
 139      * the internal buffers and readchain.isfinished() or
 140      * ! writechain.isok().
 141      *
 142      * Returns: true if it is still possible to read and write data
 143      */
 144     virtual bool isok() const;
 145
 146     virtual size_t uread(void *buf, size_t size);
 147     virtual size_t uwrite(const void *buf, size_t size);
 148
 149 protected:
 150     void pre_select(SelectInfo &si);
 151     bool post_select(SelectInfo &si);
 152     virtual bool flush_internal(time_t msec_timeout);
 153
 154 private:
 155     void checkreadisok();
 156     void checkwriteisok();
 157
 158     // pulls a chunk of specified size from the underlying stream
 159     void pull(size_t size);
 160
 161     // pushes a chunk to the underlying stream
 162     bool push(bool flush, bool finish);
 163
 164 public:
 165     const char *wstype() const { return "WvEncoderStream"; }
 166 };
 167
 168 #endif // __WVENCODERSTREAM_H