Tag Parser: TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType > Class Template Reference

Tag Parser 12.5.3 C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags

Loading...
Searching...
No Matches
Public Types | Public Member Functions | Protected Attributes | List of all members
TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType > Class Template Reference

The GenericContainer class helps parsing header, track, tag and chapter information of a file. More...

`#include <genericcontainer.h>`

Inheritance diagram for TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >:
[legend]
Collaboration diagram for TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >:
[legend]

## Public Types
using | ContainerFileInfoType = FileInfoType
using | ContainerTagType = TagType
using | ContainerTrackType = TrackType
using | ContainerElementType = ElementType

## Public Member Functions
| GenericContainer (FileInfoType &fileInfo, std::uint64_t startOffset)
| Constructs a new container for the specified fileInfo at the specified startOffset.
| ~GenericContainer () override
| Destroys the container.
void | validateElementStructure (Diagnostics &diag, AbortableProgressFeedback &progress, std::uint64_t *paddingSize=nullptr)
| Parses all elements the file consists of.
FileInfoType & | fileInfo () const
| Returns the related file info.
ElementType * | firstElement () const
| Returns the first element of the file if available; otherwiese returns nullptr.
const std::vector< std::unique_ptr< ElementType > > & | additionalElements () const
| Returns all available additional elements.
std::vector< std::unique_ptr< ElementType > > & | additionalElements ()
| Returns all available additional elements.
TagType * | tag (std::size_t index) override
| Returns the tag with the specified index.
std::size_t | tagCount () const override
| Returns the number of tags attached to the container.
TrackType * | track (std::size_t index) override
| Returns the track with the specified index.
TrackType * | trackById (std::uint64_t id)
std::size_t | trackCount () const override
| Returns the number of tracks the container holds.
const std::vector< std::unique_ptr< TagType > > & | tags () const
| Returns the tags of the file.
std::vector< std::unique_ptr< TagType > > & | tags ()
| Returns the tags of the file.
const std::vector< std::unique_ptr< TrackType > > & | tracks () const
| Returns the tracks of the file.
std::vector< std::unique_ptr< TrackType > > & | tracks ()
| Returns the tracks of the file.
TagType * | createTag (const TagTarget &target=TagTarget()) override
| Creates and returns a tag for the specified target.
bool | removeTag (Tag *tag) override
| Removes the specified tag from the container.
void | removeAllTags () override
| Removes all tags attached to the container.
bool | addTrack (TrackType *track)
| Adds the specified track to the container.
bool | removeTrack (AbstractTrack *track) override
| Removes the specified track to the container.
void | removeAllTracks () override
| Removes all tracks from the container.
void | reset () override
| Discards all parsing results.
Public Member Functions inherited from TagParser::AbstractContainer
virtual | ~AbstractContainer ()
| Destroys the container.
std::iostream & | stream ()
| Returns the related stream.
void | setStream (std::iostream &stream)
| Sets the related stream.
std::uint64_t | startOffset () const
| Returns the start offset in the related stream.
CppUtilities::BinaryReader & | reader ()
| Returns the related BinaryReader.
CppUtilities::BinaryWriter & | writer ()
| Returns the related BinaryWriter.
void | parseHeader (Diagnostics &diag, AbortableProgressFeedback &progress)
| Parses the header if not parsed yet.
void | parseTags (Diagnostics &diag, AbortableProgressFeedback &progress)
| Parses the tag information if not parsed yet.
void | parseTracks (Diagnostics &diag, AbortableProgressFeedback &progress)
| Parses the tracks of the file if not parsed yet.
void | parseChapters (Diagnostics &diag, AbortableProgressFeedback &progress)
| Parses the chapters of the file if not parsed yet.
void | parseAttachments (Diagnostics &diag, AbortableProgressFeedback &progress)
| Parses the attachments of the file if not parsed yet.
void | makeFile (Diagnostics &diag, AbortableProgressFeedback &progress)
| Rewrites the file to apply changed tag information.
bool | isHeaderParsed () const
| Returns an indication whether the header has been parsed yet.
bool | areTagsParsed () const
| Returns an indication whether the tags have been parsed yet.
bool | areTracksParsed () const
| Returns an indication whether the tracks have been parsed yet.
bool | areChaptersParsed () const
| Returns an indication whether the chapters have been parsed yet.
bool | areAttachmentsParsed () const
| Returns an indication whether the attachments have been parsed yet.
virtual ElementPosition | determineTagPosition (Diagnostics &diag) const
| Determines the position of the tags inside the file.
virtual bool | supportsTrackModifications () const
| Returns whether the implementation supports adding or removing of tracks.
virtual ElementPosition | determineIndexPosition (Diagnostics &diag) const
| Determines the position of the index.
virtual AbstractChapter * | chapter (std::size_t index)
| Returns the chapter with the specified index.
virtual std::size_t | chapterCount () const
| Returns the number of chapters the container holds.
virtual AbstractAttachment * | createAttachment ()
| Creates and returns a new attachment.
virtual AbstractAttachment * | attachment (std::size_t index)
| Returns the attachment with the specified index.
virtual std::size_t | attachmentCount () const
| Returns the number of attachments the container holds.
std::uint64_t | version () const
| Returns the version if known; otherwise returns 0.
std::uint64_t | readVersion () const
| Returns the "read version" if known; otherwise returns 0.
const std::string & | documentType () const
| Returns a string that describes the document type if available; otherwise returns an empty string.
std::uint64_t | doctypeVersion () const
| Returns the document type version if known; otherwise returns 0.
std::uint64_t | doctypeReadVersion () const
| Returns the document type "read version" if known; otherwise returns 0.
const std::vector< std::string > & | titles () const
| Returns the title(s) of the file.
void | setTitle (std::string_view title, std::size_t segmentIndex=0)
| Sets the title for the specified segment.
virtual bool | supportsTitle () const
| Returns whether the title property is supported.
const std::vector< std::string > & | muxingApplications () const
| Returns the muxing applications specified as meta-data.
const std::vector< std::string > & | writingApplications () const
| Returns the writing applications specified as meta-data.
virtual std::size_t | segmentCount () const
| Returns the number of segments.
CppUtilities::TimeSpan | duration () const
| Returns the duration of the file if known; otherwise returns a time span of zero ticks.
CppUtilities::DateTime | creationTime () const
| Returns the creation time of the file if known; otherwise the returned date time is null.
CppUtilities::DateTime | modificationTime () const
| Returns the modification time of the file if known; otherwise the returned date time is null.
std::uint32_t | timeScale () const
| Returns the time scale of the file if known; otherwise returns 0.

