The EbmlElement class helps to parse EBML files such as Matroska files. More...

#include <ebmlelement.h>

Inheritance diagram for TagParser::EbmlElement:

Collaboration diagram for TagParser::EbmlElement:

Public Member Functions
	EbmlElement (MatroskaContainer &container, std::uint64_t startOffset)
	Constructs a new top level element with the specified container at the specified startOffset.

std::string	idToString () const
	Converts the specified EBML ID to a printable string.

bool	isParent () const
	Returns an indication whether the element is a parent element.

bool	isPadding () const
	Returns an indication whether the element is considered as padding.

std::uint64_t	firstChildOffset () const
	Returns the offset of the first child of the element.

std::string	readString ()
	Reads the content of the element as string.

std::uint64_t	readUInteger ()
	Reads the content of the element as unsigned integer.

double	readFloat ()
	Reads the content of the element as float.

Public Member Functions inherited from TagParser::GenericFileElement< EbmlElement >
	GenericFileElement (ContainerType &container, std::uint64_t startOffset)

	GenericFileElement (EbmlElement &parent, std::uint64_t startOffset)
	Constructs a new sub level file element with the specified parent at the specified startOffset.

	GenericFileElement (ContainerType &container, std::uint64_t startOffset, std::uint64_t maxSize)

	GenericFileElement (const GenericFileElement &other)=delete

	GenericFileElement (GenericFileElement &other)=delete

GenericFileElement &	operator= (const GenericFileElement &other)=delete

ContainerType &	container ()
	Returns the related container.

const ContainerType &	container () const
	Returns the related container.

std::iostream &	stream ()
	Returns the related stream.

CppUtilities::BinaryReader &	reader ()
	Returns the related BinaryReader.

CppUtilities::BinaryWriter &	writer ()
	Returns the related BinaryWriter.

std::uint64_t	startOffset () const
	Returns the start offset in the related stream.

std::uint64_t	relativeStartOffset () const
	Returns the offset of the element in its parent or - if it is a top-level element - in the related stream.

const IdentifierType &	id () const
	Returns the element ID.

std::string	idToString () const
	Returns a printable string representation of the element ID.

std::uint32_t	idLength () const
	Returns the length of the id denotation in byte.

std::uint32_t	headerSize () const
	Returns the header size of the element in byte.

DataSizeType	dataSize () const
	Returns the data size of the element in byte.

std::uint32_t	sizeLength () const
	Returns the length of the size denotation of the element in byte.

std::uint64_t	dataOffset () const
	Returns the data offset of the element in the related stream.

std::uint64_t	totalSize () const
	Returns the total size of the element.

std::uint64_t	endOffset () const
	Returns the offset of the first byte which doesn't belong to this element anymore.

std::uint64_t	maxTotalSize () const
	Returns maximum total size.

std::uint8_t	level () const
	Returns how deep the element is nested (0 for top-level elements, 1 for children of top-level elements, ...).

EbmlElement *	parent ()
	Returns the parent of the element.

const EbmlElement *	parent () const
	Returns the parent of the element.

EbmlElement *	parent (std::uint8_t n)
	Returns the n-th parent of the element.

const EbmlElement *	parent (std::uint8_t n) const
	Returns the n-th parent of the element.

EbmlElement *	nextSibling ()
	Returns the next sibling of the element.

const EbmlElement *	nextSibling () const
	Returns the next sibling of the element.

EbmlElement *	firstChild ()
	Returns the first child of the element.

const EbmlElement *	firstChild () const
	Returns the first child of the element.

EbmlElement *	lastChild ()
	Returns the last child of the element.

const EbmlElement *	lastChild () const
	Returns the last child of the element.

EbmlElement *	subelementByPath (Diagnostics &diag, IdentifierType item)
	Returns the sub element for the specified path.

EbmlElement *	subelementByPath (Diagnostics &diag, IdentifierType item, IdentifierType remainingPath...)
	Returns the sub element for the specified path.

const EbmlElement *	subelementByPath (Diagnostics &diag, IdentifierType item) const
	Returns the sub element for the specified path.

const EbmlElement *	subelementByPath (Diagnostics &diag, IdentifierType item, IdentifierType remainingPath...) const
	Returns the sub element for the specified path.

EbmlElement *	childById (const IdentifierType &id, Diagnostics &diag)
	Returns the first child with the specified id.

const EbmlElement *	childById (const IdentifierType &id, Diagnostics &diag) const
	Returns the first child with the specified id.

EbmlElement *	siblingById (const IdentifierType &id, Diagnostics &diag)
	Returns the first sibling with the specified id.

const EbmlElement *	siblingById (const IdentifierType &id, Diagnostics &diag) const
	Returns the first sibling with the specified id.

