Tag Parser 11.0.0
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 | List of all members
TagParser::MatroskaContainer Class Referencefinal

Implementation of GenericContainer<MediaFileInfo, MatroskaTag, MatroskaTrack, EbmlElement>. More...

#include <matroskacontainer.h>

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

Public Member Functions

 MatroskaContainer (MediaFileInfo &stream, std::uint64_t startOffset)
 Constructs a new container for the specified fileInfo at the specified startOffset. More...
 
 ~MatroskaContainer () override
 
void validateIndex (Diagnostics &diag, AbortableProgressFeedback &progress)
 Validates the file index (cue entries). More...
 
std::uint64_t maxIdLength () const
 Returns the maximal ID length in bytes. More...
 
std::uint64_t maxSizeLength () const
 Returns the maximal size length in bytes. More...
 
const std::vector< std::unique_ptr< MatroskaSeekInfo > > & seekInfos () const
 Returns seek information read from "SeekHead"-elements when parsing segment info. More...
 
void setMaxFullParseSize (std::uint64_t maxFullParseSize)
 Sets the maximal file size for a "full parse" in byte. More...
 
const std::vector< std::unique_ptr< MatroskaEditionEntry > > & editionEntires () const
 Returns the edition entries. More...
 
MatroskaChapterchapter (std::size_t index) override
 Returns the chapter with the specified index. More...
 
std::size_t chapterCount () const override
 Returns the number of chapters the container holds. More...
 
MatroskaAttachmentcreateAttachment () override
 Creates and returns a new attachment. More...
 
MatroskaAttachmentattachment (std::size_t index) override
 Returns the attachment with the specified index. More...
 
std::size_t attachmentCount () const override
 Returns the number of attachments the container holds. More...
 
ElementPosition determineElementPosition (std::uint64_t elementId, Diagnostics &diag) const
 Determines the position of the element with the specified elementId. More...
 
ElementPosition determineTagPosition (Diagnostics &diag) const override
 Determines the position of the tags inside the file. More...
 
ElementPosition determineIndexPosition (Diagnostics &diag) const override
 Determines the position of the index. More...
 
virtual bool supportsTitle () const override
 Returns whether the title property is supported. More...
 
virtual std::size_t segmentCount () const override
 Returns the number of segments. More...
 
void reset () override
 Discards all parsing results. More...
 
- Public Member Functions inherited from TagParser::GenericContainer< MediaFileInfo, MatroskaTag, MatroskaTrack, EbmlElement >
 GenericContainer (MediaFileInfo &fileInfo, std::uint64_t startOffset)
 Constructs a new container for the specified fileInfo at the specified startOffset. More...
 
 ~GenericContainer () override
 Destroys the container. More...
 
void validateElementStructure (Diagnostics &diag, AbortableProgressFeedback &progress, std::uint64_t *paddingSize=nullptr)
 Parses all elements the file consists of. More...
 
MediaFileInfofileInfo () const
 Returns the related file info. More...
 
EbmlElementfirstElement () const
 Returns the first element of the file if available; otherwiese returns nullptr. More...
 
const std::vector< std::unique_ptr< EbmlElement > > & additionalElements () const
 Returns all available additional elements. More...
 
std::vector< std::unique_ptr< EbmlElement > > & additionalElements ()
 Returns all available additional elements. More...
 
MatroskaTagtag (std::size_t index) override
 Returns the tag with the specified index. More...
 
std::size_t tagCount () const override
 Returns the number of tags attached to the container. More...
 
MatroskaTracktrack (std::size_t index) override
 Returns the track with the specified index. More...
 
MatroskaTracktrackById (std::uint64_t id)
 
std::size_t trackCount () const override
 Returns the number of tracks the container holds. More...
 
const std::vector< std::unique_ptr< MatroskaTag > > & tags () const
 Returns the tags of the file. More...
 
std::vector< std::unique_ptr< MatroskaTag > > & tags ()
 Returns the tags of the file. More...
 
const std::vector< std::unique_ptr< MatroskaTrack > > & tracks () const
 Returns the tracks of the file. More...
 
std::vector< std::unique_ptr< MatroskaTrack > > & tracks ()
 Returns the tracks of the file. More...
 
MatroskaTagcreateTag (const TagTarget &target=TagTarget()) override
 Creates and returns a tag for the specified target. More...
 
bool removeTag (Tag *tag) override
 Removes the specified tag from the container. More...
 
void removeAllTags () override
 Removes all tags attached to the container. More...
 
bool addTrack (MatroskaTrack *track)
 Adds the specified track to the container. More...
 
