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{Library}
  12
  13 \helpref{wxBase}{librarieslist}
  14
  15 \wxheading{See also}
  16
  17 \helpref{wxStreamBase}{wxstreambase}
  18
  19 \latexignore{\rtfignore{\wxheading{Members}}}
  20
  21
  22 \membersection{wxStreamBuffer::wxStreamBuffer}\label{wxstreambufferctor}
  23
  24 \func{}{wxStreamBuffer}{\param{wxStreamBase\&}{ stream}, \param{BufMode}{ mode}}
  25
  26 Constructor, creates a new stream buffer using {\it stream} as a parent stream
  27 and {\it mode} as the IO mode. {\it mode} can be: wxStreamBuffer::read,
  28 wxStreamBuffer::write, wxStreamBuffer::read\_write.
  29
  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. Note that
  33 all errors and messages linked to the stream are stored in the stream, not
  34 the stream buffers:
  35
  36 \begin{verbatim}
  37   streambuffer.Read(...);
  38   streambuffer2.Read(...); /* This call erases previous error messages set by
  39                               ``streambuffer'' */
  40 \end{verbatim}
  41
  42 \func{}{wxStreamBuffer}{\param{BufMode}{ mode}}
  43
  44 Constructor, creates a new empty stream buffer which won't flush any data
  45 to a stream. {\it mode} specifies the type of the buffer (read, write, read\_write).
  46 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 doesn't currently work for standalone stream buffers.
  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 has the same attributes, size, position
  60 and they share the same buffer. This will cause problems if the stream to
  61 which the stream buffer belong is destroyed and the newly cloned stream
  62 buffer continues to be used, trying to call functions in the (destroyed)
  63 stream. It is advised to use this feature only in very local area of the
  64 program.
  65
  66 \wxheading{See also}
  67
  68 \helpref{wxStreamBuffer:SetBufferIO}{wxstreambuffersetbufferio}
  69
  70
  71 \membersection{wxStreamBuffer::\destruct{wxStreamBuffer}}\label{wxstreambufferdtor}
  72
  73 \func{}{wxStreamBuffer}{\destruct{wxStreamBuffer}}
  74
  75 Destructor. It finalizes all IO calls and frees all internal buffers if
  76 necessary.
  77
  78
  79 \membersection{wxStreamBuffer::FillBuffer}\label{wxstreambufferfillbuffer}
  80
  81 \func{bool}{FillBuffer}{\void}
  82
  83 Fill the IO buffer.
  84
  85
  86 \membersection{wxStreamBuffer::Fixed}\label{wxstreambufferfixed}
  87
  88 \func{void}{Fixed}{\param{bool}{ fixed}}
  89
  90 Toggles the fixed flag. Usually this flag is toggled at the same time as
  91 {\it flushable}. This flag allows (when it has the false value) or forbids
  92 (when it has the true value) the stream buffer to resize dynamically the IO buffer.
  93
  94 \wxheading{See also}
  95
  96 \helpref{wxStreamBuffer::SetBufferIO}{wxstreambuffersetbufferio}
  97
  98
  99 \membersection{wxStreamBuffer::Flushable}\label{wxstreambufferflushable}
 100
 101 \func{void}{Flushable}{\param{bool}{ flushable}}
 102
 103 Toggles the flushable flag. If {\it flushable} is disabled, no data are sent
 104 to the parent stream.
 105
 106
 107 \membersection{wxStreamBuffer::FlushBuffer}\label{wxstreambufferflushbuffer}
 108
 109 \func{bool}{FlushBuffer}{\void}
 110
 111 Flushes the IO buffer.
 112
 113
 114 \membersection{wxStreamBuffer::GetBufferEnd}\label{wxstreambuffergetbufferend}
 115
 116 \constfunc{void *}{GetBufferEnd}{\void}
 117
 118 Returns a pointer on the end of the stream buffer.
 119
 120
 121 \membersection{wxStreamBuffer::GetBufferPos}\label{wxstreambuffergetbufferpos}
 122
 123 \constfunc{void *}{GetBufferPos}{\void}
 124
 125 Returns a pointer on the current position of the stream buffer.
 126
 127
 128 \membersection{wxStreamBuffer::GetBufferSize}\label{wxstreambuffergetbuffersize}
 129
 130 \constfunc{size\_t}{GetBufferSize}{\void}
 131
 132 Returns the size of the buffer.
 133
 134
 135 \membersection{wxStreamBuffer::GetBufferStart}\label{wxstreambuffergetbufferstart}
 136
 137 \constfunc{void *}{GetBufferStart}{\void}
 138
 139 Returns a pointer on the start of the stream buffer.
 140
 141
 142 \membersection{wxStreamBuffer::GetChar}\label{wxstreambuffergetchar}
 143
 144 \func{char}{GetChar}{\void}
 145
 146 Gets a single char from the stream buffer. It acts like the Read call.
 147
 148 \wxheading{Problem}
 149
 150 You aren't directly notified if an error occurred during the IO call.
 151
 152 \wxheading{See also}
 153
 154 \helpref{wxStreamBuffer::Read}{wxstreambufferread}
 155
 156
 157 \membersection{wxStreamBuffer::GetDataLeft}\label{wxstreambuffergetdataleft}
 158
 159 \func{size\_t}{GetDataLeft}{\void}
 160
 161 Returns the amount of available data in the buffer.
 162
 163
 164 \membersection{wxStreamBuffer::GetIntPosition}\label{wxstreambuffergetintposition}
 165
 166 \constfunc{off\_t}{GetIntPosition}{\void}
 167
 168 Returns the current position (counted in bytes) in the stream buffer.
 169
 170
 171 \membersection{wxStreamBuffer::GetLastAccess}\label{wxstreambuffergetlastaccess}
 172
 173 \constfunc{size\_t}{GetLastAccess}{\void}
 174
 175 Returns the amount of bytes read during the last IO call to the parent stream.
 176
 177
 178 \membersection{wxStreamBuffer::PutChar}\label{wxstreambufferputchar}
 179
 180 \func{void}{PutChar}{\param{char }{c}}
 181
 182 Puts a single char to the stream buffer.
 183
 184 \wxheading{Problem}
 185
 186 You aren't directly notified if an error occurred during the IO call.
 187
 188 \wxheading{See also}
 189
 190 \helpref{wxStreamBuffer::Read}{wxstreambufferwrite}
 191
 192
 193 \membersection{wxStreamBuffer::Read}\label{wxstreambufferread}
 194
 195 \func{size\_t}{Read}{\param{void *}{buffer}, \param{size\_t }{size}}
 196
 197 Reads a block of the specified {\it size} and stores the data in {\it buffer}.
 198 This function tries to read from the buffer first and if more data has been
 199 requested, reads more data from the associated stream and updates the buffer
 200 accordingly until all requested data is read.
 201
 202 \wxheading{Return value}
 203
 204 It returns the size of the data read. If the returned size is different of the specified
 205 {\it size}, an error has occurred and should be tested using
 206 \helpref{GetLastError}{wxstreambasegetlasterror}.
 207
 208 \func{size\_t}{Read}{\param{wxStreamBuffer *}{buffer}}
 209
 210 Copies data to {\it buffer}. The function returns when {\it buffer} is full or when there isn't
 211 any more data in the current buffer.
 212
 213 \wxheading{See also}
 214
 215 \helpref{wxStreamBuffer::Write}{wxstreambufferwrite}
 216
 217
 218 \membersection{wxStreamBuffer::ResetBuffer}\label{wxstreambufferresetbuffer}
 219
 220 \func{void}{ResetBuffer}{\void}
 221
 222 Resets to the initial state variables concerning the buffer.
 223
 224
 225 \membersection{wxStreamBuffer::Seek}\label{wxstreambufferseek}
 226
 227 \func{off\_t}{Seek}{\param{off\_t }{pos}, \param{wxSeekMode }{mode}}
 228
 229 Changes the current position.
 230
 231 {\it mode} may be one of the following:
 232
 233 \twocolwidtha{5cm}
 234 \begin{twocollist}\itemsep=0pt
 235 \twocolitem{{\bf wxFromStart}}{The position is counted from the start of the stream.}
 236 \twocolitem{{\bf wxFromCurrent}}{The position is counted from the current position of the stream.}
 237 \twocolitem{{\bf wxFromEnd}}{The position is counted from the end of the stream.}
 238 \end{twocollist}
 239
 240 \wxheading{Return value}
 241
 242 Upon successful completion, it returns the new offset as measured in bytes from
 243 the beginning of the stream. Otherwise, it returns wxInvalidOffset.
 244
 245
 246 \membersection{wxStreamBuffer::SetBufferIO}\label{wxstreambuffersetbufferio}
 247
 248 \func{void}{SetBufferIO}{\param{char*}{ buffer\_start}, \param{char*}{ buffer\_end}}
 249
 250 Specifies which pointers to use for stream buffering. You need to pass a pointer on the
 251 start of the buffer end and another on the end. The object will use this buffer
 252 to cache stream data. It may be used also as a source/destination buffer when
 253 you create an empty stream buffer (See \helpref{wxStreamBuffer::wxStreamBuffer}{wxstreambufferctor}).
 254
 255 \wxheading{Remarks}
 256
 257 When you use this function, you will have to destroy the IO buffers yourself
 258 after the stream buffer is destroyed or don't use it anymore.
 259 In the case you use it with an empty buffer, the stream buffer will not resize
 260 it when it is full.
 261
 262 \wxheading{See also}
 263
 264 \helpref{wxStreamBuffer constructor}{wxstreambufferctor}\\
 265 \helpref{wxStreamBuffer::Fixed}{wxstreambufferfixed}\\
 266 \helpref{wxStreamBuffer::Flushable}{wxstreambufferflushable}
 267
 268 \func{void}{SetBufferIO}{\param{size\_t}{ bufsize}}
 269
 270 Destroys or invalidates the previous IO buffer and allocates a new one of the
 271 specified size.
 272
 273 \wxheading{Warning}
 274
 275 All previous pointers aren't valid anymore.
 276
 277 \wxheading{Remark}
 278
 279 The created IO buffer is growable by the object.
 280
 281 \wxheading{See also}
 282
 283 \helpref{wxStreamBuffer::Fixed}{wxstreambufferfixed}\\
 284 \helpref{wxStreamBuffer::Flushable}{wxstreambufferflushable}
 285
 286
 287 \membersection{wxStreamBuffer::SetIntPosition}\label{wxstreambuffersetintposition}
 288
 289 \func{void}{SetIntPosition}{\param{size\_t}{ pos}}
 290
 291 Sets the current position (in bytes) in the stream buffer.
 292
 293 \wxheading{Warning}
 294
 295 Since it is a very low-level function, there is no check on the position:
 296 specifying an invalid position can induce unexpected results.
 297
 298
 299 \membersection{wxStreamBuffer::Stream}\label{wxstreambufferstream}
 300
 301 \func{wxStreamBase*}{Stream}{\void}
 302
 303 Returns the parent stream of the stream buffer.
 304
 305
 306 \membersection{wxStreamBuffer::Tell}\label{wxstreambuffertell}
 307
 308 \constfunc{off\_t}{Tell}{\void}
 309
 310 Gets the current position in the stream. This position is calculated from
 311 the {\it real} position in the stream and from the internal buffer position: so
 312 it gives you the position in the {\it real} stream counted from the start of
 313 the stream.
 314
 315 \wxheading{Return value}
 316
 317 Returns the current position in the stream if possible, wxInvalidOffset in the
 318 other case.
 319
 320
 321 \membersection{wxStreamBuffer::Truncate}\label{wxstreambuffertruncate}
 322
 323 \func{void}{Truncate}{\void}
 324
 325 Truncates the buffer to the current position.
 326
 327 Note: Truncate() cannot be used to enlarge the buffer. This is
 328 usually not needed since the buffer expands automatically.
 329
 330
 331 \membersection{wxStreamBuffer::Write}\label{wxstreambufferwrite}
 332
 333 \func{size\_t}{Write}{\param{const void *}{buffer}, \param{size\_t }{size}}
 334
 335 Writes a block of the specified {\it size} using data of {\it buffer}. The data
 336 are cached in a buffer before being sent in one block to the stream.
 337
 338 \func{size\_t}{Write}{\param{wxStreamBuffer *}{buffer}}
 339
 340 See \helpref{Read}{wxstreambufferread}.
 341