1 /* libmpd (high level libmpdclient library)
2 * Copyright (C) 2004-2009 Qball Cow <qball@sarine.nl>
3 * Project homepage: http://gmpcwiki.sarine.nl/
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.
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.
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.
22 * A small example of a console client using libmpd.
25 /** \defgroup 1Basic Basic
36 #define __REGEX_IMPORT__ 1
37 #define __W32API_USE_DLLIMPORT__ 1
40 #include "libmpdclient.h"
43 /** Defined for readability: True is 1. */
48 /** Defined for readability: False is 0. */
51 #include "libmpd-version.h"
52 extern char *libmpd_version
;
55 * Enum that represent the errors libmpd functions can return
59 /** Command/function completed succesfull */
61 /** Error in the function's arguments */
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,
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,
85 /** Tag Item not found */
86 MPD_TAG_NOT_FOUND
= -90,
88 /* MPD_PLALIST_LOAD_FAILED */
89 MPD_PLAYLIST_LOAD_FAILED
= -100,
91 /** Fatal error, something I am not sure what todo with */
92 MPD_FATAL_ERROR
= -1000
98 * The Main Mpd Object. Don't access any of the internal values directly, but use the provided functions.
100 typedef struct _MpdObj MpdObj
;
104 * enum that represents the state of a command.
107 MPD_SERVER_COMMAND_ALLOWED
= TRUE
,
108 MPD_SERVER_COMMAND_NOT_ALLOWED
= FALSE
,
109 MPD_SERVER_COMMAND_NOT_SUPPORTED
= -1,
110 MPD_SERVER_COMMAND_ERROR
= -2
116 * enumeration to determine what value the MpdData structure hold.
117 * The MpdData structure can hold only one type of value,
118 * but a list of MpdData structs can hold structs with different type of values.
119 * It's required to check every MpdData Structure.
122 /** The MpdData structure holds no value*/
124 /** Holds an Tag String. value->tag is filled value->tag_type defines what type of tag.*/
126 /** Holds an Directory String. value->directory is filled.*/
127 MPD_DATA_TYPE_DIRECTORY
,
128 /** Holds an MpdSong Structure. value->song is valid.*/
130 /** Holds an Playlist String. value->playlist is filled.*/
131 MPD_DATA_TYPE_PLAYLIST
,
132 /** Holds an MpdOutputDevice structure. value->output_dev is valid.*/
133 MPD_DATA_TYPE_OUTPUT_DEV
138 * A fast linked list that is used to pass data from libmpd to the client.
140 typedef struct _MpdData
{
141 /** a #MpdDataType */
145 /** a #mpd_TagItems defining what #tag contains */
147 /** a string containing the tag*/
152 /** a path to a playlist */
153 mpd_PlaylistFile
*playlist
;
156 /** an output device entity */
157 mpd_OutputEntity
*output_dev
;
161 void (*freefunc
)(void *userdata
);
165 #include "libmpd-player.h"
166 #include "libmpd-status.h"
167 #include "libmpd-database.h"
168 #include "libmpd-playlist.h"
169 #include "libmpd-strfsong.h"
170 #include "libmpd-sticker.h"
177 * Create a new #MpdObj with default settings.
178 * Hostname will be set to "localhost".
183 * mpd_new("localhost",6600,NULL);
186 * @returns the new #MpdObj
188 MpdObj
*mpd_new_default();
193 * @param hostname The hostname to connect to
194 * @param port The port to connect to
195 * @param password The password to use for the connection, or NULL for no password
197 * Create a new #MpdObj with provided settings:
199 * @returns the new #MpdObj
202 MpdObj
*mpd_new(char *hostname
, int port
, char *password
);
208 *@param hostname The new hostname to use
212 * @returns a #MpdError. (#MPD_OK if everything went ok)
214 int mpd_set_hostname(MpdObj
* mi
, char *hostname
);
217 * @param mi a #MpdObj
219 * gets the set hostname
221 * @returns a const char representing the hostname
223 const char * mpd_get_hostname(MpdObj
*mi
);
226 * @param mi a #MpdObj
227 * @param password The new password to use
231 * @returns a #MpdError. (#MPD_OK if everything went ok)
233 int mpd_set_password(MpdObj
* mi
,const char *password
);
237 * @param mi a #MpdObj
238 * @param port The port to use. (Default: 6600)
240 * Set the Port number
243 * @returns a #MpdError. (#MPD_OK if everything went ok)
245 int mpd_set_port(MpdObj
* mi
, int port
);
251 * @param mi a #MpdObj
252 * @param timeout: A timeout (in seconds)
254 * Set the timeout of the connection.
255 * If already connected the timeout of the running connection
257 * @returns a #MpdError. (MPD_OK if everything went ok)
259 int mpd_set_connection_timeout(MpdObj
* mi
, float timeout
);
262 int mpd_connect_real(MpdObj
*mi
,mpd_Connection
*connection
);
264 * @param mi a #MpdObj
266 * Connect to the mpd daemon.
267 * Warning: mpd_connect connects anonymous, to authenticate use #mpd_send_password
269 * @returns returns a #MpdError, MPD_OK when successful
271 int mpd_connect(MpdObj
* mi
);
275 * @param mi The #MpdObj to disconnect
277 * Disconnect the current connection
278 * @returns MPD_OK (always)
280 int mpd_disconnect(MpdObj
* mi
);
285 * @param mi a #MpdObj
287 * Checks if #MpdObj is connected
288 * @returns True when connected
290 int mpd_check_connected(MpdObj
* mi
);
295 * @param mi a #MpdObj
297 * Checks if there was an error
298 * @returns True when there is an error
300 int mpd_check_error(MpdObj
* mi
);
305 * @param mi a #MpdObj
307 * Free the #MpdObj, when still connected the connection will be disconnected first
309 void mpd_free(MpdObj
* mi
);
314 * @param mi a #MpdObj
316 * Forces libmpd to re-authenticate itself.
318 * When successful it will trigger the "permission" changed signal.
320 * @returns: a #MpdError
322 int mpd_send_password(MpdObj
* mi
);
331 * Bitwise enumeration to determine what triggered the status_changed signals
332 * This is used in combination with the #StatusChangedCallback
334 * void status_changed_callback(MpdObj *mi, ChangedStatusType what)
336 * if(what&MPD_CST_SONGID)
338 * // act on song change
341 * if(what&MPD_CST_RANDOM)
343 * // act on random change
350 /** The playlist has changed */
351 MPD_CST_PLAYLIST
= 0x0001,
352 /** The song position of the playing song has changed*/
353 MPD_CST_SONGPOS
= 0x0002,
354 /** The songid of the playing song has changed */
355 MPD_CST_SONGID
= 0x0004,
356 /** The database has changed. */
357 MPD_CST_DATABASE
= 0x0008,
358 /** the state of updating the database has changed.*/
359 MPD_CST_UPDATING
= 0x0010,
360 /** the volume has changed */
361 MPD_CST_VOLUME
= 0x0020,
362 /** The total time of the currently playing song has changed*/
363 MPD_CST_TOTAL_TIME
= 0x0040,
364 /** The elapsed time of the current song has changed.*/
365 MPD_CST_ELAPSED_TIME
= 0x0080,
366 /** The crossfade time has changed. */
367 MPD_CST_CROSSFADE
= 0x0100,
368 /** The random state is changed. */
369 MPD_CST_RANDOM
= 0x0200,
370 /** repeat state is changed. */
371 MPD_CST_REPEAT
= 0x0400,
372 /** Not implemented */
373 MPD_CST_AUDIO
= 0x0800,
374 /** The state of the player has changed.*/
375 MPD_CST_STATE
= 0x1000,
376 /** The permissions the client has, has changed.*/
377 MPD_CST_PERMISSION
= 0x2000,
378 /** The bitrate of the playing song has changed. */
379 MPD_CST_BITRATE
= 0x4000,
380 /** the audio format of the playing song changed.*/
381 MPD_CST_AUDIOFORMAT
= 0x8000,
382 /** the queue has changed */
383 MPD_CST_STORED_PLAYLIST
= 0x20000,
385 MPD_CST_SERVER_ERROR
= 0x40000,
386 /** output changed */
387 MPD_CST_OUTPUT
= 0x80000,
388 /** Sticker changed */
389 MPD_CST_STICKER
= 0x100000,
390 /** Next song changed */
391 MPD_CST_NEXTSONG
= 0x200000,
392 /** Single mode changed */
393 MPD_CST_SINGLE_MODE
= 0x400000,
394 /** Consume mode changed */
395 MPD_CST_CONSUME_MODE
= 0x800000,
396 /** Replaygain mode changed */
397 MPD_CST_REPLAYGAIN
= 0x1000000
401 /* callback typedef's */
403 * @param mi a #MpdObj
404 * @param what a #ChangedStatusType that determines what changed triggered the signal. This is a bitmask.
405 * @param userdata user data set when the signal handler was connected.
407 * Signal that gets called when the state of mpd has changed. Look #ChangedStatusType to see the possible events.
409 typedef void (*StatusChangedCallback
) (MpdObj
* mi
, ChangedStatusType what
, void *userdata
);
415 * @param mi a #MpdObj
416 * @param id The error Code.
417 * @param msg human-readable informative error message.
418 * @param userdata user data set when the signal handler was connected.
419 * This signal is called when an error has occurred in the communication with mpd.
421 * return: TRUE if libmpd should disconnect.
423 typedef int (*ErrorCallback
) (MpdObj
* mi
, int id
, char *msg
, void *userdata
);
428 * @param mi a #MpdObj
429 * @param connect 1 if you are now connected, 0 if you are disconnected.
430 * @param userdata user data set when the signal handler was connected.
431 * Signal is triggered when the connection state changes.
434 typedef void (*ConnectionChangedCallback
) (MpdObj
* mi
, int connect
, void *userdata
);
438 /* new style signal connectors */
440 * @param mi a #MpdObj
441 * @param status_changed a #StatusChangedCallback
442 * @param userdata user data passed to the callback
444 void mpd_signal_connect_status_changed(MpdObj
* mi
, StatusChangedCallback status_changed
,
450 * @param mi a #MpdObj
451 * @param error a #ErrorCallback
452 * @param userdata user data passed to the callback
454 void mpd_signal_connect_error(MpdObj
* mi
, ErrorCallback error
, void *userdata
);
459 * @param mi a #MpdObj
460 * @param connection_changed a #ConnectionChangedCallback
461 * @param userdata user data passed to the callback
463 void mpd_signal_connect_connection_changed(MpdObj
* mi
,
464 ConnectionChangedCallback connection_changed
,
471 /**\defgroup MpdData Data Object
472 * This is a fast linked list implementation where data returned from mpd is stored in.
478 * @param data a #MpdData
480 * Checks if the passed #MpdData is the last in a list
481 * @returns TRUE when data is the last in the list.
483 int mpd_data_is_last(MpdData
const *data
);
487 * @param data a #MpdData
489 * Free's a #MpdData List
491 void mpd_data_free(MpdData
* data
);
496 * @param data a #MpdData
498 * Returns the next #MpdData in the list.
499 * If it's the last item in the list, it will free the list.
501 * You can iterate through a list like this and have it freed afterwards.
503 * for(data = mpd_database_get_albums(mi);data != NULL; data = mpd_data_get_next(data))
508 * @returns The next #MpdData or %NULL
510 MpdData
*mpd_data_get_next(MpdData
* data
);
516 * @param data a #MpdData
518 * Returns the first #MpdData in the list.
520 * @returns The first #MpdData or %NULL
522 MpdData
*mpd_data_get_first(MpdData
const *data
);
527 * @param data a #MpdData item
529 * removes the passed #MpdData from the underlying list, and returns the element before data
531 * @returns a #MpdData list
533 MpdData
*mpd_data_delete_item(MpdData
* data
);
540 /** \defgroup Server Server
541 * Functions to get information about the mpd daemon and or modify it.
547 * @param mi a #MpdObj
549 * Returns a list of audio output devices stored in a #MpdData list
551 * @returns a #MpdData
553 MpdData
*mpd_server_get_output_devices(MpdObj
* mi
);
558 * @param mi a #MpdObj
559 * @param device_id The id of the output device
560 * @param state The state to change the output device to, 1 is enable, 0 is disable.
562 * Enable or Disable an audio output device
564 * @returns 0 if successful
566 int mpd_server_set_output_device(MpdObj
* mi
, int device_id
, int state
);
571 * @param mi a #MpdObj
573 * Gets a unix timestamp of the last time the database was updated.
575 * @returns unix Timestamp
577 long unsigned mpd_server_get_database_update_time(MpdObj
* mi
);
582 * @param mi a #MpdObj
583 * @param major the major version number
584 * @param minor the minor version number
585 * @param micro the micro version number
587 * Checks if the connected mpd server version is equal or higher.
589 * @returns #TRUE when version of mpd equals or is higher, else #FALSE
591 int mpd_server_check_version(MpdObj
* mi
, int major
, int minor
, int micro
);
594 * @param mi a #MpdObj
596 * @return a string with version or NULL when not connected
599 char *mpd_server_get_version(MpdObj
*mi
);
601 * @param mi a #MpdObj
602 * @param command the command to check
604 * Checks if the user is allowed to execute the command and if the server supports it
606 * @returns Returns #MpdServerCommand
608 int mpd_server_check_command_allowed(MpdObj
* mi
, const char *command
);
613 * @param mi a #MpdObj
615 * @returns an array with urlhandlers (NULL terminated). Result must be freed.
617 char ** mpd_server_get_url_handlers(MpdObj
*mi
);
620 * @param mi a #MpdObj
622 * @returns an array with supported tag types. (NULL Terminated). Result must be freed.
625 char ** mpd_server_get_tag_types(MpdObj
*mi
);
628 /** \defgroup Misc Misc
634 * @param name a NULL terminated string
636 * gets the Matching #MpdDataType matching at the string
638 * @returns a #MpdDataType
640 int mpd_misc_get_tag_by_name(char *name
);
645 * @param mi a #MpdObj
647 * Reports if the connected mpd supports the idle command.
649 * @returns a boolean, TRUE if it has idle support
651 int mpd_server_has_idle(MpdObj
*mi
);
654 * @param mi a #MpdObj
655 * @param tag a #mpd_TagItems
657 * Returns if mpd supports this tag.
659 * return 1 if support 0 if not
661 int mpd_server_tag_supported(MpdObj
*mi
, int tag
);
665 MPD_SERVER_REPLAYGAIN_MODE_OFF
= 0,
666 MPD_SERVER_REPLAYGAIN_MODE_TRACK
= 1,
667 MPD_SERVER_REPLAYGAIN_MODE_ALBUM
= 2,
668 MPD_SERVER_REPLAYGAIN_MODE_AUTO
= 3
669 }MpdServerReplaygainMode
;
671 MpdServerReplaygainMode
mpd_server_get_replaygain_mode(MpdObj
*mi
);
673 int mpd_server_set_replaygain_mode(MpdObj
*mi
, MpdServerReplaygainMode mode
);