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

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

#include <mp4atom.h>

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

Public Member Functions

 Mp4Atom (containerType &container, uint64 startOffset)
 
std::string idToString () const
 Converts the specified atom ID to a printable string. More...
 
bool isParent () const
 Returns an indication whether the atom is a parent element. More...
 
bool isPadding () const
 Returns an indication whether the atom is a padding element. More...
 
uint64 firstChildOffset () const
 Returns the offset of the first child (relative to the start offset of this atom). More...
 
- Public Member Functions inherited from Media::GenericFileElement< Mp4Atom >
 GenericFileElement (containerType &container, uint64 startOffset)
 
 GenericFileElement (implementationType &parent, uint64 startOffset)
 
 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...
 
implementationTypeparent ()
 Returns the parent of the element. More...
 
const implementationTypeparent () const
 Returns the parent of the element. More...
 
implementationTypenextSibling ()
 Returns the next sibling of the element. More...
 
const implementationTypenextSibling () const
 Returns the next sibling of the element. More...
 
implementationTypefirstChild ()
 Returns the first child of the element. More...
 
const implementationTypefirstChild () const
 Returns the first child of the element. More...
 
implementationTypesubelementByPath (const std::initializer_list< identifierType > &path)
 Returns the sub element for the specified path. More...
 
implementationTypesubelementByPath (std::list< identifierType > &path)
 
implementationTypechildById (const identifierType &id)
 Returns the first child with the specified id. More...
 
implementationTypesiblingById (const identifierType &id, bool includeThis=false)
 Returns the first sibling with the specified id. More...
 
FileElementIterator< implementationTypebegin ()
 Returns an iterator for iterating over the element's childs. More...
 
const FileElementIterator< implementationTypebegin () const
 Returns an iterator for iterating over the element's childs (constant). More...
 
FileElementIterator< implementationTypeend ()
 Returns an invalid iterator. More...
 
const FileElementIterator< implementationTypeend () const
 Returns an invalid iterator. 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 ()
 Parses the header information of the element which is read from the related stream at the start offset. More...
 
void reparse ()
 Parses the header information of the element which is read from the related stream at the start offset. More...
 
void validateSubsequentElementStructure (NotificationList &gatheredNotifications, uint64 *paddingSize=nullptr)
 Parses (see parse()) this and all subsequent elements. More...
 
void copyHeader (std::ostream &targetStream)
 Writes the header informaton of the element to the specified targetStream. More...
 
void copyWithoutChilds (std::ostream &targetStream)
 Writes the element without its childs to the specified targetStream. More...
 
void copyEntirely (std::ostream &targetStream)
 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)
 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...
 
implementationTypedenoteFirstChild (uint32 offset)
 Denotes the first child to start at the specified offset (relative to the start offset of this descriptor). More...
 
- Public Member Functions inherited from Media::StatusProvider
const NotificationListnotifications () const
 Returns notifications for the current object. More...
 
bool hasNotifications () const
 Returns an indication whether there are notifications for the current object. More...
 
bool hasCriticalNotifications () const
 Returns an indication whether there are critical notifications for the current object. More...
 
NotificationType worstNotificationType () const
 Returns the worst notification type. More...
 
const std::string & currentStatus () const
 Returns a status information for the current object. More...
 
double currentPercentage () const
 Returns the progress percentage of the current object. More...
 
size_t registerCallback (CallbackFunction callback)
 Registers a callback function. More...
 
void unregisterCallback (size_t id)
 Unregisters a previously registered callback function whith the specified id. More...
 
void unregisterAllCallbacks ()
 Unregisters all callback functions. More...
 
void forwardStatusUpdateCalls (StatusProvider *other=nullptr)
 Forwards all status updates calls to the specified statusProvider. More...
 
StatusProviderusedProvider ()
 Returns the provider which callback functions will be called when the status or the percentage is updated. More...
 
void tryToAbort ()
 Commands the object to abort the current operation. More...
 
bool isAborted () const
 Returns an indication whether the current operation should be aborted. More...
 
void invalidateStatus ()
 Invalidates the current status. More...
 
void invalidateNotifications ()
 Invalidates the object's notifications. More...
 
void updateStatus (const std::string &status)
 This method is meant to be called by the derived class to report updated status information. More...
 
void updateStatus (const std::string &status, double percentage)
 This method is meant to be called by the derived class to report updated status information. More...
 
void updatePercentage (double percentage)
 This method is meant to be called by the derived class to report updated progress percentage only. More...
 
void addNotification (const Notification &notification)
 This method is meant to be called by the derived class to add a notification. More...
 
void addNotification (NotificationType type, const std::string &message, const std::string &context)
 This method is meant to be called by the derived class to add a notification of the specified type, message and context. More...
 
void addNotifications (const StatusProvider &from)
 This method is meant to be called by the derived class to add all notifications from another StatusProvider instance. More...
 
void addNotifications (const std::string &higherContext, const StatusProvider &from)
 This method is meant to be called by the derived class to add all notifications from another StatusProvider instance. More...
 
