From aac9e7c280a9686520e0f8f4bd7ffe4ed901716d Mon Sep 17 00:00:00 2001 From: Rémy Oudompheng Date: Sun, 6 Mar 2011 17:50:01 +0100 Subject: Move documentation of public transaction functions to alpm.h --- lib/libalpm/alpm.h | 65 ++++++++++++++++++++++++++++++++++++++++------------- lib/libalpm/trans.c | 28 +++++------------------ 2 files changed, 54 insertions(+), 39 deletions(-) diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h index 0f3b7166..b1f9542a 100644 --- a/lib/libalpm/alpm.h +++ b/lib/libalpm/alpm.h @@ -263,12 +263,13 @@ alpm_list_t *alpm_find_grp_pkgs(alpm_list_t *dbs, const char *name); pmpkg_t *alpm_sync_newversion(pmpkg_t *pkg, alpm_list_t *dbs_sync); -/* - * Transactions +/** + * @addtogroup alpm_api_trans Transaction Functions + * Functions to manipulate libalpm transactions + * @{ */ - -/* Flags */ +/** Transaction flags */ typedef enum _pmtransflag_t { PM_TRANS_FLAG_NODEPS = 1, PM_TRANS_FLAG_FORCE = (1 << 1), @@ -290,12 +291,7 @@ typedef enum _pmtransflag_t { PM_TRANS_FLAG_NOLOCK = (1 << 17) } pmtransflag_t; -/** - * @addtogroup alpm_trans - * @{ - */ -/** - * @brief Transaction events. +/** Transaction events. * NULL parameters are passed to in all events unless specified otherwise. */ typedef enum _pmtransevt_t { @@ -374,9 +370,8 @@ typedef enum _pmtransevt_t { /** Disk space usage was computed for a package */ PM_TRANS_EVT_DISKSPACE_DONE, } pmtransevt_t; -/*@}*/ -/* Transaction Conversations (ie, questions) */ +/** Transaction Conversations (ie, questions) */ typedef enum _pmtransconv_t { PM_TRANS_CONV_INSTALL_IGNOREPKG = 1, PM_TRANS_CONV_REPLACE_PKG = (1 << 1), @@ -387,7 +382,7 @@ typedef enum _pmtransconv_t { PM_TRANS_CONV_SELECT_PROVIDER = (1 << 6), } pmtransconv_t; -/* Transaction Progress */ +/** Transaction Progress */ typedef enum _pmtransprog_t { PM_TRANS_PROGRESS_ADD_START, PM_TRANS_PROGRESS_UPGRADE_START, @@ -397,27 +392,65 @@ typedef enum _pmtransprog_t { PM_TRANS_PROGRESS_INTEGRITY_START, } pmtransprog_t; -/* Transaction Event callback */ +/** Transaction Event callback */ typedef void (*alpm_trans_cb_event)(pmtransevt_t, void *, void *); -/* Transaction Conversation callback */ +/** Transaction Conversation callback */ typedef void (*alpm_trans_cb_conv)(pmtransconv_t, void *, void *, void *, int *); -/* Transaction Progress callback */ +/** Transaction Progress callback */ typedef void (*alpm_trans_cb_progress)(pmtransprog_t, const char *, int, size_t, size_t); int alpm_trans_get_flags(void); + +/** Returns a list of packages added by the transaction. + * @return a list of pmpkg_t structures + */ alpm_list_t * alpm_trans_get_add(void); + +/** Returns the list of packages removed by the transaction. + * @return a list of pmpkg_t structures + */ alpm_list_t * alpm_trans_get_remove(void); + +/** Initialize the transaction. + * @param flags flags of the transaction (like nodeps, etc) + * @param event event callback function pointer + * @param conv question callback function pointer + * @param progress progress callback function pointer + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_trans_init(pmtransflag_t flags, alpm_trans_cb_event cb_event, alpm_trans_cb_conv conv, alpm_trans_cb_progress cb_progress); + +/** Prepare a transaction. + * @param data the address of an alpm_list where a list + * of pmdepmissing_t objects is dumped (conflicting packages) + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_trans_prepare(alpm_list_t **data); + +/** Commit a transaction. + * @param data the address of an alpm_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(alpm_list_t **data); + +/** Interrupt a transaction. + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_trans_interrupt(void); + +/** Release a transaction. + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_trans_release(void); +/** @} */ + int alpm_sync_sysupgrade(int enable_downgrade); int alpm_add_pkg(pmpkg_t *pkg); int alpm_remove_pkg(pmpkg_t *pkg); diff --git a/lib/libalpm/trans.c b/lib/libalpm/trans.c index 309a56a3..c5af7c69 100644 --- a/lib/libalpm/trans.c +++ b/lib/libalpm/trans.c @@ -97,13 +97,7 @@ static int remove_lock(pmhandle_t *handle) return(0); } -/** Initialize the transaction. - * @param flags flags of the transaction (like nodeps, etc) - * @param event event callback function pointer - * @param conv question callback function pointer - * @param progress progress callback function pointer - * @return 0 on success, -1 on error (pm_errno is set accordingly) - */ +/** Initialize the transaction. */ int SYMEXPORT alpm_trans_init(pmtransflag_t flags, alpm_trans_cb_event event, alpm_trans_cb_conv conv, alpm_trans_cb_progress progress) @@ -176,11 +170,7 @@ static alpm_list_t *check_arch(alpm_list_t *pkgs) return(invalid); } -/** Prepare a transaction. - * @param data the address of an alpm_list where a list - * of pmdepmissing_t objects is dumped (conflicting packages) - * @return 0 on success, -1 on error (pm_errno is set accordingly) - */ +/** Prepare a transaction. */ int SYMEXPORT alpm_trans_prepare(alpm_list_t **data) { pmtrans_t *trans; @@ -226,11 +216,7 @@ int SYMEXPORT alpm_trans_prepare(alpm_list_t **data) return(0); } -/** Commit a transaction. - * @param data the address of an alpm_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) - */ +/** Commit a transaction. */ int SYMEXPORT alpm_trans_commit(alpm_list_t **data) { pmtrans_t *trans; @@ -271,9 +257,7 @@ int SYMEXPORT alpm_trans_commit(alpm_list_t **data) return(0); } -/** Interrupt a transaction. - * @return 0 on success, -1 on error (pm_errno is set accordingly) - */ +/** Interrupt a transaction. */ int SYMEXPORT alpm_trans_interrupt(void) { pmtrans_t *trans; @@ -293,9 +277,7 @@ int SYMEXPORT alpm_trans_interrupt(void) return(0); } -/** Release a transaction. - * @return 0 on success, -1 on error (pm_errno is set accordingly) - */ +/** Release a transaction. */ int SYMEXPORT alpm_trans_release(void) { pmtrans_t *trans; -- cgit v1.2.3-70-g09d2