## Protected Attributes
std::unique_ptr< ElementType > | m_firstElement
std::vector< std::unique_ptr< ElementType > > | m_additionalElements
std::vector< std::unique_ptr< TagType > > | m_tags
std::vector< std::unique_ptr< TrackType > > | 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

## Additional Inherited Members
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.
virtual void | internalParseHeader (Diagnostics &diag, AbortableProgressFeedback &progress)
| Internally called to parse the header.
virtual void | internalParseTags (Diagnostics &diag, AbortableProgressFeedback &progress)
| Internally called to parse the tags.
virtual void | internalParseTracks (Diagnostics &diag, AbortableProgressFeedback &progress)
| Internally called to parse the tracks.
virtual void | internalParseChapters (Diagnostics &diag, AbortableProgressFeedback &progress)
| Internally called to parse the chapters.
virtual void | internalParseAttachments (Diagnostics &diag, AbortableProgressFeedback &progress)
| Internally called to parse the attachments.
virtual void | internalMakeFile (Diagnostics &diag, AbortableProgressFeedback &progress)
| Internally called to make the file.
std::vector< std::string > & | muxingApplications ()
| Returns the muxing applications specified as meta-data.
std::vector< std::string > & | writingApplications ()
| Returns the writing applications specified as meta-data.

## Detailed Description

template<class FileInfoType, class TagType, class TrackType, class ElementType>
class TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >

The GenericContainer class helps parsing header, track, tag and chapter information of a file.

Template Parameters

  FileInfoType | Specifies the file info class (a class derived from TagParser::BasicFileInfo) which is used to specify the related file.
  TagType | Specifies the class which is used to deal with the tag information of the file.
  TrackType | Specifies the class which is used to deal with the track of the file.
  ElementType | Specifies the class which is used to deal with the elements the file consists of.

