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 /* CAUTION: These functions are not thread safe. */ 00025 00026 /* --- PLAYLIST CORE API --- */ 00027 00028 /* Returns the number of playlists currently open. There will always be at 00029 * least one playlist open. The playlists are numbered starting from zero. */ 00030 AUD_FUNC0 (gint, playlist_count) 00031 00032 /* Adds a new playlist before the one numbered <at>. If <at> is negative or 00033 * equal to the number of playlists, adds a new playlist after the last one. */ 00034 AUD_FUNC1 (void, playlist_insert, gint, at) 00035 00036 /* Moves a contiguous block of <count> playlists starting with the one numbered 00037 * <from> such that that playlist ends up at the position <to>. */ 00038 AUD_FUNC3 (void, playlist_reorder, gint, from, gint, to, gint, count) 00039 00040 /* Closes a playlist. CAUTION: The playlist is not saved, and no confirmation 00041 * is presented to the user. If <playlist> is the only playlist, a new playlist 00042 * is added. If <playlist> is the active playlist, another playlist is marked 00043 * active. If <playlist> is the one from which the last song played was taken, 00044 * playback is stopped. In this case, calls to playlist_get_playing() will 00045 * return -1, and the behavior of drct_play() is unspecified. */ 00046 AUD_FUNC1 (void, playlist_delete, gint, playlist) 00047 00048 /* Sets the filename associated with a playlist. (Audacious currently makes no 00049 * use of the filename.) */ 00050 AUD_FUNC2 (void, playlist_set_filename, gint, playlist, const gchar *, filename) 00051 00052 /* Returns the filename associated with a playlist. */ 00053 AUD_FUNC1 (const gchar *, playlist_get_filename, gint, playlist) 00054 00055 /* Sets the title associated with a playlist. */ 00056 AUD_FUNC2 (void, playlist_set_title, gint, playlist, const gchar *, title) 00057 00058 /* Returns the title associated with a playlist. */ 00059 AUD_FUNC1 (const gchar *, playlist_get_title, gint, playlist) 00060 00061 /* Marks a playlist as active. This is the playlist which the user will see and 00062 * on which most DRCT functions will take effect. */ 00063 AUD_FUNC1 (void, playlist_set_active, gint, playlist) 00064 00065 /* Returns the number of the playlist marked active. */ 00066 AUD_FUNC0 (gint, playlist_get_active) 00067 00068 /* Sets the playlist in which playback will begin when drct_play() is called. 00069 * This does not mark the playlist as active. If a song is already playing, it 00070 * will be stopped. If <playlist> is negative, calls to playlist_get_playing() 00071 * will return -1, and the behavior of drct_play() is unspecified. */ 00072 AUD_FUNC1 (void, playlist_set_playing, gint, playlist) 00073 00074 /* Returns the number of the playlist from which the last song played was taken, 00075 * or -1 if that cannot be determined. Note that this playlist may not be 00076 * marked active. */ 00077 AUD_FUNC0 (gint, playlist_get_playing) 00078 00079 /* Returns the number of entries in a playlist. The entries are numbered 00080 * starting from zero. */ 00081 AUD_FUNC1 (gint, playlist_entry_count, gint, playlist) 00082 00083 /* Adds a song file to a playlist before the entry numbered <at>. If <at> is 00084 * negative or equal to the number of entries, the song is added after the last 00085 * entry. <tuple> may be NULL, in which case Audacious will attempt to read 00086 * metadata from the song file. Audacious will free the memory used by the 00087 * filename and the tuple when they are no longer needed. NOTE: This function 00088 * cannot be used to insert playlist files or entire folders. To do that, see 00089 * playlist_insert_playlist or playlist_insert_folder. */ 00090 AUD_FUNC4 (void, playlist_entry_insert, gint, playlist, gint, at, gchar *, 00091 filename, Tuple *, tuple) 00092 00093 /* Similar to playlist_entry_insert, adds multiple song files to a playlist. 00094 * The filenames are stored as (gchar *) in an index (see libaudcore/index.h). 00095 * Tuples are likewise stored as (Tuple *) in an index of the same length. 00096 * <tuples> may be NULL, or individual pointers within it may be NULL. 00097 * Audacious will free both indexes, the filenames, and the tuples when they are 00098 * no longer needed. */ 00099 AUD_FUNC4 (void, playlist_entry_insert_batch, gint, playlist, gint, at, 00100 struct index *, filenames, struct index *, tuples) 00101 00102 /* Removes a contiguous block of <number> entries starting from the one numbered 00103 * <at> from a playlist. If the last song played is in this block, playback is 00104 * stopped. In this case, calls to playlist_get_position() will return -1, and 00105 * the behavior of drct_play() is unspecified. */ 00106 AUD_FUNC3 (void, playlist_entry_delete, gint, playlist, gint, at, gint, number) 00107 00108 /* Returns the filename of an entry. The returned string is valid until another 00109 * playlist function is called or control returns to the program's main loop. */ 00110 AUD_FUNC2 (const gchar *, playlist_entry_get_filename, gint, playlist, gint, 00111 entry) 00112 00113 /* Returns a handle to the decoder plugin associated with an entry, or NULL if 00114 * none can be found. If <fast> is nonzero, returns NULL if no decoder plugin 00115 * has yet been found. */ 00116 AUD_FUNC3 (PluginHandle *, playlist_entry_get_decoder, gint, playlist, gint, 00117 entry, gboolean, fast) 00118 00119 /* Returns the tuple associated with an entry, or NULL if one is not available. 00120 * The returned tuple is read-only and valid until another playlist function is 00121 * called or control returns to the program's main loop. If <fast> is nonzero, 00122 * returns NULL if metadata for the entry has not yet been read from the song 00123 * file. */ 00124 AUD_FUNC3 (const Tuple *, playlist_entry_get_tuple, gint, playlist, gint, entry, 00125 gboolean, fast) 00126 00127 /* Returns a formatted title string for an entry. This may include information 00128 * such as the filename, song title, and/or artist. The returned string is 00129 * valid until another playlist function is called or control returns to the 00130 * program's main loop. If <fast> is nonzero, returns the entry's filename if 00131 * metadata for the entry has not yet been read. */ 00132 AUD_FUNC3 (const gchar *, playlist_entry_get_title, gint, playlist, gint, entry, 00133 gboolean, fast) 00134 00135 /* Returns three strings (title, artist, and album) describing an entry. The 00136 * returned strings are valid until another playlist function is called or 00137 * control returns to the program's main loop. If <fast> is nonzero, return's 00138 * the entry's filename for <title> and NULL for <artist> and <album> if 00139 * metadata for the entry has not yet been read. */ 00140 AUD_FUNC6 (void, playlist_entry_describe, gint, playlist, gint, entry, 00141 const gchar * *, title, const gchar * *, artist, const gchar * *, album, 00142 gboolean, fast) 00143 00144 /* Returns the length in milliseconds of an entry, or -1 if the length is not 00145 * known. <fast> is as in playlist_entry_get_tuple(). */ 00146 AUD_FUNC3 (gint, playlist_entry_get_length, gint, playlist, gint, entry, 00147 gboolean, fast) 00148 00149 /* Sets the entry which will be played (if this playlist is selected with 00150 * playlist_set_playing()) when drct_play() is called. If a song from this 00151 * playlist is already playing, it will be stopped. If <position> is negative, 00152 * calls to playlist_get_position() will return -1, and the behavior of 00153 * drct_play() is unspecified. */ 00154 AUD_FUNC2 (void, playlist_set_position, gint, playlist, gint, position) 00155 00156 /* Returns the number of the entry which was last played from this playlist, or 00157 * -1 if that cannot be determined. */ 00158 AUD_FUNC1 (gint, playlist_get_position, gint, playlist) 00159 00160 /* Sets whether an entry is selected. */ 00161 AUD_FUNC3 (void, playlist_entry_set_selected, gint, playlist, gint, entry, 00162 gboolean, selected) 00163 00164 /* Returns whether an entry is selected. */ 00165 AUD_FUNC2 (gboolean, playlist_entry_get_selected, gint, playlist, gint, entry) 00166 00167 /* Returns the number of selected entries in a playlist. */ 00168 AUD_FUNC1 (gint, playlist_selected_count, gint, playlist) 00169 00170 /* Selects all (or none) of the entries in a playlist. */ 00171 AUD_FUNC2 (void, playlist_select_all, gint, playlist, gboolean, selected) 00172 00173 /* Moves a selected entry within a playlist by an offset of <distance> entries. 00174 * Other selected entries are gathered around it. Returns the offset by which 00175 * the entry was actually moved, which may be less in absolute value than the 00176 * requested offset. */ 00177 AUD_FUNC3 (gint, playlist_shift, gint, playlist, gint, position, gint, distance) 00178 00179 /* Removes the selected entries from a playlist. If the last song played is one 00180 * of these entries, playback is stopped. In this case, calls to 00181 * playlist_get_position() will return -1, and the behavior of drct_play() is 00182 * unspecified. */ 00183 AUD_FUNC1 (void, playlist_delete_selected, gint, playlist) 00184 00185 /* Sorts the entries in a playlist based on filename. The callback function 00186 * should return negative if the first filename comes before the second, 00187 * positive if it comes after, or zero if the two are indistinguishable. */ 00188 AUD_FUNC2 (void, playlist_sort_by_filename, gint, playlist, 00189 PlaylistStringCompareFunc, compare) 00190 00191 /* Sorts the entries in a playlist based on tuple. */ 00192 AUD_FUNC2 (void, playlist_sort_by_tuple, gint, playlist, 00193 PlaylistTupleCompareFunc, compare) 00194 00195 /* Sorts the entries in a playlist based on formatted title string. */ 00196 AUD_FUNC2 (void, playlist_sort_by_title, gint, playlist, 00197 PlaylistStringCompareFunc, compare) 00198 00199 /* Sorts only the selected entries in a playlist based on filename. */ 00200 AUD_FUNC2 (void, playlist_sort_selected_by_filename, gint, playlist, 00201 PlaylistStringCompareFunc, compare) 00202 00203 /* Sorts only the selected entries in a playlist based on tuple. */ 00204 AUD_FUNC2 (void, playlist_sort_selected_by_tuple, gint, playlist, 00205 PlaylistTupleCompareFunc, compare) 00206 00207 /* Sorts only the selected entries in a playlist based on formatted title string. */ 00208 AUD_FUNC2 (void, playlist_sort_selected_by_title, gint, playlist, 00209 PlaylistStringCompareFunc, compare) 00210 00211 /* Reverses the order of the entries in a playlist. */ 00212 AUD_FUNC1 (void, playlist_reverse, gint, playlist) 00213 00214 /* Reorders the entries in a playlist randomly. */ 00215 AUD_FUNC1 (void, playlist_randomize, gint, playlist) 00216 00217 /* Discards the metadata stored for all the entries in a playlist and starts 00218 * reading it afresh from the song files in the background. */ 00219 AUD_FUNC1 (void, playlist_rescan, gint, playlist) 00220 00221 /* Like playlist_rescan, but applies only to the selected entries in a playlist. */ 00222 AUD_FUNC1 (void, playlist_rescan_selected, gint, playlist) 00223 00224 /* Discards the metadata stored for all the entries that refer to a particular 00225 * song file, in whatever playlist they appear, and starts reading it afresh 00226 * from that file in the background. */ 00227 AUD_FUNC1 (void, playlist_rescan_file, const gchar *, filename) 00228 00229 /* Calculates the total length in milliseconds of all the entries in a playlist. 00230 * <fast> is as in playlist_entry_get_tuple(). */ 00231 AUD_FUNC2 (gint64, playlist_get_total_length, gint, playlist, gboolean, fast) 00232 00233 /* Calculates the total length in milliseconds of only the selected entries in a 00234 * playlist. <fast> is as in playlist_entry_get_tuple(). */ 00235 AUD_FUNC2 (gint64, playlist_get_selected_length, gint, playlist, gboolean, fast) 00236 00237 /* Returns the number of entries in a playlist queue. The entries are numbered 00238 * starting from zero, lower numbers being played first. */ 00239 AUD_FUNC1 (gint, playlist_queue_count, gint, playlist) 00240 00241 /* Adds an entry to a playlist's queue before the entry numbered <at> in the 00242 * queue. If <at> is negative or equal to the number of entries in the queue, 00243 * adds the entry after the last one in the queue. The same entry cannot be 00244 * added to the queue more than once. */ 00245 AUD_FUNC3 (void, playlist_queue_insert, gint, playlist, gint, at, gint, entry) 00246 00247 /* Adds the selected entries in a playlist to the queue, if they are not already 00248 * in it. */ 00249 AUD_FUNC2 (void, playlist_queue_insert_selected, gint, playlist, gint, at) 00250 00251 /* Returns the position in the playlist of the entry at a given position in the 00252 * queue. */ 00253 AUD_FUNC2 (gint, playlist_queue_get_entry, gint, playlist, gint, at) 00254 00255 /* Returns the position in the queue of the entry at a given position in the 00256 * playlist. If it is not in the queue, returns -1. */ 00257 AUD_FUNC2 (gint, playlist_queue_find_entry, gint, playlist, gint, entry) 00258 00259 /* Removes a contiguous block of <number> entries starting with the one numbered 00260 * <at> from the queue. */ 00261 AUD_FUNC3 (void, playlist_queue_delete, gint, playlist, gint, at, gint, number) 00262 00263 /* Removes the selected entries in a playlist from the queue, if they are in it. */ 00264 AUD_FUNC1 (void, playlist_queue_delete_selected, gint, playlist) 00265 00266 /* Returns nonzero if any playlist has been changed since the last call of the 00267 * "playlist update" hook. If called from within the hook, returns nonzero. */ 00268 AUD_FUNC0 (gboolean, playlist_update_pending) 00269 00270 /* May be called within the "playlist update" hook to determine what range of 00271 * entries must be updated. If all entries in all playlists must be updated, 00272 * returns zero. If a limited range in a single playlist must be updated, 00273 * returns nonzero. In this case, stores the number of that playlist at 00274 * <playlist>, the number of the first entry to be updated at <at>, and the 00275 * number of contiguous entries to be updated at <count>. Note that entries may 00276 * have been added or removed within this range. */ 00277 AUD_FUNC3 (gboolean, playlist_update_range, gint *, playlist, gint *, at, 00278 gint *, count) 00279 00280 /* --- PLAYLIST UTILITY API --- */ 00281 00282 /* Sorts the entries in a playlist according to one of the schemes listed in 00283 * playlist.h. */ 00284 AUD_FUNC2 (void, playlist_sort_by_scheme, gint, playlist, gint, scheme) 00285 00286 /* Sorts only the selected entries in a playlist according to one of those 00287 * schemes. */ 00288 AUD_FUNC2 (void, playlist_sort_selected_by_scheme, gint, playlist, gint, scheme) 00289 00290 /* Removes duplicate entries in a playlist according to one of those schemes. 00291 * As currently implemented, first sorts the playlist. */ 00292 AUD_FUNC2 (void, playlist_remove_duplicates_by_scheme, gint, playlist, gint, 00293 scheme) 00294 00295 /* Removes all entries referring to unavailable files in a playlist. ("Remove 00296 * failed" is something of a misnomer for the current behavior.) As currently 00297 * implemented, only works for file:// URIs. */ 00298 AUD_FUNC1 (void, playlist_remove_failed, gint, playlist) 00299 00300 /* Selects all the entries in a playlist that match regular expressions stored 00301 * in the fields of a tuple. Does not free the memory used by the tuple. 00302 * Example: To select all the songs whose title starts with the letter "A", 00303 * create a blank tuple and set its title field to "^A". */ 00304 AUD_FUNC2 (void, playlist_select_by_patterns, gint, playlist, const Tuple *, 00305 patterns) 00306 00307 /* Returns nonzero if <filename> refers to a playlist file. */ 00308 AUD_FUNC1 (gboolean, filename_is_playlist, const gchar *, filename) 00309 00310 /* Reads entries from a playlist file and add them to a playlist. <at> is as in 00311 * playlist_entry_insert(). Returns nonzero on success. */ 00312 AUD_FUNC3 (gboolean, playlist_insert_playlist, gint, playlist, gint, at, 00313 const gchar *, filename) 00314 00315 /* Saves the entries in a playlist to a playlist file. The format of the file 00316 * is determined from the file extension. Returns nonzero on success. */ 00317 AUD_FUNC2 (gboolean, playlist_save, gint, playlist, const gchar *, filename) 00318 00319 /* Begins searching a folder recursively for supported files (including playlist 00320 * files) and adding them to a playlist. The search continues in the 00321 * background. If <play> is nonzero, begins playback of the first entry added 00322 * (or a random entry if shuffle is enabled) once the search is complete. 00323 * CAUTION: Editing the playlist while the search is in progress may lead to 00324 * unexpected results. */ 00325 AUD_FUNC4 (void, playlist_insert_folder, gint, playlist, gint, at, 00326 const gchar *, folder, gboolean, play) 00327 00328 /* --- ADDED IN AUDACIOUS 2.5-BETA2 --- */ 00329 00330 /* Returns a unique non-negative integer which can be used to identify a given 00331 * playlist even if its numbering changes (as when playlists are reordered). 00332 * On error, returns -1. */ 00333 AUD_FUNC1 (gint, playlist_get_unique_id, gint, playlist) 00334 00335 /* Returns the number of the playlist identified by a given integer ID as 00336 * returned by playlist_get_unique_id(). If the playlist no longer exists, 00337 * returns -1. */ 00338 AUD_FUNC1 (gint, playlist_by_unique_id, gint, id)