X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/c977fa847c49b28aef4f8881660bad0775401763..e5794f50e7b2c1c0a97d9c6d3fddb78504d077e8:/interface/wx/stream.h diff --git a/interface/wx/stream.h b/interface/wx/stream.h index d452e2fe54..0d7511ce44 100644 --- a/interface/wx/stream.h +++ b/interface/wx/stream.h @@ -32,7 +32,7 @@ public: /** Destructor. */ - ~wxCountingOutputStream(); + virtual ~wxCountingOutputStream(); /** Returns the current size of the stream. @@ -60,12 +60,34 @@ class wxBufferedInputStream : public wxFilterInputStream { public: /** - Constructor. - If a non @NULL buffer is given to the stream, it will be deleted by it. + Constructor using the provided buffer or default. + + @param stream + The associated low-level stream. + @param buffer + The buffer to use if non-@NULL. Notice that the ownership of this + buffer is taken by the stream, i.e. it will delete it. If this + parameter is @NULL a default 1KB buffer is used. */ wxBufferedInputStream(wxInputStream& stream, wxStreamBuffer *buffer = NULL); + /** + Constructor allowing to specify the size of the buffer. + + This is just a more convenient alternative to creating a wxStreamBuffer + of the given size and using the other overloaded constructor of this + class. + + @param stream + The associated low-level stream. + @param bufsize + The size of the buffer, in bytes. + + @since 2.9.0 + */ + wxBufferedInputStream(wxInputStream& stream, size_t bufsize); + /** Destructor. */ @@ -77,12 +99,16 @@ public: /** @class wxStreamBuffer - @todo WRITE A DESCRIPTION + wxStreamBuffer is a cache manager for wxStreamBase: it manages a stream buffer + linked to a stream. + + Each stream always has one autoinitialized stream buffer, but you may + attach more of them to the same stream. @library{wxbase} @category{streams} - @see wxStreamBase + @see wxStreamBase, @ref overview_stream */ class wxStreamBuffer { @@ -105,16 +131,39 @@ public: @code streambuffer.Read(...); - streambuffer2.Read(...); // This call erases previous error messages set by 'streambuffer' + streambuffer2.Read(...); + // This call erases previous error messages set by 'streambuffer' + // assuming that both instances are stream buffers for the same stream @endcode @see SetBufferIO() */ wxStreamBuffer(wxStreamBase& stream, BufMode mode); + /** + Constructor for an input buffer of the specified size. + + Using it is equivalent to using the constructor above with read mode + and calling SetBufferIO() but is more convenient. + + @since 2.9.0 + */ + wxStreamBuffer(wxInputStream& stream, size_t bufsize); + + /** + Constructor for an output buffer of the specified size. + + Using it is equivalent to using the constructor above with write mode + and calling SetBufferIO() but is more convenient. + + @since 2.9.0 + */ + wxStreamBuffer(wxOutputStream& stream, size_t bufsize); + /** Constructor; creates a new empty stream buffer which won't flush any data to a stream. 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 @@ -129,7 +178,9 @@ public: wxStreamBuffer(BufMode mode); /** - Constructor. It initializes the stream buffer with the data of the specified + Copy constructor. + + This method initializes the stream buffer with the data of the specified stream buffer. The new stream buffer has the same attributes, size, position and they share the same buffer. This will cause problems if the stream to which the stream buffer belong is destroyed and the newly cloned stream @@ -199,7 +250,7 @@ public: @see Read() */ - char GetChar(); + virtual char GetChar(); /** Returns the amount of available data in the buffer. @@ -209,7 +260,7 @@ public: /** Returns the current position (counted in bytes) in the stream buffer. */ - off_t GetIntPosition() const; + size_t GetIntPosition() const; /** Returns the amount of bytes read during the last IO call to the parent stream. @@ -224,7 +275,7 @@ public: @see Read() */ - void PutChar(char c); + virtual void PutChar(char c); /** Reads a block of the specified size and stores the data in buffer. @@ -236,7 +287,7 @@ public: different of the specified size, an error has occurred and should be tested using GetLastError(). */ - size_t Read(void* buffer, size_t size); + virtual size_t Read(void* buffer, size_t size); /** Copies data to @a buffer. @@ -245,7 +296,7 @@ public: @see Write() */ - Return value size_t Read(wxStreamBuffer* buffer); + size_t Read(wxStreamBuffer* buffer); /** Resets to the initial state variables concerning the buffer. @@ -264,7 +315,7 @@ public: measured in bytes from the beginning of the stream. Otherwise, it returns wxInvalidOffset. */ - off_t Seek(off_t pos, wxSeekMode mode); + virtual wxFileOffset Seek(wxFileOffset pos, wxSeekMode mode); /** Specifies which pointers to use for stream buffering. @@ -281,7 +332,7 @@ public: @see wxStreamBuffer(), Fixed(), Flushable() */ - void SetBufferIO(char* buffer_start, char* buffer_end); + void SetBufferIO(void* start, void* end, bool takeOwnership = false); /** Destroys or invalidates the previous IO buffer and allocates a new one of the @@ -308,6 +359,7 @@ public: /** Returns the parent stream of the stream buffer. + @deprecated use GetStream() instead */ wxStreamBase* Stream(); @@ -320,7 +372,7 @@ public: @return Returns the current position in the stream if possible, wxInvalidOffset in the other case. */ - off_t Tell() const; + virtual wxFileOffset Tell() const; /** Truncates the buffer to the current position. @@ -334,7 +386,7 @@ public: Writes a block of the specified size using data of buffer. The data are cached in a buffer before being sent in one block to the stream. */ - size_t Write(const void* buffer, size_t size); + virtual size_t Write(const void* buffer, size_t size); /** See Read(). @@ -363,7 +415,7 @@ public: /** Destructor. */ - ~wxOutputStream(); + virtual ~wxOutputStream(); /** Closes the stream, returning @false if an error occurs. @@ -374,14 +426,14 @@ public: as a file, then the underlying resource is closed too if it is owned by this stream, or left open otherwise. */ - bool Close(); + virtual bool Close(); /** Returns the number of bytes written during the last Write(). It may return 0 even if there is no error on the stream if it is only temporarily impossible to write to it. */ - size_t LastWrite() const; + virtual size_t LastWrite() const; /** Puts the specified character in the output queue and increments the @@ -399,12 +451,12 @@ public: @return The new stream position or wxInvalidOffset on error. */ - off_t SeekO(off_t pos, wxSeekMode mode = wxFromStart); + virtual wxFileOffset SeekO(wxFileOffset pos, wxSeekMode mode = wxFromStart); /** Returns the current stream position. */ - off_t TellO() const; + virtual wxFileOffset TellO() const; /** Writes up to the specified amount of bytes using the data of buffer. @@ -417,14 +469,14 @@ public: This function returns a reference on the current object, so the user can test any states of the stream right away. */ - wxOutputStream Write(const void* buffer, size_t size); + virtual wxOutputStream& Write(const void* buffer, size_t size); /** Reads data from the specified input stream and stores them in the current stream. The data is read until an error is raised by one of the two streams. */ - wxOutputStream Write(wxInputStream& stream_in); + wxOutputStream& Write(wxInputStream& stream_in); }; @@ -450,7 +502,7 @@ enum wxStreamProtocolType handle it and create a stream to decompress it: @code - factory = wxFilterClassFactory::Find(filename, wxSTREAM_FILEEXT); + factory = wxFilterClassFactory::Find(filename, wxSTREAM_FILEEXT); if (factory) stream = factory-NewStream(new wxFFileInputStream(filename)); @endcode @@ -534,7 +586,7 @@ public: list << *p << _T("\n"); @endcode */ - const wxChar* const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL) const; + virtual const wxChar * const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL) const = 0; //@{ /** @@ -667,25 +719,48 @@ class wxBufferedOutputStream : public wxFilterOutputStream { public: /** - Creates a buffered stream using a buffer of a default size of 1024 bytes for - cashing the stream @a parent. + Constructor using the provided buffer or default. + + @param stream + The associated low-level stream. + @param buffer + The buffer to use if non-@NULL. Notice that the ownership of this + buffer is taken by the stream, i.e. it will delete it. If this + parameter is @NULL a default 1KB buffer is used. */ - wxBufferedOutputStream(const wxOutputStream& parent); + wxBufferedOutputStream(wxOutputStream& stream, + wxStreamBuffer *buffer = NULL); + + /** + Constructor allowing to specify the size of the buffer. + + This is just a more convenient alternative to creating a wxStreamBuffer + of the given size and using the other overloaded constructor of this + class. + + @param stream + The associated low-level stream. + @param bufsize + The size of the buffer, in bytes. + + @since 2.9.0 + */ + wxBufferedOutputStream(wxOutputStream& stream, size_t bufsize); /** Destructor. Calls Sync() and destroys the internal buffer. */ - ~wxBufferedOutputStream(); + virtual ~wxBufferedOutputStream(); /** Calls Sync() and changes the stream position. */ - off_t SeekO(off_t pos, wxSeekMode mode); + virtual wxFileOffset SeekO(wxFileOffset pos, wxSeekMode mode = wxFromStart); /** Flushes the buffer and calls Sync() on the parent stream. */ - void Sync(); + virtual void Sync(); }; @@ -709,35 +784,37 @@ public: /** Destructor. */ - ~wxInputStream(); + virtual ~wxInputStream(); /** Returns @true if some data is available in the stream right now, so that calling Read() wouldn't block. */ - bool CanRead() const; + virtual bool CanRead() const; /** Returns @true after an attempt has been made to read past the end of the stream. */ - bool Eof() const; + virtual bool Eof() const; /** Returns the first character in the input queue and removes it, blocking until it appears if necessary. + + On success returns a value between 0 - 255; on end of file returns @c wxEOF. */ - char GetC(); + int GetC(); /** Returns the last number of bytes read. */ - size_t LastRead() const; + virtual size_t LastRead() const; /** Returns the first character in the input queue without removing it. */ - char Peek(); + virtual char Peek(); /** Reads the specified amount of bytes and stores the data in buffer. @@ -748,7 +825,7 @@ public: @return This function returns a reference on the current object, so the user can test any states of the stream right away. */ - wxInputStream Read(void* buffer, size_t size); + virtual wxInputStream& Read(void* buffer, size_t size); /** Reads data from the input queue and stores it in the specified output stream. @@ -769,12 +846,12 @@ public: @return The new stream position or wxInvalidOffset on error. */ - off_t SeekI(off_t pos, wxSeekMode mode = wxFromStart); + virtual wxFileOffset SeekI(wxFileOffset pos, wxSeekMode mode = wxFromStart); /** Returns the current stream position. */ - off_t TellI() const; + virtual wxFileOffset TellI() const; /** This function is only useful in read mode. @@ -792,13 +869,13 @@ public: @return Returns the amount of bytes saved in the Write-Back buffer. */ - size_t Ungetch(const char* buffer, size_t size); + size_t Ungetch(const void* buffer, size_t size); /** This function acts like the previous one except that it takes only one character: it is sometimes shorter to use than the generic function. */ - Return value bool Ungetch(char c); + bool Ungetch(char c); }; @@ -836,7 +913,7 @@ public: /** Destructor. */ - ~wxStreamBase(); + virtual ~wxStreamBase(); /** This function returns the last error. @@ -850,7 +927,7 @@ public: @since 2.5.4 */ - wxFileOffset GetLength() const; + virtual wxFileOffset GetLength() const; /** This function returns the size of the stream. @@ -861,7 +938,7 @@ public: streams. In that cases, GetSize returns 0 so you should always test its return value. */ - size_t GetSize() const; + virtual size_t GetSize() const; /** Returns @true if no error occurred on the stream. @@ -873,7 +950,7 @@ public: /** Returns @true if the streams supports seeking to arbitrary offsets. */ - bool IsSeekable() const; + virtual bool IsSeekable() const; /** Internal function. It is called when the stream wants to read data of the @@ -882,20 +959,23 @@ public: size_t OnSysRead(void* buffer, size_t bufsize); /** - Internal function. - It is called when the stream needs to change the current position. + See OnSysRead(). */ - off_t OnSysSeek(off_t pos, wxSeekMode mode); + size_t OnSysWrite(const void* buffer, size_t bufsize); + + +protected: /** Internal function. - It is called when the stream needs to know the real position. + It is called when the stream needs to change the current position. */ - off_t OnSysTell() const; + virtual wxFileOffset OnSysSeek(wxFileOffset pos, wxSeekMode mode); /** - See OnSysRead(). + Internal function. + It is called when the stream needs to know the real position. */ - size_t OnSysWrite(const void* buffer, size_t bufsize); + virtual wxFileOffset OnSysTell() const; };