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