00001 /* 00002 * tuple.h 00003 * Copyright 2007-2011 William Pitcock, Christian Birchinger, Matti Hämäläinen, 00004 * Giacomo Lozito, Eugene Zagidullin, and John Lindgren 00005 * 00006 * This program is free software; you can redistribute it and/or modify 00007 * it under the terms of the GNU General Public License as published by 00008 * the Free Software Foundation; under version 3 of the License. 00009 * 00010 * This program is distributed in the hope that it will be useful, 00011 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00013 * GNU General Public License for more details. 00014 * 00015 * You should have received a copy of the GNU General Public License 00016 * along with this program. If not, see <http://www.gnu.org/licenses>. 00017 * 00018 * The Audacious team does not consider modular code linking to 00019 * Audacious or using our public API to be a derived work. 00020 */ 00021 00027 #ifndef LIBAUDCORE_TUPLE_H 00028 #define LIBAUDCORE_TUPLE_H 00029 00030 #include <libaudcore/core.h> 00031 00035 enum { 00036 FIELD_ARTIST = 0, 00037 FIELD_TITLE, 00038 FIELD_ALBUM, 00039 FIELD_COMMENT, 00040 FIELD_GENRE, 00042 FIELD_TRACK_NUMBER, 00043 FIELD_LENGTH, 00044 FIELD_YEAR, 00045 FIELD_QUALITY, 00048 FIELD_CODEC, 00049 FIELD_FILE_NAME, 00050 FIELD_FILE_PATH, 00051 FIELD_FILE_EXT, 00053 FIELD_SONG_ARTIST, 00054 FIELD_COMPOSER, 00055 FIELD_PERFORMER, 00056 FIELD_COPYRIGHT, 00057 FIELD_DATE, 00058 00059 FIELD_SUBSONG_ID, 00060 FIELD_SUBSONG_NUM, 00061 FIELD_MIMETYPE, 00062 FIELD_BITRATE, 00064 FIELD_SEGMENT_START, 00065 FIELD_SEGMENT_END, 00066 00067 /* Preserving replay gain information accurately is a challenge since there 00068 * are several differents formats around. We use an integer fraction, with 00069 * the denominator stored in the *_UNIT fields. For example, if ALBUM_GAIN 00070 * is 512 and GAIN_UNIT is 256, then the album gain is +2 dB. If TRACK_PEAK 00071 * is 787 and PEAK_UNIT is 1000, then the peak volume is 0.787 in a -1.0 to 00072 * 1.0 range. */ 00073 FIELD_GAIN_ALBUM_GAIN, 00074 FIELD_GAIN_ALBUM_PEAK, 00075 FIELD_GAIN_TRACK_GAIN, 00076 FIELD_GAIN_TRACK_PEAK, 00077 FIELD_GAIN_GAIN_UNIT, 00078 FIELD_GAIN_PEAK_UNIT, 00079 00080 TUPLE_FIELDS 00081 }; 00082 00083 typedef enum { 00084 TUPLE_STRING, 00085 TUPLE_INT, 00086 TUPLE_UNKNOWN 00087 } TupleValueType; 00088 00089 int tuple_field_by_name (const char * name); 00090 const char * tuple_field_get_name (int field); 00091 TupleValueType tuple_field_get_type (int field); 00092 00093 typedef struct _Tuple Tuple; 00094 00095 /* Creates a new, blank tuple with a reference count of one. */ 00096 Tuple * tuple_new (void); 00097 00098 /* Increments the reference count of <tuple> by one. */ 00099 Tuple * tuple_ref (Tuple * tuple); 00100 00101 /* Decrements the reference count of <tuple> by one. If the reference count 00102 * drops to zero, releases all memory used by <tuple>. */ 00103 void tuple_unref (Tuple * tuple); 00104 00105 /* Makes a copy of <tuple>. Only use tuple_copy() if you need to modify one 00106 * copy of the tuple while not modifying the other. In most cases, tuple_ref() 00107 * is more appropriate. */ 00108 Tuple *tuple_copy(const Tuple *); 00109 00110 /* Parses the URI <filename> and sets FIELD_FILE_NAME, FIELD_FILE_PATH, 00111 * FIELD_FILE_EXT, and FIELD_SUBSONG_ID accordingly. */ 00112 void tuple_set_filename(Tuple *tuple, const char *filename); 00113 00114 /* Convenience function, equivalent to calling tuple_new() and then 00115 * tuple_set_filename(). */ 00116 Tuple *tuple_new_from_filename(const char *filename); 00117 00118 /* Sets a field to the integer value <x>. */ 00119 void tuple_set_int (Tuple * tuple, int nfield, const char * field, int x); 00120 00121 /* Sets the field specified by <nfield> (one of the FIELD_* constants) or 00122 * <field> (one of the names returned by tuple_field_get_name() to the string 00123 * value <str>. Only one of <nfield> or <field> may be set. If <nfield> is 00124 * set, <field> must be NULL; if <field> is set, <nfield> must be -1. As a 00125 * special case, if <str> is NULL, the result is equivalent to calling 00126 * tuple_unset(). */ 00127 void tuple_set_str (Tuple * tuple, int nfield, const char * field, const char * str); 00128 00129 /* Clears any value that a field is currently set to. */ 00130 void tuple_unset (Tuple * tuple, int nfield, const char * field); 00131 00132 /* Returns the value type of a field, or TUPLE_UNKNOWN if the field has not been 00133 * set to any value. */ 00134 TupleValueType tuple_get_value_type (const Tuple * tuple, int nfield, 00135 const char * field); 00136 00137 /* Returns the string value of a field. The returned string is pooled and must 00138 * be released with str_unref() when no longer needed. If the field has not 00139 * been set to any value, returns NULL. */ 00140 char * tuple_get_str (const Tuple * tuple, int nfield, const char * field); 00141 00142 /* Returns the integer value of a field. If the field has not been set to any 00143 * value, returns 0. (In hindsight, it would have been better to return -1 in 00144 * this case. If you need to distinguish between a value of 0 and a field not 00145 * set to any value, use tuple_get_value_type().) */ 00146 int tuple_get_int (const Tuple * tuple, int nfield, const char * field); 00147 00148 /* Fills in format-related fields (specifically FIELD_CODEC, FIELD_QUALITY, and 00149 * FIELD_BITRATE). Plugins should use this function instead of setting these 00150 * fields individually so that the style is consistent across file formats. 00151 * <format> should be a brief description such as "Microsoft WAV", "MPEG-1 layer 00152 * 3", "Audio CD", and so on. <samplerate> is in Hertz. <bitrate> is in 1000 00153 * bits per second. */ 00154 void tuple_set_format (Tuple * tuple, const char * format, int channels, int 00155 samplerate, int bitrate); 00156 00157 /* In addition to the normal fields, tuples contain an integer array of subtune 00158 * ID numbers. This function sets that array. It also sets FIELD_SUBSONG_NUM 00159 * to the value <n_subtunes>. */ 00160 void tuple_set_subtunes (Tuple * tuple, int n_subtunes, const int * subtunes); 00161 00162 /* Returns the length of the subtune array. If the array has not been set, 00163 * returns zero. Note that if FIELD_SUBSONG_NUM is changed after 00164 * tuple_set_subtunes() is called, this function returns the value <n_subtunes> 00165 * passed to tuple_set_subtunes(), not the value of FIELD_SUBSONG_NUM. */ 00166 int tuple_get_n_subtunes (Tuple * tuple); 00167 00168 /* Returns the <n>th member of the subtune array. */ 00169 int tuple_get_nth_subtune (Tuple * tuple, int n); 00170 00171 /* Generates a formatted title string for <tuple> according to <format>. The 00172 * syntax of <format> is documented in tuple_formatter.c. The returned string 00173 * is pooled and must be released with str_unref() when no longer need. The 00174 * returned string is never NULL, though it may be the empty string. */ 00175 char * tuple_format_title (Tuple * tuple, const char * format); 00176 00177 #endif /* LIBAUDCORE_TUPLE_H */