| 1 | ///////////////////////////////////////////////////////////////////////////// |
| 2 | // Name: stream.h |
| 3 | // Purpose: stream classes overview |
| 4 | // Author: wxWidgets team |
| 5 | // RCS-ID: $Id$ |
| 6 | // Licence: wxWindows licence |
| 7 | ///////////////////////////////////////////////////////////////////////////// |
| 8 | |
| 9 | /** |
| 10 | |
| 11 | @page overview_stream Stream classes overview |
| 12 | |
| 13 | Classes: |
| 14 | @li wxStreamBase |
| 15 | @li wxStreamBuffer |
| 16 | @li wxInputStream |
| 17 | @li wxOutputStream |
| 18 | @li wxFilterInputStream |
| 19 | @li wxFilterOutputStream |
| 20 | @li wxFileInputStream |
| 21 | @li wxFileOutputStream |
| 22 | @li wxTextInputStream |
| 23 | @li wxTextOutputStream |
| 24 | @li wxDataInputStream |
| 25 | @li wxDataOutputStream |
| 26 | |
| 27 | @li @ref overview_stream_intro |
| 28 | @li @ref overview_stream_example |
| 29 | |
| 30 | <hr> |
| 31 | |
| 32 | |
| 33 | |
| 34 | @section overview_stream_intro Introduction |
| 35 | |
| 36 | @subsection overview_stream_intro_std wxWidgets and Standard Streams |
| 37 | |
| 38 | wxWidgets provides its own set of stream classes in order to support platforms |
| 39 | not providing standard C++ streams implementation and also to make it possible |
| 40 | to provide binary versions of wxWidgets application not depending on any |
| 41 | particular standard library version. The wxWidgets stream classes also provide |
| 42 | some functionality not available in the standard library such as support for |
| 43 | several compression formats and possibility to work with sockets or text |
| 44 | controls (for output only in the latter case). |
| 45 | |
| 46 | Nevertheless wxWidgets programs can also use standard stream classes and are |
| 47 | encouraged to do so if the above considerations don't apply. Moreover, |
| 48 | wxStdInputStream and wxStdOutputStream classes are provided to provide a degree |
| 49 | of interoperability between the two and make it possible to use any wxWidgets |
| 50 | stream as a standard stream (the converse possibility to use a standard stream |
| 51 | as a wxWidgets stream is planned for a future release). |
| 52 | |
| 53 | |
| 54 | @subsection overview_stream_intro_overview Stream Classes |
| 55 | |
| 56 | wxStream classes are divided in two main groups: |
| 57 | |
| 58 | @li The core: wxStreamBase, wxStreamBuffer, wxInputStream, wxOutputStream, |
| 59 | wxFilterInputStream, wxFilterOutputStream |
| 60 | @li The "IO" classes: wxSocketInputStream, wxSocketOutputStream, |
| 61 | wxFileInputStream, wxFileOutputStream, ... |
| 62 | @li Classes for reading text or binary data from a particular stream |
| 63 | such as wxTextInputStream, wxTextOutputStream, wxDataInputStream |
| 64 | and wxDataOutputStream |
| 65 | |
| 66 | wxStreamBase is the base definition of a stream. It defines, for example, the |
| 67 | API of OnSysRead(), OnSysWrite(), OnSysSeek() and OnSysTell(). These functions are |
| 68 | really implemented by the "IO" classes. |
| 69 | wxInputStream and wxOutputStream classes inherit from wxStreamBase and provide |
| 70 | specialized methods for input and output. |
| 71 | |
| 72 | wxStreamBuffer is a cache manager for wxStreamBase: it manages a stream buffer |
| 73 | linked to a stream. One stream can have multiple stream buffers but one stream |
| 74 | has always one autoinitialized stream buffer. |
| 75 | |
| 76 | wxInputStream is the base class for read-only streams. It implements Read(), |
| 77 | SeekI() (I for Input), and all read or IO generic related functions. |
| 78 | wxOutputStream does the same thing for write-only streams. |
| 79 | |
| 80 | wxFilterInputStream and wxFileterOutputStream are the base class definitions for |
| 81 | stream filtering. |
| 82 | Stream filtering means a stream which does no syscall but filters data which |
| 83 | are passed to it and then pass them to another stream. |
| 84 | For example, wxZLibInputStream is an inline stream decompressor. |
| 85 | |
| 86 | The "IO" classes implements the specific parts of the stream. This could be |
| 87 | nothing in the case of wxMemoryInputStream and wxMemoryOutputStream which base |
| 88 | themselves on wxStreamBuffer. |
| 89 | This could also be a simple link to the true syscall (for example read(...), write(...)). |
| 90 | |
| 91 | |
| 92 | @section overview_stream_example Example |
| 93 | |
| 94 | Usage is simple. We can take the example of wxFileInputStream and here is some |
| 95 | sample code: |
| 96 | |
| 97 | @code |
| 98 | ... |
| 99 | // The constructor initializes the stream buffer and open the file descriptor |
| 100 | // associated to the name of the file. |
| 101 | wxFileInputStream in_stream("the_file_to_be_read"); |
| 102 | |
| 103 | // Ok, read some bytes ... nb_datas is expressed in bytes. |
| 104 | in_stream.Read(data, nb_datas); |
| 105 | if (in_stream.LastError() != wxSTREAM_NOERROR) { |
| 106 | // Oh oh, something bad happens. |
| 107 | // For a complete list, look into the documentation at wxStreamBase. |
| 108 | } |
| 109 | |
| 110 | // You can also inline all like this. |
| 111 | if (in_stream.Read(data, nb_datas).LastError() != wxSTREAM_NOERROR) { |
| 112 | // Do something. |
| 113 | } |
| 114 | |
| 115 | // You can also get the last number of bytes REALLY put into the buffer. |
| 116 | size_t really_read = in_stream.LastRead(); |
| 117 | |
| 118 | // Ok, moves to the beginning of the stream. SeekI returns the last position |
| 119 | // in the stream counted from the beginning. |
| 120 | off_t old_position = in_stream.SeekI(0, wxFromBeginning); |
| 121 | |
| 122 | // What is my current position ? |
| 123 | off_t position = in_stream.TellI(); |
| 124 | |
| 125 | // wxFileInputStream will close the file descriptor on destruction. |
| 126 | @endcode |
| 127 | |
| 128 | */ |
| 129 | |