Tag Parser  7.0.1
C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags
Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | Friends | List of all members
TagParser::EbmlElement Class Reference

#include <ebmlelement.h>

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

Public Member Functions

 EbmlElement (MatroskaContainer &container, uint64 startOffset)
 Constructs a new top level element with the specified container at the specified startOffset. More...
 
std::string idToString () const
 Converts the specified EBML ID to a printable string. More...
 
bool isParent () const
 Returns an indication whether the element is a parent element. More...
 
bool isPadding () const
 Returns an indication whether the element is considered as padding. More...
 
uint64 firstChildOffset () const
 Returns the offset of the first child of the element. More...
 
std::string readString ()
 Reads the content of the element as string. More...
 
uint64 readUInteger ()
 Reads the content of the element as unsigned integer. More...
 
float64 readFloat ()
 Reads the content of the element as float. More...
 
- Public Member Functions inherited from TagParser::GenericFileElement< ImplementationType >
 GenericFileElement (ContainerType &container, uint64 startOffset)
 
 GenericFileElement (ImplementationType &parent, uint64 startOffset)
 Constructs a new sub level file element with the specified parent at the specified startOffset. More...
 
 GenericFileElement (ContainerType &container, uint64 startOffset, uint64 maxSize)
 
 GenericFileElement (const GenericFileElement &other)=delete
 
 GenericFileElement (GenericFileElement &other)=delete
 
GenericFileElementoperator= (const GenericFileElement &other)=delete
 
ContainerTypecontainer ()
 Returns the related container. More...
 
const ContainerTypecontainer () const
 Returns the related container. More...
 
std::iostream & stream ()
 Returns the related stream. More...
 
IoUtilities::BinaryReader & reader ()
 Returns the related BinaryReader. More...
 
IoUtilities::BinaryWriter & writer ()
 Returns the related BinaryWriter. More...
 
uint64 startOffset () const
 Returns the start offset in the related stream. More...
 
uint64 relativeStartOffset () const
 Returns the offset of the element in its parent or - if it is a top-level element - in the related stream. More...
 
const IdentifierTypeid () const
 Returns the element ID. More...
 
std::string idToString () const
 Returns a printable string representation of the element ID. More...
 
uint32 idLength () const
 Returns the length of the id denotation in byte. More...
 
uint32 headerSize () const
 Returns the header size of the element in byte. More...
 
DataSizeType dataSize () const
 Returns the data size of the element in byte. More...
 
uint32 sizeLength () const
 Returns the length of the size denotation of the element in byte. More...
 
uint64 dataOffset () const
 Returns the data offset of the element in the related stream. More...
 
uint64 totalSize () const
 Returns the total size of the element. More...
 
uint64 endOffset () const
 Returns the offset of the first byte which doesn't belong to this element anymore. More...
 
uint64 maxTotalSize () const
 Returns maximum total size. More...
 
byte level () const
 Returns how deep the element is nested (0 for top-level elements, 1 for children of top-level elements, ...). More...
 
ImplementationType * parent ()
 Returns the parent of the element. More...
 
const ImplementationType * parent () const
 Returns the parent of the element. More...
 
ImplementationType * parent (byte n)
 Returns the n-th parent of the element. More...
 
const ImplementationType * parent (byte n) const
 Returns the n-th parent of the element. More...
 
ImplementationType * nextSibling ()
 Returns the next sibling of the element. More...
 
const ImplementationType * nextSibling () const
 Returns the next sibling of the element. More...
 
ImplementationType * firstChild ()
 Returns the first child of the element. More...
 
const ImplementationType * firstChild () const
 Returns the first child of the element. More...
 
ImplementationType * lastChild ()
 Returns the last child of the element. More...
 
const ImplementationType * lastChild () const
 Returns the last child of the element. More...
 
ImplementationType * subelementByPath (Diagnostics &diag, IdentifierType item)
 Returns the sub element for the specified path. More...
 
