VLC  4.0.0-dev
Files | Data Structures | Macros | Typedefs | Enumerations | Functions

VLC provides a simple name-value dictionary for user settings. More...

Collaboration diagram for User settings:

Files

file  vlc_configuration.h
 This file describes the programming interface for the configuration module.
 

Data Structures

struct  config_category_t
 
union  module_value_t
 
struct  module_config_t
 Configuration item. More...
 
struct  config_chain_t
 

Macros

#define config_SaveConfigFile(a)   config_SaveConfigFile(VLC_OBJECT(a))
 
#define config_ChainParse(a, b, c, d)   config_ChainParse( VLC_OBJECT(a), b, c, d )
 

Typedefs

typedef int(* vlc_string_list_cb) (const char *, char ***, char ***)
 
typedef int(* vlc_integer_list_cb) (const char *, int64_t **, char ***)
 
typedef enum vlc_system_dir vlc_sysdir_t
 System directory identifiers. More...
 
typedef enum vlc_user_dir vlc_userdir_t
 

Enumerations

enum  vlc_system_dir {
  VLC_PKG_DATA_DIR , VLC_PKG_LIB_DIR , VLC_PKG_LIBEXEC_DIR , VLC_PKG_INCLUDE_DIR_RESERVED ,
  VLC_SYSDATA_DIR , VLC_LIB_DIR , VLC_LIBEXEC_DIR , VLC_INCLUDE_DIR_RESERVED ,
  VLC_LOCALE_DIR
}
 System directory identifiers. More...
 
enum  vlc_user_dir {
  VLC_HOME_DIR , VLC_CONFIG_DIR , VLC_USERDATA_DIR , VLC_CACHE_DIR ,
  VLC_DESKTOP_DIR =0x80 , VLC_DOWNLOAD_DIR , VLC_TEMPLATES_DIR , VLC_PUBLICSHARE_DIR ,
  VLC_DOCUMENTS_DIR , VLC_MUSIC_DIR , VLC_PICTURES_DIR , VLC_VIDEOS_DIR
}
 

Functions

int config_GetType (const char *name)
 Gets a configuration item type. More...
 
int64_t config_GetInt (const char *name)
 Gets an integer configuration item's value. More...
 
void config_PutInt (const char *name, int64_t val)
 Sets an integer configuration item's value. More...
 
float config_GetFloat (const char *name)
 Gets a floating point configuration item's value. More...
 
void config_PutFloat (const char *name, float val)
 Sets a floating point configuration item's value. More...
 
char * config_GetPsz (const char *name)
 Gets a string configuration item's value. More...
 
void config_PutPsz (const char *name, const char *val)
 Sets a string configuration item's value. More...
 
ssize_t config_GetIntChoices (const char *, int64_t **values, char ***texts)
 Enumerates integer configuration choices. More...
 
ssize_t config_GetPszChoices (const char *, char ***values, char ***texts)
 Determines a list of suggested values for a string configuration item. More...
 
int config_SaveConfigFile (_Generic((vlc_object_t *) ->obj, struct vlc_object_marker *:(vlc_object_t *), default:(&((vlc_object_t *) ->obj))))
 
void config_ResetAll (void)
 Resets the configuration. More...
 
module_config_tconfig_FindConfig (const char *name)
 Looks up a configuration item. More...
 
char * config_GetSysPath (vlc_sysdir_t dir, const char *filename)
 Gets an installation directory. More...
 
char * config_GetUserDir (vlc_userdir_t)
 
void config_AddIntf (const char *)
 
void config_RemoveIntf (const char *)
 
bool config_ExistIntf (const char *)
 
void config_ChainParse (_Generic((vlc_object_t *) ->obj, struct vlc_object_marker *:(vlc_object_t *), default:(&((vlc_object_t *) ->obj))), const char *psz_prefix, const char *const *ppsz_options, const config_chain_t *)
 This function will. More...
 
const char * config_ChainParseOptions (config_chain_t **pp_cfg, const char *ppsz_opts)
 This function will parse a configuration string (psz_opts) and. More...
 
char * config_ChainCreate (char **ppsz_name, config_chain_t **pp_cfg, const char *psz_string)
 This function will parse a configuration string (psz_string) and. More...
 
void config_ChainDestroy (config_chain_t *)
 This function will release a linked list of config_chain_t (Including the head) More...
 
config_chain_tconfig_ChainDuplicate (const config_chain_t *)
 This function will duplicate a linked list of config_chain_t. More...
 
