Abstracts a file as a stream of bytes. More...

#include <InputByteStream.h>

Inheritance diagram for InputByteStream:

Public Member Functions
	InputByteStream (int fileno) throw (InputByteStreamError)
	Prepares to read a stream from the specified file descriptor, which must be open. More...

	InputByteStream (string srcspec) throw (InputByteStreamError)
	Prepares to read a stream from the specified source. More...

	~InputByteStream ()
	Closes the file and reclaims any buffers. More...

bool	eof ()
	Indicates whether we are at the end of the file. More...

virtual void	close ()
	Closes the stream, releasing all resources. More...

Byte	getByte (void) throw (InputByteStreamError)
	Reads a byte from the stream. More...

const Byte *	getBlock (unsigned int length) throw (InputByteStreamError)
	Retrieves a block from the current position in the stream. More...

void	skip (unsigned int) throw (InputByteStreamError)
	Skips a given number of bytes forward in the stream. More...

signed int	getSIU (int) throw (InputByteStreamError)
	Obtains an n-byte unsigned integer from the stream, as a signed int. More...

signed int	getSIS (int) throw (InputByteStreamError)
	Obtains an n-byte signed integer from the stream, as a signed int. More...

unsigned int	getUIU (int) throw (InputByteStreamError)
	Obtains an n-byte unsigned integer from the stream, as an unsigned int. More...

Static Public Member Functions
static unsigned int	getUIU (int, const Byte *) throw (InputByteStreamError)
	Obtains an n-byte unsigned integer from the beginning of a `Byte` array, as an unsigned int. More...

static void	setDefaultBufferSize (unsigned int length)
	Sets the default buffer size to be used for reading files. More...

static void	verbosity (const verbosities level)
	Sets the verbosity of this module. More...

static verbosities	getVerbosity (void)
	Returns the verbosity setting of this class. More...

Protected Member Functions
	InputByteStream ()
	No-argument constructor creates a new InputByteStream object, but does not associate it with any source of bytes. More...

bool	bindToFileDescriptor (int fileno, string filename="", int bufsize=0, bool fillBufferAndClose=false, bool assertIsSeekable=false) throw (InputByteStreamError)
	Binds this stream to a given file descriptor. More...

int	openSourceSpec (string srcspec) throw (InputByteStreamError)
	Opens a source. More...

int	getFD (void) const
	Returns the file descriptor this stream is bound to. More...

void	bufferSeek (unsigned int pos) throw (InputByteStreamError)
	Seeks to a specific point in the buffer. More...

void	reloadBuffer (void)
	Reloads the buffer, presumably after the file descriptor has been adjusted by an extending class. More...

Detailed Description

Abstracts a file as a stream of bytes.

Functions are provided to read individual bytes from the file and blocks of contiguous bytes.

Since this class is intended to help reading TeX DVI and PK files, we also provide methods to read signed and unsigned integers from the stream, encoded as described in the DVI driver standard.

This class is designed to be extended (and is extended in fact in classes FileByteStream and PipeStream). The subclassing interface consists of a no-argument constructor, a method to associate the class with a given file descriptor (bindToFileDescriptor), and a convenience method to help opening files, using the same specification syntax supported by this class (openSourceSpec). Since one of the main purposes of this subclassing is to support a class which handles a seekable input stream, we also have getFD to get the file descriptor being handled, and reloadBuffer to indicate to the parent class that the underlying stream has been modified (typically by a seek operation) so that the input buffer should be invalidated. If bindToFileDescriptor was invoked with the fillBufferAndClose flag true, then the bufferSeek method allows rapid seeking by simply adjusting the buffer pointer; though this is useless unless the whole stream is in the buffer, the class makes no check on this, and it is the extending class's responsibility to make sure that this is not called inappropriately.

Constructor & Destructor Documentation

InputByteStream::InputByteStream	(	int	fd)
throw	(	InputByteStreamError
	)

