fix others $Id$ keywords

[wxWidgets.git] / interface / wx / stream.h

diff --git a/interface/wx/stream.h b/interface/wx/stream.h
index 532ac2d28daf75ea18219c48c598a60b91caff0b..7ff04991aab4baeaa164d8dfd9cb071743fef684 100644 (file)
--- a/interface/wx/stream.h
+++ b/interface/wx/stream.h
@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        stream.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        stream.h

-// Purpose:     interface of wxCountingOutputStream
+// Purpose:     interface of wxStreamBase and its derived classes

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license


@@ -8,23 +8,15 @@
 
 /**
     @class wxCountingOutputStream
 
 /**
     @class wxCountingOutputStream

-    @wxheader{stream.h}

 
     wxCountingOutputStream is a specialized output stream which does not write any
 
     wxCountingOutputStream is a specialized output stream which does not write any

-    data anywhere,
-    instead it counts how many bytes would get written if this were a normal
-    stream. This
-    can sometimes be useful or required if some data gets serialized to a stream or
-    compressed
-    by using stream compression and thus the final size of the stream cannot be
-    known other
-    than pretending to write the stream. One case where the resulting size would
-    have to be
-    known is if the data has to be written to a piece of memory and the memory has
-    to be
-    allocated before writing to it (which is probably always the case when writing
-    to a
-    memory stream).
+    data anywhere, instead it counts how many bytes would get written if this were a
+    normal stream. This can sometimes be useful or required if some data gets
+    serialized to a stream or compressed by using stream compression and thus the
+    final size of the stream cannot be known other than pretending to write the stream.
+    One case where the resulting size would have to be known is if the data has
+    to be written to a piece of memory and the memory has to be allocated before
+    writing to it (which is probably always the case when writing to a memory stream).

 
     @library{wxbase}
     @category{streams}
 
     @library{wxbase}
     @category{streams}


@@ -40,7 +32,7 @@ public:
     /**
         Destructor.
     */
     /**
         Destructor.
     */

