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
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. */
32 #ifndef LIBMPDCLIENT_H
33 #define LIBMPDCLIENT_H
36 # define __W32API_USE_DLLIMPORT__ 1
41 #define MPD_BUFFER_MAX_LENGTH 50000
42 #define MPD_ERRORSTR_MAX_LENGTH 1000
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 typedef enum mpd_TagItems {
81 MPD_TAG_ITEM_COMPOSER,
82 MPD_TAG_ITEM_PERFORMER,
85 MPD_TAG_ITEM_FILENAME,
87 MPD_TAG_NUM_OF_ITEM_TYPES
90 extern const char *mpdTagItemKeys[MPD_TAG_NUM_OF_ITEM_TYPES];
92 /* internal stuff don't touch this struct */
93 typedef struct _mpd_ReturnElement {
99 * holds info about connection to mpd
100 * use error, and errorStr to detect errors */
101 typedef struct _mpd_Connection {
102 /* use this to check the version of mpd */
104 /* IMPORTANT, you want to get the error messages from here */
105 char errorStr[MPD_ERRORSTR_MAX_LENGTH + 1];
108 /* this will be set to MPD_ERROR_* if there is an error, 0 if not */
110 /* DON'T TOUCH any of the rest of this stuff */
112 char buffer[MPD_BUFFER_MAX_LENGTH + 1];
119 mpd_ReturnElement *returnElement;
120 struct timeval timeout;
125 * use this to open a new connection
126 * you should use mpd_closeConnection when you're done with the connection,
127 * even if an error has occurred
128 * _timeout_ is the connection timeout period in seconds */
129 mpd_Connection *mpd_newConnection(const char *host, int port, float timeout);
131 void mpd_setConnectionTimeout(mpd_Connection *connection, float timeout);
133 /* mpd_closeConnection
134 * use this to close a connection and free subsequent memory */
135 void mpd_closeConnection(mpd_Connection *connection);
139 void mpd_clearError(mpd_Connection *connection);
143 /* use these with status.state to determine what state the player is in */
144 #define MPD_STATUS_STATE_UNKNOWN 0
145 #define MPD_STATUS_STATE_STOP 1
146 #define MPD_STATUS_STATE_PLAY 2
147 #define MPD_STATUS_STATE_PAUSE 3
149 /* use this with status.volume to determine if mpd has volume support */
150 #define MPD_STATUS_NO_VOLUME -1
153 * holds info return from status command */
154 typedef struct mpd_Status {
155 /* 0-100, or MPD_STATUS_NO_VOLUME when there is no volume support */
157 /* 1 if repeat is on, 0 otherwise */
159 /* 1 if random is on, 0 otherwise */
161 /* playlist length */
163 /* playlist, use this to determine when the playlist has changed */
165 /* use with MPD_STATUS_STATE_* to determine state of player */
167 /* crossfade setting in seconds */
169 /* if a song is currently selected (always the case when state is PLAY
170 * or PAUSE), this is the position of the currently playing song in the
171 * playlist, beginning with 0 */
173 /* Song ID of the currently selected song */
175 /* time in seconds that have elapsed in the currently playing/paused song */
177 /* length in seconds of the currently playing/paused song */
179 /* current bit rate in kbs */
181 /* audio sample rate */
182 unsigned int sampleRate;
187 /* 1 if mpd is updating, 0 otherwise */
193 void mpd_sendStatusCommand(mpd_Connection *connection);
196 * returns status info, be sure to free it with mpd_freeStatus()
197 * call this after mpd_sendStatusCommand() */
198 mpd_Status *mpd_getStatus(mpd_Connection *connection);
201 * free's status info malloc'd and returned by mpd_getStatus */
202 void mpd_freeStatus(mpd_Status *status);
204 typedef struct _mpd_Stats {
208 unsigned long uptime;
209 unsigned long dbUpdateTime;
210 unsigned long playTime;
211 unsigned long dbPlayTime;
214 typedef struct _mpd_SearchStats {
216 unsigned long playTime;
219 void mpd_sendStatsCommand(mpd_Connection *connection);
221 mpd_Stats *mpd_getStats(mpd_Connection *connection);
223 void mpd_freeStats(mpd_Stats *stats);
225 mpd_SearchStats *mpd_getSearchStats(mpd_Connection *connection);
227 void mpd_freeSearchStats(mpd_SearchStats *stats);
231 #define MPD_SONG_NO_TIME -1
232 #define MPD_SONG_NO_NUM -1
233 #define MPD_SONG_NO_ID -1
236 * for storing song info returned by mpd */
237 typedef struct _mpd_Song {
238 /* filename of song */
240 /* artist, maybe NULL if there is no tag */
242 /* title, maybe NULL if there is no tag */
244 /* album, maybe NULL if there is no tag */
246 /* track, maybe NULL if there is no tag */
248 /* name, maybe NULL if there is no tag; it's the name of the current song,
249 * f.e. the icyName of the stream */
266 /* length of song in seconds, check that it is not MPD_SONG_NO_TIME */
268 /* if plchanges/playlistinfo/playlistid used, is the position of the song
271 /* song id for a song in the playlist */
276 * use to allocate memory for a new mpd_Song
277 * file, artist, etc all initialized to NULL
278 * if you're going to assign values to file, artist, etc., be sure to
279 * malloc or strdup the memory
280 * use mpd_freeSong to free the memory for the mpd_Song, it will also
281 * free memory for file, artist, etc, so don't do it yourself */
282 mpd_Song *mpd_newSong(void);
285 * use to free memory allocated by mpd_newSong
286 * also it will free memory pointed to by file, artist, etc, so be careful */
287 void mpd_freeSong(mpd_Song *song);
290 * works like strDup, but for a mpd_Song */
291 mpd_Song *mpd_songDup(mpd_Song *song);
293 /* DIRECTORY STUFF */
296 * used to store info from directory (right now just the path) */
297 typedef struct _mpd_Directory {
302 * allocates memory for a new directory
303 * use mpd_freeDirectory to free this memory */
304 mpd_Directory *mpd_newDirectory(void);
307 * used to free memory allocated with mpd_newDirectory, and it frees
308 * path of mpd_Directory, so be careful */
309 void mpd_freeDirectory(mpd_Directory *directory);
312 * works like strdup, but for mpd_Directory */
313 mpd_Directory *mpd_directoryDup(mpd_Directory *directory);
315 /* PLAYLISTFILE STUFF */
318 * stores info about playlist file returned by lsinfo */
319 typedef struct _mpd_PlaylistFile {
323 /* mpd_newPlaylistFile
324 * allocates memory for new mpd_PlaylistFile, path is set to NULL
325 * free this memory with mpd_freePlaylistFile */
326 mpd_PlaylistFile *mpd_newPlaylistFile(void);
329 * free memory allocated for freePlaylistFile
330 * will also free path, so be careful */
331 void mpd_freePlaylistFile(mpd_PlaylistFile *playlist);
333 /* mpd_playlistFileDup
334 * works like strdup, but for mpd_PlaylistFile */
335 mpd_PlaylistFile *mpd_playlistFileDup(mpd_PlaylistFile *playlist);
337 /* INFO ENTITY STUFF */
339 /* the type of entity returned from one of the commands that generates info
340 * use in conjunction with mpd_InfoEntity.type */
341 #define MPD_INFO_ENTITY_TYPE_DIRECTORY 0
342 #define MPD_INFO_ENTITY_TYPE_SONG 1
343 #define MPD_INFO_ENTITY_TYPE_PLAYLISTFILE 2
346 * stores info on stuff returned info commands */
347 typedef struct mpd_InfoEntity {
348 /* the type of entity, use with MPD_INFO_ENTITY_TYPE_* to determine
349 * what this entity is (song, directory, etc...) */
351 /* the actual data you want, mpd_Song, mpd_Directory, etc */
353 mpd_Directory *directory;
355 mpd_PlaylistFile *playlistFile;
359 mpd_InfoEntity *mpd_newInfoEntity(void);
361 void mpd_freeInfoEntity(mpd_InfoEntity *entity);
363 /* INFO COMMANDS AND STUFF */
365 /* use this function to loop over after calling Info/Listall functions */
366 mpd_InfoEntity *mpd_getNextInfoEntity(mpd_Connection *connection);
368 /* fetches the currently selected song (the song referenced by status->song
369 * and status->songid */
370 void mpd_sendCurrentSongCommand(mpd_Connection *connection);
372 /* songNum of -1, means to display the whole list */
373 void mpd_sendPlaylistInfoCommand(mpd_Connection *connection, int songNum);
375 /* songId of -1, means to display the whole list */
376 void mpd_sendPlaylistIdCommand(mpd_Connection *connection, int songId);
378 /* use this to get the changes in the playlist since version _playlist_ */
379 void mpd_sendPlChangesCommand(mpd_Connection *connection, long long playlist);
382 * @param connection: A valid and connected mpd_Connection.
383 * @param playlist: The playlist version you want the diff with.
385 * A more bandwidth efficient version of the mpd_sendPlChangesCommand.
386 * It only returns the pos+id of the changes song. */
387 void mpd_sendPlChangesPosIdCommand(mpd_Connection *connection,
390 /* recursively fetches all songs/dir/playlists in "dir*
391 * (no metadata is returned) */
392 void mpd_sendListallCommand(mpd_Connection *connection, const char *dir);
394 /* same as sendListallCommand, but also metadata is returned */
395 void mpd_sendListallInfoCommand(mpd_Connection *connection, const char *dir);
397 /* non-recursive version of ListallInfo */
398 void mpd_sendLsInfoCommand(mpd_Connection *connection, const char *dir);
400 #define MPD_TABLE_ARTIST MPD_TAG_ITEM_ARTIST
401 #define MPD_TABLE_ALBUM MPD_TAG_ITEM_ALBUM
402 #define MPD_TABLE_TITLE MPD_TAG_ITEM_TITLE
403 #define MPD_TABLE_FILENAME MPD_TAG_ITEM_FILENAME
405 void mpd_sendSearchCommand(mpd_Connection *connection, int table,
408 void mpd_sendFindCommand(mpd_Connection *connection, int table,
411 /* LIST TAG COMMANDS */
413 /* use this function fetch next artist entry, be sure to free the
415 * NULL means there are no more.
416 * Best used with sendListArtists */
417 char *mpd_getNextArtist(mpd_Connection *connection);
419 char *mpd_getNextAlbum(mpd_Connection *connection);
421 char *mpd_getNextTag(mpd_Connection *connection, int type);
423 /* list artist or albums by artist
424 * arg1 should be set to the artist if listing albums by a artist
425 * otherwise NULL for listing all artists or albums */
426 void mpd_sendListCommand(mpd_Connection *connection, int table,
429 /* SIMPLE COMMANDS */
431 void mpd_sendAddCommand(mpd_Connection *connection, const char *file);
433 int mpd_sendAddIdCommand(mpd_Connection *connection, const char *file);
435 void mpd_sendDeleteCommand(mpd_Connection *connection, int songNum);
437 void mpd_sendDeleteIdCommand(mpd_Connection *connection, int songNum);
439 void mpd_sendSaveCommand(mpd_Connection *connection, const char *name);
441 void mpd_sendLoadCommand(mpd_Connection *connection, const char *name);
443 void mpd_sendRmCommand(mpd_Connection *connection, const char *name);
445 void mpd_sendRenameCommand(mpd_Connection *connection, const char *from,
448 void mpd_sendShuffleCommand(mpd_Connection *connection);
450 void mpd_sendClearCommand(mpd_Connection *connection);
452 /* use this to start playing at the beginning, useful when in random mode */
453 #define MPD_PLAY_AT_BEGINNING -1
455 void mpd_sendPlayCommand(mpd_Connection *connection, int songNum);
457 void mpd_sendPlayIdCommand(mpd_Connection *connection, int songNum);
459 void mpd_sendStopCommand(mpd_Connection *connection);
461 void mpd_sendPauseCommand(mpd_Connection *connection, int pauseMode);
463 void mpd_sendNextCommand(mpd_Connection *connection);
465 void mpd_sendPrevCommand(mpd_Connection *connection);
467 void mpd_sendMoveCommand(mpd_Connection *connection, int from, int to);
469 void mpd_sendMoveIdCommand(mpd_Connection *connection, int from, int to);
471 void mpd_sendSwapCommand(mpd_Connection *connection, int song1, int song2);
473 void mpd_sendSwapIdCommand(mpd_Connection *connection, int song1, int song2);
475 void mpd_sendSeekCommand(mpd_Connection *connection, int song, int seek_time);
477 void mpd_sendSeekIdCommand(mpd_Connection *connection, int song, int seek_time);
479 void mpd_sendRepeatCommand(mpd_Connection *connection, int repeatMode);
481 void mpd_sendRandomCommand(mpd_Connection *connection, int randomMode);
483 void mpd_sendSetvolCommand(mpd_Connection *connection, int volumeChange);
485 /* WARNING: don't use volume command, its depreacted */
486 void mpd_sendVolumeCommand(mpd_Connection *connection, int volumeChange);
488 void mpd_sendCrossfadeCommand(mpd_Connection *connection, int seconds);
490 void mpd_sendUpdateCommand(mpd_Connection *connection, char *path);
492 /* returns the update job id, call this after a update command */
493 int mpd_getUpdateId(mpd_Connection *connection);
495 void mpd_sendPasswordCommand(mpd_Connection *connection, const char *pass);
497 /* after executing a command, when you're done with it to get its status
498 * (you want to check connection->error for an error) */
499 void mpd_finishCommand(mpd_Connection *connection);
501 /* command list stuff, use this to do things like add files very quickly */
502 void mpd_sendCommandListBegin(mpd_Connection *connection);
504 void mpd_sendCommandListOkBegin(mpd_Connection *connection);
506 void mpd_sendCommandListEnd(mpd_Connection *connection);
508 /* advance to the next listOk
509 * returns 0 if advanced to the next list_OK,
510 * returns -1 if it advanced to an OK or ACK */
511 int mpd_nextListOkCommand(mpd_Connection *connection);
513 typedef struct _mpd_OutputEntity {
519 void mpd_sendOutputsCommand(mpd_Connection *connection);
521 mpd_OutputEntity *mpd_getNextOutput(mpd_Connection *connection);
523 void mpd_sendEnableOutputCommand(mpd_Connection *connection, int outputId);
525 void mpd_sendDisableOutputCommand(mpd_Connection *connection, int outputId);
527 void mpd_freeOutputElement(mpd_OutputEntity *output);
530 * @param connection a #mpd_Connection
532 * Queries mpd for the allowed commands */
533 void mpd_sendCommandsCommand(mpd_Connection *connection);
536 * @param connection a #mpd_Connection
538 * Queries mpd for the not allowed commands */
539 void mpd_sendNotCommandsCommand(mpd_Connection *connection);
542 * @param connection a #mpd_Connection
544 * returns the next supported command.
546 * @returns a string, needs to be freed */
547 char *mpd_getNextCommand(mpd_Connection *connection);
549 void mpd_sendUrlHandlersCommand(mpd_Connection *connection);
551 char *mpd_getNextHandler(mpd_Connection *connection);
553 void mpd_sendTagTypesCommand(mpd_Connection *connection);
555 char *mpd_getNextTagType(mpd_Connection *connection);
558 * @param connection a MpdConnection
559 * @param path the path to the playlist.
561 * List the content, with full metadata, of a stored playlist. */
562 void mpd_sendListPlaylistInfoCommand(mpd_Connection *connection, char *path);
565 * @param connection a MpdConnection
566 * @param path the path to the playlist.
568 * List the content of a stored playlist. */
569 void mpd_sendListPlaylistCommand(mpd_Connection *connection, char *path);
572 * @param connection a #mpd_Connection
573 * @param exact if to match exact
576 * use mpd_addConstraintSearch to add a constraint to the search
577 * use mpd_commitSearch to do the actual search */
578 void mpd_startSearch(mpd_Connection *connection, int exact);
581 * @param connection a #mpd_Connection
584 void mpd_addConstraintSearch(mpd_Connection *connection, int type,
588 * @param connection a #mpd_Connection */
589 void mpd_commitSearch(mpd_Connection *connection);
592 * @param connection a #mpd_Connection
593 * @param type The type to search for
595 * starts a search for fields... f.e. get a list of artists would be:
597 * mpd_startFieldSearch(connection, MPD_TAG_ITEM_ARTIST);
598 * mpd_commitSearch(connection);
601 * or get a list of artist in genre "jazz" would be:
603 * mpd_startFieldSearch(connection, MPD_TAG_ITEM_ARTIST);
604 * mpd_addConstraintSearch(connection, MPD_TAG_ITEM_GENRE, "jazz")
605 * mpd_commitSearch(connection);
608 * mpd_startSearch will return a list of songs
609 * (and you need mpd_getNextInfoEntity)
610 * this will return a list of only one field (the one specified with type)
611 * you need mpd_getNextTag to get the results */
612 void mpd_startFieldSearch(mpd_Connection *connection, int type);
614 void mpd_startPlaylistSearch(mpd_Connection *connection, int exact);
616 void mpd_startStatsSearch(mpd_Connection *connection);
618 void mpd_sendPlaylistClearCommand(mpd_Connection *connection, char *path);
620 void mpd_sendPlaylistAddCommand(mpd_Connection *connection, char *playlist,
623 void mpd_sendPlaylistMoveCommand(mpd_Connection *connection, char *playlist,
626 void mpd_sendPlaylistDeleteCommand(mpd_Connection *connection, char *playlist,