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