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"
44 /** Defined for readability: True is 1. */
49 /** Defined for readability: False is 0. */
52 #include "libmpd-version.h"
53 extern char *libmpd_version
;
56 * Enum that represent the errors libmpd functions can return
60 /** Command/function completed succesfull */
62 /** Error in the function's arguments */
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,
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,
86 /** Tag ITem not found */
87 MPD_TAG_NOT_FOUND
= -90,
89 /** Fatal error, something I am not sure what todo with */
90 MPD_FATAL_ERROR
= -1000
96 * The Main Mpd Object. Don't access any of the internal values directly, but use the provided functions.
98 typedef struct _MpdObj MpdObj
;
102 * enum that represents the state of a command.
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
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.
120 /** The MpdData structure holds no value*/
122 /** Holds an Tag String. value->tag is filled value->tag_type defines what type of tag.*/
124 /** Holds an Directory String. value->directory is filled.*/
125 MPD_DATA_TYPE_DIRECTORY
,
126 /** Holds an MpdSong Structure. value->song is valid.*/
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
136 * A fast linked list that is used to pass data from libmpd to the client.
138 typedef struct _MpdData
{
139 /** a #MpdDataType */
143 /** a #mpd_TagItems defining what #tag contains */
145 /** a string containing the tag*/
150 /** a path to a playlist */
154 /** an output device entity */
155 mpd_OutputEntity
*output_dev
;
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"
171 * Create an new #MpdObj with default settings.
172 * Hostname will be set to "localhost".
177 * mpd_new("localhost",6600,NULL);
180 * @returns the new #MpdObj
182 MpdObj
*mpd_new_default();
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
191 * Create a new #MpdObj with provided settings:
193 * @returns the new #MpdObj
196 MpdObj
*mpd_new(char *hostname
, int port
, char *password
);
202 *@param hostname The new hostname to use
206 * @returns a #MpdError. (#MPD_OK if everything went ok)
208 int mpd_set_hostname(MpdObj
* mi
, char *hostname
);
211 * @param mi a #MpdObj
213 * gets the set hostname
214 * returns: a const char
216 const char * mpd_get_hostname(MpdObj
*mi
);
219 * @param mi a #MpdObj
220 * @param password The new password to use
224 * @returns a #MpdError. (#MPD_OK if everything went ok)
226 int mpd_set_password(MpdObj
* mi
, char *password
);
230 * @param mi a #MpdObj
231 * @param port The port to use. (Default: 6600)
233 * Set the Port number
236 * @returns a #MpdError. (#MPD_OK if everything went ok)
238 int mpd_set_port(MpdObj
* mi
, int port
);
244 * @param mi a #MpdObj
245 * @param timeout: A timeout (in seconds)
247 * Set the timeout of the connection.
248 * If allready connected the timeout of the running connection
250 * @returns a #MpdError. (MPD_OK if everything went ok)
252 int mpd_set_connection_timeout(MpdObj
* mi
, float timeout
);
255 int mpd_connect_real(MpdObj
*mi
,mpd_Connection
*connection
);
257 * @param mi a #MpdObj
259 * Connect to the mpd daemon.
260 * Warning: mpd_connect connects anonymous, to authentificate use #mpd_send_password
262 * @returns returns a #MpdError, MPD_OK when successful
264 int mpd_connect(MpdObj
* mi
);
268 * @param mi The #MpdObj to disconnect
270 * Disconnect the current connection
271 * @returns MPD_OK (always)
273 int mpd_disconnect(MpdObj
* mi
);
278 * @param mi a #MpdObj
280 * Checks if #MpdObj is connected
281 * @returns True when connected
283 int mpd_check_connected(MpdObj
* mi
);
288 * @param mi a #MpdObj
290 * Checks if there was an error
291 * @returns True when there is an error
293 int mpd_check_error(MpdObj
* mi
);
298 * @param mi a #MpdObj
300 * Free the #MpdObj, when still connected the connection will be disconnected first
302 void mpd_free(MpdObj
* mi
);
307 * @param mi a #MpdObj
309 * Forces libmpd to re-authenticate itself.
311 * When succesfull it will trigger the "permission" changed signal.
313 * @returns: a #MpdError
315 int mpd_send_password(MpdObj
* mi
);
324 * Bitwise enumeration to determine what triggered the status_changed signals
325 * This is used in combination with the #StatusChangedCallback
327 * void status_changed_callback(MpdObj *mi, ChangedStatusType what)
329 * if(what&MPD_CST_SONGID)
331 * // act on song change
334 * if(what&MPD_CST_RANDOM)
336 * // act on random change
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,
380 MPD_CST_SERVER_ERROR
= 0x30000
384 /* callback typedef's */
386 * @param mi a #MpdObj
387 * @param what a #ChangedStatusType that determines what changed triggered the signal. This is a bitmask.
388 * @param userdata user data set when the signal handler was connected.
390 * Signal that get's called when the state of mpd changed. Look #ChangedStatusType to see the possible events.
392 typedef void (*StatusChangedCallback
) (MpdObj
* mi
, ChangedStatusType what
, void *userdata
);
398 * @param mi a #MpdObj
399 * @param id The error Code.
400 * @param msg human-readable informative error message.
401 * @param userdata user data set when the signal handler was connected.
402 * This signal is called when an error has occured in the communication with mpd.
404 typedef void (*ErrorCallback
) (MpdObj
* mi
, int id
, char *msg
, void *userdata
);
409 * @param mi a #MpdObj
410 * @param connect 1 if you are now connect, 0 if you are disconnect.
411 * @param userdata user data set when the signal handler was connected.
412 * Signal is triggered when the connection state changes.
415 typedef void (*ConnectionChangedCallback
) (MpdObj
* mi
, int connect
, void *userdata
);
419 /* new style signal connectors */
421 * @param mi a #MpdObj
422 * @param status_changed a #StatusChangedCallback
423 * @param userdata user data passed to the callback
425 void mpd_signal_connect_status_changed(MpdObj
* mi
, StatusChangedCallback status_changed
,
431 * @param mi a #MpdObj
432 * @param error a #ErrorCallback
433 * @param userdata user data passed to the callback
435 void mpd_signal_connect_error(MpdObj
* mi
, ErrorCallback error
, void *userdata
);
440 * @param mi a #MpdObj
441 * @param connection_changed a #ConnectionChangedCallback
442 * @param userdata user data passed to the callback
444 void mpd_signal_connect_connection_changed(MpdObj
* mi
,
445 ConnectionChangedCallback connection_changed
,
452 /**\defgroup MpdData Data Object
453 * This is a fast linked list implementation where data returned from mpd is stored in.
459 * @param data a #MpdData
461 * Check's if the passed #MpdData is the last in a list
462 * @returns TRUE when data is the last in the list.
464 int mpd_data_is_last(MpdData
const *data
);
468 * @param data a #MpdData
470 * Free's a #MpdData List
472 void mpd_data_free(MpdData
* data
);
477 * @param data a #MpdData
479 * Returns the next #MpdData in the list.
480 * If it's the last item in the list, it will free the list.
482 * You can itterate through a list like this and have it free'ed afterwards.
484 * for(data = mpd_database_get_albums(mi);data != NULL; data = mpd_data_get_next(data))
489 * @returns The next #MpdData or %NULL
491 MpdData
*mpd_data_get_next(MpdData
* data
);
497 * @param data a #MpdData
499 * Returns the first #MpdData in the list.
501 * @returns The first #MpdData or %NULL
503 MpdData
*mpd_data_get_first(MpdData
const *data
);
508 * @param data a #MpdData item
510 * removes the passed #MpdData from the underlying list, and returns the element before data
512 * @returns a #MpdData list
514 MpdData
*mpd_data_delete_item(MpdData
* data
);
521 /** \defgroup Server Server
522 * Functions to get information about the mpd daemon and or modify it.
528 * @param mi a #MpdObj
530 * Returns a list of audio output devices stored in a #MpdData list
532 * @returns a #MpdData
534 MpdData
*mpd_server_get_output_devices(MpdObj
* mi
);
539 * @param mi a #MpdObj
540 * @param device_id The id of the output device
541 * @param state The state to change the output device to, 1 is enable, 0 is disable.
543 * Enable or Disable an audio output device
545 * @returns 0 if successful
547 int mpd_server_set_output_device(MpdObj
* mi
, int device_id
, int state
);
552 * @param mi a #MpdObj
554 * Get's a unix timestamp of the last time the database was updated.
556 * @returns unix Timestamp
558 long unsigned mpd_server_get_database_update_time(MpdObj
* mi
);
563 * @param mi a #MpdObj
564 * @param major the major version number
565 * @param minor the minor version number
566 * @param micro the micro version number
568 * Checks if the connected mpd server version is equal or higer.
570 * @returns #TRUE when version of mpd equals or is higher, else #FALSE
572 int mpd_server_check_version(MpdObj
* mi
, int major
, int minor
, int micro
);
575 * @param mi a #MpdObj
577 * @return a string with version or NULL when not connected
580 char *mpd_server_get_version(MpdObj
*mi
);
582 * @param mi a #MpdObj
583 * @param command the command to check
585 * Checks if the user is allowed to execute the command and if the server supports it
587 * @returns Returns #MpdServerCommand
589 int mpd_server_check_command_allowed(MpdObj
* mi
, const char *command
);
594 * @param mi a #MpdObj
596 * @returns an array with urlhandlers (NULL terminated).
598 char ** mpd_server_get_url_handlers(MpdObj
*mi
);
602 /** \defgroup Misc Misc
609 * @param string A NULL terminated string
611 * Splits a string in tokens while keeping ()[] in tact.
612 * This can be used to match a string tokenized
613 * and with regex support agains a user defined string.
615 * @returns An array of regex patterns
617 regex_t
**mpd_misc_tokenize(char *string
);
621 * @param tokens an array of regex patterns.
623 * Free's a list of regex patterns
625 void mpd_misc_tokens_free(regex_t
** tokens
);
629 * @param name a NULL terminated string
631 * gets the Matching #MpdDataType matching at the string
633 * @returns a #MpdDataType
635 int mpd_misc_get_tag_by_name(char *name
);