docs/doxygen/overviews/stream.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        stream.h
   3 // Purpose:     topic overview
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /*!
  10
  11 @page overview_stream wxStreams Overview
  12
  13 Classes:
  14 @li wxStreamBase
  15 @li wxStreamBuffer
  16 @li wxInputStream
  17 @li wxOutputStream
  18 @li wxFilterInputStream
  19 @li wxFilterOutputStream
  20
  21 Standard C++ streams can cause problems on several platforms: they work quite
  22 well in most cases, but in the multi-threaded case, for example, they have many
  23 problems. Some Borland compilers refuse to work at all with them and using
  24 iostreams on Linux makes writing programs that are binary compatible across
  25 different Linux distributions, impossible.
  26
  27 Therefore, wxStreams have been added to wxWidgets so that applications can
  28 reliably compile and run on all supported platforms without dependence on a
  29 particular release of libg++.
  30
  31 wxStreams is divided in two main parts:
  32
  33 @li The core: wxStreamBase, wxStreamBuffer, wxInputStream, wxOutputStream,
  34     wxFilterIn/OutputStream
  35 @li The "IO" classes: wxSocketIn/OutputStream, wxDataIn/OutputStream,
  36     wxFileIn/OutputStream, ...
  37
  38 wxStreamBase is the base definition of a stream. It defines, for example, the
  39 API of OnSysRead, OnSysWrite, OnSysSeek and OnSysTell. These functions are
  40 really implemented by the "IO" classes. wxInputStream and wxOutputStream
  41 inherit from it.
  42
  43 wxStreamBuffer is a cache manager for wxStreamBase: it manages a stream buffer
  44 linked to a stream. One stream can have multiple stream buffers  but one stream
  45 have always one autoinitialized stream buffer.
  46
  47 wxInputStream is the base class for read-only streams. It implements Read,
  48 SeekI (I for Input), and all read or IO generic related functions.
  49 wxOutputStream does the same thing but it is for write-only streams.
  50
  51 wxFilterIn/OutputStream is the base class definition for stream filtering.
  52 Stream filtering means a stream which does no syscall but filters data which
  53 are passed to it and then pass them to another stream. For example,
  54 wxZLibInputStream is an inline stream decompressor.
  55
  56 The "IO" classes implements the specific parts of the stream. This could be
  57 nothing in the case of wxMemoryIn/OutputStream which bases itself on
  58 wxStreamBuffer. This could also be a simple link to the a true syscall (for
  59 example read(...), write(...)).
  60
  61 @section overview_stream_example Example
  62
  63 Usage is simple. We can take the example of wxFileInputStream and here is some
  64 sample code:
  65
  66 @code
  67 ...
  68 // The constructor initializes the stream buffer and open the file descriptor
  69 // associated to the name of the file.
  70 wxFileInputStream in_stream("the_file_to_be_read");
  71
  72 // Ok, read some bytes ... nb_datas is expressed in bytes.
  73 in_stream.Read(data, nb_datas);
  74 if (in_stream.LastError() != wxSTREAM_NOERROR) {
  75     // Oh oh, something bad happens.
  76     // For a complete list, look into the documentation at wxStreamBase.
  77 }
  78
  79 // You can also inline all like this.
  80 if (in_stream.Read(data, nb_datas).LastError() != wxSTREAM_NOERROR) {
  81     // Do something.
  82 }
  83
  84 // You can also get the last number of bytes REALLY put into the buffer.
  85 size_t really_read = in_stream.LastRead();
  86
  87 // Ok, moves to the beginning of the stream. SeekI returns the last position
  88 // in the stream counted from the beginning.
  89 off_t old_position = in_stream.SeekI(0, wxFromBeginning);
  90
  91 // What is my current position ?
  92 off_t position = in_stream.TellI();
  93
  94 // wxFileInputStream will close the file descriptor on destruction.
  95 @endcode
  96
  97 */
  98