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
union	module_value_t

struct	module_config_t
	Configuration item. More...

struct	config_chain_t

Macros
#define	config_SaveConfigFile(a) config_SaveConfigFile(vlc_object_instance(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.

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 , VLC_SNAPSHOTS_DIR }

Functions
int	config_GetType (const char *name)
	Gets a configuration item type.

int64_t	config_GetInt (const char *name)
	Gets an integer configuration item's value.

void	config_PutInt (const char *name, int64_t val)
	Sets an integer configuration item's value.

float	config_GetFloat (const char *name)
	Gets a floating point configuration item's value.

void	config_PutFloat (const char *name, float val)
	Sets a floating point configuration item's value.

char *	config_GetPsz (const char *name)
	Gets a string configuration item's value.

void	config_PutPsz (const char name, const char val)
	Sets a string configuration item's value.

ssize_t	config_GetIntChoices (const char , int64_t values, char **texts)
	Enumerates integer configuration choices.

ssize_t	config_GetPszChoices (const char , char values, char *texts)
	Determines a list of suggested values for a string configuration item.

int	config_SaveConfigFile (libvlc_int_t *)
	Saves the in-memory configuration into a file.

void	config_ResetAll (void)
	Resets the configuration.

module_config_t *	config_FindConfig (const char *name)
	Looks up a configuration item.

char *	config_GetSysPath (vlc_sysdir_t dir, const char *filename)
	Gets an installation directory.

char *	config_GetUserDir (vlc_userdir_t)

void	config_AddIntf (const char *)

void	config_RemoveIntf (const char *)

bool	config_ExistIntf (const char *)

void	config_ChainParse (vlc_object_t , const char psz_prefix, const char const ppsz_options, const config_chain_t *)
	This function will.

const char *	config_ChainParseOptions (config_chain_t *pp_cfg, const char ppsz_opts)
	This function will parse a configuration string (psz_opts) and.

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.

void	config_ChainDestroy (config_chain_t *)
	This function will release a linked list of config_chain_t (Including the head)

config_chain_t *	config_ChainDuplicate (const config_chain_t *)
	This function will duplicate a linked list of config_chain_t.

char *	config_StringUnescape (char *psz_string)
	This function will unescape a string in place and will return a pointer on the given string.

char *	config_StringEscape (const char *psz_string)
	This function will escape a string that can be unescaped by config_StringUnescape.

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,
		d
	)	config_ChainParse( VLC_OBJECT(a), b, c, d )

◆ config_SaveConfigFile

#define config_SaveConfigFile ( a ) config_SaveConfigFile(vlc_object_instance(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

typedef enum vlc_system_dir vlc_sysdir_t

System directory identifiers.

◆ vlc_userdir_t

typedef enum vlc_user_dir vlc_userdir_t

Enumeration Type Documentation

◆ vlc_system_dir

enum 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

enum 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
VLC_SNAPSHOTS_DIR

Function Documentation

◆ config_AddIntf()

void config_AddIntf ( const char * psz_intf )

References asprintf(), config_GetPsz(), and config_PutPsz().

◆ 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(), sout_StreamNew(), vlc_audio_meter_AddPlugin(), vlc_rd_new(), and vlc_sd_Create().

◆ config_ChainDestroy()

void config_ChainDestroy ( config_chain_t * p_cfg )

This function will release a linked list of config_chain_t (Including the head)

References config_chain_t::p_next, config_chain_t::psz_name, and config_chain_t::psz_value.

Referenced by AppendRemapFilter(), ChangeFilters(), demux_FilterChainNew(), filter_chain_AppendFromString(), intf_Create(), intf_DestroyAll(), sout_AccessOutDelete(), sout_MuxDelete(), sout_StreamChainNew(), sout_StreamDelete(), vlc_audio_meter_AddPlugin(), vlc_audio_meter_RemovePlugin(), vlc_rd_new(), vlc_rd_release(), and vlc_sd_Destroy().

◆ 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	(	vlc_object_t *	p_this,
		const char *	psz_prefix,
		const char const	ppsz_options,
		const config_chain_t *	cfg
	)

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.

References vlc_value_t::b_bool, CONFIG_CLASS, config_FindConfig(), config_GetType(), CONFIG_ITEM_BOOL, CONFIG_ITEM_FLOAT, CONFIG_ITEM_INTEGER, CONFIG_ITEM_STRING, module_value_t::f, vlc_value_t::f_float, module_value_t::i, vlc_value_t::i_int, module_config_t::i_type, i_type, vlc_param::item, module_config_t::max, module_config_t::min, msg_Dbg, msg_Err, msg_Warn, name, vlc_param::obsolete, config_chain_t::p_next, config_chain_t::psz_name, psz_name, vlc_value_t::psz_string, config_chain_t::psz_value, strtoll(), var_Change(), var_Create(), var_Get(), var_Set(), vlc_atof_c(), vlc_param_Find(), VLC_VAR_DOINHERIT, and VLC_VAR_SETMINMAX.

◆ 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

name	Configuration item name

Returns: The internal structure, or NULL if not found.

References vlc_param::item, name, unlikely, and vlc_param_Find().

Referenced by aout_New(), config_ChainParse(), config_LoadCmdLine(), 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

name	Configuration 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 vlc_param::f, module_config_t::i_type, IsConfigFloatType, vlc_param::item, name, vlc_param::value, and vlc_param_Find().

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