ImplementationType * subelementByPath (Diagnostics &diag, IdentifierType item, IdentifierType remainingPath...)
 Returns the sub element for the specified path. More...
 
const ImplementationType * subelementByPath (Diagnostics &diag, IdentifierType item) const
 Returns the sub element for the specified path. More...
 
const ImplementationType * subelementByPath (Diagnostics &diag, IdentifierType item, IdentifierType remainingPath...) const
 Returns the sub element for the specified path. More...
 
ImplementationType * childById (const IdentifierType &id, Diagnostics &diag)
 Returns the first child with the specified id. More...
 
const ImplementationType * childById (const IdentifierType &id, Diagnostics &diag) const
 Returns the first child with the specified id. More...
 
ImplementationType * siblingById (const IdentifierType &id, Diagnostics &diag)
 Returns the first sibling with the specified id. More...
 
const ImplementationType * siblingById (const IdentifierType &id, Diagnostics &diag) const
 Returns the first sibling with the specified id. More...
 
ImplementationType * siblingByIdIncludingThis (const IdentifierType &id, Diagnostics &diag)
 Returns the first sibling with the specified id or the current instance if its ID equals id. More...
 
const ImplementationType * siblingByIdIncludingThis (const IdentifierType &id, Diagnostics &diag) const
 Returns the first sibling with the specified id or the current instance if its ID equals id. More...
 
bool isParent () const
 Returns an indication whether this instance is a parent element. More...
 
bool isPadding () const
 Returns an indication whether this instance is a padding element. More...
 
uint64 firstChildOffset () const
 Returns the offset of the first child (relative to the start offset of this element). More...
 
bool isParsed () const
 Returns an indication whether this instance has been parsed yet. More...
 
void clear ()
 Clears the status of the element. More...
 
void parse (Diagnostics &diag)
 Parses the header information of the element which is read from the related stream at the start offset. More...
 
void reparse (Diagnostics &diag)
 Parses the header information of the element which is read from the related stream at the start offset. More...
 
void validateSubsequentElementStructure (Diagnostics &diag, uint64 *paddingSize=nullptr)
 Parses (see parse()) this and all subsequent elements. More...
 
void copyHeader (std::ostream &targetStream, Diagnostics &diag, AbortableProgressFeedback *progress)
 Writes the header informaton of the element to the specified targetStream. More...
 
void copyWithoutChilds (std::ostream &targetStream, Diagnostics &diag, AbortableProgressFeedback *progress)
 Writes the element without its childs to the specified targetStream. More...
 
void copyEntirely (std::ostream &targetStream, Diagnostics &diag, AbortableProgressFeedback *progress)
 Writes the entire element including all childs to the specified targetStream. More...
 
void makeBuffer ()
 Buffers the element (header and data). More...
 
void discardBuffer ()
 Discards buffered data. More...
 
void copyBuffer (std::ostream &targetStream)
 Copies buffered data to targetStream. More...
 
void copyPreferablyFromBuffer (std::ostream &targetStream, Diagnostics &diag, AbortableProgressFeedback *progress)
 Copies buffered data to targetStream if data has been buffered; copies from input stream otherwise. More...
 
const std::unique_ptr< char[]> & buffer ()
 Returns buffered data. More...
 
ImplementationType * denoteFirstChild (uint32 offset)
 Denotes the first child to start at the specified offset (relative to the start offset of this descriptor). More...
 

Static Public Member Functions

static byte calculateIdLength (IdentifierType id)
 Returns the length of the specified id in byte. More...
 
static byte calculateSizeDenotationLength (uint64 size)
 Returns the length of the size denotation for the specified size in byte. More...
 
static byte makeId (IdentifierType id, char *buff)
 Stores the specified id in the specified buffer which must be at least 8 bytes long. More...
 
static byte makeSizeDenotation (uint64 size, char *buff)
 Makes the size denotation for the specified size and stores it to buff. More...
 
static byte makeSizeDenotation (uint64 size, char *buff, byte minBytes)
 Makes the size denotation for the specified size and stores it to buff. More...
 
