Added wxPGProperty::Enable() for conveniency. Refactored related code and improved...

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

diff --git a/interface/wx/stream.h b/interface/wx/stream.h
index 828fad13746ffbe18f15e0bc474a81f8873add48..7ab40df6608cca70441fbb29be5e92853ae1e013 100644 (file)
--- a/interface/wx/stream.h
+++ b/interface/wx/stream.h
@@ -3,86 +3,137 @@
 // Purpose:     interface of wxStreamBase and its derived classes
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxStreamBase and its derived classes
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /////////////////////////////////////////////////////////////////////////////
 

+

 /**
 /**

-    @class wxCountingOutputStream
+    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.
+};

 
 

-    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).
+/**
+    @class wxStreamBase
+
+    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}

+
+    @see wxStreamBuffer

 */
 */

-class wxCountingOutputStream : public wxOutputStream
+class wxStreamBase

 {
 public:
     /**
 {
 public:
     /**

-        Creates a wxCountingOutputStream object.
+        Creates a dummy stream object. It doesn't do anything.

     */
     */

-    wxCountingOutputStream();
+    wxStreamBase();

 
     /**
         Destructor.
     */
 
     /**
         Destructor.
     */

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

 
     /**
 
     /**

-        Returns the current size of the stream.
+        This function returns the last error.

     */
     */

-    size_t GetSize() 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 ::wxInvalidOffset.

 
 

+        @since 2.5.4
+    */
+    virtual wxFileOffset GetLength() const;

 
 

-/**
-    @class wxBufferedInputStream
+    /**
+        This function returns the size of the stream.
+        For example, for a file it is the size of the file.

 
 

-    This stream acts as a cache. It caches the bytes read from the specified
-    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).
+        @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.
+    */
+    virtual size_t GetSize() const;

 
 

-    @library{wxbase}
-    @category{streams}
+    /**
+        Returns @true if no error occurred on the stream.
+
+        @see GetLastError()
+    */
+    virtual bool IsOk() const;

 
 

-    @see wxStreamBuffer, wxInputStream, wxBufferedOutputStream
-*/
-class wxBufferedInputStream : public wxFilterInputStream
-{
-public:

     /**
     /**

-        Constructor.
-        If a non @NULL buffer is given to the stream, it will be deleted by it.
+        Returns @true if the stream supports seeking to arbitrary offsets.

     */
     */

-    wxBufferedInputStream(wxInputStream& stream,
-                          wxStreamBuffer *buffer = NULL);
+    virtual bool IsSeekable() const;

 
     /**
 
     /**

-        Destructor.
+        Returns the opposite of IsOk().
+        You can use this function to test the validity of the stream as if
+        it was a pointer:
+
+        @code
+            bool DoSomething(wxInputStream& stream)
+            {
+                wxInt32 data;
+                if (!stream.Read(&data, 4))
+                    return false;
+                ...
+            }
+        @endcode

     */
     */

-    virtual ~wxBufferedInputStream();
-};
+    bool operator!() const;
+
+protected:
+
+    /**
+        Internal function.
+        It is called when the stream needs to change the current position.
+
+        @param pos
+            Offset to seek to.
+        @param mode
+            One of the ::wxSeekMode enumeration values.
+
+        @return The new stream position or ::wxInvalidOffset on error.
+    */
+    virtual wxFileOffset OnSysSeek(wxFileOffset pos, wxSeekMode mode);

 
 

+    /**
+        Internal function.
+        It is called when the stream needs to know the real position.

 
 

+        @return The current stream position.
+    */
+    virtual wxFileOffset OnSysTell() const;
+};

 
 /**
     @class wxStreamBuffer
 
 
 /**
     @class wxStreamBuffer
 

-    @todo WRITE A DESCRIPTION
+    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
 {
 */
 class wxStreamBuffer
 {


@@ -105,13 +156,45 @@ public:
 
         @code
         streambuffer.Read(...);
 
         @code
         streambuffer.Read(...);

-        streambuffer2.Read(...); // This call erases previous error messages set by 'streambuffer'
+        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);
 
         @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
