From 3b79e625fedcf8e39e0baeca175f98b3da0eff6e Mon Sep 17 00:00:00 2001 From: Yanbo Zhou Date: Fri, 22 Dec 2017 10:47:30 +0800 Subject: [PATCH] include/conf: add comments for public APIs Change-Id: I099b30d0df1fc45ba3fe1c2a3a4b08dd91354133 Signed-off-by: Yanbo Zhou Reviewed-on: https://review.gerrithub.io/392732 Tested-by: SPDK Automated Test System Reviewed-by: Daniel Verkamp Reviewed-by: Jim Harris --- include/spdk/conf.h | 132 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 131 insertions(+), 1 deletion(-) diff --git a/include/spdk/conf.h b/include/spdk/conf.h index bd7e64ed3..51cbd8d69 100644 --- a/include/spdk/conf.h +++ b/include/spdk/conf.h @@ -50,25 +50,155 @@ struct spdk_conf_item; struct spdk_conf_section; struct spdk_conf; +/** + * Allocate a configuration struct used for the initialization of SPDK app. + * + * \return a pointer to the allocated configuration struct. + */ struct spdk_conf *spdk_conf_allocate(void); + +/** + * Free the configuration struct. + * + * \param cp Configuration struct to free. + */ void spdk_conf_free(struct spdk_conf *cp); + +/** + * Read configuration file for spdk_conf struct. + * + * \param cp Configuration struct used for the initialization of SPDK app. + * \param file File to read that is created by user to configure SPDK app. + * + * \return 0 on success, -1 on failure. + */ int spdk_conf_read(struct spdk_conf *cp, const char *file); + +/** + * Find the specified section of the configuration. + * + * \param cp Configuration struct used for the initialization of SPDK app. + * \param name Name of section to find. + * + * \return a pointer to the requested section on success or NULL otherwise. + */ struct spdk_conf_section *spdk_conf_find_section(struct spdk_conf *cp, const char *name); -/* Configuration file iteration */ +/** + * Get the first section of the configuration. + * + * \param cp Configuration struct used for the initialization of SPDK app. + * + * \return a pointer to the requested section on success or NULL otherwise. + */ struct spdk_conf_section *spdk_conf_first_section(struct spdk_conf *cp); + +/** + * Get the next section of the configuration. + * + * \param sp The current section of the configuration. + * + * \return a pointer to the requested section on success or NULL otherwise. + */ struct spdk_conf_section *spdk_conf_next_section(struct spdk_conf_section *sp); +/** + * Match prefix of the name of section. + * + * \param sp The section of the configuration. + * \param name_prefix Prefix name to match. + * + * \return ture on success, false on failure. + */ bool spdk_conf_section_match_prefix(const struct spdk_conf_section *sp, const char *name_prefix); + +/** + * Get the name of the section. + * + * \param sp The section of the configuration. + * + * \return the name of the section. + */ const char *spdk_conf_section_get_name(const struct spdk_conf_section *sp); + +/** + * Get the number of the section. + * + * \param sp The section of the configuration. + * + * \return the number of the section. + */ int spdk_conf_section_get_num(const struct spdk_conf_section *sp); + +/** + * Get the value of the item with name 'key' in the section. + * + * If key appears multiple times, idx1 will control which version to retrieve. + * Indices will start from the top of the configuration file at 0 and increment + * by one for each new apperarance. If the configuration key contains multiple + * whitespace delimited values, idx2 controls which value is returned. The index + * begins at 0. + * + * + * \param sp The section of the configuration. + * \param key Name of item. + * \param idx1 The index into the item list for the key. + * \param idx2 The index into the value list for the item. + * + * \return the requested value on success or NULL otherwise. + */ char *spdk_conf_section_get_nmval(struct spdk_conf_section *sp, const char *key, int idx1, int idx2); + +/** + * Get the first value of the item with name 'key' in the section. + * + * \param sp The section of the configuration. + * \param key Name of item. + * \param idx The index into the value list for the item. + * + * \return the requested value on success or NULL otherwise. + */ char *spdk_conf_section_get_nval(struct spdk_conf_section *sp, const char *key, int idx); + +/** + * Get the first value of the first item with name 'key' in the section. + * + * \param sp The section of the configuration. + * \param key Name of item. + * + * \return the requested value on success or NULL otherwise. + */ char *spdk_conf_section_get_val(struct spdk_conf_section *sp, const char *key); + +/** + * Get the first value of the first item with name 'key' in the section. + * + * \param sp The section of the configuration. + * \param key Name of item. + * + * \return the requested value on success or NULL otherwise. + */ int spdk_conf_section_get_intval(struct spdk_conf_section *sp, const char *key); + +/** + * Get the bool value of the item with name 'key' in the section. + * + * This is used to check whether the service is enabled. + * + * \param sp The section of the configuration. + * \param key Name of item. + * \param default_val Default value. + * + * \return true if matching 'Yes/Y/True', false if matching 'No/N/False', default value otherwise. + */ bool spdk_conf_section_get_boolval(struct spdk_conf_section *sp, const char *key, bool default_val); +/** + * Set the configuration as the default. + * + * \param cp Configuration to set. + */ void spdk_conf_set_as_default(struct spdk_conf *cp); #ifdef __cplusplus