]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/tstream.tex
First step in background erase optimization
[wxWidgets.git] / docs / latex / wx / tstream.tex
CommitLineData
20e05ffb 1\section{wxStreams overview}\label{wxstreamoverview}
55b7bba1
GL
2
3Classes: \helpref{wxStreamBase}{wxstreambase},
4 \helpref{wxStreamBuffer}{wxstreambuffer}, \helpref{wxInputStream}{wxinputstream},
5 \helpref{wxOutputStream}{wxoutputstream},
6 \helpref{wxFilterInputStream}{wxfilterinputstream},
7 \helpref{wxFilterOutputStream}{wxfilteroutputstream}
8
9\wxheading{Purpose of wxStream}
10
2723cfeb
JS
11We had troubles with standard C++ streams on several platforms:
12they react quite well in most cases, but in the multi-threaded case, for example,
4130b487
RR
13they have many problems. Some Borland Compilers refuse to work at all
14with them and using iostreams on Linux makes writing programs, that are
15binary compatible across different Linux distributions, impossible.
55b7bba1 16
fc2171bd 17Therefore, wxStreams have been added to wxWidgets because an application should
2723cfeb 18compile and run on all supported platforms and we don't want users to depend on release
55b7bba1
GL
19X.XX of libg++ or some other compiler to run the program.
20
21wxStreams is divided in two main parts:
2723cfeb 22
55b7bba1
GL
23\begin{enumerate}\itemsep=0pt
24\item the core: wxStreamBase, wxStreamBuffer, wxInputStream, wxOutputStream,
25wxFilterIn/OutputStream
26\item the "IO" classes: wxSocketIn/OutputStream, wxDataIn/OutputStream, wxFileIn/OutputStream, ...
27\end{enumerate}
28
29wxStreamBase is the base definition of a stream. It defines, for example,
f6bcfd97 30the API of OnSysRead, OnSysWrite, OnSysSeek and OnSysTell. These functions
55b7bba1
GL
31are really implemented by the "IO" classes.
32wxInputStream and wxOutputStream inherit from it.
33
34wxStreamBuffer is a cache manager for wxStreamBase (it manages a stream buffer
35linked to a stream). One stream can have multiple stream buffers but one stream
36have always one autoinitialized stream buffer.
37
38wxInputStream is the base class for read-only streams. It implements Read,
39SeekI (I for Input), and all read or IO generic related functions.
40wxOutputStream does the same thing but it is for write-only streams.
41
f6bcfd97
BP
42wxFilterIn/OutputStream is the base class definition for stream filtering.
43Stream filtering means a stream which does no syscall but filters data
55b7bba1
GL
44which are passed to it and then pass them to another stream.
45For example, wxZLibInputStream is an inline stream decompressor.
46
47The "IO" classes implements the specific parts of the stream. This could be
48nothing in the case of wxMemoryIn/OutputStream which bases itself on
49wxStreamBuffer. This could also be a simple link to the a true syscall
50(for example read(...), write(...)).
51
52\wxheading{Generic usage: an example}
53
2723cfeb 54Usage is simple. We can take the example of wxFileInputStream and here is some sample
55b7bba1
GL
55code:
56
57\begin{verbatim}
58 ...
59 // The constructor initializes the stream buffer and open the file descriptor
60 // associated to the name of the file.
4130b487 61 wxFileInputStream in_stream("the_file_to_be_read");
55b7bba1 62
4130b487
RR
63 // Ok, read some bytes ... nb_datas is expressed in bytes.
64 in_stream.Read(data, nb_datas);
20e05ffb 65 if (in_stream.LastError() != wxSTREAM_NOERROR) {
55b7bba1
GL
66 // Oh oh, something bad happens.
67 // For a complete list, look into the documentation at wxStreamBase.
68 }
69
70 // You can also inline all like this.
20e05ffb 71 if (in_stream.Read(data, nb_datas).LastError() != wxSTREAM_NOERROR) {
55b7bba1
GL
72 // Do something.
73 }
74
75 // You can also get the last number of bytes REALLY put into the buffer.
4130b487 76 size_t really_read = in_stream.LastRead();
55b7bba1
GL
77
78 // Ok, moves to the beginning of the stream. SeekI returns the last position
79 // in the stream counted from the beginning.
4130b487 80 off_t old_position = in_stream.SeekI(0, wxFromBeginning);
55b7bba1
GL
81
82 // What is my current position ?
4130b487 83 off_t position = in_stream.TellI();
55b7bba1
GL
84
85 // wxFileInputStream will close the file descriptor on the destruction.
86\end{verbatim}
87
2723cfeb 88\wxheading{Compatibility with C++ streams}
55b7bba1
GL
89
90As I said previously, we could add a filter stream so it takes an istream
91argument and builds a wxInputStream from it: I don't think it should
fc2171bd 92be difficult to implement it and it may be available in the fix of wxWidgets 2.0.
22d6efa8 93