char * config_StringUnescape (char *psz_string)
 This function will unescape a string in place and will return a pointer on the given string. More...
 
char * config_StringEscape (const char *psz_string)
 This function will escape a string that can be unescaped by config_StringUnescape. More...
 

Detailed Description

VLC provides a simple name-value dictionary for user settings.

Those settings are per-user per-system - they are shared by all LibVLC instances in a single process, and potentially other processes as well.

Each name-value pair is called a configuration item.

Macro Definition Documentation

◆ config_ChainParse

#define config_ChainParse (   a,
  b,
  c,
 
)    config_ChainParse( VLC_OBJECT(a), b, c, d )

◆ config_SaveConfigFile

#define config_SaveConfigFile (   a)    config_SaveConfigFile(VLC_OBJECT(a))

Typedef Documentation

◆ vlc_integer_list_cb

typedef int(* vlc_integer_list_cb) (const char *, int64_t **, char ***)

◆ vlc_string_list_cb

typedef int(* vlc_string_list_cb) (const char *, char ***, char ***)

◆ vlc_sysdir_t

System directory identifiers.

◆ vlc_userdir_t

Enumeration Type Documentation

◆ vlc_system_dir

System directory identifiers.

Enumerator
VLC_PKG_DATA_DIR 

Package-specific architecture-independent read-only data directory (e.g.

/usr/local/data/vlc).

VLC_PKG_LIB_DIR 

Package-specific architecture-dependent read-only data directory (e.g.

/usr/local/lib/vlc).

VLC_PKG_LIBEXEC_DIR 

Package-specific executable read-only directory (e.g.

/usr/local/libexec/vlc).

VLC_PKG_INCLUDE_DIR_RESERVED 
VLC_SYSDATA_DIR 

Global architecture-independent read-only data directory (e.g.

/usr/local/data). Available only on some platforms.

VLC_LIB_DIR 

Global architecture-dependent read-only directory (e.g.

/usr/local/lib).

VLC_LIBEXEC_DIR 

Global executable read-only directory (e.g.

/usr/local/libexec).

VLC_INCLUDE_DIR_RESERVED 
VLC_LOCALE_DIR 

Base directory for package read-only locale data.

◆ vlc_user_dir

Enumerator
VLC_HOME_DIR 
VLC_CONFIG_DIR 
VLC_USERDATA_DIR 
VLC_CACHE_DIR 
VLC_DESKTOP_DIR 
VLC_DOWNLOAD_DIR 
VLC_TEMPLATES_DIR 
VLC_PUBLICSHARE_DIR 
VLC_DOCUMENTS_DIR 
VLC_MUSIC_DIR 
VLC_PICTURES_DIR 
VLC_VIDEOS_DIR 

Function Documentation

◆ config_AddIntf()

void config_AddIntf ( const char *  psz_intf)

◆ config_ChainCreate()

char* config_ChainCreate ( char **  ppsz_name,
config_chain_t **  pp_cfg,
const char *  psz_string 
)

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.

References config_ChainParseOptions(), SKIPSPACE, strdup(), and strndup().

Referenced by AppendRemapFilter(), ChangeFilters(), demux_FilterChainNew(), filter_chain_AppendFromString(), intf_Create(), sout_AccessOutNew(), sout_MuxNew(), sout_StreamChainNew(), vlc_audio_meter_AddPlugin(), vlc_rd_new(), and vlc_sd_Create().

◆ config_ChainDestroy()

void config_ChainDestroy ( config_chain_t p_cfg)

◆ config_ChainDuplicate()

config_chain_t* config_ChainDuplicate ( const config_chain_t p_src)

This function will duplicate a linked list of config_chain_t.

References p, config_chain_t::p_next, config_chain_t::psz_name, config_chain_t::psz_value, and strdup().

◆ config_ChainParse()

void config_ChainParse ( _Generic((vlc_object_t *) ->obj, struct vlc_object_marker *:(vlc_object_t *), default:(&((vlc_object_t *) ->obj)))  ,
const char *  psz_prefix,
const char *const *  ppsz_options,
const config_chain_t  
)

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.

◆ config_ChainParseOptions()

const char* config_ChainParseOptions ( config_chain_t **  pp_cfg,
const char *  ppsz_opts 
)

This function will parse a configuration string (psz_opts) and.

  • 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=*}

The options values are unescaped using config_StringUnescape.

References ChainGetValue(), config_chain_t::p_next, config_chain_t::psz_name, config_chain_t::psz_value, SKIPSPACE, and strndup().

Referenced by config_ChainCreate().

◆ config_ExistIntf()

