1 /* libmpdclient
2 * (c)2003-2004 by Warren Dukes (shank@mercury.chem.pitt.edu)
3 * This project's homepage is: http://www.musicpd.org
4 *
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2.1 of the License, or (at your option) any later version.
9 *
10 * This library 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 Lesser General Public License for more details.
14 *
15 * You should have received a copy of the GNU Lesser General Public
16 * License along with this program; if not, write to the Free Software
17 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
18 */
20 #ifndef LIBMPDCLIENT_H
21 #define LIBMPDCLIENT_H
23 #include <sys/time.h>
25 #define MPD_BUFFER_MAX_LENGTH 50000
26 #define MPD_WELCOME_MESSAGE "OK MPD "
28 #define MPD_ERROR_TIMEOUT 10 /* timeout trying to talk to mpd */
29 #define MPD_ERROR_SYSTEM 11 /* system error */
30 #define MPD_ERROR_UNKHOST 12 /* unknown host */
31 #define MPD_ERROR_CONNPORT 13 /* problems connecting to port on host */
32 #define MPD_ERROR_NOTMPD 14 /* mpd not running on port at host */
33 #define MPD_ERROR_NORESPONSE 15 /* no response on attempting to connect */
34 #define MPD_ERROR_SENDING 16 /* error sending command */
35 #define MPD_ERROR_CONNCLOSED 17 /* connection closed by mpd */
36 #define MPD_ERROR_ACK 18 /* ACK returned! */
37 #define MPD_ERROR_BUFFEROVERRUN 19 /* Buffer was overrun! */
39 #define MPD_ERROR_CODE_UNK -1;
40 #define MPD_ERROR_AT_UNK -1;
42 #ifdef __cplusplus
43 extern "C" {
44 #endif
46 /* internal stuff don't touch this struct */
47 typedef struct _mpd_ReturnElement {
48 char * name;
49 char * value;
50 } mpd_ReturnElement;
52 /* mpd_Connection
53 * holds info about connection to mpd
54 * use error, and errorStr to detect errors
55 */
56 typedef struct _mpd_Connection {
57 /* use this to check the version of mpd */
58 int version[3];
59 /* IMPORTANT, you want to get the error messages from here */
60 char errorStr[MPD_BUFFER_MAX_LENGTH+1];
61 int errorCode;
62 int errorAt;
63 /* this will be set to MPD_ERROR_* if there is an error, 0 if not */
64 int error;
65 /* DON'T TOUCH any of the rest of this stuff */
66 int sock;
67 char buffer[MPD_BUFFER_MAX_LENGTH+1];
68 int buflen;
69 int bufstart;
70 int doneProcessing;
71 int commandList;
72 mpd_ReturnElement * returnElement;
73 struct timeval timeout;
74 } mpd_Connection;
76 /* mpd_newConnection
77 * use this to open a new connection
78 * you should use mpd_closeConnection, when your done with the connection,
79 * even if an error has occurred
80 * _timeout_ is the connection timeout period in seconds
81 */
82 mpd_Connection * mpd_newConnection(const char * host, int port, float timeout);
84 void mpd_setConnectionTimeout(mpd_Connection * connection, float timeout);
86 /* mpd_closeConnection
87 * use this to close a connection and free'ing subsequent memory
88 */
89 void mpd_closeConnection(mpd_Connection * connection);
91 /* mpd_clearError
92 * clears error
93 */
94 void mpd_clearError(mpd_Connection * connection);
96 /* STATUS STUFF */
98 /* use these with status.state to determine what state the player is in */
99 #define MPD_STATUS_STATE_UNKNOWN 0
100 #define MPD_STATUS_STATE_STOP 1
101 #define MPD_STATUS_STATE_PLAY 2
102 #define MPD_STATUS_STATE_PAUSE 3
104 /* us this with status.volume to determine if mpd has volume support */
105 #define MPD_STATUS_NO_VOLUME -1
107 /* mpd_Status
108 * holds info return from status command
109 */
110 typedef struct mpd_Status {
111 /* 0-100, or MPD_STATUS_NO_VOLUME when there is no volume support */
112 int volume;
113 /* 1 if repeat is on, 0 otherwise */
114 int repeat;
115 /* 1 if random is on, 0 otherwise */
116 int random;
117 /* playlist length */
118 int playlistLength;
119 /* playlist, use this to determine when the playlist has changed */
120 long long playlist;
121 /* use with MPD_STATUS_STATE_* to determine state of player */
122 int state;
123 /* crossfade setting in seconds */
124 int crossfade;
125 /* if in PLAY or PAUSE state, this is the number of the currently
126 * playing song in the playlist, beginning with 0
127 */
128 int song;
129 /* time in seconds that have elapsed in the currently playing/paused
130 * song
131 */
132 int elapsedTime;
133 /* length in seconds of the currently playing/paused song */
134 int totalTime;
135 /* current bit rate in kbs */
136 int bitRate;
137 /* audio sample rate */
138 unsigned int sampleRate;
139 /* audio bits */
140 int bits;
141 /* audio channels */
142 int channels;
143 /* 1 if mpd is updating, 0 otherwise */
144 int updatingDb;
145 /* error */
146 char * error;
147 } mpd_Status;
149 /* mpd_getStatus
150 * returns status info, be sure to free it with mpd_freeStatus()
151 */
152 mpd_Status * mpd_getStatus(mpd_Connection * connection);
154 /* mpd_freeStatus
155 * free's status info malloc'd and returned by mpd_getStatus
156 */
157 void mpd_freeStatus(mpd_Status * status);
159 typedef struct _mpd_Stats {
160 int numberOfArtists;
161 int numberOfAlbums;
162 int numberOfSongs;
163 unsigned long uptime;
164 unsigned long dbUpdateTime;
165 unsigned long playTime;
166 unsigned long dbPlayTime;
167 } mpd_Stats;
169 mpd_Stats * mpd_getStats(mpd_Connection * connection);
171 void mpd_freeStats(mpd_Stats * stats);
173 /* SONG STUFF */
175 #define MPD_SONG_NO_TIME -1
176 #define MPD_SONG_NO_NUM -1
178 /* mpd_Song
179 * for storing song info returned by mpd
180 */
181 typedef struct _mpd_Song {
182 /* filename of song */
183 char * file;
184 /* artist, maybe NULL if there is no tag */
185 char * artist;
186 /* title, maybe NULL if there is no tag */
187 char * title;
188 /* album, maybe NULL if there is no tag */
189 char * album;
190 /* track, maybe NULL if there is no tag */
191 char * track;
192 /* name, maybe NULL if there is no tag; it's the name of the current
193 * song, f.e. the icyName of the stream */
194 char * name;
195 /* length of song in seconds, check that it is not MPD_SONG_NO_TIME */
196 int time;
197 /* if plchanges or playlistinfo used, is the number of the song in
198 * the playlist */
199 int num;
200 } mpd_Song;
202 /* mpd_newSong
203 * use to allocate memory for a new mpd_Song
204 * file, artist, etc all initialized to NULL
205 * if your going to assign values to file, artist, etc
206 * be sure to malloc or strdup the memory
207 * use mpd_freeSong to free the memory for the mpd_Song, it will also
208 * free memory for file, artist, etc, so don't do it yourself
209 */
210 mpd_Song * mpd_newSong();
212 /* mpd_freeSong
213 * use to free memory allocated by mpd_newSong
214 * also it will free memory pointed to by file, artist, etc, so be careful
215 */
216 void mpd_freeSong(mpd_Song * song);
218 /* mpd_songDup
219 * works like strDup, but for a mpd_Song
220 */
221 mpd_Song * mpd_songDup(mpd_Song * song);
223 /* DIRECTORY STUFF */
225 /* mpd_Directory
226 * used to store info fro directory (right now that just the path)
227 */
228 typedef struct _mpd_Directory {
229 char * path;
230 } mpd_Directory;
232 /* mpd_newDirectory
233 * allocates memory for a new directory
234 * use mpd_freeDirectory to free this memory
235 */
236 mpd_Directory * mpd_newDirectory ();
238 /* mpd_freeDirectory
239 * used to free memory allocated with mpd_newDirectory, and it frees
240 * path of mpd_Directory, so be careful
241 */
242 void mpd_freeDirectory(mpd_Directory * directory);
244 /* mpd_directoryDup
245 * works like strdup, but for mpd_Directory
246 */
247 mpd_Directory * mpd_directoryDup(mpd_Directory * directory);
249 /* PLAYLISTFILE STUFF */
251 /* mpd_PlaylistFile
252 * stores info about playlist file returned by lsinfo
253 */
254 typedef struct _mpd_PlaylistFile {
255 char * path;
256 } mpd_PlaylistFile;
258 /* mpd_newPlaylistFile
259 * allocates memory for new mpd_PlaylistFile, path is set to NULL
260 * free this memory with mpd_freePlaylistFile
261 */
262 mpd_PlaylistFile * mpd_newPlaylistFile();
264 /* mpd_freePlaylist
265 * free memory allocated for freePlaylistFile, will also free
266 * path, so be careful
267 */
268 void mpd_freePlaylistFile(mpd_PlaylistFile * playlist);
270 /* mpd_playlistFileDup
271 * works like strdup, but for mpd_PlaylistFile
272 */
273 mpd_PlaylistFile * mpd_playlistFileDup(mpd_PlaylistFile * playlist);
275 /* INFO ENTITY STUFF */
277 /* the type of entity returned from one of the commands that generates info
278 * use in conjunction with mpd_InfoEntity.type
279 */
280 #define MPD_INFO_ENTITY_TYPE_DIRECTORY 0
281 #define MPD_INFO_ENTITY_TYPE_SONG 1
282 #define MPD_INFO_ENTITY_TYPE_PLAYLISTFILE 2
284 /* mpd_InfoEntity
285 * stores info on stuff returned info commands
286 */
287 typedef struct mpd_InfoEntity {
288 /* the type of entity, use with MPD_INFO_ENTITY_TYPE_* to determine
289 * what this entity is (song, directory, etc...)
290 */
291 int type;
292 /* the actual data you want, mpd_Song, mpd_Directory, etc */
293 union {
294 mpd_Directory * directory;
295 mpd_Song * song;
296 mpd_PlaylistFile * playlistFile;
297 } info;
298 } mpd_InfoEntity;
300 mpd_InfoEntity * mpd_newInfoEntity();
302 void mpd_freeInfoEntity(mpd_InfoEntity * entity);
304 /* INFO COMMANDS AND STUFF */
306 /* use this function to loop over after calling Info/Listall functions */
307 mpd_InfoEntity * mpd_getNextInfoEntity(mpd_Connection * connection);
309 /* songNum of -1, means to display the whole list */
310 void mpd_sendPlaylistInfoCommand(mpd_Connection * connection, int songNum);
312 /* use this to get the changes in the playlist since version _playlist_ */
313 void mpd_sendPlChangesCommand(mpd_Connection * connection, long long playlist);
315 void mpd_sendListallCommand(mpd_Connection * connection, const char * dir);
317 void mpd_sendListallInfoCommand(mpd_Connection * connection, const char * dir);
319 void mpd_sendLsInfoCommand(mpd_Connection * connection, const char * dir);
321 #define MPD_TABLE_ARTIST 0
322 #define MPD_TABLE_ALBUM 1
323 #define MPD_TABLE_TITLE 2
324 #define MPD_TABLE_FILENAME 3
326 void mpd_sendSearchCommand(mpd_Connection * connection, int table,
327 const char * str);
329 void mpd_sendFindCommand(mpd_Connection * connection, int table,
330 const char * str);
332 /* LIST TAG COMMANDS */
334 /* use this function fetch next artist entry, be sure to free the returned
335 * string. NULL means there are no more. Best used with sendListArtists
336 */
337 char * mpd_getNextArtist(mpd_Connection * connection);
339 char * mpd_getNextAlbum(mpd_Connection * connection);
341 /* list artist or albums by artist, arg1 should be set to the artist if
342 * listing albums by a artist, otherwise NULL for listing all artists or albums
343 */
344 void mpd_sendListCommand(mpd_Connection * connection, int table,
345 const char * arg1);
347 /* SIMPLE COMMANDS */
349 void mpd_sendAddCommand(mpd_Connection * connection, const char * file);
351 void mpd_sendDeleteCommand(mpd_Connection * connection, int songNum);
353 void mpd_sendSaveCommand(mpd_Connection * connection, const char * name);
355 void mpd_sendLoadCommand(mpd_Connection * connection, const char * name);
357 void mpd_sendRmCommand(mpd_Connection * connection, const char * name);
359 void mpd_sendShuffleCommand(mpd_Connection * connection);
361 void mpd_sendClearCommand(mpd_Connection * connection);
363 /* use this to start playing at the beginning, useful when in random mode */
364 #define MPD_PLAY_AT_BEGINNING -1
366 void mpd_sendPlayCommand(mpd_Connection * connection, int songNum);
368 void mpd_sendStopCommand(mpd_Connection * connection);
370 void mpd_sendPauseCommand(mpd_Connection * connection);
372 void mpd_sendNextCommand(mpd_Connection * connection);
374 void mpd_sendPrevCommand(mpd_Connection * connection);
376 void mpd_sendMoveCommand(mpd_Connection * connection, int from, int to);
378 void mpd_sendSwapCommand(mpd_Connection * connection, int song1, int song2);
380 void mpd_sendSeekCommand(mpd_Connection * connection, int song, int time);
382 void mpd_sendRepeatCommand(mpd_Connection * connection, int repeatMode);
384 void mpd_sendRandomCommand(mpd_Connection * connection, int randomMode);
386 void mpd_sendSetvolCommand(mpd_Connection * connection, int volumeChange);
388 /* WARNING: don't use volume command, its depreacted */
389 void mpd_sendVolumeCommand(mpd_Connection * connection, int volumeChange);
391 void mpd_sendCrossfadeCommand(mpd_Connection * connection, int seconds);
393 void mpd_sendUpdateCommand(mpd_Connection * connection);
395 /* returns the update job id, call this after a update command*/
396 int mpd_getUpdateId(mpd_Connection * connection);
398 void mpd_sendPasswordCommand(mpd_Connection * connection, const char * pass);
400 /* after executing a command, when your done with it to get its status
401 * (you want to check connection->error for an error)
402 */
403 void mpd_finishCommand(mpd_Connection * connection);
405 /* command list stuff, use this to do things like add files very quickly */
406 void mpd_sendCommandListBegin(mpd_Connection * connection);
408 void mpd_sendCommandListEnd(mpd_Connection * connection);
410 #ifdef __cplusplus
411 }
412 #endif
414 #endif