X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=include%2Fvlc_configuration.h;h=fa702f71bc3db8888f2ce6967444d36885f3659f;hb=1df015beff013d3fae00a4fae905ef28c4df10ce;hp=15c6a2202083577b92f0a37cc3602b34f01b8cdc;hpb=59dec65d5fe153565ea8705767874a2d876d2103;p=vlc diff --git a/include/vlc_configuration.h b/include/vlc_configuration.h index 15c6a22020..fa702f71bc 100644 --- a/include/vlc_configuration.h +++ b/include/vlc_configuration.h @@ -23,13 +23,14 @@ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA. *****************************************************************************/ -#if !defined( __LIBVLC__ ) - #error You are not libvlc or one of its plugins. You cannot include this file -#endif - -#ifndef _VLC_CONFIGURATION_H -#define _VLC_CONFIGURATION_H 1 +#ifndef VLC_CONFIGURATION_H +#define VLC_CONFIGURATION_H 1 +/** + * \file + * This file describes the programming interface for the configuration module. + * It includes functions allowing to declare, get or set configuration options. + */ # ifdef __cplusplus extern "C" { @@ -177,34 +178,34 @@ struct module_config_t int i_action; /* actions list size */ /* Misc */ - vlc_mutex_t *p_lock; /* Lock to use when modifying the config */ - bool b_dirty; /* Dirty flag to indicate a config change */ - bool b_advanced; /* Flag to indicate an advanced option */ - bool b_internal; /* Flag to indicate option is not to be shown */ - bool b_restart; /* Flag to indicate the option needs a restart */ + vlc_mutex_t *p_lock; /* Lock to use when modifying the config */ + bool b_dirty; /* Dirty flag to indicate a config change */ + bool b_advanced; /* Flag to indicate an advanced option */ + bool b_internal; /* Flag to indicate option is not to be shown */ + bool b_restart; /* Flag to indicate the option needs a restart */ /* to take effect */ /* Deprecated */ - char *psz_oldname; /* Old option name */ - bool b_removed; + char *psz_oldname; /* Old option name */ + bool b_removed; /* Option values loaded from config file */ - bool b_autosave; /* Config will be auto-saved at exit time */ - bool b_unsaveable; /* Config should not be saved */ + bool b_autosave; /* Config will be auto-saved at exit time */ + bool b_unsaveable; /* Config should not be saved */ - bool b_safe; + bool b_safe; }; /***************************************************************************** * Prototypes - these methods are used to get, set or manipulate configuration * data. *****************************************************************************/ -VLC_EXPORT( int, __config_GetType, (vlc_object_t *, const char *) ); -VLC_EXPORT( int, __config_GetInt, (vlc_object_t *, const char *) ); +VLC_EXPORT( int, __config_GetType, (vlc_object_t *, const char *) LIBVLC_USED ); +VLC_EXPORT( int, __config_GetInt, (vlc_object_t *, const char *) LIBVLC_USED ); VLC_EXPORT( void, __config_PutInt, (vlc_object_t *, const char *, int) ); -VLC_EXPORT( float, __config_GetFloat, (vlc_object_t *, const char *) ); +VLC_EXPORT( float, __config_GetFloat, (vlc_object_t *, const char *) LIBVLC_USED ); VLC_EXPORT( void, __config_PutFloat, (vlc_object_t *, const char *, float) ); -VLC_EXPORT( char *, __config_GetPsz, (vlc_object_t *, const char *) ); +VLC_EXPORT( char *, __config_GetPsz, (vlc_object_t *, const char *) LIBVLC_USED ); VLC_EXPORT( void, __config_PutPsz, (vlc_object_t *, const char *, const char *) ); #define config_SaveConfigFile(a,b) __config_SaveConfigFile(VLC_OBJECT(a),b) @@ -212,18 +213,18 @@ VLC_EXPORT( int, __config_SaveConfigFile, ( vlc_object_t *, const char * ) ); #define config_ResetAll(a) __config_ResetAll(VLC_OBJECT(a)) VLC_EXPORT( void, __config_ResetAll, ( vlc_object_t * ) ); -VLC_EXPORT( module_config_t *, config_FindConfig,( vlc_object_t *, const char * ) ); +VLC_EXPORT( module_config_t *, config_FindConfig,( vlc_object_t *, const char * ) LIBVLC_USED ); -VLC_EXPORT(const char *, config_GetDataDir, ( void )); -VLC_EXPORT(const char *, config_GetConfDir, ( void ) ); -VLC_EXPORT(const char *, config_GetHomeDir, ( void )); -VLC_EXPORT(char *, config_GetUserConfDir, ( void ) ); -VLC_EXPORT(char *, config_GetUserDataDir, ( void ) ); -VLC_EXPORT(char *, config_GetCacheDir, ( void ) ); +VLC_EXPORT(const char *, config_GetDataDir, ( void ) LIBVLC_USED); +VLC_EXPORT(const char *, config_GetConfDir, ( void ) LIBVLC_USED); +VLC_EXPORT(const char *, config_GetHomeDir, ( void ) LIBVLC_USED); +VLC_EXPORT(char *, config_GetUserConfDir, ( void ) LIBVLC_USED); +VLC_EXPORT(char *, config_GetUserDataDir, ( void ) LIBVLC_USED); +VLC_EXPORT(char *, config_GetCacheDir, ( void ) LIBVLC_USED); VLC_EXPORT( void, __config_AddIntf, ( vlc_object_t *, const char * ) ); VLC_EXPORT( void, __config_RemoveIntf, ( vlc_object_t *, const char * ) ); -VLC_EXPORT( bool, __config_ExistIntf, ( vlc_object_t *, const char * ) ); +VLC_EXPORT( bool, __config_ExistIntf, ( vlc_object_t *, const char * ) LIBVLC_USED); #define config_GetType(a,b) __config_GetType(VLC_OBJECT(a),b) #define config_GetInt(a,b) __config_GetInt(VLC_OBJECT(a),b) @@ -242,17 +243,63 @@ VLC_EXPORT( bool, __config_ExistIntf, ( vlc_object_t *, const char * ) ); ****************************************************************************/ struct config_chain_t { - config_chain_t *p_next; + config_chain_t *p_next; /**< Pointer on the next config_chain_t element */ - char *psz_name; - char *psz_value; + char *psz_name; /**< Option name */ + char *psz_value; /**< Option value */ }; +/** + * This function will + * - create all options in the array ppsz_options (var_Create). + * - parse the given linked list of config_chain_t and set the value (var_Set). + * + * The option names will be created by adding the psz_prefix prefix. + */ #define config_ChainParse( a, b, c, d ) __config_ChainParse( VLC_OBJECT(a), b, c, d ) VLC_EXPORT( void, __config_ChainParse, ( vlc_object_t *, const char *psz_prefix, const char *const *ppsz_options, config_chain_t * ) ); -VLC_EXPORT( char *, config_ChainCreate, ( char **, config_chain_t **, const char * ) ); + +/** + * This function will parse a configuration string (psz_string) and + * - set the module name (*ppsz_name) + * - set all options for this module in a chained list (*pp_cfg) + * - returns a pointer on the next module if any. + * + * The string format is + * module{option=*,option=*}[:modulenext{option=*,...}] + * + * The options values are unescaped using config_StringUnescape. + */ +VLC_EXPORT( char *, config_ChainCreate, ( char **ppsz_name, config_chain_t **pp_cfg, const char *psz_string ) ); + +/** + * This function will release a linked list of config_chain_t + * (Including the head) + */ VLC_EXPORT( void, config_ChainDestroy, ( config_chain_t * ) ); +/** + * This function will unescape a string in place and will return a pointer on + * the given string. + * No memory is allocated by it (unlike config_StringEscape). + * If NULL is given as parameter nothing will be done (NULL will be returned). + * + * The following sequences will be unescaped (only one time): + * \\ \' and \" + */ +VLC_EXPORT( char *, config_StringUnescape, ( char *psz_string ) ); + +/** + * This function will escape a string that can be unescaped by + * config_StringUnescape. + * The returned value is allocated by it. You have to free it once you + * do not need it anymore (unlike config_StringUnescape). + * If NULL is given as parameter nothing will be done (NULL will be returned). + * + * The escaped characters are ' " and \ + */ +VLC_EXPORT( char *, config_StringEscape, ( const char *psz_string ) LIBVLC_USED); + # ifdef __cplusplus } # endif