1 /* -*- mode: c; c-basic-offset: 4; tab-width: 4; indent-tabs-mode: t -*-
4 * (c)2003-2006 by Warren Dukes (warren.dukes@gmail.com)
5 * This project's homepage is: http://www.musicpd.org
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
11 * - Redistributions of source code must retain the above copyright
12 * notice, this list of conditions and the following disclaimer.
14 * - Redistributions in binary form must reproduce the above copyright
15 * notice, this list of conditions and the following disclaimer in the
16 * documentation and/or other materials provided with the distribution.
18 * - Neither the name of the Music Player Daemon nor the names of its
19 * contributors may be used to endorse or promote products derived from
20 * this software without specific prior written permission.
22 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
23 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
24 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
25 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR
26 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
27 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
28 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
29 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
30 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
31 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
32 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */
34 #ifndef LIBMPDCLIENT_H
35 #define LIBMPDCLIENT_H
38 # define __W32API_USE_DLLIMPORT__ 1
43 #define MPD_BUFFER_MAX_LENGTH 50000
44 #define MPD_ERRORSTR_MAX_LENGTH 1000
45 #define MPD_WELCOME_MESSAGE "OK MPD "
47 #define MPD_ERROR_TIMEOUT 10 /* timeout trying to talk to mpd */
48 #define MPD_ERROR_SYSTEM 11 /* system error */
49 #define MPD_ERROR_UNKHOST 12 /* unknown host */
50 #define MPD_ERROR_CONNPORT 13 /* problems connecting to port on host */
51 #define MPD_ERROR_NOTMPD 14 /* mpd not running on port at host */
52 #define MPD_ERROR_NORESPONSE 15 /* no response on attempting to connect */
53 #define MPD_ERROR_SENDING 16 /* error sending command */
54 #define MPD_ERROR_CONNCLOSED 17 /* connection closed by mpd */
55 #define MPD_ERROR_ACK 18 /* ACK returned! */
56 #define MPD_ERROR_BUFFEROVERRUN 19 /* Buffer was overrun! */
58 #define MPD_ACK_ERROR_UNK -1
59 #define MPD_ERROR_AT_UNK -1
61 #define MPD_ACK_ERROR_NOT_LIST 1
62 #define MPD_ACK_ERROR_ARG 2
63 #define MPD_ACK_ERROR_PASSWORD 3
64 #define MPD_ACK_ERROR_PERMISSION 4
65 #define MPD_ACK_ERROR_UNKNOWN_CMD 5
67 #define MPD_ACK_ERROR_NO_EXIST 50
68 #define MPD_ACK_ERROR_PLAYLIST_MAX 51
69 #define MPD_ACK_ERROR_SYSTEM 52
70 #define MPD_ACK_ERROR_PLAYLIST_LOAD 53
71 #define MPD_ACK_ERROR_UPDATE_ALREADY 54
72 #define MPD_ACK_ERROR_PLAYER_SYNC 55
73 #define MPD_ACK_ERROR_EXIST 56
75 typedef enum mpd_TagItems {
83 MPD_TAG_ITEM_COMPOSER,
84 MPD_TAG_ITEM_PERFORMER,
87 MPD_TAG_ITEM_FILENAME,
89 MPD_TAG_NUM_OF_ITEM_TYPES
92 extern const char *mpdTagItemKeys[MPD_TAG_NUM_OF_ITEM_TYPES];
94 /* internal stuff don't touch this struct */
95 typedef struct _mpd_ReturnElement {
101 * holds info about connection to mpd
102 * use error, and errorStr to detect errors */
103 typedef struct _mpd_Connection {
104 /* use this to check the version of mpd */
106 /* IMPORTANT, you want to get the error messages from here */
107 char errorStr[MPD_ERRORSTR_MAX_LENGTH + 1];
110 /* this will be set to MPD_ERROR_* if there is an error, 0 if not */
112 /* DON'T TOUCH any of the rest of this stuff */
114 char buffer[MPD_BUFFER_MAX_LENGTH + 1];
121 mpd_ReturnElement *returnElement;
122 struct timeval timeout;
127 * use this to open a new connection
128 * you should use mpd_closeConnection when you're done with the connection,
129 * even if an error has occurred
130 * _timeout_ is the connection timeout period in seconds */
131 mpd_Connection *mpd_newConnection(const char *host, int port, float timeout);
133 void mpd_setConnectionTimeout(mpd_Connection *connection, float timeout);
135 /* mpd_closeConnection
136 * use this to close a connection and free subsequent memory */
137 void mpd_closeConnection(mpd_Connection *connection);
141 void mpd_clearError(mpd_Connection *connection);
145 /* use these with status.state to determine what state the player is in */
146 #define MPD_STATUS_STATE_UNKNOWN 0
147 #define MPD_STATUS_STATE_STOP 1
148 #define MPD_STATUS_STATE_PLAY 2
149 #define MPD_STATUS_STATE_PAUSE 3
151 /* use this with status.volume to determine if mpd has volume support */
152 #define MPD_STATUS_NO_VOLUME -1
155 * holds info return from status command */
156 typedef struct mpd_Status {
157 /* 0-100, or MPD_STATUS_NO_VOLUME when there is no volume support */
159 /* 1 if repeat is on, 0 otherwise */
161 /* 1 if random is on, 0 otherwise */
163 /* playlist length */
165 /* playlist, use this to determine when the playlist has changed */
167 /* use with MPD_STATUS_STATE_* to determine state of player */
169 /* crossfade setting in seconds */
171 /* if a song is currently selected (always the case when state is PLAY
172 * or PAUSE), this is the position of the currently playing song in the
173 * playlist, beginning with 0 */
175 /* Song ID of the currently selected song */
177 /* time in seconds that have elapsed in the currently playing/paused song */
179 /* length in seconds of the currently playing/paused song */
181 /* current bit rate in kbs */
183 /* audio sample rate */
184 unsigned int sampleRate;
189 /* 1 if mpd is updating, 0 otherwise */
195 void mpd_sendStatusCommand(mpd_Connection *connection);
198 * returns status info, be sure to free it with mpd_freeStatus()
199 * call this after mpd_sendStatusCommand() */
200 mpd_Status *mpd_getStatus(mpd_Connection *connection);
203 * free's status info malloc'd and returned by mpd_getStatus */
204 void mpd_freeStatus(mpd_Status *status);
206 typedef struct _mpd_Stats {
210 unsigned long uptime;
211 unsigned long dbUpdateTime;
212 unsigned long playTime;
213 unsigned long dbPlayTime;
216 typedef struct _mpd_SearchStats {
218 unsigned long playTime;
221 void mpd_sendStatsCommand(mpd_Connection *connection);
223 mpd_Stats *mpd_getStats(mpd_Connection *connection);
225 void mpd_freeStats(mpd_Stats *stats);
227 mpd_SearchStats *mpd_getSearchStats(mpd_Connection *connection);
229 void mpd_freeSearchStats(mpd_SearchStats *stats);
233 #define MPD_SONG_NO_TIME -1
234 #define MPD_SONG_NO_NUM -1
235 #define MPD_SONG_NO_ID -1
238 * for storing song info returned by mpd */
239 typedef struct _mpd_Song {
240 /* filename of song */
242 /* artist, maybe NULL if there is no tag */
244 /* title, maybe NULL if there is no tag */
246 /* album, maybe NULL if there is no tag */
248 /* track, maybe NULL if there is no tag */
250 /* name, maybe NULL if there is no tag; it's the name of the current song,
251 * f.e. the icyName of the stream */
268 /* length of song in seconds, check that it is not MPD_SONG_NO_TIME */
270 /* if plchanges/playlistinfo/playlistid used, is the position of the song
273 /* song id for a song in the playlist */
278 * use to allocate memory for a new mpd_Song
279 * file, artist, etc all initialized to NULL
280 * if you're going to assign values to file, artist, etc., be sure to
281 * malloc or strdup the memory
282 * use mpd_freeSong to free the memory for the mpd_Song, it will also
283 * free memory for file, artist, etc, so don't do it yourself */
284 mpd_Song *mpd_newSong(void);
287 * use to free memory allocated by mpd_newSong
288 * also it will free memory pointed to by file, artist, etc, so be careful */
289 void mpd_freeSong(mpd_Song *song);
292 * works like strDup, but for a mpd_Song */
293 mpd_Song *mpd_songDup(mpd_Song *song);
295 /* DIRECTORY STUFF */
298 * used to store info from directory (right now just the path) */
299 typedef struct _mpd_Directory {
304 * allocates memory for a new directory
305 * use mpd_freeDirectory to free this memory */
306 mpd_Directory *mpd_newDirectory(void);
309 * used to free memory allocated with mpd_newDirectory, and it frees
310 * path of mpd_Directory, so be careful */
311 void mpd_freeDirectory(mpd_Directory *directory);
314 * works like strdup, but for mpd_Directory */
315 mpd_Directory *mpd_directoryDup(mpd_Directory *directory);
317 /* PLAYLISTFILE STUFF */
320 * stores info about playlist file returned by lsinfo */
321 typedef struct _mpd_PlaylistFile {
325 /* mpd_newPlaylistFile
326 * allocates memory for new mpd_PlaylistFile, path is set to NULL
327 * free this memory with mpd_freePlaylistFile */
328 mpd_PlaylistFile *mpd_newPlaylistFile(void);
331 * free memory allocated for freePlaylistFile
332 * will also free path, so be careful */
333 void mpd_freePlaylistFile(mpd_PlaylistFile *playlist);
335 /* mpd_playlistFileDup
336 * works like strdup, but for mpd_PlaylistFile */
337 mpd_PlaylistFile *mpd_playlistFileDup(mpd_PlaylistFile *playlist);
339 /* INFO ENTITY STUFF */
341 /* the type of entity returned from one of the commands that generates info
342 * use in conjunction with mpd_InfoEntity.type */
343 #define MPD_INFO_ENTITY_TYPE_DIRECTORY 0
344 #define MPD_INFO_ENTITY_TYPE_SONG 1
345 #define MPD_INFO_ENTITY_TYPE_PLAYLISTFILE 2
348 * stores info on stuff returned info commands */
349 typedef struct mpd_InfoEntity {
350 /* the type of entity, use with MPD_INFO_ENTITY_TYPE_* to determine
351 * what this entity is (song, directory, etc...) */
353 /* the actual data you want, mpd_Song, mpd_Directory, etc */
355 mpd_Directory *directory;
357 mpd_PlaylistFile *playlistFile;
361 mpd_InfoEntity *mpd_newInfoEntity(void);
363 void mpd_freeInfoEntity(mpd_InfoEntity *entity);
365 /* INFO COMMANDS AND STUFF */
367 /* use this function to loop over after calling Info/Listall functions */
368 mpd_InfoEntity *mpd_getNextInfoEntity(mpd_Connection *connection);
370 /* fetches the currently selected song (the song referenced by status->song
371 * and status->songid */
372 void mpd_sendCurrentSongCommand(mpd_Connection *connection);
374 /* songNum of -1, means to display the whole list */
375 void mpd_sendPlaylistInfoCommand(mpd_Connection *connection, int songNum);
377 /* songId of -1, means to display the whole list */
378 void mpd_sendPlaylistIdCommand(mpd_Connection *connection, int songId);
380 /* use this to get the changes in the playlist since version _playlist_ */
381 void mpd_sendPlChangesCommand(mpd_Connection *connection, long long playlist);
384 * @param connection: A valid and connected mpd_Connection.
385 * @param playlist: The playlist version you want the diff with.
387 * A more bandwidth efficient version of the mpd_sendPlChangesCommand.
388 * It only returns the pos+id of the changes song. */
389 void mpd_sendPlChangesPosIdCommand(mpd_Connection *connection,
392 /* recursively fetches all songs/dir/playlists in "dir*
393 * (no metadata is returned) */
394 void mpd_sendListallCommand(mpd_Connection *connection, const char *dir);
396 /* same as sendListallCommand, but also metadata is returned */
397 void mpd_sendListallInfoCommand(mpd_Connection *connection, const char *dir);
399 /* non-recursive version of ListallInfo */
400 void mpd_sendLsInfoCommand(mpd_Connection *connection, const char *dir);
402 #define MPD_TABLE_ARTIST MPD_TAG_ITEM_ARTIST
403 #define MPD_TABLE_ALBUM MPD_TAG_ITEM_ALBUM
404 #define MPD_TABLE_TITLE MPD_TAG_ITEM_TITLE
405 #define MPD_TABLE_FILENAME MPD_TAG_ITEM_FILENAME
407 void mpd_sendSearchCommand(mpd_Connection *connection, int table,
410 void mpd_sendFindCommand(mpd_Connection *connection, int table,
413 /* LIST TAG COMMANDS */
415 /* use this function fetch next artist entry, be sure to free the
417 * NULL means there are no more.
418 * Best used with sendListArtists */
419 char *mpd_getNextArtist(mpd_Connection *connection);
421 char *mpd_getNextAlbum(mpd_Connection *connection);
423 char *mpd_getNextTag(mpd_Connection *connection, int type);
425 /* list artist or albums by artist
426 * arg1 should be set to the artist if listing albums by a artist
427 * otherwise NULL for listing all artists or albums */
428 void mpd_sendListCommand(mpd_Connection *connection, int table,
431 /* SIMPLE COMMANDS */
433 void mpd_sendAddCommand(mpd_Connection *connection, const char *file);
435 int mpd_sendAddIdCommand(mpd_Connection *connection, const char *file);
437 void mpd_sendDeleteCommand(mpd_Connection *connection, int songNum);
439 void mpd_sendDeleteIdCommand(mpd_Connection *connection, int songNum);
441 void mpd_sendSaveCommand(mpd_Connection *connection, const char *name);
443 void mpd_sendLoadCommand(mpd_Connection *connection, const char *name);
445 void mpd_sendRmCommand(mpd_Connection *connection, const char *name);
447 void mpd_sendRenameCommand(mpd_Connection *connection, const char *from,
450 void mpd_sendShuffleCommand(mpd_Connection *connection);
452 void mpd_sendClearCommand(mpd_Connection *connection);
454 /* use this to start playing at the beginning, useful when in random mode */
455 #define MPD_PLAY_AT_BEGINNING -1
457 void mpd_sendPlayCommand(mpd_Connection *connection, int songNum);
459 void mpd_sendPlayIdCommand(mpd_Connection *connection, int songNum);
461 void mpd_sendStopCommand(mpd_Connection *connection);
463 void mpd_sendPauseCommand(mpd_Connection *connection, int pauseMode);
465 void mpd_sendNextCommand(mpd_Connection *connection);
467 void mpd_sendPrevCommand(mpd_Connection *connection);
469 void mpd_sendMoveCommand(mpd_Connection *connection, int from, int to);
471 void mpd_sendMoveIdCommand(mpd_Connection *connection, int from, int to);
473 void mpd_sendSwapCommand(mpd_Connection *connection, int song1, int song2);
475 void mpd_sendSwapIdCommand(mpd_Connection *connection, int song1, int song2);
477 void mpd_sendSeekCommand(mpd_Connection *connection, int song, int seek_time);
479 void mpd_sendSeekIdCommand(mpd_Connection *connection, int song, int seek_time);
481 void mpd_sendRepeatCommand(mpd_Connection *connection, int repeatMode);
483 void mpd_sendRandomCommand(mpd_Connection *connection, int randomMode);
485 void mpd_sendSetvolCommand(mpd_Connection *connection, int volumeChange);
487 /* WARNING: don't use volume command, its depreacted */
488 void mpd_sendVolumeCommand(mpd_Connection *connection, int volumeChange);
490 void mpd_sendCrossfadeCommand(mpd_Connection *connection, int seconds);
492 void mpd_sendUpdateCommand(mpd_Connection *connection, char *path);
494 /* returns the update job id, call this after a update command */
495 int mpd_getUpdateId(mpd_Connection *connection);
497 void mpd_sendPasswordCommand(mpd_Connection *connection, const char *pass);
499 /* after executing a command, when you're done with it to get its status
500 * (you want to check connection->error for an error) */
501 void mpd_finishCommand(mpd_Connection *connection);
503 /* command list stuff, use this to do things like add files very quickly */
504 void mpd_sendCommandListBegin(mpd_Connection *connection);
506 void mpd_sendCommandListOkBegin(mpd_Connection *connection);
508 void mpd_sendCommandListEnd(mpd_Connection *connection);
510 /* advance to the next listOk
511 * returns 0 if advanced to the next list_OK,
512 * returns -1 if it advanced to an OK or ACK */
513 int mpd_nextListOkCommand(mpd_Connection *connection);
515 typedef struct _mpd_OutputEntity {
521 void mpd_sendOutputsCommand(mpd_Connection *connection);
523 mpd_OutputEntity *mpd_getNextOutput(mpd_Connection *connection);
525 void mpd_sendEnableOutputCommand(mpd_Connection *connection, int outputId);
527 void mpd_sendDisableOutputCommand(mpd_Connection *connection, int outputId);
529 void mpd_freeOutputElement(mpd_OutputEntity *output);
532 * @param connection a #mpd_Connection
534 * Queries mpd for the allowed commands */
535 void mpd_sendCommandsCommand(mpd_Connection *connection);
538 * @param connection a #mpd_Connection
540 * Queries mpd for the not allowed commands */
541 void mpd_sendNotCommandsCommand(mpd_Connection *connection);
544 * @param connection a #mpd_Connection
546 * returns the next supported command.
548 * @returns a string, needs to be freed */
549 char *mpd_getNextCommand(mpd_Connection *connection);
551 void mpd_sendUrlHandlersCommand(mpd_Connection *connection);
553 char *mpd_getNextHandler(mpd_Connection *connection);
555 void mpd_sendTagTypesCommand(mpd_Connection *connection);
557 char *mpd_getNextTagType(mpd_Connection *connection);
560 * @param connection a MpdConnection
561 * @param path the path to the playlist.
563 * List the content, with full metadata, of a stored playlist. */
564 void mpd_sendListPlaylistInfoCommand(mpd_Connection *connection, char *path);
567 * @param connection a MpdConnection
568 * @param path the path to the playlist.
570 * List the content of a stored playlist. */
571 void mpd_sendListPlaylistCommand(mpd_Connection *connection, char *path);
574 * @param connection a #mpd_Connection
575 * @param exact if to match exact
578 * use mpd_addConstraintSearch to add a constraint to the search
579 * use mpd_commitSearch to do the actual search */
580 void mpd_startSearch(mpd_Connection *connection, int exact);
583 * @param connection a #mpd_Connection
586 void mpd_addConstraintSearch(mpd_Connection *connection, int type,
590 * @param connection a #mpd_Connection */
591 void mpd_commitSearch(mpd_Connection *connection);
594 * @param connection a #mpd_Connection
595 * @param type The type to search for
597 * starts a search for fields... f.e. get a list of artists would be:
599 * mpd_startFieldSearch(connection, MPD_TAG_ITEM_ARTIST);
600 * mpd_commitSearch(connection);
603 * or get a list of artist in genre "jazz" would be:
605 * mpd_startFieldSearch(connection, MPD_TAG_ITEM_ARTIST);
606 * mpd_addConstraintSearch(connection, MPD_TAG_ITEM_GENRE, "jazz")
607 * mpd_commitSearch(connection);
610 * mpd_startSearch will return a list of songs
611 * (and you need mpd_getNextInfoEntity)
612 * this will return a list of only one field (the one specified with type)
613 * you need mpd_getNextTag to get the results */
614 void mpd_startFieldSearch(mpd_Connection *connection, int type);
616 void mpd_startPlaylistSearch(mpd_Connection *connection, int exact);
618 void mpd_startStatsSearch(mpd_Connection *connection);
620 void mpd_sendPlaylistClearCommand(mpd_Connection *connection, char *path);
622 void mpd_sendPlaylistAddCommand(mpd_Connection *connection, char *playlist,
625 void mpd_sendPlaylistMoveCommand(mpd_Connection *connection, char *playlist,
628 void mpd_sendPlaylistDeleteCommand(mpd_Connection *connection, char *playlist,