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
8 * Authors: Gildas Bazin <gbazin@videolan.org>
10 * This program is free software; you can redistribute it and/or modify it
11 * under the terms of the GNU Lesser General Public License as published by
12 * the Free Software Foundation; either version 2.1 of the License, or
13 * (at your option) any later version.
15 * This program is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 * GNU Lesser General Public License for more details.
20 * You should have received a copy of the GNU Lesser General Public License
21 * along with this program; if not, write to the Free Software Foundation,
22 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
23 *****************************************************************************/
25 #ifndef VLC_CONFIGURATION_H
26 #define VLC_CONFIGURATION_H 1
29 * \defgroup config User settings
31 * VLC provides a simple name-value dictionary for user settings.
33 * Those settings are per-user per-system - they are shared by all LibVLC
34 * instances in a single process, and potentially other processes as well.
36 * Each name-value pair is called a configuration item.
42 * This file describes the programming interface for the configuration module.
43 * It includes functions allowing to declare, get or set configuration options.
46 #include <sys/types.h> /* for ssize_t */
52 struct config_category_t
66 typedef int (*vlc_string_list_cb
)(const char *, char ***, char ***);
67 typedef int (*vlc_integer_list_cb
)(const char *, int64_t **, char ***);
72 * This is the internal reprensation of a configuration item.
73 * See also config_FindConfig().
75 struct module_config_t
77 uint8_t i_type
; /**< Configuration type */
78 char i_short
; /**< Optional short option name */
79 unsigned b_internal
:1; /**< Hidden from preferences and help */
80 unsigned b_unsaveable
:1; /**< Not stored in configuration */
81 unsigned b_safe
:1; /**< Safe for web plugins and playlist files */
82 unsigned b_removed
:1; /**< Obsolete */
84 const char *psz_type
; /**< Configuration subtype */
85 const char *psz_name
; /**< Option name */
86 const char *psz_text
; /**< Short comment on the configuration option */
87 const char *psz_longtext
; /**< Long comment on the configuration option */
89 module_value_t value
; /**< Current value */
90 module_value_t orig
; /**< Default value */
91 module_value_t min
; /**< Minimum value (for scalars only) */
92 module_value_t max
; /**< Maximum value (for scalars only) */
95 uint16_t list_count
; /**< Choices count */
98 const char **psz
; /**< Table of possible string choices */
99 const int *i
; /**< Table of possible integer choices */
100 vlc_string_list_cb psz_cb
; /**< Callback to enumerate string choices */
101 vlc_integer_list_cb i_cb
; /**< Callback to enumerate integer choices */
102 } list
; /**< Possible choices */
103 const char **list_text
; /**< Human-readable names for list values */
104 const char *list_cb_name
; /**< Symbol name of the enumeration callback */
105 void *owner
; /**< Origin run-time linker module handle */
109 * Gets a configuration item type
111 * This function checks the type of configuration item by name.
112 * \param name Configuration item name
113 * \return The configuration item type or 0 if not found.
115 VLC_API
int config_GetType(const char *name
) VLC_USED
;
118 * Gets an integer configuration item.
120 * This function retrieves the current value of a configuration item of
121 * integral type (\ref CONFIG_ITEM_INTEGER and \ref CONFIG_ITEM_BOOL).
123 * \warning The behaviour is undefined if the configuration item exists but is
124 * not of integer or boolean type.
126 * \param name Configuration item name
127 * \return The configuration item value or -1 if not found.
128 * \bug A legitimate integer value of -1 cannot be distinguished from an error.
130 VLC_API
int64_t config_GetInt(const char *name
) VLC_USED
;
133 * Sets an integer configuration item.
135 * This function changes the current value of a configuration item of
136 * integral type (\ref CONFIG_ITEM_INTEGER and \ref CONFIG_ITEM_BOOL).
138 * \warning The behaviour is undefined if the configuration item exists but is
139 * not of integer or boolean type.
141 * \note If no configuration item by the specified exist, the function has no
144 * \param name Configuration item name
145 * \param val New value
147 VLC_API
void config_PutInt(const char *name
, int64_t val
);
150 * Gets an floating point configuration item.
152 * This function retrieves the current value of a configuration item of
153 * floating point type (\ref CONFIG_ITEM_FLOAT).
155 * \warning The behaviour is undefined if the configuration item exists but is
156 * not of floating point type.
158 * \param name Configuration item name
159 * \return The configuration item value or -1 if not found.
160 * \bug A legitimate floating point value of -1 cannot be distinguished from an
163 VLC_API
float config_GetFloat(const char *name
) VLC_USED
;
166 * Sets an integer configuration item.
168 * This function changes the current value of a configuration item of
169 * integral type (\ref CONFIG_ITEM_FLOAT).
171 * \warning The behaviour is undefined if the configuration item exists but is
172 * not of floating point type.
174 * \note If no configuration item by the specified exist, the function has no
177 * \param name Configuration item name
178 * \param val New value
180 VLC_API
void config_PutFloat(const char *name
, float val
);
183 * Gets an string configuration item.
185 * This function retrieves the current value of a configuration item of
186 * string type (\ref CONFIG_ITEM_STRING).
188 * \note The caller must free() the returned pointer (if non-NULL), which is a
189 * duplicate of the current value. It is not safe to return a pointer to the
190 * current value internally as it can be modified at any time by any other
193 * \warning The behaviour is undefined if the configuration item exists but is
194 * not of floating point type.
196 * \param name Configuration item name
197 * \return Normally, a heap-allocated copy of the configuration item value.
198 * If the value is the empty string, if the configuration does not exist,
199 * or if an error occurs, NULL is returned.
200 * \bug The empty string value cannot be distinguished from an error.
202 VLC_API
char *config_GetPsz(const char *name
) VLC_USED VLC_MALLOC
;
205 * Sets an string configuration item.
207 * This function changes the current value of a configuration item of
208 * string type (e.g. \ref CONFIG_ITEM_STRING).
210 * \warning The behaviour is undefined if the configuration item exists but is
211 * not of a string type.
213 * \note If no configuration item by the specified exist, the function has no
216 * \param name Configuration item name
217 * \param val New value (will be copied)
218 * \bug This function allocates memory but errors cannot be detected.
220 VLC_API
void config_PutPsz(const char *name
, const char *val
);
223 * Enumerates integer configuration choices.
225 * Determines a list of suggested values for an integer configuration item.
226 * \param values pointer to a table of integer values [OUT]
227 * \param texts pointer to a table of descriptions strings [OUT]
228 * \return number of choices, or -1 on error
229 * \note the caller is responsible for calling free() on all descriptions and
230 * on both tables. In case of error, both pointers are set to NULL.
232 VLC_API ssize_t
config_GetIntChoices(const char *, int64_t **values
,
233 char ***texts
) VLC_USED
;
236 * Determines a list of suggested values for a string configuration item.
237 * \param values pointer to a table of value strings [OUT]
238 * \param texts pointer to a table of descriptions strings [OUT]
239 * \return number of choices, or -1 on error
240 * \note the caller is responsible for calling free() on all values, on all
241 * descriptions and on both tables.
242 * In case of error, both pointers are set to NULL.
244 VLC_API ssize_t
config_GetPszChoices(const char *,
245 char ***values
, char ***texts
) VLC_USED
;
247 VLC_API
int config_SaveConfigFile( vlc_object_t
* );
248 #define config_SaveConfigFile(a) config_SaveConfigFile(VLC_OBJECT(a))
251 * Resets the configuration.
253 * This function resets all configuration items to their respective
254 * compile-time default value.
256 VLC_API
void config_ResetAll(void);
259 * Looks up a configuration item.
261 * This function looks for the internal representation of a configuration item.
262 * Where possible, this should be avoided in favor of more specific function
265 * \param name Configuration item name
266 * \return The internal structure, or NULL if not found.
268 VLC_API module_config_t
*config_FindConfig(const char *name
) VLC_USED
;
271 * System directory identifiers
273 typedef enum vlc_system_dir
275 VLC_PKG_DATA_DIR
, /**< Package-specific architecture-independent read-only
276 data directory (e.g. /usr/local/data/vlc). */
277 VLC_PKG_LIB_DIR
, /**< Package-specific architecture-dependent read-only
278 data directory (e.g. /usr/local/lib/vlc). */
279 VLC_PKG_LIBEXEC_DIR
, /**< Package-specific executable read-only directory
280 (e.g. /usr/local/libexec/vlc). */
281 VLC_PKG_INCLUDE_DIR_RESERVED
,
282 VLC_SYSDATA_DIR
, /**< Global architecture-independent read-only
283 data directory (e.g. /usr/local/data).
284 Available only on some platforms. */
285 VLC_LIB_DIR
, /**< Global architecture-dependent read-only directory
286 (e.g. /usr/local/lib). */
287 VLC_LIBEXEC_DIR
, /**< Global executable read-only directory
288 (e.g. /usr/local/libexec). */
289 VLC_INCLUDE_DIR_RESERVED
,
290 VLC_LOCALE_DIR
, /**< Base directory for package read-only locale data. */
294 * Gets an installation directory.
296 * This function determines one of the installation directory.
298 * @param dir identifier of the directory (see \ref vlc_sysdir_t)
299 * @param filename name of a file or other object within the directory
300 * (or NULL to obtain the plain directory)
302 * @return a heap-allocated string (use free() to release it), or NULL on error
304 VLC_API
char *config_GetSysPath(vlc_sysdir_t dir
, const char *filename
)
307 typedef enum vlc_user_dir
309 VLC_HOME_DIR
, /* User's home */
310 VLC_CONFIG_DIR
, /* VLC-specific configuration directory */
311 VLC_USERDATA_DIR
, /* VLC-specific data directory */
312 VLC_CACHE_DIR
, /* VLC-specific user cached data directory */
313 /* Generic directories (same as XDG) */
314 VLC_DESKTOP_DIR
=0x80,
324 VLC_API
char * config_GetUserDir( vlc_userdir_t
) VLC_USED VLC_MALLOC
;
326 VLC_API
void config_AddIntf(const char *);
327 VLC_API
void config_RemoveIntf(const char *);
328 VLC_API
bool config_ExistIntf(const char *) VLC_USED
;
330 /****************************************************************************
332 ****************************************************************************/
333 struct config_chain_t
335 config_chain_t
*p_next
; /**< Pointer on the next config_chain_t element */
337 char *psz_name
; /**< Option name */
338 char *psz_value
; /**< Option value */
343 * - create all options in the array ppsz_options (var_Create).
344 * - parse the given linked list of config_chain_t and set the value (var_Set).
346 * The option names will be created by adding the psz_prefix prefix.
348 VLC_API
void config_ChainParse( vlc_object_t
*, const char *psz_prefix
, const char *const *ppsz_options
, config_chain_t
* );
349 #define config_ChainParse( a, b, c, d ) config_ChainParse( VLC_OBJECT(a), b, c, d )
352 * This function will parse a configuration string (psz_opts) and
353 * - set all options for this module in a chained list (*pp_cfg)
354 * - returns a pointer on the next module if any.
356 * The string format is
357 * module{option=*,option=*}
359 * The options values are unescaped using config_StringUnescape.
361 VLC_API
const char *config_ChainParseOptions( config_chain_t
**pp_cfg
, const char *ppsz_opts
);
364 * This function will parse a configuration string (psz_string) and
365 * - set the module name (*ppsz_name)
366 * - set all options for this module in a chained list (*pp_cfg)
367 * - returns a pointer on the next module if any.
369 * The string format is
370 * module{option=*,option=*}[:modulenext{option=*,...}]
372 * The options values are unescaped using config_StringUnescape.
374 VLC_API
char *config_ChainCreate( char **ppsz_name
, config_chain_t
**pp_cfg
, const char *psz_string
) VLC_USED VLC_MALLOC
;
377 * This function will release a linked list of config_chain_t
378 * (Including the head)
380 VLC_API
void config_ChainDestroy( config_chain_t
* );
383 * This function will duplicate a linked list of config_chain_t
385 VLC_API config_chain_t
* config_ChainDuplicate( const config_chain_t
* ) VLC_USED VLC_MALLOC
;
388 * This function will unescape a string in place and will return a pointer on
390 * No memory is allocated by it (unlike config_StringEscape).
391 * If NULL is given as parameter nothing will be done (NULL will be returned).
393 * The following sequences will be unescaped (only one time):
396 VLC_API
char * config_StringUnescape( char *psz_string
);
399 * This function will escape a string that can be unescaped by
400 * config_StringUnescape.
401 * The returned value is allocated by it. You have to free it once you
402 * do not need it anymore (unlike config_StringUnescape).
403 * If NULL is given as parameter nothing will be done (NULL will be returned).
405 * The escaped characters are ' " and \
407 VLC_API
char * config_StringEscape( const char *psz_string
) VLC_USED VLC_MALLOC
;
415 #endif /* _VLC_CONFIGURATION_H */