This pure, virtual class is meant to encapsulate the operation of reading both 2 differently formatted evio versions. More...

#include <IEvioReader.h>

Public Types
enum	ReadWriteStatus { SUCCESS = 0, END_OF_FILE, CANNOT_OPEN_FILE, EVIO_EXCEPTION, UNKNOWN_ERROR }
	This `enum` denotes the status of a read/write. More...

Public Member Functions
virtual void	setBuffer (std::shared_ptr< ByteBuffer > &buf)=0
	This method can be used to avoid creating additional EvioReader objects by reusing this one with another buffer. More...

virtual bool	isClosed ()=0
	Has close() been called (without reopening by calling setBuffer(std::shared_ptr<ByteBuffer> &))? More...

virtual bool	checkBlockNumberSequence ()=0
	Is this reader checking the block number sequence and throwing an exception if it's not sequential and starting with 1? More...

virtual ByteOrder &	getByteOrder ()=0
	Get the byte order of the file/buffer being read. More...

virtual uint32_t	getEvioVersion ()=0
	Get the evio version number. More...

virtual std::string	getPath ()=0
	Get the path to the file. More...

virtual std::shared_ptr < EventParser > &	getParser ()=0
	Get the file/buffer parser. More...

virtual void	setParser (std::shared_ptr< EventParser > &evParser)=0
	Set the file/buffer parser. More...

virtual std::string	getDictionaryXML ()=0
	Get the XML format dictionary if there is one. More...

virtual bool	hasDictionaryXML ()=0
	Does this evio file have an associated XML dictionary? More...

virtual std::shared_ptr < EvioEvent >	getFirstEvent ()=0
	Get the "first" event if there is one. More...

virtual bool	hasFirstEvent ()=0
	Does this evio file have an associated first event? It's also called the Beginning-Of-Run event. More...

virtual size_t	getNumEventsRemaining ()=0
	Get the number of events remaining in the file. More...

virtual std::shared_ptr < ByteBuffer >	getByteBuffer ()=0
	Get the byte buffer being read. More...

virtual size_t	fileSize ()=0
	Get the size of the file being read, in bytes. More...

virtual std::shared_ptr < IBlockHeader >	getFirstBlockHeader ()=0
	This returns the FIRST block (record) header. More...

virtual std::shared_ptr < EvioEvent >	getEvent (size_t index)=0
	Get the event in the file/buffer at a given index (starting at 1). More...

virtual std::shared_ptr < EvioEvent >	parseEvent (size_t index)=0
	This is a workhorse method. More...

virtual std::shared_ptr < EvioEvent >	nextEvent ()=0
	Get the next event in the file/buffer. More...

virtual std::shared_ptr < EvioEvent >	parseNextEvent ()=0
	This is a workhorse method. More...

virtual void	parseEvent (std::shared_ptr< EvioEvent > evioEvent)=0
	This will parse an event, SAX-like. More...

virtual uint32_t	getEventArray (size_t evNumber, std::vector< uint8_t > &vec)=0
	Get an evio bank or event in vector-of-bytes form. More...

virtual uint32_t	getEventBuffer (size_t evNumber, ByteBuffer &buf)=0
	Get an evio bank or event in ByteBuffer form. More...

virtual void	rewind ()=0
	The equivalent of rewinding the file. More...

virtual ssize_t	position ()=0
	This is equivalent to obtaining the current position in the file. More...

virtual void	close ()=0
	This is closes the file, but for buffers it only sets the position to 0. More...

virtual std::shared_ptr < IBlockHeader >	getCurrentBlockHeader ()=0
	This returns the current (active) block (physical record) header. More...

virtual std::shared_ptr < EvioEvent >	gotoEventNumber (size_t evNumber)=0
	Go to a specific event in the file. More...

virtual size_t	getEventCount ()=0
	This is the number of events in the file/buffer. More...

virtual size_t	getBlockCount ()=0
	This is the number of blocks/records in the file/buffer including the empty block, record or trailer at the end. More...

Detailed Description

This pure, virtual class is meant to encapsulate the operation of reading both 2 differently formatted evio versions.

One implementing class reads evio versions 1 - 4, and the other, version 6.

Date: 06/8/2020

Author: timmer

Member Enumeration Documentation

enum evio::IEvioReader::ReadWriteStatus