name	Configuration 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 vlc_param::i, module_config_t::i_type, IsConfigIntegerType, vlc_param::item, name, vlc_param::value, and vlc_param_Find().

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

values	pointer to a table of integer values [OUT]
texts	pointer 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

name	Configuration 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 module_config_t::i_type, IsConfigStringType, vlc_param::item, name, vlc_param::str, strdup(), vlc_param::value, vlc_param_Find(), vlc_rcu_read_lock(), and vlc_rcu_read_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

values	pointer to a table of value strings [OUT]
texts	pointer 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

dir	identifier of the directory (see vlc_sysdir_t)
filename	name 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_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

name	Configuration item name

Returns: The configuration item type or 0 if not found.

References CONFIG_CLASS, CONFIG_ITEM_BOOL, CONFIG_ITEM_FLOAT, CONFIG_ITEM_INTEGER, CONFIG_ITEM_STRING, module_config_t::i_type, vlc_param::item, name, vlc_param_Find(), 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 )

References ARRAY_SIZE, getenv(), platform_GetUserDir(), strdup(), and userdir_to_env.

Referenced by ArtCacheGetDirPath(), config_GetConfigFile(), config_OpenConfigFile(), config_PrepareDir(), EsOutSetRecord(), GetDirByItemUIDs(), platform_GetUserDir(), and vout_snapshot_GetDirectory().

◆ 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

name	Configuration item name
val	New value

References config_dirty, config_lock, module_value_t::f, vlc_param::f, f_value, module_config_t::i_type, IsConfigFloatType, vlc_param::item, module_config_t::max, module_config_t::min, name, module_config_t::value, vlc_param::value, vlc_mutex_lock(), vlc_mutex_unlock(), and vlc_param_Find().

◆ 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

name	Configuration item name
val	New value

References config_dirty, config_lock, module_value_t::i, vlc_param::i, module_config_t::i_type, i_value, IsConfigIntegerType, vlc_param::item, module_config_t::max, module_config_t::min, name, module_config_t::value, vlc_param::value, vlc_mutex_lock(), vlc_mutex_unlock(), and vlc_param_Find().

◆ 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

name	Configuration item name
val	New value (will be copied)

Bug:: This function allocates memory but errors cannot be detected.

References config_dirty, config_lock, psz_name, psz_value, vlc_mutex_lock(), vlc_mutex_unlock(), vlc_param_Find(), and vlc_param_SetString().

Referenced by config_AddIntf(), and config_RemoveIntf().

◆ config_RemoveIntf()

void config_RemoveIntf ( const char * psz_intf )

References asprintf(), config_GetPsz(), and config_PutPsz().

◆ config_ResetAll()

void config_ResetAll ( void )

Resets the configuration.

This function resets all configuration items to their respective compile-time default value.

References config_dirty, config_lock, module_value_t::f, vlc_param::f, module_value_t::i, vlc_param::i, module_config_t::i_type, IsConfigFloatType, IsConfigIntegerType, IsConfigStringType, vlc_param::item, vlc_plugin_t::next, module_config_t::orig, p, module_value_t::psz, module_config_t::value, vlc_param::value, vlc_mutex_lock(), vlc_mutex_unlock(), vlc_param_SetString(), and vlc_plugins.

◆ config_SaveConfigFile()

int config_SaveConfigFile ( libvlc_int_t * p_this )

Saves the in-memory configuration into a file.

Returns: 0 on success, -1 on error.

References asprintf(), CONFIG_CLASS, config_GetConfigFile(), CONFIG_ITEM, CONFIG_ITEM_BOOL, config_PrepareDir(), config_Write(), module_value_t::f, freelocale(), getpid(), module_value_t::i, module_config_t::i_type, IsConfigFloatType, IsConfigIntegerType, IsConfigStringType, LC_NUMERIC_MASK, lock, module_get_object(), msg_Err, N_, newlocale(), vlc_plugin_t::next, module_config_t::orig, p, module_value_t::psz, module_t::psz_longname, module_config_t::psz_name, module_config_t::psz_text, uselocale(), vlc_close(), vlc_mutex_lock(), vlc_mutex_unlock(), vlc_open(), vlc_plugins, vlc_rcu_read_lock(), vlc_rcu_read_unlock(), vlc_rename(), VLC_STATIC_MUTEX, vlc_strerror_c(), and vlc_unlink().

◆ 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, vlc_param::str, 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().

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ config_ChainParse

◆ config_SaveConfigFile

Typedef Documentation

◆ vlc_integer_list_cb

◆ vlc_string_list_cb

◆ vlc_sysdir_t

◆ vlc_userdir_t

Enumeration Type Documentation

◆ vlc_system_dir

◆ vlc_user_dir

Function Documentation

◆ config_AddIntf()

◆ config_ChainCreate()

◆ config_ChainDestroy()

◆ config_ChainDuplicate()

◆ config_ChainParse()

◆ config_ChainParseOptions()

◆ config_ExistIntf()

◆ config_FindConfig()

◆ config_GetFloat()

◆ config_GetInt()

◆ config_GetIntChoices()

◆ config_GetPsz()

◆ config_GetPszChoices()

◆ config_GetSysPath()

◆ config_GetType()

◆ config_GetUserDir()

◆ config_PutFloat()

◆ config_PutInt()

◆ config_PutPsz()

◆ config_RemoveIntf()

◆ config_ResetAll()

◆ config_SaveConfigFile()

◆ config_StringEscape()

◆ config_StringUnescape()