text: /////////////////////////////////////////////////////////////////////////////
  // Name:        stream.h
  // Purpose:     interface of wxStreamBase and its derived classes
  // Author:      wxWidgets team
  // Licence:     wxWindows licence
  /////////////////////////////////////////////////////////////////////////////
  
  
  /**
      These enumeration values are returned by various functions in the context
      of wxStream classes.
  */
  enum wxStreamError
  {
      wxSTREAM_NO_ERROR = 0,      //!< No error occurred.
      wxSTREAM_EOF,               //!< EOF reached in Read() or similar.
      wxSTREAM_WRITE_ERROR,       //!< generic write error on the last write call.
      wxSTREAM_READ_ERROR         //!< generic read error on the last read call.
  };
  
  /**
      @class wxStreamBase
  
      This class is the base class of most stream related classes in wxWidgets.
      It must not be used directly.
  
      @library{wxbase}
      @category{streams}
  
      @see wxStreamBuffer
  */
  class wxStreamBase
  {
  public:
      /**
          Creates a dummy stream object. It doesn't do anything.
      */
      wxStreamBase();
  
      /**
          Destructor.
      */
      virtual ~wxStreamBase();
  
      /**
          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 ::wxInvalidOffset.
  
          @since 2.5.4
      */
      virtual wxFileOffset GetLength() const;
  
      /**
          This function returns the size of the stream.
          For example, for a file it is the size of the file.
  
          @warning
          There are streams which do not have size by definition, such as socket
          streams. In that cases, GetSize() returns 0 so you should always test its
          return value.
      */
      virtual size_t GetSize() const;
  
      /**
          Returns @true if no error occurred on the stream.
  
          @see GetLastError()
      */
      virtual bool IsOk() const;
  
      /**
          Returns @true if the stream supports seeking to arbitrary offsets.
      */
      virtual bool IsSeekable() const;
  
      /**
          Resets the stream state.
  
          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).
  
          @see GetLastError()
       */
      void Reset(wxStreamError error = wxSTREAM_NO_ERROR);
  
      /**
          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
      */
      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
  
      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}
  
      @see wxStreamBase, @ref overview_stream
  */
  class wxStreamBuffer
  {
  public:
      /** BufMode flags */
      enum BufMode
      {
          read,
          write,
          read_write
      };
  
      /**
          Constructor, creates a new stream buffer using @a stream as a parent stream
          and mode as the IO mode.
  
          @param stream
              The parent stream.
          @param mode
              Can be: wxStreamBuffer::read, wxStreamBuffer::write, wxStreamBuffer::read_write.
  
          One stream can have many stream buffers but only one is used internally
          to pass IO call (e.g. wxInputStream::Read() -> wxStreamBuffer::Read()),
          but you can call directly wxStreamBuffer::Read without any problems.
          Note that all errors and messages linked to the stream are stored in the
          stream, not the stream buffers:
  
          @code
          streambuffer.Read(...);
          streambuffer2.Read(...);
              // This call erases previous error messages set by 'streambuffer'
              // assuming that both instances are stream buffers for the same stream
          @endcode
  
          @see SetBufferIO()
      */
      wxStreamBuffer(wxStreamBase& stream, BufMode mode);
  
      /**
          Constructor for an input buffer of the specified size.
  
          Using it is equivalent to using the constructor above with read mode
          and calling SetBufferIO() but is more convenient.
  
          @since 2.9.0
  
          @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).
  
          This stream buffer has the advantage to be stream independent and to work
          only on memory buffers but it is still compatible with the rest of the
          wxStream classes. You can write, read to this special stream and it will
          grow (if it is allowed by the user) its internal buffer.
          Briefly, it has all functionality of a "normal" stream.
  
          @warning
          The "read_write" mode doesn't currently work for standalone stream buffers.
  
          @see SetBufferIO()
      */
      wxStreamBuffer(BufMode mode);
  
      /**
          Copy constructor.
  
          This method initializes the stream buffer with the data of the specified
          stream buffer. The new stream buffer has the same attributes, size, position
          and they share the same buffer. This will cause problems if the stream to
          which the stream buffer belong is destroyed and the newly cloned stream
          buffer continues to be used, trying to call functions in the (destroyed)
          stream. It is advised to use this feature only in very local area of the
          program.
      */
      wxStreamBuffer(const wxStreamBuffer& buffer);
  
      /**
          Destructor.
          It finalizes all IO calls and frees all internal buffers if necessary.
      */
      ~wxStreamBuffer();
  
      /**
          Fill the IO buffer.
      */
      bool FillBuffer();
  
      /**
          Toggles the fixed flag. Usually this flag is toggled at the same time as
          @e flushable. This flag allows (when it has the @false value) or forbids
          (when it has the @true value) the stream buffer to resize dynamically the
          IO buffer.
  
          @see SetBufferIO()
      */
      void Fixed(bool fixed);
  
      /**
          Flushes the IO buffer.
      */
      bool FlushBuffer();
  
      /**
          Toggles the flushable flag.
          If @a flushable is disabled, no data are sent to the parent stream.
      */
      void Flushable(bool flushable);
  
      /**
          Returns a pointer on the end of the stream buffer.
      */
      void* GetBufferEnd() const;
  
      /**
          Returns a pointer on the current position of the stream buffer.
      */
      void* GetBufferPos() const;
  
      /**
          Returns the size of the buffer.
      */
      size_t GetBufferSize() const;
  
      /**
          Returns a pointer on the start of the stream buffer.
      */
      void* GetBufferStart() const;
  
      /**
          Gets a single char from the stream buffer. It acts like the Read() call.
  
          @warning
          You aren't directly notified if an error occurred during the IO call.
  
          @see Read()
      */
      virtual char GetChar();
  
      /**
          Returns the amount of available data in the buffer.
      */
      size_t GetDataLeft();
  
      /**
          Returns the current position (counted in bytes) in the stream buffer.
      */
      size_t GetIntPosition() const;
  
      /**
          Returns the amount of bytes read during the last IO call to the parent stream.
      */
      size_t GetLastAccess() const;
  
      /**
          Puts a single char to the stream buffer.
  
          @warning
          You aren't directly notified if an error occurred during the IO call.
  
          @see Read()
      */
      virtual void PutChar(char c);
  
      /**
          Reads a block of the specified size and stores the data in buffer.
          This function tries to read from the buffer first and if more data has
          been requested, reads more data from the associated stream and updates
          the buffer accordingly until all requested data is read.
  
          @return It returns the size of the data read. If the returned size is
                  different of the specified size, an error has occurred and
                  should be tested using GetLastError().
      */
      virtual size_t Read(void* buffer, size_t size);
  
      /**
          Copies data to @a buffer.
          The function returns when @a buffer is full or when there isn't
          any more data in the current buffer.
  
          @see Write()
      */
      size_t Read(wxStreamBuffer* buffer);
  
      /**
          Resets to the initial state variables concerning the buffer.
      */
      void ResetBuffer();
  
      /**
          Changes the current position.
          Parameter @a mode may be one of the following:
  
          - @b wxFromStart: The position is counted from the start of the stream.
          - @b wxFromCurrent: The position is counted from the current position of the stream.
          - @b wxFromEnd: The position is counted from the end of the stream.
  
          @return Upon successful completion, it returns the new offset as
                  measured in bytes from the beginning of the stream.
                  Otherwise, it returns ::wxInvalidOffset.
      */
      virtual wxFileOffset Seek(wxFileOffset pos, wxSeekMode mode);
  
      /**
          Specifies which pointers to use for stream buffering.
          You need to pass a pointer on the start of the buffer end and another
          on the end. The object will use this buffer to cache stream data.
          It may be used also as a source/destination buffer when you create an
          empty stream buffer (See wxStreamBuffer::wxStreamBuffer).
  
          @remarks
          When you use this function, you will have to destroy the IO buffers
          yourself after the stream buffer is destroyed or don't use it anymore.
          In the case you use it with an empty buffer, the stream buffer will not
          resize it when it is full.
  
          @see wxStreamBuffer(), Fixed(), Flushable()
      */
      void SetBufferIO(void* start, void* end, bool takeOwnership = false);
  
      /**
          Destroys or invalidates the previous IO buffer and allocates a new one of the
          specified size.
  
          @warning
          All previous pointers aren't valid anymore.
  
          @remarks
          The created IO buffer is growable by the object.
  
          @see Fixed(), Flushable()
      */
      void SetBufferIO(size_t bufsize);
  
      /**
          Sets the current position (in bytes) in the stream buffer.
  
          @warning
          Since it is a very low-level function, there is no check on the position:
          specifying an invalid position can induce unexpected results.
      */
      void SetIntPosition(size_t pos);
  
      /**
          Returns the parent stream of the stream buffer.
          @deprecated use GetStream() instead
      */
      wxStreamBase* Stream();
  
      /**
          Gets the current position in the stream. This position is calculated from
          the @e real position in the stream and from the internal buffer position: so
          it gives you the position in the @e real stream counted from the start of
          the stream.
  
          @return Returns the current position in the stream if possible,
                  ::wxInvalidOffset in the other case.
      */
      virtual wxFileOffset Tell() const;
  
      /**
          Truncates the buffer to the current position.
  
          @note Truncate() cannot be used to enlarge the buffer. This is
                usually not needed since the buffer expands automatically.
      */
      void Truncate();
  
      /**
          Writes a block of the specified size using data of buffer.
          The data are cached in a buffer before being sent in one block to the stream.
      */
      virtual size_t Write(const void* buffer, size_t size);
  
      /**
          See Read().
      */
      size_t Write(wxStreamBuffer* buffer);
  };
  
  
  
  /**
      @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}
  */
  class wxOutputStream : public wxStreamBase
  {
  public:
      /**
          Creates a dummy wxOutputStream object.
      */
      wxOutputStream();
  
      /**
          Destructor.
      */
      virtual ~wxOutputStream();
  
      /**
          Closes the stream, returning @false if an error occurs.
          The stream is closed implicitly in the destructor if Close() is not
          called explicitly.
  
          If this stream wraps another stream or some other resource such
          as a file, then the underlying resource is closed too if it is owned
          by this stream, or left open otherwise.
      */
      virtual bool Close();
  
      /**
          Returns the number of bytes written during the last Write().
          It may return 0 even if there is no error on the stream if it is
          only temporarily impossible to write to it.
      */
      virtual size_t LastWrite() const;
  
      /**
          Puts the specified character in the output queue and increments the
          stream position.
      */
      void PutC(char c);
  
      /**
          Changes the stream current position.
  
          @param pos
              Offset to seek to.
          @param mode
              One of wxFromStart, wxFromEnd, wxFromCurrent.
  
          @return The new stream position or ::wxInvalidOffset on error.
      */
      virtual wxFileOffset SeekO(wxFileOffset pos, wxSeekMode mode = wxFromStart);
  
      /**
          Returns the current stream position.
      */
      virtual wxFileOffset TellO() const;
  
      /**
          Writes up to the specified amount of bytes using the data of buffer.
          Note that not all data can always be written so you must check the number
          of bytes really written to the stream using LastWrite() when this function
          returns.
  
          In some cases (for example a write end of a pipe which is currently full)
          it is even possible that there is no errors and zero bytes have been written.
          This function returns a reference on the current object, so the user can
          test any states of the stream right away.
      */
      virtual wxOutputStream& Write(const void* buffer, size_t size);
  
      /**
          Reads data from the specified input stream and stores them
          in the current stream. The data is read until an error is raised
          by one of the two streams.
      */
      wxOutputStream& Write(wxInputStream& stream_in);
  
      /**
          Writes exactly the specified number of bytes from the buffer.
  
          Returns @true if exactly @a size bytes were written. Otherwise, returns
          @false and LastWrite() should be used to retrieve the exact amount of
          the data written if necessary.
  
          This method uses repeated calls to Write() (which may return writing
          only part of the data) if necessary.
  
          @since 2.9.5
      */
      bool WriteAll(const void* buffer, size_t size);
  
  protected:
      /**
          Internal function. It is called when the stream wants to write data of the
          specified size @a bufsize into the given @a buffer.
  
          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 wxInputStream
  
      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).
  
      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}
  */
  class wxInputStream : public wxStreamBase
  {
  public:
      /**
          Creates a dummy input stream.
      */
      wxInputStream();
  
      /**
          Destructor.
      */
      virtual ~wxInputStream();
  
      /**
          Returns @true if some data is available in the stream right now, so that
          calling Read() wouldn't block.
      */
      virtual bool CanRead() const;
  
      /**
          Returns @true after an attempt has been made to read past the end of the
          stream.
      */
      virtual bool Eof() const;
  
      /**
          Returns the first character in the input queue and removes it,
          blocking until it appears if necessary.
  
          On success returns a value between 0 - 255; on end of file returns @c wxEOF.
      */
      int GetC();
  
      /**
          Returns the last number of bytes read.
      */
      virtual size_t LastRead() const;
  
      /**
          Returns the first character in the input queue without removing it.
      */
      virtual char Peek();
  
      /**
          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).
  
          @warning
          The buffer absolutely needs to have at least the specified size.
  
          @return This function returns a reference on the current object, so the
                  user can test any states of the stream right away.
      */
      virtual wxInputStream& Read(void* buffer, size_t size);
  
      /**
          Reads data from the input queue and stores it in the specified output stream.
          The data is read until an error is raised by one of the two streams.
  
          @return This function returns a reference on the current object, so the
                  user can test any states of the stream right away.
      */
      wxInputStream& Read(wxOutputStream& stream_out);
  
      /**
          Reads exactly the specified number of bytes into the buffer.
  
          Returns @true only if the entire amount of data was read, otherwise
          @false is returned and the number of bytes really read can be retrieved
          using LastRead(), as with Read().
  
          This method uses repeated calls to Read() (which may return after
          reading less than the requested number of bytes) if necessary.
  
          @warning
          The buffer absolutely needs to have at least the specified size.
  
          @since 2.9.5
      */
      bool ReadAll(void* buffer, size_t size);
  
      /**
          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).
  
          @param pos
              Offset to seek to.
          @param mode
              One of wxFromStart, wxFromEnd, wxFromCurrent.
  
          @return The new stream position or ::wxInvalidOffset on error.
      */
      virtual wxFileOffset SeekI(wxFileOffset pos, wxSeekMode mode = wxFromStart);
  
      /**
          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;
  
      /**
          This function is only useful in read mode.
          It is the manager of the "Write-Back" buffer. This buffer acts like a
          temporary buffer where data which has to be read during the next read IO
          call are put. This is useful when you get a big block of data which you
          didn't want to read: you can replace them at the top of the input queue
          by this way.
  
          Be very careful about this call in connection with calling SeekI() on
          the same stream. Any call to SeekI() will invalidate any previous call
          to this method (otherwise you could SeekI() to one position, "unread" a
          few bytes there, SeekI() to another position and data would be either
          lost or corrupted).
  
          @return Returns the amount of bytes saved in the Write-Back buffer.
      */
      size_t Ungetch(const void* buffer, size_t size);
  
      /**
          This function acts like the previous one except that it takes only one
          character: it is sometimes shorter to use than the generic function.
      */
      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) = 0;
  };
  
  
  
  
  /**
      @class wxCountingOutputStream
  
      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}
  */
  class wxCountingOutputStream : public wxOutputStream
  {
  public:
      /**
          Creates a wxCountingOutputStream object.
      */
      wxCountingOutputStream();
  
      /**
          Destructor.
      */
      virtual ~wxCountingOutputStream();
  
      /**
          Returns the current length of the stream.
  
          This is the amount of data written to the stream so far, in bytes.
      */
      virtual wxFileOffset GetLength() const;
  };
  
  
  /**
      @class wxBufferedInputStream
  
      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}
  
      @see wxStreamBuffer, wxInputStream, wxBufferedOutputStream
  */
  class wxBufferedInputStream : public wxFilterInputStream
  {
  public:
      /**
          Constructor using the provided buffer or default.
  
          @param stream
              The associated low-level stream.
          @param buffer
              The buffer to use if non-@NULL. Notice that the ownership of this
              buffer is taken by the stream, i.e. it will delete it. If this
              parameter is @NULL a default 1KB buffer is used.
      */
      wxBufferedInputStream(wxInputStream& stream,
                            wxStreamBuffer *buffer = NULL);
  
      /**
          Constructor allowing to specify the size of the buffer.
  
          This is just a more convenient alternative to creating a wxStreamBuffer
          of the given size and using the other overloaded constructor of this
          class.
  
          @param stream
              The associated low-level stream.
          @param bufsize
              The size of the buffer, in bytes.
  
          @since 2.9.0
       */
      wxBufferedInputStream(wxInputStream& stream, size_t bufsize);
  
      /**
          Destructor.
      */
      virtual ~wxBufferedInputStream();
  };
  
  
  
  
  /**
      Enumeration values used by wxFilterClassFactory.
  */
  enum wxStreamProtocolType
  {
      wxSTREAM_PROTOCOL,  //!< wxFileSystem protocol (should be only one).
      wxSTREAM_MIMETYPE,  //!< MIME types the stream handles.
      wxSTREAM_ENCODING,  //!< The HTTP Content-Encodings the stream handles.
      wxSTREAM_FILEEXT    //!< File extensions the stream handles.
  };
  
  /**
      @class wxFilterClassFactory
  
      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}
  
      @see wxFilterInputStream, wxFilterOutputStream, wxArchiveClassFactory,
          @ref overview_archive
  */
  class wxFilterClassFactory : public wxObject
  {
  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.
      */
      bool CanHandle(const wxString& protocol,
                     wxStreamProtocolType type = wxSTREAM_PROTOCOL) 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.
  
          When using @c wxSTREAM_FILEEXT for the second parameter, the first parameter
          can be a complete filename rather than just an extension.
      */
      static const wxFilterClassFactory* Find(const wxString& protocol,
                                              wxStreamProtocolType type = wxSTREAM_PROTOCOL);
  
      //@{
      /**
          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() << 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.
      */
      static const wxFilterClassFactory* GetFirst();
      const wxFilterClassFactory* GetNext() const;
      //@}
  
      /**
          Returns the wxFileSystem protocol supported by this factory.
          Equivalent to @code wxString(*GetProtocols()) @endcode.
      */
      wxString GetProtocol() const;
  
      /**
          Returns the protocols, MIME types, HTTP encodings or file extensions
          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;
  
          for (p = factory->GetProtocols(wxSTREAM_FILEEXT); *p; p++)
              list << *p << wxT("\n");
          @endcode
      */
      virtual const wxChar * const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL) const = 0;
  
      //@{
      /**
          Create a new input or output stream to decompress or compress a given stream.
  
          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 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;
      //@}
  
      /**
          Remove the file extension of @a location if it is one of the file
          extensions handled by this factory.
      */
      wxString PopExtension(const wxString& location) const;
  
      /**
          Adds this class factory to the list returned  by GetFirst()/GetNext().
  
          It is not necessary to do this to use the filter streams. It is usually
          used when implementing streams, typically the implementation will
          add a static instance of its factory class.
  
          It 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.
      */
      void PushFront();
  
      /**
          Removes this class factory from the list returned by GetFirst()/GetNext().
          Removing from the list isn't a thread safe operation so can't be done
          when other threads are running that will be using the list.
  
          The list does not own the factories, so removing a factory does not delete it.
      */
      void Remove();
  };
  
  
  
  /**
      @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
  */
  class wxFilterOutputStream : public wxOutputStream
  {
  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 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.
  
      @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 wxFilterClassFactory, wxFilterOutputStream
  */
  class wxFilterInputStream : public wxInputStream
  {
  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.
      */
      wxFilterInputStream(wxInputStream& stream);
      wxFilterInputStream(wxInputStream* stream);
      //@}
  };
  
  
  
  /**
      @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:
      /**
          Constructor using the provided buffer or default.
  
          @param stream
              The associated low-level stream.
          @param buffer
              The buffer to use if non-@NULL. Notice that the ownership of this
              buffer is taken by the stream, i.e. it will delete it. If this
              parameter is @NULL a default 1KB buffer is used.
      */
      wxBufferedOutputStream(wxOutputStream& stream,
                             wxStreamBuffer *buffer = NULL);
  
      /**
          Constructor allowing to specify the size of the buffer.
  
          This is just a more convenient alternative to creating a wxStreamBuffer
          of the given size and using the other overloaded constructor of this
          class.
  
          @param stream
              The associated low-level stream.
          @param bufsize
              The size of the buffer, in bytes.
  
          @since 2.9.0
       */
      wxBufferedOutputStream(wxOutputStream& stream, size_t bufsize);
  
      /**
          Destructor. Calls Sync() and destroys the internal buffer.
      */
      virtual ~wxBufferedOutputStream();
  
      /**
          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();
  };
  
  
  /**
      @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:
      //@{
      /**
          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.
      */
      wxWrapperInputStream(wxInputStream& stream);
      wxWrapperInputStream(wxInputStream* stream);
      //@}
  
  protected:
      /**
          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);
      //@}
  };
  