liboggz: oggz_comments.h File Reference

liboggz 1.1.1

Data Structures | Functions
oggz_comments.h File Reference

Reading of comments. More...

`#include <oggz/oggz.h>`

Go to the source code of this file.

## Data Structures
struct | OggzComment
| A comment. More...

## Functions
const char * | oggz_comment_get_vendor (OGGZ *oggz, long serialno)
| Retrieve the vendor string. More...
int | oggz_comment_set_vendor (OGGZ *oggz, long serialno, const char *vendor_string)
| Set the vendor string. More...
const OggzComment * | oggz_comment_first (OGGZ *oggz, long serialno)
| Retrieve the first comment. More...
const OggzComment * | oggz_comment_next (OGGZ *oggz, long serialno, const OggzComment *comment)
| Retrieve the next comment. More...
const OggzComment * | oggz_comment_first_byname (OGGZ *oggz, long serialno, char *name)
| Retrieve the first comment with a given name. More...
const OggzComment * | oggz_comment_next_byname (OGGZ *oggz, long serialno, const OggzComment *comment)
| Retrieve the next comment following and with the same name as a given comment. More...
int | oggz_comment_add (OGGZ *oggz, long serialno, OggzComment *comment)
| Add a comment. More...
int | oggz_comment_add_byname (OGGZ *oggz, long serialno, const char *name, const char *value)
| Add a comment by name and value. More...
int | oggz_comment_remove (OGGZ *oggz, long serialno, OggzComment *comment)
| Remove a comment. More...
int | oggz_comment_remove_byname (OGGZ *oggz, long serialno, char *name)
| Remove all comments with a given name. More...
ogg_packet * | oggz_comments_generate (OGGZ *oggz, long serialno, int FLAC_final_metadata_block)
| Output a comment packet for the specified stream. More...
int | oggz_comments_copy (OGGZ *src, long src_serialno, OGGZ *dest, long dest_serialno)
void | oggz_packet_destroy (ogg_packet *packet)
| Free a packet and its payload. More...

## Detailed Description

Reading of comments.

Vorbis, Speex and Theora 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 reading, Oggz will decode the comment block before calling the second read() callback for each stream. Hence, retrieving comment data is possible once the read() callback has been called a second time.
- When writing, Oggz allows you to set up the comments in memory, and provides a single function to generate a corresponding ogg_packet. It is your responsibility to then actually write that packet in sequence.

Each comment block contains one Vendor string, which can be retrieved with oggz_comment_get_vendor().

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.

# Reading comments

