class McapReader

Declaration

class McapReader { /* full declaration omitted */ };

Description

Provides a read interface to an MCAP file.

Declared at: mcap/include/mcap/reader.hpp:375

Method Overview

• public static mcap::Status ParseAttachment(const mcap::Record & record, mcap::Attachment * attachment)
• public static mcap::Status ParseAttachmentIndex(const mcap::Record & record, mcap::AttachmentIndex * attachmentIndex)
• public static mcap::Status ParseChannel(const mcap::Record & record, mcap::Channel * channel)
• public static mcap::Status ParseChunk(const mcap::Record & record, mcap::Chunk * chunk)
• public static mcap::Status ParseChunkIndex(const mcap::Record & record, mcap::ChunkIndex * chunkIndex)
• public static std::optional<Compression> ParseCompression(const std::string_view compression)
• public static mcap::Status ParseDataEnd(const mcap::Record & record, mcap::DataEnd * dataEnd)
• public static mcap::Status ParseFooter(const mcap::Record & record, mcap::Footer * footer)
• public static mcap::Status ParseHeader(const mcap::Record & record, mcap::Header * header)
• public static mcap::Status ParseMessage(const mcap::Record & record, mcap::Message * message)
• public static mcap::Status ParseMessageIndex(const mcap::Record & record, mcap::MessageIndex * messageIndex)
• public static mcap::Status ParseMetadata(const mcap::Record & record, mcap::Metadata * metadata)
• public static mcap::Status ParseMetadataIndex(const mcap::Record & record, mcap::MetadataIndex * metadataIndex)
• public static mcap::Status ParseSchema(const mcap::Record & record, mcap::Schema * schema)
• public static mcap::Status ParseStatistics(const mcap::Record & record, mcap::Statistics * statistics)
• public static mcap::Status ParseSummaryOffset(const mcap::Record & record, mcap::SummaryOffset * summaryOffset)
• public static mcap::Status ReadFooter(mcap::IReadable & reader, uint64_t offset, mcap::Footer * footer)
• public static mcap::Status ReadRecord(mcap::IReadable & reader, uint64_t offset, mcap::Record * record)
• public const std::multimap<std::string, AttachmentIndex> & attachmentIndexes() const
• public std::pair<ByteOffset, ByteOffset> byteRange(mcap::Timestamp startingAt, mcap::Timestamp endingBefore = MaxTime) const
• public mcap::ChannelPtr channel(mcap::ChannelId channelId) const
• public const std::unordered_map<ChannelId, ChannelPtr> channels() const
• public const std::vector<ChunkIndex> & chunkIndexes() const
• public void close()
• public mcap::IReadable * dataSource()
• public const std::optional<Footer> & footer() const
• public const std::optional<Header> & header() const
• public const std::multimap<std::string, MetadataIndex> & metadataIndexes() const
• public mcap::Status open(mcap::IReadable & reader)
• public mcap::Status open(std::string_view filename)
• public mcap::Status open(std::ifstream & stream)
• public mcap::LinearMessageView readMessages(const mcap::ProblemCallback & onProblem, mcap::Timestamp startingAt, mcap::Timestamp endingBefore = MaxTime)
• public mcap::LinearMessageView readMessages()
• public mcap::LinearMessageView readMessages(const mcap::ProblemCallback & onProblem)
• public mcap::LinearMessageView readMessages(const mcap::ReadMessageOptions & options)
• public mcap::LinearMessageView readMessages(mcap::Timestamp startingAt, mcap::Timestamp endingBefore = MaxTime)
• public mcap::LinearMessageView readMessages(const mcap::ProblemCallback & onProblem, const mcap::ReadMessageOptions & options)
• public mcap::Status readSummary(mcap::ReadSummaryMethod method, const mcap::ProblemCallback & onProblem = [](const mcap::Status &) { })
• public mcap::SchemaPtr schema(mcap::SchemaId schemaId) const
• public const std::unordered_map<SchemaId, SchemaPtr> schemas() const
• public const std::optional<Statistics> & statistics() const
• public ~McapReader()

Methods

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

Declared at: mcap/include/mcap/reader.hpp:631

Parameters

const mcap::Record& record

mcap::Attachment* attachment

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

Declared at: mcap/include/mcap/reader.hpp:632