Prepares to read a stream from the specified file descriptor, which must be open.

Parameters

fd	an open file descriptor

Exceptions

InputByteStreamError if there is a problem binding to the descriptor

InputByteStream::InputByteStream	(	string	srcspec)
throw	(	InputByteStreamError
	)

Prepares to read a stream from the specified source.

The source may be

a file name, which should be readable
a specifier of the form <osfile>filename: the specified file is opened
a specifier of the form <osfd>integer: the integer specifyies an (open) OS file descriptor; thus <osfd>0 opens the standard input

Parameters

srcspec a source specification as described above

Exceptions

InputByteStreamError if there is a problem opening or binding to the descriptor

InputByteStream::~InputByteStream ( )

Closes the file and reclaims any buffers.

References close().

InputByteStream::InputByteStream ( )

protected

No-argument constructor creates a new InputByteStream object, but does not associate it with any source of bytes.

To associate it with a source, use bindToFileDescriptor or the convenience method openSourceSpec.

Member Function Documentation

bool InputByteStream::bindToFileDescriptor	(	int	fileno,
		string	filename = `""`,
		int	bufsize = `0`,
		bool	fillBufferAndClose = `false`,
		bool	assertIsSeekable = `false`
	)
throw	(	InputByteStreamError
	)

protected

Binds this stream to a given file descriptor.

If the parameter fillBufferAndClose is true, then this method will keep reading from the file descriptor until it reaches either the end of the newly-allocated buffer, or end-of-file, whichever comes first. It will then close the file descriptor. In this case (and in this case alone), the method bufferSeek becomes useful, and can be used by an extending class to implement an efficient seek operation on the file.

Parameters

fileno	the file descriptor to be handled by this object
filename	the file name associated with this descriptor; this may be the empty string
bufsize	a size suggested for the input buffer, or zero to accept the default
fillBufferAndClose	if true, read the entire contents of the file into memory
assertIsSeekable	if true, the caller is asserting that the given file descriptor points to a seekable object (presumably because it will depend on it being so). If this is not the case (the descriptor refers to a pipe or other non-seekable, and non-mappable, object), then throw an exception. If this is false, no assertion is being made; it is not being asserted that the object is non-seekable.

Exceptions

InputByteStreamError if there is some other problem reading the file; or if a negative buffer size is given; or if the assertion described for parameter assertIsSeekable turns out to be false.

Returns: true on success

References debug, normal, and Util::verbosity_.

void InputByteStream::bufferSeek	(	unsigned int	offset)
throw	(	InputByteStreamError
	)

protected

Seeks to a specific point in the buffer.

This is only useful when the buffer holds the complete file, that is, when bindToFileDescriptor was called with parameter fillBufferAndClose true.

Parameters

offset the offset from the beginning of the buffer, where the current position is relocated to

Exceptions

InputByteStreamError if the offset would take the pointer outside the buffer, or if the stream has been closed

References debug, and Util::verbosity_.

void InputByteStream::close ( void )

virtual

Closes the stream, releasing all resources.

Reimplemented in PipeStream.

References normal, and Util::verbosity_.

Referenced by PipeStream::close(), and ~InputByteStream().

bool InputByteStream::eof ( )

Indicates whether we are at the end of the file.

This method does not return true until after a failed attempt to read past the end of file; that is, it does not return true immediately after the last byte has been read from the file.

Returns: true if we are at the end of the file

Referenced by DviFile::eof(), and getByte().

const Byte * InputByteStream::getBlock	(	unsigned int	length)
throw	(	InputByteStreamError
	)

Retrieves a block from the current position in the stream.

Leaves the pointer pointing after the block returned.

Parameters

length the size of block desired

Returns: a pointer to a block of bytes

Exceptions

InputByteStreamError if the requested number of bytes cannot be read, which includes the case of this method being called when eof() is true

