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