bool removeTrack (AbstractTrack *track) override
 Removes the specified track to the container. More...
 
void removeAllTracks () override
 Removes all tracks from the container. More...
 
void reset () override
 Discards all parsing results. More...
 
- Public Member Functions inherited from TagParser::AbstractContainer
virtual ~AbstractContainer ()
 Destroys the container. More...
 
std::iostream & stream ()
 Returns the related stream. More...
 
void setStream (std::iostream &stream)
 Sets the related stream. More...
 
std::uint64_t startOffset () const
 Returns the start offset in the related stream. More...
 
CppUtilities::BinaryReader & reader ()
 Returns the related BinaryReader. More...
 
CppUtilities::BinaryWriter & writer ()
 Returns the related BinaryWriter. More...
 
void parseHeader (Diagnostics &diag, AbortableProgressFeedback &progress)
 Parses the header if not parsed yet. More...
 
void parseTags (Diagnostics &diag, AbortableProgressFeedback &progress)
 Parses the tag information if not parsed yet. More...
 
void parseTracks (Diagnostics &diag, AbortableProgressFeedback &progress)
 Parses the tracks of the file if not parsed yet. More...
 
void parseChapters (Diagnostics &diag, AbortableProgressFeedback &progress)
 Parses the chapters of the file if not parsed yet. More...
 
void parseAttachments (Diagnostics &diag, AbortableProgressFeedback &progress)
 Parses the attachments of the file if not parsed yet. More...
 
void makeFile (Diagnostics &diag, AbortableProgressFeedback &progress)
 Rewrites the file to apply changed tag information. More...
 
bool isHeaderParsed () const
 Returns an indication whether the header has been parsed yet. More...
 
bool areTagsParsed () const
 Returns an indication whether the tags have been parsed yet. More...
 
bool areTracksParsed () const
 Returns an indication whether the tracks have been parsed yet. More...
 
bool areChaptersParsed () const
 Returns an indication whether the chapters have been parsed yet. More...
 
bool areAttachmentsParsed () const
 Returns an indication whether the attachments have been parsed yet. More...
 
virtual TagcreateTag (const TagTarget &target=TagTarget())
 Creates and returns a tag for the specified target. More...
 
virtual Tagtag (std::size_t index)
 Returns the tag with the specified index. More...
 
virtual std::size_t tagCount () const
 Returns the number of tags attached to the container. More...
 
virtual bool removeTag (Tag *tag)
 Removes the specified tag from the container. More...
 
virtual void removeAllTags ()
 Removes all tags attached to the container. More...
 
virtual ElementPosition determineTagPosition (Diagnostics &diag) const
 Determines the position of the tags inside the file. More...
 
virtual AbstractTracktrack (std::size_t index)
 Returns the track with the specified index. More...
 
virtual std::size_t trackCount () const
 Returns the number of tracks the container holds. More...
 
virtual bool removeTrack (AbstractTrack *track)
 Removes the specified track to the container. More...
 
virtual void removeAllTracks ()
 Removes all tracks from the container. More...
 
virtual bool supportsTrackModifications () const
 Returns whether the implementation supports adding or removing of tracks. More...
 
virtual ElementPosition determineIndexPosition (Diagnostics &diag) const
 Determines the position of the index. More...
 
virtual AbstractChapterchapter (std::size_t index)
 Returns the chapter with the specified index. More...
 
virtual std::size_t chapterCount () const
 Returns the number of chapters the container holds. More...
 
virtual AbstractAttachmentcreateAttachment ()
 Creates and returns a new attachment. More...
 
virtual AbstractAttachmentattachment (std::size_t index)
 Returns the attachment with the specified index. More...
 
virtual std::size_t attachmentCount () const
 Returns the number of attachments the container holds. More...
 
std::uint64_t version () const
 Returns the version if known; otherwise returns 0. More...
 
std::uint64_t readVersion () const
 Returns the "read version" if known; otherwise returns 0. More...
 
const std::string & documentType () const
 Returns a string that describes the document type if available; otherwise returns an empty string. More...
 
std::uint64_t doctypeVersion () const
 Returns the document type version if known; otherwise returns 0. More...
 
std::uint64_t doctypeReadVersion () const
 Returns the document type "read version" if known; otherwise returns 0. More...
 
const std::vector< std::string > & titles () const
 Returns the title(s) of the file. More...
 
void setTitle (std::string_view title, std::size_t segmentIndex=0)
 Sets the title for the specified segment. More...
 
virtual bool supportsTitle () const
 Returns whether the title property is supported. More...
 
virtual std::size_t segmentCount () const
 Returns the number of segments. More...
 
