gstreamermm  1.10.0
Public Types | Public Member Functions | Static Public Member Functions | Protected Attributes | Related Functions | List of all members
Gst::TagList Class Reference

A class tha represents a list of tags and values used to describe media metadata. More...

#include <gstreamermm/taglist.h>

Public Types

typedef sigc::slot< void, const Glib::ustring& > SlotForeach
 For example, void on_foreach(const Glib::ustring& tag);. More...
 

Public Member Functions

 TagList ()
 
 TagList (GstTagList* gobject, bool make_a_copy=true)
 
 TagList (const TagList& other)
 
TagListoperator= (const TagList& other)
 
 ~TagList ()
 
void swap (TagList& other)
 
GstTagList* gobj ()
 Provides access to the underlying C instance. More...
 
const GstTagList* gobj () const
 Provides access to the underlying C instance. More...
 
GstTagList* gobj_copy () const
 Provides access to the underlying C instance. The caller is responsible for freeing it. Use when directly setting fields in structs. More...
 
 operator bool () const
 Use this to discover if the TagList is a valid object. More...
 
bool is_empty () const
 Checks if the given taglist is empty. More...
 
void insert (const Gst::TagList& other, TagMergeMode mode=TAG_MERGE_PREPEND)
 Inserts the tags of the other list into the first list using the given mode. More...
 
Gst::TagList merge (const Gst::TagList& other, TagMergeMode mode=TAG_MERGE_PREPEND)
 Merges the two given lists into a new list. More...
 
guint size (const Glib::ustring& tag) const
 Checks how many value are stored in this tag list for the given tag. More...
 
void add_value (Tag tag, const Glib::ValueBase& value, TagMergeMode mode=TAG_MERGE_PREPEND)
 Sets a GValue for the given tag using the specified mode. More...
 
void add_value (const Glib::ustring& tag, const Glib::ValueBase& value, TagMergeMode mode=TAG_MERGE_PREPEND)
 Sets a GValue for the given tag using the specified mode. More...
 
void add (Tag tag, const char* data, TagMergeMode mode=TAG_MERGE_PREPEND)
 Sets the value for the given tag to string data using the specified mode. More...
 
void add (const Glib::ustring& tag, const char* data, TagMergeMode mode=TAG_MERGE_PREPEND)
 Sets the value for the given tag to string data using the specified mode. More...
 
template<class DataType >
void add (Tag tag, const DataType& data, TagMergeMode mode=TAG_MERGE_PREPEND)
 Sets the value for the given tag using the specified mode. More...
 
template<class DataType >
void add (const Glib::ustring& tag, const DataType& data, TagMergeMode mode=TAG_MERGE_PREPEND)
 Sets the value for the given tag using the specified mode. More...
 
void add (Tag tag, const Glib::Date& date, TagMergeMode mode=TAG_MERGE_PREPEND)
 Sets the value for the given tag using the specified mode. More...
 
void add (const Glib::ustring& tag, const Glib::Date& date, TagMergeMode mode=TAG_MERGE_PREPEND)
 Sets the value for the given tag using the specified mode. More...
 
void remove_tag (Tag tag)
 Removes the given tag from the taglist. More...
 
void remove_tag (const Glib::ustring& tag)
 Removes the given tag from the taglist. More...
 
void foreach (const SlotForeach& slot)
 Calls the given slot for each tag inside the tag list. More...
 
bool get_value (Tag tag, Glib::ValueBase& dest) const
 Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag. More...
 
bool get_value (const Glib::ustring& tag, Glib::ValueBase& dest) const
 Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag. More...
 
bool get_value (Tag tag, guint index, Glib::ValueBase& dest) const
 Gets the value that is at the given index for the given tag. More...
 
bool get_value (const Glib::ustring& tag, guint index, Glib::ValueBase& dest) const
 Gets the value that is at the given index for the given tag. More...
 
template<class DataType >
bool get (Tag tag, DataType& value) const
 Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag. More...
 
template<class DataType >
bool get (const Glib::ustring& tag, DataType& value) const
 Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag. More...
 
template<class DataType >
bool get (Tag tag, guint index, DataType& value) const
 Gets the value that is at the given index for the given tag. More...
 
