vlc | branch: master | Rémi Denis-Courmont <[email protected]> | Sun Feb 11 21:32:40 2018 +0200| [a797cb268309d7195547c61e29d881c144c2323e] | committer: Rémi Denis-Courmont
configuration: clean up and doxify documentation > http://git.videolan.org/gitweb.cgi/vlc.git/?a=commit;h=a797cb268309d7195547c61e29d881c144c2323e --- include/vlc_configuration.h | 234 +++++++++++++++++++++++++++++++++++++------- src/config/core.c | 72 -------------- 2 files changed, 197 insertions(+), 109 deletions(-) diff --git a/include/vlc_configuration.h b/include/vlc_configuration.h index 2779e99d17..0a02b05b41 100644 --- a/include/vlc_configuration.h +++ b/include/vlc_configuration.h @@ -27,6 +27,18 @@ #define VLC_CONFIGURATION_H 1 /** + * \defgroup config User settings + * \ingroup interface + * VLC provides a simple name-value dictionary for user settings. + * + * Those settings are per-user per-system - they are shared by all LibVLC + * instances in a single process, and potentially other processes as well. + * + * Each name-value pair is called a configuration item. + * @{ + */ + +/** * \file * This file describes the programming interface for the configuration module. * It includes functions allowing to declare, get or set configuration options. @@ -57,63 +69,209 @@ typedef int (*vlc_string_list_cb)(vlc_object_t *, const char *, typedef int (*vlc_integer_list_cb)(vlc_object_t *, const char *, int64_t **, char ***); +/** + * Configuration item + * + * This is the internal reprensation of a configuration item. + * See also config_FindConfig(). + */ struct module_config_t { - uint8_t i_type; /* Configuration type */ - char i_short; /* Optional short option name */ - unsigned b_advanced:1; /* Advanced option */ - unsigned b_internal:1; /* Hidden from prefs and help */ - unsigned b_unsaveable:1; /* Not stored in configuration */ - unsigned b_safe:1; /* Safe in web plugins and playlists */ - unsigned b_removed:1; /* Deprecated */ - - const char *psz_type; /* Configuration subtype */ - const char *psz_name; /* Option name */ - const char *psz_text; /* Short comment on the configuration option */ - const char *psz_longtext; /* Long comment on the configuration option */ - - module_value_t value; /* Option value */ - module_value_t orig; - module_value_t min; - module_value_t max; + uint8_t i_type; /**< Configuration type */ + char i_short; /**< Optional short option name */ + unsigned b_advanced:1; /**< Advanced option */ + unsigned b_internal:1; /**< Hidden from preferences and help */ + unsigned b_unsaveable:1; /**< Not stored in configuration */ + unsigned b_safe:1; /**< Safe for web plugins and playlist files */ + unsigned b_removed:1; /**< Obsolete */ + + const char *psz_type; /**< Configuration subtype */ + const char *psz_name; /**< Option name */ + const char *psz_text; /**< Short comment on the configuration option */ + const char *psz_longtext; /**< Long comment on the configuration option */ + + module_value_t value; /**< Current value */ + module_value_t orig; /**< Default value */ + module_value_t min; /**< Minimum value (for scalars only) */ + module_value_t max; /**< Maximum value (for scalars only) */ /* Values list */ - uint16_t list_count; /* Options list size */ + uint16_t list_count; /**< Choices count */ union { - const char **psz; /* List of possible values for the option */ - const int *i; - vlc_string_list_cb psz_cb; - vlc_integer_list_cb i_cb; - } list; - const char **list_text; /* Friendly names for list values */ - const char *list_cb_name; - void *owner; + const char **psz; /**< Table of possible string choices */ + const int *i; /**< Table of possible integer choices */ + vlc_string_list_cb psz_cb; /**< Callback to enumerate string choices */ + vlc_integer_list_cb i_cb; /**< Callback to enumerate integer choices */ + } list; /**< Possible choices */ + const char **list_text; /**< Human-readable names for list values */ + const char *list_cb_name; /**< Symbol name of the enumeration callback */ + void *owner; /**< Origin run-time linker module handle */ }; -/***************************************************************************** - * Prototypes - these methods are used to get, set or manipulate configuration - * data. - *****************************************************************************/ -VLC_API int config_GetType(const char *) VLC_USED; +/** + * Gets a configuration item type + * + * This function checks the type of configuration item by name. + * \param name Configuration item name + * \return The configuration item type or 0 if not found. + */ +VLC_API int config_GetType(const char *name) VLC_USED; + +/** + * Gets an integer configuration item. + * + * This function retrieves the current value of a configuration item of + * integral type (\ref CONFIG_ITEM_INTEGER and \ref CONFIG_ITEM_BOOL). + * + * \warning The behaviour is undefined if the configuration item exists but is + * not of integer or boolean type. + * + * \param name Configuration item name + * \return The configuration item value or -1 if not found. + * \bug A legitimate integer value of -1 cannot be distinguished from an error. + */ VLC_API int64_t config_GetInt(vlc_object_t *, const char *) VLC_USED; -VLC_API void config_PutInt(vlc_object_t *, const char *, int64_t); -VLC_API float config_GetFloat(vlc_object_t *, const char *) VLC_USED; -VLC_API void config_PutFloat(vlc_object_t *, const char *, float); -VLC_API char * config_GetPsz(vlc_object_t *, const char *) VLC_USED VLC_MALLOC; -VLC_API void config_PutPsz(vlc_object_t *, const char *, const char *); + +/** + * Sets an integer configuration item. + * + * This function changes the current value of a configuration item of + * integral type (\ref CONFIG_ITEM_INTEGER and \ref CONFIG_ITEM_BOOL). + * + * \warning The behaviour is undefined if the configuration item exists but is + * not of integer or boolean type. + * + * \note If no configuration item by the specified exist, the function has no + * effects. + * + * \param name Configuration item name + * \param val New value + */ +VLC_API void config_PutInt(vlc_object_t *, const char *name, int64_t val); + +/** + * Gets an floating point configuration item. + * + * This function retrieves the current value of a configuration item of + * floating point type (\ref CONFIG_ITEM_FLOAT). + * + * \warning The behaviour is undefined if the configuration item exists but is + * not of floating point type. + * + * \param name Configuration item name + * \return The configuration item value or -1 if not found. + * \bug A legitimate floating point value of -1 cannot be distinguished from an + * error. + */ +VLC_API float config_GetFloat(vlc_object_t *, const char *name) VLC_USED; + +/** + * Sets an integer configuration item. + * + * This function changes the current value of a configuration item of + * integral type (\ref CONFIG_ITEM_FLOAT). + * + * \warning The behaviour is undefined if the configuration item exists but is + * not of floating point type. + * + * \note If no configuration item by the specified exist, the function has no + * effects. + * + * \param name Configuration item name + * \param val New value + */ +VLC_API void config_PutFloat(vlc_object_t *, const char *name, float val); + +/** + * Gets an string configuration item. + * + * This function retrieves the current value of a configuration item of + * string type (\ref CONFIG_ITEM_STRING). + * + * \note The caller must free() the returned pointer (if non-NULL), which is a + * duplicate of the current value. It is not safe to return a pointer to the + * current value internally as it can be modified at any time by any other + * thread. + * + * \warning The behaviour is undefined if the configuration item exists but is + * not of floating point type. + * + * \param name Configuration item name + * \return Normally, a heap-allocated copy of the configuration item value. + * If the value is the empty string, if the configuration does not exist, + * or if an error occurs, NULL is returned. + * \bug The empty string value cannot be distinguished from an error. + */ +VLC_API char * config_GetPsz(vlc_object_t *, const char *name) +VLC_USED VLC_MALLOC; + +/** + * Sets an string configuration item. + * + * This function changes the current value of a configuration item of + * string type (e.g. \ref CONFIG_ITEM_STRING). + * + * \warning The behaviour is undefined if the configuration item exists but is + * not of a string type. + * + * \note If no configuration item by the specified exist, the function has no + * effects. + * + * \param name Configuration item name + * \param val New value (will be copied) + * \bug This function allocates memory but errors cannot be detected. + */ +VLC_API void config_PutPsz(vlc_object_t *, const char *name, const char *val); + +/** + * Enumerates integer configuration choices. + * + * Determines a list of suggested values for an integer configuration item. + * \param values pointer to a table of integer values [OUT] + * \param texts pointer to a table of descriptions strings [OUT] + * \return number of choices, or -1 on error + * \note the caller is responsible for calling free() on all descriptions and + * on both tables. In case of error, both pointers are set to NULL. + */ VLC_API ssize_t config_GetIntChoices(vlc_object_t *, const char *, int64_t **, char ***) VLC_USED; + +/** + * Determines a list of suggested values for a string configuration item. + * \param values pointer to a table of value strings [OUT] + * \param texts pointer to a table of descriptions strings [OUT] + * \return number of choices, or -1 on error + * \note the caller is responsible for calling free() on all values, on all + * descriptions and on both tables. + * In case of error, both pointers are set to NULL. + */ VLC_API ssize_t config_GetPszChoices(vlc_object_t *, const char *, char ***, char ***) VLC_USED; VLC_API int config_SaveConfigFile( vlc_object_t * ); #define config_SaveConfigFile(a) config_SaveConfigFile(VLC_OBJECT(a)) +/** + * Resets the configuration. + * + * This function resets all configuration items to their respective + * compile-time default value. + */ VLC_API void config_ResetAll( vlc_object_t * ); #define config_ResetAll(a) config_ResetAll(VLC_OBJECT(a)) -VLC_API module_config_t * config_FindConfig(const char *) VLC_USED; +/** + * Looks up a configuration item. + * + * This function looks for the internal representation of a configuration item. + * Where possible, this should be avoided in favor of more specific function + * calls. + * + * \param name Configuration item name + * \return The internal structure, or NULL if not found. + */ +VLC_API module_config_t *config_FindConfig(const char *name) VLC_USED; /** * Gets the arch-independent installation directory. @@ -260,4 +418,6 @@ VLC_API char * config_StringEscape( const char *psz_string ) VLC_USED VLC_MALLOC } # endif +/** @} */ + #endif /* _VLC_CONFIGURATION_H */ diff --git a/src/config/core.c b/src/config/core.c index fe6abb6e98..6b4f6d97dc 100644 --- a/src/config/core.c +++ b/src/config/core.c @@ -46,11 +46,6 @@ static inline char *strdupnull (const char *src) return src ? strdup (src) : NULL; } -/***************************************************************************** - * config_GetType: get the type of a variable (bool, int, float, string) - ***************************************************************************** - * This function is used to get the type of a variable from its name. - *****************************************************************************/ int config_GetType(const char *psz_name) { module_config_t *p_config = config_FindConfig(psz_name); @@ -83,13 +78,6 @@ bool config_IsSafe( const char *name ) } #undef config_GetInt -/***************************************************************************** - * config_GetInt: get the value of an int variable - ***************************************************************************** - * This function is used to get the value of variables which are internally - * represented by an integer (CONFIG_ITEM_INTEGER and - * CONFIG_ITEM_BOOL). - *****************************************************************************/ int64_t config_GetInt( vlc_object_t *p_this, const char *psz_name ) { module_config_t *p_config = config_FindConfig( psz_name ); @@ -112,12 +100,6 @@ int64_t config_GetInt( vlc_object_t *p_this, const char *psz_name ) } #undef config_GetFloat -/***************************************************************************** - * config_GetFloat: get the value of a float variable - ***************************************************************************** - * This function is used to get the value of variables which are internally - * represented by a float (CONFIG_ITEM_FLOAT). - *****************************************************************************/ float config_GetFloat( vlc_object_t *p_this, const char *psz_name ) { module_config_t *p_config; @@ -142,17 +124,6 @@ float config_GetFloat( vlc_object_t *p_this, const char *psz_name ) } #undef config_GetPsz -/***************************************************************************** - * config_GetPsz: get the string value of a string variable - ***************************************************************************** - * This function is used to get the value of variables which are internally - * represented by a string (CONFIG_ITEM_STRING, CONFIG_ITEM_*FILE, - * CONFIG_ITEM_DIRECTORY, CONFIG_ITEM_PASSWORD, and CONFIG_ITEM_MODULE). - * - * Important note: remember to free() the returned char* because it's a - * duplicate of the actual value. It isn't safe to return a pointer to the - * actual value as it can be modified at any time. - *****************************************************************************/ char * config_GetPsz( vlc_object_t *p_this, const char *psz_name ) { module_config_t *p_config; @@ -177,13 +148,6 @@ char * config_GetPsz( vlc_object_t *p_this, const char *psz_name ) } #undef config_PutPsz -/***************************************************************************** - * config_PutPsz: set the string value of a string variable - ***************************************************************************** - * This function is used to set the value of variables which are internally - * represented by a string (CONFIG_ITEM_STRING, CONFIG_ITEM_*FILE, - * CONFIG_ITEM_DIRECTORY, CONFIG_ITEM_PASSWORD, and CONFIG_ITEM_MODULE). - *****************************************************************************/ void config_PutPsz( vlc_object_t *p_this, const char *psz_name, const char *psz_value ) { @@ -215,13 +179,6 @@ void config_PutPsz( vlc_object_t *p_this, } #undef config_PutInt -/***************************************************************************** - * config_PutInt: set the integer value of an int variable - ***************************************************************************** - * This function is used to set the value of variables which are internally - * represented by an integer (CONFIG_ITEM_INTEGER and - * CONFIG_ITEM_BOOL). - *****************************************************************************/ void config_PutInt( vlc_object_t *p_this, const char *psz_name, int64_t i_value ) { @@ -248,12 +205,6 @@ void config_PutInt( vlc_object_t *p_this, const char *psz_name, } #undef config_PutFloat -/***************************************************************************** - * config_PutFloat: set the value of a float variable - ***************************************************************************** - * This function is used to set the value of variables which are internally - * represented by a float (CONFIG_ITEM_FLOAT). - *****************************************************************************/ void config_PutFloat( vlc_object_t *p_this, const char *psz_name, float f_value ) { @@ -282,14 +233,6 @@ void config_PutFloat( vlc_object_t *p_this, vlc_rwlock_unlock (&config_lock); } -/** - * Determines a list of suggested values for an integer configuration item. - * \param values pointer to a table of integer values [OUT] - * \param texts pointer to a table of descriptions strings [OUT] - * \return number of choices, or -1 on error - * \note the caller is responsible for calling free() on all descriptions and - * on both tables. In case of error, both pointers are set to NULL. - */ ssize_t config_GetIntChoices (vlc_object_t *obj, const char *name, int64_t **restrict values, char ***restrict texts) { @@ -385,15 +328,6 @@ static ssize_t config_ListModules (const char *cap, char ***restrict values, return n + 2; } -/** - * Determines a list of suggested values for a string configuration item. - * \param values pointer to a table of value strings [OUT] - * \param texts pointer to a table of descriptions strings [OUT] - * \return number of choices, or -1 on error - * \note the caller is responsible for calling free() on all values, on all - * descriptions and on both tables. - * In case of error, both pointers are set to NULL. - */ ssize_t config_GetPszChoices (vlc_object_t *obj, const char *name, char ***restrict values, char ***restrict texts) { @@ -517,9 +451,6 @@ void config_UnsortConfig (void) free (clist); } -/***************************************************************************** - * config_FindConfig: find the config structure associated with an option. - *****************************************************************************/ module_config_t *config_FindConfig(const char *name) { if (unlikely(name == NULL)) @@ -555,9 +486,6 @@ void config_Free (module_config_t *tab, size_t confsize) } #undef config_ResetAll -/***************************************************************************** - * config_ResetAll: reset the configuration data for all the modules. - *****************************************************************************/ void config_ResetAll( vlc_object_t *p_this ) { vlc_rwlock_wrlock (&config_lock); _______________________________________________ vlc-commits mailing list [email protected] https://mailman.videolan.org/listinfo/vlc-commits
