Chris@0: /*
Chris@0:  * libid3tag - ID3 tag manipulation library
Chris@0:  * Copyright (C) 2000-2004 Underbit Technologies, Inc.
Chris@0:  *
Chris@0:  * This program is free software; you can redistribute it and/or modify
Chris@0:  * it under the terms of the GNU General Public License as published by
Chris@0:  * the Free Software Foundation; either version 2 of the License, or
Chris@0:  * (at your option) any later version.
Chris@0:  *
Chris@0:  * This program is distributed in the hope that it will be useful,
Chris@0:  * but WITHOUT ANY WARRANTY; without even the implied warranty of
Chris@0:  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
Chris@0:  * GNU General Public License for more details.
Chris@0:  *
Chris@0:  * You should have received a copy of the GNU General Public License
Chris@0:  * along with this program; if not, write to the Free Software
Chris@0:  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
Chris@0:  *
Chris@0:  * If you would like to negotiate alternate licensing terms, you may do
Chris@0:  * so by contacting: Underbit Technologies, Inc. <info@underbit.com>
Chris@0:  *
Chris@0:  * $Id: id3tag.h,v 1.17 2004/01/23 23:22:46 rob Exp $
Chris@0:  */
Chris@0: 
Chris@0: # ifndef LIBID3TAG_ID3TAG_H
Chris@0: # define LIBID3TAG_ID3TAG_H
Chris@0: 
Chris@0: # ifdef __cplusplus
Chris@0: extern "C" {
Chris@0: # endif
Chris@0: 
Chris@0: # define ID3_TAG_VERSION		0x0400
Chris@0: # define ID3_TAG_VERSION_MAJOR(x)	(((x) >> 8) & 0xff)
Chris@0: # define ID3_TAG_VERSION_MINOR(x)	(((x) >> 0) & 0xff)
Chris@0: 
Chris@0: typedef unsigned char id3_byte_t;
Chris@0: typedef unsigned long id3_length_t;
Chris@0: 
Chris@0: typedef unsigned long id3_ucs4_t;
Chris@0: 
Chris@0: typedef unsigned char id3_latin1_t;
Chris@0: typedef unsigned short id3_utf16_t;
Chris@0: typedef signed char id3_utf8_t;
Chris@0: 
Chris@0: struct id3_tag {
Chris@0:   unsigned int refcount;
Chris@0:   unsigned int version;
Chris@0:   int flags;
Chris@0:   int extendedflags;
Chris@0:   int restrictions;
Chris@0:   int options;
Chris@0:   unsigned int nframes;
Chris@0:   struct id3_frame **frames;
Chris@0:   id3_length_t paddedsize;
Chris@0: };
Chris@0: 
Chris@0: # define ID3_TAG_QUERYSIZE	10
Chris@0: 
Chris@0: /* ID3v1 field frames */
Chris@0: 
Chris@0: # define ID3_FRAME_TITLE	"TIT2"
Chris@0: # define ID3_FRAME_ARTIST	"TPE1"
Chris@0: # define ID3_FRAME_ALBUM	"TALB"
Chris@0: # define ID3_FRAME_TRACK	"TRCK"
Chris@0: # define ID3_FRAME_YEAR		"TDRC"
Chris@0: # define ID3_FRAME_GENRE	"TCON"
Chris@0: # define ID3_FRAME_COMMENT	"COMM"
Chris@0: 
Chris@0: /* special frames */
Chris@0: 
Chris@0: # define ID3_FRAME_OBSOLETE	"ZOBS"	/* with apologies to the French */
Chris@0: 
Chris@0: /* tag flags */
Chris@0: 
Chris@0: enum {
Chris@0:   ID3_TAG_FLAG_UNSYNCHRONISATION     = 0x80,
Chris@0:   ID3_TAG_FLAG_EXTENDEDHEADER        = 0x40,
Chris@0:   ID3_TAG_FLAG_EXPERIMENTALINDICATOR = 0x20,
Chris@0:   ID3_TAG_FLAG_FOOTERPRESENT         = 0x10,
Chris@0: 
Chris@0:   ID3_TAG_FLAG_KNOWNFLAGS            = 0xf0
Chris@0: };
Chris@0: 
Chris@0: /* tag extended flags */
Chris@0: 
Chris@0: enum {
Chris@0:   ID3_TAG_EXTENDEDFLAG_TAGISANUPDATE   = 0x40,
Chris@0:   ID3_TAG_EXTENDEDFLAG_CRCDATAPRESENT  = 0x20,
Chris@0:   ID3_TAG_EXTENDEDFLAG_TAGRESTRICTIONS = 0x10,
Chris@0: 
Chris@0:   ID3_TAG_EXTENDEDFLAG_KNOWNFLAGS      = 0x70
Chris@0: };
Chris@0: 
Chris@0: /* tag restrictions */
Chris@0: 
Chris@0: enum {
Chris@0:   ID3_TAG_RESTRICTION_TAGSIZE_MASK             = 0xc0,
Chris@0:   ID3_TAG_RESTRICTION_TAGSIZE_128_FRAMES_1_MB  = 0x00,
Chris@0:   ID3_TAG_RESTRICTION_TAGSIZE_64_FRAMES_128_KB = 0x40,
Chris@0:   ID3_TAG_RESTRICTION_TAGSIZE_32_FRAMES_40_KB  = 0x80,
Chris@0:   ID3_TAG_RESTRICTION_TAGSIZE_32_FRAMES_4_KB   = 0xc0
Chris@0: };
Chris@0: 
Chris@0: enum {
Chris@0:   ID3_TAG_RESTRICTION_TEXTENCODING_MASK        = 0x20,
Chris@0:   ID3_TAG_RESTRICTION_TEXTENCODING_NONE        = 0x00,
Chris@0:   ID3_TAG_RESTRICTION_TEXTENCODING_LATIN1_UTF8 = 0x20
Chris@0: };
Chris@0: 
Chris@0: enum {
Chris@0:   ID3_TAG_RESTRICTION_TEXTSIZE_MASK            = 0x18,
Chris@0:   ID3_TAG_RESTRICTION_TEXTSIZE_NONE            = 0x00,
Chris@0:   ID3_TAG_RESTRICTION_TEXTSIZE_1024_CHARS      = 0x08,
Chris@0:   ID3_TAG_RESTRICTION_TEXTSIZE_128_CHARS       = 0x10,
Chris@0:   ID3_TAG_RESTRICTION_TEXTSIZE_30_CHARS        = 0x18
Chris@0: };
Chris@0: 
Chris@0: enum {
Chris@0:   ID3_TAG_RESTRICTION_IMAGEENCODING_MASK       = 0x04,
Chris@0:   ID3_TAG_RESTRICTION_IMAGEENCODING_NONE       = 0x00,
Chris@0:   ID3_TAG_RESTRICTION_IMAGEENCODING_PNG_JPEG   = 0x04
Chris@0: };
Chris@0: 
Chris@0: enum {
Chris@0:   ID3_TAG_RESTRICTION_IMAGESIZE_MASK           = 0x03,
Chris@0:   ID3_TAG_RESTRICTION_IMAGESIZE_NONE           = 0x00,
Chris@0:   ID3_TAG_RESTRICTION_IMAGESIZE_256_256        = 0x01,
Chris@0:   ID3_TAG_RESTRICTION_IMAGESIZE_64_64          = 0x02,
Chris@0:   ID3_TAG_RESTRICTION_IMAGESIZE_64_64_EXACT    = 0x03
Chris@0: };
Chris@0: 
Chris@0: /* library options */
Chris@0: 
Chris@0: enum {
Chris@0:   ID3_TAG_OPTION_UNSYNCHRONISATION = 0x0001,	/* use unsynchronisation */
Chris@0:   ID3_TAG_OPTION_COMPRESSION       = 0x0002,	/* use compression */
Chris@0:   ID3_TAG_OPTION_CRC               = 0x0004,	/* use CRC */
Chris@0: 
Chris@0:   ID3_TAG_OPTION_APPENDEDTAG       = 0x0010,	/* tag will be appended */
Chris@0:   ID3_TAG_OPTION_FILEALTERED       = 0x0020,	/* audio data was altered */
Chris@0: 
Chris@0:   ID3_TAG_OPTION_ID3V1             = 0x0100	/* render ID3v1/ID3v1.1 tag */
Chris@0: };
Chris@0: 
Chris@0: struct id3_frame {
Chris@0:   char id[5];
Chris@0:   char const *description;
Chris@0:   unsigned int refcount;
Chris@0:   int flags;
Chris@0:   int group_id;
Chris@0:   int encryption_method;
Chris@0:   id3_byte_t *encoded;
Chris@0:   id3_length_t encoded_length;
Chris@0:   id3_length_t decoded_length;
Chris@0:   unsigned int nfields;
Chris@0:   union id3_field *fields;
Chris@0: };
Chris@0: 
Chris@0: enum {
Chris@0:   /* frame status flags */
Chris@0:   ID3_FRAME_FLAG_TAGALTERPRESERVATION	= 0x4000,
Chris@0:   ID3_FRAME_FLAG_FILEALTERPRESERVATION	= 0x2000,
Chris@0:   ID3_FRAME_FLAG_READONLY		= 0x1000,
Chris@0: 
Chris@0:   ID3_FRAME_FLAG_STATUSFLAGS            = 0xff00,
Chris@0: 
Chris@0:   /* frame format flags */
Chris@0:   ID3_FRAME_FLAG_GROUPINGIDENTITY	= 0x0040,
Chris@0:   ID3_FRAME_FLAG_COMPRESSION		= 0x0008,
Chris@0:   ID3_FRAME_FLAG_ENCRYPTION		= 0x0004,
Chris@0:   ID3_FRAME_FLAG_UNSYNCHRONISATION	= 0x0002,
Chris@0:   ID3_FRAME_FLAG_DATALENGTHINDICATOR	= 0x0001,
Chris@0: 
Chris@0:   ID3_FRAME_FLAG_FORMATFLAGS            = 0x00ff,
Chris@0: 
Chris@0:   ID3_FRAME_FLAG_KNOWNFLAGS             = 0x704f
Chris@0: };
Chris@0: 
Chris@0: enum id3_field_type {
Chris@0:   ID3_FIELD_TYPE_TEXTENCODING,
Chris@0:   ID3_FIELD_TYPE_LATIN1,
Chris@0:   ID3_FIELD_TYPE_LATIN1FULL,
Chris@0:   ID3_FIELD_TYPE_LATIN1LIST,
Chris@0:   ID3_FIELD_TYPE_STRING,
Chris@0:   ID3_FIELD_TYPE_STRINGFULL,
Chris@0:   ID3_FIELD_TYPE_STRINGLIST,
Chris@0:   ID3_FIELD_TYPE_LANGUAGE,
Chris@0:   ID3_FIELD_TYPE_FRAMEID,
Chris@0:   ID3_FIELD_TYPE_DATE,
Chris@0:   ID3_FIELD_TYPE_INT8,
Chris@0:   ID3_FIELD_TYPE_INT16,
Chris@0:   ID3_FIELD_TYPE_INT24,
Chris@0:   ID3_FIELD_TYPE_INT32,
Chris@0:   ID3_FIELD_TYPE_INT32PLUS,
Chris@0:   ID3_FIELD_TYPE_BINARYDATA
Chris@0: };
Chris@0: 
Chris@0: enum id3_field_textencoding {
Chris@0:   ID3_FIELD_TEXTENCODING_ISO_8859_1 = 0x00,
Chris@0:   ID3_FIELD_TEXTENCODING_UTF_16     = 0x01,
Chris@0:   ID3_FIELD_TEXTENCODING_UTF_16BE   = 0x02,
Chris@0:   ID3_FIELD_TEXTENCODING_UTF_8      = 0x03
Chris@0: };
Chris@0: 
Chris@0: union id3_field {
Chris@0:   enum id3_field_type type;
Chris@0:   struct {
Chris@0:     enum id3_field_type type;
Chris@0:     signed long value;
Chris@0:   } number;
Chris@0:   struct {
Chris@0:     enum id3_field_type type;
Chris@0:     id3_latin1_t *ptr;
Chris@0:   } latin1;
Chris@0:   struct {
Chris@0:     enum id3_field_type type;
Chris@0:     unsigned int nstrings;
Chris@0:     id3_latin1_t **strings;
Chris@0:   } latin1list;
Chris@0:   struct {
Chris@0:     enum id3_field_type type;
Chris@0:     id3_ucs4_t *ptr;
Chris@0:   } string;
Chris@0:   struct {
Chris@0:     enum id3_field_type type;
Chris@0:     unsigned int nstrings;
Chris@0:     id3_ucs4_t **strings;
Chris@0:   } stringlist;
Chris@0:   struct {
Chris@0:     enum id3_field_type type;
Chris@0:     char value[9];
Chris@0:   } immediate;
Chris@0:   struct {
Chris@0:     enum id3_field_type type;
Chris@0:     id3_byte_t *data;
Chris@0:     id3_length_t length;
Chris@0:   } binary;
Chris@0: };
Chris@0: 
Chris@0: /* file interface */
Chris@0: 
Chris@0: enum id3_file_mode {
Chris@0:   ID3_FILE_MODE_READONLY = 0,
Chris@0:   ID3_FILE_MODE_READWRITE
Chris@0: };
Chris@0: 
Chris@0: struct id3_file *id3_file_open(char const *, enum id3_file_mode);
Chris@0: struct id3_file *id3_file_fdopen(int, enum id3_file_mode);
Chris@0: int id3_file_close(struct id3_file *);
Chris@0: 
Chris@0: struct id3_tag *id3_file_tag(struct id3_file const *);
Chris@0: 
Chris@0: int id3_file_update(struct id3_file *);
Chris@0: 
Chris@0: /* tag interface */
Chris@0: 
Chris@0: struct id3_tag *id3_tag_new(void);
Chris@0: void id3_tag_delete(struct id3_tag *);
Chris@0: 
Chris@0: unsigned int id3_tag_version(struct id3_tag const *);
Chris@0: 
Chris@0: int id3_tag_options(struct id3_tag *, int, int);
Chris@0: void id3_tag_setlength(struct id3_tag *, id3_length_t);
Chris@0: 
Chris@0: void id3_tag_clearframes(struct id3_tag *);
Chris@0: 
Chris@0: int id3_tag_attachframe(struct id3_tag *, struct id3_frame *);
Chris@0: int id3_tag_detachframe(struct id3_tag *, struct id3_frame *);
Chris@0: 
Chris@0: struct id3_frame *id3_tag_findframe(struct id3_tag const *,
Chris@0: 				    char const *, unsigned int);
Chris@0: 
Chris@0: signed long id3_tag_query(id3_byte_t const *, id3_length_t);
Chris@0: 
Chris@0: struct id3_tag *id3_tag_parse(id3_byte_t const *, id3_length_t);
Chris@0: id3_length_t id3_tag_render(struct id3_tag const *, id3_byte_t *);
Chris@0: 
Chris@0: /* frame interface */
Chris@0: 
Chris@0: struct id3_frame *id3_frame_new(char const *);
Chris@0: void id3_frame_delete(struct id3_frame *);
Chris@0: 
Chris@0: union id3_field *id3_frame_field(struct id3_frame const *, unsigned int);
Chris@0: 
Chris@0: /* field interface */
Chris@0: 
Chris@0: enum id3_field_type id3_field_type(union id3_field const *);
Chris@0: 
Chris@0: int id3_field_setint(union id3_field *, signed long);
Chris@0: int id3_field_settextencoding(union id3_field *, enum id3_field_textencoding);
Chris@0: int id3_field_setstrings(union id3_field *, unsigned int, id3_ucs4_t **);
Chris@0: int id3_field_addstring(union id3_field *, id3_ucs4_t const *);
Chris@0: int id3_field_setlanguage(union id3_field *, char const *);
Chris@0: int id3_field_setlatin1(union id3_field *, id3_latin1_t const *);
Chris@0: int id3_field_setfulllatin1(union id3_field *, id3_latin1_t const *);
Chris@0: int id3_field_setstring(union id3_field *, id3_ucs4_t const *);
Chris@0: int id3_field_setfullstring(union id3_field *, id3_ucs4_t const *);
Chris@0: int id3_field_setframeid(union id3_field *, char const *);
Chris@0: int id3_field_setbinarydata(union id3_field *,
Chris@0: 			    id3_byte_t const *, id3_length_t);
Chris@0: 
Chris@0: signed long id3_field_getint(union id3_field const *);
Chris@0: enum id3_field_textencoding id3_field_gettextencoding(union id3_field const *);
Chris@0: id3_latin1_t const *id3_field_getlatin1(union id3_field const *);
Chris@0: id3_latin1_t const *id3_field_getfulllatin1(union id3_field const *);
Chris@0: id3_ucs4_t const *id3_field_getstring(union id3_field const *);
Chris@0: id3_ucs4_t const *id3_field_getfullstring(union id3_field const *);
Chris@0: unsigned int id3_field_getnstrings(union id3_field const *);
Chris@0: id3_ucs4_t const *id3_field_getstrings(union id3_field const *,
Chris@0: 				       unsigned int);
Chris@0: char const *id3_field_getframeid(union id3_field const *);
Chris@0: id3_byte_t const *id3_field_getbinarydata(union id3_field const *,
Chris@0: 					  id3_length_t *);
Chris@0: 
Chris@0: /* genre interface */
Chris@0: 
Chris@0: id3_ucs4_t const *id3_genre_index(unsigned int);
Chris@0: id3_ucs4_t const *id3_genre_name(id3_ucs4_t const *);
Chris@0: int id3_genre_number(id3_ucs4_t const *);
Chris@0: 
Chris@0: /* ucs4 interface */
Chris@0: 
Chris@0: id3_latin1_t *id3_ucs4_latin1duplicate(id3_ucs4_t const *);
Chris@0: id3_utf16_t *id3_ucs4_utf16duplicate(id3_ucs4_t const *);
Chris@0: id3_utf8_t *id3_ucs4_utf8duplicate(id3_ucs4_t const *);
Chris@0: 
Chris@0: void id3_ucs4_putnumber(id3_ucs4_t *, unsigned long);
Chris@0: unsigned long id3_ucs4_getnumber(id3_ucs4_t const *);
Chris@0: 
Chris@0: /* latin1/utf16/utf8 interfaces */
Chris@0: 
Chris@0: id3_ucs4_t *id3_latin1_ucs4duplicate(id3_latin1_t const *);
Chris@0: id3_ucs4_t *id3_utf16_ucs4duplicate(id3_utf16_t const *);
Chris@0: id3_ucs4_t *id3_utf8_ucs4duplicate(id3_utf8_t const *);
Chris@0: 
Chris@0: /* version interface */
Chris@0: 
Chris@0: # define ID3_VERSION_MAJOR	0
Chris@0: # define ID3_VERSION_MINOR	15
Chris@0: # define ID3_VERSION_PATCH	1
Chris@0: # define ID3_VERSION_EXTRA	" (beta)"
Chris@0: 
Chris@0: # define ID3_VERSION_STRINGIZE(str)	#str
Chris@0: # define ID3_VERSION_STRING(num)	ID3_VERSION_STRINGIZE(num)
Chris@0: 
Chris@0: # define ID3_VERSION	ID3_VERSION_STRING(ID3_VERSION_MAJOR) "."  \
Chris@0: 			ID3_VERSION_STRING(ID3_VERSION_MINOR) "."  \
Chris@0: 			ID3_VERSION_STRING(ID3_VERSION_PATCH)  \
Chris@0: 			ID3_VERSION_EXTRA
Chris@0: 
Chris@0: # define ID3_PUBLISHYEAR	"2000-2004"
Chris@0: # define ID3_AUTHOR		"Underbit Technologies, Inc."
Chris@0: # define ID3_EMAIL		"info@underbit.com"
Chris@0: 
Chris@0: extern char const id3_version[];
Chris@0: extern char const id3_copyright[];
Chris@0: extern char const id3_author[];
Chris@0: extern char const id3_build[];
Chris@0: 
Chris@0: # ifdef __cplusplus
Chris@0: }
Chris@0: # endif
Chris@0: 
Chris@0: # endif