From 96432ab4ef27bc6a570427736d8b7f439535e05f Mon Sep 17 00:00:00 2001 From: Rémy Oudompheng Date: Sun, 6 Mar 2011 18:44:03 +0100 Subject: Move documentation of public database functions to alpm.h --- lib/libalpm/alpm.h | 84 ++++++++++++++++++++++++++++++++++++++++++++++++++---- lib/libalpm/db.c | 65 ++++++++---------------------------------- 2 files changed, 91 insertions(+), 58 deletions(-) diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h index 39f987dd..3cbb0290 100644 --- a/lib/libalpm/alpm.h +++ b/lib/libalpm/alpm.h @@ -158,8 +158,6 @@ void alpm_option_set_usedelta(int usedelta); int alpm_option_get_checkspace(void); void alpm_option_set_checkspace(int checkspace); -pmdb_t *alpm_option_get_localdb(void); -alpm_list_t *alpm_option_get_syncdbs(void); /* * Install reasons -- ie, why the package was installed @@ -170,30 +168,106 @@ typedef enum _pmpkgreason_t { PM_PKG_REASON_DEPEND = 1 /* installed as a dependency for another package */ } pmpkgreason_t; -/* - * Databases +/** @addtogroup alpm_api_databases Database Functions + * Functions to query and manipulate the database of libalpm. + * @{ + */ + +/** Get the database of locally installed packages. + * The returned pointer points to an internal structure + * of libalpm which should only be manipulated through + * libalpm functions. + * @return a reference to the local database + */ +pmdb_t *alpm_option_get_localdb(void); + +/** Get the list of sync databases. + * Returns a list of pmdb_t structures, one for each registered + * sync database. + * @return a reference to an internal list of pmdb_t structures */ +alpm_list_t *alpm_option_get_syncdbs(void); +/** Register a sync database of packages. + * @param treename the name of the sync repository + * @return a pmdb_t* on success (the value), NULL on error + */ pmdb_t *alpm_db_register_sync(const char *treename); + +/** Unregister a package database. + * @param db pointer to the package database to unregister + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_db_unregister(pmdb_t *db); + +/** Unregister all package databases. + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_db_unregister_all(void); +/** Get the name of a package database. + * @param db pointer to the package database + * @return the name of the package database, NULL on error + */ const char *alpm_db_get_name(const pmdb_t *db); + +/** Get a download URL for the package database. + * @param db pointer to the package database + * @return a fully-specified download URL, NULL on error + */ const char *alpm_db_get_url(const pmdb_t *db); +/** Set the serverlist of a database. + * @param db database pointer + * @param url url of the server + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_db_setserver(pmdb_t *db, const char *url); int alpm_db_update(int level, pmdb_t *db); +/** Get a package entry from a package database. + * @param db pointer to the package database to get the package from + * @param name of the package + * @return the package entry on success, NULL on error + */ pmpkg_t *alpm_db_get_pkg(pmdb_t *db, const char *name); + +/** Get the package cache of a package database. + * @param db pointer to the package database to get the package from + * @return the list of packages on success, NULL on error + */ alpm_list_t *alpm_db_get_pkgcache(pmdb_t *db); +/** Get a group entry from a package database. + * @param db pointer to the package database to get the group from + * @param name of the group + * @return the groups entry on success, NULL on error + */ pmgrp_t *alpm_db_readgrp(pmdb_t *db, const char *name); + +/** Get the group cache of a package database. + * @param db pointer to the package database to get the group from + * @return the list of groups on success, NULL on error + */ alpm_list_t *alpm_db_get_grpcache(pmdb_t *db); + +/** Searches a database. + * @param db pointer to the package database to search in + * @param needles the list of strings to search for + * @return the list of packages on success, NULL on error + */ alpm_list_t *alpm_db_search(pmdb_t *db, const alpm_list_t* needles); + +/** Set install reason for a package in db. + * @param db pointer to the package database + * @param name the name of the package + * @param reason the new install reason + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_db_set_pkgreason(pmdb_t *db, const char *name, pmpkgreason_t reason); -/* +/** * Packages */ diff --git a/lib/libalpm/db.c b/lib/libalpm/db.c index 49bbd00f..1a3168b4 100644 --- a/lib/libalpm/db.c +++ b/lib/libalpm/db.c @@ -47,10 +47,7 @@ * @{ */ -/** Register a sync database of packages. - * @param treename the name of the sync repository - * @return a pmdb_t* on success (the value), NULL on error - */ +/** Register a sync database of packages. */ pmdb_t SYMEXPORT *alpm_db_register_sync(const char *treename) { ALPM_LOG_FUNC; @@ -75,9 +72,7 @@ void _alpm_db_unregister(pmdb_t *db) _alpm_db_free(db); } -/** Unregister all package databases - * @return 0 on success, -1 on error (pm_errno is set accordingly) - */ +/** Unregister all package databases. */ int SYMEXPORT alpm_db_unregister_all(void) { alpm_list_t *i; @@ -100,10 +95,7 @@ int SYMEXPORT alpm_db_unregister_all(void) return(0); } -/** Unregister a package database - * @param db pointer to the package database to unregister - * @return 0 on success, -1 on error (pm_errno is set accordingly) - */ +/** Unregister a package database. */ int SYMEXPORT alpm_db_unregister(pmdb_t *db) { int found = 0; @@ -140,11 +132,7 @@ int SYMEXPORT alpm_db_unregister(pmdb_t *db) return(0); } -/** Set the serverlist of a database. - * @param db database pointer - * @param url url of the server - * @return 0 on success, -1 on error (pm_errno is set accordingly) - */ +/** Set the serverlist of a database. */ int SYMEXPORT alpm_db_setserver(pmdb_t *db, const char *url) { alpm_list_t *i; @@ -187,10 +175,7 @@ int SYMEXPORT alpm_db_setserver(pmdb_t *db, const char *url) return(0); } -/** Get the name of a package database - * @param db pointer to the package database - * @return the name of the package database, NULL on error - */ +/** Get the name of a package database. */ const char SYMEXPORT *alpm_db_get_name(const pmdb_t *db) { ALPM_LOG_FUNC; @@ -202,10 +187,7 @@ const char SYMEXPORT *alpm_db_get_name(const pmdb_t *db) return db->treename; } -/** Get a download URL for the package database - * @param db pointer to the package database - * @return a fully-specified download URL, NULL on error - */ +/** Get a download URL for the package database. */ const char SYMEXPORT *alpm_db_get_url(const pmdb_t *db) { char *url; @@ -223,11 +205,7 @@ const char SYMEXPORT *alpm_db_get_url(const pmdb_t *db) } -/** Get a package entry from a package database - * @param db pointer to the package database to get the package from - * @param name of the package - * @return the package entry on success, NULL on error - */ +/** Get a package entry from a package database. */ pmpkg_t SYMEXPORT *alpm_db_get_pkg(pmdb_t *db, const char *name) { ALPM_LOG_FUNC; @@ -240,10 +218,7 @@ pmpkg_t SYMEXPORT *alpm_db_get_pkg(pmdb_t *db, const char *name) return(_alpm_db_get_pkgfromcache(db, name)); } -/** Get the package cache of a package database - * @param db pointer to the package database to get the package from - * @return the list of packages on success, NULL on error - */ +/** Get the package cache of a package database. */ alpm_list_t SYMEXPORT *alpm_db_get_pkgcache(pmdb_t *db) { ALPM_LOG_FUNC; @@ -255,11 +230,7 @@ alpm_list_t SYMEXPORT *alpm_db_get_pkgcache(pmdb_t *db) return(_alpm_db_get_pkgcache(db)); } -/** Get a group entry from a package database - * @param db pointer to the package database to get the group from - * @param name of the group - * @return the groups entry on success, NULL on error - */ +/** Get a group entry from a package database. */ pmgrp_t SYMEXPORT *alpm_db_readgrp(pmdb_t *db, const char *name) { ALPM_LOG_FUNC; @@ -272,10 +243,7 @@ pmgrp_t SYMEXPORT *alpm_db_readgrp(pmdb_t *db, const char *name) return(_alpm_db_get_grpfromcache(db, name)); } -/** Get the group cache of a package database - * @param db pointer to the package database to get the group from - * @return the list of groups on success, NULL on error - */ +/** Get the group cache of a package database. */ alpm_list_t SYMEXPORT *alpm_db_get_grpcache(pmdb_t *db) { ALPM_LOG_FUNC; @@ -287,11 +255,7 @@ alpm_list_t SYMEXPORT *alpm_db_get_grpcache(pmdb_t *db) return(_alpm_db_get_grpcache(db)); } -/** Searches a database - * @param db pointer to the package database to search in - * @param needles the list of strings to search for - * @return the list of packages on success, NULL on error - */ +/** Searches a database. */ alpm_list_t SYMEXPORT *alpm_db_search(pmdb_t *db, const alpm_list_t* needles) { ALPM_LOG_FUNC; @@ -303,12 +267,7 @@ alpm_list_t SYMEXPORT *alpm_db_search(pmdb_t *db, const alpm_list_t* needles) return(_alpm_db_search(db, needles)); } -/** Set install reason for a package in db - * @param db pointer to the package database - * @param name the name of the package - * @param reason the new install reason - * @return 0 on success, -1 on error (pm_errno is set accordingly) - */ +/** Set install reason for a package in db. */ int SYMEXPORT alpm_db_set_pkgreason(pmdb_t *db, const char *name, pmpkgreason_t reason) { ALPM_LOG_FUNC; -- cgit v1.2.3-55-g3dc8