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 the entry's filename if metadata for the entry has not yet been read. */
00163 AUD_FUNC3 (char *, playlist_entry_get_title, int, playlist, int, entry,
00164  bool_t, fast)
00165 
00166 /* Returns three strings (title, artist, and album) describing an entry.  The
00167  * strings are pooled, and the usual cautions apply.  If <fast> is nonzero,
00168  * returns a "best guess" based on the entry's filename if metadata for the
00169  * entry has not yet been read.  May return NULL for any and all values. */
00170 AUD_VFUNC6 (playlist_entry_describe, int, playlist, int, entry,
00171  char * *, title, char * *, artist, char * *, album, bool_t, fast)
00172 
00173 /* Returns the length in milliseconds of an entry, or -1 if the length is not
00174  * known.  <fast> is as in playlist_entry_get_tuple(). */
00175 AUD_FUNC3 (int, playlist_entry_get_length, int, playlist, int, entry,
00176  bool_t, fast)
00177 
00178 /* Sets the entry which will be played (if this playlist is selected with
00179  * playlist_set_playing()) when drct_play() is called.  If a song from this
00180  * playlist is already playing, it will be stopped.  If <position> is negative,
00181  * calls to playlist_get_position() will return -1, and the behavior of
00182  * drct_play() is unspecified. */
00183 AUD_VFUNC2 (playlist_set_position, int, playlist, int, position)
00184 
00185 /* Returns the number of the entry which was last played from this playlist, or
00186  * -1 if that cannot be determined. */
00187 AUD_FUNC1 (int, playlist_get_position, int, playlist)
00188 
00189 /* Sets whether an entry is selected. */
00190 AUD_VFUNC3 (playlist_entry_set_selected, int, playlist, int, entry,
00191  bool_t, selected)
00192 
00193 /* Returns whether an entry is selected. */
00194 AUD_FUNC2 (bool_t, playlist_entry_get_selected, int, playlist, int, entry)
00195 
00196 /* Returns the number of selected entries in a playlist. */
00197 AUD_FUNC1 (int, playlist_selected_count, int, playlist)
00198 
00199 /* Selects all (or none) of the entries in a playlist. */
00200 AUD_VFUNC2 (playlist_select_all, int, playlist, bool_t, selected)
00201 
00202 /* Moves a selected entry within a playlist by an offset of <distance> entries.
00203  * Other selected entries are gathered around it.  Returns the offset by which
00204  * the entry was actually moved, which may be less in absolute value than the
00205  * requested offset. */
00206 AUD_FUNC3 (int, playlist_shift, int, playlist, int, position, int, distance)
00207 
00208 /* Removes the selected entries from a playlist.  If the last song played is one
00209  * of these entries, playback is stopped.  In this case, calls to
00210  * playlist_get_position() will return -1, and the behavior of drct_play() is
00211  * unspecified. */
00212 AUD_VFUNC1 (playlist_delete_selected, int, playlist)
00213 
00214 /* Sorts the entries in a playlist based on filename.  The callback function
00215  * should return negative if the first filename comes before the second,
00216  * positive if it comes after, or zero if the two are indistinguishable. */
00217 AUD_VFUNC2 (playlist_sort_by_filename, int, playlist,
00218  PlaylistStringCompareFunc, compare)
00219 
00220 /* Sorts the entries in a playlist based on tuple.  May fail if metadata
00221  * scanning is still in progress (or has been disabled). */
00222 AUD_VFUNC2 (playlist_sort_by_tuple, int, playlist,
00223  PlaylistTupleCompareFunc, compare)
00224 
00225 /* Sorts the entries in a playlist based on formatted title string.  May fail if
00226  * metadata scanning is still in progress (or has been disabled). */
00227 AUD_VFUNC2 (playlist_sort_by_title, int, playlist,
00228  PlaylistStringCompareFunc, compare)
00229 
00230 /* Sorts only the selected entries in a playlist based on filename. */
00231 AUD_VFUNC2 (playlist_sort_selected_by_filename, int, playlist,
00232  PlaylistStringCompareFunc, compare)
00233 
00234 /* Sorts only the selected entries in a playlist based on tuple.  May fail if
00235  * metadata scanning is still in progress (or has been disabled). */
00236 AUD_VFUNC2 (playlist_sort_selected_by_tuple, int, playlist,
00237  PlaylistTupleCompareFunc, compare)
00238 
00239 /* Sorts only the selected entries in a playlist based on formatted title
00240  * string.  May fail if metadata scanning is still in progress (or has been
00241  * disabled). */
00242 AUD_VFUNC2 (playlist_sort_selected_by_title, int, playlist,
00243  PlaylistStringCompareFunc, compare)
00244 
00245 /* Reverses the order of the entries in a playlist. */
00246 AUD_VFUNC1 (playlist_reverse, int, playlist)
00247 
00248 /* Reorders the entries in a playlist randomly. */
00249 AUD_VFUNC1 (playlist_randomize, int, playlist)
00250 
00251 /* Discards the metadata stored for all the entries in a playlist and starts
00252  * reading it afresh from the song files in the background. */
00253 AUD_VFUNC1 (playlist_rescan, int, playlist)
00254 
00255 /* Like playlist_rescan, but applies only to the selected entries in a playlist. */
00256 AUD_VFUNC1 (playlist_rescan_selected, int, playlist)
00257 
00258 /* Discards the metadata stored for all the entries that refer to a particular
00259  * song file, in whatever playlist they appear, and starts reading it afresh
00260  * from that file in the background. */
00261 AUD_VFUNC1 (playlist_rescan_file, const char *, filename)
00262 
00263 /* Calculates the total length in milliseconds of all the entries in a playlist.
00264  * Only takes into account entries for which metadata has already been read. */
00265 AUD_FUNC1 (int64_t, playlist_get_total_length, int, playlist)
00266 
00267 /* Calculates the total length in milliseconds of only the selected entries in a
00268  * playlist.  Only takes into account entries for which metadata has already
00269  * been read. */
00270 AUD_FUNC1 (int64_t, playlist_get_selected_length, int, playlist)
00271 
00272 /* Returns the number of entries in a playlist queue.  The entries are numbered
00273  * starting from zero, lower numbers being played first. */
00274 AUD_FUNC1 (int, playlist_queue_count, int, playlist)
00275 
00276 /* Adds an entry to a playlist's queue before the entry numbered <at> in the
00277  * queue.  If <at> is negative or equal to the number of entries in the queue,
00278  * adds the entry after the last one in the queue.  The same entry cannot be
00279  * added to the queue more than once. */
00280 AUD_VFUNC3 (playlist_queue_insert, int, playlist, int, at, int, entry)
00281 
00282 /* Adds the selected entries in a playlist to the queue, if they are not already
00283  * in it. */
00284 AUD_VFUNC2 (playlist_queue_insert_selected, int, playlist, int, at)
00285 
00286 /* Returns the position in the playlist of the entry at a given position in the
00287  * queue. */
00288 AUD_FUNC2 (int, playlist_queue_get_entry, int, playlist, int, at)
00289 
00290 /* Returns the position in the queue of the entry at a given position in the
00291  * playlist.  If it is not in the queue, returns -1. */
00292 AUD_FUNC2 (int, playlist_queue_find_entry, int, playlist, int, entry)
00293 
00294 /* Removes a contiguous block of <number> entries starting with the one numbered
00295  * <at> from the queue. */
00296 AUD_VFUNC3 (playlist_queue_delete, int, playlist, int, at, int, number)
00297 
00298 /* Removes the selected entries in a playlist from the queue, if they are in it. */
00299 AUD_VFUNC1 (playlist_queue_delete_selected, int, playlist)
00300 
00301 /* Returns nonzero if a "playlist update" hook call is pending.  If called from
00302  * within the hook, the current hook call is not considered pending. */
00303 AUD_FUNC0 (bool_t, playlist_update_pending)
00304 
00305 /* May be called within the "playlist update" hook to determine the update level
00306  * and number of entries changed in a playlist.  Returns the update level for
00307  * the playlist, storing the number of the first entry changed in <at> and the
00308  * number of contiguous entries to be updated in <count>.  Note that entries may
00309  * have been added or removed within this range.  If no entries in the playlist
00310  * have changed, returns zero. */
00311 AUD_FUNC3 (int, playlist_updated_range, int, playlist, int *, at, int *, count)
00312 
00313 /* Returns nonzero if entries are being added to a playlist in the background. */
00314 AUD_FUNC1 (bool_t, playlist_add_in_progress, int, playlist)
00315 
00316 /* Returns nonzero if entries in a playlist are being scanned for metadata in
00317  * the background. */
00318 AUD_FUNC1 (bool_t, playlist_scan_in_progress, int, playlist)
00319 
00320 /* --- PLAYLIST UTILITY API --- */
00321 
00322 /* Sorts the entries in a playlist according to one of the schemes listed in
00323  * playlist.h. */
00324 AUD_VFUNC2 (playlist_sort_by_scheme, int, playlist, int, scheme)
00325 
00326 /* Sorts only the selected entries in a playlist according to one of those
00327  * schemes. */
00328 AUD_VFUNC2 (playlist_sort_selected_by_scheme, int, playlist, int, scheme)
00329 
00330 /* Removes duplicate entries in a playlist according to one of those schemes.
00331  * As currently implemented, first sorts the playlist. */
00332 AUD_VFUNC2 (playlist_remove_duplicates_by_scheme, int, playlist, int,
00333  scheme)
00334 
00335 /* Removes all entries referring to unavailable files in a playlist.  ("Remove
00336  * failed" is something of a misnomer for the current behavior.)  As currently
00337  * implemented, only works for file:// URIs. */
00338 AUD_VFUNC1 (playlist_remove_failed, int, playlist)
00339 
00340 /* Selects all the entries in a playlist that match regular expressions stored
00341  * in the fields of a tuple.  Does not free the memory used by the tuple.
00342  * Example: To select all the songs whose title starts with the letter "A",
00343  * create a blank tuple and set its title field to "^A". */
00344 AUD_VFUNC2 (playlist_select_by_patterns, int, playlist, const Tuple *,
00345  patterns)
00346 
00347 /* Returns nonzero if <filename> refers to a playlist file. */
00348 AUD_FUNC1 (bool_t, filename_is_playlist, const char *, filename)
00349 
00350 /* Saves the entries in a playlist to a playlist file.  The format of the file
00351  * is determined from the file extension.  Returns nonzero on success. */
00352 AUD_FUNC2 (bool_t, playlist_save, int, playlist, const char *, filename)