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 size of the stream.
 757     */
 758     size_t GetSize() const;
 759 };
 760
 761
 762 /**
 763     @class wxBufferedInputStream
 764
 765     This stream acts as a cache. It caches the bytes read from the specified
 766     input stream (see wxFilterInputStream).
 767     It uses wxStreamBuffer and sets the default in-buffer size to 1024 bytes.
 768     This class may not be used without some other stream to read the data
 769     from (such as a file stream or a memory stream).
 770
 771     @library{wxbase}
 772     @category{streams}
 773
 774     @see wxStreamBuffer, wxInputStream, wxBufferedOutputStream
 775 */
 776 class wxBufferedInputStream : public wxFilterInputStream
 777 {
 778 public:
 779     /**
 780         Constructor using the provided buffer or default.
 781
 782         @param stream
 783             The associated low-level stream.
 784         @param buffer
 785             The buffer to use if non-@NULL. Notice that the ownership of this
 786             buffer is taken by the stream, i.e. it will delete it. If this
 787             parameter is @NULL a default 1KB buffer is used.
 788     */
 789     wxBufferedInputStream(wxInputStream& stream,
 790                           wxStreamBuffer *buffer = NULL);
 791
 792     /**
 793         Constructor allowing to specify the size of the buffer.
 794
 795         This is just a more convenient alternative to creating a wxStreamBuffer
 796         of the given size and using the other overloaded constructor of this
 797         class.
 798
 799         @param stream
 800             The associated low-level stream.
 801         @param bufsize
 802             The size of the buffer, in bytes.
 803
 804         @since 2.9.0
 805      */
 806     wxBufferedInputStream(wxInputStream& stream, size_t bufsize);
 807
 808     /**
 809         Destructor.
 810     */
 811     virtual ~wxBufferedInputStream();
 812 };
 813
 814
 815
 816
 817 /**
 818     Enumeration values used by wxFilterClassFactory.
 819 */
 820 enum wxStreamProtocolType
 821 {
 822     wxSTREAM_PROTOCOL,  //!< wxFileSystem protocol (should be only one).
 823     wxSTREAM_MIMETYPE,  //!< MIME types the stream handles.
 824     wxSTREAM_ENCODING,  //!< The HTTP Content-Encodings the stream handles.
 825     wxSTREAM_FILEEXT    //!< File extensions the stream handles.
 826 };
 827
 828 /**
 829     @class wxFilterClassFactory
 830
 831     Allows the creation of filter streams to handle compression formats such
 832     as gzip and bzip2.
 833
 834     For example, given a filename you can search for a factory that will
 835     handle it and create a stream to decompress it:
 836
 837     @code
 838         factory = wxFilterClassFactory::Find(filename, wxSTREAM_FILEEXT);
 839         if (factory)
 840             stream = factory->NewStream(new wxFFileInputStream(filename));
 841     @endcode
 842
 843     wxFilterClassFactory::Find can also search for a factory by MIME type,
 844     HTTP encoding or by wxFileSystem protocol.
 845     The available factories can be enumerated using wxFilterClassFactory::GetFirst()
 846     and wxFilterClassFactory::GetNext().
 847
 848     @library{wxbase}
 849     @category{streams}
 850
 851     @see wxFilterInputStream, wxFilterOutputStream, wxArchiveClassFactory,
 852         @ref overview_archive
 853 */
 854 class wxFilterClassFactory : public wxObject
 855 {
 856 public:
 857     /**
 858         Returns @true if this factory can handle the given protocol, MIME type, HTTP
 859         encoding or file extension.
 860
 861         When using @c wxSTREAM_FILEEXT for the second parameter, the first parameter
 862         can be a complete filename rather than just an extension.
 863     */
 864     bool CanHandle(const wxString& protocol,
 865                    wxStreamProtocolType type = wxSTREAM_PROTOCOL) const;
 866
 867     /**
 868         A static member that finds a factory that can handle a given protocol, MIME
 869         type, HTTP encoding or file extension. Returns a pointer to the class
 870         factory if found, or @NULL otherwise.
 871         It does not give away ownership of the factory.
 872
 873         When using @c wxSTREAM_FILEEXT for the second parameter, the first parameter
 874         can be a complete filename rather than just an extension.
 875     */
 876     static const wxFilterClassFactory* Find(const wxString& protocol,
 877                                             wxStreamProtocolType type = wxSTREAM_PROTOCOL);
 878
 879     //@{
 880     /**
 881         GetFirst and GetNext can be used to enumerate the available factories.
 882         For example, to list them:
 883
 884         @code
 885         wxString list;
 886         const wxFilterClassFactory *factory = wxFilterClassFactory::GetFirst();
 887
 888         while (factory) {
 889             list << factory->GetProtocol() << wxT("\n");
 890             factory = factory->GetNext();
 891         }
 892         @endcode
 893
 894         GetFirst()/GetNext() return a pointer to a factory or @NULL if no more
 895         are available. They do not give away ownership of the factory.
 896     */
 897     static const wxFilterClassFactory* GetFirst();
 898     const wxFilterClassFactory* GetNext() const;
 899     //@}
 900
 901     /**
 902         Returns the wxFileSystem protocol supported by this factory.
 903         Equivalent to @code wxString(*GetProtocols()) @endcode.
 904     */
 905     wxString GetProtocol() const;
 906
 907     /**
 908         Returns the protocols, MIME types, HTTP encodings or file extensions
 909         supported by this factory, as an array of null terminated strings.
 910         It does not give away ownership of the array or strings.
 911
 912         For example, to list the file extensions a factory supports:
 913
 914         @code
 915         wxString list;
 916         const wxChar *const *p;
 917
 918         for (p = factory->GetProtocols(wxSTREAM_FILEEXT); *p; p++)
 919             list << *p << wxT("\n");
 920         @endcode
 921     */
 922     virtual const wxChar * const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL) const = 0;
 923
 924     //@{
 925     /**
 926         Create a new input or output stream to decompress or compress a given stream.
 927
 928         If the parent stream is passed as a pointer then the new filter stream
 929         takes ownership of it. If it is passed by reference then it does not.
 930     */
 931     virtual wxFilterInputStream*  NewStream(wxInputStream& stream) const = 0;
 932     virtual wxFilterOutputStream* NewStream(wxOutputStream& stream) const = 0;
 933     virtual wxFilterInputStream*  NewStream(wxInputStream* stream) const = 0;
 934     virtual wxFilterOutputStream* NewStream(wxOutputStream* stream) const = 0;
 935     //@}
 936
 937     /**
 938         Remove the file extension of @a location if it is one of the file
 939         extensions handled by this factory.
 940     */
 941     wxString PopExtension(const wxString& location) const;
 942
 943     /**
 944         Adds this class factory to the list returned  by GetFirst()/GetNext().
 945
 946         It is not necessary to do this to use the filter streams. It is usually
 947         used when implementing streams, typically the implementation will
 948         add a static instance of its factory class.
 949
 950         It can also be used to change the order of a factory already in the list,
 951         bringing it to the front. This isn't a thread safe operation so can't be
 952         done when other threads are running that will be using the list.
 953
 954         The list does not take ownership of the factory.
 955     */
 956     void PushFront();
 957
 958     /**
 959         Removes this class factory from the list returned by GetFirst()/GetNext().
 960         Removing from the list isn't a thread safe operation so can't be done
 961         when other threads are running that will be using the list.
 962
 963         The list does not own the factories, so removing a factory does not delete it.
 964     */
 965     void Remove();
 966 };
 967
 968
 969
 970 /**
 971     @class wxFilterOutputStream
 972
 973     A filter stream has the capability of a normal stream but it can be placed
 974     on top of another stream. So, for example, it can compress, encrypt the data
 975     which are passed to it and write them to another stream.
 976
 977     @note
 978     The use of this class is exactly the same as of wxOutputStream.
 979     Only a constructor differs and it is documented below.
 980
 981     @library{wxbase}
 982     @category{streams}
 983
 984     @see wxFilterClassFactory, wxFilterInputStream
 985 */
 986 class wxFilterOutputStream : public wxOutputStream
 987 {
 988 public:
 989     //@{
 990     /**
 991         Initializes a "filter" stream.
 992
 993         If the parent stream is passed as a pointer then the new filter stream
 994         takes ownership of it. If it is passed by reference then it does not.
 995     */
 996     wxFilterOutputStream(wxOutputStream& stream);
 997     wxFilterOutputStream(wxOutputStream* stream);
 998     //@}
 999 };