EbmlElement *	siblingByIdIncludingThis (const IdentifierType &id, Diagnostics &diag)
	Returns the first sibling with the specified id or the current instance if its ID equals id.

const EbmlElement *	siblingByIdIncludingThis (const IdentifierType &id, Diagnostics &diag) const
	Returns the first sibling with the specified id or the current instance if its ID equals id.

bool	isParent () const
	Returns an indication whether this instance is a parent element.

bool	isPadding () const
	Returns an indication whether this instance is a padding element.

std::uint64_t	firstChildOffset () const
	Returns the offset of the first child (relative to the start offset of this element).

bool	isParsed () const
	Returns an indication whether this instance has been parsed yet.

void	clear ()
	Clears the status of the element.

void	parse (Diagnostics &diag)
	Parses the header information of the element which is read from the related stream at the start offset.

void	reparse (Diagnostics &diag)
	Parses the header information of the element which is read from the related stream at the start offset.

void	validateSubsequentElementStructure (Diagnostics &diag, std::uint64_t paddingSize=nullptr, AbortableProgressFeedback progress=nullptr)
	Parses (see parse()) this and all subsequent elements.

void	copyHeader (TargetStream &targetStream, Diagnostics &diag, AbortableProgressFeedback *progress)
	Writes the header information of the element to the specified targetStream.

void	copyWithoutChilds (TargetStream &targetStream, Diagnostics &diag, AbortableProgressFeedback *progress)
	Writes the element without its children to the specified targetStream.

void	copyEntirely (TargetStream &targetStream, Diagnostics &diag, AbortableProgressFeedback *progress)
	Writes the entire element including all children to the specified targetStream.

void	makeBuffer ()
	Buffers the element (header and data).

void	discardBuffer ()
	Discards buffered data.

void	copyBuffer (TargetStream &targetStream)
	Copies buffered data to targetStream.

void	copyPreferablyFromBuffer (TargetStream &targetStream, Diagnostics &diag, AbortableProgressFeedback *progress)
	Copies buffered data to targetStream if data has been buffered; copies from input stream otherwise.

const std::unique_ptr< char[]> &	buffer ()
	Returns buffered data.

EbmlElement *	denoteFirstChild (std::uint32_t offset)
	Denotes the first child to start at the specified offset (relative to the start offset of this descriptor).

Static Public Member Functions
static std::uint8_t	calculateIdLength (IdentifierType id)
	Returns the length of the specified id in byte.

static std::uint8_t	calculateSizeDenotationLength (std::uint64_t size)
	Returns the length of the size denotation for the specified size in byte.

static std::uint8_t	makeId (IdentifierType id, char *buff)
	Stores the specified id in the specified buffer which must be at least 8 bytes long.

static std::uint8_t	makeSizeDenotation (std::uint64_t size, char *buff)
	Makes the size denotation for the specified size and stores it to buff.

static std::uint8_t	makeSizeDenotation (std::uint64_t size, char *buff, std::uint8_t minBytes)
	Makes the size denotation for the specified size and stores it to buff.

static std::uint8_t	calculateUIntegerLength (std::uint64_t integer)
	Returns the length of the specified unsigned integer in byte.

static std::uint8_t	makeUInteger (std::uint64_t value, char *buff)
	Writes value to buff.

static std::uint8_t	makeUInteger (std::uint64_t value, char *buff, std::uint8_t minBytes)
	Writes value to buff.

static void	makeSimpleElement (std::ostream &stream, IdentifierType id, std::uint64_t content)
	Makes a simple EBML element.

static void	makeSimpleElement (std::ostream &stream, IdentifierType id, std::string_view content)

Static Public Member Functions inherited from TagParser::GenericFileElement< EbmlElement >
static constexpr std::uint32_t	maximumIdLengthSupported ()
	Returns the maximum id length supported by the class in byte.

static constexpr std::uint32_t	maximumSizeLengthSupported ()
	Returns the maximum size length supported by the class in byte.

static constexpr std::uint8_t	minimumElementSize ()
	Returns the minimum element size.

Static Public Attributes
static std::uint64_t	bytesToBeSkipped = 0x4000
	Specifies the number of bytes to be skipped till a valid EBML element is found in the stream.

Protected Member Functions
	EbmlElement (EbmlElement &parent, std::uint64_t startOffset)
	Constructs a new sub level element with the specified parent at the specified startOffset.

	EbmlElement (MatroskaContainer &container, std::uint64_t startOffset, std::uint64_t maxSize)
	Constructs a new top level element with the specified container at the specified startOffset.

void	internalParse (Diagnostics &diag)
	Parses the EBML element.

