src/libmpd-playlist.h

   1 /* libmpd (high level libmpdclient library)
   2  * Copyright (C) 2004-2009 Qball Cow <qball@sarine.nl>
   3  * Project homepage: http://gmpcwiki.sarine.nl/
   4
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  18 */
  19
  20 #ifndef __MPD_LIB_PLAYLIST__
  21 #define __MPD_LIB_PLAYLIST__
  22
  23 /**
  24  * \defgroup Playlist Playlist
  25  */
  26 /*@{*/
  27
  28
  29 /**
  30  * mpd_playlist_get_playlist_id
  31  * @param mi a #MpdObj
  32  *
  33  * Returns the id of the current playlist
  34  *
  35  * @returns a long long
  36  */
  37 long long       mpd_playlist_get_playlist_id            (MpdObj *mi);
  38
  39
  40 /**
  41  * @param mi a #MpdObj
  42  *
  43  * Returns the id of the previous playlist
  44  *
  45  * @returns a long long
  46  */
  47 long long       mpd_playlist_get_old_playlist_id         (MpdObj *mi);
  48
  49
  50 /**
  51  * @param mi a #MpdObj
  52  * @param songid a SongId
  53  *
  54  * returns the mpd_Song for playlist entry with songid.
  55  *
  56  * @returns a mpd_Song
  57  */
  58 mpd_Song *      mpd_playlist_get_song                   (MpdObj *mi, int songid);
  59
  60
  61 /**
  62  * @param mi a #MpdObj
  63  * @param songpos a Songpos
  64  *
  65  * returns the mpd_Song for playlist entry with songpos.
  66  *
  67  * @returns a mpd_Song
  68  */
  69
  70 mpd_Song * mpd_playlist_get_song_from_pos(MpdObj *mi, int songpos);
  71
  72
  73 /**
  74  * @param mi a #MpdObj
  75  * @param start a Songpos
  76  * @param stop  a Songpos
  77  *
  78  * returns the MpdData list with song from the playlist from pos start until stop.
  79  * so start = 0, stop = 5 will return song 0,1,2,3,4,5.
  80  *
  81  * @returns a MdpData
  82  */
  83 MpdData * mpd_playlist_get_song_from_pos_range(MpdObj *mi, int start, int stop);
  84
  85
  86 /**
  87  * @param mi a #MpdObj
  88  *
  89  * returns the mpd_Song for the currently playing song
  90  *
  91  * @returns a mpd_Song, this is an internally cached version, and should not be freed. It's also not guaranteed to stay valid (it will be inside the same function if no other mpd_* function gets called.)
  92  * if you need to keep it around, make a copy.
  93  */
  94 mpd_Song *      mpd_playlist_get_current_song           (MpdObj *mi);
  95
  96
  97 /**
  98  * mpd_playlist_clear
  99  * @param mi a #MpdObj
 100  *
 101  * Clears the playlist
 102  *
 103  * @returns 0 on success or #MpdError on error.
 104  */
 105 int             mpd_playlist_clear                      (MpdObj *mi);
 106
 107
 108 /**
 109  * @param mi a #MpdObj
 110  *
 111  * Shuffles the order of the playlist, this is different than playing random
 112  *
 113  * @returns 0 on success or #MpdError on error.
 114  */
 115 int             mpd_playlist_shuffle                    (MpdObj *mi);
 116
 117
 118 /**
 119  * @param mi a #MpdObj
 120  * @param old_pos The current position in the playlist
 121  * @param new_pos The new position in the playlist.
 122  *
 123  * Moves a song in the playlist. This uses the position of the song, not the id
 124  * @returns a #MpdError
 125  */
 126 int             mpd_playlist_move_pos           (MpdObj *mi, int old_pos, int new_pos);
 127
 128
 129 /**
 130  * @param mi a #MpdObj
 131  * @param old_id The id of the song to move
 132  * @param new_id The id of the song to move too.
 133  *
 134  * Moves a song in the playlist. This uses the id of the song, not the position
 135  * @returns a #MpdError
 136  */
 137 int             mpd_playlist_move_id            (MpdObj *mi, int old_id, int new_id);
 138
 139
 140 /**
 141  * @param mi a #MpdObj
 142  * @param old_playlist_id The id of the old playlist you want to get the changes with.
 143  *
 144  * Gets a list of songs that changed between the current and the old playlist
 145  *
 146  * @returns a #MpdData list
 147  */
 148 MpdData *       mpd_playlist_get_changes                (MpdObj *mi,int old_playlist_id);
 149
 150 /**
 151  * @param mi a #MpdObj
 152  * @param old_playlist_id The id of the old playlist you want to get the changes with.
 153  *
 154  * Gets a list of the song id/pos that changed between the current and the old playlist
 155  * Check if this command is available.
 156  *
 157  * @returns a #MpdData list
 158  */
 159 MpdData * mpd_playlist_get_changes_posid(MpdObj *mi,int old_playlist_id);
 160
 161
 162 /**
 163  * @param mi    a #MpdObj
 164  *
 165  * @returns The number of songs in the current playlist.
 166  */
 167 int             mpd_playlist_get_playlist_length        (MpdObj *mi);
 168
 169 /**
 170  * @param mi a #MpdObj
 171  * @param path the path of the song to be added.
 172  *
 173  * Adds a song to the playlist, use #mpd_playlist_queue_add to add multiple songs.
 174  *
 175  * @returns a #MpdError
 176  */
 177 int             mpd_playlist_add                        (MpdObj *mi,const char *path);
 178
 179 /**
 180  * @param mi a #MpdObj
 181  * @param songid a song id.
 182  *
 183  * Deletes a single song by it's id.
 184  *
 185  * @returns a #MpdError
 186  */
 187 int mpd_playlist_delete_id(MpdObj *mi, int songid);
 188
 189 /**
 190  * @param mi a #MpdObj
 191  * @param songpos a song pos.
 192  *
 193  * Deletes a single song by it's position.
 194  *
 195  * @returns a #MpdError
 196  */
 197 int mpd_playlist_delete_pos(MpdObj *mi, int songpos);
 198
 199 /**
 200  * @param mi a #MpdObj
 201  * @param path a path to a song
 202  *
 203  * Add a single path and return the id
 204  * Only use this to add a single song, if you need to add multiple songs,
 205  * use the #mpd_playlist_queue_add for improved performance
 206  *
 207  * @returns a #MpdError or the songid of the added song
 208  */
 209
 210 int mpd_playlist_add_get_id(MpdObj *mi,const char *path);
 211
 212 /*@}*/
 213
 214
 215 /** \defgroup comqueue Command Queue
 216  * \ingroup Playlist
 217  * These functions allow you to queue commands, and send them
 218  * in one command list to mpd. This is very efficient.
 219  * It's advised to use these for large deletions and additions.
 220  * These functions don't cause an extra overhead compared to the non_queue functions.
 221  * Because the non_queue functions just wrap the following.
 222  */
 223 /*@{*/
 224
 225 /**
 226  * @param mi a #MpdObj
 227  * @param path The path to a song to add
 228  *
 229  * This queues an add command. The actual add isn't done until #mpd_playlist_queue_commit is called
 230  *
 231  * @returns a #MpdError
 232  */
 233 int     mpd_playlist_queue_add          (MpdObj *mi,const char *path);
 234
 235
 236
 237 /**
 238  * @param mi a #MpdObj
 239  * @param path The path to a playlist to load
 240  *
 241  * This queues a load command. The actual load isn't done until #mpd_playlist_queue_commit is called
 242  *
 243  * @returns a #MpdError
 244  */
 245 int     mpd_playlist_queue_load         (MpdObj *mi,const char *path);
 246
 247
 248 /**
 249  * @param mi a #MpdObj
 250  * @param id The songid of the song you want to delete
 251  *
 252  * This queues a delete song from playlist command. The actually delete isn't done until #mpd_playlist_queue_commit is called
 253  * @returns a #MpdError
 254  */
 255 int     mpd_playlist_queue_delete_id    (MpdObj *mi,int id);
 256
 257
 258 /**
 259  * @param mi a #MpdObj
 260  * @param songpos a song pos.
 261  *
 262  * Queues the deletion of a single song by it's position.
 263  *
 264  * @returns a #MpdError
 265  */
 266 int     mpd_playlist_queue_delete_pos   (MpdObj *mi,int songpos);
 267
 268
 269 /**
 270  * @param mi a #MpdObj
 271  *
 272  * Commits the queue'd commands in a command list. This is an efficient way of doing a lot of adds/removes.
 273  *
 274  * @returns a #MpdError
 275  */
 276 int     mpd_playlist_queue_commit               (MpdObj *mi);
 277
 278 /*@}*/
 279
 280 /** \defgroup playlistsearch Playlist Search
 281  * \ingroup Playlist
 282  *      Allow server side search of the current playlist.
 283  */
 284 /*@{*/
 285
 286 /**
 287  * @param mi a #MpdObj
 288  * @param exact if #TRUE only return exact matches
 289  *
 290  * Starts a playlist search. Add constraints using #mpd_playlist_search_add_constraint
 291  * And execute the search with #mpd_playlist_search_commit
 292  *
 293  */
 294 void mpd_playlist_search_start(MpdObj *mi, int exact);
 295
 296 /**
 297  * @param mi a #MpdObj
 298  *
 299  * Executes the playlist search. This needs to be started with #mpd_playlist_search_start
 300  *
 301  * @returns a #MpdData list
 302  */
 303 MpdData * mpd_playlist_search_commit(MpdObj *mi);
 304
 305 /**
 306  * @param mi A #MpdObj
 307  * @param field A #mpd_TagItems
 308  * @param value a string to match the field against
 309  *
 310  * Adds a constraint to the playlist search.
 311  */
 312 void mpd_playlist_search_add_constraint(MpdObj *mi, mpd_TagItems field, const char *value);
 313
 314 /*@}*/
 315
 316 /** \defgroup playlistqueue Playlist Queue
 317  * \ingroup Playlist
 318  *      Allow control of MPD new queue system
 319  */
 320 /*@{*/
 321
 322
 323
 324 /**
 325  * @param mi a #MpdObj
 326  * @param path The path to a playlist to load
 327  *
 328  * This queues a load command. The actual load isn't done until #mpd_playlist_queue_commit is called
 329  *
 330  * @returns a #MpdError
 331  */
 332 int     mpd_playlist_load               (MpdObj *mi,const char *path);
 333
 334 int mpd_playlist_set_priority(MpdObj *mi, int song_id, int priority);
 335 /*@}*/
 336
 337 #endif