1000
1001
1002
1003 /**
1004     @class wxFilterInputStream
1005
1006     A filter stream has the capability of a normal stream but it can be placed on
1007     top of another stream. So, for example, it can uncompress or decrypt the data which
1008     are read from another stream and pass it to the requester.
1009
1010     @note
1011     The interface of this class is the same as that of wxInputStream.
1012     Only a constructor differs and it is documented below.
1013
1014     @library{wxbase}
1015     @category{streams}
1016
1017     @see wxFilterClassFactory, wxFilterOutputStream
1018 */
1019 class wxFilterInputStream : public wxInputStream
1020 {
1021 public:
1022     //@{
1023     /**
1024         Initializes a "filter" stream.
1025
1026         If the parent stream is passed as a pointer then the new filter stream
1027         takes ownership of it. If it is passed by reference then it does not.
1028     */
1029     wxFilterInputStream(wxInputStream& stream);
1030     wxFilterInputStream(wxInputStream* stream);
1031     //@}
1032 };
1033
1034
1035
1036 /**
1037     @class wxBufferedOutputStream
1038
1039     This stream acts as a cache. It caches the bytes to be written to the specified
1040     output stream (See wxFilterOutputStream). The data is only written when the
1041     cache is full, when the buffered stream is destroyed or when calling SeekO().
1042
1043     This class may not be used without some other stream to write the data
1044     to (such as a file stream or a memory stream).
1045
1046     @library{wxbase}
1047     @category{streams}
1048
1049     @see wxStreamBuffer, wxOutputStream
1050 */
1051 class wxBufferedOutputStream : public wxFilterOutputStream
1052 {
1053 public:
1054     /**
1055         Constructor using the provided buffer or default.
1056
1057         @param stream
1058             The associated low-level stream.
1059         @param buffer
1060             The buffer to use if non-@NULL. Notice that the ownership of this
1061             buffer is taken by the stream, i.e. it will delete it. If this
1062             parameter is @NULL a default 1KB buffer is used.
1063     */
1064     wxBufferedOutputStream(wxOutputStream& stream,
1065                            wxStreamBuffer *buffer = NULL);
1066
1067     /**
1068         Constructor allowing to specify the size of the buffer.
1069
1070         This is just a more convenient alternative to creating a wxStreamBuffer
1071         of the given size and using the other overloaded constructor of this
1072         class.
1073
1074         @param stream
1075             The associated low-level stream.
1076         @param bufsize
1077             The size of the buffer, in bytes.
1078
1079         @since 2.9.0
1080      */
1081     wxBufferedOutputStream(wxOutputStream& stream, size_t bufsize);
1082
1083     /**
1084         Destructor. Calls Sync() and destroys the internal buffer.
1085     */
1086     virtual ~wxBufferedOutputStream();
1087
1088     /**
1089         Calls Sync() and changes the stream position.
1090     */
1091     virtual wxFileOffset SeekO(wxFileOffset pos, wxSeekMode mode = wxFromStart);
1092
1093     /**
1094         Flushes the buffer and calls Sync() on the parent stream.
1095     */
1096     virtual void Sync();
1097 };
1098
1099
1100 /**
1101     @class wxWrapperInputStream
1102
1103     A wrapper input stream is a kind of filter stream which forwards all the
1104     operations to its base stream. This is useful to build utility classes such
1105     as wxFSInputStream.
1106
1107     @note
1108     The interface of this class is the same as that of wxInputStream.
1109     Only a constructor differs and it is documented below.
1110
1111     @library{wxbase}
1112     @category{streams}
1113
1114     @see wxFSInputStream, wxFilterInputStream
1115     @since 2.9.4
1116 */
1117 class wxWrapperInputStream : public wxFilterInputStream
1118 {
1119 public:
1120     //@{
1121     /**
1122         Initializes a wrapper stream.
1123
1124         If the parent stream is passed as a pointer then the new wrapper stream
1125         takes ownership of it. If it is passed by reference then it does not.
1126     */
1127     wxWrapperInputStream(wxInputStream& stream);
1128     wxWrapperInputStream(wxInputStream* stream);
1129     //@}
1130
1131 protected:
1132     /**
1133         Default constructor, use InitParentStream() to finish initialization.
1134
1135         This constructor can be used by the derived classes from their own
1136         constructors when the parent stream can't be specified immediately.
1137         The derived class must call InitParentStream() later to do it.
1138      */
1139     wxWrapperInputStream();
1140
1141     //@{
1142     /**
1143         Set up the wrapped stream for an object initialized using the default
1144         constructor.
1145
1146         The ownership logic is the same as for the non-default constructor,
1147         i.e. this object takes ownership of the stream if it's passed by
1148         pointer but not if it's passed by reference.
1149      */
1150     void InitParentStream(wxInputStream& stream);
1151     void InitParentStream(wxInputStream* stream);
1152     //@}
1153 };