1 /* libmpd (high level libmpdclient library)
2 * Copyright (C) 2004-2009 Qball Cow <qball@sarine.nl>
3 * Project homepage: http://gmpcwiki.sarine.nl/
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.
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.
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.
20 #ifndef __MPD_LIB_PLAYLIST__
21 #define __MPD_LIB_PLAYLIST__
24 * \defgroup Playlist Playlist
30 * mpd_playlist_get_playlist_id
33 * Returns the id of the current playlist
35 * @returns a long long
37 long long mpd_playlist_get_playlist_id (MpdObj
*mi
);
43 * Returns the id of the previous playlist
45 * @returns a long long
47 long long mpd_playlist_get_old_playlist_id (MpdObj
*mi
);
52 * @param songid a SongId
54 * returns the mpd_Song for playlist entry with songid.
58 mpd_Song
* mpd_playlist_get_song (MpdObj
*mi
, int songid
);
63 * @param songpos a Songpos
65 * returns the mpd_Song for playlist entry with songpos.
70 mpd_Song
* mpd_playlist_get_song_from_pos(MpdObj
*mi
, int songpos
);
75 * @param start a Songpos
76 * @param stop a Songpos
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.
83 MpdData
* mpd_playlist_get_song_from_pos_range(MpdObj
*mi
, int start
, int stop
);
89 * returns the mpd_Song for the currently playing song
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.
94 mpd_Song
* mpd_playlist_get_current_song (MpdObj
*mi
);
101 * Clears the playlist
103 * @returns 0 on success or #MpdError on error.
105 int mpd_playlist_clear (MpdObj
*mi
);
109 * @param mi a #MpdObj
111 * Shuffles the order of the playlist, this is different than playing random
113 * @returns 0 on success or #MpdError on error.
115 int mpd_playlist_shuffle (MpdObj
*mi
);
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.
123 * Moves a song in the playlist. This uses the position of the song, not the id
124 * @returns a #MpdError
126 int mpd_playlist_move_pos (MpdObj
*mi
, int old_pos
, int new_pos
);
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.
134 * Moves a song in the playlist. This uses the id of the song, not the position
135 * @returns a #MpdError
137 int mpd_playlist_move_id (MpdObj
*mi
, int old_id
, int new_id
);
141 * @param mi a #MpdObj
142 * @param old_playlist_id The id of the old playlist you want to get the changes with.
144 * Gets a list of songs that changed between the current and the old playlist
146 * @returns a #MpdData list
148 MpdData
* mpd_playlist_get_changes (MpdObj
*mi
,int old_playlist_id
);
151 * @param mi a #MpdObj
152 * @param old_playlist_id The id of the old playlist you want to get the changes with.
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.
157 * @returns a #MpdData list
159 MpdData
* mpd_playlist_get_changes_posid(MpdObj
*mi
,int old_playlist_id
);
163 * @param mi a #MpdObj
165 * @returns The number of songs in the current playlist.
167 int mpd_playlist_get_playlist_length (MpdObj
*mi
);
170 * @param mi a #MpdObj
171 * @param path the path of the song to be added.
173 * Adds a song to the playlist, use #mpd_playlist_queue_add to add multiple songs.
175 * @returns a #MpdError
177 int mpd_playlist_add (MpdObj
*mi
,const char *path
);
180 * @param mi a #MpdObj
181 * @param songid a song id.
183 * Deletes a single song by it's id.
185 * @returns a #MpdError
187 int mpd_playlist_delete_id(MpdObj
*mi
, int songid
);
190 * @param mi a #MpdObj
191 * @param songpos a song pos.
193 * Deletes a single song by it's position.
195 * @returns a #MpdError
197 int mpd_playlist_delete_pos(MpdObj
*mi
, int songpos
);
200 * @param mi a #MpdObj
201 * @param path a path to a song
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
207 * @returns a #MpdError or the songid of the added song
210 int mpd_playlist_add_get_id(MpdObj
*mi
,const char *path
);
215 /** \defgroup comqueue Command Queue
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.
226 * @param mi a #MpdObj
227 * @param path The path to a song to add
229 * This queues an add command. The actual add isn't done until #mpd_playlist_queue_commit is called
231 * @returns a #MpdError
233 int mpd_playlist_queue_add (MpdObj
*mi
,const char *path
);
238 * @param mi a #MpdObj
239 * @param path The path to a playlist to load
241 * This queues a load command. The actual load isn't done until #mpd_playlist_queue_commit is called
243 * @returns a #MpdError
245 int mpd_playlist_queue_load (MpdObj
*mi
,const char *path
);
249 * @param mi a #MpdObj
250 * @param id The songid of the song you want to delete
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
255 int mpd_playlist_queue_delete_id (MpdObj
*mi
,int id
);
259 * @param mi a #MpdObj
260 * @param songpos a song pos.
262 * Queues the deletion of a single song by it's position.
264 * @returns a #MpdError
266 int mpd_playlist_queue_delete_pos (MpdObj
*mi
,int songpos
);
270 * @param mi a #MpdObj
272 * Commits the queue'd commands in a command list. This is an efficient way of doing a lot of adds/removes.
274 * @returns a #MpdError
276 int mpd_playlist_queue_commit (MpdObj
*mi
);
280 /** \defgroup playlistsearch Playlist Search
282 * Allow server side search of the current playlist.
287 * @param mi a #MpdObj
288 * @param exact if #TRUE only return exact matches
290 * Starts a playlist search. Add constraints using #mpd_playlist_search_add_constraint
291 * And execute the search with #mpd_playlist_search_commit
294 void mpd_playlist_search_start(MpdObj
*mi
, int exact
);
297 * @param mi a #MpdObj
299 * Executes the playlist search. This needs to be started with #mpd_playlist_search_start
301 * @returns a #MpdData list
303 MpdData
* mpd_playlist_search_commit(MpdObj
*mi
);
306 * @param mi A #MpdObj
307 * @param field A #mpd_TagItems
308 * @param value a string to match the field against
310 * Adds a constraint to the playlist search.
312 void mpd_playlist_search_add_constraint(MpdObj
*mi
, mpd_TagItems field
, const char *value
);
316 /** \defgroup playlistqueue Playlist Queue
318 * Allow control of MPD new queue system
325 * @param mi a #MpdObj
326 * @param path The path to a playlist to load
328 * This queues a load command. The actual load isn't done until #mpd_playlist_queue_commit is called
330 * @returns a #MpdError
332 int mpd_playlist_load (MpdObj
*mi
,const char *path
);
334 int mpd_playlist_set_priority(MpdObj
*mi
, int song_id
, int priority
);