gstreamermm: Gst::TagList Class Reference

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)
TagList& | operator= (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

  tag | The tag name.
  data | A string to which the tag should be set to.
  mode | The 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

  tag | The tag name.
  data | A string to which the tag should be set to.
  mode | The 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

  tag | The tag name.
  data | A value which the tag should be set to (this can be any supported C++ type).
  mode | The 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

  tag | The tag name.
  data | A value which the tag should be set to (this can be any supported C++ type).
  mode | The 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

  tag | The tag name.
  date | A date.
  mode | The 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

  tag | The tag name.
  date | A date.
  mode | The 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

  tag | The tag name.
  mode | The mode to use.
  value | The 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

  tag | The tag name.
  mode | The mode to use.
  value | The Glib::Value<> to use.

## ◆ exists()

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

Checks if the given type is already registered.

Parameters

  tag | Name 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

  slot | Slot 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

  tag | The tag to read out.
  value | Location 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

  tag | The tag to read out.
  value | Location 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

  tag | The tag to read out.
  index | Number of entry to read out.
  value | Location 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

  tag | The tag to read out.
  index | Number of entry to read out.
  value | Location 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

  tag | The 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

  tag | The 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

  tag | The 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

  tag | The 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

  dest | An uninitialized Glib::ValueBase to copy into.
  tag | The 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

  dest | An uninitialized Glib::ValueBase to copy into.
  tag | The 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

  tag | The tag to read out.
  index | Number of entry to read out.
  dest | The 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

  tag | The tag to read out.
  index | Number of entry to read out.
  dest | The 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

  other | List to merge from.
  mode | The 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

  tag | Tag 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

  other | Second list to merge.
  mode | The 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

  tag | Tag to remove.

## ◆ remove_tag() [2/2]

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

Removes the given tag from the taglist.

Parameters

  tag | Tag 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

  tag | The 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

  lhs | The left-hand side
  rhs | The 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

  object | The C instance.
  take_copy | False 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