bool config_ExistIntf ( const char *  psz_intf)

References config_GetPsz().

◆ config_FindConfig()

module_config_t* config_FindConfig ( const char *  name)

Looks up a configuration item.

This function looks for the internal representation of a configuration item. Where possible, this should be avoided in favor of more specific function calls.

Parameters
nameConfiguration item name
Returns
The internal structure, or NULL if not found.

References config, confnamecmp(), name, p, and unlikely.

Referenced by aout_New(), config_ChainParse(), config_FindConfigChecked(), config_GetPszChoices(), config_GetType(), config_IsSafe(), config_LoadCmdLine(), config_LoadConfigFile(), and vout_InitInterlacingSupport().

◆ config_GetFloat()

float config_GetFloat ( const char *  name)

Gets a floating point configuration item's value.

This function retrieves the current value of a configuration item of floating point type (CONFIG_ITEM_FLOAT).

Warning
The behaviour is undefined if the configuration item exists but is not of floating point type.
Parameters
nameConfiguration item name
Returns
The configuration item value or -1 if not found.
Bug:
A legitimate floating point value of -1 cannot be distinguished from an error.

References config_FindConfigChecked(), config_lock, module_value_t::f, module_config_t::i_type, IsConfigFloatType, psz_name, module_config_t::value, vlc_rwlock_rdlock(), and vlc_rwlock_unlock().

Referenced by var_Inherit().

◆ config_GetInt()

int64_t config_GetInt ( const char *  name)

Gets an integer configuration item's value.

This function retrieves the current value of a configuration item of integral type (CONFIG_ITEM_INTEGER and CONFIG_ITEM_BOOL).

Warning
The behaviour is undefined if the configuration item exists but is not of integer or boolean type.
Parameters
nameConfiguration item name
Returns
The configuration item value or -1 if not found.
Bug:
A legitimate integer value of -1 cannot be distinguished from an error.

References config_FindConfigChecked(), config_lock, module_value_t::i, module_config_t::i_type, IsConfigIntegerType, psz_name, module_config_t::value, vlc_rwlock_rdlock(), and vlc_rwlock_unlock().

Referenced by var_Inherit().

◆ config_GetIntChoices()

ssize_t config_GetIntChoices ( const char *  ,
int64_t **  values,
char ***  texts 
)

Enumerates integer configuration choices.

Determines a list of suggested values for an integer configuration item.

Parameters
valuespointer to a table of integer values [OUT]
textspointer to a table of descriptions strings [OUT]
Returns
number of choices, or -1 on error
Note
the caller is responsible for calling free() on all descriptions and on both tables. In case of error, both pointers are set to NULL.

◆ config_GetPsz()

char* config_GetPsz ( const char *  name)

Gets a string configuration item's value.

This function retrieves the current value of a configuration item of string type (CONFIG_ITEM_STRING).

Note
The caller must free() the returned pointer (if non-NULL), which is a duplicate of the current value. It is not safe to return a pointer to the current value internally as it can be modified at any time by any other thread.
Warning
The behaviour is undefined if the configuration item exists but is not of string type.
Parameters
nameConfiguration item name
Returns
Normally, a heap-allocated copy of the configuration item value. If the value is the empty string, if the configuration does not exist, or if an error occurs, NULL is returned.
Bug:
The empty string value cannot be distinguished from an error.

References config_FindConfigChecked(), config_lock, module_config_t::i_type, IsConfigStringType, module_value_t::psz, psz_name, psz_value, strdupnull(), module_config_t::value, vlc_rwlock_rdlock(), and vlc_rwlock_unlock().

Referenced by config_AddIntf(), config_ExistIntf(), config_RemoveIntf(), var_Inherit(), and vlc_getProxyUrl().

◆ config_GetPszChoices()

ssize_t config_GetPszChoices ( const char *  ,
char ***  values,
char ***  texts 
)

Determines a list of suggested values for a string configuration item.

Parameters
valuespointer to a table of value strings [OUT]
textspointer to a table of descriptions strings [OUT]
Returns
number of choices, or -1 on error
Note
the caller is responsible for calling free() on all values, on all descriptions and on both tables. In case of error, both pointers are set to NULL.

◆ config_GetSysPath()

char* config_GetSysPath ( vlc_sysdir_t  dir,
const char *  filename 
)

Gets an installation directory.

This function determines one of the installation directory.

Parameters
diridentifier of the directory (see vlc_sysdir_t)
filenamename of a file or other object within the directory (or NULL to obtain the plain directory)
Returns
a heap-allocated string (use free() to release it), or NULL on error

