Audacious
$Id:Doxyfile42802007-03-2104:39:00Znenolod$
|
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 a "best guess" based on the entry's filename if metadata for the 00163 * entry has not yet been read. */ 00164 AUD_FUNC3 (char *, playlist_entry_get_title, int, playlist, int, entry, 00165 bool_t, fast) 00166 00167 /* Returns three strings (title, artist, and album) describing an entry. The 00168 * strings are pooled, and the usual cautions apply. If <fast> is nonzero, 00169 * returns a "best guess" based on the entry's filename if metadata for the 00170 * entry has not yet been read. May return NULL for any and all values. */ 00171 AUD_VFUNC6 (playlist_entry_describe, int, playlist, int, entry, 00172 char * *, title, char * *, artist, char * *, album, bool_t, fast) 00173 00174 /* Returns the length in milliseconds of an entry, or -1 if the length is not 00175 * known. <fast> is as in playlist_entry_get_tuple(). */ 00176 AUD_FUNC3 (int, playlist_entry_get_length, int, playlist, int, entry, 00177 bool_t, fast) 00178 00179 /* Sets the entry which will be played (if this playlist is selected with 00180 * playlist_set_playing()) when drct_play() is called. If a song from this 00181 * playlist is already playing, it will be stopped. If <position> is negative, 00182 * calls to playlist_get_position() will return -1, and the behavior of 00183 * drct_play() is unspecified. */ 00184 AUD_VFUNC2 (playlist_set_position, int, playlist, int, position) 00185 00186 /* Returns the number of the entry which was last played from this playlist, or 00187 * -1 if that cannot be determined. */ 00188 AUD_FUNC1 (int, playlist_get_position, int, playlist) 00189 00190 /* Sets whether an entry is selected. */ 00191 AUD_VFUNC3 (playlist_entry_set_selected, int, playlist, int, entry, 00192 bool_t, selected) 00193 00194 /* Returns whether an entry is selected. */ 00195 AUD_FUNC2 (bool_t, playlist_entry_get_selected, int, playlist, int, entry) 00196 00197 /* Returns the number of selected entries in a playlist. */ 00198 AUD_FUNC1 (int, playlist_selected_count, int, playlist) 00199 00200 /* Selects all (or none) of the entries in a playlist. */ 00201 AUD_VFUNC2 (playlist_select_all, int, playlist, bool_t, selected) 00202 00203 /* Moves a selected entry within a playlist by an offset of <distance> entries. 00204 * Other selected entries are gathered around it. Returns the offset by which 00205 * the entry was actually moved, which may be less in absolute value than the 00206 * requested offset. */ 00207 AUD_FUNC3 (int, playlist_shift, int, playlist, int, position, int, distance) 00208 00209 /* Removes the selected entries from a playlist. If the last song played is one 00210 * of these entries, playback is stopped. In this case, calls to 00211 * playlist_get_position() will return -1, and the behavior of drct_play() is 00212 * unspecified. */ 00213 AUD_VFUNC1 (playlist_delete_selected, int, playlist) 00214 00215 /* Sorts the entries in a playlist based on filename. The callback function 00216 * should return negative if the first filename comes before the second, 00217 * positive if it comes after, or zero if the two are indistinguishable. */ 00218 AUD_VFUNC2 (playlist_sort_by_filename, int, playlist, 00219 PlaylistStringCompareFunc, compare) 00220 00221 /* Sorts the entries in a playlist based on tuple. May fail if metadata 00222 * scanning is still in progress (or has been disabled). */ 00223 AUD_VFUNC2 (playlist_sort_by_tuple, int, playlist, 00224 PlaylistTupleCompareFunc, compare) 00225 00226 /* Sorts the entries in a playlist based on formatted title string. May fail if 00227 * metadata scanning is still in progress (or has been disabled). */ 00228 AUD_VFUNC2 (playlist_sort_by_title, int, playlist, 00229 PlaylistStringCompareFunc, compare) 00230 00231 /* Sorts only the selected entries in a playlist based on filename. */ 00232 AUD_VFUNC2 (playlist_sort_selected_by_filename, int, playlist, 00233 PlaylistStringCompareFunc, compare) 00234 00235 /* Sorts only the selected entries in a playlist based on tuple. May fail if 00236 * metadata scanning is still in progress (or has been disabled). */ 00237 AUD_VFUNC2 (playlist_sort_selected_by_tuple, int, playlist, 00238 PlaylistTupleCompareFunc, compare) 00239 00240 /* Sorts only the selected entries in a playlist based on formatted title 00241 * string. May fail if metadata scanning is still in progress (or has been 00242 * disabled). */ 00243 AUD_VFUNC2 (playlist_sort_selected_by_title, int, playlist, 00244 PlaylistStringCompareFunc, compare) 00245 00246 /* Reverses the order of the entries in a playlist. */ 00247 AUD_VFUNC1 (playlist_reverse, int, playlist) 00248 00249 /* Reorders the entries in a playlist randomly. */ 00250 AUD_VFUNC1 (playlist_randomize, int, playlist) 00251 00252 /* Discards the metadata stored for all the entries in a playlist and starts 00253 * reading it afresh from the song files in the background. */ 00254 AUD_VFUNC1 (playlist_rescan, int, playlist) 00255 00256 /* Like playlist_rescan, but applies only to the selected entries in a playlist. */ 00257 AUD_VFUNC1 (playlist_rescan_selected, int, playlist) 00258 00259 /* Discards the metadata stored for all the entries that refer to a particular 00260 * song file, in whatever playlist they appear, and starts reading it afresh 00261 * from that file in the background. */ 00262 AUD_VFUNC1 (playlist_rescan_file, const char *, filename) 00263 00264 /* Calculates the total length in milliseconds of all the entries in a playlist. 00265 * Only takes into account entries for which metadata has already been read. */ 00266 AUD_FUNC1 (int64_t, playlist_get_total_length, int, playlist) 00267 00268 /* Calculates the total length in milliseconds of only the selected entries in a 00269 * playlist. Only takes into account entries for which metadata has already 00270 * been read. */ 00271 AUD_FUNC1 (int64_t, playlist_get_selected_length, int, playlist) 00272 00273 /* Returns the number of entries in a playlist queue. The entries are numbered 00274 * starting from zero, lower numbers being played first. */ 00275 AUD_FUNC1 (int, playlist_queue_count, int, playlist) 00276 00277 /* Adds an entry to a playlist's queue before the entry numbered <at> in the 00278 * queue. If <at> is negative or equal to the number of entries in the queue, 00279 * adds the entry after the last one in the queue. The same entry cannot be 00280 * added to the queue more than once. */ 00281 AUD_VFUNC3 (playlist_queue_insert, int, playlist, int, at, int, entry) 00282 00283 /* Adds the selected entries in a playlist to the queue, if they are not already 00284 * in it. */ 00285 AUD_VFUNC2 (playlist_queue_insert_selected, int, playlist, int, at) 00286 00287 /* Returns the position in the playlist of the entry at a given position in the 00288 * queue. */ 00289 AUD_FUNC2 (int, playlist_queue_get_entry, int, playlist, int, at) 00290 00291 /* Returns the position in the queue of the entry at a given position in the 00292 * playlist. If it is not in the queue, returns -1. */ 00293 AUD_FUNC2 (int, playlist_queue_find_entry, int, playlist, int, entry) 00294 00295 /* Removes a contiguous block of <number> entries starting with the one numbered 00296 * <at> from the queue. */ 00297 AUD_VFUNC3 (playlist_queue_delete, int, playlist, int, at, int, number) 00298 00299 /* Removes the selected entries in a playlist from the queue, if they are in it. */ 00300 AUD_VFUNC1 (playlist_queue_delete_selected, int, playlist) 00301 00302 /* Returns nonzero if a "playlist update" hook call is pending. If called from 00303 * within the hook, the current hook call is not considered pending. */ 00304 AUD_FUNC0 (bool_t, playlist_update_pending) 00305 00306 /* May be called within the "playlist update" hook to determine the update level 00307 * and number of entries changed in a playlist. Returns the update level for 00308 * the playlist, storing the number of the first entry changed in <at> and the 00309 * number of contiguous entries to be updated in <count>. Note that entries may 00310 * have been added or removed within this range. If no entries in the playlist 00311 * have changed, returns zero. */ 00312 AUD_FUNC3 (int, playlist_updated_range, int, playlist, int *, at, int *, count) 00313 00314 /* Returns nonzero if entries are being added to a playlist in the background. */ 00315 AUD_FUNC1 (bool_t, playlist_add_in_progress, int, playlist) 00316 00317 /* Returns nonzero if entries in a playlist are being scanned for metadata in 00318 * the background. */ 00319 AUD_FUNC1 (bool_t, playlist_scan_in_progress, int, playlist) 00320 00321 /* --- PLAYLIST UTILITY API --- */ 00322 00323 /* Sorts the entries in a playlist according to one of the schemes listed in 00324 * playlist.h. */ 00325 AUD_VFUNC2 (playlist_sort_by_scheme, int, playlist, int, scheme) 00326 00327 /* Sorts only the selected entries in a playlist according to one of those 00328 * schemes. */ 00329 AUD_VFUNC2 (playlist_sort_selected_by_scheme, int, playlist, int, scheme) 00330 00331 /* Removes duplicate entries in a playlist according to one of those schemes. 00332 * As currently implemented, first sorts the playlist. */ 00333 AUD_VFUNC2 (playlist_remove_duplicates_by_scheme, int, playlist, int, 00334 scheme) 00335 00336 /* Removes all entries referring to unavailable files in a playlist. ("Remove 00337 * failed" is something of a misnomer for the current behavior.) As currently 00338 * implemented, only works for file:// URIs. */ 00339 AUD_VFUNC1 (playlist_remove_failed, int, playlist) 00340 00341 /* Selects all the entries in a playlist that match regular expressions stored 00342 * in the fields of a tuple. Does not free the memory used by the tuple. 00343 * Example: To select all the songs whose title starts with the letter "A", 00344 * create a blank tuple and set its title field to "^A". */ 00345 AUD_VFUNC2 (playlist_select_by_patterns, int, playlist, const Tuple *, 00346 patterns) 00347 00348 /* Returns nonzero if <filename> refers to a playlist file. */ 00349 AUD_FUNC1 (bool_t, filename_is_playlist, const char *, filename) 00350 00351 /* Saves the entries in a playlist to a playlist file. The format of the file 00352 * is determined from the file extension. Returns nonzero on success. */ 00353 AUD_FUNC2 (bool_t, playlist_save, int, playlist, const char *, filename)