Tag Parser  6.4.0
C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags
Public Types | Public Member Functions | Protected Attributes | List of all members
Media::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 Media::GenericContainer< FileInfoType, TagType, TrackType, ElementType >:
[legend]
Collaboration diagram for Media::GenericContainer< FileInfoType, TagType, TrackType, ElementType >:
[legend]

Public Types

typedef FileInfoType fileInfoType
 
typedef TagType tagType
 
typedef TrackType trackType
 
typedef ElementType elementType
 
- Public Types inherited from Media::StatusProvider
typedef std::function< void(StatusProvider &sender)> CallbackFunction
 
typedef std::vector< CallbackFunctionCallbackVector
 
typedef std::pair< int, CallbackFunctionCallbackPair
 

Public Member Functions

 GenericContainer (FileInfoType &fileInfo, uint64 startOffset)
 Constructs a new container for the specified fileInfo at the specified startOffset. More...
 
 ~GenericContainer ()
 Destroys the container. More...
 
void validateElementStructure (NotificationList &gatheredNotifications, uint64 *paddingSize=nullptr)
 Parses all elements the file consists of. More...
 
FileInfoType & fileInfo () const
 Returns the related file info. More...
 
ElementType * firstElement () const
 Returns the first element of the file if available; otherwiese returns nullptr. More...
 
const std::vector< std::unique_ptr< ElementType > > & additionalElements () const
 Returns all available additional elements. More...
 
std::vector< std::unique_ptr< ElementType > > & additionalElements ()
 Returns all available additional elements. More...
 
TagTypetag (std::size_t index)
 Returns the tag with the specified index. More...
 
std::size_t tagCount () const
 Returns the number of tags attached to the container. More...
 
TrackTypetrack (std::size_t index)
 Returns the track with the specified index. More...
 
TrackTypetrackById (uint64 id)
 
std::size_t trackCount () const
 Returns the number of tracks the container holds. More...
 
const std::vector< std::unique_ptr< TagType > > & tags () const
 Returns the tags of the file. More...
 
std::vector< std::unique_ptr< TagType > > & tags ()
 Returns the tags of the file. More...
 
const std::vector< std::unique_ptr< TrackType > > & tracks () const
 Returns the tracks of the file. More...
 
std::vector< std::unique_ptr< TrackType > > & tracks ()
 Returns the tracks of the file. More...
 
TagTypecreateTag (const TagTarget &target=TagTarget())
 Creates and returns a tag for the specified target. More...
 
bool removeTag (Tag *tag)
 Removes the specified tag from the container. More...
 
void removeAllTags ()
 Removes all tags attached to the container. More...
 
bool addTrack (TrackType *track)
 Adds the specified track to the container. More...
 
bool removeTrack (AbstractTrack *track)
 Removes the specified track to the container. More...
 
void removeAllTracks ()
 Removes all tracks from the container. More...
 
void reset ()
 Discards all parsing results. More...
 
- Public Member Functions inherited from Media::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...
 
uint64 startOffset () const
 Returns the start offset in the related stream. More...
 
IoUtilities::BinaryReader & reader ()
 Returns the related BinaryReader. More...
 
IoUtilities::BinaryWriter & writer ()
 Returns the related BinaryWriter. More...
 
void parseHeader ()
 Parses the header if not parsed yet. More...
 
void parseTags ()
 Parses the tag information if not parsed yet. More...
 
void parseTracks ()
 Parses the tracks of the file if not parsed yet. More...
 
void parseChapters ()
 Parses the chapters of the file if not parsed yet. More...
 
void parseAttachments ()
 Parses the attachments of the file if not parsed yet. More...
 
void makeFile ()
 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 ElementPosition determineTagPosition () const
 Determines the position of the tags inside the file. More...
 
virtual bool supportsTrackModifications () const
 Returns whether the implementation supports adding or removing of tracks. More...
 
virtual ElementPosition determineIndexPosition () 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...
 
uint64 version () const
 Returns the version if known; otherwise returns 0. More...
 
uint64 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...
 
uint64 doctypeVersion () const
 Returns the document type version if known; otherwise returns 0. More...
 
uint64 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 (const std::string &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...
 
ChronoUtilities::TimeSpan duration () const
 Returns the duration of the file if known; otherwise returns a time span of zero ticks. More...
 
ChronoUtilities::DateTime creationTime () const
 Returns the creation time of the file if known; otherwise the returned date time is null. More...
 
ChronoUtilities::DateTime modificationTime () const
 Returns the modification time of the file if known; otherwise the returned date time is null. More...
 
uint32 timeScale () const
 Returns the time scale of the file if known; otherwise returns 0. More...
 
- Public Member Functions inherited from Media::StatusProvider
const NotificationListnotifications () 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...
 
StatusProviderusedProvider ()
 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 &notification)
 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 &notifications)
 This protected method is meant to be called by the derived class to add the specified notifications. More...
 

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 Media::AbstractContainer
uint64 m_version
 
