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 #ifdef __cplusplus
  40 extern "C" {
  41 #endif
  42
  43 /* internal stuff don't touch this struct */
  44 typedef struct _mpd_ReturnElement {
  45         char * name;
  46         char * value;
  47 } mpd_ReturnElement;
  48
  49 /* mpd_Connection
  50  * holds info about connection to mpd
  51  * use error, and errorStr to detect errors
  52  */
  53 typedef struct _mpd_Connection {
  54         /* use this to check the version of mpd */
  55         int version[3];
  56         /* IMPORTANT, you want to get the error messages from here */
  57         char errorStr[MPD_BUFFER_MAX_LENGTH+1];
  58         /* this will be set to 1 if there is an error, 0 if not */
  59         int error;
  60         /* DON'T TOUCH any of the rest of this stuff */
  61         int sock;
  62         char buffer[MPD_BUFFER_MAX_LENGTH+1];
  63         int buflen;
  64         int bufstart;
  65         int doneProcessing;
  66         int commandList;
  67         mpd_ReturnElement * returnElement;
  68         struct timeval timeout;
  69 } mpd_Connection;
  70
  71 /* mpd_newConnection
  72  * use this to open a new connection
  73  * you should use mpd_closeConnection, when your done with the connection,
  74  * even if an error has occurred
  75  * _timeout_ is the connection timeout period in seconds
  76  */
  77 mpd_Connection * mpd_newConnection(const char * host, int port, float timeout);
  78
  79 void mpd_setConnectionTimeout(mpd_Connection * connection, float timeout);
  80
  81 /* mpd_closeConnection
  82  * use this to close a connection and free'ing subsequent memory
  83  */
  84 void mpd_closeConnection(mpd_Connection * connection);
  85
  86 /* mpd_clearError
  87  * clears error
  88  */
  89 void mpd_clearError(mpd_Connection * connection);
  90
  91 /* STATUS STUFF */
  92
  93 /* use these with status.state to determine what state the player is in */
  94 #define MPD_STATUS_STATE_UNKNOWN        0
  95 #define MPD_STATUS_STATE_STOP           1
  96 #define MPD_STATUS_STATE_PLAY           2
  97 #define MPD_STATUS_STATE_PAUSE          3
  98
  99 /* us this with status.volume to determine if mpd has volume support */
 100 #define MPD_STATUS_NO_VOLUME            -1
 101
 102 /* mpd_Status
 103  * holds info return from status command
 104  */
 105 typedef struct mpd_Status {
 106         /* 0-100, or MPD_STATUS_NO_VOLUME when there is no volume support */
 107         int volume;
 108         /* 1 if repeat is on, 0 otherwise */
 109         int repeat;
 110         /* 1 if random is on, 0 otherwise */
 111         int random;
 112         /* playlist length */
 113         int playlistLength;
 114         /* playlist, use this to determine when the playlist has changed */
 115         long long playlist;
 116         /* use with MPD_STATUS_STATE_* to determine state of player */
 117         int state;
 118         /* crossfade setting in seconds */
 119         int crossfade;
 120         /* if in PLAY or PAUSE state, this is the number of the currently
 121          * playing song in the playlist, beginning with 0
 122          */
 123         int song;
 124         /* time in seconds that have elapsed in the currently playing/paused
 125          * song
 126          */
 127         int elapsedTime;
 128         /* length in seconds of the currently playing/paused song */
 129         int totalTime;
 130         /* current bit rate in kbs */
 131         int bitRate;
 132         /* audio sample rate */
 133         unsigned int sampleRate;
 134         /* audio bits */
 135         int bits;
 136         /* audio channels */
 137         int channels;
 138         /* 1 if mpd is updating, 0 otherwise */
 139         int updatingDb;
 140         /* error */
 141         char * error;
 142 } mpd_Status;
 143
 144 /* mpd_getStatus
 145  * returns status info, be sure to free it with mpd_freeStatus()
 146  */
 147 mpd_Status * mpd_getStatus(mpd_Connection * connection);
 148
 149 /* mpd_freeStatus
 150  * free's status info malloc'd and returned by mpd_getStatus
 151  */
 152 void mpd_freeStatus(mpd_Status * status);
 153
 154 typedef struct _mpd_Stats {
 155         int numberOfArtists;
 156         int numberOfAlbums;
 157         int numberOfSongs;
 158         unsigned long uptime;
 159         unsigned long dbUpdateTime;
 160         unsigned long playTime;
 161         unsigned long dbPlayTime;
 162 } mpd_Stats;
 163
 164 mpd_Stats * mpd_getStats(mpd_Connection * connection);
 165
 166 void mpd_freeStats(mpd_Stats * stats);
 167
 168 /* SONG STUFF */
 169
 170 #define MPD_SONG_NO_TIME        -1
 171
 172 /* mpd_Song
 173  * for storing song info returned by mpd
 174  */
 175 typedef struct _mpd_Song {
 176         /* filename of song */
 177         char * file;
 178         /* artist, maybe NULL if there is no tag */
 179         char * artist;
 180         /* title, maybe NULL if there is no tag */
 181         char * title;
 182         /* album, maybe NULL if there is no tag */
 183         char * album;
 184         /* track, maybe NULL if there is no tag */
 185         char * track;
 186         /* length of song in seconds, check that it is not MPD_SONG_NO_TIME  */
 187         int time;
 188 } mpd_Song;
 189
 190 /* mpd_newSong
 191  * use to allocate memory for a new mpd_Song
 192  * file, artist, etc all initialized to NULL
 193  * if your going to assign values to file, artist, etc
 194  * be sure to malloc or strdup the memory
 195  * use mpd_freeSong to free the memory for the mpd_Song, it will also
 196  * free memory for file, artist, etc, so don't do it yourself
 197  */
 198 mpd_Song * mpd_newSong();
 199
 200 /* mpd_freeSong
 201  * use to free memory allocated by mpd_newSong
 202  * also it will free memory pointed to by file, artist, etc, so be careful
 203  */
 204 void mpd_freeSong(mpd_Song * song);
 205
 206 /* mpd_songDup
 207  * works like strDup, but for a mpd_Song
 208  */
 209 mpd_Song * mpd_songDup(mpd_Song * song);
 210
 211 /* DIRECTORY STUFF */
 212
 213 /* mpd_Directory
 214  * used to store info fro directory (right now that just the path)
 215  */
 216 typedef struct _mpd_Directory {
 217         char * path;
 218 } mpd_Directory;
 219
 220 /* mpd_newDirectory
 221  * allocates memory for a new directory
 222  * use mpd_freeDirectory to free this memory
 223  */
 224 mpd_Directory * mpd_newDirectory ();
 225
 226 /* mpd_freeDirectory
 227  * used to free memory allocated with mpd_newDirectory, and it frees
 228  * path of mpd_Directory, so be careful
 229  */
 230 void mpd_freeDirectory(mpd_Directory * directory);
 231
 232 /* mpd_directoryDup
 233  * works like strdup, but for mpd_Directory
 234  */
 235 mpd_Directory * mpd_directoryDup(mpd_Directory * directory);
 236
 237 /* PLAYLISTFILE STUFF */
 238
 239 /* mpd_PlaylistFile
 240  * stores info about playlist file returned by lsinfo
 241  */
 242 typedef struct _mpd_PlaylistFile {
 243         char * path;
 244 } mpd_PlaylistFile;
 245
 246 /* mpd_newPlaylistFile
 247  * allocates memory for new mpd_PlaylistFile, path is set to NULL
 248  * free this memory with mpd_freePlaylistFile
 249  */
 250 mpd_PlaylistFile * mpd_newPlaylistFile();
 251
 252 /* mpd_freePlaylist
 253  * free memory allocated for freePlaylistFile, will also free
 254  * path, so be careful
 255  */
 256 void mpd_freePlaylistFile(mpd_PlaylistFile * playlist);
 257
 258 /* mpd_playlistFileDup
 259  * works like strdup, but for mpd_PlaylistFile
 260  */
 261 mpd_PlaylistFile * mpd_playlistFileDup(mpd_PlaylistFile * playlist);
 262
 263 /* INFO ENTITY STUFF */
 264
 265 /* the type of entity returned from one of the commands that generates info
 266  * use in conjunction with mpd_InfoEntity.type
 267  */
 268 #define MPD_INFO_ENTITY_TYPE_DIRECTORY          0
 269 #define MPD_INFO_ENTITY_TYPE_SONG               1
 270 #define MPD_INFO_ENTITY_TYPE_PLAYLISTFILE       2
 271
 272 /* mpd_InfoEntity
 273  * stores info on stuff returned info commands
 274  */
 275 typedef struct mpd_InfoEntity {
 276         /* the type of entity, use with MPD_INFO_ENTITY_TYPE_* to determine
 277          * what this entity is (song, directory, etc...)
 278          */
 279         int type;
 280         /* the actual data you want, mpd_Song, mpd_Directory, etc */
 281         union {
 282                 mpd_Directory * directory;
 283                 mpd_Song * song;
 284                 mpd_PlaylistFile * playlistFile;
 285         } info;
 286 } mpd_InfoEntity;
 287
 288 mpd_InfoEntity * mpd_newInfoEntity();
 289
 290 void mpd_freeInfoEntity(mpd_InfoEntity * entity);
 291
 292 /* INFO COMMANDS AND STUFF */
 293
 294 /* use this function to loop over after calling Info/Listall functions */
 295 mpd_InfoEntity * mpd_getNextInfoEntity(mpd_Connection * connection);
 296
 297 /* songNum of -1, means to display the whole list */
 298 void mpd_sendPlaylistInfoCommand(mpd_Connection * connection, int songNum);
 299
 300 void mpd_sendListallCommand(mpd_Connection * connection, const char * dir);
 301
 302 void mpd_sendListallInfoCommand(mpd_Connection * connection, const char * dir);
 303
 304 void mpd_sendLsInfoCommand(mpd_Connection * connection, const char * dir);
 305
 306 #define MPD_TABLE_ARTIST        0
 307 #define MPD_TABLE_ALBUM         1
 308 #define MPD_TABLE_TITLE         2
 309 #define MPD_TABLE_FILENAME      3
 310
 311 void mpd_sendSearchCommand(mpd_Connection * connection, int table,
 312                 const char * str);
 313
 314 void mpd_sendFindCommand(mpd_Connection * connection, int table,
 315                 const char * str);
 316
 317 /* LIST TAG COMMANDS */
 318
 319 /* use this function fetch next artist entry, be sure to free the returned
 320  * string.  NULL means there are no more.  Best used with sendListArtists
 321  */
 322 char * mpd_getNextArtist(mpd_Connection * connection);
 323
 324 char * mpd_getNextAlbum(mpd_Connection * connection);
 325
 326 /* list artist or albums by artist, arg1 should be set to the artist if
 327  * listing albums by a artist, otherwise NULL for listing all artists or albums
 328  */
 329 void mpd_sendListCommand(mpd_Connection * connection, int table,
 330                 const char * arg1);
 331
 332 /* SIMPLE COMMANDS */
 333
 334 void mpd_sendAddCommand(mpd_Connection * connection, const char * file);
 335
 336 void mpd_sendDeleteCommand(mpd_Connection * connection, int songNum);
 337
 338 void mpd_sendSaveCommand(mpd_Connection * connection, const char * name);
 339
 340 void mpd_sendLoadCommand(mpd_Connection * connection, const char * name);
 341
 342 void mpd_sendRmCommand(mpd_Connection * connection, const char * name);
 343
 344 void mpd_sendShuffleCommand(mpd_Connection * connection);
 345
 346 void mpd_sendClearCommand(mpd_Connection * connection);
 347
 348 /* use this to start playing at the beginning, useful when in random mode */
 349 #define MPD_PLAY_AT_BEGINNING   -1
 350
 351 void mpd_sendPlayCommand(mpd_Connection * connection, int songNum);
 352
 353 void mpd_sendStopCommand(mpd_Connection * connection);
 354
 355 void mpd_sendPauseCommand(mpd_Connection * connection);
 356
 357 void mpd_sendNextCommand(mpd_Connection * connection);
 358
 359 void mpd_sendPrevCommand(mpd_Connection * connection);
 360
 361 void mpd_sendMoveCommand(mpd_Connection * connection, int from, int to);
 362
 363 void mpd_sendSwapCommand(mpd_Connection * connection, int song1, int song2);
 364
 365 void mpd_sendSeekCommand(mpd_Connection * connection, int song, int time);
 366
 367 void mpd_sendRepeatCommand(mpd_Connection * connection, int repeatMode);
 368
 369 void mpd_sendRandomCommand(mpd_Connection * connection, int randomMode);
 370
 371 void mpd_sendSetvolCommand(mpd_Connection * connection, int volumeChange);
 372
 373 /* WARNING: don't use volume command, its depreacted */
 374 void mpd_sendVolumeCommand(mpd_Connection * connection, int volumeChange);
 375
 376 void mpd_sendCrossfadeCommand(mpd_Connection * connection, int seconds);
 377
 378 void mpd_sendUpdateCommand(mpd_Connection * connection);
 379
 380 /* returns the update job id, call this after a update command*/
 381 int mpd_getUpdateId(mpd_Connection * connection);
 382
 383 void mpd_sendPasswordCommand(mpd_Connection * connection, const char * pass);
 384
 385 /* after executing a command, when your done with it to get its status
 386  * (you want to check connection->error for an error)
 387  */
 388 void mpd_finishCommand(mpd_Connection * connection);
 389
 390 /* command list stuff, use this to do things like add files very quickly */
 391 void mpd_sendCommandListBegin(mpd_Connection * connection);
 392
 393 void mpd_sendCommandListEnd(mpd_Connection * connection);
 394
 395 #ifdef __cplusplus
 396 }
 397 #endif
 398
 399 #endif