This enum denotes the status of a read/write.

Used internally.
SUCCESS indicates a successful read.
END_OF_FILE indicates that we cannot read because an END_OF_FILE has occurred. Technically this means that whatever we are trying to read is larger than the buffer's unread bytes.
CANNOT_OPEN_FILE indicates that we cannot write because the destination file cannot be opened.
EVIO_EXCEPTION indicates that an EvioException was thrown during a read/write, possibly due to out of range values.
UNKNOWN_ERROR indicates that an unrecoverable error has occurred.

Enumerator
SUCCESS
END_OF_FILE
CANNOT_OPEN_FILE
EVIO_EXCEPTION
UNKNOWN_ERROR

Member Function Documentation

virtual bool evio::IEvioReader::checkBlockNumberSequence ( )

pure virtual

Is this reader checking the block number sequence and throwing an exception if it's not sequential and starting with 1?

Returns: true if checking block number sequence, else false

Implemented in evio::EvioReaderV4, evio::EvioReader, and evio::EvioReaderV6.

virtual void evio::IEvioReader::close ( )

pure virtual

This is closes the file, but for buffers it only sets the position to 0.

Implemented in evio::EvioReaderV4, evio::EvioReader, and evio::EvioReaderV6.

virtual size_t evio::IEvioReader::fileSize ( )

pure virtual

Get the size of the file being read, in bytes.

Returns: the file size in bytes

Implemented in evio::EvioReaderV4, evio::EvioReader, and evio::EvioReaderV6.

virtual size_t evio::IEvioReader::getBlockCount ( )

pure virtual

This is the number of blocks/records in the file/buffer including the empty block, record or trailer at the end.

Exceptions

EvioException if object closed.

Returns: the number of records in the file/buffer (estimate for version 3 files).

Implemented in evio::EvioReaderV4, evio::EvioReader, and evio::EvioReaderV6.

virtual std::shared_ptr<ByteBuffer> evio::IEvioReader::getByteBuffer ( )

pure virtual

Get the byte buffer being read.

Not useful when reading files.

Returns: the byte buffer being read (in certain cases).

Implemented in evio::EvioReaderV4, evio::EvioReader, and evio::EvioReaderV6.

virtual ByteOrder& evio::IEvioReader::getByteOrder ( )

pure virtual

Get the byte order of the file/buffer being read.

Returns: byte order of the file/buffer being read.

Implemented in evio::EvioReaderV4, evio::EvioReader, and evio::EvioReaderV6.

virtual std::shared_ptr<IBlockHeader> evio::IEvioReader::getCurrentBlockHeader ( )

pure virtual

This returns the current (active) block (physical record) header.

Since most users have no interest in physical records, this method should not be used.

Returns: the current block header.

Implemented in evio::EvioReaderV4, evio::EvioReader, and evio::EvioReaderV6.

virtual std::string evio::IEvioReader::getDictionaryXML ( )

pure virtual

Get the XML format dictionary if there is one.

Returns: XML format dictionary, else null.

Implemented in evio::EvioReaderV4, evio::EvioReader, and evio::EvioReaderV6.

virtual std::shared_ptr<EvioEvent> evio::IEvioReader::getEvent ( size_t index )

pure virtual

Get the event in the file/buffer at a given index (starting at 1).

As useful as this sounds, most applications will probably call parseNextEvent() or parseEvent(size_t) instead, since it combines combines getting an event with parsing it.

Parameters

index number of event desired, starting at 1, from beginning of file/buffer

Returns: the event in the file/buffer at the given index or null if none

Exceptions

EvioException if failed file access; if failed read due to bad file/buffer format; if index out of bounds; if object closed

Implemented in evio::EvioReaderV4, evio::EvioReader, and evio::EvioReaderV6.

virtual uint32_t evio::IEvioReader::getEventArray	(	size_t	evNumber,
		std::vector< uint8_t > &	vec
	)

pure virtual

Get an evio bank or event in vector-of-bytes form.

Parameters

evNumber	number of event of interest (starting at 1).
vec	vector to contain bank's/event's bytes.

Returns: number of bytes in returned event.

Exceptions

EvioException if failed file access; if eventNumber out of bounds (starts at 1); if the event number does not correspond to an existing event; if object closed

