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