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