1 /***************************************************************************** 2 * vlc_configuration.h : configuration management module 3 * This file describes the programming interface for the configuration module. 4 * It includes functions allowing to declare, get or set configuration options. 5 ***************************************************************************** 6 * Copyright (C) 1999-2006 VLC authors and VideoLAN 7 * $Id: 209168615be2a7bc5db889282b32389093ab262e $ 8 * 9 * Authors: Gildas Bazin <gbazin@videolan.org> 10 * 11 * This program is free software; you can redistribute it and/or modify it 12 * under the terms of the GNU Lesser General Public License as published by 13 * the Free Software Foundation; either version 2.1 of the License, or 14 * (at your option) any later version. 15 * 16 * This program is distributed in the hope that it will be useful, 17 * but WITHOUT ANY WARRANTY; without even the implied warranty of 18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 19 * GNU Lesser General Public License for more details. 20 * 21 * You should have received a copy of the GNU Lesser General Public License 22 * along with this program; if not, write to the Free Software Foundation, 23 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA. 24 *****************************************************************************/ 25 26 #ifndef VLC_CONFIGURATION_H 27 #define VLC_CONFIGURATION_H 1 28 29 /** 30 * \file 31 * This file describes the programming interface for the configuration module. 32 * It includes functions allowing to declare, get or set configuration options. 33 */ 34 35 #include <sys/types.h> /* for ssize_t */ 36 37 # ifdef __cplusplus 38 extern "C" { 39 # endif 40 41 struct config_category_t 42 { 43 int i_id; 44 const char *psz_name; 45 const char *psz_help; 46 }; 47 48 typedef union 49 { 50 char *psz; 51 int64_t i; 52 float f; 53 } module_value_t; 54 55 typedef int (*vlc_string_list_cb)(vlc_object_t *, const char *, 56 char ***, char ***); 57 typedef int (*vlc_integer_list_cb)(vlc_object_t *, const char *, 58 int64_t **, char ***); 59 60 struct module_config_t 61 { 62 uint8_t i_type; /* Configuration type */ 63 char i_short; /* Optional short option name */ 64 unsigned b_advanced:1; /* Advanced option */ 65 unsigned b_internal:1; /* Hidden from prefs and help */ 66 unsigned b_unsaveable:1; /* Not stored in configuration */ 67 unsigned b_safe:1; /* Safe in web plugins and playlists */ 68 unsigned b_removed:1; /* Deprecated */ 69 70 const char *psz_type; /* Configuration subtype */ 71 const char *psz_name; /* Option name */ 72 const char *psz_text; /* Short comment on the configuration option */ 73 const char *psz_longtext; /* Long comment on the configuration option */ 74 75 module_value_t value; /* Option value */ 76 module_value_t orig; 77 module_value_t min; 78 module_value_t max; 79 80 /* Values list */ 81 uint16_t list_count; /* Options list size */ 82 union 83 { 84 const char **psz; /* List of possible values for the option */ 85 const int *i; 86 vlc_string_list_cb psz_cb; 87 vlc_integer_list_cb i_cb; 88 } list; 89 const char **list_text; /* Friendly names for list values */ 90 const char *list_cb_name; 91 void *owner; 92 }; 93 94 /***************************************************************************** 95 * Prototypes - these methods are used to get, set or manipulate configuration 96 * data. 97 *****************************************************************************/ 98 VLC_API int config_GetType(const char *) VLC_USED; 99 VLC_API int64_t config_GetInt(vlc_object_t *, const char *) VLC_USED; 100 VLC_API void config_PutInt(vlc_object_t *, const char *, int64_t); 101 VLC_API float config_GetFloat(vlc_object_t *, const char *) VLC_USED; 102 VLC_API void config_PutFloat(vlc_object_t *, const char *, float); 103 VLC_API char * config_GetPsz(vlc_object_t *, const char *) VLC_USED VLC_MALLOC; 104 VLC_API void config_PutPsz(vlc_object_t *, const char *, const char *); 105 VLC_API ssize_t config_GetIntChoices(vlc_object_t *, const char *, 106 int64_t **, char ***) VLC_USED; 107 VLC_API ssize_t config_GetPszChoices(vlc_object_t *, const char *, 108 char ***, char ***) VLC_USED; 109 110 VLC_API int config_SaveConfigFile( vlc_object_t * ); 111 #define config_SaveConfigFile(a) config_SaveConfigFile(VLC_OBJECT(a)) 112 113 VLC_API void config_ResetAll( vlc_object_t * ); 114 #define config_ResetAll(a) config_ResetAll(VLC_OBJECT(a)) 115 116 VLC_API module_config_t * config_FindConfig(const char *) VLC_USED; 117 VLC_API char * config_GetDataDir(void) VLC_USED VLC_MALLOC; 118 VLC_API char *config_GetLibDir(void) VLC_USED; 119 120 typedef enum vlc_userdir 121 { 122 VLC_HOME_DIR, /* User's home */ 123 VLC_CONFIG_DIR, /* VLC-specific configuration directory */ 124 VLC_DATA_DIR, /* VLC-specific data directory */ 125 VLC_CACHE_DIR, /* VLC-specific user cached data directory */ 126 /* Generic directories (same as XDG) */ 127 VLC_DESKTOP_DIR=0x80, 128 VLC_DOWNLOAD_DIR, 129 VLC_TEMPLATES_DIR, 130 VLC_PUBLICSHARE_DIR, 131 VLC_DOCUMENTS_DIR, 132 VLC_MUSIC_DIR, 133 VLC_PICTURES_DIR, 134 VLC_VIDEOS_DIR, 135 } vlc_userdir_t; 136 137 VLC_API char * config_GetUserDir( vlc_userdir_t ) VLC_USED VLC_MALLOC; 138 139 VLC_API void config_AddIntf( vlc_object_t *, const char * ); 140 VLC_API void config_RemoveIntf( vlc_object_t *, const char * ); 141 VLC_API bool config_ExistIntf( vlc_object_t *, const char * ) VLC_USED; 142 143 #define config_GetInt(a,b) config_GetInt(VLC_OBJECT(a),b) 144 #define config_PutInt(a,b,c) config_PutInt(VLC_OBJECT(a),b,c) 145 #define config_GetFloat(a,b) config_GetFloat(VLC_OBJECT(a),b) 146 #define config_PutFloat(a,b,c) config_PutFloat(VLC_OBJECT(a),b,c) 147 #define config_GetPsz(a,b) config_GetPsz(VLC_OBJECT(a),b) 148 #define config_PutPsz(a,b,c) config_PutPsz(VLC_OBJECT(a),b,c) 149 150 #define config_AddIntf(a,b) config_AddIntf(VLC_OBJECT(a),b) 151 #define config_RemoveIntf(a,b) config_RemoveIntf(VLC_OBJECT(a),b) 152 #define config_ExistIntf(a,b) config_ExistIntf(VLC_OBJECT(a),b) 153 154 /**************************************************************************** 155 * config_chain_t: 156 ****************************************************************************/ 157 struct config_chain_t 158 { 159 config_chain_t *p_next; /**< Pointer on the next config_chain_t element */ 160 161 char *psz_name; /**< Option name */ 162 char *psz_value; /**< Option value */ 163 }; 164 165 /** 166 * This function will 167 * - create all options in the array ppsz_options (var_Create). 168 * - parse the given linked list of config_chain_t and set the value (var_Set). 169 * 170 * The option names will be created by adding the psz_prefix prefix. 171 */ 172 VLC_API void config_ChainParse( vlc_object_t *, const char *psz_prefix, const char *const *ppsz_options, config_chain_t * ); 173 #define config_ChainParse( a, b, c, d ) config_ChainParse( VLC_OBJECT(a), b, c, d ) 174 175 /** 176 * This function will parse a configuration string (psz_opts) and 177 * - set all options for this module in a chained list (*pp_cfg) 178 * - returns a pointer on the next module if any. 179 * 180 * The string format is 181 * module{option=*,option=*} 182 * 183 * The options values are unescaped using config_StringUnescape. 184 */ 185 VLC_API const char *config_ChainParseOptions( config_chain_t **pp_cfg, const char *ppsz_opts ); 186 187 /** 188 * This function will parse a configuration string (psz_string) and 189 * - set the module name (*ppsz_name) 190 * - set all options for this module in a chained list (*pp_cfg) 191 * - returns a pointer on the next module if any. 192 * 193 * The string format is 194 * module{option=*,option=*}[:modulenext{option=*,...}] 195 * 196 * The options values are unescaped using config_StringUnescape. 197 */ 198 VLC_API char *config_ChainCreate( char **ppsz_name, config_chain_t **pp_cfg, const char *psz_string ) VLC_USED VLC_MALLOC; 199 200 /** 201 * This function will release a linked list of config_chain_t 202 * (Including the head) 203 */ 204 VLC_API void config_ChainDestroy( config_chain_t * ); 205 206 /** 207 * This function will duplicate a linked list of config_chain_t 208 */ 209 VLC_API config_chain_t * config_ChainDuplicate( const config_chain_t * ) VLC_USED VLC_MALLOC; 210 211 /** 212 * This function will unescape a string in place and will return a pointer on 213 * the given string. 214 * No memory is allocated by it (unlike config_StringEscape). 215 * If NULL is given as parameter nothing will be done (NULL will be returned). 216 * 217 * The following sequences will be unescaped (only one time): 218 * \\ \' and \" 219 */ 220 VLC_API char * config_StringUnescape( char *psz_string ); 221 222 /** 223 * This function will escape a string that can be unescaped by 224 * config_StringUnescape. 225 * The returned value is allocated by it. You have to free it once you 226 * do not need it anymore (unlike config_StringUnescape). 227 * If NULL is given as parameter nothing will be done (NULL will be returned). 228 * 229 * The escaped characters are ' " and \ 230 */ 231 VLC_API char * config_StringEscape( const char *psz_string ) VLC_USED VLC_MALLOC; 232 233 # ifdef __cplusplus 234 } 235 # endif 236 237 #endif /* _VLC_CONFIGURATION_H */ 238