Friends
class	GenericFileElement< EbmlElement >

Additional Inherited Members
Public Types inherited from TagParser::GenericFileElement< EbmlElement >
using	ContainerType = typename FileElementTraits< EbmlElement >::ContainerType
	Specifies the type of the corresponding container.

using	IdentifierType = typename FileElementTraits< EbmlElement >::IdentifierType
	Specifies the type used to store identifiers.

using	DataSizeType = typename FileElementTraits< EbmlElement >::DataSizeType
	Specifies the type used to store data sizes.

Protected Attributes inherited from TagParser::GenericFileElement< EbmlElement >
IdentifierType	m_id

std::uint64_t	m_startOffset

std::uint64_t	m_maxSize

DataSizeType	m_dataSize

std::uint32_t	m_idLength

std::uint32_t	m_sizeLength

EbmlElement *	m_parent

std::unique_ptr< EbmlElement >	m_nextSibling

std::unique_ptr< EbmlElement >	m_firstChild

std::unique_ptr< char[]>	m_buffer

bool	m_sizeUnknown

Detailed Description

The EbmlElement class helps to parse EBML files such as Matroska files.

Definition at line 32 of file ebmlelement.h.

Constructor & Destructor Documentation

◆ EbmlElement() [1/3]

TagParser::EbmlElement::EbmlElement	(	MatroskaContainer &	container,
		std::uint64_t	startOffset
	)

Constructs a new top level element with the specified container at the specified startOffset.

Definition at line 37 of file ebmlelement.cpp.

◆ EbmlElement() [2/3]

TagParser::EbmlElement::EbmlElement	(	EbmlElement &	parent,
		std::uint64_t	startOffset
	)

protected

Constructs a new sub level element with the specified parent at the specified startOffset.

Definition at line 53 of file ebmlelement.cpp.

◆ EbmlElement() [3/3]

TagParser::EbmlElement::EbmlElement	(	MatroskaContainer &	container,
		std::uint64_t	startOffset,
		std::uint64_t	maxSize
	)

protected

Constructs a new top level element with the specified container at the specified startOffset.

Definition at line 45 of file ebmlelement.cpp.

Member Function Documentation

◆ calculateIdLength()

std::uint8_t TagParser::EbmlElement::calculateIdLength ( IdentifierType id )

static

Returns the length of the specified id in byte.

Exceptions

Throws InvalidDataException() if id can not be represented.

Definition at line 269 of file ebmlelement.cpp.

◆ calculateSizeDenotationLength()

std::uint8_t TagParser::EbmlElement::calculateSizeDenotationLength ( std::uint64_t size )

static

Returns the length of the size denotation for the specified size in byte.

Exceptions

Throws InvalidDataException() if size can not be represented.

Definition at line 288 of file ebmlelement.cpp.

◆ calculateUIntegerLength()

std::uint8_t TagParser::EbmlElement::calculateUIntegerLength ( std::uint64_t integer )

static

Returns the length of the specified unsigned integer in byte.

Exceptions

Throws InvalidDataException() if integer can not be represented.

Definition at line 415 of file ebmlelement.cpp.

◆ firstChildOffset()

std::uint64_t TagParser::EbmlElement::firstChildOffset ( ) const

inline

Returns the offset of the first child of the element.

Remarks: The returned offset is relative to the start offset if this element.

Definition at line 157 of file ebmlelement.h.

◆ idToString()

std::string TagParser::EbmlElement::idToString ( ) const

inline

Converts the specified EBML ID to a printable string.

Definition at line 71 of file ebmlelement.h.

◆ internalParse()

void TagParser::EbmlElement::internalParse ( Diagnostics & diag )

protected

Parses the EBML element.

Definition at line 69 of file ebmlelement.cpp.

◆ isPadding()

bool TagParser::EbmlElement::isPadding ( ) const

inline

Returns an indication whether the element is considered as padding.

Definition at line 148 of file ebmlelement.h.

◆ isParent()

bool TagParser::EbmlElement::isParent ( ) const

inline

Returns an indication whether the element is a parent element.

Remarks: This information is not read from the element header. Some elements are simply known to be parents whereas all other are considered as non-parents.

Definition at line 87 of file ebmlelement.h.

◆ makeId()

std::uint8_t TagParser::EbmlElement::makeId	(	IdentifierType	id,
		char *	buff
	)

static

Stores the specified id in the specified buffer which must be at least 8 bytes long.

Returns: Returns the number of bytes written to buff.

Exceptions

Throws InvalidDataException() if id can not be represented.

Definition at line 317 of file ebmlelement.cpp.

◆ makeSimpleElement() [1/2]

