src/libmpdclient.h

   1 /* libmpdclient
   2    (c) 2003-2008 The Music Player Daemon Project
   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 "connection.h"
  37 #include "song.h"
  38
  39 #ifdef WIN32
  40 #  define __W32API_USE_DLLIMPORT__ 1
  41 #endif
  42
  43 #include <stddef.h>
  44 #include <sys/time.h>
  45 #include <stdarg.h>
  46 #ifdef MPD_GLIB
  47 #include <glib.h>
  48 #endif
  49
  50 #ifdef __cplusplus
  51 extern "C" {
  52 #endif
  53
  54 typedef enum mpd_TagItems
  55 {
  56         MPD_TAG_ITEM_ARTIST,
  57         MPD_TAG_ITEM_ALBUM,
  58         MPD_TAG_ITEM_TITLE,
  59         MPD_TAG_ITEM_TRACK,
  60         MPD_TAG_ITEM_NAME,
  61         MPD_TAG_ITEM_GENRE,
  62         MPD_TAG_ITEM_DATE,
  63         MPD_TAG_ITEM_COMPOSER,
  64         MPD_TAG_ITEM_PERFORMER,
  65         MPD_TAG_ITEM_COMMENT,
  66         MPD_TAG_ITEM_DISC,
  67         MPD_TAG_ITEM_FILENAME,
  68         MPD_TAG_ITEM_ANY,
  69         MPD_TAG_NUM_OF_ITEM_TYPES
  70 } mpd_TagItems;
  71
  72 extern const char *const mpdTagItemKeys[MPD_TAG_NUM_OF_ITEM_TYPES];
  73 typedef struct _mpd_Stats {
  74         int numberOfArtists;
  75         int numberOfAlbums;
  76         int numberOfSongs;
  77         unsigned long uptime;
  78         unsigned long dbUpdateTime;
  79         unsigned long playTime;
  80         unsigned long dbPlayTime;
  81 } mpd_Stats;
  82
  83 typedef struct _mpd_SearchStats {
  84         int numberOfSongs;
  85         unsigned long playTime;
  86 } mpd_SearchStats;
  87
  88 void mpd_sendStatsCommand(mpd_Connection * connection);
  89
  90 mpd_Stats * mpd_getStats(mpd_Connection * connection);
  91
  92 void mpd_freeStats(mpd_Stats * stats);
  93
  94 mpd_SearchStats * mpd_getSearchStats(mpd_Connection * connection);
  95
  96 void mpd_freeSearchStats(mpd_SearchStats * stats);
  97
  98 /* DIRECTORY STUFF */
  99
 100 /* mpd_Directory
 101  * used to store info fro directory (right now that just the path)
 102  */
 103 typedef struct _mpd_Directory {
 104         char * path;
 105 } mpd_Directory;
 106
 107 /* mpd_newDirectory
 108  * allocates memory for a new directory
 109  * use mpd_freeDirectory to free this memory
 110  */
 111 mpd_Directory * mpd_newDirectory(void);
 112
 113 /* mpd_freeDirectory
 114  * used to free memory allocated with mpd_newDirectory, and it frees
 115  * path of mpd_Directory, so be careful
 116  */
 117 void mpd_freeDirectory(mpd_Directory * directory);
 118
 119 /* mpd_directoryDup
 120  * works like strdup, but for mpd_Directory
 121  */
 122 mpd_Directory * mpd_directoryDup(const mpd_Directory * directory);
 123
 124 /* PLAYLISTFILE STUFF */
 125
 126 /* mpd_PlaylistFile
 127  * stores info about playlist file returned by lsinfo
 128  */
 129 typedef struct _mpd_PlaylistFile {
 130         char * path;
 131 } mpd_PlaylistFile;
 132
 133 /* mpd_newPlaylistFile
 134  * allocates memory for new mpd_PlaylistFile, path is set to NULL
 135  * free this memory with mpd_freePlaylistFile
 136  */
 137 mpd_PlaylistFile * mpd_newPlaylistFile(void);
 138
 139 /* mpd_freePlaylist
 140  * free memory allocated for freePlaylistFile, will also free
 141  * path, so be careful
 142  */
 143 void mpd_freePlaylistFile(mpd_PlaylistFile * playlist);
 144
 145 /* mpd_playlistFileDup
 146  * works like strdup, but for mpd_PlaylistFile
 147  */
 148 mpd_PlaylistFile * mpd_playlistFileDup(const mpd_PlaylistFile * playlist);
 149
 150 /* INFO ENTITY STUFF */
 151
 152 /* the type of entity returned from one of the commands that generates info
 153  * use in conjunction with mpd_InfoEntity.type
 154  */
 155 #define MPD_INFO_ENTITY_TYPE_DIRECTORY          0
 156 #define MPD_INFO_ENTITY_TYPE_SONG               1
 157 #define MPD_INFO_ENTITY_TYPE_PLAYLISTFILE       2
 158
 159 /* mpd_InfoEntity
 160  * stores info on stuff returned info commands
 161  */
 162 typedef struct mpd_InfoEntity {
 163         /* the type of entity, use with MPD_INFO_ENTITY_TYPE_* to determine
 164          * what this entity is (song, directory, etc...)
 165          */
 166         int type;
 167         /* the actual data you want, mpd_Song, mpd_Directory, etc */
 168         union {
 169                 mpd_Directory * directory;
 170                 struct mpd_song *song;
 171                 mpd_PlaylistFile * playlistFile;
 172         } info;
 173 } mpd_InfoEntity;
 174
 175 mpd_InfoEntity * mpd_newInfoEntity(void);
 176
 177 void mpd_freeInfoEntity(mpd_InfoEntity * entity);
 178
 179 /* INFO COMMANDS AND STUFF */
 180
 181 /* use this function to loop over after calling Info/Listall functions */
 182 mpd_InfoEntity * mpd_getNextInfoEntity(mpd_Connection * connection);
 183
 184 /* fetches the currently seeletect song (the song referenced by status->song
 185  * and status->songid*/
 186 void mpd_sendCurrentSongCommand(mpd_Connection * connection);
 187
 188 /* songNum of -1, means to display the whole list */
 189 void mpd_sendPlaylistInfoCommand(mpd_Connection * connection, int songNum);
 190
 191 /* songId of -1, means to display the whole list */
 192 void mpd_sendPlaylistIdCommand(mpd_Connection * connection, int songId);
 193
 194 /* use this to get the changes in the playlist since version _playlist_ */
 195 void mpd_sendPlChangesCommand(mpd_Connection * connection, long long playlist);
 196
 197 /**
 198  * @param connection: A valid and connected mpd_Connection.
 199  * @param playlist: The playlist version you want the diff with.
 200  * A more bandwidth efficient version of the mpd_sendPlChangesCommand.
 201  * It only returns the pos+id of the changes song.
 202  */
 203 void mpd_sendPlChangesPosIdCommand(mpd_Connection * connection, long long playlist);
 204
 205 /* recursivel fetches all songs/dir/playlists in "dir* (no metadata is
 206  * returned) */
 207 void mpd_sendListallCommand(mpd_Connection * connection, const char * dir);
 208
 209 /* same as sendListallCommand, but also metadata is returned */
 210 void mpd_sendListallInfoCommand(mpd_Connection * connection, const char * dir);
 211
 212 /* non-recursive version of ListallInfo */
 213 void mpd_sendLsInfoCommand(mpd_Connection * connection, const char * dir);
 214
 215 #define MPD_TABLE_ARTIST        MPD_TAG_ITEM_ARTIST
 216 #define MPD_TABLE_ALBUM         MPD_TAG_ITEM_ALBUM
 217 #define MPD_TABLE_TITLE         MPD_TAG_ITEM_TITLE
 218 #define MPD_TABLE_FILENAME      MPD_TAG_ITEM_FILENAME
 219
 220 void mpd_sendSearchCommand(mpd_Connection * connection, int table,
 221                 const char * str);
 222
 223 void mpd_sendFindCommand(mpd_Connection * connection, int table,
 224                 const char * str);
 225
 226 /* LIST TAG COMMANDS */
 227
 228 /* use this function fetch next artist entry, be sure to free the returned
 229  * string.  NULL means there are no more.  Best used with sendListArtists
 230  */
 231 char * mpd_getNextArtist(mpd_Connection * connection);
 232
 233 char * mpd_getNextAlbum(mpd_Connection * connection);
 234
 235 char * mpd_getNextTag(mpd_Connection *connection, int type);
 236
 237 /* list artist or albums by artist, arg1 should be set to the artist if
 238  * listing albums by a artist, otherwise NULL for listing all artists or albums
 239  */
 240 void mpd_sendListCommand(mpd_Connection * connection, int table,
 241                 const char * arg1);
 242
 243 /* SIMPLE COMMANDS */
 244
 245 void mpd_sendAddCommand(mpd_Connection * connection, const char * file);
 246
 247 int mpd_sendAddIdCommand(mpd_Connection *connection, const char *file);
 248
 249 void mpd_sendDeleteCommand(mpd_Connection * connection, int songNum);
 250
 251 void mpd_sendDeleteIdCommand(mpd_Connection * connection, int songNum);
 252
 253 void mpd_sendSaveCommand(mpd_Connection * connection, const char * name);
 254
 255 void mpd_sendLoadCommand(mpd_Connection * connection, const char * name);
 256
 257 void mpd_sendRmCommand(mpd_Connection * connection, const char * name);
 258
 259 void mpd_sendRenameCommand(mpd_Connection *connection, const char *from,
 260                            const char *to);
 261
 262 void mpd_sendShuffleCommand(mpd_Connection * connection);
 263
 264 void mpd_sendClearCommand(mpd_Connection * connection);
 265
 266 /* use this to start playing at the beginning, useful when in random mode */
 267 #define MPD_PLAY_AT_BEGINNING   -1
 268
 269 void mpd_sendPlayCommand(mpd_Connection * connection, int songNum);
 270
 271 void mpd_sendPlayIdCommand(mpd_Connection * connection, int songNum);
 272
 273 void mpd_sendStopCommand(mpd_Connection * connection);
 274
 275 void mpd_sendPauseCommand(mpd_Connection * connection, int pauseMode);
 276
 277 void mpd_sendNextCommand(mpd_Connection * connection);
 278
 279 void mpd_sendPrevCommand(mpd_Connection * connection);
 280
 281 void mpd_sendMoveCommand(mpd_Connection * connection, int from, int to);
 282
 283 void mpd_sendMoveIdCommand(mpd_Connection * connection, int from, int to);
 284
 285 void mpd_sendSwapCommand(mpd_Connection * connection, int song1, int song2);
 286
 287 void mpd_sendSwapIdCommand(mpd_Connection * connection, int song1, int song2);
 288
 289 void mpd_sendSeekCommand(mpd_Connection * connection, int song, int time);
 290
 291 void mpd_sendSeekIdCommand(mpd_Connection * connection, int song, int time);
 292
 293 void mpd_sendRepeatCommand(mpd_Connection * connection, int repeatMode);
 294
 295 void mpd_sendRandomCommand(mpd_Connection * connection, int randomMode);
 296
 297 void mpd_sendSetvolCommand(mpd_Connection * connection, int volumeChange);
 298
 299 /* WARNING: don't use volume command, its depreacted */
 300 void mpd_sendVolumeCommand(mpd_Connection * connection, int volumeChange);
 301
 302 void mpd_sendCrossfadeCommand(mpd_Connection * connection, int seconds);
 303
 304 void mpd_sendUpdateCommand(mpd_Connection * connection, const char *path);
 305
 306 /* returns the update job id, call this after a update command*/
 307 int mpd_getUpdateId(mpd_Connection * connection);
 308
 309 void mpd_sendPasswordCommand(mpd_Connection * connection, const char * pass);
 310
 311 /* after executing a command, when your done with it to get its status
 312  * (you want to check connection->error for an error)
 313  */
 314 void mpd_finishCommand(mpd_Connection * connection);
 315
 316 /* command list stuff, use this to do things like add files very quickly */
 317 void mpd_sendCommandListBegin(mpd_Connection * connection);
 318
 319 void mpd_sendCommandListOkBegin(mpd_Connection * connection);
 320
 321 void mpd_sendCommandListEnd(mpd_Connection * connection);
 322
 323 /* advance to the next listOk
 324  * returns 0 if advanced to the next list_OK,
 325  * returns -1 if it advanced to an OK or ACK */
 326 int mpd_nextListOkCommand(mpd_Connection * connection);
 327
 328 typedef struct _mpd_OutputEntity {
 329         int id;
 330         char * name;
 331         int enabled;
 332 } mpd_OutputEntity;
 333
 334 void mpd_sendOutputsCommand(mpd_Connection * connection);
 335
 336 mpd_OutputEntity * mpd_getNextOutput(mpd_Connection * connection);
 337
 338 void mpd_sendEnableOutputCommand(mpd_Connection * connection, int outputId);
 339
 340 void mpd_sendDisableOutputCommand(mpd_Connection * connection, int outputId);
 341
 342 void mpd_freeOutputElement(mpd_OutputEntity * output);
 343
 344 /**
 345  * @param connection a #mpd_Connection
 346  *
 347  * Queries mpd for the allowed commands
 348  */
 349 void mpd_sendCommandsCommand(mpd_Connection * connection);
 350
 351 /**
 352  * @param connection a #mpd_Connection
 353  *
 354  * Queries mpd for the not allowed commands
 355  */
 356 void mpd_sendNotCommandsCommand(mpd_Connection * connection);
 357
 358 /**
 359  * @param connection a #mpd_Connection
 360  *
 361  * returns the next supported command.
 362  *
 363  * @returns a string, needs to be free'ed
 364  */
 365 char *mpd_getNextCommand(mpd_Connection *connection);
 366
 367 void mpd_sendUrlHandlersCommand(mpd_Connection * connection);
 368
 369 char *mpd_getNextHandler(mpd_Connection * connection);
 370
 371 void mpd_sendTagTypesCommand(mpd_Connection * connection);
 372
 373 char *mpd_getNextTagType(mpd_Connection * connection);
 374
 375 /**
 376  * @param connection a MpdConnection
 377  * @param path  the path to the playlist.
 378  *
 379  * List the content, with full metadata, of a stored playlist.
 380  *
 381  */
 382 void mpd_sendListPlaylistInfoCommand(mpd_Connection *connection, char *path);
 383
 384 /**
 385  * @param connection a MpdConnection
 386  * @param path  the path to the playlist.
 387  *
 388  * List the content of a stored playlist.
 389  *
 390  */
 391 void mpd_sendListPlaylistCommand(mpd_Connection *connection, char *path);
 392
 393 /**
 394  * @param connection a #mpd_Connection
 395  * @param exact if to match exact
 396  *
 397  * starts a search, use mpd_addConstraintSearch to add
 398  * a constraint to the search, and mpd_commitSearch to do the actual search
 399  */
 400 void mpd_startSearch(mpd_Connection *connection, int exact);
 401
 402 /**
 403  * @param connection a #mpd_Connection
 404  * @param type
 405  * @param name
 406  */
 407 void mpd_addConstraintSearch(mpd_Connection *connection, int type, const char *name);
 408
 409 /**
 410  * @param connection a #mpd_Connection
 411  */
 412 void mpd_commitSearch(mpd_Connection *connection);
 413
 414 /**
 415  * @param connection a #mpd_Connection
 416  * @param type The type to search for
 417  *
 418  * starts a search for fields... f.e. get a list of artists would be:
 419  * @code
 420  * mpd_startFieldSearch(connection, MPD_TAG_ITEM_ARTIST);
 421  * mpd_commitSearch(connection);
 422  * @endcode
 423  *
 424  * or get a list of artist in genre "jazz" would be:
 425  * @code
 426  * mpd_startFieldSearch(connection, MPD_TAG_ITEM_ARTIST);
 427  * mpd_addConstraintSearch(connection, MPD_TAG_ITEM_GENRE, "jazz")
 428  * mpd_commitSearch(connection);
 429  * @endcode
 430  *
 431  * mpd_startSearch will return  a list of songs (and you need mpd_getNextInfoEntity)
 432  * this one will return a list of only one field (the one specified with type) and you need
 433  * mpd_getNextTag to get the results
 434  */
 435 void mpd_startFieldSearch(mpd_Connection *connection, int type);
 436
 437 void mpd_startPlaylistSearch(mpd_Connection *connection, int exact);
 438
 439 void mpd_startStatsSearch(mpd_Connection *connection);
 440
 441 void mpd_sendPlaylistClearCommand(mpd_Connection *connection, char *path);
 442
 443 void mpd_sendPlaylistAddCommand(mpd_Connection *connection,
 444                                 char *playlist, char *path);
 445
 446 void mpd_sendPlaylistMoveCommand(mpd_Connection *connection,
 447                                  char *playlist, int from, int to);
 448
 449 void mpd_sendPlaylistDeleteCommand(mpd_Connection *connection,
 450                                    char *playlist, int pos);
 451
 452 #ifdef __cplusplus
 453 }
 454 #endif
 455
 456 #endif