2 * Copyright (C) 2004-2005 Qball Cow <Qball@qballcow.nl>
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.
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.
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.
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 */
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"
173 * Create a new #MpdObj with default settings.
174 * Hostname will be set to "localhost".
179 * mpd_new("localhost",6600,NULL);
182 * @returns the new #MpdObj
184 MpdObj
*mpd_new_default();
189 * @param hostname The hostname to connect to
190 * @param port The port to connect to
191 * @param password The password to use for the connection, or NULL for no password
193 * Create a new #MpdObj with provided settings:
195 * @returns the new #MpdObj
198 MpdObj
*mpd_new(char *hostname
, int port
, char *password
);
204 *@param hostname The new hostname to use
208 * @returns a #MpdError. (#MPD_OK if everything went ok)
210 int mpd_set_hostname(MpdObj
* mi
, char *hostname
);
213 * @param mi a #MpdObj
215 * gets the set hostname
216 * returns: a const char
218 const char * mpd_get_hostname(MpdObj
*mi
);
221 * @param mi a #MpdObj
222 * @param password The new password to use
226 * @returns a #MpdError. (#MPD_OK if everything went ok)
228 int mpd_set_password(MpdObj
* mi
, char *password
);
232 * @param mi a #MpdObj
233 * @param port The port to use. (Default: 6600)
235 * Set the Port number
238 * @returns a #MpdError. (#MPD_OK if everything went ok)
240 int mpd_set_port(MpdObj
* mi
, int port
);
246 * @param mi a #MpdObj
247 * @param timeout: A timeout (in seconds)
249 * Set the timeout of the connection.
250 * If allready connected the timeout of the running connection
252 * @returns a #MpdError. (MPD_OK if everything went ok)
254 int mpd_set_connection_timeout(MpdObj
* mi
, float timeout
);
257 int mpd_connect_real(MpdObj
*mi
,mpd_Connection
*connection
);
259 * @param mi a #MpdObj
261 * Connect to the mpd daemon.
262 * Warning: mpd_connect connects anonymous, to authenticate use #mpd_send_password
264 * @returns returns a #MpdError, MPD_OK when successful
266 int mpd_connect(MpdObj
* mi
);
270 * @param mi The #MpdObj to disconnect
272 * Disconnect the current connection
273 * @returns MPD_OK (always)
275 int mpd_disconnect(MpdObj
* mi
);
280 * @param mi a #MpdObj
282 * Checks if #MpdObj is connected
283 * @returns True when connected
285 int mpd_check_connected(MpdObj
* mi
);
290 * @param mi a #MpdObj
292 * Checks if there was an error
293 * @returns True when there is an error
295 int mpd_check_error(MpdObj
* mi
);
300 * @param mi a #MpdObj
302 * Free the #MpdObj, when still connected the connection will be disconnected first
304 void mpd_free(MpdObj
* mi
);
309 * @param mi a #MpdObj
311 * Forces libmpd to re-authenticate itself.
313 * When succesfull it will trigger the "permission" changed signal.
315 * @returns: a #MpdError
317 int mpd_send_password(MpdObj
* mi
);
326 * Bitwise enumeration to determine what triggered the status_changed signals
327 * This is used in combination with the #StatusChangedCallback
329 * void status_changed_callback(MpdObj *mi, ChangedStatusType what)
331 * if(what&MPD_CST_SONGID)
333 * // act on song change
336 * if(what&MPD_CST_RANDOM)
338 * // act on random change
345 /** The playlist has changed */
346 MPD_CST_PLAYLIST
= 0x0001,
347 /** The song position of the playing song has changed*/
348 MPD_CST_SONGPOS
= 0x0002,
349 /** The songid of the playing song has changed */
350 MPD_CST_SONGID
= 0x0004,
351 /** The database has changed. */
352 MPD_CST_DATABASE
= 0x0008,
353 /** the state of updating the database has changed.*/
354 MPD_CST_UPDATING
= 0x0010,
355 /** the volume has changed */
356 MPD_CST_VOLUME
= 0x0020,
357 /** The total time of the currently playing song has changed*/
358 MPD_CST_TOTAL_TIME
= 0x0040,
359 /** The elapsed time of the current song has changed.*/
360 MPD_CST_ELAPSED_TIME
= 0x0080,
361 /** The crossfade time has changed. */
362 MPD_CST_CROSSFADE
= 0x0100,
363 /** The random state is changed. */
364 MPD_CST_RANDOM
= 0x0200,
365 /** repeat state is changed. */
366 MPD_CST_REPEAT
= 0x0400,
367 /** Not implemented */
368 MPD_CST_AUDIO
= 0x0800,
369 /** The state of the player has changed.*/
370 MPD_CST_STATE
= 0x1000,
371 /** The permissions the client has, has changed.*/
372 MPD_CST_PERMISSION
= 0x2000,
373 /** The bitrate of the playing song has changed. */
374 MPD_CST_BITRATE
= 0x4000,
375 /** the audio format of the playing song changed.*/
376 MPD_CST_AUDIOFORMAT
= 0x8000,
377 /** the queue has changed */
378 MPD_CST_STORED_PLAYLIST
= 0x20000,
380 MPD_CST_SERVER_ERROR
= 0x40000,
381 /** output changed */
382 MPD_CST_OUTPUT
= 0x80000
386 /* callback typedef's */
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.
392 * Signal that get's called when the state of mpd has changed. Look #ChangedStatusType to see the possible events.
394 typedef void (*StatusChangedCallback
) (MpdObj
* mi
, ChangedStatusType what
, void *userdata
);
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.
406 * return: TRUE if libmpd should disconnect.
408 typedef int (*ErrorCallback
) (MpdObj
* mi
, int id
, char *msg
, void *userdata
);
413 * @param mi a #MpdObj
414 * @param connect 1 if you are now connected, 0 if you are disconnected.
415 * @param userdata user data set when the signal handler was connected.
416 * Signal is triggered when the connection state changes.
419 typedef void (*ConnectionChangedCallback
) (MpdObj
* mi
, int connect
, void *userdata
);
423 /* new style signal connectors */
425 * @param mi a #MpdObj
426 * @param status_changed a #StatusChangedCallback
427 * @param userdata user data passed to the callback
429 void mpd_signal_connect_status_changed(MpdObj
* mi
, StatusChangedCallback status_changed
,
435 * @param mi a #MpdObj
436 * @param error a #ErrorCallback
437 * @param userdata user data passed to the callback
439 void mpd_signal_connect_error(MpdObj
* mi
, ErrorCallback error
, void *userdata
);
444 * @param mi a #MpdObj
445 * @param connection_changed a #ConnectionChangedCallback
446 * @param userdata user data passed to the callback
448 void mpd_signal_connect_connection_changed(MpdObj
* mi
,
449 ConnectionChangedCallback connection_changed
,
456 /**\defgroup MpdData Data Object
457 * This is a fast linked list implementation where data returned from mpd is stored in.
463 * @param data a #MpdData
465 * Checks if the passed #MpdData is the last in a list
466 * @returns TRUE when data is the last in the list.
468 int mpd_data_is_last(MpdData
const *data
);
472 * @param data a #MpdData
474 * Free's a #MpdData List
476 void mpd_data_free(MpdData
* data
);
481 * @param data a #MpdData
483 * Returns the next #MpdData in the list.
484 * If it's the last item in the list, it will free the list.
486 * You can iterate through a list like this and have it freed afterwards.
488 * for(data = mpd_database_get_albums(mi);data != NULL; data = mpd_data_get_next(data))
493 * @returns The next #MpdData or %NULL
495 MpdData
*mpd_data_get_next(MpdData
* data
);
501 * @param data a #MpdData
503 * Returns the first #MpdData in the list.
505 * @returns The first #MpdData or %NULL
507 MpdData
*mpd_data_get_first(MpdData
const *data
);
512 * @param data a #MpdData item
514 * removes the passed #MpdData from the underlying list, and returns the element before data
516 * @returns a #MpdData list
518 MpdData
*mpd_data_delete_item(MpdData
* data
);
525 /** \defgroup Server Server
526 * Functions to get information about the mpd daemon and or modify it.
532 * @param mi a #MpdObj
534 * Returns a list of audio output devices stored in a #MpdData list
536 * @returns a #MpdData
538 MpdData
*mpd_server_get_output_devices(MpdObj
* mi
);
543 * @param mi a #MpdObj
544 * @param device_id The id of the output device
545 * @param state The state to change the output device to, 1 is enable, 0 is disable.
547 * Enable or Disable an audio output device
549 * @returns 0 if successful
551 int mpd_server_set_output_device(MpdObj
* mi
, int device_id
, int state
);
556 * @param mi a #MpdObj
558 * Gets a unix timestamp of the last time the database was updated.
560 * @returns unix Timestamp
562 long unsigned mpd_server_get_database_update_time(MpdObj
* mi
);
567 * @param mi a #MpdObj
568 * @param major the major version number
569 * @param minor the minor version number
570 * @param micro the micro version number
572 * Checks if the connected mpd server version is equal or higer.
574 * @returns #TRUE when version of mpd equals or is higher, else #FALSE
576 int mpd_server_check_version(MpdObj
* mi
, int major
, int minor
, int micro
);
579 * @param mi a #MpdObj
581 * @return a string with version or NULL when not connected
584 char *mpd_server_get_version(MpdObj
*mi
);
586 * @param mi a #MpdObj
587 * @param command the command to check
589 * Checks if the user is allowed to execute the command and if the server supports it
591 * @returns Returns #MpdServerCommand
593 int mpd_server_check_command_allowed(MpdObj
* mi
, const char *command
);
598 * @param mi a #MpdObj
600 * @returns an array with urlhandlers (NULL terminated). Result must be freed.
602 char ** mpd_server_get_url_handlers(MpdObj
*mi
);
605 * @param mi a #MpdObj
607 * @returns an array with supported tag types. (NULL Terminated). Result must be freed.
610 char ** mpd_server_get_tag_types(MpdObj
*mi
);
613 /** \defgroup Misc Misc
619 * @param name a NULL terminated string
621 * gets the Matching #MpdDataType matching at the string
623 * @returns a #MpdDataType
625 int mpd_misc_get_tag_by_name(char *name
);
630 * @param mi a #MpdObj
632 * Reports if the connected mpd supports the idle command.
634 * @returns a boolean, TRUE if it has idle support
636 int mpd_server_has_idle(MpdObj
*mi
);