X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/b82827dd43caa489eade15cc02edef7fb79e8c20..e39d30c05b9febb396cd9f133b9df7718142e299:/docs/latex/wx/stream.tex diff --git a/docs/latex/wx/stream.tex b/docs/latex/wx/stream.tex index cd2abb12bf..420a2c04db 100644 --- a/docs/latex/wx/stream.tex +++ b/docs/latex/wx/stream.tex @@ -1,218 +1,341 @@ -\section{\class{wxStreamBuffer}}\label{wxstreambuf} +\section{\class{wxStreamBuffer}}\label{wxstreambuffer} \wxheading{Derived from} None +\wxheading{Include files} + + + +\wxheading{Library} + +\helpref{wxBase}{librarieslist} + \wxheading{See also} \helpref{wxStreamBase}{wxstreambase} -% --------------------------------------------------------------------------- -% Members -% --------------------------------------------------------------------------- \latexignore{\rtfignore{\wxheading{Members}}} -% ----------- -% ctor & dtor -% ----------- -\membersection{wxStreamBuffer::wxStreamBuffer} + +\membersection{wxStreamBuffer::wxStreamBuffer}\label{wxstreambufferctor} \func{}{wxStreamBuffer}{\param{wxStreamBase\&}{ stream}, \param{BufMode}{ mode}} -Constructor, creates a new stream buffer using \it{stream} as a parent stream -and \it{mode} as the IO mode. \it{mode} can be: wxStreamBuffer::read, +Constructor, creates a new stream buffer using {\it stream} as a parent stream +and {\it mode} as the IO mode. {\it mode} can be: wxStreamBuffer::read, wxStreamBuffer::write, wxStreamBuffer::read\_write. -\membersection{wxStreamBuffer::wxStreamBuffer} +One stream can have many stream buffers but only one is used internally to +pass IO call (e.g. wxInputStream::Read() -> wxStreamBuffer::Read()), but you +can call directly wxStreamBuffer::Read without any problems. Note that +all errors and messages linked to the stream are stored in the stream, not +the stream buffers: + +\begin{verbatim} + streambuffer.Read(...); + streambuffer2.Read(...); /* This call erases previous error messages set by + ``streambuffer'' */ +\end{verbatim} \func{}{wxStreamBuffer}{\param{BufMode}{ mode}} -Constructor, creates a new empty stream buffer which won't flush any datas -to a stream. \it{mode} specifies the type of the buffer (read, write, read\_write). +Constructor, creates a new empty stream buffer which won't flush any data +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 +work only on memory buffers but it is still compatible with the rest of the +wxStream classes. You can write, read to this special stream and it will +grow (if it is allowed by the user) its internal buffer. Briefly, it has all +functionality of a ``normal'' stream. -\membersection{wxStreamBuffer::wxStreamBuffer} +\wxheading{Warning} -\func{}{wxStreamBuffer}{\param{const wxStreamBase\&}{ buffer}} +The "read\_write" mode doesn't currently work for standalone stream buffers. -Constructor, creates a new stream buffer from the specified stream \it{buffer}. +\func{}{wxStreamBuffer}{\param{const wxStreamBuffer\&}{buffer}} -\membersection{wxStreamBuffer::\destruct{wxStreamBuffer}} +Constructor. It initializes the stream buffer with the data of the specified +stream buffer. The new stream buffer has the same attributes, size, position +and they share the same buffer. This will cause problems if the stream to +which the stream buffer belong is destroyed and the newly cloned stream +buffer continues to be used, trying to call functions in the (destroyed) +stream. It is advised to use this feature only in very local area of the +program. -\func{}{\destruct{wxStreamBuffer}} +\wxheading{See also} -Destructor, destroys the stream buffer. +\helpref{wxStreamBuffer:SetBufferIO}{wxstreambuffersetbufferio} -% ----------- -% Filtered IO -% ----------- -\membersection{wxStreamBuffer::Read}\label{wxstreambufread} -\func{size\_t}{Read}{\param{void *}{buffer}, \param{size\_t }{size}} +\membersection{wxStreamBuffer::\destruct{wxStreamBuffer}}\label{wxstreambufferdtor} -Reads a block of the specified \it{size} and stores datas in \it{buffer}. +\func{}{wxStreamBuffer}{\destruct{wxStreamBuffer}} -\wxheading{Return value} +Destructor. It finalizes all IO calls and frees all internal buffers if +necessary. -It returns the real read size. If returned size is different of the specified -\it{size}, an error occured and should be tested using -\helpref{GetError}{wxstreambasegeterror}. -\membersection{wxStreamBuffer::Read}\label{wxstreambufreadbuf} +\membersection{wxStreamBuffer::FillBuffer}\label{wxstreambufferfillbuffer} -\func{size\_t}{Read}{\param{wxStreamBuffer *}{buffer}} +\func{bool}{FillBuffer}{\void} -Reads a \it{buffer}. The function returns when \it{buffer} is full or -when there aren't datas anymore in the current buffer. +Fill the IO buffer. -\membersection{wxStreamBuffer::Write} -\func{size\_t}{Write}{\param{const void *}{buffer}, \param{size\_t }{size}} +\membersection{wxStreamBuffer::Fixed}\label{wxstreambufferfixed} -Writes a block of the specified \it{size} using datas of \it{buffer}. +\func{void}{Fixed}{\param{bool}{ fixed}} -\membersection{wxStreamBuffer::Write} +Toggles the fixed flag. Usually this flag is toggled at the same time as +{\it flushable}. This flag allows (when it has the false value) or forbids +(when it has the true value) the stream buffer to resize dynamically the IO buffer. -\func{size\_t}{Write}{\param{wxStreamBuffer *}{buffer}} +\wxheading{See also} + +\helpref{wxStreamBuffer::SetBufferIO}{wxstreambuffersetbufferio} + + +\membersection{wxStreamBuffer::Flushable}\label{wxstreambufferflushable} + +\func{void}{Flushable}{\param{bool}{ flushable}} + +Toggles the flushable flag. If {\it flushable} is disabled, no data are sent +to the parent stream. + + +\membersection{wxStreamBuffer::FlushBuffer}\label{wxstreambufferflushbuffer} + +\func{bool}{FlushBuffer}{\void} + +Flushes the IO buffer. + + +\membersection{wxStreamBuffer::GetBufferEnd}\label{wxstreambuffergetbufferend} + +\constfunc{void *}{GetBufferEnd}{\void} + +Returns a pointer on the end of the stream buffer. -See \helpref{Read}{wxstreambufreadbuf} -\membersection{wxStreamBuffer::WriteBack} +\membersection{wxStreamBuffer::GetBufferPos}\label{wxstreambuffergetbufferpos} -\func{size\_t}{WriteBack}{\param{const char *}{buffer}, \param{size\_t}{ size}} +\constfunc{void *}{GetBufferPos}{\void} + +Returns a pointer on the current position of the stream buffer. -This function is only useful in ``read'' mode. It puts the specified \it{buffer} -in the input queue of the stream buf. By this way, the next -\helpref{Read}{wxstreambufread} call will first use these datas. -\membersection{wxStreamBuffer::WriteBack} +\membersection{wxStreamBuffer::GetBufferSize}\label{wxstreambuffergetbuffersize} -\func{size\_t}{WriteBack}{\param{char }{c}} +\constfunc{size\_t}{GetBufferSize}{\void} -As for the previous function, it puts the specified byte in the input queue of the -stream buffer. +Returns the size of the buffer. -\membersection{wxStreamBuffer::GetChar} + +\membersection{wxStreamBuffer::GetBufferStart}\label{wxstreambuffergetbufferstart} + +\constfunc{void *}{GetBufferStart}{\void} + +Returns a pointer on the start of the stream buffer. + + +\membersection{wxStreamBuffer::GetChar}\label{wxstreambuffergetchar} \func{char}{GetChar}{\void} -Gets a single char from the stream buffer. +Gets a single char from the stream buffer. It acts like the Read call. + +\wxheading{Problem} + +You aren't directly notified if an error occurred during the IO call. + +\wxheading{See also} + +\helpref{wxStreamBuffer::Read}{wxstreambufferread} + + +\membersection{wxStreamBuffer::GetDataLeft}\label{wxstreambuffergetdataleft} + +\func{size\_t}{GetDataLeft}{\void} + +Returns the amount of available data in the buffer. + + +\membersection{wxStreamBuffer::GetIntPosition}\label{wxstreambuffergetintposition} + +\constfunc{off\_t}{GetIntPosition}{\void} + +Returns the current position (counted in bytes) in the stream buffer. -\membersection{wxStreamBuffer::PutChar} + +\membersection{wxStreamBuffer::GetLastAccess}\label{wxstreambuffergetlastaccess} + +\constfunc{size\_t}{GetLastAccess}{\void} + +Returns the amount of bytes read during the last IO call to the parent stream. + + +\membersection{wxStreamBuffer::PutChar}\label{wxstreambufferputchar} \func{void}{PutChar}{\param{char }{c}} Puts a single char to the stream buffer. -\membersection{wxStreamBuffer::Tell} +\wxheading{Problem} -\constfunc{off\_t}{Tell}{\void} +You aren't directly notified if an error occurred during the IO call. -Gets the current position in the \it{stream}. +\wxheading{See also} -\membersection{wxStreamBuffer::Seek} +\helpref{wxStreamBuffer::Read}{wxstreambufferwrite} -\func{off\_t}{Seek}{\param{off\_t }{pos}, \param{wxSeekMode }{mode}} -Changes the current position. (TODO) +\membersection{wxStreamBuffer::Read}\label{wxstreambufferread} + +\func{size\_t}{Read}{\param{void *}{buffer}, \param{size\_t }{size}} + +Reads a block of the specified {\it size} and stores the data in {\it buffer}. +This function tries to read from the buffer first and if more data has been +requested, reads more data from the associated stream and updates the buffer +accordingly until all requested data is read. + +\wxheading{Return value} -% -------------- -% Buffer control -% -------------- -\membersection{wxStreamBuffer::ResetBuffer} +It returns the size of the data read. If the returned size is different of the specified +{\it size}, an error has occurred and should be tested using +\helpref{GetLastError}{wxstreambasegetlasterror}. + +\func{size\_t}{Read}{\param{wxStreamBuffer *}{buffer}} + +Copies data to {\it buffer}. The function returns when {\it buffer} is full or when there isn't +any more data in the current buffer. + +\wxheading{See also} + +\helpref{wxStreamBuffer::Write}{wxstreambufferwrite} + + +\membersection{wxStreamBuffer::ResetBuffer}\label{wxstreambufferresetbuffer} \func{void}{ResetBuffer}{\void} -Frees all internal buffers and resets to initial state all variables. +Resets to the initial state variables concerning the buffer. + -\membersection{wxStreamBuffer::SetBufferIO} +\membersection{wxStreamBuffer::Seek}\label{wxstreambufferseek} + +\func{off\_t}{Seek}{\param{off\_t }{pos}, \param{wxSeekMode }{mode}} -\func{void}{SetBufferIO}{\param{char *}{ buffer\_start}, \param{char *}{ buffer\_end}} +Changes the current position. + +{\it mode} may be one of the following: + +\twocolwidtha{5cm} +\begin{twocollist}\itemsep=0pt +\twocolitem{{\bf wxFromStart}}{The position is counted from the start of the stream.} +\twocolitem{{\bf wxFromCurrent}}{The position is counted from the current position of the stream.} +\twocolitem{{\bf wxFromEnd}}{The position is counted from the end of the stream.} +\end{twocollist} + +\wxheading{Return value} + +Upon successful completion, it returns the new offset as measured in bytes from +the beginning of the stream. Otherwise, it returns wxInvalidOffset. + + +\membersection{wxStreamBuffer::SetBufferIO}\label{wxstreambuffersetbufferio} + +\func{void}{SetBufferIO}{\param{char*}{ buffer\_start}, \param{char*}{ buffer\_end}} Specifies which pointers to use for stream buffering. You need to pass a pointer on the -start of the buffer end and another on the end. +start of the buffer end and another on the end. The object will use this buffer +to cache stream data. It may be used also as a source/destination buffer when +you create an empty stream buffer (See \helpref{wxStreamBuffer::wxStreamBuffer}{wxstreambufferctor}). -\membersection{wxStreamBuffer::SetBufferIO} +\wxheading{Remarks} -\func{void}{SetBufferIO}{\param{size\_t}{ bufsize}} +When you use this function, you will have to destroy the IO buffers yourself +after the stream buffer is destroyed or don't use it anymore. +In the case you use it with an empty buffer, the stream buffer will not resize +it when it is full. -Changes the size of the current IO buffer. +\wxheading{See also} -\membersection{wxStreamBuffer::GetBufferStart} +\helpref{wxStreamBuffer constructor}{wxstreambufferctor}\\ +\helpref{wxStreamBuffer::Fixed}{wxstreambufferfixed}\\ +\helpref{wxStreamBuffer::Flushable}{wxstreambufferflushable} -\constfunc{char *}{GetBufferStart}{\void} +\func{void}{SetBufferIO}{\param{size\_t}{ bufsize}} -Returns a pointer on the start of the stream buffer. +Destroys or invalidates the previous IO buffer and allocates a new one of the +specified size. -\membersection{wxStreamBuffer::GetBufferEnd} +\wxheading{Warning} -\constfunc{char *}{GetBufferEnd}{\void} +All previous pointers aren't valid anymore. -Returns a pointer on the end of the stream buffer. +\wxheading{Remark} -\membersection{wxStreamBuffer::GetBufferPos} +The created IO buffer is growable by the object. -\constfunc{char *}{GetBufferPos}{\void} +\wxheading{See also} -Returns a pointer on the current position of the stream buffer. +\helpref{wxStreamBuffer::Fixed}{wxstreambufferfixed}\\ +\helpref{wxStreamBuffer::Flushable}{wxstreambufferflushable} -\membersection{wxStreamBuffer::GetIntPosition} -\constfunc{off\_t}{GetIntPosition}{\void} +\membersection{wxStreamBuffer::SetIntPosition}\label{wxstreambuffersetintposition} -Returns the current position in the stream buffer. +\func{void}{SetIntPosition}{\param{size\_t}{ pos}} -\membersection{wxStreamBuffer::SetIntPosition} +Sets the current position (in bytes) in the stream buffer. -\func{void}{SetIntPosition}{\void} +\wxheading{Warning} -Sets the current position in the stream buffer. +Since it is a very low-level function, there is no check on the position: +specifying an invalid position can induce unexpected results. -\membersection{wxStreamBuffer::GetLastAccess} -\constfunc{size\_t}{GetLastAccess}{\void} +\membersection{wxStreamBuffer::Stream}\label{wxstreambufferstream} -Returns the amount of bytes read during the last IO call to the parent stream. +\func{wxStreamBase*}{Stream}{\void} -\membersection{wxStreamBuffer::Fixed} +Returns the parent stream of the stream buffer. -\func{void}{Fixed}{\param{bool}{ fixed}} -Toggles the fixed flag. Usually this flag is toggled at the same time as -\it{flushable}. This flag allows (when it is FALSE) or forbids (when it is TRUE) -the stream buffer to resize dynamically the IO buffer. +\membersection{wxStreamBuffer::Tell}\label{wxstreambuffertell} -\membersection{wxStreamBuffer::Flushable} +\constfunc{off\_t}{Tell}{\void} -\func{void}{Flushable}{\param{bool}{ flushable}} +Gets the current position in the stream. This position is calculated from +the {\it real} position in the stream and from the internal buffer position: so +it gives you the position in the {\it real} stream counted from the start of +the stream. -Toggles the flushable flag. If \it{flushable} is disabled, no datas are sent -to the parent stream. +\wxheading{Return value} -\membersection{wxStreamBuffer::FlushBuffer} +Returns the current position in the stream if possible, wxInvalidOffset in the +other case. -\func{bool}{FlushBuffer}{\void} -Flushes the IO buffer. +\membersection{wxStreamBuffer::Truncate}\label{wxstreambuffertruncate} -\membersection{wxStreamBuffer::FillBuffer} +\func{void}{Truncate}{\void} -\func{bool}{FillBuffer}{\void} +Truncates the buffer to the current position. -Fill the IO buffer. +Note: Truncate() cannot be used to enlarge the buffer. This is +usually not needed since the buffer expands automatically. -\membersection{wxStreamBuffer::GetDataLeft} -\func{size\_t}{GetDataLeft}{\void} +\membersection{wxStreamBuffer::Write}\label{wxstreambufferwrite} -Returns the amount of available datas in the buffer. +\func{size\_t}{Write}{\param{const void *}{buffer}, \param{size\_t }{size}} -% -------------- -% Administration -% -------------- -\membersection{wxStreamBuffer::Stream} +Writes a block of the specified {\it size} using data of {\it buffer}. The data +are cached in a buffer before being sent in one block to the stream. -\func{wxStreamBase *}{Stream}{\void} +\func{size\_t}{Write}{\param{wxStreamBuffer *}{buffer}} -Returns the stream parent of the stream buffer. +See \helpref{Read}{wxstreambufferread}.