interface/wx/stream.h

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