src/libmpdclient.h

   1 /* libmpdclient
   2    (c)2003-2006 by Warren Dukes (warren.dukes@gmail.com)
   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 #ifdef WIN32
  37 #  define __W32API_USE_DLLIMPORT__ 1
  38 #endif
  39
  40 #include <sys/time.h>
  41 #include <stdarg.h>
  42 #define MPD_BUFFER_MAX_LENGTH   50000
  43 #define MPD_WELCOME_MESSAGE     "OK MPD "
  44
  45 #define MPD_ERROR_TIMEOUT       10      /* timeout trying to talk to mpd */
  46 #define MPD_ERROR_SYSTEM        11      /* system error */
  47 #define MPD_ERROR_UNKHOST       12      /* unknown host */
  48 #define MPD_ERROR_CONNPORT      13      /* problems connecting to port on host */
  49 #define MPD_ERROR_NOTMPD        14      /* mpd not running on port at host */
  50 #define MPD_ERROR_NORESPONSE    15      /* no response on attempting to connect */
  51 #define MPD_ERROR_SENDING       16      /* error sending command */
  52 #define MPD_ERROR_CONNCLOSED    17      /* connection closed by mpd */
  53 #define MPD_ERROR_ACK           18      /* ACK returned! */
  54 #define MPD_ERROR_BUFFEROVERRUN 19      /* Buffer was overrun! */
  55
  56 #define MPD_ACK_ERROR_UNK       -1
  57 #define MPD_ERROR_AT_UNK        -1
  58
  59 #define MPD_ACK_ERROR_NOT_LIST                  1
  60 #define MPD_ACK_ERROR_ARG                       2
  61 #define MPD_ACK_ERROR_PASSWORD                  3
  62 #define MPD_ACK_ERROR_PERMISSION                4
  63 #define MPD_ACK_ERROR_UNKNOWN_CMD               5
  64
  65 #define MPD_ACK_ERROR_NO_EXIST                  50
  66 #define MPD_ACK_ERROR_PLAYLIST_MAX              51
  67 #define MPD_ACK_ERROR_SYSTEM                    52
  68 #define MPD_ACK_ERROR_PLAYLIST_LOAD             53
  69 #define MPD_ACK_ERROR_UPDATE_ALREADY            54
  70 #define MPD_ACK_ERROR_PLAYER_SYNC               55
  71 #define MPD_ACK_ERROR_EXIST                     56
  72
  73 #ifdef __cplusplus
  74 extern "C" {
  75 #endif
  76 #if 0
  77         typedef enum mpd_TagItems {
  78                 MPD_TAG_ITEM_ARTIST,
  79                 MPD_TAG_ITEM_ALBUM,
  80                 MPD_TAG_ITEM_TITLE,
  81                 MPD_TAG_ITEM_TRACK,
  82                 MPD_TAG_ITEM_NAME,
  83                 MPD_TAG_ITEM_GENRE,
  84                 MPD_TAG_ITEM_DATE,
  85                 MPD_TAG_ITEM_COMPOSER,
  86                 MPD_TAG_ITEM_PERFORMER,
  87                 MPD_TAG_ITEM_COMMENT,
  88                 MPD_TAG_ITEM_DISC,
  89                 MPD_TAG_ITEM_FILENAME,
  90                 MPD_TAG_NUM_OF_ITEM_TYPES
  91         } mpd_TagItems;
  92
  93         extern char *mpdTagItemKeys[MPD_TAG_NUM_OF_ITEM_TYPES];
  94 #endif
  95 /* internal stuff don't touch this struct */
  96         typedef struct _mpd_ReturnElement {
  97                 char *name;
  98                 char *value;
  99         } mpd_ReturnElement;
 100
 101 /* mpd_Connection
 102  * holds info about connection to mpd
 103  * use error, and errorStr to detect errors
 104  */
 105         typedef struct _mpd_Connection {
 106                 /* use this to check the version of mpd */
 107                 int version[3];
 108                 /* IMPORTANT, you want to get the error messages from here */
 109                 char errorStr[MPD_BUFFER_MAX_LENGTH + 1];
 110                 int errorCode;
 111                 int errorAt;
 112                 /* this will be set to MPD_ERROR_* if there is an error, 0 if not */
 113                 int error;
 114                 /* DON'T TOUCH any of the rest of this stuff */
 115                 int sock;
 116                 char buffer[MPD_BUFFER_MAX_LENGTH + 1];
 117                 int buflen;
 118                 int bufstart;
 119                 int doneProcessing;
 120                 int listOks;
 121                 int doneListOk;
 122                 int commandList;
 123                 mpd_ReturnElement *returnElement;
 124                 struct timeval timeout;
 125                 char *request;
 126         } mpd_Connection;
 127
 128 /* mpd_newConnection
 129  * use this to open a new connection
 130  * you should use mpd_closeConnection, when your done with the connection,
 131  * even if an error has occurred
 132  * _timeout_ is the connection timeout period in seconds
 133  */
 134         mpd_Connection *mpd_newConnection(const char *host, int port,
 135                                           float timeout);
 136
 137         void mpd_setConnectionTimeout(mpd_Connection * connection,
 138                                       float timeout);
 139
 140 /* mpd_closeConnection
 141  * use this to close a connection and free'ing subsequent memory
 142  */
 143         void mpd_closeConnection(mpd_Connection * connection);
 144
 145 /* mpd_clearError
 146  * clears error
 147  */
 148         void mpd_clearError(mpd_Connection * connection);
 149
 150 /* STATUS STUFF */
 151
 152 /* use these with status.state to determine what state the player is in */
 153 #define MPD_STATUS_STATE_UNKNOWN        0
 154 #define MPD_STATUS_STATE_STOP           1
 155 #define MPD_STATUS_STATE_PLAY           2
 156 #define MPD_STATUS_STATE_PAUSE          3
 157
 158 /* us this with status.volume to determine if mpd has volume support */
 159 #define MPD_STATUS_NO_VOLUME            -1
 160
 161 /* mpd_Status
 162  * holds info return from status command
 163  */
 164         typedef struct mpd_Status {
 165                 /* 0-100, or MPD_STATUS_NO_VOLUME when there is no volume support */
 166                 int volume;
 167                 /* 1 if repeat is on, 0 otherwise */
 168                 int repeat;
 169                 /* 1 if random is on, 0 otherwise */
 170                 int random;
 171                 /* playlist length */
 172                 int playlistLength;
 173                 /* playlist, use this to determine when the playlist has changed */
 174 /*              long long playlist; */
 175                 /* use with MPD_STATUS_STATE_* to determine state of player */
 176                 int state;
 177                 /* crossfade setting in seconds */
 178                 int crossfade;
 179                 /* if a song is currently selected (always the case when state is
 180                  * PLAY or PAUSE), this is the position of the currently
 181                  * playing song in the playlist, beginning with 0
 182                  */
 183                 int song;
 184                 /* Song ID of the currently selected song */
 185                 int songid;
 186                 /* time in seconds that have elapsed in the currently playing/paused
 187                  * song
 188                  */
 189                 int elapsedTime;
 190                 /* length in seconds of the currently playing/paused song */
 191                 int totalTime;
 192                 /* current bit rate in kbs */
 193                 int bitRate;
 194                 /* audio sample rate */
 195                 unsigned int sampleRate;
 196                 /* audio bits */
 197                 int bits;
 198                 /* audio channels */
 199                 int channels;
 200                 /* 1 if mpd is updating, 0 otherwise */
 201                 int updatingDb;
 202                 /* error */
 203                 char *error;
 204         } mpd_Status;
 205
 206         void mpd_sendStatusCommand(mpd_Connection * connection);
 207
 208 /* mpd_getStatus
 209  * returns status info, be sure to free it with mpd_freeStatus()
 210  * call this after mpd_sendStatusCommand()
 211  */
 212         mpd_Status *mpd_getStatus(mpd_Connection * connection);
 213
 214 /* mpd_freeStatus
 215  * free's status info malloc'd and returned by mpd_getStatus
 216  */
 217         void mpd_freeStatus(mpd_Status * status);
 218
 219         typedef struct _mpd_Stats {
 220                 int numberOfArtists;
 221                 int numberOfAlbums;
 222                 int numberOfSongs;
 223                 unsigned long uptime;
 224                 unsigned long dbUpdateTime;
 225                 unsigned long playTime;
 226                 unsigned long dbPlayTime;
 227         } mpd_Stats;
 228
 229         void mpd_sendStatsCommand(mpd_Connection * connection);
 230
 231         mpd_Stats *mpd_getStats(mpd_Connection * connection);
 232
 233         void mpd_freeStats(mpd_Stats * stats);
 234
 235 /* SONG STUFF */
 236
 237 #define MPD_SONG_NO_TIME        -1
 238 #define MPD_SONG_NO_NUM         -1
 239 #define MPD_SONG_NO_ID          -1
 240
 241 /* mpd_Song
 242  * for storing song info returned by mpd
 243  */
 244         typedef struct _mpd_Song {
 245                 /* filename of song */
 246                 char *file;
 247                 /* artist, maybe NULL if there is no tag */
 248                 char *artist;
 249                 /* title, maybe NULL if there is no tag */
 250                 char *title;
 251                 /* album, maybe NULL if there is no tag */
 252                 char *album;
 253                 /* track, maybe NULL if there is no tag */
 254                 char *track;
 255                 /* name, maybe NULL if there is no tag; it's the name of the current
 256                  * song, f.e. the icyName of the stream */
 257                 char *name;
 258                 /* date */
 259                 char *date;
 260
 261                 /* added by qball */
 262                 /* Genre */
 263                 char *genre;
 264                 /* Composer */
 265                 char *composer;
 266                 /* Disc */
 267                 char *disc;
 268                 /* Comment */
 269                 char *comment;
 270
 271                 /* length of song in seconds, check that it is not MPD_SONG_NO_TIME  */
 272                 int time;
 273                 /* if plchanges/playlistinfo/playlistid used, is the position of the
 274                  * song in the playlist */
 275                 int pos;
 276                 /* song id for a song in the playlist */
 277                 int id;
 278         } mpd_Song;
 279 /* mpd_newSong
 280  * use to allocate memory for a new mpd_Song
 281  * file, artist, etc all initialized to NULL
 282  * if your going to assign values to file, artist, etc
 283  * be sure to malloc or strdup the memory
 284  * use mpd_freeSong to free the memory for the mpd_Song, it will also
 285  * free memory for file, artist, etc, so don't do it yourself
 286  */
 287         mpd_Song *mpd_newSong(void);
 288
 289 /* mpd_freeSong
 290  * use to free memory allocated by mpd_newSong
 291  * also it will free memory pointed to by file, artist, etc, so be careful
 292  */
 293         void mpd_freeSong(mpd_Song * song);
 294
 295 /* mpd_songDup
 296  * works like strDup, but for a mpd_Song
 297  */
 298         mpd_Song *mpd_songDup(mpd_Song * song);
 299
 300 /* DIRECTORY STUFF */
 301
 302 /* mpd_Directory
 303  * used to store info fro directory (right now that just the path)
 304  */
 305         typedef struct _mpd_Directory {
 306                 char *path;
 307         } mpd_Directory;
 308
 309 /* mpd_newDirectory
 310  * allocates memory for a new directory
 311  * use mpd_freeDirectory to free this memory
 312  */
 313         mpd_Directory *mpd_newDirectory(void);
 314
 315 /* mpd_freeDirectory
 316  * used to free memory allocated with mpd_newDirectory, and it frees
 317  * path of mpd_Directory, so be careful
 318  */
 319         void mpd_freeDirectory(mpd_Directory * directory);
 320
 321 /* mpd_directoryDup
 322  * works like strdup, but for mpd_Directory
 323  */
 324         mpd_Directory *mpd_directoryDup(mpd_Directory * directory);
 325
 326 /* PLAYLISTFILE STUFF */
 327
 328 /* mpd_PlaylistFile
 329  * stores info about playlist file returned by lsinfo
 330  */
 331         typedef struct _mpd_PlaylistFile {
 332                 char *path;
 333         } mpd_PlaylistFile;
 334
 335 /* mpd_newPlaylistFile
 336  * allocates memory for new mpd_PlaylistFile, path is set to NULL
 337  * free this memory with mpd_freePlaylistFile
 338  */
 339         mpd_PlaylistFile *mpd_newPlaylistFile(void);
 340
 341 /* mpd_freePlaylist
 342  * free memory allocated for freePlaylistFile, will also free
 343  * path, so be careful
 344  */
 345         void mpd_freePlaylistFile(mpd_PlaylistFile * playlist);
 346
 347 /* mpd_playlistFileDup
 348  * works like strdup, but for mpd_PlaylistFile
 349  */
 350         mpd_PlaylistFile *mpd_playlistFileDup(mpd_PlaylistFile * playlist);
 351
 352 /* INFO ENTITY STUFF */
 353
 354 /* the type of entity returned from one of the commands that generates info
 355  * use in conjunction with mpd_InfoEntity.type
 356  */
 357 #define MPD_INFO_ENTITY_TYPE_DIRECTORY          0
 358 #define MPD_INFO_ENTITY_TYPE_SONG               1
 359 #define MPD_INFO_ENTITY_TYPE_PLAYLISTFILE       2
 360
 361 /* mpd_InfoEntity
 362  * stores info on stuff returned info commands
 363  */
 364         typedef struct mpd_InfoEntity {
 365                 /* the type of entity, use with MPD_INFO_ENTITY_TYPE_* to determine
 366                  * what this entity is (song, directory, etc...)
 367                  */
 368                 int type;
 369                 /* the actual data you want, mpd_Song, mpd_Directory, etc */
 370                 union {
 371                         mpd_Directory *directory;
 372                         mpd_Song *song;
 373                         mpd_PlaylistFile *playlistFile;
 374                 } info;
 375         } mpd_InfoEntity;
 376
 377         mpd_InfoEntity *mpd_newInfoEntity(void);
 378
 379         void mpd_freeInfoEntity(mpd_InfoEntity * entity);
 380
 381 /* INFO COMMANDS AND STUFF */
 382
 383 /* use this function to loop over after calling Info/Listall functions */
 384         mpd_InfoEntity *mpd_getNextInfoEntity(mpd_Connection * connection);
 385
 386 /* fetches the currently seeletect song (the song referenced by status->song
 387  * and status->songid*/
 388         void mpd_sendCurrentSongCommand(mpd_Connection * connection);
 389
 390
 391 /* songNum of -1, means to display the whole list */
 392         void mpd_sendPlaylistInfoCommand(mpd_Connection * connection,
 393                                          int songNum);
 394 #if 0
 395 /* songId of -1, means to display the whole list */
 396         void mpd_sendPlaylistIdCommand(mpd_Connection * connection, int songId);
 397
 398 /* use this to get the changes in the playlist since version _playlist_ */
 399         void mpd_sendPlChangesCommand(mpd_Connection * connection,
 400                                       long long playlist);
 401 #endif
 402 /**
 403  * @param connection: A valid and connected mpd_Connection.
 404  * @param playlist: The playlist version you want the diff with.
 405  * A more bandwidth efficient version of the mpd_sendPlChangesCommand.
 406  * It only returns the pos+id of the changes song.
 407  */
 408 #if 0
 409         void mpd_sendPlChangesPosIdCommand(mpd_Connection * connection,
 410                                            long long playlist);
 411 #endif
 412 /* recursivel fetches all songs/dir/playlists in "dir* (no metadata is
 413  * returned) */
 414         void mpd_sendListallCommand(mpd_Connection * connection,
 415                                     const char *dir);
 416
 417 /* same as sendListallCommand, but also metadata is returned */
 418         void mpd_sendListallInfoCommand(mpd_Connection * connection,
 419                                         const char *dir);
 420
 421 /* non-recursive version of ListallInfo */
 422         void mpd_sendLsInfoCommand(mpd_Connection * connection,
 423                                    const char *dir);
 424
 425 #define MPD_TABLE_ARTIST        0
 426 #define MPD_TABLE_ALBUM         1
 427 #define MPD_TABLE_TITLE         2
 428 #define MPD_TABLE_FILENAME      3
 429
 430         void mpd_sendSearchCommand(mpd_Connection * connection, int table,
 431                                    const char *str);
 432
 433         void mpd_sendFindCommand(mpd_Connection * connection, int table,
 434                                  const char *str);
 435
 436 /* LIST TAG COMMANDS */
 437
 438 /* use this function fetch next artist entry, be sure to free the returned
 439  * string.  NULL means there are no more.  Best used with sendListArtists
 440  */
 441         char *mpd_getNextArtist(mpd_Connection * connection);
 442
 443         char *mpd_getNextAlbum(mpd_Connection * connection);
 444
 445         char *mpd_getNextTag(mpd_Connection * connection, int table);
 446
 447 /* list artist or albums by artist, arg1 should be set to the artist if
 448  * listing albums by a artist, otherwise NULL for listing all artists or albums
 449  */
 450         void mpd_sendListCommand(mpd_Connection * connection, int table,
 451                                  const char *arg1);
 452
 453 /* SIMPLE COMMANDS */
 454
 455         void mpd_sendAddCommand(mpd_Connection * connection, const char *file);
 456
 457         void mpd_sendDeleteCommand(mpd_Connection * connection, int songNum);
 458
 459         void mpd_sendDeleteIdCommand(mpd_Connection * connection, int songNum);
 460
 461         void mpd_sendSaveCommand(mpd_Connection * connection, const char *name);
 462
 463         void mpd_sendLoadCommand(mpd_Connection * connection, const char *name);
 464
 465         void mpd_sendRmCommand(mpd_Connection * connection, const char *name);
 466
 467         void mpd_sendShuffleCommand(mpd_Connection * connection);
 468
 469         void mpd_sendClearCommand(mpd_Connection * connection);
 470
 471 /* use this to start playing at the beginning, useful when in random mode */
 472 #define MPD_PLAY_AT_BEGINNING   -1
 473
 474         void mpd_sendPlayCommand(mpd_Connection * connection, int songNum);
 475
 476         void mpd_sendPlayIdCommand(mpd_Connection * connection, int songNum);
 477
 478         void mpd_sendStopCommand(mpd_Connection * connection);
 479
 480         void mpd_sendPauseCommand(mpd_Connection * connection, int pauseMode);
 481
 482         void mpd_sendNextCommand(mpd_Connection * connection);
 483
 484         void mpd_sendPrevCommand(mpd_Connection * connection);
 485
 486         void mpd_sendMoveCommand(mpd_Connection * connection, int from, int to);
 487
 488         void mpd_sendMoveIdCommand(mpd_Connection * connection, int from,
 489                                    int to);
 490
 491         void mpd_sendSwapCommand(mpd_Connection * connection, int song1,
 492                                  int song2);
 493
 494         void mpd_sendSwapIdCommand(mpd_Connection * connection, int song1,
 495                                    int song2);
 496
 497         void mpd_sendSeekCommand(mpd_Connection * connection, int song,
 498                                  int time);
 499
 500         void mpd_sendSeekIdCommand(mpd_Connection * connection, int song,
 501                                    int time);
 502
 503         void mpd_sendRepeatCommand(mpd_Connection * connection, int repeatMode);
 504
 505         void mpd_sendRandomCommand(mpd_Connection * connection, int randomMode);
 506
 507         void mpd_sendSetvolCommand(mpd_Connection * connection,
 508                                    int volumeChange);
 509
 510 /* WARNING: don't use volume command, its depreacted */
 511         void mpd_sendVolumeCommand(mpd_Connection * connection,
 512                                    int volumeChange);
 513
 514         void mpd_sendCrossfadeCommand(mpd_Connection * connection, int seconds);
 515
 516         void mpd_sendUpdateCommand(mpd_Connection * connection, char *path);
 517
 518 /* returns the update job id, call this after a update command*/
 519         int mpd_getUpdateId(mpd_Connection * connection);
 520
 521         void mpd_sendPasswordCommand(mpd_Connection * connection,
 522                                      const char *pass);
 523
 524 /* after executing a command, when your done with it to get its status
 525  * (you want to check connection->error for an error)
 526  */
 527         void mpd_finishCommand(mpd_Connection * connection);
 528
 529 /* command list stuff, use this to do things like add files very quickly */
 530         void mpd_sendCommandListBegin(mpd_Connection * connection);
 531
 532         void mpd_sendCommandListOkBegin(mpd_Connection * connection);
 533
 534         void mpd_sendCommandListEnd(mpd_Connection * connection);
 535
 536 /* advance to the next listOk
 537  * returns 0 if advanced to the next list_OK,
 538  * returns -1 if it advanced to an OK or ACK */
 539         int mpd_nextListOkCommand(mpd_Connection * connection);
 540
 541         typedef struct _mpd_OutputEntity {
 542                 int id;
 543                 char *name;
 544                 int enabled;
 545         } mpd_OutputEntity;
 546
 547         void mpd_sendOutputsCommand(mpd_Connection * connection);
 548
 549         mpd_OutputEntity *mpd_getNextOutput(mpd_Connection * connection);
 550
 551         void mpd_sendEnableOutputCommand(mpd_Connection * connection,
 552                                          int outputId);
 553
 554         void mpd_sendDisableOutputCommand(mpd_Connection * connection,
 555                                           int outputId);
 556
 557         void mpd_freeOutputElement(mpd_OutputEntity * output);
 558
 559 /**
 560  * @param connection a #mpd_Connection
 561  *
 562  * Queries mpd for the allowed commands
 563  */
 564         void mpd_sendCommandsCommand(mpd_Connection * connection);
 565 /**
 566  * @param connection a #mpd_Connection
 567  *
 568  * Queries mpd for the not allowed commands
 569  */
 570         void mpd_sendNotCommandsCommand(mpd_Connection * connection);
 571
 572 /**
 573  * @param connection a #mpd_Connection
 574  *
 575  * returns the next supported command.
 576  *
 577  * @returns a string, needs to be free'ed
 578  */
 579         char *mpd_getNextCommand(mpd_Connection * connection);
 580
 581 /**
 582  * @param connection a MpdConnection
 583  * @param path  the path to the playlist.
 584  *
 585  * List the content, with full metadata, of a stored playlist.
 586  *
 587  */
 588         void mpd_sendListPlaylistInfoCommand(mpd_Connection * connection,
 589                                              char *path);
 590 /**
 591  * @param connection a MpdConnection
 592  * @param path  the path to the playlist.
 593  *
 594  * List the content of a stored playlist.
 595  *
 596  */
 597         void mpd_sendListPlaylistCommand(mpd_Connection * connection,
 598                                          char *path);
 599
 600 /**
 601  * @param connection a #mpd_Connection
 602  * @param exact if to match exact
 603  *
 604  * starts a search, use mpd_addConstraintSearch to add
 605  * a constraint to the search, and mpd_commitSearch to do the actual search
 606  */
 607         void mpd_startSearch(mpd_Connection * connection, int exact);
 608 /**
 609  * @param connection a #mpd_Connection
 610  * @param field
 611  * @param name
 612  *
 613  */
 614         void mpd_addConstraintSearch(mpd_Connection * connection, int field,
 615                                      char *name);
 616 /**
 617  * @param connection a #mpd_Connection
 618  *
 619  */
 620         void mpd_commitSearch(mpd_Connection * connection);
 621
 622 /**
 623  * @param connection a #mpd_Connection
 624  * @param field The field to search
 625  *
 626  * starts a search for fields... f.e. get a list of artists would be:
 627  * mpd_startFieldSearch(connection, MPD_TAG_ITEM_ARTIST);
 628  * mpd_commitSearch(connection);
 629  *
 630  * or get a list of artist in genre "jazz" would be:
 631  * @code
 632  * mpd_startFieldSearch(connection, MPD_TAG_ITEM_ARTIST);
 633  * mpd_addConstraintSearch(connection, MPD_TAG_ITEM_GENRE, "jazz")
 634  * mpd_commitSearch(connection);
 635  * @endcode
 636  *
 637  * mpd_startSearch will return  a list of songs (and you need mpd_getNextInfoEntity)
 638  * this one will return a list of only one field (the field specified with field) and you need
 639  * mpd_getNextTag to get the results
 640  */
 641         void mpd_startFieldSearch(mpd_Connection * connection, int field);
 642 #ifdef __cplusplus
 643 }
 644 #endif
 645 #endif