src/libmpdclient.h

   1 /* libmpdclient
   2    (c)2003-2006 by Warren Dukes (warren.dukes@gmail.com)
   3    This project's homepage is: http://www.musicpd.org
   4
   5    Redistribution and use in source and binary forms, with or without
   6    modification, are permitted provided that the following conditions
   7    are met:
   8
   9    - Redistributions of source code must retain the above copyright
  10    notice, this list of conditions and the following disclaimer.
  11
  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.
  15
  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.
  19
  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 */
  32
  33 #ifndef LIBMPDCLIENT_H
  34 #define LIBMPDCLIENT_H
  35
  36 #include "song.h"
  37
  38 #ifdef WIN32
  39 #  define __W32API_USE_DLLIMPORT__ 1
  40 #endif
  41
  42 #include <sys/time.h>
  43 #include <stddef.h>
  44
  45 #define MPD_BUFFER_MAX_LENGTH   50000
  46 #define MPD_WELCOME_MESSAGE     "OK MPD "
  47
  48 #define MPD_ERROR_TIMEOUT       10 /* timeout trying to talk to mpd */
  49 #define MPD_ERROR_SYSTEM        11 /* system error */
  50 #define MPD_ERROR_UNKHOST       12 /* unknown host */
  51 #define MPD_ERROR_CONNPORT      13 /* problems connecting to port on host */
  52 #define MPD_ERROR_NOTMPD        14 /* mpd not running on port at host */
  53 #define MPD_ERROR_NORESPONSE    15 /* no response on attempting to connect */
  54 #define MPD_ERROR_SENDING       16 /* error sending command */
  55 #define MPD_ERROR_CONNCLOSED    17 /* connection closed by mpd */
  56 #define MPD_ERROR_ACK           18 /* ACK returned! */
  57 #define MPD_ERROR_BUFFEROVERRUN 19 /* Buffer was overrun! */
  58
  59 #define MPD_ACK_ERROR_UNK       -1
  60 #define MPD_ERROR_AT_UNK        -1
  61
  62 #define MPD_ACK_ERROR_NOT_LIST                  1
  63 #define MPD_ACK_ERROR_ARG                       2
  64 #define MPD_ACK_ERROR_PASSWORD                  3
  65 #define MPD_ACK_ERROR_PERMISSION                4
  66 #define MPD_ACK_ERROR_UNKNOWN_CMD               5
  67
  68 #define MPD_ACK_ERROR_NO_EXIST                  50
  69 #define MPD_ACK_ERROR_PLAYLIST_MAX              51
  70 #define MPD_ACK_ERROR_SYSTEM                    52
  71 #define MPD_ACK_ERROR_PLAYLIST_LOAD             53
  72 #define MPD_ACK_ERROR_UPDATE_ALREADY            54
  73 #define MPD_ACK_ERROR_PLAYER_SYNC               55
  74 #define MPD_ACK_ERROR_EXIST                     56
  75
  76 #ifdef __cplusplus
  77 extern "C" {
  78 #endif
  79
  80 typedef enum mpd_TagItems
  81 {
  82         MPD_TAG_ITEM_ARTIST,
  83         MPD_TAG_ITEM_ALBUM,
  84         MPD_TAG_ITEM_TITLE,
  85         MPD_TAG_ITEM_TRACK,
  86         MPD_TAG_ITEM_NAME,
  87         MPD_TAG_ITEM_GENRE,
  88         MPD_TAG_ITEM_DATE,
  89         MPD_TAG_ITEM_COMPOSER,
  90         MPD_TAG_ITEM_PERFORMER,
  91         MPD_TAG_ITEM_COMMENT,
  92         MPD_TAG_ITEM_DISC,
  93         MPD_TAG_ITEM_FILENAME,
  94         MPD_TAG_NUM_OF_ITEM_TYPES
  95 }mpd_TagItems;
  96
  97 extern const char *const mpdTagItemKeys[MPD_TAG_NUM_OF_ITEM_TYPES];
  98
  99 /* internal stuff don't touch this struct */
 100 typedef struct _mpd_ReturnElement {
 101         char * name;
 102         char * value;
 103 } mpd_ReturnElement;
 104
 105 /* mpd_Connection
 106  * holds info about connection to mpd
 107  * use error, and errorStr to detect errors
 108  */
 109 typedef struct _mpd_Connection {
 110         /* use this to check the version of mpd */
 111         int version[3];
 112         /* IMPORTANT, you want to get the error messages from here */
 113         char errorStr[MPD_BUFFER_MAX_LENGTH+1];
 114         int errorCode;
 115         int errorAt;
 116         /* this will be set to MPD_ERROR_* if there is an error, 0 if not */
 117         int error;
 118         /* DON'T TOUCH any of the rest of this stuff */
 119         int sock;
 120         char buffer[MPD_BUFFER_MAX_LENGTH+1];
 121         size_t buflen;
 122         size_t bufstart;
 123         int doneProcessing;
 124         int listOks;
 125         int doneListOk;
 126         int commandList;
 127         mpd_ReturnElement * returnElement;
 128         struct timeval timeout;
 129         char *request;
 130 } mpd_Connection;
 131
 132 /* mpd_newConnection
 133  * use this to open a new connection
 134  * you should use mpd_closeConnection, when your done with the connection,
 135  * even if an error has occurred
 136  * _timeout_ is the connection timeout period in seconds
 137  */
 138 mpd_Connection * mpd_newConnection(const char * host, int port, float timeout);
 139
 140 void mpd_setConnectionTimeout(mpd_Connection * connection, float timeout);
 141
 142 /* mpd_closeConnection
 143  * use this to close a connection and free'ing subsequent memory
 144  */
 145 void mpd_closeConnection(mpd_Connection * connection);
 146
 147 /* mpd_clearError
 148  * clears error
 149  */
 150 void mpd_clearError(mpd_Connection * connection);
 151
 152 /* STATUS STUFF */
 153
 154 /* use these with status.state to determine what state the player is in */
 155 #define MPD_STATUS_STATE_UNKNOWN        0
 156 #define MPD_STATUS_STATE_STOP           1
 157 #define MPD_STATUS_STATE_PLAY           2
 158 #define MPD_STATUS_STATE_PAUSE          3
 159
 160 /* us this with status.volume to determine if mpd has volume support */
 161 #define MPD_STATUS_NO_VOLUME            -1
 162
 163 /* mpd_Status
 164  * holds info return from status command
 165  */
 166 typedef struct mpd_Status {
 167         /* 0-100, or MPD_STATUS_NO_VOLUME when there is no volume support */
 168         int volume;
 169         /* 1 if repeat is on, 0 otherwise */
 170         int repeat;
 171         /* 1 if random is on, 0 otherwise */
 172         int random;
 173         /* playlist length */
 174         int playlistLength;
 175         /* playlist, use this to determine when the playlist has changed */
 176         long long playlist;
 177         /* use with MPD_STATUS_STATE_* to determine state of player */
 178         int state;
 179         /* crossfade setting in seconds */
 180         int crossfade;
 181         /* if a song is currently selected (always the case when state is
 182          * PLAY or PAUSE), this is the position of the currently
 183          * playing song in the playlist, beginning with 0
 184          */
 185         int song;
 186         /* Song ID of the currently selected song */
 187         int songid;
 188         /* time in seconds that have elapsed in the currently playing/paused
 189          * song
 190          */
 191         int elapsedTime;
 192         /* length in seconds of the currently playing/paused song */
 193         int totalTime;
 194         /* current bit rate in kbs */
 195         int bitRate;
 196         /* audio sample rate */
 197         unsigned int sampleRate;
 198         /* audio bits */
 199         int bits;
 200         /* audio channels */
 201         int channels;
 202         /* 1 if mpd is updating, 0 otherwise */
 203         int updatingDb;
 204         /* error */
 205         char * error;
 206 } mpd_Status;
 207
 208 void mpd_sendStatusCommand(mpd_Connection * connection);
 209
 210 /* mpd_getStatus
 211  * returns status info, be sure to free it with mpd_freeStatus()
 212  * call this after mpd_sendStatusCommand()
 213  */
 214 mpd_Status * mpd_getStatus(mpd_Connection * connection);
 215
 216 /* mpd_freeStatus
 217  * free's status info malloc'd and returned by mpd_getStatus
 218  */
 219 void mpd_freeStatus(mpd_Status * status);
 220
 221 typedef struct _mpd_Stats {
 222         int numberOfArtists;
 223         int numberOfAlbums;
 224         int numberOfSongs;
 225         unsigned long uptime;
 226         unsigned long dbUpdateTime;
 227         unsigned long playTime;
 228         unsigned long dbPlayTime;
 229 } mpd_Stats;
 230
 231 void mpd_sendStatsCommand(mpd_Connection * connection);
 232
 233 mpd_Stats * mpd_getStats(mpd_Connection * connection);
 234
 235 void mpd_freeStats(mpd_Stats * stats);
 236
 237 /* DIRECTORY STUFF */
 238
 239 /* mpd_Directory
 240  * used to store info fro directory (right now that just the path)
 241  */
 242 typedef struct _mpd_Directory {
 243         char * path;
 244 } mpd_Directory;
 245
 246 /* mpd_newDirectory
 247  * allocates memory for a new directory
 248  * use mpd_freeDirectory to free this memory
 249  */
 250 mpd_Directory * mpd_newDirectory(void);
 251
 252 /* mpd_freeDirectory
 253  * used to free memory allocated with mpd_newDirectory, and it frees
 254  * path of mpd_Directory, so be careful
 255  */
 256 void mpd_freeDirectory(mpd_Directory * directory);
 257
 258 /* mpd_directoryDup
 259  * works like strdup, but for mpd_Directory
 260  */
 261 mpd_Directory * mpd_directoryDup(mpd_Directory * directory);
 262
 263 /* PLAYLISTFILE STUFF */
 264
 265 /* mpd_PlaylistFile
 266  * stores info about playlist file returned by lsinfo
 267  */
 268 typedef struct _mpd_PlaylistFile {
 269         char * path;
 270 } mpd_PlaylistFile;
 271
 272 /* mpd_newPlaylistFile
 273  * allocates memory for new mpd_PlaylistFile, path is set to NULL
 274  * free this memory with mpd_freePlaylistFile
 275  */
 276 mpd_PlaylistFile * mpd_newPlaylistFile(void);
 277
 278 /* mpd_freePlaylist
 279  * free memory allocated for freePlaylistFile, will also free
 280  * path, so be careful
 281  */
 282 void mpd_freePlaylistFile(mpd_PlaylistFile * playlist);
 283
 284 /* mpd_playlistFileDup
 285  * works like strdup, but for mpd_PlaylistFile
 286  */
 287 mpd_PlaylistFile * mpd_playlistFileDup(mpd_PlaylistFile * playlist);
 288
 289 /* INFO ENTITY STUFF */
 290
 291 /* the type of entity returned from one of the commands that generates info
 292  * use in conjunction with mpd_InfoEntity.type
 293  */
 294 #define MPD_INFO_ENTITY_TYPE_DIRECTORY          0
 295 #define MPD_INFO_ENTITY_TYPE_SONG               1
 296 #define MPD_INFO_ENTITY_TYPE_PLAYLISTFILE       2
 297
 298 /* mpd_InfoEntity
 299  * stores info on stuff returned info commands
 300  */
 301 typedef struct mpd_InfoEntity {
 302         /* the type of entity, use with MPD_INFO_ENTITY_TYPE_* to determine
 303          * what this entity is (song, directory, etc...)
 304          */
 305         int type;
 306         /* the actual data you want, mpd_Song, mpd_Directory, etc */
 307         union {
 308                 mpd_Directory * directory;
 309                 mpd_Song * song;
 310                 mpd_PlaylistFile * playlistFile;
 311         } info;
 312 } mpd_InfoEntity;
 313
 314 mpd_InfoEntity * mpd_newInfoEntity(void);
 315
 316 void mpd_freeInfoEntity(mpd_InfoEntity * entity);
 317
 318 /* INFO COMMANDS AND STUFF */
 319
 320 /* use this function to loop over after calling Info/Listall functions */
 321 mpd_InfoEntity * mpd_getNextInfoEntity(mpd_Connection * connection);
 322
 323 /* fetches the currently seeletect song (the song referenced by status->song
 324  * and status->songid*/
 325 void mpd_sendCurrentSongCommand(mpd_Connection * connection);
 326
 327 /* songNum of -1, means to display the whole list */
 328 void mpd_sendPlaylistInfoCommand(mpd_Connection * connection, int songNum);
 329
 330 /* songId of -1, means to display the whole list */
 331 void mpd_sendPlaylistIdCommand(mpd_Connection * connection, int songId);
 332
 333 /* use this to get the changes in the playlist since version _playlist_ */
 334 void mpd_sendPlChangesCommand(mpd_Connection * connection, long long playlist);
 335
 336 /**
 337  * @param connection: A valid and connected mpd_Connection.
 338  * @param playlist: The playlist version you want the diff with.
 339  * A more bandwidth efficient version of the mpd_sendPlChangesCommand.
 340  * It only returns the pos+id of the changes song.
 341  */
 342 void mpd_sendPlChangesPosIdCommand(mpd_Connection * connection, long long playlist);
 343
 344 /* recursivel fetches all songs/dir/playlists in "dir* (no metadata is
 345  * returned) */
 346 void mpd_sendListallCommand(mpd_Connection * connection, const char * dir);
 347
 348 /* same as sendListallCommand, but also metadata is returned */
 349 void mpd_sendListallInfoCommand(mpd_Connection * connection, const char * dir);
 350
 351 /* non-recursive version of ListallInfo */
 352 void mpd_sendLsInfoCommand(mpd_Connection * connection, const char * dir);
 353
 354 #define MPD_TABLE_ARTIST        0
 355 #define MPD_TABLE_ALBUM         1
 356 #define MPD_TABLE_TITLE         2
 357 #define MPD_TABLE_FILENAME      3
 358
 359 void mpd_sendSearchCommand(mpd_Connection * connection, int table,
 360                 const char * str);
 361
 362 void mpd_sendFindCommand(mpd_Connection * connection, int table,
 363                 const char * str);
 364
 365 /* LIST TAG COMMANDS */
 366
 367 /* use this function fetch next artist entry, be sure to free the returned
 368  * string.  NULL means there are no more.  Best used with sendListArtists
 369  */
 370 char * mpd_getNextArtist(mpd_Connection * connection);
 371
 372 char * mpd_getNextAlbum(mpd_Connection * connection);
 373
 374 char * mpd_getNextTag(mpd_Connection *connection, int table);
 375
 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);
 381
 382 /* SIMPLE COMMANDS */
 383
 384 void mpd_sendAddCommand(mpd_Connection * connection, const char * file);
 385
 386 void mpd_sendDeleteCommand(mpd_Connection * connection, int songNum);
 387
 388 void mpd_sendDeleteIdCommand(mpd_Connection * connection, int songNum);
 389
 390 void mpd_sendSaveCommand(mpd_Connection * connection, const char * name);
 391
 392 void mpd_sendLoadCommand(mpd_Connection * connection, const char * name);
 393
 394 void mpd_sendRmCommand(mpd_Connection * connection, const char * name);
 395
 396 void mpd_sendShuffleCommand(mpd_Connection * connection);
 397
 398 void mpd_sendClearCommand(mpd_Connection * connection);
 399
 400 /* use this to start playing at the beginning, useful when in random mode */
 401 #define MPD_PLAY_AT_BEGINNING   -1
 402
 403 void mpd_sendPlayCommand(mpd_Connection * connection, int songNum);
 404
 405 void mpd_sendPlayIdCommand(mpd_Connection * connection, int songNum);
 406
 407 void mpd_sendStopCommand(mpd_Connection * connection);
 408
 409 void mpd_sendPauseCommand(mpd_Connection * connection, int pauseMode);
 410
 411 void mpd_sendNextCommand(mpd_Connection * connection);
 412
 413 void mpd_sendPrevCommand(mpd_Connection * connection);
 414
 415 void mpd_sendMoveCommand(mpd_Connection * connection, int from, int to);
 416
 417 void mpd_sendMoveIdCommand(mpd_Connection * connection, int from, int to);
 418
 419 void mpd_sendSwapCommand(mpd_Connection * connection, int song1, int song2);
 420
 421 void mpd_sendSwapIdCommand(mpd_Connection * connection, int song1, int song2);
 422
 423 void mpd_sendSeekCommand(mpd_Connection * connection, int song, int time);
 424
 425 void mpd_sendSeekIdCommand(mpd_Connection * connection, int song, int time);
 426
 427 void mpd_sendRepeatCommand(mpd_Connection * connection, int repeatMode);
 428
 429 void mpd_sendRandomCommand(mpd_Connection * connection, int randomMode);
 430
 431 void mpd_sendSetvolCommand(mpd_Connection * connection, int volumeChange);
 432
 433 /* WARNING: don't use volume command, its depreacted */
 434 void mpd_sendVolumeCommand(mpd_Connection * connection, int volumeChange);
 435
 436 void mpd_sendCrossfadeCommand(mpd_Connection * connection, int seconds);
 437
 438 void mpd_sendUpdateCommand(mpd_Connection * connection, const char *path);
 439
 440 /* returns the update job id, call this after a update command*/
 441 int mpd_getUpdateId(mpd_Connection * connection);
 442
 443 void mpd_sendPasswordCommand(mpd_Connection * connection, const char * pass);
 444
 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);
 449
 450 /* command list stuff, use this to do things like add files very quickly */
 451 void mpd_sendCommandListBegin(mpd_Connection * connection);
 452
 453 void mpd_sendCommandListOkBegin(mpd_Connection * connection);
 454
 455 void mpd_sendCommandListEnd(mpd_Connection * connection);
 456
 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);
 461
 462 typedef struct _mpd_OutputEntity {
 463         int id;
 464         char * name;
 465         int enabled;
 466 } mpd_OutputEntity;
 467
 468 void mpd_sendOutputsCommand(mpd_Connection * connection);
 469
 470 mpd_OutputEntity * mpd_getNextOutput(mpd_Connection * connection);
 471
 472 void mpd_sendEnableOutputCommand(mpd_Connection * connection, int outputId);
 473
 474 void mpd_sendDisableOutputCommand(mpd_Connection * connection, int outputId);
 475
 476 void mpd_freeOutputElement(mpd_OutputEntity * output);
 477
 478 /**
 479  * @param connection a #mpd_Connection
 480  *
 481  * Queries mpd for the allowed commands
 482  */
 483 void mpd_sendCommandsCommand(mpd_Connection * connection);
 484 /**
 485  * @param connection a #mpd_Connection
 486  *
 487  * Queries mpd for the not allowed commands
 488  */
 489 void mpd_sendNotCommandsCommand(mpd_Connection * connection);
 490
 491 /**
 492  * @param connection a #mpd_Connection
 493  *
 494  * returns the next supported command.
 495  *
 496  * @returns a string, needs to be free'ed
 497  */
 498 char *mpd_getNextCommand(mpd_Connection *connection);
 499
 500 /**
 501  * @param connection a MpdConnection
 502  * @param path  the path to the playlist.
 503  *
 504  * List the content, with full metadata, of a stored playlist.
 505  *
 506  */
 507 void mpd_sendListPlaylistInfoCommand(mpd_Connection *connection, char *path);
 508 /**
 509  * @param connection a MpdConnection
 510  * @param path  the path to the playlist.
 511  *
 512  * List the content of a stored playlist.
 513  *
 514  */
 515 void mpd_sendListPlaylistCommand(mpd_Connection *connection, char *path);
 516
 517 /**
 518  * @param connection a #mpd_Connection
 519  * @param exact if to match exact
 520  *
 521  * starts a search, use mpd_addConstraintSearch to add
 522  * a constraint to the search, and mpd_commitSearch to do the actual search
 523  */
 524 void mpd_startSearch(mpd_Connection * connection,int exact);
 525 /**
 526  * @param connection a #mpd_Connection
 527  * @param field
 528  * @param name
 529  *
 530  */
 531 void mpd_addConstraintSearch(mpd_Connection *connection, int field, char *name);
 532 /**
 533  * @param connection a #mpd_Connection
 534  *
 535  */
 536 void mpd_commitSearch(mpd_Connection *connection);
 537
 538 /**
 539  * @param connection a #mpd_Connection
 540  * @param field The field to search
 541  *
 542  * starts a search for fields... f.e. get a list of artists would be:
 543  * mpd_startFieldSearch(connection, MPD_TAG_ITEM_ARTIST);
 544  * mpd_commitSearch(connection);
 545  *
 546  * or get a list of artist in genre "jazz" would be:
 547  * @code
 548  * mpd_startFieldSearch(connection, MPD_TAG_ITEM_ARTIST);
 549  * mpd_addConstraintSearch(connection, MPD_TAG_ITEM_GENRE, "jazz")
 550  * mpd_commitSearch(connection);
 551  * @endcode
 552  *
 553  * mpd_startSearch will return  a list of songs (and you need mpd_getNextInfoEntity)
 554  * this one will return a list of only one field (the field specified with field) and you need
 555  * mpd_getNextTag to get the results
 556  */
 557 void mpd_startFieldSearch(mpd_Connection * connection,int field);
 558 #ifdef __cplusplus
 559 }
 560 #endif
 561
 562 #endif