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