The class to read VRS files. More...

#include <RecordFileReader.h>

Classes
class	RecordTypeCounter

Public Member Functions
	RecordFileReader (const RecordFileReader &)=delete

RecordFileReader &	operator= (const RecordFileReader &)=delete

bool	isVrsFile (const string &filePath)

bool	isVrsFile (const FileSpec &fileSpec)

int	openFile (const string &filePath, bool autoWriteFixedIndex=false)

int	openFile (const FileSpec &fileSpec, bool autoWriteFixedIndex=false)

bool	isOpened () const

void	setStreamPlayer (StreamId streamId, StreamPlayer *streamPlayer)

int	clearStreamPlayers ()

bool	prefetchRecordSequence (const vector< const IndexRecord::RecordInfo * > &records, bool clearSequence=true)

bool	isRecordAvailableOrPrefetch (const IndexRecord::RecordInfo &recordInfo)

int	readRecord (const IndexRecord::RecordInfo &recordInfo)

int	readRecord (const IndexRecord::RecordInfo &recordInfo, StreamPlayer *streamPlayer, bool setupPlayer=false)

int	readAllRecords ()

vector< std::pair< string, int64_t > >	getFileChunks () const

int64_t	getTotalSourceSize () const

int	closeFile ()

bool	hasIndex () const

const set< StreamId > &	getStreams () const

vector< StreamId >	getStreams (RecordableTypeId typeId, const string &flavor={}) const

StreamId	getStreamForType (RecordableTypeId typeId, uint32_t indexNumber=0) const

StreamId	getStreamForName (const string &name) const

StreamId	getStreamForFlavor (RecordableTypeId typeId, const string &flavor, uint32_t indexNumber=0) const

StreamId	getStreamForTag (const string &tagName, const string &tag, RecordableTypeId typeId=RecordableTypeId::Undefined) const

StreamId	getStreamForSerialNumber (const string &streamSerialNumber) const
	Find the stream with the specified stream serial number.

const vector< IndexRecord::RecordInfo > &	getIndex () const

const vector< const IndexRecord::RecordInfo * > &	getIndex (StreamId streamId) const

uint32_t	getRecordCount () const

uint32_t	getRecordCount (StreamId streamId) const

uint32_t	getRecordCount (StreamId streamId, Record::Type recordType) const

const IndexRecord::RecordInfo *	getRecord (uint32_t globalIndex) const

const IndexRecord::RecordInfo *	getRecord (StreamId streamId, uint32_t indexNumber) const

const IndexRecord::RecordInfo *	getRecord (StreamId streamId, Record::Type recordType, uint32_t indexNumber) const

const IndexRecord::RecordInfo *	getLastRecord (StreamId streamId, Record::Type recordType) const

const IndexRecord::RecordInfo *	getRecordByTime (double timestamp) const

const IndexRecord::RecordInfo *	getRecordByTime (Record::Type recordType, double timestamp) const

const IndexRecord::RecordInfo *	getRecordByTime (StreamId streamId, double timestamp) const

const IndexRecord::RecordInfo *	getRecordByTime (StreamId streamId, Record::Type recordType, double timestamp) const

const IndexRecord::RecordInfo *	getNearestRecordByTime (double timestamp, double epsilon, StreamId streamId={}, Record::Type recordType=Record::Type::UNDEFINED) const

uint32_t	getRecordIndex (const IndexRecord::RecordInfo *record) const

uint32_t	getRecordStreamIndex (const IndexRecord::RecordInfo *record) const

uint32_t	getRecordSize (uint32_t recordIndex, bool useBoundaries=true) const

double	getFirstDataRecordTime () const

double	getLastDataRecordTime () const

bool	readFirstConfigurationRecord (StreamId streamId, StreamPlayer *streamPlayer=nullptr)

bool	readFirstConfigurationRecords (StreamPlayer *streamPlayer=nullptr)

bool	readFirstConfigurationRecordsForType (RecordableTypeId typeId, StreamPlayer *streamPlayer=nullptr)

const map< string, string > &	getTags () const

const string &	getTag (const string &name) const

const StreamTags &	getTags (StreamId streamId) const

const map< StreamId, StreamTags > &	getStreamTags () const
	Get the tags for all the streams at once.

