00001 /* 00002 * playlist-api.h 00003 * Copyright 2010 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. */ 00042 AUD_FUNC1 (void, playlist_delete, gint, playlist) 00043 00044 /* Sets the filename associated with a playlist. (Audacious currently makes no 00045 * use of the filename.) */ 00046 AUD_FUNC2 (void, playlist_set_filename, gint, playlist, const gchar *, filename) 00047 00048 /* Returns the filename associated with a playlist. */ 00049 AUD_FUNC1 (const gchar *, playlist_get_filename, gint, playlist) 00050 00051 /* Sets the title associated with a playlist. */ 00052 AUD_FUNC2 (void, playlist_set_title, gint, playlist, const gchar *, title) 00053 00054 /* Returns the title associated with a playlist. */ 00055 AUD_FUNC1 (const gchar *, playlist_get_title, gint, playlist) 00056 00057 /* Marks a playlist as active. This is the playlist which the user will see and 00058 * on which most DRCT functions will take effect. */ 00059 AUD_FUNC1 (void, playlist_set_active, gint, playlist) 00060 00061 /* Returns the number of the playlist marked active. */ 00062 AUD_FUNC0 (gint, playlist_get_active) 00063 00064 /* Sets the playlist in which playback will begin when drct_play() is called. 00065 * This does not mark the playlist as active. If a song is already playing, it 00066 * will be stopped. If <playlist> is negative, calls to playlist_get_playing() 00067 * will return -1, and the behavior of drct_play() is unspecified. */ 00068 AUD_FUNC1 (void, playlist_set_playing, gint, playlist) 00069 00070 /* Returns the number of the playlist from which the last song played was taken, 00071 * or -1 if that cannot be determined. Note that this playlist may not be 00072 * marked active. */ 00073 AUD_FUNC0 (gint, playlist_get_playing) 00074 00075 /* Returns the number of entries in a playlist. The entries are numbered 00076 * starting from zero. */ 00077 AUD_FUNC1 (gint, playlist_entry_count, gint, playlist) 00078 00079 /* Adds a song file to a playlist before the entry numbered <at>. If <at> is 00080 * negative or equal to the number of entries, the song is added after the last 00081 * entry. <tuple> may be NULL, in which case Audacious will attempt to read 00082 * metadata from the song file. Audacious will free the memory used by the 00083 * filename and the tuple when they are no longer needed. NOTE: This function 00084 * cannot be used to insert playlist files or entire folders. To do that, see 00085 * playlist_insert_playlist or playlist_insert_folder. */ 00086 AUD_FUNC4 (void, playlist_entry_insert, gint, playlist, gint, at, gchar *, 00087 filename, Tuple *, tuple) 00088 00089 /* Similar to playlist_entry_insert, adds multiple song files to a playlist. 00090 * The filenames are stored as (gchar *) in an index (see libaudcore/index.h). 00091 * Tuples are likewise stored as (Tuple *) in an index of the same length. 00092 * <tuples> may be NULL, or individual pointers within it may be NULL. 00093 * Audacious will free both indexes, the filenames, and the tuples when they are 00094 * no longer needed. */ 00095 AUD_FUNC4 (void, playlist_entry_insert_batch, gint, playlist, gint, at, 00096 struct index *, filenames, struct index *, tuples) 00097 00098 /* Removes a contiguous block of <number> entries starting from the one numbered 00099 * <at> from a playlist. */ 00100 AUD_FUNC3 (void, playlist_entry_delete, gint, playlist, gint, at, gint, number) 00101 00102 /* Returns the filename of an entry. The returned string is valid until another 00103 * playlist function is called or control returns to the program's main loop. */ 00104 AUD_FUNC2 (const gchar *, playlist_entry_get_filename, gint, playlist, gint, 00105 entry) 00106 00107 /* Returns the tuple associated with an entry, or NULL if one is not available. 00108 * The returned tuple is read-only and valid until another playlist function is 00109 * called or control returns to the program's main loop. If <fast> is nonzero, 00110 * returns NULL if metadata for the entry has not yet been read from the song 00111 * file. */ 00112 AUD_FUNC3 (const Tuple *, playlist_entry_get_tuple, gint, playlist, gint, entry, 00113 gboolean, fast) 00114 00115 /* Returns a formatted title string for an entry. This may include information 00116 * such as the filename, song title, and/or artist. The returned string is 00117 * valid until another playlist function is called or control returns to the 00118 * program's main loop. <fast> is as in playlist_entry_get_tuple(). */ 00119 AUD_FUNC3 (const gchar *, playlist_entry_get_title, gint, playlist, gint, entry, 00120 gboolean, fast) 00121 00122 /* Returns the length in milliseconds of an entry, or -1 if the length is not 00123 * known. <fast> is as in playlist_entry_get_tuple(). */ 00124 AUD_FUNC3 (gint, playlist_entry_get_length, gint, playlist, gint, entry, 00125 gboolean, fast) 00126 00127 /* Sets the entry which will be played (if this playlist is selected with 00128 * playlist_set_playing()) when drct_play() is called. If a song from this 00129 * playlist is already playing, it will be stopped. If <position> is negative, 00130 * calls to playlist_get_position() will return -1, and the behavior of 00131 * drct_play() is unspecified. */ 00132 AUD_FUNC2 (void, playlist_set_position, gint, playlist, gint, position) 00133 00134 /* Returns the number of the entry which was last played from this playlist, or 00135 * -1 if that cannot be determined. */ 00136 AUD_FUNC1 (gint, playlist_get_position, gint, playlist) 00137 00138 /* Sets whether an entry is selected. */ 00139 AUD_FUNC3 (void, playlist_entry_set_selected, gint, playlist, gint, entry, 00140 gboolean, selected) 00141 00142 /* Returns whether an entry is selected. */ 00143 AUD_FUNC2 (gboolean, playlist_entry_get_selected, gint, playlist, gint, entry) 00144 00145 /* Returns the number of selected entries in a playlist. */ 00146 AUD_FUNC1 (gint, playlist_selected_count, gint, playlist) 00147 00148 /* Selects all (or none) of the entries in a playlist. */ 00149 AUD_FUNC2 (void, playlist_select_all, gint, playlist, gboolean, selected) 00150 00151 /* Moves an entry, along with selected entries near it, within a playlist, by an 00152 * offset of <distance> entries. For an exact definition of "near it", read the 00153 * source code. Returns the offset by which the entry was actually moved, which 00154 * may be less (in absolute value) than the requested offset. */ 00155 AUD_FUNC3 (gint, playlist_shift, gint, playlist, gint, position, gint, distance) 00156 00157 /* Removes the selected entries from a playlist. */ 00158 AUD_FUNC1 (void, playlist_delete_selected, gint, playlist) 00159 00160 /* Sorts the entries in a playlist based on filename. The callback function 00161 * should return negative if the first filename comes before the second, 00162 * positive if it comes after, or zero if the two are indistinguishable. */ 00163 AUD_FUNC2 (void, playlist_sort_by_filename, gint, playlist, 00164 PlaylistFilenameCompareFunc, compare) 00165 00166 /* Sorts the entries in a playlist based on tuple. */ 00167 AUD_FUNC2 (void, playlist_sort_by_tuple, gint, playlist, 00168 PlaylistTupleCompareFunc, compare) 00169 00170 /* Sorts only the selected entries in a playlist based on filename. */ 00171 AUD_FUNC2 (void, playlist_sort_selected_by_filename, gint, playlist, 00172 PlaylistFilenameCompareFunc, compare) 00173 00174 /* Sorts only the selected entries in a playlist based on tuple. */ 00175 AUD_FUNC2 (void, playlist_sort_selected_by_tuple, gint, playlist, 00176 PlaylistTupleCompareFunc, compare) 00177 00178 /* Reverses the order of the entries in a playlist. */ 00179 AUD_FUNC1 (void, playlist_reverse, gint, playlist) 00180 00181 /* Reorders the entries in a playlist randomly. */ 00182 AUD_FUNC1 (void, playlist_randomize, gint, playlist) 00183 00184 /* Discards the metadata stored for all the entries in a playlist and starts 00185 * reading it afresh from the song files in the background. */ 00186 AUD_FUNC1 (void, playlist_rescan, gint, playlist) 00187 00188 /* Discards the metadata stored for all the entries that refer to a particular 00189 * song file, in whatever playlist they appear, and starts reading it afresh 00190 * from that file in the background. */ 00191 AUD_FUNC1 (void, playlist_rescan_file, const gchar *, filename) 00192 00193 /* Calculates the total length in milliseconds of all the entries in a playlist. 00194 * <fast> is as in playlist_entry_get_tuple(). */ 00195 AUD_FUNC2 (gint64, playlist_get_total_length, gint, playlist, gboolean, fast) 00196 00197 /* Calculates the total length in milliseconds of only the selected entries in a 00198 * playlist. <fast> is as in playlist_entry_get_tuple(). */ 00199 AUD_FUNC2 (gint64, playlist_get_selected_length, gint, playlist, gboolean, fast) 00200 00201 /* Returns the number of entries in a playlist queue. The entries are numbered 00202 * starting from zero, lower numbers being played first. */ 00203 AUD_FUNC1 (gint, playlist_queue_count, gint, playlist) 00204 00205 /* Adds an entry to a playlist's queue before the entry numbered <at> in the 00206 * queue. If <at> is negative or equal to the number of entries in the queue, 00207 * adds the entry after the last one in the queue. The same entry cannot be 00208 * added to the queue more than once. */ 00209 AUD_FUNC3 (void, playlist_queue_insert, gint, playlist, gint, at, gint, entry) 00210 00211 /* Adds the selected entries in a playlist to the queue, if they are not already 00212 * in it. */ 00213 AUD_FUNC2 (void, playlist_queue_insert_selected, gint, playlist, gint, at) 00214 00215 /* Returns the position in the playlist of the entry at a given position in the 00216 * queue. */ 00217 AUD_FUNC2 (gint, playlist_queue_get_entry, gint, playlist, gint, at) 00218 00219 /* Returns the position in the queue of the entry at a given position in the 00220 * playlist. If it is not in the queue, returns -1. */ 00221 AUD_FUNC2 (gint, playlist_queue_find_entry, gint, playlist, gint, entry) 00222 00223 /* Removes a contiguous block of <number> entries starting with the one numbered 00224 * <at> from the queue. */ 00225 AUD_FUNC3 (void, playlist_queue_delete, gint, playlist, gint, at, gint, number) 00226 00227 /* Removes the selected entries in a playlist from the queue, if they are in it. */ 00228 AUD_FUNC1 (void, playlist_queue_delete_selected, gint, playlist) 00229 00230 /* Returns nonzero if any playlist has been changed since the last call of the 00231 * "playlist update" hook. If called from within the hook, returns nonzero. */ 00232 AUD_FUNC0 (gboolean, playlist_update_pending) 00233 00234 /* --- PLAYLIST UTILITY API --- */ 00235 00236 /* Sorts the entries in a playlist according to one of the schemes listed in 00237 * playlist.h. */ 00238 AUD_FUNC2 (void, playlist_sort_by_scheme, gint, playlist, gint, scheme) 00239 00240 /* Sorts only the selected entries in a playlist according to one of those 00241 * schemes. */ 00242 AUD_FUNC2 (void, playlist_sort_selected_by_scheme, gint, playlist, gint, scheme) 00243 00244 /* Removes duplicate entries in a playlist according to one of those schemes. 00245 * As currently implemented, first sorts the playlist. */ 00246 AUD_FUNC2 (void, playlist_remove_duplicates_by_scheme, gint, playlist, gint, 00247 scheme) 00248 00249 /* Removes from a playlist entries of files that do not exists or were not 00250 * recognized. */ 00251 AUD_FUNC1 (void, playlist_remove_failed, gint, playlist) 00252 00253 /* Selects all the entries in a playlist that match regular expressions stored 00254 * in the fields of a tuple. Does not free the memory used by the tuple. 00255 * Example: To select all the songs whose title starts with the letter "A", 00256 * create a blank tuple and set its title field to "^A". */ 00257 AUD_FUNC2 (void, playlist_select_by_patterns, gint, playlist, const Tuple *, 00258 patterns) 00259 00260 /* Returns nonzero if <filename> refers to a playlist file. */ 00261 AUD_FUNC1 (gboolean, filename_is_playlist, const gchar *, filename) 00262 00263 /* Reads entries from a playlist file and add them to a playlist. <at> is as in 00264 * playlist_entry_insert(). Returns nonzero on success. */ 00265 AUD_FUNC3 (gboolean, playlist_insert_playlist, gint, playlist, gint, at, 00266 const gchar *, filename) 00267 00268 /* Saves the entries in a playlist to a playlist file. The format of the file 00269 * is determined from the file extension. Returns nonzero on success. */ 00270 AUD_FUNC2 (gboolean, playlist_save, gint, playlist, const gchar *, filename) 00271 00272 /* Begins searching a folder recursively for supported files (including playlist 00273 * files) and adding them to a playlist. The search continues in the 00274 * background. If <play> is nonzero, begins playback of the first entry added 00275 * (or a random entry if shuffle is enabled) once the search is complete. 00276 * CAUTION: Editing the playlist while the search is in progress may lead to 00277 * unexpected results. */ 00278 AUD_FUNC4 (void, playlist_insert_folder, gint, playlist, gint, at, 00279 const gchar *, folder, gboolean, play)