src/libmpd-database.h

   1 /* libmpd (high level libmpdclient library)
   2  * Copyright (C) 2004-2009 Qball Cow <qball@sarine.nl>
   3  * Project homepage: http://gmpcwiki.sarine.nl/
   4
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9
  10  * This program 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 General Public License for more details.
  14
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  18 */
  19
  20 #ifndef __MPD_LIB_DATABASE__
  21 #define __MPD_LIB_DATABASE__
  22
  23 /** \defgroup database Database
  24  */
  25 /*@{*/
  26
  27
  28
  29 /**
  30  * @param mi A #MpdObj
  31  * @param artist an artist name
  32  *
  33  * Grabs a list of albums of a certain artist from mpd.
  34  * if artist is %NULL it grabs all albums
  35  *
  36  * @returns A #MpdData list.
  37  */
  38 MpdData *       mpd_database_get_albums         (MpdObj *mi,const char *artist);
  39
  40
  41 /**
  42  * @param mi a #MpdObj
  43  *
  44  * returns a list of all available artists.
  45  *
  46  * @returns a #MpdData list
  47  */
  48 MpdData *       mpd_database_get_artists                (MpdObj *mi);
  49
  50
  51 /**
  52  * @param mi a #MpdObj
  53  *
  54  * Gets the complete database, only returns songs
  55  *
  56  * @returns a #MpdData list with songs
  57  */
  58
  59 MpdData * mpd_database_get_complete(MpdObj *mi);
  60
  61
  62 /**
  63  *@param mi A #MpdObj
  64  *@param path The path mpd should update.
  65  *
  66  * Force mpd to update (parts of) the database.
  67  *
  68  * @returns a #MpdError
  69  */
  70 int     mpd_database_update_dir         (MpdObj *mi,const char *path);
  71
  72
  73 /**
  74  * @param mi a #MpdObj
  75  * @param table table
  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
  80  */
  81 MpdData * mpd_database_find(MpdObj *mi, int table,const char *string, int exact);
  82
  83 /**
  84  * @param mi a #MpdObj
  85  * @param path a NULL terminated path string
  86  *
  87  * Gets the contents of a directory, it can return songs, directories and playlists
  88  *
  89  * @returns a #MpdData list with songs, directories and playlists
  90  */
  91 MpdData * mpd_database_get_directory(MpdObj *mi,const char *path);
  92
  93 /**
  94  * @param mi a #MpdObj
  95  * @param path a string containing the  path
  96  *
  97  * Recursively list all the songs directory path
  98  *
  99  * @returns a #MpdData
 100  */
 101 MpdData * mpd_database_get_directory_recursive(MpdObj *mi, const char *path);
 102
 103 /**
 104  * @param mi A #MpdObj
 105  * @param path an Path to a file
 106  *
 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.
 109  *
 110  * @returns a #mpd_Song
 111  */
 112 mpd_Song * mpd_database_get_fileinfo(MpdObj *mi,const char *path);
 113
 114 /*@}*/
 115
 116 /** \defgroup advsearch Database Advanced Search
 117  * \ingroup database
 118  * The following functions provide an interface to the improved search capabilities of mpd 0.12.0.
 119  */
 120 /*@{*/
 121
 122
 123 /**
 124  * @param mi A #MpdObj
 125  * @param field A #mpd_TagItems
 126  * @param value a string that %field needs to match
 127  *
 128  * Adds a constraint to the search
 129  */
 130 void mpd_database_search_add_constraint(MpdObj *mi, mpd_TagItems field, const char *value);
 131
 132 /**
 133  * @param mi A #MpdObj
 134  * @param exact a boolean indicating if the search is fuzzy or exact
 135  *
 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:
 138  *
 139  * @code
 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);
 143  * @endcode
 144  *
 145  * If you only want the songs from the album unplugged:
 146  *
 147  * @code
 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);
 152  * @endcode
 153  *
 154  * This function requires mpd 0.12.0 or higher
 155  */
 156
 157 void mpd_database_search_start(MpdObj *mi, int exact);
 158
 159 /**
 160  * @param mi a #MpdObj
 161  * @param field a #mpd_TagItems
 162  *
 163  * Starts a field search, eg. if you want a list of all albums, you do;
 164  *
 165  * @code
 166  * mpd_database_search_field_start(mi, MPD_TAG_ITEM_ALBUM);
 167  * data = mpd_database_search_commit(mi);
 168  * @endcode
 169  *
 170  * You can add constraints using mpd_database_search_add_constraint, for example if you want
 171  * all albums by eric clapton:
 172  *
 173  * @code
 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);
 177  * @endcode
 178  */
 179 void mpd_database_search_field_start(MpdObj *mi, mpd_TagItems field);
 180
 181 /**
 182  * @param mi A #MpdObj
 183  *
 184  * Commits the search and gathers the result in a #MpdData list.
 185  *
 186  * @returns a #MpdData list with the search result, or NULL when nothing is found
 187  */
 188 MpdData * mpd_database_search_commit(MpdObj *mi);
 189
 190
 191
 192 /*@}*/
 193 /** \defgroup databaseSearchStats Database Search Statistics
 194  * \ingroup database
 195  * A extension 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.
 198  */
 199 /*@{*/
 200
 201 /*! \var typedef mpd_SearchStat MpdDBStats
 202     \brief A Structure containing numberOfSongs and playTime
 203
 204     see #mpd_SearchStats
 205 */
 206
 207 typedef mpd_SearchStats MpdDBStats;
 208
 209 /**
 210  * @param mi A #MpdObj
 211  *
 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
 214  *
 215  * This function requires mpd 0.13.0 or higher
 216  */
 217
 218 void mpd_database_search_stats_start(MpdObj *mi);
 219
 220
 221 /**
 222  * @param mi A #MpdObj
 223  *
 224  * Gets statistics results of a search.
 225  *
 226  * @returns a #MpdDBStats
 227  */
 228 MpdDBStats * mpd_database_search_stats_commit(MpdObj *mi);
 229
 230 /**
 231  * @param data a #MpdDBStats
 232  *
 233  * frees the #MpdDBStats structure.
 234  */
 235 void mpd_database_search_free_stats(MpdDBStats *data);
 236
 237 /*@}*/
 238
 239 /** \defgroup databasePlaylist Database Playlist
 240  * \ingroup database
 241  */
 242 /*@{*/
 243
 244
 245 /**
 246  * @param mi A #MpdObj
 247  * @param path path of the playlist
 248  *
 249  * Deletes a playlist.
 250  * @returns a #MpdError
 251  */
 252
 253 int mpd_database_delete_playlist(MpdObj *mi,const char *path);
 254
 255 /**
 256  * @param mi a #MpdObj
 257  * @param name The name of the playlist
 258  *
 259  * Saves the current playlist to a file.
 260  *
 261  * @returns a #MpdError. #MPD_OK if successful,
 262  * #MPD_DATABASE_PLAYLIST_EXIST when the playlist already exists.
 263  */
 264 int             mpd_database_save_playlist                      (MpdObj *mi,const char *name);
 265
 266 /**
 267  * @param mi a #MpdObj
 268  * @param playlist the playlist you need the content of.
 269  *
 270  * Needs mpd 0.12.0 or higher.
 271  *
 272  * @returns a #MpdData list
 273  */
 274 MpdData *mpd_database_get_playlist_content(MpdObj *mi,const char *playlist);
 275
 276 /**
 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
 280  *
 281  * Add a path to a stored playlist.
 282  * Needs 0.13.0
 283  */
 284 void mpd_database_playlist_list_add(MpdObj *mi, const char *path, const char *file);
 285
 286 /**
 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
 290  *
 291  * Deletes the song at position pos from a playlist.
 292  * Needs mpd 0.13.0
 293  *
 294  */
 295 void mpd_database_playlist_list_delete(MpdObj *mi, const char *path, int pos);
 296
 297 /**
 298  * @param mi a #MpdObj
 299  * @param path a string containing the path of the playlist
 300  *
 301  * Clears the content of a stored playlist, also used to create an empty playlist
 302  * Needs mpd 0.13.0
 303  */
 304 void mpd_database_playlist_clear(MpdObj *mi,const char *path);
 305
 306 /**
 307  * @param mi a #MpdObj
 308  * @param old a string, old playlist name
 309  * @param new  a string, new playlist name
 310  *
 311  * Renames a stored playlist
 312  * Needs mpd 0.13.0
 313  */
 314 void mpd_database_playlist_rename(MpdObj *mi, const char *old_name, const char *new_name);
 315
 316 /**
 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.
 321  *
 322  * Moves songs in a stored playlist
 323  * Needs mpd 0.13.0
 324  */
 325 int mpd_database_playlist_move(MpdObj *mi, const char *playlist, int old_pos, int new_pos);
 326 MpdData * mpd_database_playlist_list(MpdObj *mi);
 327 /*@}*/
 328 #endif