Definition at line 22 of file genericcontainer.h.

## Member Typedef Documentation

## ◆ ContainerElementType

template<class FileInfoType, class TagType, class TrackType, class ElementType>

using TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::ContainerElementType = ElementType

Definition at line 55 of file genericcontainer.h.

## ◆ ContainerFileInfoType

template<class FileInfoType, class TagType, class TrackType, class ElementType>

using TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::ContainerFileInfoType = FileInfoType

Definition at line 52 of file genericcontainer.h.

## ◆ ContainerTagType

template<class FileInfoType, class TagType, class TrackType, class ElementType>

using TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::ContainerTagType = TagType

Definition at line 53 of file genericcontainer.h.

## ◆ ContainerTrackType

template<class FileInfoType, class TagType, class TrackType, class ElementType>

using TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::ContainerTrackType = TrackType

Definition at line 54 of file genericcontainer.h.

## Constructor & Destructor Documentation

## ◆ GenericContainer()

template<class FileInfoType, class TagType, class TrackType, class ElementType>

TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::GenericContainer | ( | FileInfoType & | fileInfo,
|  | std::uint64_t | startOffset )

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

Definition at line 71 of file genericcontainer.h.

## ◆ ~GenericContainer()

template<class FileInfoType, class TagType, class TrackType, class ElementType>

TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::~GenericContainer | ( |  | ) |
| override

Destroys the container.

Destroys the reader, the writer and track, tag, chapter and attachment objects as well. Does NOT destroy the stream which has been specified when constructing the object.

Definition at line 84 of file genericcontainer.h.

## Member Function Documentation

## ◆ additionalElements() [1/2]

template<class FileInfoType, class TagType, class TrackType, class ElementType>

std::vector< std::unique_ptr< ElementType > > & TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::additionalElements | ( |  | ) |
| inline

Returns all available additional elements.

The parser might decide to split up a file's element tree to skip irrelevant elements to achieve better performance. This method gives access to those sub element trees. Each of the returned elements represents an independent element tree within the file.

Definition at line 158 of file genericcontainer.h.

## ◆ additionalElements() [2/2]

template<class FileInfoType, class TagType, class TrackType, class ElementType>

const std::vector< std::unique_ptr< ElementType > > & TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::additionalElements | ( |  | ) | const
| inline

Returns all available additional elements.

The parser might decide to split up a file's element tree to skip irrelevant elements to achieve better performance. This method gives access to those sub element trees. Each of the returned elements represents an independent element tree within the file.

Definition at line 145 of file genericcontainer.h.

## ◆ addTrack()

template<class FileInfoType, class TagType, class TrackType, class ElementType>

bool TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::addTrack | ( | TrackType * | track | ) |

Adds the specified track to the container.

Adding tracks might be not supported by the implementation.

See also
  supportsTrackModifications()

The tracks needs to be parsed before additional tracks can be added.

See also
  areTracksParsed()
  parseTracks()

Remarks
  The container takes ownership over the specified track if it was possible to add the track. This makes adding a track from another container impossible without removing it from the other container first.

Returns
  Returns an indication whether the track could be added.

Definition at line 315 of file genericcontainer.h.

## ◆ createTag()

template<class FileInfoType, class TagType, class TrackType, class ElementType>

TagType * TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::createTag | ( | const TagTarget & | target = TagTarget() | ) |
| overridevirtual

Creates and returns a tag for the specified target.

Remarks
  - If there is already a tag (for the specified target) present, no new tag will be created. The present tag will be returned instead.
  - If an empty target is specified it will be ignored.
  - If targets aren't supported the specified target will be ignored.
  - If no tag could be created, nullptr is returned.
  - The container keeps the ownership over the created tag.

Reimplemented from TagParser::AbstractContainer.

Reimplemented in TagParser::OggContainer.

Definition at line 259 of file genericcontainer.h.

## ◆ fileInfo()

template<class FileInfoType, class TagType, class TrackType, class ElementType>

FileInfoType & TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::fileInfo | ( |  | ) | const
| inline

Returns the related file info.

The related file info has been specified when constructing the container.

Definition at line 114 of file genericcontainer.h.

## ◆ firstElement()

