1/* 2 * libid3tag - ID3 tag manipulation library 3 * Copyright (C) 2000-2004 Underbit Technologies, Inc. 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 16 * along with this program; if not, write to the Free Software 17 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 18 * 19 * If you would like to negotiate alternate licensing terms, you may do 20 * so by contacting: Underbit Technologies, Inc. <info@underbit.com> 21 * 22 * $Id: id3tag.h,v 1.17 2004/01/23 23:22:46 rob Exp $ 23 */ 24 25# ifndef LIBID3TAG_ID3TAG_H 26# define LIBID3TAG_ID3TAG_H 27 28# ifdef __cplusplus 29extern "C" { 30# endif 31 32# define ID3_TAG_VERSION 0x0400 33# define ID3_TAG_VERSION_MAJOR(x) (((x) >> 8) & 0xff) 34# define ID3_TAG_VERSION_MINOR(x) (((x) >> 0) & 0xff) 35 36typedef unsigned char id3_byte_t; 37typedef unsigned long id3_length_t; 38 39typedef unsigned long id3_ucs4_t; 40 41typedef unsigned char id3_latin1_t; 42typedef unsigned short id3_utf16_t; 43typedef signed char id3_utf8_t; 44 45struct id3_tag { 46 unsigned int refcount; 47 unsigned int version; 48 int flags; 49 int extendedflags; 50 int restrictions; 51 int options; 52 unsigned int nframes; 53 struct id3_frame **frames; 54 id3_length_t paddedsize; 55}; 56 57# define ID3_TAG_QUERYSIZE 10 58 59/* ID3v1 field frames */ 60 61# define ID3_FRAME_TITLE "TIT2" 62# define ID3_FRAME_ARTIST "TPE1" 63# define ID3_FRAME_ALBUM "TALB" 64# define ID3_FRAME_TRACK "TRCK" 65# define ID3_FRAME_YEAR "TDRC" 66# define ID3_FRAME_GENRE "TCON" 67# define ID3_FRAME_COMMENT "COMM" 68 69/* special frames */ 70 71# define ID3_FRAME_OBSOLETE "ZOBS" /* with apologies to the French */ 72 73/* tag flags */ 74 75enum { 76 ID3_TAG_FLAG_UNSYNCHRONISATION = 0x80, 77 ID3_TAG_FLAG_EXTENDEDHEADER = 0x40, 78 ID3_TAG_FLAG_EXPERIMENTALINDICATOR = 0x20, 79 ID3_TAG_FLAG_FOOTERPRESENT = 0x10, 80 81 ID3_TAG_FLAG_KNOWNFLAGS = 0xf0 82}; 83 84/* tag extended flags */ 85 86enum { 87 ID3_TAG_EXTENDEDFLAG_TAGISANUPDATE = 0x40, 88 ID3_TAG_EXTENDEDFLAG_CRCDATAPRESENT = 0x20, 89 ID3_TAG_EXTENDEDFLAG_TAGRESTRICTIONS = 0x10, 90 91 ID3_TAG_EXTENDEDFLAG_KNOWNFLAGS = 0x70 92}; 93 94/* tag restrictions */ 95 96enum { 97 ID3_TAG_RESTRICTION_TAGSIZE_MASK = 0xc0, 98 ID3_TAG_RESTRICTION_TAGSIZE_128_FRAMES_1_MB = 0x00, 99 ID3_TAG_RESTRICTION_TAGSIZE_64_FRAMES_128_KB = 0x40, 100 ID3_TAG_RESTRICTION_TAGSIZE_32_FRAMES_40_KB = 0x80, 101 ID3_TAG_RESTRICTION_TAGSIZE_32_FRAMES_4_KB = 0xc0 102}; 103 104enum { 105 ID3_TAG_RESTRICTION_TEXTENCODING_MASK = 0x20, 106 ID3_TAG_RESTRICTION_TEXTENCODING_NONE = 0x00, 107 ID3_TAG_RESTRICTION_TEXTENCODING_LATIN1_UTF8 = 0x20 108}; 109 110enum { 111 ID3_TAG_RESTRICTION_TEXTSIZE_MASK = 0x18, 112 ID3_TAG_RESTRICTION_TEXTSIZE_NONE = 0x00, 113 ID3_TAG_RESTRICTION_TEXTSIZE_1024_CHARS = 0x08, 114 ID3_TAG_RESTRICTION_TEXTSIZE_128_CHARS = 0x10, 115 ID3_TAG_RESTRICTION_TEXTSIZE_30_CHARS = 0x18 116}; 117 118enum { 119 ID3_TAG_RESTRICTION_IMAGEENCODING_MASK = 0x04, 120 ID3_TAG_RESTRICTION_IMAGEENCODING_NONE = 0x00, 121 ID3_TAG_RESTRICTION_IMAGEENCODING_PNG_JPEG = 0x04 122}; 123 124enum { 125 ID3_TAG_RESTRICTION_IMAGESIZE_MASK = 0x03, 126 ID3_TAG_RESTRICTION_IMAGESIZE_NONE = 0x00, 127 ID3_TAG_RESTRICTION_IMAGESIZE_256_256 = 0x01, 128 ID3_TAG_RESTRICTION_IMAGESIZE_64_64 = 0x02, 129 ID3_TAG_RESTRICTION_IMAGESIZE_64_64_EXACT = 0x03 130}; 131 132/* library options */ 133 134enum { 135 ID3_TAG_OPTION_UNSYNCHRONISATION = 0x0001, /* use unsynchronisation */ 136 ID3_TAG_OPTION_COMPRESSION = 0x0002, /* use compression */ 137 ID3_TAG_OPTION_CRC = 0x0004, /* use CRC */ 138 139 ID3_TAG_OPTION_APPENDEDTAG = 0x0010, /* tag will be appended */ 140 ID3_TAG_OPTION_FILEALTERED = 0x0020, /* audio data was altered */ 141 142 ID3_TAG_OPTION_ID3V1 = 0x0100 /* render ID3v1/ID3v1.1 tag */ 143}; 144 145struct id3_frame { 146 char id[5]; 147 char const *description; 148 unsigned int refcount; 149 int flags; 150 int group_id; 151 int encryption_method; 152 id3_byte_t *encoded; 153 id3_length_t encoded_length; 154 id3_length_t decoded_length; 155 unsigned int nfields; 156 union id3_field *fields; 157}; 158 159enum { 160 /* frame status flags */ 161 ID3_FRAME_FLAG_TAGALTERPRESERVATION = 0x4000, 162 ID3_FRAME_FLAG_FILEALTERPRESERVATION = 0x2000, 163 ID3_FRAME_FLAG_READONLY = 0x1000, 164 165 ID3_FRAME_FLAG_STATUSFLAGS = 0xff00, 166 167 /* frame format flags */ 168 ID3_FRAME_FLAG_GROUPINGIDENTITY = 0x0040, 169 ID3_FRAME_FLAG_COMPRESSION = 0x0008, 170 ID3_FRAME_FLAG_ENCRYPTION = 0x0004, 171 ID3_FRAME_FLAG_UNSYNCHRONISATION = 0x0002, 172 ID3_FRAME_FLAG_DATALENGTHINDICATOR = 0x0001, 173 174 ID3_FRAME_FLAG_FORMATFLAGS = 0x00ff, 175 176 ID3_FRAME_FLAG_KNOWNFLAGS = 0x704f 177}; 178 179enum id3_field_type { 180 ID3_FIELD_TYPE_TEXTENCODING, 181 ID3_FIELD_TYPE_LATIN1, 182 ID3_FIELD_TYPE_LATIN1FULL, 183 ID3_FIELD_TYPE_LATIN1LIST, 184 ID3_FIELD_TYPE_STRING, 185 ID3_FIELD_TYPE_STRINGFULL, 186 ID3_FIELD_TYPE_STRINGLIST, 187 ID3_FIELD_TYPE_LANGUAGE, 188 ID3_FIELD_TYPE_FRAMEID, 189 ID3_FIELD_TYPE_DATE, 190 ID3_FIELD_TYPE_INT8, 191 ID3_FIELD_TYPE_INT16, 192 ID3_FIELD_TYPE_INT24, 193 ID3_FIELD_TYPE_INT32, 194 ID3_FIELD_TYPE_INT32PLUS, 195 ID3_FIELD_TYPE_BINARYDATA 196}; 197 198enum id3_field_textencoding { 199 ID3_FIELD_TEXTENCODING_ISO_8859_1 = 0x00, 200 ID3_FIELD_TEXTENCODING_UTF_16 = 0x01, 201 ID3_FIELD_TEXTENCODING_UTF_16BE = 0x02, 202 ID3_FIELD_TEXTENCODING_UTF_8 = 0x03 203}; 204 205union id3_field { 206 enum id3_field_type type; 207 struct { 208 enum id3_field_type type; 209 signed long value; 210 } number; 211 struct { 212 enum id3_field_type type; 213 id3_latin1_t *ptr; 214 } latin1; 215 struct { 216 enum id3_field_type type; 217 unsigned int nstrings; 218 id3_latin1_t **strings; 219 } latin1list; 220 struct { 221 enum id3_field_type type; 222 id3_ucs4_t *ptr; 223 } string; 224 struct { 225 enum id3_field_type type; 226 unsigned int nstrings; 227 id3_ucs4_t **strings; 228 } stringlist; 229 struct { 230 enum id3_field_type type; 231 char value[9]; 232 } immediate; 233 struct { 234 enum id3_field_type type; 235 id3_byte_t *data; 236 id3_length_t length; 237 } binary; 238}; 239 240/* file interface */ 241 242enum id3_file_mode { 243 ID3_FILE_MODE_READONLY = 0, 244 ID3_FILE_MODE_READWRITE 245}; 246 247struct id3_file *id3_file_open(char const *, enum id3_file_mode); 248struct id3_file *id3_file_fdopen(int, enum id3_file_mode); 249int id3_file_close(struct id3_file *); 250 251struct id3_tag *id3_file_tag(struct id3_file const *); 252 253int id3_file_update(struct id3_file *); 254 255/* tag interface */ 256 257struct id3_tag *id3_tag_new(void); 258void id3_tag_delete(struct id3_tag *); 259 260unsigned int id3_tag_version(struct id3_tag const *); 261 262int id3_tag_options(struct id3_tag *, int, int); 263void id3_tag_setlength(struct id3_tag *, id3_length_t); 264 265void id3_tag_clearframes(struct id3_tag *); 266 267int id3_tag_attachframe(struct id3_tag *, struct id3_frame *); 268int id3_tag_detachframe(struct id3_tag *, struct id3_frame *); 269 270struct id3_frame *id3_tag_findframe(struct id3_tag const *, 271 char const *, unsigned int); 272 273signed long id3_tag_query(id3_byte_t const *, id3_length_t); 274 275struct id3_tag *id3_tag_parse(id3_byte_t const *, id3_length_t); 276id3_length_t id3_tag_render(struct id3_tag const *, id3_byte_t *); 277 278/* frame interface */ 279 280struct id3_frame *id3_frame_new(char const *); 281void id3_frame_delete(struct id3_frame *); 282 283union id3_field *id3_frame_field(struct id3_frame const *, unsigned int); 284 285/* field interface */ 286 287enum id3_field_type id3_field_type(union id3_field const *); 288 289int id3_field_setint(union id3_field *, signed long); 290int id3_field_settextencoding(union id3_field *, enum id3_field_textencoding); 291int id3_field_setstrings(union id3_field *, unsigned int, id3_ucs4_t **); 292int id3_field_addstring(union id3_field *, id3_ucs4_t const *); 293int id3_field_setlanguage(union id3_field *, char const *); 294int id3_field_setlatin1(union id3_field *, id3_latin1_t const *); 295int id3_field_setfulllatin1(union id3_field *, id3_latin1_t const *); 296int id3_field_setstring(union id3_field *, id3_ucs4_t const *); 297int id3_field_setfullstring(union id3_field *, id3_ucs4_t const *); 298int id3_field_setframeid(union id3_field *, char const *); 299int id3_field_setbinarydata(union id3_field *, 300 id3_byte_t const *, id3_length_t); 301 302signed long id3_field_getint(union id3_field const *); 303enum id3_field_textencoding id3_field_gettextencoding(union id3_field const *); 304id3_latin1_t const *id3_field_getlatin1(union id3_field const *); 305id3_latin1_t const *id3_field_getfulllatin1(union id3_field const *); 306id3_ucs4_t const *id3_field_getstring(union id3_field const *); 307id3_ucs4_t const *id3_field_getfullstring(union id3_field const *); 308unsigned int id3_field_getnstrings(union id3_field const *); 309id3_ucs4_t const *id3_field_getstrings(union id3_field const *, 310 unsigned int); 311char const *id3_field_getframeid(union id3_field const *); 312id3_byte_t const *id3_field_getbinarydata(union id3_field const *, 313 id3_length_t *); 314 315/* genre interface */ 316 317id3_ucs4_t const *id3_genre_index(unsigned int); 318id3_ucs4_t const *id3_genre_name(id3_ucs4_t const *); 319int id3_genre_number(id3_ucs4_t const *); 320 321/* ucs4 interface */ 322 323id3_latin1_t *id3_ucs4_latin1duplicate(id3_ucs4_t const *); 324id3_utf16_t *id3_ucs4_utf16duplicate(id3_ucs4_t const *); 325id3_utf8_t *id3_ucs4_utf8duplicate(id3_ucs4_t const *); 326 327void id3_ucs4_putnumber(id3_ucs4_t *, unsigned long); 328unsigned long id3_ucs4_getnumber(id3_ucs4_t const *); 329 330/* latin1/utf16/utf8 interfaces */ 331 332id3_ucs4_t *id3_latin1_ucs4duplicate(id3_latin1_t const *); 333id3_ucs4_t *id3_utf16_ucs4duplicate(id3_utf16_t const *); 334id3_ucs4_t *id3_utf8_ucs4duplicate(id3_utf8_t const *); 335 336/* version interface */ 337 338# define ID3_VERSION_MAJOR 0 339# define ID3_VERSION_MINOR 15 340# define ID3_VERSION_PATCH 1 341# define ID3_VERSION_EXTRA " (beta)" 342 343# define ID3_VERSION_STRINGIZE(str) #str 344# define ID3_VERSION_STRING(num) ID3_VERSION_STRINGIZE(num) 345 346# define ID3_VERSION ID3_VERSION_STRING(ID3_VERSION_MAJOR) "." \ 347 ID3_VERSION_STRING(ID3_VERSION_MINOR) "." \ 348 ID3_VERSION_STRING(ID3_VERSION_PATCH) \ 349 ID3_VERSION_EXTRA 350 351# define ID3_PUBLISHYEAR "2000-2004" 352# define ID3_AUTHOR "Underbit Technologies, Inc." 353# define ID3_EMAIL "info@underbit.com" 354 355extern char const id3_version[]; 356extern char const id3_copyright[]; 357extern char const id3_author[]; 358extern char const id3_build[]; 359 360# ifdef __cplusplus 361} 362# endif 363 364# endif 365