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

## 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 stream has one comment packet, which occurs before any encoded audio data in the stream.
- When encoding, FishSound will generate the comment block and pass it to the encoded() callback in sequence, just like any other packet. Hence, all comments must be set before any call to fish_sound_encode_*().
- When decoding, FishSound will decode the comment block before calling the first decoded() callback. Hence, retrieving comment data is possible from as soon as the decoded() callback is first called.

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:

- Both the name and value must be non-empty
- The name is case-insensitive and must consist of ASCII within the range 0x20 to 0x7D inclusive, 0x3D ('=') excluded.
- The name is not unique; multiple entries may exist with equivalent name within a Vorbiscomment block.
- The value may be any UTF-8 string.

# 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

  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

## 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

  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

## fish_sound_comment_first()

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.

## 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

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

## fish_sound_comment_get_vendor()

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.

## fish_sound_comment_next()

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.

## 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

  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.

## fish_sound_comment_remove()

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

## fish_sound_comment_remove_byname()

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