-    ~wxCountingOutputStream();
+    virtual ~wxCountingOutputStream();

 
     /**
         Returns the current size of the stream.
 
     /**
         Returns the current size of the stream.


@@ -52,10 +44,9 @@ public:
 
 /**
     @class wxBufferedInputStream
 
 /**
     @class wxBufferedInputStream

-    @wxheader{stream.h}

 
     This stream acts as a cache. It caches the bytes read from the specified
 
     This stream acts as a cache. It caches the bytes read from the specified

-    input stream (See wxFilterInputStream).
+    input stream (see wxFilterInputStream).

     It uses wxStreamBuffer and sets the default in-buffer size to 1024 bytes.
     This class may not be used without some other stream to read the data
     from (such as a file stream or a memory stream).
     It uses wxStreamBuffer and sets the default in-buffer size to 1024 bytes.
     This class may not be used without some other stream to read the data
     from (such as a file stream or a memory stream).


@@ -68,44 +59,140 @@ public:
 class wxBufferedInputStream : public wxFilterInputStream
 {
 public:
 class wxBufferedInputStream : public wxFilterInputStream
 {
 public:

+    /**
+        Constructor using the provided buffer or default.
+
+        @param stream
+            The associated low-level stream.
+        @param buffer
+            The buffer to use if non-@NULL. Notice that the ownership of this
+            buffer is taken by the stream, i.e. it will delete it. If this
+            parameter is @NULL a default 1KB buffer is used.
+    */
+    wxBufferedInputStream(wxInputStream& stream,
+                          wxStreamBuffer *buffer = NULL);
+
+    /**
+        Constructor allowing to specify the size of the buffer.

 
 

+        This is just a more convenient alternative to creating a wxStreamBuffer
+        of the given size and using the other overloaded constructor of this
+        class.
+
+        @param stream
+            The associated low-level stream.
+        @param bufsize
+            The size of the buffer, in bytes.
+
+        @since 2.9.0
+     */
+    wxBufferedInputStream(wxInputStream& stream, size_t bufsize);
+
+    /**
+        Destructor.
+    */
+    virtual ~wxBufferedInputStream();

 };
 
 
 
 /**
     @class wxStreamBuffer
 };
 
 
 
 /**
     @class wxStreamBuffer

-    @wxheader{stream.h}

 
 

+    wxStreamBuffer is a cache manager for wxStreamBase: it manages a stream buffer
+    linked to a stream.
+
+    Each stream always has one autoinitialized stream buffer, but you may
+    attach more of them to the same stream.

 
     @library{wxbase}
     @category{streams}
 
 
     @library{wxbase}
     @category{streams}
 

-    @see wxStreamBase
+    @see wxStreamBase, @ref overview_stream

 */
 class wxStreamBuffer
 {
 public:
 */
 class wxStreamBuffer
 {
 public:

-    //@{
+
+    /**
+        Constructor, creates a new stream buffer using @a stream as a parent stream
+        and mode as the IO mode.
+
+        @param stream
+            The parent stream.
+        @param mode
+            Can be: wxStreamBuffer::read, wxStreamBuffer::write, wxStreamBuffer::read_write.
+
+        One stream can have many stream buffers but only one is used internally
+        to pass IO call (e.g. wxInputStream::Read() -> wxStreamBuffer::Read()),
+        but you can call directly wxStreamBuffer::Read without any problems.
+        Note that all errors and messages linked to the stream are stored in the
+        stream, not the stream buffers:
+
+        @code
+        streambuffer.Read(...);
+        streambuffer2.Read(...);
+            // This call erases previous error messages set by 'streambuffer'
+            // assuming that both instances are stream buffers for the same stream
+        @endcode
+
+        @see SetBufferIO()
+    */
+    wxStreamBuffer(wxStreamBase& stream, BufMode mode);
+
+    /**
+        Constructor for an input buffer of the specified size.
+
+        Using it is equivalent to using the constructor above with read mode
+        and calling SetBufferIO() but is more convenient.
+
+        @since 2.9.0
+     */
+    wxStreamBuffer(wxInputStream& stream, size_t bufsize);
+
+    /**
+        Constructor for an output buffer of the specified size.
+
+        Using it is equivalent to using the constructor above with write mode
+        and calling SetBufferIO() but is more convenient.
+
+        @since 2.9.0
+     */
+    wxStreamBuffer(wxOutputStream& stream, size_t bufsize);
+
+    /**
+        Constructor; creates a new empty stream buffer which won't flush any data
+        to a stream. mode specifies the type of the buffer (read, write, read_write).
+
+        This stream buffer has the advantage to be stream independent and to work
+        only on memory buffers but it is still compatible with the rest of the
+        wxStream classes. You can write, read to this special stream and it will
+        grow (if it is allowed by the user) its internal buffer.
+        Briefly, it has all functionality of a "normal" stream.
+
+        @warning
+        The "read_write" mode doesn't currently work for standalone stream buffers.
+
+        @see SetBufferIO()
+    */
+    wxStreamBuffer(BufMode mode);
+

     /**
     /**

-        Constructor. It initializes the stream buffer with the data of the specified
+        Copy constructor.
+
+        This method initializes the stream buffer with the data of the specified

         stream buffer. The new stream buffer has the same attributes, size, position
         and they share the same buffer. This will cause problems if the stream to
         which the stream buffer belong is destroyed and the newly cloned stream
         buffer continues to be used, trying to call functions in the (destroyed)
         stream. It is advised to use this feature only in very local area of the
         program.
         stream buffer. The new stream buffer has the same attributes, size, position
         and they share the same buffer. This will cause problems if the stream to
         which the stream buffer belong is destroyed and the newly cloned stream
         buffer continues to be used, trying to call functions in the (destroyed)
         stream. It is advised to use this feature only in very local area of the
         program.

-
-        @see @ref setbufferio() wxStreamBuffer:SetBufferIO

     */
     */

-    wxStreamBuffer(wxStreamBase& stream, BufMode mode);
-    wxStreamBuffer(BufMode mode);

     wxStreamBuffer(const wxStreamBuffer& buffer);
     wxStreamBuffer(const wxStreamBuffer& buffer);

-    //@}

 
     /**
 
     /**

-        Destructor. It finalizes all IO calls and frees all internal buffers if
-        necessary.
+        Destructor.
+        It finalizes all IO calls and frees all internal buffers if necessary.

     */
     wxStreamBuffer();
 
     */
     wxStreamBuffer();
 


@@ -117,8 +204,8 @@ public:
     /**
         Toggles the fixed flag. Usually this flag is toggled at the same time as
         @e flushable. This flag allows (when it has the @false value) or forbids
     /**
         Toggles the fixed flag. Usually this flag is toggled at the same time as
         @e flushable. This flag allows (when it has the @false value) or forbids

-        (when it has the @true value) the stream buffer to resize dynamically the IO
-        buffer.
+        (when it has the @true value) the stream buffer to resize dynamically the
+        IO buffer.

 
         @see SetBufferIO()
     */
 
         @see SetBufferIO()
     */


@@ -130,8 +217,8 @@ public:
     bool FlushBuffer();
 
     /**
     bool FlushBuffer();
 
     /**

-        Toggles the flushable flag. If @a flushable is disabled, no data are sent
-        to the parent stream.
+        Toggles the flushable flag.
+        If @a flushable is disabled, no data are sent to the parent stream.

     */
     void Flushable(bool flushable);
 
     */
     void Flushable(bool flushable);
 


@@ -156,11 +243,14 @@ public:
     void* GetBufferStart() const;
 
     /**
     void* GetBufferStart() const;
 
     /**

-        Gets a single char from the stream buffer. It acts like the Read call.
+        Gets a single char from the stream buffer. It acts like the Read() call.
+
+        @warning
+        You aren't directly notified if an error occurred during the IO call.

 
         @see Read()
     */
 
         @see Read()
     */

-    char GetChar();
+    virtual char GetChar();

 
     /**
         Returns the amount of available data in the buffer.
 
     /**
         Returns the amount of available data in the buffer.


@@ -170,7 +260,7 @@ public:
     /**
         Returns the current position (counted in bytes) in the stream buffer.
     */
     /**
         Returns the current position (counted in bytes) in the stream buffer.
     */

-    off_t GetIntPosition() const;
+    size_t GetIntPosition() const;

 
     /**
         Returns the amount of bytes read during the last IO call to the parent stream.
 
     /**
         Returns the amount of bytes read during the last IO call to the parent stream.


@@ -180,21 +270,33 @@ public:
     /**
         Puts a single char to the stream buffer.
 
     /**
         Puts a single char to the stream buffer.
 

+        @warning
+        You aren't directly notified if an error occurred during the IO call.
+

         @see Read()
     */
         @see Read()
     */

-    void PutChar(char c);
+    virtual void PutChar(char c);

 
 

-    //@{

     /**
     /**

-        Copies data to @e buffer. The function returns when @a buffer is full or when
-        there isn't
+        Reads a block of the specified size and stores the data in buffer.
+        This function tries to read from the buffer first and if more data has
+        been requested, reads more data from the associated stream and updates
+        the buffer accordingly until all requested data is read.
+
+        @return It returns the size of the data read. If the returned size is
+                different of the specified size, an error has occurred and
+                should be tested using GetLastError().
+    */
+    virtual size_t Read(void* buffer, size_t size);
+
+    /**
+        Copies data to @a buffer.
+        The function returns when @a buffer is full or when there isn't

         any more data in the current buffer.
 
         @see Write()
     */
         any more data in the current buffer.
 
         @see Write()
     */

-    size_t Read(void* buffer, size_t size);
-    Return value size_t Read(wxStreamBuffer* buffer);
-    //@}
+    size_t Read(wxStreamBuffer* buffer);

 
     /**
         Resets to the initial state variables concerning the buffer.
 
     /**
         Resets to the initial state variables concerning the buffer.


@@ -203,50 +305,61 @@ public:
 
     /**
         Changes the current position.
 
     /**
         Changes the current position.

-        @a mode may be one of the following:
+        Parameter @a mode may be one of the following:

 
 

-        @b wxFromStart
+        - @b wxFromStart: The position is counted from the start of the stream.
+        - @b wxFromCurrent: The position is counted from the current position of the stream.
+        - @b wxFromEnd: The position is counted from the end of the stream.

 
 

-        The position is counted from the start of the stream.
-
-        @b wxFromCurrent
-
-        The position is counted from the current position of the stream.
+        @return Upon successful completion, it returns the new offset as
+                measured in bytes from the beginning of the stream.
+                Otherwise, it returns wxInvalidOffset.
+    */
+    virtual wxFileOffset Seek(wxFileOffset pos, wxSeekMode mode);

 
 

-        @b wxFromEnd
+    /**
+        Specifies which pointers to use for stream buffering.
+        You need to pass a pointer on the start of the buffer end and another
+        on the end. The object will use this buffer to cache stream data.
+        It may be used also as a source/destination buffer when you create an
+        empty stream buffer (See wxStreamBuffer::wxStreamBuffer).

 
 

-        The position is counted from the end of the stream.
+        @remarks
+        When you use this function, you will have to destroy the IO buffers
+        yourself after the stream buffer is destroyed or don't use it anymore.
+        In the case you use it with an empty buffer, the stream buffer will not
+        resize it when it is full.

 
 

-        @return Upon successful completion, it returns the new offset as
-                 measured in bytes from the beginning of the stream.
-                 Otherwise, it returns wxInvalidOffset.
+        @see wxStreamBuffer(), Fixed(), Flushable()

     */
     */

-    off_t Seek(off_t pos, wxSeekMode mode);
+    void SetBufferIO(void* start, void* end, bool takeOwnership = false);

 
 

-    //@{

     /**
         Destroys or invalidates the previous IO buffer and allocates a new one of the
         specified size.
 
     /**
         Destroys or invalidates the previous IO buffer and allocates a new one of the
         specified size.
 

-        @see Fixed(), Flushable()
-    */
-    void SetBufferIO(char* buffer_start, char* buffer_end);
-    Remarks See also
-    wxStreamBuffer constructor
+        @warning
+        All previous pointers aren't valid anymore.

 
 

-    wxStreamBuffer::Fixed
+        @remarks
+        The created IO buffer is growable by the object.

 
 

-    wxStreamBuffer::Flushable
+        @see Fixed(), Flushable()
+    */

     void SetBufferIO(size_t bufsize);
     void SetBufferIO(size_t bufsize);

-    //@}

 
     /**
         Sets the current position (in bytes) in the stream buffer.
 
     /**
         Sets the current position (in bytes) in the stream buffer.

+
+        @warning
+        Since it is a very low-level function, there is no check on the position:
+        specifying an invalid position can induce unexpected results.

     */
     void SetIntPosition(size_t pos);
 
     /**
         Returns the parent stream of the stream buffer.
     */
     void SetIntPosition(size_t pos);
 
     /**
         Returns the parent stream of the stream buffer.

+        @deprecated use GetStream() instead

     */
     wxStreamBase* Stream();
 
     */
     wxStreamBase* Stream();
 


@@ -257,31 +370,34 @@ public:
         the stream.
 
         @return Returns the current position in the stream if possible,
         the stream.
 
         @return Returns the current position in the stream if possible,

-                 wxInvalidOffset in the other case.
+                wxInvalidOffset in the other case.

     */
     */

-    off_t Tell() const;
+    virtual wxFileOffset Tell() const;

 
     /**
         Truncates the buffer to the current position.
 
     /**
         Truncates the buffer to the current position.

-        Note: Truncate() cannot be used to enlarge the buffer. This is
-        usually not needed since the buffer expands automatically.
+
+        @note Truncate() cannot be used to enlarge the buffer. This is
+              usually not needed since the buffer expands automatically.

     */
     void Truncate();
 
     */
     void Truncate();
 

-    //@{
+    /**
+        Writes a block of the specified size using data of buffer.
+        The data are cached in a buffer before being sent in one block to the stream.
+    */
+    virtual size_t Write(const void* buffer, size_t size);
+

     /**
         See Read().
     */
     /**
         See Read().
     */

-    size_t Write(const void* buffer, size_t size);

     size_t Write(wxStreamBuffer* buffer);
     size_t Write(wxStreamBuffer* buffer);

-    //@}

 };
 
 
 
 /**
     @class wxOutputStream
 };
 
 
 
 /**
     @class wxOutputStream

-    @wxheader{stream.h}

 
     wxOutputStream is an abstract base class which may not be used directly.
 
 
     wxOutputStream is an abstract base class which may not be used directly.
 


@@ -299,24 +415,25 @@ public:
     /**
         Destructor.
     */
     /**
         Destructor.
     */

-    ~wxOutputStream();
+    virtual ~wxOutputStream();

 
     /**
 
     /**

-        Closes the stream, returning @false if an error occurs. The
-        stream is closed implicitly in the destructor if Close() is not
+        Closes the stream, returning @false if an error occurs.
+        The stream is closed implicitly in the destructor if Close() is not

         called explicitly.
         called explicitly.

+

         If this stream wraps another stream or some other resource such
         as a file, then the underlying resource is closed too if it is owned
         by this stream, or left open otherwise.
     */
         If this stream wraps another stream or some other resource such
         as a file, then the underlying resource is closed too if it is owned
         by this stream, or left open otherwise.
     */

-    bool Close();
+    virtual bool Close();

 
     /**
 
     /**

-        Returns the number of bytes written during the last
-        Write(). It may return 0 even if there is no
-        error on the stream if it is only temporarily impossible to write to it.
+        Returns the number of bytes written during the last Write().
+        It may return 0 even if there is no error on the stream if it is
+        only temporarily impossible to write to it.

     */
     */

-    size_t LastWrite() const;
+    virtual size_t LastWrite() const;

 
     /**
         Puts the specified character in the output queue and increments the
 
     /**
         Puts the specified character in the output queue and increments the


@@ -334,29 +451,49 @@ public:
 
         @return The new stream position or wxInvalidOffset on error.
     */
 
         @return The new stream position or wxInvalidOffset on error.
     */

-    off_t SeekO(off_t pos, wxSeekMode mode = wxFromStart);
+    virtual wxFileOffset SeekO(wxFileOffset pos, wxSeekMode mode = wxFromStart);

 
     /**
         Returns the current stream position.
     */
 
     /**
         Returns the current stream position.
     */

-    off_t TellO() const;
+    virtual wxFileOffset TellO() const;
+
+    /**
+        Writes up to the specified amount of bytes using the data of buffer.
+        Note that not all data can always be written so you must check the number
+        of bytes really written to the stream using LastWrite() when this function
+        returns.
+
+        In some cases (for example a write end of a pipe which is currently full)
+        it is even possible that there is no errors and zero bytes have been written.
+        This function returns a reference on the current object, so the user can
+        test any states of the stream right away.
+    */
+    virtual wxOutputStream& Write(const void* buffer, size_t size);

 
 

-    //@{

     /**
         Reads data from the specified input stream and stores them
         in the current stream. The data is read until an error is raised
         by one of the two streams.
     */
     /**
         Reads data from the specified input stream and stores them
         in the current stream. The data is read until an error is raised
         by one of the two streams.
     */

-    wxOutputStream Write(const void* buffer, size_t size);
-    wxOutputStream Write(wxInputStream& stream_in);
-    //@}
+    wxOutputStream& Write(wxInputStream& stream_in);

 };
 
 
 };
 
 

