class ByteStream

Abstract class for a stream of bytes.

Inheritance:


Public

[more] Virtual Functions.

[more]virtual ~ByteStream()
Virtual destructor.
[more]virtual size_t read(void *buffer, size_t size)
Reads data from a ByteStream.
[more]virtual size_t write(const void *buffer, size_t size)
Writes data to a ByteStream.
[more]virtual long tell(void)
Returns the offset of the current position in the ByteStream.
[more]virtual int is_seekable(void) const
Tests whether function seek can seek backwards.
[more]virtual void seek(long offset, int whence = SEEK_SET)
Sets the current position for reading or writing the ByteStream.
[more]virtual void flush()
Flushes all buffers in the ByteStream.

[more] Utility Functions.

[more]size_t readall(void *buffer, size_t size)
Reads data and blocks until everything has been read.
[more]size_t writall(const void *buffer, size_t size)
Writes data and blocks until everything has been written.
[more]size_t copy(ByteStream &bsfrom, size_t size=0)
Copy data from another ByteStream.
[more]void write8(unsigned int card8)
Writes a one-byte integer to a ByteStream.
[more]void write16(unsigned int card16)
Writes a two-bytes integer to a ByteStream.
[more]void write32(unsigned int card32)
Writes a four-bytes integer to a ByteStream.
[more]unsigned int read8()
Reads a one-byte integer from a ByteStream.
[more]unsigned int read16()
Reads a two-bytes integer from a ByteStream.
[more]unsigned int read32()
Reads a four-bytes integer from a ByteStream.


Documentation

Abstract class for a stream of bytes. Class ByteStream represent an object from which (resp. to which) bytes can be read (resp. written) as with a regular file. Virtual functions read and write must implement these two basic operations. In addition, function tell returns an offset identifying the current position, and function seek may be used to change the current position.

Note. Both the copy constructor and the copy operator are declared as private members. It is therefore not possible to make multiple copies of instances of this class, as implied by the class semantic.

o Virtual Functions.
These functions are usually implemented by each subclass of ByteStream.

ovirtual ~ByteStream()
Virtual destructor.

ovirtual size_t read(void *buffer, size_t size)
Reads data from a ByteStream. This function must be implemented by each subclass of ByteStream. At most size bytes are read from the ByteStream and stored in the memory area pointed to by buffer. Function read returns immediately if size is zero. The actual number of bytes read is returned. Function read returns a number of bytes smaller than size if the end-of-file mark is reached before filling the buffer. Subsequent invocations will always return value 0. Function read may also return a value greater than zero but smaller than size for internal reasons. Programs must be ready to handle these cases or use function readall. Exception GException is thrown with a plain text error message whenever an error occurs.

ovirtual size_t write(const void *buffer, size_t size)
Writes data to a ByteStream. This function must be implemented by each subclass of ByteStream. At most size bytes from buffer buffer are written to the ByteStream. Function write returns immediately if size is zero. The actual number of bytes written is returned. Function write may also return a value greater than zero but smaller than size for internal reasons. Programs must be ready to handle these cases or use function writall. Exception GException is thrown with a plain text error message whenever an error occurs.

ovirtual long tell(void)
Returns the offset of the current position in the ByteStream. This function must be implemented by each subclass of ByteStream.

ovirtual int is_seekable(void) const
Tests whether function seek can seek backwards. Class ByteStream provides a default implementation which always returns false. Subclasses implementing backward seek capabilities must override this default implementation and return true.

ovirtual void seek(long offset, int whence = SEEK_SET)
Sets the current position for reading or writing the ByteStream. Class ByteStream provides a default implementation able to seek forward by calling function read until reaching the desired position. Subclasses implementing better seek capabilities must override this default implementation. The new current position is computed by applying displacement offset to the position represented by argument whence. The following values are recognized for argument whence:
SEEK_SET
Argument offset indicates the position relative to the beginning of the ByteStream.
SEEK_CUR
Argument offset is a signed displacement relative to the current position.
SEEK_END
Argument offset is a displacement relative to the end of the file. It is then advisable to provide a negative value for offset.
Results are undefined whenever the new position is greater than the total size of the ByteStream. Exception
GException is thrown with a plain text error message whenever an error occurs.

ovirtual void flush()
Flushes all buffers in the ByteStream. Calling this function guarantees that pending data have been actually written (i.e. passed to the operating system). Class ByteStream provides a default implementation which does nothing.

o Utility Functions.
Class ByteStream implements these functions using the virtual interface functions only. All subclasses of ByteStream inherit these functions.

osize_t readall(void *buffer, size_t size)
Reads data and blocks until everything has been read. This function is essentially similar to function read. Unlike function read however, function readall will never return a value smaller than size unless an end-of-file mark is reached. This is implemented by repeatedly calling function read until everything is read or until we reach an end-of-file mark. Note that read and readall are equivalent when size is one.

osize_t writall(const void *buffer, size_t size)
Writes data and blocks until everything has been written. This function is essentially similar to function write. Unlike function write however, function writall will only return after all size bytes have been written. This is implemented by repeatedly calling function write until everything is written. Note that write and writall are equivalent when size is one.

osize_t copy(ByteStream &bsfrom, size_t size=0)
Copy data from another ByteStream. A maximum of size bytes are read from the ByteStream bsfrom and are written to the ByteStream *this at the current position. Less than size bytes may be written if an end-of-file mark is reached on bsfrom. This function returns the total number of bytes copied. Setting argument size to zero (the default value) has a special meaning: the copying process will continue until reaching the end-of-file mark on ByteStream bsfrom, regardless of the number of bytes transferred.

ovoid write8(unsigned int card8)
Writes a one-byte integer to a ByteStream.

ovoid write16(unsigned int card16)
Writes a two-bytes integer to a ByteStream. The integer most significant byte is written first, regardless of the processor endianness.

ovoid write32(unsigned int card32)
Writes a four-bytes integer to a ByteStream. The integer most significant bytes are written first, regardless of the processor endianness.

ounsigned int read8()
Reads a one-byte integer from a ByteStream.

ounsigned int read16()
Reads a two-bytes integer from a ByteStream. The integer most significant byte is read first, regardless of the processor endianness.

ounsigned int read32()
Reads a four-bytes integer from a ByteStream. The integer most significant bytes are read first, regardless of the processor endianness.


Direct child classes:
IFFByteStream
StdioByteStream
StaticByteStream
MemoryByteStream
BSByteStream

Alphabetic index HTML hierarchy of classes or Java