[vlc-devel] [PATCH 3/5] variables: move documentation to headers
Thomas Guillem
thomas at gllm.fr
Thu Nov 3 10:16:49 CET 2016
---
include/vlc_variables.h | 151 +++++++++++++++++++++++++++++++++++++++++++++---
src/libvlc.h | 13 +++++
src/misc/variables.c | 148 -----------------------------------------------
3 files changed, 157 insertions(+), 155 deletions(-)
diff --git a/include/vlc_variables.h b/include/vlc_variables.h
index f931fac..e68e723 100644
--- a/include/vlc_variables.h
+++ b/include/vlc_variables.h
@@ -118,49 +118,163 @@ enum {
/*****************************************************************************
* Prototypes
*****************************************************************************/
+
+/**
+ * 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!
+ *
+ * \param p_this The object in which to create the variable
+ * \param psz_name The name of the variable
+ * \param i_type The variables type. Must be one of \ref var_type combined with
+ * zero or more \ref var_flags
+ */
VLC_API int var_Create( vlc_object_t *, const char *, int );
#define var_Create(a,b,c) var_Create( VLC_OBJECT(a), b, c )
+/**
+ * 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.
+ *
+ * \param p_this The object that holds the variable
+ * \param psz_name The name of the variable
+ */
VLC_API void var_Destroy( vlc_object_t *, const char * );
#define var_Destroy(a,b) var_Destroy( VLC_OBJECT(a), b )
+/**
+ * Perform an action on a variable
+ *
+ * \param p_this The object that holds the variable
+ * \param psz_name The name of the variable
+ * \param i_action The action to perform. Must be one of \ref var_action
+ * \param p_val First action parameter
+ * \param p_val2 Second action parameter
+ */
VLC_API int var_Change( vlc_object_t *, const char *, int, vlc_value_t *, vlc_value_t * );
#define var_Change(a,b,c,d,e) var_Change( VLC_OBJECT(a), b, c, d, e )
+/**
+ * Request a variable's type
+ *
+ * \return The variable type if it exists, or 0 if the
+ * variable could not be found.
+ * \see \ref var_type
+ */
VLC_API int var_Type( vlc_object_t *, const char * ) VLC_USED;
#define var_Type(a,b) var_Type( VLC_OBJECT(a), b )
+/**
+ * Set a variable's value
+ *
+ * \param p_this The object that hold the variable
+ * \param psz_name The name of the variable
+ * \param val the value to set
+ */
VLC_API int var_Set( vlc_object_t *, const char *, vlc_value_t );
#define var_Set(a,b,c) var_Set( VLC_OBJECT(a), b, c )
+/**
+ * Get a variable's value
+ *
+ * \param p_this The object that holds the variable
+ * \param psz_name The name of the variable
+ * \param p_val Pointer to a vlc_value_t that will hold the variable's value
+ * after the function is finished
+ */
VLC_API int var_Get( vlc_object_t *, const char *, vlc_value_t * );
#define var_Get(a,b,c) var_Get( VLC_OBJECT(a), b, c )
VLC_API int var_SetChecked( vlc_object_t *, const char *, int, vlc_value_t );
#define var_SetChecked(o,n,t,v) var_SetChecked(VLC_OBJECT(o),n,t,v)
+
VLC_API int var_GetChecked( vlc_object_t *, const char *, int, vlc_value_t * );
#define var_GetChecked(o,n,t,v) var_GetChecked(VLC_OBJECT(o),n,t,v)
+
+/**
+ * Perform a Get and Set on a variable
+ *
+ * \param p_this: The object that hold the variable
+ * \param psz_name: the name of the variable
+ * \param i_action: the action to perform
+ * \param p_val: The action parameter
+ * \return vlc error codes
+ */
VLC_API int var_GetAndSet( vlc_object_t *, const char *, int, vlc_value_t * );
+/**
+ * Finds the value of a variable. If the specified object does not hold a
+ * variable with the specified name, try the parent object, and iterate until
+ * the top of the tree. If no match is found, the value is read from the
+ * configuration.
+ */
VLC_API int var_Inherit( vlc_object_t *, const char *, int, vlc_value_t * );
+/**
+ * Free a list and the associated strings returned by var_Change with the
+ * VLC_VAR_GETCHOICES action
+ * \param p_val: the list variable
+ * \param p_val2: the variable associated or NULL
+ */
VLC_API void var_FreeChoiceLists( vlc_value_t *, vlc_value_t * );
-
/*****************************************************************************
* Variable callbacks
- *****************************************************************************
- * int MyCallback( vlc_object_t *p_this,
- * char const *psz_variable,
- * vlc_value_t oldvalue,
- * vlc_value_t newvalue,
- * void *p_data);
*****************************************************************************/
+
+/**
+ * Register a callback in a variable
+ *
+ * We store a function pointer that will be called upon variable
+ * modification.
+ *
+ * \param p_this The object that holds the variable
+ * \param psz_name The name of the variable
+ * \param pf_callback The function pointer
+ * \param 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.
+ */
VLC_API void var_AddCallback( vlc_object_t *, const char *, vlc_callback_t, void * );
+
+/**
+ * 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.
+ */
VLC_API void var_DelCallback( vlc_object_t *, const char *, vlc_callback_t, void * );
+
+/**
+ * Trigger callback on a variable
+ *
+ * \param p_this The object that hold the variable
+ * \param psz_name The name of the variable
+ */
VLC_API void var_TriggerCallback( vlc_object_t *, const char * );
+/**
+ * Register a callback for a choice variable
+ *
+ * The callback is triggered when an element is added/removed from the
+ * list or when the list is cleared.
+ *
+ * See var_AddCallback().
+ */
VLC_API void var_AddChoiceCallback( vlc_object_t *, const char *, vlc_choice_callback_t, void * );
+
+/**
+ * Remove a callback from a choice variable
+ *
+ * See var_DelCallback().
+ */
VLC_API void var_DelChoiceCallback( vlc_object_t *, const char *, vlc_choice_callback_t, void * );
#define var_AddCallback(a,b,c,d) var_AddCallback( VLC_OBJECT(a), b, c, d )
@@ -652,6 +766,13 @@ static inline void *var_InheritAddress( vlc_object_t *obj, const char *name )
}
#define var_InheritAddress(o, n) var_InheritAddress(VLC_OBJECT(o), n)
+/**
+ * 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.
+ */
VLC_API int var_InheritURational( vlc_object_t *, unsigned *num, unsigned *den, const char *var );
#define var_InheritURational(a,b,c,d) var_InheritURational(VLC_OBJECT(a), b, c, d)
@@ -662,6 +783,22 @@ VLC_API int var_InheritURational( vlc_object_t *, unsigned *num, unsigned *den,
#define var_GetNonEmptyString(a,b) var_GetNonEmptyString( VLC_OBJECT(a),b)
#define var_GetAddress(a,b) var_GetAddress( VLC_OBJECT(a),b)
+/**
+ * Parses a set of colon-separated or semicolon-separated
+ * <code>name=value</code> 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.
+ *
+ * \param obj VLC object on which to set variables (and emit error messages)
+ * \param mrl string to parse
+ * \param pref prefix to prepend to option names in the string
+ *
+ * \return VLC_ENOMEM on error, VLC_SUCCESS on success.
+ */
VLC_API int var_LocationParse(vlc_object_t *, const char *mrl, const char *prefix);
#define var_LocationParse(o, m, p) var_LocationParse(VLC_OBJECT(o), m, p)
diff --git a/src/libvlc.h b/src/libvlc.h
index 63d8b54..97364ad 100644
--- a/src/libvlc.h
+++ b/src/libvlc.h
@@ -170,6 +170,19 @@ void intf_DestroyAll( libvlc_int_t * );
/*
* Variables stuff
*/
+
+/**
+ * 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.
+ * \param p_obj the object in which the variable must be created
+ * \param psz_option the option to parse
+ * \param trusted whether the option is set by a trusted input or not
+ * \return nothing
+ */
void var_OptionParse (vlc_object_t *, const char *, bool trusted);
/*
diff --git a/src/misc/variables.c b/src/misc/variables.c
index 5dd1b98..9d5e3ba 100644
--- a/src/misc/variables.c
+++ b/src/misc/variables.c
@@ -282,18 +282,6 @@ static void TriggerChoiceCallback(vlc_object_t *obj, variable_t *var,
}
#undef var_Create
-/**
- * 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!
- *
- * \param p_this The object in which to create the variable
- * \param psz_name The name of the variable
- * \param i_type The variables type. Must be one of \ref var_type combined with
- * zero or more \ref var_flags
- */
int var_Create( vlc_object_t *p_this, const char *psz_name, int i_type )
{
assert( p_this );
@@ -385,15 +373,6 @@ int var_Create( vlc_object_t *p_this, const char *psz_name, int i_type )
return ret;
}
-/**
- * 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.
- *
- * \param p_this The object that holds the variable
- * \param psz_name The name of the variable
- */
void (var_Destroy)(vlc_object_t *p_this, const char *psz_name)
{
variable_t *p_var;
@@ -436,15 +415,6 @@ void var_DestroyAll( vlc_object_t *obj )
}
#undef var_Change
-/**
- * Perform an action on a variable
- *
- * \param p_this The object that holds the variable
- * \param psz_name The name of the variable
- * \param i_action The action to perform. Must be one of \ref var_action
- * \param p_val First action parameter
- * \param p_val2 Second action parameter
- */
int var_Change( vlc_object_t *p_this, const char *psz_name,
int i_action, vlc_value_t *p_val, vlc_value_t *p_val2 )
{
@@ -620,15 +590,6 @@ int var_Change( vlc_object_t *p_this, const char *psz_name,
}
#undef var_GetAndSet
-/**
- * Perform a Get and Set on a variable
- *
- * \param p_this: The object that hold the variable
- * \param psz_name: the name of the variable
- * \param i_action: the action to perform
- * \param p_val: The action parameter
- * \return vlc error codes
- */
int var_GetAndSet( vlc_object_t *p_this, const char *psz_name, int i_action,
vlc_value_t *p_val )
{
@@ -691,13 +652,6 @@ int var_GetAndSet( vlc_object_t *p_this, const char *psz_name, int i_action,
}
#undef var_Type
-/**
- * Request a variable's type
- *
- * \return The variable type if it exists, or 0 if the
- * variable could not be found.
- * \see \ref var_type
- */
int var_Type( vlc_object_t *p_this, const char *psz_name )
{
variable_t *p_var;
@@ -766,13 +720,6 @@ int var_SetChecked( vlc_object_t *p_this, const char *psz_name,
}
#undef var_Set
-/**
- * Set a variable's value
- *
- * \param p_this The object that hold the variable
- * \param psz_name The name of the variable
- * \param val the value to set
- */
int var_Set( vlc_object_t *p_this, const char *psz_name, vlc_value_t val )
{
return var_SetChecked( p_this, psz_name, 0, val );
@@ -809,14 +756,6 @@ int var_GetChecked( vlc_object_t *p_this, const char *psz_name,
}
#undef var_Get
-/**
- * Get a variable's value
- *
- * \param p_this The object that holds the variable
- * \param psz_name The name of the variable
- * \param p_val Pointer to a vlc_value_t that will hold the variable's value
- * after the function is finished
- */
int var_Get( vlc_object_t *p_this, const char *psz_name, vlc_value_t *p_val )
{
return var_GetChecked( p_this, psz_name, 0, p_val );
@@ -862,22 +801,6 @@ static void AddCallback( vlc_object_t *p_this, const char *psz_name,
}
#undef var_AddCallback
-/**
- * Register a callback in a variable
- *
- * We store a function pointer that will be called upon variable
- * modification.
- *
- * \param p_this The object that holds the variable
- * \param psz_name The name of the variable
- * \param pf_callback The function pointer
- * \param 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.
- */
void var_AddCallback( vlc_object_t *p_this, const char *psz_name,
vlc_callback_t pf_callback, void *p_data )
{
@@ -949,12 +872,6 @@ static void DelCallback( vlc_object_t *p_this, const char *psz_name,
}
#undef var_DelCallback
-/**
- * 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.
- */
void var_DelCallback( vlc_object_t *p_this, const char *psz_name,
vlc_callback_t pf_callback, void *p_data )
{
@@ -966,12 +883,6 @@ void var_DelCallback( vlc_object_t *p_this, const char *psz_name,
}
#undef var_TriggerCallback
-/**
- * Trigger callback on a variable
- *
- * \param p_this The object that hold the variable
- * \param psz_name The name of the variable
- */
void var_TriggerCallback( vlc_object_t *p_this, const char *psz_name )
{
vlc_object_internals_t *p_priv = vlc_internals( p_this );
@@ -988,14 +899,6 @@ void var_TriggerCallback( vlc_object_t *p_this, const char *psz_name )
}
#undef var_AddChoiceCallback
-/**
- * Register a callback for a choice variable
- *
- * The callback is triggered when an element is added/removed from the
- * list or when the list is cleared.
- *
- * See var_AddCallback().
- */
void var_AddChoiceCallback( vlc_object_t *p_this, const char *psz_name,
vlc_choice_callback_t pf_callback, void *p_data )
{
@@ -1007,11 +910,6 @@ void var_AddChoiceCallback( vlc_object_t *p_this, const char *psz_name,
}
#undef var_DelChoiceCallback
-/**
- * Remove a callback from a choice variable
- *
- * See var_DelCallback().
- */
void var_DelChoiceCallback( vlc_object_t *p_this, const char *psz_name,
vlc_choice_callback_t pf_callback, void *p_data )
{
@@ -1022,16 +920,6 @@ void var_DelChoiceCallback( vlc_object_t *p_this, const char *psz_name,
DelCallback(p_this, psz_name, entry, vlc_choice_callback);
}
-/** 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.
- * \param p_obj the object in which the variable must be created
- * \param psz_option the option to parse
- * \param trusted whether the option is set by a trusted input or not
- * \return nothing
- */
void var_OptionParse( vlc_object_t *p_obj, const char *psz_option,
bool trusted )
{
@@ -1123,22 +1011,6 @@ cleanup:
}
#undef var_LocationParse
-/**
- * Parses a set of colon-separated or semicolon-separated
- * <code>name=value</code> 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.
- *
- * @param obj VLC object on which to set variables (and emit error messages)
- * @param mrl string to parse
- * @param pref prefix to prepend to option names in the string
- *
- * @return VLC_ENOMEM on error, VLC_SUCCESS on success.
- */
int var_LocationParse (vlc_object_t *obj, const char *mrl, const char *pref)
{
int ret = VLC_SUCCESS;
@@ -1168,12 +1040,6 @@ int var_LocationParse (vlc_object_t *obj, const char *mrl, const char *pref)
return ret;
}
-/**
- * Finds the value of a variable. If the specified object does not hold a
- * variable with the specified name, try the parent object, and iterate until
- * the top of the tree. If no match is found, the value is read from the
- * configuration.
- */
int var_Inherit( vlc_object_t *p_this, const char *psz_name, int i_type,
vlc_value_t *p_val )
{
@@ -1208,14 +1074,6 @@ int var_Inherit( vlc_object_t *p_this, const char *psz_name, int i_type,
return VLC_SUCCESS;
}
-
-/**
- * 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.
- */
int (var_InheritURational)(vlc_object_t *object,
unsigned *num, unsigned *den,
const char *var)
@@ -1283,12 +1141,6 @@ error:
return VLC_EGENERIC;
}
-/**
- * Free a list and the associated strings returned by var_Change with the
- * VLC_VAR_GETCHOICES action
- * @param p_val: the list variable
- * @param p_val2: the variable associated or NULL
- */
void var_FreeChoiceLists( vlc_value_t *p_val, vlc_value_t *p_val2 )
{
switch( p_val->p_list->i_type & VLC_VAR_CLASS )
--
2.9.3
More information about the vlc-devel
mailing list