src/libmpdclient.h

   1 /* libmpdclient
   2    (c)2003-2004 by Warren Dukes (shank@mercury.chem.pitt.edu)
   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
  34 #ifndef LIBMPDCLIENT_H
  35 #define LIBMPDCLIENT_H
  36
  37 #include <sys/time.h>
  38
  39 #define MPD_BUFFER_MAX_LENGTH   50000
  40 #define MPD_WELCOME_MESSAGE     "OK MPD "
  41
  42 #define MPD_ERROR_TIMEOUT       10 /* timeout trying to talk to mpd */
  43 #define MPD_ERROR_SYSTEM        11 /* system error */
  44 #define MPD_ERROR_UNKHOST       12 /* unknown host */
  45 #define MPD_ERROR_CONNPORT      13 /* problems connecting to port on host */
  46 #define MPD_ERROR_NOTMPD        14 /* mpd not running on port at host */
  47 #define MPD_ERROR_NORESPONSE    15 /* no response on attempting to connect */
  48 #define MPD_ERROR_SENDING       16 /* error sending command */
  49 #define MPD_ERROR_CONNCLOSED    17 /* connection closed by mpd */
  50 #define MPD_ERROR_ACK           18 /* ACK returned! */
  51 #define MPD_ERROR_BUFFEROVERRUN 19 /* Buffer was overrun! */
  52
  53 #define MPD_ACK_ERROR_UNK       -1
  54 #define MPD_ERROR_AT_UNK        -1
  55
  56 #define MPD_ACK_ERROR_NOT_LIST                  1
  57 #define MPD_ACK_ERROR_ARG                       2
  58 #define MPD_ACK_ERROR_PASSWORD                  3
  59 #define MPD_ACK_ERROR_PERMISSION                4
  60 #define MPD_ACK_ERROR_UNKNOWN_CMD               5
  61
  62 #define MPD_ACK_ERROR_NO_EXIST                  50
  63 #define MPD_ACK_ERROR_PLAYLIST_MAX              51
  64 #define MPD_ACK_ERROR_SYSTEM                    52
  65 #define MPD_ACK_ERROR_PLAYLIST_LOAD             53
  66 #define MPD_ACK_ERROR_UPDATE_ALREADY            54
  67 #define MPD_ACK_ERROR_PLAYER_SYNC               55
  68 #define MPD_ACK_ERROR_EXIST                     56
  69
  70 #ifdef __cplusplus
  71 extern "C" {
  72 #endif
  73
  74 /* internal stuff don't touch this struct */
  75 typedef struct _mpd_ReturnElement {
  76         char * name;
  77         char * value;
  78 } mpd_ReturnElement;
  79
  80 /* mpd_Connection
  81  * holds info about connection to mpd
  82  * use error, and errorStr to detect errors
  83  */
  84 typedef struct _mpd_Connection {
  85         /* use this to check the version of mpd */
  86         int version[3];
  87         /* IMPORTANT, you want to get the error messages from here */
  88         char errorStr[MPD_BUFFER_MAX_LENGTH+1];
  89         int errorCode;
  90         int errorAt;
  91         /* this will be set to MPD_ERROR_* if there is an error, 0 if not */
  92         int error;
  93         /* DON'T TOUCH any of the rest of this stuff */
  94         int sock;
  95         char buffer[MPD_BUFFER_MAX_LENGTH+1];
  96         int buflen;
  97         int bufstart;
  98         int doneProcessing;
  99         int listOks;
 100         int doneListOk;
 101         int commandList;
 102         mpd_ReturnElement * returnElement;
 103         struct timeval timeout;
 104 } mpd_Connection;
 105
 106 /* mpd_newConnection
 107  * use this to open a new connection
 108  * you should use mpd_closeConnection, when your done with the connection,
 109  * even if an error has occurred
 110  * _timeout_ is the connection timeout period in seconds
 111  */
 112 mpd_Connection * mpd_newConnection(const char * host, int port, float timeout);
 113
 114 void mpd_setConnectionTimeout(mpd_Connection * connection, float timeout);
 115
 116 /* mpd_closeConnection
 117  * use this to close a connection and free'ing subsequent memory
 118  */
 119 void mpd_closeConnection(mpd_Connection * connection);
 120
 121 /* mpd_clearError
 122  * clears error
 123  */
 124 void mpd_clearError(mpd_Connection * connection);
 125
 126 /* STATUS STUFF */
 127
 128 /* use these with status.state to determine what state the player is in */
 129 #define MPD_STATUS_STATE_UNKNOWN        0
 130 #define MPD_STATUS_STATE_STOP           1
 131 #define MPD_STATUS_STATE_PLAY           2
 132 #define MPD_STATUS_STATE_PAUSE          3
 133
 134 /* us this with status.volume to determine if mpd has volume support */
 135 #define MPD_STATUS_NO_VOLUME            -1
 136
 137 /* mpd_Status
 138  * holds info return from status command
 139  */
 140 typedef struct mpd_Status {
 141         /* 0-100, or MPD_STATUS_NO_VOLUME when there is no volume support */
 142         int volume;
 143         /* 1 if repeat is on, 0 otherwise */
 144         int repeat;
 145         /* 1 if random is on, 0 otherwise */
 146         int random;
 147         /* playlist length */
 148         int playlistLength;
 149         /* playlist, use this to determine when the playlist has changed */
 150         long long playlist;
 151         /* use with MPD_STATUS_STATE_* to determine state of player */
 152         int state;
 153         /* crossfade setting in seconds */
 154         int crossfade;
 155         /* if a song is currently selected (always the case when state is
 156          * PLAY or PAUSE), this is the position of the currently
 157          * playing song in the playlist, beginning with 0
 158          */
 159         int song;
 160         /* Song ID of the currently selected song */
 161         int songid;
 162         /* time in seconds that have elapsed in the currently playing/paused
 163          * song
 164          */
 165         int elapsedTime;
 166         /* length in seconds of the currently playing/paused song */
 167         int totalTime;
 168         /* current bit rate in kbs */
 169         int bitRate;
 170         /* audio sample rate */
 171         unsigned int sampleRate;
 172         /* audio bits */
 173         int bits;
 174         /* audio channels */
 175         int channels;
 176         /* 1 if mpd is updating, 0 otherwise */
 177         int updatingDb;
 178         /* error */
 179         char * error;
 180 } mpd_Status;
 181
 182 void mpd_sendStatusCommand(mpd_Connection * connection);
 183
 184 /* mpd_getStatus
 185  * returns status info, be sure to free it with mpd_freeStatus()
 186  * call this after mpd_sendStatusCommand()
 187  */
 188 mpd_Status * mpd_getStatus(mpd_Connection * connection);
 189
 190 /* mpd_freeStatus
 191  * free's status info malloc'd and returned by mpd_getStatus
 192  */
 193 void mpd_freeStatus(mpd_Status * status);
 194
 195 typedef struct _mpd_Stats {
 196         int numberOfArtists;
 197         int numberOfAlbums;
 198         int numberOfSongs;
 199         unsigned long uptime;
 200         unsigned long dbUpdateTime;
 201         unsigned long playTime;
 202         unsigned long dbPlayTime;
 203 } mpd_Stats;
 204
 205 void mpd_sendStatsCommand(mpd_Connection * connection);
 206
 207 mpd_Stats * mpd_getStats(mpd_Connection * connection);
 208
 209 void mpd_freeStats(mpd_Stats * stats);
 210
 211 /* SONG STUFF */
 212
 213 #define MPD_SONG_NO_TIME        -1
 214 #define MPD_SONG_NO_NUM         -1
 215 #define MPD_SONG_NO_ID          -1
 216
 217 /* mpd_Song
 218  * for storing song info returned by mpd
 219  */
 220 typedef struct _mpd_Song {
 221         /* filename of song */
 222         char * file;
 223         /* artist, maybe NULL if there is no tag */
 224         char * artist;
 225         /* title, maybe NULL if there is no tag */
 226         char * title;
 227         /* album, maybe NULL if there is no tag */
 228         char * album;
 229         /* track, maybe NULL if there is no tag */
 230         char * track;
 231         /* name, maybe NULL if there is no tag; it's the name of the current
 232          * song, f.e. the icyName of the stream */
 233         char * name;
 234         /* length of song in seconds, check that it is not MPD_SONG_NO_TIME  */
 235         int time;
 236         /* if plchanges/playlistinfo/playlistid used, is the position of the
 237          * song in the playlist */
 238         int pos;
 239         /* song id for a song in the playlist */
 240         int id;
 241 } mpd_Song;
 242
 243 /* mpd_newSong
 244  * use to allocate memory for a new mpd_Song
 245  * file, artist, etc all initialized to NULL
 246  * if your going to assign values to file, artist, etc
 247  * be sure to malloc or strdup the memory
 248  * use mpd_freeSong to free the memory for the mpd_Song, it will also
 249  * free memory for file, artist, etc, so don't do it yourself
 250  */
 251 mpd_Song * mpd_newSong();
 252
 253 /* mpd_freeSong
 254  * use to free memory allocated by mpd_newSong
 255  * also it will free memory pointed to by file, artist, etc, so be careful
 256  */
 257 void mpd_freeSong(mpd_Song * song);
 258
 259 /* mpd_songDup
 260  * works like strDup, but for a mpd_Song
 261  */
 262 mpd_Song * mpd_songDup(mpd_Song * song);
 263
 264 /* DIRECTORY STUFF */
 265
 266 /* mpd_Directory
 267  * used to store info fro directory (right now that just the path)
 268  */
 269 typedef struct _mpd_Directory {
 270         char * path;
 271 } mpd_Directory;
 272
 273 /* mpd_newDirectory
 274  * allocates memory for a new directory
 275  * use mpd_freeDirectory to free this memory
 276  */
 277 mpd_Directory * mpd_newDirectory ();
 278
 279 /* mpd_freeDirectory
 280  * used to free memory allocated with mpd_newDirectory, and it frees
 281  * path of mpd_Directory, so be careful
 282  */
 283 void mpd_freeDirectory(mpd_Directory * directory);
 284
 285 /* mpd_directoryDup
 286  * works like strdup, but for mpd_Directory
 287  */
 288 mpd_Directory * mpd_directoryDup(mpd_Directory * directory);
 289
 290 /* PLAYLISTFILE STUFF */
 291
 292 /* mpd_PlaylistFile
 293  * stores info about playlist file returned by lsinfo
 294  */
 295 typedef struct _mpd_PlaylistFile {
 296         char * path;
 297 } mpd_PlaylistFile;
 298
 299 /* mpd_newPlaylistFile
 300  * allocates memory for new mpd_PlaylistFile, path is set to NULL
 301  * free this memory with mpd_freePlaylistFile
 302  */
 303 mpd_PlaylistFile * mpd_newPlaylistFile();
 304
 305 /* mpd_freePlaylist
 306  * free memory allocated for freePlaylistFile, will also free
 307  * path, so be careful
 308  */
 309 void mpd_freePlaylistFile(mpd_PlaylistFile * playlist);
 310
 311 /* mpd_playlistFileDup
 312  * works like strdup, but for mpd_PlaylistFile
 313  */
 314 mpd_PlaylistFile * mpd_playlistFileDup(mpd_PlaylistFile * playlist);
 315
 316 /* INFO ENTITY STUFF */
 317
 318 /* the type of entity returned from one of the commands that generates info
 319  * use in conjunction with mpd_InfoEntity.type
 320  */
 321 #define MPD_INFO_ENTITY_TYPE_DIRECTORY          0
 322 #define MPD_INFO_ENTITY_TYPE_SONG               1
 323 #define MPD_INFO_ENTITY_TYPE_PLAYLISTFILE       2
 324
 325 /* mpd_InfoEntity
 326  * stores info on stuff returned info commands
 327  */
 328 typedef struct mpd_InfoEntity {
 329         /* the type of entity, use with MPD_INFO_ENTITY_TYPE_* to determine
 330          * what this entity is (song, directory, etc...)
 331          */
 332         int type;
 333         /* the actual data you want, mpd_Song, mpd_Directory, etc */
 334         union {
 335                 mpd_Directory * directory;
 336                 mpd_Song * song;
 337                 mpd_PlaylistFile * playlistFile;
 338         } info;
 339 } mpd_InfoEntity;
 340
 341 mpd_InfoEntity * mpd_newInfoEntity();
 342
 343 void mpd_freeInfoEntity(mpd_InfoEntity * entity);
 344
 345 /* INFO COMMANDS AND STUFF */
 346
 347 /* use this function to loop over after calling Info/Listall functions */
 348 mpd_InfoEntity * mpd_getNextInfoEntity(mpd_Connection * connection);
 349
 350 /* fetches the currently seeletect song (the song referenced by status->song
 351  * and status->songid*/
 352 void mpd_sendCurrentSongCommand(mpd_Connection * connection);
 353
 354 /* songNum of -1, means to display the whole list */
 355 void mpd_sendPlaylistInfoCommand(mpd_Connection * connection, int songNum);
 356
 357 /* use this to get the changes in the playlist since version _playlist_ */
 358 void mpd_sendPlChangesCommand(mpd_Connection * connection, long long playlist);
 359
 360 /* recursivel fetches all songs/dir/playlists in "dir* (no metadata is
 361  * returned) */
 362 void mpd_sendListallCommand(mpd_Connection * connection, const char * dir);
 363
 364 /* same as sendListallCommand, but also metadata is returned */
 365 void mpd_sendListallInfoCommand(mpd_Connection * connection, const char * dir);
 366
 367 /* non-recursive version of ListallInfo */
 368 void mpd_sendLsInfoCommand(mpd_Connection * connection, const char * dir);
 369
 370 #define MPD_TABLE_ARTIST        0
 371 #define MPD_TABLE_ALBUM         1
 372 #define MPD_TABLE_TITLE         2
 373 #define MPD_TABLE_FILENAME      3
 374
 375 void mpd_sendSearchCommand(mpd_Connection * connection, int table,
 376                 const char * str);
 377
 378 void mpd_sendFindCommand(mpd_Connection * connection, int table,
 379                 const char * str);
 380
 381 /* LIST TAG COMMANDS */
 382
 383 /* use this function fetch next artist entry, be sure to free the returned
 384  * string.  NULL means there are no more.  Best used with sendListArtists
 385  */
 386 char * mpd_getNextArtist(mpd_Connection * connection);
 387
 388 char * mpd_getNextAlbum(mpd_Connection * connection);
 389
 390 /* list artist or albums by artist, arg1 should be set to the artist if
 391  * listing albums by a artist, otherwise NULL for listing all artists or albums
 392  */
 393 void mpd_sendListCommand(mpd_Connection * connection, int table,
 394                 const char * arg1);
 395
 396 /* SIMPLE COMMANDS */
 397
 398 void mpd_sendAddCommand(mpd_Connection * connection, const char * file);
 399
 400 void mpd_sendDeleteCommand(mpd_Connection * connection, int songNum);
 401
 402 void mpd_sendDeleteIdCommand(mpd_Connection * connection, int songNum);
 403
 404 void mpd_sendSaveCommand(mpd_Connection * connection, const char * name);
 405
 406 void mpd_sendLoadCommand(mpd_Connection * connection, const char * name);
 407
 408 void mpd_sendRmCommand(mpd_Connection * connection, const char * name);
 409
 410 void mpd_sendShuffleCommand(mpd_Connection * connection);
 411
 412 void mpd_sendClearCommand(mpd_Connection * connection);
 413
 414 /* use this to start playing at the beginning, useful when in random mode */
 415 #define MPD_PLAY_AT_BEGINNING   -1
 416
 417 void mpd_sendPlayCommand(mpd_Connection * connection, int songNum);
 418
 419 void mpd_sendPlayIdCommand(mpd_Connection * connection, int songNum);
 420
 421 void mpd_sendStopCommand(mpd_Connection * connection);
 422
 423 void mpd_sendPauseCommand(mpd_Connection * connection, int pauseMode);
 424
 425 void mpd_sendNextCommand(mpd_Connection * connection);
 426
 427 void mpd_sendPrevCommand(mpd_Connection * connection);
 428
 429 void mpd_sendMoveCommand(mpd_Connection * connection, int from, int to);
 430
 431 void mpd_sendMoveIdCommand(mpd_Connection * connection, int from, int to);
 432
 433 void mpd_sendSwapCommand(mpd_Connection * connection, int song1, int song2);
 434
 435 void mpd_sendSwapIdCommand(mpd_Connection * connection, int song1, int song2);
 436
 437 void mpd_sendSeekCommand(mpd_Connection * connection, int song, int time);
 438
 439 void mpd_sendSeekIdCommand(mpd_Connection * connection, int song, int time);
 440
 441 void mpd_sendRepeatCommand(mpd_Connection * connection, int repeatMode);
 442
 443 void mpd_sendRandomCommand(mpd_Connection * connection, int randomMode);
 444
 445 void mpd_sendSetvolCommand(mpd_Connection * connection, int volumeChange);
 446
 447 /* WARNING: don't use volume command, its depreacted */
 448 void mpd_sendVolumeCommand(mpd_Connection * connection, int volumeChange);
 449
 450 void mpd_sendCrossfadeCommand(mpd_Connection * connection, int seconds);
 451
 452 void mpd_sendUpdateCommand(mpd_Connection * connection, char * path);
 453
 454 /* returns the update job id, call this after a update command*/
 455 int mpd_getUpdateId(mpd_Connection * connection);
 456
 457 void mpd_sendPasswordCommand(mpd_Connection * connection, const char * pass);
 458
 459 /* after executing a command, when your done with it to get its status
 460  * (you want to check connection->error for an error)
 461  */
 462 void mpd_finishCommand(mpd_Connection * connection);
 463
 464 /* command list stuff, use this to do things like add files very quickly */
 465 void mpd_sendCommandListBegin(mpd_Connection * connection);
 466
 467 void mpd_sendCommandListOkBegin(mpd_Connection * connection);
 468
 469 void mpd_sendCommandListEnd(mpd_Connection * connection);
 470
 471 /* advance to the next listOk
 472  * returns 0 if advanced to the next list_OK,
 473  * returns -1 if it advanced to an OK or ACK */
 474 int mpd_nextListOkCommand(mpd_Connection * connection);
 475
 476 #ifdef __cplusplus
 477 }
 478 #endif
 479
 480 #endif