1 /* libmpdclient
2 * (c)2003-2004 by Warren Dukes (shank@mercury.chem.pitt.edu)
3 * This project's homepage is: http://www.musicpd.org
4 *
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2.1 of the License, or (at your option) any later version.
9 *
10 * This library 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 Lesser General Public License for more details.
14 *
15 * You should have received a copy of the GNU Lesser General Public
16 * License along with this program; if not, write to the Free Software
17 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
18 */
20 #ifndef LIBMPDCLIENT_H
21 #define LIBMPDCLIENT_H
23 #include <sys/time.h>
25 #define MPD_BUFFER_MAX_LENGTH 50000
26 #define MPD_WELCOME_MESSAGE "OK MPD "
28 #define MPD_ERROR_TIMEOUT 10 /* timeout trying to talk to mpd */
29 #define MPD_ERROR_SYSTEM 11 /* system error */
30 #define MPD_ERROR_UNKHOST 12 /* unknown host */
31 #define MPD_ERROR_CONNPORT 13 /* problems connecting to port on host */
32 #define MPD_ERROR_NOTMPD 14 /* mpd not running on port at host */
33 #define MPD_ERROR_NORESPONSE 15 /* no response on attempting to connect */
34 #define MPD_ERROR_SENDING 16 /* error sending command */
35 #define MPD_ERROR_CONNCLOSED 17 /* connection closed by mpd */
36 #define MPD_ERROR_ACK 18 /* ACK returned! */
37 #define MPD_ERROR_BUFFEROVERRUN 19 /* Buffer was overrun! */
39 #define MPD_ACK_ERROR_UNK -1
40 #define MPD_ERROR_AT_UNK -1
42 #define MPD_ACK_ERROR_NOT_LIST 1
43 #define MPD_ACK_ERROR_ARG 2
44 #define MPD_ACK_ERROR_PASSWORD 3
45 #define MPD_ACK_ERROR_PERMISSION 4
46 #define MPD_ACK_ERROR_UNKNOWN_CMD 5
48 #define MPD_ACK_ERROR_NO_EXIST 50
49 #define MPD_ACK_ERROR_PLAYLIST_MAX 51
50 #define MPD_ACK_ERROR_SYSTEM 52
51 #define MPD_ACK_ERROR_PLAYLIST_LOAD 53
52 #define MPD_ACK_ERROR_UPDATE_ALREADY 54
53 #define MPD_ACK_ERROR_PLAYER_SYNC 55
54 #define MPD_ACK_ERROR_EXIST 56
56 #ifdef __cplusplus
57 extern "C" {
58 #endif
60 /* internal stuff don't touch this struct */
61 typedef struct _mpd_ReturnElement {
62 char * name;
63 char * value;
64 } mpd_ReturnElement;
66 /* mpd_Connection
67 * holds info about connection to mpd
68 * use error, and errorStr to detect errors
69 */
70 typedef struct _mpd_Connection {
71 /* use this to check the version of mpd */
72 int version[3];
73 /* IMPORTANT, you want to get the error messages from here */
74 char errorStr[MPD_BUFFER_MAX_LENGTH+1];
75 int errorCode;
76 int errorAt;
77 /* this will be set to MPD_ERROR_* if there is an error, 0 if not */
78 int error;
79 /* DON'T TOUCH any of the rest of this stuff */
80 int sock;
81 char buffer[MPD_BUFFER_MAX_LENGTH+1];
82 int buflen;
83 int bufstart;
84 int doneProcessing;
85 int listOks;
86 int doneListOk;
87 int commandList;
88 mpd_ReturnElement * returnElement;
89 struct timeval timeout;
90 } mpd_Connection;
92 /* mpd_newConnection
93 * use this to open a new connection
94 * you should use mpd_closeConnection, when your done with the connection,
95 * even if an error has occurred
96 * _timeout_ is the connection timeout period in seconds
97 */
98 mpd_Connection * mpd_newConnection(const char * host, int port, float timeout);
100 void mpd_setConnectionTimeout(mpd_Connection * connection, float timeout);
102 /* mpd_closeConnection
103 * use this to close a connection and free'ing subsequent memory
104 */
105 void mpd_closeConnection(mpd_Connection * connection);
107 /* mpd_clearError
108 * clears error
109 */
110 void mpd_clearError(mpd_Connection * connection);
112 /* STATUS STUFF */
114 /* use these with status.state to determine what state the player is in */
115 #define MPD_STATUS_STATE_UNKNOWN 0
116 #define MPD_STATUS_STATE_STOP 1
117 #define MPD_STATUS_STATE_PLAY 2
118 #define MPD_STATUS_STATE_PAUSE 3
120 /* us this with status.volume to determine if mpd has volume support */
121 #define MPD_STATUS_NO_VOLUME -1
123 /* mpd_Status
124 * holds info return from status command
125 */
126 typedef struct mpd_Status {
127 /* 0-100, or MPD_STATUS_NO_VOLUME when there is no volume support */
128 int volume;
129 /* 1 if repeat is on, 0 otherwise */
130 int repeat;
131 /* 1 if random is on, 0 otherwise */
132 int random;
133 /* playlist length */
134 int playlistLength;
135 /* playlist, use this to determine when the playlist has changed */
136 long long playlist;
137 /* use with MPD_STATUS_STATE_* to determine state of player */
138 int state;
139 /* crossfade setting in seconds */
140 int crossfade;
141 /* if a song is currently selected (always the case when state is
142 * PLAY or PAUSE), this is the position of the currently
143 * playing song in the playlist, beginning with 0
144 */
145 int song;
146 /* Song ID of the currently selected song */
147 int songid;
148 /* time in seconds that have elapsed in the currently playing/paused
149 * song
150 */
151 int elapsedTime;
152 /* length in seconds of the currently playing/paused song */
153 int totalTime;
154 /* current bit rate in kbs */
155 int bitRate;
156 /* audio sample rate */
157 unsigned int sampleRate;
158 /* audio bits */
159 int bits;
160 /* audio channels */
161 int channels;
162 /* 1 if mpd is updating, 0 otherwise */
163 int updatingDb;
164 /* error */
165 char * error;
166 } mpd_Status;
168 void mpd_sendStatusCommand(mpd_Connection * connection);
170 /* mpd_getStatus
171 * returns status info, be sure to free it with mpd_freeStatus()
172 * call this after mpd_sendStatusCommand()
173 */
174 mpd_Status * mpd_getStatus(mpd_Connection * connection);
176 /* mpd_freeStatus
177 * free's status info malloc'd and returned by mpd_getStatus
178 */
179 void mpd_freeStatus(mpd_Status * status);
181 typedef struct _mpd_Stats {
182 int numberOfArtists;
183 int numberOfAlbums;
184 int numberOfSongs;
185 unsigned long uptime;
186 unsigned long dbUpdateTime;
187 unsigned long playTime;
188 unsigned long dbPlayTime;
189 } mpd_Stats;
191 void mpd_sendStatsCommand(mpd_Connection * connection);
193 mpd_Stats * mpd_getStats(mpd_Connection * connection);
195 void mpd_freeStats(mpd_Stats * stats);
197 /* SONG STUFF */
199 #define MPD_SONG_NO_TIME -1
200 #define MPD_SONG_NO_NUM -1
201 #define MPD_SONG_NO_ID -1
203 /* mpd_Song
204 * for storing song info returned by mpd
205 */
206 typedef struct _mpd_Song {
207 /* filename of song */
208 char * file;
209 /* artist, maybe NULL if there is no tag */
210 char * artist;
211 /* title, maybe NULL if there is no tag */
212 char * title;
213 /* album, maybe NULL if there is no tag */
214 char * album;
215 /* track, maybe NULL if there is no tag */
216 char * track;
217 /* name, maybe NULL if there is no tag; it's the name of the current
218 * song, f.e. the icyName of the stream */
219 char * name;
220 /* length of song in seconds, check that it is not MPD_SONG_NO_TIME */
221 int time;
222 /* if plchanges/playlistinfo/playlistid used, is the position of the
223 * song in the playlist */
224 int pos;
225 /* song id for a song in the playlist */
226 int id;
227 } mpd_Song;
229 /* mpd_newSong
230 * use to allocate memory for a new mpd_Song
231 * file, artist, etc all initialized to NULL
232 * if your going to assign values to file, artist, etc
233 * be sure to malloc or strdup the memory
234 * use mpd_freeSong to free the memory for the mpd_Song, it will also
235 * free memory for file, artist, etc, so don't do it yourself
236 */
237 mpd_Song * mpd_newSong();
239 /* mpd_freeSong
240 * use to free memory allocated by mpd_newSong
241 * also it will free memory pointed to by file, artist, etc, so be careful
242 */
243 void mpd_freeSong(mpd_Song * song);
245 /* mpd_songDup
246 * works like strDup, but for a mpd_Song
247 */
248 mpd_Song * mpd_songDup(mpd_Song * song);
250 /* DIRECTORY STUFF */
252 /* mpd_Directory
253 * used to store info fro directory (right now that just the path)
254 */
255 typedef struct _mpd_Directory {
256 char * path;
257 } mpd_Directory;
259 /* mpd_newDirectory
260 * allocates memory for a new directory
261 * use mpd_freeDirectory to free this memory
262 */
263 mpd_Directory * mpd_newDirectory ();
265 /* mpd_freeDirectory
266 * used to free memory allocated with mpd_newDirectory, and it frees
267 * path of mpd_Directory, so be careful
268 */
269 void mpd_freeDirectory(mpd_Directory * directory);
271 /* mpd_directoryDup
272 * works like strdup, but for mpd_Directory
273 */
274 mpd_Directory * mpd_directoryDup(mpd_Directory * directory);
276 /* PLAYLISTFILE STUFF */
278 /* mpd_PlaylistFile
279 * stores info about playlist file returned by lsinfo
280 */
281 typedef struct _mpd_PlaylistFile {
282 char * path;
283 } mpd_PlaylistFile;
285 /* mpd_newPlaylistFile
286 * allocates memory for new mpd_PlaylistFile, path is set to NULL
287 * free this memory with mpd_freePlaylistFile
288 */
289 mpd_PlaylistFile * mpd_newPlaylistFile();
291 /* mpd_freePlaylist
292 * free memory allocated for freePlaylistFile, will also free
293 * path, so be careful
294 */
295 void mpd_freePlaylistFile(mpd_PlaylistFile * playlist);
297 /* mpd_playlistFileDup
298 * works like strdup, but for mpd_PlaylistFile
299 */
300 mpd_PlaylistFile * mpd_playlistFileDup(mpd_PlaylistFile * playlist);
302 /* INFO ENTITY STUFF */
304 /* the type of entity returned from one of the commands that generates info
305 * use in conjunction with mpd_InfoEntity.type
306 */
307 #define MPD_INFO_ENTITY_TYPE_DIRECTORY 0
308 #define MPD_INFO_ENTITY_TYPE_SONG 1
309 #define MPD_INFO_ENTITY_TYPE_PLAYLISTFILE 2
311 /* mpd_InfoEntity
312 * stores info on stuff returned info commands
313 */
314 typedef struct mpd_InfoEntity {
315 /* the type of entity, use with MPD_INFO_ENTITY_TYPE_* to determine
316 * what this entity is (song, directory, etc...)
317 */
318 int type;
319 /* the actual data you want, mpd_Song, mpd_Directory, etc */
320 union {
321 mpd_Directory * directory;
322 mpd_Song * song;
323 mpd_PlaylistFile * playlistFile;
324 } info;
325 } mpd_InfoEntity;
327 mpd_InfoEntity * mpd_newInfoEntity();
329 void mpd_freeInfoEntity(mpd_InfoEntity * entity);
331 /* INFO COMMANDS AND STUFF */
333 /* use this function to loop over after calling Info/Listall functions */
334 mpd_InfoEntity * mpd_getNextInfoEntity(mpd_Connection * connection);
336 /* fetches the currently seeletect song (the song referenced by status->song
337 * and status->songid*/
338 void mpd_sendCurrentSongCommand(mpd_Connection * connection);
340 /* songNum of -1, means to display the whole list */
341 void mpd_sendPlaylistInfoCommand(mpd_Connection * connection, int songNum);
343 /* use this to get the changes in the playlist since version _playlist_ */
344 void mpd_sendPlChangesCommand(mpd_Connection * connection, long long playlist);
346 /* recursivel fetches all songs/dir/playlists in "dir* (no metadata is
347 * returned) */
348 void mpd_sendListallCommand(mpd_Connection * connection, const char * dir);
350 /* same as sendListallCommand, but also metadata is returned */
351 void mpd_sendListallInfoCommand(mpd_Connection * connection, const char * dir);
353 /* non-recursive version of ListallInfo */
354 void mpd_sendLsInfoCommand(mpd_Connection * connection, const char * dir);
356 #define MPD_TABLE_ARTIST 0
357 #define MPD_TABLE_ALBUM 1
358 #define MPD_TABLE_TITLE 2
359 #define MPD_TABLE_FILENAME 3
361 void mpd_sendSearchCommand(mpd_Connection * connection, int table,
362 const char * str);
364 void mpd_sendFindCommand(mpd_Connection * connection, int table,
365 const char * str);
367 /* LIST TAG COMMANDS */
369 /* use this function fetch next artist entry, be sure to free the returned
370 * string. NULL means there are no more. Best used with sendListArtists
371 */
372 char * mpd_getNextArtist(mpd_Connection * connection);
374 char * mpd_getNextAlbum(mpd_Connection * connection);
376 /* list artist or albums by artist, arg1 should be set to the artist if
377 * listing albums by a artist, otherwise NULL for listing all artists or albums
378 */
379 void mpd_sendListCommand(mpd_Connection * connection, int table,
380 const char * arg1);
382 /* SIMPLE COMMANDS */
384 void mpd_sendAddCommand(mpd_Connection * connection, const char * file);
386 void mpd_sendDeleteCommand(mpd_Connection * connection, int songNum);
388 void mpd_sendDeleteIdCommand(mpd_Connection * connection, int songNum);
390 void mpd_sendSaveCommand(mpd_Connection * connection, const char * name);
392 void mpd_sendLoadCommand(mpd_Connection * connection, const char * name);
394 void mpd_sendRmCommand(mpd_Connection * connection, const char * name);
396 void mpd_sendShuffleCommand(mpd_Connection * connection);
398 void mpd_sendClearCommand(mpd_Connection * connection);
400 /* use this to start playing at the beginning, useful when in random mode */
401 #define MPD_PLAY_AT_BEGINNING -1
403 void mpd_sendPlayCommand(mpd_Connection * connection, int songNum);
405 void mpd_sendPlayIdCommand(mpd_Connection * connection, int songNum);
407 void mpd_sendStopCommand(mpd_Connection * connection);
409 void mpd_sendPauseCommand(mpd_Connection * connection, int pauseMode);
411 void mpd_sendNextCommand(mpd_Connection * connection);
413 void mpd_sendPrevCommand(mpd_Connection * connection);
415 void mpd_sendMoveCommand(mpd_Connection * connection, int from, int to);
417 void mpd_sendMoveIdCommand(mpd_Connection * connection, int from, int to);
419 void mpd_sendSwapCommand(mpd_Connection * connection, int song1, int song2);
421 void mpd_sendSwapIdCommand(mpd_Connection * connection, int song1, int song2);
423 void mpd_sendSeekCommand(mpd_Connection * connection, int song, int time);
425 void mpd_sendSeekIdCommand(mpd_Connection * connection, int song, int time);
427 void mpd_sendRepeatCommand(mpd_Connection * connection, int repeatMode);
429 void mpd_sendRandomCommand(mpd_Connection * connection, int randomMode);
431 void mpd_sendSetvolCommand(mpd_Connection * connection, int volumeChange);
433 /* WARNING: don't use volume command, its depreacted */
434 void mpd_sendVolumeCommand(mpd_Connection * connection, int volumeChange);
436 void mpd_sendCrossfadeCommand(mpd_Connection * connection, int seconds);
438 void mpd_sendUpdateCommand(mpd_Connection * connection, char * path);
440 /* returns the update job id, call this after a update command*/
441 int mpd_getUpdateId(mpd_Connection * connection);
443 void mpd_sendPasswordCommand(mpd_Connection * connection, const char * pass);
445 /* after executing a command, when your done with it to get its status
446 * (you want to check connection->error for an error)
447 */
448 void mpd_finishCommand(mpd_Connection * connection);
450 /* command list stuff, use this to do things like add files very quickly */
451 void mpd_sendCommandListBegin(mpd_Connection * connection);
453 void mpd_sendCommandListOkBegin(mpd_Connection * connection);
455 void mpd_sendCommandListEnd(mpd_Connection * connection);
457 /* advance to the next listOk
458 * returns 0 if advanced to the next list_OK,
459 * returns -1 if it advanced to an OK or ACK */
460 int mpd_nextListOkCommand(mpd_Connection * connection);
462 #ifdef __cplusplus
463 }
464 #endif
466 #endif