Oggz contains API methods to iterate through all comments associated with the logical bitstreams of an OGGZ* handle (oggz_comment_first() and oggz_comment_next(), and to iterate through comments matching a particular name (oggz_comment_first_byname() and oggz_comment_next_byname()). Given that multiple comments may exist with the same name, you should not use oggz_comment_first_byname() as a simple "get" function.

# Writing comments

For writing, Oggz contains API methods for adding comments (oggz_comment_add() and oggz_comment_add_byname()), for removing comments (oggz_comment_remove() and oggz_comment_remove_byname()) and for setting the vendor string (oggz_comment_set_vendor()).

## Function Documentation

## ◆ oggz_comment_add()

int oggz_comment_add | ( | OGGZ * | oggz,
|  | long | serialno,
|  | OggzComment * | comment
| ) |  |

Add a comment.

Parameters

  oggz | A OGGZ* handle (created with mode OGGZ_WRITE)
  serialno | Identify a logical bitstream within oggz
  comment | The comment to add

Return values

  0 | Success
  OGGZ_ERR_BAD | oggz is not a valid OGGZ* handle
  OGGZ_ERR_INVALID | Operation not suitable for this OGGZ
  OGGZ_ERR_OUT_OF_MEMORY | Out of memory

## ◆ oggz_comment_add_byname()

int oggz_comment_add_byname | ( | OGGZ * | oggz,
|  | long | serialno,
|  | const char * | name,
|  | const char * | value
| ) |  |

Add a comment by name and value.

Parameters

  oggz | A OGGZ* handle (created with mode OGGZ_WRITE)
  serialno | Identify a logical bitstream within oggz
  name | The name of the comment to add
  value | The contents of the comment to add

Return values

  0 | Success
  OGGZ_ERR_BAD | oggz is not a valid OGGZ* handle
  OGGZ_ERR_INVALID | Operation not suitable for this OGGZ
  OGGZ_ERR_OUT_OF_MEMORY | Out of memory

## ◆ oggz_comment_first()

const OggzComment* oggz_comment_first | ( | OGGZ * | oggz,
|  | long | serialno
| ) |  |

Retrieve the first comment.

Parameters

  oggz | A OGGZ* handle
  serialno | Identify a logical bitstream within oggz

Returns
  A read-only copy of the first comment.

Return values

  NULL | No comments exist for this OGGZ* object, or serialno does not identify an existing logical bitstream in oggz.

## ◆ oggz_comment_first_byname()

const OggzComment* oggz_comment_first_byname | ( | OGGZ * | oggz,
|  | long | serialno,
|  | char * | name
| ) |  |

Retrieve the first comment with a given name.

Parameters

  oggz | A OGGZ* handle
  serialno | Identify a logical bitstream within oggz
  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, or serialno does not identify an existing logical bitstream in oggz.

Note
  If name is NULL, the behaviour is the same as for oggz_comment_first()

## ◆ oggz_comment_get_vendor()

const char* oggz_comment_get_vendor | ( | OGGZ * | oggz,
|  | long | serialno
| ) |  |

Retrieve the vendor string.

Parameters

  oggz | A OGGZ* handle
  serialno | Identify a logical bitstream within oggz

Returns
  A read-only copy of the vendor string.

Return values

  NULL | No vendor string is associated with oggz, or oggz is NULL, or serialno does not identify an existing logical bitstream in oggz.

## ◆ oggz_comment_next()

const OggzComment* oggz_comment_next | ( | OGGZ * | oggz,
|  | long | serialno,
|  | const OggzComment * | comment
| ) |  |

Retrieve the next comment.

Parameters

  oggz | A OGGZ* handle
  serialno | Identify a logical bitstream within oggz
  comment | The previous comment.

Returns
  A read-only copy of the comment immediately following the given comment.

Return values

  NULL | serialno does not identify an existing logical bitstream in oggz.

## ◆ oggz_comment_next_byname()

const OggzComment* oggz_comment_next_byname | ( | OGGZ * | oggz,
|  | long | serialno,
|  | const OggzComment * | comment
| ) |  |

Retrieve the next comment following and with the same name as a given comment.

Parameters

  oggz | A OGGZ* handle
  serialno | Identify a logical bitstream within oggz
  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 OGGZ* object, or serialno does not identify an existing logical bitstream in oggz.

## ◆ oggz_comment_remove()

int oggz_comment_remove | ( | OGGZ * | oggz,
|  | long | serialno,
|  | OggzComment * | comment
| ) |  |

Remove a comment.

Parameters

  oggz | A OGGZ* handle (created with OGGZ_WRITE)
  serialno | Identify a logical bitstream within oggz
  comment | The comment to remove.

Return values

  1 | Success: comment removed
  0 | No-op: comment not found, nothing to remove
  OGGZ_ERR_BAD | oggz is not a valid OGGZ* handle
  OGGZ_ERR_INVALID | Operation not suitable for this OGGZ
  OGGZ_ERR_BAD_SERIALNO | serialno does not identify an existing logical bitstream in oggz.

## ◆ oggz_comment_remove_byname()

int oggz_comment_remove_byname | ( | OGGZ * | oggz,
|  | long | serialno,
|  | char * | name
| ) |  |

Remove all comments with a given name.

Parameters

  oggz | A OGGZ* handle (created with OGGZ_WRITE)
  serialno | Identify a logical bitstream within oggz
  name | The name of the comments to remove

Return values

  >= 0 | The number of comments removed
  OGGZ_ERR_BAD | oggz is not a valid OGGZ* handle
  OGGZ_ERR_INVALID | Operation not suitable for this OGGZ
  OGGZ_ERR_BAD_SERIALNO | serialno does not identify an existing logical bitstream in oggz.

## ◆ oggz_comment_set_vendor()

int oggz_comment_set_vendor | ( | OGGZ * | oggz,
|  | long | serialno,
|  | const char * | vendor_string
| ) |  |

Set the vendor string.

Parameters

  oggz | A OGGZ* handle
  serialno | Identify a logical bitstream within oggz
  vendor_string | The contents of the vendor string to add

Return values

  0 | Success
  OGGZ_ERR_BAD | oggz is not a valid OGGZ* handle
  OGGZ_ERR_INVALID | Operation not suitable for this OGGZ
  OGGZ_ERR_OUT_OF_MEMORY | Out of memory

Note
  The vendor string should identify the library used to produce the stream, e.g. libvorbis 1.0 used "Xiph.Org libVorbis I 20020717". If copying a bitstream it should be the same as the source.

## ◆ oggz_comments_generate()

ogg_packet* oggz_comments_generate | ( | OGGZ * | oggz,
|  | long | serialno,
|  | int | FLAC_final_metadata_block
| ) |  |

Output a comment packet for the specified stream.

Parameters

  oggz | A OGGZ* handle (created with OGGZ_WRITE)
  serialno | Identify a logical bitstream within oggz
  FLAC_final_metadata_block | Set this to zero unless the packet_type is FLAC, and there are no further metadata blocks to follow. See note below for details.

Returns
  A comment packet for the stream. When no longer needed it should be freed with oggz_packet_destroy().

Return values

  NULL | content type does not support comments, not enough memory or comment was too long for FLAC

Note
  FLAC streams may contain multiple metadata blocks of different types. When encapsulated in Ogg the first of these must be a Vorbis comment packet but PADDING, APPLICATION, SEEKTABLE, CUESHEET and PICTURE may follow. The last metadata block must have its first bit set to 1. Since liboggz does not know whether you will supply more metadata blocks you must tell it if this is the last (or only) metadata block by setting FLAC_final_metadata_block to 1.
  As FLAC metadata blocks are limited in size to 16MB minus 1 byte, this function will refuse to produce longer comment packets for FLAC.
  See http://flac.sourceforge.net/format.html for more details.

## ◆ oggz_packet_destroy()

void oggz_packet_destroy | ( | ogg_packet * | packet | ) |

Free a packet and its payload.

Parameters

  packet | A packet previously returned from a function such as oggz_comment_generate(). User generated packets should not be passed.