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