Audacious  $Id:Doxyfile42802007-03-2104:39:00Znenolod$
tuple.h
Go to the documentation of this file.
1 /*
2  * tuple.h
3  * Copyright 2007-2011 William Pitcock, Christian Birchinger, Matti Hämäläinen,
4  * Giacomo Lozito, Eugene Zagidullin, and John Lindgren
5  *
6  * This program is free software; you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation; under version 3 of the License.
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, see <http://www.gnu.org/licenses>.
17  *
18  * The Audacious team does not consider modular code linking to
19  * Audacious or using our public API to be a derived work.
20  */
21 
27 #ifndef LIBAUDCORE_TUPLE_H
28 #define LIBAUDCORE_TUPLE_H
29 
30 #include <libaudcore/core.h>
31 
35 enum {
58 
66 
67  /* Preserving replay gain information accurately is a challenge since there
68  * are several differents formats around. We use an integer fraction, with
69  * the denominator stored in the *_UNIT fields. For example, if ALBUM_GAIN
70  * is 512 and GAIN_UNIT is 256, then the album gain is +2 dB. If TRACK_PEAK
71  * is 787 and PEAK_UNIT is 1000, then the peak volume is 0.787 in a -1.0 to
72  * 1.0 range. */
79 
81 };
82 
83 typedef enum {
88 
89 int tuple_field_by_name (const char * name);
90 const char * tuple_field_get_name (int field);
92 
93 typedef struct _Tuple Tuple;
94 
95 /* Creates a new, blank tuple with a reference count of one. */
96 Tuple * tuple_new (void);
97 
98 /* Increments the reference count of <tuple> by one. */
99 Tuple * tuple_ref (Tuple * tuple);
100 
101 /* Decrements the reference count of <tuple> by one. If the reference count
102  * drops to zero, releases all memory used by <tuple>. */
103 void tuple_unref (Tuple * tuple);
104 
105 /* Makes a copy of <tuple>. Only use tuple_copy() if you need to modify one
106  * copy of the tuple while not modifying the other. In most cases, tuple_ref()
107  * is more appropriate. */
108 Tuple *tuple_copy(const Tuple *);
109 
110 /* Parses the URI <filename> and sets FIELD_FILE_NAME, FIELD_FILE_PATH,
111  * FIELD_FILE_EXT, and FIELD_SUBSONG_ID accordingly. */
112 void tuple_set_filename(Tuple *tuple, const char *filename);
113 
114 /* Convenience function, equivalent to calling tuple_new() and then
115  * tuple_set_filename(). */
116 Tuple *tuple_new_from_filename(const char *filename);
117 
118 /* Sets a field to the integer value <x>. */
119 void tuple_set_int (Tuple * tuple, int nfield, const char * field, int x);
120 
121 /* Sets the field specified by <nfield> (one of the FIELD_* constants) or
122  * <field> (one of the names returned by tuple_field_get_name() to the string
123  * value <str>. Only one of <nfield> or <field> may be set. If <nfield> is
124  * set, <field> must be NULL; if <field> is set, <nfield> must be -1. As a
125  * special case, if <str> is NULL, the result is equivalent to calling
126  * tuple_unset(). */
127 void tuple_set_str (Tuple * tuple, int nfield, const char * field, const char * str);
128 
129 /* Clears any value that a field is currently set to. */
130 void tuple_unset (Tuple * tuple, int nfield, const char * field);
131 
132 /* Returns the value type of a field, or TUPLE_UNKNOWN if the field has not been
133  * set to any value. */
134 TupleValueType tuple_get_value_type (const Tuple * tuple, int nfield,
135  const char * field);
136 
137 /* Returns the string value of a field. The returned string is pooled and must
138  * be released with str_unref() when no longer needed. If the field has not
139  * been set to any value, returns NULL. */
140 char * tuple_get_str (const Tuple * tuple, int nfield, const char * field);
141 
142 /* Returns the integer value of a field. If the field has not been set to any
143  * value, returns 0. (In hindsight, it would have been better to return -1 in
144  * this case. If you need to distinguish between a value of 0 and a field not
145  * set to any value, use tuple_get_value_type().) */
146 int tuple_get_int (const Tuple * tuple, int nfield, const char * field);
147 
148 /* Fills in format-related fields (specifically FIELD_CODEC, FIELD_QUALITY, and
149  * FIELD_BITRATE). Plugins should use this function instead of setting these
150  * fields individually so that the style is consistent across file formats.
151  * <format> should be a brief description such as "Microsoft WAV", "MPEG-1 layer
152  * 3", "Audio CD", and so on. <samplerate> is in Hertz. <bitrate> is in 1000
153  * bits per second. */
154 void tuple_set_format (Tuple * tuple, const char * format, int channels, int
155  samplerate, int bitrate);
156 
157 /* In addition to the normal fields, tuples contain an integer array of subtune
158  * ID numbers. This function sets that array. It also sets FIELD_SUBSONG_NUM
159  * to the value <n_subtunes>. */
160 void tuple_set_subtunes (Tuple * tuple, int n_subtunes, const int * subtunes);
161 
162 /* Returns the length of the subtune array. If the array has not been set,
163  * returns zero. Note that if FIELD_SUBSONG_NUM is changed after
164  * tuple_set_subtunes() is called, this function returns the value <n_subtunes>
165  * passed to tuple_set_subtunes(), not the value of FIELD_SUBSONG_NUM. */
166 int tuple_get_n_subtunes (Tuple * tuple);
167 
168 /* Returns the <n>th member of the subtune array. */
169 int tuple_get_nth_subtune (Tuple * tuple, int n);
170 
171 /* Generates a formatted title string for <tuple> according to <format>. The
172  * syntax of <format> is documented in tuple_formatter.c. The returned string
173  * is pooled and must be released with str_unref() when no longer need. The
174  * returned string is never NULL, though it may be the empty string. */
175 char * tuple_format_title (Tuple * tuple, const char * format);
176 
177 #endif /* LIBAUDCORE_TUPLE_H */