Audacious $Id:Doxyfile42802007-03-2104:39:00Znenolod$
playlist-api.h
Go to the documentation of this file.
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)