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 /** Fatal error, something I am not sure what todo with */
89 MPD_FATAL_ERROR
= -1000
95 * The Main Mpd Object. Don't access any of the internal values directly, but use the provided functions.
97 typedef struct _MpdObj MpdObj
;
101 * enum that represents the state of a command.
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
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.
119 /** The MpdData structure holds no value*/
121 /** Holds an Tag String. value->tag is filled value->tag_type defines what type of tag.*/
123 /** Holds an Directory String. value->directory is filled.*/
124 MPD_DATA_TYPE_DIRECTORY
,
125 /** Holds an MpdSong Structure. value->song is valid.*/
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
135 * A fast linked list that is used to pass data from libmpd to the client.
137 typedef struct _MpdData
{
138 /** a #MpdDataType */
142 /** a #mpd_TagItems defining what #tag contains */
144 /** a string containing the tag*/
149 /** a path to a playlist */
150 mpd_PlaylistFile
*playlist
;
153 /** an output device entity */
154 mpd_OutputEntity
*output_dev
;
158 void (*freefunc
)(void *userdata
);
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"
174 * Create a new #MpdObj with default settings.
175 * Hostname will be set to "localhost".
180 * mpd_new("localhost",6600,NULL);
183 * @returns the new #MpdObj
185 MpdObj
*mpd_new_default();
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
194 * Create a new #MpdObj with provided settings:
196 * @returns the new #MpdObj
199 MpdObj
*mpd_new(char *hostname
, int port
, char *password
);
205 *@param hostname The new hostname to use
209 * @returns a #MpdError. (#MPD_OK if everything went ok)
211 int mpd_set_hostname(MpdObj
* mi
, char *hostname
);
214 * @param mi a #MpdObj
216 * gets the set hostname
218 * @returns a const char representing the hostname
220 const char * mpd_get_hostname(MpdObj
*mi
);
223 * @param mi a #MpdObj
224 * @param password The new password to use
228 * @returns a #MpdError. (#MPD_OK if everything went ok)
230 int mpd_set_password(MpdObj
* mi
,const char *password
);
234 * @param mi a #MpdObj
235 * @param port The port to use. (Default: 6600)
237 * Set the Port number
240 * @returns a #MpdError. (#MPD_OK if everything went ok)
242 int mpd_set_port(MpdObj
* mi
, int port
);
248 * @param mi a #MpdObj
249 * @param timeout: A timeout (in seconds)
251 * Set the timeout of the connection.
252 * If already connected the timeout of the running connection
254 * @returns a #MpdError. (MPD_OK if everything went ok)
256 int mpd_set_connection_timeout(MpdObj
* mi
, float timeout
);
259 int mpd_connect_real(MpdObj
*mi
,mpd_Connection
*connection
);
261 * @param mi a #MpdObj
263 * Connect to the mpd daemon.
264 * Warning: mpd_connect connects anonymous, to authenticate use #mpd_send_password
266 * @returns returns a #MpdError, MPD_OK when successful
268 int mpd_connect(MpdObj
* mi
);
272 * @param mi The #MpdObj to disconnect
274 * Disconnect the current connection
275 * @returns MPD_OK (always)
277 int mpd_disconnect(MpdObj
* mi
);
282 * @param mi a #MpdObj
284 * Checks if #MpdObj is connected
285 * @returns True when connected
287 int mpd_check_connected(MpdObj
* mi
);
292 * @param mi a #MpdObj
294 * Checks if there was an error
295 * @returns True when there is an error
297 int mpd_check_error(MpdObj
* mi
);
302 * @param mi a #MpdObj
304 * Free the #MpdObj, when still connected the connection will be disconnected first
306 void mpd_free(MpdObj
* mi
);
311 * @param mi a #MpdObj
313 * Forces libmpd to re-authenticate itself.
315 * When successful it will trigger the "permission" changed signal.
317 * @returns: a #MpdError
319 int mpd_send_password(MpdObj
* mi
);
328 * Bitwise enumeration to determine what triggered the status_changed signals
329 * This is used in combination with the #StatusChangedCallback
331 * void status_changed_callback(MpdObj *mi, ChangedStatusType what)
333 * if(what&MPD_CST_SONGID)
335 * // act on song change
338 * if(what&MPD_CST_RANDOM)
340 * // act on random change
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,
382 MPD_CST_SERVER_ERROR
= 0x40000,
383 /** output changed */
384 MPD_CST_OUTPUT
= 0x80000,
385 /** Sticker changed */
386 MPD_CST_STICKER
= 0x100000
390 /* callback typedef's */
392 * @param mi a #MpdObj
393 * @param what a #ChangedStatusType that determines what changed triggered the signal. This is a bitmask.
394 * @param userdata user data set when the signal handler was connected.
396 * Signal that gets called when the state of mpd has changed. Look #ChangedStatusType to see the possible events.
398 typedef void (*StatusChangedCallback
) (MpdObj
* mi
, ChangedStatusType what
, void *userdata
);
404 * @param mi a #MpdObj
405 * @param id The error Code.
406 * @param msg human-readable informative error message.
407 * @param userdata user data set when the signal handler was connected.
408 * This signal is called when an error has occurred in the communication with mpd.
410 * return: TRUE if libmpd should disconnect.
412 typedef int (*ErrorCallback
) (MpdObj
* mi
, int id
, char *msg
, void *userdata
);
417 * @param mi a #MpdObj
418 * @param connect 1 if you are now connected, 0 if you are disconnected.
419 * @param userdata user data set when the signal handler was connected.
420 * Signal is triggered when the connection state changes.
423 typedef void (*ConnectionChangedCallback
) (MpdObj
* mi
, int connect
, void *userdata
);
427 /* new style signal connectors */
429 * @param mi a #MpdObj
430 * @param status_changed a #StatusChangedCallback
431 * @param userdata user data passed to the callback
433 void mpd_signal_connect_status_changed(MpdObj
* mi
, StatusChangedCallback status_changed
,
439 * @param mi a #MpdObj
440 * @param error a #ErrorCallback
441 * @param userdata user data passed to the callback
443 void mpd_signal_connect_error(MpdObj
* mi
, ErrorCallback error
, void *userdata
);
448 * @param mi a #MpdObj
449 * @param connection_changed a #ConnectionChangedCallback
450 * @param userdata user data passed to the callback
452 void mpd_signal_connect_connection_changed(MpdObj
* mi
,
453 ConnectionChangedCallback connection_changed
,
460 /**\defgroup MpdData Data Object
461 * This is a fast linked list implementation where data returned from mpd is stored in.
467 * @param data a #MpdData
469 * Checks if the passed #MpdData is the last in a list
470 * @returns TRUE when data is the last in the list.
472 int mpd_data_is_last(MpdData
const *data
);
476 * @param data a #MpdData
478 * Free's a #MpdData List
480 void mpd_data_free(MpdData
* data
);
485 * @param data a #MpdData
487 * Returns the next #MpdData in the list.
488 * If it's the last item in the list, it will free the list.
490 * You can iterate through a list like this and have it freed afterwards.
492 * for(data = mpd_database_get_albums(mi);data != NULL; data = mpd_data_get_next(data))
497 * @returns The next #MpdData or %NULL
499 MpdData
*mpd_data_get_next(MpdData
* data
);
505 * @param data a #MpdData
507 * Returns the first #MpdData in the list.
509 * @returns The first #MpdData or %NULL
511 MpdData
*mpd_data_get_first(MpdData
const *data
);
516 * @param data a #MpdData item
518 * removes the passed #MpdData from the underlying list, and returns the element before data
520 * @returns a #MpdData list
522 MpdData
*mpd_data_delete_item(MpdData
* data
);
529 /** \defgroup Server Server
530 * Functions to get information about the mpd daemon and or modify it.
536 * @param mi a #MpdObj
538 * Returns a list of audio output devices stored in a #MpdData list
540 * @returns a #MpdData
542 MpdData
*mpd_server_get_output_devices(MpdObj
* mi
);
547 * @param mi a #MpdObj
548 * @param device_id The id of the output device
549 * @param state The state to change the output device to, 1 is enable, 0 is disable.
551 * Enable or Disable an audio output device
553 * @returns 0 if successful
555 int mpd_server_set_output_device(MpdObj
* mi
, int device_id
, int state
);
560 * @param mi a #MpdObj
562 * Gets a unix timestamp of the last time the database was updated.
564 * @returns unix Timestamp
566 long unsigned mpd_server_get_database_update_time(MpdObj
* mi
);
571 * @param mi a #MpdObj
572 * @param major the major version number
573 * @param minor the minor version number
574 * @param micro the micro version number
576 * Checks if the connected mpd server version is equal or higher.
578 * @returns #TRUE when version of mpd equals or is higher, else #FALSE
580 int mpd_server_check_version(MpdObj
* mi
, int major
, int minor
, int micro
);
583 * @param mi a #MpdObj
585 * @return a string with version or NULL when not connected
588 char *mpd_server_get_version(MpdObj
*mi
);
590 * @param mi a #MpdObj
591 * @param command the command to check
593 * Checks if the user is allowed to execute the command and if the server supports it
595 * @returns Returns #MpdServerCommand
597 int mpd_server_check_command_allowed(MpdObj
* mi
, const char *command
);
602 * @param mi a #MpdObj
604 * @returns an array with urlhandlers (NULL terminated). Result must be freed.
606 char ** mpd_server_get_url_handlers(MpdObj
*mi
);
609 * @param mi a #MpdObj
611 * @returns an array with supported tag types. (NULL Terminated). Result must be freed.
614 char ** mpd_server_get_tag_types(MpdObj
*mi
);
617 /** \defgroup Misc Misc
623 * @param name a NULL terminated string
625 * gets the Matching #MpdDataType matching at the string
627 * @returns a #MpdDataType
629 int mpd_misc_get_tag_by_name(char *name
);
634 * @param mi a #MpdObj
636 * Reports if the connected mpd supports the idle command.
638 * @returns a boolean, TRUE if it has idle support
640 int mpd_server_has_idle(MpdObj
*mi
);
643 * @param mi a #MpdObj
644 * @param tag a #mpd_TagItems
646 * Returns if mpd supports this tag.
648 * return 1 if support 0 if not
650 int mpd_server_tag_supported(MpdObj
*mi
, int tag
);