1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxStreamBase and its derived classes
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
10 @class wxCountingOutputStream
12 wxCountingOutputStream is a specialized output stream which does not write any
13 data anywhere, instead it counts how many bytes would get written if this were a
14 normal stream. This can sometimes be useful or required if some data gets
15 serialized to a stream or compressed by using stream compression and thus the
16 final size of the stream cannot be known other than pretending to write the stream.
17 One case where the resulting size would have to be known is if the data has
18 to be written to a piece of memory and the memory has to be allocated before
19 writing to it (which is probably always the case when writing to a memory stream).
24 class wxCountingOutputStream
: public wxOutputStream
28 Creates a wxCountingOutputStream object.
30 wxCountingOutputStream();
35 virtual ~wxCountingOutputStream();
38 Returns the current size of the stream.
40 size_t GetSize() const;
46 @class wxBufferedInputStream
48 This stream acts as a cache. It caches the bytes read from the specified
49 input stream (see wxFilterInputStream).
50 It uses wxStreamBuffer and sets the default in-buffer size to 1024 bytes.
51 This class may not be used without some other stream to read the data
52 from (such as a file stream or a memory stream).
57 @see wxStreamBuffer, wxInputStream, wxBufferedOutputStream
59 class wxBufferedInputStream
: public wxFilterInputStream
63 Constructor using the provided buffer or default.
66 The associated low-level stream.
68 The buffer to use if non-@NULL. Notice that the ownership of this
69 buffer is taken by the stream, i.e. it will delete it. If this
70 parameter is @NULL a default 1KB buffer is used.
72 wxBufferedInputStream(wxInputStream
& stream
,
73 wxStreamBuffer
*buffer
= NULL
);
76 Constructor allowing to specify the size of the buffer.
78 This is just a more convenient alternative to creating a wxStreamBuffer
79 of the given size and using the other overloaded constructor of this
83 The associated low-level stream.
85 The size of the buffer, in bytes.
89 wxBufferedInputStream(wxInputStream
& stream
, size_t bufsize
);
94 virtual ~wxBufferedInputStream();
100 @class wxStreamBuffer
102 @todo WRITE A DESCRIPTION
114 Constructor, creates a new stream buffer using @a stream as a parent stream
115 and mode as the IO mode.
120 Can be: wxStreamBuffer::read, wxStreamBuffer::write, wxStreamBuffer::read_write.
122 One stream can have many stream buffers but only one is used internally
123 to pass IO call (e.g. wxInputStream::Read() -> wxStreamBuffer::Read()),
124 but you can call directly wxStreamBuffer::Read without any problems.
125 Note that all errors and messages linked to the stream are stored in the
126 stream, not the stream buffers:
129 streambuffer.Read(...);
130 streambuffer2.Read(...); // This call erases previous error messages set by 'streambuffer'
135 wxStreamBuffer(wxStreamBase
& stream
, BufMode mode
);
138 Constructor for an input buffer of the specified size.
140 Using it is equivalent to using the constructor above with read mode
141 and calling SetBufferIO() but is more convenient.
145 wxStreamBuffer(wxInputStream
& stream
, size_t bufsize
);
148 Constructor for an output buffer of the specified size.
150 Using it is equivalent to using the constructor above with write mode
151 and calling SetBufferIO() but is more convenient.
155 wxStreamBuffer(wxOutputStream
& stream
, size_t bufsize
);
158 Constructor; creates a new empty stream buffer which won't flush any data
159 to a stream. mode specifies the type of the buffer (read, write, read_write).
161 This stream buffer has the advantage to be stream independent and to work
162 only on memory buffers but it is still compatible with the rest of the
163 wxStream classes. You can write, read to this special stream and it will
164 grow (if it is allowed by the user) its internal buffer.
165 Briefly, it has all functionality of a "normal" stream.
168 The "read_write" mode doesn't currently work for standalone stream buffers.
172 wxStreamBuffer(BufMode mode
);
177 This method initializes the stream buffer with the data of the specified
178 stream buffer. The new stream buffer has the same attributes, size, position
179 and they share the same buffer. This will cause problems if the stream to
180 which the stream buffer belong is destroyed and the newly cloned stream
181 buffer continues to be used, trying to call functions in the (destroyed)
182 stream. It is advised to use this feature only in very local area of the
185 wxStreamBuffer(const wxStreamBuffer
& buffer
);
189 It finalizes all IO calls and frees all internal buffers if necessary.
199 Toggles the fixed flag. Usually this flag is toggled at the same time as
200 @e flushable. This flag allows (when it has the @false value) or forbids
201 (when it has the @true value) the stream buffer to resize dynamically the
206 void Fixed(bool fixed
);
209 Flushes the IO buffer.
214 Toggles the flushable flag.
215 If @a flushable is disabled, no data are sent to the parent stream.
217 void Flushable(bool flushable
);
220 Returns a pointer on the end of the stream buffer.
222 void* GetBufferEnd() const;
225 Returns a pointer on the current position of the stream buffer.
227 void* GetBufferPos() const;
230 Returns the size of the buffer.
232 size_t GetBufferSize() const;
235 Returns a pointer on the start of the stream buffer.
237 void* GetBufferStart() const;
240 Gets a single char from the stream buffer. It acts like the Read() call.
243 You aren't directly notified if an error occurred during the IO call.
247 virtual char GetChar();
250 Returns the amount of available data in the buffer.
252 size_t GetDataLeft();
255 Returns the current position (counted in bytes) in the stream buffer.
257 size_t GetIntPosition() const;
260 Returns the amount of bytes read during the last IO call to the parent stream.
262 size_t GetLastAccess() const;
265 Puts a single char to the stream buffer.
268 You aren't directly notified if an error occurred during the IO call.
272 virtual void PutChar(char c
);
275 Reads a block of the specified size and stores the data in buffer.
276 This function tries to read from the buffer first and if more data has
277 been requested, reads more data from the associated stream and updates
278 the buffer accordingly until all requested data is read.
280 @return It returns the size of the data read. If the returned size is
281 different of the specified size, an error has occurred and
282 should be tested using GetLastError().
284 virtual size_t Read(void* buffer
, size_t size
);
287 Copies data to @a buffer.
288 The function returns when @a buffer is full or when there isn't
289 any more data in the current buffer.
293 Return value
size_t Read(wxStreamBuffer
* buffer
);
296 Resets to the initial state variables concerning the buffer.
301 Changes the current position.
302 Parameter @a mode may be one of the following:
304 - @b wxFromStart: The position is counted from the start of the stream.
305 - @b wxFromCurrent: The position is counted from the current position of the stream.
306 - @b wxFromEnd: The position is counted from the end of the stream.
308 @return Upon successful completion, it returns the new offset as
309 measured in bytes from the beginning of the stream.
310 Otherwise, it returns wxInvalidOffset.
312 virtual wxFileOffset
Seek(wxFileOffset pos
, wxSeekMode mode
);
315 Specifies which pointers to use for stream buffering.
316 You need to pass a pointer on the start of the buffer end and another
317 on the end. The object will use this buffer to cache stream data.
318 It may be used also as a source/destination buffer when you create an
319 empty stream buffer (See wxStreamBuffer::wxStreamBuffer).
322 When you use this function, you will have to destroy the IO buffers
323 yourself after the stream buffer is destroyed or don't use it anymore.
324 In the case you use it with an empty buffer, the stream buffer will not
325 resize it when it is full.
327 @see wxStreamBuffer(), Fixed(), Flushable()
329 void SetBufferIO(char* buffer_start
, char* buffer_end
);
332 Destroys or invalidates the previous IO buffer and allocates a new one of the
336 All previous pointers aren't valid anymore.
339 The created IO buffer is growable by the object.
341 @see Fixed(), Flushable()
343 void SetBufferIO(size_t bufsize
);
346 Sets the current position (in bytes) in the stream buffer.
349 Since it is a very low-level function, there is no check on the position:
350 specifying an invalid position can induce unexpected results.
352 void SetIntPosition(size_t pos
);
355 Returns the parent stream of the stream buffer.
357 wxStreamBase
* Stream();
360 Gets the current position in the stream. This position is calculated from
361 the @e real position in the stream and from the internal buffer position: so
362 it gives you the position in the @e real stream counted from the start of
365 @return Returns the current position in the stream if possible,
366 wxInvalidOffset in the other case.
368 virtual wxFileOffset
Tell() const;
371 Truncates the buffer to the current position.
373 @note Truncate() cannot be used to enlarge the buffer. This is
374 usually not needed since the buffer expands automatically.
379 Writes a block of the specified size using data of buffer.
380 The data are cached in a buffer before being sent in one block to the stream.
382 virtual size_t Write(const void* buffer
, size_t size
);
387 size_t Write(wxStreamBuffer
* buffer
);
393 @class wxOutputStream
395 wxOutputStream is an abstract base class which may not be used directly.
400 class wxOutputStream
: public wxStreamBase
404 Creates a dummy wxOutputStream object.
411 virtual ~wxOutputStream();
414 Closes the stream, returning @false if an error occurs.
415 The stream is closed implicitly in the destructor if Close() is not
418 If this stream wraps another stream or some other resource such
419 as a file, then the underlying resource is closed too if it is owned
420 by this stream, or left open otherwise.
422 virtual bool Close();
425 Returns the number of bytes written during the last Write().
426 It may return 0 even if there is no error on the stream if it is
427 only temporarily impossible to write to it.
429 virtual size_t LastWrite() const;
432 Puts the specified character in the output queue and increments the
438 Changes the stream current position.
443 One of wxFromStart, wxFromEnd, wxFromCurrent.
445 @return The new stream position or wxInvalidOffset on error.
447 virtual wxFileOffset
SeekO(wxFileOffset pos
, wxSeekMode mode
= wxFromStart
);
450 Returns the current stream position.
452 virtual wxFileOffset
TellO() const;
455 Writes up to the specified amount of bytes using the data of buffer.
456 Note that not all data can always be written so you must check the number
457 of bytes really written to the stream using LastWrite() when this function
460 In some cases (for example a write end of a pipe which is currently full)
461 it is even possible that there is no errors and zero bytes have been written.
462 This function returns a reference on the current object, so the user can
463 test any states of the stream right away.
465 wxOutputStream
Write(const void* buffer
, size_t size
);
468 Reads data from the specified input stream and stores them
469 in the current stream. The data is read until an error is raised
470 by one of the two streams.
472 wxOutputStream
Write(wxInputStream
& stream_in
);
477 Enumeration values used by wxFilterClassFactory.
479 enum wxStreamProtocolType
481 wxSTREAM_PROTOCOL
, //!< wxFileSystem protocol (should be only one).
482 wxSTREAM_MIMETYPE
, //!< MIME types the stream handles.
483 wxSTREAM_ENCODING
, //!< The HTTP Content-Encodings the stream handles.
484 wxSTREAM_FILEEXT
//!< File extensions the stream handles.
489 @class wxFilterClassFactory
491 Allows the creation of filter streams to handle compression formats such
494 For example, given a filename you can search for a factory that will
495 handle it and create a stream to decompress it:
498 factory = wxFilterClassFactory::Find(filename, wxSTREAM_FILEEXT);
500 stream = factory-NewStream(new wxFFileInputStream(filename));
503 wxFilterClassFactory::Find can also search for a factory by MIME type,
504 HTTP encoding or by wxFileSystem protocol.
505 The available factories can be enumerated using wxFilterClassFactory::GetFirst()
506 and wxFilterClassFactory::GetNext().
511 @see wxFilterInputStream, wxFilterOutputStream, wxArchiveClassFactory,
512 @ref overview_archive
514 class wxFilterClassFactory
: public wxObject
518 Returns @true if this factory can handle the given protocol, MIME type, HTTP
519 encoding or file extension.
521 When using @c wxSTREAM_FILEEXT for the second parameter, the first parameter
522 can be a complete filename rather than just an extension.
524 bool CanHandle(const wxString
& protocol
,
525 wxStreamProtocolType type
= wxSTREAM_PROTOCOL
) const;
528 A static member that finds a factory that can handle a given protocol, MIME
529 type, HTTP encoding or file extension. Returns a pointer to the class
530 factory if found, or @NULL otherwise.
531 It does not give away ownership of the factory.
533 When using @c wxSTREAM_FILEEXT for the second parameter, the first parameter
534 can be a complete filename rather than just an extension.
536 static const wxFilterClassFactory
* Find(const wxString
& protocol
,
537 wxStreamProtocolType type
= wxSTREAM_PROTOCOL
);
541 GetFirst and GetNext can be used to enumerate the available factories.
542 For example, to list them:
546 const wxFilterClassFactory *factory = wxFilterClassFactory::GetFirst();
549 list << factory->GetProtocol() << _T("\n");
550 factory = factory->GetNext();
554 GetFirst()/GetNext() return a pointer to a factory or @NULL if no more
555 are available. They do not give away ownership of the factory.
557 static const wxFilterClassFactory
* GetFirst() const;
558 const wxFilterClassFactory
* GetNext() const;
562 Returns the wxFileSystem protocol supported by this factory.
563 Equivalent to @code wxString(*GetProtocols()) @endcode.
565 wxString
GetProtocol() const;
568 Returns the protocols, MIME types, HTTP encodings or file extensions
569 supported by this factory, as an array of null terminated strings.
570 It does not give away ownership of the array or strings.
572 For example, to list the file extensions a factory supports:
576 const wxChar *const *p;
578 for (p = factory->GetProtocols(wxSTREAM_FILEEXT); *p; p++)
579 list << *p << _T("\n");
582 virtual const wxChar
* const* GetProtocols(wxStreamProtocolType type
= wxSTREAM_PROTOCOL
) const = 0;
586 Create a new input or output stream to decompress or compress a given stream.
588 If the parent stream is passed as a pointer then the new filter stream
589 takes ownership of it. If it is passed by reference then it does not.
591 wxFilterInputStream
* NewStream(wxInputStream
& stream
) const;
592 wxFilterOutputStream
* NewStream(wxOutputStream
& stream
) const;
593 wxFilterInputStream
* NewStream(wxInputStream
* stream
) const;
594 wxFilterOutputStream
* NewStream(wxOutputStream
* stream
) const;
598 Remove the file extension of @a location if it is one of the file
599 extensions handled by this factory.
601 wxString
PopExtension(const wxString
& location
) const;
604 Adds this class factory to the list returned by GetFirst()/GetNext().
606 It is not necessary to do this to use the filter streams. It is usually
607 used when implementing streams, typically the implementation will
608 add a static instance of its factory class.
610 It can also be used to change the order of a factory already in the list,
611 bringing it to the front. This isn't a thread safe operation so can't be
612 done when other threads are running that will be using the list.
614 The list does not take ownership of the factory.
619 Removes this class factory from the list returned by GetFirst()/GetNext().
620 Removing from the list isn't a thread safe operation so can't be done
621 when other threads are running that will be using the list.
623 The list does not own the factories, so removing a factory does not delete it.
631 @class wxFilterOutputStream
633 A filter stream has the capability of a normal stream but it can be placed
634 on top of another stream. So, for example, it can compress, encrypt the data
635 which are passed to it and write them to another stream.
638 The use of this class is exactly the same as of wxOutputStream.
639 Only a constructor differs and it is documented below.
644 @see wxFilterClassFactory, wxFilterInputStream
646 class wxFilterOutputStream
: public wxOutputStream
651 Initializes a "filter" stream.
653 If the parent stream is passed as a pointer then the new filter stream
654 takes ownership of it. If it is passed by reference then it does not.
656 wxFilterOutputStream(wxOutputStream
& stream
);
657 wxFilterOutputStream(wxOutputStream
* stream
);
664 @class wxFilterInputStream
666 A filter stream has the capability of a normal stream but it can be placed on
667 top of another stream. So, for example, it can uncompress or decrypt the data which
668 are read from another stream and pass it to the requester.
671 The interface of this class is the same as that of wxInputStream.
672 Only a constructor differs and it is documented below.
677 @see wxFilterClassFactory, wxFilterOutputStream
679 class wxFilterInputStream
: public wxInputStream
684 Initializes a "filter" stream.
686 If the parent stream is passed as a pointer then the new filter stream
687 takes ownership of it. If it is passed by reference then it does not.
689 wxFilterInputStream(wxInputStream
& stream
);
690 wxFilterInputStream(wxInputStream
* stream
);
697 @class wxBufferedOutputStream
699 This stream acts as a cache. It caches the bytes to be written to the specified
700 output stream (See wxFilterOutputStream). The data is only written when the
701 cache is full, when the buffered stream is destroyed or when calling SeekO().
703 This class may not be used without some other stream to write the data
704 to (such as a file stream or a memory stream).
709 @see wxStreamBuffer, wxOutputStream
711 class wxBufferedOutputStream
: public wxFilterOutputStream
715 Constructor using the provided buffer or default.
718 The associated low-level stream.
720 The buffer to use if non-@NULL. Notice that the ownership of this
721 buffer is taken by the stream, i.e. it will delete it. If this
722 parameter is @NULL a default 1KB buffer is used.
724 wxBufferedOutputStream(wxOutputStream
& stream
,
725 wxStreamBuffer
*buffer
= NULL
);
728 Constructor allowing to specify the size of the buffer.
730 This is just a more convenient alternative to creating a wxStreamBuffer
731 of the given size and using the other overloaded constructor of this
735 The associated low-level stream.
737 The size of the buffer, in bytes.
741 wxBufferedOutputStream(wxOutputStream
& stream
, size_t bufsize
);
744 Destructor. Calls Sync() and destroys the internal buffer.
746 virtual ~wxBufferedOutputStream();
749 Calls Sync() and changes the stream position.
751 virtual wxFileOffset
SeekO(wxFileOffset pos
, wxSeekMode mode
= wxFromStart
);
754 Flushes the buffer and calls Sync() on the parent stream.
764 wxInputStream is an abstract base class which may not be used directly.
769 class wxInputStream
: public wxStreamBase
773 Creates a dummy input stream.
780 virtual ~wxInputStream();
783 Returns @true if some data is available in the stream right now, so that
784 calling Read() wouldn't block.
786 virtual bool CanRead() const;
789 Returns @true after an attempt has been made to read past the end of the
792 virtual bool Eof() const;
795 Returns the first character in the input queue and removes it,
796 blocking until it appears if necessary.
801 Returns the last number of bytes read.
803 virtual size_t LastRead() const;
806 Returns the first character in the input queue without removing it.
811 Reads the specified amount of bytes and stores the data in buffer.
814 The buffer absolutely needs to have at least the specified size.
816 @return This function returns a reference on the current object, so the
817 user can test any states of the stream right away.
819 wxInputStream
Read(void* buffer
, size_t size
);
822 Reads data from the input queue and stores it in the specified output stream.
823 The data is read until an error is raised by one of the two streams.
825 @return This function returns a reference on the current object, so the
826 user can test any states of the stream right away.
828 wxInputStream
& Read(wxOutputStream
& stream_out
);
831 Changes the stream current position.
836 One of wxFromStart, wxFromEnd, wxFromCurrent.
838 @return The new stream position or wxInvalidOffset on error.
840 virtual wxFileOffset
SeekI(wxFileOffset pos
, wxSeekMode mode
= wxFromStart
);
843 Returns the current stream position.
845 virtual wxFileOffset
TellI() const;
848 This function is only useful in read mode.
849 It is the manager of the "Write-Back" buffer. This buffer acts like a
850 temporary buffer where data which has to be read during the next read IO
851 call are put. This is useful when you get a big block of data which you
852 didn't want to read: you can replace them at the top of the input queue
855 Be very careful about this call in connection with calling SeekI() on
856 the same stream. Any call to SeekI() will invalidate any previous call
857 to this method (otherwise you could SeekI() to one position, "unread" a
858 few bytes there, SeekI() to another position and data would be either
861 @return Returns the amount of bytes saved in the Write-Back buffer.
863 size_t Ungetch(const char* buffer
, size_t size
);
866 This function acts like the previous one except that it takes only one
867 character: it is sometimes shorter to use than the generic function.
869 Return value
bool Ungetch(char c
);
874 These enumeration values are returned by various functions in the context
879 wxSTREAM_NO_ERROR
= 0, //!< No error occurred.
880 wxSTREAM_EOF
, //!< EOF reached in Read() or similar.
881 wxSTREAM_WRITE_ERROR
, //!< generic write error on the last write call.
882 wxSTREAM_READ_ERROR
//!< generic read error on the last read call.
888 This class is the base class of most stream related classes in wxWidgets.
889 It must not be used directly.
900 Creates a dummy stream object. It doesn't do anything.
907 virtual ~wxStreamBase();
910 This function returns the last error.
912 wxStreamError
GetLastError() const;
915 Returns the length of the stream in bytes. If the length cannot be
916 determined (this is always the case for socket streams for example),
917 returns @c wxInvalidOffset.
921 virtual wxFileOffset
GetLength() const;
924 This function returns the size of the stream.
925 For example, for a file it is the size of the file.
928 There are streams which do not have size by definition, such as socket
929 streams. In that cases, GetSize returns 0 so you should always test its
932 virtual size_t GetSize() const;
935 Returns @true if no error occurred on the stream.
939 virtual bool IsOk() const;
942 Returns @true if the streams supports seeking to arbitrary offsets.
944 virtual bool IsSeekable() const;
947 Internal function. It is called when the stream wants to read data of the
948 specified size. It should return the size that was actually read.
950 size_t OnSysRead(void* buffer
, size_t bufsize
);
955 size_t OnSysWrite(const void* buffer
, size_t bufsize
);
962 It is called when the stream needs to change the current position.
964 virtual wxFileOffset
OnSysSeek(wxFileOffset pos
, wxSeekMode mode
);
968 It is called when the stream needs to know the real position.
970 virtual wxFileOffset
OnSysTell() const;