docs/latex/wx/stream.tex

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