template<class DataType >
bool get (const Glib::ustring& tag, guint index, DataType& value) const
 Gets the value that is at the given index for the given tag. More...
 

Static Public Member Functions

static bool exists (const Glib::ustring& tag)
 Checks if the given type is already registered. More...
 
static GType get_type (const Glib::ustring& tag)
 Gets the Type used for this tag. More...
 
static Glib::ustring get_nick (const Glib::ustring& tag)
 Returns the human-readable name of this tag, You must not change or free this string. More...
 
static Glib::ustring get_description (const Glib::ustring& tag)
 Returns the human-readable description of this tag, You must not change or free this string. More...
 
static Gst::TagFlag get_flag (const Glib::ustring& tag)
 Gets the flag of tag. More...
 
static bool is_fixed (const Glib::ustring& tag)
 Checks if the given tag is fixed. More...
 

Protected Attributes

GstTagList* gobject_
 

Related Functions

(Note that these are not member functions.)

void swap (TagList& lhs, TagList& rhs)
 
Gst::TagList wrap_taglist (GstTagList* object, bool take_copy=false)
 A Glib::wrap() method for this object. More...
 

Detailed Description

A class tha represents a list of tags and values used to describe media metadata.

Taglists form part of media streams and describe the content of a stream in a non-technical way. Examples include the author of a song, the title of that very same song or the album it is a part of. Tag reading is done through a Gst::Bus. You can listen for Gst::MESSAGE_TAG messages and handle them as you wish.

Note, however, that the Gst::MESSAGE_TAG message may be fired multiple times in the pipeline. It is the application's responsibility to put all those tags together and display them to the user in a nice, coherent way. Usually, using merge() is a good enough way of doing this; make sure to empty the cache when loading a new song, or after every few minutes when listening to internet radio. Also, make sure you use Gst::TAG_MERGE_PREPEND as merging mode, so that a new title (which came in later) has a preference over the old one for display.

Member Typedef Documentation

◆ SlotForeach

typedef sigc::slot<void, const Glib::ustring&> Gst::TagList::SlotForeach

For example, void on_foreach(const Glib::ustring& tag);.

Constructor & Destructor Documentation

◆ TagList() [1/3]

Gst::TagList::TagList ( )

◆ TagList() [2/3]

Gst::TagList::TagList ( GstTagList *  gobject,
bool  make_a_copy = true 
)
explicit

◆ TagList() [3/3]

Gst::TagList::TagList ( const TagList other)

◆ ~TagList()

Gst::TagList::~TagList ( )

Member Function Documentation

◆ add() [1/6]

void Gst::TagList::add ( Tag  tag,
const char *  data,
TagMergeMode  mode = TAG_MERGE_PREPEND 
)

Sets the value for the given tag to string data using the specified mode.

Parameters
tagThe tag name.
dataA string to which the tag should be set to.
modeThe merge mode to use.

◆ add() [2/6]

void Gst::TagList::add ( const Glib::ustring &  tag,
const char *  data,
TagMergeMode  mode = TAG_MERGE_PREPEND 
)

Sets the value for the given tag to string data using the specified mode.

Parameters
tagThe tag name.
dataA string to which the tag should be set to.
modeThe merge mode to use.

◆ add() [3/6]

template <class DataType >
void Gst::TagList::add ( Tag  tag,
const DataType &  data,
TagMergeMode  mode = TAG_MERGE_PREPEND 
)

Sets the value for the given tag using the specified mode.

Parameters
tagThe tag name.
dataA value which the tag should be set to (this can be any supported C++ type).
modeThe merge mode to use.

◆ add() [4/6]

template <class DataType >
void Gst::TagList::add ( const Glib::ustring &  tag,
const DataType &  data,
TagMergeMode  mode = TAG_MERGE_PREPEND 
)

Sets the value for the given tag using the specified mode.

Parameters
tagThe tag name.
dataA value which the tag should be set to (this can be any supported C++ type).
modeThe merge mode to use.

◆ add() [5/6]

void Gst::TagList::add ( Tag  tag,
const Glib::Date &  date,
TagMergeMode  mode = TAG_MERGE_PREPEND 
)

Sets the value for the given tag using the specified mode.

Parameters
tagThe tag name.
dateA date.
modeThe merge mode to use.

