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.
20 #ifndef __MPD_LIB_DATABASE__
21 #define __MPD_LIB_DATABASE__
23 /** \defgroup database Database
31 * @param artist an artist name
33 * Grabs a list of albums of a certain artist from mpd.
34 * if artist is %NULL it grabs all albums
36 * @returns A #MpdData list.
38 MpdData
* mpd_database_get_albums (MpdObj
*mi
, char *artist
);
44 * returns a list of all available artists.
46 * @returns a #MpdData list
48 MpdData
* mpd_database_get_artists (MpdObj
*mi
);
54 * Gets the complete datababse, only returns songs
56 * @returns a #MpdData list with songs
59 MpdData
* mpd_database_get_complete(MpdObj
*mi
);
64 *@param path The path mpd should update.
66 * Force mpd to update (parts of) the database.
68 * @returns a #MpdError
70 int mpd_database_update_dir (MpdObj
*mi
, char *path
);
76 * @param string string to search for
77 * @param exact if #TRUE only return exact matches
78 * WARNING: This function is deprecated, use mpd_database_search_start
79 * @returns a #MpdData list
81 MpdData
* mpd_database_find(MpdObj
*mi
, int table
, char *string
, int exact
);
85 * @param path a NULL terminated path string
87 * Gets the contents of a directory, it can return songs, directories and playlists
89 * @returns a #MpdData list with songs, directories and playlists
91 MpdData
* mpd_database_get_directory(MpdObj
*mi
,char *path
);
95 * @param path a string containing the path
97 * Recursively list all the songs directory path
101 MpdData
* mpd_database_get_directory_recursive(MpdObj
*mi
, const char *path
);
104 * @param mi A #MpdObj
105 * @param path an Path to a file
107 * Grabs the song info for a single file. Make sure you pass a url to a song
108 * and not a directory, that might result in strange behaviour.
110 * @returns a #mpd_Song
112 mpd_Song
* mpd_database_get_fileinfo(MpdObj
*mi
,const char *path
);
116 /** \defgroup advsearch Database Advanced Search
118 * The following functions provide an interface to the improved search capabilities of mpd 0.12.0.
124 * @param mi A #MpdObj
125 * @param field A #mpd_TagItems
126 * @param value a string that %field needs to match
128 * Adds a constraint to the search
130 void mpd_database_search_add_constraint(MpdObj
*mi
, mpd_TagItems field
, const char *value
);
133 * @param mi A #MpdObj
134 * @param exact a boolean indicating if the search is fuzzy or exact
136 * Starts a search, you can add "constraints" by calling mpd_database_search_add_constraint
137 * For Example if you want all songs by Eric Clapton you could do:
140 * mpd_database_search_start(mi, TRUE);
141 * mpd_database_search_add_constraint(mi, MPD_TAG_ITEM_ARTIST, "Eric Clapton");
142 * data= mpd_database_search_commit(mi);
145 * If you only want the songs from the album unplugged:
148 * mpd_database_search_start(mi, TRUE);
149 * mpd_database_search_add_constraint(mi, MPD_TAG_ITEM_ARTIST, "Eric Clapton");
150 * mpd_database_search_add_constraint(mi, MPD_TAG_ITEM_ALBUM, "Unplugged");
151 * data= mpd_database_search_commit(mi);
154 * This function requires mpd 0.12.0 or higher
157 void mpd_database_search_start(MpdObj
*mi
, int exact
);
160 * @param mi a #MpdObj
161 * @param field a #mpd_TagItems
163 * Starts a field search, eg. if you want a list of all albums, you do;
166 * mpd_database_search_field_start(mi, MPD_TAG_ITEM_ALBUM);
167 * data = mpd_database_search_commit(mi);
170 * You can add constraints using mpd_database_search_add_constraint, for example if you want
171 * all albums by eric clapton:
174 * mpd_database_search_field_start(mi, MPD_TAG_ITEM_ALBUM);
175 * mpd_database_search_add_constraint(mi, MPD_TAG_ITEM_ARTIST, "Eric Clapton");
176 * data = mpd_database_search_commit(mi);
179 void mpd_database_search_field_start(MpdObj
*mi
, mpd_TagItems field
);
182 * @param mi A #MpdObj
184 * Commits the search and gathers the result in a #MpdData list.
186 * @returns a #MpdData list with the search result, or NULL when nothing is found
188 MpdData
* mpd_database_search_commit(MpdObj
*mi
);
193 /** \defgroup databaseSearchStats Database Search Statistics
195 * A extention to the database search, that instead of returning the full results.
196 * Only reports back a few statistics about the result.
197 * For now Number of Songs are reported and total playtime.
201 /*! \var typedef mpd_SearchStat MpdDBStats
202 \brief A Structure containing numberOfSongs and playTime
207 typedef mpd_SearchStats MpdDBStats
;
210 * @param mi A #MpdObj
212 * Starts a search, you can add constraints by calling #mpd_database_search_add_constraint.
213 * To get the result call #mpd_database_search_stats_commit
215 * This function requires mpd 0.13.0 or higher
218 void mpd_database_search_stats_start(MpdObj
*mi
);
222 * @param mi A #MpdObj
224 * Gets statistics results of a search.
226 * return a #MpdDBStats
228 MpdDBStats
* mpd_database_search_stats_commit(MpdObj
*mi
);
231 * @param data a #MpdDBStats
233 * frees the #MpdDBStats structure.
235 void mpd_database_search_free_stats(MpdDBStats
*data
);
239 /** \defgroup databasePlaylist Database Playlist
246 * @param mi A #MpdObj
247 * @param path path of the playlist
249 * Deletes a playlist.
253 int mpd_database_delete_playlist(MpdObj
*mi
,char *path
);
256 * @param mi a #MpdObj
257 * @param name The name of the playlist
259 * Saves the current playlist to a file.
261 * @returns a #MpdError. #MPD_OK if succesfull,
262 * #MPD_DATABASE_PLAYLIST_EXIST when the playlist allready exists.
264 int mpd_database_save_playlist (MpdObj
*mi
, char *name
);
267 * @param mi a #MpdObj
268 * @param playlist the playlist you need the content off.
270 * Needs mpd 0.12.0 or higher.
272 * @returns a #MpdData list
274 MpdData
*mpd_database_get_playlist_content(MpdObj
*mi
,char *playlist
);
277 * @param mi a #MpdObj
278 * @param path a string contains the path of the playlist
279 * @param file a string contains the path of the song to add
281 * Add a path to a stored playlist.
284 void mpd_database_playlist_list_add(MpdObj
*mi
, const char *path
, const char *file
);
287 * @param mi a #MpdObj
288 * @param path a string containing the path of the playlist
289 * @param pos an int representing the position of a song
291 * Deletes the song at position pos from a playlist.
295 void mpd_database_playlist_list_delete(MpdObj
*mi
, const char *path
, int pos
);
298 * @param mi a #MpdObj
299 * @param path a string containing the path of the playlist
301 * Clears the content of a stored playlist, also used to create an empty playlist
304 void mpd_database_playlist_clear(MpdObj
*mi
,const char *path
);
307 * @param mi a #MpdObj
308 * @param old a string, old playlist name
309 * @param new a string, new playlist name
311 * Renames a stored playlist
314 void mpd_database_playlist_rename(MpdObj
*mi
, const char *old_name
, const char *new_name
);
317 * @param mi a #MpdObj
318 * @param playlist a string containing the path of the playlist
319 * @param old_pos an integer representing old position
320 * @param new_pos an integer representing the position to move old_pos to.
322 * Moves songs in a stored playlist
325 int mpd_database_playlist_move(MpdObj
*mi
, const char *playlist
, int old_pos
, int new_pos
);