From a10584aec48617b4152b7e0653eb8b43f062839a Mon Sep 17 00:00:00 2001 From: Aurelien Foret Date: Sat, 21 Jan 2006 19:29:10 +0000 Subject: document package, group, sync and transaction functions (patch from VMiklos ) --- lib/libalpm/alpm.c | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 62 insertions(+), 1 deletion(-) (limited to 'lib/libalpm/alpm.c') diff --git a/lib/libalpm/alpm.c b/lib/libalpm/alpm.c index 4d21ebdc..da3eaae0 100644 --- a/lib/libalpm/alpm.c +++ b/lib/libalpm/alpm.c @@ -412,6 +412,11 @@ PMList *alpm_db_getgrpcache(pmdb_t *db) * @{ */ +/** Get informations about a package. + * @param pkg package pointer + * @param parm name of the info to get + * @return a void* on success (the value), NULL on error + */ void *alpm_pkg_getinfo(pmpkg_t *pkg, unsigned char parm) { void *data = NULL; @@ -507,6 +512,11 @@ void *alpm_pkg_getinfo(pmpkg_t *pkg, unsigned char parm) return(data); } +/** Create a package from a file. + * @param filename location of the package tarball + * @param pkg address of the package pointer + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_pkg_load(char *filename, pmpkg_t **pkg) { /* Sanity checks */ @@ -522,6 +532,10 @@ int alpm_pkg_load(char *filename, pmpkg_t **pkg) return(0); } +/** Free a package. + * @param pkg package pointer to free + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_pkg_free(pmpkg_t *pkg) { ASSERT(pkg != NULL, RET_ERR(PM_ERR_WRONG_ARGS, -1)); @@ -532,6 +546,12 @@ int alpm_pkg_free(pmpkg_t *pkg) return(0); } +/** Compare versions. + * @param ver1 first version + * @param ver2 secont version + * @return postive, 0 or negative if ver1 is less, equal or more + * than ver2, respectively. + */ int alpm_pkg_vercmp(const char *ver1, const char *ver2) { return(versioncmp(ver1, ver2)); @@ -542,6 +562,11 @@ int alpm_pkg_vercmp(const char *ver1, const char *ver2) * @{ */ +/** Get informations about a group. + * @param grp group pointer + * @param parm name of the info to get + * @return a void* on success (the value), NULL on error + */ void *alpm_grp_getinfo(pmgrp_t *grp, unsigned char parm) { void *data = NULL; @@ -565,6 +590,11 @@ void *alpm_grp_getinfo(pmgrp_t *grp, unsigned char parm) * @{ */ +/** Get informations about a sync. + * @param sync package pointer + * @param parm name of the info to get + * @return a void* on success (the value), NULL on error + */ void *alpm_sync_getinfo(pmsyncpkg_t *sync, unsigned char parm) { void *data; @@ -589,6 +619,10 @@ void *alpm_sync_getinfo(pmsyncpkg_t *sync, unsigned char parm) * @{ */ +/** Get informations about the transaction. + * @param parm name of the info to get + * @return a void* on success (the value), NULL on error + */ void *alpm_trans_getinfo(unsigned char parm) { pmtrans_t *trans; @@ -613,6 +647,13 @@ void *alpm_trans_getinfo(unsigned char parm) return(data); } +/** Initialize the transaction. + * @param type type of the transaction + * @param flags flags of the transaction (like nodeps, etc) + * @param event event callback function pointer + * @param conv conversation callback function pointer + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_trans_init(unsigned char type, unsigned char flags, alpm_trans_cb_event event, alpm_trans_cb_conv conv) { /* Sanity checks */ @@ -621,7 +662,7 @@ int alpm_trans_init(unsigned char type, unsigned char flags, alpm_trans_cb_event /* ORE * perform sanity checks on type and flags: - * for instance, we can't set UPGRADE and FRESHEN at the same time */ + * for instance, we can't set UPGRADE and FRESHEN at the same time */ handle->trans = trans_new(); if(handle->trans == NULL) { @@ -631,6 +672,9 @@ int alpm_trans_init(unsigned char type, unsigned char flags, alpm_trans_cb_event return(trans_init(handle->trans, type, flags, event, conv)); } +/** Search for packages to upgrade and add them to the transaction. + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_trans_sysupgrade() { pmtrans_t *trans; @@ -645,6 +689,10 @@ int alpm_trans_sysupgrade() return(trans_sysupgrade(trans)); } +/** Add a target to the transaction. + * @param target the name of the target to add + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_trans_addtarget(char *target) { pmtrans_t *trans; @@ -660,6 +708,11 @@ int alpm_trans_addtarget(char *target) return(trans_addtarget(trans, target)); } +/** Prepare a transaction. + * @param data the address of a PM_LIST where detailed description + * of an error can be dumped (ie. list of conflicting files) + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_trans_prepare(PMList **data) { pmtrans_t *trans; @@ -674,6 +727,11 @@ int alpm_trans_prepare(PMList **data) return(trans_prepare(handle->trans, data)); } +/** Commit a transaction. + * @param data the address of a PM_LIST where detailed description + * of an error can be dumped (ie. list of conflicting files) + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_trans_commit(PMList **data) { pmtrans_t *trans; @@ -691,6 +749,9 @@ int alpm_trans_commit(PMList **data) return(trans_commit(handle->trans, data)); } +/** Release a transaction. + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_trans_release() { pmtrans_t *trans; -- cgit v1.2.3-24-g4f1b