libfishsound 1.0.0
|
Encoding and decoding of comments. More...
#include <fishsound/fishsound.h>
Go to the source code of this file.
Data Structures | |
struct | FishSoundComment |
A comment. More... | |
Functions | |
const char * | fish_sound_comment_get_vendor (FishSound *fsound) |
Retrieve the vendor string. | |
const FishSoundComment * | fish_sound_comment_first (FishSound *fsound) |
Retrieve the first comment. | |
const FishSoundComment * | fish_sound_comment_next (FishSound *fsound, const FishSoundComment *comment) |
Retrieve the next comment. | |
const FishSoundComment * | fish_sound_comment_first_byname (FishSound *fsound, char *name) |
Retrieve the first comment with a given name. | |
const FishSoundComment * | fish_sound_comment_next_byname (FishSound *fsound, const FishSoundComment *comment) |
Retrieve the next comment following and with the same name as a given comment. | |
int | fish_sound_comment_add (FishSound *fsound, FishSoundComment *comment) |
Add a comment. | |
int | fish_sound_comment_add_byname (FishSound *fsound, const char *name, const char *value) |
Add a comment by name and value. | |
int | fish_sound_comment_remove (FishSound *fsound, FishSoundComment *comment) |
Remove a comment. | |
int | fish_sound_comment_remove_byname (FishSound *fsound, char *name) |
Remove all comments with a given name. | |
Encoding and decoding of comments.
Vorbis and Speex bitstreams use a comment format called "Vorbiscomment", defined here. Many standard comment names (such as TITLE, COPYRIGHT and GENRE) are defined in that document.
The following general features of Vorbiscomment are relevant to this API:
Each comment block contains one Vendor string, which can be retrieved with fish_sound_comment_get_vendor(). When encoding, this string is effectively fixed by the codec libraries; it cannot be set by the application.
The rest of a comment block consists of name = value pairs, with the following restrictions:
FishSound contains API methods to iterate through all comments associated with a FishSound* handle (fish_sound_comment_first() and fish_sound_comment_next(), and to iterate through comments matching a particular name (fish_sound_comment_first_byname() and fish_sound_comment_next_byname()). Given that multiple comments may exist with the same name, you should not use fish_sound_comment_first_byname() as a simple "get" function.
For encoding, FishSound contains API methods for adding comments (fish_sound_comment_add() and fish_sound_comment_add_byname() and for removing comments (fish_sound_comment_remove() and fish_sound_comment_remove_byname()).
int fish_sound_comment_add | ( | FishSound * | fsound, |
FishSoundComment * | comment | ||
) |
Add a comment.
fsound | A FishSound* handle (created with mode FISH_SOUND_ENCODE) |
comment | The comment to add |
0 | Success |
FISH_SOUND_ERR_BAD | fsound is not a valid FishSound* handle |
FISH_SOUND_ERR_INVALID | Operation not suitable for this FishSound |
int fish_sound_comment_add_byname | ( | FishSound * | fsound, |
const char * | name, | ||
const char * | value | ||
) |
Add a comment by name and value.
fsound | A FishSound* handle (created with mode FISH_SOUND_ENCODE) |
name | The name of the comment to add |
value | The contents of the comment to add |
0 | Success |
FISH_SOUND_ERR_BAD | fsound is not a valid FishSound* handle |
FISH_SOUND_ERR_INVALID | Operation not suitable for this FishSound |
const FishSoundComment * fish_sound_comment_first | ( | FishSound * | fsound | ) |
Retrieve the first comment.
fsound | A FishSound* handle |
const FishSoundComment * fish_sound_comment_first_byname | ( | FishSound * | fsound, |
char * | name | ||
) |
Retrieve the first comment with a given name.
fsound | A FishSound* handle |
name | the name of the comment to retrieve. |
NULL | no match was found. |
const char * fish_sound_comment_get_vendor | ( | FishSound * | fsound | ) |
Retrieve the vendor string.
fsound | A FishSound* handle |
NULL | No vendor string is associated with fsound, or fsound is NULL. |
const FishSoundComment * fish_sound_comment_next | ( | FishSound * | fsound, |
const FishSoundComment * | comment | ||
) |
Retrieve the next comment.
fsound | A FishSound* handle |
comment | The previous comment. |
const FishSoundComment * fish_sound_comment_next_byname | ( | FishSound * | fsound, |
const FishSoundComment * | comment | ||
) |
Retrieve the next comment following and with the same name as a given comment.
fsound | A FishSound* handle |
comment | A comment |
NULL | no further comments with the same name exist for this FishSound* object. |
int fish_sound_comment_remove | ( | FishSound * | fsound, |
FishSoundComment * | comment | ||
) |
Remove a comment.
fsound | A FishSound* handle (created with FISH_SOUND_ENCODE) |
comment | The comment to remove. |
1 | Success: comment removed |
0 | No-op: comment not found, nothing to remove |
FISH_SOUND_ERR_BAD | fsound is not a valid FishSound* handle |
FISH_SOUND_ERR_INVALID | Operation not suitable for this FishSound |
int fish_sound_comment_remove_byname | ( | FishSound * | fsound, |
char * | name | ||
) |
Remove all comments with a given name.
fsound | A FishSound* handle (created with FISH_SOUND_ENCODE) |
name | The name of the comments to remove |
>= 0 | The number of comments removed |
FISH_SOUND_ERR_BAD | fsound is not a valid FishSound* handle |
FISH_SOUND_ERR_INVALID | Operation not suitable for this FishSound |