From 07b732709364e538ab7ccc49d8f2643d9d28b49d Mon Sep 17 00:00:00 2001 From: Guilhem Lavaux Date: Sun, 7 Feb 1999 21:12:41 +0000 Subject: [PATCH 1/1] * A few updates (stream doc) git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@1636 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/latex/wx/socket.tex | 8 ++- docs/latex/wx/stream.tex | 129 ++++++++++++++++++++++++++++++------- docs/latex/wx/strmbase.tex | 9 ++- src/common/stream.cpp | 4 ++ 4 files changed, 122 insertions(+), 28 deletions(-) diff --git a/docs/latex/wx/socket.tex b/docs/latex/wx/socket.tex index 5fb23c57d0..122bf38f64 100644 --- a/docs/latex/wx/socket.tex +++ b/docs/latex/wx/socket.tex @@ -154,7 +154,13 @@ Returns a reference to the current object. \func{void}{SetFlags}{\param{wxSockFlags}{ flags}} -TODO +\twocolwidtha{7cm} +\begin{twocollist}\itemsep=0pt +\twocolitem{{\bf wxSocketBase::NONE}}{Normal functionnalities.} +\twocolitem{{\bf wxSocketBase::NOWAIT}}{Get the available data in the input queue and exit immediately.} +\twocolitem{{\bf wxSocketBase::WAITALL}}{Wait for all required data unless an error occured.} +\twocolitem{{\bf wxSocketBase::SPEED}}{Disable the asynchronous IO functionnality.} +\end{twocollist} % % Read diff --git a/docs/latex/wx/stream.tex b/docs/latex/wx/stream.tex index 2715542ddd..641609234a 100644 --- a/docs/latex/wx/stream.tex +++ b/docs/latex/wx/stream.tex @@ -23,25 +23,59 @@ None 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. +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. -\membersection{wxStreamBuffer::wxStreamBuffer} +\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} \func{}{wxStreamBuffer}{\param{BufMode}{ mode}} 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). +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 +functionnalities of a ``normal'' stream. -\membersection{wxStreamBuffer::wxStreamBuffer} +\wxheading{Warning} + +The "read\_write" mode may not work: it isn't completely finished. + +\wxheading{See also} + +\helpref{wxStreamBuffer:SetBufferIO}{wxstreambufsetbufferio} + +\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. -\func{}{wxStreamBuffer}{\param{const wxStreamBase\&}{ buffer}} +\wxheading{Warning} -Constructor, creates a new stream buffer from the specified stream \it{buffer}. +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. \membersection{wxStreamBuffer::\destruct{wxStreamBuffer}} \func{}{wxStreamBuffer}{\destruct{wxStreamBuffer}} -Destructor, destroys the stream buffer. +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 @@ -51,6 +85,10 @@ Destructor, destroys the stream buffer. \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} @@ -58,7 +96,9 @@ 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}. -\membersection{wxStreamBuffer::Read}\label{wxstreambufreadbuf} +\wxheading{See also} + +\helpref{wxStreamBuffer::WriteBack}{wxstreambufwriteback} \func{size\_t}{Read}{\param{wxStreamBuffer *}{buffer}} @@ -69,34 +109,45 @@ when there aren't datas anymore in the current buffer. \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}. - -\membersection{wxStreamBuffer::Write} +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. \func{size\_t}{Write}{\param{wxStreamBuffer *}{buffer}} See \helpref{Read}{wxstreambufreadbuf} -\membersection{wxStreamBuffer::WriteBack} +\membersection{wxStreamBuffer::WriteBack}\label{wxstreambufwriteback} \func{size\_t}{WriteBack}{\param{const char*}{ buffer}, \param{size\_t}{ size}} -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. +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. -\membersection{wxStreamBuffer::WriteBack} +\wxheading{Return value} + +Returns the amount of bytes saved in the Write-Back buffer. \func{size\_t}{WriteBack}{\param{char }{c}} -As for the previous function, it puts the specified byte in the input queue of the -stream buffer. +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}{wxstreambufread} \membersection{wxStreamBuffer::PutChar} @@ -104,17 +155,47 @@ Gets a single char from the stream buffer. 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}{wxstreambufwrite} + \membersection{wxStreamBuffer::Tell} \constfunc{off\_t}{Tell}{\void} -Gets the current position in the \it{stream}. +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} + +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. (TODO) +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 @@ -123,17 +204,15 @@ Changes the current position. (TODO) \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::SetBufferIO}\label{wxstreambufsetbufferio} \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. -\membersection{wxStreamBuffer::SetBufferIO} - \func{void}{SetBufferIO}{\param{size\_t}{ bufsize}} Changes the size of the current IO buffer. @@ -214,5 +293,5 @@ Returns the amount of available datas in the buffer. \func{wxStreamBase*}{Stream}{\void} -Returns the stream parent of the stream buffer. +Returns the parent stream of the stream buffer. diff --git a/docs/latex/wx/strmbase.tex b/docs/latex/wx/strmbase.tex index 5902315c4e..4ff8ade705 100644 --- a/docs/latex/wx/strmbase.tex +++ b/docs/latex/wx/strmbase.tex @@ -37,8 +37,13 @@ Destructor. \constfunc{wxStreamError}{LastError}{\void} This function returns the last error. -% It is of the form: -% TODO +\twocolwidtha{5cm} +\begin{twocollist}\itemsep=0pt +\twocolitem{{\bf wxStream_NOERROR}}{No error occured.} +\twocolitem{{\bf wxStream_EOF}}{An End-Of-File occured.} +\twocolitem{{\bf wxStream_WRITE_ERR}}{A generic error occured on the last write call.} +\twocolitem{\bf wxStream_READ_ERR}{A generic error occured on the last read call.} +\end{twocollist} \membersection{wxStreamBase::StreamSize} \constfunc{size_t}{StreamSize}{\void} diff --git a/src/common/stream.cpp b/src/common/stream.cpp index 728d50b5cf..f2bb737c0d 100644 --- a/src/common/stream.cpp +++ b/src/common/stream.cpp @@ -82,6 +82,9 @@ size_t wxStreamBuffer::WriteBack(const char *buf, size_t bufsize) { char *ptrback; + if (m_mode != read) + return 0; + ptrback = AllocSpaceWBack(bufsize); if (!ptrback) return 0; @@ -137,6 +140,7 @@ void wxStreamBuffer::SetBufferIO(size_t bufsize) void wxStreamBuffer::ResetBuffer() { m_stream->m_lasterror = wxStream_NOERROR; + m_stream->m_lastcount = 0; if (m_mode == read) m_buffer_pos = m_buffer_end; else -- 2.45.2