static void TagParser::EbmlElement::makeSimpleElement	(	std::ostream &	stream,
		IdentifierType	id,
		std::string_view	content
	)

static

◆ makeSimpleElement() [2/2]

void TagParser::EbmlElement::makeSimpleElement	(	std::ostream &	stream,
		IdentifierType	id,
		std::uint64_t	content
	)

static

Makes a simple EBML element.

Parameters

stream	Specifies the stream to write the data to.
id	Specifies the element ID.
content	Specifies the value of the element as unsigned integer.

Definition at line 513 of file ebmlelement.cpp.

◆ makeSizeDenotation() [1/2]

std::uint8_t TagParser::EbmlElement::makeSizeDenotation	(	std::uint64_t	size,
		char *	buff
	)

static

Makes the size denotation for the specified size and stores it to buff.

Parameters

size	Specifies the size to be denoted.
buff	Specifies the buffer to store the denotation. Must be at least 8 bytes long.

Returns: Returns the number of bytes written to buff.

Exceptions

Throws InvalidDataException() if size can not be represented.

Definition at line 343 of file ebmlelement.cpp.

◆ makeSizeDenotation() [2/2]

std::uint8_t TagParser::EbmlElement::makeSizeDenotation	(	std::uint64_t	size,
		char *	buff,
		std::uint8_t	minBytes
	)

static

Makes the size denotation for the specified size and stores it to buff.

Parameters

size	Specifies the size to be denoted.
buff	Specifies the buffer to store the denotation. Must be at least 8 bytes long.
minBytes	Specifies the minimum number of bytes to use. Might be use allow subsequent element growth.

Returns: Returns the number of bytes written to buff. Always in the range of minBytes and 8.

Exceptions

Throws InvalidDataException() if size can not be represented.

Definition at line 381 of file ebmlelement.cpp.

◆ makeUInteger() [1/2]

std::uint8_t TagParser::EbmlElement::makeUInteger	(	std::uint64_t	value,
		char *	buff
	)

static

Writes value to buff.

Returns: Returns the number of bytes written to buff.

Definition at line 440 of file ebmlelement.cpp.

◆ makeUInteger() [2/2]

std::uint8_t TagParser::EbmlElement::makeUInteger	(	std::uint64_t	value,
		char *	buff,
		std::uint8_t	minBytes
	)

static

Writes value to buff.

Returns: Returns the number of bytes written to buff.

Parameters

value	Specifies the value to be written.
buff	Specifies the buffer to write to.
minBytes	Specifies the minimum number of bytes to use.

Remarks: Regardless of minBytes, this function will never make more than 8 bytes.

Definition at line 478 of file ebmlelement.cpp.

◆ readFloat()

double TagParser::EbmlElement::readFloat ( )

Reads the content of the element as float.

Remarks: Reads exactly 4 or 8 bytes. If the element stores more or less data zero is returned.

Definition at line 252 of file ebmlelement.cpp.

◆ readString()

std::string TagParser::EbmlElement::readString ( )

Reads the content of the element as string.

Definition at line 226 of file ebmlelement.cpp.

◆ readUInteger()

std::uint64_t TagParser::EbmlElement::readUInteger ( )

Reads the content of the element as unsigned integer.

Reads up to 8 bytes. If the element stores more data the additional bytes are ignored.

Definition at line 238 of file ebmlelement.cpp.

Friends And Related Symbol Documentation

◆ GenericFileElement< EbmlElement >

friend class GenericFileElement< EbmlElement >

friend

Definition at line 157 of file ebmlelement.h.

Member Data Documentation

◆ bytesToBeSkipped

std::uint64_t TagParser::EbmlElement::bytesToBeSkipped = 0x4000

static

Specifies the number of bytes to be skipped till a valid EBML element is found in the stream.

Definition at line 56 of file ebmlelement.h.

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

matroska/ebmlelement.h
matroska/ebmlelement.cpp

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ EbmlElement() [1/3]

◆ EbmlElement() [2/3]

◆ EbmlElement() [3/3]

Member Function Documentation

◆ calculateIdLength()

◆ calculateSizeDenotationLength()

◆ calculateUIntegerLength()

◆ firstChildOffset()

◆ idToString()

◆ internalParse()

◆ isPadding()

◆ isParent()

◆ makeId()

◆ makeSimpleElement() [1/2]

◆ makeSimpleElement() [2/2]

◆ makeSizeDenotation() [1/2]

◆ makeSizeDenotation() [2/2]

◆ makeUInteger() [1/2]

◆ makeUInteger() [2/2]

◆ readFloat()

◆ readString()

◆ readUInteger()

Friends And Related Symbol Documentation

◆ GenericFileElement< EbmlElement >

Member Data Documentation

◆ bytesToBeSkipped