References ARRAY_SIZE, asprintf(), config_GetDataDir(), config_getDataDirReal(), config_GetLibDir(), config_GetLibExecDir(), config_getLibraryDirReal(), config_GetRealDir(), config_GetSysPath(), getenv(), name, strdup(), unlikely, vlc_assert_unreachable, VLC_LIB_DIR, VLC_LIBEXEC_DIR, VLC_LOCALE_DIR, VLC_PKG_DATA_DIR, VLC_PKG_LIB_DIR, VLC_PKG_LIBEXEC_DIR, and VLC_SYSDATA_DIR.

Referenced by config_GetSysPath(), GetDefaultArtUri(), and vlc_bindtextdomain().

◆ config_GetType()

int config_GetType ( const char *  name)

Gets a configuration item type.

This function checks the type of configuration item by name.

Parameters
nameConfiguration item name
Returns
The configuration item type or 0 if not found.

References CONFIG_CLASS, config_FindConfig(), CONFIG_ITEM_BOOL, CONFIG_ITEM_FLOAT, CONFIG_ITEM_INTEGER, CONFIG_ITEM_STRING, module_config_t::i_type, psz_name, VLC_VAR_BOOL, VLC_VAR_FLOAT, VLC_VAR_INTEGER, and VLC_VAR_STRING.

Referenced by config_ChainParse(), filter_AddProxyCallbacks(), var_OptionParse(), and vout_Create().

◆ config_GetUserDir()

char* config_GetUserDir ( vlc_userdir_t  type)

◆ config_PutFloat()

void config_PutFloat ( const char *  name,
float  val 
)

Sets a floating point configuration item's value.

This function changes the current value of a configuration item of floating point type (CONFIG_ITEM_FLOAT).

Warning
The behaviour is undefined if the configuration item exists but is not of floating point type.
Note
If no configuration item by the specified exist, the function has no effects.
Parameters
nameConfiguration item name
valNew value

References config_dirty, config_FindConfigChecked(), config_lock, module_value_t::f, f_value, module_config_t::i_type, IsConfigFloatType, module_config_t::max, module_config_t::min, psz_name, module_config_t::value, vlc_rwlock_unlock(), and vlc_rwlock_wrlock().

◆ config_PutInt()

void config_PutInt ( const char *  name,
int64_t  val 
)

Sets an integer configuration item's value.

This function changes the current value of a configuration item of integral type (CONFIG_ITEM_INTEGER and CONFIG_ITEM_BOOL).

Warning
The behaviour is undefined if the configuration item exists but is not of integer or boolean type.
Note
If no configuration item by the specified exist, the function has no effects.
Parameters
nameConfiguration item name
valNew value

References config_dirty, config_FindConfigChecked(), config_lock, module_value_t::i, module_config_t::i_type, i_value, IsConfigIntegerType, module_config_t::max, module_config_t::min, psz_name, module_config_t::value, vlc_rwlock_unlock(), and vlc_rwlock_wrlock().

◆ config_PutPsz()

void config_PutPsz ( const char *  name,
const char *  val 
)

Sets a string configuration item's value.

This function changes the current value of a configuration item of string type (e.g. CONFIG_ITEM_STRING).

Warning
The behaviour is undefined if the configuration item exists but is not of a string type.
Note
If no configuration item by the specified exist, the function has no effects.
Parameters
nameConfiguration item name
valNew value (will be copied)
Bug:
This function allocates memory but errors cannot be detected.

References config_dirty, config_FindConfigChecked(), config_lock, module_config_t::i_type, IsConfigStringType, module_value_t::psz, psz_name, psz_value, strdup(), module_config_t::value, vlc_rwlock_unlock(), and vlc_rwlock_wrlock().

Referenced by config_AddIntf(), and config_RemoveIntf().

◆ config_RemoveIntf()

void config_RemoveIntf ( const char *  psz_intf)

◆ config_ResetAll()

void config_ResetAll ( void  )

◆ config_SaveConfigFile()

int config_SaveConfigFile ( _Generic((vlc_object_t *) ->obj, struct vlc_object_marker *:(vlc_object_t *), default:(&((vlc_object_t *) ->obj)))  )

◆ config_StringEscape()

char* config_StringEscape ( const 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 \

References IsEscapeNeeded(), p, and unlikely.

Referenced by EsOutSetRecord().

◆ config_StringUnescape()

char* config_StringUnescape ( char *  psz_string)

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 "

References IsEscape().

Referenced by ChainGetValue().