template<class FileInfoType, class TagType, class TrackType, class ElementType>

ElementType * TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::firstElement | ( |  | ) | const
| inline

Returns the first element of the file if available; otherwiese returns nullptr.

This method gives access to the element structure of the container - the entire element tree can be looked up using the nextSibling() and firstChild() methods of the returned element.

The header needs to be parsed before (see parseHeader()).

The container keeps ownership over the returned element.

See also
  isHeaderParsed()

Definition at line 132 of file genericcontainer.h.

## ◆ removeAllTags()

template<class FileInfoType, class TagType, class TrackType, class ElementType>

void TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::removeAllTags | ( |  | ) |
| inlineoverridevirtual

Removes all tags attached to the container.

The tags need to be parsed before they can be removed.

See also
  areTagsParsed()
  parseTags()

Remarks
  The current tag objects are destroyed. All pointers obtained by calling tag() are invalidated.

Reimplemented from TagParser::AbstractContainer.

Reimplemented in TagParser::OggContainer.

Definition at line 293 of file genericcontainer.h.

## ◆ removeAllTracks()

template<class FileInfoType, class TagType, class TrackType, class ElementType>

void TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::removeAllTracks | ( |  | ) |
| overridevirtual

Removes all tracks from the container.

Modifying tracks might be not supported by the implementation.

See also
  supportsTrackModifications()

The tracks need to be parsed before they can be removed.

See also
  areTracksParsed()
  parseTracks()

Remarks
  The current track objects are destroyed. All pointers obtained by calling track() are invalidated.

Reimplemented from TagParser::AbstractContainer.

Definition at line 359 of file genericcontainer.h.

## ◆ removeTag()

template<class FileInfoType, class TagType, class TrackType, class ElementType>

bool TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::removeTag | ( | Tag * | tag | ) |
| overridevirtual

Removes the specified tag from the container.

Does nothing if the tag is not attached to the container.

The tags need to be parsed before a removal is possible.

See also
  areTagsParsed()
  parseTags()

Remarks
  The tag is not destroyed. The ownership is transferred to the caller.

Returns
  Returns whether the tag could be removed.

Reimplemented from TagParser::AbstractContainer.

Reimplemented in TagParser::OggContainer.

Definition at line 281 of file genericcontainer.h.

## ◆ removeTrack()

template<class FileInfoType, class TagType, class TrackType, class ElementType>

bool TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::removeTrack | ( | AbstractTrack * | track | ) |
| overridevirtual

Removes the specified track to the container.

Removal of tracks might be not supported by the implementation.

See also
  supportsTrackModifications()

The tracks need to be parsed before a removal is possible.

See also
  areTracksParsed()
  parseTracks()

Remarks
  The track is not destroyed. The ownership is transferred to the caller.

Returns
  Returns whether the track could be removed.

Reimplemented from TagParser::AbstractContainer.

Definition at line 336 of file genericcontainer.h.

## ◆ reset()

template<class FileInfoType, class TagType, class TrackType, class ElementType>

void TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::reset | ( |  | ) |
| overridevirtual

Discards all parsing results.

Reimplemented from TagParser::AbstractContainer.

Reimplemented in TagParser::MatroskaContainer, TagParser::Mp4Container, and TagParser::OggContainer.

Definition at line 368 of file genericcontainer.h.

## ◆ tag()

template<class FileInfoType, class TagType, class TrackType, class ElementType>

TagType * TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::tag | ( | std::size_t | index | ) |
| inlineoverridevirtual

Returns the tag with the specified index.

index must be less than tagCount().

Reimplemented from TagParser::AbstractContainer.

Reimplemented in TagParser::OggContainer.

Definition at line 164 of file genericcontainer.h.

## ◆ tagCount()

template<class FileInfoType, class TagType, class TrackType, class ElementType>

std::size_t TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::tagCount | ( |  | ) | const
| inlineoverridevirtual

Returns the number of tags attached to the container.

This method returns zero if the tags have not been parsed yet.

Reimplemented from TagParser::AbstractContainer.

Reimplemented in TagParser::OggContainer.

Definition at line 170 of file genericcontainer.h.

## ◆ tags() [1/2]

