docs/latex/wx/stream.tex

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