libretro/scummvm
1
0
Fork 0
mirror of https://github.com/libretro/scummvm.git synced 2024-12-11 19:54:03 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

COMMON: Document that Stream API is meant to imitate ISO C FILE semantics

Browse Source
This commit is contained in:
Max Horn 2011-05-18 13:06:41 +02:00
parent 39ab4a2dc4
commit 904739cc00
1 changed files with 24 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
common/stream.h
View File

@ -42,12 +42,18 @@ public:
* Returns true if an I/O failure occurred.
* This flag is never cleared automatically. In order to clear it,
* client code has to call clearErr() explicitly.
*
* @note The semantics of any implementation of this method are
* supposed to match those of ISO C ferror().
*/
virtual bool err() const { return false; }
/**
* Reset the I/O error status as returned by err().
* For a ReadStream, also reset the end-of-stream status returned by eos().
*
* @note The semantics of any implementation of this method are
* supposed to match those of ISO C clearerr().
*/
virtual void clearErr() {}
};
@ -61,6 +67,9 @@ public:
* Write data into the stream. Subclasses must implement this
* method; all other write methods are implemented using it.
*
* @note The semantics of any implementation of this method are
* supposed to match those of ISO C fwrite().
*
* @param dataPtr pointer to the data to be written
* @param dataSize number of bytes to be written
* @return the number of bytes which were actually written.
@ -72,6 +81,9 @@ public:
* storage medium; unbuffered streams can use the default
* implementation.
*
* @note The semantics of any implementation of this method are
* supposed to match those of ISO C fflush().
*
* @return true on success, false in case of a failure
*/
virtual bool flush() { return true; }
@ -155,6 +167,11 @@ public:
* Returns true if a read failed because the stream end has been reached.
* This flag is cleared by clearErr().
* For a SeekableReadStream, it is also cleared by a successful seek.
*
* @note The semantics of any implementation of this method are
* supposed to match those of ISO C feof(). In particular, in a stream
* with N bytes, reading exactly N bytes from the start should *not*
* set eos; only reading *beyond* the available data should set it.
*/
virtual bool eos() const = 0;
@ -162,6 +179,10 @@ public:
* Read data from the stream. Subclasses must implement this
* method; all other read methods are implemented using it.
*
* @note The semantics of any implementation of this method are
* supposed to match those of ISO C fread(), in particular where
* it concerns setting error and end of file/stream flags.
*
* @param dataPtr pointer to a buffer into which the data is read
* @param dataSize number of bytes to be read
* @return the number of bytes which were actually read.
@ -335,6 +356,9 @@ public:
* position indicator, or end-of-file, respectively. A successful call
* to the seek() method clears the end-of-file indicator for the stream.
*
* @note The semantics of any implementation of this method are
* supposed to match those of ISO C fseek().
*
* @param offset the relative offset in bytes
* @param whence the seek reference: SEEK_SET, SEEK_CUR, or SEEK_END
* @return true on success, false in case of a failure