docs/latex/wx/stream.tex

   1 \section{\class{wxStreamBuffer}}\label{wxstreambuffer}
   2
   3 \wxheading{Derived from}
   4
   5 None
   6
   7 \wxheading{See also}
   8
   9 \helpref{wxStreamBase}{wxstreambase}
  10
  11 % ---------------------------------------------------------------------------
  12 % Members
  13 % ---------------------------------------------------------------------------
  14 \latexignore{\rtfignore{\wxheading{Members}}}
  15
  16 % -----------
  17 % ctor & dtor
  18 % -----------
  19 \membersection{wxStreamBuffer::wxStreamBuffer}
  20
  21 \func{}{wxStreamBuffer}{\param{wxStreamBase\&}{ stream}, \param{BufMode}{ mode}}
  22
  23 Constructor, creates a new stream buffer using \it{stream} as a parent stream
  24 and \it{mode} as the IO mode. \it{mode} can be: wxStreamBuffer::read,
  25 wxStreamBuffer::write, wxStreamBuffer::read\_write.
  26 One stream can have many stream buffers but only one is used internally to
  27 pass IO call (e.g. wxInputStream::Read() -> wxStreamBuffer::Read()). But you
  28 can call directly wxStreamBuffer::Read without any problems.
  29
  30 \wxheading{Warning}
  31
  32 All errors and messages linked to the stream are stored in the stream object.
  33 \begin{verbatim}
  34    streambuffer.Read(...);
  35    streambuffer2.Read(...); /* This one erases previous error messages set by
  36                                ``streambuffer'' */
  37 \end{verbatim}
  38
  39 \func{}{wxStreamBuffer}{\param{BufMode}{ mode}}
  40
  41 Constructor, creates a new empty stream buffer which won't flush any data
  42 to a stream. \it{mode} specifies the type of the buffer (read, write, read\_write). This stream buffer has the advantage to be stream independent and to
  43 work only on memory buffers but it is still compatible with the rest of the
  44 wxStream classes. You can write, read to this special stream and it will
  45 grow (if it is allowed by the user) its internal buffer. Briefly, it has all
  46 functionnalities of a ``normal'' stream.
  47
  48 \wxheading{Warning}
  49
  50 The "read\_write" mode may not work: it isn't completely finished.
  51
  52 \wxheading{See also}
  53
  54 \helpref{wxStreamBuffer:SetBufferIO}{wxstreambufsetbufferio}
  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 is nearly exactly the same as the
  60 original: it has the same attributes, the same size, the same position, shares
  61 the same internal buffer. The interresting point is that they can differ
  62 in the future but the root is the same.
  63
  64 \wxheading{Warning}
  65
  66 The fact that the two stream buffers shared the same buffer could generate
  67 segmentation violation if the parent is destroyed and the children continues
  68 operating. It is advised to use this feature only in very local area of the
  69 program.
  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. In the case of a children stream buffer, the internal buffer isn't
  77 freed, this is the job of the parent.
  78 The "Write-Back" buffer is freed.
  79
  80 % -----------
  81 % Filtered IO
  82 % -----------
  83 \membersection{wxStreamBuffer::Read}\label{wxstreambufread}
  84
  85 \func{size\_t}{Read}{\param{void *}{buffer}, \param{size\_t }{size}}
  86
  87 Reads a block of the specified \it{size} and stores datas in \it{buffer}.
  88 This function uses also the "Write-Back" buffer: in the case there are datas
  89 waiting in this buffer, they are used before anything else. After that, if there
  90 are still datas to be read, the stream is read and the stream buffer position
  91 is incremented.
  92
  93 \wxheading{Return value}
  94
  95 It returns the real read size. If returned size is different of the specified
  96 \it{size}, an error occured and should be tested using
  97 \helpref{LastError}{wxstreambaselasterror}.
  98
  99 \wxheading{See also}
 100
 101 \helpref{wxStreamBuffer::WriteBack}{wxstreambufwriteback}
 102
 103 \func{size\_t}{Read}{\param{wxStreamBuffer *}{buffer}}
 104
 105 Reads a \it{buffer}. The function returns when \it{buffer} is full or
 106 when there aren't datas anymore in the current buffer.
 107
 108 \membersection{wxStreamBuffer::Write}
 109
 110 \func{size\_t}{Write}{\param{const void *}{buffer}, \param{size\_t }{size}}
 111
 112 Writes a block of the specified \it{size} using datas of \it{buffer}. The datas
 113 are cached in a buffer before being sent in one block to the stream.
 114
 115 \func{size\_t}{Write}{\param{wxStreamBuffer *}{buffer}}
 116
 117 See \helpref{Read}{wxstreambufreadbuf}
 118
 119 \membersection{wxStreamBuffer::WriteBack}\label{wxstreambufwriteback}
 120
 121 \func{size\_t}{WriteBack}{\param{const char*}{ buffer}, \param{size\_t}{ size}}
 122
 123 This function is only useful in \it{read} mode. It is the manager of the "Write-Back"
 124 buffer. This buffer acts like a temporary buffer where datas which has to be
 125 read during the next read IO call are put. This is useful when you get a big
 126 block of data which you didn't want to read: you can replace them at the top
 127 of the input queue by this way.
 128
 129 \wxheading{Return value}
 130
 131 Returns the amount of bytes saved in the Write-Back buffer.
 132
 133 \func{size\_t}{WriteBack}{\param{char }{c}}
 134
 135 This function acts like the previous one except that it takes only one
 136 character: it is sometimes shorter to use than the generic function.
 137
 138 \membersection{wxStreamBuffer::GetChar}
 139
 140 \func{char}{GetChar}{\void}
 141
 142 Gets a single char from the stream buffer. It acts like the Read call.
 143
 144 \wxheading{Problem}
 145
 146 You aren't directly notified if an error occured during the IO call.
 147
 148 \wxheading{See also}
 149
 150 \helpref{wxStreamBuffer::Read}{wxstreambufread}
 151
 152 \membersection{wxStreamBuffer::PutChar}
 153
 154 \func{void}{PutChar}{\param{char }{c}}
 155
 156 Puts a single char to the stream buffer.
 157
 158 \wxheading{Problem}
 159
 160 You aren't directly notified if an error occured during the IO call.
 161
 162 \wxheading{See also}
 163
 164 \helpref{wxStreamBuffer::Read}{wxstreambufwrite}
 165
 166 \membersection{wxStreamBuffer::Tell}
 167
 168 \constfunc{off\_t}{Tell}{\void}
 169
 170 Gets the current position in the stream. This position is calculated from
 171 the \it{real} position in the stream and from the internal buffer position: so
 172 it gives you the position in the \it{real} stream counted from the start of
 173 the stream.
 174
 175 \wxheading{Return value}
 176
 177 Returns the current position in the stream if possible, wxInvalidOffset in the
 178 other case.
 179
 180 \membersection{wxStreamBuffer::Seek}\label{wxstreambufferseek}
 181
 182 \func{off\_t}{Seek}{\param{off\_t }{pos}, \param{wxSeekMode }{mode}}
 183
 184 Changes the current position.
 185
 186 \it{mode} may be one of the following:
 187
 188 \twocolwidtha{5cm}
 189 \begin{twocollist}\itemsep=0pt
 190 \twocolitem{{\bf wxFromStart}}{The position is counted from the start of the stream.}
 191 \twocolitem{{\bf wxFromCurrent}}{The position is counted from the current position of the stream.}
 192 \twocolitem{{\bf wxFromEnd}}{The position is counted from the end of the stream.}
 193 \end{twocollist}
 194
 195 \wxheading{Return value}
 196
 197 Upon successful completion, it returns the new offset as measured in bytes from
 198 the beginning of the stream. Otherwise, it returns wxInvalidOffset.
 199
 200 % --------------
 201 % Buffer control
 202 % --------------
 203 \membersection{wxStreamBuffer::ResetBuffer}
 204
 205 \func{void}{ResetBuffer}{\void}
 206
 207 Resets to the initial state variables concerning the buffer.
 208
 209 \membersection{wxStreamBuffer::SetBufferIO}\label{wxstreambufsetbufferio}
 210
 211 \func{void}{SetBufferIO}{\param{char*}{ buffer\_start}, \param{char*}{ buffer\_end}}
 212
 213 Specifies which pointers to use for stream buffering. You need to pass a pointer on the
 214 start of the buffer end and another on the end.
 215
 216 \func{void}{SetBufferIO}{\param{size\_t}{ bufsize}}
 217
 218 Changes the size of the current IO buffer.
 219
 220 \membersection{wxStreamBuffer::GetBufferStart}
 221
 222 \constfunc{char *}{GetBufferStart}{\void}
 223
 224 Returns a pointer on the start of the stream buffer.
 225
 226 \membersection{wxStreamBuffer::GetBufferEnd}
 227
 228 \constfunc{char *}{GetBufferEnd}{\void}
 229
 230 Returns a pointer on the end of the stream buffer.
 231
 232 \membersection{wxStreamBuffer::GetBufferPos}
 233
 234 \constfunc{char *}{GetBufferPos}{\void}
 235
 236 Returns a pointer on the current position of the stream buffer.
 237
 238 \membersection{wxStreamBuffer::GetIntPosition}
 239
 240 \constfunc{off\_t}{GetIntPosition}{\void}
 241
 242 Returns the current position in the stream buffer.
 243
 244 \membersection{wxStreamBuffer::SetIntPosition}
 245
 246 \func{void}{SetIntPosition}{\void}
 247
 248 Sets the current position in the stream buffer.
 249
 250 \membersection{wxStreamBuffer::GetLastAccess}
 251
 252 \constfunc{size\_t}{GetLastAccess}{\void}
 253
 254 Returns the amount of bytes read during the last IO call to the parent stream.
 255
 256 \membersection{wxStreamBuffer::Fixed}
 257
 258 \func{void}{Fixed}{\param{bool}{ fixed}}
 259
 260 Toggles the fixed flag. Usually this flag is toggled at the same time as
 261 \it{flushable}. This flag allows (when it is FALSE) or forbids (when it is TRUE)
 262 the stream buffer to resize dynamically the IO buffer.
 263
 264 \membersection{wxStreamBuffer::Flushable}
 265
 266 \func{void}{Flushable}{\param{bool}{ flushable}}
 267
 268 Toggles the flushable flag. If \it{flushable} is disabled, no datas are sent
 269 to the parent stream.
 270
 271 \membersection{wxStreamBuffer::FlushBuffer}
 272
 273 \func{bool}{FlushBuffer}{\void}
 274
 275 Flushes the IO buffer.
 276
 277 \membersection{wxStreamBuffer::FillBuffer}
 278
 279 \func{bool}{FillBuffer}{\void}
 280
 281 Fill the IO buffer.
 282
 283 \membersection{wxStreamBuffer::GetDataLeft}
 284
 285 \func{size\_t}{GetDataLeft}{\void}
 286
 287 Returns the amount of available datas in the buffer.
 288
 289 % --------------
 290 % Administration
 291 % --------------
 292 \membersection{wxStreamBuffer::Stream}
 293
 294 \func{wxStreamBase*}{Stream}{\void}
 295
 296 Returns the parent stream of the stream buffer.
 297