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/param.h>
24 #include <sys/time.h>
26 #define MPD_BUFFER_MAX_LENGTH 50000
27 #define MPD_WELCOME_MESSAGE "OK MPD "
29 #define MPD_ERROR_TIMEOUT 10 /* timeout trying to talk to mpd */
30 #define MPD_ERROR_SYSTEM 11 /* system error */
31 #define MPD_ERROR_UNKHOST 12 /* unknown host */
32 #define MPD_ERROR_CONNPORT 13 /* problems connecting to port on host */
33 #define MPD_ERROR_NOTMPD 14 /* mpd not running on port at host */
34 #define MPD_ERROR_NORESPONSE 15 /* no response on attempting to connect */
35 #define MPD_ERROR_SENDING 16 /* error sending command */
36 #define MPD_ERROR_CONNCLOSED 17 /* connection closed by mpd */
37 #define MPD_ERROR_ACK 18 /* ACK returned! */
38 #define MPD_ERROR_BUFFEROVERRUN 19 /* Buffer was overrun! */
40 #ifdef __cplusplus
41 extern "C" {
42 #endif
44 /* internal stuff don't touch this struct */
45 typedef struct _mpd_ReturnElement {
46 char * name;
47 char * value;
48 } mpd_ReturnElement;
50 /* mpd_Connection
51 * holds info about connection to mpd
52 * use error, and errorStr to detect errors
53 */
54 typedef struct _mpd_Connection {
55 /* use this to check the version of mpd */
56 int version[3];
57 /* IMPORTANT, you want to get the error messages from here */
58 char errorStr[MPD_BUFFER_MAX_LENGTH+1];
59 /* this will be set to 1 if there is an error, 0 if not */
60 int error;
61 /* DON'T TOUCH any of the rest of this stuff */
62 int sock;
63 char buffer[MPD_BUFFER_MAX_LENGTH+1];
64 int buflen;
65 int bufstart;
66 int doneProcessing;
67 int commandList;
68 mpd_ReturnElement * returnElement;
69 struct timeval timeout;
70 } mpd_Connection;
72 /* mpd_newConnection
73 * use this to open a new connection
74 * you should use mpd_closeConnection, when your done with the connection,
75 * even if an error has occurred
76 * _timeout_ is the connection timeout period in seconds
77 */
78 mpd_Connection * mpd_newConnection(const char * host, int port, float timeout);
80 void mpd_setConnectionTimeout(mpd_Connection * connection, float timeout);
82 /* mpd_closeConnection
83 * use this to close a connection and free'ing subsequent memory
84 */
85 void mpd_closeConnection(mpd_Connection * connection);
87 /* mpd_clearError
88 * clears error
89 */
90 void mpd_clearError(mpd_Connection * connection);
92 /* STATUS STUFF */
94 /* use these with status.state to determine what state the player is in */
95 #define MPD_STATUS_STATE_UNKNOWN 0
96 #define MPD_STATUS_STATE_STOP 1
97 #define MPD_STATUS_STATE_PLAY 2
98 #define MPD_STATUS_STATE_PAUSE 3
100 /* us this with status.volume to determine if mpd has volume support */
101 #define MPD_STATUS_NO_VOLUME -1
103 /* mpd_Status
104 * holds info return from status command
105 */
106 typedef struct mpd_Status {
107 /* 0-100, or MPD_STATUS_NO_VOLUME when there is no volume support */
108 int volume;
109 /* 1 if repeat is on, 0 otherwise */
110 int repeat;
111 /* 1 if random is on, 0 otherwise */
112 int random;
113 /* playlist length */
114 int playlistLength;
115 /* playlist, use this to determine when the playlist has changed */
116 long long playlist;
117 /* use with MPD_STATUS_STATE_* to determine state of player */
118 int state;
119 /* crossfade setting in seconds */
120 int crossfade;
121 /* if in PLAY or PAUSE state, this is the number of the currently
122 * playing song in the playlist, beginning with 0
123 */
124 int song;
125 /* time in seconds that have elapsed in the currently playing/paused
126 * song
127 */
128 int elapsedTime;
129 /* length in seconds of the currently playing/paused song */
130 int totalTime;
131 /* current bit rate in kbs */
132 int bitRate;
133 /* audio sample rate */
134 unsigned int sampleRate;
135 /* audio bits */
136 int bits;
137 /* audio channels */
138 int channels;
139 /* error */
140 char * error;
141 } mpd_Status;
143 /* mpd_getStatus
144 * returns status info, be sure to free it with mpd_freeStatus()
145 */
146 mpd_Status * mpd_getStatus(mpd_Connection * connection);
148 /* mpd_freeStatus
149 * free's status info malloc'd and returned by mpd_getStatus
150 */
151 void mpd_freeStatus(mpd_Status * status);
153 typedef struct _mpd_Stats {
154 int numberOfArtists;
155 int numberOfAlbums;
156 int numberOfSongs;
157 unsigned long uptime;
158 unsigned long dbUpdateTime;
159 unsigned long playTime;
160 unsigned long dbPlayTime;
161 } mpd_Stats;
163 mpd_Stats * mpd_getStats(mpd_Connection * connection);
165 void mpd_freeStats(mpd_Stats * stats);
167 /* SONG STUFF */
169 #define MPD_SONG_NO_TIME -1
171 /* mpd_Song
172 * for storing song info returned by mpd
173 */
174 typedef struct _mpd_Song {
175 /* filename of song */
176 char * file;
177 /* artist, maybe NULL if there is no tag */
178 char * artist;
179 /* title, maybe NULL if there is no tag */
180 char * title;
181 /* album, maybe NULL if there is no tag */
182 char * album;
183 /* track, maybe NULL if there is no tag */
184 char * track;
185 /* length of song in seconds, check that it is not MPD_SONG_NO_TIME */
186 int time;
187 } mpd_Song;
189 /* mpd_newSong
190 * use to allocate memory for a new mpd_Song
191 * file, artist, etc all initialized to NULL
192 * if your going to assign values to file, artist, etc
193 * be sure to malloc or strdup the memory
194 * use mpd_freeSong to free the memory for the mpd_Song, it will also
195 * free memory for file, artist, etc, so don't do it yourself
196 */
197 mpd_Song * mpd_newSong();
199 /* mpd_freeSong
200 * use to free memory allocated by mpd_newSong
201 * also it will free memory pointed to by file, artist, etc, so be careful
202 */
203 void mpd_freeSong(mpd_Song * song);
205 /* mpd_songDup
206 * works like strDup, but for a mpd_Song
207 */
208 mpd_Song * mpd_songDup(mpd_Song * song);
210 /* DIRECTORY STUFF */
212 /* mpd_Directory
213 * used to store info fro directory (right now that just the path)
214 */
215 typedef struct _mpd_Directory {
216 char * path;
217 } mpd_Directory;
219 /* mpd_newDirectory
220 * allocates memory for a new directory
221 * use mpd_freeDirectory to free this memory
222 */
223 mpd_Directory * mpd_newDirectory ();
225 /* mpd_freeDirectory
226 * used to free memory allocated with mpd_newDirectory, and it frees
227 * path of mpd_Directory, so be careful
228 */
229 void mpd_freeDirectory(mpd_Directory * directory);
231 /* mpd_directoryDup
232 * works like strdup, but for mpd_Directory
233 */
234 mpd_Directory * mpd_directoryDup(mpd_Directory * directory);
236 /* PLAYLISTFILE STUFF */
238 /* mpd_PlaylistFile
239 * stores info about playlist file returned by lsinfo
240 */
241 typedef struct _mpd_PlaylistFile {
242 char * path;
243 } mpd_PlaylistFile;
245 /* mpd_newPlaylistFile
246 * allocates memory for new mpd_PlaylistFile, path is set to NULL
247 * free this memory with mpd_freePlaylistFile
248 */
249 mpd_PlaylistFile * mpd_newPlaylistFile();
251 /* mpd_freePlaylist
252 * free memory allocated for freePlaylistFile, will also free
253 * path, so be careful
254 */
255 void mpd_freePlaylistFile(mpd_PlaylistFile * playlist);
257 /* mpd_playlistFileDup
258 * works like strdup, but for mpd_PlaylistFile
259 */
260 mpd_PlaylistFile * mpd_playlistFileDup(mpd_PlaylistFile * playlist);
262 /* INFO ENTITY STUFF */
264 /* the type of entity returned from one of the commands that generates info
265 * use in conjunction with mpd_InfoEntity.type
266 */
267 #define MPD_INFO_ENTITY_TYPE_DIRECTORY 0
268 #define MPD_INFO_ENTITY_TYPE_SONG 1
269 #define MPD_INFO_ENTITY_TYPE_PLAYLISTFILE 2
271 /* mpd_InfoEntity
272 * stores info on stuff returned info commands
273 */
274 typedef struct mpd_InfoEntity {
275 /* the type of entity, use with MPD_INFO_ENTITY_TYPE_* to determine
276 * what this entity is (song, directory, etc...)
277 */
278 int type;
279 /* the actual data you want, mpd_Song, mpd_Directory, etc */
280 union {
281 mpd_Directory * directory;
282 mpd_Song * song;
283 mpd_PlaylistFile * playlistFile;
284 } info;
285 } mpd_InfoEntity;
287 mpd_InfoEntity * mpd_newInfoEntity();
289 void mpd_freeInfoEntity(mpd_InfoEntity * entity);
291 /* INFO COMMANDS AND STUFF */
293 /* use this function to loop over after calling Info/Listall functions */
294 mpd_InfoEntity * mpd_getNextInfoEntity(mpd_Connection * connection);
296 /* songNum of -1, means to display the whole list */
297 void mpd_sendPlaylistInfoCommand(mpd_Connection * connection, int songNum);
299 void mpd_sendListallCommand(mpd_Connection * connection, const char * dir);
301 void mpd_sendListallInfoCommand(mpd_Connection * connection, const char * dir);
303 void mpd_sendLsInfoCommand(mpd_Connection * connection, const char * dir);
305 #define MPD_TABLE_ARTIST 0
306 #define MPD_TABLE_ALBUM 1
307 #define MPD_TABLE_TITLE 2
308 #define MPD_TABLE_FILENAME 3
310 void mpd_sendSearchCommand(mpd_Connection * connection, int table,
311 const char * str);
313 void mpd_sendFindCommand(mpd_Connection * connection, int table,
314 const char * str);
316 /* LIST TAG COMMANDS */
318 /* use this function fetch next artist entry, be sure to free the returned
319 * string. NULL means there are no more. Best used with sendListArtists
320 */
321 char * mpd_getNextArtist(mpd_Connection * connection);
323 char * mpd_getNextAlbum(mpd_Connection * connection);
325 /* list artist or albums by artist, arg1 should be set to the artist if
326 * listing albums by a artist, otherwise NULL for listing all artists or albums
327 */
328 void mpd_sendListCommand(mpd_Connection * connection, int table,
329 const char * arg1);
331 void mpd_sendListAlbumsCommand(mpd_Connection * connection,
332 const char * artist);
334 /* SIMPLE COMMANDS */
336 void mpd_sendAddCommand(mpd_Connection * connection, const char * file);
338 void mpd_sendDeleteCommand(mpd_Connection * connection, int songNum);
340 void mpd_sendSaveCommand(mpd_Connection * connection, const char * name);
342 void mpd_sendLoadCommand(mpd_Connection * connection, const char * name);
344 void mpd_sendRmCommand(mpd_Connection * connection, const char * name);
346 void mpd_sendShuffleCommand(mpd_Connection * connection);
348 void mpd_sendClearCommand(mpd_Connection * connection);
350 /* use this to start playing at the beginning, useful when in random mode */
351 #define MPD_PLAY_AT_BEGINNING -1
353 void mpd_sendPlayCommand(mpd_Connection * connection, int songNum);
355 void mpd_sendStopCommand(mpd_Connection * connection);
357 void mpd_sendPauseCommand(mpd_Connection * connection);
359 void mpd_sendNextCommand(mpd_Connection * connection);
361 void mpd_sendPrevCommand(mpd_Connection * connection);
363 void mpd_sendMoveCommand(mpd_Connection * connection, int from, int to);
365 void mpd_sendSwapCommand(mpd_Connection * connection, int song1, int song2);
367 void mpd_sendSeekCommand(mpd_Connection * connection, int song, int time);
369 void mpd_sendRepeatCommand(mpd_Connection * connection, int repeatMode);
371 void mpd_sendRandomCommand(mpd_Connection * connection, int randomMode);
373 void mpd_sendSetvolCommand(mpd_Connection * connection, int volumeChange);
375 /* WARNING: don't use volume command, its depreacted */
376 void mpd_sendVolumeCommand(mpd_Connection * connection, int volumeChange);
378 void mpd_sendCrossfadeCommand(mpd_Connection * connection, int seconds);
380 int mpd_getCrossfade(mpd_Connection * connection);
382 void mpd_sendUpdateCommand(mpd_Connection * connection);
384 void mpd_sendPasswordCommand(mpd_Connection * connection, const char * pass);
386 /* after executing a command, when your done with it to get its status
387 * (you want to check connection->error for an error)
388 */
389 void mpd_finishCommand(mpd_Connection * connection);
391 /* command list stuff, use this to do things like add files very quickly */
392 void mpd_sendCommandListBegin(mpd_Connection * connection);
394 void mpd_sendCommandListEnd(mpd_Connection * connection);
396 #ifdef __cplusplus
397 }
398 #endif
400 #endif