interface/stream.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        stream.h
   3 // Purpose:     interface of wxCountingOutputStream
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxCountingOutputStream
  11     @wxheader{stream.h}
  12
  13     wxCountingOutputStream is a specialized output stream which does not write any
  14     data anywhere,
  15     instead it counts how many bytes would get written if this were a normal
  16     stream. This
  17     can sometimes be useful or required if some data gets serialized to a stream or
  18     compressed
  19     by using stream compression and thus the final size of the stream cannot be
  20     known other
  21     than pretending to write the stream. One case where the resulting size would
  22     have to be
  23     known is if the data has to be written to a piece of memory and the memory has
  24     to be
  25     allocated before writing to it (which is probably always the case when writing
  26     to a
  27     memory stream).
  28
  29     @library{wxbase}
  30     @category{streams}
  31 */
  32 class wxCountingOutputStream : public wxOutputStream
  33 {
  34 public:
  35     /**
  36         Creates a wxCountingOutputStream object.
  37     */
  38     wxCountingOutputStream();
  39
  40     /**
  41         Destructor.
  42     */
  43     ~wxCountingOutputStream();
  44
  45     /**
  46         Returns the current size of the stream.
  47     */
  48     size_t GetSize() const;
  49 };
  50
  51
  52
  53 /**
  54     @class wxBufferedInputStream
  55     @wxheader{stream.h}
  56
  57     This stream acts as a cache. It caches the bytes read from the specified
  58     input stream (See wxFilterInputStream).
  59     It uses wxStreamBuffer and sets the default in-buffer size to 1024 bytes.
  60     This class may not be used without some other stream to read the data
  61     from (such as a file stream or a memory stream).
  62
  63     @library{wxbase}
  64     @category{streams}
  65
  66     @see wxStreamBuffer, wxInputStream, wxBufferedOutputStream
  67 */
  68 class wxBufferedInputStream : public wxFilterInputStream
  69 {
  70 public:
  71
  72 };
  73
  74
  75
  76 /**
  77     @class wxStreamBuffer
  78     @wxheader{stream.h}
  79
  80
  81     @library{wxbase}
  82     @category{streams}
  83
  84     @see wxStreamBase
  85 */
  86 class wxStreamBuffer
  87 {
  88 public:
  89     //@{
  90     /**
  91         Constructor. It initializes the stream buffer with the data of the specified
  92         stream buffer. The new stream buffer has the same attributes, size, position
  93         and they share the same buffer. This will cause problems if the stream to
  94         which the stream buffer belong is destroyed and the newly cloned stream
  95         buffer continues to be used, trying to call functions in the (destroyed)
  96         stream. It is advised to use this feature only in very local area of the
  97         program.
  98
  99         @see @ref setbufferio() wxStreamBuffer:SetBufferIO
 100     */
 101     wxStreamBuffer(wxStreamBase& stream, BufMode mode);
 102     wxStreamBuffer(BufMode mode);
 103     wxStreamBuffer(const wxStreamBuffer& buffer);
 104     //@}
 105
 106     /**
 107         Destructor. It finalizes all IO calls and frees all internal buffers if
 108         necessary.
 109     */
 110     wxStreamBuffer();
 111
 112     /**
 113         Fill the IO buffer.
 114     */
 115     bool FillBuffer();
 116
 117     /**
 118         Toggles the fixed flag. Usually this flag is toggled at the same time as
 119         @e flushable. This flag allows (when it has the @false value) or forbids
 120         (when it has the @true value) the stream buffer to resize dynamically the IO
 121         buffer.
 122
 123         @see SetBufferIO()
 124     */
 125     void Fixed(bool fixed);
 126
 127     /**
 128         Flushes the IO buffer.
 129     */
 130     bool FlushBuffer();
 131
 132     /**
 133         Toggles the flushable flag. If @a flushable is disabled, no data are sent
 134         to the parent stream.
 135     */
 136     void Flushable(bool flushable);
 137
 138     /**
 139         Returns a pointer on the end of the stream buffer.
 140     */
 141     void* GetBufferEnd() const;
 142
 143     /**
 144         Returns a pointer on the current position of the stream buffer.
 145     */
 146     void* GetBufferPos() const;
 147
 148     /**
 149         Returns the size of the buffer.
 150     */
 151     size_t GetBufferSize() const;
 152
 153     /**
 154         Returns a pointer on the start of the stream buffer.
 155     */
 156     void* GetBufferStart() const;
 157
 158     /**
 159         Gets a single char from the stream buffer. It acts like the Read call.
 160
 161         @see Read()
 162     */
 163     char GetChar();
 164
 165     /**
 166         Returns the amount of available data in the buffer.
 167     */
 168     size_t GetDataLeft();
 169
 170     /**
 171         Returns the current position (counted in bytes) in the stream buffer.
 172     */
 173     off_t GetIntPosition() const;
 174
 175     /**
 176         Returns the amount of bytes read during the last IO call to the parent stream.
 177     */
 178     size_t GetLastAccess() const;
 179
 180     /**
 181         Puts a single char to the stream buffer.
 182
 183         @see Read()
 184     */
 185     void PutChar(char c);
 186
 187     //@{
 188     /**
 189         Copies data to @e buffer. The function returns when @a buffer is full or when
 190         there isn't
 191         any more data in the current buffer.
 192
 193         @see Write()
 194     */
 195     size_t Read(void* buffer, size_t size);
 196     Return value size_t Read(wxStreamBuffer* buffer);
 197     //@}
 198
 199     /**
 200         Resets to the initial state variables concerning the buffer.
 201     */
 202     void ResetBuffer();
 203
 204     /**
 205         Changes the current position.
 206         @a mode may be one of the following:
 207
 208         @b wxFromStart
 209
 210         The position is counted from the start of the stream.
 211
 212         @b wxFromCurrent
 213
 214         The position is counted from the current position of the stream.
 215
 216         @b wxFromEnd
 217
 218         The position is counted from the end of the stream.
 219
 220         @return Upon successful completion, it returns the new offset as
 221                  measured in bytes from the beginning of the stream.
 222                  Otherwise, it returns wxInvalidOffset.
 223     */
 224     off_t Seek(off_t pos, wxSeekMode mode);
 225
 226     //@{
 227     /**
 228         Destroys or invalidates the previous IO buffer and allocates a new one of the
 229         specified size.
 230
 231         @see Fixed(), Flushable()
 232     */
 233     void SetBufferIO(char* buffer_start, char* buffer_end);
 234     Remarks See also
 235     wxStreamBuffer constructor
 236
 237     wxStreamBuffer::Fixed
 238
 239     wxStreamBuffer::Flushable
 240     void SetBufferIO(size_t bufsize);
 241     //@}
 242
 243     /**
 244         Sets the current position (in bytes) in the stream buffer.
 245     */
 246     void SetIntPosition(size_t pos);
 247
 248     /**
 249         Returns the parent stream of the stream buffer.
 250     */
 251     wxStreamBase* Stream();
 252
 253     /**
 254         Gets the current position in the stream. This position is calculated from
 255         the @e real position in the stream and from the internal buffer position: so
 256         it gives you the position in the @e real stream counted from the start of
 257         the stream.
 258
 259         @return Returns the current position in the stream if possible,
 260                  wxInvalidOffset in the other case.
 261     */
 262     off_t Tell() const;
 263
 264     /**
 265         Truncates the buffer to the current position.
 266         Note: Truncate() cannot be used to enlarge the buffer. This is
 267         usually not needed since the buffer expands automatically.
 268     */
 269     void Truncate();
 270
 271     //@{
 272     /**
 273         See Read().
 274     */
 275     size_t Write(const void* buffer, size_t size);
 276     size_t Write(wxStreamBuffer* buffer);
 277     //@}
 278 };
 279
 280
 281
 282 /**
 283     @class wxOutputStream
 284     @wxheader{stream.h}
 285
 286     wxOutputStream is an abstract base class which may not be used directly.
 287
 288     @library{wxbase}
 289     @category{streams}
 290 */
 291 class wxOutputStream : public wxStreamBase
 292 {
 293 public:
 294     /**
 295         Creates a dummy wxOutputStream object.
 296     */
 297     wxOutputStream();
 298
 299     /**
 300         Destructor.
 301     */
 302     ~wxOutputStream();
 303
 304     /**
 305         Closes the stream, returning @false if an error occurs. The
 306         stream is closed implicitly in the destructor if Close() is not
 307         called explicitly.
 308         If this stream wraps another stream or some other resource such
 309         as a file, then the underlying resource is closed too if it is owned
 310         by this stream, or left open otherwise.
 311     */
 312     bool Close();
 313
 314     /**
 315         Returns the number of bytes written during the last
 316         Write(). It may return 0 even if there is no
 317         error on the stream if it is only temporarily impossible to write to it.
 318     */
 319     size_t LastWrite() const;
 320
 321     /**
 322         Puts the specified character in the output queue and increments the
 323         stream position.
 324     */
 325     void PutC(char c);
 326
 327     /**
 328         Changes the stream current position.
 329
 330         @param pos
 331             Offset to seek to.
 332         @param mode
 333             One of wxFromStart, wxFromEnd, wxFromCurrent.
 334
 335         @return The new stream position or wxInvalidOffset on error.
 336     */
 337     off_t SeekO(off_t pos, wxSeekMode mode = wxFromStart);
 338
 339     /**
 340         Returns the current stream position.
 341     */
 342     off_t TellO() const;
 343
 344     //@{
 345     /**
 346         Reads data from the specified input stream and stores them
 347         in the current stream. The data is read until an error is raised
 348         by one of the two streams.
 349     */
 350     wxOutputStream Write(const void* buffer, size_t size);
 351     wxOutputStream Write(wxInputStream& stream_in);
 352     //@}
 353 };
 354
 355
 356
 357 /**
 358     @class wxFilterClassFactory
 359     @wxheader{stream.h}
 360
 361     Allows the creation of filter streams to handle compression formats such
 362     as gzip and bzip2.
 363
 364     For example, given a filename you can search for a factory that will
 365     handle it and create a stream to decompress it:
 366
 367     @code
 368     factory = wxFilterClassFactory::Find(filename, wxSTREAM_FILEEXT);
 369         if (factory)
 370             stream = factory-NewStream(new wxFFileInputStream(filename));
 371     @endcode
 372
 373     wxFilterClassFactory::Find can also search
 374     for a factory by MIME type, HTTP encoding or by wxFileSystem protocol.
 375     The available factories can be enumerated
 376     using @ref wxFilterClassFactory::getfirst "GetFirst() and GetNext".
 377
 378     @library{wxbase}
 379     @category{FIXME}
 380
 381     @see wxFilterInputStream, wxFilterOutputStream, wxArchiveClassFactory, @ref
 382     overview_wxarc "Archive formats such as zip"
 383 */
 384 class wxFilterClassFactory : public wxObject
 385 {
 386 public:
 387     /**
 388         Returns @true if this factory can handle the given protocol, MIME type, HTTP
 389         encoding or file extension.
 390         When using wxSTREAM_FILEEXT for the second parameter, the first parameter
 391         can be a complete filename rather than just an extension.
 392     */
 393     bool CanHandle(const wxString& protocol,
 394                    wxStreamProtocolType type = wxSTREAM_PROTOCOL) const;
 395
 396     /**
 397         A static member that finds a factory that can handle a given protocol, MIME
 398         type, HTTP encoding or file extension.  Returns a pointer to the class
 399         factory if found, or @NULL otherwise. It does not give away ownership of the
 400         factory.
 401         When using wxSTREAM_FILEEXT for the second parameter, the first parameter
 402         can be a complete filename rather than just an extension.
 403     */
 404     static const wxFilterClassFactory* Find(const wxString& protocol,
 405                                             wxStreamProtocolType type = wxSTREAM_PROTOCOL);
 406
 407     //@{
 408     /**
 409         GetFirst and GetNext can be used to enumerate the available factories.
 410         For example, to list them:
 411
 412         GetFirst()/GetNext() return a pointer to a factory or @NULL if no more
 413         are available. They do not give away ownership of the factory.
 414     */
 415     static const wxFilterClassFactory* GetFirst() const;
 416     const wxFilterClassFactory* GetNext() const;
 417     //@}
 418
 419     /**
 420         Returns the wxFileSystem protocol supported by this factory. Equivalent
 421         to wxString(*GetProtcols()).
 422     */
 423     wxString GetProtocol() const;
 424
 425     /**
 426         Returns the protocols, MIME types, HTTP encodings or file extensions
 427         supported by this factory, as an array of null terminated strings. It does
 428         not give away ownership of the array or strings.
 429         For example, to list the file extensions a factory supports:
 430     */
 431     const wxChar* const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL) const;
 432
 433     //@{
 434     /**
 435         Create a new input or output stream to decompress or compress a given stream.
 436         If the parent stream is passed as a pointer then the new filter stream
 437         takes ownership of it. If it is passed by reference then it does not.
 438     */
 439     wxFilterInputStream* NewStream(wxInputStream& stream) const;
 440     const wxFilterOutputStream*  NewStream(wxOutputStream& stream) const;
 441     const wxFilterInputStream*  NewStream(wxInputStream* stream) const;
 442     const wxFilterOutputStream*  NewStream(wxOutputStream* stream) const;
 443     //@}
 444
 445     /**
 446         Remove the file extension of @a location if it is one of the file
 447         extensions handled by this factory.
 448     */
 449     wxString PopExtension(const wxString& location) const;
 450
 451     /**
 452         Adds this class factory to the list returned
 453         by @ref getfirst() GetFirst()/GetNext.
 454         It is not necessary to do this to use the filter streams. It is usually
 455         used when implementing streams, typically the implementation will
 456         add a static instance of its factory class.
 457         It can also be used to change the order of a factory already in the list,
 458         bringing it to the front. This isn't a thread safe operation
 459         so can't be done when other threads are running that will be using the list.
 460         The list does not take ownership of the factory.
 461     */
 462     void PushFront();
 463
 464     /**
 465         Removes this class factory from the list returned
 466         by @ref getfirst() GetFirst()/GetNext.
 467         Removing from the list isn't a thread safe operation
 468         so can't be done when other threads are running that will be using the list.
 469         The list does not own the factories, so removing a factory does not delete it.
 470     */
 471     void Remove();
 472 };
 473
 474
 475
 476 /**
 477     @class wxFilterOutputStream
 478     @wxheader{stream.h}
 479
 480     A filter stream has the capability of a normal
 481     stream but it can be placed on top of another stream. So, for example, it
 482     can compress, encrypt the data which are passed to it and write them to another
 483     stream.
 484
 485     @library{wxbase}
 486     @category{streams}
 487
 488     @see wxFilterClassFactory, wxFilterInputStream
 489 */
 490 class wxFilterOutputStream : public wxOutputStream
 491 {
 492 public:
 493     //@{
 494     /**
 495         Initializes a "filter" stream.
 496         If the parent stream is passed as a pointer then the new filter stream
 497         takes ownership of it. If it is passed by reference then it does not.
 498     */
 499     wxFilterOutputStream(wxOutputStream& stream);
 500     wxFilterOutputStream(wxOutputStream* stream);
 501     //@}
 502 };
 503
 504
 505
 506 /**
 507     @class wxFilterInputStream
 508     @wxheader{stream.h}
 509
 510     A filter stream has the capability of a normal stream but it can be placed on
 511     top
 512     of another stream. So, for example, it can uncompress or decrypt the data which
 513     are read
 514     from another stream and pass it to the requester.
 515
 516     @library{wxbase}
 517     @category{streams}
 518
 519     @see wxFilterClassFactory, wxFilterOutputStream
 520 */
 521 class wxFilterInputStream : public wxInputStream
 522 {
 523 public:
 524     //@{
 525     /**
 526         Initializes a "filter" stream.
 527         If the parent stream is passed as a pointer then the new filter stream
 528         takes ownership of it. If it is passed by reference then it does not.
 529     */
 530     wxFilterInputStream(wxInputStream& stream);
 531     wxFilterInputStream(wxInputStream* stream);
 532     //@}
 533 };
 534
 535
 536
 537 /**
 538     @class wxBufferedOutputStream
 539     @wxheader{stream.h}
 540
 541     This stream acts as a cache. It caches the bytes to be written to the specified
 542     output stream (See wxFilterOutputStream). The
 543     data is only written when the cache is full, when the buffered stream is
 544     destroyed or when calling SeekO().
 545
 546     This class may not be used without some other stream to write the data
 547     to (such as a file stream or a memory stream).
 548
 549     @library{wxbase}
 550     @category{streams}
 551
 552     @see wxStreamBuffer, wxOutputStream
 553 */
 554 class wxBufferedOutputStream : public wxFilterOutputStream
 555 {
 556 public:
 557     /**
 558         Creates a buffered stream using a buffer of a default size of 1024 bytes for
 559         cashing
 560         the stream @e parent.
 561     */
 562     wxBufferedOutputStream(const wxOutputStream& parent);
 563
 564     /**
 565         Destructor. Calls Sync() and destroys the internal buffer.
 566     */
 567     ~wxBufferedOutputStream();
 568
 569     /**
 570         Calls Sync() and changes the stream position.
 571     */
 572     off_t SeekO(off_t pos, wxSeekMode mode);
 573
 574     /**
 575         Flushes the buffer and calls Sync() on the parent stream.
 576     */
 577     void Sync();
 578 };
 579
 580
 581
 582 /**
 583     @class wxInputStream
 584     @wxheader{stream.h}
 585
 586     wxInputStream is an abstract base class which may not be used directly.
 587
 588     @library{wxbase}
 589     @category{streams}
 590 */
 591 class wxInputStream : public wxStreamBase
 592 {
 593 public:
 594     /**
 595         Creates a dummy input stream.
 596     */
 597     wxInputStream();
 598
 599     /**
 600         Destructor.
 601     */
 602     ~wxInputStream();
 603
 604     /**
 605         Returns @true if some data is available in the stream right now, so that
 606         calling Read() wouldn't block.
 607     */
 608     bool CanRead() const;
 609
 610     /**
 611         Returns @true after an attempt has been made to read past the end of the
 612         stream.
 613     */
 614     bool Eof() const;
 615
 616     /**
 617         Returns the first character in the input queue and removes it,
 618         blocking until it appears if necessary.
 619     */
 620     char GetC();
 621
 622     /**
 623         Returns the last number of bytes read.
 624     */
 625     size_t LastRead() const;
 626
 627     /**
 628         Returns the first character in the input queue without removing it.
 629     */
 630     char Peek();
 631
 632     //@{
 633     /**
 634         Reads data from the input queue and stores it in the specified output stream.
 635         The data is read until an error is raised by one of the two streams.
 636
 637         @return This function returns a reference on the current object, so the
 638                  user can test any states of the stream right away.
 639     */
 640     wxInputStream Read(void* buffer, size_t size);
 641     Warning Return value
 642     This function returns a reference on the current object, so the user can test
 643     any states of the stream right away.
 644     wxInputStream&  Read(wxOutputStream& stream_out);
 645     //@}
 646
 647     /**
 648         Changes the stream current position.
 649
 650         @param pos
 651             Offset to seek to.
 652         @param mode
 653             One of wxFromStart, wxFromEnd, wxFromCurrent.
 654
 655         @return The new stream position or wxInvalidOffset on error.
 656     */
 657     off_t SeekI(off_t pos, wxSeekMode mode = wxFromStart);
 658
 659     /**
 660         Returns the current stream position.
 661     */
 662     off_t TellI() const;
 663
 664     //@{
 665     /**
 666         This function acts like the previous one except that it takes only one
 667         character: it is sometimes shorter to use than the generic function.
 668     */
 669     size_t Ungetch(const char* buffer, size_t size);
 670     Return value bool Ungetch(char c);
 671     //@}
 672 };
 673
 674
 675
 676 /**
 677     @class wxStreamBase
 678     @wxheader{stream.h}
 679
 680     This class is the base class of most stream related classes in wxWidgets. It
 681     must
 682     not be used directly.
 683
 684     @library{wxbase}
 685     @category{streams}
 686
 687     @see wxStreamBuffer
 688 */
 689 class wxStreamBase
 690 {
 691 public:
 692     /**
 693         Creates a dummy stream object. It doesn't do anything.
 694     */
 695     wxStreamBase();
 696
 697     /**
 698         Destructor.
 699     */
 700     ~wxStreamBase();
 701
 702     /**
 703         This function returns the last error.
 704
 705         @b wxSTREAM_NO_ERROR
 706
 707         No error occurred.
 708
 709         @b wxSTREAM_EOF
 710
 711         An End-Of-File occurred.
 712
 713         @b wxSTREAM_WRITE_ERROR
 714
 715         A generic error occurred on the last write call.
 716
 717         @b wxSTREAM_READ_ERROR
 718
 719         A generic error occurred on the last read call.
 720     */
 721     wxStreamError GetLastError() const;
 722
 723     /**
 724         Returns the length of the stream in bytes. If the length cannot be determined
 725         (this is always the case for socket streams for example), returns
 726         @c wxInvalidOffset.
 727
 728         @since 2.5.4
 729     */
 730     wxFileOffset GetLength() const;
 731
 732     /**
 733         GetLength()
 734         This function returns the size of the stream. For example, for a file it is the
 735         size of the file.
 736     */
 737     size_t GetSize() const;
 738
 739     /**
 740         Returns @true if no error occurred on the stream.
 741
 742         @see GetLastError()
 743     */
 744     virtual bool IsOk() const;
 745
 746     /**
 747         Returns @true if the streams supports seeking to arbitrary offsets.
 748     */
 749     bool IsSeekable() const;
 750
 751     /**
 752         Internal function. It is called when the stream wants to read data of the
 753         specified size. It should return the size that was actually read.
 754     */
 755     size_t OnSysRead(void* buffer, size_t bufsize);
 756
 757     /**
 758         Internal function. It is called when the stream needs to change the
 759         current position.
 760     */
 761     off_t OnSysSeek(off_t pos, wxSeekMode mode);
 762
 763     /**
 764         Internal function. Is is called when the stream needs to know the
 765         real position.
 766     */
 767     off_t OnSysTell() const;
 768
 769     /**
 770         See OnSysRead().
 771     */
 772     size_t OnSysWrite(const void* buffer, size_t bufsize);
 773 };
 774