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-2011 John Lindgren
4  *
5  * This file is part of Audacious.
6  *
7  * Audacious is free software: you can redistribute it and/or modify it under
8  * the terms of the GNU General Public License as published by the Free Software
9  * Foundation, version 2 or version 3 of the License.
10  *
11  * Audacious is distributed in the hope that it will be useful, but WITHOUT ANY
12  * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
13  * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
14  *
15  * You should have received a copy of the GNU General Public License along with
16  * Audacious. If not, see <http://www.gnu.org/licenses/>.
17  *
18  * The Audacious team does not consider modular code linking to Audacious or
19  * using our public API to be a derived work.
20  */
21 
22 /* Do not include this file directly; use playlist.h instead. */
23 
24 /* Any functions in this API with a return type of (char *) return pooled
25  * strings that must not be modified and must be released with str_unref() when
26  * no longer needed. */
27 
28 /* --- PLAYLIST CORE API --- */
29 
30 /* Returns the number of playlists currently open. There will always be at
31  * least one playlist open. The playlists are numbered starting from zero. */
33 
34 /* Adds a new playlist before the one numbered <at>. If <at> is negative or
35  * equal to the number of playlists, adds a new playlist after the last one. */
37 
38 /* Moves a contiguous block of <count> playlists starting with the one numbered
39  * <from> such that that playlist ends up at the position <to>. */
40 AUD_VFUNC3 (playlist_reorder, int, from, int, to, int, count)
41 
42 /* Closes a playlist. CAUTION: The playlist is not saved, and no confirmation
43  * is presented to the user. If <playlist> is the only playlist, a new playlist
44  * is added. If <playlist> is the active playlist, another playlist is marked
45  * active. If <playlist> is the one from which the last song played was taken,
46  * playback is stopped. In this case, calls to playlist_get_playing() will
47  * return -1, and the behavior of drct_play() is unspecified. */
49 
50 /* Returns a unique non-negative integer which can be used to identify a given
51  * playlist even if its numbering changes (as when playlists are reordered).
52  * On error, returns -1. */
54 
55 /* Returns the number of the playlist identified by a given integer ID as
56  * returned by playlist_get_unique_id(). If the playlist no longer exists,
57  * returns -1. */
58 AUD_FUNC1 (int, playlist_by_unique_id, int, id)
59 
60 /* Sets the filename associated with a playlist. (Audacious currently makes no
61  * use of the filename.) */
63 
64 /* Returns the filename associated with a playlist. */
65 AUD_FUNC1 (char *, playlist_get_filename, int, playlist)
66 
67 /* Sets the title associated with a playlist. */
68 AUD_VFUNC2 (playlist_set_title, int, playlist, const char *, title)
69 
70 /* Returns the title associated with a playlist. */
71 AUD_FUNC1 (char *, playlist_get_title, int, playlist)
72 
73 /* Marks a playlist as active. This is the playlist which the user will see and
74  * on which most DRCT functions will take effect. */
75 AUD_VFUNC1 (playlist_set_active, int, playlist)
76 
77 /* Returns the number of the playlist marked active. */
79 
80 /* Sets the playlist in which playback will begin when drct_play() is called.
81  * This does not mark the playlist as active. If a song is already playing, it
82  * will be stopped. If <playlist> is negative, calls to playlist_get_playing()
83  * will return -1, and the behavior of drct_play() is unspecified. */
84 AUD_VFUNC1 (playlist_set_playing, int, playlist)
85 
86 /* Returns the number of the playlist from which the last song played was taken,
87  * or -1 if that cannot be determined. Note that this playlist may not be
88  * marked active. */
90 
91 /* Returns the number of a "blank" playlist. The active playlist is returned if
92  * it has the default title and has no entries; otherwise, a new playlist is
93  * added and returned. */
95 
96 /* Returns the number of the "temporary" playlist (which is no different from
97  * any other playlist except in name). If the playlist does not exist, a
98  * "blank" playlist is obtained from playlist_get_blank() and is renamed to
99  * become the temporary playlist. */
101 
102 /* Returns the number of entries in a playlist. The entries are numbered
103  * starting from zero. */
104 AUD_FUNC1 (int, playlist_entry_count, int, playlist)
105 
106 /* Adds a song file, playlist file, or folder to a playlist before the entry
107  * numbered <at>. If <at> is negative or equal to the number of entries, the
108  * item is added after the last entry. <tuple> may be NULL, in which case
109  * Audacious will attempt to read metadata from the song file. The caller gives
110  * up one reference count to <tuple>. If <play> is nonzero, Audacious will
111  * begin playback of the items once they have been added.
112  *
113  * Because adding items to the playlist can be a slow process, this function may
114  * return before the process is complete. Hence, the caller must not assume
115  * that there will be new entries in the playlist immediately. */
116 AUD_VFUNC5 (playlist_entry_insert, int, playlist, int, at, const char *,
117  filename, Tuple *, tuple, bool_t, play)
118 
119 /* Similar to playlist_entry_insert, adds multiple song files, playlist files,
120  * or folders to a playlist. The filenames, stored as (char *) in an index
121  * (see libaudcore/index.h), must be pooled with str_get(); the caller gives up
122  * one reference count to each filename. Tuples are likewise stored as
123  * (Tuple *) in an index of the same length; the caller gives up one reference
124  * count to each tuple. <tuples> may be NULL, or individual pointers within it
125  * may be NULL. Finally, the caller also gives up ownership of the indexes
126  * themselves and should not access them after the call. */
127 AUD_VFUNC5 (playlist_entry_insert_batch, int, playlist, int, at,
128  Index *, filenames, Index *, tuples, bool_t, play)
129 
130 /* Similar to playlist_entry_insert_batch, but allows the caller to prevent some
131  * items from being added by returning false from the <filter> callback. Useful
132  * for searching a folder and adding only new files to the playlist. <user> is
133  * an untyped pointer passed to the <filter> callback. */
134 AUD_VFUNC7 (playlist_entry_insert_filtered, int, playlist, int, at,
135  Index *, filenames, Index *, tuples, PlaylistFilterFunc, filter,
136  void *, user, bool_t, play)
137 
138 /* Removes a contiguous block of <number> entries starting from the one numbered
139  * <at> from a playlist. If the last song played is in this block, playback is
140  * stopped. In this case, calls to playlist_get_position() will return -1, and
141  * the behavior of drct_play() is unspecified. */
142 AUD_VFUNC3 (playlist_entry_delete, int, playlist, int, at, int, number)
143 
144 /* Returns the filename of an entry. */
145 AUD_FUNC2 (char *, playlist_entry_get_filename, int, playlist, int, entry)
146 
147 /* Returns a handle to the decoder plugin associated with an entry, or NULL if
148  * none can be found. If <fast> is nonzero, returns NULL if no decoder plugin
149  * has yet been found. */
151  entry, bool_t, fast)
152 
153 /* Returns the tuple associated with an entry, or NULL if one is not available.
154  * The reference count of the tuple is incremented. If <fast> is nonzero,
155  * returns NULL if metadata for the entry has not yet been read from the song
156  * file. */
157 AUD_FUNC3 (Tuple *, playlist_entry_get_tuple, int, playlist, int, entry,
158  bool_t, fast)
159 
160 /* Returns a formatted title string for an entry. This may include information
161  * such as the filename, song title, and/or artist. If <fast> is nonzero,
162  * returns a "best guess" based on the entry's filename if metadata for the
163  * entry has not yet been read. */
164 AUD_FUNC3 (char *, playlist_entry_get_title, int, playlist, int, entry,
165  bool_t, fast)
166 
167 /* Returns three strings (title, artist, and album) describing an entry. The
168  * strings are pooled, and the usual cautions apply. If <fast> is nonzero,
169  * returns a "best guess" based on the entry's filename if metadata for the
170  * entry has not yet been read. May return NULL for any and all values. */
171 AUD_VFUNC6 (playlist_entry_describe, int, playlist, int, entry,
172  char * *, title, char * *, artist, char * *, album, bool_t, fast)
173 
174 /* Returns the length in milliseconds of an entry, or -1 if the length is not
175  * known. <fast> is as in playlist_entry_get_tuple(). */
176 AUD_FUNC3 (int, playlist_entry_get_length, int, playlist, int, entry,
177  bool_t, fast)
178 
179 /* Sets the entry which will be played (if this playlist is selected with
180  * playlist_set_playing()) when drct_play() is called. If a song from this
181  * playlist is already playing, it will be stopped. If <position> is negative,
182  * calls to playlist_get_position() will return -1, and the behavior of
183  * drct_play() is unspecified. */
184 AUD_VFUNC2 (playlist_set_position, int, playlist, int, position)
185 
186 /* Returns the number of the entry which was last played from this playlist, or
187  * -1 if that cannot be determined. */
188 AUD_FUNC1 (int, playlist_get_position, int, playlist)
189 
190 /* Sets whether an entry is selected. */
191 AUD_VFUNC3 (playlist_entry_set_selected, int, playlist, int, entry,
192  bool_t, selected)
193 
194 /* Returns whether an entry is selected. */
195 AUD_FUNC2 (bool_t, playlist_entry_get_selected, int, playlist, int, entry)
196 
197 /* Returns the number of selected entries in a playlist. */
198 AUD_FUNC1 (int, playlist_selected_count, int, playlist)
199 
200 /* Selects all (or none) of the entries in a playlist. */
201 AUD_VFUNC2 (playlist_select_all, int, playlist, bool_t, selected)
202 
203 /* Moves a selected entry within a playlist by an offset of <distance> entries.
204  * Other selected entries are gathered around it. Returns the offset by which
205  * the entry was actually moved, which may be less in absolute value than the
206  * requested offset. */
207 AUD_FUNC3 (int, playlist_shift, int, playlist, int, position, int, distance)
208 
209 /* Removes the selected entries from a playlist. If the last song played is one
210  * of these entries, playback is stopped. In this case, calls to
211  * playlist_get_position() will return -1, and the behavior of drct_play() is
212  * unspecified. */
213 AUD_VFUNC1 (playlist_delete_selected, int, playlist)
214 
215 /* Sorts the entries in a playlist based on filename. The callback function
216  * should return negative if the first filename comes before the second,
217  * positive if it comes after, or zero if the two are indistinguishable. */
219  PlaylistStringCompareFunc, compare)
220 
221 /* Sorts the entries in a playlist based on tuple. May fail if metadata
222  * scanning is still in progress (or has been disabled). */
223 AUD_VFUNC2 (playlist_sort_by_tuple, int, playlist,
224  PlaylistTupleCompareFunc, compare)
225 
226 /* Sorts the entries in a playlist based on formatted title string. May fail if
227  * metadata scanning is still in progress (or has been disabled). */
228 AUD_VFUNC2 (playlist_sort_by_title, int, playlist,
229  PlaylistStringCompareFunc, compare)
230 
231 /* Sorts only the selected entries in a playlist based on filename. */
233  PlaylistStringCompareFunc, compare)
234 
235 /* Sorts only the selected entries in a playlist based on tuple. May fail if
236  * metadata scanning is still in progress (or has been disabled). */
238  PlaylistTupleCompareFunc, compare)
239 
240 /* Sorts only the selected entries in a playlist based on formatted title
241  * string. May fail if metadata scanning is still in progress (or has been
242  * disabled). */
244  PlaylistStringCompareFunc, compare)
245 
246 /* Reverses the order of the entries in a playlist. */
247 AUD_VFUNC1 (playlist_reverse, int, playlist)
248 
249 /* Reorders the entries in a playlist randomly. */
250 AUD_VFUNC1 (playlist_randomize, int, playlist)
251 
252 /* Discards the metadata stored for all the entries in a playlist and starts
253  * reading it afresh from the song files in the background. */
254 AUD_VFUNC1 (playlist_rescan, int, playlist)
255 
256 /* Like playlist_rescan, but applies only to the selected entries in a playlist. */
257 AUD_VFUNC1 (playlist_rescan_selected, int, playlist)
258 
259 /* Discards the metadata stored for all the entries that refer to a particular
260  * song file, in whatever playlist they appear, and starts reading it afresh
261  * from that file in the background. */
262 AUD_VFUNC1 (playlist_rescan_file, const char *, filename)
263 
264 /* Calculates the total length in milliseconds of all the entries in a playlist.
265  * Only takes into account entries for which metadata has already been read. */
266 AUD_FUNC1 (int64_t, playlist_get_total_length, int, playlist)
267 
268 /* Calculates the total length in milliseconds of only the selected entries in a
269  * playlist. Only takes into account entries for which metadata has already
270  * been read. */
271 AUD_FUNC1 (int64_t, playlist_get_selected_length, int, playlist)
272 
273 /* Returns the number of entries in a playlist queue. The entries are numbered
274  * starting from zero, lower numbers being played first. */
275 AUD_FUNC1 (int, playlist_queue_count, int, playlist)
276 
277 /* Adds an entry to a playlist's queue before the entry numbered <at> in the
278  * queue. If <at> is negative or equal to the number of entries in the queue,
279  * adds the entry after the last one in the queue. The same entry cannot be
280  * added to the queue more than once. */
281 AUD_VFUNC3 (playlist_queue_insert, int, playlist, int, at, int, entry)
282 
283 /* Adds the selected entries in a playlist to the queue, if they are not already
284  * in it. */
285 AUD_VFUNC2 (playlist_queue_insert_selected, int, playlist, int, at)
286 
287 /* Returns the position in the playlist of the entry at a given position in the
288  * queue. */
289 AUD_FUNC2 (int, playlist_queue_get_entry, int, playlist, int, at)
290 
291 /* Returns the position in the queue of the entry at a given position in the
292  * playlist. If it is not in the queue, returns -1. */
293 AUD_FUNC2 (int, playlist_queue_find_entry, int, playlist, int, entry)
294 
295 /* Removes a contiguous block of <number> entries starting with the one numbered
296  * <at> from the queue. */
297 AUD_VFUNC3 (playlist_queue_delete, int, playlist, int, at, int, number)
298 
299 /* Removes the selected entries in a playlist from the queue, if they are in it. */
301 
302 /* Returns nonzero if a "playlist update" hook call is pending. If called from
303  * within the hook, the current hook call is not considered pending. */
305 
306 /* May be called within the "playlist update" hook to determine the update level
307  * and number of entries changed in a playlist. Returns the update level for
308  * the playlist, storing the number of the first entry changed in <at> and the
309  * number of contiguous entries to be updated in <count>. Note that entries may
310  * have been added or removed within this range. If no entries in the playlist
311  * have changed, returns zero. */
312 AUD_FUNC3 (int, playlist_updated_range, int, playlist, int *, at, int *, count)
313 
314 /* Returns nonzero if entries are being added to a playlist in the background. */
315 AUD_FUNC1 (bool_t, playlist_add_in_progress, int, playlist)
316 
317 /* Returns nonzero if entries in a playlist are being scanned for metadata in
318  * the background. */
319 AUD_FUNC1 (bool_t, playlist_scan_in_progress, int, playlist)
320 
321 /* --- PLAYLIST UTILITY API --- */
322 
323 /* Sorts the entries in a playlist according to one of the schemes listed in
324  * playlist.h. */
325 AUD_VFUNC2 (playlist_sort_by_scheme, int, playlist, int, scheme)
326 
327 /* Sorts only the selected entries in a playlist according to one of those
328  * schemes. */
329 AUD_VFUNC2 (playlist_sort_selected_by_scheme, int, playlist, int, scheme)
330 
331 /* Removes duplicate entries in a playlist according to one of those schemes.
332  * As currently implemented, first sorts the playlist. */
334  scheme)
335 
336 /* Removes all entries referring to unavailable files in a playlist. ("Remove
337  * failed" is something of a misnomer for the current behavior.) As currently
338  * implemented, only works for file:// URIs. */
339 AUD_VFUNC1 (playlist_remove_failed, int, playlist)
340 
341 /* Selects all the entries in a playlist that match regular expressions stored
342  * in the fields of a tuple. Does not free the memory used by the tuple.
343  * Example: To select all the songs whose title starts with the letter "A",
344  * create a blank tuple and set its title field to "^A". */
345 AUD_VFUNC2 (playlist_select_by_patterns, int, playlist, const Tuple *,
346  patterns)
347 
348 /* Returns nonzero if <filename> refers to a playlist file. */
349 AUD_FUNC1 (bool_t, filename_is_playlist, const char *, filename)
350 
351 /* Saves the entries in a playlist to a playlist file. The format of the file
352  * is determined from the file extension. Returns nonzero on success. */
353 AUD_FUNC2 (bool_t, playlist_save, int, playlist, const char *, filename)