docs/doxygen/overviews/stream.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        stream.h
   3 // Purpose:     stream classes 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 @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