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  * Redistribution and use in source and binary forms, with or without
7  * modification, are permitted provided that the following conditions are met:
8  *
9  * 1. Redistributions of source code must retain the above copyright notice,
10  * this list of conditions, and the following disclaimer.
11  *
12  * 2. Redistributions in binary form must reproduce the above copyright notice,
13  * this list of conditions, and the following disclaimer in the documentation
14  * provided with the distribution.
15  *
16  * This software is provided "as is" and without any warranty, express or
17  * implied. In no event shall the authors be liable for any damages arising from
18  * the use of this software.
19  */
20 
26 #ifndef LIBAUDCORE_TUPLE_H
27 #define LIBAUDCORE_TUPLE_H
28 
29 #include <libaudcore/core.h>
30 
34 enum {
57 
65 
66  /* Preserving replay gain information accurately is a challenge since there
67  * are several differents formats around. We use an integer fraction, with
68  * the denominator stored in the *_UNIT fields. For example, if ALBUM_GAIN
69  * is 512 and GAIN_UNIT is 256, then the album gain is +2 dB. If TRACK_PEAK
70  * is 787 and PEAK_UNIT is 1000, then the peak volume is 0.787 in a -1.0 to
71  * 1.0 range. */
78 
80 };
81 
82 typedef enum {
87 
88 int tuple_field_by_name (const char * name);
89 const char * tuple_field_get_name (int field);
91 
92 typedef struct _Tuple Tuple;
93 
94 /* Creates a new, blank tuple with a reference count of one. */
95 Tuple * tuple_new (void);
96 
97 /* Increments the reference count of <tuple> by one. */
98 Tuple * tuple_ref (Tuple * tuple);
99 
100 /* Decrements the reference count of <tuple> by one. If the reference count
101  * drops to zero, releases all memory used by <tuple>. */
102 void tuple_unref (Tuple * tuple);
103 
104 /* Makes a copy of <tuple>. Only use tuple_copy() if you need to modify one
105  * copy of the tuple while not modifying the other. In most cases, tuple_ref()
106  * is more appropriate. */
107 Tuple *tuple_copy(const Tuple *);
108 
109 /* Parses the URI <filename> and sets FIELD_FILE_NAME, FIELD_FILE_PATH,
110  * FIELD_FILE_EXT, and FIELD_SUBSONG_ID accordingly. */
111 void tuple_set_filename(Tuple *tuple, const char *filename);
112 
113 /* Convenience function, equivalent to calling tuple_new() and then
114  * tuple_set_filename(). */
115 Tuple *tuple_new_from_filename(const char *filename);
116 
117 /* Sets a field to the integer value <x>. */
118 void tuple_set_int (Tuple * tuple, int nfield, const char * field, int x);
119 
120 /* Sets the field specified by <nfield> (one of the FIELD_* constants) or
121  * <field> (one of the names returned by tuple_field_get_name() to the string
122  * value <str>. Only one of <nfield> or <field> may be set. If <nfield> is
123  * set, <field> must be NULL; if <field> is set, <nfield> must be -1. As a
124  * special case, if <str> is NULL, the result is equivalent to calling
125  * tuple_unset(). */
126 void tuple_set_str (Tuple * tuple, int nfield, const char * field, const char * str);
127 
128 /* Clears any value that a field is currently set to. */
129 void tuple_unset (Tuple * tuple, int nfield, const char * field);
130 
131 /* Returns the value type of a field, or TUPLE_UNKNOWN if the field has not been
132  * set to any value. */
133 TupleValueType tuple_get_value_type (const Tuple * tuple, int nfield,
134  const char * field);
135 
136 /* Returns the string value of a field. The returned string is pooled and must
137  * be released with str_unref() when no longer needed. If the field has not
138  * been set to any value, returns NULL. */
139 char * tuple_get_str (const Tuple * tuple, int nfield, const char * field);
140 
141 /* Returns the integer value of a field. If the field has not been set to any
142  * value, returns 0. (In hindsight, it would have been better to return -1 in
143  * this case. If you need to distinguish between a value of 0 and a field not
144  * set to any value, use tuple_get_value_type().) */
145 int tuple_get_int (const Tuple * tuple, int nfield, const char * field);
146 
147 /* Fills in format-related fields (specifically FIELD_CODEC, FIELD_QUALITY, and
148  * FIELD_BITRATE). Plugins should use this function instead of setting these
149  * fields individually so that the style is consistent across file formats.
150  * <format> should be a brief description such as "Microsoft WAV", "MPEG-1 layer
151  * 3", "Audio CD", and so on. <samplerate> is in Hertz. <bitrate> is in 1000
152  * bits per second. */
153 void tuple_set_format (Tuple * tuple, const char * format, int channels, int
154  samplerate, int bitrate);
155 
156 /* In addition to the normal fields, tuples contain an integer array of subtune
157  * ID numbers. This function sets that array. It also sets FIELD_SUBSONG_NUM
158  * to the value <n_subtunes>. */
159 void tuple_set_subtunes (Tuple * tuple, int n_subtunes, const int * subtunes);
160 
161 /* Returns the length of the subtune array. If the array has not been set,
162  * returns zero. Note that if FIELD_SUBSONG_NUM is changed after
163  * tuple_set_subtunes() is called, this function returns the value <n_subtunes>
164  * passed to tuple_set_subtunes(), not the value of FIELD_SUBSONG_NUM. */
165 int tuple_get_n_subtunes (Tuple * tuple);
166 
167 /* Returns the <n>th member of the subtune array. */
168 int tuple_get_nth_subtune (Tuple * tuple, int n);
169 
170 /* Generates a formatted title string for <tuple> according to <format>. The
171  * syntax of <format> is documented in tuple_formatter.c. The returned string
172  * is pooled and must be released with str_unref() when no longer need. The
173  * returned string is never NULL, though it may be the empty string. */
174 char * tuple_format_title (Tuple * tuple, const char * format);
175 
176 #endif /* LIBAUDCORE_TUPLE_H */