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 negative or
33  * equal to 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. In this case, calls to playlist_get_playing() will return -1. */
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. Any information needed to resume
78  * playback from the previously playing playlist is saved, and playback is
79  * resumed in the newly set playlist if possible. (See playlist_set_position()
80  * for a way to prevent this resuming.) */
81 AUD_VFUNC1 (playlist_set_playing, int, playlist)
82 
83 /* Returns the number of the currently playing playlist, or -1 if there is none. */
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 the last song played is in this block, playback is
135  * stopped. In this case, calls to playlist_get_position() will return -1, and
136  * the behavior of drct_play() is unspecified. */
137 AUD_VFUNC3 (playlist_entry_delete, int, playlist, int, at, int, number)
138 
139 /* Returns the filename of an entry. */
140 AUD_FUNC2 (char *, playlist_entry_get_filename, int, playlist, int, entry)
141 
142 /* Returns a handle to the decoder plugin associated with an entry, or NULL if
143  * none can be found. If <fast> is nonzero, returns NULL if no decoder plugin
144  * has yet been found. */
146  entry, bool_t, fast)
147 
148 /* Returns the tuple associated with an entry, or NULL if one is not available.
149  * The reference count of the tuple is incremented. If <fast> is nonzero,
150  * returns NULL if metadata for the entry has not yet been read from the song
151  * file. */
152 AUD_FUNC3 (Tuple *, playlist_entry_get_tuple, int, playlist, int, entry,
153  bool_t, fast)
154 
155 /* Returns a formatted title string for an entry. This may include information
156  * such as the filename, song title, and/or artist. If <fast> is nonzero,
157  * returns a "best guess" based on the entry's filename if metadata for the
158  * entry has not yet been read. */
159 AUD_FUNC3 (char *, playlist_entry_get_title, int, playlist, int, entry,
160  bool_t, fast)
161 
162 /* Returns three strings (title, artist, and album) describing an entry. The
163  * strings are pooled, and the usual cautions apply. If <fast> is nonzero,
164  * returns a "best guess" based on the entry's filename if metadata for the
165  * entry has not yet been read. The caller may pass NULL for any values that
166  * are not needed; NULL may also be returned for any values that are not
167  * available. */
168 AUD_VFUNC6 (playlist_entry_describe, int, playlist, int, entry,
169  char * *, title, char * *, artist, char * *, album, bool_t, fast)
170 
171 /* Returns the length in milliseconds of an entry, or -1 if the length is not
172  * known. <fast> is as in playlist_entry_get_tuple(). */
173 AUD_FUNC3 (int, playlist_entry_get_length, int, playlist, int, entry,
174  bool_t, fast)
175 
176 /* Sets the entry which will be played (if this playlist is selected with
177  * playlist_set_playing()) when drct_play() is called. If a song from this
178  * playlist is already playing, it will be stopped. If the playlist has resume
179  * information set, it will be cleared. It is possible to set a position of -1,
180  * meaning that no entry is set to be played. */
181 AUD_VFUNC2 (playlist_set_position, int, playlist, int, position)
182 
183 /* Returns the number of the entry set to be played (which may or may not be
184  * currently playing), or -1 if there is none. */
185 AUD_FUNC1 (int, playlist_get_position, int, playlist)
186 
187 /* Sets whether an entry is selected. */
188 AUD_VFUNC3 (playlist_entry_set_selected, int, playlist, int, entry,
189  bool_t, selected)
190 
191 /* Returns whether an entry is selected. */
192 AUD_FUNC2 (bool_t, playlist_entry_get_selected, int, playlist, int, entry)
193 
194 /* Returns the number of selected entries in a playlist. */
195 AUD_FUNC1 (int, playlist_selected_count, int, playlist)
196 
197 /* Selects all (or none) of the entries in a playlist. */
198 AUD_VFUNC2 (playlist_select_all, int, playlist, bool_t, selected)
199 
200 /* Moves a selected entry within a playlist by an offset of <distance> entries.
201  * Other selected entries are gathered around it. Returns the offset by which
202  * the entry was actually moved, which may be less in absolute value than the
203  * requested offset. */
204 AUD_FUNC3 (int, playlist_shift, int, playlist, int, position, int, distance)
205 
206 /* Removes the selected entries from a playlist. If the currently playing entry
207  * is among these, playback is stopped. */
208 AUD_VFUNC1 (playlist_delete_selected, int, playlist)
209 
210 /* Sorts the entries in a playlist based on filename. The callback function
211  * should return negative if the first filename comes before the second,
212  * positive if it comes after, or zero if the two are indistinguishable. */
214  PlaylistStringCompareFunc, compare)
215 
216 /* Sorts the entries in a playlist based on tuple. May fail if metadata
217  * scanning is still in progress (or has been disabled). */
218 AUD_VFUNC2 (playlist_sort_by_tuple, int, playlist,
219  PlaylistTupleCompareFunc, compare)
220 
221 /* Sorts the entries in a playlist based on formatted title string. May fail if
222  * metadata scanning is still in progress (or has been disabled). */
223 AUD_VFUNC2 (playlist_sort_by_title, int, playlist,
224  PlaylistStringCompareFunc, compare)
225 
226 /* Sorts only the selected entries in a playlist based on filename. */
228  PlaylistStringCompareFunc, compare)
229 
230 /* Sorts only the selected entries in a playlist based on tuple. May fail if
231  * metadata scanning is still in progress (or has been disabled). */
233  PlaylistTupleCompareFunc, compare)
234 
235 /* Sorts only the selected entries in a playlist based on formatted title
236  * string. May fail if metadata scanning is still in progress (or has been
237  * disabled). */
239  PlaylistStringCompareFunc, compare)
240 
241 /* Reverses the order of the entries in a playlist. */
242 AUD_VFUNC1 (playlist_reverse, int, playlist)
243 
244 /* Reorders the entries in a playlist randomly. */
245 AUD_VFUNC1 (playlist_randomize, int, playlist)
246 
247 /* Discards the metadata stored for all the entries in a playlist and starts
248  * reading it afresh from the song files in the background. */
249 AUD_VFUNC1 (playlist_rescan, int, playlist)
250 
251 /* Like playlist_rescan, but applies only to the selected entries in a playlist. */
252 AUD_VFUNC1 (playlist_rescan_selected, int, playlist)
253 
254 /* Discards the metadata stored for all the entries that refer to a particular
255  * song file, in whatever playlist they appear, and starts reading it afresh
256  * from that file in the background. */
257 AUD_VFUNC1 (playlist_rescan_file, const char *, filename)
258 
259 /* Calculates the total length in milliseconds of all the entries in a playlist.
260  * Only takes into account entries for which metadata has already been read. */
261 AUD_FUNC1 (int64_t, playlist_get_total_length, int, playlist)
262 
263 /* Calculates the total length in milliseconds of only the selected entries in a
264  * playlist. Only takes into account entries for which metadata has already
265  * been read. */
266 AUD_FUNC1 (int64_t, playlist_get_selected_length, int, playlist)
267 
268 /* Returns the number of entries in a playlist queue. The entries are numbered
269  * starting from zero, lower numbers being played first. */
270 AUD_FUNC1 (int, playlist_queue_count, int, playlist)
271 
272 /* Adds an entry to a playlist's queue before the entry numbered <at> in the
273  * queue. If <at> is negative or equal to the number of entries in the queue,
274  * adds the entry after the last one in the queue. The same entry cannot be
275  * added to the queue more than once. */
276 AUD_VFUNC3 (playlist_queue_insert, int, playlist, int, at, int, entry)
277 
278 /* Adds the selected entries in a playlist to the queue, if they are not already
279  * in it. */
280 AUD_VFUNC2 (playlist_queue_insert_selected, int, playlist, int, at)
281 
282 /* Returns the position in the playlist of the entry at a given position in the
283  * queue. */
284 AUD_FUNC2 (int, playlist_queue_get_entry, int, playlist, int, at)
285 
286 /* Returns the position in the queue of the entry at a given position in the
287  * playlist. If it is not in the queue, returns -1. */
288 AUD_FUNC2 (int, playlist_queue_find_entry, int, playlist, int, entry)
289 
290 /* Removes a contiguous block of <number> entries starting with the one numbered
291  * <at> from the queue. */
292 AUD_VFUNC3 (playlist_queue_delete, int, playlist, int, at, int, number)
293 
294 /* Removes the selected entries in a playlist from the queue, if they are in it. */
296 
297 /* Returns nonzero if a "playlist update" hook call is pending. If called from
298  * within the hook, the current hook call is not considered pending. */
300 
301 /* May be called within the "playlist update" hook to determine the update level
302  * and number of entries changed in a playlist. Returns the update level for
303  * the playlist, storing the number of the first entry changed in <at> and the
304  * number of contiguous entries to be updated in <count>. Note that entries may
305  * have been added or removed within this range. If no entries in the playlist
306  * have changed, returns zero. */
307 AUD_FUNC3 (int, playlist_updated_range, int, playlist, int *, at, int *, count)
308 
309 /* Returns nonzero if entries are being added to a playlist in the background. */
310 AUD_FUNC1 (bool_t, playlist_add_in_progress, int, playlist)
311 
312 /* Returns nonzero if entries in a playlist are being scanned for metadata in
313  * the background. */
314 AUD_FUNC1 (bool_t, playlist_scan_in_progress, int, playlist)
315 
316 /* --- PLAYLIST UTILITY API --- */
317 
318 /* Sorts the entries in a playlist according to one of the schemes listed in
319  * playlist.h. */
320 AUD_VFUNC2 (playlist_sort_by_scheme, int, playlist, int, scheme)
321 
322 /* Sorts only the selected entries in a playlist according to one of those
323  * schemes. */
324 AUD_VFUNC2 (playlist_sort_selected_by_scheme, int, playlist, int, scheme)
325 
326 /* Removes duplicate entries in a playlist according to one of those schemes.
327  * As currently implemented, first sorts the playlist. */
329  scheme)
330 
331 /* Removes all entries referring to unavailable files in a playlist. ("Remove
332  * failed" is something of a misnomer for the current behavior.) As currently
333  * implemented, only works for file:// URIs. */
334 AUD_VFUNC1 (playlist_remove_failed, int, playlist)
335 
336 /* Selects all the entries in a playlist that match regular expressions stored
337  * in the fields of a tuple. Does not free the memory used by the tuple.
338  * Example: To select all the songs whose title starts with the letter "A",
339  * create a blank tuple and set its title field to "^A". */
340 AUD_VFUNC2 (playlist_select_by_patterns, int, playlist, const Tuple *,
341  patterns)
342 
343 /* Returns nonzero if <filename> refers to a playlist file. */
344 AUD_FUNC1 (bool_t, filename_is_playlist, const char *, filename)
345 
346 /* Saves the entries in a playlist to a playlist file. The format of the file
347  * is determined from the file extension. Returns nonzero on success. */
348 AUD_FUNC2 (bool_t, playlist_save, int, playlist, const char *, filename)