Detailed Description

Provides a read interface to an MCAP file.

Definition at line 275 of file reader.hpp.

#include <reader.hpp>

Public Member Functions
	~McapReader ()

Status	open (IReadable &reader)
	Opens an MCAP file for reading from an already constructed IReadable implementation.

Status	open (std::string_view filename)
	Opens an MCAP file for reading from a given filename.

Status	open (std::ifstream &stream)
	Opens an MCAP file for reading from a std::ifstream input file stream.

void	close ()
	Closes the MCAP file, clearing any internal data structures and state and dropping the data source reference.

Status	readSummary (ReadSummaryMethod method, const ProblemCallback &onProblem=[](const Status &) {})
	Read and parse the Summary section at the end of the MCAP file, if available. This will populate internal indexes to allow for efficient summarization and random access. This method will automatically be called upon requesting summary data or first seek if Summary section parsing is allowed by the configuration options.

LinearMessageView	readMessages (Timestamp startTime=0, Timestamp endTime=MaxTime)
	Returns an iterable view with `begin()` and `end()` methods for iterating Messages in the MCAP file. If a non-zero `startTime` is provided, this will first parse the Summary section (by calling `readSummary()`) if allowed by the configuration options and it has not been parsed yet.

LinearMessageView	readMessages (const ProblemCallback &onProblem, Timestamp startTime=0, Timestamp endTime=MaxTime)
	Returns an iterable view with `begin()` and `end()` methods for iterating Messages in the MCAP file. If a non-zero `startTime` is provided, this will first parse the Summary section (by calling `readSummary()`) if allowed by the configuration options and it has not been parsed yet.

LinearMessageView	readMessages (const ProblemCallback &onProblem, const ReadMessageOptions &options)
	Returns an iterable view with `begin()` and `end()` methods for iterating Messages in the MCAP file. Uses the options from `options` to select the messages that are yielded.

std::pair< ByteOffset, ByteOffset >	byteRange (Timestamp startTime, Timestamp endTime=MaxTime) const
	Returns starting and ending byte offsets that must be read to iterate all messages in the given time range. If `readSummary()` has been successfully called and the recording contains Chunk records, this range will be narrowed to Chunk records that contain messages in the given time range. Otherwise, this range will be the entire Data section if the Data End record has been found or the entire file otherwise.

IReadable *	dataSource ()
	Returns a pointer to the IReadable data source backing this reader. Will return nullptr if the reader is not open.

const std::optional< Header > &	header () const
	Returns the parsed Header record, if it has been encountered.

const std::optional< Footer > &	footer () const
	Returns the parsed Footer record, if it has been encountered.

const std::optional< Statistics > &	statistics () const
	Returns the parsed Statistics record, if it has been encountered.

const std::unordered_map< ChannelId, ChannelPtr >	channels () const
	Returns all of the parsed Channel records. Call `readSummary()` first to fully populate this data structure.

const std::unordered_map< SchemaId, SchemaPtr >	schemas () const
	Returns all of the parsed Schema records. Call `readSummary()` first to fully populate this data structure.

ChannelPtr	channel (ChannelId channelId) const
	Look up a Channel record by channel ID. If the Channel has not been encountered yet or does not exist in the file, this will return nullptr.

SchemaPtr	schema (SchemaId schemaId) const
	Look up a Schema record by schema ID. If the Schema has not been encountered yet or does not exist in the file, this will return nullptr.

const std::vector< ChunkIndex > &	chunkIndexes () const
	Returns all of the parsed ChunkIndex records. Call `readSummary()` first to fully populate this data structure.

const std::multimap< std::string, MetadataIndex > &	metadataIndexes () const
	Returns all of the parsed MetadataIndex records. Call `readSummary()` first to fully populate this data structure. The multimap's keys are the `name` field from each indexed Metadata.

const std::multimap< std::string, AttachmentIndex > &	attachmentIndexes () const
	Returns all of the parsed AttachmentIndex records. Call `readSummary()` first to fully populate this data structure. The multimap's keys are the `name` field from each indexed Attachment.

Static Public Member Functions
static Status	ReadRecord (IReadable &reader, uint64_t offset, Record *record)

static Status	ReadFooter (IReadable &reader, uint64_t offset, Footer *footer)

static Status	ParseHeader (const Record &record, Header *header)

static Status	ParseFooter (const Record &record, Footer *footer)

static Status	ParseSchema (const Record &record, Schema *schema)

static Status	ParseChannel (const Record &record, Channel *channel)

static Status	ParseMessage (const Record &record, Message *message)

static Status	ParseChunk (const Record &record, Chunk *chunk)

static Status	ParseMessageIndex (const Record &record, MessageIndex *messageIndex)

static Status	ParseChunkIndex (const Record &record, ChunkIndex *chunkIndex)

static Status	ParseAttachment (const Record &record, Attachment *attachment)

static Status	ParseAttachmentIndex (const Record &record, AttachmentIndex *attachmentIndex)

static Status	ParseStatistics (const Record &record, Statistics *statistics)

static Status	ParseMetadata (const Record &record, Metadata *metadata)

static Status	ParseMetadataIndex (const Record &record, MetadataIndex *metadataIndex)

static Status	ParseSummaryOffset (const Record &record, SummaryOffset *summaryOffset)

static Status	ParseDataEnd (const Record &record, DataEnd *dataEnd)

static std::optional< Compression >	ParseCompression (const std::string_view compression)
	Converts a compression string ("", "zstd", "lz4") to the Compression enum.

Private Types
using	ChunkInterval = internal::Interval< ByteOffset, ChunkIndex >

Private Member Functions
void	reset_ ()

Status	readSummarySection_ (IReadable &reader)

Status	readSummaryFromScan_ (IReadable &reader)

Private Attributes
friend	LinearMessageView

IReadable *	input_ = nullptr

std::FILE *	file_ = nullptr

std::unique_ptr< FileReader >	fileInput_

std::unique_ptr< FileStreamReader >	fileStreamInput_

std::optional< Header >	header_

std::optional< Footer >	footer_

std::optional< Statistics >	statistics_

std::vector< ChunkIndex >	chunkIndexes_

internal::IntervalTree< ByteOffset, ChunkIndex >	chunkRanges_

std::multimap< std::string, AttachmentIndex >	attachmentIndexes_

std::multimap< std::string, MetadataIndex >	metadataIndexes_

std::unordered_map< SchemaId, SchemaPtr >	schemas_

std::unordered_map< ChannelId, ChannelPtr >	channels_

ByteOffset	dataStart_ = 0

ByteOffset	dataEnd_ = EndOffset

bool	parsedSummary_ = false

Member Typedef Documentation

◆ ChunkInterval

using mcap::McapReader::ChunkInterval = internal::Interval<ByteOffset, ChunkIndex>

private

Definition at line 478 of file reader.hpp.

Constructor & Destructor Documentation

◆ ~McapReader()

mcap::McapReader::~McapReader ( )

Definition at line 269 of file reader.inl.

Member Function Documentation

◆ attachmentIndexes()

const std::multimap< std::string, AttachmentIndex > & mcap::McapReader::attachmentIndexes ( ) const

Returns all of the parsed AttachmentIndex records. Call readSummary() first to fully populate this data structure. The multimap's keys are the name field from each indexed Attachment.

Definition at line 650 of file reader.inl.

◆ byteRange()

std::pair< ByteOffset, ByteOffset > mcap::McapReader::byteRange	(	Timestamp	startTime,
		Timestamp	endTime = `MaxTime`
	)		const

Returns starting and ending byte offsets that must be read to iterate all messages in the given time range. If readSummary() has been successfully called and the recording contains Chunk records, this range will be narrowed to Chunk records that contain messages in the given time range. Otherwise, this range will be the entire Data section if the Data End record has been found or the entire file otherwise.

This method is automatically used by readMessages(), and only needs to be called directly if the caller is manually constructing an iterator.

Parameters

startTime	Start time in nanoseconds.
endTime	Optional end time in nanoseconds.

Returns: Start and end byte offsets.

Definition at line 587 of file reader.inl.

◆ channel()

ChannelPtr mcap::McapReader::channel ( ChannelId channelId ) const

Look up a Channel record by channel ID. If the Channel has not been encountered yet or does not exist in the file, this will return nullptr.

Parameters

channelId Channel ID to search for

Returns: ChannelPtr A shared pointer to a Channel record, or nullptr

Definition at line 632 of file reader.inl.

◆ channels()

const std::unordered_map< ChannelId, ChannelPtr > mcap::McapReader::channels ( ) const

Returns all of the parsed Channel records. Call readSummary() first to fully populate this data structure.

Definition at line 624 of file reader.inl.

◆ chunkIndexes()

const std::vector< ChunkIndex > & mcap::McapReader::chunkIndexes ( ) const

Returns all of the parsed ChunkIndex records. Call readSummary() first to fully populate this data structure.

Definition at line 642 of file reader.inl.

◆ close()

void mcap::McapReader::close ( )

Closes the MCAP file, clearing any internal data structures and state and dropping the data source reference.

Definition at line 345 of file reader.inl.

◆ dataSource()

IReadable * mcap::McapReader::dataSource ( )

Returns a pointer to the IReadable data source backing this reader. Will return nullptr if the reader is not open.

Definition at line 608 of file reader.inl.

◆ footer()

const std::optional< Footer > & mcap::McapReader::footer ( ) const

Returns the parsed Footer record, if it has been encountered.

Definition at line 616 of file reader.inl.

◆ header()

const std::optional< Header > & mcap::McapReader::header ( ) const

Returns the parsed Header record, if it has been encountered.

Definition at line 612 of file reader.inl.

◆ metadataIndexes()

const std::multimap< std::string, MetadataIndex > & mcap::McapReader::metadataIndexes ( ) const

Returns all of the parsed MetadataIndex records. Call readSummary() first to fully populate this data structure. The multimap's keys are the name field from each indexed Metadata.

Definition at line 646 of file reader.inl.

◆ open() [1/3]

Status mcap::McapReader::open ( IReadable & reader )

Opens an MCAP file for reading from an already constructed IReadable implementation.

Parameters

reader An implementation of the IReader interface that provides raw MCAP data.

Returns: Status StatusCode::Success on success. If a non-success Status is returned, the data source is not considered open and McapReader is not usable until open() is called and a success response is returned.

Definition at line 273 of file reader.inl.

◆ open() [2/3]

Status mcap::McapReader::open ( std::ifstream & stream )

Opens an MCAP file for reading from a std::ifstream input file stream.

Parameters

stream Input file stream to read MCAP data from.

Returns: Status StatusCode::Success on success. If a non-success Status is returned, the file is not considered open and McapReader is not usable until open() is called and a success response is returned.

Definition at line 340 of file reader.inl.

◆ open() [3/3]

Status mcap::McapReader::open ( std::string_view filename )

Opens an MCAP file for reading from a given filename.

Parameters

filename Filename to open.

Returns: Status StatusCode::Success on success. If a non-success Status is returned, the data source is not considered open and McapReader is not usable until open() is called and a success response is returned.

Definition at line 325 of file reader.inl.

◆ ParseAttachment()

Status mcap::McapReader::ParseAttachment	(	const Record &	record,
		Attachment *	attachment
	)

static

Definition at line 993 of file reader.inl.

◆ ParseAttachmentIndex()

Status mcap::McapReader::ParseAttachmentIndex	(	const Record &	record,
		AttachmentIndex *	attachmentIndex
	)

static

Definition at line 1060 of file reader.inl.

◆ ParseChannel()

Status mcap::McapReader::ParseChannel	(	const Record &	record,
		Channel *	channel
	)

static

Definition at line 806 of file reader.inl.

◆ ParseChunk()

Status mcap::McapReader::ParseChunk	(	const Record &	record,
		Chunk *	chunk
	)

static

Definition at line 864 of file reader.inl.

◆ ParseChunkIndex()

Status mcap::McapReader::ParseChunkIndex	(	const Record &	record,
		ChunkIndex *	chunkIndex
	)

static

Definition at line 931 of file reader.inl.

◆ ParseCompression()

std::optional< Compression > mcap::McapReader::ParseCompression ( const std::string_view compression )

static

Converts a compression string ("", "zstd", "lz4") to the Compression enum.

Definition at line 1207 of file reader.inl.

◆ ParseDataEnd()

Status mcap::McapReader::ParseDataEnd	(	const Record &	record,
		DataEnd *	dataEnd
	)

static

Definition at line 1194 of file reader.inl.

◆ ParseFooter()

Status mcap::McapReader::ParseFooter	(	const Record &	record,
		Footer *	footer
	)

static

Definition at line 752 of file reader.inl.

◆ ParseHeader()

Status mcap::McapReader::ParseHeader	(	const Record &	record,
		Header *	header
	)

static

Definition at line 729 of file reader.inl.

◆ ParseMessage()

Status mcap::McapReader::ParseMessage	(	const Record &	record,
		Message *	message
	)

static

Definition at line 846 of file reader.inl.

◆ ParseMessageIndex()

Status mcap::McapReader::ParseMessageIndex	(	const Record &	record,
		MessageIndex *	messageIndex
	)

static

Definition at line 904 of file reader.inl.

◆ ParseMetadata()

Status mcap::McapReader::ParseMetadata	(	const Record &	record,
		Metadata *	metadata
	)

static

Definition at line 1132 of file reader.inl.

◆ ParseMetadataIndex()

Status mcap::McapReader::ParseMetadataIndex	(	const Record &	record,
		MetadataIndex *	metadataIndex
	)

static

Definition at line 1157 of file reader.inl.

◆ ParseSchema()

Status mcap::McapReader::ParseSchema	(	const Record &	record,
		Schema *	schema
	)

static

Definition at line 768 of file reader.inl.

◆ ParseStatistics()

Status mcap::McapReader::ParseStatistics	(	const Record &	record,
		Statistics *	statistics
	)

static

Definition at line 1094 of file reader.inl.

◆ ParseSummaryOffset()

Status mcap::McapReader::ParseSummaryOffset	(	const Record &	record,
		SummaryOffset *	summaryOffset
	)

static

Definition at line 1178 of file reader.inl.

◆ ReadFooter()

Status mcap::McapReader::ReadFooter	(	IReadable &	reader,
		uint64_t	offset,
		Footer *	footer
	)

static

Definition at line 694 of file reader.inl.

◆ readMessages() [1/3]

LinearMessageView mcap::McapReader::readMessages	(	const ProblemCallback &	onProblem,
		const ReadMessageOptions &	options
	)

Returns an iterable view with begin() and end() methods for iterating Messages in the MCAP file. Uses the options from options to select the messages that are yielded.

Definition at line 575 of file reader.inl.

◆ readMessages() [2/3]

LinearMessageView mcap::McapReader::readMessages	(	const ProblemCallback &	onProblem,
		Timestamp	startTime = `0`,
		Timestamp	endTime = `MaxTime`
	)

Returns an iterable view with begin() and end() methods for iterating Messages in the MCAP file. If a non-zero startTime is provided, this will first parse the Summary section (by calling readSummary()) if allowed by the configuration options and it has not been parsed yet.

Parameters

onProblem	A callback that will be called when a parsing error occurs. Problems can either be recoverable, indicating some data could not be read, or non-recoverable, stopping the iteration.
startTime	Optional start time in nanoseconds. Messages before this time will not be returned.
endTime	Optional end time in nanoseconds. Messages equal to or after this time will not be returned.

Definition at line 567 of file reader.inl.

◆ readMessages() [3/3]

LinearMessageView mcap::McapReader::readMessages	(	Timestamp	startTime = `0`,
		Timestamp	endTime = `MaxTime`
	)

Returns an iterable view with begin() and end() methods for iterating Messages in the MCAP file. If a non-zero startTime is provided, this will first parse the Summary section (by calling readSummary()) if allowed by the configuration options and it has not been parsed yet.

Parameters

startTime	Optional start time in nanoseconds. Messages before this time will not be returned.
endTime	Optional end time in nanoseconds. Messages equal to or after this time will not be returned.

Definition at line 562 of file reader.inl.

◆ ReadRecord()

Status mcap::McapReader::ReadRecord	(	IReadable &	reader,
		uint64_t	offset,
		Record *	record
	)

static

Definition at line 654 of file reader.inl.

◆ readSummary()

Status mcap::McapReader::readSummary	(	ReadSummaryMethod	method,
		const ProblemCallback &	onProblem = `[](const Status&) {}`
	)

Read and parse the Summary section at the end of the MCAP file, if available. This will populate internal indexes to allow for efficient summarization and random access. This method will automatically be called upon requesting summary data or first seek if Summary section parsing is allowed by the configuration options.

Definition at line 369 of file reader.inl.

◆ readSummaryFromScan_()

Status mcap::McapReader::readSummaryFromScan_ ( IReadable & reader )

private

Definition at line 487 of file reader.inl.

◆ readSummarySection_()

Status mcap::McapReader::readSummarySection_ ( IReadable & reader )

private

Definition at line 413 of file reader.inl.

◆ reset_()

void mcap::McapReader::reset_ ( )

private

Definition at line 356 of file reader.inl.

◆ schema()

SchemaPtr mcap::McapReader::schema ( SchemaId schemaId ) const

Look up a Schema record by schema ID. If the Schema has not been encountered yet or does not exist in the file, this will return nullptr.

Parameters

schemaId Schema ID to search for

Returns: SchemaPtr A shared pointer to a Schema record, or nullptr

Definition at line 637 of file reader.inl.

◆ schemas()

const std::unordered_map< SchemaId, SchemaPtr > mcap::McapReader::schemas ( ) const

Returns all of the parsed Schema records. Call readSummary() first to fully populate this data structure.

Definition at line 628 of file reader.inl.

◆ statistics()

const std::optional< Statistics > & mcap::McapReader::statistics ( ) const

Returns the parsed Statistics record, if it has been encountered.

Definition at line 620 of file reader.inl.

Member Data Documentation

◆ attachmentIndexes_

std::multimap<std::string, AttachmentIndex> mcap::McapReader::attachmentIndexes_

private

Definition at line 490 of file reader.hpp.

◆ channels_

std::unordered_map<ChannelId, ChannelPtr> mcap::McapReader::channels_

private

Definition at line 493 of file reader.hpp.

◆ chunkIndexes_

std::vector<ChunkIndex> mcap::McapReader::chunkIndexes_

private

Definition at line 488 of file reader.hpp.

◆ chunkRanges_

internal::IntervalTree<ByteOffset, ChunkIndex> mcap::McapReader::chunkRanges_

private

Definition at line 489 of file reader.hpp.

◆ dataEnd_

ByteOffset mcap::McapReader::dataEnd_ = EndOffset

private

Definition at line 495 of file reader.hpp.

◆ dataStart_

ByteOffset mcap::McapReader::dataStart_ = 0

private

Definition at line 494 of file reader.hpp.

◆ file_

std::FILE* mcap::McapReader::file_ = nullptr

private

Definition at line 482 of file reader.hpp.

◆ fileInput_

std::unique_ptr<FileReader> mcap::McapReader::fileInput_

private

Definition at line 483 of file reader.hpp.

◆ fileStreamInput_

std::unique_ptr<FileStreamReader> mcap::McapReader::fileStreamInput_

private

Definition at line 484 of file reader.hpp.

◆ footer_

std::optional<Footer> mcap::McapReader::footer_

private

Definition at line 486 of file reader.hpp.

◆ header_

std::optional<Header> mcap::McapReader::header_

private

Definition at line 485 of file reader.hpp.

◆ input_

IReadable* mcap::McapReader::input_ = nullptr

private

Definition at line 481 of file reader.hpp.

◆ LinearMessageView

friend mcap::McapReader::LinearMessageView

private

Definition at line 479 of file reader.hpp.

◆ metadataIndexes_

std::multimap<std::string, MetadataIndex> mcap::McapReader::metadataIndexes_

private

Definition at line 491 of file reader.hpp.

◆ parsedSummary_

bool mcap::McapReader::parsedSummary_ = false

private

Definition at line 496 of file reader.hpp.

◆ schemas_

std::unordered_map<SchemaId, SchemaPtr> mcap::McapReader::schemas_

private

Definition at line 492 of file reader.hpp.

◆ statistics_

std::optional<Statistics> mcap::McapReader::statistics_

private

Definition at line 487 of file reader.hpp.

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

Detailed Description

Public Member Functions

Static Public Member Functions

Private Types

Private Member Functions

Private Attributes

Member Typedef Documentation

◆ ChunkInterval

Constructor & Destructor Documentation

◆ ~McapReader()

Member Function Documentation

◆ attachmentIndexes()

◆ byteRange()

◆ channel()

◆ channels()

◆ chunkIndexes()

◆ close()

◆ dataSource()

◆ footer()

◆ header()

◆ metadataIndexes()

◆ open() [1/3]

◆ open() [2/3]

◆ open() [3/3]

◆ ParseAttachment()

◆ ParseAttachmentIndex()

◆ ParseChannel()

◆ ParseChunk()

◆ ParseChunkIndex()

◆ ParseCompression()

◆ ParseDataEnd()

◆ ParseFooter()

◆ ParseHeader()

◆ ParseMessage()

◆ ParseMessageIndex()

◆ ParseMetadata()

◆ ParseMetadataIndex()

◆ ParseSchema()

◆ ParseStatistics()

◆ ParseSummaryOffset()

◆ ReadFooter()

◆ readMessages() [1/3]

◆ readMessages() [2/3]

◆ readMessages() [3/3]

◆ ReadRecord()

◆ readSummary()

◆ readSummaryFromScan_()

◆ readSummarySection_()

◆ reset_()

◆ schema()

◆ schemas()

◆ statistics()

Member Data Documentation

◆ attachmentIndexes_

◆ channels_

◆ chunkIndexes_

◆ chunkRanges_

◆ dataEnd_

◆ dataStart_

◆ file_

◆ fileInput_

◆ fileStreamInput_

◆ footer_

◆ header_

◆ input_

◆ LinearMessageView

◆ metadataIndexes_

◆ parsedSummary_

◆ schemas_

◆ statistics_