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