Gst::TagList Class Reference

A List of tags and values used to describe media metadata. More...

#include <taglist.h>

Inheritance diagram for Gst::TagList:

Gst::Structure

List of all members.

Public Types

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

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.
const GstTagList* gobj () const
 Provides access to the underlying C instance.
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.
bool is_empty () const
 Checks if the given taglist is empty.
void insert (const TagList& other, TagMergeMode mode=TAG_MERGE_PREPEND)
 Inserts the tags of the second list into the first list using the given mode.
TagList merge (const TagList& other, TagMergeMode mode=TAG_MERGE_PREPEND)
 Merges the two given lists into a new list.
guint get_tag_size (const Glib::ustring& tag) const
 Checks how many value are stored in this tag list for the given tag.
void add (const Glib::ustring& tag, const Glib::ValueBase& value, TagMergeMode mode=TAG_MERGE_PREPEND)
 Sets a GValue for the given tag using the specified mode.
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.
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.
void remove_tag (const Glib::ustring& tag)
 Removes the given tag from the taglist.
void foreach (const SlotForeach& slot)
 Calls the given slot for each tag inside the tag list.
bool get (const Glib::ustring& tag, guint index, Glib::ValueBase& value)
 Gets the value that is at the given index for the given tag.
bool get (const Glib::ustring& tag, char& value)
 Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.
bool get (const Glib::ustring& tag, guint index, char& value)
 Gets the value that is at the given index for the given tag.
bool get (const Glib::ustring& tag, guchar& value)
 Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.
bool get (const Glib::ustring& tag, guint index, guchar& value)
 Gets the value that is at the given index for the given tag.
bool get (const Glib::ustring& tag, bool& value)
 Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.
bool get (const Glib::ustring& tag, guint index, bool& value)
 Gets the value that is at the given index for the given tag.
bool get (const Glib::ustring& tag, int& value)
 Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.
bool get (const Glib::ustring& tag, guint index, int& value)
 Gets the value that is at the given index for the given tag.
bool get (const Glib::ustring& tag, guint& value)
 Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.
bool get (const Glib::ustring& tag, guint index, guint& value)
 Gets the value that is at the given index for the given tag.
bool get (const Glib::ustring& tag, long& value)
 Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.
bool get (const Glib::ustring& tag, guint index, long& value)
 Gets the value that is at the given index for the given tag.
bool get (const Glib::ustring& tag, gulong& value)
 Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.
bool get (const Glib::ustring& tag, guint index, gulong& value)
 Gets the value that is at the given index for the given tag.
bool get (const Glib::ustring& tag, float& value)
 Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.
bool get (const Glib::ustring& tag, guint index, float& value)
 Gets the value that is at the given index for the given tag.
bool get (const Glib::ustring& tag, double& value)
 Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.
bool get (const Glib::ustring& tag, guint index, double& value)
 Gets the value that is at the given index for the given tag.
bool get (const Glib::ustring& tag, Glib::ustring& value)
 Copies the contents for the given tag into the value, possibly merging multiple values into one if multiple values are associated with the tag.
bool get (const Glib::ustring& tag, guint index, Glib::ustring& value)
 Gets the value that is at the given index for the given tag in the given list.
bool get (const Glib::ustring& tag, Glib::Date& value)
 Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.
bool get (const Glib::ustring& tag, guint index, Glib::Date& value)
 Gets the value that is at the given index for the given tag.

Static Public Member Functions

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

Protected Attributes

GstTagList* gobject_

Related Functions

(Note that these are not member functions.)

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


Detailed Description

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

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

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

Reimplemented from Gst::Structure.


Constructor & Destructor Documentation

Gst::TagList::TagList (  ) 

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

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

Gst::TagList::~TagList (  ) 


Member Function Documentation

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

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 C++ class).
mode The merge mode to use.

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.

