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 * a "best guess" based on the entry's filename if metadata for the entry has 00148 * not yet been read. May return NULL for any and all values. */ 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. May fail if metadata 00200 * scanning is still in progress (or has been disabled). */ 00201 AUD_FUNC2 (void, playlist_sort_by_tuple, gint, playlist, 00202 PlaylistTupleCompareFunc, compare) 00203 00204 /* Sorts the entries in a playlist based on formatted title string. May fail if 00205 * metadata scanning is still in progress (or has been disabled). */ 00206 AUD_FUNC2 (void, playlist_sort_by_title, gint, playlist, 00207 PlaylistStringCompareFunc, compare) 00208 00209 /* Sorts only the selected entries in a playlist based on filename. */ 00210 AUD_FUNC2 (void, playlist_sort_selected_by_filename, gint, playlist, 00211 PlaylistStringCompareFunc, compare) 00212 00213 /* Sorts only the selected entries in a playlist based on tuple. May fail if 00214 * metadata scanning is still in progress (or has been disabled). */ 00215 AUD_FUNC2 (void, playlist_sort_selected_by_tuple, gint, playlist, 00216 PlaylistTupleCompareFunc, compare) 00217 00218 /* Sorts only the selected entries in a playlist based on formatted title 00219 * string. May fail if metadata scanning is still in progress (or has been 00220 * disabled). */ 00221 AUD_FUNC2 (void, playlist_sort_selected_by_title, gint, playlist, 00222 PlaylistStringCompareFunc, compare) 00223 00224 /* Reverses the order of the entries in a playlist. */ 00225 AUD_FUNC1 (void, playlist_reverse, gint, playlist) 00226 00227 /* Reorders the entries in a playlist randomly. */ 00228 AUD_FUNC1 (void, playlist_randomize, gint, playlist) 00229 00230 /* Discards the metadata stored for all the entries in a playlist and starts 00231 * reading it afresh from the song files in the background. */ 00232 AUD_FUNC1 (void, playlist_rescan, gint, playlist) 00233 00234 /* Like playlist_rescan, but applies only to the selected entries in a playlist. */ 00235 AUD_FUNC1 (void, playlist_rescan_selected, gint, playlist) 00236 00237 /* Discards the metadata stored for all the entries that refer to a particular 00238 * song file, in whatever playlist they appear, and starts reading it afresh 00239 * from that file in the background. */ 00240 AUD_FUNC1 (void, playlist_rescan_file, const gchar *, filename) 00241 00242 /* Calculates the total length in milliseconds of all the entries in a playlist. 00243 * Only takes into account entries for which metadata has already been read. */ 00244 AUD_FUNC1 (gint64, playlist_get_total_length, gint, playlist) 00245 00246 /* Calculates the total length in milliseconds of only the selected entries in a 00247 * playlist. Only takes into account entries for which metadata has already 00248 * been read. */ 00249 AUD_FUNC1 (gint64, playlist_get_selected_length, gint, playlist) 00250 00251 /* Returns the number of entries in a playlist queue. The entries are numbered 00252 * starting from zero, lower numbers being played first. */ 00253 AUD_FUNC1 (gint, playlist_queue_count, gint, playlist) 00254 00255 /* Adds an entry to a playlist's queue before the entry numbered <at> in the 00256 * queue. If <at> is negative or equal to the number of entries in the queue, 00257 * adds the entry after the last one in the queue. The same entry cannot be 00258 * added to the queue more than once. */ 00259 AUD_FUNC3 (void, playlist_queue_insert, gint, playlist, gint, at, gint, entry) 00260 00261 /* Adds the selected entries in a playlist to the queue, if they are not already 00262 * in it. */ 00263 AUD_FUNC2 (void, playlist_queue_insert_selected, gint, playlist, gint, at) 00264 00265 /* Returns the position in the playlist of the entry at a given position in the 00266 * queue. */ 00267 AUD_FUNC2 (gint, playlist_queue_get_entry, gint, playlist, gint, at) 00268 00269 /* Returns the position in the queue of the entry at a given position in the 00270 * playlist. If it is not in the queue, returns -1. */ 00271 AUD_FUNC2 (gint, playlist_queue_find_entry, gint, playlist, gint, entry) 00272 00273 /* Removes a contiguous block of <number> entries starting with the one numbered 00274 * <at> from the queue. */ 00275 AUD_FUNC3 (void, playlist_queue_delete, gint, playlist, gint, at, gint, number) 00276 00277 /* Removes the selected entries in a playlist from the queue, if they are in it. */ 00278 AUD_FUNC1 (void, playlist_queue_delete_selected, gint, playlist) 00279 00280 /* Returns nonzero if any playlist has been changed since the last call of the 00281 * "playlist update" hook. If called from within the hook, returns nonzero. */ 00282 AUD_FUNC0 (gboolean, playlist_update_pending) 00283 00284 /* May be called within the "playlist update" hook to determine what range of 00285 * entries must be updated. If all entries in all playlists must be updated, 00286 * returns zero. If a limited range in a single playlist must be updated, 00287 * returns nonzero. In this case, stores the number of that playlist at 00288 * <playlist>, the number of the first entry to be updated at <at>, and the 00289 * number of contiguous entries to be updated at <count>. Note that entries may 00290 * have been added or removed within this range. */ 00291 AUD_FUNC3 (gboolean, playlist_update_range, gint *, playlist, gint *, at, 00292 gint *, count) 00293 00294 /* --- PLAYLIST UTILITY API --- */ 00295 00296 /* Sorts the entries in a playlist according to one of the schemes listed in 00297 * playlist.h. */ 00298 AUD_FUNC2 (void, playlist_sort_by_scheme, gint, playlist, gint, scheme) 00299 00300 /* Sorts only the selected entries in a playlist according to one of those 00301 * schemes. */ 00302 AUD_FUNC2 (void, playlist_sort_selected_by_scheme, gint, playlist, gint, scheme) 00303 00304 /* Removes duplicate entries in a playlist according to one of those schemes. 00305 * As currently implemented, first sorts the playlist. */ 00306 AUD_FUNC2 (void, playlist_remove_duplicates_by_scheme, gint, playlist, gint, 00307 scheme) 00308 00309 /* Removes all entries referring to unavailable files in a playlist. ("Remove 00310 * failed" is something of a misnomer for the current behavior.) As currently 00311 * implemented, only works for file:// URIs. */ 00312 AUD_FUNC1 (void, playlist_remove_failed, gint, playlist) 00313 00314 /* Selects all the entries in a playlist that match regular expressions stored 00315 * in the fields of a tuple. Does not free the memory used by the tuple. 00316 * Example: To select all the songs whose title starts with the letter "A", 00317 * create a blank tuple and set its title field to "^A". */ 00318 AUD_FUNC2 (void, playlist_select_by_patterns, gint, playlist, const Tuple *, 00319 patterns) 00320 00321 /* Returns nonzero if <filename> refers to a playlist file. */ 00322 AUD_FUNC1 (gboolean, filename_is_playlist, const gchar *, filename) 00323 00324 /* Saves the entries in a playlist to a playlist file. The format of the file 00325 * is determined from the file extension. Returns nonzero on success. */ 00326 AUD_FUNC2 (gboolean, playlist_save, gint, playlist, const gchar *, filename)