From 9fb811c3988b039bedbb4967bc5bed7d06687d5a Mon Sep 17 00:00:00 2001 From: Qball Cow Date: Sun, 21 Oct 2007 13:48:33 +0200 Subject: [PATCH] Fixing up the documentation, regrouping and adding missing descriptions. --- src/libmpd-database.h | 124 ++++++++++++++++++++++++++++---------------------- src/libmpd-playlist.c | 4 +- src/libmpd-playlist.h | 44 ++++++++++++++---- src/libmpd-status.h | 39 +++++++++++----- src/libmpd.h | 2 +- 5 files changed, 136 insertions(+), 77 deletions(-) diff --git a/src/libmpd-database.h b/src/libmpd-database.h index de8c309..4a02820 100644 --- a/src/libmpd-database.h +++ b/src/libmpd-database.h @@ -87,31 +87,6 @@ int mpd_database_update_dir (MpdObj *mi, char *path); */ MpdData * mpd_database_token_find (MpdObj *mi , char *string); - - -/** - * @param mi A #MpdObj - * @param path path of the playlist - * - * Deletes a playlist. - * @returns - */ - -int mpd_database_delete_playlist(MpdObj *mi,char *path); - - - -/** - * @param mi a #MpdObj - * @param name The name of the playlist - * - * Saves the current playlist to a file. - * - * @returns a #MpdError. #MPD_OK if succesfull, - * #MPD_DATABASE_PLAYLIST_EXIST when the playlist allready exists. - */ -int mpd_database_save_playlist (MpdObj *mi, char *name); - /** * @param mi a #MpdObj * @param table table @@ -132,25 +107,16 @@ MpdData * mpd_database_find(MpdObj *mi, int table, char *string, int exact); */ MpdData * mpd_database_get_directory(MpdObj *mi,char *path); - /** * @param mi a #MpdObj - * @param playlist the playlist you need the content off. + * @param path a string containing the path * - * Only works with patched mpd. - * Check for %mpd_server_command_allowed(mi, "listPlaylistInfo"); + * Recursively list all the songs directory path * - * @returns a #MpdData list + * returns a #MpdData */ -MpdData *mpd_database_get_playlist_content(MpdObj *mi,char *playlist); - -/*@}*/ +MpdData * mpd_database_get_directory_recursive(MpdObj *mi, const char *path); -/** \defgroup advsearch Database Advanced Search - * \ingroup database - * The following functions provide an interface to the improved search capabilities of mpd 0.12.0. - */ -/*@{*/ /** * @param mi A #MpdObj * @param path an Path to a file @@ -162,6 +128,15 @@ MpdData *mpd_database_get_playlist_content(MpdObj *mi,char *playlist); */ mpd_Song * mpd_database_get_fileinfo(MpdObj *mi,const char *path); +/*@}*/ + +/** \defgroup advsearch Database Advanced Search + * \ingroup database + * The following functions provide an interface to the improved search capabilities of mpd 0.12.0. + */ +/*@{*/ + + /** * @param mi A #MpdObj * @param field A #mpd_TagItems @@ -232,13 +207,18 @@ MpdData * mpd_database_search_commit(MpdObj *mi); /*@}*/ - +/** \defgroup databaseSearchStats Database Search Statistics + * \ingroup database + * A extention to the database search, that instead of returning the full results. + * Only reports back a few statistics about the result. + * For now Number of Songs are reported and total playtime. + */ +/*@{*/ /*! \var typedef mpd_SearchStat MpdDBStats \brief A Structure containing numberOfSongs and playTime - int numberOfSongs - unsigned long playTime + see #mpd_SearchStats */ typedef mpd_SearchStats MpdDBStats; @@ -246,8 +226,8 @@ typedef mpd_SearchStats MpdDBStats; /** * @param mi A #MpdObj * - * Starts a search, you can add "constraints" by calling mpd_database_search_add_constraint - * to get the result call mpd_database_search_stats_commit + * Starts a search, you can add constraints by calling #mpd_database_search_add_constraint. + * To get the result call #mpd_database_search_stats_commit * * This function requires mpd 0.13.0 or higher */ @@ -271,12 +251,53 @@ MpdDBStats * mpd_database_search_stats_commit(MpdObj *mi); */ void mpd_database_search_free_stats(MpdDBStats *data); +/*@}*/ + +/** \defgroup databasePlaylist Database Playlist + * \ingroup database + */ +/*@{*/ + + +/** + * @param mi A #MpdObj + * @param path path of the playlist + * + * Deletes a playlist. + * @returns + */ + +int mpd_database_delete_playlist(MpdObj *mi,char *path); + +/** + * @param mi a #MpdObj + * @param name The name of the playlist + * + * Saves the current playlist to a file. + * + * @returns a #MpdError. #MPD_OK if succesfull, + * #MPD_DATABASE_PLAYLIST_EXIST when the playlist allready exists. + */ +int mpd_database_save_playlist (MpdObj *mi, char *name); + +/** + * @param mi a #MpdObj + * @param playlist the playlist you need the content off. + * + * Check for #mpd_server_command_allowed(mi, "listplaylistinfo"); + * Needs mpd 0.12.0 or higher. + * + * @returns a #MpdData list + */ +MpdData *mpd_database_get_playlist_content(MpdObj *mi,char *playlist); + /** * @param mi a #MpdObj * @param path a string contains the path of the playlist * @param file a string contains the path of the song to add * * Add a path to a stored playlist. + * Needs 0.13.0 */ void mpd_database_playlist_list_add(MpdObj *mi, const char *path, const char *file); @@ -286,25 +307,17 @@ void mpd_database_playlist_list_add(MpdObj *mi, const char *path, const char *fi * @param pos a int representing the position of a song * * Deletes the song at position pos from a playlist. - */ -void mpd_database_playlist_list_delete(MpdObj *mi, const char *path, int pos); - -/** - * @param mi a #MpdObj - * @param path a string containing the path - * - * Recursively list all the songs directory path + * Needs mpd 0.13.0 * - * returns a #MpdData */ -MpdData * mpd_database_get_directory_recursive(MpdObj *mi, const char *path); +void mpd_database_playlist_list_delete(MpdObj *mi, const char *path, int pos); /** * @param mi a #MpdObj * @param path a string contains the path of the playlist * * Clears the content of a stored playlist, also used to create an empty playlist - * + * Needs mpd 0.13.0 */ void mpd_database_playlist_clear(MpdObj *mi,const char *path); @@ -314,6 +327,7 @@ void mpd_database_playlist_clear(MpdObj *mi,const char *path); * @param new a string, new playlist name * * Renames a stored playlist + * Needs mpd 0.13.0 */ void mpd_database_playlist_rename(MpdObj *mi, const char *old, const char *new); @@ -324,6 +338,8 @@ void mpd_database_playlist_rename(MpdObj *mi, const char *old, const char *new); * @param new_pos integer representing the position to move old_pos to. * * Moves songs in a stored playlists + * Needs mpd 0.13.0 */ int mpd_database_playlist_move(MpdObj *mi, const char *playlist, int old_pos, int new_pos); +/*@}*/ #endif diff --git a/src/libmpd-playlist.c b/src/libmpd-playlist.c index 706a39c..a827011 100644 --- a/src/libmpd-playlist.c +++ b/src/libmpd-playlist.c @@ -859,7 +859,7 @@ int mpd_playlist_queue_mpd_queue_add(MpdObj *mi,int id) mi->queue->path = NULL; return MPD_OK; } -int mpd_playlist_queue_mpd_queue_remove(MpdObj *mi,int id) +int mpd_playlist_queue_mpd_queue_remove(MpdObj *mi,int pos) { if(!mpd_check_connected(mi)) { @@ -883,7 +883,7 @@ int mpd_playlist_queue_mpd_queue_remove(MpdObj *mi,int id) mi->queue->next = NULL; } mi->queue->type = MPD_QUEUE_MPD_QUEUE_REMOVE; - mi->queue->id = id; + mi->queue->id = pos; mi->queue->path = NULL; return MPD_OK; } diff --git a/src/libmpd-playlist.h b/src/libmpd-playlist.h index 249e172..76e5edd 100644 --- a/src/libmpd-playlist.h +++ b/src/libmpd-playlist.h @@ -262,19 +262,47 @@ int mpd_playlist_queue_delete_pos (MpdObj *mi,int songpos); */ int mpd_playlist_queue_commit (MpdObj *mi); +/*@}*/ -MpdData * mpd_playlist_search_commit(MpdObj *mi); +/** \defgroup playlistsearch Playlist Search + * \ingroup Playlist + * Allow server side search of the current playlist. + */ +/*@{*/ -void mpd_playlist_search_add_constraint(MpdObj *mi, mpd_TagItems field, const char *value); +/** + * @param mi a #MpdObj + * @param exact if #TRUE only return exact matches + * + * Starts a playlist search. Add constraints using #mpd_playlist_search_add_constraint + * And execute the search with #mpd_playlist_search_commit + * + */ +void mpd_playlist_search_start(MpdObj *mi, int exact); +/** + * @param mi a #MpdObj + * + * Executes the playlist search. This needs to be started with #mpd_playlist_search_start + * + * @returns a #MpdData list + */ +MpdData * mpd_playlist_search_commit(MpdObj *mi); -void mpd_playlist_search_start(MpdObj *mi, int exact); +/** + * @param mi A #MpdObj + * @param field A #mpd_TagItems + * @param value a string to match the field against + * + * Adds a constraint to the playlist search. + */ +void mpd_playlist_search_add_constraint(MpdObj *mi, mpd_TagItems field, const char *value); /*@}*/ /** \defgroup playlistqueue Playlist Queue * \ingroup Playlist - * Allow control of mpd's new playlsit queue + * Allow control of MPD new queue system */ /*@{*/ @@ -300,7 +328,7 @@ int mpd_playlist_mpd_queue_add(MpdObj *mi, int songid); /** * @param mi a #MpdObj - * @param songpos the pos of the song to remov + * @param songpos the pos of the song to remove * * Removes the song from the queue at position pos * @@ -311,7 +339,7 @@ int mpd_playlist_mpd_queue_remove(MpdObj *mi, int songpos); /** * * @param mi a #MpdObj - * @param songid Add a song to the queue + * @param id Add the song with id to the queue * * This only queues the add, use #mpd_playlist_queue_commit to actually commit it. * @@ -320,13 +348,13 @@ int mpd_playlist_mpd_queue_remove(MpdObj *mi, int songpos); int mpd_playlist_queue_mpd_queue_add(MpdObj *mi,int id); /** * @param mi a #MpdObj - * @param songpos the pos of the song to remov + * @param pos the pos of the song to remove * * This only queues the remove, use #mpd_playlist_queue_commit to actually commit it. * * @returns a #MpdError */ -int mpd_playlist_queue_mpd_queue_remove(MpdObj *mi,int id); +int mpd_playlist_queue_mpd_queue_remove(MpdObj *mi,int pos); /*@}*/ #endif diff --git a/src/libmpd-status.h b/src/libmpd-status.h index 2561df4..f8958f4 100644 --- a/src/libmpd-status.h +++ b/src/libmpd-status.h @@ -183,6 +183,33 @@ int mpd_status_set_crossfade (MpdObj *mi, int crossfade_time); /** * @param mi a #MpdObj * + * Checks if mpd is updating it's music db. + * + * @returns TRUE if mpd is still updating, FALSE if not. + */ +int mpd_status_db_is_updating (MpdObj *mi); + +/** + * @param mi a #MpdObj + * + * @returns the error message that mpd last reported, on NULL. Needs to be free'ed. + */ + +char * mpd_status_get_mpd_error(MpdObj *mi); + +/*@}*/ + +/**\defgroup 20stats Stats + * Functions to get mpd statistics + */ +/*@{*/ + + + + +/** + * @param mi a #MpdObj + * * Shouldn't be used from the program. */ int mpd_stats_update (MpdObj *mi); @@ -250,18 +277,6 @@ int mpd_stats_get_playtime (MpdObj *mi); -/** - * @param mi a #MpdObj - * - * Checks if mpd is updating it's music db. - * - * @returns TRUE if mpd is still updating, FALSE if not. - */ -int mpd_status_db_is_updating (MpdObj *mi); - - - -char * mpd_status_get_mpd_error(MpdObj *mi); /*@}*/ #endif diff --git a/src/libmpd.h b/src/libmpd.h index ba7388a..701f500 100644 --- a/src/libmpd.h +++ b/src/libmpd.h @@ -140,7 +140,7 @@ typedef struct _MpdData { MpdDataType type; union { struct { - /** a #mpd_TagType defining what #tag contains */ + /** a #mpd_TagItems defining what #tag contains */ int tag_type; /** a string containing the tag*/ char *tag; -- 2.11.4.GIT