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