Classes | Functions

comments.h File Reference

Encoding and decoding of comments. More...

#include <fishsound/fishsound.h>
Include dependency graph for comments.h:
This graph shows which files directly or indirectly include this file:

Classes

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

int fish_sound_comment_add ( FishSound fsound,
FishSoundComment comment 
)

Add a comment.

Parameters:
fsound A FishSound* handle (created with mode FISH_SOUND_ENCODE)
comment The comment to add
Return values:
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.

Parameters:
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
Return values:
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.

Parameters:
fsound A FishSound* handle
Returns:
A read-only copy of the first comment, or NULL if no comments exist for this FishSound* object.
const FishSoundComment* fish_sound_comment_first_byname ( FishSound fsound,
char *  name 
)

Retrieve the first comment with a given name.

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

Retrieve the vendor string.

Parameters:
fsound A FishSound* handle
Returns:
A read-only copy of the vendor string
Return values:
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.

Parameters:
fsound A FishSound* handle
comment The previous comment.
Returns:
A read-only copy of the comment immediately following the given 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.

Parameters:
fsound A FishSound* handle
comment A comment
Returns:
A read-only copy of the next comment with the same name as comment.
Return values:
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.

Parameters:
fsound A FishSound* handle (created with FISH_SOUND_ENCODE)
comment The comment to remove.
Return values:
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.

Parameters:
fsound A FishSound* handle (created with FISH_SOUND_ENCODE)
name The name of the comments to remove
Return values:
>= 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