+
+        @param bufsize
+            The size of buffer in bytes.
+        @param stream
+            The associated input stream, the buffer will be used in read mode.
+     */
+    wxStreamBuffer(size_t bufsize, wxInputStream& stream);
+
+    /**
+        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
+
+        @param bufsize
+            The size of buffer in bytes.
+        @param stream
+            The associated output stream, the buffer will be used in write mode.
+     */
+    wxStreamBuffer(size_t bufsize, wxOutputStream& stream);
+

     /**
         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).
     /**
         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).


@@ -130,7 +213,7 @@ public:
     wxStreamBuffer(BufMode mode);
 
     /**
     wxStreamBuffer(BufMode mode);
 
     /**

-        Constructor.
+        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
 
         This method initializes the stream buffer with the data of the specified
         stream buffer. The new stream buffer has the same attributes, size, position


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

-    wxFileOffset 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.


@@ -248,7 +331,7 @@ public:
 
         @see Write()
     */
 
         @see Write()
     */

-    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.


@@ -265,7 +348,7 @@ public:
 
         @return Upon successful completion, it returns the new offset as
                 measured in bytes from the beginning 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.
+                Otherwise, it returns ::wxInvalidOffset.

     */
     virtual wxFileOffset Seek(wxFileOffset pos, wxSeekMode mode);
 
     */
     virtual wxFileOffset Seek(wxFileOffset pos, wxSeekMode mode);
 


@@ -284,7 +367,7 @@ public:
 
         @see wxStreamBuffer(), Fixed(), Flushable()
     */
 
         @see wxStreamBuffer(), Fixed(), Flushable()
     */

-    void SetBufferIO(char* buffer_start, char* buffer_end);
+    void SetBufferIO(void* start, void* end, bool takeOwnership = false);

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


@@ -311,6 +394,7 @@ public:
 
     /**
         Returns the parent stream of the stream buffer.
 
     /**
         Returns the parent stream of the stream buffer.

+        @deprecated use GetStream() instead

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


@@ -321,7 +405,7 @@ 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.

     */
     virtual wxFileOffset Tell() const;
 
     */
     virtual wxFileOffset Tell() const;
 


@@ -351,6 +435,11 @@ public:
     @class wxOutputStream
 
     wxOutputStream is an abstract base class which may not be used directly.
     @class wxOutputStream
 
     wxOutputStream is an abstract base class which may not be used directly.

+    It is the base class of all streams which provide a Write() function,
+    i.e. which can be used to output data (e.g. to a file, to a socket, etc).
+
+    If you want to create your own output stream, you'll need to derive from this
+    class and implement the protected OnSysWrite() function only.

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


@@ -400,7 +489,7 @@ public:
         @param mode
             One of wxFromStart, wxFromEnd, wxFromCurrent.
 
         @param mode
             One of wxFromStart, wxFromEnd, wxFromCurrent.
 

-        @return The new stream position or wxInvalidOffset on error.
+        @return The new stream position or ::wxInvalidOffset on error.

     */
     virtual wxFileOffset SeekO(wxFileOffset pos, wxSeekMode mode = wxFromStart);
 
     */
     virtual wxFileOffset SeekO(wxFileOffset pos, wxSeekMode mode = wxFromStart);
 


@@ -420,487 +509,541 @@ public:
         This function returns a reference on the current object, so the user can
         test any states of the stream right away.
     */
         This function returns a reference on the current object, so the user can
         test any states of the stream right away.
     */

-    wxOutputStream Write(const void* buffer, size_t size);
+    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(wxInputStream& stream_in);
-};
+    wxOutputStream& Write(wxInputStream& stream_in);

 
 

+protected:
+    /**
+        Internal function. It is called when the stream wants to write data of the
+        specified size @a bufsize into the given @a buffer.

 
 

-/**
-    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.
+        It should return the size that was actually wrote (which maybe zero if
+        @a bufsize is zero or if an error occurred; in this last case the internal
+        variable @c m_lasterror should be appropriately set).
+    */
+    size_t OnSysWrite(const void* buffer, size_t bufsize);

 };
 
 
 /**
 };
 
 
 /**

-    @class wxFilterClassFactory
-
-    Allows the creation of filter streams to handle compression formats such
-    as gzip and bzip2.
-
-    For example, given a filename you can search for a factory that will
-    handle it and create a stream to decompress it:
+    @class wxInputStream

 
 

-    @code
-        factory = wxFilterClassFactory::Find(filename, wxSTREAM_FILEEXT);
-        if (factory)
-            stream = factory-NewStream(new wxFFileInputStream(filename));
-    @endcode
+    wxInputStream is an abstract base class which may not be used directly.
+    It is the base class of all streams which provide a Read() function,
+    i.e. which can be used to read data from a source (e.g. a file, a socket, etc).

 
 

-    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().
+    If you want to create your own input stream, you'll need to derive from this
+    class and implement the protected OnSysRead() function only.

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

-
-    @see wxFilterInputStream, wxFilterOutputStream, wxArchiveClassFactory,
-        @ref overview_archive

 */
 */

