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