const string &	getTag (StreamId streamId, const string &name) const

const string &	getOriginalRecordableTypeName (StreamId streamId) const

const string &	getFlavor (StreamId streamId) const

const string &	getSerialNumber (StreamId streamId) const

string	getStreamsSignature () const

bool	mightContainImages (StreamId streamId) const

bool	mightContainAudio (StreamId streamId) const

bool	getRecordFormat (StreamId streamId, Record::Type recordType, uint32_t formatVersion, RecordFormat &outFormat) const

uint32_t	getRecordFormats (StreamId streamId, RecordFormatMap &outFormats) const

std::unique_ptr< DataLayout >	getDataLayout (StreamId streamId, const ContentBlockId &blockId) const

void	setOpenProgressLogger (ProgressLogger *progressLogger)

bool	setCachingStrategy (CachingStrategy cachingStrategy)

CachingStrategy	getCachingStrategy () const

bool	setStatsCallback (const FileHandler::CacheStatsCallbackFunction &statsCallback)
	Set callback function for cache stats.

bool	purgeFileCache ()

void	setFileHandler (std::unique_ptr< FileHandler > fileHandler)

std::unique_ptr< FileHandler >	getFileHandler () const

void	buildRecordBoundaries (bool boundariesAndLimits=false) const
	private, for testing only

Static Public Member Functions
static int	vrsFilePathToFileSpec (const string &filePath, FileSpec &outFileSpec, bool checkLocalFile=false)

Detailed Description

The class to read VRS files.

Recipe:

open a VRS file using openFile().
get info about the VRS file using getTags(). (optional: the writer may provide recording context info).
find out which streams it contains using getStreams().
attach record players to the streams you care about, using setStreamPlayer().
playback records one-by-one using readRecord(), or all at once using readAllRecords().
close the file. State, configuration & data records handling is delegated to their stream id players. Player can 'process' the data in the callback made by the file reader's thread, or delegate the work by posting a PlaybackRecord to a PlaybackThread.

Member Function Documentation

◆ clearStreamPlayers()

int vrs::RecordFileReader::clearStreamPlayers ( )

Remove all registered stream players.

Returns: O on success.

◆ closeFile()

int vrs::RecordFileReader::closeFile ( )

Close the underlying file, if one is open.

Returns: 0 on success or if no file was open, or some file system error code.

◆ getFileChunks()

vector< pair< string, int64_t > > vrs::RecordFileReader::getFileChunks ( ) const

Get a list of the file's chunks, path + size in bytes.

Returns: A vector of pairs path-file size.

◆ getFileHandler()

unique_ptr< FileHandler > vrs::RecordFileReader::getFileHandler ( ) const

Get a clone of the current file handler, for use elsewhere.

Returns: A copy of the current file handler.

◆ getFirstDataRecordTime()

double vrs::RecordFileReader::getFirstDataRecordTime ( ) const

Timestamp for the first data record in the whole file.

Returns: The timestamp for the file data record, or 0, if the file contains no data record.

◆ getFlavor()

const string & vrs::RecordFileReader::getFlavor ( StreamId streamId ) const

Streams using << Recordable Class >> ids require a << flavor >>, which must be provided when the stream was created. Use this API to get the recordable flavor provided, if any, when the stream was created.

Parameters

streamId StreamId of the record stream to consider.

Returns: The flavor for the corresponding RecordableTypeId, or an empty string, if no flavor was provided when the stream was created.

◆ getIndex() [1/2]

const vector< IndexRecord::RecordInfo > & vrs::RecordFileReader::getIndex ( ) const

inline

Get the index of the VRS file, which is an ordered array of RecordInfo, each describing the records, sorted by timestamp.

Returns: The index.

◆ getIndex() [2/2]

const vector< const IndexRecord::RecordInfo * > & vrs::RecordFileReader::getIndex ( StreamId streamId ) const

Get a record index limited to a specific stream.

Parameters

streamId StreamId of the record stream to consider.

Returns: The index of the file, with all the records.

◆ getLastDataRecordTime()

double vrs::RecordFileReader::getLastDataRecordTime ( ) const

Timestamp for the last data record in the whole file.

Returns: The timestamp for the file data record, or 0, if the file contains no data record.

