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