CppUtilities::TimeSpan duration () const
 Returns the duration of the file if known; otherwise returns a time span of zero ticks. More...
 
CppUtilities::DateTime creationTime () const
 Returns the creation time of the file if known; otherwise the returned date time is null. More...
 
CppUtilities::DateTime modificationTime () const
 Returns the modification time of the file if known; otherwise the returned date time is null. More...
 
std::uint32_t timeScale () const
 Returns the time scale of the file if known; otherwise returns 0. More...
 
virtual void reset ()
 Discards all parsing results. More...
 

Static Public Member Functions

static std::uint64_t maxFullParseSize ()
 Returns the maximal file size for a "full parse" in byte. More...
 

Protected Member Functions

void internalParseHeader (Diagnostics &diag, AbortableProgressFeedback &progress) override
 Internally called to parse the header. More...
 
void internalParseTags (Diagnostics &diag, AbortableProgressFeedback &progress) override
 Internally called to parse the tags. More...
 
void internalParseTracks (Diagnostics &diag, AbortableProgressFeedback &progress) override
 Internally called to parse the tracks. More...
 
void internalParseChapters (Diagnostics &diag, AbortableProgressFeedback &progress) override
 Internally called to parse the chapters. More...
 
void internalParseAttachments (Diagnostics &diag, AbortableProgressFeedback &progress) override
 Internally called to parse the attachments. More...
 
void internalMakeFile (Diagnostics &diag, AbortableProgressFeedback &progress) override
 Internally called to make the file. More...
 
- Protected Member Functions inherited from TagParser::AbstractContainer
 AbstractContainer (std::iostream &stream, std::uint64_t startOffset)
 Constructs a new container for the specified file stream at the specified startOffset. More...
 
virtual void internalParseHeader (Diagnostics &diag, AbortableProgressFeedback &progress)
 Internally called to parse the header. More...
 
virtual void internalParseTags (Diagnostics &diag, AbortableProgressFeedback &progress)
 Internally called to parse the tags. More...
 
virtual void internalParseTracks (Diagnostics &diag, AbortableProgressFeedback &progress)
 Internally called to parse the tracks. More...
 
virtual void internalParseChapters (Diagnostics &diag, AbortableProgressFeedback &progress)
 Internally called to parse the chapters. More...
 
virtual void internalParseAttachments (Diagnostics &diag, AbortableProgressFeedback &progress)
 Internally called to parse the attachments. More...
 
virtual void internalMakeFile (Diagnostics &diag, AbortableProgressFeedback &progress)
 Internally called to make the file. More...
 

Additional Inherited Members

- Public Types inherited from TagParser::GenericContainer< MediaFileInfo, MatroskaTag, MatroskaTrack, EbmlElement >
using ContainerFileInfoType = MediaFileInfo
 
using ContainerTagType = MatroskaTag
 
using ContainerTrackType = MatroskaTrack
 
using ContainerElementType = EbmlElement
 
- Protected Attributes inherited from TagParser::GenericContainer< MediaFileInfo, MatroskaTag, MatroskaTrack, EbmlElement >
std::unique_ptr< EbmlElementm_firstElement
 
std::vector< std::unique_ptr< EbmlElement > > m_additionalElements
 
std::vector< std::unique_ptr< MatroskaTag > > m_tags
 
std::vector< std::unique_ptr< MatroskaTrack > > m_tracks
 
- Protected Attributes inherited from TagParser::AbstractContainer
std::uint64_t m_version
 
std::uint64_t m_readVersion
 
std::string m_doctype
 
std::uint64_t m_doctypeVersion
 
std::uint64_t m_doctypeReadVersion
 
std::vector< std::string > m_titles
 
CppUtilities::TimeSpan m_duration
 
CppUtilities::DateTime m_creationTime
 
CppUtilities::DateTime m_modificationTime
 
std::uint32_t m_timeScale
 
bool m_headerParsed
 
bool m_tagsParsed
 
bool m_tracksParsed
 
bool m_tracksAltered
 
bool m_chaptersParsed
 
bool m_attachmentsParsed
 

Detailed Description

Implementation of GenericContainer<MediaFileInfo, MatroskaTag, MatroskaTrack, EbmlElement>.

Definition at line 24 of file matroskacontainer.h.

Constructor & Destructor Documentation

◆ MatroskaContainer()

TagParser::MatroskaContainer::MatroskaContainer ( MediaFileInfo stream,
std::uint64_t  startOffset 
)

Constructs a new container for the specified fileInfo at the specified startOffset.

Definition at line 43 of file matroskacontainer.cpp.

◆ ~MatroskaContainer()

