src/tag.h

   1 /*
   2  * Copyright (C) 2003-2010 The Music Player Daemon Project
   3  * http://www.musicpd.org
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  18  */
  19
  20 #ifndef MPD_TAG_H
  21 #define MPD_TAG_H
  22
  23 #include "gcc.h"
  24
  25 #include <stdint.h>
  26 #include <stddef.h>
  27 #include <stdbool.h>
  28 #include <string.h>
  29
  30 /**
  31  * Codes for the type of a tag item.
  32  */
  33 enum tag_type {
  34         TAG_ARTIST,
  35         TAG_ARTIST_SORT,
  36         TAG_ALBUM,
  37         TAG_ALBUM_ARTIST,
  38         TAG_ALBUM_ARTIST_SORT,
  39         TAG_TITLE,
  40         TAG_TRACK,
  41         TAG_NAME,
  42         TAG_GENRE,
  43         TAG_DATE,
  44         TAG_COMPOSER,
  45         TAG_PERFORMER,
  46         TAG_COMMENT,
  47         TAG_DISC,
  48
  49         TAG_MUSICBRAINZ_ARTISTID,
  50         TAG_MUSICBRAINZ_ALBUMID,
  51         TAG_MUSICBRAINZ_ALBUMARTISTID,
  52         TAG_MUSICBRAINZ_TRACKID,
  53
  54         TAG_NUM_OF_ITEM_TYPES
  55 };
  56
  57 /**
  58  * An array of strings, which map the #tag_type to its machine
  59  * readable name (specific to the MPD protocol).
  60  */
  61 extern const char *tag_item_names[];
  62
  63 /**
  64  * One tag value.  It is a mapping of #tag_type to am arbitrary string
  65  * value.  Each tag can have multiple items of one tag type (although
  66  * few clients support that).
  67  */
  68 struct tag_item {
  69         /** the type of this item */
  70         enum tag_type type;
  71
  72         /**
  73          * the value of this tag; this is a variable length string
  74          */
  75         char value[sizeof(long)];
  76 } mpd_packed;
  77
  78 /**
  79  * The meta information about a song file.  It is a MPD specific
  80  * subset of tags (e.g. from ID3, vorbis comments, ...).
  81  */
  82 struct tag {
  83         /**
  84          * The duration of the song (in seconds).  A value of zero
  85          * means that the length is unknown.  If the duration is
  86          * really between zero and one second, you should round up to
  87          * 1.
  88          */
  89         int time;
  90
  91         /** an array of tag items */
  92         struct tag_item **items;
  93
  94         /** the total number of tag items in the #items array */
  95         unsigned num_items;
  96 };
  97
  98 /**
  99  * Parse the string, and convert it into a #tag_type.  Returns
 100  * #TAG_NUM_OF_ITEM_TYPES if the string could not be recognized.
 101  */
 102 enum tag_type
 103 tag_name_parse(const char *name);
 104
 105 /**
 106  * Parse the string, and convert it into a #tag_type.  Returns
 107  * #TAG_NUM_OF_ITEM_TYPES if the string could not be recognized.
 108  *
 109  * Case does not matter.
 110  */
 111 enum tag_type
 112 tag_name_parse_i(const char *name);
 113
 114 /**
 115  * Creates an empty #tag.
 116  */
 117 struct tag *tag_new(void);
 118
 119 /**
 120  * Initializes the tag library.
 121  */
 122 void tag_lib_init(void);
 123
 124 /**
 125  * Clear all tag items with the specified type.
 126  */
 127 void tag_clear_items_by_type(struct tag *tag, enum tag_type type);
 128
 129 /**
 130  * Frees a #tag object and all its items.
 131  */
 132 void tag_free(struct tag *tag);
 133
 134 /**
 135  * Gives an optional hint to the tag library that we will now add
 136  * several tag items; this is used by the library to optimize memory
 137  * allocation.  Only one tag may be in this state, and this tag must
 138  * not have any items yet.  You must call tag_end_add() when you are
 139  * done.
 140  */
 141 void tag_begin_add(struct tag *tag);
 142
 143 /**
 144  * Finishes the operation started with tag_begin_add().
 145  */
 146 void tag_end_add(struct tag *tag);
 147
 148 /**
 149  * Appends a new tag item.
 150  *
 151  * @param tag the #tag object
 152  * @param type the type of the new tag item
 153  * @param value the value of the tag item (not null-terminated)
 154  * @param len the length of #value
 155  */
 156 void tag_add_item_n(struct tag *tag, enum tag_type type,
 157                     const char *value, size_t len);
 158
 159 /**
 160  * Appends a new tag item.
 161  *
 162  * @param tag the #tag object
 163  * @param type the type of the new tag item
 164  * @param value the value of the tag item (null-terminated)
 165  */
 166 static inline void
 167 tag_add_item(struct tag *tag, enum tag_type type, const char *value)
 168 {
 169         tag_add_item_n(tag, type, value, strlen(value));
 170 }
 171
 172 /**
 173  * Duplicates a #tag object.
 174  */
 175 struct tag *tag_dup(const struct tag *tag);
 176
 177 /**
 178  * Merges the data from two tags.  If both tags share data for the
 179  * same tag_type, only data from "add" is used.
 180  *
 181  * @return a newly allocated tag, which must be freed with tag_free()
 182  */
 183 struct tag *
 184 tag_merge(const struct tag *base, const struct tag *add);
 185
 186 /**
 187  * Merges the data from two tags.  Any of the two may be NULL.  Both
 188  * are freed by this function.
 189  *
 190  * @return a newly allocated tag, which must be freed with tag_free()
 191  */
 192 struct tag *
 193 tag_merge_replace(struct tag *base, struct tag *add);
 194
 195 /**
 196  * Returns true if the tag contains no items.  This ignores the "time"
 197  * attribute.
 198  */
 199 static inline bool
 200 tag_is_empty(const struct tag *tag)
 201 {
 202         return tag->num_items == 0;
 203 }
 204
 205 /**
 206  * Returns true if the tag contains any information.
 207  */
 208 static inline bool
 209 tag_is_defined(const struct tag *tag)
 210 {
 211         return !tag_is_empty(tag) || tag->time >= 0;
 212 }
 213
 214 /**
 215  * Returns the first value of the specified tag type, or NULL if none
 216  * is present in this tag object.
 217  */
 218 const char *
 219 tag_get_value(const struct tag *tag, enum tag_type type);
 220
 221 /**
 222  * Checks whether the tag contains one or more items with
 223  * the specified type.
 224  */
 225 bool tag_has_type(const struct tag *tag, enum tag_type type);
 226
 227 /**
 228  * Compares two tags, including the duration and all tag items.  The
 229  * order of the tag items matters.
 230  */
 231 bool tag_equal(const struct tag *tag1, const struct tag *tag2);
 232
 233 #endif