uint64 m_readVersion
 
std::string m_doctype
 
uint64 m_doctypeVersion
 
uint64 m_doctypeReadVersion
 
std::vector< std::string > m_titles
 
ChronoUtilities::TimeSpan m_duration
 
ChronoUtilities::DateTime m_creationTime
 
ChronoUtilities::DateTime m_modificationTime
 
uint32 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 Media::AbstractContainer
 AbstractContainer (std::iostream &stream, uint64 startOffset)
 Constructs a new container for the specified file stream at the specified startOffset. More...
 
virtual void internalParseHeader ()
 Internally called to parse the header. More...
 
virtual void internalParseTags ()
 Internally called to parse the tags. More...
 
virtual void internalParseTracks ()
 Internally called to parse the tracks. More...
 
virtual void internalParseChapters ()
 Internally called to parse the chapters. More...
 
virtual void internalParseAttachments ()
 Internally called to parse the attachments. More...
 
virtual void internalMakeFile ()
 Internally called to make the file. More...
 
- Protected Member Functions inherited from Media::StatusProvider
 StatusProvider ()
 Constructs a new StatusProvider. More...
 

Detailed Description

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

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

Template Parameters
FileInfoTypeSpecifies the file info class (a class derived from Media::BasicFileInfo) which is used to specify the related file.
TagTypeSpecifies the class which is used to deal with the tag information of the file.
TrackTypeSpecifies the class which is used to deal with the track of the file.
ElementTypeSpecifies the class which is used to deal with the elements the file consists of.

Definition at line 24 of file genericcontainer.h.

Member Typedef Documentation

◆ elementType

template<class FileInfoType, class TagType, class TrackType, class ElementType>
typedef ElementType Media::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::elementType

Definition at line 58 of file genericcontainer.h.

◆ fileInfoType

template<class FileInfoType, class TagType, class TrackType, class ElementType>
typedef FileInfoType Media::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::fileInfoType

Definition at line 55 of file genericcontainer.h.

◆ tagType

template<class FileInfoType, class TagType, class TrackType, class ElementType>
typedef TagType Media::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::tagType

Definition at line 56 of file genericcontainer.h.

◆ trackType

template<class FileInfoType, class TagType, class TrackType, class ElementType>
typedef TrackType Media::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::trackType

Definition at line 57 of file genericcontainer.h.

Constructor & Destructor Documentation

◆ GenericContainer()

template<class FileInfoType, class TagType , class TrackType , class ElementType >
Media::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::GenericContainer ( FileInfoType &  fileInfo,
uint64  startOffset 
)

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

Definition at line 74 of file genericcontainer.h.

◆ ~GenericContainer()

template<class FileInfoType , class TagType , class TrackType , class ElementType >
Media::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::~GenericContainer ( )

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 86 of file genericcontainer.h.

Member Function Documentation

◆ additionalElements() [1/2]

template<class FileInfoType , class TagType , class TrackType , class ElementType >
const std::vector< std::unique_ptr< ElementType > > & Media::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 achive 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.

◆ additionalElements() [2/2]

template<class FileInfoType , class TagType , class TrackType , class ElementType >
std::vector< std::unique_ptr< ElementType > > & Media::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 achive 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.

◆ addTrack()

template<class FileInfoType , class TagType , class TrackType, class ElementType >
bool Media::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 316 of file genericcontainer.h.

◆ createTag()

template<class FileInfoType , class TagType , class TrackType , class ElementType >
TagType * Media::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::createTag ( const TagTarget target = TagTarget())
virtual

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 Media::AbstractContainer.

Definition at line 259 of file genericcontainer.h.

◆ fileInfo()

template<class FileInfoType , class TagType , class TrackType , class ElementType >
FileInfoType & Media::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::fileInfo ( ) const
inline

Returns the related file info.

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

Definition at line 114 of file genericcontainer.h.

◆ firstElement()

template<class FileInfoType , class TagType , class TrackType , class ElementType >
ElementType * Media::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 Media::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::removeAllTags ( )
inlinevirtual

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 Media::AbstractContainer.

Definition at line 294 of file genericcontainer.h.

◆ removeAllTracks()

