| 1 | \section{wxStreams overview}\label{wxstreamoverview} |
| 2 | |
| 3 | Classes: \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 | |
| 11 | Standard C++ streams can cause problems on several platforms: |
| 12 | they work quite well in most cases, but in the multi-threaded case, for example, |
| 13 | they have many problems. Some Borland compilers refuse to work at all |
| 14 | with them and using iostreams on Linux makes writing programs that are |
| 15 | binary compatible across different Linux distributions, impossible. |
| 16 | |
| 17 | Therefore, wxStreams have been added to wxWidgets so that applications can |
| 18 | reliably compile and run on all supported platforms without dependence on a |
| 19 | particular release of libg++. |
| 20 | |
| 21 | wxStreams is divided in two main parts: |
| 22 | |
| 23 | \begin{enumerate}\itemsep=0pt |
| 24 | \item the core: wxStreamBase, wxStreamBuffer, wxInputStream, wxOutputStream, |
| 25 | wxFilterIn/OutputStream |
| 26 | \item the "IO" classes: wxSocketIn/OutputStream, wxDataIn/OutputStream, wxFileIn/OutputStream, ... |
| 27 | \end{enumerate} |
| 28 | |
| 29 | wxStreamBase is the base definition of a stream. It defines, for example, |
| 30 | the API of OnSysRead, OnSysWrite, OnSysSeek and OnSysTell. These functions |
| 31 | are really implemented by the "IO" classes. |
| 32 | wxInputStream and wxOutputStream inherit from it. |
| 33 | |
| 34 | wxStreamBuffer is a cache manager for wxStreamBase: it manages a stream buffer |
| 35 | linked to a stream. One stream can have multiple stream buffers but one stream |
| 36 | have always one autoinitialized stream buffer. |
| 37 | |
| 38 | wxInputStream is the base class for read-only streams. It implements Read, |
| 39 | SeekI (I for Input), and all read or IO generic related functions. |
| 40 | wxOutputStream does the same thing but it is for write-only streams. |
| 41 | |
| 42 | wxFilterIn/OutputStream is the base class definition for stream filtering. |
| 43 | Stream filtering means a stream which does no syscall but filters data |
| 44 | which are passed to it and then pass them to another stream. |
| 45 | For example, wxZLibInputStream is an inline stream decompressor. |
| 46 | |
| 47 | The "IO" classes implements the specific parts of the stream. This could be |
| 48 | nothing in the case of wxMemoryIn/OutputStream which bases itself on |
| 49 | wxStreamBuffer. 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 | |
| 54 | Usage is simple. We can take the example of wxFileInputStream and here is some sample |
| 55 | code: |
| 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. |
| 61 | wxFileInputStream in_stream("the_file_to_be_read"); |
| 62 | |
| 63 | // Ok, read some bytes ... nb_datas is expressed in bytes. |
| 64 | in_stream.Read(data, nb_datas); |
| 65 | if (in_stream.LastError() != wxSTREAM_NOERROR) { |
| 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. |
| 71 | if (in_stream.Read(data, nb_datas).LastError() != wxSTREAM_NOERROR) { |
| 72 | // Do something. |
| 73 | } |
| 74 | |
| 75 | // You can also get the last number of bytes REALLY put into the buffer. |
| 76 | size_t really_read = in_stream.LastRead(); |
| 77 | |
| 78 | // Ok, moves to the beginning of the stream. SeekI returns the last position |
| 79 | // in the stream counted from the beginning. |
| 80 | off_t old_position = in_stream.SeekI(0, wxFromBeginning); |
| 81 | |
| 82 | // What is my current position ? |
| 83 | off_t position = in_stream.TellI(); |
| 84 | |
| 85 | // wxFileInputStream will close the file descriptor on destruction. |
| 86 | \end{verbatim} |
| 87 | |