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     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(void* start, void* end, bool takeOwnership = false);
 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         @deprecated use GetStream() instead
 357     */
 358     wxStreamBase* Stream();
 359
 360     /**
 361         Gets the current position in the stream. This position is calculated from
 362         the @e real position in the stream and from the internal buffer position: so
 363         it gives you the position in the @e real stream counted from the start of
 364         the stream.
 365
 366         @return Returns the current position in the stream if possible,
 367                 wxInvalidOffset in the other case.
 368     */
 369     virtual wxFileOffset Tell() const;
 370
 371     /**
 372         Truncates the buffer to the current position.
 373
 374         @note Truncate() cannot be used to enlarge the buffer. This is
 375               usually not needed since the buffer expands automatically.
 376     */
 377     void Truncate();
 378
 379     /**
 380         Writes a block of the specified size using data of buffer.
 381         The data are cached in a buffer before being sent in one block to the stream.
 382     */
 383     virtual size_t Write(const void* buffer, size_t size);
 384
 385     /**
 386         See Read().
 387     */
 388     size_t Write(wxStreamBuffer* buffer);
 389 };
 390
 391
 392
 393 /**
 394     @class wxOutputStream
 395
 396     wxOutputStream is an abstract base class which may not be used directly.
 397
 398     @library{wxbase}
 399     @category{streams}
 400 */
 401 class wxOutputStream : public wxStreamBase
 402 {
 403 public:
 404     /**
 405         Creates a dummy wxOutputStream object.
 406     */
 407     wxOutputStream();
 408
 409     /**
 410         Destructor.
 411     */
 412     virtual ~wxOutputStream();
 413
 414     /**
 415         Closes the stream, returning @false if an error occurs.
 416         The stream is closed implicitly in the destructor if Close() is not
 417         called explicitly.
 418
 419         If this stream wraps another stream or some other resource such
 420         as a file, then the underlying resource is closed too if it is owned
 421         by this stream, or left open otherwise.
 422     */
 423     virtual bool Close();
 424
 425     /**
 426         Returns the number of bytes written during the last Write().
 427         It may return 0 even if there is no error on the stream if it is
 428         only temporarily impossible to write to it.
 429     */
 430     virtual size_t LastWrite() const;
 431
 432     /**
 433         Puts the specified character in the output queue and increments the
 434         stream position.
 435     */
 436     void PutC(char c);
 437
 438     /**
 439         Changes the stream current position.
 440
 441         @param pos
 442             Offset to seek to.
 443         @param mode
 444             One of wxFromStart, wxFromEnd, wxFromCurrent.
 445
 446         @return The new stream position or wxInvalidOffset on error.
 447     */
 448     virtual wxFileOffset SeekO(wxFileOffset pos, wxSeekMode mode = wxFromStart);
 449
 450     /**
 451         Returns the current stream position.
 452     */
 453     virtual wxFileOffset TellO() const;
 454
 455     /**
 456         Writes up to the specified amount of bytes using the data of buffer.
 457         Note that not all data can always be written so you must check the number
 458         of bytes really written to the stream using LastWrite() when this function
 459         returns.
 460
 461         In some cases (for example a write end of a pipe which is currently full)
 462         it is even possible that there is no errors and zero bytes have been written.
 463         This function returns a reference on the current object, so the user can
 464         test any states of the stream right away.
 465     */
 466     virtual wxOutputStream& Write(const void* buffer, size_t size);
 467
 468     /**
 469         Reads data from the specified input stream and stores them
 470         in the current stream. The data is read until an error is raised
 471         by one of the two streams.
 472     */
 473     wxOutputStream& Write(wxInputStream& stream_in);
 474 };
 475
 476
 477 /**
 478     Enumeration values used by wxFilterClassFactory.
 479 */
 480 enum wxStreamProtocolType
 481 {
 482     wxSTREAM_PROTOCOL,  //!< wxFileSystem protocol (should be only one).
 483     wxSTREAM_MIMETYPE,  //!< MIME types the stream handles.
 484     wxSTREAM_ENCODING,  //!< The HTTP Content-Encodings the stream handles.
 485     wxSTREAM_FILEEXT    //!< File extensions the stream handles.
 486 };
 487
 488
 489 /**
 490     @class wxFilterClassFactory
 491
 492     Allows the creation of filter streams to handle compression formats such
 493     as gzip and bzip2.
 494
 495     For example, given a filename you can search for a factory that will
 496     handle it and create a stream to decompress it:
 497
 498     @code
 499         factory = wxFilterClassFactory::Find(filename, wxSTREAM_FILEEXT);
 500         if (factory)
 501             stream = factory-NewStream(new wxFFileInputStream(filename));
 502     @endcode
 503
 504     wxFilterClassFactory::Find can also search for a factory by MIME type,
 505     HTTP encoding or by wxFileSystem protocol.
 506     The available factories can be enumerated using wxFilterClassFactory::GetFirst()
 507     and wxFilterClassFactory::GetNext().
 508
 509     @library{wxbase}
 510     @category{streams}
 511
 512     @see wxFilterInputStream, wxFilterOutputStream, wxArchiveClassFactory,
 513         @ref overview_archive
 514 */
 515 class wxFilterClassFactory : public wxObject
 516 {
 517 public:
 518     /**
 519         Returns @true if this factory can handle the given protocol, MIME type, HTTP
 520         encoding or file extension.
 521
 522         When using @c wxSTREAM_FILEEXT for the second parameter, the first parameter
 523         can be a complete filename rather than just an extension.
 524     */
 525     bool CanHandle(const wxString& protocol,
 526                    wxStreamProtocolType type = wxSTREAM_PROTOCOL) const;
 527
 528     /**
 529         A static member that finds a factory that can handle a given protocol, MIME
 530         type, HTTP encoding or file extension. Returns a pointer to the class
 531         factory if found, or @NULL otherwise.
 532         It does not give away ownership of the factory.
 533
 534         When using @c wxSTREAM_FILEEXT for the second parameter, the first parameter
 535         can be a complete filename rather than just an extension.
 536     */
 537     static const wxFilterClassFactory* Find(const wxString& protocol,
 538                                             wxStreamProtocolType type = wxSTREAM_PROTOCOL);
 539
 540     //@{
 541     /**
 542         GetFirst and GetNext can be used to enumerate the available factories.
 543         For example, to list them:
 544
 545         @code
 546         wxString list;
 547         const wxFilterClassFactory *factory = wxFilterClassFactory::GetFirst();
 548
 549         while (factory) {
 550             list << factory->GetProtocol() << _T("\n");
 551             factory = factory->GetNext();
 552         }
 553         @endcode
 554
 555         GetFirst()/GetNext() return a pointer to a factory or @NULL if no more
 556         are available. They do not give away ownership of the factory.
 557     */
 558     static const wxFilterClassFactory* GetFirst() const;
 559     const wxFilterClassFactory* GetNext() const;
 560     //@}
 561
 562     /**
 563         Returns the wxFileSystem protocol supported by this factory.
 564         Equivalent to @code wxString(*GetProtocols()) @endcode.
 565     */
 566     wxString GetProtocol() const;
 567
 568     /**
 569         Returns the protocols, MIME types, HTTP encodings or file extensions
 570         supported by this factory, as an array of null terminated strings.
 571         It does not give away ownership of the array or strings.
 572
 573         For example, to list the file extensions a factory supports:
 574
 575         @code
 576         wxString list;
 577         const wxChar *const *p;
 578
 579         for (p = factory->GetProtocols(wxSTREAM_FILEEXT); *p; p++)
 580             list << *p << _T("\n");
 581         @endcode
 582     */
 583     virtual const wxChar * const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL) const = 0;
 584
 585     //@{
 586     /**
 587         Create a new input or output stream to decompress or compress a given stream.
 588
 589         If the parent stream is passed as a pointer then the new filter stream
 590         takes ownership of it. If it is passed by reference then it does not.
 591     */
 592     wxFilterInputStream*  NewStream(wxInputStream& stream) const;
 593     wxFilterOutputStream* NewStream(wxOutputStream& stream) const;
 594     wxFilterInputStream*  NewStream(wxInputStream* stream) const;
 595     wxFilterOutputStream* NewStream(wxOutputStream* stream) const;
 596     //@}
 597
 598     /**
 599         Remove the file extension of @a location if it is one of the file
 600         extensions handled by this factory.
 601     */
 602     wxString PopExtension(const wxString& location) const;
 603
 604     /**
 605         Adds this class factory to the list returned  by GetFirst()/GetNext().
 606
 607         It is not necessary to do this to use the filter streams. It is usually
 608         used when implementing streams, typically the implementation will
 609         add a static instance of its factory class.
 610
 611         It can also be used to change the order of a factory already in the list,
 612         bringing it to the front. This isn't a thread safe operation so can't be
 613         done when other threads are running that will be using the list.
 614
 615         The list does not take ownership of the factory.
 616     */
 617     void PushFront();
 618
 619     /**
 620         Removes this class factory from the list returned by GetFirst()/GetNext().
 621         Removing from the list isn't a thread safe operation so can't be done
 622         when other threads are running that will be using the list.
 623
 624         The list does not own the factories, so removing a factory does not delete it.
 625     */
 626     void Remove();
 627 };
 628
 629
 630
 631 /**
 632     @class wxFilterOutputStream
 633
 634     A filter stream has the capability of a normal stream but it can be placed
 635     on top of another stream. So, for example, it can compress, encrypt the data
 636     which are passed to it and write them to another stream.
 637
 638     @note
 639     The use of this class is exactly the same as of wxOutputStream.
 640     Only a constructor differs and it is documented below.
 641
 642     @library{wxbase}
 643     @category{streams}
 644
 645     @see wxFilterClassFactory, wxFilterInputStream
 646 */
 647 class wxFilterOutputStream : public wxOutputStream
 648 {
 649 public:
 650     //@{
 651     /**
 652         Initializes a "filter" stream.
 653
 654         If the parent stream is passed as a pointer then the new filter stream
 655         takes ownership of it. If it is passed by reference then it does not.
 656     */
 657     wxFilterOutputStream(wxOutputStream& stream);
 658     wxFilterOutputStream(wxOutputStream* stream);
 659     //@}
 660 };
 661
 662
 663
 664 /**
 665     @class wxFilterInputStream
 666
 667     A filter stream has the capability of a normal stream but it can be placed on
 668     top of another stream. So, for example, it can uncompress or decrypt the data which
 669     are read from another stream and pass it to the requester.
 670
 671     @note
 672     The interface of this class is the same as that of wxInputStream.
 673     Only a constructor differs and it is documented below.
 674
 675     @library{wxbase}
 676     @category{streams}
 677
 678     @see wxFilterClassFactory, wxFilterOutputStream
 679 */
 680 class wxFilterInputStream : public wxInputStream
 681 {
 682 public:
 683     //@{
 684     /**
 685         Initializes a "filter" stream.
 686
 687         If the parent stream is passed as a pointer then the new filter stream
 688         takes ownership of it. If it is passed by reference then it does not.
 689     */
 690     wxFilterInputStream(wxInputStream& stream);
 691     wxFilterInputStream(wxInputStream* stream);
 692     //@}
 693 };
 694
 695
 696
 697 /**
 698     @class wxBufferedOutputStream
 699
 700     This stream acts as a cache. It caches the bytes to be written to the specified
 701     output stream (See wxFilterOutputStream). The data is only written when the
 702     cache is full, when the buffered stream is destroyed or when calling SeekO().
 703
 704     This class may not be used without some other stream to write the data
 705     to (such as a file stream or a memory stream).
 706
 707     @library{wxbase}
 708     @category{streams}
 709
 710     @see wxStreamBuffer, wxOutputStream
 711 */
 712 class wxBufferedOutputStream : public wxFilterOutputStream
 713 {
 714 public:
 715     /**
 716         Constructor using the provided buffer or default.
 717
 718         @param stream
 719             The associated low-level stream.
 720         @param buffer
 721             The buffer to use if non-@NULL. Notice that the ownership of this
 722             buffer is taken by the stream, i.e. it will delete it. If this
 723             parameter is @NULL a default 1KB buffer is used.
 724     */
 725     wxBufferedOutputStream(wxOutputStream& stream,
 726                            wxStreamBuffer *buffer = NULL);
 727
 728     /**
 729         Constructor allowing to specify the size of the buffer.
 730
 731         This is just a more convenient alternative to creating a wxStreamBuffer
 732         of the given size and using the other overloaded constructor of this
 733         class.
 734
 735         @param stream
 736             The associated low-level stream.
 737         @param bufsize
 738             The size of the buffer, in bytes.
 739
 740         @since 2.9.0
 741      */
 742     wxBufferedOutputStream(wxOutputStream& stream, size_t bufsize);
 743
 744     /**
 745         Destructor. Calls Sync() and destroys the internal buffer.
 746     */
 747     virtual ~wxBufferedOutputStream();
 748
 749     /**
 750         Calls Sync() and changes the stream position.
 751     */
 752     virtual wxFileOffset SeekO(wxFileOffset pos, wxSeekMode mode = wxFromStart);
 753
 754     /**
 755         Flushes the buffer and calls Sync() on the parent stream.
 756     */
 757     virtual void Sync();
 758 };
 759
 760
 761
 762 /**
 763     @class wxInputStream
 764
 765     wxInputStream is an abstract base class which may not be used directly.
 766
 767     @library{wxbase}
 768     @category{streams}
 769 */
 770 class wxInputStream : public wxStreamBase
 771 {
 772 public:
 773     /**
 774         Creates a dummy input stream.
 775     */
 776     wxInputStream();
 777
 778     /**
 779         Destructor.
 780     */
 781     virtual ~wxInputStream();
 782
 783     /**
 784         Returns @true if some data is available in the stream right now, so that
 785         calling Read() wouldn't block.
 786     */
 787     virtual bool CanRead() const;
 788
 789     /**
 790         Returns @true after an attempt has been made to read past the end of the
 791         stream.
 792     */
 793     virtual bool Eof() const;
 794
 795     /**
 796         Returns the first character in the input queue and removes it,
 797         blocking until it appears if necessary.
 798
 799         On success returns a value between 0 - 255; on end of file returns @c wxEOF.
 800     */
 801     int GetC();
 802
 803     /**
 804         Returns the last number of bytes read.
 805     */
 806     virtual size_t LastRead() const;
 807
 808     /**
 809         Returns the first character in the input queue without removing it.
 810     */
 811     virtual char Peek();
 812
 813     /**
 814         Reads the specified amount of bytes and stores the data in buffer.
 815
 816         @warning
 817         The buffer absolutely needs to have at least the specified size.
 818
 819         @return This function returns a reference on the current object, so the
 820                 user can test any states of the stream right away.
 821     */
 822     virtual wxInputStream& Read(void* buffer, size_t size);
 823
 824     /**
 825         Reads data from the input queue and stores it in the specified output stream.
 826         The data is read until an error is raised by one of the two streams.
 827
 828         @return This function returns a reference on the current object, so the
 829                 user can test any states of the stream right away.
 830     */
 831     wxInputStream& Read(wxOutputStream& stream_out);
 832
 833     /**
 834         Changes the stream current position.
 835
 836         @param pos
 837             Offset to seek to.
 838         @param mode
 839             One of wxFromStart, wxFromEnd, wxFromCurrent.
 840
 841         @return The new stream position or wxInvalidOffset on error.
 842     */
 843     virtual wxFileOffset SeekI(wxFileOffset pos, wxSeekMode mode = wxFromStart);
 844
 845     /**
 846         Returns the current stream position.
 847     */
 848     virtual wxFileOffset TellI() const;
 849
 850     /**
 851         This function is only useful in read mode.
 852         It is the manager of the "Write-Back" buffer. This buffer acts like a
 853         temporary buffer where data which has to be read during the next read IO
 854         call are put. This is useful when you get a big block of data which you
 855         didn't want to read: you can replace them at the top of the input queue
 856         by this way.
 857
 858         Be very careful about this call in connection with calling SeekI() on
 859         the same stream. Any call to SeekI() will invalidate any previous call
 860         to this method (otherwise you could SeekI() to one position, "unread" a
 861         few bytes there, SeekI() to another position and data would be either
 862         lost or corrupted).
 863
 864         @return Returns the amount of bytes saved in the Write-Back buffer.
 865     */
 866     size_t Ungetch(const void* buffer, size_t size);
 867
 868     /**
 869         This function acts like the previous one except that it takes only one
 870         character: it is sometimes shorter to use than the generic function.
 871     */
 872     bool Ungetch(char c);
 873 };
 874
 875
 876 /**
 877     These enumeration values are returned by various functions in the context
 878     of wxStream classes.
 879 */
 880 enum wxStreamError
 881 {
 882     wxSTREAM_NO_ERROR = 0,      //!< No error occurred.
 883     wxSTREAM_EOF,               //!< EOF reached in Read() or similar.
 884     wxSTREAM_WRITE_ERROR,       //!< generic write error on the last write call.
 885     wxSTREAM_READ_ERROR         //!< generic read error on the last read call.
 886 };
 887
 888 /**
 889     @class wxStreamBase
 890
 891     This class is the base class of most stream related classes in wxWidgets.
 892     It must not be used directly.
 893
 894     @library{wxbase}
 895     @category{streams}
 896
 897     @see wxStreamBuffer
 898 */
 899 class wxStreamBase
 900 {
 901 public:
 902     /**
 903         Creates a dummy stream object. It doesn't do anything.
 904     */
 905     wxStreamBase();
 906
 907     /**
 908         Destructor.
 909     */
 910     virtual ~wxStreamBase();
 911
 912     /**
 913         This function returns the last error.
 914     */
 915     wxStreamError GetLastError() const;
 916
 917     /**
 918         Returns the length of the stream in bytes. If the length cannot be
 919         determined (this is always the case for socket streams for example),
 920         returns @c wxInvalidOffset.
 921
 922         @since 2.5.4
 923     */
 924     virtual wxFileOffset GetLength() const;
 925
 926     /**
 927         This function returns the size of the stream.
 928         For example, for a file it is the size of the file.
 929
 930         @warning
 931         There are streams which do not have size by definition, such as socket
 932         streams. In that cases, GetSize returns 0 so you should always test its
 933         return value.
 934     */
 935     virtual size_t GetSize() const;
 936
 937     /**
 938         Returns @true if no error occurred on the stream.
 939
 940         @see GetLastError()
 941     */
 942     virtual bool IsOk() const;
 943
 944     /**
 945         Returns @true if the streams supports seeking to arbitrary offsets.
 946     */
 947     virtual bool IsSeekable() const;
 948
 949     /**
 950         Internal function. It is called when the stream wants to read data of the
 951         specified size. It should return the size that was actually read.
 952     */
 953     size_t OnSysRead(void* buffer, size_t bufsize);
 954
 955     /**
 956         See OnSysRead().
 957     */
 958     size_t OnSysWrite(const void* buffer, size_t bufsize);
 959
 960
 961 protected:
 962
 963     /**
 964         Internal function.
 965         It is called when the stream needs to change the current position.
 966     */
 967     virtual wxFileOffset OnSysSeek(wxFileOffset pos, wxSeekMode mode);
 968
 969     /**
 970         Internal function.
 971         It is called when the stream needs to know the real position.
 972     */
 973     virtual wxFileOffset OnSysTell() const;
 974 };
 975