◆ add() [6/6]

void Gst::TagList::add ( const Glib::ustring &  tag,
const Glib::Date &  date,
TagMergeMode  mode = TAG_MERGE_PREPEND 
)

Sets the value for the given tag using the specified mode.

Parameters
tagThe tag name.
dateA date.
modeThe merge mode to use.

◆ add_value() [1/2]

void Gst::TagList::add_value ( Tag  tag,
const Glib::ValueBase &  value,
TagMergeMode  mode = TAG_MERGE_PREPEND 
)

Sets a GValue for the given tag using the specified mode.

Parameters
tagThe tag name.
modeThe mode to use.
valueThe Glib::Value<> to use.

◆ add_value() [2/2]

void Gst::TagList::add_value ( const Glib::ustring &  tag,
const Glib::ValueBase &  value,
TagMergeMode  mode = TAG_MERGE_PREPEND 
)

Sets a GValue for the given tag using the specified mode.

Parameters
tagThe tag name.
modeThe mode to use.
valueThe Glib::Value<> to use.

◆ exists()

static bool Gst::TagList::exists ( const Glib::ustring &  tag)
static

Checks if the given type is already registered.

Parameters
tagName of the tag.
Returns
true if the type is already registered.

◆ foreach()

void Gst::TagList::foreach ( const SlotForeach slot)

Calls the given slot for each tag inside the tag list.

Note that if there is no tag, the slot won't be called at all.

Parameters
slotSlot to be called for each tag.

◆ get() [1/4]

template <class DataType >
bool Gst::TagList::get ( Tag  tag,
DataType &  value 
) const

Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.

Parameters
tagThe tag to read out.
valueLocation for the result (this can be any supported C++ type).
Returns
true, if a value was copied, false if the tag didn't exist in the given list.

◆ get() [2/4]

template <class DataType >
bool Gst::TagList::get ( const Glib::ustring &  tag,
DataType &  value 
) const

Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.

Parameters
tagThe tag to read out.
valueLocation for the result (this can be any supported C++ type).
Returns
true, if a value was copied, false if the tag didn't exist in the given list.

◆ get() [3/4]

template <class DataType >
bool Gst::TagList::get ( Tag  tag,
guint  index,
DataType &  value 
) const

Gets the value that is at the given index for the given tag.

Parameters
tagThe tag to read out.
indexNumber of entry to read out.
valueLocation for the result (this can be any supported C++ type).
Returns
true, if a value was copied, false if the tag didn't exist in the given list.

◆ get() [4/4]

template <class DataType >
bool Gst::TagList::get ( const Glib::ustring &  tag,
guint  index,
DataType &  value 
) const

Gets the value that is at the given index for the given tag.

Parameters
tagThe tag to read out.
indexNumber of entry to read out.
valueLocation for the result (this can be any supported C++ type).
Returns
true, if a value was copied, false if the tag didn't exist in the given list.

◆ get_description()

static Glib::ustring Gst::TagList::get_description ( const Glib::ustring &  tag)
static

Returns the human-readable description of this tag, You must not change or free this string.

Parameters
tagThe tag.
Returns
The human-readable description of this tag.

◆ get_flag()

static Gst::TagFlag Gst::TagList::get_flag ( const Glib::ustring &  tag)
static

Gets the flag of tag.

Parameters
tagThe tag.
Returns
The flag of this tag.

◆ get_nick()

static Glib::ustring Gst::TagList::get_nick ( const Glib::ustring &  tag)
static

Returns the human-readable name of this tag, You must not change or free this string.

Parameters
tagThe tag.
Returns
The human-readable name of this tag.

◆ get_type()

static GType Gst::TagList::get_type ( const Glib::ustring &  tag)
static

Gets the Type used for this tag.

Parameters
tagThe tag.
Returns
The Type of this tag.

◆ get_value() [1/4]

bool Gst::TagList::get_value ( Tag  tag,
Glib::ValueBase &  dest 
) const

Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.

Parameters
destAn uninitialized Glib::ValueBase to copy into.
tagThe tag to read out.
Returns
true, if a value was copied, false if the tag didn't exist in the list.

◆ get_value() [2/4]

bool Gst::TagList::get_value ( const Glib::ustring &  tag,
Glib::ValueBase &  dest 
) const

Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.

