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 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}}
  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 Reads a {\it buffer}. The function returns when {\it buffer} is full or when there isn't
  99 data anymore 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}
 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}
 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}
 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}
 182
 183 \func{void}{ResetBuffer}{\void}
 184
 185 Resets to the initial state variables concerning the buffer.
 186
 187 \membersection{wxStreamBuffer::SetBufferIO}\label{wxstreambuffersetbufferio}
 188
 189 \func{void}{SetBufferIO}{\param{char*}{ buffer\_start}, \param{char*}{ buffer\_end}}
 190
 191 Specifies which pointers to use for stream buffering. You need to pass a pointer on the
 192 start of the buffer end and another on the end. The object will use this buffer
 193 to cache stream data. It may be used also as a source/destination buffer when
 194 you create an empty stream buffer (See \helpref{wxStreamBuffer::wxStreamBuffer}{wxstreambufconst}).
 195
 196 \wxheading{Remarks}
 197
 198 When you use this function, you will have to destroy the IO buffers yourself
 199 after the stream buffer is destroyed or don't use it anymore.
 200 In the case you use it with an empty buffer, the stream buffer will not resize
 201 it when it is full.
 202
 203 \wxheading{See also}
 204
 205 \helpref{wxStreamBuffer constructor}{wxstreambufconst}\\
 206 \helpref{wxStreamBuffer::Fixed}{wxstreambufferfixed}\\
 207 \helpref{wxStreamBuffer::Flushable}{wxstreambufferflushable}
 208
 209 \func{void}{SetBufferIO}{\param{size\_t}{ bufsize}}
 210
 211 Destroys or invalidates the previous IO buffer and allocates a new one of the
 212 specified size.
 213
 214 \wxheading{Warning}
 215
 216 All previous pointers aren't valid anymore.
 217
 218 \wxheading{Remark}
 219
 220 The created IO buffer is growable by the object.
 221
 222 \wxheading{See also}
 223
 224 \helpref{wxStreamBuffer::Fixed}{wxstreambufferfixed}\\
 225 \helpref{wxStreamBuffer::Flushable}{wxstreambufferflushable}
 226
 227 \membersection{wxStreamBuffer::GetBufferStart}
 228
 229 \constfunc{char *}{GetBufferStart}{\void}
 230
 231 Returns a pointer on the start of the stream buffer.
 232
 233 \membersection{wxStreamBuffer::GetBufferEnd}
 234
 235 \constfunc{char *}{GetBufferEnd}{\void}
 236
 237 Returns a pointer on the end of the stream buffer.
 238
 239 \membersection{wxStreamBuffer::GetBufferPos}
 240
 241 \constfunc{char *}{GetBufferPos}{\void}
 242
 243 Returns a pointer on the current position of the stream buffer.
 244
 245 \membersection{wxStreamBuffer::GetIntPosition}
 246
 247 \constfunc{off\_t}{GetIntPosition}{\void}
 248
 249 Returns the current position (counted in bytes) in the stream buffer.
 250
 251 \membersection{wxStreamBuffer::SetIntPosition}
 252
 253 \func{void}{SetIntPosition}{\param{size\_t}{ pos}}
 254
 255 Sets the current position (in bytes) in the stream buffer.
 256
 257 \wxheading{Warning}
 258
 259 Since it is a very low-level function, there is no check on the position:
 260 specifing an invalid position can induce unexpected results.
 261
 262 \membersection{wxStreamBuffer::GetLastAccess}
 263
 264 \constfunc{size\_t}{GetLastAccess}{\void}
 265
 266 Returns the amount of bytes read during the last IO call to the parent stream.
 267
 268 \membersection{wxStreamBuffer::Fixed}\label{wxstreambufferfixed}
 269
 270 \func{void}{Fixed}{\param{bool}{ fixed}}
 271
 272 Toggles the fixed flag. Usually this flag is toggled at the same time as
 273 {\it flushable}. This flag allows (when it has the false value) or forbids
 274 (when it has the true value) the stream buffer to resize dynamically the IO buffer.
 275
 276 \wxheading{See also}
 277
 278 \helpref{wxStreamBuffer::SetBufferIO}{wxstreambuffersetbufferio}
 279
 280 \membersection{wxStreamBuffer::Flushable}\label{wxstreambufferflushable}
 281
 282 \func{void}{Flushable}{\param{bool}{ flushable}}
 283
 284 Toggles the flushable flag. If {\it flushable} is disabled, no data are sent
 285 to the parent stream.
 286
 287 \membersection{wxStreamBuffer::FlushBuffer}
 288
 289 \func{bool}{FlushBuffer}{\void}
 290
 291 Flushes the IO buffer.
 292
 293 \membersection{wxStreamBuffer::FillBuffer}
 294
 295 \func{bool}{FillBuffer}{\void}
 296
 297 Fill the IO buffer.
 298
 299 \membersection{wxStreamBuffer::GetDataLeft}
 300
 301 \func{size\_t}{GetDataLeft}{\void}
 302
 303 Returns the amount of available data in the buffer.
 304
 305 % --------------
 306 % Administration
 307 % --------------
 308 \membersection{wxStreamBuffer::Stream}
 309
 310 \func{wxStreamBase*}{Stream}{\void}
 311
 312 Returns the parent stream of the stream buffer.
 313