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 *
 165 mpd_newConnection(const char *host, int port, float timeout_);
 166
 167 void
 168 mpd_setConnectionTimeout(mpd_Connection *connection, float timeout_);
 169
 170 /* mpd_closeConnection
 171  * use this to close a connection and free'ing subsequent memory
 172  */
 173 void mpd_closeConnection(mpd_Connection * connection);
 174
 175 /* mpd_clearError
 176  * clears error
 177  */
 178 void mpd_clearError(mpd_Connection * connection);
 179
 180 /* STATUS STUFF */
 181
 182 /* use these with status.state to determine what state the player is in */
 183 #define MPD_STATUS_STATE_UNKNOWN        0
 184 #define MPD_STATUS_STATE_STOP           1
 185 #define MPD_STATUS_STATE_PLAY           2
 186 #define MPD_STATUS_STATE_PAUSE          3
 187
 188 /* us this with status.volume to determine if mpd has volume support */
 189 #define MPD_STATUS_NO_VOLUME            -1
 190
 191 /* mpd_Status
 192  * holds info return from status command
 193  */
 194 typedef struct mpd_Status {
 195         /* 0-100, or MPD_STATUS_NO_VOLUME when there is no volume support */
 196         int volume;
 197         /* 1 if repeat is on, 0 otherwise */
 198         int repeat;
 199         /* 1 if random is on, 0 otherwise */
 200         int random;
 201         /* 1 if single is on, 0 otherwise */
 202         int single;
 203         /* 1 if consume is on, 0 otherwise */
 204         int consume;
 205         /* playlist length */
 206         int playlistLength;
 207         /* playlist, use this to determine when the playlist has changed */
 208         long long playlist;
 209         /* use with MPD_STATUS_STATE_* to determine state of player */
 210         int state;
 211         /* crossfade setting in seconds */
 212         int crossfade;
 213         /* if a song is currently selected (always the case when state is
 214          * PLAY or PAUSE), this is the position of the currently
 215          * playing song in the playlist, beginning with 0
 216          */
 217         int song;
 218         /* Song ID of the currently selected song */
 219         int songid;
 220         /* time in seconds that have elapsed in the currently playing/paused
 221          * song
 222          */
 223         int elapsedTime;
 224         /* length in seconds of the currently playing/paused song */
 225         int totalTime;
 226         /* current bit rate in kbs */
 227         int bitRate;
 228         /* audio sample rate */
 229         unsigned int sampleRate;
 230         /* audio bits */
 231         int bits;
 232         /* audio channels */
 233         int channels;
 234         /* 1 if mpd is updating, 0 otherwise */
 235         int updatingDb;
 236         /* error */
 237         char * error;
 238 } mpd_Status;
 239
 240 void mpd_sendStatusCommand(mpd_Connection * connection);
 241
 242 /* mpd_getStatus
 243  * returns status info, be sure to free it with mpd_freeStatus()
 244  * call this after mpd_sendStatusCommand()
 245  */
 246 mpd_Status * mpd_getStatus(mpd_Connection * connection);
 247
 248 /* mpd_freeStatus
 249  * free's status info malloc'd and returned by mpd_getStatus
 250  */
 251 void mpd_freeStatus(mpd_Status * status);
 252
 253 typedef struct _mpd_Stats {
 254         int numberOfArtists;
 255         int numberOfAlbums;
 256         int numberOfSongs;
 257         unsigned long uptime;
 258         unsigned long dbUpdateTime;
 259         unsigned long playTime;
 260         unsigned long dbPlayTime;
 261 } mpd_Stats;
 262
 263 void mpd_sendStatsCommand(mpd_Connection * connection);
 264
 265 mpd_Stats * mpd_getStats(mpd_Connection * connection);
 266
 267 void mpd_freeStats(mpd_Stats * stats);
 268
 269 /* DIRECTORY STUFF */
 270
 271 /* mpd_Directory
 272  * used to store info fro directory (right now that just the path)
 273  */
 274 typedef struct _mpd_Directory {
 275         char * path;
 276 } mpd_Directory;
 277
 278 /* mpd_newDirectory
 279  * allocates memory for a new directory
 280  * use mpd_freeDirectory to free this memory
 281  */
 282 mpd_Directory * mpd_newDirectory(void);
 283
 284 /* mpd_freeDirectory
 285  * used to free memory allocated with mpd_newDirectory, and it frees
 286  * path of mpd_Directory, so be careful
 287  */
 288 void mpd_freeDirectory(mpd_Directory * directory);
 289
 290 /* mpd_directoryDup
 291  * works like strdup, but for mpd_Directory
 292  */
 293 mpd_Directory * mpd_directoryDup(mpd_Directory * directory);
 294
 295 /* PLAYLISTFILE STUFF */
 296
 297 /* mpd_PlaylistFile
 298  * stores info about playlist file returned by lsinfo
 299  */
 300 typedef struct _mpd_PlaylistFile {
 301         char * path;
 302 } mpd_PlaylistFile;
 303
 304 /* mpd_newPlaylistFile
 305  * allocates memory for new mpd_PlaylistFile, path is set to NULL
 306  * free this memory with mpd_freePlaylistFile
 307  */
 308 mpd_PlaylistFile * mpd_newPlaylistFile(void);
 309
 310 /* mpd_freePlaylist
 311  * free memory allocated for freePlaylistFile, will also free
 312  * path, so be careful
 313  */
 314 void mpd_freePlaylistFile(mpd_PlaylistFile * playlist);
 315
 316 /* mpd_playlistFileDup
 317  * works like strdup, but for mpd_PlaylistFile
 318  */
 319 mpd_PlaylistFile * mpd_playlistFileDup(mpd_PlaylistFile * playlist);
 320
 321 /* INFO ENTITY STUFF */
 322
 323 /* the type of entity returned from one of the commands that generates info
 324  * use in conjunction with mpd_InfoEntity.type
 325  */
 326 #define MPD_INFO_ENTITY_TYPE_DIRECTORY          0
 327 #define MPD_INFO_ENTITY_TYPE_SONG               1
 328 #define MPD_INFO_ENTITY_TYPE_PLAYLISTFILE       2
 329
 330 /* mpd_InfoEntity
 331  * stores info on stuff returned info commands
 332  */
 333 typedef struct mpd_InfoEntity {
 334         /* the type of entity, use with MPD_INFO_ENTITY_TYPE_* to determine
 335          * what this entity is (song, directory, etc...)
 336          */
 337         int type;
 338         /* the actual data you want, mpd_Song, mpd_Directory, etc */
 339         union {
 340                 mpd_Directory * directory;
 341                 mpd_Song * song;
 342                 mpd_PlaylistFile * playlistFile;
 343         } info;
 344 } mpd_InfoEntity;
 345
 346 mpd_InfoEntity * mpd_newInfoEntity(void);
 347
 348 void mpd_freeInfoEntity(mpd_InfoEntity * entity);
 349
 350 /* INFO COMMANDS AND STUFF */
 351
 352 /* use this function to loop over after calling Info/Listall functions */
 353 mpd_InfoEntity * mpd_getNextInfoEntity(mpd_Connection * connection);
 354
 355 /* fetches the currently seeletect song (the song referenced by status->song
 356  * and status->songid*/
 357 void mpd_sendCurrentSongCommand(mpd_Connection * connection);
 358
 359 /* songNum of -1, means to display the whole list */
 360 void mpd_sendPlaylistInfoCommand(mpd_Connection * connection, int songNum);
 361
 362 /* songId of -1, means to display the whole list */
 363 void mpd_sendPlaylistIdCommand(mpd_Connection * connection, int songId);
 364
 365 /* use this to get the changes in the playlist since version _playlist_ */
 366 void mpd_sendPlChangesCommand(mpd_Connection * connection, long long playlist);
 367
 368 /**
 369  * @param connection: A valid and connected mpd_Connection.
 370  * @param playlist: The playlist version you want the diff with.
 371  * A more bandwidth efficient version of the mpd_sendPlChangesCommand.
 372  * It only returns the pos+id of the changes song.
 373  */
 374 void mpd_sendPlChangesPosIdCommand(mpd_Connection * connection, long long playlist);
 375
 376 /* recursivel fetches all songs/dir/playlists in "dir* (no metadata is
 377  * returned) */
 378 void mpd_sendListallCommand(mpd_Connection * connection, const char * dir);
 379
 380 /* same as sendListallCommand, but also metadata is returned */
 381 void mpd_sendListallInfoCommand(mpd_Connection * connection, const char * dir);
 382
 383 /* non-recursive version of ListallInfo */
 384 void mpd_sendLsInfoCommand(mpd_Connection * connection, const char * dir);
 385
 386 #define MPD_TABLE_ARTIST        0
 387 #define MPD_TABLE_ALBUM         1
 388 #define MPD_TABLE_TITLE         2
 389 #define MPD_TABLE_FILENAME      3
 390
 391 void mpd_sendSearchCommand(mpd_Connection * connection, int table,
 392                 const char * str);
 393
 394 void mpd_sendFindCommand(mpd_Connection * connection, int table,
 395                 const char * str);
 396
 397 /* LIST TAG COMMANDS */
 398
 399 /* use this function fetch next artist entry, be sure to free the returned
 400  * string.  NULL means there are no more.  Best used with sendListArtists
 401  */
 402 char * mpd_getNextArtist(mpd_Connection * connection);
 403
 404 char * mpd_getNextAlbum(mpd_Connection * connection);
 405
 406 char * mpd_getNextTag(mpd_Connection *connection, int table);
 407
 408 /* list artist or albums by artist, arg1 should be set to the artist if
 409  * listing albums by a artist, otherwise NULL for listing all artists or albums
 410  */
 411 void mpd_sendListCommand(mpd_Connection * connection, int table,
 412                 const char * arg1);
 413
 414 /* SIMPLE COMMANDS */
 415
 416 void mpd_sendAddCommand(mpd_Connection * connection, const char * file);
 417
 418 void mpd_sendDeleteCommand(mpd_Connection * connection, int songNum);
 419
 420 void mpd_sendDeleteIdCommand(mpd_Connection * connection, int songNum);
 421
 422 void mpd_sendSaveCommand(mpd_Connection * connection, const char * name);
 423
 424 void mpd_sendLoadCommand(mpd_Connection * connection, const char * name);
 425
 426 void mpd_sendRmCommand(mpd_Connection * connection, const char * name);
 427
 428 void mpd_sendShuffleCommand(mpd_Connection * connection);
 429
 430 void mpd_sendShuffleRangeCommand(mpd_Connection * connection, unsigned start, unsigned end);
 431
 432 void mpd_sendClearCommand(mpd_Connection * connection);
 433
 434 /* use this to start playing at the beginning, useful when in random mode */
 435 #define MPD_PLAY_AT_BEGINNING   -1
 436
 437 void mpd_sendPlayCommand(mpd_Connection * connection, int songNum);
 438
 439 void mpd_sendPlayIdCommand(mpd_Connection * connection, int songNum);
 440
 441 void mpd_sendStopCommand(mpd_Connection * connection);
 442
 443 void mpd_sendPauseCommand(mpd_Connection * connection, int pauseMode);
 444
 445 void mpd_sendNextCommand(mpd_Connection * connection);
 446
 447 void mpd_sendPrevCommand(mpd_Connection * connection);
 448
 449 void mpd_sendMoveCommand(mpd_Connection * connection, int from, int to);
 450
 451 void mpd_sendMoveIdCommand(mpd_Connection * connection, int from, int to);
 452
 453 void mpd_sendSwapCommand(mpd_Connection * connection, int song1, int song2);
 454
 455 void mpd_sendSwapIdCommand(mpd_Connection * connection, int song1, int song2);
 456
 457 void mpd_sendSeekCommand(mpd_Connection * connection, int song, int to);
 458
 459 void mpd_sendSeekIdCommand(mpd_Connection * connection, int song, int to);
 460
 461 void mpd_sendRepeatCommand(mpd_Connection * connection, int repeatMode);
 462
 463 void mpd_sendRandomCommand(mpd_Connection * connection, int randomMode);
 464
 465 void mpd_sendSingleCommand(mpd_Connection * connection, int singleMode);
 466
 467 void mpd_sendConsumeCommand(mpd_Connection * connection, int consumeMode);
 468
 469 void mpd_sendSetvolCommand(mpd_Connection * connection, int volumeChange);
 470
 471 /* WARNING: don't use volume command, its deprecated */
 472 void mpd_sendVolumeCommand(mpd_Connection * connection, int volumeChange);
 473
 474 void mpd_sendCrossfadeCommand(mpd_Connection * connection, int seconds);
 475
 476 void mpd_sendUpdateCommand(mpd_Connection * connection, const char *path);
 477
 478 /* returns the update job id, call this after a update command*/
 479 int mpd_getUpdateId(mpd_Connection * connection);
 480
 481 void mpd_sendPasswordCommand(mpd_Connection * connection, const char * pass);
 482
 483 /* after executing a command, when your done with it to get its status
 484  * (you want to check connection->error for an error)
 485  */
 486 void mpd_finishCommand(mpd_Connection * connection);
 487
 488 /* command list stuff, use this to do things like add files very quickly */
 489 void mpd_sendCommandListBegin(mpd_Connection * connection);
 490
 491 void mpd_sendCommandListOkBegin(mpd_Connection * connection);
 492
 493 void mpd_sendCommandListEnd(mpd_Connection * connection);
 494
 495 /* advance to the next listOk
 496  * returns 0 if advanced to the next list_OK,
 497  * returns -1 if it advanced to an OK or ACK */
 498 int mpd_nextListOkCommand(mpd_Connection * connection);
 499
 500 typedef struct _mpd_OutputEntity {
 501         int id;
 502         char * name;
 503         int enabled;
 504 } mpd_OutputEntity;
 505
 506 void mpd_sendOutputsCommand(mpd_Connection * connection);
 507
 508 mpd_OutputEntity * mpd_getNextOutput(mpd_Connection * connection);
 509
 510 void mpd_sendEnableOutputCommand(mpd_Connection * connection, int outputId);
 511
 512 void mpd_sendDisableOutputCommand(mpd_Connection * connection, int outputId);
 513
 514 void mpd_freeOutputElement(mpd_OutputEntity * output);
 515
 516 /**
 517  * @param connection a #mpd_Connection
 518  *
 519  * Queries mpd for the allowed commands
 520  */
 521 void mpd_sendCommandsCommand(mpd_Connection * connection);
 522 /**
 523  * @param connection a #mpd_Connection
 524  *
 525  * Queries mpd for the not allowed commands
 526  */
 527 void mpd_sendNotCommandsCommand(mpd_Connection * connection);
 528
 529 /**
 530  * @param connection a #mpd_Connection
 531  *
 532  * returns the next supported command.
 533  *
 534  * @returns a string, needs to be free'ed
 535  */
 536 char *mpd_getNextCommand(mpd_Connection *connection);
 537
 538 /**
 539  * @param connection a MpdConnection
 540  * @param path  the path to the playlist.
 541  *
 542  * List the content, with full metadata, of a stored playlist.
 543  *
 544  */
 545 void mpd_sendListPlaylistInfoCommand(mpd_Connection *connection, char *path);
 546 /**
 547  * @param connection a MpdConnection
 548  * @param path  the path to the playlist.
 549  *
 550  * List the content of a stored playlist.
 551  *
 552  */
 553 void mpd_sendListPlaylistCommand(mpd_Connection *connection, char *path);
 554
 555 /**
 556  * @param connection a #mpd_Connection
 557  * @param exact if to match exact
 558  *
 559  * starts a search, use mpd_addConstraintSearch to add
 560  * a constraint to the search, and mpd_commitSearch to do the actual search
 561  */
 562 void mpd_startSearch(mpd_Connection * connection,int exact);
 563 /**
 564  * @param connection a #mpd_Connection
 565  * @param field
 566  * @param name
 567  *
 568  */
 569 void mpd_addConstraintSearch(mpd_Connection *connection, int field, char *name);
 570 /**
 571  * @param connection a #mpd_Connection
 572  *
 573  */
 574 void mpd_commitSearch(mpd_Connection *connection);
 575
 576 /**
 577  * @param connection a #mpd_Connection
 578  * @param field The field to search
 579  *
 580  * starts a search for fields... f.e. get a list of artists would be:
 581  * mpd_startFieldSearch(connection, MPD_TAG_ITEM_ARTIST);
 582  * mpd_commitSearch(connection);
 583  *
 584  * or get a list of artist in genre "jazz" would be:
 585  * @code
 586  * mpd_startFieldSearch(connection, MPD_TAG_ITEM_ARTIST);
 587  * mpd_addConstraintSearch(connection, MPD_TAG_ITEM_GENRE, "jazz")
 588  * mpd_commitSearch(connection);
 589  * @endcode
 590  *
 591  * mpd_startSearch will return  a list of songs (and you need mpd_getNextInfoEntity)
 592  * this one will return a list of only one field (the field specified with field) and you need
 593  * mpd_getNextTag to get the results
 594  */
 595 void mpd_startFieldSearch(mpd_Connection * connection,int field);
 596 #ifdef __cplusplus
 597 }
 598 #endif
 599
 600 #endif