]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/stream.tex
* Stream doc.
[wxWidgets.git] / docs / latex / wx / stream.tex
CommitLineData
e2a6f233 1\section{\class{wxStreamBuffer}}\label{wxstreambuffer}
7da42094 2
b82827dd
JS
3\wxheading{Derived from}
4
5None
6
7da42094 7\wxheading{See also}
b82827dd 8
7da42094
GL
9\helpref{wxStreamBase}{wxstreambase}
10
11% ---------------------------------------------------------------------------
12% Members
13% ---------------------------------------------------------------------------
7da42094
GL
14\latexignore{\rtfignore{\wxheading{Members}}}
15
16% -----------
17% ctor & dtor
18% -----------
da3aea64 19\membersection{wxStreamBuffer::wxStreamBuffer}\label{wxstreambufconst}
b82827dd
JS
20
21\func{}{wxStreamBuffer}{\param{wxStreamBase\&}{ stream}, \param{BufMode}{ mode}}
7da42094
GL
22
23Constructor, creates a new stream buffer using \it{stream} as a parent stream
24and \it{mode} as the IO mode. \it{mode} can be: wxStreamBuffer::read,
b82827dd 25wxStreamBuffer::write, wxStreamBuffer::read\_write.
07b73270
GL
26One stream can have many stream buffers but only one is used internally to
27pass IO call (e.g. wxInputStream::Read() -> wxStreamBuffer::Read()). But you
28can call directly wxStreamBuffer::Read without any problems.
7da42094 29
07b73270
GL
30\wxheading{Warning}
31
32All errors and messages linked to the stream are stored in the stream object.
33\begin{verbatim}
34 streambuffer.Read(...);
35 streambuffer2.Read(...); /* This one erases previous error messages set by
36 ``streambuffer'' */
37\end{verbatim}
b82827dd 38
7da42094
GL
39\func{}{wxStreamBuffer}{\param{BufMode}{ mode}}
40
e2a6f233 41Constructor, creates a new empty stream buffer which won't flush any data
07b73270
GL
42to a stream. \it{mode} specifies the type of the buffer (read, write, read\_write). This stream buffer has the advantage to be stream independent and to
43work only on memory buffers but it is still compatible with the rest of the
44wxStream classes. You can write, read to this special stream and it will
45grow (if it is allowed by the user) its internal buffer. Briefly, it has all
46functionnalities of a ``normal'' stream.
7da42094 47
07b73270
GL
48\wxheading{Warning}
49
50The "read\_write" mode may not work: it isn't completely finished.
7f42cff1
GL
51You can create "memory" streams by this way:
52\begin{verbatim}
53 wxStreamBuffer *sb = new wxStreamBuffer(wxStreamBuffer::read)
54 wxInputStream *input = new wxInputStream(sb);
55
56 sb->Fixed(FALSE); // It can change the size of the buffer.
57
58 // input is now a read-only memory stream.
59\end{verbatim}
60But you should care about destroying the stream buffer \it{YOURSELF}.
07b73270
GL
61
62\wxheading{See also}
63
750b78ba 64\helpref{wxStreamBuffer:SetBufferIO}{wxstreambuffersetbufferio}
07b73270
GL
65
66\func{}{wxStreamBuffer}{\param{const wxStreamBuffer &}{buffer}}
67
68Constructor. It initializes the stream buffer with the data of the specified
69stream buffer. The new stream buffer is nearly exactly the same as the
70original: it has the same attributes, the same size, the same position, shares
71the same internal buffer. The interresting point is that they can differ
72in the future but the root is the same.
b82827dd 73
07b73270 74\wxheading{Warning}
7da42094 75
07b73270
GL
76The fact that the two stream buffers shared the same buffer could generate
77segmentation violation if the parent is destroyed and the children continues
78operating. It is advised to use this feature only in very local area of the
79program.
7da42094 80
b82827dd
JS
81\membersection{wxStreamBuffer::\destruct{wxStreamBuffer}}
82
e2a6f233 83\func{}{wxStreamBuffer}{\destruct{wxStreamBuffer}}
7da42094 84
07b73270
GL
85Destructor. It finalizes all IO calls and frees all internal buffers if
86necessary. In the case of a children stream buffer, the internal buffer isn't
87freed, this is the job of the parent.
88The "Write-Back" buffer is freed.
7da42094
GL
89
90% -----------
91% Filtered IO
92% -----------
750b78ba 93\membersection{wxStreamBuffer::Read}\label{wxstreambufferread}
b82827dd
JS
94
95\func{size\_t}{Read}{\param{void *}{buffer}, \param{size\_t }{size}}
7da42094
GL
96
97Reads a block of the specified \it{size} and stores datas in \it{buffer}.
07b73270
GL
98This function uses also the "Write-Back" buffer: in the case there are datas
99waiting in this buffer, they are used before anything else. After that, if there
100are still datas to be read, the stream is read and the stream buffer position
101is incremented.
7da42094
GL
102
103\wxheading{Return value}
104
b82827dd
JS
105It returns the real read size. If returned size is different of the specified
106\it{size}, an error occured and should be tested using
e2a6f233 107\helpref{LastError}{wxstreambaselasterror}.
7da42094 108
07b73270
GL
109\wxheading{See also}
110
750b78ba 111\helpref{wxStreamBuffer::WriteBack}{wxstreambufferwriteback}
b82827dd
JS
112
113\func{size\_t}{Read}{\param{wxStreamBuffer *}{buffer}}
7da42094
GL
114
115Reads a \it{buffer}. The function returns when \it{buffer} is full or
116when there aren't datas anymore in the current buffer.
117
750b78ba 118\membersection{wxStreamBuffer::Write}\label{wxstreambufferwrite}
b82827dd
JS
119
120\func{size\_t}{Write}{\param{const void *}{buffer}, \param{size\_t }{size}}
7da42094 121
07b73270
GL
122Writes a block of the specified \it{size} using datas of \it{buffer}. The datas
123are cached in a buffer before being sent in one block to the stream.
b82827dd
JS
124
125\func{size\_t}{Write}{\param{wxStreamBuffer *}{buffer}}
7da42094 126
750b78ba 127See \helpref{Read}{wxstreambufferread}.
7da42094 128
750b78ba 129\membersection{wxStreamBuffer::WriteBack}\label{wxstreambufferwriteback}
b82827dd 130
06ad8636 131\func{size\_t}{WriteBack}{\param{const char*}{ buffer}, \param{size\_t}{ size}}
7da42094 132
07b73270
GL
133This function is only useful in \it{read} mode. It is the manager of the "Write-Back"
134buffer. This buffer acts like a temporary buffer where datas which has to be
135read during the next read IO call are put. This is useful when you get a big
136block of data which you didn't want to read: you can replace them at the top
137of the input queue by this way.
7da42094 138
07b73270
GL
139\wxheading{Return value}
140
141Returns the amount of bytes saved in the Write-Back buffer.
b82827dd
JS
142
143\func{size\_t}{WriteBack}{\param{char }{c}}
7da42094 144
07b73270
GL
145This function acts like the previous one except that it takes only one
146character: it is sometimes shorter to use than the generic function.
7da42094
GL
147
148\membersection{wxStreamBuffer::GetChar}
b82827dd 149
7da42094
GL
150\func{char}{GetChar}{\void}
151
07b73270
GL
152Gets a single char from the stream buffer. It acts like the Read call.
153
154\wxheading{Problem}
155
156You aren't directly notified if an error occured during the IO call.
157
158\wxheading{See also}
159
750b78ba 160\helpref{wxStreamBuffer::Read}{wxstreambufferread}
7da42094
GL
161
162\membersection{wxStreamBuffer::PutChar}
b82827dd 163
7da42094
GL
164\func{void}{PutChar}{\param{char }{c}}
165
166Puts a single char to the stream buffer.
167
07b73270
GL
168\wxheading{Problem}
169
170You aren't directly notified if an error occured during the IO call.
171
172\wxheading{See also}
173
750b78ba 174\helpref{wxStreamBuffer::Read}{wxstreambufferwrite}
07b73270 175
7da42094 176\membersection{wxStreamBuffer::Tell}
b82827dd
JS
177
178\constfunc{off\_t}{Tell}{\void}
7da42094 179
07b73270
GL
180Gets the current position in the stream. This position is calculated from
181the \it{real} position in the stream and from the internal buffer position: so
182it gives you the position in the \it{real} stream counted from the start of
183the stream.
184
185\wxheading{Return value}
186
187Returns the current position in the stream if possible, wxInvalidOffset in the
188other case.
7da42094 189
e2a6f233 190\membersection{wxStreamBuffer::Seek}\label{wxstreambufferseek}
b82827dd
JS
191
192\func{off\_t}{Seek}{\param{off\_t }{pos}, \param{wxSeekMode }{mode}}
7da42094 193
07b73270
GL
194Changes the current position.
195
196\it{mode} may be one of the following:
197
198\twocolwidtha{5cm}
199\begin{twocollist}\itemsep=0pt
200\twocolitem{{\bf wxFromStart}}{The position is counted from the start of the stream.}
201\twocolitem{{\bf wxFromCurrent}}{The position is counted from the current position of the stream.}
202\twocolitem{{\bf wxFromEnd}}{The position is counted from the end of the stream.}
203\end{twocollist}
204
205\wxheading{Return value}
206
207Upon successful completion, it returns the new offset as measured in bytes from
208the beginning of the stream. Otherwise, it returns wxInvalidOffset.
7da42094
GL
209
210% --------------
211% Buffer control
212% --------------
7da42094 213\membersection{wxStreamBuffer::ResetBuffer}
b82827dd 214
7da42094
GL
215\func{void}{ResetBuffer}{\void}
216
07b73270 217Resets to the initial state variables concerning the buffer.
7da42094 218
750b78ba 219\membersection{wxStreamBuffer::SetBufferIO}\label{wxstreambuffersetbufferio}
b82827dd 220
06ad8636 221\func{void}{SetBufferIO}{\param{char*}{ buffer\_start}, \param{char*}{ buffer\_end}}
7da42094
GL
222
223Specifies which pointers to use for stream buffering. You need to pass a pointer on the
da3aea64
GL
224start of the buffer end and another on the end. The object will use this buffer
225to cache stream data. It may be used also as a source/destination buffer when
226you create an empty stream buffer (See \helpref{wxStreamBuffer::wxStreamBuffer}{wxstreambufconst}).
227
228\wxheading{Remarks}
229
230When you use this function, you'll have to destroy the IO buffers yourself
231after the stream buffer is destroyed or don't use it anymore.
232In the case you use it with an empty buffer, the stream buffer will not grow
233it when it is full.
234
235\wxheading{See also}
236
237\helpref{wxStreamBuffer constructor}{wxstreambufconst}\\
750b78ba
JS
238\helpref{wxStreamBuffer::Fixed}{wxstreambufferfixed}\\
239\helpref{wxStreamBuffer::Flushable}{wxstreambufferflushable}
7da42094 240
b82827dd 241\func{void}{SetBufferIO}{\param{size\_t}{ bufsize}}
7da42094 242
da3aea64
GL
243Destroys or invalidates the previous IO buffer and allocates a new one of the
244specified size.
245
246\wxheading{Warning}
247
248All previous pointers aren't valid anymore.
249
250\wxheading{Remark}
251
252The created IO buffer is growable by the object.
253
254\wxheading{See also}
255
750b78ba
JS
256\helpref{wxStreamBuffer::Fixed}{wxstreambufferfixed}\\
257\helpref{wxStreamBuffer::Flushable}{wxstreambufferflushable}
7da42094
GL
258
259\membersection{wxStreamBuffer::GetBufferStart}
b82827dd 260
7da42094
GL
261\constfunc{char *}{GetBufferStart}{\void}
262
263Returns a pointer on the start of the stream buffer.
264
265\membersection{wxStreamBuffer::GetBufferEnd}
b82827dd 266
7da42094
GL
267\constfunc{char *}{GetBufferEnd}{\void}
268
269Returns a pointer on the end of the stream buffer.
270
271\membersection{wxStreamBuffer::GetBufferPos}
b82827dd 272
7da42094
GL
273\constfunc{char *}{GetBufferPos}{\void}
274
275Returns a pointer on the current position of the stream buffer.
276
277\membersection{wxStreamBuffer::GetIntPosition}
b82827dd
JS
278
279\constfunc{off\_t}{GetIntPosition}{\void}
7da42094 280
da3aea64 281Returns the current position (counted in bytes) in the stream buffer.
7da42094
GL
282
283\membersection{wxStreamBuffer::SetIntPosition}
b82827dd 284
7da42094
GL
285\func{void}{SetIntPosition}{\void}
286
287Sets the current position in the stream buffer.
288
289\membersection{wxStreamBuffer::GetLastAccess}
b82827dd
JS
290
291\constfunc{size\_t}{GetLastAccess}{\void}
7da42094
GL
292
293Returns the amount of bytes read during the last IO call to the parent stream.
294
750b78ba 295\membersection{wxStreamBuffer::Fixed}\label{wxstreambufferfixed}
b82827dd 296
7da42094
GL
297\func{void}{Fixed}{\param{bool}{ fixed}}
298
b82827dd 299Toggles the fixed flag. Usually this flag is toggled at the same time as
da3aea64
GL
300\it{flushable}. This flag allows (when it has the FALSE value) or forbids
301(when it has the TRUE value) the stream buffer to resize dynamically the IO buffer.
302
303\wxheading{See also}
304
750b78ba 305\helpref{wxStreamBuffer::SetBufferIO}{wxstreambuffersetbufferio}
7da42094 306
750b78ba 307\membersection{wxStreamBuffer::Flushable}\label{wxstreambufferflushable}
b82827dd 308
7da42094
GL
309\func{void}{Flushable}{\param{bool}{ flushable}}
310
311Toggles the flushable flag. If \it{flushable} is disabled, no datas are sent
312to the parent stream.
313
314\membersection{wxStreamBuffer::FlushBuffer}
b82827dd 315
7da42094
GL
316\func{bool}{FlushBuffer}{\void}
317
318Flushes the IO buffer.
319
320\membersection{wxStreamBuffer::FillBuffer}
b82827dd 321
7da42094
GL
322\func{bool}{FillBuffer}{\void}
323
324Fill the IO buffer.
325
326\membersection{wxStreamBuffer::GetDataLeft}
b82827dd
JS
327
328\func{size\_t}{GetDataLeft}{\void}
7da42094
GL
329
330Returns the amount of available datas in the buffer.
331
332% --------------
333% Administration
334% --------------
7da42094 335\membersection{wxStreamBuffer::Stream}
b82827dd 336
06ad8636 337\func{wxStreamBase*}{Stream}{\void}
7da42094 338
07b73270 339Returns the parent stream of the stream buffer.
b82827dd 340