00001 /* 00002 * playlist-api.h 00003 * Copyright 2010-2011 John Lindgren 00004 * 00005 * This file is part of Audacious. 00006 * 00007 * Audacious is free software: you can redistribute it and/or modify it under 00008 * the terms of the GNU General Public License as published by the Free Software 00009 * Foundation, version 2 or version 3 of the License. 00010 * 00011 * Audacious is distributed in the hope that it will be useful, but WITHOUT ANY 00012 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 00013 * A PARTICULAR PURPOSE. See the GNU General Public License for more details. 00014 * 00015 * You should have received a copy of the GNU General Public License along with 00016 * Audacious. If not, see <http://www.gnu.org/licenses/>. 00017 * 00018 * The Audacious team does not consider modular code linking to Audacious or 00019 * using our public API to be a derived work. 00020 */ 00021 00022 /* Do not include this file directly; use playlist.h instead. */ 00023 00024 /* Any functions in this API with a return type of (char *) return pooled 00025 * strings that must not be modified and must be released with str_unref() when 00026 * no longer needed. */ 00027 00028 /* --- PLAYLIST CORE API --- */ 00029 00030 /* Returns the number of playlists currently open. There will always be at 00031 * least one playlist open. The playlists are numbered starting from zero. */ 00032 AUD_FUNC0 (int, playlist_count) 00033 00034 /* Adds a new playlist before the one numbered <at>. If <at> is negative or 00035 * equal to the number of playlists, adds a new playlist after the last one. */ 00036 AUD_VFUNC1 (playlist_insert, int, at) 00037 00038 /* Moves a contiguous block of <count> playlists starting with the one numbered 00039 * <from> such that that playlist ends up at the position <to>. */ 00040 AUD_VFUNC3 (playlist_reorder, int, from, int, to, int, count) 00041 00042 /* Closes a playlist. CAUTION: The playlist is not saved, and no confirmation 00043 * is presented to the user. If <playlist> is the only playlist, a new playlist 00044 * is added. If <playlist> is the active playlist, another playlist is marked 00045 * active. If <playlist> is the one from which the last song played was taken, 00046 * playback is stopped. In this case, calls to playlist_get_playing() will 00047 * return -1, and the behavior of drct_play() is unspecified. */ 00048 AUD_VFUNC1 (playlist_delete, int, playlist) 00049 00050 /* Returns a unique non-negative integer which can be used to identify a given 00051 * playlist even if its numbering changes (as when playlists are reordered). 00052 * On error, returns -1. */ 00053 AUD_FUNC1 (int, playlist_get_unique_id, int, playlist) 00054 00055 /* Returns the number of the playlist identified by a given integer ID as 00056 * returned by playlist_get_unique_id(). If the playlist no longer exists, 00057 * returns -1. */ 00058 AUD_FUNC1 (int, playlist_by_unique_id, int, id) 00059 00060 /* Sets the filename associated with a playlist. (Audacious currently makes no 00061 * use of the filename.) */ 00062 AUD_VFUNC2 (playlist_set_filename, int, playlist, const char *, filename) 00063 00064 /* Returns the filename associated with a playlist. */ 00065 AUD_FUNC1 (char *, playlist_get_filename, int, playlist) 00066 00067 /* Sets the title associated with a playlist. */ 00068 AUD_VFUNC2 (playlist_set_title, int, playlist, const char *, title) 00069 00070 /* Returns the title associated with a playlist. */ 00071 AUD_FUNC1 (char *, playlist_get_title, int, playlist) 00072 00073 /* Marks a playlist as active. This is the playlist which the user will see and 00074 * on which most DRCT functions will take effect. */ 00075 AUD_VFUNC1 (playlist_set_active, int, playlist) 00076 00077 /* Returns the number of the playlist marked active. */ 00078 AUD_FUNC0 (int, playlist_get_active) 00079 00080 /* Sets the playlist in which playback will begin when drct_play() is called. 00081 * This does not mark the playlist as active. If a song is already playing, it 00082 * will be stopped. If <playlist> is negative, calls to playlist_get_playing() 00083 * will return -1, and the behavior of drct_play() is unspecified. */ 00084 AUD_VFUNC1 (playlist_set_playing, int, playlist) 00085 00086 /* Returns the number of the playlist from which the last song played was taken, 00087 * or -1 if that cannot be determined. Note that this playlist may not be 00088 * marked active. */ 00089 AUD_FUNC0 (int, playlist_get_playing) 00090 00091 /* Returns the number of a "blank" playlist. The active playlist is returned if 00092 * it has the default title and has no entries; otherwise, a new playlist is 00093 * added and returned. */ 00094 AUD_FUNC0 (int, playlist_get_blank) 00095 00096 /* Returns the number of the "temporary" playlist (which is no different from 00097 * any other playlist except in name). If the playlist does not exist, a 00098 * "blank" playlist is obtained from playlist_get_blank() and is renamed to 00099 * become the temporary playlist. */ 00100 AUD_FUNC0 (int, playlist_get_temporary) 00101 00102 /* Returns the number of entries in a playlist. The entries are numbered 00103 * starting from zero. */ 00104 AUD_FUNC1 (int, playlist_entry_count, int, playlist) 00105 00106 /* Adds a song file, playlist file, or folder to a playlist before the entry 00107 * numbered <at>. If <at> is negative or equal to the number of entries, the 00108 * item is added after the last entry. <tuple> may be NULL, in which case 00109 * Audacious will attempt to read metadata from the song file. The caller gives 00110 * up one reference count to <tuple>. If <play> is nonzero, Audacious will 00111 * begin playback of the items once they have been added. 00112 * 00113 * Because adding items to the playlist can be a slow process, this function may 00114 * return before the process is complete. Hence, the caller must not assume 00115 * that there will be new entries in the playlist immediately. */ 00116 AUD_VFUNC5 (playlist_entry_insert, int, playlist, int, at, const char *, 00117 filename, Tuple *, tuple, bool_t, play) 00118 00119 /* Similar to playlist_entry_insert, adds multiple song files, playlist files, 00120 * or folders to a playlist. The filenames, stored as (char *) in an index 00121 * (see libaudcore/index.h), must be pooled with str_get(); the caller gives up 00122 * one reference count to each filename. Tuples are likewise stored as 00123 * (Tuple *) in an index of the same length; the caller gives up one reference 00124 * count to each tuple. <tuples> may be NULL, or individual pointers within it 00125 * may be NULL. Finally, the caller also gives up ownership of the indexes 00126 * themselves and should not access them after the call. */ 00127 AUD_VFUNC5 (playlist_entry_insert_batch, int, playlist, int, at, 00128 Index *, filenames, Index *, tuples, bool_t, play) 00129 00130 /* Similar to playlist_entry_insert_batch, but allows the caller to prevent some 00131 * items from being added by returning false from the <filter> callback. Useful 00132 * for searching a folder and adding only new files to the playlist. <user> is 00133 * an untyped pointer passed to the <filter> callback. */ 00134 AUD_VFUNC7 (playlist_entry_insert_filtered, int, playlist, int, at, 00135 Index *, filenames, Index *, tuples, PlaylistFilterFunc, filter, 00136 void *, user, bool_t, play) 00137 00138 /* Removes a contiguous block of <number> entries starting from the one numbered 00139 * <at> from a playlist. If the last song played is in this block, playback is 00140 * stopped. In this case, calls to playlist_get_position() will return -1, and 00141 * the behavior of drct_play() is unspecified. */ 00142 AUD_VFUNC3 (playlist_entry_delete, int, playlist, int, at, int, number) 00143 00144 /* Returns the filename of an entry. */ 00145 AUD_FUNC2 (char *, playlist_entry_get_filename, int, playlist, int, entry) 00146 00147 /* Returns a handle to the decoder plugin associated with an entry, or NULL if 00148 * none can be found. If <fast> is nonzero, returns NULL if no decoder plugin 00149 * has yet been found. */ 00150 AUD_FUNC3 (PluginHandle *, playlist_entry_get_decoder, int, playlist, int, 00151 entry, bool_t, fast) 00152 00153 /* Returns the tuple associated with an entry, or NULL if one is not available. 00154 * The reference count of the tuple is incremented. If <fast> is nonzero, 00155 * returns NULL if metadata for the entry has not yet been read from the song 00156 * file. */ 00157 AUD_FUNC3 (Tuple *, playlist_entry_get_tuple, int, playlist, int, entry, 00158 bool_t, fast) 00159 00160 /* Returns a formatted title string for an entry. This may include information 00161 * such as the filename, song title, and/or artist. If <fast> is nonzero, 00162 * returns the entry's filename if metadata for the entry has not yet been read. */ 00163 AUD_FUNC3 (char *, playlist_entry_get_title, int, playlist, int, entry, 00164 bool_t, fast) 00165 00166 /* Returns three strings (title, artist, and album) describing an entry. The 00167 * strings are pooled, and the usual cautions apply. If <fast> is nonzero, 00168 * returns a "best guess" based on the entry's filename if metadata for the 00169 * entry has not yet been read. May return NULL for any and all values. */ 00170 AUD_VFUNC6 (playlist_entry_describe, int, playlist, int, entry, 00171 char * *, title, char * *, artist, char * *, album, bool_t, fast) 00172 00173 /* Returns the length in milliseconds of an entry, or -1 if the length is not 00174 * known. <fast> is as in playlist_entry_get_tuple(). */ 00175 AUD_FUNC3 (int, playlist_entry_get_length, int, playlist, int, entry, 00176 bool_t, fast) 00177 00178 /* Sets the entry which will be played (if this playlist is selected with 00179 * playlist_set_playing()) when drct_play() is called. If a song from this 00180 * playlist is already playing, it will be stopped. If <position> is negative, 00181 * calls to playlist_get_position() will return -1, and the behavior of 00182 * drct_play() is unspecified. */ 00183 AUD_VFUNC2 (playlist_set_position, int, playlist, int, position) 00184 00185 /* Returns the number of the entry which was last played from this playlist, or 00186 * -1 if that cannot be determined. */ 00187 AUD_FUNC1 (int, playlist_get_position, int, playlist) 00188 00189 /* Sets whether an entry is selected. */ 00190 AUD_VFUNC3 (playlist_entry_set_selected, int, playlist, int, entry, 00191 bool_t, selected) 00192 00193 /* Returns whether an entry is selected. */ 00194 AUD_FUNC2 (bool_t, playlist_entry_get_selected, int, playlist, int, entry) 00195 00196 /* Returns the number of selected entries in a playlist. */ 00197 AUD_FUNC1 (int, playlist_selected_count, int, playlist) 00198 00199 /* Selects all (or none) of the entries in a playlist. */ 00200 AUD_VFUNC2 (playlist_select_all, int, playlist, bool_t, selected) 00201 00202 /* Moves a selected entry within a playlist by an offset of <distance> entries. 00203 * Other selected entries are gathered around it. Returns the offset by which 00204 * the entry was actually moved, which may be less in absolute value than the 00205 * requested offset. */ 00206 AUD_FUNC3 (int, playlist_shift, int, playlist, int, position, int, distance) 00207 00208 /* Removes the selected entries from a playlist. If the last song played is one 00209 * of these entries, playback is stopped. In this case, calls to 00210 * playlist_get_position() will return -1, and the behavior of drct_play() is 00211 * unspecified. */ 00212 AUD_VFUNC1 (playlist_delete_selected, int, playlist) 00213 00214 /* Sorts the entries in a playlist based on filename. The callback function 00215 * should return negative if the first filename comes before the second, 00216 * positive if it comes after, or zero if the two are indistinguishable. */ 00217 AUD_VFUNC2 (playlist_sort_by_filename, int, playlist, 00218 PlaylistStringCompareFunc, compare) 00219 00220 /* Sorts the entries in a playlist based on tuple. May fail if metadata 00221 * scanning is still in progress (or has been disabled). */ 00222 AUD_VFUNC2 (playlist_sort_by_tuple, int, playlist, 00223 PlaylistTupleCompareFunc, compare) 00224 00225 /* Sorts the entries in a playlist based on formatted title string. May fail if 00226 * metadata scanning is still in progress (or has been disabled). */ 00227 AUD_VFUNC2 (playlist_sort_by_title, int, playlist, 00228 PlaylistStringCompareFunc, compare) 00229 00230 /* Sorts only the selected entries in a playlist based on filename. */ 00231 AUD_VFUNC2 (playlist_sort_selected_by_filename, int, playlist, 00232 PlaylistStringCompareFunc, compare) 00233 00234 /* Sorts only the selected entries in a playlist based on tuple. May fail if 00235 * metadata scanning is still in progress (or has been disabled). */ 00236 AUD_VFUNC2 (playlist_sort_selected_by_tuple, int, playlist, 00237 PlaylistTupleCompareFunc, compare) 00238 00239 /* Sorts only the selected entries in a playlist based on formatted title 00240 * string. May fail if metadata scanning is still in progress (or has been 00241 * disabled). */ 00242 AUD_VFUNC2 (playlist_sort_selected_by_title, int, playlist, 00243 PlaylistStringCompareFunc, compare) 00244 00245 /* Reverses the order of the entries in a playlist. */ 00246 AUD_VFUNC1 (playlist_reverse, int, playlist) 00247 00248 /* Reorders the entries in a playlist randomly. */ 00249 AUD_VFUNC1 (playlist_randomize, int, playlist) 00250 00251 /* Discards the metadata stored for all the entries in a playlist and starts 00252 * reading it afresh from the song files in the background. */ 00253 AUD_VFUNC1 (playlist_rescan, int, playlist) 00254 00255 /* Like playlist_rescan, but applies only to the selected entries in a playlist. */ 00256 AUD_VFUNC1 (playlist_rescan_selected, int, playlist) 00257 00258 /* Discards the metadata stored for all the entries that refer to a particular 00259 * song file, in whatever playlist they appear, and starts reading it afresh 00260 * from that file in the background. */ 00261 AUD_VFUNC1 (playlist_rescan_file, const char *, filename) 00262 00263 /* Calculates the total length in milliseconds of all the entries in a playlist. 00264 * Only takes into account entries for which metadata has already been read. */ 00265 AUD_FUNC1 (int64_t, playlist_get_total_length, int, playlist) 00266 00267 /* Calculates the total length in milliseconds of only the selected entries in a 00268 * playlist. Only takes into account entries for which metadata has already 00269 * been read. */ 00270 AUD_FUNC1 (int64_t, playlist_get_selected_length, int, playlist) 00271 00272 /* Returns the number of entries in a playlist queue. The entries are numbered 00273 * starting from zero, lower numbers being played first. */ 00274 AUD_FUNC1 (int, playlist_queue_count, int, playlist) 00275 00276 /* Adds an entry to a playlist's queue before the entry numbered <at> in the 00277 * queue. If <at> is negative or equal to the number of entries in the queue, 00278 * adds the entry after the last one in the queue. The same entry cannot be 00279 * added to the queue more than once. */ 00280 AUD_VFUNC3 (playlist_queue_insert, int, playlist, int, at, int, entry) 00281 00282 /* Adds the selected entries in a playlist to the queue, if they are not already 00283 * in it. */ 00284 AUD_VFUNC2 (playlist_queue_insert_selected, int, playlist, int, at) 00285 00286 /* Returns the position in the playlist of the entry at a given position in the 00287 * queue. */ 00288 AUD_FUNC2 (int, playlist_queue_get_entry, int, playlist, int, at) 00289 00290 /* Returns the position in the queue of the entry at a given position in the 00291 * playlist. If it is not in the queue, returns -1. */ 00292 AUD_FUNC2 (int, playlist_queue_find_entry, int, playlist, int, entry) 00293 00294 /* Removes a contiguous block of <number> entries starting with the one numbered 00295 * <at> from the queue. */ 00296 AUD_VFUNC3 (playlist_queue_delete, int, playlist, int, at, int, number) 00297 00298 /* Removes the selected entries in a playlist from the queue, if they are in it. */ 00299 AUD_VFUNC1 (playlist_queue_delete_selected, int, playlist) 00300 00301 /* Returns nonzero if a "playlist update" hook call is pending. If called from 00302 * within the hook, the current hook call is not considered pending. */ 00303 AUD_FUNC0 (bool_t, playlist_update_pending) 00304 00305 /* May be called within the "playlist update" hook to determine the update level 00306 * and number of entries changed in a playlist. Returns the update level for 00307 * the playlist, storing the number of the first entry changed in <at> and the 00308 * number of contiguous entries to be updated in <count>. Note that entries may 00309 * have been added or removed within this range. If no entries in the playlist 00310 * have changed, returns zero. */ 00311 AUD_FUNC3 (int, playlist_updated_range, int, playlist, int *, at, int *, count) 00312 00313 /* Returns nonzero if entries are being added to a playlist in the background. */ 00314 AUD_FUNC1 (bool_t, playlist_add_in_progress, int, playlist) 00315 00316 /* Returns nonzero if entries in a playlist are being scanned for metadata in 00317 * the background. */ 00318 AUD_FUNC1 (bool_t, playlist_scan_in_progress, int, playlist) 00319 00320 /* --- PLAYLIST UTILITY API --- */ 00321 00322 /* Sorts the entries in a playlist according to one of the schemes listed in 00323 * playlist.h. */ 00324 AUD_VFUNC2 (playlist_sort_by_scheme, int, playlist, int, scheme) 00325 00326 /* Sorts only the selected entries in a playlist according to one of those 00327 * schemes. */ 00328 AUD_VFUNC2 (playlist_sort_selected_by_scheme, int, playlist, int, scheme) 00329 00330 /* Removes duplicate entries in a playlist according to one of those schemes. 00331 * As currently implemented, first sorts the playlist. */ 00332 AUD_VFUNC2 (playlist_remove_duplicates_by_scheme, int, playlist, int, 00333 scheme) 00334 00335 /* Removes all entries referring to unavailable files in a playlist. ("Remove 00336 * failed" is something of a misnomer for the current behavior.) As currently 00337 * implemented, only works for file:// URIs. */ 00338 AUD_VFUNC1 (playlist_remove_failed, int, playlist) 00339 00340 /* Selects all the entries in a playlist that match regular expressions stored 00341 * in the fields of a tuple. Does not free the memory used by the tuple. 00342 * Example: To select all the songs whose title starts with the letter "A", 00343 * create a blank tuple and set its title field to "^A". */ 00344 AUD_VFUNC2 (playlist_select_by_patterns, int, playlist, const Tuple *, 00345 patterns) 00346 00347 /* Returns nonzero if <filename> refers to a playlist file. */ 00348 AUD_FUNC1 (bool_t, filename_is_playlist, const char *, filename) 00349 00350 /* Saves the entries in a playlist to a playlist file. The format of the file 00351 * is determined from the file extension. Returns nonzero on success. */ 00352 AUD_FUNC2 (bool_t, playlist_save, int, playlist, const char *, filename)