Class McapReader

Class Documentation

class McapReader

Provides a read interface to an MCAP file.

Public Functions

~McapReader()
Status 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.

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

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

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.

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.

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.

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.

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.

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.

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.

Parameters:

channelId – Channel ID to search for

Returns:

ChannelPtr A shared pointer to a Channel record, or 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.

Parameters:

schemaId – Schema ID to search for

Returns:

SchemaPtr A shared pointer to a Schema record, or 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.

Public Static 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.