TagParser::MatroskaContainer::~MatroskaContainer ( )
override

Definition at line 56 of file matroskacontainer.cpp.

Member Function Documentation

◆ attachment()

MatroskaAttachment * TagParser::MatroskaContainer::attachment ( std::size_t  index)
inlineoverridevirtual

Returns the attachment with the specified index.

index must be less than attachmentCount().

Reimplemented from TagParser::AbstractContainer.

Definition at line 137 of file matroskacontainer.h.

◆ attachmentCount()

std::size_t TagParser::MatroskaContainer::attachmentCount ( ) const
inlineoverridevirtual

Returns the number of attachments the container holds.

Reimplemented from TagParser::AbstractContainer.

Definition at line 142 of file matroskacontainer.h.

◆ chapter()

MatroskaChapter * TagParser::MatroskaContainer::chapter ( std::size_t  index)
overridevirtual

Returns the chapter with the specified index.

index must be less than chapterCount().

Reimplemented from TagParser::AbstractContainer.

Definition at line 316 of file matroskacontainer.cpp.

◆ chapterCount()

size_t TagParser::MatroskaContainer::chapterCount ( ) const
overridevirtual

Returns the number of chapters the container holds.

Reimplemented from TagParser::AbstractContainer.

Definition at line 329 of file matroskacontainer.cpp.

◆ createAttachment()

MatroskaAttachment * TagParser::MatroskaContainer::createAttachment ( )
overridevirtual

Creates and returns a new attachment.

Returns
Returns the created attachment.
Remarks
The container keeps the ownership over the created attachment.

Reimplemented from TagParser::AbstractContainer.

Definition at line 338 of file matroskacontainer.cpp.

◆ determineElementPosition()

ElementPosition TagParser::MatroskaContainer::determineElementPosition ( std::uint64_t  elementId,
Diagnostics diag 
) const

Determines the position of the element with the specified elementId.

See also
determineTagPosition() and determineIndexPosition()

Definition at line 367 of file matroskacontainer.cpp.

◆ determineIndexPosition()

ElementPosition TagParser::MatroskaContainer::determineIndexPosition ( Diagnostics diag) const
overridevirtual

Determines the position of the index.

Returns
Returns ElementPosition::BeforeData or ElementPosition::AfterData if the position could be determined; otherwise returns ElementPosition::Keep.
Remarks
  • It might be required to parse tracks before the index position can be determined.
  • Not be applicable for files composed of multiple segments.
See also
MediaFileInfo::indexPosition()

Reimplemented from TagParser::AbstractContainer.

Definition at line 398 of file matroskacontainer.cpp.

◆ determineTagPosition()

ElementPosition TagParser::MatroskaContainer::determineTagPosition ( Diagnostics diag) const
overridevirtual

Determines the position of the tags inside the file.

Returns
Returns ElementPosition::BeforeData or ElementPosition::AfterData if the position could be determined; otherwise returns ElementPosition::Keep.
Remarks
  • It might be required to parse tags before the tag position can be determined.
  • Not be applicable for files composed of multiple segments.
See also
MediaFileInfo::tagPosition()

Reimplemented from TagParser::AbstractContainer.

Definition at line 393 of file matroskacontainer.cpp.

◆ editionEntires()

const std::vector< std::unique_ptr< MatroskaEditionEntry > > & TagParser::MatroskaContainer::editionEntires ( ) const
inline

Returns the edition entries.

Definition at line 132 of file matroskacontainer.h.

◆ internalMakeFile()

void TagParser::MatroskaContainer::internalMakeFile ( Diagnostics diag,
AbortableProgressFeedback progress 
)
overrideprotectedvirtual

Internally called to make the file.

Must be implemented when subclassing.

Exceptions
ThrowsFailure or a derived class when a parsing error occurs.
Throwsstd::ios_base::failure when an IO error occurs.

Reimplemented from TagParser::AbstractContainer.

Definition at line 856 of file matroskacontainer.cpp.

◆ internalParseAttachments()

void TagParser::MatroskaContainer::internalParseAttachments ( Diagnostics diag,
AbortableProgressFeedback progress 
)
overrideprotectedvirtual

Internally called to parse the attachments.

Must be implemented when subclassing to provide this feature.

Exceptions
ThrowsFailure or a derived class when a parsing error occurs.
Throwsstd::ios_base::failure when an IO error occurs.

Reimplemented from TagParser::AbstractContainer.

Definition at line 772 of file matroskacontainer.cpp.

◆ internalParseChapters()

void TagParser::MatroskaContainer::internalParseChapters ( Diagnostics diag,
AbortableProgressFeedback progress 
)
overrideprotectedvirtual

