variables.c File Reference

Include dependency graph for variables.c:

Data Structures
struct	callback_entry_t

Functions
static int	CmpBool (vlc_value_t v, vlc_value_t w)
static int	CmpInt (vlc_value_t v, vlc_value_t w)
static int	CmpTime (vlc_value_t v, vlc_value_t w)
static int	CmpString (vlc_value_t v, vlc_value_t w)
static int	CmpFloat (vlc_value_t v, vlc_value_t w)
static int	CmpAddress (vlc_value_t v, vlc_value_t w)
static void	DupDummy (vlc_value_t *p_val)
static void	DupString (vlc_value_t *p_val)
static void	FreeDummy (vlc_value_t *p_val)
static void	FreeString (vlc_value_t *p_val)
static void	FreeList (vlc_value_t *p_val)
static void	WaitUnused (vlc_object_t *p_this, variable_t *p_var)
	Waits until the variable is inactive (i.e.
static void	CheckValue (variable_t *, vlc_value_t *)
static int	TriggerCallback (vlc_object_t *, variable_t *, const char *, vlc_value_t)
static int	varcmp (const void *a, const void *b)
static variable_t *	Lookup (vlc_object_t *obj, const char *psz_name)
static void	Destroy (variable_t *p_var)
int	var_Create (((vlc_object_t *)(vlc_object_t *p_this)), const char *psz_name, int i_type)
	Initialize a vlc variable.
int	var_Destroy (((vlc_object_t *)(vlc_object_t *p_this)), const char *psz_name)
	Destroy a vlc variable.
static void	CleanupVar (void *var)
void	var_DestroyAll (vlc_object_t *obj)
int	var_Change (((vlc_object_t *)(vlc_object_t *p_this)), const char *psz_name, int i_action, vlc_value_t *p_val, vlc_value_t *p_val2)
	Perform an action on a variable.
int	var_GetAndSet (vlc_object_t *p_this, const char *psz_name, int i_action, vlc_value_t *p_val)
	Perform a Get and Set on a variable.
int	var_Type (((vlc_object_t *)(vlc_object_t *p_this)), const char *psz_name)
	Request a variable's type.
int	var_SetChecked (((vlc_object_t *)(vlc_object_t *p_this)), const char *psz_name, int expected_type, vlc_value_t val)
int	var_Set (((vlc_object_t *)(vlc_object_t *p_this)), const char *psz_name, vlc_value_t val)
	Set a variable's value.
int	var_GetChecked (((vlc_object_t *)(vlc_object_t *p_this)), const char *psz_name, int expected_type, vlc_value_t *p_val)
int	var_Get (((vlc_object_t *)(vlc_object_t *p_this)), const char *psz_name, vlc_value_t *p_val)
	Get a variable's value.
int	var_AddCallback (((vlc_object_t *)(vlc_object_t *p_this)), const char *psz_name, vlc_callback_t pf_callback, void *p_data)
	Register a callback in a variable.
int	var_DelCallback (((vlc_object_t *)(vlc_object_t *p_this)), const char *psz_name, vlc_callback_t pf_callback, void *p_data)
	Remove a callback from a variable.
int	var_TriggerCallback (((vlc_object_t *)(vlc_object_t *p_this)), const char *psz_name)
	Trigger callback on a variable.
void	var_OptionParse (vlc_object_t *p_obj, const char *psz_option, bool trusted)
	Parse a stringified option This function parse a string option and create the associated object variable The option must be of the form "[no[-]]foo[=bar]" where foo is the option name and bar is the value of the option.
int	var_LocationParse (((vlc_object_t *)(vlc_object_t *obj)), const char *mrl, const char *pref)
	Parses a set of colon-separated or semicolon-separated <variable name>="">=pairs.
int	var_Inherit (vlc_object_t *p_this, const char *psz_name, int i_type, vlc_value_t *p_val)
	Finds the value of a variable.
int()	var_InheritURational (vlc_object_t *object, unsigned *num, unsigned *den, const char *var)
	It inherits a string as an unsigned rational number (it also accepts basic float number).
int	var_Command (((vlc_object_t *)(vlc_object_t *p_this)), const char *psz_name, const char *psz_cmd, const char *psz_arg, char **psz_msg)
void	var_FreeList (vlc_value_t *p_val, vlc_value_t *p_val2)
	Free a list and the associated strings.

Variables
static struct variable_ops_t	void_ops = { NULL, DupDummy, FreeDummy, }
static struct variable_ops_t	addr_ops = { CmpAddress, DupDummy, FreeDummy, }
static struct variable_ops_t	bool_ops = { CmpBool, DupDummy, FreeDummy, }
static struct variable_ops_t	float_ops = { CmpFloat, DupDummy, FreeDummy, }
static struct variable_ops_t	int_ops = { CmpInt, DupDummy, FreeDummy, }
static struct variable_ops_t	string_ops = { CmpString, DupString, FreeString, }
static struct variable_ops_t	time_ops = { CmpTime, DupDummy, FreeDummy, }
static struct variable_ops_t	coords_ops = { NULL, DupDummy, FreeDummy, }

Function Documentation

static void CheckValue ( variable_t *  p_var, vlc_value_t *  p_val  )

static

References variable_t::choices, vlc_value_t::f_float, vlc_list_t::i_count, variable_t::i_default, vlc_value_t::i_int, variable_t::i_type, variable_t::max, variable_t::min, variable_t::ops, vlc_list_t::p_values, variable_ops_t::pf_cmp, variable_ops_t::pf_dup, variable_ops_t::pf_free, variable_t::step, VLC_VAR_FLOAT, VLC_VAR_HASCHOICE, VLC_VAR_HASMAX, VLC_VAR_HASMIN, VLC_VAR_HASSTEP, VLC_VAR_INTEGER, VLC_VAR_TIME, and VLC_VAR_TYPE.

Referenced by var_Change(), var_GetAndSet(), and var_SetChecked().

static void CleanupVar ( void *  var )

static

References Destroy().

Referenced by var_DestroyAll().

static int CmpAddress ( vlc_value_t  v, vlc_value_t  w  )

static

References vlc_value_t::p_address.

static int CmpBool ( vlc_value_t  v, vlc_value_t  w  )

static

References vlc_value_t::b_bool.

static int CmpFloat ( vlc_value_t  v, vlc_value_t  w  )

static

References vlc_value_t::f_float.

static int CmpInt ( vlc_value_t  v, vlc_value_t  w  )

static

References vlc_value_t::i_int.

static int CmpString ( vlc_value_t  v, vlc_value_t  w  )

static

References vlc_value_t::psz_string.

static int CmpTime ( vlc_value_t  v, vlc_value_t  w  )

static

References vlc_value_t::i_time.

static void Destroy ( variable_t *  p_var )

static

References variable_t::choices, variable_t::choices_text, vlc_list_t::i_count, variable_t::i_entries, variable_t::ops, variable_t::p_entries, vlc_list_t::p_values, callback_entry_t::pf_callback, variable_ops_t::pf_free, variable_t::psz_name, vlc_value_t::psz_string, variable_t::psz_text, and variable_t::val.

Referenced by CleanupVar(), var_Create(), and var_Destroy().

static void DupDummy ( vlc_value_t *  p_val )

static

static void DupString ( vlc_value_t *  p_val )

static

References vlc_value_t::psz_string, and strdup().

static void FreeDummy ( vlc_value_t *  p_val )

static

static void FreeList ( vlc_value_t *  p_val )

static

References FreeString(), vlc_list_t::i_count, vlc_value_t::p_list, vlc_list_t::p_values, vlc_list_t::pi_types, VLC_VAR_CLASS, and VLC_VAR_STRING.

Referenced by var_FreeList().

static void FreeString ( vlc_value_t *  p_val )

static

References vlc_value_t::psz_string.

Referenced by FreeList().

static variable_t* Lookup ( vlc_object_t *  obj, const char *  psz_name  )

static

References tfind(), vlc_object_internals::var_lock, vlc_object_internals::var_root, varcmp(), vlc_assert_locked, and vlc_internals.

Referenced by var_AddCallback(), var_Change(), var_DelCallback(), var_Destroy(), var_GetAndSet(), var_GetChecked(), var_SetChecked(), var_TriggerCallback(), and var_Type().

static int TriggerCallback ( vlc_object_t *  p_this, variable_t *  p_var, const char *  psz_name, vlc_value_t  oldval  )

static

< No error

< No error

References variable_t::b_incallback, variable_t::i_entries, callback_entry_t::p_data, variable_t::p_entries, callback_entry_t::pf_callback, variable_t::val, vlc_object_internals::var_lock, vlc_object_internals::var_wait, vlc_cond_broadcast(), vlc_internals, vlc_mutex_lock(), vlc_mutex_unlock(), and VLC_SUCCESS.

Referenced by var_GetAndSet(), var_SetChecked(), and var_TriggerCallback().

int var_AddCallback	(	((vlc_object_t *)(vlc_object_t *p_this))	,
		const char *	psz_name,
		vlc_callback_t	pf_callback,
		void *	p_data
	)

Register a callback in a variable.

We store a function pointer that will be called upon variable modification.

Parameters

p_this	The object that holds the variable
psz_name	The name of the variable
pf_callback	The function pointer
p_data	A generic pointer that will be passed as the last argument to the callback function.

Warning

The callback function is run in the thread that calls var_Set on the variable. Use proper locking. This thread may not have much time to spare, so keep callback functions short.

< Variable not found

< No error

References variable_t::i_entries, INSERT_ELEM, Lookup(), msg_Err, callback_entry_t::p_data, variable_t::p_entries, callback_entry_t::pf_callback, vlc_object_internals::var_lock, VLC_ENOVAR, vlc_internals, vlc_mutex_lock(), vlc_mutex_unlock(), VLC_SUCCESS, and WaitUnused().

int var_Change	(	((vlc_object_t *)(vlc_object_t *p_this))	,
		const char *	psz_name,
		int	i_action,
		vlc_value_t *	p_val,
		vlc_value_t *	p_val2
	)

Perform an action on a variable.

Parameters

p_this	The object that holds the variable
psz_name	The name of the variable
i_action	The action to perform. Must be one of Variable actions
p_val	First action parameter
p_val2	Second action parameter

< No error

< Variable not found

< Unspecified error

< Unspecified error

< Unspecified error

< Unspecified error

References CheckValue(), variable_t::choices, variable_t::choices_text, vlc_list_t::i_count, variable_t::i_default, vlc_value_t::i_int, variable_t::i_type, INSERT_ELEM, Lookup(), variable_t::max, variable_t::min, variable_t::ops, vlc_value_t::p_list, vlc_list_t::p_values, variable_ops_t::pf_cmp, variable_ops_t::pf_dup, variable_ops_t::pf_free, vlc_list_t::pi_types, vlc_value_t::psz_string, variable_t::psz_text, REMOVE_ELEM, variable_t::step, strdup(), variable_t::val, vlc_object_internals::var_lock, VLC_EGENERIC, VLC_ENOVAR, vlc_internals, vlc_mutex_lock(), vlc_mutex_unlock(), VLC_SUCCESS, VLC_VAR_ADDCHOICE, VLC_VAR_CHOICESCOUNT, VLC_VAR_CLEARCHOICES, VLC_VAR_DELCHOICE, VLC_VAR_GETCHOICES, VLC_VAR_GETLIST, VLC_VAR_GETMAX, VLC_VAR_GETMIN, VLC_VAR_GETSTEP, VLC_VAR_GETTEXT, VLC_VAR_HASMAX, VLC_VAR_HASMIN, VLC_VAR_HASSTEP, VLC_VAR_ISCOMMAND, VLC_VAR_SETDEFAULT, VLC_VAR_SETISCOMMAND, VLC_VAR_SETMAX, VLC_VAR_SETMIN, VLC_VAR_SETSTEP, VLC_VAR_SETTEXT, VLC_VAR_SETVALUE, and VLC_VAR_STRING.

int var_Command	(	((vlc_object_t *)(vlc_object_t *p_this))	,
		const char *	psz_name,
		const char *	psz_cmd,
		const char *	psz_arg,
		char **	psz_msg
	)

< Object not found

< Unspecified error

< Unspecified error

References asprintf(), i_type, vlc_object_t::p_libvlc, strdup(), us_atof(), var_SetBool, var_SetFloat, var_SetInteger, var_SetString, var_Type, VLC_EGENERIC, VLC_ENOOBJ, vlc_error(), vlc_object_find_name, vlc_object_release, VLC_VAR_BOOL, VLC_VAR_CLASS, VLC_VAR_FLOAT, VLC_VAR_INTEGER, VLC_VAR_ISCOMMAND, and VLC_VAR_STRING.

int var_Create	(	((vlc_object_t *)(vlc_object_t *p_this))	,
		const char *	psz_name,
		int	i_type
	)

Initialize a vlc variable.

We hash the given string and insert it into the sorted list. The insertion may require slow memory copies, but think about what we gain in the log(n) lookup phase when setting/getting the variable value!

Parameters

p_this	The object in which to create the variable
psz_name	The name of the variable
i_type	The variables type. Must be one of Variable types combined with zero or more Additive flags

< Not enough memory

< No error

< Not enough memory

References addr_ops, vlc_value_t::b_bool, variable_t::b_incallback, bool_ops, variable_t::choices, variable_t::choices_text, vlc_value_t::coords, coords_ops, Destroy(), vlc_value_t::f_float, float_ops, vlc_list_t::i_count, variable_t::i_default, variable_t::i_entries, vlc_value_t::i_int, vlc_value_t::i_time, variable_t::i_type, variable_t::i_usage, INSERT_ELEM, int_ops, msg_Err, variable_t::ops, vlc_value_t::p_address, variable_t::p_entries, vlc_list_t::p_values, variable_ops_t::pf_dup, variable_t::psz_name, vlc_value_t::psz_string, variable_t::psz_text, strdup(), string_ops, time_ops, tsearch(), unlikely, variable_t::val, var_Inherit(), vlc_object_internals::var_lock, vlc_object_internals::var_root, varcmp(), VLC_ENOMEM, vlc_internals, vlc_mutex_lock(), vlc_mutex_unlock(), VLC_SUCCESS, VLC_VAR_ADDRESS, VLC_VAR_BOOL, VLC_VAR_CLASS, VLC_VAR_COORDS, VLC_VAR_DOINHERIT, VLC_VAR_FLOAT, VLC_VAR_HASCHOICE, VLC_VAR_INTEGER, VLC_VAR_ISCOMMAND, VLC_VAR_STRING, VLC_VAR_TIME, VLC_VAR_VOID, void_ops, vlc_value_t::x, and vlc_value_t::y.

int var_DelCallback	(	((vlc_object_t *)(vlc_object_t *p_this))	,
		const char *	psz_name,
		vlc_callback_t	pf_callback,
		void *	p_data
	)

Remove a callback from a variable.

pf_callback and p_data have to be given again, because different objects might have registered the same callback function.

< Variable not found

< Unspecified error

< No error

References variable_t::i_entries, Lookup(), callback_entry_t::p_data, variable_t::p_entries, callback_entry_t::pf_callback, REMOVE_ELEM, vlc_object_internals::var_lock, VLC_EGENERIC, VLC_ENOVAR, vlc_internals, vlc_mutex_lock(), vlc_mutex_unlock(), VLC_SUCCESS, and WaitUnused().

int var_Destroy	(	((vlc_object_t *)(vlc_object_t *p_this))	,
		const char *	psz_name
	)

Destroy a vlc variable.

Look for the variable and destroy it if it is found. As in var_Create we do a call to memmove() but we have performance counterparts elsewhere.

Parameters

p_this	The object that holds the variable
psz_name	The name of the variable

< Variable not found

< No error

References Destroy(), variable_t::i_usage, Lookup(), tdelete(), vlc_object_internals::var_lock, vlc_object_internals::var_root, varcmp(), VLC_ENOVAR, vlc_internals, vlc_mutex_lock(), vlc_mutex_unlock(), VLC_SUCCESS, and WaitUnused().

void var_DestroyAll

(

vlc_object_t *

obj

)

References CleanupVar(), tdestroy(), vlc_object_internals::var_root, and vlc_internals.

Referenced by vlc_object_destroy().

int var_Get	(	((vlc_object_t *)(vlc_object_t *p_this))	,
		const char *	psz_name,
		vlc_value_t *	p_val
	)

Get a variable's value.

Parameters

p_this	The object that holds the variable
psz_name	The name of the variable
p_val	Pointer to a vlc_value_t that will hold the variable's value after the function is finished

References var_GetChecked.

int var_GetChecked	(	((vlc_object_t *)(vlc_object_t *p_this))	,
		const char *	psz_name,
		int	expected_type,
		vlc_value_t *	p_val
	)

< No error

< Variable not found

References variable_t::i_type, Lookup(), variable_t::ops, variable_ops_t::pf_dup, variable_t::val, vlc_object_internals::var_lock, VLC_ENOVAR, vlc_internals, vlc_mutex_lock(), vlc_mutex_unlock(), VLC_SUCCESS, VLC_VAR_CLASS, and VLC_VAR_VOID.

int() var_InheritURational	(	vlc_object_t *	object,
		unsigned *	num,
		unsigned *	den,
		const char *	var
	)

It inherits a string as an unsigned rational number (it also accepts basic float number).

It returns an error if the rational number cannot be parsed (0/0 is valid). The rational is already reduced.

< No error

< Unspecified error

References us_atof(), var_InheritString, VLC_EGENERIC, VLC_SUCCESS, and vlc_ureduce().

int var_LocationParse	(	((vlc_object_t *)(vlc_object_t *obj))	,
		const char *	mrl,
		const char *	pref
	)

Parses a set of colon-separated or semicolon-separated <variable name>="">=pairs.

Some access (or access_demux) plugins uses this scheme in media resource location.

Note

Only trusted/safe variables are allowed. This is intended.

Warning

Only use this for plugins implementing VLC-specific resource location schemes. This would not make any sense for standardized ones.

Parameters

obj	VLC object on which to set variables (and emit error messages)
mrl	string to parse
pref	prefix to prepend to option names in the string

Returns

VLC_ENOMEM on error, VLC_SUCCESS on success.

< No error

< Not enough memory

References likely, var_OptionParse(), VLC_ENOMEM, and VLC_SUCCESS.

void var_OptionParse	(	vlc_object_t *	p_obj,
		const char *	psz_option,
		bool	trusted
	)

Parse a stringified option This function parse a string option and create the associated object variable The option must be of the form "[no[-]]foo[=bar]" where foo is the option name and bar is the value of the option.

Parameters

p_obj	the object in which the variable must be created
psz_option	the option to parse
trusted	whether the option is set by a trusted input or not

Returns

nothing

References vlc_value_t::b_bool, config_GetType, config_IsSafe(), vlc_value_t::f_float, vlc_value_t::i_int, i_type, msg_Err, psz_name, vlc_value_t::psz_string, psz_value, strdup(), strtoll(), us_atof(), var_Create, var_Set, VLC_VAR_BOOL, VLC_VAR_FLOAT, VLC_VAR_INTEGER, and VLC_VAR_STRING.

Referenced by Create(), and var_LocationParse().

int var_Set	(	((vlc_object_t *)(vlc_object_t *p_this))	,
		const char *	psz_name,
		vlc_value_t	val
	)

Set a variable's value.

Parameters

p_this	The object that hold the variable
psz_name	The name of the variable
val	the value to set

References var_SetChecked.

int var_SetChecked	(	((vlc_object_t *)(vlc_object_t *p_this))	,
		const char *	psz_name,
		int	expected_type,
		vlc_value_t	val
	)

< No error

< Variable not found

References CheckValue(), variable_t::i_type, Lookup(), variable_t::ops, variable_ops_t::pf_dup, variable_ops_t::pf_free, TriggerCallback(), variable_t::val, vlc_object_internals::var_lock, VLC_ENOVAR, vlc_internals, vlc_mutex_lock(), vlc_mutex_unlock(), VLC_SUCCESS, VLC_VAR_CLASS, VLC_VAR_VOID, and WaitUnused().

int var_TriggerCallback	(	((vlc_object_t *)(vlc_object_t *p_this))	,
		const char *	psz_name
	)

Trigger callback on a variable.

Parameters

p_this	The object that hold the variable
psz_name	The name of the variable

< Variable not found

References Lookup(), TriggerCallback(), variable_t::val, vlc_object_internals::var_lock, VLC_ENOVAR, vlc_internals, vlc_mutex_lock(), vlc_mutex_unlock(), and WaitUnused().

int var_Type	(	((vlc_object_t *)(vlc_object_t *p_this))	,
		const char *	psz_name
	)

Request a variable's type.

Returns

The variable type if it exists, or 0 if the variable could not be found.

See Also

Variable types

References variable_t::i_type, i_type, Lookup(), vlc_object_internals::var_lock, vlc_internals, vlc_mutex_lock(), and vlc_mutex_unlock().

static int varcmp ( const void *  a, const void *  b  )

static

References variable_t::psz_name.

Referenced by Lookup(), var_Create(), and var_Destroy().

static void WaitUnused ( vlc_object_t *  p_this, variable_t *  p_var  )

static

Waits until the variable is inactive (i.e.

not executing a callback)

References variable_t::b_incallback, mutex_cleanup_push, vlc_object_internals::var_lock, vlc_object_internals::var_wait, vlc_cleanup_pop, vlc_cond_wait(), and vlc_internals.

Referenced by var_AddCallback(), var_DelCallback(), var_Destroy(), var_GetAndSet(), var_SetChecked(), and var_TriggerCallback().

Variable Documentation

struct variable_ops_t addr_ops = { CmpAddress, DupDummy, FreeDummy, }

static

Referenced by var_Create().

struct variable_ops_t bool_ops = { CmpBool, DupDummy, FreeDummy, }

static

Referenced by var_Create().

struct variable_ops_t coords_ops = { NULL, DupDummy, FreeDummy, }

static

Referenced by var_Create().

struct variable_ops_t float_ops = { CmpFloat, DupDummy, FreeDummy, }

static

Referenced by var_Create().

struct variable_ops_t int_ops = { CmpInt, DupDummy, FreeDummy, }

static

Referenced by var_Create().

struct variable_ops_t string_ops = { CmpString, DupString, FreeString, }

static

Referenced by var_Create().

struct variable_ops_t time_ops = { CmpTime, DupDummy, FreeDummy, }

static

Referenced by var_Create().

struct variable_ops_t void_ops = { NULL, DupDummy, FreeDummy, }

static

Referenced by var_Create().