static byte calculateUIntegerLength (uint64 integer)
 Returns the length of the specified unsigned integer in byte. More...
 
static byte makeUInteger (uint64 value, char *buff)
 Writes value to buff. More...
 
static byte makeUInteger (uint64 value, char *buff, byte minBytes)
 Writes value to buff. More...
 
static void makeSimpleElement (std::ostream &stream, IdentifierType id, uint64 content)
 Makes a simple EBML element. More...
 
static void makeSimpleElement (std::ostream &stream, IdentifierType id, const std::string &content)
 Makes a simple EBML element. More...
 
static void makeSimpleElement (std::ostream &stream, IdentifierType id, const char *data, std::size_t dataSize)
 Makes a simple EBML element. More...
 
- Static Public Member Functions inherited from TagParser::GenericFileElement< ImplementationType >
static constexpr uint32 maximumIdLengthSupported ()
 Returns the maximum id length supported by the class in byte. More...
 
static constexpr uint32 maximumSizeLengthSupported ()
 Returns the maximum size length supported by the class in byte. More...
 
static constexpr byte minimumElementSize ()
 Returns the mimimum element size. More...
 

Static Public Attributes

static uint64 bytesToBeSkipped = 0x4000
 Specifies the number of bytes to be skipped till a valid EBML element is found in the stream. More...
 

Protected Member Functions

 EbmlElement (EbmlElement &parent, uint64 startOffset)
 Constructs a new sub level element with the specified parent at the specified startOffset. More...
 
 EbmlElement (MatroskaContainer &container, uint64 startOffset, uint64 maxSize)
 Constructs a new top level element with the specified container at the specified startOffset. More...
 
void internalParse (Diagnostics &diag)
 Parses the EBML element. More...
 

Friends

class GenericFileElement< EbmlElement >
 

Additional Inherited Members

- Public Types inherited from TagParser::GenericFileElement< ImplementationType >
typedef FileElementTraits< ImplementationType >::ContainerType ContainerType
 Specifies the type of the corresponding container. More...
 
typedef FileElementTraits< ImplementationType >::IdentifierType IdentifierType
 Specifies the type used to store identifiers. More...
 
typedef FileElementTraits< ImplementationType >::DataSizeType DataSizeType
 Specifies the type used to store data sizes. More...
 
- Protected Attributes inherited from TagParser::GenericFileElement< ImplementationType >
IdentifierType m_id
 
uint64 m_startOffset
 
uint64 m_maxSize
 
DataSizeType m_dataSize
 
uint32 m_idLength
 
uint32 m_sizeLength
 
ImplementationType * m_parent
 
std::unique_ptr< ImplementationType > m_nextSibling
 
std::unique_ptr< ImplementationType > m_firstChild
 
std::unique_ptr< char[]> m_buffer
 
bool m_sizeUnknown
 

Detailed Description

Definition at line 31 of file ebmlelement.h.

Constructor & Destructor Documentation

◆ EbmlElement() [1/3]

TagParser::EbmlElement::EbmlElement ( MatroskaContainer container,
uint64  startOffset 
)

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

Definition at line 38 of file ebmlelement.cpp.

◆ EbmlElement() [2/3]

TagParser::EbmlElement::EbmlElement ( EbmlElement parent,
uint64  startOffset 
)
protected

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

Definition at line 54 of file ebmlelement.cpp.

◆ EbmlElement() [3/3]

TagParser::EbmlElement::EbmlElement ( MatroskaContainer container,
uint64  startOffset,
uint64  maxSize 
)
protected

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

Definition at line 46 of file ebmlelement.cpp.

Member Function Documentation

◆ calculateIdLength()

byte TagParser::EbmlElement::calculateIdLength ( GenericFileElement::IdentifierType  id)
static

Returns the length of the specified id in byte.

Exceptions
ThrowsInvalidDataException() if id can not be represented.

Definition at line 271 of file ebmlelement.cpp.

◆ calculateSizeDenotationLength()

