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();
  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         @sa @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         @sa 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 @e 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();
 142
 143     /**
 144         Returns a pointer on the current position of the stream buffer.
 145     */
 146     void * GetBufferPos();
 147
 148     /**
 149         Returns the size of the buffer.
 150     */
 151     size_t GetBufferSize();
 152
 153     /**
 154         Returns a pointer on the start of the stream buffer.
 155     */
 156     void * GetBufferStart();
 157
 158     /**
 159         Gets a single char from the stream buffer. It acts like the Read call.
 160
 161         @sa 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();
 174
 175     /**
 176         Returns the amount of bytes read during the last IO call to the parent stream.
 177     */
 178     size_t GetLastAccess();
 179
 180     /**
 181         Puts a single char to the stream buffer.
 182
 183         @sa Read()
 184     */
 185     void PutChar(char c);
 186
 187     //@{
 188     /**
 189         Copies data to @e buffer. The function returns when @e buffer is full or when
 190         there isn't
 191         any more data in the current buffer.
 192
 193         @sa 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
 207         @e mode may be one of the following:
 208
 209
 210         @b wxFromStart
 211
 212
 213         The position is counted from the start of the stream.
 214
 215         @b wxFromCurrent
 216
 217
 218         The position is counted from the current position of the stream.
 219
 220         @b wxFromEnd
 221
 222
 223         The position is counted from the end of the stream.
 224
 225
 226         @returns Upon successful completion, it returns the new offset as
 227                    measured in bytes from the beginning of the stream.
 228                    Otherwise, it returns wxInvalidOffset.
 229     */
 230     off_t Seek(off_t pos, wxSeekMode mode);
 231
 232     //@{
 233     /**
 234         Destroys or invalidates the previous IO buffer and allocates a new one of the
 235         specified size.
 236
 237         @sa Fixed(), Flushable()
 238     */
 239     void SetBufferIO(char* buffer_start, char* buffer_end);
 240         Remarks See also
 241 wxStreamBuffer constructor
 242
 243 wxStreamBuffer::Fixed
 244
 245 wxStreamBuffer::Flushable
 246 void SetBufferIO(size_t bufsize);
 247     //@}
 248
 249     /**
 250         Sets the current position (in bytes) in the stream buffer.
 251     */
 252     void SetIntPosition(size_t pos);
 253
 254     /**
 255         Returns the parent stream of the stream buffer.
 256     */
 257     wxStreamBase* Stream();
 258
 259     /**
 260         Gets the current position in the stream. This position is calculated from
 261         the @e real position in the stream and from the internal buffer position: so
 262         it gives you the position in the @e real stream counted from the start of
 263         the stream.
 264
 265         @returns Returns the current position in the stream if possible,
 266                    wxInvalidOffset in the other case.
 267     */
 268     off_t Tell();
 269
 270     /**
 271         Truncates the buffer to the current position.
 272
 273         Note: Truncate() cannot be used to enlarge the buffer. This is
 274         usually not needed since the buffer expands automatically.
 275     */
 276     void Truncate();
 277
 278     //@{
 279     /**
 280         See Read().
 281     */
 282     size_t Write(const void * buffer, size_t size);
 283         size_t Write(wxStreamBuffer * buffer);
 284     //@}
 285 };
 286
 287
 288 /**
 289     @class wxOutputStream
 290     @wxheader{stream.h}
 291
 292     wxOutputStream is an abstract base class which may not be used directly.
 293
 294     @library{wxbase}
 295     @category{streams}
 296 */
 297 class wxOutputStream : public wxStreamBase
 298 {
 299 public:
 300     /**
 301         Creates a dummy wxOutputStream object.
 302     */
 303     wxOutputStream();
 304
 305     /**
 306         Destructor.
 307     */
 308     ~wxOutputStream();
 309
 310     /**
 311         Closes the stream, returning @false if an error occurs. The
 312         stream is closed implicitly in the destructor if Close() is not
 313         called explicitly.
 314
 315         If this stream wraps another stream or some other resource such
 316         as a file, then the underlying resource is closed too if it is owned
 317         by this stream, or left open otherwise.
 318     */
 319     bool Close();
 320
 321     /**
 322         Returns the number of bytes written during the last
 323         Write(). It may return 0 even if there is no
 324         error on the stream if it is only temporarily impossible to write to it.
 325     */
 326     size_t LastWrite();
 327
 328     /**
 329         Puts the specified character in the output queue and increments the
 330         stream position.
 331     */
 332 #define void PutC(char c)     /* implementation is private */
 333
 334     /**
 335         Changes the stream current position.
 336
 337         @param pos
 338         Offset to seek to.
 339
 340         @param mode
 341         One of wxFromStart, wxFromEnd, wxFromCurrent.
 342
 343         @returns The new stream position or wxInvalidOffset on error.
 344     */
 345     off_t SeekO(off_t pos, wxSeekMode mode = wxFromStart);
 346
 347     /**
 348         Returns the current stream position.
 349     */
 350     off_t TellO();
 351
 352     //@{
 353     /**
 354         Reads data from the specified input stream and stores them
 355         in the current stream. The data is read until an error is raised
 356         by one of the two streams.
 357     */
 358     wxOutputStream Write(const void * buffer, size_t size);
 359         wxOutputStream Write(wxInputStream& stream_in);
 360     //@}
 361 };
 362
 363
 364 /**
 365     @class wxFilterClassFactory
 366     @wxheader{stream.h}
 367
 368     Allows the creation of filter streams to handle compression formats such
 369     as gzip and bzip2.
 370
 371     For example, given a filename you can search for a factory that will
 372     handle it and create a stream to decompress it:
 373
 374     @code
 375     factory = wxFilterClassFactory::Find(filename, wxSTREAM_FILEEXT);
 376         if (factory)
 377             stream = factory-NewStream(new wxFFileInputStream(filename));
 378     @endcode
 379
 380     wxFilterClassFactory::Find can also search
 381     for a factory by MIME type, HTTP encoding or by wxFileSystem protocol.
 382     The available factories can be enumerated
 383     using @ref wxFilterClassFactory::getfirst "GetFirst() and GetNext".
 384
 385     @library{wxbase}
 386     @category{FIXME}
 387
 388     @seealso
 389     wxFilterInputStream, wxFilterOutputStream, wxArchiveClassFactory, @ref
 390     overview_wxarc "Archive formats such as zip"
 391 */
 392 class wxFilterClassFactory : public wxObject
 393 {
 394 public:
 395     /**
 396         Returns @true if this factory can handle the given protocol, MIME type, HTTP
 397         encoding or file extension.
 398
 399         When using wxSTREAM_FILEEXT for the second parameter, the first parameter
 400         can be a complete filename rather than just an extension.
 401     */
 402     bool CanHandle(const wxString& protocol,
 403                    wxStreamProtocolType type = wxSTREAM_PROTOCOL);
 404
 405     /**
 406         A static member that finds a factory that can handle a given protocol, MIME
 407         type, HTTP encoding or file extension.  Returns a pointer to the class
 408         factory if found, or @NULL otherwise. It does not give away ownership of the
 409         factory.
 410
 411         When using wxSTREAM_FILEEXT for the second parameter, the first parameter
 412         can be a complete filename rather than just an extension.
 413     */
 414     static const wxFilterClassFactory* Find(const wxString& protocol,
 415                                             wxStreamProtocolType type = wxSTREAM_PROTOCOL);
 416
 417     //@{
 418     /**
 419         GetFirst and GetNext can be used to enumerate the available factories.
 420
 421         For example, to list them:
 422         GetFirst()/GetNext() return a pointer to a factory or @NULL if no more
 423         are available. They do not give away ownership of the factory.
 424     */
 425     static const wxFilterClassFactory* GetFirst();
 426         const wxFilterClassFactory* GetNext();
 427     //@}
 428
 429     /**
 430         Returns the wxFileSystem protocol supported by this factory. Equivalent
 431         to wxString(*GetProtcols()).
 432     */
 433     wxString GetProtocol();
 434
 435     /**
 436         Returns the protocols, MIME types, HTTP encodings or file extensions
 437         supported by this factory, as an array of null terminated strings. It does
 438         not give away ownership of the array or strings.
 439
 440         For example, to list the file extensions a factory supports:
 441     */
 442     const wxChar * const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL);
 443
 444     //@{
 445     /**
 446         Create a new input or output stream to decompress or compress a given stream.
 447
 448         If the parent stream is passed as a pointer then the new filter stream
 449         takes ownership of it. If it is passed by reference then it does not.
 450     */
 451     wxFilterInputStream* NewStream(wxInputStream& stream);
 452         wxFilterOutputStream* NewStream(wxOutputStream& stream);
 453         wxFilterInputStream* NewStream(wxInputStream* stream);
 454         wxFilterOutputStream* NewStream(wxOutputStream* stream);
 455     //@}
 456
 457     /**
 458         Remove the file extension of @e location if it is one of the file
 459         extensions handled by this factory.
 460     */
 461     wxString PopExtension(const wxString& location);
 462
 463     /**
 464         Adds this class factory to the list returned
 465         by @ref getfirst() GetFirst()/GetNext.
 466
 467         It is not necessary to do this to use the filter streams. It is usually
 468         used when implementing streams, typically the implementation will
 469         add a static instance of its factory class.
 470
 471         It can also be used to change the order of a factory already in the list,
 472         bringing it to the front. This isn't a thread safe operation
 473         so can't be done when other threads are running that will be using the list.
 474
 475         The list does not take ownership of the factory.
 476     */
 477     void PushFront();
 478
 479     /**
 480         Removes this class factory from the list returned
 481         by @ref getfirst() GetFirst()/GetNext.
 482
 483         Removing from the list isn't a thread safe operation
 484         so can't be done when other threads are running that will be using the list.
 485
 486         The list does not own the factories, so removing a factory does not delete it.
 487     */
 488     void Remove();
 489 };
 490
 491
 492 /**
 493     @class wxFilterOutputStream
 494     @wxheader{stream.h}
 495
 496     A filter stream has the capability of a normal
 497     stream but it can be placed on top of another stream. So, for example, it
 498     can compress, encrypt the data which are passed to it and write them to another
 499     stream.
 500
 501     @library{wxbase}
 502     @category{streams}
 503
 504     @seealso
 505     wxFilterClassFactory, wxFilterInputStream
 506 */
 507 class wxFilterOutputStream : public wxOutputStream
 508 {
 509 public:
 510     //@{
 511     /**
 512         Initializes a "filter" stream.
 513
 514         If the parent stream is passed as a pointer then the new filter stream
 515         takes ownership of it. If it is passed by reference then it does not.
 516     */
 517     wxFilterOutputStream(wxOutputStream& stream);
 518         wxFilterOutputStream(wxOutputStream* stream);
 519     //@}
 520 };
 521
 522
 523 /**
 524     @class wxFilterInputStream
 525     @wxheader{stream.h}
 526
 527     A filter stream has the capability of a normal stream but it can be placed on
 528     top
 529     of another stream. So, for example, it can uncompress or decrypt the data which
 530     are read
 531     from another stream and pass it to the requester.
 532
 533     @library{wxbase}
 534     @category{streams}
 535
 536     @seealso
 537     wxFilterClassFactory, wxFilterOutputStream
 538 */
 539 class wxFilterInputStream : public wxInputStream
 540 {
 541 public:
 542     //@{
 543     /**
 544         Initializes a "filter" stream.
 545
 546         If the parent stream is passed as a pointer then the new filter stream
 547         takes ownership of it. If it is passed by reference then it does not.
 548     */
 549     wxFilterInputStream(wxInputStream& stream);
 550         wxFilterInputStream(wxInputStream* stream);
 551     //@}
 552 };
 553
 554
 555 /**
 556     @class wxBufferedOutputStream
 557     @wxheader{stream.h}
 558
 559     This stream acts as a cache. It caches the bytes to be written to the specified
 560     output stream (See wxFilterOutputStream). The
 561     data is only written when the cache is full, when the buffered stream is
 562     destroyed or when calling SeekO().
 563
 564     This class may not be used without some other stream to write the data
 565     to (such as a file stream or a memory stream).
 566
 567     @library{wxbase}
 568     @category{streams}
 569
 570     @seealso
 571     wxStreamBuffer, wxOutputStream
 572 */
 573 class wxBufferedOutputStream : public wxFilterOutputStream
 574 {
 575 public:
 576     /**
 577         Creates a buffered stream using a buffer of a default size of 1024 bytes for
 578         cashing
 579         the stream @e parent.
 580     */
 581     wxBufferedOutputStream(const wxOutputStream& parent);
 582
 583     /**
 584         Destructor. Calls Sync() and destroys the internal buffer.
 585     */
 586     ~wxBufferedOutputStream();
 587
 588     /**
 589         Calls Sync() and changes the stream position.
 590     */
 591     off_t SeekO(off_t pos, wxSeekMode mode);
 592
 593     /**
 594         Flushes the buffer and calls Sync() on the parent stream.
 595     */
 596     void Sync();
 597 };
 598
 599
 600 /**
 601     @class wxInputStream
 602     @wxheader{stream.h}
 603
 604     wxInputStream is an abstract base class which may not be used directly.
 605
 606     @library{wxbase}
 607     @category{streams}
 608 */
 609 class wxInputStream : public wxStreamBase
 610 {
 611 public:
 612     /**
 613         Creates a dummy input stream.
 614     */
 615     wxInputStream();
 616
 617     /**
 618         Destructor.
 619     */
 620     ~wxInputStream();
 621
 622     /**
 623         Returns @true if some data is available in the stream right now, so that
 624         calling Read() wouldn't block.
 625     */
 626     bool CanRead();
 627
 628     /**
 629         Returns @true after an attempt has been made to read past the end of the
 630         stream.
 631     */
 632 #define bool Eof()     /* implementation is private */
 633
 634     /**
 635         Returns the first character in the input queue and removes it,
 636         blocking until it appears if necessary.
 637     */
 638 #define char GetC()     /* implementation is private */
 639
 640     /**
 641         Returns the last number of bytes read.
 642     */
 643     size_t LastRead();
 644
 645     /**
 646         Returns the first character in the input queue without removing it.
 647     */
 648     char Peek();
 649
 650     //@{
 651     /**
 652         Reads data from the input queue and stores it in the specified output stream.
 653         The data is read until an error is raised by one of the two streams.
 654
 655         @returns This function returns a reference on the current object, so the
 656                    user can test any states of the stream right away.
 657     */
 658     wxInputStream Read(void * buffer, size_t size);
 659         Warning Return value
 660 This function returns a reference on the current object, so the user can test
 661 any states of the stream right away.
 662 wxInputStream&  Read(wxOutputStream& stream_out);
 663     //@}
 664
 665     /**
 666         Changes the stream current position.
 667
 668         @param pos
 669         Offset to seek to.
 670
 671         @param mode
 672         One of wxFromStart, wxFromEnd, wxFromCurrent.
 673
 674         @returns The new stream position or wxInvalidOffset on error.
 675     */
 676     off_t SeekI(off_t pos, wxSeekMode mode = wxFromStart);
 677
 678     /**
 679         Returns the current stream position.
 680     */
 681     off_t TellI();
 682
 683     //@{
 684     /**
 685         This function acts like the previous one except that it takes only one
 686         character: it is sometimes shorter to use than the generic function.
 687     */
 688     size_t Ungetch(const char* buffer, size_t size);
 689         Return value bool Ungetch(char c);
 690     //@}
 691 };
 692
 693
 694 /**
 695     @class wxStreamBase
 696     @wxheader{stream.h}
 697
 698     This class is the base class of most stream related classes in wxWidgets. It
 699     must
 700     not be used directly.
 701
 702     @library{wxbase}
 703     @category{streams}
 704
 705     @seealso
 706     wxStreamBuffer
 707 */
 708 class wxStreamBase
 709 {
 710 public:
 711     /**
 712         Creates a dummy stream object. It doesn't do anything.
 713     */
 714     wxStreamBase();
 715
 716     /**
 717         Destructor.
 718     */
 719     ~wxStreamBase();
 720
 721     /**
 722         This function returns the last error.
 723
 724
 725         @b wxSTREAM_NO_ERROR
 726
 727
 728         No error occurred.
 729
 730         @b wxSTREAM_EOF
 731
 732
 733         An End-Of-File occurred.
 734
 735         @b wxSTREAM_WRITE_ERROR
 736
 737
 738         A generic error occurred on the last write call.
 739
 740         @b wxSTREAM_READ_ERROR
 741
 742
 743         A generic error occurred on the last read call.
 744     */
 745     wxStreamError GetLastError();
 746
 747     /**
 748         Returns the length of the stream in bytes. If the length cannot be determined
 749         (this is always the case for socket streams for example), returns
 750         @c wxInvalidOffset.
 751
 752         This function is new since wxWidgets version 2.5.4
 753     */
 754     wxFileOffset GetLength();
 755
 756     /**
 757         GetLength()
 758
 759         This function returns the size of the stream. For example, for a file it is the
 760         size of the file.
 761     */
 762     size_t GetSize();
 763
 764     /**
 765         Returns @true if no error occurred on the stream.
 766
 767         @sa GetLastError()
 768     */
 769 #define virtual bool IsOk()     /* implementation is private */
 770
 771     /**
 772         Returns @true if the streams supports seeking to arbitrary offsets.
 773     */
 774     bool IsSeekable();
 775
 776     /**
 777         Internal function. It is called when the stream wants to read data of the
 778         specified size. It should return the size that was actually read.
 779     */
 780     size_t OnSysRead(void* buffer, size_t bufsize);
 781
 782     /**
 783         Internal function. It is called when the stream needs to change the
 784         current position.
 785     */
 786     off_t OnSysSeek(off_t pos, wxSeekMode mode);
 787
 788     /**
 789         Internal function. Is is called when the stream needs to know the
 790         real position.
 791     */
 792     off_t OnSysTell();
 793
 794     /**
 795         See OnSysRead().
 796     */
 797     size_t OnSysWrite(const void * buffer, size_t bufsize);
 798 };