libfishsound 1.0.0
Data Structures | Functions
comments.h File Reference

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 FishSoundCommentfish_sound_comment_first (FishSound *fsound)
 Retrieve the first comment.
 
const FishSoundCommentfish_sound_comment_next (FishSound *fsound, const FishSoundComment *comment)
 Retrieve the next comment.
 
const FishSoundCommentfish_sound_comment_first_byname (FishSound *fsound, char *name)
 Retrieve the first comment with a given name.
 
const FishSoundCommentfish_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.
 

Detailed Description

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:

Retrieving comments

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.

Encoding comments

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()).

Function Documentation

◆ fish_sound_comment_add()

int fish_sound_comment_add ( FishSound fsound,
FishSoundComment comment 
)

Add a comment.

Parameters
fsoundA FishSound* handle (created with mode FISH_SOUND_ENCODE)
commentThe comment to add
Return values
0Success
FISH_SOUND_ERR_BADfsound is not a valid FishSound* handle
FISH_SOUND_ERR_INVALIDOperation not suitable for this FishSound

◆ fish_sound_comment_add_byname()

int fish_sound_comment_add_byname ( FishSound fsound,
const char *  name,
const char *  value 
)

Add a comment by name and value.

Parameters
fsoundA FishSound* handle (created with mode FISH_SOUND_ENCODE)
nameThe name of the comment to add
valueThe contents of the comment to add
Return values
0Success
FISH_SOUND_ERR_BADfsound is not a valid FishSound* handle
FISH_SOUND_ERR_INVALIDOperation not suitable for this FishSound

◆ fish_sound_comment_first()

const FishSoundComment * fish_sound_comment_first ( FishSound fsound)

Retrieve the first comment.

Parameters
fsoundA FishSound* handle
Returns
A read-only copy of the first comment, or NULL if no comments exist for this FishSound* object.

◆ fish_sound_comment_first_byname()

const FishSoundComment * fish_sound_comment_first_byname ( FishSound fsound,
char *  name 
)

Retrieve the first comment with a given name.

Parameters
fsoundA FishSound* handle
namethe name of the comment to retrieve.
Returns
A read-only copy of the first comment matching the given name.
Return values
NULLno match was found.
Note
If name is NULL, the behaviour is the same as for fish_sound_comment_first()

◆ fish_sound_comment_get_vendor()

const char * fish_sound_comment_get_vendor ( FishSound fsound)

Retrieve the vendor string.

Parameters
fsoundA FishSound* handle
Returns
A read-only copy of the vendor string
Return values
NULLNo vendor string is associated with fsound, or fsound is NULL.

◆ fish_sound_comment_next()

const FishSoundComment * fish_sound_comment_next ( FishSound fsound,
const FishSoundComment comment 
)

Retrieve the next comment.

Parameters
fsoundA FishSound* handle
commentThe previous comment.
Returns
A read-only copy of the comment immediately following the given comment.

◆ fish_sound_comment_next_byname()

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.

Parameters
fsoundA FishSound* handle
commentA comment
Returns
A read-only copy of the next comment with the same name as comment.
Return values
NULLno further comments with the same name exist for this FishSound* object.

◆ fish_sound_comment_remove()

int fish_sound_comment_remove ( FishSound fsound,
FishSoundComment comment 
)

Remove a comment.

Parameters
fsoundA FishSound* handle (created with FISH_SOUND_ENCODE)
commentThe comment to remove.
Return values
1Success: comment removed
0No-op: comment not found, nothing to remove
FISH_SOUND_ERR_BADfsound is not a valid FishSound* handle
FISH_SOUND_ERR_INVALIDOperation not suitable for this FishSound

◆ fish_sound_comment_remove_byname()

int fish_sound_comment_remove_byname ( FishSound fsound,
char *  name 
)

Remove all comments with a given name.

Parameters
fsoundA FishSound* handle (created with FISH_SOUND_ENCODE)
nameThe name of the comments to remove
Return values
>= 0The number of comments removed
FISH_SOUND_ERR_BADfsound is not a valid FishSound* handle
FISH_SOUND_ERR_INVALIDOperation not suitable for this FishSound