Firelight Technologies FMOD Studio API

Sound::getTag

Retrieves a descriptive tag stored by the sound, to describe things like the song name, author etc.

C++ Syntax

FMOD_RESULT Sound::getTag(
  const char *name,
  int index,
  FMOD_TAG *tag
);

C Syntax

FMOD_RESULT FMOD_Sound_GetTag(
  FMOD_SOUND *sound,
  const char *name,
  int index,
  FMOD_TAG *tag
);

Parameters

name
Optional. Name of a tag to retrieve. Used to specify a particular tag if the user requires it. To get all types of tags leave this parameter as 0 or NULL.
index
Index into the tag list. If the name parameter is null, then the index is the index into all tags present, from 0 up to but not including the numtags value returned by Sound::getNumTags.
If name is not null, then index is the index from 0 up to the number of tags with the same name. For example if there were 2 tags with the name "TITLE" then you could use 0 and 1 to reference them.
Specifying an index of -1 returns new or updated tags. This can be used to pull tags out as they are added or updated.
tag
Pointer to a tag structure. This will receive

Return Values

If the function succeeds then the return value is FMOD_OK.
If the function fails then the return value will be one of the values defined in the FMOD_RESULT enumeration.

Remarks

The number of tags available can be found with Sound::getNumTags. The way to display or retrieve tags can be done in 3 different ways.
All tags can be continuously retrieved by looping from 0 to the numtags value in Sound::getNumTags - 1. Updated tags will refresh automatically, and the 'updated' member of the FMOD_TAG structure will be set to true if a tag has been updated, due to something like a netstream changing the song name for example.
Tags could also be retrieved by specifying -1 as the index and only updating tags that are returned. If all tags are retrieved and this function is called the function will return an error of FMOD_ERR_TAGNOTFOUND.
Specific tags can be retrieved by specifying a name parameter. The index can be 0 based or -1 in the same fashion as described previously.

See Also




Version 1.03.06 Built on Apr 17, 2014