Audacious
$Id:Doxyfile42802007-03-2104:39:00Znenolod$
Main Page
Related Pages
Classes
Files
File List
File Members
src
libaudcore
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
{
35
FIELD_ARTIST
= 0,
36
FIELD_TITLE
,
37
FIELD_ALBUM
,
38
FIELD_COMMENT
,
39
FIELD_GENRE
,
41
FIELD_TRACK_NUMBER
,
42
FIELD_LENGTH
,
43
FIELD_YEAR
,
44
FIELD_QUALITY
,
47
FIELD_CODEC
,
48
FIELD_FILE_NAME
,
49
FIELD_FILE_PATH
,
50
FIELD_FILE_EXT
,
52
FIELD_SONG_ARTIST
,
53
FIELD_COMPOSER
,
54
FIELD_PERFORMER
,
55
FIELD_COPYRIGHT
,
56
FIELD_DATE
,
57
58
FIELD_SUBSONG_ID
,
59
FIELD_SUBSONG_NUM
,
60
FIELD_MIMETYPE
,
61
FIELD_BITRATE
,
63
FIELD_SEGMENT_START
,
64
FIELD_SEGMENT_END
,
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. */
72
FIELD_GAIN_ALBUM_GAIN
,
73
FIELD_GAIN_ALBUM_PEAK
,
74
FIELD_GAIN_TRACK_GAIN
,
75
FIELD_GAIN_TRACK_PEAK
,
76
FIELD_GAIN_GAIN_UNIT
,
77
FIELD_GAIN_PEAK_UNIT
,
78
79
TUPLE_FIELDS
80
};
81
82
typedef
enum
{
83
TUPLE_STRING
,
84
TUPLE_INT
,
85
TUPLE_UNKNOWN
86
}
TupleValueType
;
87
88
int
tuple_field_by_name
(
const
char
*
name
);
89
const
char
*
tuple_field_get_name
(
int
field);
90
TupleValueType
tuple_field_get_type
(
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 */
Generated by
1.8.3.1