• Main Page
  • Related Pages
  • Classes
  • Files
  • File List
  • File Members

playlist-api.h

Go to the documentation of this file.
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)

Generated on Wed Apr 6 2011 for Audacious by  doxygen 1.7.1