-class wxFilterClassFactory : public wxObject
+class wxInputStream : public wxStreamBase

 {
 public:
     /**
 {
 public:
     /**

-        Returns @true if this factory can handle the given protocol, MIME type, HTTP
-        encoding or file extension.
-
-        When using @c wxSTREAM_FILEEXT for the second parameter, the first parameter
-        can be a complete filename rather than just an extension.
+        Creates a dummy input stream.

     */
     */

-    bool CanHandle(const wxString& protocol,
-                   wxStreamProtocolType type = wxSTREAM_PROTOCOL) const;
+    wxInputStream();

 
     /**
 
     /**

-        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 @c wxSTREAM_FILEEXT for the second parameter, the first parameter
-        can be a complete filename rather than just an extension.
+        Destructor.

     */
     */

-    static const wxFilterClassFactory* Find(const wxString& protocol,
-                                            wxStreamProtocolType type = wxSTREAM_PROTOCOL);
+    virtual ~wxInputStream();

 
 

-    //@{

     /**
     /**

-        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.
+        Returns @true if some data is available in the stream right now, so that
+        calling Read() wouldn't block.

     */
     */

-    static const wxFilterClassFactory* GetFirst() const;
-    const wxFilterClassFactory* GetNext() const;
-    //@}
+    virtual bool CanRead() const;

 
     /**
 
     /**

-        Returns the wxFileSystem protocol supported by this factory.
-        Equivalent to @code wxString(*GetProtocols()) @endcode.
+        Returns @true after an attempt has been made to read past the end of the
+        stream.

     */
     */

-    wxString GetProtocol() const;
+    virtual bool Eof() 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.
-
-        For example, to list the file extensions a factory supports:
-
-        @code
-        wxString list;
-        const wxChar *const *p;
+        Returns the first character in the input queue and removes it,
+        blocking until it appears if necessary.

 
 

-        for (p = factory->GetProtocols(wxSTREAM_FILEEXT); *p; p++)
-            list << *p << _T("\n");
-        @endcode
+        On success returns a value between 0 - 255; on end of file returns @c wxEOF.

     */
     */

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

 
 

-    //@{

     /**
     /**

-        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.
+        Returns the last number of bytes read.

     */
     */

-    wxFilterInputStream*  NewStream(wxInputStream& stream) const;
-    wxFilterOutputStream* NewStream(wxOutputStream& stream) const;
-    wxFilterInputStream*  NewStream(wxInputStream* stream) const;
-    wxFilterOutputStream* NewStream(wxOutputStream* stream) const;
-    //@}
+    virtual size_t LastRead() const;

 
     /**
 
     /**

-        Remove the file extension of @a location if it is one of the file
-        extensions handled by this factory.
+        Returns the first character in the input queue without removing it.

     */
     */

-    wxString PopExtension(const wxString& location) const;
+    virtual char Peek();

 
     /**
 
     /**

-        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.
+        Reads the specified amount of bytes and stores the data in buffer.
+        To check if the call was successfull you must use LastRead() to check
+        if this call did actually read @a size bytes (if it didn't, GetLastError()
+        should return a meaningful value).

 
 

-        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.
+        @warning
+        The buffer absolutely needs to have at least the specified size.

 
 

-        The list does not take ownership of the factory.
+        @return This function returns a reference on the current object, so the
+                user can test any states of the stream right away.

     */
     */

-    void PushFront();
+    virtual wxInputStream& Read(void* buffer, size_t size);

 
     /**
 
     /**

-        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.
+        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.

 
 

-        The list does not own the factories, so removing a factory does not delete it.
+        @return This function returns a reference on the current object, so the
+                user can test any states of the stream right away.

     */
     */

-    void Remove();
-};
-
+    wxInputStream& Read(wxOutputStream& stream_out);

 
 

