docs/latex/wx/tstream.tex

   1 \section{wxStreams overview}\label{wxstreamoverview}
   2
   3 Classes: \helpref{wxStreamBase}{wxstreambase},
   4  \helpref{wxStreamBuffer}{wxstreambuffer}, \helpref{wxInputStream}{wxinputstream},
   5  \helpref{wxOutputStream}{wxoutputstream},
   6  \helpref{wxFilterInputStream}{wxfilterinputstream},
   7  \helpref{wxFilterOutputStream}{wxfilteroutputstream}
   8
   9 \wxheading{Purpose of wxStream}
  10
  11 We had troubles with standard C++ streams on several platforms:
  12 they react quite well in most cases, but in the multi-threaded case, for example,
  13 they have many problems. Some Borland Compilers refuse to work at all
  14 with them and using iostreams on Linux makes writing programs, that are
  15 binary compatible across different Linux distributions, impossible.
  16
  17 Therefore, wxStreams have been added to wxWidgets because an application should
  18 compile and run on all supported platforms and we don't want users to depend on release
  19 X.XX of libg++ or some other compiler to run the program.
  20
  21 wxStreams is divided in two main parts:
  22
  23 \begin{enumerate}\itemsep=0pt
  24 \item the core: wxStreamBase, wxStreamBuffer, wxInputStream, wxOutputStream,
  25 wxFilterIn/OutputStream
  26 \item the "IO" classes: wxSocketIn/OutputStream, wxDataIn/OutputStream, wxFileIn/OutputStream, ...
  27 \end{enumerate}
  28
  29 wxStreamBase is the base definition of a stream. It defines, for example,
  30 the API of OnSysRead, OnSysWrite, OnSysSeek and OnSysTell. These functions
  31 are really implemented by the "IO" classes.
  32 wxInputStream and wxOutputStream inherit from it.
  33
  34 wxStreamBuffer is a cache manager for wxStreamBase (it manages a stream buffer
  35 linked to a stream). One stream can have multiple stream buffers  but one stream
  36 have always one autoinitialized stream buffer.
  37
  38 wxInputStream is the base class for read-only streams. It implements Read,
  39 SeekI (I for Input), and all read or IO generic related functions.
  40 wxOutputStream does the same thing but it is for write-only streams.
  41
  42 wxFilterIn/OutputStream is the base class definition for stream filtering.
  43 Stream filtering means a stream which does no syscall but filters data
  44 which are passed to it and then pass them to another stream.
  45 For example, wxZLibInputStream is an inline stream decompressor.
  46
  47 The "IO" classes implements the specific parts of the stream. This could be
  48 nothing in the case of wxMemoryIn/OutputStream which bases itself on
  49 wxStreamBuffer. This could also be a simple link to the a true syscall
  50 (for example read(...), write(...)).
  51
  52 \wxheading{Generic usage: an example}
  53
  54 Usage is simple. We can take the example of wxFileInputStream and here is some sample
  55 code:
  56
  57 \begin{verbatim}
  58  ...
  59  // The constructor initializes the stream buffer and open the file descriptor
  60  // associated to the name of the file.
  61  wxFileInputStream in_stream("the_file_to_be_read");
  62
  63  // Ok, read some bytes ... nb_datas is expressed in bytes.
  64  in_stream.Read(data, nb_datas);
  65  if (in_stream.LastError() != wxSTREAM_NOERROR) {
  66    // Oh oh, something bad happens.
  67    // For a complete list, look into the documentation at wxStreamBase.
  68  }
  69
  70  // You can also inline all like this.
  71  if (in_stream.Read(data, nb_datas).LastError() != wxSTREAM_NOERROR) {
  72    // Do something.
  73  }
  74
  75  // You can also get the last number of bytes REALLY put into the buffer.
  76  size_t really_read = in_stream.LastRead();
  77
  78  // Ok, moves to the beginning of the stream. SeekI returns the last position
  79  // in the stream counted from the beginning.
  80  off_t old_position = in_stream.SeekI(0, wxFromBeginning);
  81
  82  // What is my current position ?
  83  off_t position = in_stream.TellI();
  84
  85  // wxFileInputStream will close the file descriptor on the destruction.
  86 \end{verbatim}
  87
  88 \wxheading{Compatibility with C++ streams}
  89
  90 As I said previously, we could add a filter stream so it takes an istream
  91 argument and builds a wxInputStream from it: I don't think it should
  92 be difficult to implement it and it may be available in the fix of wxWidgets 2.0.
  93