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
  77 typedef enum mpd_TagItems
  78 {
  79         MPD_TAG_ITEM_ARTIST,
  80         MPD_TAG_ITEM_ALBUM,
  81         MPD_TAG_ITEM_TITLE,
  82         MPD_TAG_ITEM_TRACK,
  83         MPD_TAG_ITEM_NAME,
  84         MPD_TAG_ITEM_GENRE,
  85         MPD_TAG_ITEM_DATE,
  86         MPD_TAG_ITEM_COMPOSER,
  87         MPD_TAG_ITEM_PERFORMER,
  88         MPD_TAG_ITEM_COMMENT,
  89         MPD_TAG_ITEM_DISC,
  90         MPD_TAG_ITEM_FILENAME,
  91         MPD_TAG_NUM_OF_ITEM_TYPES
  92 }mpd_TagItems;
  93
  94 extern char * mpdTagItemKeys[MPD_TAG_NUM_OF_ITEM_TYPES];
  95
  96 /* internal stuff don't touch this struct */
  97 typedef struct _mpd_ReturnElement {
  98         char * name;
  99         char * value;
 100 } mpd_ReturnElement;
 101
 102 /* mpd_Connection
 103  * holds info about connection to mpd
 104  * use error, and errorStr to detect errors
 105  */
 106 typedef struct _mpd_Connection {
 107         /* use this to check the version of mpd */
 108         int version[3];
 109         /* IMPORTANT, you want to get the error messages from here */
 110         char errorStr[MPD_BUFFER_MAX_LENGTH+1];
 111         int errorCode;
 112         int errorAt;
 113         /* this will be set to MPD_ERROR_* if there is an error, 0 if not */
 114         int error;
 115         /* DON'T TOUCH any of the rest of this stuff */
 116         int sock;
 117         char buffer[MPD_BUFFER_MAX_LENGTH+1];
 118         int buflen;
 119         int bufstart;
 120         int doneProcessing;
 121         int listOks;
 122         int doneListOk;
 123         int commandList;
 124         mpd_ReturnElement * returnElement;
 125         struct timeval timeout;
 126         char *request;
 127 } mpd_Connection;
 128
 129 /* mpd_newConnection
 130  * use this to open a new connection
 131  * you should use mpd_closeConnection, when your done with the connection,
 132  * even if an error has occurred
 133  * _timeout_ is the connection timeout period in seconds
 134  */
 135 mpd_Connection * mpd_newConnection(const char * host, int port, float timeout);
 136
 137 void mpd_setConnectionTimeout(mpd_Connection * connection, float timeout);
 138
 139 /* mpd_closeConnection
 140  * use this to close a connection and free'ing subsequent memory
 141  */
 142 void mpd_closeConnection(mpd_Connection * connection);
 143
 144 /* mpd_clearError
 145  * clears error
 146  */
 147 void mpd_clearError(mpd_Connection * connection);
 148
 149 /* STATUS STUFF */
 150
 151 /* use these with status.state to determine what state the player is in */
 152 #define MPD_STATUS_STATE_UNKNOWN        0
 153 #define MPD_STATUS_STATE_STOP           1
 154 #define MPD_STATUS_STATE_PLAY           2
 155 #define MPD_STATUS_STATE_PAUSE          3
 156
 157 /* us this with status.volume to determine if mpd has volume support */
 158 #define MPD_STATUS_NO_VOLUME            -1
 159
 160 /* mpd_Status
 161  * holds info return from status command
 162  */
 163 typedef struct mpd_Status {
 164         /* 0-100, or MPD_STATUS_NO_VOLUME when there is no volume support */
 165         int volume;
 166         /* 1 if repeat is on, 0 otherwise */
 167         int repeat;
 168         /* 1 if random is on, 0 otherwise */
 169         int random;
 170         /* playlist length */
 171         int playlistLength;
 172         /* playlist, use this to determine when the playlist has changed */
 173         long long playlist;
 174         /* use with MPD_STATUS_STATE_* to determine state of player */
 175         int state;
 176         /* crossfade setting in seconds */
 177         int crossfade;
 178         /* if a song is currently selected (always the case when state is
 179          * PLAY or PAUSE), this is the position of the currently
 180          * playing song in the playlist, beginning with 0
 181          */
 182         int song;
 183         /* Song ID of the currently selected song */
 184         int songid;
 185         /* time in seconds that have elapsed in the currently playing/paused
 186          * song
 187          */
 188         int elapsedTime;
 189         /* length in seconds of the currently playing/paused song */
 190         int totalTime;
 191         /* current bit rate in kbs */
 192         int bitRate;
 193         /* audio sample rate */
 194         unsigned int sampleRate;
 195         /* audio bits */
 196         int bits;
 197         /* audio channels */
 198         int channels;
 199         /* 1 if mpd is updating, 0 otherwise */
 200         int updatingDb;
 201         /* error */
 202         char * error;
 203 } mpd_Status;
 204
 205 void mpd_sendStatusCommand(mpd_Connection * connection);
 206
 207 /* mpd_getStatus
 208  * returns status info, be sure to free it with mpd_freeStatus()
 209  * call this after mpd_sendStatusCommand()
 210  */
 211 mpd_Status * mpd_getStatus(mpd_Connection * connection);
 212
 213 /* mpd_freeStatus
 214  * free's status info malloc'd and returned by mpd_getStatus
 215  */
 216 void mpd_freeStatus(mpd_Status * status);
 217
 218 typedef struct _mpd_Stats {
 219         int numberOfArtists;
 220         int numberOfAlbums;
 221         int numberOfSongs;
 222         unsigned long uptime;
 223         unsigned long dbUpdateTime;
 224         unsigned long playTime;
 225         unsigned long dbPlayTime;
 226 } mpd_Stats;
 227
 228 void mpd_sendStatsCommand(mpd_Connection * connection);
 229
 230 mpd_Stats * mpd_getStats(mpd_Connection * connection);
 231
 232 void mpd_freeStats(mpd_Stats * stats);
 233
 234 /* SONG STUFF */
 235
 236 #define MPD_SONG_NO_TIME        -1
 237 #define MPD_SONG_NO_NUM         -1
 238 #define MPD_SONG_NO_ID          -1
 239
 240 /* mpd_Song
 241  * for storing song info returned by mpd
 242  */
 243 typedef struct _mpd_Song {
 244         /* filename of song */
 245         char * file;
 246         /* artist, maybe NULL if there is no tag */
 247         char * artist;
 248         /* title, maybe NULL if there is no tag */
 249         char * title;
 250         /* album, maybe NULL if there is no tag */
 251         char * album;
 252         /* track, maybe NULL if there is no tag */
 253         char * track;
 254         /* name, maybe NULL if there is no tag; it's the name of the current
 255          * song, f.e. the icyName of the stream */
 256         char * name;
 257         /* date */
 258         char *date;
 259
 260         /* added by qball */
 261         /* Genre */
 262         char *genre;
 263         /* Composer */
 264         char *composer;
 265         /* Disc */
 266         char *disc;
 267         /* Comment */
 268         char *comment;
 269
 270         /* length of song in seconds, check that it is not MPD_SONG_NO_TIME  */
 271         int time;
 272         /* if plchanges/playlistinfo/playlistid used, is the position of the
 273          * song in the playlist */
 274         int pos;
 275         /* song id for a song in the playlist */
 276         int id;
 277 } mpd_Song;
 278
 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 /* songNum of -1, means to display the whole list */
 391 void mpd_sendPlaylistInfoCommand(mpd_Connection * connection, int songNum);
 392
 393 /* songId of -1, means to display the whole list */
 394 void mpd_sendPlaylistIdCommand(mpd_Connection * connection, int songId);
 395
 396 /* use this to get the changes in the playlist since version _playlist_ */
 397 void mpd_sendPlChangesCommand(mpd_Connection * connection, long long playlist);
 398
 399 /**
 400  * @param connection: A valid and connected mpd_Connection.
 401  * @param playlist: The playlist version you want the diff with.
 402  * A more bandwidth efficient version of the mpd_sendPlChangesCommand.
 403  * It only returns the pos+id of the changes song.
 404  */
 405 void mpd_sendPlChangesPosIdCommand(mpd_Connection * connection, long long playlist);
 406
 407 /* recursivel fetches all songs/dir/playlists in "dir* (no metadata is
 408  * returned) */
 409 void mpd_sendListallCommand(mpd_Connection * connection, const char * dir);
 410
 411 /* same as sendListallCommand, but also metadata is returned */
 412 void mpd_sendListallInfoCommand(mpd_Connection * connection, const char * dir);
 413
 414 /* non-recursive version of ListallInfo */
 415 void mpd_sendLsInfoCommand(mpd_Connection * connection, const char * dir);
 416
 417 #define MPD_TABLE_ARTIST        0
 418 #define MPD_TABLE_ALBUM         1
 419 #define MPD_TABLE_TITLE         2
 420 #define MPD_TABLE_FILENAME      3
 421
 422 void mpd_sendSearchCommand(mpd_Connection * connection, int table,
 423                 const char * str);
 424
 425 void mpd_sendFindCommand(mpd_Connection * connection, int table,
 426                 const char * str);
 427
 428 /* LIST TAG COMMANDS */
 429
 430 /* use this function fetch next artist entry, be sure to free the returned
 431  * string.  NULL means there are no more.  Best used with sendListArtists
 432  */
 433 char * mpd_getNextArtist(mpd_Connection * connection);
 434
 435 char * mpd_getNextAlbum(mpd_Connection * connection);
 436
 437 char * mpd_getNextTag(mpd_Connection *connection, int table);
 438
 439 /* list artist or albums by artist, arg1 should be set to the artist if
 440  * listing albums by a artist, otherwise NULL for listing all artists or albums
 441  */
 442 void mpd_sendListCommand(mpd_Connection * connection, int table,
 443                 const char * arg1);
 444
 445 /* SIMPLE COMMANDS */
 446
 447 void mpd_sendAddCommand(mpd_Connection * connection, const char * file);
 448
 449 void mpd_sendDeleteCommand(mpd_Connection * connection, int songNum);
 450
 451 void mpd_sendDeleteIdCommand(mpd_Connection * connection, int songNum);
 452
 453 void mpd_sendSaveCommand(mpd_Connection * connection, const char * name);
 454
 455 void mpd_sendLoadCommand(mpd_Connection * connection, const char * name);
 456
 457 void mpd_sendRmCommand(mpd_Connection * connection, const char * name);
 458
 459 void mpd_sendShuffleCommand(mpd_Connection * connection);
 460
 461 void mpd_sendClearCommand(mpd_Connection * connection);
 462
 463 /* use this to start playing at the beginning, useful when in random mode */
 464 #define MPD_PLAY_AT_BEGINNING   -1
 465
 466 void mpd_sendPlayCommand(mpd_Connection * connection, int songNum);
 467
 468 void mpd_sendPlayIdCommand(mpd_Connection * connection, int songNum);
 469
 470 void mpd_sendStopCommand(mpd_Connection * connection);
 471
 472 void mpd_sendPauseCommand(mpd_Connection * connection, int pauseMode);
 473
 474 void mpd_sendNextCommand(mpd_Connection * connection);
 475
 476 void mpd_sendPrevCommand(mpd_Connection * connection);
 477
 478 void mpd_sendMoveCommand(mpd_Connection * connection, int from, int to);
 479
 480 void mpd_sendMoveIdCommand(mpd_Connection * connection, int from, int to);
 481
 482 void mpd_sendSwapCommand(mpd_Connection * connection, int song1, int song2);
 483
 484 void mpd_sendSwapIdCommand(mpd_Connection * connection, int song1, int song2);
 485
 486 void mpd_sendSeekCommand(mpd_Connection * connection, int song, int time);
 487
 488 void mpd_sendSeekIdCommand(mpd_Connection * connection, int song, int time);
 489
 490 void mpd_sendRepeatCommand(mpd_Connection * connection, int repeatMode);
 491
 492 void mpd_sendRandomCommand(mpd_Connection * connection, int randomMode);
 493
 494 void mpd_sendSetvolCommand(mpd_Connection * connection, int volumeChange);
 495
 496 /* WARNING: don't use volume command, its depreacted */
 497 void mpd_sendVolumeCommand(mpd_Connection * connection, int volumeChange);
 498
 499 void mpd_sendCrossfadeCommand(mpd_Connection * connection, int seconds);
 500
 501 void mpd_sendUpdateCommand(mpd_Connection * connection, char * path);
 502
 503 /* returns the update job id, call this after a update command*/
 504 int mpd_getUpdateId(mpd_Connection * connection);
 505
 506 void mpd_sendPasswordCommand(mpd_Connection * connection, const char * pass);
 507
 508 /* after executing a command, when your done with it to get its status
 509  * (you want to check connection->error for an error)
 510  */
 511 void mpd_finishCommand(mpd_Connection * connection);
 512
 513 /* command list stuff, use this to do things like add files very quickly */
 514 void mpd_sendCommandListBegin(mpd_Connection * connection);
 515
 516 void mpd_sendCommandListOkBegin(mpd_Connection * connection);
 517
 518 void mpd_sendCommandListEnd(mpd_Connection * connection);
 519
 520 /* advance to the next listOk
 521  * returns 0 if advanced to the next list_OK,
 522  * returns -1 if it advanced to an OK or ACK */
 523 int mpd_nextListOkCommand(mpd_Connection * connection);
 524
 525 typedef struct _mpd_OutputEntity {
 526         int id;
 527         char * name;
 528         int enabled;
 529 } mpd_OutputEntity;
 530
 531 void mpd_sendOutputsCommand(mpd_Connection * connection);
 532
 533 mpd_OutputEntity * mpd_getNextOutput(mpd_Connection * connection);
 534
 535 void mpd_sendEnableOutputCommand(mpd_Connection * connection, int outputId);
 536
 537 void mpd_sendDisableOutputCommand(mpd_Connection * connection, int outputId);
 538
 539 void mpd_freeOutputElement(mpd_OutputEntity * output);
 540
 541 /**
 542  * @param connection a #mpd_Connection
 543  *
 544  * Queries mpd for the allowed commands
 545  */
 546 void mpd_sendCommandsCommand(mpd_Connection * connection);
 547 /**
 548  * @param connection a #mpd_Connection
 549  *
 550  * Queries mpd for the not allowed commands
 551  */
 552 void mpd_sendNotCommandsCommand(mpd_Connection * connection);
 553
 554 /**
 555  * @param connection a #mpd_Connection
 556  *
 557  * returns the next supported command.
 558  *
 559  * @returns a string, needs to be free'ed
 560  */
 561 char *mpd_getNextCommand(mpd_Connection *connection);
 562
 563 /**
 564  * @param connection a MpdConnection
 565  * @param path  the path to the playlist.
 566  *
 567  * List the content, with full metadata, of a stored playlist.
 568  *
 569  */
 570 void mpd_sendListPlaylistInfoCommand(mpd_Connection *connection, char *path);
 571 /**
 572  * @param connection a MpdConnection
 573  * @param path  the path to the playlist.
 574  *
 575  * List the content of a stored playlist.
 576  *
 577  */
 578 void mpd_sendListPlaylistCommand(mpd_Connection *connection, char *path);
 579
 580 /**
 581  * @param connection a #mpd_Connection
 582  * @param exact if to match exact
 583  *
 584  * starts a search, use mpd_addConstraintSearch to add
 585  * a constraint to the search, and mpd_commitSearch to do the actual search
 586  */
 587 void mpd_startSearch(mpd_Connection * connection,int exact);
 588 /**
 589  * @param connection a #mpd_Connection
 590  * @param field
 591  * @param name
 592  *
 593  */
 594 void mpd_addConstraintSearch(mpd_Connection *connection, int field, char *name);
 595 /**
 596  * @param connection a #mpd_Connection
 597  *
 598  */
 599 void mpd_commitSearch(mpd_Connection *connection);
 600
 601 /**
 602  * @param connection a #mpd_Connection
 603  * @param field The field to search
 604  *
 605  * starts a search for fields... f.e. get a list of artists would be:
 606  * mpd_startFieldSearch(connection, MPD_TAG_ITEM_ARTIST);
 607  * mpd_commitSearch(connection);
 608  *
 609  * or get a list of artist in genre "jazz" would be:
 610  * @code
 611  * mpd_startFieldSearch(connection, MPD_TAG_ITEM_ARTIST);
 612  * mpd_addConstraintSearch(connection, MPD_TAG_ITEM_GENRE, "jazz")
 613  * mpd_commitSearch(connection);
 614  * @endcode
 615  *
 616  * mpd_startSearch will return  a list of songs (and you need mpd_getNextInfoEntity)
 617  * this one will return a list of only one field (the field specified with field) and you need
 618  * mpd_getNextTag to get the results
 619  */
 620 void mpd_startFieldSearch(mpd_Connection * connection,int field);
 621 #ifdef __cplusplus
 622 }
 623 #endif
 624
 625 #endif