MCAPTraceFileWriter

class MCAPTraceFileWriter : public osi3::TraceFileWriter

MCAP format implementation of the trace file writer.

Handles writing OSI messages to MCAP format files with support for channels, schemas, and metadata.

Note

Thread Safety: Not thread-safe. External synchronization required for concurrent access.

Public Functions

~MCAPTraceFileWriter() override

Destructor, closes the file if still open.

virtual bool Open(const std::filesystem::path &file_path) override

Opens a trace file for writing using default MCAP options.

Parameters:

file_path – Path to the file to be created/opened

Returns:

true if successful, false otherwise

bool Open(const std::filesystem::path &file_path, const mcap::McapWriterOptions &options)

Opens a file for writing with additional options.

This alternative opening method allows specifying additional options like compression and chunk size.

Parameters:

• file_path – Path to the file to be created/opened

• options – Options for the MCAP writer

Returns:

true if successful, false otherwise

template<typename T>
bool WriteMessage(const T &top_level_message, const std::string &topic)

Writes a protobuf message to the file.

Template Parameters:

T – Type of the protobuf message

Parameters:

• top_level_message – The message to write

• topic – Optional topic name for the message

Returns:

true if successful, false otherwise

bool AddFileMetadata(const mcap::Metadata &metadata)

Adds metadata for the trace file.

Parameters:

metadata – MCAP metadata object

Returns:

true if successful, false otherwise

bool AddFileMetadata(const std::string &name, const std::unordered_map<std::string, std::string> &metadata_entries)

Adds metadata for the trace file.

This overload allows for specification of metadata entries by name and key-value pairs

Parameters:

• name – Name of the metadata entry

• metadata_entries – Key-value pairs of metadata

Returns:

true if successful, false otherwise

uint16_t AddChannel(const std::string &topic, const google::protobuf::Descriptor *descriptor, std::unordered_map<std::string, std::string> channel_metadata = {})

Adds a new channel to the MCAP file.

Parameters:

• topic – Name of the channel/topic

• descriptor – Protobuf descriptor for the message type

• channel_metadata – Additional metadata for the channel (passed by value; OSI metadata is added in-place)

Returns:

Channel ID for the newly created channel

virtual void Close() override

Closes the trace file and finalizes MCAP output.

inline mcap::McapWriter *GetMcapWriter()

Gets the underlying MCAP writer instance.

This function can be useful for advanced operations like adding non-OSI message which requires direct access to underlying the MCAP writer.

Returns:

Pointer to the internal McapWriter object

Public Static Functions

static mcap::Metadata PrepareRequiredFileMetadata()

Prepares the required (by OSI spec.) metadata for the MCAP trace file.

This function initializes and populates an mcap::Metadata object with information specific to the OSI (Open Simulation Interface) trace format and its versioning. The metadata includes details about the OSI version, protobuf version.

Returns:

mcap::Metadata Object containing the necessary metadata for the MCAP trace file.

static std::string GetCurrentTimeAsString()

Helper function that returns the current time as a formatted string.

This helper function is intended to be used when creating metadata entries that require timestamps, particularly for the OSI-specification mandatory metadata. The timestamp format follows the OSI specification for zero_time and creation_time metadata.

Returns:

Current timestamp as string in required format