◆ getLastRecord()

const IndexRecord::RecordInfo * vrs::RecordFileReader::getLastRecord	(	StreamId	streamId,
		Record::Type	recordType
	)		const

Find the last record for a specific stream and specific type.

Parameters

streamId	StreamId of the record stream to consider.
recordType	Type of the records to consider.

Returns: Pointer to the record info, or nullptr if the streamId or no record of the type was found.

◆ getNearestRecordByTime()

const IndexRecord::RecordInfo * vrs::RecordFileReader::getNearestRecordByTime	(	double	timestamp,
		double	epsilon,
		StreamId	streamId = `{}`,
		Record::Type	recordType = `Record::Type::UNDEFINED`
	)		const

Find the nearest record of a specific stream within the range of (timestamp - epsilon) - (timestamp + epsilon).

Parameters

timestamp	timestamp to seek.
epsilon	the threshold we search for the index.
streamId	StreamId of the stream to consider. Leave undefined to search all streams
recordType	record type to find, or Record::Type::UNDEFINED for any record type.

Returns: Pointer to the record info, or nullptr (timestamp is too big?).

◆ getOriginalRecordableTypeName()

const string & vrs::RecordFileReader::getOriginalRecordableTypeName ( StreamId streamId ) const

RecordableTypeId text descriptions may change over time, so at the time of recording, we capture the text name, so that we can see what it was when the file was recorded.

Parameters

streamId StreamId of the record stream to consider.

Returns: The original text description for the corresponding RecordableTypeId.

◆ getRecord() [1/3]

const IndexRecord::RecordInfo * vrs::RecordFileReader::getRecord	(	StreamId	streamId,
		Record::Type	recordType,
		uint32_t	indexNumber
	)		const

Find a specific record for a specific stream and type, by index number. nullptr is returned if no record is found for that index number.

Parameters

streamId	StreamId of the record stream to consider.
recordType	Type of the records to consider.
indexNumber	Index of the record to look for.

Returns: Pointer to the record info, or nullptr if the streamId or the indexNumber wasn't found for that specific type.

◆ getRecord() [2/3]

const IndexRecord::RecordInfo * vrs::RecordFileReader::getRecord	(	StreamId	streamId,
		uint32_t	indexNumber
	)		const

Find a specific record for a specific stream, regardless of type, by index number.

Parameters

streamId	StreamId of the record stream to consider.
indexNumber	Index of the record to look for.

Returns: Pointer to the record info, or nullptr if the streamId, or a record with the indexNumber wasn't found.

◆ getRecord() [3/3]

const IndexRecord::RecordInfo * vrs::RecordFileReader::getRecord ( uint32_t globalIndex ) const

Find a specific record, regardless of its stream or type, by its absolute index number in the file.

Parameters

globalIndex Index of the record to look for.

Returns: Pointer to the record info, or nullptr the index exceeds the total number of records.

◆ getRecordByTime() [1/4]

const IndexRecord::RecordInfo * vrs::RecordFileReader::getRecordByTime ( double timestamp ) const

Find the first record at or after a timestamp.

Parameters

timestamp timestamp to seek.

Returns: Pointer to the record info, or nullptr (timestamp is too big?).

◆ getRecordByTime() [2/4]

const IndexRecord::RecordInfo * vrs::RecordFileReader::getRecordByTime	(	Record::Type	recordType,
		double	timestamp
	)		const

Find the first record of a specific type at or after a timestamp.

Parameters

recordtype	record type to find.
timestamp	timestamp to seek.

Returns: Pointer to the record info, or nullptr (timestamp is too big?).

◆ getRecordByTime() [3/4]

const IndexRecord::RecordInfo * vrs::RecordFileReader::getRecordByTime	(	StreamId	streamId,
		double	timestamp
	)		const

Find the first record of a specific stream at or after a timestamp.

Parameters

streamId	StreamId of the stream to consider.
timestamp	timestamp to seek.

Returns: Pointer to the record info, or nullptr (timestamp is too big?).

◆ getRecordByTime() [4/4]

const IndexRecord::RecordInfo * vrs::RecordFileReader::getRecordByTime	(	StreamId	streamId,
		Record::Type	recordType,
		double	timestamp
	)		const

