Tag Parser: TagParser::Mp4Atom Class Reference

Tag Parser 12.5.3 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 | Protected Member Functions | Friends | List of all members
TagParser::Mp4Atom Class Reference

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

`#include <mp4atom.h>`

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

## 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 & | 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, ...).
Mp4Atom * | parent ()
| Returns the parent of the element.
Mp4Atom * | nextSibling ()
| Returns the next sibling of the element.
Mp4Atom * | firstChild ()
| Returns the first child of the element.
Mp4Atom * | lastChild ()
| Returns the last child of the element.
Mp4Atom * | subelementByPath (Diagnostics &diag, IdType item)
| Returns the sub element for the specified path.
Mp4Atom * | childById (const IdentifierType &id, Diagnostics &diag)
| Returns the first child with the specified id.
Mp4Atom * | siblingById (const IdentifierType &id, Diagnostics &diag)
| 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.
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.

Definition at line 38 of file mp4atom.h.

## 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