diff --git a/docs/latex/wx/tstream.tex b/docs/latex/wx/tstream.tex new file mode 100644 index 0000000000..5c4bc5c449 --- /dev/null +++ b/docs/latex/wx/tstream.tex @@ -0,0 +1,89 @@ +\section{Streams in wxWindows overview}\label{wxstreamoverview} + +Classes: \helpref{wxStreamBase}{wxstreambase}, + \helpref{wxStreamBuffer}{wxstreambuffer}, \helpref{wxInputStream}{wxinputstream}, + \helpref{wxOutputStream}{wxoutputstream}, + \helpref{wxFilterInputStream}{wxfilterinputstream}, + \helpref{wxFilterOutputStream}{wxfilteroutputstream} + +\wxheading{Purpose of wxStream} + +We went into troubles with c++ std streams on some platform: +they react quite well in most cases, but in multi-threaded case, for example, +they have a LOT of problems. + +Then, wxStreams have been built in wxWindows because an application should compile +and run on all supported platforms and we don't want users depend on release +X.XX of libg++ or some other compiler to run the program. + +wxStreams is divided in two main parts: +\begin{enumerate}\itemsep=0pt +\item the core: wxStreamBase, wxStreamBuffer, wxInputStream, wxOutputStream, +wxFilterIn/OutputStream +\item the "IO" classes: wxSocketIn/OutputStream, wxDataIn/OutputStream, wxFileIn/OutputStream, ... +\end{enumerate} + +wxStreamBase is the base definition of a stream. It defines, for example, +the API of OnSysRead, OnSysWrite, OnSysSeek and OnSysTell. These functions are +are really implemented by the "IO" classes. +wxInputStream and wxOutputStream inherit from it. + +wxStreamBuffer is a cache manager for wxStreamBase (it manages a stream buffer +linked to a stream). One stream can have multiple stream buffers but one stream +have always one autoinitialized stream buffer. + +wxInputStream is the base class for read-only streams. It implements Read, +SeekI (I for Input), and all read or IO generic related functions. +wxOutputStream does the same thing but it is for write-only streams. + +wxFilterIn/OutputStream is base class definition for stream filtering. +I mean by stream filtering, a stream which does no syscall but filter datas +which are passed to it and then pass them to another stream. +For example, wxZLibInputStream is an inline stream decompressor. + +The "IO" classes implements the specific parts of the stream. This could be +nothing in the case of wxMemoryIn/OutputStream which bases itself on +wxStreamBuffer. This could also be a simple link to the a true syscall +(for example read(...), write(...)). + +\wxheading{Generic usage: an example} + +About its usage, it's simple. We can take the example of wxFileInputStream and here is a sample +code: + +\begin{verbatim} + ... + // The constructor initializes the stream buffer and open the file descriptor + // associated to the name of the file. + wxFileInputStream in\_stream("the\_file\_to\_be\_read"); + + // Ok, read some bytes ... nb\_datas is expressed in bytes. + in\_stream.Read(data, nb\_datas); + if (in\_stream.LastError() != wxStream\_NOERROR) { + // Oh oh, something bad happens. + // For a complete list, look into the documentation at wxStreamBase. + } + + // You can also inline all like this. + if (in\_stream.Read(data, nb\_datas).LastError() != wxStream\_NOERROR) { + // Do something. + } + + // You can also get the last number of bytes REALLY put into the buffer. + size\_t really\_read = in\_stream.LastRead(); + + // Ok, moves to the beginning of the stream. SeekI returns the last position + // in the stream counted from the beginning. + off\_t old_position = in\_stream.SeekI(0, wxFromBeginning); + + // What is my current position ? + off\_t position = in\_stream.TellI(); + + // wxFileInputStream will close the file descriptor on the destruction. +\end{verbatim} + +\wxheading{Compatibility with c++ stream} + +As I said previously, we could add a filter stream so it takes an istream +argument and builds a wxInputStream from it: I don't think it should +be difficult to implement it and it may be available in the fix of wxWindows 2.0.