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 @li @ref overview_stream_intro
  22 @li @ref overview_stream_example
  23
  24 <hr>
  25
  26
  27
  28 @section overview_stream_intro Introduction
  29
  30 Standard C++ streams can cause problems on several platforms: they work quite
  31 well in most cases, but in the multi-threaded case, for example, they have many
  32 problems. Some Borland compilers refuse to work at all with them.
  33 @todo is this still true?
  34
  35 Besides, using @c std::iostream on Linux makes impossible to write programs that are
  36 binary compatible across different Linux distributions.
  37
  38 Therefore, wxStreams have been added to wxWidgets so that an applications can
  39 reliably compile and run on all supported platforms without dependence on a
  40 particular release of libg++.
  41
  42 wxStream classes are divided in two main groups:
  43
  44 @li The core: wxStreamBase, wxStreamBuffer, wxInputStream, wxOutputStream,
  45     wxFilterInputStream, wxFilterOutputStream
  46 @li The "IO" classes: wxSocketInputStream, wxSocketOutputStream,
  47     wxFileInputStream, wxFileOutputStream, ...
  48
  49 wxStreamBase is the base definition of a stream. It defines, for example, the
  50 API of OnSysRead(), OnSysWrite(), OnSysSeek() and OnSysTell(). These functions are
  51 really implemented by the "IO" classes.
  52 wxInputStream and wxOutputStream classes inherit from wxStreamBase and provide
  53 specialized methods for input and output.
  54
  55 wxStreamBuffer is a cache manager for wxStreamBase: it manages a stream buffer
  56 linked to a stream. One stream can have multiple stream buffers but one stream
  57 has always one autoinitialized stream buffer.
  58
  59 wxInputStream is the base class for read-only streams. It implements Read(),
  60 SeekI() (I for Input), and all read or IO generic related functions.
  61 wxOutputStream does the same thing for write-only streams.
  62
  63 wxFilterInputStream and wxFileterOutputStream are the base class definitions for
  64 stream filtering.
  65 Stream filtering means a stream which does no syscall but filters data which
  66 are passed to it and then pass them to another stream.
  67 For example, wxZLibInputStream is an inline stream decompressor.
  68
  69 The "IO" classes implements the specific parts of the stream. This could be
  70 nothing in the case of wxMemoryInputStream and wxMemoryOutputStream which base
  71 themselves on wxStreamBuffer.
  72 This could also be a simple link to the true syscall (for example read(...), write(...)).
  73
  74
  75 @section overview_stream_example Example
  76
  77 Usage is simple. We can take the example of wxFileInputStream and here is some
  78 sample code:
  79
  80 @code
  81 ...
  82 // The constructor initializes the stream buffer and open the file descriptor
  83 // associated to the name of the file.
  84 wxFileInputStream in_stream("the_file_to_be_read");
  85
  86 // Ok, read some bytes ... nb_datas is expressed in bytes.
  87 in_stream.Read(data, nb_datas);
  88 if (in_stream.LastError() != wxSTREAM_NOERROR) {
  89     // Oh oh, something bad happens.
  90     // For a complete list, look into the documentation at wxStreamBase.
  91 }
  92
  93 // You can also inline all like this.
  94 if (in_stream.Read(data, nb_datas).LastError() != wxSTREAM_NOERROR) {
  95     // Do something.
  96 }
  97
  98 // You can also get the last number of bytes REALLY put into the buffer.
  99 size_t really_read = in_stream.LastRead();
 100
 101 // Ok, moves to the beginning of the stream. SeekI returns the last position
 102 // in the stream counted from the beginning.
 103 off_t old_position = in_stream.SeekI(0, wxFromBeginning);
 104
 105 // What is my current position ?
 106 off_t position = in_stream.TellI();
 107
 108 // wxFileInputStream will close the file descriptor on destruction.
 109 @endcode
 110
 111 */
 112