aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMax Kellermann <max@duempel.org>2009-03-01 00:55:20 +0100
committerMax Kellermann <max@duempel.org>2009-03-01 00:55:20 +0100
commit6153c86bc3c2c10055143bd85aa3c1ea0dedd769 (patch)
treed884d69646c337016e00f221651730046e1efa0d
parentb49518c63632ab6a31a8d1267959110858d9f004 (diff)
downloadmpd-6153c86bc3c2c10055143bd85aa3c1ea0dedd769.tar.gz
mpd-6153c86bc3c2c10055143bd85aa3c1ea0dedd769.tar.xz
mpd-6153c86bc3c2c10055143bd85aa3c1ea0dedd769.zip
tag: added API documentation
-rw-r--r--src/tag.h65
1 files changed, 65 insertions, 0 deletions
diff --git a/src/tag.h b/src/tag.h
index 34f99c0b5..760e0b35b 100644
--- a/src/tag.h
+++ b/src/tag.h
@@ -26,6 +26,9 @@
#include <stdbool.h>
#include <string.h>
+/**
+ * Codes for the type of a tag item.
+ */
enum tag_type {
TAG_ITEM_ARTIST,
TAG_ITEM_ALBUM,
@@ -48,25 +51,65 @@ enum tag_type {
TAG_NUM_OF_ITEM_TYPES
};
+/**
+ * An array of strings, which map the #tag_type to its machine
+ * readable name (specific to the MPD protocol).
+ */
extern const char *tag_item_names[];
+/**
+ * One tag value. It is a mapping of #tag_type to am arbitrary string
+ * value. Each tag can have multiple items of one tag type (although
+ * few clients support that).
+ */
struct tag_item {
+ /** the type of this item */
enum tag_type type;
+
+ /**
+ * the value of this tag; this is a variable length string
+ */
char value[sizeof(long)];
} mpd_packed;
+/**
+ * The meta information about a song file. It is a MPD specific
+ * subset of tags (e.g. from ID3, vorbis comments, ...).
+ */
struct tag {
+ /**
+ * The duration of the song (in seconds). A value of zero
+ * means that the length is unknown. If the duration is
+ * really between zero and one second, you should round up to
+ * 1.
+ */
int time;
+
+ /** an array of tag items */
struct tag_item **items;
+
+ /** the total number of tag items in the #items array */
unsigned num_items;
};
+/**
+ * Creates an empty #tag.
+ */
struct tag *tag_new(void);
+/**
+ * Initializes the tag library.
+ */
void tag_lib_init(void);
+/**
+ * Clear all tag items with the specified type.
+ */
void tag_clear_items_by_type(struct tag *tag, enum tag_type type);
+/**
+ * Frees a #tag object and all its items.
+ */
void tag_free(struct tag *tag);
/**
@@ -83,15 +126,33 @@ void tag_begin_add(struct tag *tag);
*/
void tag_end_add(struct tag *tag);
+/**
+ * Appends a new tag item.
+ *
+ * @param tag the #tag object
+ * @param type the type of the new tag item
+ * @param value the value of the tag item (not null-terminated)
+ * @param len the length of #value
+ */
void tag_add_item_n(struct tag *tag, enum tag_type type,
const char *value, size_t len);
+/**
+ * Appends a new tag item.
+ *
+ * @param tag the #tag object
+ * @param type the type of the new tag item
+ * @param value the value of the tag item (null-terminated)
+ */
static inline void
tag_add_item(struct tag *tag, enum tag_type type, const char *value)
{
tag_add_item_n(tag, type, value, strlen(value));
}
+/**
+ * Duplicates a #tag object.
+ */
struct tag *tag_dup(const struct tag *tag);
/**
@@ -135,6 +196,10 @@ tag_get_value(const struct tag *tag, enum tag_type type);
*/
bool tag_has_type(const struct tag *tag, enum tag_type type);
+/**
+ * Compares two tags, including the duration and all tag items. The
+ * order of the tag items matters.
+ */
bool tag_equal(const struct tag *tag1, const struct tag *tag2);
#endif