X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7da420943efcbf51634e043b082f0e5798c0f8e5..42e69d6b435a4dd5415caf3750db62cf45b6f373:/docs/latex/wx/stream.tex diff --git a/docs/latex/wx/stream.tex b/docs/latex/wx/stream.tex index e464875640..20cf2e72d2 100644 --- a/docs/latex/wx/stream.tex +++ b/docs/latex/wx/stream.tex @@ -1,188 +1,351 @@ -\section{\class{wxStreamBuffer}}\label{wxstreambuf} +\section{\class{wxStreamBuffer}}\label{wxstreambuffer} + +\wxheading{Derived from} + +None + +\wxheading{Include files} + + \wxheading{See also} + \helpref{wxStreamBase}{wxstreambase} % --------------------------------------------------------------------------- % Members % --------------------------------------------------------------------------- - \latexignore{\rtfignore{\wxheading{Members}}} % ----------- % ctor & dtor % ----------- +\membersection{wxStreamBuffer::wxStreamBuffer}\label{wxstreambufconst} -\membersection{wxStreamBuffer::wxStreamBuffer} -\func{}{wxStreamBuffer}{\param{wxStreamBase&}{ stream}, \param{BufMode}{ mode}} +\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, -wxStreamBuffer::write, wxStreamBuffer::read_write. +wxStreamBuffer::write, wxStreamBuffer::read\_write. +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. + +\wxheading{Warning} + +All errors and messages linked to the stream are stored in the stream object. +\begin{verbatim} + streambuffer.Read(...); + streambuffer2.Read(...); /* This one erases previous error messages set by + ``streambuffer'' */ +\end{verbatim} -\membersection{wxStreamBuffer::wxStreamBuffer} \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. + +\wxheading{Warning} + +The "read\_write" mode may not work: it isn't completely finished. +You can create "memory" streams by this way: + +\begin{verbatim} + wxStreamBuffer *sb = new wxStreamBuffer(wxStreamBuffer::read) + wxInputStream *input = new wxInputStream(sb); -\membersection{wxStreamBuffer::wxStreamBuffer} -\func{}{wxStreamBuffer}{\param{const wxStreamBase&}{ buffer}} + sb->Fixed(FALSE); // It can change the size of the buffer. -Constructor, creates a new stream buffer from the specified stream \it{buffer}. + // input is now a read-only memory stream. +\end{verbatim} -\membersection{wxStreamBuffer::~wxStreamBuffer} -\func{}{\destruct{wxStreamBuffer}} +But you should take care when destroying the stream buffer yourself. -Destructor, destroys the stream buffer. +\func{}{wxStreamBuffer}{\param{const wxStreamBuffer\&}{buffer}} + +Constructor. It initializes the stream buffer with the data of the specified +stream buffer. The new stream buffer is nearly exactly the same as the +original: it has the same attributes, the same size, the same position, shares +the same internal buffer. The interresting point is that they can differ +in the future but the root is the same. + +\wxheading{Warning} + +The fact that the two stream buffers shared the same buffer could generate +segmentation violation if the parent is destroyed and the children continues +operating. It is advised to use this feature only in very local area of the +program. + +\wxheading{See also} + +\helpref{wxStreamBuffer:SetBufferIO}{wxstreambuffersetbufferio} + +\membersection{wxStreamBuffer::\destruct{wxStreamBuffer}} + +\func{}{wxStreamBuffer}{\destruct{wxStreamBuffer}} + +Destructor. It finalizes all IO calls and frees all internal buffers if +necessary. In the case of a children stream buffer, the internal buffer isn't +freed, this is the job of the parent. +The "Write-Back" buffer is freed. % ----------- % Filtered IO % ----------- +\membersection{wxStreamBuffer::Read}\label{wxstreambufferread} -\membersection{wxStreamBuffer::Read}\label{wxstreambufread} -\func{size_t}{Read}{\param{void *}{buffer}, \param{size_t }{size}} +\func{size\_t}{Read}{\param{void *}{buffer}, \param{size\_t }{size}} Reads a block of the specified \it{size} and stores datas in \it{buffer}. +This function uses also the "Write-Back" buffer: in the case there are datas +waiting in this buffer, they are used before anything else. After that, if there +are still datas to be read, the stream is read and the stream buffer position +is incremented. \wxheading{Return value} -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}. +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{LastError}{wxstreambaselasterror}. + +\wxheading{See also} + +\helpref{wxStreamBuffer::WriteBack}{wxstreambufferwriteback} -\membersection{wxStreamBuffer::Read}\label{wxstreambufreadbuf} -\func{size_t}{Read}{\param{wxStreamBuffer *}{buffer}} +\func{size\_t}{Read}{\param{wxStreamBuffer *}{buffer}} Reads a \it{buffer}. The function returns when \it{buffer} is full or when there aren't datas anymore in the current buffer. -\membersection{wxStreamBuffer::Write} -\func{size_t}{Write}{\param{const void *}{buffer}, \param{size_t }{size}} +\membersection{wxStreamBuffer::Write}\label{wxstreambufferwrite} + +\func{size\_t}{Write}{\param{const void *}{buffer}, \param{size\_t }{size}} -Writes a block of the specified \it{size} using datas of \it{buffer}. +Writes a block of the specified \it{size} using datas of \it{buffer}. The datas +are cached in a buffer before being sent in one block to the stream. -\membersection{wxStreamBuffer::Write} -\func{size_t}{Write}{\param{wxStreamBuffer *}{buffer}} +\func{size\_t}{Write}{\param{wxStreamBuffer *}{buffer}} -See \helpref{Read}{wxstreambufreadbuf} +See \helpref{Read}{wxstreambufferread}. -\membersection{wxStreamBuffer::WriteBack} -\func{size_t}{WriteBack}{\param{const char *}{buffer}, \param{size_t}{ size}} +\membersection{wxStreamBuffer::WriteBack}\label{wxstreambufferwriteback} -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. +\func{size\_t}{WriteBack}{\param{const char*}{ buffer}, \param{size\_t}{ size}} + +This function is only useful in \it{read} mode. It is the manager of the "Write-Back" +buffer. This buffer acts like a temporary buffer where datas which has to be +read during the next read IO call are put. This is useful when you get a big +block of data which you didn't want to read: you can replace them at the top +of the input queue by this way. + +\wxheading{Return value} -\membersection{wxStreamBuffer::WriteBack} -\func{size_t}{WriteBack}{\param{char }{c}} +Returns the amount of bytes saved in the Write-Back buffer. -As for the previous function, it puts the specified byte in the input queue of the -stream buffer. +\func{size\_t}{WriteBack}{\param{char }{c}} + +This function acts like the previous one except that it takes only one +character: it is sometimes shorter to use than the generic function. \membersection{wxStreamBuffer::GetChar} + \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 occured during the IO call. + +\wxheading{See also} + +\helpref{wxStreamBuffer::Read}{wxstreambufferread} \membersection{wxStreamBuffer::PutChar} + \func{void}{PutChar}{\param{char }{c}} Puts a single char to the stream buffer. +\wxheading{Problem} + +You aren't directly notified if an error occured during the IO call. + +\wxheading{See also} + +\helpref{wxStreamBuffer::Read}{wxstreambufferwrite} + \membersection{wxStreamBuffer::Tell} -\constfunc{off_t}{Tell}{\void} -Gets the current position in the \it{stream}. +\constfunc{off\_t}{Tell}{\void} -\membersection{wxStreamBuffer::Seek} -\func{off_t}{Seek}{\param{off_t }{pos}, \param{wxSeekMode }{mode}} +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. + +\wxheading{Return value} -Changes the current position. (TODO) +Returns the current position in the stream if possible, wxInvalidOffset in the +other case. + +\membersection{wxStreamBuffer::Seek}\label{wxstreambufferseek} + +\func{off\_t}{Seek}{\param{off\_t }{pos}, \param{wxSeekMode }{mode}} + +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. % -------------- % Buffer control % -------------- - \membersection{wxStreamBuffer::ResetBuffer} + \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} - \func{void}{SetBufferIO}{\param{char *}{ buffer_start}, \param{char *}{ buffer_end}} +\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}{wxstreambufconst}). + +\wxheading{Remarks} -\membersection{wxStreamBuffer::SetBufferIO} -\func{void}{SetBufferIO}{\param{size_t}{ bufsize}} +When you use this function, you'll 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 grow +it when it is full. -Changes the size of the current IO buffer. +\wxheading{See also} + +\helpref{wxStreamBuffer constructor}{wxstreambufconst}\\ +\helpref{wxStreamBuffer::Fixed}{wxstreambufferfixed}\\ +\helpref{wxStreamBuffer::Flushable}{wxstreambufferflushable} + +\func{void}{SetBufferIO}{\param{size\_t}{ bufsize}} + +Destroys or invalidates the previous IO buffer and allocates a new one of the +specified size. + +\wxheading{Warning} + +All previous pointers aren't valid anymore. + +\wxheading{Remark} + +The created IO buffer is growable by the object. + +\wxheading{See also} + +\helpref{wxStreamBuffer::Fixed}{wxstreambufferfixed}\\ +\helpref{wxStreamBuffer::Flushable}{wxstreambufferflushable} \membersection{wxStreamBuffer::GetBufferStart} + \constfunc{char *}{GetBufferStart}{\void} Returns a pointer on the start of the stream buffer. \membersection{wxStreamBuffer::GetBufferEnd} + \constfunc{char *}{GetBufferEnd}{\void} Returns a pointer on the end of the stream buffer. \membersection{wxStreamBuffer::GetBufferPos} + \constfunc{char *}{GetBufferPos}{\void} Returns a pointer on the current position of the stream buffer. \membersection{wxStreamBuffer::GetIntPosition} -\constfunc{off_t}{GetIntPosition}{\void} -Returns the current position in the stream buffer. +\constfunc{off\_t}{GetIntPosition}{\void} + +Returns the current position (counted in bytes) in the stream buffer. \membersection{wxStreamBuffer::SetIntPosition} + \func{void}{SetIntPosition}{\void} -Sets the current position in the stream buffer. +Sets the current position (in bytes) in the stream buffer. + +\wxheading{Warning} + +Since it is a very low-level function, there is no check on the position: +specify an invalid position can induce unexpected results. \membersection{wxStreamBuffer::GetLastAccess} -\constfunc{size_t}{GetLastAccess}{\void} + +\constfunc{size\_t}{GetLastAccess}{\void} Returns the amount of bytes read during the last IO call to the parent stream. -\membersection{wxStreamBuffer::Fixed} +\membersection{wxStreamBuffer::Fixed}\label{wxstreambufferfixed} + \func{void}{Fixed}{\param{bool}{ fixed}} -Toggles the fixed flag. Usually this flag is toggled at the same time that -\it{flushable}. This flag allows (when it is false) or not (when it is true) -the stream buffer to resize dynamically the IO buffer. +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. + +\wxheading{See also} + +\helpref{wxStreamBuffer::SetBufferIO}{wxstreambuffersetbufferio} + +\membersection{wxStreamBuffer::Flushable}\label{wxstreambufferflushable} -\membersection{wxStreamBuffer::Flushable} \func{void}{Flushable}{\param{bool}{ flushable}} Toggles the flushable flag. If \it{flushable} is disabled, no datas are sent to the parent stream. \membersection{wxStreamBuffer::FlushBuffer} + \func{bool}{FlushBuffer}{\void} Flushes the IO buffer. \membersection{wxStreamBuffer::FillBuffer} + \func{bool}{FillBuffer}{\void} Fill the IO buffer. \membersection{wxStreamBuffer::GetDataLeft} -\func{size_t}{GetDataLeft}{\void} + +\func{size\_t}{GetDataLeft}{\void} Returns the amount of available datas in the buffer. % -------------- % Administration % -------------- - \membersection{wxStreamBuffer::Stream} -\func{wxStreamBase *}{Stream}{\void} -Returns the stream parent of the stream buffer. +\func{wxStreamBase*}{Stream}{\void} + +Returns the parent stream of the stream buffer. +