Audacious  $Id:Doxyfile42802007-03-2104:39:00Znenolod$
tuple.h
Go to the documentation of this file.
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 */