+/**
+    Enumeration values used by wxFilterClassFactory.
+*/
+enum wxStreamProtocolType
+{
+    wxSTREAM_PROTOCOL,  //!< wxFileSystem protocol (should be only one).
+    wxSTREAM_MIMETYPE,  //!< MIME types the stream handles.
+    wxSTREAM_ENCODING,  //!< The HTTP Content-Encodings the stream handles.
+    wxSTREAM_FILEEXT    //!< File extensions the stream handles.
+};
+

 
 /**
     @class wxFilterClassFactory
 
 /**
     @class wxFilterClassFactory

-    @wxheader{stream.h}

 
     Allows the creation of filter streams to handle compression formats such
     as gzip and bzip2.
 
     Allows the creation of filter streams to handle compression formats such
     as gzip and bzip2.


@@ -365,21 +502,21 @@ public:
     handle it and create a stream to decompress it:
 
     @code
     handle it and create a stream to decompress it:
 
     @code

-    factory = wxFilterClassFactory::Find(filename, wxSTREAM_FILEEXT);
+        factory = wxFilterClassFactory::Find(filename, wxSTREAM_FILEEXT);

         if (factory)
         if (factory)

-            stream = factory-NewStream(new wxFFileInputStream(filename));
+            stream = factory->NewStream(new wxFFileInputStream(filename));

     @endcode
 
     @endcode
 

-    wxFilterClassFactory::Find can also search
-    for a factory by MIME type, HTTP encoding or by wxFileSystem protocol.
-    The available factories can be enumerated
-    using @ref wxFilterClassFactory::getfirst "GetFirst() and GetNext".
+    wxFilterClassFactory::Find can also search for a factory by MIME type,
+    HTTP encoding or by wxFileSystem protocol.
+    The available factories can be enumerated using wxFilterClassFactory::GetFirst()
+    and wxFilterClassFactory::GetNext().

 
     @library{wxbase}
 
     @library{wxbase}

-    @category{FIXME}
+    @category{streams}

 
 

-    @see wxFilterInputStream, wxFilterOutputStream, wxArchiveClassFactory, @ref
-    overview_wxarc "Archive formats such as zip"
+    @see wxFilterInputStream, wxFilterOutputStream, wxArchiveClassFactory,
+        @ref overview_archive

 */
 class wxFilterClassFactory : public wxObject
 {
 */
 class wxFilterClassFactory : public wxObject
 {


@@ -387,7 +524,8 @@ public:
     /**
         Returns @true if this factory can handle the given protocol, MIME type, HTTP
         encoding or file extension.
     /**
         Returns @true if this factory can handle the given protocol, MIME type, HTTP
         encoding or file extension.

-        When using wxSTREAM_FILEEXT for the second parameter, the first parameter
+
+        When using @c wxSTREAM_FILEEXT for the second parameter, the first parameter

         can be a complete filename rather than just an extension.
     */
     bool CanHandle(const wxString& protocol,
         can be a complete filename rather than just an extension.
     */
     bool CanHandle(const wxString& protocol,


@@ -395,10 +533,11 @@ public:
 
     /**
         A static member that finds a factory that can handle a given protocol, MIME
 
     /**
         A static member that finds a factory that can handle a given protocol, MIME

-        type, HTTP encoding or file extension.  Returns a pointer to the class
-        factory if found, or @NULL otherwise. It does not give away ownership of the
-        factory.
-        When using wxSTREAM_FILEEXT for the second parameter, the first parameter
+        type, HTTP encoding or file extension. Returns a pointer to the class
+        factory if found, or @NULL otherwise.
+        It does not give away ownership of the factory.
+
+        When using @c wxSTREAM_FILEEXT for the second parameter, the first parameter

         can be a complete filename rather than just an extension.
     */
     static const wxFilterClassFactory* Find(const wxString& protocol,
         can be a complete filename rather than just an extension.
     */
     static const wxFilterClassFactory* Find(const wxString& protocol,


@@ -409,37 +548,57 @@ public:
         GetFirst and GetNext can be used to enumerate the available factories.
         For example, to list them:
 
         GetFirst and GetNext can be used to enumerate the available factories.
         For example, to list them:
 

+        @code
+        wxString list;
+        const wxFilterClassFactory *factory = wxFilterClassFactory::GetFirst();
+
+        while (factory) {
+            list << factory->GetProtocol() << _T("\n");
+            factory = factory->GetNext();
+        }
+        @endcode
+

         GetFirst()/GetNext() return a pointer to a factory or @NULL if no more
         are available. They do not give away ownership of the factory.
     */
         GetFirst()/GetNext() return a pointer to a factory or @NULL if no more
         are available. They do not give away ownership of the factory.
     */

-    static const wxFilterClassFactory* GetFirst() const;
+    static const wxFilterClassFactory* GetFirst();

     const wxFilterClassFactory* GetNext() const;
     //@}
 
     /**
     const wxFilterClassFactory* GetNext() const;
     //@}
 
     /**

-        Returns the wxFileSystem protocol supported by this factory. Equivalent
-        to wxString(*GetProtcols()).
+        Returns the wxFileSystem protocol supported by this factory.
+        Equivalent to @code wxString(*GetProtocols()) @endcode.

     */
     wxString GetProtocol() const;
 
     /**
         Returns the protocols, MIME types, HTTP encodings or file extensions
     */
     wxString GetProtocol() const;
 
     /**
         Returns the protocols, MIME types, HTTP encodings or file extensions

-        supported by this factory, as an array of null terminated strings. It does
-        not give away ownership of the array or strings.
+        supported by this factory, as an array of null terminated strings.
+        It does not give away ownership of the array or strings.
+

         For example, to list the file extensions a factory supports:
         For example, to list the file extensions a factory supports:

+
+        @code
+        wxString list;
+        const wxChar *const *p;
+
+        for (p = factory->GetProtocols(wxSTREAM_FILEEXT); *p; p++)
+            list << *p << _T("\n");
+        @endcode

     */
     */

-    const wxChar* const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL) const;
+    virtual const wxChar * const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL) const = 0;

 
     //@{
     /**
         Create a new input or output stream to decompress or compress a given stream.
 
     //@{
     /**
         Create a new input or output stream to decompress or compress a given stream.

+

         If the parent stream is passed as a pointer then the new filter stream
         takes ownership of it. If it is passed by reference then it does not.
     */
         If the parent stream is passed as a pointer then the new filter stream
         takes ownership of it. If it is passed by reference then it does not.
     */

-    wxFilterInputStream* NewStream(wxInputStream& stream) const;
-    const wxFilterOutputStream*  NewStream(wxOutputStream& stream) const;
-    const wxFilterInputStream*  NewStream(wxInputStream* stream) const;
-    const wxFilterOutputStream*  NewStream(wxOutputStream* stream) const;
+    virtual wxFilterInputStream*  NewStream(wxInputStream& stream) const = 0;
+    virtual wxFilterOutputStream* NewStream(wxOutputStream& stream) const = 0;
+    virtual wxFilterInputStream*  NewStream(wxInputStream* stream) const = 0;
+    virtual wxFilterOutputStream* NewStream(wxOutputStream* stream) const = 0;

     //@}
 
     /**
     //@}
 
     /**


@@ -449,23 +608,25 @@ public:
     wxString PopExtension(const wxString& location) const;
 
     /**
     wxString PopExtension(const wxString& location) const;
 
     /**

-        Adds this class factory to the list returned
-        by @ref getfirst() GetFirst()/GetNext.
+        Adds this class factory to the list returned  by GetFirst()/GetNext().
+

         It is not necessary to do this to use the filter streams. It is usually
         used when implementing streams, typically the implementation will
         add a static instance of its factory class.
         It is not necessary to do this to use the filter streams. It is usually
         used when implementing streams, typically the implementation will
         add a static instance of its factory class.

+

         It can also be used to change the order of a factory already in the list,
         It can also be used to change the order of a factory already in the list,

-        bringing it to the front. This isn't a thread safe operation
-        so can't be done when other threads are running that will be using the list.
+        bringing it to the front. This isn't a thread safe operation so can't be
+        done when other threads are running that will be using the list.
+

         The list does not take ownership of the factory.
     */
     void PushFront();
 
     /**
         The list does not take ownership of the factory.
     */
     void PushFront();
 
     /**

-        Removes this class factory from the list returned
-        by @ref getfirst() GetFirst()/GetNext.
-        Removing from the list isn't a thread safe operation
-        so can't be done when other threads are running that will be using the list.
+        Removes this class factory from the list returned by GetFirst()/GetNext().
+        Removing from the list isn't a thread safe operation so can't be done
+        when other threads are running that will be using the list.
+

         The list does not own the factories, so removing a factory does not delete it.
     */
     void Remove();
         The list does not own the factories, so removing a factory does not delete it.
     */
     void Remove();


@@ -475,12 +636,14 @@ public:
 
 /**
     @class wxFilterOutputStream
 
 /**
     @class wxFilterOutputStream

-    @wxheader{stream.h}

 
 

-    A filter stream has the capability of a normal
-    stream but it can be placed on top of another stream. So, for example, it
-    can compress, encrypt the data which are passed to it and write them to another
-    stream.
+    A filter stream has the capability of a normal stream but it can be placed
+    on top of another stream. So, for example, it can compress, encrypt the data
+    which are passed to it and write them to another stream.
+
+    @note
+    The use of this class is exactly the same as of wxOutputStream.
+    Only a constructor differs and it is documented below.

 
     @library{wxbase}
     @category{streams}
 
     @library{wxbase}
     @category{streams}


@@ -493,6 +656,7 @@ public:
     //@{
     /**
         Initializes a "filter" stream.
     //@{
     /**
         Initializes a "filter" stream.

+

         If the parent stream is passed as a pointer then the new filter stream
         takes ownership of it. If it is passed by reference then it does not.
     */
         If the parent stream is passed as a pointer then the new filter stream
         takes ownership of it. If it is passed by reference then it does not.
     */


@@ -505,13 +669,14 @@ public:
 
 /**
     @class wxFilterInputStream
 
 /**
     @class wxFilterInputStream

-    @wxheader{stream.h}

 
     A filter stream has the capability of a normal stream but it can be placed on
 
     A filter stream has the capability of a normal stream but it can be placed on

-    top
-    of another stream. So, for example, it can uncompress or decrypt the data which
-    are read
-    from another stream and pass it to the requester.
+    top of another stream. So, for example, it can uncompress or decrypt the data which
+    are read from another stream and pass it to the requester.
+
+    @note
+    The interface of this class is the same as that of wxInputStream.
+    Only a constructor differs and it is documented below.

 
     @library{wxbase}
     @category{streams}
 
     @library{wxbase}
     @category{streams}


@@ -524,6 +689,7 @@ public:
     //@{
     /**
         Initializes a "filter" stream.
     //@{
     /**
         Initializes a "filter" stream.

+

         If the parent stream is passed as a pointer then the new filter stream
         takes ownership of it. If it is passed by reference then it does not.
     */
         If the parent stream is passed as a pointer then the new filter stream
         takes ownership of it. If it is passed by reference then it does not.
     */


@@ -536,12 +702,10 @@ public:
 
 /**
     @class wxBufferedOutputStream
 
 /**
     @class wxBufferedOutputStream

-    @wxheader{stream.h}

 
     This stream acts as a cache. It caches the bytes to be written to the specified
 
     This stream acts as a cache. It caches the bytes to be written to the specified

-    output stream (See wxFilterOutputStream). The
-    data is only written when the cache is full, when the buffered stream is
-    destroyed or when calling SeekO().
+    output stream (See wxFilterOutputStream). The data is only written when the
+    cache is full, when the buffered stream is destroyed or when calling SeekO().

 
     This class may not be used without some other stream to write the data
     to (such as a file stream or a memory stream).
 
     This class may not be used without some other stream to write the data
     to (such as a file stream or a memory stream).


@@ -555,33 +719,54 @@ class wxBufferedOutputStream : public wxFilterOutputStream
 {
 public:
     /**
 {
 public:
     /**

-        Creates a buffered stream using a buffer of a default size of 1024 bytes for
-        cashing
-        the stream @e parent.
+        Constructor using the provided buffer or default.
+
+        @param stream
+            The associated low-level stream.
+        @param buffer
+            The buffer to use if non-@NULL. Notice that the ownership of this
+            buffer is taken by the stream, i.e. it will delete it. If this
+            parameter is @NULL a default 1KB buffer is used.

     */
     */

-    wxBufferedOutputStream(const wxOutputStream& parent);
+    wxBufferedOutputStream(wxOutputStream& stream,
+                           wxStreamBuffer *buffer = NULL);
+
+    /**
+        Constructor allowing to specify the size of the buffer.
+
+        This is just a more convenient alternative to creating a wxStreamBuffer
+        of the given size and using the other overloaded constructor of this
+        class.
+
+        @param stream
+            The associated low-level stream.
+        @param bufsize
+            The size of the buffer, in bytes.
+
+        @since 2.9.0
+     */
+    wxBufferedOutputStream(wxOutputStream& stream, size_t bufsize);

 
     /**
         Destructor. Calls Sync() and destroys the internal buffer.
     */
 
     /**
         Destructor. Calls Sync() and destroys the internal buffer.
     */

-    ~wxBufferedOutputStream();
+    virtual ~wxBufferedOutputStream();

 
     /**
         Calls Sync() and changes the stream position.
     */
 
     /**
         Calls Sync() and changes the stream position.
     */

-    off_t SeekO(off_t pos, wxSeekMode mode);
+    virtual wxFileOffset SeekO(wxFileOffset pos, wxSeekMode mode = wxFromStart);

 
     /**
         Flushes the buffer and calls Sync() on the parent stream.
     */
 
     /**
         Flushes the buffer and calls Sync() on the parent stream.
     */

-    void Sync();
+    virtual void Sync();

 };
 
 
 
 /**
     @class wxInputStream
 };
 
 
 
 /**
     @class wxInputStream

-    @wxheader{stream.h}

 
     wxInputStream is an abstract base class which may not be used directly.
 
 
     wxInputStream is an abstract base class which may not be used directly.
 


@@ -599,50 +784,57 @@ public:
     /**
         Destructor.
     */
     /**
         Destructor.
     */

-    ~wxInputStream();
+    virtual ~wxInputStream();

 
     /**
         Returns @true if some data is available in the stream right now, so that
         calling Read() wouldn't block.
     */
 
     /**
         Returns @true if some data is available in the stream right now, so that
         calling Read() wouldn't block.
     */

-    bool CanRead() const;
+    virtual bool CanRead() const;

 
     /**
         Returns @true after an attempt has been made to read past the end of the
         stream.
     */
 
     /**
         Returns @true after an attempt has been made to read past the end of the
         stream.
     */

-    bool Eof() const;
+    virtual bool Eof() const;

 
     /**
         Returns the first character in the input queue and removes it,
         blocking until it appears if necessary.
 
     /**
         Returns the first character in the input queue and removes it,
         blocking until it appears if necessary.

+
+        On success returns a value between 0 - 255; on end of file returns @c wxEOF.

     */
     */

-    char GetC();
+    int GetC();

 
     /**
         Returns the last number of bytes read.
     */
 
     /**
         Returns the last number of bytes read.
     */

-    size_t LastRead() const;
+    virtual size_t LastRead() const;

 
     /**
         Returns the first character in the input queue without removing it.
     */
 
     /**
         Returns the first character in the input queue without removing it.
     */

-    char Peek();
+    virtual char Peek();
+
+    /**
+        Reads the specified amount of bytes and stores the data in buffer.
+
+        @warning
+        The buffer absolutely needs to have at least the specified size.
+
+        @return This function returns a reference on the current object, so the
+                user can test any states of the stream right away.
+    */
+    virtual wxInputStream& Read(void* buffer, size_t size);

 
 

-    //@{

     /**
         Reads data from the input queue and stores it in the specified output stream.
         The data is read until an error is raised by one of the two streams.
 
         @return This function returns a reference on the current object, so the
     /**
         Reads data from the input queue and stores it in the specified output stream.
         The data is read until an error is raised by one of the two streams.
 
         @return This function returns a reference on the current object, so the

-                 user can test any states of the stream right away.
+                user can test any states of the stream right away.

     */
     */

-    wxInputStream Read(void* buffer, size_t size);
-    Warning Return value
-    This function returns a reference on the current object, so the user can test
-    any states of the stream right away.
-    wxInputStream&  Read(wxOutputStream& stream_out);
-    //@}
+    wxInputStream& Read(wxOutputStream& stream_out);

 
     /**
         Changes the stream current position.
 
     /**
         Changes the stream current position.


@@ -654,32 +846,56 @@ public:
 
         @return The new stream position or wxInvalidOffset on error.
     */
 
         @return The new stream position or wxInvalidOffset on error.
     */

-    off_t SeekI(off_t pos, wxSeekMode mode = wxFromStart);
+    virtual wxFileOffset SeekI(wxFileOffset pos, wxSeekMode mode = wxFromStart);

 
     /**
         Returns the current stream position.
     */
 
     /**
         Returns the current stream position.
     */

-    off_t TellI() const;
+    virtual wxFileOffset TellI() const;
+
+    /**
+        This function is only useful in read mode.
+        It is the manager of the "Write-Back" buffer. This buffer acts like a
+        temporary buffer where data which has to be read during the next read IO
+        call are put. This is useful when you get a big block of data which you
+        didn't want to read: you can replace them at the top of the input queue
+        by this way.
+
+        Be very careful about this call in connection with calling SeekI() on
+        the same stream. Any call to SeekI() will invalidate any previous call
+        to this method (otherwise you could SeekI() to one position, "unread" a
+        few bytes there, SeekI() to another position and data would be either
+        lost or corrupted).
+
+        @return Returns the amount of bytes saved in the Write-Back buffer.
+    */
+    size_t Ungetch(const void* buffer, size_t size);

 
 

-    //@{

     /**
         This function acts like the previous one except that it takes only one
         character: it is sometimes shorter to use than the generic function.
     */
     /**
         This function acts like the previous one except that it takes only one
         character: it is sometimes shorter to use than the generic function.
     */

-    size_t Ungetch(const char* buffer, size_t size);
-    Return value bool Ungetch(char c);
-    //@}
+    bool Ungetch(char c);

 };
 
 
 };
 
 

+/**
+    These enumeration values are returned by various functions in the context
+    of wxStream classes.
+*/
+enum wxStreamError
+{
+    wxSTREAM_NO_ERROR = 0,      //!< No error occurred.
+    wxSTREAM_EOF,               //!< EOF reached in Read() or similar.
+    wxSTREAM_WRITE_ERROR,       //!< generic write error on the last write call.
+    wxSTREAM_READ_ERROR         //!< generic read error on the last read call.
+};

 
 /**
     @class wxStreamBase
 
 /**
     @class wxStreamBase

-    @wxheader{stream.h}

 
 

-    This class is the base class of most stream related classes in wxWidgets. It
-    must
-    not be used directly.
+    This class is the base class of most stream related classes in wxWidgets.
+    It must not be used directly.

 
     @library{wxbase}
     @category{streams}
 
     @library{wxbase}
     @category{streams}


@@ -697,44 +913,32 @@ public:
     /**
         Destructor.
     */
     /**
         Destructor.
     */

-    ~wxStreamBase();
+    virtual ~wxStreamBase();

 
     /**
         This function returns the last error.
 
     /**
         This function returns the last error.

-
-        @b wxSTREAM_NO_ERROR
-
-        No error occurred.
-
-        @b wxSTREAM_EOF
-
-        An End-Of-File occurred.
-
-        @b wxSTREAM_WRITE_ERROR
-
-        A generic error occurred on the last write call.
-
-        @b wxSTREAM_READ_ERROR
-
-        A generic error occurred on the last read call.

     */
     wxStreamError GetLastError() const;
 
     /**
     */
     wxStreamError GetLastError() const;
 
     /**

-        Returns the length of the stream in bytes. If the length cannot be determined
-        (this is always the case for socket streams for example), returns
-        @c wxInvalidOffset.
+        Returns the length of the stream in bytes. If the length cannot be
+        determined (this is always the case for socket streams for example),
+        returns @c wxInvalidOffset.

 
         @since 2.5.4
     */
 
         @since 2.5.4
     */

-    wxFileOffset GetLength() const;
+    virtual wxFileOffset GetLength() const;

 
     /**
 
     /**

-        GetLength()
-        This function returns the size of the stream. For example, for a file it is the
-        size of the file.
+        This function returns the size of the stream.
+        For example, for a file it is the size of the file.
+
+        @warning
+        There are streams which do not have size by definition, such as socket
+        streams. In that cases, GetSize returns 0 so you should always test its
+        return value.

     */
     */

-    size_t GetSize() const;
+    virtual size_t GetSize() const;

 
     /**
         Returns @true if no error occurred on the stream.
 
     /**
         Returns @true if no error occurred on the stream.


@@ -746,7 +950,7 @@ public:
     /**
         Returns @true if the streams supports seeking to arbitrary offsets.
     */
     /**
         Returns @true if the streams supports seeking to arbitrary offsets.
     */

-    bool IsSeekable() const;
+    virtual bool IsSeekable() const;

 
     /**
         Internal function. It is called when the stream wants to read data of the
 
     /**
         Internal function. It is called when the stream wants to read data of the


@@ -755,20 +959,23 @@ public:
     size_t OnSysRead(void* buffer, size_t bufsize);
 
     /**
     size_t OnSysRead(void* buffer, size_t bufsize);
 
     /**

-        Internal function. It is called when the stream needs to change the
-        current position.
+        See OnSysRead().

     */
     */

-    off_t OnSysSeek(off_t pos, wxSeekMode mode);
+    size_t OnSysWrite(const void* buffer, size_t bufsize);
+
+
+protected:

 
     /**
 
     /**

-        Internal function. Is is called when the stream needs to know the
-        real position.
+        Internal function.
+        It is called when the stream needs to change the current position.

     */
     */

-    off_t OnSysTell() const;
+    virtual wxFileOffset OnSysSeek(wxFileOffset pos, wxSeekMode mode);

 
     /**
 
     /**

-        See OnSysRead().
+        Internal function.
+        It is called when the stream needs to know the real position.

     */
     */

-    size_t OnSysWrite(const void* buffer, size_t bufsize);
+    virtual wxFileOffset OnSysTell() const;

 };
 
 };