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