]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/tstream.tex
wxEvent::Skip() clarification added
[wxWidgets.git] / docs / latex / wx / tstream.tex
CommitLineData
55b7bba1
GL
1\section{Streams in wxWindows overview}\label{wxstreamoverview}
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
11We went into troubles with c++ std streams on some platform:
12they react quite well in most cases, but in multi-threaded case, for example,
13they have a LOT of problems.
14
15Then, wxStreams have been built in wxWindows because an application should compile
16and run on all supported platforms and we don't want users depend on release
17X.XX of libg++ or some other compiler to run the program.
18
19wxStreams is divided in two main parts:
20\begin{enumerate}\itemsep=0pt
21\item the core: wxStreamBase, wxStreamBuffer, wxInputStream, wxOutputStream,
22wxFilterIn/OutputStream
23\item the "IO" classes: wxSocketIn/OutputStream, wxDataIn/OutputStream, wxFileIn/OutputStream, ...
24\end{enumerate}
25
26wxStreamBase is the base definition of a stream. It defines, for example,
27the API of OnSysRead, OnSysWrite, OnSysSeek and OnSysTell. These functions are
28are really implemented by the "IO" classes.
29wxInputStream and wxOutputStream inherit from it.
30
31wxStreamBuffer is a cache manager for wxStreamBase (it manages a stream buffer
32linked to a stream). One stream can have multiple stream buffers but one stream
33have always one autoinitialized stream buffer.
34
35wxInputStream is the base class for read-only streams. It implements Read,
36SeekI (I for Input), and all read or IO generic related functions.
37wxOutputStream does the same thing but it is for write-only streams.
38
39wxFilterIn/OutputStream is base class definition for stream filtering.
40I mean by stream filtering, a stream which does no syscall but filter datas
41which are passed to it and then pass them to another stream.
42For example, wxZLibInputStream is an inline stream decompressor.
43
44The "IO" classes implements the specific parts of the stream. This could be
45nothing in the case of wxMemoryIn/OutputStream which bases itself on
46wxStreamBuffer. This could also be a simple link to the a true syscall
47(for example read(...), write(...)).
48
49\wxheading{Generic usage: an example}
50
51About its usage, it's simple. We can take the example of wxFileInputStream and here is a sample
52code:
53
54\begin{verbatim}
55 ...
56 // The constructor initializes the stream buffer and open the file descriptor
57 // associated to the name of the file.
58 wxFileInputStream in\_stream("the\_file\_to\_be\_read");
59
60 // Ok, read some bytes ... nb\_datas is expressed in bytes.
61 in\_stream.Read(data, nb\_datas);
62 if (in\_stream.LastError() != wxStream\_NOERROR) {
63 // Oh oh, something bad happens.
64 // For a complete list, look into the documentation at wxStreamBase.
65 }
66
67 // You can also inline all like this.
68 if (in\_stream.Read(data, nb\_datas).LastError() != wxStream\_NOERROR) {
69 // Do something.
70 }
71
72 // You can also get the last number of bytes REALLY put into the buffer.
73 size\_t really\_read = in\_stream.LastRead();
74
75 // Ok, moves to the beginning of the stream. SeekI returns the last position
76 // in the stream counted from the beginning.
77 off\_t old_position = in\_stream.SeekI(0, wxFromBeginning);
78
79 // What is my current position ?
80 off\_t position = in\_stream.TellI();
81
82 // wxFileInputStream will close the file descriptor on the destruction.
83\end{verbatim}
84
85\wxheading{Compatibility with c++ stream}
86
87As I said previously, we could add a filter stream so it takes an istream
88argument and builds a wxInputStream from it: I don't think it should
89be difficult to implement it and it may be available in the fix of wxWindows 2.0.