interface/wx/stream.h

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