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