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