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 You 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}
  60 But you should care about destroying the stream buffer \it{YOURSELF}.
  61
  62 \wxheading{See also}
  63
  64 \helpref{wxStreamBuffer:SetBufferIO}{wxstreambuffersetbufferio}
  65
  66 \func{}{wxStreamBuffer}{\param{const wxStreamBuffer &}{buffer}}
  67
  68 Constructor. It initializes the stream buffer with the data of the specified
  69 stream buffer. The new stream buffer is nearly exactly the same as the
  70 original: it has the same attributes, the same size, the same position, shares
  71 the same internal buffer. The interresting point is that they can differ
  72 in the future but the root is the same.
  73
  74 \wxheading{Warning}
  75
  76 The fact that the two stream buffers shared the same buffer could generate
  77 segmentation violation if the parent is destroyed and the children continues
  78 operating. It is advised to use this feature only in very local area of the
  79 program.
  80
  81 \membersection{wxStreamBuffer::\destruct{wxStreamBuffer}}
  82
  83 \func{}{wxStreamBuffer}{\destruct{wxStreamBuffer}}
  84
  85 Destructor. It finalizes all IO calls and frees all internal buffers if
  86 necessary. In the case of a children stream buffer, the internal buffer isn't
  87 freed, this is the job of the parent.
  88 The "Write-Back" buffer is freed.
  89
  90 % -----------
  91 % Filtered IO
  92 % -----------
  93 \membersection{wxStreamBuffer::Read}\label{wxstreambufferread}
  94
  95 \func{size\_t}{Read}{\param{void *}{buffer}, \param{size\_t }{size}}
  96
  97 Reads a block of the specified \it{size} and stores datas in \it{buffer}.
  98 This function uses also the "Write-Back" buffer: in the case there are datas
  99 waiting in this buffer, they are used before anything else. After that, if there
 100 are still datas to be read, the stream is read and the stream buffer position
 101 is incremented.
 102
 103 \wxheading{Return value}
 104
 105 It returns the real read size. If returned size is different of the specified
 106 \it{size}, an error occured and should be tested using
 107 \helpref{LastError}{wxstreambaselasterror}.
 108
 109 \wxheading{See also}
 110
 111 \helpref{wxStreamBuffer::WriteBack}{wxstreambufferwriteback}
 112
 113 \func{size\_t}{Read}{\param{wxStreamBuffer *}{buffer}}
 114
 115 Reads a \it{buffer}. The function returns when \it{buffer} is full or
 116 when there aren't datas anymore in the current buffer.
 117
 118 \membersection{wxStreamBuffer::Write}\label{wxstreambufferwrite}
 119
 120 \func{size\_t}{Write}{\param{const void *}{buffer}, \param{size\_t }{size}}
 121
 122 Writes a block of the specified \it{size} using datas of \it{buffer}. The datas
 123 are cached in a buffer before being sent in one block to the stream.
 124
 125 \func{size\_t}{Write}{\param{wxStreamBuffer *}{buffer}}
 126
 127 See \helpref{Read}{wxstreambufferread}.
 128
 129 \membersection{wxStreamBuffer::WriteBack}\label{wxstreambufferwriteback}
 130
 131 \func{size\_t}{WriteBack}{\param{const char*}{ buffer}, \param{size\_t}{ size}}
 132
 133 This function is only useful in \it{read} mode. It is the manager of the "Write-Back"
 134 buffer. This buffer acts like a temporary buffer where datas which has to be
 135 read during the next read IO call are put. This is useful when you get a big
 136 block of data which you didn't want to read: you can replace them at the top
 137 of the input queue by this way.
 138
 139 \wxheading{Return value}
 140
 141 Returns the amount of bytes saved in the Write-Back buffer.
 142
 143 \func{size\_t}{WriteBack}{\param{char }{c}}
 144
 145 This function acts like the previous one except that it takes only one
 146 character: it is sometimes shorter to use than the generic function.
 147
 148 \membersection{wxStreamBuffer::GetChar}
 149
 150 \func{char}{GetChar}{\void}
 151
 152 Gets a single char from the stream buffer. It acts like the Read call.
 153
 154 \wxheading{Problem}
 155
 156 You aren't directly notified if an error occured during the IO call.
 157
 158 \wxheading{See also}
 159
 160 \helpref{wxStreamBuffer::Read}{wxstreambufferread}
 161
 162 \membersection{wxStreamBuffer::PutChar}
 163
 164 \func{void}{PutChar}{\param{char }{c}}
 165
 166 Puts a single char to the stream buffer.
 167
 168 \wxheading{Problem}
 169
 170 You aren't directly notified if an error occured during the IO call.
 171
 172 \wxheading{See also}
 173
 174 \helpref{wxStreamBuffer::Read}{wxstreambufferwrite}
 175
 176 \membersection{wxStreamBuffer::Tell}
 177
 178 \constfunc{off\_t}{Tell}{\void}
 179
 180 Gets the current position in the stream. This position is calculated from
 181 the \it{real} position in the stream and from the internal buffer position: so
 182 it gives you the position in the \it{real} stream counted from the start of
 183 the stream.
 184
 185 \wxheading{Return value}
 186
 187 Returns the current position in the stream if possible, wxInvalidOffset in the
 188 other case.
 189
 190 \membersection{wxStreamBuffer::Seek}\label{wxstreambufferseek}
 191
 192 \func{off\_t}{Seek}{\param{off\_t }{pos}, \param{wxSeekMode }{mode}}
 193
 194 Changes 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
 207 Upon successful completion, it returns the new offset as measured in bytes from
 208 the beginning of the stream. Otherwise, it returns wxInvalidOffset.
 209
 210 % --------------
 211 % Buffer control
 212 % --------------
 213 \membersection{wxStreamBuffer::ResetBuffer}
 214
 215 \func{void}{ResetBuffer}{\void}
 216
 217 Resets to the initial state variables concerning the buffer.
 218
 219 \membersection{wxStreamBuffer::SetBufferIO}\label{wxstreambuffersetbufferio}
 220
 221 \func{void}{SetBufferIO}{\param{char*}{ buffer\_start}, \param{char*}{ buffer\_end}}
 222
 223 Specifies which pointers to use for stream buffering. You need to pass a pointer on the
 224 start of the buffer end and another on the end. The object will use this buffer
 225 to cache stream data. It may be used also as a source/destination buffer when
 226 you create an empty stream buffer (See \helpref{wxStreamBuffer::wxStreamBuffer}{wxstreambufconst}).
 227
 228 \wxheading{Remarks}
 229
 230 When you use this function, you'll have to destroy the IO buffers yourself
 231 after the stream buffer is destroyed or don't use it anymore.
 232 In the case you use it with an empty buffer, the stream buffer will not grow
 233 it when it is full.
 234
 235 \wxheading{See also}
 236
 237 \helpref{wxStreamBuffer constructor}{wxstreambufconst}\\
 238 \helpref{wxStreamBuffer::Fixed}{wxstreambufferfixed}\\
 239 \helpref{wxStreamBuffer::Flushable}{wxstreambufferflushable}
 240
 241 \func{void}{SetBufferIO}{\param{size\_t}{ bufsize}}
 242
 243 Destroys or invalidates the previous IO buffer and allocates a new one of the
 244 specified size.
 245
 246 \wxheading{Warning}
 247
 248 All previous pointers aren't valid anymore.
 249
 250 \wxheading{Remark}
 251
 252 The created IO buffer is growable by the object.
 253
 254 \wxheading{See also}
 255
 256 \helpref{wxStreamBuffer::Fixed}{wxstreambufferfixed}\\
 257 \helpref{wxStreamBuffer::Flushable}{wxstreambufferflushable}
 258
 259 \membersection{wxStreamBuffer::GetBufferStart}
 260
 261 \constfunc{char *}{GetBufferStart}{\void}
 262
 263 Returns a pointer on the start of the stream buffer.
 264
 265 \membersection{wxStreamBuffer::GetBufferEnd}
 266
 267 \constfunc{char *}{GetBufferEnd}{\void}
 268
 269 Returns a pointer on the end of the stream buffer.
 270
 271 \membersection{wxStreamBuffer::GetBufferPos}
 272
 273 \constfunc{char *}{GetBufferPos}{\void}
 274
 275 Returns a pointer on the current position of the stream buffer.
 276
 277 \membersection{wxStreamBuffer::GetIntPosition}
 278
 279 \constfunc{off\_t}{GetIntPosition}{\void}
 280
 281 Returns the current position (counted in bytes) in the stream buffer.
 282
 283 \membersection{wxStreamBuffer::SetIntPosition}
 284
 285 \func{void}{SetIntPosition}{\void}
 286
 287 Sets the current position in the stream buffer.
 288
 289 \membersection{wxStreamBuffer::GetLastAccess}
 290
 291 \constfunc{size\_t}{GetLastAccess}{\void}
 292
 293 Returns the amount of bytes read during the last IO call to the parent stream.
 294
 295 \membersection{wxStreamBuffer::Fixed}\label{wxstreambufferfixed}
 296
 297 \func{void}{Fixed}{\param{bool}{ fixed}}
 298
 299 Toggles the fixed flag. Usually this flag is toggled at the same time as
 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
 305 \helpref{wxStreamBuffer::SetBufferIO}{wxstreambuffersetbufferio}
 306
 307 \membersection{wxStreamBuffer::Flushable}\label{wxstreambufferflushable}
 308
 309 \func{void}{Flushable}{\param{bool}{ flushable}}
 310
 311 Toggles the flushable flag. If \it{flushable} is disabled, no datas are sent
 312 to the parent stream.
 313
 314 \membersection{wxStreamBuffer::FlushBuffer}
 315
 316 \func{bool}{FlushBuffer}{\void}
 317
 318 Flushes the IO buffer.
 319
 320 \membersection{wxStreamBuffer::FillBuffer}
 321
 322 \func{bool}{FillBuffer}{\void}
 323
 324 Fill the IO buffer.
 325
 326 \membersection{wxStreamBuffer::GetDataLeft}
 327
 328 \func{size\_t}{GetDataLeft}{\void}
 329
 330 Returns the amount of available datas in the buffer.
 331
 332 % --------------
 333 % Administration
 334 % --------------
 335 \membersection{wxStreamBuffer::Stream}
 336
 337 \func{wxStreamBase*}{Stream}{\void}
 338
 339 Returns the parent stream of the stream buffer.
 340