The reorg is being put in trunk, I think it's ready. Now we just get to find

out how many applications won't work anymore :)

1 files changed, 132 insertions, 16 deletions

diff --git a/src/stream.h b/src/stream.h
index e086e28..1e236a6 100644
--- a/src/stream.h
+++ b/src/stream.h
@@ -1,27 +1,143 @@
-#ifndef STREAM_H
-#define STREAM_H
+#ifndef BU_STREAM_H
+#define BU_STREAM_H
 
 #include <stdint.h>
 #include <stdio.h>
 
-class Stream
+namespace Bu
 {
-public:
-        Stream();
-        virtual ~Stream();
+        /**
+         * The basis for a completely general data transport mechanism.  Anything
+         * that inherits from this should provide at least the basic read and/or
+         * write functions, and very probably the close function.  Any functions
+         * that aren't supported should throw an exception if called.
+         *
+         * The constructor of a child class should pretty much universally be used
+         * to open the stream.  I can't think of anything that should require an
+         * exception.
+         */
+        class Stream
+        {
+        public:
+                Stream();
+                virtual ~Stream();
 
-        virtual void close() = 0;
-        virtual size_t read( char *pBuf, size_t nBytes ) = 0;
-        virtual size_t write( const char *pBuf, size_t nBytes ) = 0;
+                /**
+                 * Close the stream.
+                 */
+                virtual void close() = 0;
 
-        virtual long tell() = 0;
-        virtual void seek( long offset ) = 0;
-        virtual void setPos( long pos ) = 0;
-        virtual void setPosEnd( long pos ) = 0;
-        virtual bool isEOS() = 0;
+                /**
+                 * Read data from the stream into a buffer.
+                 *@param pBuf (void *) Buffer which will be filled.
+                 *@param nBytes (size_t) Max data to read.
+                 *@returns (size_t) Amount of data read.
+                 */
+                virtual size_t read( void *pBuf, size_t nBytes ) = 0;
 
-private:
+                /**
+                 * Write data to the stream.
+                 *@param pBuf (const void *) The data to be written.
+                 *@param nBytes (size_t) Amount of data to write from pBuf.
+                 *@returns (size_t) Amount of data actually written.
+                 */
+                virtual size_t write( const void *pBuf, size_t nBytes ) = 0;
 
-};
+                /**
+                 * Get the current position in the stream.
+                 *@returns (long) The current position in the stream.
+                 */
+                virtual long tell() = 0;
+
+                /**
+                 * Seek to a position in the stream relative to the current position.
+                 *@param offset (long) Offset from current position to seek to.
+                 */
+                virtual void seek( long offset ) = 0;
+
+                /**
+                 * Set position in the stream relative to the start of the stream.
+                 *@param pos (long) The position.
+                 */
+                virtual void setPos( long pos ) = 0;
+
+                /**
+                 * Set position in the stream relative to the end of the stream.
+                 *@param pos (long) The position.
+                 */
+                virtual void setPosEnd( long pos ) = 0;
+
+                /**
+                 * Are we at the end of the stream?
+                 *@returns (bool) Are we at the end of the stream?
+                 */
+                virtual bool isEOS() = 0;
+
+                /**
+                 * Is the stream open?
+                 *@returns (bool) Is the stream open?
+                 */
+                virtual bool isOpen() = 0;
+
+                /**
+                 * Flush any data still held in buffers.
+                 */
+                virtual void flush() = 0;
+
+                /**
+                 * In non-blocking streams this indicates if a read operation will
+                 * return data at the moment or not.  In blocking streams this should
+                 * return the same value as isEOS().
+                 */
+                virtual bool canRead() = 0;
+
+                /**
+                 * In non-blocking streams this indicates if a write operation will
+                 * succeed or fail.  In some cases writing is not allowed (e.g. 
+                 * internal buffers are full) temporarilly.  In blocking streams this
+                 * should return the same value as isWritable.
+                 */
+                virtual bool canWrite() = 0;
+
+                /**
+                 * Indicates if the stream is capable of read operations.  This does not
+                 * indicate if such operations will return useful data, see canRead for
+                 * that.
+                 */
+                virtual bool isReadable() = 0;
+
+                /**
+                 * Indicates if the stream is capable of write operations.  This does
+                 * not indicate if such operations will succeed or fail, see canWrite
+                 * for that.
+                 */
+                virtual bool isWritable() = 0;
+
+                /**
+                 * Indicates if the stream is capable of seek operations.  This is
+                 * generally false for non-blocking streams.  Some buffered streams may
+                 * support limited in-buffer seeking.
+                 */
+                virtual bool isSeekable() = 0;
+
+                /**
+                 * Are we currently set to block mode?
+                 *@returns (bool)
+                 */
+                virtual bool isBlocking() = 0;
+
+                /**
+                 * Set stream to blocking or non-blocking mode.
+                 *@param bBlocking (bool) Whether we should block or not.
+                 */
+                virtual void setBlocking( bool bBlocking=true ) = 0;
+
+        public: // Filters
+
+
+        private:
+
+        };
+}
 
 #endif