oggz_comments.h File Reference

Reading of comments. More...

#include <oggz/oggz.h>

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.

oggz_comments.h File Reference

Data Structures

Functions

Detailed Description

Reading comments

Writing comments

Function Documentation