X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/9d33840bab4e10d701dd36f9b8660f6a13f05afe..7344108e8a129a3f9b4df5ab0f98a1713db03b89:/interface/wx/stream.h diff --git a/interface/wx/stream.h b/interface/wx/stream.h index 6398891aa7..6fd27a4126 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. @@ -562,7 +608,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). @@ -586,6 +632,11 @@ public: /** 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 +647,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 +687,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; }; @@ -802,7 +855,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 +885,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 +1066,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); + //@} +};