interface/stream.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        stream.h
   3 // Purpose:     documentation for wxCountingOutputStream class
   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     @class wxBufferedInputStream
  54     @wxheader{stream.h}
  55
  56     This stream acts as a cache. It caches the bytes read from the specified
  57     input stream (See wxFilterInputStream).
  58     It uses wxStreamBuffer and sets the default in-buffer size to 1024 bytes.
  59     This class may not be used without some other stream to read the data
  60     from (such as a file stream or a memory stream).
  61
  62     @library{wxbase}
  63     @category{streams}
  64
  65     @seealso
  66     wxStreamBuffer, wxInputStream, wxBufferedOutputStream
  67 */
  68 class wxBufferedInputStream : public wxFilterInputStream
  69 {
  70 public:
  71
  72 };
  73
  74
  75 /**
  76     @class wxStreamBuffer
  77     @wxheader{stream.h}
  78
  79
  80     @library{wxbase}
  81     @category{streams}
  82
  83     @seealso
  84     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         @returns 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         @returns 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     @class wxOutputStream
 283     @wxheader{stream.h}
 284
 285     wxOutputStream is an abstract base class which may not be used directly.
 286
 287     @library{wxbase}
 288     @category{streams}
 289 */
 290 class wxOutputStream : public wxStreamBase
 291 {
 292 public:
 293     /**
 294         Creates a dummy wxOutputStream object.
 295     */
 296     wxOutputStream();
 297
 298     /**
 299         Destructor.
 300     */
 301     ~wxOutputStream();
 302
 303     /**
 304         Closes the stream, returning @false if an error occurs. The
 305         stream is closed implicitly in the destructor if Close() is not
 306         called explicitly.
 307         If this stream wraps another stream or some other resource such
 308         as a file, then the underlying resource is closed too if it is owned
 309         by this stream, or left open otherwise.
 310     */
 311     bool Close();
 312
 313     /**
 314         Returns the number of bytes written during the last
 315         Write(). It may return 0 even if there is no
 316         error on the stream if it is only temporarily impossible to write to it.
 317     */
 318     size_t LastWrite() const;
 319
 320     /**
 321         Puts the specified character in the output queue and increments the
 322         stream position.
 323     */
 324     void PutC(char c);
 325
 326     /**
 327         Changes the stream current position.
 328
 329         @param pos
 330             Offset to seek to.
 331         @param mode
 332             One of wxFromStart, wxFromEnd, wxFromCurrent.
 333
 334         @returns The new stream position or wxInvalidOffset on error.
 335     */
 336     off_t SeekO(off_t pos, wxSeekMode mode = wxFromStart);
 337
 338     /**
 339         Returns the current stream position.
 340     */
 341     off_t TellO() const;
 342
 343     //@{
 344     /**
 345         Reads data from the specified input stream and stores them
 346         in the current stream. The data is read until an error is raised
 347         by one of the two streams.
 348     */
 349     wxOutputStream Write(const void* buffer, size_t size);
 350     wxOutputStream Write(wxInputStream& stream_in);
 351     //@}
 352 };
 353
 354
 355 /**
 356     @class wxFilterClassFactory
 357     @wxheader{stream.h}
 358
 359     Allows the creation of filter streams to handle compression formats such
 360     as gzip and bzip2.
 361
 362     For example, given a filename you can search for a factory that will
 363     handle it and create a stream to decompress it:
 364
 365     @code
 366     factory = wxFilterClassFactory::Find(filename, wxSTREAM_FILEEXT);
 367         if (factory)
 368             stream = factory-NewStream(new wxFFileInputStream(filename));
 369     @endcode
 370
 371     wxFilterClassFactory::Find can also search
 372     for a factory by MIME type, HTTP encoding or by wxFileSystem protocol.
 373     The available factories can be enumerated
 374     using @ref wxFilterClassFactory::getfirst "GetFirst() and GetNext".
 375
 376     @library{wxbase}
 377     @category{FIXME}
 378
 379     @seealso
 380     wxFilterInputStream, wxFilterOutputStream, wxArchiveClassFactory, @ref
 381     overview_wxarc "Archive formats such as zip"
 382 */
 383 class wxFilterClassFactory : public wxObject
 384 {
 385 public:
 386     /**
 387         Returns @true if this factory can handle the given protocol, MIME type, HTTP
 388         encoding or file extension.
 389         When using wxSTREAM_FILEEXT for the second parameter, the first parameter
 390         can be a complete filename rather than just an extension.
 391     */
 392     bool CanHandle(const wxString& protocol,
 393                    wxStreamProtocolType type = wxSTREAM_PROTOCOL) const;
 394
 395     /**
 396         A static member that finds a factory that can handle a given protocol, MIME
 397         type, HTTP encoding or file extension.  Returns a pointer to the class
 398         factory if found, or @NULL otherwise. It does not give away ownership of the
 399         factory.
 400         When using wxSTREAM_FILEEXT for the second parameter, the first parameter
 401         can be a complete filename rather than just an extension.
 402     */
 403     static const wxFilterClassFactory* Find(const wxString& protocol,
 404                                             wxStreamProtocolType type = wxSTREAM_PROTOCOL);
 405
 406     //@{
 407     /**
 408         GetFirst and GetNext can be used to enumerate the available factories.
 409         For example, to list them:
 410
 411         GetFirst()/GetNext() return a pointer to a factory or @NULL if no more
 412         are available. They do not give away ownership of the factory.
 413     */
 414     static const wxFilterClassFactory* GetFirst() const;
 415     const wxFilterClassFactory* GetNext() const;
 416     //@}
 417
 418     /**
 419         Returns the wxFileSystem protocol supported by this factory. Equivalent
 420         to wxString(*GetProtcols()).
 421     */
 422     wxString GetProtocol() const;
 423
 424     /**
 425         Returns the protocols, MIME types, HTTP encodings or file extensions
 426         supported by this factory, as an array of null terminated strings. It does
 427         not give away ownership of the array or strings.
 428         For example, to list the file extensions a factory supports:
 429     */
 430     const wxChar* const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL) const;
 431
 432     //@{
 433     /**
 434         Create a new input or output stream to decompress or compress a given stream.
 435         If the parent stream is passed as a pointer then the new filter stream
 436         takes ownership of it. If it is passed by reference then it does not.
 437     */
 438     wxFilterInputStream* NewStream(wxInputStream& stream) const;
 439     const wxFilterOutputStream*  NewStream(wxOutputStream& stream) const;
 440     const wxFilterInputStream*  NewStream(wxInputStream* stream) const;
 441     const wxFilterOutputStream*  NewStream(wxOutputStream* stream) const;
 442     //@}
 443
 444     /**
 445         Remove the file extension of @a location if it is one of the file
 446         extensions handled by this factory.
 447     */
 448     wxString PopExtension(const wxString& location) const;
 449
 450     /**
 451         Adds this class factory to the list returned
 452         by @ref getfirst() GetFirst()/GetNext.
 453         It is not necessary to do this to use the filter streams. It is usually
 454         used when implementing streams, typically the implementation will
 455         add a static instance of its factory class.
 456         It can also be used to change the order of a factory already in the list,
 457         bringing it to the front. This isn't a thread safe operation
 458         so can't be done when other threads are running that will be using the list.
 459         The list does not take ownership of the factory.
 460     */
 461     void PushFront();
 462
 463     /**
 464         Removes this class factory from the list returned
 465         by @ref getfirst() GetFirst()/GetNext.
 466         Removing from the list isn't a thread safe operation
 467         so can't be done when other threads are running that will be using the list.
 468         The list does not own the factories, so removing a factory does not delete it.
 469     */
 470     void Remove();
 471 };
 472
 473
 474 /**
 475     @class wxFilterOutputStream
 476     @wxheader{stream.h}
 477
 478     A filter stream has the capability of a normal
 479     stream but it can be placed on top of another stream. So, for example, it
 480     can compress, encrypt the data which are passed to it and write them to another
 481     stream.
 482
 483     @library{wxbase}
 484     @category{streams}
 485
 486     @seealso
 487     wxFilterClassFactory, wxFilterInputStream
 488 */
 489 class wxFilterOutputStream : public wxOutputStream
 490 {
 491 public:
 492     //@{
 493     /**
 494         Initializes a "filter" stream.
 495         If the parent stream is passed as a pointer then the new filter stream
 496         takes ownership of it. If it is passed by reference then it does not.
 497     */
 498     wxFilterOutputStream(wxOutputStream& stream);
 499     wxFilterOutputStream(wxOutputStream* stream);
 500     //@}
 501 };
 502
 503
 504 /**
 505     @class wxFilterInputStream
 506     @wxheader{stream.h}
 507
 508     A filter stream has the capability of a normal stream but it can be placed on
 509     top
 510     of another stream. So, for example, it can uncompress or decrypt the data which
 511     are read
 512     from another stream and pass it to the requester.
 513
 514     @library{wxbase}
 515     @category{streams}
 516
 517     @seealso
 518     wxFilterClassFactory, wxFilterOutputStream
 519 */
 520 class wxFilterInputStream : public wxInputStream
 521 {
 522 public:
 523     //@{
 524     /**
 525         Initializes a "filter" stream.
 526         If the parent stream is passed as a pointer then the new filter stream
 527         takes ownership of it. If it is passed by reference then it does not.
 528     */
 529     wxFilterInputStream(wxInputStream& stream);
 530     wxFilterInputStream(wxInputStream* stream);
 531     //@}
 532 };
 533
 534
 535 /**
 536     @class wxBufferedOutputStream
 537     @wxheader{stream.h}
 538
 539     This stream acts as a cache. It caches the bytes to be written to the specified
 540     output stream (See wxFilterOutputStream). The
 541     data is only written when the cache is full, when the buffered stream is
 542     destroyed or when calling SeekO().
 543
 544     This class may not be used without some other stream to write the data
 545     to (such as a file stream or a memory stream).
 546
 547     @library{wxbase}
 548     @category{streams}
 549
 550     @seealso
 551     wxStreamBuffer, wxOutputStream
 552 */
 553 class wxBufferedOutputStream : public wxFilterOutputStream
 554 {
 555 public:
 556     /**
 557         Creates a buffered stream using a buffer of a default size of 1024 bytes for
 558         cashing
 559         the stream @e parent.
 560     */
 561     wxBufferedOutputStream(const wxOutputStream& parent);
 562
 563     /**
 564         Destructor. Calls Sync() and destroys the internal buffer.
 565     */
 566     ~wxBufferedOutputStream();
 567
 568     /**
 569         Calls Sync() and changes the stream position.
 570     */
 571     off_t SeekO(off_t pos, wxSeekMode mode);
 572
 573     /**
 574         Flushes the buffer and calls Sync() on the parent stream.
 575     */
 576     void Sync();
 577 };
 578
 579
 580 /**
 581     @class wxInputStream
 582     @wxheader{stream.h}
 583
 584     wxInputStream is an abstract base class which may not be used directly.
 585
 586     @library{wxbase}
 587     @category{streams}
 588 */
 589 class wxInputStream : public wxStreamBase
 590 {
 591 public:
 592     /**
 593         Creates a dummy input stream.
 594     */
 595     wxInputStream();
 596
 597     /**
 598         Destructor.
 599     */
 600     ~wxInputStream();
 601
 602     /**
 603         Returns @true if some data is available in the stream right now, so that
 604         calling Read() wouldn't block.
 605     */
 606     bool CanRead() const;
 607
 608     /**
 609         Returns @true after an attempt has been made to read past the end of the
 610         stream.
 611     */
 612     bool Eof() const;
 613
 614     /**
 615         Returns the first character in the input queue and removes it,
 616         blocking until it appears if necessary.
 617     */
 618     char GetC();
 619
 620     /**
 621         Returns the last number of bytes read.
 622     */
 623     size_t LastRead() const;
 624
 625     /**
 626         Returns the first character in the input queue without removing it.
 627     */
 628     char Peek();
 629
 630     //@{
 631     /**
 632         Reads data from the input queue and stores it in the specified output stream.
 633         The data is read until an error is raised by one of the two streams.
 634
 635         @returns This function returns a reference on the current object, so the
 636                  user can test any states of the stream right away.
 637     */
 638     wxInputStream Read(void* buffer, size_t size);
 639     Warning Return value
 640     This function returns a reference on the current object, so the user can test
 641     any states of the stream right away.
 642     wxInputStream&  Read(wxOutputStream& stream_out);
 643     //@}
 644
 645     /**
 646         Changes the stream current position.
 647
 648         @param pos
 649             Offset to seek to.
 650         @param mode
 651             One of wxFromStart, wxFromEnd, wxFromCurrent.
 652
 653         @returns The new stream position or wxInvalidOffset on error.
 654     */
 655     off_t SeekI(off_t pos, wxSeekMode mode = wxFromStart);
 656
 657     /**
 658         Returns the current stream position.
 659     */
 660     off_t TellI() const;
 661
 662     //@{
 663     /**
 664         This function acts like the previous one except that it takes only one
 665         character: it is sometimes shorter to use than the generic function.
 666     */
 667     size_t Ungetch(const char* buffer, size_t size);
 668     Return value bool Ungetch(char c);
 669     //@}
 670 };
 671
 672
 673 /**
 674     @class wxStreamBase
 675     @wxheader{stream.h}
 676
 677     This class is the base class of most stream related classes in wxWidgets. It
 678     must
 679     not be used directly.
 680
 681     @library{wxbase}
 682     @category{streams}
 683
 684     @seealso
 685     wxStreamBuffer
 686 */
 687 class wxStreamBase
 688 {
 689 public:
 690     /**
 691         Creates a dummy stream object. It doesn't do anything.
 692     */
 693     wxStreamBase();
 694
 695     /**
 696         Destructor.
 697     */
 698     ~wxStreamBase();
 699
 700     /**
 701         This function returns the last error.
 702
 703         @b wxSTREAM_NO_ERROR
 704
 705         No error occurred.
 706
 707         @b wxSTREAM_EOF
 708
 709         An End-Of-File occurred.
 710
 711         @b wxSTREAM_WRITE_ERROR
 712
 713         A generic error occurred on the last write call.
 714
 715         @b wxSTREAM_READ_ERROR
 716
 717         A generic error occurred on the last read call.
 718     */
 719     wxStreamError GetLastError() const;
 720
 721     /**
 722         Returns the length of the stream in bytes. If the length cannot be determined
 723         (this is always the case for socket streams for example), returns
 724         @c wxInvalidOffset.
 725         This function is new since wxWidgets version 2.5.4
 726     */
 727     wxFileOffset GetLength() const;
 728
 729     /**
 730         GetLength()
 731         This function returns the size of the stream. For example, for a file it is the
 732         size of the file.
 733     */
 734     size_t GetSize() const;
 735
 736     /**
 737         Returns @true if no error occurred on the stream.
 738
 739         @see GetLastError()
 740     */
 741     virtual bool IsOk() const;
 742
 743     /**
 744         Returns @true if the streams supports seeking to arbitrary offsets.
 745     */
 746     bool IsSeekable() const;
 747
 748     /**
 749         Internal function. It is called when the stream wants to read data of the
 750         specified size. It should return the size that was actually read.
 751     */
 752     size_t OnSysRead(void* buffer, size_t bufsize);
 753
 754     /**
 755         Internal function. It is called when the stream needs to change the
 756         current position.
 757     */
 758     off_t OnSysSeek(off_t pos, wxSeekMode mode);
 759
 760     /**
 761         Internal function. Is is called when the stream needs to know the
 762         real position.
 763     */
 764     off_t OnSysTell() const;
 765
 766     /**
 767         See OnSysRead().
 768     */
 769     size_t OnSysWrite(const void* buffer, size_t bufsize);
 770 };