Find the first record of a specific stream of a specific type at or after a timestamp.

Parameters

streamId	StreamId of the stream to consider.
recordtype	record type to find.
timestamp	timestamp to seek.

Returns: Pointer to the record info, or nullptr (timestamp is too big?).

◆ getRecordCount() [1/3]

uint32_t vrs::RecordFileReader::getRecordCount ( ) const

inline

Get the number of records in the whole file.

Returns: The number of records in the whole VRS file, or 0, if no file is opened.

◆ getRecordCount() [2/3]

uint32_t vrs::RecordFileReader::getRecordCount ( StreamId streamId ) const

Get the number of records of a specific stream.

Parameters

streamId StreamId of the record stream to consider.

Returns: The number of records of the specified stream.

◆ getRecordCount() [3/3]

uint32_t vrs::RecordFileReader::getRecordCount	(	StreamId	streamId,
		Record::Type	recordType
	)		const

Get the number of records for a specific stream and specific record type. Attention: this computation has a linear complexity, so cache the result!

Parameters

streamId	StreamId of the record stream to consider.
recordType	Type of records to count.

Returns: Number of records for the specified stream id & record type.

◆ getRecordFormat()

bool vrs::RecordFileReader::getRecordFormat	(	StreamId	streamId,
		Record::Type	recordType,
		uint32_t	formatVersion,
		RecordFormat &	outFormat
	)		const

Get the RecordFormat for a specific stream, record type & record format version. Mostly useful for testing.

Parameters

streamId	StreamId of the record stream to consider.
recordType	Type of the records to consider.
formatVersion	Version to consider.
outFormat	RecordFormat reference to set.

Returns: True if outFormat value was set, false if no RecordFormat version was found.

◆ getRecordFormats()

uint32_t vrs::RecordFileReader::getRecordFormats	(	StreamId	streamId,
		RecordFormatMap &	outFormats
	)		const

Get all the RecordFormat description used in this VRS file. Mostly useful for tools like VRStool & VRSplayer.

Parameters

streamId	StreamId of the record stream to consider.
outFormats	Reference to be set.

Returns: Number of formats found.

◆ getRecordIndex()

uint32_t vrs::RecordFileReader::getRecordIndex ( const IndexRecord::RecordInfo * record ) const

Get a record's index in the global index.

Parameters

record pointer of the record.

Returns: Index in the global index, or getRecordCount() is record is nullptr.

◆ getRecordSize()

uint32_t vrs::RecordFileReader::getRecordSize	(	uint32_t	recordIndex,
		bool	useBoundaries = `true`
	)		const

Get a record's disk size.

Parameters

record	index of the record.
useBoundaries	if true, use the record's boundaries when available to compute the size. For testing only: use the default value!

Returns: The record's size on disk, or 0 for invalid indexes.

◆ getRecordStreamIndex()

uint32_t vrs::RecordFileReader::getRecordStreamIndex ( const IndexRecord::RecordInfo * record ) const

Get a record's index in the record's stream index.

Parameters

record pointer of the record.

Returns: Index in the record's stream index, or getRecordCount() is record is nullptr.

◆ getSerialNumber()

const string & vrs::RecordFileReader::getSerialNumber ( StreamId streamId ) const

Get a stream's serial number. When streams are created, they are assigned a unique serial number by their Recordable object. That serial number is universally unique and it will be preserved during file copies, file processing, and other manipulations that preserve stream tags.

Parameters

streamId StreamId of the record stream to consider.

Returns: The stream's serial number, or the empty string if the stream ID is not valid. When opening files created before stream serial numbers were introduced, RecordFileReader automatically generates a stable serial number for every stream based on the file tags, the stream's tags (both user and VRS internal tags), and the stream type and sequence number. This serial number is stable and preserved during copy and filtering operations that preserve stream tags.

◆ getStreamForFlavor()

StreamId vrs::RecordFileReader::getStreamForFlavor	(	RecordableTypeId	typeId,
		const string &	flavor,
		uint32_t	indexNumber = `0`
	)		const

Find a stream of a specific flavor, by index number. Use isValid() to tell if a device was found.

Parameters

typeId	The RecordableTypeId of the type of device to look for.
flavor	A recordable flavor to search for.
indexNumber	An index.

