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