// Name: stream.h
// Purpose: interface of wxStreamBase and its derived classes
// Author: wxWidgets team
-// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
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:
/**
class wxStreamBuffer
{
public:
+ /** BufMode flags */
+ enum BufMode
+ {
+ read,
+ write,
+ read_write
+ };
/**
Constructor, creates a new stream buffer using @a stream as a parent stream
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.
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
Destructor.
It finalizes all IO calls and frees all internal buffers if necessary.
*/
- wxStreamBuffer();
+ ~wxStreamBuffer();
/**
Fill the IO buffer.
*/
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
/**
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).
*/
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
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;
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;
};
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;
};
const wxFilterClassFactory *factory = wxFilterClassFactory::GetFirst();
while (factory) {
- list << factory->GetProtocol() << _T("\n");
+ list << factory->GetProtocol() << wxT("\n");
factory = factory->GetNext();
}
@endcode
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;
};
+/**
+ @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);
+ //@}
+};
projects / wxWidgets.git / blobdiff