Tag Parser: TagParser::EbmlElement Class Reference

Tag Parser 12.5.2 C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags

Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | Friends | List of all members
TagParser::EbmlElement Class Reference

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

`#include <ebmlelement.h>`

Inheritance diagram for TagParser::EbmlElement:
[legend]
Collaboration diagram for TagParser::EbmlElement:
[legend]

## 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 & | operator= (const GenericFileElement &other)=delete
ContainerType & | container ()
| 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.
EbmlElement * | nextSibling ()
| Returns the next sibling of the element.
EbmlElement * | firstChild ()
| Returns the first child of the element.
EbmlElement * | lastChild ()
| Returns the last child of the element.
EbmlElement * | subelementByPath (Diagnostics &diag, IdType item)
| Returns the sub element for the specified path.
EbmlElement * | childById (const IdentifierType &id, Diagnostics &diag)
| Returns the first child with the specified id.
EbmlElement * | siblingById (const IdentifierType &id, Diagnostics &diag)
| 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.
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
| Specifies the type of the corresponding container.
using | IdentifierType
| Specifies the type used to store identifiers.
using | 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 416 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]

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

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 382 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 441 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 479 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