From 0cc4ba224e49ab93b3f93c3049de6aa692c31143 Mon Sep 17 00:00:00 2001 From: Juan RP Date: Sat, 22 Jan 2011 14:24:51 +0100 Subject: [PATCH] Update API documentation for recent changes. --HG-- branch : progress_callback --- include/xbps_api.h | 126 ++++++++++++++++++++++++++------------------- lib/download.c | 4 +- lib/fexec.c | 10 ---- lib/initend.c | 8 +++ 4 files changed, 82 insertions(+), 66 deletions(-) diff --git a/include/xbps_api.h b/include/xbps_api.h index cc344605..2a02cd15 100644 --- a/include/xbps_api.h +++ b/include/xbps_api.h @@ -196,54 +196,66 @@ int xbps_cmpver(const char *pkg1, const char *pkg2); /** @addtogroup download */ /*@{*/ +/** + * @struct xbps_fetch_progress_data xbps_api.h "xbps_api.h" + * @brief Structure to be passed to the fetch progress function callback. + * + * This structure is passed as argument to the fetch progress function + * callback and its members will be updated when there's any progress. + * All members marked as read-only in this struct are set internally by + * xbps_unpack_binary_pkg() and shouldn't be modified in the passed + * function callback. + */ struct xbps_fetch_progress_data { - /* - * @var[out] file_size + /** + * @var file_size * - * Filename size for the file to be fetched (set internally). + * Filename size for the file to be fetched (set internally, + * read only). */ off_t file_size; - /* - * @var[out] file_offset + /** + * @var file_offset * - * Current offset for the filename being fetched (set internally). + * Current offset for the filename being fetched (set internally, + * read only). */ off_t file_offset; - /* - * @var[out] file_dloaded; + /** + * @var file_dloaded * * Bytes downloaded for the file being fetched (set internally). */ off_t file_dloaded; - /* - * @var[out] file_name; + /** + * @var file_name * - * File name being fetched (set internally). + * File name being fetched (set internally, read only). */ const char *file_name; - /* - * @var[out] cb_start + /** + * @var cb_start * * If true the function callback should be prepared to start - * the transfer progress (set internally). + * the transfer progress (set internally, read only). */ bool cb_start; - /* - * var[out] cb_update + /** + * var cb_update * * If true the function callback should be prepared to - * update the transfer progress (set internally). + * update the transfer progress (set internally, read only). */ bool cb_update; - /* - * var[out] cb_end + /** + * var cb_end * * If true the function callback should be prepated to - * end the transfer progress (set internally). + * end the transfer progress (set internally, read only). */ bool cb_end; - /* - * @var[in] cookie + /** + * @var cookie * * Pointer to private user data. */ @@ -284,18 +296,6 @@ const char *xbps_fetch_error_string(void); int xbps_humanize_number(char *, int64_t); -/** - * @ingroup dircreate - * - * Creates a directory (and required components if necessary). - * - * @param[in] path Path for final directory. - * @param[in] mode Mode for final directory (0755 if not specified). - * - * @return 0 on success, -1 on error and errno set appropiately. - */ -int xbps_mkpath(char *path, mode_t mode); - /** * @ingroup pkg_orphans * @@ -929,46 +929,54 @@ int xbps_set_pkg_state_dictionary(prop_dictionary_t dict, pkg_state_t state); /*@}*/ /** @addtogroup unpack */ +/*@{*/ /** * @struct xbps_unpack_progress_data xbps_api.h "xbps_api.h" * @brief Structure to be passed to the unpacking progress function callback. + * + * This structure is passed as argument to the unpack progress function + * callback and its members will be updated when there's any progress. + * All members in this struct are set internally by xbps_unpack_binary_pkg() + * and should be used in read-only mode in the function callback. */ struct xbps_unpack_progress_data { - /* + /** * @var entry * - * Entry pathname string (set internally). + * Entry pathname string (set internally, read only). */ const char *entry; - /* - * @var[out] entry_size + /** + * @var entry_size * - * Entry file size (set internally). + * Entry file size (set internally, read only). */ int64_t entry_size; - /* - * @var[out] entry_extract_count; + /** + * @var entry_extract_count * - * Total number of extracted entries (set internally). + * Total number of extracted entries (set internally, read only). */ ssize_t entry_extract_count; - /* - * @var[out] entry_total_count + /** + * @var entry_total_count * - * Total number of entries in package (set internally). + * Total number of entries in package (set internally, read only). */ ssize_t entry_total_count; - /* - * @var[out] entry_is_metadata + /** + * @var entry_is_metadata * - * If true "entry" is a package metadata file (set internally). + * If true "entry" is a package metadata file (set internally, + * read only). */ bool entry_is_metadata; - /* - * @var[out] entry_is_conf + /** + * @var entry_is_conf * - * If true "entry" is a configuration file (set internally). + * If true "entry" is a configuration file (set internally, + * read only). */ bool entry_is_conf; }; @@ -978,15 +986,15 @@ struct xbps_unpack_progress_data { * * @param[in] trans_pkg_dict Package proplib dictionary as stored in the * \a packages array returned by the transaction dictionary. - * @param[in] unpack_progress_cb Pointer to a function callback to update progress data + * @param[in] progress_cb Pointer to a function callback to update progress data * while extracting files in package (optional). * @param[in] xupd Pointer to a struct xbps_unpack_progress_data to be passed to - * the function callback \a unpack_progress_cb. + * the function callback \a progress_cb. * * @return 0 on success, otherwise an errno value. */ int xbps_unpack_binary_pkg(prop_dictionary_t trans_pkg_dict, - void (*unpack_progress_cb)(void *), + void (*progress_cb)(void *), struct xbps_unpack_progress_data *xupd); /*@}*/ @@ -994,6 +1002,16 @@ int xbps_unpack_binary_pkg(prop_dictionary_t trans_pkg_dict, /** @addtogroup util */ /*@{*/ +/** + * Creates a directory (and required components if necessary). + * + * @param[in] path Path for final directory. + * @param[in] mode Mode for final directory (0755 if not specified). + * + * @return 0 on success, -1 on error and errno set appropiately. + */ +int xbps_mkpath(char *path, mode_t mode); + /** * Returns a string by concatenating its variable argument list * as specified by the format string \a fmt. diff --git a/lib/download.c b/lib/download.c index 21496dd9..9098b9af 100644 --- a/lib/download.c +++ b/lib/download.c @@ -47,9 +47,9 @@ /** * @file lib/download.c * @brief Download routines - * @defgroup download Internal download functions + * @defgroup download Download functions * - * These functions allow you to download files. + * XBPS download related functions, frontend for NetBSD's libfetch. */ static const char * print_time(time_t *t) diff --git a/lib/fexec.c b/lib/fexec.c index 1680fdfc..bfb11bf7 100644 --- a/lib/fexec.c +++ b/lib/fexec.c @@ -37,16 +37,6 @@ #include #include "xbps_api_impl.h" -/** - * @file lib/fexec.c - * @brief Generic file execution routines - * @defgroup fexec File execution functions - * - * These functions will fork and execute a program in cwd (current working - * directory), destination directory or changing root directory to - * destination directory and passing an arbitrary number of arguments to it. - */ - static int pfcexec(const char *path, const char *file, const char **argv) { diff --git a/lib/initend.c b/lib/initend.c index 3965bdaa..ff4ae569 100644 --- a/lib/initend.c +++ b/lib/initend.c @@ -32,6 +32,14 @@ #include #include "xbps_api_impl.h" +/** + * @file lib/initend.c + * @brief Initialization and finalization routines + * @defgroup initend Initialization and finalization functions + * + * Use these functions to initialize some parameters before starting + * using libxbps and finalize usage to release resources at the end. + */ static bool with_debug; void