src/libmpd.h

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