The Mp4Atom class helps to parse MP4 files. More...

#include <mp4atom.h>

Inheritance diagram for TagParser::Mp4Atom:

Collaboration diagram for TagParser::Mp4Atom:

Public Member Functions
	Mp4Atom (ContainerType &container, std::uint64_t startOffset)

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

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

bool	isPadding () const
	Returns an indication whether the atom is a padding element.

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

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

	GenericFileElement (Mp4Atom &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, ...).

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

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

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

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

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

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

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

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

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

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

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

Mp4Atom *	subelementByPath (Diagnostics &diag, IdType item, IdTypes... remainingPath)
	Returns the sub element for the specified path.

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

const Mp4Atom *	subelementByPath (Diagnostics &diag, IdType item, IdTypes... remainingPath) const
	Returns the sub element for the specified path.

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

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

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

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

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

const Mp4Atom *	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.

Mp4Atom *	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 void	seekBackAndWriteAtomSize (std::ostream &stream, const std::ostream::pos_type &startOffset, Diagnostics &diag)
	This function helps to write the atom size after writing an atom to a stream.

static void	seekBackAndWriteAtomSize64 (std::ostream &stream, const std::ostream::pos_type &startOffset)
	This function helps to write the atom size after writing an atom to a stream.

static constexpr void	addHeaderSize (std::uint64_t &dataSize)
	Adds the header size to the specified data size.

static void	makeHeader (std::uint64_t size, std::uint32_t id, CppUtilities::BinaryWriter &writer)
	Writes an MP4 atom header to the specified stream.

Static Public Member Functions inherited from TagParser::GenericFileElement< Mp4Atom >
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.

Protected Member Functions
	Mp4Atom (ContainerType &container, std::uint64_t startOffset, std::uint64_t maxSize)

	Mp4Atom (Mp4Atom &parent, std::uint64_t startOffset)
	Constructs a new sub level atom with the specified parent at the specified startOffset.

void	internalParse (Diagnostics &diag)
	Parses the MP4 atom.

Friends
class	GenericFileElement< Mp4Atom >

Additional Inherited Members
Public Types inherited from TagParser::GenericFileElement< Mp4Atom >
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< Mp4Atom >
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

Mp4Atom *	m_parent

std::unique_ptr< Mp4Atom >	m_nextSibling

std::unique_ptr< Mp4Atom >	m_firstChild

std::unique_ptr< char[]>	m_buffer

bool	m_sizeUnknown

Detailed Description

The Mp4Atom class helps to parse MP4 files.

Constructor & Destructor Documentation

◆ Mp4Atom() [1/3]

TagParser::Mp4Atom::Mp4Atom	(	ContainerType &	container,
		std::uint64_t	startOffset )

◆ Mp4Atom() [2/3]

TagParser::Mp4Atom::Mp4Atom	(	ContainerType &	container,
		std::uint64_t	startOffset,
		std::uint64_t	maxSize )

protected

◆ Mp4Atom() [3/3]

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

protected

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

Definition at line 45 of file mp4atom.cpp.

Member Function Documentation

◆ addHeaderSize()

void TagParser::Mp4Atom::addHeaderSize ( std::uint64_t & dataSize )

staticconstexpr

Adds the header size to the specified data size.

Definition at line 81 of file mp4atom.h.

◆ firstChildOffset()

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

Returns the offset of the first child (relative to the start offset of this atom).

Remarks: This information is not read from the atom header. The offsets are known for specific atoms.; This method returns zero for non-parent atoms which have no children.; Children with variable offset such as the "esds"-atom must be denoted!

Definition at line 264 of file mp4atom.cpp.

◆ idToString()

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

inline

Converts the specified atom ID to a printable string.

Definition at line 67 of file mp4atom.h.

◆ internalParse()

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

protected

Parses the MP4 atom.

Definition at line 61 of file mp4atom.cpp.

◆ isPadding()

bool TagParser::Mp4Atom::isPadding ( ) const

Returns an indication whether the atom is a padding element.

Remarks: This information is not read from the atom header. Atoms with the IDs "free" and "skip" are considered as padding.

Definition at line 244 of file mp4atom.cpp.

◆ isParent()

bool TagParser::Mp4Atom::isParent ( ) const

Returns an indication whether the atom is a parent element.

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

Definition at line 190 of file mp4atom.cpp.

◆ makeHeader()

void TagParser::Mp4Atom::makeHeader	(	std::uint64_t	size,
		std::uint32_t	id,
		CppUtilities::BinaryWriter &	writer )

static

Writes an MP4 atom header to the specified stream.

Definition at line 171 of file mp4atom.cpp.

◆ seekBackAndWriteAtomSize()

void TagParser::Mp4Atom::seekBackAndWriteAtomSize	(	std::ostream &	stream,
		const std::ostream::pos_type &	startOffset,
		Diagnostics &	diag )

static

This function helps to write the atom size after writing an atom to a stream.

Parameters

stream	Specifies the stream.
startOffset	Specifies the start offset of the atom.

Remarks: The caller must ensure that no seek before startOffset happened.

Exceptions

The	caller has to be sure, that the number of written bytes does not exceed maximum of an 32-bit unsigned integer. Otherwise the function will throw Failure and Mp4Atom::seekBackAndWriteAtomSize64 should be used instead.

This function seeks back to the start offset and writes the difference between the previous offset and the start offset as 32-bit unsigned integer to the stream. Then it seeks back to the previous offset.

Definition at line 133 of file mp4atom.cpp.

◆ seekBackAndWriteAtomSize64()

void TagParser::Mp4Atom::seekBackAndWriteAtomSize64	(	std::ostream &	stream,
		const std::ostream::pos_type &	startOffset )

static

This function helps to write the atom size after writing an atom to a stream.

Parameters

stream	Specifies the stream.
startOffset	Specifies the start offset of the atom.

Remarks: The caller must ensure that no seek before startOffset happened.

This function seeks back to the start offset and writes the difference between the previous offset and the start offset as 64-bit unsigned integer to the stream. Then it seeks back to the previous offset.

Definition at line 157 of file mp4atom.cpp.

Friends And Related Symbol Documentation

◆ GenericFileElement< Mp4Atom >

friend class GenericFileElement< Mp4Atom >

friend

Definition at line 32 of file mp4atom.h.

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

mp4/mp4atom.h
mp4/mp4atom.cpp

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Mp4Atom() [1/3]

◆ Mp4Atom() [2/3]

◆ Mp4Atom() [3/3]

Member Function Documentation

◆ addHeaderSize()

◆ firstChildOffset()

◆ idToString()

◆ internalParse()

◆ isPadding()

◆ isParent()

◆ makeHeader()

◆ seekBackAndWriteAtomSize()

◆ seekBackAndWriteAtomSize64()

Friends And Related Symbol Documentation

◆ GenericFileElement< Mp4Atom >