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