void addNotifications (const NotificationList &notifications)
 This method is meant to be called by the derived class to add the specified notifications. More...
 

Static Public Member Functions

static void seekBackAndWriteAtomSize (std::ostream &stream, const std::ostream::pos_type &startOffset)
 This function helps to write the atom size after writing an atom to a stream. More...
 
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. More...
 
static void addHeaderSize (uint64 &dataSize)
 Adds the header size to the specified data size. More...
 
static void makeHeader (uint64 size, uint32 id, IoUtilities::BinaryWriter &writer)
 Writes an MP4 atom header to the specified stream. More...
 
- Static Public Member Functions inherited from Media::GenericFileElement< Mp4Atom >
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...
 

Protected Member Functions

 Mp4Atom (containerType &container, uint64 startOffset, uint64 maxSize)
 
 Mp4Atom (implementationType &parent, uint64 startOffset)
 
void internalParse ()
 Parses the MP4 atom. More...
 
- Protected Member Functions inherited from Media::StatusProvider
 StatusProvider ()
 Constructs a new StatusProvider. More...
 

Friends

class GenericFileElement< Mp4Atom >
 

Additional Inherited Members

- Public Types inherited from Media::GenericFileElement< Mp4Atom >
typedef FileElementTraits< Mp4Atom >::containerType containerType
 Specifies the type of the corresponding container. More...
 
typedef FileElementTraits< Mp4Atom >::identifierType identifierType
 Specifies the type used to store identifiers. More...
 
typedef FileElementTraits< Mp4Atom >::dataSizeType dataSizeType
 Specifies the type used to store data sizes. More...
 
typedef FileElementTraits< Mp4Atom >::implementationType implementationType
 Specifies the type of the actual implementation. More...
 
- Public Types inherited from Media::StatusProvider
typedef std::function< void(StatusProvider &sender)> CallbackFunction
 
typedef std::vector< CallbackFunctionCallbackVector
 
typedef std::pair< int, CallbackFunctionCallbackPair
 
- Protected Attributes inherited from Media::GenericFileElement< Mp4Atom >
identifierType m_id
 
uint64 m_startOffset
 
uint64 m_maxSize
 
uint32 m_idLength
 
dataSizeType m_dataSize
 
uint32 m_sizeLength
 
implementationTypem_parent
 
std::unique_ptr< implementationTypem_nextSibling
 
std::unique_ptr< implementationTypem_firstChild
 
std::unique_ptr< char[]> m_buffer
 

Detailed Description

The Mp4Atom class helps to parse MP4 files.

Definition at line 57 of file mp4atom.h.

Constructor & Destructor Documentation

◆ Mp4Atom() [1/3]

Media::Mp4Atom::Mp4Atom ( containerType container,
uint64  startOffset 
)

◆ Mp4Atom() [2/3]

Media::Mp4Atom::Mp4Atom ( containerType container,
uint64  startOffset,
uint64  maxSize 
)
protected

◆ Mp4Atom() [3/3]

Media::Mp4Atom::Mp4Atom ( implementationType parent,
uint64  startOffset 
)
protected

Member Function Documentation

◆ addHeaderSize()

void Media::Mp4Atom::addHeaderSize ( uint64 &  dataSize)
inlinestatic

Adds the header size to the specified data size.

Definition at line 101 of file mp4atom.h.

◆ firstChildOffset()

uint64 Media::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 childs.
Childs with variable offset such as the "esds"-atom must be denoted!

Definition at line 228 of file mp4atom.cpp.

◆ idToString()

std::string Media::Mp4Atom::idToString ( ) const
inline

Converts the specified atom ID to a printable string.

Definition at line 87 of file mp4atom.h.

◆ internalParse()

void Media::Mp4Atom::internalParse ( )
protected

Parses the MP4 atom.

Definition at line 59 of file mp4atom.cpp.

◆ isPadding()

bool Media::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 209 of file mp4atom.cpp.

◆ isParent()

bool Media::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 177 of file mp4atom.cpp.

◆ makeHeader()

void Media::Mp4Atom::makeHeader ( uint64  size,
uint32  id,
IoUtilities::BinaryWriter &  writer 
)
static

Writes an MP4 atom header to the specified stream.

Definition at line 158 of file mp4atom.cpp.

◆ seekBackAndWriteAtomSize()

void Media::Mp4Atom::seekBackAndWriteAtomSize ( 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
streamSpecifies the stream.
startOffsetSpecifies the start offset of the atom.

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 126 of file mp4atom.cpp.

◆ seekBackAndWriteAtomSize64()

void Media::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
streamSpecifies the stream.
startOffsetSpecifies the start offset of the atom.

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 144 of file mp4atom.cpp.

Friends And Related Function Documentation

◆ GenericFileElement< Mp4Atom >

friend class GenericFileElement< Mp4Atom >
friend

Definition at line 59 of file mp4atom.h.


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