Implemented in evio::EvioReaderV4, evio::EvioReader, and evio::EvioReaderV6.

virtual uint32_t evio::IEvioReader::getEventBuffer	(	size_t	evNumber,
		ByteBuffer &	buf
	)

pure virtual

Get an evio bank or event in ByteBuffer form.

Parameters

evNumber	number of event of interest
buf	buffer to contain bank's/event's bytes.

Returns: number of bytes in returned event.

Exceptions

EvioException if failed file access; if eventNumber out of bounds (starts at 1); if the event number does not correspond to an existing event; if object closed

Implemented in evio::EvioReaderV4, evio::EvioReader, and evio::EvioReaderV6.

virtual size_t evio::IEvioReader::getEventCount ( )

pure virtual

This is the number of events in the file/buffer.

Any dictionary or first event are not included in the count.

Returns: the number of events in the file/buffer.

Exceptions

EvioException if read failure; if failed file access; if object closed

Implemented in evio::EvioReaderV4, evio::EvioReader, and evio::EvioReaderV6.

virtual uint32_t evio::IEvioReader::getEvioVersion ( )

pure virtual

Get the evio version number.

Returns: evio version number.

Implemented in evio::EvioReaderV4, evio::EvioReader, and evio::EvioReaderV6.

virtual std::shared_ptr<IBlockHeader> evio::IEvioReader::getFirstBlockHeader ( )

pure virtual

This returns the FIRST block (record) header.

Returns: the first block (record) header.

Implemented in evio::EvioReaderV4, evio::EvioReader, and evio::EvioReaderV6.

virtual std::shared_ptr<EvioEvent> evio::IEvioReader::getFirstEvent ( )

pure virtual

Get the "first" event if there is one.

It's also called the Beginning-Of-Run event. This event is defined once but included in each of the related split files written out.

Returns: the first event is it existed, else null.

Implemented in evio::EvioReaderV4, evio::EvioReader, and evio::EvioReaderV6.

virtual size_t evio::IEvioReader::getNumEventsRemaining ( )

pure virtual

Get the number of events remaining in the file.

Useful only if doing a sequential read.

Returns: number of events remaining in the file

Exceptions

EvioException if failed reading from file

Implemented in evio::EvioReaderV4, evio::EvioReader, and evio::EvioReaderV6.

virtual std::shared_ptr<EventParser>& evio::IEvioReader::getParser ( )

pure virtual

Get the file/buffer parser.

Returns: file/buffer parser.

Implemented in evio::EvioReaderV4, evio::EvioReader, and evio::EvioReaderV6.

virtual std::string evio::IEvioReader::getPath ( )

pure virtual

Get the path to the file.

Returns: path to the file

Implemented in evio::EvioReaderV4, evio::EvioReader, and evio::EvioReaderV6.

virtual std::shared_ptr<EvioEvent> evio::IEvioReader::gotoEventNumber ( size_t evNumber )

pure virtual

Go to a specific event in the file.

The events are numbered 1..N. This number is transient–it is not part of the event as stored in the evio file. In versions 4 and up this is just a wrapper on getEvent(size_t).

Parameters

evNumber the event number in a 1..N counting sense, from the start of the file.

Returns: the specified event in file or null if there's an error or nothing at that event #.

Exceptions

EvioException if object closed; if failed file access

Implemented in evio::EvioReaderV4, evio::EvioReader, and evio::EvioReaderV6.

virtual bool evio::IEvioReader::hasDictionaryXML ( )

pure virtual

Does this evio file have an associated XML dictionary?

Returns: true if this evio file has an associated XML dictionary, else false

Implemented in evio::EvioReaderV4, evio::EvioReader, and evio::EvioReaderV6.

virtual bool evio::IEvioReader::hasFirstEvent ( )

pure virtual

Does this evio file have an associated first event? It's also called the Beginning-Of-Run event.

This event is defined once but included in each of the related split files written out.

Returns: true if this evio file has an associated first event, else false

Implemented in evio::EvioReaderV4, evio::EvioReader, and evio::EvioReaderV6.

virtual bool evio::IEvioReader::isClosed ( )

pure virtual

Has close() been called (without reopening by calling setBuffer(std::shared_ptr<ByteBuffer> &))?

Returns: true

if this object closed, else
false

.

Implemented in evio::EvioReaderV4, evio::EvioReader, and evio::EvioReaderV6.

virtual std::shared_ptr<EvioEvent> evio::IEvioReader::nextEvent ( )

pure virtual

Get the next event in the file/buffer.

As useful as this sounds, most applications will probably call parseNextEvent() instead, since it combines getting the next event with parsing the next event.

Although this method can get events in versions 4+, it now delegates that to another method. No changes were made to this method from versions 1-3 in order to read the version 4 format as it is subset of versions 1-3 with variable block length.

Returns: the next event in the file. On error it throws an EvioException. On end of file, it returns null.

Exceptions

EvioException if failed file access; if failed read due to bad buffer format; if object closed

Implemented in evio::EvioReaderV4, evio::EvioReader, and evio::EvioReaderV6.

virtual std::shared_ptr<EvioEvent> evio::IEvioReader::parseEvent ( size_t index )

pure virtual

This is a workhorse method.

It retrieves the desired event from the file/buffer, and then parses it SAX-like. It will drill down and uncover all structures (banks, segments, and tagsegments) and notify any interested listeners.

Parameters

index number of event desired, starting at 1, from beginning of file/buffer

Returns: the parsed event at the given index or null if none

Exceptions

EvioException if failed file access; if failed read due to bad file/buffer format; if index out of bounds; if object closed

Implemented in evio::EvioReaderV4, evio::EvioReader, and evio::EvioReaderV6.

virtual void evio::IEvioReader::parseEvent ( std::shared_ptr< EvioEvent > evioEvent )

pure virtual

This will parse an event, SAX-like.

It will drill down and uncover all structures (banks, segments, and tagsegments) and notify any interested listeners.

As useful as this sounds, most applications will probably call parseNextEvent() instead, since it combines combines getting the next event with parsing the next event.

This method is only called by synchronized methods and therefore is not synchronized.

Parameters

evioEvent the event to parse.

Exceptions

EvioException if bad format

Implemented in evio::EvioReaderV4, evio::EvioReader, and evio::EvioReaderV6.

virtual std::shared_ptr<EvioEvent> evio::IEvioReader::parseNextEvent ( )

pure virtual

This is a workhorse method.

It retrieves the next event from the file/buffer, and then parses it SAX-like. It will drill down and uncover all structures (banks, segments, and tagsegments) and notify any interested listeners.

Returns: the event that was parsed. On error it throws an EvioException. On end of file, it returns null.

Exceptions

EvioException if failed file access; if read failure or bad format; if object closed

Implemented in evio::EvioReaderV4, evio::EvioReader, and evio::EvioReaderV6.

virtual ssize_t evio::IEvioReader::position ( )

pure virtual

This is equivalent to obtaining the current position in the file.

What it actually does is return the position of the buffer. Only meaningful to evio versions 1-3 and for sequential reading.

Returns: the position of the buffer; -1 if not sequential read and version 4+

Exceptions

EvioException if object closed; if error accessing file

Implemented in evio::EvioReaderV4, evio::EvioReader, and evio::EvioReaderV6.

virtual void evio::IEvioReader::rewind ( )

pure virtual

The equivalent of rewinding the file.

What it actually does is set the position of the file/buffer back to where it was after calling the constructor - after the first header.

Exceptions

EvioException if object closed; if failed file access or buffer/file read

Implemented in evio::EvioReaderV4, evio::EvioReader, and evio::EvioReaderV6.

virtual void evio::IEvioReader::setBuffer ( std::shared_ptr< ByteBuffer > & buf )

pure virtual

This method can be used to avoid creating additional EvioReader objects by reusing this one with another buffer.

The method close() is called before anything else.

Parameters

buf	ByteBuffer to be read.

Exceptions

underflow_error	if not enough data in buffer.
EvioException	if buf is null; buf not in proper format; if first record/block number != 1 when checkRecNumSeq arg is true.

Implemented in evio::EvioReaderV4, evio::EvioReader, and evio::EvioReaderV6.

virtual void evio::IEvioReader::setParser ( std::shared_ptr< EventParser > & evParser )

pure virtual

Set the file/buffer parser.

Parameters

evParser file/buffer parser.

Implemented in evio::EvioReaderV4, evio::EvioReader, and evio::EvioReaderV6.

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

IEvioReader.h

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Member Function Documentation