include/vlc_configuration.h

   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$
   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  * \defgroup config User settings
  31  * \ingroup interface
  32  * VLC provides a simple name-value dictionary for user settings.
  33  *
  34  * Those settings are per-user per-system - they are shared by all LibVLC
  35  * instances in a single process, and potentially other processes as well.
  36  *
  37  * Each name-value pair is called a configuration item.
  38  * @{
  39  */
  40
  41 /**
  42  * \file
  43  * This file describes the programming interface for the configuration module.
  44  * It includes functions allowing to declare, get or set configuration options.
  45  */
  46
  47 #include <sys/types.h>  /* for ssize_t */
  48
  49 # ifdef __cplusplus
  50 extern "C" {
  51 # endif
  52
  53 struct config_category_t
  54 {
  55     int         i_id;
  56     const char *psz_name;
  57     const char *psz_help;
  58 };
  59
  60 typedef union
  61 {
  62     char       *psz;
  63     int64_t     i;
  64     float       f;
  65 } module_value_t;
  66
  67 typedef int (*vlc_string_list_cb)(const char *, char ***, char ***);
  68 typedef int (*vlc_integer_list_cb)(const char *, int64_t **, char ***);
  69
  70 /**
  71  * Configuration item
  72  *
  73  * This is the internal reprensation of a configuration item.
  74  * See also config_FindConfig().
  75  */
  76 struct module_config_t
  77 {
  78     uint8_t     i_type; /**< Configuration type */
  79     char        i_short; /**< Optional short option name */
  80     unsigned    b_advanced:1; /**< Advanced option */
  81     unsigned    b_internal:1; /**< Hidden from preferences and help */
  82     unsigned    b_unsaveable:1; /**< Not stored in configuration */
  83     unsigned    b_safe:1; /**< Safe for web plugins and playlist files */
  84     unsigned    b_removed:1; /**< Obsolete */
  85
  86     const char *psz_type; /**< Configuration subtype */
  87     const char *psz_name; /**< Option name */
  88     const char *psz_text; /**< Short comment on the configuration option */
  89     const char *psz_longtext; /**< Long comment on the configuration option */
  90
  91     module_value_t value; /**< Current value */
  92     module_value_t orig; /**< Default value */
  93     module_value_t min; /**< Minimum value (for scalars only) */
  94     module_value_t max; /**< Maximum value (for scalars only) */
  95
  96     /* Values list */
  97     uint16_t list_count; /**< Choices count */
  98     union
  99     {
 100         const char **psz; /**< Table of possible string choices */
 101         const int  *i; /**< Table of possible integer choices */
 102         vlc_string_list_cb psz_cb; /**< Callback to enumerate string choices */
 103         vlc_integer_list_cb i_cb; /**< Callback to enumerate integer choices */
 104     } list; /**< Possible choices */
 105     const char **list_text; /**< Human-readable names for list values */
 106     const char *list_cb_name; /**< Symbol name of the enumeration callback */
 107     void *owner; /**< Origin run-time linker module handle */
 108 };
 109
 110 /**
 111  * Gets a configuration item type
 112  *
 113  * This function checks the type of configuration item by name.
 114  * \param name Configuration item name
 115  * \return The configuration item type or 0 if not found.
 116  */
 117 VLC_API int config_GetType(const char *name) VLC_USED;
 118
 119 /**
 120  * Gets an integer configuration item.
 121  *
 122  * This function retrieves the current value of a configuration item of
 123  * integral type (\ref CONFIG_ITEM_INTEGER and \ref CONFIG_ITEM_BOOL).
 124  *
 125  * \warning The behaviour is undefined if the configuration item exists but is
 126  * not of integer or boolean type.
 127  *
 128  * \param name Configuration item name
 129  * \return The configuration item value or -1 if not found.
 130  * \bug A legitimate integer value of -1 cannot be distinguished from an error.
 131  */
 132 VLC_API int64_t config_GetInt(const char *name) VLC_USED;
 133
 134 /**
 135  * Sets an integer configuration item.
 136  *
 137  * This function changes the current value of a configuration item of
 138  * integral type (\ref CONFIG_ITEM_INTEGER and \ref CONFIG_ITEM_BOOL).
 139  *
 140  * \warning The behaviour is undefined if the configuration item exists but is
 141  * not of integer or boolean type.
 142  *
 143  * \note If no configuration item by the specified exist, the function has no
 144  * effects.
 145  *
 146  * \param name Configuration item name
 147  * \param val New value
 148  */
 149 VLC_API void config_PutInt(const char *name, int64_t val);
 150
 151 /**
 152  * Gets an floating point configuration item.
 153  *
 154  * This function retrieves the current value of a configuration item of
 155  * floating point type (\ref CONFIG_ITEM_FLOAT).
 156  *
 157  * \warning The behaviour is undefined if the configuration item exists but is
 158  * not of floating point type.
 159  *
 160  * \param name Configuration item name
 161  * \return The configuration item value or -1 if not found.
 162  * \bug A legitimate floating point value of -1 cannot be distinguished from an
 163  * error.
 164  */
 165 VLC_API float config_GetFloat(const char *name) VLC_USED;
 166
 167 /**
 168  * Sets an integer configuration item.
 169  *
 170  * This function changes the current value of a configuration item of
 171  * integral type (\ref CONFIG_ITEM_FLOAT).
 172  *
 173  * \warning The behaviour is undefined if the configuration item exists but is
 174  * not of floating point type.
 175  *
 176  * \note If no configuration item by the specified exist, the function has no
 177  * effects.
 178  *
 179  * \param name Configuration item name
 180  * \param val New value
 181  */
 182 VLC_API void config_PutFloat(const char *name, float val);
 183
 184 /**
 185  * Gets an string configuration item.
 186  *
 187  * This function retrieves the current value of a configuration item of
 188  * string type (\ref CONFIG_ITEM_STRING).
 189  *
 190  * \note The caller must free() the returned pointer (if non-NULL), which is a
 191  * duplicate of the current value. It is not safe to return a pointer to the
 192  * current value internally as it can be modified at any time by any other
 193  * thread.
 194  *
 195  * \warning The behaviour is undefined if the configuration item exists but is
 196  * not of floating point type.
 197  *
 198  * \param name Configuration item name
 199  * \return Normally, a heap-allocated copy of the configuration item value.
 200  * If the value is the empty string, if the configuration does not exist,
 201  * or if an error occurs, NULL is returned.
 202  * \bug The empty string value cannot be distinguished from an error.
 203  */
 204 VLC_API char *config_GetPsz(const char *name) VLC_USED VLC_MALLOC;
 205
 206 /**
 207  * Sets an string configuration item.
 208  *
 209  * This function changes the current value of a configuration item of
 210  * string type (e.g. \ref CONFIG_ITEM_STRING).
 211  *
 212  * \warning The behaviour is undefined if the configuration item exists but is
 213  * not of a string type.
 214  *
 215  * \note If no configuration item by the specified exist, the function has no
 216  * effects.
 217  *
 218  * \param name Configuration item name
 219  * \param val New value (will be copied)
 220  * \bug This function allocates memory but errors cannot be detected.
 221  */
 222 VLC_API void config_PutPsz(const char *name, const char *val);
 223
 224 /**
 225  * Enumerates integer configuration choices.
 226  *
 227  * Determines a list of suggested values for an integer configuration item.
 228  * \param values pointer to a table of integer values [OUT]
 229  * \param texts pointer to a table of descriptions strings [OUT]
 230  * \return number of choices, or -1 on error
 231  * \note the caller is responsible for calling free() on all descriptions and
 232  * on both tables. In case of error, both pointers are set to NULL.
 233  */
 234 VLC_API ssize_t config_GetIntChoices(const char *, int64_t **values,
 235                                      char ***texts) VLC_USED;
 236
 237 /**
 238  * Determines a list of suggested values for a string configuration item.
 239  * \param values pointer to a table of value strings [OUT]
 240  * \param texts pointer to a table of descriptions strings [OUT]
 241  * \return number of choices, or -1 on error
 242  * \note the caller is responsible for calling free() on all values, on all
 243  * descriptions and on both tables.
 244  * In case of error, both pointers are set to NULL.
 245  */
 246 VLC_API ssize_t config_GetPszChoices(const char *,
 247                                      char ***values, char ***texts) VLC_USED;
 248
 249 VLC_API int config_SaveConfigFile( vlc_object_t * );
 250 #define config_SaveConfigFile(a) config_SaveConfigFile(VLC_OBJECT(a))
 251
 252 /**
 253  * Resets the configuration.
 254  *
 255  * This function resets all configuration items to their respective
 256  * compile-time default value.
 257  */
 258 VLC_API void config_ResetAll(void);
 259
 260 /**
 261  * Looks up a configuration item.
 262  *
 263  * This function looks for the internal representation of a configuration item.
 264  * Where possible, this should be avoided in favor of more specific function
 265  * calls.
 266  *
 267  * \param name Configuration item name
 268  * \return The internal structure, or NULL if not found.
 269  */
 270 VLC_API module_config_t *config_FindConfig(const char *name) VLC_USED;
 271
 272 /**
 273  * System directory identifiers
 274  */
 275 typedef enum vlc_system_dir
 276 {
 277     VLC_PKG_DATA_DIR, /**< Package-specific architecture-independent read-only
 278                            data directory (e.g. /usr/local/data/vlc). */
 279     VLC_PKG_LIB_DIR, /**< Package-specific architecture-dependent read-only
 280                           data directory (e.g. /usr/local/lib/vlc). */
 281     VLC_PKG_LIBEXEC_DIR, /**< Package-specific executable read-only directory
 282                               (e.g. /usr/local/libexec/vlc). */
 283     VLC_PKG_INCLUDE_DIR_RESERVED,
 284     VLC_SYSDATA_DIR, /**< Global architecture-independent read-only
 285                           data directory (e.g. /usr/local/data).
 286                           Available only on some platforms. */
 287     VLC_LIB_DIR, /**< Global architecture-dependent read-only directory
 288                       (e.g. /usr/local/lib). */
 289     VLC_LIBEXEC_DIR, /**< Global executable read-only directory
 290                           (e.g. /usr/local/libexec). */
 291     VLC_INCLUDE_DIR_RESERVED,
 292     VLC_LOCALE_DIR, /**< Base directory for package read-only locale data. */
 293 } vlc_sysdir_t;
 294
 295 /**
 296  * Gets an installation directory.
 297  *
 298  * This function determines one of the installation directory.
 299  *
 300  * @param dir identifier of the directory (see \ref vlc_sysdir_t)
 301  * @param filename name of a file or other object within the directory
 302  *                 (or NULL to obtain the plain directory)
 303  *
 304  * @return a heap-allocated string (use free() to release it), or NULL on error
 305  */
 306 VLC_API char *config_GetSysPath(vlc_sysdir_t dir, const char *filename)
 307 VLC_USED VLC_MALLOC;
 308
 309 typedef enum vlc_user_dir
 310 {
 311     VLC_HOME_DIR, /* User's home */
 312     VLC_CONFIG_DIR, /* VLC-specific configuration directory */
 313     VLC_USERDATA_DIR, /* VLC-specific data directory */
 314     VLC_CACHE_DIR, /* VLC-specific user cached data directory */
 315     /* Generic directories (same as XDG) */
 316     VLC_DESKTOP_DIR=0x80,
 317     VLC_DOWNLOAD_DIR,
 318     VLC_TEMPLATES_DIR,
 319     VLC_PUBLICSHARE_DIR,
 320     VLC_DOCUMENTS_DIR,
 321     VLC_MUSIC_DIR,
 322     VLC_PICTURES_DIR,
 323     VLC_VIDEOS_DIR,
 324 } vlc_userdir_t;
 325
 326 VLC_API char * config_GetUserDir( vlc_userdir_t ) VLC_USED VLC_MALLOC;
 327
 328 VLC_API void config_AddIntf(const char *);
 329 VLC_API void config_RemoveIntf(const char *);
 330 VLC_API bool config_ExistIntf(const char *) VLC_USED;
 331
 332 /****************************************************************************
 333  * config_chain_t:
 334  ****************************************************************************/
 335 struct config_chain_t
 336 {
 337     config_chain_t *p_next;     /**< Pointer on the next config_chain_t element */
 338
 339     char        *psz_name;      /**< Option name */
 340     char        *psz_value;     /**< Option value */
 341 };
 342
 343 /**
 344  * This function will
 345  * - create all options in the array ppsz_options (var_Create).
 346  * - parse the given linked list of config_chain_t and set the value (var_Set).
 347  *
 348  * The option names will be created by adding the psz_prefix prefix.
 349  */
 350 VLC_API void config_ChainParse( vlc_object_t *, const char *psz_prefix, const char *const *ppsz_options, config_chain_t * );
 351 #define config_ChainParse( a, b, c, d ) config_ChainParse( VLC_OBJECT(a), b, c, d )
 352
 353 /**
 354  * This function will parse a configuration string (psz_opts) and
 355  * - set all options for this module in a chained list (*pp_cfg)
 356  * - returns a pointer on the next module if any.
 357  *
 358  * The string format is
 359  *   module{option=*,option=*}
 360  *
 361  * The options values are unescaped using config_StringUnescape.
 362  */
 363 VLC_API const char *config_ChainParseOptions( config_chain_t **pp_cfg, const char *ppsz_opts );
 364
 365 /**
 366  * This function will parse a configuration string (psz_string) and
 367  * - set the module name (*ppsz_name)
 368  * - set all options for this module in a chained list (*pp_cfg)
 369  * - returns a pointer on the next module if any.
 370  *
 371  * The string format is
 372  *   module{option=*,option=*}[:modulenext{option=*,...}]
 373  *
 374  * The options values are unescaped using config_StringUnescape.
 375  */
 376 VLC_API char *config_ChainCreate( char **ppsz_name, config_chain_t **pp_cfg, const char *psz_string ) VLC_USED VLC_MALLOC;
 377
 378 /**
 379  * This function will release a linked list of config_chain_t
 380  * (Including the head)
 381  */
 382 VLC_API void config_ChainDestroy( config_chain_t * );
 383
 384 /**
 385  * This function will duplicate a linked list of config_chain_t
 386  */
 387 VLC_API config_chain_t * config_ChainDuplicate( const config_chain_t * ) VLC_USED VLC_MALLOC;
 388
 389 /**
 390  * This function will unescape a string in place and will return a pointer on
 391  * the given string.
 392  * No memory is allocated by it (unlike config_StringEscape).
 393  * If NULL is given as parameter nothing will be done (NULL will be returned).
 394  *
 395  * The following sequences will be unescaped (only one time):
 396  * \\ \' and \"
 397  */
 398 VLC_API char * config_StringUnescape( char *psz_string );
 399
 400 /**
 401  * This function will escape a string that can be unescaped by
 402  * config_StringUnescape.
 403  * The returned value is allocated by it. You have to free it once you
 404  * do not need it anymore (unlike config_StringUnescape).
 405  * If NULL is given as parameter nothing will be done (NULL will be returned).
 406  *
 407  * The escaped characters are ' " and \
 408  */
 409 VLC_API char * config_StringEscape( const char *psz_string ) VLC_USED VLC_MALLOC;
 410
 411 # ifdef __cplusplus
 412 }
 413 # endif
 414
 415 /** @} */
 416
 417 #endif /* _VLC_CONFIGURATION_H */