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