Tag Parser
6.1.1
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... | |
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 28 of file genericfileelement.h.
typedef FileElementTraits<ImplementationType>::containerType Media::GenericFileElement< ImplementationType >::containerType |
Specifies the type of the corresponding container.
Definition at line 124 of file genericfileelement.h.
typedef FileElementTraits<ImplementationType>::dataSizeType Media::GenericFileElement< ImplementationType >::dataSizeType |
Specifies the type used to store data sizes.
Definition at line 134 of file genericfileelement.h.
typedef FileElementTraits<ImplementationType>::identifierType Media::GenericFileElement< ImplementationType >::identifierType |
Specifies the type used to store identifiers.
Definition at line 129 of file genericfileelement.h.
typedef FileElementTraits<ImplementationType>::implementationType Media::GenericFileElement< ImplementationType >::implementationType |
Specifies the type of the actual implementation.
Definition at line 139 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 621 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 630 of file genericfileelement.h.
|
inline |
Returns buffered data.
The returned array is totalSize() bytes long.
Definition at line 854 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 578 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 696 of file genericfileelement.h.
|
inline |
Returns the related container.
Definition at line 279 of file genericfileelement.h.
|
inline |
Returns the related container.
Definition at line 288 of file genericfileelement.h.
|
inline |
Copies buffered data to targetStream.
Definition at line 844 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 813 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 791 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 800 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 402 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 382 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 890 of file genericfileelement.h.
|
inline |
Discards buffered data.
Definition at line 834 of file genericfileelement.h.
FileElementIterator< typename GenericFileElement< ImplementationType >::implementationType > Media::GenericFileElement< ImplementationType >::end | ( | ) |
Returns an invalid iterator.
Definition at line 639 of file genericfileelement.h.
const FileElementIterator< typename GenericFileElement< ImplementationType >::implementationType > Media::GenericFileElement< ImplementationType >::end | ( | ) | const |
Returns an invalid iterator.
Definition at line 648 of file genericfileelement.h.
|
inline |
Returns the offset of the first byte which doesn't belong to this element anymore.
Definition at line 422 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 500 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 514 of file genericfileelement.h.
|
inline |
Returns the offset of the first child (relative to the start offset of this element).
Definition at line 675 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 371 of file genericfileelement.h.
|
inline |
Returns the element ID.
Definition at line 342 of file genericfileelement.h.
|
inline |
Returns the length of the id denotation in byte.
Definition at line 360 of file genericfileelement.h.
|
inline |
Returns a printable string representation of the element ID.
Definition at line 351 of file genericfileelement.h.
|
inline |
Returns an indication whether this instance is a padding element.
Definition at line 666 of file genericfileelement.h.
|
inline |
Returns an indication whether this instance is a parent element.
Definition at line 657 of file genericfileelement.h.
|
inline |
Returns an indication whether this instance has been parsed yet.
Definition at line 684 of file genericfileelement.h.
void Media::GenericFileElement< ImplementationType >::makeBuffer | ( | ) |
Buffers the element (header and data).
Definition at line 823 of file genericfileelement.h.
|
inlinestatic |
Returns the maximum id length supported by the class in byte.
Definition at line 904 of file genericfileelement.h.
|
inlinestatic |
Returns the maximum size length supported by the class in byte.
Definition at line 913 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 434 of file genericfileelement.h.
|
inlinestatic |
Returns the mimimum element size.
Definition at line 922 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 472 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 486 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 446 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 458 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 723 of file genericfileelement.h.
|
inline |
Returns the related BinaryReader.
Definition at line 306 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 333 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 748 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 605 of file genericfileelement.h.
|
inline |
Returns the length of the size denotation of the element in byte.
Definition at line 391 of file genericfileelement.h.
|
inline |
Returns the start offset in the related stream.
Definition at line 324 of file genericfileelement.h.
|
inline |
Returns the related stream.
Definition at line 297 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 529 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 413 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 768 of file genericfileelement.h.
|
inline |
Returns the related BinaryWriter.
Definition at line 315 of file genericfileelement.h.
|
friend |
Definition at line 118 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.