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