Parameters

const mcap::Record& record

mcap::AttachmentIndex* attachmentIndex

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

Declared at: mcap/include/mcap/reader.hpp:626

Parameters

const mcap::Record& record

mcap::Channel* channel

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

Declared at: mcap/include/mcap/reader.hpp:628

Parameters

const mcap::Record& record

mcap::Chunk* chunk

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

Declared at: mcap/include/mcap/reader.hpp:630

Parameters

const mcap::Record& record

mcap::ChunkIndex* chunkIndex

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

Description

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

Declared at: mcap/include/mcap/reader.hpp:642

Parameters

const std::string_view compression

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

Declared at: mcap/include/mcap/reader.hpp:637

Parameters

const mcap::Record& record

mcap::DataEnd* dataEnd

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

Declared at: mcap/include/mcap/reader.hpp:624

Parameters

const mcap::Record& record

mcap::Footer* footer

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

Declared at: mcap/include/mcap/reader.hpp:623

Parameters

const mcap::Record& record

mcap::Header* header

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

Declared at: mcap/include/mcap/reader.hpp:627

Parameters

const mcap::Record& record

mcap::Message* message

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

Declared at: mcap/include/mcap/reader.hpp:629

Parameters

const mcap::Record& record

mcap::MessageIndex* messageIndex

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

Declared at: mcap/include/mcap/reader.hpp:634

Parameters

const mcap::Record& record

mcap::Metadata* metadata

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

Declared at: mcap/include/mcap/reader.hpp:635

Parameters

const mcap::Record& record

mcap::MetadataIndex* metadataIndex

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

Declared at: mcap/include/mcap/reader.hpp:625

Parameters

const mcap::Record& record

mcap::Schema* schema

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

Declared at: mcap/include/mcap/reader.hpp:633

Parameters

const mcap::Record& record

mcap::Statistics* statistics

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

Declared at: mcap/include/mcap/reader.hpp:636

Parameters

const mcap::Record& record

mcap::SummaryOffset* summaryOffset

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

Declared at: mcap/include/mcap/reader.hpp:621

Parameters

mcap::IReadable& reader

uint64_t offset

mcap::Footer* footer

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

Declared at: mcap/include/mcap/reader.hpp:620

Parameters

mcap::IReadable& reader

uint64_t offset

mcap::Record* record

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

Description

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.

Declared at: mcap/include/mcap/reader.hpp:614

¶std::pair<ByteOffset, ByteOffset> byteRange(
    mcap::Timestamp startingAt,
    mcap::Timestamp endingBefore = MaxTime) const

Description

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.

Declared at: mcap/include/mcap/reader.hpp:546

Parameters

mcap::Timestamp startingAt

Start time in nanoseconds (inclusive).

mcap::Timestamp endingBefore = MaxTime

Optional end time in nanoseconds (exclusive).

Returns

Start and end byte offsets.

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

Description

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.

Declared at: mcap/include/mcap/reader.hpp:586

Parameters

mcap::ChannelId channelId

Channel ID to search for

Returns

ChannelPtr A shared pointer to a Channel record, or nullptr

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

Description

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

Declared at: mcap/include/mcap/reader.hpp:572

¶const std::vector<ChunkIndex>& chunkIndexes()
    const

Description

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

Declared at: mcap/include/mcap/reader.hpp:600

¶void close()

Description

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

Declared at: mcap/include/mcap/reader.hpp:415

¶mcap::IReadable* dataSource()

Description

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

Declared at: mcap/include/mcap/reader.hpp:553

¶const std::optional<Footer>& footer() const

Description

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

Declared at: mcap/include/mcap/reader.hpp:562

¶const std::optional<Header>& header() const

Description

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

Declared at: mcap/include/mcap/reader.hpp:558

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

Description

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.

Declared at: mcap/include/mcap/reader.hpp:607

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

Description

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

Declared at: mcap/include/mcap/reader.hpp:389

Parameters

mcap::IReadable& 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.

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

Description

Opens an MCAP file for reading from a given filename.

Declared at: mcap/include/mcap/reader.hpp:398

Parameters

std::string_view 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.

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

Description

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

Declared at: mcap/include/mcap/reader.hpp:408

Parameters

std::ifstream& 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.