template<class FileInfoType, class TagType, class TrackType, class ElementType>

std::vector< std::unique_ptr< TagType > > & TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::tags | ( |  | ) |
| inline

Returns the tags of the file.

The tags need to be parsed before (see parseTags()).

The container keeps ownership over the returned tags. Do not push or remove elements to the returned vector.

See also
  areTagsParsed()

Definition at line 223 of file genericcontainer.h.

## ◆ tags() [2/2]

template<class FileInfoType, class TagType, class TrackType, class ElementType>

const std::vector< std::unique_ptr< TagType > > & TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::tags | ( |  | ) | const
| inline

Returns the tags of the file.

The tags need to be parsed before (see parseTags()).

The container keeps ownership over the returned tags.

See also
  areTagsParsed()

Definition at line 208 of file genericcontainer.h.

## ◆ track()

template<class FileInfoType, class TagType, class TrackType, class ElementType>

TrackType * TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::track | ( | std::size_t | index | ) |
| inlineoverridevirtual

Returns the track with the specified index.

index must be less than trackCount().

Reimplemented from TagParser::AbstractContainer.

Definition at line 176 of file genericcontainer.h.

## ◆ trackById()

template<class FileInfoType, class TagType, class TrackType, class ElementType>

TrackType * TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::trackById | ( | std::uint64_t | id | ) |
| inline

Definition at line 182 of file genericcontainer.h.

## ◆ trackCount()

template<class FileInfoType, class TagType, class TrackType, class ElementType>

std::size_t TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::trackCount | ( |  | ) | const
| inlineoverridevirtual

Returns the number of tracks the container holds.

Reimplemented from TagParser::AbstractContainer.

Definition at line 193 of file genericcontainer.h.

## ◆ tracks() [1/2]

template<class FileInfoType, class TagType, class TrackType, class ElementType>

std::vector< std::unique_ptr< TrackType > > & TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::tracks | ( |  | ) |
| inline

Returns the tracks of the file.

The tags need to be parsed before (see parseTracks()).

The container keeps ownership over the returned tracks. Do not push or remove elements to the returned vector.

See also
  areTracksParsed()

Definition at line 253 of file genericcontainer.h.

## ◆ tracks() [2/2]

template<class FileInfoType, class TagType, class TrackType, class ElementType>

const std::vector< std::unique_ptr< TrackType > > & TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::tracks | ( |  | ) | const
| inline

Returns the tracks of the file.

The tags need to be parsed before (see parseTracks()).

The container keeps ownership over the returned tracks.

See also
  areTracksParsed()

Definition at line 238 of file genericcontainer.h.

## ◆ validateElementStructure()

template<class FileInfoType, class TagType, class TrackType, class ElementType>

void TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::validateElementStructure | ( | Diagnostics & | diag,
|  | AbortableProgressFeedback & | progress,
|  | std::uint64_t * | paddingSize = nullptr )
| inline

Parses all elements the file consists of.

All parsing notifications will be stored in gatheredNotifications. The size of padding/void elements will be accumulated and stored in at paddingSize if it is not a null pointer.

Exceptions

  Throws | Failure or a derived class when a parsing error occurs.
  Throws | std::ios_base::failure when an IO error occurs.

Definition at line 99 of file genericcontainer.h.

## Member Data Documentation

## ◆ m_additionalElements

template<class FileInfoType, class TagType, class TrackType, class ElementType>

std::vector<std::unique_ptr<ElementType> > TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::m_additionalElements
| protected

Definition at line 59 of file genericcontainer.h.

## ◆ m_firstElement

template<class FileInfoType, class TagType, class TrackType, class ElementType>

std::unique_ptr<ElementType> TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::m_firstElement
| protected

Definition at line 58 of file genericcontainer.h.

## ◆ m_tags

template<class FileInfoType, class TagType, class TrackType, class ElementType>

std::vector<std::unique_ptr<TagType> > TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::m_tags
| protected

Definition at line 60 of file genericcontainer.h.

## ◆ m_tracks

template<class FileInfoType, class TagType, class TrackType, class ElementType>

std::vector<std::unique_ptr<TrackType> > TagParser::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::m_tracks
| protected

Definition at line 61 of file genericcontainer.h.

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

- genericcontainer.h