src/libmpd.h

   1 /* libmpd (high level libmpdclient library)
   2  * Copyright (C) 2004-2009 Qball Cow <qball@sarine.nl>
   3  * Project homepage: http://gmpcwiki.sarine.nl/
   4
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9
  10  * This program 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 General Public License for more details.
  14
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  18 */
  19
  20 /**
  21  * \example testcase.c
  22  * A small example of a console client using libmpd.
  23  */
  24
  25 /** \defgroup 1Basic Basic
  26  */
  27 /*@{*/
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 #ifndef __MPD_LIB__
  34 #define __MPD_LIB__
  35 #ifdef WIN32
  36 #define __REGEX_IMPORT__ 1
  37 #define __W32API_USE_DLLIMPORT__ 1
  38 #endif
  39
  40 #include "libmpdclient.h"
  41
  42 #ifndef TRUE
  43 /** Defined for readability: True is 1. */
  44 #define TRUE 1
  45 #endif
  46
  47 #ifndef FALSE
  48 /** Defined for readability: False is 0. */
  49 #define FALSE 0
  50 #endif
  51 #include "libmpd-version.h"
  52 extern char *libmpd_version;
  53
  54 /**
  55  * Enum that represent the errors libmpd functions can return
  56  */
  57
  58 typedef enum {
  59         /** Command/function completed succesfull */
  60         MPD_OK = 0,
  61         /** Error in the function's arguments */
  62         MPD_ARGS_ERROR = -5,
  63         /** Action failed because there is no connection to an mpd daemon */
  64         MPD_NOT_CONNECTED = -10,
  65         /** Failed to grab status*/
  66         MPD_STATUS_FAILED  = -20,
  67         /** Connection is still locked   */
  68         MPD_LOCK_FAILED  = -30,
  69         /** Failed to grab status        */
  70         MPD_STATS_FAILED = -40,
  71         /** Mpd server returned an error         */
  72         MPD_SERVER_ERROR = -50,
  73         /** Mpd doesn't support this feature */
  74         MPD_SERVER_NOT_SUPPORTED = -51,
  75
  76         /**  The playlist already exists         */
  77         MPD_DATABASE_PLAYLIST_EXIST  = -60,
  78         /** Playlist is empty */
  79         MPD_PLAYLIST_EMPTY = -70,
  80         /** Playlist queue is empty */
  81         MPD_PLAYLIST_QUEUE_EMPTY = -75,
  82         /** Player isn't Playing */
  83         MPD_PLAYER_NOT_PLAYING = -80,
  84
  85         /** Tag Item not found */
  86         MPD_TAG_NOT_FOUND = -90,
  87
  88         /** Fatal error, something I am not sure what todo with */
  89         MPD_FATAL_ERROR = -1000
  90 }MpdError;
  91
  92
  93
  94 /**
  95  *  The Main Mpd Object. Don't access any of the internal values directly, but use the provided functions.
  96  */
  97 typedef struct _MpdObj MpdObj;
  98
  99 /**
 100  *
 101  * enum that represents the state of a command.
 102  */
 103 typedef enum {
 104         MPD_SERVER_COMMAND_ALLOWED = TRUE,
 105         MPD_SERVER_COMMAND_NOT_ALLOWED = FALSE,
 106         MPD_SERVER_COMMAND_NOT_SUPPORTED = -1,
 107         MPD_SERVER_COMMAND_ERROR = -2
 108 } MpdServerCommand;
 109
 110
 111 /**
 112  * \ingroup MpdData
 113  * enumeration to determine what value the MpdData structure hold.
 114  * The MpdData structure can hold only one type of value,
 115  * but a list of MpdData structs can hold structs with different type of values.
 116  * It's required to check every MpdData Structure.
 117  */
 118 typedef enum {
 119         /** The MpdData structure holds no value*/
 120         MPD_DATA_TYPE_NONE,
 121         /** Holds an Tag String. value->tag is filled value->tag_type defines what type of tag.*/
 122         MPD_DATA_TYPE_TAG,
 123         /** Holds an Directory String. value->directory is filled.*/
 124         MPD_DATA_TYPE_DIRECTORY,
 125         /** Holds an MpdSong Structure. value->song is valid.*/
 126         MPD_DATA_TYPE_SONG,
 127         /** Holds an Playlist String. value->playlist is filled.*/
 128         MPD_DATA_TYPE_PLAYLIST,
 129         /** Holds an MpdOutputDevice structure. value->output_dev is valid.*/
 130         MPD_DATA_TYPE_OUTPUT_DEV
 131 } MpdDataType;
 132
 133 /**
 134  * \ingroup #MpdData
 135  * A fast linked list that is used to pass data from libmpd to the client.
 136  */
 137 typedef struct _MpdData {
 138         /** a #MpdDataType */
 139         MpdDataType type;
 140         union {
 141                 struct {
 142                         /** a #mpd_TagItems defining what #tag contains */
 143                         int tag_type;
 144                         /** a string containing the tag*/
 145                         char *tag;
 146                 };
 147                 /** a directory */
 148                 char *directory;
 149                 /** a path to a playlist */
 150                 mpd_PlaylistFile *playlist;
 151                 /** a  mpd_Song */
 152                 mpd_Song *song;
 153                 /** an output device entity */
 154                 mpd_OutputEntity *output_dev;
 155         };
 156
 157     void *userdata;
 158     void (*freefunc)(void *userdata);
 159 } MpdData;
 160
 161
 162 #include "libmpd-player.h"
 163 #include "libmpd-status.h"
 164 #include "libmpd-database.h"
 165 #include "libmpd-playlist.h"
 166 #include "libmpd-strfsong.h"
 167 #include "libmpd-sticker.h"
 168
 169
 170
 171 /**
 172  * mpd_new_default
 173  *
 174  * Create a new #MpdObj with default settings.
 175  * Hostname will be set to "localhost".
 176  * Port will be 6600.
 177  *
 178  * same as calling:
 179  * @code
 180  * mpd_new("localhost",6600,NULL);
 181  * @endcode
 182  *
 183  * @returns the new #MpdObj
 184  */
 185 MpdObj *mpd_new_default();
 186
 187
 188
 189 /**
 190  * @param hostname The hostname to connect to
 191  * @param port The port to connect to
 192  * @param password The password to use for the connection, or NULL for no password
 193  *
 194  * Create a new #MpdObj with provided settings:
 195  *
 196  * @returns the new #MpdObj
 197  */
 198
 199 MpdObj *mpd_new(char *hostname, int port, char *password);
 200
 201
 202
 203 /**
 204  *@param mi a #MpdObj
 205  *@param hostname The new hostname to use
 206  *
 207  * set the hostname
 208  *
 209  * @returns a #MpdError. (#MPD_OK if everything went ok)
 210  */
 211 int mpd_set_hostname(MpdObj * mi, char *hostname);
 212
 213 /**
 214  * @param mi a #MpdObj
 215  *
 216  * gets the set hostname
 217  *
 218  * @returns a const char representing the hostname
 219  */
 220 const char * mpd_get_hostname(MpdObj *mi);
 221
 222 /**
 223  * @param mi a #MpdObj
 224  * @param password The new password to use
 225  *
 226  * Set the password
 227  *
 228  * @returns a #MpdError. (#MPD_OK if everything went ok)
 229  */
 230 int mpd_set_password(MpdObj * mi,const char *password);
 231
 232
 233 /**
 234  * @param mi a #MpdObj
 235  * @param port The port to use. (Default: 6600)
 236  *
 237  * Set the Port number
 238  *
 239  *
 240  * @returns a #MpdError. (#MPD_OK if everything went ok)
 241  */
 242 int mpd_set_port(MpdObj * mi, int port);
 243
 244
 245
 246
 247 /**
 248  * @param mi a #MpdObj
 249  * @param timeout: A timeout (in seconds)
 250  *
 251  * Set the timeout of the connection.
 252  * If already connected the timeout of the running connection
 253  *
 254  * @returns a #MpdError. (MPD_OK if everything went ok)
 255  */
 256 int mpd_set_connection_timeout(MpdObj * mi, float timeout);
 257
 258
 259 int mpd_connect_real(MpdObj *mi,mpd_Connection *connection);
 260 /**
 261  * @param mi a #MpdObj
 262  *
 263  * Connect to the mpd daemon.
 264  * Warning: mpd_connect connects anonymous, to authenticate use #mpd_send_password
 265  *
 266  * @returns returns a #MpdError, MPD_OK when successful
 267  */
 268 int mpd_connect(MpdObj * mi);
 269
 270
 271 /**
 272  * @param mi The #MpdObj to disconnect
 273  *
 274  * Disconnect the current connection
 275  * @returns MPD_OK (always)
 276  */
 277 int mpd_disconnect(MpdObj * mi);
 278
 279
 280
 281 /**
 282  * @param mi    a #MpdObj
 283  *
 284  * Checks if #MpdObj is connected
 285  * @returns True when connected
 286  */
 287 int mpd_check_connected(MpdObj * mi);
 288
 289
 290
 291 /**
 292  * @param mi a #MpdObj
 293  *
 294  * Checks if there was an error
 295  * @returns True when there is an error
 296  */
 297 int mpd_check_error(MpdObj * mi);
 298
 299
 300
 301 /**
 302  * @param mi a #MpdObj
 303  *
 304  * Free the #MpdObj, when still connected the connection will be disconnected first
 305  */
 306 void mpd_free(MpdObj * mi);
 307
 308
 309
 310 /**
 311  * @param mi a #MpdObj
 312  *
 313  * Forces libmpd to re-authenticate itself.
 314  *
 315  * When successful it will trigger the "permission" changed signal.
 316  *
 317  * @returns: a #MpdError
 318  */
 319 int mpd_send_password(MpdObj * mi);
 320
 321
 322
 323 /*
 324  * signals
 325  */
 326
 327 /**
 328  * Bitwise enumeration to determine what triggered the status_changed signals
 329  * This is used in combination with the #StatusChangedCallback
 330  * @code
 331  * void status_changed_callback(MpdObj *mi, ChangedStatusType what)
 332  * {
 333  *      if(what&MPD_CST_SONGID)
 334  *      {
 335  *              // act on song change
 336  *
 337  *      }
 338  *      if(what&MPD_CST_RANDOM)
 339  *      {
 340  *              // act on random change
 341  *      }
 342  *      // etc.
 343  * }
 344  * @endcode
 345  */
 346 typedef enum {
 347         /** The playlist has changed */
 348         MPD_CST_PLAYLIST      = 0x0001,
 349         /** The song position of the playing song has changed*/
 350         MPD_CST_SONGPOS       = 0x0002,
 351         /** The songid of the playing song has changed */
 352         MPD_CST_SONGID        = 0x0004,
 353         /** The database has changed. */
 354         MPD_CST_DATABASE      = 0x0008,
 355         /** the state of updating the database has changed.*/
 356         MPD_CST_UPDATING      = 0x0010,
 357         /** the volume has changed */
 358         MPD_CST_VOLUME        = 0x0020,
 359         /** The total time of the currently playing song has changed*/
 360         MPD_CST_TOTAL_TIME    = 0x0040,
 361         /** The elapsed time of the current song has changed.*/
 362         MPD_CST_ELAPSED_TIME  = 0x0080,
 363         /** The crossfade time has changed. */
 364         MPD_CST_CROSSFADE     = 0x0100,
 365         /** The random state is changed.     */
 366         MPD_CST_RANDOM        = 0x0200,
 367         /** repeat state is changed.     */
 368         MPD_CST_REPEAT        = 0x0400,
 369         /** Not implemented  */
 370         MPD_CST_AUDIO         = 0x0800,
 371         /** The state of the player has changed.*/
 372         MPD_CST_STATE         = 0x1000,
 373         /** The permissions the client has, has changed.*/
 374         MPD_CST_PERMISSION    = 0x2000,
 375         /** The bitrate of the playing song has changed.    */
 376         MPD_CST_BITRATE       = 0x4000,
 377         /** the audio format of the playing song changed.*/
 378         MPD_CST_AUDIOFORMAT   = 0x8000,
 379         /** the queue has changed */
 380         MPD_CST_STORED_PLAYLIST           = 0x20000,
 381     /** server error */
 382     MPD_CST_SERVER_ERROR        = 0x40000,
 383     /** output changed */
 384     MPD_CST_OUTPUT              = 0x80000,
 385     /** Sticker changed */
 386     MPD_CST_STICKER             = 0x100000,
 387     /** Next song changed */
 388     MPD_CST_NEXTSONG            = 0x200000,
 389     /** Single mode changed */
 390     MPD_CST_SINGLE_MODE         = 0x400000,
 391     /** Consume mode changed */
 392     MPD_CST_CONSUME_MODE        = 0x800000
 393 } ChangedStatusType;
 394
 395
 396 /* callback typedef's */
 397 /**
 398  * @param mi a #MpdObj
 399  * @param what a #ChangedStatusType that determines what changed triggered the signal. This is a bitmask.
 400  * @param userdata user data set when the signal handler was connected.
 401  *
 402  * Signal that gets called when the state of mpd has changed. Look #ChangedStatusType to see the possible events.
 403  */
 404 typedef void (*StatusChangedCallback) (MpdObj * mi, ChangedStatusType what, void *userdata);
 405
 406
 407
 408
 409 /**
 410  * @param mi a #MpdObj
 411  * @param id The error Code.
 412  * @param msg human-readable informative error message.
 413  * @param userdata  user data set when the signal handler was connected.
 414  * This signal is called when an error has occurred in the communication with mpd.
 415  *
 416  * return: TRUE if libmpd should disconnect.
 417  */
 418 typedef int (*ErrorCallback) (MpdObj * mi, int id, char *msg, void *userdata);
 419
 420
 421
 422 /**
 423  * @param mi a #MpdObj
 424  * @param connect 1 if you are now connected, 0 if you are disconnected.
 425  * @param userdata  user data set when the signal handler was connected.
 426  * Signal is triggered when the connection state changes.
 427  */
 428
 429 typedef void (*ConnectionChangedCallback) (MpdObj * mi, int connect, void *userdata);
 430
 431
 432
 433 /* new style signal connectors */
 434 /**
 435  * @param mi a #MpdObj
 436  * @param status_changed a #StatusChangedCallback
 437  * @param userdata user data passed to the callback
 438  */
 439 void mpd_signal_connect_status_changed(MpdObj * mi, StatusChangedCallback status_changed,
 440                                                void *userdata);
 441
 442
 443
 444 /**
 445  * @param mi a #MpdObj
 446  * @param error a #ErrorCallback
 447  * @param userdata user data passed to the callback
 448  */
 449 void mpd_signal_connect_error(MpdObj * mi, ErrorCallback error, void *userdata);
 450
 451
 452
 453 /**
 454  * @param mi a #MpdObj
 455  * @param connection_changed a #ConnectionChangedCallback
 456  * @param userdata user data passed to the callback
 457  */
 458 void mpd_signal_connect_connection_changed(MpdObj * mi,
 459                                                    ConnectionChangedCallback connection_changed,
 460                                                    void *userdata);
 461
 462 /*@}*/
 463
 464
 465
 466 /**\defgroup MpdData Data Object
 467  * This is a fast linked list implementation where data returned from mpd is stored in.
 468  */
 469
 470 /*@{*/
 471
 472 /**
 473  * @param data a #MpdData
 474  *
 475  * Checks if the passed #MpdData is the last in a list
 476  * @returns TRUE when data is the last in the list.
 477  */
 478 int mpd_data_is_last(MpdData const *data);
 479
 480
 481 /**
 482  * @param data a #MpdData
 483  *
 484  * Free's a #MpdData List
 485  */
 486 void mpd_data_free(MpdData * data);
 487
 488
 489
 490 /**
 491  * @param data a #MpdData
 492  *
 493  * Returns the next #MpdData in the list.
 494  * If it's the last item in the list, it will free the list.
 495  *
 496  * You can iterate through a list like this and have it freed afterwards.
 497  * @code
 498  *      for(data = mpd_database_get_albums(mi);data != NULL; data = mpd_data_get_next(data))
 499  *      {
 500  *              // do your thing
 501  *      }
 502  * @endcode
 503  * @returns The next #MpdData or %NULL
 504  */
 505 MpdData *mpd_data_get_next(MpdData * data);
 506
 507
 508
 509
 510 /**
 511  * @param data a #MpdData
 512  *
 513  * Returns the first #MpdData in the list.
 514  *
 515  * @returns The first #MpdData or %NULL
 516  */
 517 MpdData *mpd_data_get_first(MpdData const *data);
 518
 519
 520
 521 /**
 522  * @param data a #MpdData item
 523  *
 524  * removes the passed #MpdData from the underlying list, and returns the element before data
 525  *
 526  * @returns a #MpdData list
 527  */
 528 MpdData *mpd_data_delete_item(MpdData * data);
 529
 530
 531
 532 /*@}*/
 533
 534
 535 /** \defgroup Server Server
 536  * Functions to get information about the mpd daemon and or modify it.
 537  */
 538 /*@{*/
 539
 540
 541 /**
 542  * @param mi a #MpdObj
 543  *
 544  * Returns a list of audio output devices stored in a #MpdData list
 545  *
 546  * @returns a #MpdData
 547  */
 548 MpdData *mpd_server_get_output_devices(MpdObj * mi);
 549
 550
 551
 552 /**
 553  * @param mi a #MpdObj
 554  * @param device_id The id of the output device
 555  * @param state The state to change the output device to, 1 is enable, 0 is disable.
 556  *
 557  * Enable or Disable an audio output device
 558  *
 559  * @returns 0 if successful
 560  */
 561 int mpd_server_set_output_device(MpdObj * mi, int device_id, int state);
 562
 563
 564
 565 /**
 566  * @param mi a #MpdObj
 567  *
 568  * Gets a unix timestamp of the last time the database was updated.
 569  *
 570  * @returns unix Timestamp
 571  */
 572 long unsigned mpd_server_get_database_update_time(MpdObj * mi);
 573
 574
 575
 576 /**
 577  * @param mi a #MpdObj
 578  * @param major the major version number
 579  * @param minor the minor version number
 580  * @param micro the micro version number
 581  *
 582  * Checks if the connected mpd server version is equal or higher.
 583  *
 584  * @returns #TRUE when version of mpd equals or is higher, else #FALSE
 585  */
 586 int mpd_server_check_version(MpdObj * mi, int major, int minor, int micro);
 587
 588 /**
 589  * @param mi a #MpdObj
 590  *
 591  * @return a string with version or NULL when not connected
 592  */
 593
 594 char *mpd_server_get_version(MpdObj *mi);
 595 /**
 596  * @param mi a #MpdObj
 597  * @param command the command to check
 598  *
 599  * Checks if the user is allowed to execute the command and if the server supports it
 600  *
 601  * @returns Returns #MpdServerCommand
 602  */
 603 int mpd_server_check_command_allowed(MpdObj * mi, const char *command);
 604
 605
 606
 607 /**
 608  * @param mi a #MpdObj
 609  *
 610  * @returns an array with urlhandlers (NULL terminated). Result must be freed.
 611  */
 612 char ** mpd_server_get_url_handlers(MpdObj *mi);
 613
 614 /**
 615  * @param mi a #MpdObj
 616  *
 617  * @returns an array with supported tag types. (NULL Terminated). Result must be freed.
 618  */
 619
 620 char ** mpd_server_get_tag_types(MpdObj *mi);
 621 /*@}*/
 622
 623 /** \defgroup Misc Misc
 624  * Helper functions.
 625  */
 626 /*@{*/
 627
 628 /**
 629  * @param name a NULL terminated string
 630  *
 631  * gets the Matching #MpdDataType matching at the string
 632  *
 633  * @returns a #MpdDataType
 634  */
 635 int mpd_misc_get_tag_by_name(char *name);
 636
 637 /*@}*/
 638
 639 /**
 640  * @param mi a #MpdObj
 641  *
 642  * Reports if the connected mpd supports the idle command.
 643  *
 644  * @returns a boolean, TRUE if it has idle support
 645  */
 646 int mpd_server_has_idle(MpdObj *mi);
 647
 648 /**
 649  * @param mi a #MpdObj
 650  * @param tag a #mpd_TagItems
 651  *
 652  * Returns if mpd supports this tag.
 653  *
 654  * return 1 if support 0 if not
 655  */
 656 int mpd_server_tag_supported(MpdObj *mi, int tag);
 657
 658 #endif
 659
 660 #ifdef __cplusplus
 661 }
 662 #endif