template<class FileInfoType , class TagType , class TrackType , class ElementType >
void Media::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::removeAllTracks ( )
virtual

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 Media::AbstractContainer.

Definition at line 359 of file genericcontainer.h.

◆ removeTag()

template<class FileInfoType , class TagType , class TrackType , class ElementType >
bool Media::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::removeTag ( Tag tag)
virtual

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 transfered to the caller.
Returns
Returns whether the tag could be removed.

Reimplemented from Media::AbstractContainer.

Definition at line 282 of file genericcontainer.h.

◆ removeTrack()

template<class FileInfoType , class TagType , class TrackType , class ElementType >
bool Media::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::removeTrack ( AbstractTrack track)
virtual

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 transfered to the caller.
Returns
Returns whether the track could be removed.

Reimplemented from Media::AbstractContainer.

Definition at line 337 of file genericcontainer.h.

◆ reset()

template<class FileInfoType , class TagType , class TrackType , class ElementType >
void Media::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::reset ( )
virtual

Discards all parsing results.

Reimplemented from Media::AbstractContainer.

Definition at line 368 of file genericcontainer.h.

◆ tag()

template<class FileInfoType , class TagType , class TrackType , class ElementType >
TagType * Media::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::tag ( std::size_t  index)
inlinevirtual

Returns the tag with the specified index.

index must be less than tagCount().

Reimplemented from Media::AbstractContainer.

Definition at line 164 of file genericcontainer.h.

◆ tagCount()

template<class FileInfoType , class TagType , class TrackType , class ElementType >
std::size_t Media::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::tagCount ( ) const
inlinevirtual

Returns the number of tags attached to the container.

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

Reimplemented from Media::AbstractContainer.

Definition at line 170 of file genericcontainer.h.

◆ tags() [1/2]

template<class FileInfoType , class TagType , class TrackType , class ElementType >
const std::vector< std::unique_ptr< TagType > > & Media::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.

◆ tags() [2/2]

template<class FileInfoType , class TagType , class TrackType , class ElementType >
std::vector< std::unique_ptr< TagType > > & Media::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.

◆ track()

template<class FileInfoType , class TagType , class TrackType , class ElementType >
TrackType * Media::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::track ( std::size_t  index)
inlinevirtual

Returns the track with the specified index.

index must be less than trackCount().

Reimplemented from Media::AbstractContainer.

Definition at line 176 of file genericcontainer.h.

◆ trackById()

template<class FileInfoType , class TagType , class TrackType , class ElementType >
TrackType * Media::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::trackById ( uint64  id)
inline

Definition at line 182 of file genericcontainer.h.

◆ trackCount()

template<class FileInfoType , class TagType , class TrackType , class ElementType >
std::size_t Media::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::trackCount ( ) const
inlinevirtual

Returns the number of tracks the container holds.

Reimplemented from Media::AbstractContainer.

Definition at line 193 of file genericcontainer.h.

◆ tracks() [1/2]

template<class FileInfoType , class TagType , class TrackType , class ElementType >
const std::vector< std::unique_ptr< TrackType > > & Media::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.

◆ tracks() [2/2]

template<class FileInfoType , class TagType , class TrackType , class ElementType >
std::vector< std::unique_ptr< TrackType > > & Media::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.

◆ validateElementStructure()

template<class FileInfoType , class TagType , class TrackType , class ElementType >
void Media::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::validateElementStructure ( NotificationList gatheredNotifications,
uint64 *  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
ThrowsFailure or a derived class when a parsing error occurs.
Throwsstd::ios_base::failure when an IO error occurs.

Definition at line 100 of file genericcontainer.h.

Member Data Documentation

◆ m_additionalElements

template<class FileInfoType, class TagType, class TrackType, class ElementType>
std::vector<std::unique_ptr<ElementType> > Media::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::m_additionalElements
protected

Definition at line 62 of file genericcontainer.h.

◆ m_firstElement

template<class FileInfoType, class TagType, class TrackType, class ElementType>
std::unique_ptr<ElementType> Media::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::m_firstElement
protected

Definition at line 61 of file genericcontainer.h.

◆ m_tags

template<class FileInfoType, class TagType, class TrackType, class ElementType>
std::vector<std::unique_ptr<TagType> > Media::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::m_tags
protected

Definition at line 63 of file genericcontainer.h.

◆ m_tracks

template<class FileInfoType, class TagType, class TrackType, class ElementType>
std::vector<std::unique_ptr<TrackType> > Media::GenericContainer< FileInfoType, TagType, TrackType, ElementType >::m_tracks
protected

Definition at line 64 of file genericcontainer.h.


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