Audacious  $Id:Doxyfile42802007-03-2104:39:00Znenolod$
playlist-api.h
Go to the documentation of this file.
1 /*
2  * playlist-api.h
3  * Copyright 2010-2012 John Lindgren
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions are met:
7  *
8  * 1. Redistributions of source code must retain the above copyright notice,
9  * this list of conditions, and the following disclaimer.
10  *
11  * 2. Redistributions in binary form must reproduce the above copyright notice,
12  * this list of conditions, and the following disclaimer in the documentation
13  * provided with the distribution.
14  *
15  * This software is provided "as is" and without any warranty, express or
16  * implied. In no event shall the authors be liable for any damages arising from
17  * the use of this software.
18  */
19 
20 /* Do not include this file directly; use playlist.h instead. */
21 
22 /* Any functions in this API with a return type of (char *) return pooled
23  * strings that must not be modified and must be released with str_unref() when
24  * no longer needed. */
25 
26 /* --- PLAYLIST CORE API --- */
27 
28 /* Returns the number of playlists currently open. There will always be at
29  * least one playlist open. The playlists are numbered starting from zero. */
31 
32 /* Adds a new playlist before the one numbered <at>. If <at> is -1 or equal to
33  * the number of playlists, adds a new playlist after the last one. */
35 
36 /* Moves a contiguous block of <count> playlists starting with the one numbered
37  * <from> such that that playlist ends up at the position <to>. */
38 AUD_VFUNC3 (playlist_reorder, int, from, int, to, int, count)
39 
40 /* Closes a playlist. CAUTION: The playlist is not saved, and no confirmation
41  * is presented to the user. If <playlist> is the only playlist, a new playlist
42  * is added. If <playlist> is the active playlist, another playlist is marked
43  * active. If <playlist> is the currently playing playlist, playback is
44  * stopped. */
46 
47 /* Returns a unique non-negative integer which can be used to identify a given
48  * playlist even if its numbering changes (as when playlists are reordered).
49  * On error, returns -1. */
51 
52 /* Returns the number of the playlist identified by a given integer ID as
53  * returned by playlist_get_unique_id(). If the playlist no longer exists,
54  * returns -1. */
55 AUD_FUNC1 (int, playlist_by_unique_id, int, id)
56 
57 /* Sets the filename associated with a playlist. (Audacious currently makes no
58  * use of the filename.) */
60 
61 /* Returns the filename associated with a playlist. */
62 AUD_FUNC1 (char *, playlist_get_filename, int, playlist)
63 
64 /* Sets the title associated with a playlist. */
65 AUD_VFUNC2 (playlist_set_title, int, playlist, const char *, title)
66 
67 /* Returns the title associated with a playlist. */
68 AUD_FUNC1 (char *, playlist_get_title, int, playlist)
69 
70 /* Sets the active playlist. This is the playlist that user interfaces will
71  * show to the user. */
72 AUD_VFUNC1 (playlist_set_active, int, playlist)
73 
74 /* Returns the number of the active playlist. */
76 
77 /* Sets the currently playing playlist. Starts playback, resuming from the
78  * position last played if possible. If <playlist> is -1 or if the requested
79  * playlist is empty, stops playback. */
80 AUD_VFUNC1 (playlist_set_playing, int, playlist)
81 
82 /* Returns the number of the currently playing playlist. If no playlist is
83  * playing, returns -1. */
85 
86 /* Returns the number of a "blank" playlist. The active playlist is returned if
87  * it has the default title and has no entries; otherwise, a new playlist is
88  * added and returned. */
90 
91 /* Returns the number of the "temporary" playlist (which is no different from
92  * any other playlist except in name). If the playlist does not exist, a
93  * "blank" playlist is obtained from playlist_get_blank() and is renamed to
94  * become the temporary playlist. */
96 
97 /* Returns the number of entries in a playlist. The entries are numbered
98  * starting from zero. */
99 AUD_FUNC1 (int, playlist_entry_count, int, playlist)
100 
101 /* Adds a song file, playlist file, or folder to a playlist before the entry
102  * numbered <at>. If <at> is negative or equal to the number of entries, the
103  * item is added after the last entry. <tuple> may be NULL, in which case
104  * Audacious will attempt to read metadata from the song file. The caller gives
105  * up one reference count to <tuple>. If <play> is nonzero, Audacious will
106  * begin playback of the items once they have been added.
107  *
108  * Because adding items to the playlist can be a slow process, this function may
109  * return before the process is complete. Hence, the caller must not assume
110  * that there will be new entries in the playlist immediately. */
111 AUD_VFUNC5 (playlist_entry_insert, int, playlist, int, at, const char *,
112  filename, Tuple *, tuple, bool_t, play)
113 
114 /* Similar to playlist_entry_insert, adds multiple song files, playlist files,
115  * or folders to a playlist. The filenames, stored as (char *) in an index
116  * (see libaudcore/index.h), must be pooled with str_get(); the caller gives up
117  * one reference count to each filename. Tuples are likewise stored as
118  * (Tuple *) in an index of the same length; the caller gives up one reference
119  * count to each tuple. <tuples> may be NULL, or individual pointers within it
120  * may be NULL. Finally, the caller also gives up ownership of the indexes
121  * themselves and should not access them after the call. */
122 AUD_VFUNC5 (playlist_entry_insert_batch, int, playlist, int, at,
123  Index *, filenames, Index *, tuples, bool_t, play)
124 
125 /* Similar to playlist_entry_insert_batch, but allows the caller to prevent some
126  * items from being added by returning false from the <filter> callback. Useful
127  * for searching a folder and adding only new files to the playlist. <user> is
128  * an untyped pointer passed to the <filter> callback. */
129 AUD_VFUNC7 (playlist_entry_insert_filtered, int, playlist, int, at,
130  Index *, filenames, Index *, tuples, PlaylistFilterFunc, filter,
131  void *, user, bool_t, play)
132 
133 /* Removes a contiguous block of <number> entries starting from the one numbered
134  * <at> from a playlist. If necessary, the playback position is moved elsewhere
135  * in the playlist and playback is restarted (or stopped). */
136 AUD_VFUNC3 (playlist_entry_delete, int, playlist, int, at, int, number)
137 
138 /* Returns the filename of an entry. */
139 AUD_FUNC2 (char *, playlist_entry_get_filename, int, playlist, int, entry)
140 
141 /* Returns a handle to the decoder plugin associated with an entry, or NULL if
142  * none can be found. If <fast> is nonzero, returns NULL if no decoder plugin
143  * has yet been found. */
145  entry, bool_t, fast)
146 
147 /* Returns the tuple associated with an entry, or NULL if one is not available.
148  * The reference count of the tuple is incremented. If <fast> is nonzero,
149  * returns NULL if metadata for the entry has not yet been read from the song
150  * file. */
151 AUD_FUNC3 (Tuple *, playlist_entry_get_tuple, int, playlist, int, entry,
152  bool_t, fast)
153 
154 /* Returns a formatted title string for an entry. This may include information
155  * such as the filename, song title, and/or artist. If <fast> is nonzero,
156  * returns a "best guess" based on the entry's filename if metadata for the
157  * entry has not yet been read. */
158 AUD_FUNC3 (char *, playlist_entry_get_title, int, playlist, int, entry,
159  bool_t, fast)
160 
161 /* Returns three strings (title, artist, and album) describing an entry. The
162  * strings are pooled, and the usual cautions apply. If <fast> is nonzero,
163  * returns a "best guess" based on the entry's filename if metadata for the
164  * entry has not yet been read. The caller may pass NULL for any values that
165  * are not needed; NULL may also be returned for any values that are not
166  * available. */
167 AUD_VFUNC6 (playlist_entry_describe, int, playlist, int, entry,
168  char * *, title, char * *, artist, char * *, album, bool_t, fast)
169 
170 /* Returns the length in milliseconds of an entry, or -1 if the length is not
171  * known. <fast> is as in playlist_entry_get_tuple(). */
172 AUD_FUNC3 (int, playlist_entry_get_length, int, playlist, int, entry,
173  bool_t, fast)
174 
175 /* Moves the playback position to the beginning of the entry at <position>. If
176  * <position> is -1, unsets the playback position. If <playlist> is the
177  * currently playing playlist, playback is restarted (or stopped). */
178 AUD_VFUNC2 (playlist_set_position, int, playlist, int, position)
179 
180 /* Returns the playback position, or -1 if it is not set. Note that the
181  * position may be set even if <playlist> is not currently playing. */
182 AUD_FUNC1 (int, playlist_get_position, int, playlist)
183 
184 /* Sets whether an entry is selected. */
185 AUD_VFUNC3 (playlist_entry_set_selected, int, playlist, int, entry,
186  bool_t, selected)
187 
188 /* Returns whether an entry is selected. */
189 AUD_FUNC2 (bool_t, playlist_entry_get_selected, int, playlist, int, entry)
190 
191 /* Returns the number of selected entries in a playlist. */
192 AUD_FUNC1 (int, playlist_selected_count, int, playlist)
193 
194 /* Selects all (or none) of the entries in a playlist. */
195 AUD_VFUNC2 (playlist_select_all, int, playlist, bool_t, selected)
196 
197 /* Moves a selected entry within a playlist by an offset of <distance> entries.
198  * Other selected entries are gathered around it. Returns the offset by which
199  * the entry was actually moved, which may be less in absolute value than the
200  * requested offset. */
201 AUD_FUNC3 (int, playlist_shift, int, playlist, int, position, int, distance)
202 
203 /* Removes the selected entries from a playlist. If necessary, the playback
204  * position is moved elsewhere in the playlist and playback is restarted (or
205  * stopped). */
206 AUD_VFUNC1 (playlist_delete_selected, int, playlist)
207 
208 /* Sorts the entries in a playlist based on filename. The callback function
209  * should return negative if the first filename comes before the second,
210  * positive if it comes after, or zero if the two are indistinguishable. */
212  PlaylistStringCompareFunc, compare)
213 
214 /* Sorts the entries in a playlist based on tuple. May fail if metadata
215  * scanning is still in progress (or has been disabled). */
216 AUD_VFUNC2 (playlist_sort_by_tuple, int, playlist,
217  PlaylistTupleCompareFunc, compare)
218 
219 /* Sorts the entries in a playlist based on formatted title string. May fail if
220  * metadata scanning is still in progress (or has been disabled). */
221 AUD_VFUNC2 (playlist_sort_by_title, int, playlist,
222  PlaylistStringCompareFunc, compare)
223 
224 /* Sorts only the selected entries in a playlist based on filename. */
226  PlaylistStringCompareFunc, compare)
227 
228 /* Sorts only the selected entries in a playlist based on tuple. May fail if
229  * metadata scanning is still in progress (or has been disabled). */
231  PlaylistTupleCompareFunc, compare)
232 
233 /* Sorts only the selected entries in a playlist based on formatted title
234  * string. May fail if metadata scanning is still in progress (or has been
235  * disabled). */
237  PlaylistStringCompareFunc, compare)
238 
239 /* Reverses the order of the entries in a playlist. */
240 AUD_VFUNC1 (playlist_reverse, int, playlist)
241 
242 /* Reorders the entries in a playlist randomly. */
243 AUD_VFUNC1 (playlist_randomize, int, playlist)
244 
245 /* Discards the metadata stored for all the entries in a playlist and starts
246  * reading it afresh from the song files in the background. */
247 AUD_VFUNC1 (playlist_rescan, int, playlist)
248 
249 /* Like playlist_rescan, but applies only to the selected entries in a playlist. */
250 AUD_VFUNC1 (playlist_rescan_selected, int, playlist)
251 
252 /* Discards the metadata stored for all the entries that refer to a particular
253  * song file, in whatever playlist they appear, and starts reading it afresh
254  * from that file in the background. */
255 AUD_VFUNC1 (playlist_rescan_file, const char *, filename)
256 
257 /* Calculates the total length in milliseconds of all the entries in a playlist.
258  * Only takes into account entries for which metadata has already been read. */
259 AUD_FUNC1 (int64_t, playlist_get_total_length, int, playlist)
260 
261 /* Calculates the total length in milliseconds of only the selected entries in a
262  * playlist. Only takes into account entries for which metadata has already
263  * been read. */
264 AUD_FUNC1 (int64_t, playlist_get_selected_length, int, playlist)
265 
266 /* Returns the number of entries in a playlist queue. The entries are numbered
267  * starting from zero, lower numbers being played first. */
268 AUD_FUNC1 (int, playlist_queue_count, int, playlist)
269 
270 /* Adds an entry to a playlist's queue before the entry numbered <at> in the
271  * queue. If <at> is negative or equal to the number of entries in the queue,
272  * adds the entry after the last one in the queue. The same entry cannot be
273  * added to the queue more than once. */
274 AUD_VFUNC3 (playlist_queue_insert, int, playlist, int, at, int, entry)
275 
276 /* Adds the selected entries in a playlist to the queue, if they are not already
277  * in it. */
278 AUD_VFUNC2 (playlist_queue_insert_selected, int, playlist, int, at)
279 
280 /* Returns the position in the playlist of the entry at a given position in the
281  * queue. */
282 AUD_FUNC2 (int, playlist_queue_get_entry, int, playlist, int, at)
283 
284 /* Returns the position in the queue of the entry at a given position in the
285  * playlist. If it is not in the queue, returns -1. */
286 AUD_FUNC2 (int, playlist_queue_find_entry, int, playlist, int, entry)
287 
288 /* Removes a contiguous block of <number> entries starting with the one numbered
289  * <at> from the queue. */
290 AUD_VFUNC3 (playlist_queue_delete, int, playlist, int, at, int, number)
291 
292 /* Removes the selected entries in a playlist from the queue, if they are in it. */
294 
295 /* Returns nonzero if a "playlist update" hook call is pending. If called from
296  * within the hook, the current hook call is not considered pending. */
298 
299 /* May be called within the "playlist update" hook to determine the update level
300  * and number of entries changed in a playlist. Returns the update level for
301  * the playlist, storing the number of the first entry changed in <at> and the
302  * number of contiguous entries to be updated in <count>. Note that entries may
303  * have been added or removed within this range. If no entries in the playlist
304  * have changed, returns zero. */
305 AUD_FUNC3 (int, playlist_updated_range, int, playlist, int *, at, int *, count)
306 
307 /* Returns nonzero if entries are being added to a playlist in the background.
308  * If <playlist> is -1, checks all playlists. */
309 AUD_FUNC1 (bool_t, playlist_add_in_progress, int, playlist)
310 
311 /* Returns nonzero if entries in a playlist are being scanned for metadata in
312  * the background. If <playlist> is -1, checks all playlists. */
313 AUD_FUNC1 (bool_t, playlist_scan_in_progress, int, playlist)
314 
315 /* --- PLAYLIST UTILITY API --- */
316 
317 /* Sorts the entries in a playlist according to one of the schemes listed in
318  * playlist.h. */
319 AUD_VFUNC2 (playlist_sort_by_scheme, int, playlist, int, scheme)
320 
321 /* Sorts only the selected entries in a playlist according to one of those
322  * schemes. */
323 AUD_VFUNC2 (playlist_sort_selected_by_scheme, int, playlist, int, scheme)
324 
325 /* Removes duplicate entries in a playlist according to one of those schemes.
326  * As currently implemented, first sorts the playlist. */
328  scheme)
329 
330 /* Removes all entries referring to unavailable files in a playlist. ("Remove
331  * failed" is something of a misnomer for the current behavior.) As currently
332  * implemented, only works for file:// URIs. */
333 AUD_VFUNC1 (playlist_remove_failed, int, playlist)
334 
335 /* Selects all the entries in a playlist that match regular expressions stored
336  * in the fields of a tuple. Does not free the memory used by the tuple.
337  * Example: To select all the songs whose title starts with the letter "A",
338  * create a blank tuple and set its title field to "^A". */
339 AUD_VFUNC2 (playlist_select_by_patterns, int, playlist, const Tuple *,
340  patterns)
341 
342 /* Returns nonzero if <filename> refers to a playlist file. */
343 AUD_FUNC1 (bool_t, filename_is_playlist, const char *, filename)
344 
345 /* Saves the entries in a playlist to a playlist file. The format of the file
346  * is determined from the file extension. Returns nonzero on success. */
347 AUD_FUNC2 (bool_t, playlist_save, int, playlist, const char *, filename)
348 
349 /* added in Audacious 3.4 */
350 
351 /* Reverses the order of the selected entries in a playlist. */
352 AUD_VFUNC1 (playlist_reverse_selected, int, playlist)
353 
354 /* Reorders the selected entries in a playlist randomly. */
356 
357 /* Sets the entry which has keyboard focus (-1 means no entry). */
358 AUD_VFUNC2 (playlist_set_focus, int, playlist_num, int, entry_num)
359 
360 /* Gets the entry which has keyboard focus (-1 means no entry). */
361 AUD_FUNC1 (int, playlist_get_focus, int, playlist_num)
bool_t(* PlaylistFilterFunc)(const char *filename, void *user)
Definition: playlist.h:61
FromFunc from
Definition: audio.c:133
int playlist_get_playing(void)
Definition: playlist-new.c:921
void playlist_select_by_patterns(int playlist, const Tuple *patterns)
void playlist_entry_insert(int playlist, int at, const char *filename, Tuple *tuple, bool_t play)
Definition: adder.c:516
int playlist_get_unique_id(int playlist_num)
Definition: playlist-new.c:774
Index Index play fast playlist_entry_get_title
Definition: playlist-api.h:158
void playlist_reverse(int playlist_num)
void playlist_sort_by_scheme(int playlist, int scheme)
void playlist_sort_selected_by_filename(int playlist_num, int(*compare)(const char *a, const char *b))
int playlist_by_unique_id(int id)
Definition: playlist-new.c:781
int playlist_queue_find_entry(int playlist_num, int entry_num)
void playlist_queue_insert(int playlist_num, int at, int entry_num)
int playlist_get_active(void)
Definition: playlist-new.c:861
Index Index play fast fast fast PlaylistStringCompareFunc
Definition: playlist-api.h:211
const char filename
Definition: misc-api.h:85
Index filenames
Definition: playlist-api.h:122
AUD_VFUNC5(playlist_entry_insert, int, playlist, int, at, const char *, filename, Tuple *, tuple, bool_t, play) AUD_VFUNC5(playlist_entry_insert_batch
playlist
Definition: playlist-api.h:122
int playlist_selected_count(int playlist_num)
Index Index play AUD_VFUNC7(playlist_entry_insert_filtered, int, playlist, int, at, Index *, filenames, Index *, tuples, PlaylistFilterFunc, filter, void *, user, bool_t, play) AUD_FUNC3(PluginHandle *
void playlist_sort_selected_by_title(int playlist_num, int(*compare)(const char *a, const char *b))
int playlist_get_temporary(void)
Definition: playlist-new.c:943
void playlist_rescan(int playlist_num)
bool_t playlist_entry_get_selected(int playlist_num, int entry_num)
bool_t play
Definition: main.c:58
int playlist_entry_count(int playlist_num)
Definition: playlist-new.c:986
bool_t playlist_add_in_progress(int playlist)
Definition: adder.c:548
void playlist_entry_set_selected(int playlist_num, int entry_num, bool_t selected)
void playlist_remove_failed(int playlist)
void playlist_queue_insert_selected(int playlist_num, int at)
void playlist_sort_by_title(int playlist_num, int(*compare)(const char *a, const char *b))
Index Index bool_t
Definition: playlist-api.h:122
Index Index play fast fast fast compare AUD_VFUNC2(playlist_sort_by_tuple, int, playlist, PlaylistTupleCompareFunc, compare) AUD_VFUNC2(playlist_sort_by_title
int playlist_queue_get_entry(int playlist_num, int at)
void playlist_queue_delete(int playlist_num, int at, int number)
Index Index play fast fast fast AUD_VFUNC3(playlist_entry_set_selected, int, playlist, int, entry, bool_t, selected) AUD_VFUNC2(playlist_sort_by_filename
void playlist_set_focus(int playlist_num, int entry_num)
void playlist_entry_insert_filtered(int playlist, int at, Index *filenames, Index *tuples, PlaylistFilterFunc filter, void *user, bool_t play)
Definition: adder.c:533
void playlist_rescan_file(const char *filename)
void playlist_entry_describe(int playlist_num, int entry_num, char **title, char **artist, char **album, bool_t fast)
void playlist_reorder(int from, int to, int count)
Definition: playlist-new.c:714
void playlist_delete(int playlist_num)
Definition: playlist-new.c:748
#define AUD_VFUNC1(n, t1, n1)
bool_t filename_is_playlist(const char *filename)
int playlist_shift(int playlist_num, int entry_num, int distance)
#define AUD_FUNC0(t, n)
Tuple * playlist_entry_get_tuple(int playlist_num, int entry_num, bool_t fast)
char * playlist_get_title(int playlist_num)
Definition: playlist-new.c:822
int playlist_count(void)
Definition: playlist-new.c:688
int playlist_updated_range(int playlist_num, int *at, int *count)
Definition: playlist-new.c:400
void playlist_select_all(int playlist_num, bool_t selected)
void playlist_set_filename(int playlist_num, const char *filename)
Definition: playlist-new.c:791
void playlist_set_active(int playlist_num)
Definition: playlist-new.c:843
AUD_FUNC2(PluginHandle *, file_find_decoder, const char *, filename, bool_t, fast) AUD_FUNC2(Tuple *
ToFunc to
Definition: audio.c:134
Index Index play fast fast playlist_entry_get_length
Definition: playlist-api.h:172
int64_t playlist_get_selected_length(int playlist_num)
char * playlist_entry_get_filename(int playlist_num, int entry_num)
int playlist_get_blank(void)
Definition: playlist-new.c:928
bool_t playlist_update_pending(void)
Definition: playlist-new.c:393
at
Definition: playlist-api.h:122
void playlist_entry_delete(int playlist_num, int at, int number)
void playlist_sort_selected_by_scheme(int playlist, int scheme)
void playlist_sort_by_tuple(int playlist_num, int(*compare)(const Tuple *a, const Tuple *b))
Index Index play fast fast fast compare compare PlaylistTupleCompareFunc
Definition: playlist-api.h:230
void playlist_entry_insert_batch(int playlist, int at, Index *filenames, Index *tuples, bool_t play)
Definition: adder.c:527
void playlist_set_position(int playlist_num, int entry_num)
bool_t playlist_scan_in_progress(int playlist_num)
Definition: playlist-new.c:413
Index Index play fast AUD_FUNC3(Tuple *, playlist_entry_get_tuple, int, playlist, int, entry, bool_t, fast) AUD_FUNC3(char *
void playlist_rescan_selected(int playlist_num)
void playlist_set_title(int playlist_num, const char *title)
Definition: playlist-new.c:810
void playlist_reverse_selected(int playlist_num)
Index Index tuples
Definition: playlist-api.h:122
void playlist_randomize_selected(int playlist_num)
#define AUD_FUNC1(t, n, t1, n1)
Index Index play playlist_entry_get_decoder
Definition: playlist-api.h:144
int playlist_queue_count(int playlist_num)
void playlist_remove_duplicates_by_scheme(int playlist, int scheme)
int playlist_get_focus(int playlist_num)
char * playlist_get_filename(int playlist_num)
Definition: playlist-new.c:803
Index Index play fast fast AUD_VFUNC6(playlist_entry_describe, int, playlist, int, entry, char **, title, char **, artist, char **, album, bool_t, fast) AUD_FUNC3(int
int playlist_get_position(int playlist_num)
void playlist_set_playing(int playlist_num)
Definition: playlist-new.c:868
void playlist_delete_selected(int playlist_num)
void playlist_insert(int at)
Definition: playlist-new.c:709
void playlist_randomize(int playlist_num)
void playlist_sort_selected_by_tuple(int playlist_num, int(*compare)(const Tuple *a, const Tuple *b))
bool_t playlist_save(int list, const char *filename)
int64_t playlist_get_total_length(int playlist_num)
void playlist_sort_by_filename(int playlist_num, int(*compare)(const char *a, const char *b))
void playlist_queue_delete_selected(int playlist_num)
Index Index play entry
Definition: playlist-api.h:144