libfishsound: comments.h File Reference

# 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

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