void Gst::TagList::add ( 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 GValue to set.

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.

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.

bool Gst::TagList::get ( const Glib::ustring &  tag,
guint  index,
Glib::Date &  value 
)

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.
Returns:
true, if a value was copied, false if the tag didn't exist in the given list.

bool Gst::TagList::get ( const Glib::ustring &  tag,
Glib::Date &  value 
)

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.
Returns:
true, if a value was copied, false if the tag didn't exist in the given list.

bool Gst::TagList::get ( const Glib::ustring &  tag,
guint  index,
Glib::ustring &  value 
)

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

The resulting string in value will be in UTF-8 encoding.

Parameters:
tag The tag to read out.
index Number of entry to read out.
value location for the result.
Returns:
true, if a value was copied, false if the tag didn't exist in the given list.

bool Gst::TagList::get ( const Glib::ustring &  tag,
Glib::ustring &  value 
)

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

Use the index version of this method if you want to retrieve the first string associated with this tag unmodified.

The resulting string in value will be in UTF-8 encoding.

Parameters:
tag The tag to read out.
value Location for the result.
Returns:
true, if a value was copied, false if the tag didn't exist in the given list.

bool Gst::TagList::get ( const Glib::ustring &  tag,
guint  index,
double &  value 
)

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.
Returns:
true, if a value was copied, false if the tag didn't exist in the given list.

bool Gst::TagList::get ( const Glib::ustring &  tag,
double &  value 
)

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.
Returns:
true, if a value was copied, false if the tag didn't exist in the given list.

bool Gst::TagList::get ( const Glib::ustring &  tag,
guint  index,
float &  value 
)

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.
Returns:
true, if a value was copied, false if the tag didn't exist in the given list.

bool Gst::TagList::get ( const Glib::ustring &  tag,
float &  value 
)

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.
Returns:
true, if a value was copied, false if the tag didn't exist in the given list.

bool Gst::TagList::get ( const Glib::ustring &  tag,
guint  index,
gulong &  value 
)

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.
Returns:
true, if a value was copied, false if the tag didn't exist in the given list.

bool Gst::TagList::get ( const Glib::ustring &  tag,
gulong &  value 
)

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.
Returns:
true, if a value was copied, false if the tag didn't exist in the given list.

bool Gst::TagList::get ( const Glib::ustring &  tag,
guint  index,
long &  value 
)

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.
Returns:
true, if a value was copied, false if the tag didn't exist in the given list.

bool Gst::TagList::get ( const Glib::ustring &  tag,
long &  value 
)

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.
Returns:
true, if a value was copied, false if the tag didn't exist in the given list.

bool Gst::TagList::get ( const Glib::ustring &  tag,
guint  index,
guint &  value 
)

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.
Returns:
true, if a value was copied, false if the tag didn't exist in the given list.

bool Gst::TagList::get ( const Glib::ustring &  tag,
guint &  value 
)

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.
Returns:
true, if a value was copied, false if the tag didn't exist in the given list.

bool Gst::TagList::get ( const Glib::ustring &  tag,
guint  index,
int &  value 
)

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.
Returns:
true, if a value was copied, false if the tag didn't exist in the given list.

bool Gst::TagList::get ( const Glib::ustring &  tag,
int &  value 
)

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.
Returns:
true, if a value was copied, false if the tag didn't exist in the given list.

bool Gst::TagList::get ( const Glib::ustring &  tag,
guint  index,
bool &  value 
)

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.
Returns:
true, if a value was copied, false if the tag didn't exist in the given list.

bool Gst::TagList::get ( const Glib::ustring &  tag,
bool &  value 
)

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.
Returns:
true, if a value was copied, false if the tag didn't exist in the given list.

bool Gst::TagList::get ( const Glib::ustring &  tag,
guint  index,
guchar &  value 
)

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.
Returns:
true, if a value was copied, false if the tag didn't exist in the given list.

bool Gst::TagList::get ( const Glib::ustring &  tag,
guchar &  value 
)

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.
Returns:
true, if a value was copied, false if the tag didn't exist in the given list.

bool Gst::TagList::get ( const Glib::ustring &  tag,
guint  index,
char &  value 
)

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.
Returns:
true, if a value was copied, false if the tag didn't exist in the given list.

bool Gst::TagList::get ( const Glib::ustring &  tag,
char &  value 
)

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.
Returns:
true, if a value was copied, false if the tag didn't exist in the given list.

bool Gst::TagList::get ( const Glib::ustring &  tag,
guint  index,
Glib::ValueBase &  value 
)

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. @param The Glib::ValueBase to store the value in.
Returns:
true if tag was available and had right number of entries, false otherwise.

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

Returns: the human-readable description of this tag.

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

static 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.

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

Returns: the human-readable name of this tag.

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

guint Gst::TagList::get_tag_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.

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.

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

Provides access to the underlying C instance.

Reimplemented from Gst::Structure.

References gobject_.

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

Provides access to the underlying C instance.

Reimplemented from Gst::Structure.

References gobject_.

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.

Reimplemented from Gst::Structure.

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

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

Parameters:
from List to merge from.
mode The mode to use.

bool Gst::TagList::is_empty (  )  const

Checks if the given taglist is empty.

Returns:
true if the taglist is empty, otherwise false.
Since: 0.10.11.

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.

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

Merges the two given lists into a new list.

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

Parameters:
list2 Second list to merge.
mode The mode to use.
Returns:
The new list.

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

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

Removes the given tag from the taglist.

Parameters:
tag Tag to remove.

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

Referenced by swap().


Friends And Related Function Documentation

void swap ( TagList lhs,
TagList rhs 
) [related]

Parameters:
lhs The left-hand side
rhs The right-hand side

References swap().

Gst::TagList wrap ( GstTagList *  object,
int  dummy,
bool  take_copy = false 
) [related]

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

The dummy int parameter is added to disambiguate Gst::TagList::wrap() from Gst::Structure::wrap() (GstTagList is in fact a GstStructure so wrap method becomes ambiguous).

Parameters:
object The C instance.
dummy An unused parameter to disambiguate Gst::TagList::wrap() from Gst::Structure::wrap(). The value of this parameter is irrelevant.
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

GstTagList* Gst::TagList::gobject_ [protected]

Reimplemented from Gst::Structure.

Referenced by gobj().


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

Generated on Fri Oct 10 04:22:48 2008 for gstreamermm by  doxygen 1.5.7.1