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         @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         @param pos
 617             Offset to seek to.
 618         @param mode
 619             One of wxFromStart, wxFromEnd, wxFromCurrent.
 620
 621         @return The new stream position or ::wxInvalidOffset on error.
 622     */
 623     virtual wxFileOffset SeekI(wxFileOffset pos, wxSeekMode mode = wxFromStart);
 624
 625     /**
 626         Returns the current stream position.
 627     */
 628     virtual wxFileOffset TellI() const;
 629
 630     /**
 631         This function is only useful in read mode.
 632         It is the manager of the "Write-Back" buffer. This buffer acts like a
 633         temporary buffer where data which has to be read during the next read IO
 634         call are put. This is useful when you get a big block of data which you
 635         didn't want to read: you can replace them at the top of the input queue
 636         by this way.
 637
 638         Be very careful about this call in connection with calling SeekI() on
 639         the same stream. Any call to SeekI() will invalidate any previous call
 640         to this method (otherwise you could SeekI() to one position, "unread" a
 641         few bytes there, SeekI() to another position and data would be either
 642         lost or corrupted).
 643
 644         @return Returns the amount of bytes saved in the Write-Back buffer.
 645     */
 646     size_t Ungetch(const void* buffer, size_t size);
 647
 648     /**
 649         This function acts like the previous one except that it takes only one
 650         character: it is sometimes shorter to use than the generic function.
 651     */
 652     bool Ungetch(char c);
 653
 654 protected:
 655
 656     /**
 657         Internal function. It is called when the stream wants to read data of the
 658         specified size @a bufsize and wants it to be placed inside @a buffer.
 659
 660         It should return the size that was actually read or zero if EOF has been
 661         reached or an error occurred (in this last case the internal @c m_lasterror
 662         variable should be set accordingly as well).
 663     */
 664     size_t OnSysRead(void* buffer, size_t bufsize);
 665 };
 666
 667
 668
 669
 670 /**
 671     @class wxCountingOutputStream
 672
 673     wxCountingOutputStream is a specialized output stream which does not write any
 674     data anywhere, instead it counts how many bytes would get written if this were a
 675     normal stream. This can sometimes be useful or required if some data gets
 676     serialized to a stream or compressed by using stream compression and thus the
 677     final size of the stream cannot be known other than pretending to write the stream.
 678     One case where the resulting size would have to be known is if the data has
 679     to be written to a piece of memory and the memory has to be allocated before
 680     writing to it (which is probably always the case when writing to a memory stream).
 681
 682     @library{wxbase}
 683     @category{streams}
 684 */
 685 class wxCountingOutputStream : public wxOutputStream
 686 {
 687 public:
 688     /**
 689         Creates a wxCountingOutputStream object.
 690     */
 691     wxCountingOutputStream();
 692
 693     /**
 694         Destructor.
 695     */
 696     virtual ~wxCountingOutputStream();
 697
 698     /**
 699         Returns the current size of the stream.
 700     */
 701     size_t GetSize() const;
 702 };
 703
 704
 705 /**
 706     @class wxBufferedInputStream
 707
 708     This stream acts as a cache. It caches the bytes read from the specified
 709     input stream (see wxFilterInputStream).
 710     It uses wxStreamBuffer and sets the default in-buffer size to 1024 bytes.
 711     This class may not be used without some other stream to read the data
 712     from (such as a file stream or a memory stream).
 713
 714     @library{wxbase}
 715     @category{streams}
 716
 717     @see wxStreamBuffer, wxInputStream, wxBufferedOutputStream
 718 */
 719 class wxBufferedInputStream : public wxFilterInputStream
 720 {
 721 public:
 722     /**
 723         Constructor using the provided buffer or default.
 724
 725         @param stream
 726             The associated low-level stream.
 727         @param buffer
 728             The buffer to use if non-@NULL. Notice that the ownership of this
 729             buffer is taken by the stream, i.e. it will delete it. If this
 730             parameter is @NULL a default 1KB buffer is used.
 731     */
 732     wxBufferedInputStream(wxInputStream& stream,
 733                           wxStreamBuffer *buffer = NULL);
 734
 735     /**
 736         Constructor allowing to specify the size of the buffer.
 737
 738         This is just a more convenient alternative to creating a wxStreamBuffer
 739         of the given size and using the other overloaded constructor of this
 740         class.
 741
 742         @param stream
 743             The associated low-level stream.
 744         @param bufsize
 745             The size of the buffer, in bytes.
 746
 747         @since 2.9.0
 748      */
 749     wxBufferedInputStream(wxInputStream& stream, size_t bufsize);
 750
 751     /**
 752         Destructor.
 753     */
 754     virtual ~wxBufferedInputStream();
 755 };
 756
 757
 758
 759
 760 /**
 761     Enumeration values used by wxFilterClassFactory.
 762 */
 763 enum wxStreamProtocolType
 764 {
 765     wxSTREAM_PROTOCOL,  //!< wxFileSystem protocol (should be only one).
 766     wxSTREAM_MIMETYPE,  //!< MIME types the stream handles.
 767     wxSTREAM_ENCODING,  //!< The HTTP Content-Encodings the stream handles.
 768     wxSTREAM_FILEEXT    //!< File extensions the stream handles.
 769 };
 770
 771 /**
 772     @class wxFilterClassFactory
 773
 774     Allows the creation of filter streams to handle compression formats such
 775     as gzip and bzip2.
 776
 777     For example, given a filename you can search for a factory that will
 778     handle it and create a stream to decompress it:
 779
 780     @code
 781         factory = wxFilterClassFactory::Find(filename, wxSTREAM_FILEEXT);
 782         if (factory)
 783             stream = factory->NewStream(new wxFFileInputStream(filename));
 784     @endcode
 785
 786     wxFilterClassFactory::Find can also search for a factory by MIME type,
 787     HTTP encoding or by wxFileSystem protocol.
 788     The available factories can be enumerated using wxFilterClassFactory::GetFirst()
 789     and wxFilterClassFactory::GetNext().
 790
 791     @library{wxbase}
 792     @category{streams}
 793
 794     @see wxFilterInputStream, wxFilterOutputStream, wxArchiveClassFactory,
 795         @ref overview_archive
 796 */
 797 class wxFilterClassFactory : public wxObject
 798 {
 799 public:
 800     /**
 801         Returns @true if this factory can handle the given protocol, MIME type, HTTP
 802         encoding or file extension.
 803
 804         When using @c wxSTREAM_FILEEXT for the second parameter, the first parameter
 805         can be a complete filename rather than just an extension.
 806     */
 807     bool CanHandle(const wxString& protocol,
 808                    wxStreamProtocolType type = wxSTREAM_PROTOCOL) const;
 809
 810     /**
 811         A static member that finds a factory that can handle a given protocol, MIME
 812         type, HTTP encoding or file extension. Returns a pointer to the class
 813         factory if found, or @NULL otherwise.
 814         It does not give away ownership of the factory.
 815
 816         When using @c wxSTREAM_FILEEXT for the second parameter, the first parameter
 817         can be a complete filename rather than just an extension.
 818     */
 819     static const wxFilterClassFactory* Find(const wxString& protocol,
 820                                             wxStreamProtocolType type = wxSTREAM_PROTOCOL);
 821
 822     //@{
 823     /**
 824         GetFirst and GetNext can be used to enumerate the available factories.
 825         For example, to list them:
 826
 827         @code
 828         wxString list;
 829         const wxFilterClassFactory *factory = wxFilterClassFactory::GetFirst();
 830
 831         while (factory) {
 832             list << factory->GetProtocol() << _T("\n");
 833             factory = factory->GetNext();
 834         }
 835         @endcode
 836
 837         GetFirst()/GetNext() return a pointer to a factory or @NULL if no more
 838         are available. They do not give away ownership of the factory.
 839     */
 840     static const wxFilterClassFactory* GetFirst();
 841     const wxFilterClassFactory* GetNext() const;
 842     //@}
 843
 844     /**
 845         Returns the wxFileSystem protocol supported by this factory.
 846         Equivalent to @code wxString(*GetProtocols()) @endcode.
 847     */
 848     wxString GetProtocol() const;
 849
 850     /**
 851         Returns the protocols, MIME types, HTTP encodings or file extensions
 852         supported by this factory, as an array of null terminated strings.
 853         It does not give away ownership of the array or strings.
 854
 855         For example, to list the file extensions a factory supports:
 856
 857         @code
 858         wxString list;
 859         const wxChar *const *p;
 860
 861         for (p = factory->GetProtocols(wxSTREAM_FILEEXT); *p; p++)
 862             list << *p << _T("\n");
 863         @endcode
 864     */
 865     virtual const wxChar * const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL) const = 0;
 866
 867     //@{
 868     /**
 869         Create a new input or output stream to decompress or compress a given stream.
 870
 871         If the parent stream is passed as a pointer then the new filter stream
 872         takes ownership of it. If it is passed by reference then it does not.
 873     */
 874     virtual wxFilterInputStream*  NewStream(wxInputStream& stream) const = 0;
 875     virtual wxFilterOutputStream* NewStream(wxOutputStream& stream) const = 0;
 876     virtual wxFilterInputStream*  NewStream(wxInputStream* stream) const = 0;
 877     virtual wxFilterOutputStream* NewStream(wxOutputStream* stream) const = 0;
 878     //@}
 879
 880     /**
 881         Remove the file extension of @a location if it is one of the file
 882         extensions handled by this factory.
 883     */
 884     wxString PopExtension(const wxString& location) const;
 885
 886     /**
 887         Adds this class factory to the list returned  by GetFirst()/GetNext().
 888
 889         It is not necessary to do this to use the filter streams. It is usually
 890         used when implementing streams, typically the implementation will
 891         add a static instance of its factory class.
 892
 893         It can also be used to change the order of a factory already in the list,
 894         bringing it to the front. This isn't a thread safe operation so can't be
 895         done when other threads are running that will be using the list.
 896
 897         The list does not take ownership of the factory.
 898     */
 899     void PushFront();
 900
 901     /**
 902         Removes this class factory from the list returned by GetFirst()/GetNext().
 903         Removing from the list isn't a thread safe operation so can't be done
 904         when other threads are running that will be using the list.
 905
 906         The list does not own the factories, so removing a factory does not delete it.
 907     */
 908     void Remove();
 909 };
 910
 911
 912
 913 /**
 914     @class wxFilterOutputStream
 915
 916     A filter stream has the capability of a normal stream but it can be placed
 917     on top of another stream. So, for example, it can compress, encrypt the data
 918     which are passed to it and write them to another stream.
 919
 920     @note
 921     The use of this class is exactly the same as of wxOutputStream.
 922     Only a constructor differs and it is documented below.
 923
 924     @library{wxbase}
 925     @category{streams}
 926
 927     @see wxFilterClassFactory, wxFilterInputStream
 928 */
 929 class wxFilterOutputStream : public wxOutputStream
 930 {
 931 public:
 932     //@{
 933     /**
 934         Initializes a "filter" stream.
 935
 936         If the parent stream is passed as a pointer then the new filter stream
 937         takes ownership of it. If it is passed by reference then it does not.
 938     */
 939     wxFilterOutputStream(wxOutputStream& stream);
 940     wxFilterOutputStream(wxOutputStream* stream);
 941     //@}
 942 };
 943
 944
 945
 946 /**
 947     @class wxFilterInputStream
 948
 949     A filter stream has the capability of a normal stream but it can be placed on
 950     top of another stream. So, for example, it can uncompress or decrypt the data which
 951     are read from another stream and pass it to the requester.
 952
 953     @note
 954     The interface of this class is the same as that of wxInputStream.
 955     Only a constructor differs and it is documented below.
 956
 957     @library{wxbase}
 958     @category{streams}
 959
 960     @see wxFilterClassFactory, wxFilterOutputStream
 961 */
 962 class wxFilterInputStream : public wxInputStream
 963 {
 964 public:
 965     //@{
 966     /**
 967         Initializes a "filter" stream.
 968
 969         If the parent stream is passed as a pointer then the new filter stream
 970         takes ownership of it. If it is passed by reference then it does not.
 971     */
 972     wxFilterInputStream(wxInputStream& stream);
 973     wxFilterInputStream(wxInputStream* stream);
 974     //@}
 975 };
 976
 977
 978
 979 /**
 980     @class wxBufferedOutputStream
 981
 982     This stream acts as a cache. It caches the bytes to be written to the specified
 983     output stream (See wxFilterOutputStream). The data is only written when the
 984     cache is full, when the buffered stream is destroyed or when calling SeekO().
 985
 986     This class may not be used without some other stream to write the data
 987     to (such as a file stream or a memory stream).
 988
 989     @library{wxbase}
 990     @category{streams}
 991
 992     @see wxStreamBuffer, wxOutputStream
 993 */
 994 class wxBufferedOutputStream : public wxFilterOutputStream
 995 {
 996 public:
 997     /**
 998         Constructor using the provided buffer or default.
 999
1000         @param stream
1001             The associated low-level stream.
1002         @param buffer
1003             The buffer to use if non-@NULL. Notice that the ownership of this
1004             buffer is taken by the stream, i.e. it will delete it. If this
1005             parameter is @NULL a default 1KB buffer is used.
1006     */
1007     wxBufferedOutputStream(wxOutputStream& stream,
1008                            wxStreamBuffer *buffer = NULL);
1009
1010     /**
1011         Constructor allowing to specify the size of the buffer.
1012
1013         This is just a more convenient alternative to creating a wxStreamBuffer
1014         of the given size and using the other overloaded constructor of this
1015         class.
1016
1017         @param stream
1018             The associated low-level stream.
1019         @param bufsize
1020             The size of the buffer, in bytes.
1021
1022         @since 2.9.0
1023      */
1024     wxBufferedOutputStream(wxOutputStream& stream, size_t bufsize);
1025
1026     /**
1027         Destructor. Calls Sync() and destroys the internal buffer.
1028     */
1029     virtual ~wxBufferedOutputStream();
1030
1031     /**
1032         Calls Sync() and changes the stream position.
1033     */
1034     virtual wxFileOffset SeekO(wxFileOffset pos, wxSeekMode mode = wxFromStart);
1035
1036     /**
1037         Flushes the buffer and calls Sync() on the parent stream.
1038     */
1039     virtual void Sync();
1040 };
1041
1042