avoid infinite recursion for richtooltops, (hopefully) fixes #15070

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

diff --git a/interface/wx/stream.h b/interface/wx/stream.h
index 88d260410367dd021534edc6b44338db1cf44aad..6fd27a412607116e8657c04d7c8e1de30eff55aa 100644 (file)
--- a/interface/wx/stream.h
+++ b/interface/wx/stream.h
@@ -3,112 +3,160 @@
 // 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.

 
 

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

 
 

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

 
 

-    @library{wxbase}
-    @category{streams}
+        @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;

 
 

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

     /**
     /**

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

 
 

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

     */
     */

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

 
     /**
 
     /**

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

 
 

-        This is just a more convenient alternative to creating a wxStreamBuffer
-        of the given size and using the other overloaded constructor of this
-        class.
+    /**
+        Resets the stream state.

 
 

-        @param stream
-            The associated low-level stream.
-        @param bufsize
-            The size of the buffer, in bytes.
+        By default, resets the stream to good state, i.e. clears any errors.
+        Since wxWidgets 2.9.3 can be also used to explicitly set the state to
+        the specified error (the @a error argument didn't exist in the previous
+        versions).

 
 

-        @since 2.9.0
+        @see GetLastError()

      */
      */

-    wxBufferedInputStream(wxInputStream& stream, size_t bufsize);
+    void Reset(wxStreamError error = wxSTREAM_NO_ERROR);

 
     /**
 
     /**

-        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
 {
 public:
 */
 class wxStreamBuffer
 {
 public:

+    /** BufMode flags */
+    enum BufMode
+    {
+        read,
+        write,
+        read_write
+    };

 
     /**
         Constructor, creates a new stream buffer using @a stream as a parent stream
 
     /**
         Constructor, creates a new stream buffer using @a stream as a parent stream


@@ -127,7 +175,9 @@ 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()
         @endcode
 
         @see SetBufferIO()


@@ -141,8 +191,13 @@ public:
         and calling SetBufferIO() but is more convenient.
 
         @since 2.9.0
         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(wxInputStream& stream, size_t bufsize);
+    wxStreamBuffer(size_t bufsize, wxInputStream& stream);

 
     /**
         Constructor for an output buffer of the specified size.
 
     /**
         Constructor for an output buffer of the specified size.


@@ -151,8 +206,13 @@ public:
         and calling SetBufferIO() but is more convenient.
 
         @since 2.9.0
         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(wxOutputStream& stream, size_t bufsize);
+    wxStreamBuffer(size_t bufsize, wxOutputStream& stream);

 
     /**
         Constructor; creates a new empty stream buffer which won't flush any data
 
     /**
         Constructor; creates a new empty stream buffer which won't flush any data


@@ -188,7 +248,7 @@ public:
         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();

 
     /**
         Fill the IO buffer.
 
     /**
         Fill the IO buffer.


@@ -290,7 +350,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.


@@ -307,7 +367,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);
 


@@ -326,7 +386,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


@@ -364,7 +424,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;
 


@@ -394,6 +454,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}


@@ -443,7 +508,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);
 


@@ -463,253 +528,221 @@ 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 successful 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.

 
 

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

 
 

-/**
-    @class wxFilterOutputStream
+        @param pos
+            Offset to seek to.
+        @param mode
+            One of wxFromStart, wxFromEnd, wxFromCurrent.

 
 

-    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.
+        @return The new stream position or ::wxInvalidOffset on error.
+    */
+    virtual wxFileOffset SeekI(wxFileOffset pos, wxSeekMode mode = wxFromStart);

 
 

-    @note
-    The use of this class is exactly the same as of wxOutputStream.
-    Only a constructor differs and it is documented below.
+    /**
+        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;

 
 

-    @library{wxbase}
-    @category{streams}
+    /**
+        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);

 
 

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

     /**
     /**

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

 
 

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

     */
     */

-    wxFilterOutputStream(wxOutputStream& stream);
-    wxFilterOutputStream(wxOutputStream* stream);
-    //@}
+    size_t OnSysRead(void* buffer, size_t bufsize) = 0;

 };
 
 
 
 };
 
 
 