Returns: A StreamId. Call isValid() to know if a matching StreamId was actually found.

◆ getStreamForName()

StreamId vrs::RecordFileReader::getStreamForName ( const string & name ) const

Find a stream from an absolute or relative numeric name. Absolute numeric names are in the form <numeric_recordable_type_id>-<instance_id>, eg 1201-1 Relative numeric names are in the form <numeric_recordable_type_id>+<instance_id>, eg 1201+1 Relative numeric names have instance ids interpreted as the nth stream of that type, eg 1201+3 is the 3rd stream with the recordable type id 1201 (if there is such a stream). In all cases, use isValid() to verify that the stream was found in the file.

Parameters

name	an absolute or relative numeric name

Returns: a StreamId, valid only if the numeric name exists in the file.

◆ getStreamForTag()

StreamId vrs::RecordFileReader::getStreamForTag	(	const string &	tagName,
		const string &	tag,
		RecordableTypeId	typeId = `RecordableTypeId::Undefined`
	)		const

Find the first stream with given tag name/value pair.

Parameters

tagName	The name of the tag to look for.
tag	The tag value to look for.
typeId	The RecordableTypeId to limit the search to, or RecordableTypeId::Undefined to look for any device type. Note: if more than one stream match the criteria, the "first" one is returned, which means the one with the lowest RecordableTypeId enum value, or if equal, the one with the lowest StreamId instanceId.

Returns: A StreamId. Call isValid() to know if a matching StreamId was actually found.

◆ getStreamForType()

StreamId vrs::RecordFileReader::getStreamForType	(	RecordableTypeId	typeId,
		uint32_t	indexNumber = `0`
	)		const

Find a stream for a specific device type, by index number. Use isValid() to tell if a device was found.

Parameters

typeId	The RecordableTypeId of the type of device to look for.
indexNumber	An index.

Returns: A StreamId. Call isValid() to know if a matching StreamId was actually found.

◆ getStreams() [1/2]

const set< StreamId > & vrs::RecordFileReader::getStreams ( ) const

inline

Get the set of StreamId for all the streams in the file.

Returns: The set of stream IDs for which there are records.

◆ getStreams() [2/2]

vector< StreamId > vrs::RecordFileReader::getStreams	(	RecordableTypeId	typeId,
		const string &	flavor = `{}`
	)		const

Get a set of StreamId for a specific type, and an optional flavor.

Parameters

typeId	a recordable type id, maybe a Recordable Class. Use RecordableTypeId::Undefined to match any recordable type.
flavor	an option flavor.

Returns: A vector of stream ids of the given type, and of the provided flavor (if any).

◆ getStreamsSignature()

string vrs::RecordFileReader::getStreamsSignature ( ) const

Get a string describing the stream configuration, with stream type, serial number, and record counts, so it can be used to verify that the file looks a specific way without doing a full checksum. The stream Instance ID are NOT used, as they might be modified during copies.

◆ getTag() [1/2]

const string & vrs::RecordFileReader::getTag ( const string & name ) const

inline

Get a specific tag by name.

Parameters

name	Name of the tag to look for.

Returns: The tag value, or the empty string if the tag wasn't found.

◆ getTag() [2/2]

const string & vrs::RecordFileReader::getTag	(	StreamId	streamId,
		const string &	name
	)		const

inline

Get a specific tag for a specific record stream.

Parameters

streamId	StreamId of the record stream to consider.
name	Name of the tag to look for.

Returns: The tag value, or the empty string if the tag wasn't found.

◆ getTags() [1/2]

const map< string, string > & vrs::RecordFileReader::getTags ( ) const

inline

Get the tags map for the whole file. Does not include any stream tag.

Returns: The file's tags map.

◆ getTags() [2/2]

const StreamTags & vrs::RecordFileReader::getTags ( StreamId streamId ) const

Get the tags for a specific record stream.

Parameters

streamId StreamId of the record stream to consider.

Returns: The tags for the stream. If the streamId doesn't exist in the file, the map returned will be an empty map.

◆ getTotalSourceSize()

int64_t vrs::RecordFileReader::getTotalSourceSize ( ) const

Get the size of the whole file.

Returns: The number of bytes of all the chunks combined.

◆ hasIndex()

bool vrs::RecordFileReader::hasIndex ( ) const

VRS might not have a valid index, for instance, if the format is too old, or if there was a crash while the file was being produced. If there is no index, one will be created when the file is opened, but it will cost time. Requirements: the file must be opened for this method to be valid.

Returns: True if the actual file has an index. Either way, we always have an in-memory index.

◆ isOpened()

bool vrs::RecordFileReader::isOpened ( ) const

Tell if an actual file is being read

Returns: True if the file is opened.

◆ isRecordAvailableOrPrefetch()

bool vrs::RecordFileReader::isRecordAvailableOrPrefetch ( const IndexRecord::RecordInfo & recordInfo )

Check if a file record is available for immediate loading (e.g. on disk or in-cache). If not, begin background prefetching at the requested frame (but do not wait for results).

Parameters

recordInfo RecordInfo reference of the record to read.

Returns: true if available, false if unavailable (e.g. would require a network fetch).

◆ isVrsFile() [1/2]

bool vrs::RecordFileReader::isVrsFile ( const FileSpec & fileSpec )

Checks if a file is most probably a VRS file by checking its header for VRS file's format magic numbers. Note: will reset the object if needed.

Parameters

fileSpec File spec of the local or remote file to check.

Returns: True if the file is probably a VRS file, false otherwise (or if no file is found).

◆ isVrsFile() [2/2]

bool vrs::RecordFileReader::isVrsFile ( const string & filePath )

Checks if a file is most probably a VRS file by checking its header for VRS file's format magic numbers. Note: will reset the object if needed.

Parameters

filePath Absolute or relative path of the file to check.

Returns: True if the file is probably a VRS file, false otherwise (or if no file is found).

◆ mightContainAudio()

bool vrs::RecordFileReader::mightContainAudio ( StreamId streamId ) const

Tell if a stream might contain some audio data (and probably will). This is a best guess effort, but it is still possible that no audio will actually be found!

Parameters

streamId StreamId of the record stream to check.

Returns: True if at least one Data record RecordFormat definition found in the stream has at least one audio content block, and the stream contains at least one data record.

◆ mightContainImages()

bool vrs::RecordFileReader::mightContainImages ( StreamId streamId ) const

Tell if a stream might contain at least one image (and probably will). This is a best guess effort, but it is still possible that no images are actually found!

Parameters

streamId StreamId of the record stream to check.

Returns: True if at least one Data record RecordFormat definition found in the stream has at least one image content block, and the stream contains at least one data record.

◆ openFile() [1/2]

int vrs::RecordFileReader::openFile	(	const FileSpec &	fileSpec,
		bool	autoWriteFixedIndex = `false`
	)

Open a record file. Use one RecordFileReader object per file you want to read.

Parameters

fileSpec	File spec of the local or remote file to check.
autoWriteFixedIndex	If the index was rebuilt, patch the original file in place.

Returns: 0 on success and you can read the file, or some non-zero error code, in which case, further read calls will fail.

◆ openFile() [2/2]

int vrs::RecordFileReader::openFile	(	const string &	filePath,
		bool	autoWriteFixedIndex = `false`
	)

Open a record file. Use one RecordFileReader object per file you want to read.

Parameters

filePath	Identifier of resource to open. Might be a file path, a URI, or a "JSON path". See FileHandlerFactory::delegateOpen for details.
autoWriteFixedIndex	If the index was rebuilt, patch the original file in place.

Returns: 0 on success and you can read the file, or some non-zero error code, in which case, further read calls will fail.

◆ prefetchRecordSequence()

bool vrs::RecordFileReader::prefetchRecordSequence	(	const vector< const IndexRecord::RecordInfo * > &	records,
		bool	clearSequence = `true`
	)

When streaming a VRS file from the cloud, it may be very beneficial to tell before hand which records will be read, in order, so that the data can be prefetched optimally. Note the only some FileHandlers implement this, others will just ignore the request, which is always safe to make.

Parameters

records

a sequence of records in the exact order they will be read. It's ok to skip one or more records, but:

don't try to read "past" records, or you'll confuse the caching strategy, possibly leading to much worse performance.
if you read a single record out of the sequence, the prefetch list will be cleared. You may call this method as often as you like, and any previous read sequence will be cleared, but whatever is already in the cache will remain.

clearSequence Flag on whether to cancel any pre-existing custom read sequence upon caching starts.

Returns: True if the file handler backend supports this request, false if it was ignored.

◆ purgeFileCache()

bool vrs::RecordFileReader::purgeFileCache ( )

inline

If the underlying file handler caches data on reads, purge its caches to free memory. Sets the caching strategy to Passive, and clears any pending read sequence.

Returns: True if the caches were purged, false if they weren't for some reason. Note: this is a best effort. If transactions are pending, their cache blocks won't be cleared.

◆ readAllRecords()

int vrs::RecordFileReader::readAllRecords ( )

Read all the records of an open file. Call closeFile() when you're done. Guaranties that records are read sorted by timestamp.

Returns: 0 if all records were read successfully, some other value otherwise.

◆ readFirstConfigurationRecord()

bool vrs::RecordFileReader::readFirstConfigurationRecord	(	StreamId	streamId,
		StreamPlayer *	streamPlayer = `nullptr`
	)

Helper function: Read a stream's first configuration record. This might be necessary to properly read records containing image or audio blocks, if their configuration is defined in a configuration record using datalayout conventions. Notes:

a RecordFormatStreamPlayer must be attached to the reader prior to making this call, so it can find the RecordFormat and DataLayout definitions.
if you provide a stream player, the caching happens in that stream player only.

if the stream contains more than one configuration record, the first configuration record probably won't be right for all the data records.

Parameters

streamId	StreamId of the record stream to consider.
streamPlayer	(optional): provide a streamPlayer that will receive the records. If provided and a stream player was previously registered to receive records for that stream, only the provided stream player will receive the data.

Returns: True if a config record was read for the given stream.

◆ readFirstConfigurationRecords()

bool vrs::RecordFileReader::readFirstConfigurationRecords ( StreamPlayer * streamPlayer = nullptr )

Helper function: Read every stream's first configuration record. See readFirstConfigurationRecord() for more information.

Parameters

streamPlayer (optional): provide a stream player that will receive the records.

Returns: True if a config record was read for the given stream.

◆ readFirstConfigurationRecordsForType()

bool vrs::RecordFileReader::readFirstConfigurationRecordsForType	(	RecordableTypeId	typeId,
		StreamPlayer *	streamPlayer = `nullptr`
	)

Helper function: Read the first configuration record of all the streams of a particular recordable type. See readFirstConfigurationRecord() for more information.

Parameters

typeId	The RecordableTypeId of the type of device to look for.
streamPlayer	(optional): provide a stream player that will receive the records.

Returns: true if a configuration record was properly read for each matching stream.

◆ readRecord() [1/2]

int vrs::RecordFileReader::readRecord ( const IndexRecord::RecordInfo & recordInfo )

Read a file's record. Preferred way to read records.

Parameters

recordInfo RecordInfo reference of the record to read.

Returns: 0 on success, or a non-zero error code. If there is no StreamPlayer hooked up for the stream, no read operation is done and 0 is returned.

◆ readRecord() [2/2]

int vrs::RecordFileReader::readRecord	(	const IndexRecord::RecordInfo &	recordInfo,
		StreamPlayer *	streamPlayer,
		bool	setupPlayer = `false`
	)

Internal: Read a record using a specific stream player. Prefer using setStreamPlayer and the single parameter version of readRecord(). Avoid calling directly, as it won't work as expected unless the player was properly setup for decoding the stream before.

Parameters

recordInfo	RecordInfo reference of the record to read.
streamPlayer	StreamPlayer object to use for this operation only. The default stream player that might have been setup using setStreamPlayer() will not receive any callback.
setupPlayer	tell if the player should be initialized through its onAttachedToFileReader callback. This must happen at least once per player and per stream, the first time around. This operation can be expensive, so this should be done only once.

Returns: 0 on success or if streamPlayer is null, or a non-zero error code.

◆ setCachingStrategy()

bool vrs::RecordFileReader::setCachingStrategy ( CachingStrategy cachingStrategy )

inline

Set & get the current file handler's Caching strategy. This should be called after opening the file, as open might replace the file handler.

◆ setFileHandler()

