1 /* libmpdclient
2 (c)2003-2006 by Warren Dukes (warren.dukes@gmail.com)
3 This project's homepage is: http://www.musicpd.org
5 Redistribution and use in source and binary forms, with or without
6 modification, are permitted provided that the following conditions
7 are met:
9 - Redistributions of source code must retain the above copyright
10 notice, this list of conditions and the following disclaimer.
12 - Redistributions in binary form must reproduce the above copyright
13 notice, this list of conditions and the following disclaimer in the
14 documentation and/or other materials provided with the distribution.
16 - Neither the name of the Music Player Daemon nor the names of its
17 contributors may be used to endorse or promote products derived from
18 this software without specific prior written permission.
20 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21 ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR
24 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
27 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
28 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
29 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
30 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 */
33 #ifndef LIBMPDCLIENT_H
34 #define LIBMPDCLIENT_H
36 #ifdef WIN32
37 # define __W32API_USE_DLLIMPORT__ 1
38 #endif
40 #include <sys/time.h>
41 #include <stdarg.h>
42 #define MPD_BUFFER_MAX_LENGTH 50000
43 #define MPD_WELCOME_MESSAGE "OK MPD "
45 #define MPD_ERROR_TIMEOUT 10 /* timeout trying to talk to mpd */
46 #define MPD_ERROR_SYSTEM 11 /* system error */
47 #define MPD_ERROR_UNKHOST 12 /* unknown host */
48 #define MPD_ERROR_CONNPORT 13 /* problems connecting to port on host */
49 #define MPD_ERROR_NOTMPD 14 /* mpd not running on port at host */
50 #define MPD_ERROR_NORESPONSE 15 /* no response on attempting to connect */
51 #define MPD_ERROR_SENDING 16 /* error sending command */
52 #define MPD_ERROR_CONNCLOSED 17 /* connection closed by mpd */
53 #define MPD_ERROR_ACK 18 /* ACK returned! */
54 #define MPD_ERROR_BUFFEROVERRUN 19 /* Buffer was overrun! */
56 #define MPD_ACK_ERROR_UNK -1
57 #define MPD_ERROR_AT_UNK -1
59 #define MPD_ACK_ERROR_NOT_LIST 1
60 #define MPD_ACK_ERROR_ARG 2
61 #define MPD_ACK_ERROR_PASSWORD 3
62 #define MPD_ACK_ERROR_PERMISSION 4
63 #define MPD_ACK_ERROR_UNKNOWN_CMD 5
65 #define MPD_ACK_ERROR_NO_EXIST 50
66 #define MPD_ACK_ERROR_PLAYLIST_MAX 51
67 #define MPD_ACK_ERROR_SYSTEM 52
68 #define MPD_ACK_ERROR_PLAYLIST_LOAD 53
69 #define MPD_ACK_ERROR_UPDATE_ALREADY 54
70 #define MPD_ACK_ERROR_PLAYER_SYNC 55
71 #define MPD_ACK_ERROR_EXIST 56
73 #ifdef __cplusplus
74 extern "C" {
75 #endif
77 typedef enum mpd_TagItems
78 {
79 MPD_TAG_ITEM_ARTIST,
80 MPD_TAG_ITEM_ALBUM,
81 MPD_TAG_ITEM_TITLE,
82 MPD_TAG_ITEM_TRACK,
83 MPD_TAG_ITEM_NAME,
84 MPD_TAG_ITEM_GENRE,
85 MPD_TAG_ITEM_DATE,
86 MPD_TAG_ITEM_COMPOSER,
87 MPD_TAG_ITEM_PERFORMER,
88 MPD_TAG_ITEM_COMMENT,
89 MPD_TAG_ITEM_DISC,
90 MPD_TAG_ITEM_FILENAME,
91 MPD_TAG_NUM_OF_ITEM_TYPES
92 }mpd_TagItems;
94 extern char * mpdTagItemKeys[MPD_TAG_NUM_OF_ITEM_TYPES];
96 /* internal stuff don't touch this struct */
97 typedef struct _mpd_ReturnElement {
98 char * name;
99 char * value;
100 } mpd_ReturnElement;
102 /* mpd_Connection
103 * holds info about connection to mpd
104 * use error, and errorStr to detect errors
105 */
106 typedef struct _mpd_Connection {
107 /* use this to check the version of mpd */
108 int version[3];
109 /* IMPORTANT, you want to get the error messages from here */
110 char errorStr[MPD_BUFFER_MAX_LENGTH+1];
111 int errorCode;
112 int errorAt;
113 /* this will be set to MPD_ERROR_* if there is an error, 0 if not */
114 int error;
115 /* DON'T TOUCH any of the rest of this stuff */
116 int sock;
117 char buffer[MPD_BUFFER_MAX_LENGTH+1];
118 int buflen;
119 int bufstart;
120 int doneProcessing;
121 int listOks;
122 int doneListOk;
123 int commandList;
124 mpd_ReturnElement * returnElement;
125 struct timeval timeout;
126 char *request;
127 } mpd_Connection;
129 /* mpd_newConnection
130 * use this to open a new connection
131 * you should use mpd_closeConnection, when your done with the connection,
132 * even if an error has occurred
133 * _timeout_ is the connection timeout period in seconds
134 */
135 mpd_Connection * mpd_newConnection(const char * host, int port, float timeout);
137 void mpd_setConnectionTimeout(mpd_Connection * connection, float timeout);
139 /* mpd_closeConnection
140 * use this to close a connection and free'ing subsequent memory
141 */
142 void mpd_closeConnection(mpd_Connection * connection);
144 /* mpd_clearError
145 * clears error
146 */
147 void mpd_clearError(mpd_Connection * connection);
149 /* STATUS STUFF */
151 /* use these with status.state to determine what state the player is in */
152 #define MPD_STATUS_STATE_UNKNOWN 0
153 #define MPD_STATUS_STATE_STOP 1
154 #define MPD_STATUS_STATE_PLAY 2
155 #define MPD_STATUS_STATE_PAUSE 3
157 /* us this with status.volume to determine if mpd has volume support */
158 #define MPD_STATUS_NO_VOLUME -1
160 /* mpd_Status
161 * holds info return from status command
162 */
163 typedef struct mpd_Status {
164 /* 0-100, or MPD_STATUS_NO_VOLUME when there is no volume support */
165 int volume;
166 /* 1 if repeat is on, 0 otherwise */
167 int repeat;
168 /* 1 if random is on, 0 otherwise */
169 int random;
170 /* playlist length */
171 int playlistLength;
172 /* playlist, use this to determine when the playlist has changed */
173 long long playlist;
174 /* use with MPD_STATUS_STATE_* to determine state of player */
175 int state;
176 /* crossfade setting in seconds */
177 int crossfade;
178 /* if a song is currently selected (always the case when state is
179 * PLAY or PAUSE), this is the position of the currently
180 * playing song in the playlist, beginning with 0
181 */
182 int song;
183 /* Song ID of the currently selected song */
184 int songid;
185 /* time in seconds that have elapsed in the currently playing/paused
186 * song
187 */
188 int elapsedTime;
189 /* length in seconds of the currently playing/paused song */
190 int totalTime;
191 /* current bit rate in kbs */
192 int bitRate;
193 /* audio sample rate */
194 unsigned int sampleRate;
195 /* audio bits */
196 int bits;
197 /* audio channels */
198 int channels;
199 /* 1 if mpd is updating, 0 otherwise */
200 int updatingDb;
201 /* error */
202 char * error;
203 } mpd_Status;
205 void mpd_sendStatusCommand(mpd_Connection * connection);
207 /* mpd_getStatus
208 * returns status info, be sure to free it with mpd_freeStatus()
209 * call this after mpd_sendStatusCommand()
210 */
211 mpd_Status * mpd_getStatus(mpd_Connection * connection);
213 /* mpd_freeStatus
214 * free's status info malloc'd and returned by mpd_getStatus
215 */
216 void mpd_freeStatus(mpd_Status * status);
218 typedef struct _mpd_Stats {
219 int numberOfArtists;
220 int numberOfAlbums;
221 int numberOfSongs;
222 unsigned long uptime;
223 unsigned long dbUpdateTime;
224 unsigned long playTime;
225 unsigned long dbPlayTime;
226 } mpd_Stats;
228 void mpd_sendStatsCommand(mpd_Connection * connection);
230 mpd_Stats * mpd_getStats(mpd_Connection * connection);
232 void mpd_freeStats(mpd_Stats * stats);
234 /* SONG STUFF */
236 #define MPD_SONG_NO_TIME -1
237 #define MPD_SONG_NO_NUM -1
238 #define MPD_SONG_NO_ID -1
240 /* mpd_Song
241 * for storing song info returned by mpd
242 */
243 typedef struct _mpd_Song {
244 /* filename of song */
245 char * file;
246 /* artist, maybe NULL if there is no tag */
247 char * artist;
248 /* title, maybe NULL if there is no tag */
249 char * title;
250 /* album, maybe NULL if there is no tag */
251 char * album;
252 /* track, maybe NULL if there is no tag */
253 char * track;
254 /* name, maybe NULL if there is no tag; it's the name of the current
255 * song, f.e. the icyName of the stream */
256 char * name;
257 /* date */
258 char *date;
260 /* added by qball */
261 /* Genre */
262 char *genre;
263 /* Composer */
264 char *composer;
265 /* Disc */
266 char *disc;
267 /* Comment */
268 char *comment;
270 /* length of song in seconds, check that it is not MPD_SONG_NO_TIME */
271 int time;
272 /* if plchanges/playlistinfo/playlistid used, is the position of the
273 * song in the playlist */
274 int pos;
275 /* song id for a song in the playlist */
276 int id;
277 } mpd_Song;
279 /* mpd_newSong
280 * use to allocate memory for a new mpd_Song
281 * file, artist, etc all initialized to NULL
282 * if your going to assign values to file, artist, etc
283 * be sure to malloc or strdup the memory
284 * use mpd_freeSong to free the memory for the mpd_Song, it will also
285 * free memory for file, artist, etc, so don't do it yourself
286 */
287 mpd_Song * mpd_newSong(void);
289 /* mpd_freeSong
290 * use to free memory allocated by mpd_newSong
291 * also it will free memory pointed to by file, artist, etc, so be careful
292 */
293 void mpd_freeSong(mpd_Song * song);
295 /* mpd_songDup
296 * works like strDup, but for a mpd_Song
297 */
298 mpd_Song * mpd_songDup(mpd_Song * song);
300 /* DIRECTORY STUFF */
302 /* mpd_Directory
303 * used to store info fro directory (right now that just the path)
304 */
305 typedef struct _mpd_Directory {
306 char * path;
307 } mpd_Directory;
309 /* mpd_newDirectory
310 * allocates memory for a new directory
311 * use mpd_freeDirectory to free this memory
312 */
313 mpd_Directory * mpd_newDirectory(void);
315 /* mpd_freeDirectory
316 * used to free memory allocated with mpd_newDirectory, and it frees
317 * path of mpd_Directory, so be careful
318 */
319 void mpd_freeDirectory(mpd_Directory * directory);
321 /* mpd_directoryDup
322 * works like strdup, but for mpd_Directory
323 */
324 mpd_Directory * mpd_directoryDup(mpd_Directory * directory);
326 /* PLAYLISTFILE STUFF */
328 /* mpd_PlaylistFile
329 * stores info about playlist file returned by lsinfo
330 */
331 typedef struct _mpd_PlaylistFile {
332 char * path;
333 } mpd_PlaylistFile;
335 /* mpd_newPlaylistFile
336 * allocates memory for new mpd_PlaylistFile, path is set to NULL
337 * free this memory with mpd_freePlaylistFile
338 */
339 mpd_PlaylistFile * mpd_newPlaylistFile(void);
341 /* mpd_freePlaylist
342 * free memory allocated for freePlaylistFile, will also free
343 * path, so be careful
344 */
345 void mpd_freePlaylistFile(mpd_PlaylistFile * playlist);
347 /* mpd_playlistFileDup
348 * works like strdup, but for mpd_PlaylistFile
349 */
350 mpd_PlaylistFile * mpd_playlistFileDup(mpd_PlaylistFile * playlist);
352 /* INFO ENTITY STUFF */
354 /* the type of entity returned from one of the commands that generates info
355 * use in conjunction with mpd_InfoEntity.type
356 */
357 #define MPD_INFO_ENTITY_TYPE_DIRECTORY 0
358 #define MPD_INFO_ENTITY_TYPE_SONG 1
359 #define MPD_INFO_ENTITY_TYPE_PLAYLISTFILE 2
361 /* mpd_InfoEntity
362 * stores info on stuff returned info commands
363 */
364 typedef struct mpd_InfoEntity {
365 /* the type of entity, use with MPD_INFO_ENTITY_TYPE_* to determine
366 * what this entity is (song, directory, etc...)
367 */
368 int type;
369 /* the actual data you want, mpd_Song, mpd_Directory, etc */
370 union {
371 mpd_Directory * directory;
372 mpd_Song * song;
373 mpd_PlaylistFile * playlistFile;
374 } info;
375 } mpd_InfoEntity;
377 mpd_InfoEntity * mpd_newInfoEntity(void);
379 void mpd_freeInfoEntity(mpd_InfoEntity * entity);
381 /* INFO COMMANDS AND STUFF */
383 /* use this function to loop over after calling Info/Listall functions */
384 mpd_InfoEntity * mpd_getNextInfoEntity(mpd_Connection * connection);
386 /* fetches the currently seeletect song (the song referenced by status->song
387 * and status->songid*/
388 void mpd_sendCurrentSongCommand(mpd_Connection * connection);
390 /* songNum of -1, means to display the whole list */
391 void mpd_sendPlaylistInfoCommand(mpd_Connection * connection, int songNum);
393 /* songId of -1, means to display the whole list */
394 void mpd_sendPlaylistIdCommand(mpd_Connection * connection, int songId);
396 /* use this to get the changes in the playlist since version _playlist_ */
397 void mpd_sendPlChangesCommand(mpd_Connection * connection, long long playlist);
399 /**
400 * @param connection: A valid and connected mpd_Connection.
401 * @param playlist: The playlist version you want the diff with.
402 * A more bandwidth efficient version of the mpd_sendPlChangesCommand.
403 * It only returns the pos+id of the changes song.
404 */
405 void mpd_sendPlChangesPosIdCommand(mpd_Connection * connection, long long playlist);
407 /* recursivel fetches all songs/dir/playlists in "dir* (no metadata is
408 * returned) */
409 void mpd_sendListallCommand(mpd_Connection * connection, const char * dir);
411 /* same as sendListallCommand, but also metadata is returned */
412 void mpd_sendListallInfoCommand(mpd_Connection * connection, const char * dir);
414 /* non-recursive version of ListallInfo */
415 void mpd_sendLsInfoCommand(mpd_Connection * connection, const char * dir);
417 #define MPD_TABLE_ARTIST 0
418 #define MPD_TABLE_ALBUM 1
419 #define MPD_TABLE_TITLE 2
420 #define MPD_TABLE_FILENAME 3
422 void mpd_sendSearchCommand(mpd_Connection * connection, int table,
423 const char * str);
425 void mpd_sendFindCommand(mpd_Connection * connection, int table,
426 const char * str);
428 /* LIST TAG COMMANDS */
430 /* use this function fetch next artist entry, be sure to free the returned
431 * string. NULL means there are no more. Best used with sendListArtists
432 */
433 char * mpd_getNextArtist(mpd_Connection * connection);
435 char * mpd_getNextAlbum(mpd_Connection * connection);
437 char * mpd_getNextTag(mpd_Connection *connection, int table);
439 /* list artist or albums by artist, arg1 should be set to the artist if
440 * listing albums by a artist, otherwise NULL for listing all artists or albums
441 */
442 void mpd_sendListCommand(mpd_Connection * connection, int table,
443 const char * arg1);
445 /* SIMPLE COMMANDS */
447 void mpd_sendAddCommand(mpd_Connection * connection, const char * file);
449 void mpd_sendDeleteCommand(mpd_Connection * connection, int songNum);
451 void mpd_sendDeleteIdCommand(mpd_Connection * connection, int songNum);
453 void mpd_sendSaveCommand(mpd_Connection * connection, const char * name);
455 void mpd_sendLoadCommand(mpd_Connection * connection, const char * name);
457 void mpd_sendRmCommand(mpd_Connection * connection, const char * name);
459 void mpd_sendShuffleCommand(mpd_Connection * connection);
461 void mpd_sendClearCommand(mpd_Connection * connection);
463 /* use this to start playing at the beginning, useful when in random mode */
464 #define MPD_PLAY_AT_BEGINNING -1
466 void mpd_sendPlayCommand(mpd_Connection * connection, int songNum);
468 void mpd_sendPlayIdCommand(mpd_Connection * connection, int songNum);
470 void mpd_sendStopCommand(mpd_Connection * connection);
472 void mpd_sendPauseCommand(mpd_Connection * connection, int pauseMode);
474 void mpd_sendNextCommand(mpd_Connection * connection);
476 void mpd_sendPrevCommand(mpd_Connection * connection);
478 void mpd_sendMoveCommand(mpd_Connection * connection, int from, int to);
480 void mpd_sendMoveIdCommand(mpd_Connection * connection, int from, int to);
482 void mpd_sendSwapCommand(mpd_Connection * connection, int song1, int song2);
484 void mpd_sendSwapIdCommand(mpd_Connection * connection, int song1, int song2);
486 void mpd_sendSeekCommand(mpd_Connection * connection, int song, int time);
488 void mpd_sendSeekIdCommand(mpd_Connection * connection, int song, int time);
490 void mpd_sendRepeatCommand(mpd_Connection * connection, int repeatMode);
492 void mpd_sendRandomCommand(mpd_Connection * connection, int randomMode);
494 void mpd_sendSetvolCommand(mpd_Connection * connection, int volumeChange);
496 /* WARNING: don't use volume command, its depreacted */
497 void mpd_sendVolumeCommand(mpd_Connection * connection, int volumeChange);
499 void mpd_sendCrossfadeCommand(mpd_Connection * connection, int seconds);
501 void mpd_sendUpdateCommand(mpd_Connection * connection, char * path);
503 /* returns the update job id, call this after a update command*/
504 int mpd_getUpdateId(mpd_Connection * connection);
506 void mpd_sendPasswordCommand(mpd_Connection * connection, const char * pass);
508 /* after executing a command, when your done with it to get its status
509 * (you want to check connection->error for an error)
510 */
511 void mpd_finishCommand(mpd_Connection * connection);
513 /* command list stuff, use this to do things like add files very quickly */
514 void mpd_sendCommandListBegin(mpd_Connection * connection);
516 void mpd_sendCommandListOkBegin(mpd_Connection * connection);
518 void mpd_sendCommandListEnd(mpd_Connection * connection);
520 /* advance to the next listOk
521 * returns 0 if advanced to the next list_OK,
522 * returns -1 if it advanced to an OK or ACK */
523 int mpd_nextListOkCommand(mpd_Connection * connection);
525 typedef struct _mpd_OutputEntity {
526 int id;
527 char * name;
528 int enabled;
529 } mpd_OutputEntity;
531 void mpd_sendOutputsCommand(mpd_Connection * connection);
533 mpd_OutputEntity * mpd_getNextOutput(mpd_Connection * connection);
535 void mpd_sendEnableOutputCommand(mpd_Connection * connection, int outputId);
537 void mpd_sendDisableOutputCommand(mpd_Connection * connection, int outputId);
539 void mpd_freeOutputElement(mpd_OutputEntity * output);
541 /**
542 * @param connection a #mpd_Connection
543 *
544 * Queries mpd for the allowed commands
545 */
546 void mpd_sendCommandsCommand(mpd_Connection * connection);
547 /**
548 * @param connection a #mpd_Connection
549 *
550 * Queries mpd for the not allowed commands
551 */
552 void mpd_sendNotCommandsCommand(mpd_Connection * connection);
554 /**
555 * @param connection a #mpd_Connection
556 *
557 * returns the next supported command.
558 *
559 * @returns a string, needs to be free'ed
560 */
561 char *mpd_getNextCommand(mpd_Connection *connection);
563 /**
564 * @param connection a MpdConnection
565 * @param path the path to the playlist.
566 *
567 * List the content, with full metadata, of a stored playlist.
568 *
569 */
570 void mpd_sendListPlaylistInfoCommand(mpd_Connection *connection, char *path);
571 /**
572 * @param connection a MpdConnection
573 * @param path the path to the playlist.
574 *
575 * List the content of a stored playlist.
576 *
577 */
578 void mpd_sendListPlaylistCommand(mpd_Connection *connection, char *path);
580 /**
581 * @param connection a #mpd_Connection
582 * @param exact if to match exact
583 *
584 * starts a search, use mpd_addConstraintSearch to add
585 * a constraint to the search, and mpd_commitSearch to do the actual search
586 */
587 void mpd_startSearch(mpd_Connection * connection,int exact);
588 /**
589 * @param connection a #mpd_Connection
590 * @param field
591 * @param name
592 *
593 */
594 void mpd_addConstraintSearch(mpd_Connection *connection, int field, char *name);
595 /**
596 * @param connection a #mpd_Connection
597 *
598 */
599 void mpd_commitSearch(mpd_Connection *connection);
601 /**
602 * @param connection a #mpd_Connection
603 * @param field The field to search
604 *
605 * starts a search for fields... f.e. get a list of artists would be:
606 * mpd_startFieldSearch(connection, MPD_TAG_ITEM_ARTIST);
607 * mpd_commitSearch(connection);
608 *
609 * or get a list of artist in genre "jazz" would be:
610 * @code
611 * mpd_startFieldSearch(connection, MPD_TAG_ITEM_ARTIST);
612 * mpd_addConstraintSearch(connection, MPD_TAG_ITEM_GENRE, "jazz")
613 * mpd_commitSearch(connection);
614 * @endcode
615 *
616 * mpd_startSearch will return a list of songs (and you need mpd_getNextInfoEntity)
617 * this one will return a list of only one field (the field specified with field) and you need
618 * mpd_getNextTag to get the results
619 */
620 void mpd_startFieldSearch(mpd_Connection * connection,int field);
621 #ifdef __cplusplus
622 }
623 #endif
625 #endif