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