byte TagParser::EbmlElement::calculateSizeDenotationLength ( uint64  size)
static

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

Exceptions
ThrowsInvalidDataException() if size can not be represented.

Definition at line 290 of file ebmlelement.cpp.

◆ calculateUIntegerLength()

byte TagParser::EbmlElement::calculateUIntegerLength ( uint64  integer)
static

Returns the length of the specified unsigned integer in byte.

Exceptions
ThrowsInvalidDataException() if integer can not be represented.

Definition at line 417 of file ebmlelement.cpp.

◆ firstChildOffset()

uint64 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 158 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 70 of file ebmlelement.cpp.

◆ isPadding()

bool TagParser::EbmlElement::isPadding ( ) const
inline

Returns an indication whether the element is considered as padding.

Definition at line 149 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 88 of file ebmlelement.h.

◆ makeId()

byte TagParser::EbmlElement::makeId ( GenericFileElement::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
ThrowsInvalidDataException() if id can not be represented.

Definition at line 319 of file ebmlelement.cpp.

◆ makeSimpleElement() [1/3]

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

Makes a simple EBML element.

Parameters
streamSpecifies the stream to write the data to.
idSpecifies the element ID.
contentSpecifies the value of the element as unsigned integer.

Definition at line 513 of file ebmlelement.cpp.

◆ makeSimpleElement() [2/3]

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

Makes a simple EBML element.

Parameters
streamSpecifies the stream to write the data to.
idSpecifies the element ID.
contentSpecifies the value of the element as string.

Definition at line 531 of file ebmlelement.cpp.

◆ makeSimpleElement() [3/3]

void TagParser::EbmlElement::makeSimpleElement ( std::ostream &  stream,
GenericFileElement::IdentifierType  id,
const char *  data,
std::size_t  dataSize 
)
static

Makes a simple EBML element.

Parameters
streamSpecifies the stream to write the data to.
idSpecifies the element ID.
dataSpecifies the data of the element.
dataSizeSpecifies the size of data.

Definition at line 548 of file ebmlelement.cpp.

◆ makeSizeDenotation() [1/2]

byte TagParser::EbmlElement::makeSizeDenotation ( uint64  size,
char *  buff 
)
static

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

Parameters
sizeSpecifies the size to be denoted.
buffSpecifies the buffer to store the denotation. Must be at least 8 bytes long.
Returns
Returns the number of bytes written to buff.
Exceptions
ThrowsInvalidDataException() if size can not be represented.

Definition at line 345 of file ebmlelement.cpp.

◆ makeSizeDenotation() [2/2]

byte TagParser::EbmlElement::makeSizeDenotation ( uint64  size,
char *  buff,
byte  minBytes 
)
static

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

Parameters
sizeSpecifies the size to be denoted.
buffSpecifies the buffer to store the denotation. Must be at least 8 bytes long.
minBytesSpecifies 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
ThrowsInvalidDataException() if size can not be represented.

Definition at line 383 of file ebmlelement.cpp.

◆ makeUInteger() [1/2]

byte TagParser::EbmlElement::makeUInteger ( uint64  value,
char *  buff 
)
static

Writes value to buff.

Returns
Returns the number of bytes written to buff.

Definition at line 442 of file ebmlelement.cpp.

◆ makeUInteger() [2/2]

byte TagParser::EbmlElement::makeUInteger ( uint64  value,
char *  buff,
byte  minBytes 
)
static

Writes value to buff.

Returns
Returns the number of bytes written to buff.
Parameters
valueSpecifies the value to be written.
buffSpecifies the buffer to write to.
minBytesSpecifies the minimum number of bytes to use.

Definition at line 478 of file ebmlelement.cpp.

◆ readFloat()

float64 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 254 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()

uint64 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 Function Documentation

◆ GenericFileElement< EbmlElement >

friend class GenericFileElement< EbmlElement >
friend

Definition at line 32 of file ebmlelement.h.

Member Data Documentation

◆ bytesToBeSkipped

uint64 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: