class ByteStream: public GPEnabled

Abstract class for a stream of bytes.

Inheritance:


Public Methods

[more]static GP<ByteStream> create(void)
Constructs an empty Memory ByteStream.
[more]static GP<ByteStream> create(void const * const buffer, const size_t size)
Constructs a Memory ByteStream by copying initial data.
[more]static GP<ByteStream> create( const char filename[], char const * const mode)
Constructs a ByteStream for accessing the file named filename.
[more]static GP<ByteStream> create( const int fd, char const * const mode, const bool closeme)
Constructs a ByteStream for accessing the stdio file f.
[more]static GP<ByteStream> create( FILE * const f, char const * const mode, const bool closeme)
Constructs a ByteStream for accessing the stdio file f.
[more]static GP<ByteStream> create_static( void const * const buffer, const size_t size)
Creates a ByteStream object for allocating the memory area of length sz starting at address buffer.

Public

[more]class Stdioclass Staticclass Memoryclass 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) const
Returns the offset of the current position in the ByteStream.
[more]virtual int seek(long offset, int whence = SEEK_SET, bool nothrow=false)
Sets the current position for reading or writing the ByteStream.
[more]virtual void flush(void)
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 write24(unsigned int card24)
Writes a three-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 read24()
Reads a three-bytes integer from a ByteStream.
[more]unsigned int read32()
Reads a four-bytes integer from a ByteStream.
[more]virtual int size(void) const
Returns the total number of bytes contained in the buffer, file, etc.
[more]TArray<char> get_data(void)
Use at your own risk, only guarenteed to work for ByteStream::Memorys.
[more]virtual size_t readat(void *buffer, size_t sz, int pos)
Reads data from a random position.


Inherited from GPEnabled:

Public Methods

oGPEnabled& operator=(const GPEnabled & obj)
oint get_count(void) const

Protected Fields

ovolatile int count


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.

oclass Stdioclass Staticclass Memoryclass 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) const
Returns the offset of the current position in the ByteStream. This function must be implemented by each subclass of ByteStream.

ovirtual int seek(long offset, int whence = SEEK_SET, bool nothrow=false)
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.

Error reporting: If seek() succeeds, 0 is returned. Otherwise it either returns -1 (if nothrow is set to FALSE) or throws the GException exception.

ovirtual void flush(void)
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 write24(unsigned int card24)
Writes a three-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 read24()
Reads a three-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.

ovirtual int size(void) const
Returns the total number of bytes contained in the buffer, file, etc. Valid offsets for function seek range from 0 to the value returned by this function.

oTArray<char> get_data(void)
Use at your own risk, only guarenteed to work for ByteStream::Memorys.

ovirtual size_t readat(void *buffer, size_t sz, int pos)
Reads data from a random position. This function reads at most sz bytes at position pos into buffer and returns the actual number of bytes read. The current position is unchanged.

ostatic GP<ByteStream> create(void)
Constructs an empty Memory ByteStream. The buffer itself is organized as an array of 4096 byte blocks. The buffer is initially empty. You must first use function write to store data into the buffer, use function seek to rewind the current position, and function read to read the data back.

ostatic GP<ByteStream> create(void const * const buffer, const size_t size)
Constructs a Memory ByteStream by copying initial data. The Memory buffer is initialized with size bytes copied from the memory area pointed to by buffer.

ostatic GP<ByteStream> create( const char filename[], char const * const mode)
Constructs a ByteStream for accessing the file named filename. Arguments filename and mode are similar to the arguments of the well known stdio function fopen. In addition a filename of - will be interpreted as the standard output or the standard input according to mode. This constructor will open a stdio file and construct a ByteStream object accessing this file. Destroying the ByteStream object will flush and close the associated stdio file. Exception GException is thrown with a plain text error message if the stdio file cannot be opened.

ostatic GP<ByteStream> create( const int fd, char const * const mode, const bool closeme)
Constructs a ByteStream for accessing the stdio file f. Argument mode indicates the type of the stdio file, as in the well known stdio function fopen. Destroying the ByteStream object will not close the stdio file f unless closeme is true.

ostatic GP<ByteStream> create( FILE * const f, char const * const mode, const bool closeme)
Constructs a ByteStream for accessing the stdio file f. Argument mode indicates the type of the stdio file, as in the well known stdio function fopen. Destroying the ByteStream object will not close the stdio file f unless closeme is true.

ostatic GP<ByteStream> create_static( void const * const buffer, const size_t size)
Creates a ByteStream object for allocating the memory area of length sz starting at address buffer. This call impliments a read-only ByteStream interface for a memory area specified by the user at construction time. Calls to function read directly access this memory area. The user must therefore make sure that its content remain valid long enough.


Direct child classes:
IFFByteStream
BSByteStream

Alphabetic index HTML hierarchy of classes or Java


DjVu is a trademark of LizardTech, Inc.
All other products mentioned are registered trademarks or trademarks of their respective companies.