Tag Parser
6.4.0
C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags
|
The GenericFileElement class helps to parse binary files which consist of an arboreal element strucutre. More...
#include <genericfileelement.h>
Public Types | |
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... | |
typedef FileElementTraits< ImplementationType >::implementationType | implementationType |
Specifies the type of the actual implementation. More... | |
![]() | |
typedef std::function< void(StatusProvider &sender)> | CallbackFunction |
typedef std::vector< CallbackFunction > | CallbackVector |
typedef std::pair< int, CallbackFunction > | CallbackPair |
Public Member Functions | |
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 | |
GenericFileElement & | operator= (const GenericFileElement &other)=delete |
containerType & | container () |
Returns the related container. More... | |
const containerType & | container () 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 identifierType & | id () 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... | |
implementationType * | parent () |
Returns the parent of the element. More... | |
const implementationType * | parent () const |
Returns the 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 * | subelementByPath (const std::initializer_list< identifierType > &path) |
Returns the sub element for the specified path. More... | |
implementationType * | subelementByPath (std::list< identifierType > &path) |
implementationType * | childById (const identifierType &id) |
Returns the first child with the specified id. More... | |
implementationType * | siblingById (const identifierType &id, bool includeThis=false) |
Returns the first sibling with the specified id. More... | |
FileElementIterator< implementationType > | begin () |
Returns an iterator for iterating over the element's childs. More... | |
FileElementIterator< implementationType > | end () |
Returns an invalid iterator. More... | |
const FileElementIterator< implementationType > | begin () const |
Returns an iterator for iterating over the element's childs (constant). More... | |
const FileElementIterator< implementationType > | end () 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... | |
implementationType * | denoteFirstChild (uint32 offset) |
Denotes the first child to start at the specified offset (relative to the start offset of this descriptor). More... | |
![]() | |
const NotificationList & | notifications () 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... | |
StatusProvider * | usedProvider () |
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 ¬ification) |
This protected 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 protected 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 protected 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 protected method is meant to be called by the derived class to add all notifications from another StatusProvider instance. More... | |
void | addNotifications (const NotificationList ¬ifications) |
This protected method is meant to be called by the derived class to add the specified notifications. More... | |
Static Public Member Functions | |
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 Attributes | |
identifierType | m_id |
uint64 | m_startOffset |
uint64 | m_maxSize |
uint32 | m_idLength |
dataSizeType | m_dataSize |
uint32 | m_sizeLength |
implementationType * | m_parent |
std::unique_ptr< implementationType > | m_nextSibling |
std::unique_ptr< implementationType > | m_firstChild |
std::unique_ptr< char[]> | m_buffer |
Friends | |
class | FileElementTraits< ImplementationType > |
Additional Inherited Members | |
![]() | |
StatusProvider () | |
Constructs a new StatusProvider. More... | |
The GenericFileElement class helps to parse binary files which consist of an arboreal element strucutre.
ImplementationType | Specifies the type of the actual implementation. |
Definition at line 27 of file genericfileelement.h.
typedef FileElementTraits<ImplementationType>::containerType Media::GenericFileElement< ImplementationType >::containerType |
Specifies the type of the corresponding container.
Definition at line 123 of file genericfileelement.h.
typedef FileElementTraits<ImplementationType>::dataSizeType Media::GenericFileElement< ImplementationType >::dataSizeType |
Specifies the type used to store data sizes.
Definition at line 133 of file genericfileelement.h.
typedef FileElementTraits<ImplementationType>::identifierType Media::GenericFileElement< ImplementationType >::identifierType |
Specifies the type used to store identifiers.
Definition at line 128 of file genericfileelement.h.
typedef FileElementTraits<ImplementationType>::implementationType Media::GenericFileElement< ImplementationType >::implementationType |
Specifies the type of the actual implementation.
Definition at line 138 of file genericfileelement.h.
Media::GenericFileElement< ImplementationType >::GenericFileElement | ( | containerType & | container, |
uint64 | startOffset | ||
) |
Media::GenericFileElement< ImplementationType >::GenericFileElement | ( | implementationType & | parent, |
uint64 | startOffset | ||
) |
Media::GenericFileElement< ImplementationType >::GenericFileElement | ( | containerType & | container, |
uint64 | startOffset, | ||
uint64 | maxSize | ||
) |
|
delete |
|
delete |
FileElementIterator< typename GenericFileElement< ImplementationType >::implementationType > Media::GenericFileElement< ImplementationType >::begin | ( | ) |
Returns an iterator for iterating over the element's childs.
Definition at line 620 of file genericfileelement.h.
const FileElementIterator< typename GenericFileElement< ImplementationType >::implementationType > Media::GenericFileElement< ImplementationType >::begin | ( | ) | const |
Returns an iterator for iterating over the element's childs (constant).
Definition at line 629 of file genericfileelement.h.
|
inline |
Returns buffered data.
The returned array is totalSize() bytes long.
Definition at line 872 of file genericfileelement.h.
GenericFileElement< ImplementationType >::implementationType * Media::GenericFileElement< ImplementationType >::childById | ( | const identifierType & | id | ) |
Returns the first child with the specified id.
The current element keeps ownership over the returned element. If no element could be found nullptr is returned.
Throws | a parsing exception when a parsing error occurs. |
Throws | std::ios_base::failure when an IO error occurs. |
Definition at line 577 of file genericfileelement.h.
void Media::GenericFileElement< ImplementationType >::clear | ( | ) |
Clears the status of the element.
Resets id length, data size, size length to zero. Subsequent elements will be deleted.
Definition at line 695 of file genericfileelement.h.
|
inline |
Returns the related container.
Definition at line 278 of file genericfileelement.h.
|
inline |
Returns the related container.
Definition at line 287 of file genericfileelement.h.
|
inline |
Copies buffered data to targetStream.
Definition at line 852 of file genericfileelement.h.
void Media::GenericFileElement< ImplementationType >::copyEntirely | ( | std::ostream & | targetStream | ) |
Writes the entire element including all childs to the specified targetStream.
Definition at line 821 of file genericfileelement.h.
void Media::GenericFileElement< ImplementationType >::copyHeader | ( | std::ostream & | targetStream | ) |
Writes the header informaton of the element to the specified targetStream.
Definition at line 799 of file genericfileelement.h.
|
inline |
Copies buffered data to targetStream if data has been buffered; copies from input stream otherwise.
Definition at line 862 of file genericfileelement.h.
void Media::GenericFileElement< ImplementationType >::copyWithoutChilds | ( | std::ostream & | targetStream | ) |
Writes the element without its childs to the specified targetStream.
Definition at line 808 of file genericfileelement.h.
|
inline |
Returns the data offset of the element in the related stream.
This is the sum of start offset and header size.
Definition at line 401 of file genericfileelement.h.
|
inline |
Returns the data size of the element in byte.
This is the size of the element excluding the header.
Definition at line 381 of file genericfileelement.h.
GenericFileElement< ImplementationType >::implementationType * Media::GenericFileElement< ImplementationType >::denoteFirstChild | ( | uint32 | relativeFirstChildOffset | ) |
Denotes the first child to start at the specified offset (relative to the start offset of this descriptor).
Definition at line 908 of file genericfileelement.h.
|
inline |
Discards buffered data.
Definition at line 842 of file genericfileelement.h.
FileElementIterator< typename GenericFileElement< ImplementationType >::implementationType > Media::GenericFileElement< ImplementationType >::end | ( | ) |
Returns an invalid iterator.
Definition at line 638 of file genericfileelement.h.
const FileElementIterator< typename GenericFileElement< ImplementationType >::implementationType > Media::GenericFileElement< ImplementationType >::end | ( | ) | const |
Returns an invalid iterator.
Definition at line 647 of file genericfileelement.h.
|
inline |
Returns the offset of the first byte which doesn't belong to this element anymore.
Definition at line 421 of file genericfileelement.h.
|
inline |
Returns the first child of the element.
The current element keeps ownership over the returned element. If no childs are present nullptr is returned.
Definition at line 499 of file genericfileelement.h.
|
inline |
Returns the first child of the element.
The current element keeps ownership over the returned element. If no childs are present nullptr is returned.
Definition at line 513 of file genericfileelement.h.
|
inline |
Returns the offset of the first child (relative to the start offset of this element).
Definition at line 674 of file genericfileelement.h.
|
inline |
Returns the header size of the element in byte.
This is the sum of the id length and the size length.
Definition at line 370 of file genericfileelement.h.
|
inline |
Returns the element ID.
Definition at line 341 of file genericfileelement.h.
|
inline |
Returns the length of the id denotation in byte.
Definition at line 359 of file genericfileelement.h.
|
inline |
Returns a printable string representation of the element ID.
Definition at line 350 of file genericfileelement.h.
|
inline |
Returns an indication whether this instance is a padding element.
Definition at line 665 of file genericfileelement.h.
|
inline |
Returns an indication whether this instance is a parent element.
Definition at line 656 of file genericfileelement.h.
|
inline |
Returns an indication whether this instance has been parsed yet.
Definition at line 683 of file genericfileelement.h.
void Media::GenericFileElement< ImplementationType >::makeBuffer | ( | ) |
Buffers the element (header and data).
Definition at line 831 of file genericfileelement.h.
|
static |
Returns the maximum id length supported by the class in byte.
Definition at line 922 of file genericfileelement.h.
|
static |
Returns the maximum size length supported by the class in byte.
Definition at line 931 of file genericfileelement.h.
|
inline |
Returns maximum total size.
This is usually the size of the file for top-level elements and the remaining size of the parent for non-top-level elements.
Definition at line 433 of file genericfileelement.h.
|
static |
Returns the mimimum element size.
Definition at line 940 of file genericfileelement.h.
|
inline |
Returns the next sibling of the element.
The current element keeps ownership over the returned element. If no next sibling is present nullptr is returned.
Definition at line 471 of file genericfileelement.h.
|
inline |
Returns the next sibling of the element.
The current element keeps ownership over the returned element. If no next sibling is present nullptr is returned.
Definition at line 485 of file genericfileelement.h.
|
delete |
|
inline |
Returns the parent of the element.
The returned element has ownership over the current instance. If the current element is a top level element nullptr is returned.
Definition at line 445 of file genericfileelement.h.
|
inline |
Returns the parent of the element.
The returned element has ownership over the current instance. If the current element is a top level element nullptr is returned.
Definition at line 457 of file genericfileelement.h.
void Media::GenericFileElement< ImplementationType >::parse | ( | ) |
Parses the header information of the element which is read from the related stream at the start offset.
The parsed information can accessed using the corresponding methods such as id() for the elemement id and totalSize() for the element size.
If the element has already been parsed (isParsed() returns true) this method does nothing. To force reparsing call reparse().
Throws | std::ios_base::failure when an IO error occurs. |
Throws | Media::Failure or a derived exception when a parsing error occurs. |
Definition at line 722 of file genericfileelement.h.
|
inline |
Returns the related BinaryReader.
Definition at line 305 of file genericfileelement.h.
|
inline |
Returns the offset of the element in its parent or - if it is a top-level element - in the related stream.
Definition at line 332 of file genericfileelement.h.
void Media::GenericFileElement< ImplementationType >::reparse | ( | ) |
Parses the header information of the element which is read from the related stream at the start offset.
The parsed information can accessed using the corresponding methods such as id() for the elemement id and totalSize() for the element size.
If the element has already been parsed (isParsed() returns true) this method clears the parsed information and reparses the header.
Throws | std::ios_base::failure when an IO error occurs. |
Throws | Media::Failure or a derived exception when a parsing error occurs. |
Definition at line 747 of file genericfileelement.h.
GenericFileElement< ImplementationType >::implementationType * Media::GenericFileElement< ImplementationType >::siblingById | ( | const identifierType & | id, |
bool | includeThis = false |
||
) |
Returns the first sibling with the specified id.
id | Specifies the id of the sibling to be returned. |
includeThis | Indicates whether this instance should be returned if it has the specified id. |
The current element keeps ownership over the returned element. If no element could be found nullptr is returned. Possibly returns a pointer to the current instance (see includeThis).
Throws | a parsing exception when a parsing error occurs. |
Throws | std::ios_base::failure when an IO error occurs. |
Definition at line 604 of file genericfileelement.h.
|
inline |
Returns the length of the size denotation of the element in byte.
Definition at line 390 of file genericfileelement.h.
|
inline |
Returns the start offset in the related stream.
Definition at line 323 of file genericfileelement.h.
|
inline |
Returns the related stream.
Definition at line 296 of file genericfileelement.h.
|
inline |
Returns the sub element for the specified path.
The current element keeps ownership over the returned element. If no element could be found nullptr is returned.
Throws | a parsing exception when a parsing error occurs. |
Throws | std::ios_base::failure when an IO error occurs. |
Definition at line 528 of file genericfileelement.h.
implementationType* Media::GenericFileElement< ImplementationType >::subelementByPath | ( | std::list< identifierType > & | path | ) |
|
inline |
Returns the total size of the element.
This is the sum of the header size and the data size.
Definition at line 412 of file genericfileelement.h.
void Media::GenericFileElement< ImplementationType >::validateSubsequentElementStructure | ( | NotificationList & | gatheredNotifications, |
uint64 * | paddingSize = nullptr |
||
) |
Parses (see parse()) this and all subsequent elements.
All parsing notifications will be stored in gatheredNotifications. If padding is found its size will be set to paddingSize if not nullptr.
Throws | std::ios_base::failure when an IO error occurs. |
Throws | Media::Failure or a derived exception when a parsing error occurs. |
Definition at line 767 of file genericfileelement.h.
|
inline |
Returns the related BinaryWriter.
Definition at line 314 of file genericfileelement.h.
|
friend |
Definition at line 117 of file genericfileelement.h.
|
protected |
Definition at line 209 of file genericfileelement.h.
|
protected |
Definition at line 204 of file genericfileelement.h.
|
protected |
Definition at line 208 of file genericfileelement.h.
|
protected |
Definition at line 200 of file genericfileelement.h.
|
protected |
Definition at line 203 of file genericfileelement.h.
|
protected |
Definition at line 202 of file genericfileelement.h.
|
protected |
Definition at line 207 of file genericfileelement.h.
|
protected |
Definition at line 206 of file genericfileelement.h.
|
protected |
Definition at line 205 of file genericfileelement.h.
|
protected |
Definition at line 201 of file genericfileelement.h.