interface/wx/stream.h

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