Tag Parser
9.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 | |
using | ContainerType = typename FileElementTraits< ImplementationType >::ContainerType |
Specifies the type of the corresponding container. More... | |
using | IdentifierType = typename FileElementTraits< ImplementationType >::IdentifierType |
Specifies the type used to store identifiers. More... | |
using | DataSizeType = typename FileElementTraits< ImplementationType >::DataSizeType |
Specifies the type used to store data sizes. More... | |
Public Member Functions | |
GenericFileElement (ContainerType &container, std::uint64_t startOffset) | |
GenericFileElement (ImplementationType &parent, std::uint64_t startOffset) | |
Constructs a new sub level file element with the specified parent at the specified startOffset. More... | |
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. More... | |
const ContainerType & | container () const |
Returns the related container. More... | |
std::iostream & | stream () |
Returns the related stream. More... | |
CppUtilities::BinaryReader & | reader () |
Returns the related BinaryReader. More... | |
CppUtilities::BinaryWriter & | writer () |
Returns the related BinaryWriter. More... | |
std::uint64_t | startOffset () const |
Returns the start offset in the related stream. More... | |
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. More... | |
const IdentifierType & | id () const |
Returns the element ID. More... | |
std::string | idToString () const |
Returns a printable string representation of the element ID. More... | |
std::uint32_t | idLength () const |
Returns the length of the id denotation in byte. More... | |
std::uint32_t | 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... | |
std::uint32_t | sizeLength () const |
Returns the length of the size denotation of the element in byte. More... | |
std::uint64_t | dataOffset () const |
Returns the data offset of the element in the related stream. More... | |
std::uint64_t | totalSize () const |
Returns the total size of the element. More... | |
std::uint64_t | endOffset () const |
Returns the offset of the first byte which doesn't belong to this element anymore. More... | |
std::uint64_t | maxTotalSize () const |
Returns maximum total size. More... | |
std::uint8_t | level () const |
Returns how deep the element is nested (0 for top-level elements, 1 for children of top-level elements, ...). More... | |
ImplementationType * | parent () |
Returns the parent of the element. More... | |
const ImplementationType * | parent () const |
Returns the parent of the element. More... | |
ImplementationType * | parent (std::uint8_t n) |
Returns the n-th parent of the element. More... | |
const ImplementationType * | parent (std::uint8_t n) const |
Returns the n-th 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 * | lastChild () |
Returns the last child of the element. More... | |
const ImplementationType * | lastChild () const |
Returns the last child of the element. More... | |
ImplementationType * | subelementByPath (Diagnostics &diag, IdentifierType item) |
Returns the sub element for the specified path. More... | |
ImplementationType * | subelementByPath (Diagnostics &diag, IdentifierType item, IdentifierType remainingPath...) |
Returns the sub element for the specified path. More... | |
const ImplementationType * | subelementByPath (Diagnostics &diag, IdentifierType item) const |
Returns the sub element for the specified path. More... | |
const ImplementationType * | subelementByPath (Diagnostics &diag, IdentifierType item, IdentifierType remainingPath...) const |
Returns the sub element for the specified path. More... | |
ImplementationType * | childById (const IdentifierType &id, Diagnostics &diag) |
Returns the first child with the specified id. More... | |
const ImplementationType * | childById (const IdentifierType &id, Diagnostics &diag) const |
Returns the first child with the specified id. More... | |
ImplementationType * | siblingById (const IdentifierType &id, Diagnostics &diag) |
Returns the first sibling with the specified id. More... | |
const ImplementationType * | siblingById (const IdentifierType &id, Diagnostics &diag) const |
Returns the first sibling with the specified id. More... | |
ImplementationType * | siblingByIdIncludingThis (const IdentifierType &id, Diagnostics &diag) |
Returns the first sibling with the specified id or the current instance if its ID equals id. More... | |
const ImplementationType * | siblingByIdIncludingThis (const IdentifierType &id, Diagnostics &diag) const |
Returns the first sibling with the specified id or the current instance if its ID equals id. 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... | |
std::uint64_t | 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 (Diagnostics &diag) |
Parses the header information of the element which is read from the related stream at the start offset. More... | |
void | reparse (Diagnostics &diag) |
Parses the header information of the element which is read from the related stream at the start offset. More... | |
void | validateSubsequentElementStructure (Diagnostics &diag, std::uint64_t *paddingSize=nullptr) |
Parses (see parse()) this and all subsequent elements. More... | |
void | copyHeader (std::ostream &targetStream, Diagnostics &diag, AbortableProgressFeedback *progress) |
Writes the header informaton of the element to the specified targetStream. More... | |
void | copyWithoutChilds (std::ostream &targetStream, Diagnostics &diag, AbortableProgressFeedback *progress) |
Writes the element without its children to the specified targetStream. More... | |
void | copyEntirely (std::ostream &targetStream, Diagnostics &diag, AbortableProgressFeedback *progress) |
Writes the entire element including all children 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, Diagnostics &diag, AbortableProgressFeedback *progress) |
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 (std::uint32_t offset) |
Denotes the first child to start at the specified offset (relative to the start offset of this descriptor). More... | |
Static Public Member Functions | |
static constexpr std::uint32_t | maximumIdLengthSupported () |
Returns the maximum id length supported by the class in byte. More... | |
static constexpr std::uint32_t | maximumSizeLengthSupported () |
Returns the maximum size length supported by the class in byte. More... | |
static constexpr std::uint8_t | minimumElementSize () |
Returns the mimimum element size. More... | |
Protected Attributes | |
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 |
ImplementationType * | m_parent |
std::unique_ptr< ImplementationType > | m_nextSibling |
std::unique_ptr< ImplementationType > | m_firstChild |
std::unique_ptr< char[]> | m_buffer |
bool | m_sizeUnknown |
Friends | |
class | FileElementTraits< ImplementationType > |
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 45 of file genericfileelement.h.
using TagParser::GenericFileElement< ImplementationType >::ContainerType = typename FileElementTraits<ImplementationType>::ContainerType |
Specifies the type of the corresponding container.
Definition at line 52 of file genericfileelement.h.
using TagParser::GenericFileElement< ImplementationType >::DataSizeType = typename FileElementTraits<ImplementationType>::DataSizeType |
Specifies the type used to store data sizes.
Definition at line 62 of file genericfileelement.h.
using TagParser::GenericFileElement< ImplementationType >::IdentifierType = typename FileElementTraits<ImplementationType>::IdentifierType |
Specifies the type used to store identifiers.
Definition at line 57 of file genericfileelement.h.
TagParser::GenericFileElement< ImplementationType >::GenericFileElement | ( | ContainerType & | container, |
std::uint64_t | startOffset | ||
) |
TagParser::GenericFileElement< ImplementationType >::GenericFileElement | ( | ImplementationType & | parent, |
std::uint64_t | startOffset | ||
) |
Constructs a new sub level file element with the specified parent at the specified startOffset.
Definition at line 183 of file genericfileelement.h.
TagParser::GenericFileElement< ImplementationType >::GenericFileElement | ( | ContainerType & | container, |
std::uint64_t | startOffset, | ||
std::uint64_t | maxSize | ||
) |
|
delete |
|
delete |
|
inline |
Returns buffered data.
The returned array is totalSize() bytes long.
Definition at line 910 of file genericfileelement.h.
ImplementationType * TagParser::GenericFileElement< ImplementationType >::childById | ( | const IdentifierType & | id, |
Diagnostics & | diag | ||
) |
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 602 of file genericfileelement.h.
const ImplementationType * TagParser::GenericFileElement< ImplementationType >::childById | ( | const IdentifierType & | id, |
Diagnostics & | diag | ||
) | const |
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 624 of file genericfileelement.h.
void TagParser::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 745 of file genericfileelement.h.
|
inline |
Returns the related container.
Definition at line 220 of file genericfileelement.h.
|
inline |
Returns the related container.
Definition at line 229 of file genericfileelement.h.
|
inline |
Copies buffered data to targetStream.
Definition at line 890 of file genericfileelement.h.
void TagParser::GenericFileElement< ImplementationType >::copyEntirely | ( | std::ostream & | targetStream, |
Diagnostics & | diag, | ||
AbortableProgressFeedback * | progress | ||
) |
Writes the entire element including all children to the specified targetStream.
Definition at line 862 of file genericfileelement.h.
void TagParser::GenericFileElement< ImplementationType >::copyHeader | ( | std::ostream & | targetStream, |
Diagnostics & | diag, | ||
AbortableProgressFeedback * | progress | ||
) |
Writes the header informaton of the element to the specified targetStream.
Definition at line 840 of file genericfileelement.h.
|
inline |
Copies buffered data to targetStream if data has been buffered; copies from input stream otherwise.
Definition at line 900 of file genericfileelement.h.
void TagParser::GenericFileElement< ImplementationType >::copyWithoutChilds | ( | std::ostream & | targetStream, |
Diagnostics & | diag, | ||
AbortableProgressFeedback * | progress | ||
) |
Writes the element without its children to the specified targetStream.
Definition at line 849 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 333 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 315 of file genericfileelement.h.
ImplementationType * TagParser::GenericFileElement< ImplementationType >::denoteFirstChild | ( | std::uint32_t | relativeFirstChildOffset | ) |
Denotes the first child to start at the specified offset (relative to the start offset of this descriptor).
Definition at line 948 of file genericfileelement.h.
|
inline |
Discards buffered data.
Definition at line 881 of file genericfileelement.h.
|
inline |
Returns the offset of the first byte which doesn't belong to this element anymore.
Definition at line 351 of file genericfileelement.h.
|
inline |
Returns the first child of the element.
The current element keeps ownership over the returned element. If no children are present nullptr is returned.
Definition at line 460 of file genericfileelement.h.
|
inline |
Returns the first child of the element.
The current element keeps ownership over the returned element. If no children are present nullptr is returned.
Definition at line 473 of file genericfileelement.h.
|
inline |
Returns the offset of the first child (relative to the start offset of this element).
Definition at line 726 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 304 of file genericfileelement.h.
|
inline |
Returns the element ID.
Definition at line 278 of file genericfileelement.h.
|
inline |
Returns the length of the id denotation in byte.
Definition at line 294 of file genericfileelement.h.
|
inline |
Returns a printable string representation of the element ID.
Definition at line 286 of file genericfileelement.h.
|
inline |
Returns an indication whether this instance is a padding element.
Definition at line 718 of file genericfileelement.h.
|
inline |
Returns an indication whether this instance is a parent element.
Definition at line 710 of file genericfileelement.h.
|
inline |
Returns an indication whether this instance has been parsed yet.
Definition at line 734 of file genericfileelement.h.
|
inline |
Returns the last child of the element.
The current element keeps ownership over the returned element. If no children are present nullptr is returned.
Definition at line 486 of file genericfileelement.h.
|
inline |
Returns the last child of the element.
The current element keeps ownership over the returned element. If no children are present nullptr is returned.
Definition at line 504 of file genericfileelement.h.
std::uint8_t TagParser::GenericFileElement< ImplementationType >::level |
Returns how deep the element is nested (0 for top-level elements, 1 for children of top-level elements, ...).
Definition at line 371 of file genericfileelement.h.
void TagParser::GenericFileElement< ImplementationType >::makeBuffer |
Buffers the element (header and data).
Definition at line 871 of file genericfileelement.h.
|
staticconstexpr |
Returns the maximum id length supported by the class in byte.
Definition at line 961 of file genericfileelement.h.
|
staticconstexpr |
Returns the maximum size length supported by the class in byte.
Definition at line 969 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 362 of file genericfileelement.h.
|
staticconstexpr |
Returns the mimimum element size.
Definition at line 977 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 434 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 447 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 385 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 396 of file genericfileelement.h.
ImplementationType * TagParser::GenericFileElement< ImplementationType >::parent | ( | std::uint8_t | n | ) |
Returns the n-th parent of the element.
Definition at line 407 of file genericfileelement.h.
|
inline |
Returns the n-th parent of the element.
Definition at line 421 of file genericfileelement.h.
void TagParser::GenericFileElement< ImplementationType >::parse | ( | Diagnostics & | diag | ) |
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 | TagParser::Failure or a derived exception when a parsing error occurs. |
Definition at line 771 of file genericfileelement.h.
|
inline |
Returns the related BinaryReader.
Definition at line 245 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 269 of file genericfileelement.h.
void TagParser::GenericFileElement< ImplementationType >::reparse | ( | Diagnostics & | diag | ) |
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 | TagParser::Failure or a derived exception when a parsing error occurs. |
Definition at line 795 of file genericfileelement.h.
ImplementationType * TagParser::GenericFileElement< ImplementationType >::siblingById | ( | const IdentifierType & | id, |
Diagnostics & | diag | ||
) |
Returns the first sibling with 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 640 of file genericfileelement.h.
const ImplementationType * TagParser::GenericFileElement< ImplementationType >::siblingById | ( | const IdentifierType & | id, |
Diagnostics & | diag | ||
) | const |
Returns the first sibling with 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 663 of file genericfileelement.h.
ImplementationType * TagParser::GenericFileElement< ImplementationType >::siblingByIdIncludingThis | ( | const IdentifierType & | id, |
Diagnostics & | diag | ||
) |
Returns the first sibling with the specified id or the current instance if its ID equals 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 679 of file genericfileelement.h.
const ImplementationType * TagParser::GenericFileElement< ImplementationType >::siblingByIdIncludingThis | ( | const IdentifierType & | id, |
Diagnostics & | diag | ||
) | const |
Returns the first sibling with the specified id or the current instance if its ID equals 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 702 of file genericfileelement.h.
|
inline |
Returns the length of the size denotation of the element in byte.
Definition at line 323 of file genericfileelement.h.
|
inline |
Returns the start offset in the related stream.
Definition at line 261 of file genericfileelement.h.
|
inline |
Returns the related stream.
Definition at line 237 of file genericfileelement.h.
ImplementationType * TagParser::GenericFileElement< ImplementationType >::subelementByPath | ( | Diagnostics & | diag, |
IdentifierType | item | ||
) |
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 519 of file genericfileelement.h.
const ImplementationType * TagParser::GenericFileElement< ImplementationType >::subelementByPath | ( | Diagnostics & | diag, |
IdentifierType | item | ||
) | const |
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 572 of file genericfileelement.h.
ImplementationType * TagParser::GenericFileElement< ImplementationType >::subelementByPath | ( | Diagnostics & | diag, |
IdentifierType | item, | ||
IdentifierType | remainingPath... | ||
) |
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 544 of file genericfileelement.h.
const ImplementationType * TagParser::GenericFileElement< ImplementationType >::subelementByPath | ( | Diagnostics & | diag, |
IdentifierType | item, | ||
IdentifierType | remainingPath... | ||
) | const |
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 587 of file genericfileelement.h.
|
inline |
Returns the total size of the element.
This is the sum of the header size and the data size.
Definition at line 343 of file genericfileelement.h.
void TagParser::GenericFileElement< ImplementationType >::validateSubsequentElementStructure | ( | Diagnostics & | diag, |
std::uint64_t * | paddingSize = nullptr |
||
) |
Parses (see parse()) this and all subsequent elements.
All diagnostic message will be stored in diag. 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 | TagParser::Failure or a derived exception when a parsing error occurs. |
Definition at line 815 of file genericfileelement.h.
|
inline |
Returns the related BinaryWriter.
Definition at line 253 of file genericfileelement.h.
|
friend |
Definition at line 977 of file genericfileelement.h.
|
protected |
Definition at line 140 of file genericfileelement.h.
|
protected |
Definition at line 134 of file genericfileelement.h.
|
protected |
Definition at line 139 of file genericfileelement.h.
|
protected |
Definition at line 131 of file genericfileelement.h.
|
protected |
Definition at line 135 of file genericfileelement.h.
|
protected |
Definition at line 133 of file genericfileelement.h.
|
protected |
Definition at line 138 of file genericfileelement.h.
|
protected |
Definition at line 137 of file genericfileelement.h.
|
protected |
Definition at line 136 of file genericfileelement.h.
|
protected |
Definition at line 150 of file genericfileelement.h.
|
protected |
Definition at line 132 of file genericfileelement.h.