-/**
-    @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:
     /**


@@ -722,8 +755,8 @@ public:
             buffer is taken by the stream, i.e. it will delete it. If this
             parameter is @NULL a default 1KB buffer is used.
     */
             buffer is taken by the stream, i.e. it will delete it. If this
             parameter is @NULL a default 1KB buffer is used.
     */

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

 
     /**
         Constructor allowing to specify the size of the buffer.
 
     /**
         Constructor allowing to specify the size of the buffer.


@@ -739,235 +772,351 @@ public:
 
         @since 2.9.0
      */
 
         @since 2.9.0
      */

-    wxBufferedOutputStream(wxOutputStream& stream, size_t bufsize);
+    wxBufferedInputStream(wxInputStream& stream, size_t bufsize);

 
     /**
 
     /**

-        Destructor. Calls Sync() and destroys the internal buffer.
+        Destructor.

     */
     */

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

 
 

-    /**
-        Calls Sync() and changes the stream position.
-    */
-    virtual wxFileOffset SeekO(wxFileOffset pos, wxSeekMode mode = wxFromStart);

 
 

-    /**
-        Flushes the buffer and calls Sync() on the parent stream.
-    */
-    virtual void Sync();
-};

 
 
 
 

+/**
+    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 wxInputStream
+    @class wxFilterClassFactory

 
 

-    wxInputStream is an abstract base class which may not be used directly.
+    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.
-    */
-    int 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 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().

 
 

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

     /**
     /**

-        This function returns the size of the stream.
-        For example, for a file it is the size of the file.
+        Constructor using the provided buffer or default.

 
 

-        @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.
+        @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 size_t GetSize() const;
+    wxBufferedOutputStream(wxOutputStream& stream,
+                           wxStreamBuffer *buffer = NULL);

 
     /**
 
     /**

-        Returns @true if no error occurred on the stream.
+        Constructor allowing to specify the size of the buffer.

 
 

-        @see GetLastError()
-    */
-    virtual bool IsOk() const;
+        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);

 
     /**
 
     /**

-        Returns @true if the streams supports seeking to arbitrary offsets.
+        Destructor. Calls Sync() and destroys the internal buffer.

     */
     */

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

 
     /**
 
     /**

-        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.
+        Calls Sync() and changes the stream position.

     */
     */

-    size_t OnSysRead(void* buffer, size_t bufsize);
+    virtual wxFileOffset SeekO(wxFileOffset pos, wxSeekMode mode = wxFromStart);

 
     /**
 
     /**

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

     */
     */

-    size_t OnSysWrite(const void* buffer, size_t bufsize);
+    virtual void Sync();
+};

 
 
 
 

-protected:
+/**
+    @class wxWrapperInputStream
+
+    A wrapper input stream is a kind of filter stream which forwards all the
+    operations to its base stream. This is useful to build utility classes such
+    as wxFSInputStream.
+
+    @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}

 
 

+    @see wxFSInputStream, wxFilterInputStream
+    @since 2.9.4
+*/
+class wxWrapperInputStream : public wxFilterInputStream
+{
+public:
+    //@{

     /**
     /**

-        Internal function.
-        It is called when the stream needs to change the current position.
+        Initializes a wrapper stream.
+
+        If the parent stream is passed as a pointer then the new wrapper stream
+        takes ownership of it. If it is passed by reference then it does not.

     */
     */

-    virtual wxFileOffset OnSysSeek(wxFileOffset pos, wxSeekMode mode);
+    wxWrapperInputStream(wxInputStream& stream);
+    wxWrapperInputStream(wxInputStream* stream);
+    //@}

 
 

+protected:

     /**
     /**

-        Internal function.
-        It is called when the stream needs to know the real position.
-    */
-    virtual wxFileOffset OnSysTell() const;
-};
+        Default constructor, use InitParentStream() to finish initialization.
+
+        This constructor can be used by the derived classes from their own
+        constructors when the parent stream can't be specified immediately.
+        The derived class must call InitParentStream() later to do it.
+     */
+    wxWrapperInputStream();
+
+    //@{
+    /**
+        Set up the wrapped stream for an object initialized using the default
+        constructor.

 
 

+        The ownership logic is the same as for the non-default constructor,
+        i.e. this object takes ownership of the stream if it's passed by
+        pointer but not if it's passed by reference.
+     */
+    void InitParentStream(wxInputStream& stream);
+    void InitParentStream(wxInputStream* stream);
+    //@}
+};