X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/15b6757b26a0277472a4f6b071b52050abd922da..e18e78a7cc106a75e5228c51edd982436682633d:/docs/doxygen/overviews/stream.h diff --git a/docs/doxygen/overviews/stream.h b/docs/doxygen/overviews/stream.h index a7782ee9f1..6a52ffd6e9 100644 --- a/docs/doxygen/overviews/stream.h +++ b/docs/doxygen/overviews/stream.h @@ -1,90 +1,108 @@ ///////////////////////////////////////////////////////////////////////////// -// Name: stream +// Name: stream.h // Purpose: topic overview // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// -/*! - - @page stream_overview wxStreams overview - - Classes: #wxStreamBase, - #wxStreamBuffer, #wxInputStream, - #wxOutputStream, - #wxFilterInputStream, - #wxFilterOutputStream - @b Purpose of wxStream - Standard C++ streams can cause problems on several platforms: - they work quite well in most cases, but in the multi-threaded case, for example, - they have many problems. Some Borland compilers refuse to work at all - with them and using iostreams on Linux makes writing programs that are - binary compatible across different Linux distributions, impossible. - Therefore, wxStreams have been added to wxWidgets so that applications can - reliably compile and run on all supported platforms without dependence on a - particular release of libg++. - wxStreams is divided in two main parts: - - - the core: wxStreamBase, wxStreamBuffer, wxInputStream, wxOutputStream, - wxFilterIn/OutputStream - the "IO" classes: wxSocketIn/OutputStream, wxDataIn/OutputStream, wxFileIn/OutputStream, ... - - - wxStreamBase is the base definition of a stream. It defines, for example, - the API of OnSysRead, OnSysWrite, OnSysSeek and OnSysTell. These functions - 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 the base class definition for stream filtering. - Stream filtering means a stream which does no syscall but filters data - 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(...)). - @b Generic usage: an example - Usage is simple. We can take the example of wxFileInputStream and here is some sample - code: - - @code - ... - // 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) { +/** + +@page overview_stream wxStreams Overview + +Classes: +@li wxStreamBase +@li wxStreamBuffer +@li wxInputStream +@li wxOutputStream +@li wxFilterInputStream +@li wxFilterOutputStream + +@li @ref overview_stream_intro +@li @ref overview_stream_example + +
+ + + +@section overview_stream_intro Introduction + +Standard C++ streams can cause problems on several platforms: they work quite +well in most cases, but in the multi-threaded case, for example, they have many +problems. Some Borland compilers refuse to work at all with them and using +iostreams on Linux makes writing programs that are binary compatible across +different Linux distributions, impossible. + +Therefore, wxStreams have been added to wxWidgets so that applications can +reliably compile and run on all supported platforms without dependence on a +particular release of libg++. + +wxStreams is divided in two main parts: + +@li The core: wxStreamBase, wxStreamBuffer, wxInputStream, wxOutputStream, + wxFilterIn/OutputStream +@li The "IO" classes: wxSocketIn/OutputStream, wxDataIn/OutputStream, + wxFileIn/OutputStream, ... + +wxStreamBase is the base definition of a stream. It defines, for example, the +API of OnSysRead, OnSysWrite, OnSysSeek and OnSysTell. These functions 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 the base class definition for stream filtering. +Stream filtering means a stream which does no syscall but filters data 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(...)). + + +@section overview_stream_example Example + +Usage is simple. We can take the example of wxFileInputStream and here is some +sample code: + +@code +... +// 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) { +} + +// 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 destruction. - @endcode - - */ - - +} + +// 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 destruction. +@endcode + +*/ +