Byte InputByteStream::getByte	(	void	)
throw	(	InputByteStreamError
	)

Reads a byte from the stream.

Increments the reading pointer. This method does not signal an error at end-of-file; if eof is true or becomes true as a result of this attempt to read past the end of the file, then we return zero. That is, eof() does not return true immediately the last byte in the file has been read.

Returns: the byte read, or zero if we are at the end of the file

Exceptions

InputByteStreamError if there is some problem reading the stream

References eof().

int InputByteStream::getFD ( void ) const

inlineprotected

Returns the file descriptor this stream is bound to.

If there is no open descriptor (see the fillBufferAndClose parameter to bindToFileDescriptor), returns negative.

Returns: the file descriptor, or negative if the descriptor has been closed

signed int InputByteStream::getSIS	(	int	n)
throw	(	InputByteStreamError
	)

Obtains an n-byte signed integer from the stream, as a signed int.

Parameters

n	the number of bytes to read, in the range 1–4 inclusive

Returns: the next integer from the input stream, as a signed int

Exceptions

InputByteStreamError if parameter n was out of range

signed int InputByteStream::getSIU	(	int	n)
throw	(	InputByteStreamError
	)

Obtains an n-byte unsigned integer from the stream, as a signed int.

Parameters

n	the number of bytes to read, in the range 1–3 inclusive (there are no 4-byte unsigned quantities in DVI files)

Returns: the next integer from the input stream, as a signed int

Exceptions

InputByteStreamError if parameter n was out of range

unsigned int InputByteStream::getUIU	(	int	n)
throw	(	InputByteStreamError
	)

Obtains an n-byte unsigned integer from the stream, as an unsigned int.

Parameters

n	the number of bytes to read, in the range 1–4 inclusive

Returns: the next integer from the input stream, as an unsigned int

Exceptions

InputByteStreamError if parameter n was out of range

unsigned int InputByteStream::getUIU	(	int	n,
		const Byte *	p
	)
throw	(	InputByteStreamError
	)

static

Obtains an n-byte unsigned integer from the beginning of a Byte array, as an unsigned int.

This has little specifically to do with Input streams, and is here as a convenience method.

Parameters

n	the number of bytes to read, in the range 1–4 inclusive
p	a pointer to an array of `Byte` values

Returns: the integer at the beginning of the given array, as an unsigned int

Exceptions

InputByteStreamError if parameter n was out of range

static verbosities InputByteStream::getVerbosity ( void )

inlinestatic

Returns the verbosity setting of this class.

Referenced by PipeStreamSignalHandling::expectAnother(), and PipeStreamSignalHandling::got_status().

int InputByteStream::openSourceSpec	(	string	srcspec)
throw	(	InputByteStreamError
	)

protected

Opens a source.

The source is specified as in InputByteStream(string). Throws an exception on any problems, so that if it returns, it has successfully opened the file, or determined that the file descriptor is (syntactically) valid.

Parameters

srcspec a source specification

Returns: an open file descriptor

Exceptions

InputByteStreamError if there is any problem opening the file

References normal, and Util::verbosity_.

void InputByteStream::reloadBuffer ( void )

protected

Reloads the buffer, presumably after the file descriptor has been adjusted by an extending class.

References debug, and Util::verbosity_.

void InputByteStream::setDefaultBufferSize ( unsigned int length)

static

Sets the default buffer size to be used for reading files.

Parameters

length the size, in bytes, of the input buffer

void InputByteStream::skip	(	unsigned int	increment)
throw	(	InputByteStreamError
	)

Skips a given number of bytes forward in the stream.

Parameters

increment the number of bytes to move forward in the stream

Exceptions

InputByteStreamError if we skip past the end of file

static void InputByteStream::verbosity ( const verbosities level)

inlinestatic

Sets the verbosity of this module.

Parameters

level the required verbosity

Referenced by main().

The documentation for this class was generated from the following files:

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation