Provides a read interface to an MCAP file. More...

#include <reader.hpp>

Public Member Functions
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. More...

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. More...

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

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

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

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

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

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

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. More...

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

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

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

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. More...

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. More...

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. More...

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. More...

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. More...

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

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

	~McapReader ()

Static Public Member Functions
static Status	ParseAttachment (const Record &record, Attachment *attachment)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

static Status	ReadRecord (IReadable &reader, uint64_t offset, Record *record)

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

Private Member Functions
Status	readSummaryFromScan_ (IReadable &reader)

Status	readSummarySection_ (IReadable &reader)

void	reset_ ()

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

std::unordered_map< ChannelId, ChannelPtr >	channels_

std::vector< ChunkIndex >	chunkIndexes_

internal::IntervalTree< ByteOffset, ChunkIndex >	chunkRanges_

ByteOffset	dataEnd_ = EndOffset

ByteOffset	dataStart_ = 0

Timestamp	endTime_ = 0

std::FILE *	file_ = nullptr

std::unique_ptr< FileReader >	fileInput_

std::unique_ptr< FileStreamReader >	fileStreamInput_

std::optional< Footer >	footer_

std::optional< Header >	header_

IReadable *	input_ = nullptr

friend	LinearMessageView

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

bool	parsedSummary_ = false

std::unordered_map< SchemaId, SchemaPtr >	schemas_

Timestamp	startTime_ = 0

std::optional< Statistics >	statistics_

Detailed Description

Provides a read interface to an MCAP file.

Definition at line 271 of file reader.hpp.

Member Typedef Documentation

◆ ChunkInterval

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

private

Definition at line 467 of file reader.hpp.

Constructor & Destructor Documentation

◆ ~McapReader()

mcap::McapReader::~McapReader ( )

Member Function Documentation

◆ 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.

◆ 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

◆ 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.

◆ 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.

◆ close()

void mcap::McapReader::close ( )

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

◆ 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.

◆ footer()

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

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

◆ header()

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

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

◆ 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.

◆ 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.

◆ 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.

◆ 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.

◆ ParseAttachment()

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

static

◆ ParseAttachmentIndex()

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

static

◆ ParseChannel()

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

static

◆ ParseChunk()

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

static

◆ ParseChunkIndex()

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

static

◆ ParseCompression()

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

static

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

◆ ParseDataEnd()

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

static

◆ ParseFooter()

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

static

◆ ParseHeader()

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

static

◆ ParseMessage()

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

static

◆ ParseMessageIndex()

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

static

◆ ParseMetadata()

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

static

◆ ParseMetadataIndex()

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

static

◆ ParseSchema()

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

static

◆ ParseStatistics()

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

static

◆ ParseSummaryOffset()

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

static

◆ ReadFooter()

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

static

◆ 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.

◆ 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.

◆ 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.

◆ ReadRecord()

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

static

◆ 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.

◆ readSummaryFromScan_()

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

private

◆ readSummarySection_()

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

private

◆ reset_()

void mcap::McapReader::reset_ ( )

private

◆ 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

◆ 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.

◆ statistics()

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

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

Member Data Documentation

◆ attachmentIndexes_

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

private

Definition at line 479 of file reader.hpp.

◆ channels_

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

private

Definition at line 482 of file reader.hpp.

◆ chunkIndexes_

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

private

Definition at line 477 of file reader.hpp.

◆ chunkRanges_

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

private

Definition at line 478 of file reader.hpp.

◆ dataEnd_

ByteOffset mcap::McapReader::dataEnd_ = EndOffset

private

Definition at line 484 of file reader.hpp.

◆ dataStart_

ByteOffset mcap::McapReader::dataStart_ = 0

private

Definition at line 483 of file reader.hpp.

◆ endTime_

Timestamp mcap::McapReader::endTime_ = 0

private

Definition at line 486 of file reader.hpp.

◆ file_

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

private

Definition at line 471 of file reader.hpp.

◆ fileInput_

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

private

Definition at line 472 of file reader.hpp.

◆ fileStreamInput_

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

private

Definition at line 473 of file reader.hpp.

◆ footer_

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

private

Definition at line 475 of file reader.hpp.

◆ header_

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

private

Definition at line 474 of file reader.hpp.

◆ input_

IReadable* mcap::McapReader::input_ = nullptr

private

Definition at line 470 of file reader.hpp.

◆ LinearMessageView

friend mcap::McapReader::LinearMessageView

private

Definition at line 468 of file reader.hpp.

◆ metadataIndexes_

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

private

Definition at line 480 of file reader.hpp.

◆ parsedSummary_

bool mcap::McapReader::parsedSummary_ = false

private

Definition at line 487 of file reader.hpp.

◆ schemas_

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

private

Definition at line 481 of file reader.hpp.

◆ startTime_

Timestamp mcap::McapReader::startTime_ = 0

private

Definition at line 485 of file reader.hpp.

◆ statistics_

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

private

Definition at line 476 of file reader.hpp.

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

reader.hpp

Public Member Functions

Static Public Member Functions

Private Types

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ ChunkInterval

Constructor & Destructor Documentation

◆ ~McapReader()

Member Function Documentation

◆ 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_

◆ endTime_

◆ file_

◆ fileInput_

◆ fileStreamInput_

◆ footer_

◆ header_

◆ input_

◆ LinearMessageView

◆ metadataIndexes_

◆ parsedSummary_

◆ schemas_

◆ startTime_

◆ statistics_