git.saurik.com Git - wxWidgets.git/blame_incremental

... / ...

Commit	Line	Data
	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