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>. If <tuple> is NULL, does
102  * nothing. */
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 */
static int channels
Definition: equalizer.c:54
Structure for holding and passing around miscellaneous track metadata.
Definition: tuple.c:63
Total number of subsongs in the file.
Definition: tuple.h:59
EXPORT void tuple_set_str(Tuple *tuple, int nfield, const char *field, const char *str)
Definition: tuple.c:396
const char filename
Definition: misc-api.h:85
String representing quality, such as &quot;lossy&quot;, &quot;lossless&quot;, &quot;sequenced&quot;.
Definition: tuple.h:44
int format
Definition: audio.c:132
File name part of the location URI.
Definition: tuple.h:48
Index number of subsong/tune.
Definition: tuple.h:58
EXPORT int tuple_field_by_name(const char *name)
Definition: tuple.c:165
EXPORT void tuple_set_int(Tuple *tuple, int nfield, const char *field, int x)
Definition: tuple.c:381
Composer of song, if different than artist.
Definition: tuple.h:53
Path part of the location URI.
Definition: tuple.h:49
EXPORT void tuple_set_filename(Tuple *tuple, const char *filename)
Sets filename/URI related fields of a #Tuple structure, based on the given filename argument...
Definition: tuple.c:305
TupleValueType
Definition: tuple.h:82
const char * name
Definition: plugin-init.c:38
EXPORT Tuple * tuple_new(void)
Definition: tuple.c:267
EXPORT void tuple_set_subtunes(Tuple *tuple, int n_subtunes, const int *subtunes)
Definition: tuple.c:564
Freeform comment.
Definition: tuple.h:38
int * subtunes
Array of int containing subtune index numbers.
Definition: tuple.c:71
EXPORT void tuple_unref(Tuple *tuple)
Definition: tuple.c:284
EXPORT TupleValueType tuple_field_get_type(int field)
Definition: tuple.c:186
EXPORT const char * tuple_field_get_name(int field)
Definition: tuple.c:178
EXPORT void tuple_unset(Tuple *tuple, int nfield, const char *field)
Definition: tuple.c:425
Song&#39;s genre.
Definition: tuple.h:39
EXPORT Tuple * tuple_copy(const Tuple *old)
Creates a copy of given Tuple structure, with copied data.
Definition: tuple.c:337
EXPORT char * tuple_format_title(Tuple *tuple, const char *format)
Definition: tuple.c:600
EXPORT int tuple_get_nth_subtune(Tuple *tuple, int n)
Definition: tuple.c:588
Codec name or similar.
Definition: tuple.h:47
Filename extension part of the location URI.
Definition: tuple.h:50
EXPORT char * tuple_get_str(const Tuple *tuple, int nfield, const char *field)
Definition: tuple.c:478
EXPORT Tuple * tuple_new_from_filename(const char *filename)
Allocates a new #Tuple structure, setting filename/URI related fields based on the given filename arg...
Definition: tuple.c:373
EXPORT Tuple * tuple_ref(Tuple *tuple)
Definition: tuple.c:274
EXPORT TupleValueType tuple_get_value_type(const Tuple *tuple, int nfield, const char *field)
Returns TupleValueType of given #Tuple field.
Definition: tuple.c:459
Song title.
Definition: tuple.h:36
Bitrate in kbps.
Definition: tuple.h:61
Track length in milliseconds.
Definition: tuple.h:42
EXPORT int tuple_get_n_subtunes(Tuple *tuple)
Definition: tuple.c:578
EXPORT void tuple_set_format(Tuple *t, const char *format, int chans, int rate, int brate)
Definition: tuple.c:531
Album name.
Definition: tuple.h:37
Year of production/performance/etc.
Definition: tuple.h:43
EXPORT int tuple_get_int(const Tuple *tuple, int nfield, const char *field)
Returns integer associated to #Tuple field.
Definition: tuple.c:509