+    /**
+        Changes the stream current position.

 
 

-/**
-    @class wxFilterOutputStream
+        This operation in general is possible only for seekable streams 
+        (see wxStreamBase::IsSeekable()); non-seekable streams support only
+        seeking positive amounts in mode @c wxFromCurrent (this is implemented
+        by reading data and simply discarding it).

 
 

-    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.
+        @param pos
+            Offset to seek to.
+        @param mode
+            One of wxFromStart, wxFromEnd, wxFromCurrent.

 
 

-    @note
-    The use of this class is exactly the same as of wxOutputStream.
-    Only a constructor differs and it is documented below.
+        @return The new stream position or ::wxInvalidOffset on error.
+    */
+    virtual wxFileOffset SeekI(wxFileOffset pos, wxSeekMode mode = wxFromStart);

 
 

-    @library{wxbase}
-    @category{streams}
+    /**
+        Returns the current stream position or ::wxInvalidOffset if it's not
+        available (e.g. socket streams do not have a size nor a current stream
+        position).
+    */
+    virtual wxFileOffset TellI() const;

 
 

-    @see wxFilterClassFactory, wxFilterInputStream
-*/
-class wxFilterOutputStream : public wxOutputStream
-{
-public:
-    //@{

     /**
     /**

-        Initializes a "filter" stream.
+        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.

 
 

-        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.
+        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.

     */
     */

-    wxFilterOutputStream(wxOutputStream& stream);
-    wxFilterOutputStream(wxOutputStream* stream);
-    //@}
+    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.
+    */
+    bool Ungetch(char c);
+
+protected:
+
+    /**
+        Internal function. It is called when the stream wants to read data of the
+        specified size @a bufsize and wants it to be placed inside @a buffer.
+
+        It should return the size that was actually read or zero if EOF has been
+        reached or an error occurred (in this last case the internal @c m_lasterror
+        variable should be set accordingly as well).
+    */
+    size_t OnSysRead(void* buffer, size_t bufsize);

 };
 
 
 
 };
 
 
 

-/**
-    @class wxFilterInputStream

 
 

-    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.
+/**
+    @class wxCountingOutputStream

 
 

-    @note
-    The interface of this class is the same as that of wxInputStream.
-    Only a constructor differs and it is documented below.
+    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).

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

-
-    @see wxFilterClassFactory, wxFilterOutputStream

 */
 */

-class wxFilterInputStream : public wxInputStream
+class wxCountingOutputStream : public wxOutputStream

 {
 public:
 {
 public:

-    //@{

     /**
     /**

-        Initializes a "filter" stream.
+        Creates a wxCountingOutputStream object.
+    */
+    wxCountingOutputStream();

 
 

-        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.
+    /**
+        Destructor.

     */
     */

-    wxFilterInputStream(wxInputStream& stream);
-    wxFilterInputStream(wxInputStream* stream);
-    //@}
-};
+    virtual ~wxCountingOutputStream();

 
 

+    /**
+        Returns the current size of the stream.
+    */
+    size_t GetSize() const;
+};

 
 
 /**
 
 
 /**

-    @class wxBufferedOutputStream
-
-    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().
+    @class wxBufferedInputStream

 
 

-    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 stream acts as a cache. It caches the bytes read from the specified
+    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).

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

-    @see wxStreamBuffer, wxOutputStream
+    @see wxStreamBuffer, wxInputStream, wxBufferedOutputStream

 */
 */

-class wxBufferedOutputStream : public wxFilterOutputStream
+class wxBufferedInputStream : public wxFilterInputStream

 {
 public:
     /**
 {
 public:
     /**

-        @todo WRITE DESCRIPTION
-    */
-    wxBufferedOutputStream(wxOutputStream& stream,
-                           wxStreamBuffer *buffer = NULL);
-    /**
-        Destructor. Calls Sync() and destroys the internal buffer.
+        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.

     */
     */

-    virtual ~wxBufferedOutputStream();
+    wxBufferedInputStream(wxInputStream& stream,
+                          wxStreamBuffer *buffer = NULL);

 
     /**
 
     /**

-        Calls Sync() and changes the stream position.
-    */
-    virtual wxFileOffset SeekO(wxFileOffset pos, wxSeekMode mode = wxFromStart)
+        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);

 
     /**
 
     /**

-        Flushes the buffer and calls Sync() on the parent stream.
+        Destructor.

     */
     */

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

 };
 
 
 
 };
 
 
 