void vrs::RecordFileReader::setFileHandler ( std::unique_ptr< FileHandler > fileHandler )

Public yet methods that public API users should probably avoid, because there are better ways to get the same results. Maybe these are useful only for testing or for VRS' internal needs. Provide a different file handler, maybe to stream files off a network storage. By default, RecordFileReader uses DiskFile to read/write files from/to a local disk. Prefer using URIs or FileSpec objects to specify a custom FileHandler when opening a file.

Parameters

fileHandler File handler to access files using a different method than the default DiskFile, for instance, to directly access files off a network location.

◆ setOpenProgressLogger()

void vrs::RecordFileReader::setOpenProgressLogger ( ProgressLogger * progressLogger )

Option to control logging when opening a file.

Parameters

progressLogger a logger implementation, or nullptr, to disable logging.

◆ setStreamPlayer()

void vrs::RecordFileReader::setStreamPlayer	(	StreamId	streamId,
		StreamPlayer *	streamPlayer
	)

Hook a stream player to a specific stream after opening a file and before reading records. The file player does not take ownership of the StreamPlayer. Using the same StreamPlayer instance for multiple streams is supported. So the caller is responsible for deleting the StreamPlayer objects after the file is read. Disconnect the StreamPlayer by passing a nullptr for the stream id.

Parameters

streamId	StreamId to hook the stream player to.
streamPlayer	StreamPlayer to attach.

◆ vrsFilePathToFileSpec()

int vrs::RecordFileReader::vrsFilePathToFileSpec	(	const string &	filePath,
		FileSpec &	outFileSpec,
		bool	checkLocalFile = `false`
	)

static

Convert a path to a FileSpec, including resolution of local chunked files

Parameters

filePath	a local file path, a URI, or a file spec in json format.
outFileSpec	on exit and on success, set to the resulting file spec.
checkLocalFile	only resolve links and look for additional chunks after validating that the local file is a VRS file, by reading the file's header and checking VRS signatures.

Returns: A status code, 0 meaning success.

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

vrs/RecordFileReader.h
vrs/RecordFileReader.cpp

Classes

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ clearStreamPlayers()

◆ closeFile()

◆ getFileChunks()

◆ getFileHandler()

◆ getFirstDataRecordTime()

◆ getFlavor()

◆ getIndex() [1/2]

◆ getIndex() [2/2]

◆ getLastDataRecordTime()

◆ getLastRecord()

◆ getNearestRecordByTime()

◆ getOriginalRecordableTypeName()

◆ getRecord() [1/3]

◆ getRecord() [2/3]

◆ getRecord() [3/3]

◆ getRecordByTime() [1/4]

◆ getRecordByTime() [2/4]

◆ getRecordByTime() [3/4]

◆ getRecordByTime() [4/4]

◆ getRecordCount() [1/3]

◆ getRecordCount() [2/3]

◆ getRecordCount() [3/3]

◆ getRecordFormat()

◆ getRecordFormats()

◆ getRecordIndex()

◆ getRecordSize()

◆ getRecordStreamIndex()

◆ getSerialNumber()

◆ getStreamForFlavor()

◆ getStreamForName()

◆ getStreamForTag()

◆ getStreamForType()

◆ getStreams() [1/2]

◆ getStreams() [2/2]

◆ getStreamsSignature()

◆ getTag() [1/2]

◆ getTag() [2/2]

◆ getTags() [1/2]

◆ getTags() [2/2]

◆ getTotalSourceSize()

◆ hasIndex()

◆ isOpened()

◆ isRecordAvailableOrPrefetch()

◆ isVrsFile() [1/2]

◆ isVrsFile() [2/2]

◆ mightContainAudio()

◆ mightContainImages()

◆ openFile() [1/2]

◆ openFile() [2/2]

◆ prefetchRecordSequence()

◆ purgeFileCache()

◆ readAllRecords()

◆ readFirstConfigurationRecord()

◆ readFirstConfigurationRecords()

◆ readFirstConfigurationRecordsForType()

◆ readRecord() [1/2]

◆ readRecord() [2/2]

◆ setCachingStrategy()

◆ setFileHandler()

◆ setOpenProgressLogger()

◆ setStreamPlayer()

◆ vrsFilePathToFileSpec()