¶mcap::LinearMessageView readMessages(
    const mcap::ProblemCallback& onProblem,
    mcap::Timestamp startingAt,
    mcap::Timestamp endingBefore = MaxTime)

Description

Returns an iterable view with `begin()` and `end()` methods for iterating Messages in the MCAP file. If a non-zero `startingAt` 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.

Declared at: mcap/include/mcap/reader.hpp:505

Parameters

const mcap::ProblemCallback& 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.

mcap::Timestamp startingAt

Start time in nanoseconds (inclusive). Messages before this time will not be returned.

mcap::Timestamp endingBefore = MaxTime

Optional end time in nanoseconds (exclusive). Messages equal to or after this time will not be returned.

¶mcap::LinearMessageView readMessages()

Description

Returns an iterable view with `begin()` and `end()` methods for iterating all Messages in the MCAP file. If the reader has not been opened, the returned view is empty and its `status()` reports `NotOpen`. Problems encountered while iterating are also recorded on the view, so `status()` can be checked after iteration to find out whether the read completed without problems. A record that cannot be read stops the iteration, in either read order; messages after it are not returned.

Declared at: mcap/include/mcap/reader.hpp:437

¶mcap::LinearMessageView readMessages(
    const mcap::ProblemCallback& onProblem)

Description

Returns an iterable view with `begin()` and `end()` methods for iterating all Messages in the MCAP file. If the reader has not been opened, the returned view is empty and its `status()` reports `NotOpen`. Problems encountered while iterating are delivered to `onProblem` and also recorded on the view, so `status()` can be checked after iteration to find out whether the read completed without problems. A record that cannot be read stops the iteration, in either read order; messages after it are not returned.

Declared at: mcap/include/mcap/reader.hpp:452

Parameters

const mcap::ProblemCallback& 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.

¶mcap::LinearMessageView readMessages(
    const mcap::ReadMessageOptions& options)

Description

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. Problems are ignored, including invalid `options` (see ReadMessageOptions::validate()), which yield an empty view; use readMessages(onProblem, options) to be notified of them.

Declared at: mcap/include/mcap/reader.hpp:464

Parameters

const mcap::ReadMessageOptions& options

Options controlling which messages are yielded and in what order.

¶mcap::LinearMessageView readMessages(
    mcap::Timestamp startingAt,
    mcap::Timestamp endingBefore = MaxTime)

Description

Returns an iterable view with `begin()` and `end()` methods for iterating Messages in the MCAP file. If a non-zero `startingAt` 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.

Declared at: mcap/include/mcap/reader.hpp:482

Parameters

mcap::Timestamp startingAt

Start time in nanoseconds (inclusive). Messages before this time will not be returned.

mcap::Timestamp endingBefore = MaxTime

Optional end time in nanoseconds (exclusive). Messages equal to or after this time will not be returned.

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

Description

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. If the reader has not been opened, the returned view is empty and its `status()` reports `NotOpen`. If `options` is not valid, such as a time range whose end is before its start, the returned view is empty and its `status()` reports `InvalidMessageReadOptions`; `onProblem` receives the same status. Problems encountered while iterating are delivered to `onProblem` and also recorded on the view, so `status()` can be checked after iteration to find out whether the read completed without problems. A record that cannot be read stops the iteration, in either read order; messages after it are not returned.

Declared at: mcap/include/mcap/reader.hpp:528

Parameters

const mcap::ProblemCallback& 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.

const mcap::ReadMessageOptions& options

Options controlling which messages are yielded and in what order.

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

Description

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.

Declared at: mcap/include/mcap/reader.hpp:424

Parameters

mcap::ReadSummaryMethod method

const mcap::ProblemCallback& onProblem = [](const mcap::Status &) { }

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

Description

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.

Declared at: mcap/include/mcap/reader.hpp:594

Parameters

mcap::SchemaId schemaId

Schema ID to search for

Returns

SchemaPtr A shared pointer to a Schema record, or nullptr

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

Description

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

Declared at: mcap/include/mcap/reader.hpp:577

¶const std::optional<Statistics>& statistics()
    const

Description

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

Declared at: mcap/include/mcap/reader.hpp:566

¶~McapReader()

Declared at: mcap/include/mcap/reader.hpp:377