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  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Lesser General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2.1 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU Lesser General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Lesser General Public
  16  * License along with this program; if not, write to the Free Software
  17  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  18  */
  19
  20 #ifndef LIBMPDCLIENT_H
  21 #define LIBMPDCLIENT_H
  22
  23 #include <sys/time.h>
  24
  25 #define MPD_BUFFER_MAX_LENGTH   50000
  26 #define MPD_WELCOME_MESSAGE     "OK MPD "
  27
  28 #define MPD_ERROR_TIMEOUT       10 /* timeout trying to talk to mpd */
  29 #define MPD_ERROR_SYSTEM        11 /* system error */
  30 #define MPD_ERROR_UNKHOST       12 /* unknown host */
  31 #define MPD_ERROR_CONNPORT      13 /* problems connecting to port on host */
  32 #define MPD_ERROR_NOTMPD        14 /* mpd not running on port at host */
  33 #define MPD_ERROR_NORESPONSE    15 /* no response on attempting to connect */
  34 #define MPD_ERROR_SENDING       16 /* error sending command */
  35 #define MPD_ERROR_CONNCLOSED    17 /* connection closed by mpd */
  36 #define MPD_ERROR_ACK           18 /* ACK returned! */
  37 #define MPD_ERROR_BUFFEROVERRUN 19 /* Buffer was overrun! */
  38
  39 #define MPD_ACK_ERROR_UNK       -1
  40 #define MPD_ERROR_AT_UNK        -1
  41
  42 #define MPD_ACK_ERROR_NOT_LIST                  1
  43 #define MPD_ACK_ERROR_ARG                       2
  44 #define MPD_ACK_ERROR_PASSWORD                  3
  45 #define MPD_ACK_ERROR_PERMISSION                4
  46 #define MPD_ACK_ERROR_UNKNOWN_CMD               5
  47
  48 #define MPD_ACK_ERROR_NO_EXIST                  50
  49 #define MPD_ACK_ERROR_PLAYLIST_MAX              51
  50 #define MPD_ACK_ERROR_SYSTEM                    52
  51 #define MPD_ACK_ERROR_PLAYLIST_LOAD             53
  52 #define MPD_ACK_ERROR_UPDATE_ALREADY            54
  53 #define MPD_ACK_ERROR_PLAYER_SYNC               55
  54 #define MPD_ACK_ERROR_EXIST                     56
  55
  56 #ifdef __cplusplus
  57 extern "C" {
  58 #endif
  59
  60 /* internal stuff don't touch this struct */
  61 typedef struct _mpd_ReturnElement {
  62         char * name;
  63         char * value;
  64 } mpd_ReturnElement;
  65
  66 /* mpd_Connection
  67  * holds info about connection to mpd
  68  * use error, and errorStr to detect errors
  69  */
  70 typedef struct _mpd_Connection {
  71         /* use this to check the version of mpd */
  72         int version[3];
  73         /* IMPORTANT, you want to get the error messages from here */
  74         char errorStr[MPD_BUFFER_MAX_LENGTH+1];
  75         int errorCode;
  76         int errorAt;
  77         /* this will be set to MPD_ERROR_* if there is an error, 0 if not */
  78         int error;
  79         /* DON'T TOUCH any of the rest of this stuff */
  80         int sock;
  81         char buffer[MPD_BUFFER_MAX_LENGTH+1];
  82         int buflen;
  83         int bufstart;
  84         int doneProcessing;
  85         int listOks;
  86         int doneListOk;
  87         int commandList;
  88         mpd_ReturnElement * returnElement;
  89         struct timeval timeout;
  90 } mpd_Connection;
  91
  92 /* mpd_newConnection
  93  * use this to open a new connection
  94  * you should use mpd_closeConnection, when your done with the connection,
  95  * even if an error has occurred
  96  * _timeout_ is the connection timeout period in seconds
  97  */
  98 mpd_Connection * mpd_newConnection(const char * host, int port, float timeout);
  99
 100 void mpd_setConnectionTimeout(mpd_Connection * connection, float timeout);
 101
 102 /* mpd_closeConnection
 103  * use this to close a connection and free'ing subsequent memory
 104  */
 105 void mpd_closeConnection(mpd_Connection * connection);
 106
 107 /* mpd_clearError
 108  * clears error
 109  */
 110 void mpd_clearError(mpd_Connection * connection);
 111
 112 /* STATUS STUFF */
 113
 114 /* use these with status.state to determine what state the player is in */
 115 #define MPD_STATUS_STATE_UNKNOWN        0
 116 #define MPD_STATUS_STATE_STOP           1
 117 #define MPD_STATUS_STATE_PLAY           2
 118 #define MPD_STATUS_STATE_PAUSE          3
 119
 120 /* us this with status.volume to determine if mpd has volume support */
 121 #define MPD_STATUS_NO_VOLUME            -1
 122
 123 /* mpd_Status
 124  * holds info return from status command
 125  */
 126 typedef struct mpd_Status {
 127         /* 0-100, or MPD_STATUS_NO_VOLUME when there is no volume support */
 128         int volume;
 129         /* 1 if repeat is on, 0 otherwise */
 130         int repeat;
 131         /* 1 if random is on, 0 otherwise */
 132         int random;
 133         /* playlist length */
 134         int playlistLength;
 135         /* playlist, use this to determine when the playlist has changed */
 136         long long playlist;
 137         /* use with MPD_STATUS_STATE_* to determine state of player */
 138         int state;
 139         /* crossfade setting in seconds */
 140         int crossfade;
 141         /* if a song is currently selected (always the case when state is
 142          * PLAY or PAUSE), this is the position of the currently
 143          * playing song in the playlist, beginning with 0
 144          */
 145         int song;
 146         /* Song ID of the currently selected song */
 147         int songid;
 148         /* time in seconds that have elapsed in the currently playing/paused
 149          * song
 150          */
 151         int elapsedTime;
 152         /* length in seconds of the currently playing/paused song */
 153         int totalTime;
 154         /* current bit rate in kbs */
 155         int bitRate;
 156         /* audio sample rate */
 157         unsigned int sampleRate;
 158         /* audio bits */
 159         int bits;
 160         /* audio channels */
 161         int channels;
 162         /* 1 if mpd is updating, 0 otherwise */
 163         int updatingDb;
 164         /* error */
 165         char * error;
 166 } mpd_Status;
 167
 168 void mpd_sendStatusCommand(mpd_Connection * connection);
 169
 170 /* mpd_getStatus
 171  * returns status info, be sure to free it with mpd_freeStatus()
 172  * call this after mpd_sendStatusCommand()
 173  */
 174 mpd_Status * mpd_getStatus(mpd_Connection * connection);
 175
 176 /* mpd_freeStatus
 177  * free's status info malloc'd and returned by mpd_getStatus
 178  */
 179 void mpd_freeStatus(mpd_Status * status);
 180
 181 typedef struct _mpd_Stats {
 182         int numberOfArtists;
 183         int numberOfAlbums;
 184         int numberOfSongs;
 185         unsigned long uptime;
 186         unsigned long dbUpdateTime;
 187         unsigned long playTime;
 188         unsigned long dbPlayTime;
 189 } mpd_Stats;
 190
 191 void mpd_sendStatsCommand(mpd_Connection * connection);
 192
 193 mpd_Stats * mpd_getStats(mpd_Connection * connection);
 194
 195 void mpd_freeStats(mpd_Stats * stats);
 196
 197 /* SONG STUFF */
 198
 199 #define MPD_SONG_NO_TIME        -1
 200 #define MPD_SONG_NO_NUM         -1
 201 #define MPD_SONG_NO_ID          -1
 202
 203 /* mpd_Song
 204  * for storing song info returned by mpd
 205  */
 206 typedef struct _mpd_Song {
 207         /* filename of song */
 208         char * file;
 209         /* artist, maybe NULL if there is no tag */
 210         char * artist;
 211         /* title, maybe NULL if there is no tag */
 212         char * title;
 213         /* album, maybe NULL if there is no tag */
 214         char * album;
 215         /* track, maybe NULL if there is no tag */
 216         char * track;
 217         /* name, maybe NULL if there is no tag; it's the name of the current
 218          * song, f.e. the icyName of the stream */
 219         char * name;
 220         /* length of song in seconds, check that it is not MPD_SONG_NO_TIME  */
 221         int time;
 222         /* if plchanges/playlistinfo/playlistid used, is the position of the
 223          * song in the playlist */
 224         int pos;
 225         /* song id for a song in the playlist */
 226         int id;
 227 } mpd_Song;
 228
 229 /* mpd_newSong
 230  * use to allocate memory for a new mpd_Song
 231  * file, artist, etc all initialized to NULL
 232  * if your going to assign values to file, artist, etc
 233  * be sure to malloc or strdup the memory
 234  * use mpd_freeSong to free the memory for the mpd_Song, it will also
 235  * free memory for file, artist, etc, so don't do it yourself
 236  */
 237 mpd_Song * mpd_newSong();
 238
 239 /* mpd_freeSong
 240  * use to free memory allocated by mpd_newSong
 241  * also it will free memory pointed to by file, artist, etc, so be careful
 242  */
 243 void mpd_freeSong(mpd_Song * song);
 244
 245 /* mpd_songDup
 246  * works like strDup, but for a mpd_Song
 247  */
 248 mpd_Song * mpd_songDup(mpd_Song * song);
 249
 250 /* DIRECTORY STUFF */
 251
 252 /* mpd_Directory
 253  * used to store info fro directory (right now that just the path)
 254  */
 255 typedef struct _mpd_Directory {
 256         char * path;
 257 } mpd_Directory;
 258
 259 /* mpd_newDirectory
 260  * allocates memory for a new directory
 261  * use mpd_freeDirectory to free this memory
 262  */
 263 mpd_Directory * mpd_newDirectory ();
 264
 265 /* mpd_freeDirectory
 266  * used to free memory allocated with mpd_newDirectory, and it frees
 267  * path of mpd_Directory, so be careful
 268  */
 269 void mpd_freeDirectory(mpd_Directory * directory);
 270
 271 /* mpd_directoryDup
 272  * works like strdup, but for mpd_Directory
 273  */
 274 mpd_Directory * mpd_directoryDup(mpd_Directory * directory);
 275
 276 /* PLAYLISTFILE STUFF */
 277
 278 /* mpd_PlaylistFile
 279  * stores info about playlist file returned by lsinfo
 280  */
 281 typedef struct _mpd_PlaylistFile {
 282         char * path;
 283 } mpd_PlaylistFile;
 284
 285 /* mpd_newPlaylistFile
 286  * allocates memory for new mpd_PlaylistFile, path is set to NULL
 287  * free this memory with mpd_freePlaylistFile
 288  */
 289 mpd_PlaylistFile * mpd_newPlaylistFile();
 290
 291 /* mpd_freePlaylist
 292  * free memory allocated for freePlaylistFile, will also free
 293  * path, so be careful
 294  */
 295 void mpd_freePlaylistFile(mpd_PlaylistFile * playlist);
 296
 297 /* mpd_playlistFileDup
 298  * works like strdup, but for mpd_PlaylistFile
 299  */
 300 mpd_PlaylistFile * mpd_playlistFileDup(mpd_PlaylistFile * playlist);
 301
 302 /* INFO ENTITY STUFF */
 303
 304 /* the type of entity returned from one of the commands that generates info
 305  * use in conjunction with mpd_InfoEntity.type
 306  */
 307 #define MPD_INFO_ENTITY_TYPE_DIRECTORY          0
 308 #define MPD_INFO_ENTITY_TYPE_SONG               1
 309 #define MPD_INFO_ENTITY_TYPE_PLAYLISTFILE       2
 310
 311 /* mpd_InfoEntity
 312  * stores info on stuff returned info commands
 313  */
 314 typedef struct mpd_InfoEntity {
 315         /* the type of entity, use with MPD_INFO_ENTITY_TYPE_* to determine
 316          * what this entity is (song, directory, etc...)
 317          */
 318         int type;
 319         /* the actual data you want, mpd_Song, mpd_Directory, etc */
 320         union {
 321                 mpd_Directory * directory;
 322                 mpd_Song * song;
 323                 mpd_PlaylistFile * playlistFile;
 324         } info;
 325 } mpd_InfoEntity;
 326
 327 mpd_InfoEntity * mpd_newInfoEntity();
 328
 329 void mpd_freeInfoEntity(mpd_InfoEntity * entity);
 330
 331 /* INFO COMMANDS AND STUFF */
 332
 333 /* use this function to loop over after calling Info/Listall functions */
 334 mpd_InfoEntity * mpd_getNextInfoEntity(mpd_Connection * connection);
 335
 336 /* fetches the currently seeletect song (the song referenced by status->song
 337  * and status->songid*/
 338 void mpd_sendCurrentSongCommand(mpd_Connection * connection);
 339
 340 /* songNum of -1, means to display the whole list */
 341 void mpd_sendPlaylistInfoCommand(mpd_Connection * connection, int songNum);
 342
 343 /* use this to get the changes in the playlist since version _playlist_ */
 344 void mpd_sendPlChangesCommand(mpd_Connection * connection, long long playlist);
 345
 346 /* recursivel fetches all songs/dir/playlists in "dir* (no metadata is
 347  * returned) */
 348 void mpd_sendListallCommand(mpd_Connection * connection, const char * dir);
 349
 350 /* same as sendListallCommand, but also metadata is returned */
 351 void mpd_sendListallInfoCommand(mpd_Connection * connection, const char * dir);
 352
 353 /* non-recursive version of ListallInfo */
 354 void mpd_sendLsInfoCommand(mpd_Connection * connection, const char * dir);
 355
 356 #define MPD_TABLE_ARTIST        0
 357 #define MPD_TABLE_ALBUM         1
 358 #define MPD_TABLE_TITLE         2
 359 #define MPD_TABLE_FILENAME      3
 360
 361 void mpd_sendSearchCommand(mpd_Connection * connection, int table,
 362                 const char * str);
 363
 364 void mpd_sendFindCommand(mpd_Connection * connection, int table,
 365                 const char * str);
 366
 367 /* LIST TAG COMMANDS */
 368
 369 /* use this function fetch next artist entry, be sure to free the returned
 370  * string.  NULL means there are no more.  Best used with sendListArtists
 371  */
 372 char * mpd_getNextArtist(mpd_Connection * connection);
 373
 374 char * mpd_getNextAlbum(mpd_Connection * connection);
 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);
 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 #ifdef __cplusplus
 463 }
 464 #endif
 465
 466 #endif