+

 /**
 /**

-    @class wxInputStream
+    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.
+};

 
 

-    wxInputStream is an abstract base class which may not be used directly.
+/**
+    @class wxFilterClassFactory
+
+    Allows the creation of filter streams to handle compression formats such
+    as gzip and bzip2.
+
+    For example, given a filename you can search for a factory that will
+    handle it and create a stream to decompress it:
+
+    @code
+        factory = wxFilterClassFactory::Find(filename, wxSTREAM_FILEEXT);
+        if (factory)
+            stream = factory->NewStream(new wxFFileInputStream(filename));
+    @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 wxFilterClassFactory::GetFirst()
+    and wxFilterClassFactory::GetNext().

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

+
+    @see wxFilterInputStream, wxFilterOutputStream, wxArchiveClassFactory,
+        @ref overview_archive

 */
 */

-class wxInputStream : public wxStreamBase
+class wxFilterClassFactory : public wxObject

 {
 public:
     /**
 {
 public:
     /**

-        Creates a dummy input stream.
-    */
-    wxInputStream();
+        Returns @true if this factory can handle the given protocol, MIME type, HTTP
+        encoding or file extension.

 
 

-    /**
-        Destructor.
+        When using @c wxSTREAM_FILEEXT for the second parameter, the first parameter
+        can be a complete filename rather than just an extension.

     */
     */

-    virtual ~wxInputStream();
+    bool CanHandle(const wxString& protocol,
+                   wxStreamProtocolType type = wxSTREAM_PROTOCOL) const;

 
     /**
 
     /**

-        Returns @true if some data is available in the stream right now, so that
-        calling Read() wouldn't block.
-    */
-    virtual bool CanRead() const;
+        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.

 
 

-    /**
-        Returns @true after an attempt has been made to read past the end of the
-        stream.
+        When using @c wxSTREAM_FILEEXT for the second parameter, the first parameter
+        can be a complete filename rather than just an extension.

     */
     */

-    virtual bool Eof() const;
+    static const wxFilterClassFactory* Find(const wxString& protocol,
+                                            wxStreamProtocolType type = wxSTREAM_PROTOCOL);

 
 

+    //@{

     /**
     /**

-        Returns the first character in the input queue and removes it,
-        blocking until it appears if necessary.
-    */
-    char GetC();
+        GetFirst and GetNext can be used to enumerate the available factories.
+        For example, to list them:

 
 

-    /**
-        Returns the last number of bytes read.
+        @code
+        wxString list;
+        const wxFilterClassFactory *factory = wxFilterClassFactory::GetFirst();
+
+        while (factory) {
+            list << factory->GetProtocol() << wxT("\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.

     */
     */

-    virtual size_t LastRead() const;
+    static const wxFilterClassFactory* GetFirst();
+    const wxFilterClassFactory* GetNext() const;
+    //@}

 
     /**
 
     /**

-        Returns the first character in the input queue without removing it.
+        Returns the wxFileSystem protocol supported by this factory.
+        Equivalent to @code wxString(*GetProtocols()) @endcode.

     */
     */

-    virtual char Peek();
+    wxString GetProtocol() const;

 
     /**
 
     /**

-        Reads the specified amount of bytes and stores the data in buffer.
-
-        @warning
-        The buffer absolutely needs to have at least the specified size.
+        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.

 
 

-        @return This function returns a reference on the current object, so the
-                user can test any states of the stream right away.
-    */
-    wxInputStream Read(void* buffer, size_t size);
+        For example, to list the file extensions a factory supports:

 
 

-    /**
-        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.
+        @code
+        wxString list;
+        const wxChar *const *p;

 
 

-        @return This function returns a reference on the current object, so the
-                user can test any states of the stream right away.
+        for (p = factory->GetProtocols(wxSTREAM_FILEEXT); *p; p++)
+            list << *p << wxT("\n");
+        @endcode

     */
     */

-    wxInputStream& Read(wxOutputStream& stream_out);
+    virtual const wxChar * const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL) const = 0;

 
 

+    //@{

     /**
     /**

-        Changes the stream current position.
-
-        @param pos
-            Offset to seek to.
-        @param mode
-            One of wxFromStart, wxFromEnd, wxFromCurrent.
+        Create a new input or output stream to decompress or compress a given stream.

 
 

-        @return The new stream position or wxInvalidOffset on error.
+        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.

     */
     */

-    virtual wxFileOffset SeekI(wxFileOffset pos, wxSeekMode mode = wxFromStart);
+    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;
+    //@}

 
     /**
 
     /**

-        Returns the current stream position.
+        Remove the file extension of @a location if it is one of the file
+        extensions handled by this factory.

     */
     */