Parameters
destAn uninitialized Glib::ValueBase to copy into.
tagThe tag to read out.
Returns
true, if a value was copied, false if the tag didn't exist in the list.

◆ get_value() [3/4]

bool Gst::TagList::get_value ( Tag  tag,
guint  index,
Glib::ValueBase &  dest 
) const

Gets the value that is at the given index for the given tag.

Parameters
tagThe tag to read out.
indexNumber of entry to read out.
destThe Glib::ValueBase to store the value in.
Returns
true if tag was available and had right number of entries, false otherwise.

◆ get_value() [4/4]

bool Gst::TagList::get_value ( const Glib::ustring &  tag,
guint  index,
Glib::ValueBase &  dest 
) const

Gets the value that is at the given index for the given tag.

Parameters
tagThe tag to read out.
indexNumber of entry to read out.
destThe Glib::ValueBase to store the value in.
Returns
true if tag was available and had right number of entries, false otherwise.

◆ gobj() [1/2]

GstTagList* Gst::TagList::gobj ( )
inline

Provides access to the underlying C instance.

◆ gobj() [2/2]

const GstTagList* Gst::TagList::gobj ( ) const
inline

Provides access to the underlying C instance.

◆ gobj_copy()

GstTagList* Gst::TagList::gobj_copy ( ) const

Provides access to the underlying C instance. The caller is responsible for freeing it. Use when directly setting fields in structs.

◆ insert()

void Gst::TagList::insert ( const Gst::TagList other,
TagMergeMode  mode = TAG_MERGE_PREPEND 
)

Inserts the tags of the other list into the first list using the given mode.

Parameters
otherList to merge from.
modeThe mode to use.

◆ is_empty()

bool Gst::TagList::is_empty ( ) const

Checks if the given taglist is empty.

Returns
true if the taglist is empty, otherwise false.

◆ is_fixed()

static bool Gst::TagList::is_fixed ( const Glib::ustring &  tag)
static

Checks if the given tag is fixed.

A fixed tag can only contain one value. Unfixed tags can contain lists of values.

Parameters
tagTag to check.
Returns
true, if the given tag is fixed.

◆ merge()

Gst::TagList Gst::TagList::merge ( const Gst::TagList other,
TagMergeMode  mode = TAG_MERGE_PREPEND 
)

Merges the two given lists into a new list.

If one of the lists is nullptr, a copy of the other is returned. If both lists are nullptr, nullptr is returned.

Free-function: gst_tag_list_unref

Parameters
otherSecond list to merge.
modeThe mode to use.
Returns
The new list.

◆ operator bool()

Gst::TagList::operator bool ( ) const

Use this to discover if the TagList is a valid object.

◆ operator=()

TagList& Gst::TagList::operator= ( const TagList other)

◆ remove_tag() [1/2]

void Gst::TagList::remove_tag ( Tag  tag)

Removes the given tag from the taglist.

Parameters
tagTag to remove.

◆ remove_tag() [2/2]

void Gst::TagList::remove_tag ( const Glib::ustring &  tag)

Removes the given tag from the taglist.

Parameters
tagTag to remove.

◆ size()

guint Gst::TagList::size ( const Glib::ustring &  tag) const

Checks how many value are stored in this tag list for the given tag.

Parameters
tagThe tag to query.
Returns
The number of tags stored.

◆ swap()

void Gst::TagList::swap ( TagList other)

Friends And Related Function Documentation

◆ swap()

void swap ( TagList lhs,
TagList rhs 
)
related
Parameters
lhsThe left-hand side
rhsThe right-hand side

◆ wrap_taglist()

Gst::TagList wrap_taglist ( GstTagList *  object,
bool  take_copy = false 
)
related

A Glib::wrap() method for this object.

The method has a non-standard name because otherwise it would collide with the wrap method for Gst::Structure because both Gst::TagList and Gst::Structure wrap the same underlying C type.

Parameters
objectThe C instance.
take_copyFalse if the result should take ownership of the C instance. True if it should take a new copy or ref.
Returns
A C++ instance that wraps this C instance.

Member Data Documentation

◆ gobject_

GstTagList* Gst::TagList::gobject_
protected