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::WriteBack}\label{wxstreambufferwriteback}
 136
 137 \func{size\_t}{WriteBack}{\param{const char*}{ buffer}, \param{size\_t}{ size}}
 138
 139 This function is only useful in \it{read} mode. It is the manager of the "Write-Back"
 140 buffer. This buffer acts like a temporary buffer where datas which has to be
 141 read during the next read IO call are put. This is useful when you get a big
 142 block of data which you didn't want to read: you can replace them at the top
 143 of the input queue by this way.
 144
 145 \wxheading{Return value}
 146
 147 Returns the amount of bytes saved in the Write-Back buffer.
 148
 149 \func{size\_t}{WriteBack}{\param{char }{c}}
 150
 151 This function acts like the previous one except that it takes only one
 152 character: it is sometimes shorter to use than the generic function.
 153
 154 \membersection{wxStreamBuffer::GetChar}
 155
 156 \func{char}{GetChar}{\void}
 157
 158 Gets a single char from the stream buffer. It acts like the Read call.
 159
 160 \wxheading{Problem}
 161
 162 You aren't directly notified if an error occured during the IO call.
 163
 164 \wxheading{See also}
 165
 166 \helpref{wxStreamBuffer::Read}{wxstreambufferread}
 167
 168 \membersection{wxStreamBuffer::PutChar}
 169
 170 \func{void}{PutChar}{\param{char }{c}}
 171
 172 Puts a single char to the stream buffer.
 173
 174 \wxheading{Problem}
 175
 176 You aren't directly notified if an error occured during the IO call.
 177
 178 \wxheading{See also}
 179
 180 \helpref{wxStreamBuffer::Read}{wxstreambufferwrite}
 181
 182 \membersection{wxStreamBuffer::Tell}
 183
 184 \constfunc{off\_t}{Tell}{\void}
 185
 186 Gets the current position in the stream. This position is calculated from
 187 the \it{real} position in the stream and from the internal buffer position: so
 188 it gives you the position in the \it{real} stream counted from the start of
 189 the stream.
 190
 191 \wxheading{Return value}
 192
 193 Returns the current position in the stream if possible, wxInvalidOffset in the
 194 other case.
 195
 196 \membersection{wxStreamBuffer::Seek}\label{wxstreambufferseek}
 197
 198 \func{off\_t}{Seek}{\param{off\_t }{pos}, \param{wxSeekMode }{mode}}
 199
 200 Changes the current position.
 201
 202 \it{mode} may be one of the following:
 203
 204 \twocolwidtha{5cm}
 205 \begin{twocollist}\itemsep=0pt
 206 \twocolitem{{\bf wxFromStart}}{The position is counted from the start of the stream.}
 207 \twocolitem{{\bf wxFromCurrent}}{The position is counted from the current position of the stream.}
 208 \twocolitem{{\bf wxFromEnd}}{The position is counted from the end of the stream.}
 209 \end{twocollist}
 210
 211 \wxheading{Return value}
 212
 213 Upon successful completion, it returns the new offset as measured in bytes from
 214 the beginning of the stream. Otherwise, it returns wxInvalidOffset.
 215
 216 % --------------
 217 % Buffer control
 218 % --------------
 219 \membersection{wxStreamBuffer::ResetBuffer}
 220
 221 \func{void}{ResetBuffer}{\void}
 222
 223 Resets to the initial state variables concerning the buffer.
 224
 225 \membersection{wxStreamBuffer::SetBufferIO}\label{wxstreambuffersetbufferio}
 226
 227 \func{void}{SetBufferIO}{\param{char*}{ buffer\_start}, \param{char*}{ buffer\_end}}
 228
 229 Specifies which pointers to use for stream buffering. You need to pass a pointer on the
 230 start of the buffer end and another on the end. The object will use this buffer
 231 to cache stream data. It may be used also as a source/destination buffer when
 232 you create an empty stream buffer (See \helpref{wxStreamBuffer::wxStreamBuffer}{wxstreambufconst}).
 233
 234 \wxheading{Remarks}
 235
 236 When you use this function, you'll have to destroy the IO buffers yourself
 237 after the stream buffer is destroyed or don't use it anymore.
 238 In the case you use it with an empty buffer, the stream buffer will not grow
 239 it when it is full.
 240
 241 \wxheading{See also}
 242
 243 \helpref{wxStreamBuffer constructor}{wxstreambufconst}\\
 244 \helpref{wxStreamBuffer::Fixed}{wxstreambufferfixed}\\
 245 \helpref{wxStreamBuffer::Flushable}{wxstreambufferflushable}
 246
 247 \func{void}{SetBufferIO}{\param{size\_t}{ bufsize}}
 248
 249 Destroys or invalidates the previous IO buffer and allocates a new one of the
 250 specified size.
 251
 252 \wxheading{Warning}
 253
 254 All previous pointers aren't valid anymore.
 255
 256 \wxheading{Remark}
 257
 258 The created IO buffer is growable by the object.
 259
 260 \wxheading{See also}
 261
 262 \helpref{wxStreamBuffer::Fixed}{wxstreambufferfixed}\\
 263 \helpref{wxStreamBuffer::Flushable}{wxstreambufferflushable}
 264
 265 \membersection{wxStreamBuffer::GetBufferStart}
 266
 267 \constfunc{char *}{GetBufferStart}{\void}
 268
 269 Returns a pointer on the start of the stream buffer.
 270
 271 \membersection{wxStreamBuffer::GetBufferEnd}
 272
 273 \constfunc{char *}{GetBufferEnd}{\void}
 274
 275 Returns a pointer on the end of the stream buffer.
 276
 277 \membersection{wxStreamBuffer::GetBufferPos}
 278
 279 \constfunc{char *}{GetBufferPos}{\void}
 280
 281 Returns a pointer on the current position of the stream buffer.
 282
 283 \membersection{wxStreamBuffer::GetIntPosition}
 284
 285 \constfunc{off\_t}{GetIntPosition}{\void}
 286
 287 Returns the current position (counted in bytes) in the stream buffer.
 288
 289 \membersection{wxStreamBuffer::SetIntPosition}
 290
 291 \func{void}{SetIntPosition}{\void}
 292
 293 Sets the current position (in bytes) in the stream buffer.
 294
 295 \wxheading{Warning}
 296
 297 Since it is a very low-level function, there is no check on the position:
 298 specify an invalid position can induce unexpected results.
 299
 300 \membersection{wxStreamBuffer::GetLastAccess}
 301
 302 \constfunc{size\_t}{GetLastAccess}{\void}
 303
 304 Returns the amount of bytes read during the last IO call to the parent stream.
 305
 306 \membersection{wxStreamBuffer::Fixed}\label{wxstreambufferfixed}
 307
 308 \func{void}{Fixed}{\param{bool}{ fixed}}
 309
 310 Toggles the fixed flag. Usually this flag is toggled at the same time as
 311 \it{flushable}. This flag allows (when it has the FALSE value) or forbids
 312 (when it has the TRUE value) the stream buffer to resize dynamically the IO buffer.
 313
 314 \wxheading{See also}
 315
 316 \helpref{wxStreamBuffer::SetBufferIO}{wxstreambuffersetbufferio}
 317
 318 \membersection{wxStreamBuffer::Flushable}\label{wxstreambufferflushable}
 319
 320 \func{void}{Flushable}{\param{bool}{ flushable}}
 321
 322 Toggles the flushable flag. If \it{flushable} is disabled, no datas are sent
 323 to the parent stream.
 324
 325 \membersection{wxStreamBuffer::FlushBuffer}
 326
 327 \func{bool}{FlushBuffer}{\void}
 328
 329 Flushes the IO buffer.
 330
 331 \membersection{wxStreamBuffer::FillBuffer}
 332
 333 \func{bool}{FillBuffer}{\void}
 334
 335 Fill the IO buffer.
 336
 337 \membersection{wxStreamBuffer::GetDataLeft}
 338
 339 \func{size\_t}{GetDataLeft}{\void}
 340
 341 Returns the amount of available datas in the buffer.
 342
 343 % --------------
 344 % Administration
 345 % --------------
 346 \membersection{wxStreamBuffer::Stream}
 347
 348 \func{wxStreamBase*}{Stream}{\void}
 349
 350 Returns the parent stream of the stream buffer.
 351