-    virtual wxFileOffset TellI() const;
+    wxString PopExtension(const wxString& location) 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.
+        Adds this class factory to the list returned  by GetFirst()/GetNext().

 
 

-        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).
+        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.

 
 

-        @return Returns the amount of bytes saved in the Write-Back buffer.
+        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.
+
+        The list does not take ownership of the factory.

     */
     */

-    size_t Ungetch(const char* buffer, size_t size);
+    void PushFront();

 
     /**
 
     /**

-        This function acts like the previous one except that it takes only one
-        character: it is sometimes shorter to use than the generic function.
+        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.

     */
     */

-    Return value bool Ungetch(char c);
+    void Remove();

 };
 
 
 };
 
 

+

 /**
 /**

-    These enumeration values are returned by various functions in the context
-    of wxStream classes.
+    @class wxFilterOutputStream
+
+    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}
+
+    @see wxFilterClassFactory, wxFilterInputStream

 */
 */

-enum wxStreamError
+class wxFilterOutputStream : public wxOutputStream

 {
 {

-    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.
+public:
+    //@{
+    /**
+        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.
+    */
+    wxFilterOutputStream(wxOutputStream& stream);
+    wxFilterOutputStream(wxOutputStream* stream);
+    //@}

 };
 
 };
 

+
+

 /**
 /**

-    @class wxStreamBase
+    @class wxFilterInputStream

 
 

-    This class is the base class of most stream related classes in wxWidgets.
-    It must not be used directly.
+    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.
+
+    @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}
 

-    @see wxStreamBuffer
+    @see wxFilterClassFactory, wxFilterOutputStream

 */
 */

-class wxStreamBase
+class wxFilterInputStream : public wxInputStream

 {
 public:
 {
 public:

+    //@{

     /**
     /**

-        Creates a dummy stream object. It doesn't do anything.
-    */
-    wxStreamBase();
+        Initializes a "filter" stream.

 
 

-    /**
-        Destructor.
+        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.

     */
     */

-    virtual ~wxStreamBase();
+    wxFilterInputStream(wxInputStream& stream);
+    wxFilterInputStream(wxInputStream* stream);
+    //@}
+};

 
 

-    /**
-        This function returns the last error.
-    */
-    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.

 
 

-        @since 2.5.4
-    */
-    virtual wxFileOffset GetLength() const;
+/**
+    @class wxBufferedOutputStream

 
 

-    /**
-        This function returns the size of the stream.
-        For example, for a file it is the size of the file.
+    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().

 
 

-        @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.
-    */
-    virtual size_t GetSize() const;
+    This class may not be used without some other stream to write the data
+    to (such as a file stream or a memory stream).
+
+    @library{wxbase}
+    @category{streams}

 
 

+    @see wxStreamBuffer, wxOutputStream
+*/
+class wxBufferedOutputStream : public wxFilterOutputStream
+{
+public:

     /**
     /**

-        Returns @true if no error occurred on the stream.
+        Constructor using the provided buffer or default.

 
 

-        @see GetLastError()
+        @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.

     */
     */

-    virtual bool IsOk() const;
+    wxBufferedOutputStream(wxOutputStream& stream,
+                           wxStreamBuffer *buffer = NULL);

 
     /**
 
     /**

-        Returns @true if the streams supports seeking to arbitrary offsets.
-    */
-    virtual bool IsSeekable() const;
+        Constructor allowing to specify the size of the buffer.

 
 

-    /**
-        Internal function. It is called when the stream wants to read data of the
-        specified size. It should return the size that was actually read.
-    */
-    size_t OnSysRead(void* buffer, size_t bufsize);
+        This is just a more convenient alternative to creating a wxStreamBuffer
+        of the given size and using the other overloaded constructor of this
+        class.

 
 

-    /**
-        See OnSysRead().
-    */
-    size_t OnSysWrite(const void* buffer, size_t bufsize);
+        @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);

 
 

-protected:
+    /**
+        Destructor. Calls Sync() and destroys the internal buffer.
+    */
+    virtual ~wxBufferedOutputStream();

 
     /**
 
     /**

-        Internal function.
-        It is called when the stream needs to change the current position.
+        Calls Sync() and changes the stream position.

     */
     */

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

 
     /**
 
     /**

-        Internal function.
-        It is called when the stream needs to know the real position.
+        Flushes the buffer and calls Sync() on the parent stream.

     */
     */

-    virtual wxFileOffset OnSysTell() const;
+    virtual void Sync();

 };
 
 };
 

+