Internally called to parse the chapters.

Must be implemented when subclassing to provide this feature.

Exceptions
ThrowsFailure or a derived class when a parsing error occurs.
Throwsstd::ios_base::failure when an IO error occurs.

Reimplemented from TagParser::AbstractContainer.

Definition at line 738 of file matroskacontainer.cpp.

◆ internalParseHeader()

void TagParser::MatroskaContainer::internalParseHeader ( Diagnostics diag,
AbortableProgressFeedback progress 
)
overrideprotectedvirtual

Internally called to parse the header.

Must be implemented when subclassing to provide this feature.

Exceptions
ThrowsFailure or a derived class when a parsing error occurs.
Throwsstd::ios_base::failure when an IO error occurs.

Reimplemented from TagParser::AbstractContainer.

Definition at line 403 of file matroskacontainer.cpp.

◆ internalParseTags()

void TagParser::MatroskaContainer::internalParseTags ( Diagnostics diag,
AbortableProgressFeedback progress 
)
overrideprotectedvirtual

Internally called to parse the tags.

Must be implemented when subclassing to provide this feature.

Exceptions
ThrowsFailure or a derived class when a parsing error occurs.
Throwsstd::ios_base::failure when an IO error occurs.

Reimplemented from TagParser::AbstractContainer.

Definition at line 661 of file matroskacontainer.cpp.

◆ internalParseTracks()

void TagParser::MatroskaContainer::internalParseTracks ( Diagnostics diag,
AbortableProgressFeedback progress 
)
overrideprotectedvirtual

Internally called to parse the tracks.

Must be implemented when subclassing to provide this feature.

Exceptions
ThrowsFailure or a derived class when a parsing error occurs.
Throwsstd::ios_base::failure when an IO error occurs.

Reimplemented from TagParser::AbstractContainer.

Definition at line 702 of file matroskacontainer.cpp.

◆ maxFullParseSize()

std::uint64_t TagParser::MatroskaContainer::maxFullParseSize ( )
inlinestatic

Returns the maximal file size for a "full parse" in byte.

The "Tags" element (which holds the tag information) is commonly at the end of a Matroska file. Hence the parser needs to walk through the entire file to find the tag information if no "SeekHead" element is present which might causes long loading times. To avoid this a maximal file size for a "full parse" can be specified. The disadvantage is that the parser relies on the presence of a SeekHead element on larger files to retrieve tag information.

The default value is 50 MiB.

See also
setMaxFullParseSize()

Definition at line 115 of file matroskacontainer.h.

◆ maxIdLength()

std::uint64_t TagParser::MatroskaContainer::maxIdLength ( ) const
inline

Returns the maximal ID length in bytes.

Definition at line 81 of file matroskacontainer.h.

◆ maxSizeLength()

std::uint64_t TagParser::MatroskaContainer::maxSizeLength ( ) const
inline

Returns the maximal size length in bytes.

Definition at line 89 of file matroskacontainer.h.

◆ reset()

void TagParser::MatroskaContainer::reset ( )
overridevirtual

Discards all parsing results.

Reimplemented from TagParser::AbstractContainer.

Definition at line 60 of file matroskacontainer.cpp.

◆ seekInfos()

const std::vector< std::unique_ptr< MatroskaSeekInfo > > & TagParser::MatroskaContainer::seekInfos ( ) const
inline

Returns seek information read from "SeekHead"-elements when parsing segment info.

Definition at line 97 of file matroskacontainer.h.

◆ segmentCount()

std::size_t TagParser::MatroskaContainer::segmentCount ( ) const
inlineoverridevirtual

Returns the number of segments.

Reimplemented from TagParser::AbstractContainer.

Definition at line 152 of file matroskacontainer.h.

◆ setMaxFullParseSize()

void TagParser::MatroskaContainer::setMaxFullParseSize ( std::uint64_t  maxFullParseSize)
inline

Sets the maximal file size for a "full parse" in byte.

See also
maxFullParseSize()

Definition at line 124 of file matroskacontainer.h.

◆ supportsTitle()

bool TagParser::MatroskaContainer::supportsTitle ( ) const
inlineoverridevirtual

Returns whether the title property is supported.

Reimplemented from TagParser::AbstractContainer.

Definition at line 147 of file matroskacontainer.h.

◆ validateIndex()

void TagParser::MatroskaContainer::validateIndex ( Diagnostics diag,
AbortableProgressFeedback progress 
)

Validates the file index (cue entries).

Remarks
Checks only for cluster positions and missing, unknown or surplus elements.

Definition at line 85 of file matroskacontainer.cpp.


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