libmpdclient.h

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