1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: stream classes
4 // Author: Guilhem Lavaux, Guillermo Rodriguez Garcia, Vadim Zeitlin
8 // Copyright: (c) Guilhem Lavaux
9 // Licence: wxWindows licence
10 /////////////////////////////////////////////////////////////////////////////
12 #ifndef _WX_WXSTREAM_H__
13 #define _WX_WXSTREAM_H__
20 #include "wx/object.h"
21 #include "wx/string.h"
22 #include "wx/filefn.h" // for wxFileOffset, wxInvalidOffset and wxSeekMode
24 class WXDLLIMPEXP_FWD_BASE wxStreamBase
;
25 class WXDLLIMPEXP_FWD_BASE wxInputStream
;
26 class WXDLLIMPEXP_FWD_BASE wxOutputStream
;
28 typedef wxInputStream
& (*__wxInputManip
)(wxInputStream
&);
29 typedef wxOutputStream
& (*__wxOutputManip
)(wxOutputStream
&);
31 WXDLLIMPEXP_BASE wxOutputStream
& wxEndL(wxOutputStream
& o_stream
);
33 // ----------------------------------------------------------------------------
35 // ----------------------------------------------------------------------------
39 wxSTREAM_NO_ERROR
= 0, // stream is in good state
40 wxSTREAM_EOF
, // EOF reached in Read() or similar
41 wxSTREAM_WRITE_ERROR
, // generic write error
42 wxSTREAM_READ_ERROR
// generic read error
47 // ============================================================================
48 // base stream classes: wxInputStream and wxOutputStream
49 // ============================================================================
51 // ---------------------------------------------------------------------------
52 // wxStreamBase: common (but non virtual!) base for all stream classes
53 // ---------------------------------------------------------------------------
55 class WXDLLIMPEXP_BASE wxStreamBase
: public wxObject
59 virtual ~wxStreamBase();
62 wxStreamError
GetLastError() const { return m_lasterror
; }
63 virtual bool IsOk() const { return GetLastError() == wxSTREAM_NO_ERROR
; }
64 bool operator!() const { return !IsOk(); }
66 // reset the stream state
67 void Reset() { m_lasterror
= wxSTREAM_NO_ERROR
; }
69 // this doesn't make sense for all streams, always test its return value
70 virtual size_t GetSize() const;
71 virtual wxFileOffset
GetLength() const { return wxInvalidOffset
; }
73 // returns true if the streams supports seeking to arbitrary offsets
74 virtual bool IsSeekable() const { return false; }
77 virtual wxFileOffset
OnSysSeek(wxFileOffset seek
, wxSeekMode mode
);
78 virtual wxFileOffset
OnSysTell() const;
81 wxStreamError m_lasterror
;
83 friend class wxStreamBuffer
;
85 DECLARE_ABSTRACT_CLASS(wxStreamBase
)
86 wxDECLARE_NO_COPY_CLASS(wxStreamBase
);
89 // ----------------------------------------------------------------------------
90 // wxInputStream: base class for the input streams
91 // ----------------------------------------------------------------------------
93 class WXDLLIMPEXP_BASE wxInputStream
: public wxStreamBase
96 // ctor and dtor, nothing exciting
98 virtual ~wxInputStream();
104 // return a character from the stream without removing it, i.e. it will
105 // still be returned by the next call to GetC()
107 // blocks until something appears in the stream if necessary, if nothing
108 // ever does (i.e. EOF) LastRead() will return 0 (and the return value is
109 // undefined), otherwise 1
112 // return one byte from the stream, blocking until it appears if
115 // on success returns a value between 0 - 255, or wxEOF on EOF or error.
118 // read at most the given number of bytes from the stream
120 // there are 2 possible situations here: either there is nothing at all in
121 // the stream right now in which case Read() blocks until something appears
122 // (use CanRead() to avoid this) or there is already some data available in
123 // the stream and then Read() doesn't block but returns just the data it
124 // can read without waiting for more
126 // in any case, if there are not enough bytes in the stream right now,
127 // LastRead() value will be less than size but greater than 0. If it is 0,
128 // it means that EOF has been reached.
129 virtual wxInputStream
& Read(void *buffer
, size_t size
);
131 // copy the entire contents of this stream into streamOut, stopping only
132 // when EOF is reached or an error occurs
133 wxInputStream
& Read(wxOutputStream
& streamOut
);
139 // returns the number of bytes read by the last call to Read(), GetC() or
142 // this should be used to discover whether that call succeeded in reading
143 // all the requested data or not
144 virtual size_t LastRead() const { return wxStreamBase::m_lastcount
; }
146 // returns true if some data is available in the stream right now, so that
147 // calling Read() wouldn't block
148 virtual bool CanRead() const;
150 // is the stream at EOF?
152 // note that this cannot be really implemented for all streams and
153 // CanRead() is more reliable than Eof()
154 virtual bool Eof() const;
160 // put back the specified number of bytes into the stream, they will be
161 // fetched by the next call to the read functions
163 // returns the number of bytes really stuffed back
164 size_t Ungetch(const void *buffer
, size_t size
);
166 // put back the specified character in the stream
168 // returns true if ok, false on error
169 bool Ungetch(char c
);
172 // position functions
173 // ------------------
175 // move the stream pointer to the given position (if the stream supports
178 // returns wxInvalidOffset on error
179 virtual wxFileOffset
SeekI(wxFileOffset pos
, wxSeekMode mode
= wxFromStart
);
181 // return the current position of the stream pointer or wxInvalidOffset
182 virtual wxFileOffset
TellI() const;
185 // stream-like operators
186 // ---------------------
188 wxInputStream
& operator>>(wxOutputStream
& out
) { return Read(out
); }
189 wxInputStream
& operator>>(__wxInputManip func
) { return func(*this); }
192 // do read up to size bytes of data into the provided buffer
194 // this method should return 0 if EOF has been reached or an error occurred
195 // (m_lasterror should be set accordingly as well) or the number of bytes
197 virtual size_t OnSysRead(void *buffer
, size_t size
) = 0;
199 // write-back buffer support
200 // -------------------------
202 // return the pointer to a buffer big enough to hold sizeNeeded bytes
203 char *AllocSpaceWBack(size_t sizeNeeded
);
205 // read up to size data from the write back buffer, return the number of
207 size_t GetWBack(void *buf
, size_t size
);
209 // write back buffer or NULL if none
212 // the size of the buffer
215 // the current position in the buffer
218 friend class wxStreamBuffer
;
220 DECLARE_ABSTRACT_CLASS(wxInputStream
)
221 wxDECLARE_NO_COPY_CLASS(wxInputStream
);
224 // ----------------------------------------------------------------------------
225 // wxOutputStream: base for the output streams
226 // ----------------------------------------------------------------------------
228 class WXDLLIMPEXP_BASE wxOutputStream
: public wxStreamBase
232 virtual ~wxOutputStream();
235 virtual wxOutputStream
& Write(const void *buffer
, size_t size
);
236 wxOutputStream
& Write(wxInputStream
& stream_in
);
238 virtual wxFileOffset
SeekO(wxFileOffset pos
, wxSeekMode mode
= wxFromStart
);
239 virtual wxFileOffset
TellO() const;
241 virtual size_t LastWrite() const { return wxStreamBase::m_lastcount
; }
244 virtual bool Close() { return true; }
246 wxOutputStream
& operator<<(wxInputStream
& out
) { return Write(out
); }
247 wxOutputStream
& operator<<( __wxOutputManip func
) { return func(*this); }
250 // to be implemented in the derived classes (it should have been pure
252 virtual size_t OnSysWrite(const void *buffer
, size_t bufsize
);
254 friend class wxStreamBuffer
;
256 DECLARE_ABSTRACT_CLASS(wxOutputStream
)
257 wxDECLARE_NO_COPY_CLASS(wxOutputStream
);
260 // ============================================================================
261 // helper stream classes
262 // ============================================================================
264 // ---------------------------------------------------------------------------
265 // A stream for measuring streamed output
266 // ---------------------------------------------------------------------------
268 class WXDLLIMPEXP_BASE wxCountingOutputStream
: public wxOutputStream
271 wxCountingOutputStream();
273 wxFileOffset
GetLength() const;
274 bool Ok() const { return IsOk(); }
275 bool IsOk() const { return true; }
278 virtual size_t OnSysWrite(const void *buffer
, size_t size
);
279 virtual wxFileOffset
OnSysSeek(wxFileOffset pos
, wxSeekMode mode
);
280 virtual wxFileOffset
OnSysTell() const;
284 DECLARE_DYNAMIC_CLASS(wxCountingOutputStream
)
285 wxDECLARE_NO_COPY_CLASS(wxCountingOutputStream
);
288 // ---------------------------------------------------------------------------
290 // ---------------------------------------------------------------------------
292 class WXDLLIMPEXP_BASE wxFilterInputStream
: public wxInputStream
295 wxFilterInputStream();
296 wxFilterInputStream(wxInputStream
& stream
);
297 wxFilterInputStream(wxInputStream
*stream
);
298 virtual ~wxFilterInputStream();
300 char Peek() { return m_parent_i_stream
->Peek(); }
302 wxFileOffset
GetLength() const { return m_parent_i_stream
->GetLength(); }
304 wxInputStream
*GetFilterInputStream() const { return m_parent_i_stream
; }
307 wxInputStream
*m_parent_i_stream
;
310 DECLARE_ABSTRACT_CLASS(wxFilterInputStream
)
311 wxDECLARE_NO_COPY_CLASS(wxFilterInputStream
);
314 class WXDLLIMPEXP_BASE wxFilterOutputStream
: public wxOutputStream
317 wxFilterOutputStream();
318 wxFilterOutputStream(wxOutputStream
& stream
);
319 wxFilterOutputStream(wxOutputStream
*stream
);
320 virtual ~wxFilterOutputStream();
322 wxFileOffset
GetLength() const { return m_parent_o_stream
->GetLength(); }
324 wxOutputStream
*GetFilterOutputStream() const { return m_parent_o_stream
; }
329 wxOutputStream
*m_parent_o_stream
;
332 DECLARE_ABSTRACT_CLASS(wxFilterOutputStream
)
333 wxDECLARE_NO_COPY_CLASS(wxFilterOutputStream
);
336 enum wxStreamProtocolType
338 wxSTREAM_PROTOCOL
, // wxFileSystem protocol (should be only one)
339 wxSTREAM_MIMETYPE
, // MIME types the stream handles
340 wxSTREAM_ENCODING
, // The HTTP Content-Encodings the stream handles
341 wxSTREAM_FILEEXT
// File extensions the stream handles
344 void WXDLLIMPEXP_BASE
wxUseFilterClasses();
346 class WXDLLIMPEXP_BASE wxFilterClassFactoryBase
: public wxObject
349 virtual ~wxFilterClassFactoryBase() { }
351 wxString
GetProtocol() const { return wxString(*GetProtocols()); }
352 wxString
PopExtension(const wxString
& location
) const;
354 virtual const wxChar
* const *GetProtocols(wxStreamProtocolType type
355 = wxSTREAM_PROTOCOL
) const = 0;
357 bool CanHandle(const wxString
& protocol
,
358 wxStreamProtocolType type
359 = wxSTREAM_PROTOCOL
) const;
362 wxString::size_type
FindExtension(const wxString
& location
) const;
364 DECLARE_ABSTRACT_CLASS(wxFilterClassFactoryBase
)
367 class WXDLLIMPEXP_BASE wxFilterClassFactory
: public wxFilterClassFactoryBase
370 virtual ~wxFilterClassFactory() { }
372 virtual wxFilterInputStream
*NewStream(wxInputStream
& stream
) const = 0;
373 virtual wxFilterOutputStream
*NewStream(wxOutputStream
& stream
) const = 0;
374 virtual wxFilterInputStream
*NewStream(wxInputStream
*stream
) const = 0;
375 virtual wxFilterOutputStream
*NewStream(wxOutputStream
*stream
) const = 0;
377 static const wxFilterClassFactory
*Find(const wxString
& protocol
,
378 wxStreamProtocolType type
379 = wxSTREAM_PROTOCOL
);
381 static const wxFilterClassFactory
*GetFirst();
382 const wxFilterClassFactory
*GetNext() const { return m_next
; }
384 void PushFront() { Remove(); m_next
= sm_first
; sm_first
= this; }
388 wxFilterClassFactory() : m_next(this) { }
390 wxFilterClassFactory
& operator=(const wxFilterClassFactory
&)
394 static wxFilterClassFactory
*sm_first
;
395 wxFilterClassFactory
*m_next
;
397 DECLARE_ABSTRACT_CLASS(wxFilterClassFactory
)
400 // ============================================================================
402 // ============================================================================
404 // ---------------------------------------------------------------------------
405 // Stream buffer: this class can be derived from and passed to
406 // wxBufferedStreams to implement custom buffering
407 // ---------------------------------------------------------------------------
409 class WXDLLIMPEXP_BASE wxStreamBuffer
419 wxStreamBuffer(wxStreamBase
& stream
, BufMode mode
)
421 InitWithStream(stream
, mode
);
424 wxStreamBuffer(wxInputStream
& stream
, size_t bufsize
)
426 InitWithStream(stream
, read
);
427 SetBufferIO(bufsize
);
430 wxStreamBuffer(wxOutputStream
& stream
, size_t bufsize
)
432 InitWithStream(stream
, write
);
433 SetBufferIO(bufsize
);
436 wxStreamBuffer(const wxStreamBuffer
& buf
);
437 virtual ~wxStreamBuffer();
440 virtual size_t Read(void *buffer
, size_t size
);
441 size_t Read(wxStreamBuffer
*buf
);
442 virtual size_t Write(const void *buffer
, size_t size
);
443 size_t Write(wxStreamBuffer
*buf
);
446 virtual char GetChar();
447 virtual void PutChar(char c
);
448 virtual wxFileOffset
Tell() const;
449 virtual wxFileOffset
Seek(wxFileOffset pos
, wxSeekMode mode
);
455 // NB: the buffer must always be allocated with malloc() if takeOwn is
456 // true as it will be deallocated by free()
457 void SetBufferIO(void *start
, void *end
, bool takeOwnership
= false);
458 void SetBufferIO(void *start
, size_t len
, bool takeOwnership
= false);
459 void SetBufferIO(size_t bufsize
);
460 void *GetBufferStart() const { return m_buffer_start
; }
461 void *GetBufferEnd() const { return m_buffer_end
; }
462 void *GetBufferPos() const { return m_buffer_pos
; }
463 size_t GetBufferSize() const { return m_buffer_end
- m_buffer_start
; }
464 size_t GetIntPosition() const { return m_buffer_pos
- m_buffer_start
; }
465 void SetIntPosition(size_t pos
) { m_buffer_pos
= m_buffer_start
+ pos
; }
466 size_t GetLastAccess() const { return m_buffer_end
- m_buffer_start
; }
467 size_t GetBytesLeft() const { return m_buffer_end
- m_buffer_pos
; }
469 void Fixed(bool fixed
) { m_fixed
= fixed
; }
470 void Flushable(bool f
) { m_flushable
= f
; }
474 size_t GetDataLeft();
477 wxStreamBase
*GetStream() const { return m_stream
; }
478 bool HasBuffer() const { return m_buffer_start
!= m_buffer_end
; }
480 bool IsFixed() const { return m_fixed
; }
481 bool IsFlushable() const { return m_flushable
; }
483 // only for input/output buffers respectively, returns NULL otherwise
484 wxInputStream
*GetInputStream() const;
485 wxOutputStream
*GetOutputStream() const;
487 #if WXWIN_COMPATIBILITY_2_6
488 // deprecated, for compatibility only
489 wxDEPRECATED( wxStreamBase
*Stream() );
490 #endif // WXWIN_COMPATIBILITY_2_6
492 // this constructs a dummy wxStreamBuffer, used by (and exists for)
493 // wxMemoryStreams only, don't use!
494 wxStreamBuffer(BufMode mode
);
497 void GetFromBuffer(void *buffer
, size_t size
);
498 void PutToBuffer(const void *buffer
, size_t size
);
500 // set the last error to the specified value if we didn't have it before
501 void SetError(wxStreamError err
);
503 // common part of several ctors
506 // common part of ctors taking wxStreamBase parameter
507 void InitWithStream(wxStreamBase
& stream
, BufMode mode
);
509 // init buffer variables to be empty
512 // free the buffer (always safe to call)
515 // the buffer itself: the pointers to its start and end and the current
516 // position in the buffer
517 char *m_buffer_start
,
521 // the stream we're associated with
522 wxStreamBase
*m_stream
;
528 bool m_destroybuf
, // deallocate buffer?
533 wxDECLARE_NO_ASSIGN_CLASS(wxStreamBuffer
);
536 // ---------------------------------------------------------------------------
537 // wxBufferedInputStream
538 // ---------------------------------------------------------------------------
540 class WXDLLIMPEXP_BASE wxBufferedInputStream
: public wxFilterInputStream
543 // create a buffered stream on top of the specified low-level stream
545 // if a non NULL buffer is given to the stream, it will be deleted by it,
546 // otherwise a default 1KB buffer will be used
547 wxBufferedInputStream(wxInputStream
& stream
,
548 wxStreamBuffer
*buffer
= NULL
);
550 // ctor allowing to specify the buffer size, it's just a more convenient
551 // alternative to creating wxStreamBuffer, calling its SetBufferIO(bufsize)
552 // and using the ctor above
553 wxBufferedInputStream(wxInputStream
& stream
, size_t bufsize
);
556 virtual ~wxBufferedInputStream();
559 wxInputStream
& Read(void *buffer
, size_t size
);
561 // Position functions
562 wxFileOffset
SeekI(wxFileOffset pos
, wxSeekMode mode
= wxFromStart
);
563 wxFileOffset
TellI() const;
564 bool IsSeekable() const { return m_parent_i_stream
->IsSeekable(); }
566 // the buffer given to the stream will be deleted by it
567 void SetInputStreamBuffer(wxStreamBuffer
*buffer
);
568 wxStreamBuffer
*GetInputStreamBuffer() const { return m_i_streambuf
; }
570 #if WXWIN_COMPATIBILITY_2_6
571 // deprecated, for compatibility only
572 wxDEPRECATED( wxStreamBuffer
*InputStreamBuffer() const );
573 #endif // WXWIN_COMPATIBILITY_2_6
576 virtual size_t OnSysRead(void *buffer
, size_t bufsize
);
577 virtual wxFileOffset
OnSysSeek(wxFileOffset seek
, wxSeekMode mode
);
578 virtual wxFileOffset
OnSysTell() const;
580 wxStreamBuffer
*m_i_streambuf
;
582 wxDECLARE_NO_COPY_CLASS(wxBufferedInputStream
);
585 // ----------------------------------------------------------------------------
586 // wxBufferedOutputStream
587 // ----------------------------------------------------------------------------
589 class WXDLLIMPEXP_BASE wxBufferedOutputStream
: public wxFilterOutputStream
592 // create a buffered stream on top of the specified low-level stream
594 // if a non NULL buffer is given to the stream, it will be deleted by it,
595 // otherwise a default 1KB buffer will be used
596 wxBufferedOutputStream(wxOutputStream
& stream
,
597 wxStreamBuffer
*buffer
= NULL
);
599 // ctor allowing to specify the buffer size, it's just a more convenient
600 // alternative to creating wxStreamBuffer, calling its SetBufferIO(bufsize)
601 // and using the ctor above
602 wxBufferedOutputStream(wxOutputStream
& stream
, size_t bufsize
);
604 virtual ~wxBufferedOutputStream();
606 wxOutputStream
& Write(const void *buffer
, size_t size
);
608 // Position functions
609 wxFileOffset
SeekO(wxFileOffset pos
, wxSeekMode mode
= wxFromStart
);
610 wxFileOffset
TellO() const;
611 bool IsSeekable() const { return m_parent_o_stream
->IsSeekable(); }
616 wxFileOffset
GetLength() const;
618 // the buffer given to the stream will be deleted by it
619 void SetOutputStreamBuffer(wxStreamBuffer
*buffer
);
620 wxStreamBuffer
*GetOutputStreamBuffer() const { return m_o_streambuf
; }
622 #if WXWIN_COMPATIBILITY_2_6
623 // deprecated, for compatibility only
624 wxDEPRECATED( wxStreamBuffer
*OutputStreamBuffer() const );
625 #endif // WXWIN_COMPATIBILITY_2_6
628 virtual size_t OnSysWrite(const void *buffer
, size_t bufsize
);
629 virtual wxFileOffset
OnSysSeek(wxFileOffset seek
, wxSeekMode mode
);
630 virtual wxFileOffset
OnSysTell() const;
632 wxStreamBuffer
*m_o_streambuf
;
634 wxDECLARE_NO_COPY_CLASS(wxBufferedOutputStream
);
637 #if WXWIN_COMPATIBILITY_2_6
638 inline wxStreamBase
*wxStreamBuffer::Stream() { return m_stream
; }
639 inline wxStreamBuffer
*wxBufferedInputStream::InputStreamBuffer() const { return m_i_streambuf
; }
640 inline wxStreamBuffer
*wxBufferedOutputStream::OutputStreamBuffer() const { return m_o_streambuf
; }
641 #endif // WXWIN_COMPATIBILITY_2_6
643 #endif // wxUSE_STREAMS
645 #endif // _WX_WXSTREAM_H__