X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/9d33840bab4e10d701dd36f9b8660f6a13f05afe..1b7751aaa9a86d76a850b9267bc0c201e3cea30f:/interface/wx/stream.h diff --git a/interface/wx/stream.h b/interface/wx/stream.h index 6398891aa7..51b983dd8a 100644 --- a/interface/wx/stream.h +++ b/interface/wx/stream.h @@ -3,7 +3,7 @@ // Purpose: interface of wxStreamBase and its derived classes // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// @@ -76,10 +76,39 @@ public: virtual bool IsOk() const; /** - Returns @true if the streams supports seeking to arbitrary offsets. + Returns @true if the stream supports seeking to arbitrary offsets. */ virtual bool IsSeekable() const; + /** + Resets the stream state. + + By default, resets the stream to good state, i.e. clears any errors. + Since wxWidgets 2.9.3 can be also used to explicitly set the state to + the specified error (the @a error argument didn't exist in the previous + versions). + + @see GetLastError() + */ + void Reset(wxStreamError error = wxSTREAM_NO_ERROR); + + /** + Returns the opposite of IsOk(). + You can use this function to test the validity of the stream as if + it was a pointer: + + @code + bool DoSomething(wxInputStream& stream) + { + wxInt32 data; + if (!stream.Read(&data, 4)) + return false; + ... + } + @endcode + */ + bool operator!() const; + protected: /** @@ -121,6 +150,13 @@ protected: class wxStreamBuffer { public: + /** BufMode flags */ + enum BufMode + { + read, + write, + read_write + }; /** Constructor, creates a new stream buffer using @a stream as a parent stream @@ -155,8 +191,13 @@ public: and calling SetBufferIO() but is more convenient. @since 2.9.0 + + @param bufsize + The size of buffer in bytes. + @param stream + The associated input stream, the buffer will be used in read mode. */ - wxStreamBuffer(wxInputStream& stream, size_t bufsize); + wxStreamBuffer(size_t bufsize, wxInputStream& stream); /** Constructor for an output buffer of the specified size. @@ -165,8 +206,13 @@ public: and calling SetBufferIO() but is more convenient. @since 2.9.0 + + @param bufsize + The size of buffer in bytes. + @param stream + The associated output stream, the buffer will be used in write mode. */ - wxStreamBuffer(wxOutputStream& stream, size_t bufsize); + wxStreamBuffer(size_t bufsize, wxOutputStream& stream); /** Constructor; creates a new empty stream buffer which won't flush any data @@ -202,7 +248,7 @@ public: Destructor. It finalizes all IO calls and frees all internal buffers if necessary. */ - wxStreamBuffer(); + ~wxStreamBuffer(); /** Fill the IO buffer. @@ -491,6 +537,20 @@ public: */ wxOutputStream& Write(wxInputStream& stream_in); + /** + Writes exactly the specified number of bytes from the buffer. + + Returns @true if exactly @a size bytes were written. Otherwise, returns + @false and LastWrite() should be used to retrieve the exact amount of + the data written if necessary. + + This method uses repeated calls to Write() (which may return writing + only part of the data) if necessary. + + @since 2.9.5 + */ + bool WriteAll(const void* buffer, size_t size); + protected: /** Internal function. It is called when the stream wants to write data of the @@ -562,7 +622,7 @@ public: /** Reads the specified amount of bytes and stores the data in buffer. - To check if the call was successfull you must use LastRead() to check + To check if the call was successful you must use LastRead() to check if this call did actually read @a size bytes (if it didn't, GetLastError() should return a meaningful value). @@ -583,9 +643,31 @@ public: */ wxInputStream& Read(wxOutputStream& stream_out); + /** + Reads exactly the specified number of bytes into the buffer. + + Returns @true only if the entire amount of data was read, otherwise + @false is returned and the number of bytes really read can be retrieved + using LastRead(), as with Read(). + + This method uses repeated calls to Read() (which may return after + reading less than the requested number of bytes) if necessary. + + @warning + The buffer absolutely needs to have at least the specified size. + + @since 2.9.5 + */ + bool ReadAll(void* buffer, size_t size); + /** Changes the stream current position. + This operation in general is possible only for seekable streams + (see wxStreamBase::IsSeekable()); non-seekable streams support only + seeking positive amounts in mode @c wxFromCurrent (this is implemented + by reading data and simply discarding it). + @param pos Offset to seek to. @param mode @@ -596,7 +678,9 @@ public: virtual wxFileOffset SeekI(wxFileOffset pos, wxSeekMode mode = wxFromStart); /** - Returns the current stream position. + Returns the current stream position or ::wxInvalidOffset if it's not + available (e.g. socket streams do not have a size nor a current stream + position). */ virtual wxFileOffset TellI() const; @@ -634,7 +718,7 @@ protected: reached or an error occurred (in this last case the internal @c m_lasterror variable should be set accordingly as well). */ - size_t OnSysRead(void* buffer, size_t bufsize); + size_t OnSysRead(void* buffer, size_t bufsize) = 0; }; @@ -669,9 +753,11 @@ public: virtual ~wxCountingOutputStream(); /** - Returns the current size of the stream. + Returns the current length of the stream. + + This is the amount of data written to the stream so far, in bytes. */ - size_t GetSize() const; + virtual wxFileOffset GetLength() const; }; @@ -802,7 +888,7 @@ public: const wxFilterClassFactory *factory = wxFilterClassFactory::GetFirst(); while (factory) { - list << factory->GetProtocol() << _T("\n"); + list << factory->GetProtocol() << wxT("\n"); factory = factory->GetNext(); } @endcode @@ -832,7 +918,7 @@ public: const wxChar *const *p; for (p = factory->GetProtocols(wxSTREAM_FILEEXT); *p; p++) - list << *p << _T("\n"); + list << *p << wxT("\n"); @endcode */ virtual const wxChar * const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL) const = 0; @@ -1013,3 +1099,57 @@ public: }; +/** + @class wxWrapperInputStream + + A wrapper input stream is a kind of filter stream which forwards all the + operations to its base stream. This is useful to build utility classes such + as wxFSInputStream. + + @note + The interface of this class is the same as that of wxInputStream. + Only a constructor differs and it is documented below. + + @library{wxbase} + @category{streams} + + @see wxFSInputStream, wxFilterInputStream + @since 2.9.4 +*/ +class wxWrapperInputStream : public wxFilterInputStream +{ +public: + //@{ + /** + Initializes a wrapper stream. + + If the parent stream is passed as a pointer then the new wrapper stream + takes ownership of it. If it is passed by reference then it does not. + */ + wxWrapperInputStream(wxInputStream& stream); + wxWrapperInputStream(wxInputStream* stream); + //@} + +protected: + /** + Default constructor, use InitParentStream() to finish initialization. + + This constructor can be used by the derived classes from their own + constructors when the parent stream can't be specified immediately. + The derived class must call InitParentStream() later to do it. + */ + wxWrapperInputStream(); + + //@{ + /** + Set up the wrapped stream for an object initialized using the default + constructor. + + The ownership logic is the same as for the non-default constructor, + i.e. this object takes ownership of the stream if it's passed by + pointer but not if it's passed by reference. + */ + void InitParentStream(wxInputStream& stream); + void InitParentStream(wxInputStream* stream); + //@} +};