liboggz: oggz_comments.h File Reference

# 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.
int | oggz_comment_set_vendor (OGGZ *oggz, long serialno, const char *vendor_string)
| Set the vendor string.
const OggzComment * | oggz_comment_first (OGGZ *oggz, long serialno)
| Retrieve the first comment.
const OggzComment * | oggz_comment_next (OGGZ *oggz, long serialno, const OggzComment *comment)
| Retrieve the next comment.
const OggzComment * | oggz_comment_first_byname (OGGZ *oggz, long serialno, char *name)
| Retrieve the first comment with a given name.
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.
int | oggz_comment_add (OGGZ *oggz, long serialno, OggzComment *comment)
| Add a comment.
int | oggz_comment_add_byname (OGGZ *oggz, long serialno, const char *name, const char *value)
| Add a comment by name and value.
int | oggz_comment_remove (OGGZ *oggz, long serialno, OggzComment *comment)
| Remove a comment.
int | oggz_comment_remove_byname (OGGZ *oggz, long serialno, char *name)
| Remove all comments with a given name.
ogg_packet * | oggz_comments_generate (OGGZ *oggz, long serialno, int FLAC_final_metadata_block)
| Output a comment packet for the specified stream.
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.

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

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

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

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.

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

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.

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.

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.

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.

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.

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.

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.

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.