interface/wx/stream.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        stream.h
   3 // Purpose:     interface of wxStreamBase and its derived classes
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     These enumeration values are returned by various functions in the context
  12     of wxStream classes.
  13 */
  14 enum wxStreamError
  15 {
  16     wxSTREAM_NO_ERROR = 0,      //!< No error occurred.
  17     wxSTREAM_EOF,               //!< EOF reached in Read() or similar.
  18     wxSTREAM_WRITE_ERROR,       //!< generic write error on the last write call.
  19     wxSTREAM_READ_ERROR         //!< generic read error on the last read call.
  20 };
  21
  22 /**
  23     @class wxStreamBase
  24
  25     This class is the base class of most stream related classes in wxWidgets.
  26     It must not be used directly.
  27
  28     @library{wxbase}
  29     @category{streams}
  30
  31     @see wxStreamBuffer
  32 */
  33 class wxStreamBase
  34 {
  35 public:
  36     /**
  37         Creates a dummy stream object. It doesn't do anything.
  38     */
  39     wxStreamBase();
  40
  41     /**
  42         Destructor.
  43     */
  44     virtual ~wxStreamBase();
  45
  46     /**
  47         This function returns the last error.
  48     */
  49     wxStreamError GetLastError() const;
  50
  51     /**
  52         Returns the length of the stream in bytes. If the length cannot be
  53         determined (this is always the case for socket streams for example),
  54         returns ::wxInvalidOffset.
  55
  56         @since 2.5.4
  57     */
  58     virtual wxFileOffset GetLength() const;
  59
  60     /**
  61         This function returns the size of the stream.
  62         For example, for a file it is the size of the file.
  63
  64         @warning
  65         There are streams which do not have size by definition, such as socket
  66         streams. In that cases, GetSize() returns 0 so you should always test its
  67         return value.
  68     */
  69     virtual size_t GetSize() const;
  70
  71     /**
  72         Returns @true if no error occurred on the stream.
  73
  74         @see GetLastError()
  75     */
  76     virtual bool IsOk() const;
  77
  78     /**
  79         Returns @true if the stream supports seeking to arbitrary offsets.
  80     */
  81     virtual bool IsSeekable() const;
  82
  83     /**
  84         Resets the stream state.
  85
  86         By default, resets the stream to good state, i.e. clears any errors.
  87         Since wxWidgets 2.9.3 can be also used to explicitly set the state to
  88         the specified error (the @a error argument didn't exist in the previous
  89         versions).
  90
  91         @see GetLastError()
  92      */
  93     void Reset(wxStreamError error = wxSTREAM_NO_ERROR);
  94
  95     /**
  96         Returns the opposite of IsOk().
  97         You can use this function to test the validity of the stream as if
  98         it was a pointer:
  99
 100         @code
 101             bool DoSomething(wxInputStream& stream)
 102             {
 103                 wxInt32 data;
 104                 if (!stream.Read(&data, 4))
 105                     return false;
 106                 ...
 107             }
 108         @endcode
 109     */
 110     bool operator!() const;
 111
 112 protected:
 113
 114     /**
 115         Internal function.
 116         It is called when the stream needs to change the current position.
 117
 118         @param pos
 119             Offset to seek to.
 120         @param mode
 121             One of the ::wxSeekMode enumeration values.
 122
 123         @return The new stream position or ::wxInvalidOffset on error.
 124     */
 125     virtual wxFileOffset OnSysSeek(wxFileOffset pos, wxSeekMode mode);
 126
 127     /**
 128         Internal function.
 129         It is called when the stream needs to know the real position.
 130
 131         @return The current stream position.
 132     */
 133     virtual wxFileOffset OnSysTell() const;
 134 };
 135
 136 /**
 137     @class wxStreamBuffer
 138
 139     wxStreamBuffer is a cache manager for wxStreamBase: it manages a stream buffer
 140     linked to a stream.
 141
 142     Each stream always has one autoinitialized stream buffer, but you may
 143     attach more of them to the same stream.
 144
 145     @library{wxbase}
 146     @category{streams}
 147
 148     @see wxStreamBase, @ref overview_stream
 149 */
 150 class wxStreamBuffer
 151 {
 152 public:
 153     /** BufMode flags */
 154     enum BufMode
 155     {
 156         read,
 157         write,
 158         read_write
 159     };
 160
 161     /**
 162         Constructor, creates a new stream buffer using @a stream as a parent stream
 163         and mode as the IO mode.
 164
 165         @param stream
 166             The parent stream.
 167         @param mode
 168             Can be: wxStreamBuffer::read, wxStreamBuffer::write, wxStreamBuffer::read_write.
 169
 170         One stream can have many stream buffers but only one is used internally
 171         to pass IO call (e.g. wxInputStream::Read() -> wxStreamBuffer::Read()),
 172         but you can call directly wxStreamBuffer::Read without any problems.
 173         Note that all errors and messages linked to the stream are stored in the
 174         stream, not the stream buffers:
 175
 176         @code
 177         streambuffer.Read(...);
 178         streambuffer2.Read(...);
 179             // This call erases previous error messages set by 'streambuffer'
 180             // assuming that both instances are stream buffers for the same stream
 181         @endcode
 182
 183         @see SetBufferIO()
 184     */
 185     wxStreamBuffer(wxStreamBase& stream, BufMode mode);
 186
 187     /**
 188         Constructor for an input buffer of the specified size.
 189
 190         Using it is equivalent to using the constructor above with read mode
 191         and calling SetBufferIO() but is more convenient.
 192
 193         @since 2.9.0
 194
 195         @param bufsize
 196             The size of buffer in bytes.
 197         @param stream
 198             The associated input stream, the buffer will be used in read mode.
 199      */
 200     wxStreamBuffer(size_t bufsize, wxInputStream& stream);
 201
 202     /**
 203         Constructor for an output buffer of the specified size.
 204
 205         Using it is equivalent to using the constructor above with write mode
 206         and calling SetBufferIO() but is more convenient.
 207
 208         @since 2.9.0
 209
 210         @param bufsize
 211             The size of buffer in bytes.
 212         @param stream
 213             The associated output stream, the buffer will be used in write mode.
 214      */
 215     wxStreamBuffer(size_t bufsize, wxOutputStream& stream);
 216
 217     /**
 218         Constructor; creates a new empty stream buffer which won't flush any data
 219         to a stream. mode specifies the type of the buffer (read, write, read_write).
 220
 221         This stream buffer has the advantage to be stream independent and to work
 222         only on memory buffers but it is still compatible with the rest of the
 223         wxStream classes. You can write, read to this special stream and it will
 224         grow (if it is allowed by the user) its internal buffer.
 225         Briefly, it has all functionality of a "normal" stream.
 226
 227         @warning
 228         The "read_write" mode doesn't currently work for standalone stream buffers.
 229
 230         @see SetBufferIO()
 231     */
 232     wxStreamBuffer(BufMode mode);
 233
 234     /**
 235         Copy constructor.
 236
 237         This method initializes the stream buffer with the data of the specified
 238         stream buffer. The new stream buffer has the same attributes, size, position
 239         and they share the same buffer. This will cause problems if the stream to
 240         which the stream buffer belong is destroyed and the newly cloned stream
 241         buffer continues to be used, trying to call functions in the (destroyed)
 242         stream. It is advised to use this feature only in very local area of the
 243         program.
 244     */
 245     wxStreamBuffer(const wxStreamBuffer& buffer);
 246
 247     /**
 248         Destructor.
 249         It finalizes all IO calls and frees all internal buffers if necessary.
 250     */
 251     ~wxStreamBuffer();
 252
 253     /**
 254         Fill the IO buffer.
 255     */
 256     bool FillBuffer();
 257
 258     /**
 259         Toggles the fixed flag. Usually this flag is toggled at the same time as
 260         @e flushable. This flag allows (when it has the @false value) or forbids
 261         (when it has the @true value) the stream buffer to resize dynamically the
 262         IO buffer.
 263
 264         @see SetBufferIO()
 265     */
 266     void Fixed(bool fixed);
 267
 268     /**
 269         Flushes the IO buffer.
 270     */
 271     bool FlushBuffer();
 272
 273     /**
 274         Toggles the flushable flag.
 275         If @a flushable is disabled, no data are sent to the parent stream.
 276     */
 277     void Flushable(bool flushable);
 278
 279     /**
 280         Returns a pointer on the end of the stream buffer.
 281     */
 282     void* GetBufferEnd() const;
 283
 284     /**
 285         Returns a pointer on the current position of the stream buffer.
 286     */
 287     void* GetBufferPos() const;
 288
 289     /**
 290         Returns the size of the buffer.
 291     */
 292     size_t GetBufferSize() const;
 293
 294     /**
 295         Returns a pointer on the start of the stream buffer.
 296     */
 297     void* GetBufferStart() const;
 298
 299     /**
 300         Gets a single char from the stream buffer. It acts like the Read() call.
 301
 302         @warning
 303         You aren't directly notified if an error occurred during the IO call.
 304
 305         @see Read()
 306     */
 307     virtual char GetChar();
 308
 309     /**
 310         Returns the amount of available data in the buffer.
 311     */
 312     size_t GetDataLeft();
 313
 314     /**
 315         Returns the current position (counted in bytes) in the stream buffer.
 316     */
 317     size_t GetIntPosition() const;
 318
 319     /**
 320         Returns the amount of bytes read during the last IO call to the parent stream.
 321     */
 322     size_t GetLastAccess() const;
 323
 324     /**
 325         Puts a single char to the stream buffer.
 326
 327         @warning
 328         You aren't directly notified if an error occurred during the IO call.
 329
 330         @see Read()
 331     */
 332     virtual void PutChar(char c);
 333
 334     /**
 335         Reads a block of the specified size and stores the data in buffer.
 336         This function tries to read from the buffer first and if more data has
 337         been requested, reads more data from the associated stream and updates
 338         the buffer accordingly until all requested data is read.
 339
 340         @return It returns the size of the data read. If the returned size is
 341                 different of the specified size, an error has occurred and
 342                 should be tested using GetLastError().
 343     */
 344     virtual size_t Read(void* buffer, size_t size);
 345
 346     /**
 347         Copies data to @a buffer.
 348         The function returns when @a buffer is full or when there isn't
 349         any more data in the current buffer.
 350
 351         @see Write()
 352     */
 353     size_t Read(wxStreamBuffer* buffer);
 354
 355     /**
 356         Resets to the initial state variables concerning the buffer.
 357     */
 358     void ResetBuffer();
 359
 360     /**
 361         Changes the current position.
 362         Parameter @a mode may be one of the following:
 363
 364         - @b wxFromStart: The position is counted from the start of the stream.
 365         - @b wxFromCurrent: The position is counted from the current position of the stream.
 366         - @b wxFromEnd: The position is counted from the end of the stream.
 367
 368         @return Upon successful completion, it returns the new offset as
 369                 measured in bytes from the beginning of the stream.
 370                 Otherwise, it returns ::wxInvalidOffset.
 371     */
 372     virtual wxFileOffset Seek(wxFileOffset pos, wxSeekMode mode);
 373
 374     /**
 375         Specifies which pointers to use for stream buffering.
 376         You need to pass a pointer on the start of the buffer end and another
 377         on the end. The object will use this buffer to cache stream data.
 378         It may be used also as a source/destination buffer when you create an
 379         empty stream buffer (See wxStreamBuffer::wxStreamBuffer).
 380
 381         @remarks
 382         When you use this function, you will have to destroy the IO buffers
 383         yourself after the stream buffer is destroyed or don't use it anymore.
 384         In the case you use it with an empty buffer, the stream buffer will not
 385         resize it when it is full.
 386
 387         @see wxStreamBuffer(), Fixed(), Flushable()
 388     */
 389     void SetBufferIO(void* start, void* end, bool takeOwnership = false);
 390
 391     /**
 392         Destroys or invalidates the previous IO buffer and allocates a new one of the
 393         specified size.
 394
 395         @warning
 396         All previous pointers aren't valid anymore.
 397
 398         @remarks
 399         The created IO buffer is growable by the object.
 400
 401         @see Fixed(), Flushable()
 402     */
 403     void SetBufferIO(size_t bufsize);
 404
 405     /**
 406         Sets the current position (in bytes) in the stream buffer.
 407
 408         @warning
 409         Since it is a very low-level function, there is no check on the position:
 410         specifying an invalid position can induce unexpected results.
 411     */
 412     void SetIntPosition(size_t pos);
 413
 414     /**
 415         Returns the parent stream of the stream buffer.
 416         @deprecated use GetStream() instead
 417     */
 418     wxStreamBase* Stream();
 419
 420     /**
 421         Gets the current position in the stream. This position is calculated from
 422         the @e real position in the stream and from the internal buffer position: so
 423         it gives you the position in the @e real stream counted from the start of
 424         the stream.
 425
 426         @return Returns the current position in the stream if possible,
 427                 ::wxInvalidOffset in the other case.
 428     */
 429     virtual wxFileOffset Tell() const;
 430
 431     /**
 432         Truncates the buffer to the current position.
 433
 434         @note Truncate() cannot be used to enlarge the buffer. This is
 435               usually not needed since the buffer expands automatically.
 436     */
 437     void Truncate();
 438
 439     /**
 440         Writes a block of the specified size using data of buffer.
 441         The data are cached in a buffer before being sent in one block to the stream.
 442     */
 443     virtual size_t Write(const void* buffer, size_t size);
 444
 445     /**
 446         See Read().
 447     */
 448     size_t Write(wxStreamBuffer* buffer);
 449 };
 450
 451
 452
 453 /**
 454     @class wxOutputStream
 455
 456     wxOutputStream is an abstract base class which may not be used directly.
 457     It is the base class of all streams which provide a Write() function,
 458     i.e. which can be used to output data (e.g. to a file, to a socket, etc).
 459
 460     If you want to create your own output stream, you'll need to derive from this
 461     class and implement the protected OnSysWrite() function only.
 462
 463     @library{wxbase}
 464     @category{streams}
 465 */
 466 class wxOutputStream : public wxStreamBase
 467 {
 468 public:
 469     /**
 470         Creates a dummy wxOutputStream object.
 471     */
 472     wxOutputStream();
 473
 474     /**
 475         Destructor.
 476     */
 477     virtual ~wxOutputStream();
 478
 479     /**
 480         Closes the stream, returning @false if an error occurs.
 481         The stream is closed implicitly in the destructor if Close() is not
 482         called explicitly.
 483
 484         If this stream wraps another stream or some other resource such
 485         as a file, then the underlying resource is closed too if it is owned
 486         by this stream, or left open otherwise.
 487     */
 488     virtual bool Close();
 489
 490     /**
 491         Returns the number of bytes written during the last Write().
 492         It may return 0 even if there is no error on the stream if it is
 493         only temporarily impossible to write to it.
 494     */
 495     virtual size_t LastWrite() const;
 496
 497     /**
 498         Puts the specified character in the output queue and increments the
 499         stream position.
 500     */
 501     void PutC(char c);
 502
 503     /**
 504         Changes the stream current position.
 505
 506         @param pos
 507             Offset to seek to.
 508         @param mode
 509             One of wxFromStart, wxFromEnd, wxFromCurrent.
 510
 511         @return The new stream position or ::wxInvalidOffset on error.
 512     */
 513     virtual wxFileOffset SeekO(wxFileOffset pos, wxSeekMode mode = wxFromStart);
 514
 515     /**
 516         Returns the current stream position.
 517     */
 518     virtual wxFileOffset TellO() const;
 519
 520     /**
 521         Writes up to the specified amount of bytes using the data of buffer.
 522         Note that not all data can always be written so you must check the number
 523         of bytes really written to the stream using LastWrite() when this function
 524         returns.
 525
 526         In some cases (for example a write end of a pipe which is currently full)
 527         it is even possible that there is no errors and zero bytes have been written.
 528         This function returns a reference on the current object, so the user can
 529         test any states of the stream right away.
 530     */
 531     virtual wxOutputStream& Write(const void* buffer, size_t size);
 532
 533     /**
 534         Reads data from the specified input stream and stores them
 535         in the current stream. The data is read until an error is raised
 536         by one of the two streams.
 537     */
 538     wxOutputStream& Write(wxInputStream& stream_in);
 539
 540 protected:
 541     /**
 542         Internal function. It is called when the stream wants to write data of the
 543         specified size @a bufsize into the given @a buffer.
 544
 545         It should return the size that was actually wrote (which maybe zero if
 546         @a bufsize is zero or if an error occurred; in this last case the internal
 547         variable @c m_lasterror should be appropriately set).
 548     */
 549     size_t OnSysWrite(const void* buffer, size_t bufsize);
 550 };
 551
 552
 553 /**
 554     @class wxInputStream
 555
 556     wxInputStream is an abstract base class which may not be used directly.
 557     It is the base class of all streams which provide a Read() function,
 558     i.e. which can be used to read data from a source (e.g. a file, a socket, etc).
 559
 560     If you want to create your own input stream, you'll need to derive from this
 561     class and implement the protected OnSysRead() function only.
 562
 563     @library{wxbase}
 564     @category{streams}
 565 */
 566 class wxInputStream : public wxStreamBase
 567 {
 568 public:
 569     /**
 570         Creates a dummy input stream.
 571     */
 572     wxInputStream();
 573
 574     /**
 575         Destructor.
 576     */
 577     virtual ~wxInputStream();
 578
 579     /**
 580         Returns @true if some data is available in the stream right now, so that
 581         calling Read() wouldn't block.
 582     */
 583     virtual bool CanRead() const;
 584
 585     /**
 586         Returns @true after an attempt has been made to read past the end of the
 587         stream.
 588     */
 589     virtual bool Eof() const;
 590
 591     /**
 592         Returns the first character in the input queue and removes it,
 593         blocking until it appears if necessary.
 594
 595         On success returns a value between 0 - 255; on end of file returns @c wxEOF.
 596     */
 597     int GetC();
 598
 599     /**
 600         Returns the last number of bytes read.
 601     */
 602     virtual size_t LastRead() const;
 603
 604     /**
 605         Returns the first character in the input queue without removing it.
 606     */
 607     virtual char Peek();
 608
 609     /**
 610         Reads the specified amount of bytes and stores the data in buffer.
 611         To check if the call was successful you must use LastRead() to check
 612         if this call did actually read @a size bytes (if it didn't, GetLastError()
 613         should return a meaningful value).
 614
 615         @warning
 616         The buffer absolutely needs to have at least the specified size.
 617
 618         @return This function returns a reference on the current object, so the
 619                 user can test any states of the stream right away.
 620     */
 621     virtual wxInputStream& Read(void* buffer, size_t size);
 622
 623     /**
 624         Reads data from the input queue and stores it in the specified output stream.
 625         The data is read until an error is raised by one of the two streams.
 626
 627         @return This function returns a reference on the current object, so the
 628                 user can test any states of the stream right away.
 629     */
 630     wxInputStream& Read(wxOutputStream& stream_out);
 631
 632     /**
 633         Changes the stream current position.
 634
 635         This operation in general is possible only for seekable streams
 636         (see wxStreamBase::IsSeekable()); non-seekable streams support only
 637         seeking positive amounts in mode @c wxFromCurrent (this is implemented
 638         by reading data and simply discarding it).
 639
 640         @param pos
 641             Offset to seek to.
 642         @param mode
 643             One of wxFromStart, wxFromEnd, wxFromCurrent.
 644
 645         @return The new stream position or ::wxInvalidOffset on error.
 646     */
 647     virtual wxFileOffset SeekI(wxFileOffset pos, wxSeekMode mode = wxFromStart);
 648
 649     /**
 650         Returns the current stream position or ::wxInvalidOffset if it's not
 651         available (e.g. socket streams do not have a size nor a current stream
 652         position).
 653     */
 654     virtual wxFileOffset TellI() const;
 655
 656     /**
 657         This function is only useful in read mode.
 658         It is the manager of the "Write-Back" buffer. This buffer acts like a
 659         temporary buffer where data which has to be read during the next read IO
 660         call are put. This is useful when you get a big block of data which you
 661         didn't want to read: you can replace them at the top of the input queue
 662         by this way.
 663
 664         Be very careful about this call in connection with calling SeekI() on
 665         the same stream. Any call to SeekI() will invalidate any previous call
 666         to this method (otherwise you could SeekI() to one position, "unread" a
 667         few bytes there, SeekI() to another position and data would be either
 668         lost or corrupted).
 669
 670         @return Returns the amount of bytes saved in the Write-Back buffer.
 671     */
 672     size_t Ungetch(const void* buffer, size_t size);
 673
 674     /**
 675         This function acts like the previous one except that it takes only one
 676         character: it is sometimes shorter to use than the generic function.
 677     */
 678     bool Ungetch(char c);
 679
 680 protected:
 681
 682     /**
 683         Internal function. It is called when the stream wants to read data of the
 684         specified size @a bufsize and wants it to be placed inside @a buffer.
 685
 686         It should return the size that was actually read or zero if EOF has been
 687         reached or an error occurred (in this last case the internal @c m_lasterror
 688         variable should be set accordingly as well).
 689     */
 690     size_t OnSysRead(void* buffer, size_t bufsize) = 0;
 691 };
 692
 693
 694
 695
 696 /**
 697     @class wxCountingOutputStream
 698
 699     wxCountingOutputStream is a specialized output stream which does not write any
 700     data anywhere, instead it counts how many bytes would get written if this were a
 701     normal stream. This can sometimes be useful or required if some data gets
 702     serialized to a stream or compressed by using stream compression and thus the
 703     final size of the stream cannot be known other than pretending to write the stream.
 704     One case where the resulting size would have to be known is if the data has
 705     to be written to a piece of memory and the memory has to be allocated before
 706     writing to it (which is probably always the case when writing to a memory stream).
 707
 708     @library{wxbase}
 709     @category{streams}
 710 */
 711 class wxCountingOutputStream : public wxOutputStream
 712 {
 713 public:
 714     /**
 715         Creates a wxCountingOutputStream object.
 716     */
 717     wxCountingOutputStream();
 718
 719     /**
 720         Destructor.
 721     */
 722     virtual ~wxCountingOutputStream();
 723
 724     /**
 725         Returns the current size of the stream.
 726     */
 727     size_t GetSize() const;
 728 };
 729
 730
 731 /**
 732     @class wxBufferedInputStream
 733
 734     This stream acts as a cache. It caches the bytes read from the specified
 735     input stream (see wxFilterInputStream).
 736     It uses wxStreamBuffer and sets the default in-buffer size to 1024 bytes.
 737     This class may not be used without some other stream to read the data
 738     from (such as a file stream or a memory stream).
 739
 740     @library{wxbase}
 741     @category{streams}
 742
 743     @see wxStreamBuffer, wxInputStream, wxBufferedOutputStream
 744 */
 745 class wxBufferedInputStream : public wxFilterInputStream
 746 {
 747 public:
 748     /**
 749         Constructor using the provided buffer or default.
 750
 751         @param stream
 752             The associated low-level stream.
 753         @param buffer
 754             The buffer to use if non-@NULL. Notice that the ownership of this
 755             buffer is taken by the stream, i.e. it will delete it. If this
 756             parameter is @NULL a default 1KB buffer is used.
 757     */
 758     wxBufferedInputStream(wxInputStream& stream,
 759                           wxStreamBuffer *buffer = NULL);
 760
 761     /**
 762         Constructor allowing to specify the size of the buffer.
 763
 764         This is just a more convenient alternative to creating a wxStreamBuffer
 765         of the given size and using the other overloaded constructor of this
 766         class.
 767
 768         @param stream
 769             The associated low-level stream.
 770         @param bufsize
 771             The size of the buffer, in bytes.
 772
 773         @since 2.9.0
 774      */
 775     wxBufferedInputStream(wxInputStream& stream, size_t bufsize);
 776
 777     /**
 778         Destructor.
 779     */
 780     virtual ~wxBufferedInputStream();
 781 };
 782
 783
 784
 785
 786 /**
 787     Enumeration values used by wxFilterClassFactory.
 788 */
 789 enum wxStreamProtocolType
 790 {
 791     wxSTREAM_PROTOCOL,  //!< wxFileSystem protocol (should be only one).
 792     wxSTREAM_MIMETYPE,  //!< MIME types the stream handles.
 793     wxSTREAM_ENCODING,  //!< The HTTP Content-Encodings the stream handles.
 794     wxSTREAM_FILEEXT    //!< File extensions the stream handles.
 795 };
 796
 797 /**
 798     @class wxFilterClassFactory
 799
 800     Allows the creation of filter streams to handle compression formats such
 801     as gzip and bzip2.
 802
 803     For example, given a filename you can search for a factory that will
 804     handle it and create a stream to decompress it:
 805
 806     @code
 807         factory = wxFilterClassFactory::Find(filename, wxSTREAM_FILEEXT);
 808         if (factory)
 809             stream = factory->NewStream(new wxFFileInputStream(filename));
 810     @endcode
 811
 812     wxFilterClassFactory::Find can also search for a factory by MIME type,
 813     HTTP encoding or by wxFileSystem protocol.
 814     The available factories can be enumerated using wxFilterClassFactory::GetFirst()
 815     and wxFilterClassFactory::GetNext().
 816
 817     @library{wxbase}
 818     @category{streams}
 819
 820     @see wxFilterInputStream, wxFilterOutputStream, wxArchiveClassFactory,
 821         @ref overview_archive
 822 */
 823 class wxFilterClassFactory : public wxObject
 824 {
 825 public:
 826     /**
 827         Returns @true if this factory can handle the given protocol, MIME type, HTTP
 828         encoding or file extension.
 829
 830         When using @c wxSTREAM_FILEEXT for the second parameter, the first parameter
 831         can be a complete filename rather than just an extension.
 832     */
 833     bool CanHandle(const wxString& protocol,
 834                    wxStreamProtocolType type = wxSTREAM_PROTOCOL) const;
 835
 836     /**
 837         A static member that finds a factory that can handle a given protocol, MIME
 838         type, HTTP encoding or file extension. Returns a pointer to the class
 839         factory if found, or @NULL otherwise.
 840         It does not give away ownership of the factory.
 841
 842         When using @c wxSTREAM_FILEEXT for the second parameter, the first parameter
 843         can be a complete filename rather than just an extension.
 844     */
 845     static const wxFilterClassFactory* Find(const wxString& protocol,
 846                                             wxStreamProtocolType type = wxSTREAM_PROTOCOL);
 847
 848     //@{
 849     /**
 850         GetFirst and GetNext can be used to enumerate the available factories.
 851         For example, to list them:
 852
 853         @code
 854         wxString list;
 855         const wxFilterClassFactory *factory = wxFilterClassFactory::GetFirst();
 856
 857         while (factory) {
 858             list << factory->GetProtocol() << wxT("\n");
 859             factory = factory->GetNext();
 860         }
 861         @endcode
 862
 863         GetFirst()/GetNext() return a pointer to a factory or @NULL if no more
 864         are available. They do not give away ownership of the factory.
 865     */
 866     static const wxFilterClassFactory* GetFirst();
 867     const wxFilterClassFactory* GetNext() const;
 868     //@}
 869
 870     /**
 871         Returns the wxFileSystem protocol supported by this factory.
 872         Equivalent to @code wxString(*GetProtocols()) @endcode.
 873     */
 874     wxString GetProtocol() const;
 875
 876     /**
 877         Returns the protocols, MIME types, HTTP encodings or file extensions
 878         supported by this factory, as an array of null terminated strings.
 879         It does not give away ownership of the array or strings.
 880
 881         For example, to list the file extensions a factory supports:
 882
 883         @code
 884         wxString list;
 885         const wxChar *const *p;
 886
 887         for (p = factory->GetProtocols(wxSTREAM_FILEEXT); *p; p++)
 888             list << *p << wxT("\n");
 889         @endcode
 890     */
 891     virtual const wxChar * const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL) const = 0;
 892
 893     //@{
 894     /**
 895         Create a new input or output stream to decompress or compress a given stream.
 896
 897         If the parent stream is passed as a pointer then the new filter stream
 898         takes ownership of it. If it is passed by reference then it does not.
 899     */
 900     virtual wxFilterInputStream*  NewStream(wxInputStream& stream) const = 0;
 901     virtual wxFilterOutputStream* NewStream(wxOutputStream& stream) const = 0;
 902     virtual wxFilterInputStream*  NewStream(wxInputStream* stream) const = 0;
 903     virtual wxFilterOutputStream* NewStream(wxOutputStream* stream) const = 0;
 904     //@}
 905
 906     /**
 907         Remove the file extension of @a location if it is one of the file
 908         extensions handled by this factory.
 909     */
 910     wxString PopExtension(const wxString& location) const;
 911
 912     /**
 913         Adds this class factory to the list returned  by GetFirst()/GetNext().
 914
 915         It is not necessary to do this to use the filter streams. It is usually
 916         used when implementing streams, typically the implementation will
 917         add a static instance of its factory class.
 918
 919         It can also be used to change the order of a factory already in the list,
 920         bringing it to the front. This isn't a thread safe operation so can't be
 921         done when other threads are running that will be using the list.
 922
 923         The list does not take ownership of the factory.
 924     */
 925     void PushFront();
 926
 927     /**
 928         Removes this class factory from the list returned by GetFirst()/GetNext().
 929         Removing from the list isn't a thread safe operation so can't be done
 930         when other threads are running that will be using the list.
 931
 932         The list does not own the factories, so removing a factory does not delete it.
 933     */
 934     void Remove();
 935 };
 936
 937
 938
 939 /**
 940     @class wxFilterOutputStream
 941
 942     A filter stream has the capability of a normal stream but it can be placed
 943     on top of another stream. So, for example, it can compress, encrypt the data
 944     which are passed to it and write them to another stream.
 945
 946     @note
 947     The use of this class is exactly the same as of wxOutputStream.
 948     Only a constructor differs and it is documented below.
 949
 950     @library{wxbase}
 951     @category{streams}
 952
 953     @see wxFilterClassFactory, wxFilterInputStream
 954 */
 955 class wxFilterOutputStream : public wxOutputStream
 956 {
 957 public:
 958     //@{
 959     /**
 960         Initializes a "filter" stream.
 961
 962         If the parent stream is passed as a pointer then the new filter stream
 963         takes ownership of it. If it is passed by reference then it does not.
 964     */
 965     wxFilterOutputStream(wxOutputStream& stream);
 966     wxFilterOutputStream(wxOutputStream* stream);
 967     //@}
 968 };
 969
 970
 971
 972 /**
 973     @class wxFilterInputStream
 974
 975     A filter stream has the capability of a normal stream but it can be placed on
 976     top of another stream. So, for example, it can uncompress or decrypt the data which
 977     are read from another stream and pass it to the requester.
 978
 979     @note
 980     The interface of this class is the same as that of wxInputStream.
 981     Only a constructor differs and it is documented below.
 982
 983     @library{wxbase}
 984     @category{streams}
 985
 986     @see wxFilterClassFactory, wxFilterOutputStream
 987 */
 988 class wxFilterInputStream : public wxInputStream
 989 {
 990 public:
 991     //@{
 992     /**
 993         Initializes a "filter" stream.
 994
 995         If the parent stream is passed as a pointer then the new filter stream
 996         takes ownership of it. If it is passed by reference then it does not.
 997     */
 998     wxFilterInputStream(wxInputStream& stream);
 999     wxFilterInputStream(wxInputStream* stream);
1000     //@}
1001 };
1002
1003
1004
1005 /**
1006     @class wxBufferedOutputStream
1007
1008     This stream acts as a cache. It caches the bytes to be written to the specified
1009     output stream (See wxFilterOutputStream). The data is only written when the
1010     cache is full, when the buffered stream is destroyed or when calling SeekO().
1011
1012     This class may not be used without some other stream to write the data
1013     to (such as a file stream or a memory stream).
1014
1015     @library{wxbase}
1016     @category{streams}
1017
1018     @see wxStreamBuffer, wxOutputStream
1019 */
1020 class wxBufferedOutputStream : public wxFilterOutputStream
1021 {
1022 public:
1023     /**
1024         Constructor using the provided buffer or default.
1025
1026         @param stream
1027             The associated low-level stream.
1028         @param buffer
1029             The buffer to use if non-@NULL. Notice that the ownership of this
1030             buffer is taken by the stream, i.e. it will delete it. If this
1031             parameter is @NULL a default 1KB buffer is used.
1032     */
1033     wxBufferedOutputStream(wxOutputStream& stream,
1034                            wxStreamBuffer *buffer = NULL);
1035
1036     /**
1037         Constructor allowing to specify the size of the buffer.
1038
1039         This is just a more convenient alternative to creating a wxStreamBuffer
1040         of the given size and using the other overloaded constructor of this
1041         class.
1042
1043         @param stream
1044             The associated low-level stream.
1045         @param bufsize
1046             The size of the buffer, in bytes.
1047
1048         @since 2.9.0
1049      */
1050     wxBufferedOutputStream(wxOutputStream& stream, size_t bufsize);
1051
1052     /**
1053         Destructor. Calls Sync() and destroys the internal buffer.
1054     */
1055     virtual ~wxBufferedOutputStream();
1056
1057     /**
1058         Calls Sync() and changes the stream position.
1059     */
1060     virtual wxFileOffset SeekO(wxFileOffset pos, wxSeekMode mode = wxFromStart);
1061
1062     /**
1063         Flushes the buffer and calls Sync() on the parent stream.
1064     */
1065     virtual void Sync();
1066 };
1067
1068
1069 /**
1070     @class wxWrapperInputStream
1071
1072     A wrapper input stream is a kind of filter stream which forwards all the
1073     operations to its base stream. This is useful to build utility classes such
1074     as wxFSInputStream.
1075
1076     @note
1077     The interface of this class is the same as that of wxInputStream.
1078     Only a constructor differs and it is documented below.
1079
1080     @library{wxbase}
1081     @category{streams}
1082
1083     @see wxFSInputStream, wxFilterInputStream
1084     @since 2.9.4
1085 */
1086 class wxWrapperInputStream : public wxFilterInputStream
1087 {
1088 public:
1089     //@{
1090     /**
1091         Initializes a wrapper stream.
1092
1093         If the parent stream is passed as a pointer then the new wrapper stream
1094         takes ownership of it. If it is passed by reference then it does not.
1095     */
1096     wxWrapperInputStream(wxInputStream& stream);
1097     wxWrapperInputStream(wxInputStream* stream);
1098     //@}
1099
1100 protected:
1101     /**
1102         Default constructor, use InitParentStream() to finish initialization.
1103
1104         This constructor can be used by the derived classes from their own
1105         constructors when the parent stream can't be specified immediately.
1106         The derived class must call InitParentStream() later to do it.
1107      */
1108     wxWrapperInputStream();
1109
1110     //@{
1111     /**
1112         Set up the wrapped stream for an object initialized using the default
1113         constructor.
1114
1115         The ownership logic is the same as for the non-default constructor,
1116         i.e. this object takes ownership of the stream if it's passed by
1117         pointer but not if it's passed by reference.
1118      */
1119     void InitParentStream(wxInputStream& stream);
1120     void InitParentStream(wxInputStream* stream);
1121     //@}
1122 };