kate_comment access

Functions
int	kate_comment_init (kate_comment *kc)
int	kate_comment_clear (kate_comment *kc)
int	kate_comment_add_length (kate_comment *kc, const char *comment, size_t len)
int	kate_comment_add (kate_comment *kc, const char *comment)
int	kate_comment_add_tag (kate_comment *kc, const char *tag, const char *value)
const char *	kate_comment_query (const kate_comment *kc, const char *tag, int count)
int	kate_comment_query_count (const kate_comment *kc, const char *tag)

Detailed Description

Function Documentation

int kate_comment_add	(	kate_comment *	kc,
		const char *	comment
	)

Adds a comment to the kate_comment structure. The comment must be of the form "tag=value" The comment tag must be 7 bit ASCII, and may not contain embedded NULs The comment value is UTF-8 and may not contain embedded NULs as the comments ends at the first NUL encountered

Parameters

kc	the kate_comment structure to add the comment to
comment	the comment to add, NUL terminated

Returns

0 success

KATE_E_* error

References kate_comment_add_length(), and KATE_E_INVALID_PARAMETER.

Referenced by kate_comment_add_tag().

int kate_comment_add_length	(	kate_comment *	kc,
		const char *	comment,
		size_t	len
	)

Adds a comment to the kate_comment structure. The comment must be of the form "tag=value" The comment tag must be 7 bit ASCII, and may not contain embedded NULs The comment value is UTF-8 and may contain embedded NULs

Parameters

kc	the kate_comment structure to add the comment to
comment	the comment to add (a stream of len bytes)
len	the number of bytes in the comment

Returns

0 success

KATE_E_* error

References kate_comment::comment_lengths, kate_comment::comments, KATE_E_BAD_TAG, KATE_E_INVALID_PARAMETER, KATE_E_OUT_OF_MEMORY, kate_text_validate(), kate_utf8, and kate_comment::user_comments.

Referenced by kate_comment_add().

int kate_comment_add_tag	(	kate_comment *	kc,
		const char *	tag,
		const char *	value
	)

Adds a comment to the kate_comment structure, formatted as "tag=value". The tag must be 7 bit ASCII and comply with Vorbis comment tag rules. The value must be valid UTF-8 text. Neither tag nor value may contain embedded NULs. To embed comments with embedded NUL in the payload, see kate_comment_add_length.

Parameters

kc	the kate_comment structure to add the comment to
tag	the tag of the comment to add
value	the contents of the comment to add

Returns

0 success

KATE_E_* error

References kate_comment_add(), KATE_E_INVALID_PARAMETER, and KATE_E_OUT_OF_MEMORY.

int kate_comment_clear

(

kate_comment *

kc

)

Destroys a kate_comment structure, it must be initialized again before being used.

Parameters

kc	the structure to clear

Returns

0 success

KATE_E_* error

References kate_comment::comment_lengths, kate_comment::comments, KATE_E_INVALID_PARAMETER, kate_comment::user_comments, and kate_comment::vendor.

int kate_comment_init

(

kate_comment *

kc

)

Initializes a kate_comment structure.

Parameters

kc	the structure to initialize

Returns

0 success

KATE_E_* error

References kate_comment::comment_lengths, kate_comment::comments, KATE_E_INVALID_PARAMETER, kate_comment::user_comments, and kate_comment::vendor.

Referenced by kate_high_decode_init().

const char* kate_comment_query	(	const kate_comment *	kc,
		const char *	tag,
		int	count
	)

Queries the value of a comment that has the given tag. The tags are case insensitive, so "tag", "TAG", "Tag", and "TaG" are all equivalent. If there are multiple comments with the same tag, count may be used to select which one to return. The number of comments with a given tag may be retrieved using kate_comment_query_count.

Parameters

kc	the kate_comment structure to look into
tag	the title of the comment to look for
count	the index of the matching comment to return (if there are several)

Returns

0 success

KATE_E_* error

References kate_comment::comments, and kate_comment::user_comments.

int kate_comment_query_count	(	const kate_comment *	kc,
		const char *	tag
	)

Returns the number of comments with the given tag. The tags are case insensitive, so "tag", "TAG", "Tag", and "TaG" are all equivalent.

Parameters

kc	the kate_comment structure to look into
tag	the title of the comment to look for

Returns

0 success

KATE_E_* error

References kate_comment::comments, KATE_E_INVALID_PARAMETER, and kate_comment::user_comments.