Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members | Related Pages

wvencoderstream.h

Go to the documentation of this file.
00001 /* -*- Mode: C++ -*-
00002  * Worldvisions Tunnel Vision Software:
00003  *   Copyright (C) 1997-2002 Net Integration Technologies, Inc.
00004  *
00005  * An stream wrapper for encoders.
00006  */
00007 #ifndef __WVENCODERSTREAM_H
00008 #define __WVENCODERSTREAM_H
00009 
00010 #include "wvstream.h"
00011 #include "wvstreamclone.h"
00012 #include "wvencoder.h"
00013 
00014 /**
00015  * WvEncoderStream chains a series of encoders on the input and
00016  * output ports of the underlying stream to effect on-the-fly data
00017  * transformations.
00018  * 
00019  * Notice that the value of WvEncoderStream's auto_flush flag becomes
00020  * important when working with encoders that treat explicit buffer
00021  * flushing in a special manner.  For instance, on flush() the Gzip
00022  * encoder synchronizes its output.  Were auto_flush to remain true,
00023  * each incremental write to the stream would cause the Gzip encoder
00024  * to flush its dictionary thereby resulting in poor compression.
00025  * 
00026  * @see WvStream::auto_flush(bool)
00027  */
00028 class WvEncoderStream : public WvStreamClone
00029 {
00030     bool is_closing;
00031     bool is_eof;
00032     WvDynBuf readinbuf;
00033     WvDynBuf readoutbuf;
00034     WvDynBuf writeinbuf;
00035     WvDynBuf writeoutbuf;
00036 
00037 public:
00038     /** Encoder chain through which input data is passed. */
00039     WvEncoderChain readchain;
00040 
00041     /** Encoder chain through which output data is passed. */
00042     WvEncoderChain writechain;
00043 
00044     /**
00045      * Controls the minimum number of unencoded bytes the encoder
00046      * should try to read at once from the underlying stream,
00047      * to optimize performance of block-oriented protocols.
00048      * This is not the same as queuemin() which guarantees how much
00049      * encoded input must be generated before select() returns true.
00050      * if 0, the encoder will only whatever is specified in uread()
00051      */
00052     size_t min_readsize;
00053 
00054     /**
00055      * Creates an encoder stream.
00056      *
00057      * "cloned" is the stream to wrap
00058      */
00059     WvEncoderStream(WvStream *cloned);
00060     virtual ~WvEncoderStream();
00061 
00062     /**
00063      * Safely shuts down the stream.
00064      * 
00065      * Does the following in sequence:
00066      * 
00067      *  - Flushes and finishes the read chain
00068      *  - Flushes and finishes the write chain
00069      *  - Flushes the stream output buffers
00070      *  - Closes the underlying stream
00071      */
00072     virtual void close();
00073 
00074     /**
00075      * Flushes the read chain through to the stream's input buffer.
00076      * 
00077      * The regular stream flush() only operates on the write chain.
00078      * 
00079      * Returns: true if the encoder chain returned true
00080      */
00081     bool flush_read();
00082 
00083     /**
00084      * Flushes the write chain through to the stream's output buffer.
00085      * 
00086      * The regular stream flush() invokes this, then attempts to
00087      * synchronously push the buffered data to the stream, which
00088      * may not always be desirable since it can be quite costly.
00089      * 
00090      * To simply cause the write chain to be flushed but allow
00091      * WvStreams to drain the encoded output buffer at its leisure,
00092      * use this function.
00093      * 
00094      * Returns: true if the encoder chain returned true
00095      */
00096     bool flush_write();
00097 
00098     /**
00099      * Calls flush() then finish() on the read chain of encoders.
00100      *
00101      * Returns: true if the encoder chain returned true
00102      */
00103     bool finish_read();
00104 
00105     /**
00106      * Calls flush() then finish() on the write chain of encoders.
00107      * 
00108      * Does not flush() the stream.
00109      * 
00110      * Returns: true if the encoder chain returned true.
00111      */
00112     bool finish_write();
00113 
00114     /**
00115      * Defines isok() semantics for encoders.
00116      * 
00117      * Returns false on error or after all data has been read from
00118      * the internal buffers and readchain.isfinished() or
00119      * ! writechain.isok().
00120      * 
00121      * Returns: true if it is still possible to read and write data
00122      */
00123     virtual bool isok() const;
00124 
00125 protected:
00126     bool pre_select(SelectInfo &si);
00127     virtual size_t uread(void *buf, size_t size);
00128     virtual size_t uwrite(const void *buf, size_t size);
00129     virtual bool flush_internal(time_t msec_timeout);
00130 
00131 private:
00132     void checkreadisok();
00133     void checkwriteisok();
00134     
00135     // pulls a chunk of specified size from the underlying stream
00136     void pull(size_t size);
00137 
00138     // pushes a chunk to the underlying stream
00139     bool push(bool flush, bool finish);
00140 };
00141 
00142 #endif // __WVENCODERSTREAM_H

Generated on Wed Dec 15 15:08:11 2004 for WvStreams by  doxygen 1.3.9.1