--- lib/libalpm/alpm.h | 439 ++++++++++++++++++++++++++++----------------- 1 file changed, 271 insertions(+), 168 deletions(-) diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h index ea99a8b3..a8d48432 100644 --- a/lib/libalpm/alpm.h +++ b/lib/libalpm/alpm.h @@ -617,105 +617,12 @@ void alpm_conflict_free(alpm_conflict_t *conflict); /* End of alpm_depends */ /** @} */ -/* - * Enumerations - * These ones are used in multiple contexts, so are forward-declared. - */ - -/** Package install reasons. */ -typedef enum _alpm_pkgreason_t { - /** Explicitly requested by the user. */ - ALPM_PKG_REASON_EXPLICIT = 0, - /** Installed as a dependency for another package. */ - ALPM_PKG_REASON_DEPEND = 1 -} alpm_pkgreason_t; - -/** Location a package object was loaded from. */ -typedef enum _alpm_pkgfrom_t { - ALPM_PKG_FROM_FILE = 1, - ALPM_PKG_FROM_LOCALDB, - ALPM_PKG_FROM_SYNCDB -} alpm_pkgfrom_t; - -/** Method used to validate a package. */ -typedef enum _alpm_pkgvalidation_t { - ALPM_PKG_VALIDATION_UNKNOWN = 0, - ALPM_PKG_VALIDATION_NONE = (1 << 0), - ALPM_PKG_VALIDATION_MD5SUM = (1 << 1), - ALPM_PKG_VALIDATION_SHA256SUM = (1 << 2), - ALPM_PKG_VALIDATION_SIGNATURE = (1 << 3) -} alpm_pkgvalidation_t; - -/* - * Structures - */ - -/** Package group */ -typedef struct _alpm_group_t { - /** group name */ - char *name; - /** list of alpm_pkg_t packages */ - alpm_list_t *packages; -} alpm_group_t; -/** File in a package */ -typedef struct _alpm_file_t { - char *name; - off_t size; - mode_t mode; -} alpm_file_t; - -/** Package filelist container */ -typedef struct _alpm_filelist_t { - size_t count; - alpm_file_t *files; -} alpm_filelist_t; - -/** Local package or package file backup entry */ -typedef struct _alpm_backup_t { - char *name; - char *hash; -} alpm_backup_t; - -/* - * Hooks - */ - -typedef enum _alpm_hook_when_t { - ALPM_HOOK_PRE_TRANSACTION = 1, - ALPM_HOOK_POST_TRANSACTION -} alpm_hook_when_t; - -/* - * Logging facilities - */ - -/** \addtogroup alpm_log Logging Functions - * @brief Functions to log using libalpm +/** \addtogroup alpm_cb Callbacks + * @brief Functions and structures for libalpm's callbacks * @{ */ -/** Logging Levels */ -typedef enum _alpm_loglevel_t { - ALPM_LOG_ERROR = 1, - ALPM_LOG_WARNING = (1 << 1), - ALPM_LOG_DEBUG = (1 << 2), - ALPM_LOG_FUNCTION = (1 << 3) -} alpm_loglevel_t; - -typedef void (*alpm_cb_log)(alpm_loglevel_t, const char *, va_list); - -/** A printf-like function for logging. - * @param handle the context handle - * @param prefix caller-specific prefix for the log - * @param fmt output format - * @return 0 on success, -1 on error (pm_errno is set accordingly) - */ -int alpm_logaction(alpm_handle_t *handle, const char *prefix, - const char *fmt, ...) __attribute__((format(printf, 3, 4))); - -/** @} */ - /** * Type of events. */ @@ -790,7 +697,7 @@ typedef enum _alpm_event_type_t { /** A .pacnew file was created; See alpm_event_pacnew_created_t for arguments. */ ALPM_EVENT_PACNEW_CREATED, /** A .pacsave file was created; See alpm_event_pacsave_created_t for - * arguments */ + * arguments. */ ALPM_EVENT_PACSAVE_CREATED, /** Processing hooks will be started. */ ALPM_EVENT_HOOK_START, @@ -798,100 +705,123 @@ typedef enum _alpm_event_type_t { ALPM_EVENT_HOOK_DONE, /** A hook is starting */ ALPM_EVENT_HOOK_RUN_START, - /** A hook has finished running */ + /** A hook has finished running. */ ALPM_EVENT_HOOK_RUN_DONE } alpm_event_type_t; +/** An event that may reprisent any event. */ typedef struct _alpm_event_any_t { - /** Type of event. */ + /** Type of event */ alpm_event_type_t type; } alpm_event_any_t; +/** An enum over the kind of package operations. */ typedef enum _alpm_package_operation_t { /** Package (to be) installed. (No oldpkg) */ ALPM_PACKAGE_INSTALL = 1, /** Package (to be) upgraded */ ALPM_PACKAGE_UPGRADE, - /** Package (to be) re-installed. */ + /** Package (to be) re-installed */ ALPM_PACKAGE_REINSTALL, - /** Package (to be) downgraded. */ + /** Package (to be) downgraded */ ALPM_PACKAGE_DOWNGRADE, - /** Package (to be) removed. (No newpkg) */ + /** Package (to be) removed (No newpkg) */ ALPM_PACKAGE_REMOVE } alpm_package_operation_t; +/** A package operation event occurred. */ typedef struct _alpm_event_package_operation_t { - /** Type of event. */ + /** Type of event */ alpm_event_type_t type; - /** Type of operation. */ + /** Type of operation */ alpm_package_operation_t operation; - /** Old package. */ + /** Old package */ alpm_pkg_t *oldpkg; - /** New package. */ + /** New package */ alpm_pkg_t *newpkg; } alpm_event_package_operation_t; +/** An optional dependency was removed. */ typedef struct _alpm_event_optdep_removal_t { - /** Type of event. */ + /** Type of event */ alpm_event_type_t type; - /** Package with the optdep. */ + /** Package with the optdep */ alpm_pkg_t *pkg; - /** Optdep being removed. */ + /** Optdep being removed */ alpm_depend_t *optdep; } alpm_event_optdep_removal_t; +/** A scriptlet was ran. */ typedef struct _alpm_event_scriptlet_info_t { - /** Type of event. */ + /** Type of event */ alpm_event_type_t type; - /** Line of scriptlet output. */ + /** Line of scriptlet output */ const char *line; } alpm_event_scriptlet_info_t; + +/** A database is missing. + * + * The database is registered but has not been downloaded + */ typedef struct _alpm_event_database_missing_t { - /** Type of event. */ + /** Type of event */ alpm_event_type_t type; - /** Name of the database. */ + /** Name of the database */ const char *dbname; } alpm_event_database_missing_t; +/** A package was downloaded. */ typedef struct _alpm_event_pkgdownload_t { - /** Type of event. */ + /** Type of event */ alpm_event_type_t type; /** Name of the file */ const char *file; } alpm_event_pkgdownload_t; +/** A pacnew file was created. */ typedef struct _alpm_event_pacnew_created_t { - /** Type of event. */ + /** Type of event */ alpm_event_type_t type; /** Whether the creation was result of a NoUpgrade or not */ int from_noupgrade; - /** Old package. */ + /** Old package */ alpm_pkg_t *oldpkg; - /** New Package. */ + /** New Package */ alpm_pkg_t *newpkg; /** Filename of the file without the .pacnew suffix */ const char *file; } alpm_event_pacnew_created_t; +/** A pacsave file was created. */ typedef struct _alpm_event_pacsave_created_t { - /** Type of event. */ + /** Type of event */ alpm_event_type_t type; - /** Old package. */ + /** Old package */ alpm_pkg_t *oldpkg; - /** Filename of the file without the .pacsave suffix. */ + /** Filename of the file without the .pacsave suffix */ const char *file; } alpm_event_pacsave_created_t; +/** Kind of hook. */ +typedef enum _alpm_hook_when_t { + /* Pre transaction hook */ + ALPM_HOOK_PRE_TRANSACTION = 1, + /* Post transaction hook */ + ALPM_HOOK_POST_TRANSACTION +} alpm_hook_when_t; + +/** pre/post transaction hooks are to be ran. */ typedef struct _alpm_event_hook_t { - /** Type of event.*/ + /** Type of event*/ alpm_event_type_t type; - /** Type of hooks. */ + /** Type of hook */ alpm_hook_when_t when; } alpm_event_hook_t; +/** A pre/post transaction hook was ran. */ typedef struct _alpm_event_hook_run_t { - /** Type of event.*/ + /** Type of event */ alpm_event_type_t type; /** Name of hook */ const char *name; @@ -904,185 +834,260 @@ typedef struct _alpm_event_hook_run_t { } alpm_event_hook_run_t; /** Events. - * This is an union passed to the callback, that allows the frontend to know + * This is a union passed to the callback that allows the frontend to know * which type of event was triggered (via type). It is then possible to * typecast the pointer to the right structure, or use the union field, in order * to access event-specific data. */ typedef union _alpm_event_t { + /** Type of event it's always safe to access this. */ alpm_event_type_t type; + /** The any event type. It's always safe to access this. */ alpm_event_any_t any; + /** Package operation */ alpm_event_package_operation_t package_operation; + /** An optdept was remove */ alpm_event_optdep_removal_t optdep_removal; + /** A scriptlet was ran */ alpm_event_scriptlet_info_t scriptlet_info; + /** A database is missing */ alpm_event_database_missing_t database_missing; + /** A package was downloaded */ alpm_event_pkgdownload_t pkgdownload; + /** A pacnew file was created */ alpm_event_pacnew_created_t pacnew_created; + /** A pacsave file was created */ alpm_event_pacsave_created_t pacsave_created; + /** Pre/post transaction hooks are being ran */ alpm_event_hook_t hook; + /** A hook was ran */ alpm_event_hook_run_t hook_run; } alpm_event_t; -/** Event callback. */ +/** Event callback. + * + * Called when an event occurs + * @param event the event that occurred */ typedef void (*alpm_cb_event)(alpm_event_t *); /** - * Type of questions. + * Type of question. * Unlike the events or progress enumerations, this enum has bitmask values * so a frontend can use a bitmask map to supply preselected answers to the * different types of questions. */ typedef enum _alpm_question_type_t { + /** Should target in ignorepkg be installed anyway? */ ALPM_QUESTION_INSTALL_IGNOREPKG = (1 << 0), + /** Should a package be replaced? */ ALPM_QUESTION_REPLACE_PKG = (1 << 1), + /** Should a conflicting package be removed? */ ALPM_QUESTION_CONFLICT_PKG = (1 << 2), + /** Should a corrupted package be deleted? */ ALPM_QUESTION_CORRUPTED_PKG = (1 << 3), + /** Should unresolvable targets be removed from the transaction? */ ALPM_QUESTION_REMOVE_PKGS = (1 << 4), + /** Provider selection */ ALPM_QUESTION_SELECT_PROVIDER = (1 << 5), + /** Should a key be imported? */ ALPM_QUESTION_IMPORT_KEY = (1 << 6) } alpm_question_type_t; +/** A question that can represent any other question. */ typedef struct _alpm_question_any_t { - /** Type of question. */ + /** Type of question */ alpm_question_type_t type; - /** Answer. */ + /** Answer */ int answer; } alpm_question_any_t; +/** Should target in ignorepkg be installed anyway? */ typedef struct _alpm_question_install_ignorepkg_t { - /** Type of question. */ + /** Type of question */ alpm_question_type_t type; - /** Answer: whether or not to install pkg anyway. */ + /** Answer: whether or not to install pkg anyway */ int install; - /* Package in IgnorePkg/IgnoreGroup. */ + /** The ignored package that we are deciding whether to install */ alpm_pkg_t *pkg; } alpm_question_install_ignorepkg_t; +/** Should a package be replaced? */ typedef struct _alpm_question_replace_t { - /** Type of question. */ + /** Type of question */ alpm_question_type_t type; - /** Answer: whether or not to replace oldpkg with newpkg. */ + /** Answer: whether or not to replace oldpkg with newpkg */ int replace; - /* Package to be replaced. */ + /** Package to be replaced */ alpm_pkg_t *oldpkg; - /* Package to replace with. */ + /** Package to replace with.*/ alpm_pkg_t *newpkg; - /* DB of newpkg */ + /** DB of newpkg */ alpm_db_t *newdb; } alpm_question_replace_t; +/** Should a conflicting package be removed? */ typedef struct _alpm_question_conflict_t { - /** Type of question. */ + /** Type of question */ alpm_question_type_t type; - /** Answer: whether or not to remove conflict->package2. */ + /** Answer: whether or not to remove conflict->package2 */ int remove; - /** Conflict info. */ + /** Conflict info */ alpm_conflict_t *conflict; } alpm_question_conflict_t; +/** Should a corrupted package be deleted? */ typedef struct _alpm_question_corrupted_t { - /** Type of question. */ + /** Type of question */ alpm_question_type_t type; - /** Answer: whether or not to remove filepath. */ + /** Answer: whether or not to remove filepath */ int remove; - /** Filename to remove */ + /** File to remove */ const char *filepath; /** Error code indicating the reason for package invalidity */ alpm_errno_t reason; } alpm_question_corrupted_t; +/** Should unresolvable targets be removed from the transaction? */ typedef struct _alpm_question_remove_pkgs_t { - /** Type of question. */ + /** Type of question */ alpm_question_type_t type; - /** Answer: whether or not to skip packages. */ + /** Answer: whether or not to skip packages */ int skip; - /** List of alpm_pkg_t* with unresolved dependencies. */ + /** List of alpm_pkg_t* with unresolved dependencies */ alpm_list_t *packages; } alpm_question_remove_pkgs_t; +/** Provider selection */ typedef struct _alpm_question_select_provider_t { - /** Type of question. */ + /** Type of question */ alpm_question_type_t type; - /** Answer: which provider to use (index from providers). */ + /** Answer: which provider to use (index from providers) */ int use_index; - /** List of alpm_pkg_t* as possible providers. */ + /** List of alpm_pkg_t* as possible providers */ alpm_list_t *providers; - /** What providers provide for. */ + /** What providers provide for */ alpm_depend_t *depend; } alpm_question_select_provider_t; +/** Should a key be imported? */ typedef struct _alpm_question_import_key_t { - /** Type of question. */ + /** Type of question */ alpm_question_type_t type; - /** Answer: whether or not to import key. */ + /** Answer: whether or not to import key */ int import; - /** The key to import. */ + /** The key to import */ alpm_pgpkey_t *key; } alpm_question_import_key_t; /** * Questions. - * This is an union passed to the callback, that allows the frontend to know + * This is an union passed to the callback that allows the frontend to know * which type of question was triggered (via type). It is then possible to * typecast the pointer to the right structure, or use the union field, in order * to access question-specific data. */ typedef union _alpm_question_t { + /** The type of question. It's always safe to access this. */ alpm_question_type_t type; + /** A question that can represent any question. + * It's always safe to access this. */ alpm_question_any_t any; + /** Should target in ignorepkg be installed anyway? */ alpm_question_install_ignorepkg_t install_ignorepkg; + /** Should a package be replaced? */ alpm_question_replace_t replace; + /** Should a conflicting package be removed? */ alpm_question_conflict_t conflict; + /** Should a corrupted package be deleted? */ alpm_question_corrupted_t corrupted; + /** Should unresolvable targets be removed from the transaction? */ alpm_question_remove_pkgs_t remove_pkgs; + /** Provider selection */ alpm_question_select_provider_t select_provider; + /** Should a key be imported? */ alpm_question_import_key_t import_key; } alpm_question_t; -/** Question callback */ +/** Question callback. + * + * This callback allows user to give input and decide what to do during certain events + * @param question the question being asked. + */ typedef void (*alpm_cb_question)(alpm_question_t *); -/** Progress */ +/** An enum over different kinds of progress alerts. */ typedef enum _alpm_progress_t { + /** Package install */ ALPM_PROGRESS_ADD_START, + /** Package upgrade */ ALPM_PROGRESS_UPGRADE_START, + /** Package downgrade */ ALPM_PROGRESS_DOWNGRADE_START, + /** Package reinstall */ ALPM_PROGRESS_REINSTALL_START, + /** Package removal */ ALPM_PROGRESS_REMOVE_START, + /** Conflict checking */ ALPM_PROGRESS_CONFLICTS_START, + /** Diskspace checking */ ALPM_PROGRESS_DISKSPACE_START, + /** Package Integrity checking */ ALPM_PROGRESS_INTEGRITY_START, + /** Loading packages from disk */ ALPM_PROGRESS_LOAD_START, + /** Checking signatures of packages */ ALPM_PROGRESS_KEYRING_START } alpm_progress_t; +/** Progress callback + * + * Alert the front end about the progress of certain events. + * Allows the implementation of loading bars for events that + * make take a while to complete. + * @param progress the kind of event that is progressing + * @param pkg for package operations, the name of the package being operated on + * @param percent the percent completion of the action + * @param howmany the total amount of items in the action + * @param current the current amount of items completed + */ /** Progress callback */ -typedef void (*alpm_cb_progress)(alpm_progress_t, const char *, int, size_t, size_t); +typedef void (*alpm_cb_progress)(alpm_progress_t progress, const char *pkg, + int percent, size_t howmany, size_t current); /* * Downloading */ -/* File download events. +/** File download events. * These events are reported by ALPM via download callback. */ -typedef enum { - ALPM_DOWNLOAD_INIT, /* alpm initializes file download logic */ - ALPM_DOWNLOAD_PROGRESS, /* download progress reported */ - ALPM_DOWNLOAD_COMPLETED /* alpm is about to release data related to the file */ +typedef enum _alpm_download_event_type_t { + /** A download was started */ + ALPM_DOWNLOAD_INIT, + /** A download made progress */ + ALPM_DOWNLOAD_PROGRESS, + /** A download completed */ + ALPM_DOWNLOAD_COMPLETED } alpm_download_event_type_t; -typedef struct { - int optional; /* whether this file is optional and thus the errors could be ignored */ +/** Context struct for when a download starts. */ +typedef struct _alpm_download_event_init_t { + /** whether this file is optional and thus the errors could be ignored */ + int optional; } alpm_download_event_init_t; -typedef struct { - off_t downloaded; /* amount of data downloaded */ - off_t total; /* total amount need to be downloaded */ +/** Context struct for when a download progresses. */ +typedef struct _alpm_download_event_progress_t { + /** Amount of data downloaded */ + off_t downloaded; + /** Total amount need to be downloaded */ + off_t total; } alpm_download_event_progress_t; -typedef struct { - /* total bytes in file */ + +/** Context struct for when a download completes. */ +typedef struct _alpm_download_event_completed_t { + /** Total bytes in file */ off_t total; - /* download result code: + /** download result code: * 0 - download completed successfully * 1 - the file is up-to-date * -1 - error @@ -1098,6 +1103,10 @@ typedef struct { typedef void (*alpm_cb_download)(const char *filename, alpm_download_event_type_t event, void *data); + +/** Total Download callback. + * @param total amount that will be downloaded during \link alpm_trans_commit \endlink. + */ typedef void (*alpm_cb_totaldl)(off_t total); /** A callback for downloading files @@ -1110,6 +1119,100 @@ typedef void (*alpm_cb_totaldl)(off_t total); typedef int (*alpm_cb_fetch)(const char *url, const char *localpath, int force); +/* End of alpm_cb */ +/** @} */ + + +/* + * Enumerations + * These ones are used in multiple contexts, so are forward-declared. + */ + +/** Package install reasons. */ +typedef enum _alpm_pkgreason_t { + /** Explicitly requested by the user. */ + ALPM_PKG_REASON_EXPLICIT = 0, + /** Installed as a dependency for another package. */ + ALPM_PKG_REASON_DEPEND = 1 +} alpm_pkgreason_t; + +/** Location a package object was loaded from. */ +typedef enum _alpm_pkgfrom_t { + ALPM_PKG_FROM_FILE = 1, + ALPM_PKG_FROM_LOCALDB, + ALPM_PKG_FROM_SYNCDB +} alpm_pkgfrom_t; + +/** Method used to validate a package. */ +typedef enum _alpm_pkgvalidation_t { + ALPM_PKG_VALIDATION_UNKNOWN = 0, + ALPM_PKG_VALIDATION_NONE = (1 << 0), + ALPM_PKG_VALIDATION_MD5SUM = (1 << 1), + ALPM_PKG_VALIDATION_SHA256SUM = (1 << 2), + ALPM_PKG_VALIDATION_SIGNATURE = (1 << 3) +} alpm_pkgvalidation_t; + +/* + * Structures + */ + +/** Package group */ +typedef struct _alpm_group_t { + /** group name */ + char *name; + /** list of alpm_pkg_t packages */ + alpm_list_t *packages; +} alpm_group_t; + +/** File in a package */ +typedef struct _alpm_file_t { + char *name; + off_t size; + mode_t mode; +} alpm_file_t; + +/** Package filelist container */ +typedef struct _alpm_filelist_t { + size_t count; + alpm_file_t *files; +} alpm_filelist_t; + +/** Local package or package file backup entry */ +typedef struct _alpm_backup_t { + char *name; + char *hash; +} alpm_backup_t; + +/* + * Logging facilities + */ + +/** \addtogroup alpm_log Logging Functions + * @brief Functions to log using libalpm + * @{ + */ + +/** Logging Levels */ +typedef enum _alpm_loglevel_t { + ALPM_LOG_ERROR = 1, + ALPM_LOG_WARNING = (1 << 1), + ALPM_LOG_DEBUG = (1 << 2), + ALPM_LOG_FUNCTION = (1 << 3) +} alpm_loglevel_t; + +typedef void (*alpm_cb_log)(alpm_loglevel_t, const char *, va_list); + +/** A printf-like function for logging. + * @param handle the context handle + * @param prefix caller-specific prefix for the log + * @param fmt output format + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ +int alpm_logaction(alpm_handle_t *handle, const char *prefix, + const char *fmt, ...) __attribute__((format(printf, 3, 4))); + +/** @} */ + /** Fetch a list of remote packages. * @param handle the context handle * @param urls list of package URLs to download -- 2.29.2