Mercurial > mplayer.hg
changeset 18258:96568be4bfdc
Doxygen attack!
| author | albeu |
|---|---|
| date | Mon, 24 Apr 2006 19:20:04 +0000 |
| parents | 744d01fe00d9 |
| children | e90af781bbb6 |
| files | m_config.c m_config.h m_option.c m_option.h m_property.c m_property.h m_struct.c m_struct.h |
| diffstat | 8 files changed, 614 insertions(+), 122 deletions(-) [+] |
line wrap: on
line diff
--- a/m_config.c Mon Apr 24 19:14:16 2006 +0000 +++ b/m_config.c Mon Apr 24 19:20:04 2006 +0000 @@ -1,3 +1,7 @@ + +/// \file +/// \ingroup Config + #include "config.h" #include <stdlib.h>
--- a/m_config.h Mon Apr 24 19:14:16 2006 +0000 +++ b/m_config.h Mon Apr 24 19:20:04 2006 +0000 @@ -1,89 +1,200 @@ #ifndef _M_CONFIG_H #define _M_CONFIG_H +/// \defgroup Config Config manager +/// +/// m_config provide an API to manipulate the config variables in MPlayer. +/// It make use of the \ref Options API to provide a context stack that +/// allow saving and later restoring the state of all variables. +///@{ + +/// \file + typedef struct m_config_option m_config_option_t; typedef struct m_config_save_slot m_config_save_slot_t; +/// \ingroup ConfigProfiles typedef struct m_profile m_profile_t; struct m_option; struct m_option_type; +/// Config option save slot struct m_config_save_slot { + /// Previous level slot. m_config_save_slot_t* prev; + /// Level at which the save was made. int lvl; // we have to store other datatypes in this as well, // so make sure we get properly aligned addresses unsigned char data[0] __attribute__ ((aligned (8))); }; +/// Config option struct m_config_option { m_config_option_t* next; - char* name; // Full name (ie option:subopt) + /// Full name (ie option:subopt). + char* name; + /// Option description. struct m_option* opt; + /// Save slot stack. m_config_save_slot_t* slots; - unsigned int flags; // currently it only tell if the option was set + /// See \ref ConfigOptionFlags. + unsigned int flags; }; +/// \defgroup ConfigProfiles Config profiles +/// \ingroup Config +/// +/// Profiles allow to predefine some set of options that can then +/// be applied later on with the internal -profile option. +/// +///@{ + +/// Config profile struct m_profile { m_profile_t* next; char* name; char* desc; int num_opts; + /// Option/value pair array. char** opts; }; +///@} + +/// Config object +/** \ingroup Config */ typedef struct m_config { + /// Registered options. + /** This contain all options and suboptions. + */ m_config_option_t* opts; - int lvl; // Current stack level + /// Current stack level. + int lvl; + /// \ref OptionParserModes int mode; + /// List of the defined profiles. m_profile_t* profiles; + /// Depth when recursively including profiles. int profile_depth; + /// Options defined by the config itself. struct m_option* self_opts; } m_config_t; +/// \defgroup ConfigOptionFlags Config option flags +/// \ingroup Config +///@{ + +/// Set if an option have been set at the current level. #define M_CFG_OPT_SET (1<<0) + +/// Set if another option already use the same variable. #define M_CFG_OPT_ALIAS (1<<1) +///@} -//////////////////////////// Functions /////////////////////////////////// - +/// Create a new config object. +/** \ingroup Config + */ m_config_t* m_config_new(void); +/// Free a config object. void m_config_free(m_config_t* config); +/// Push a new context. +/** \param config The config object. + */ void m_config_push(m_config_t* config); +/// Pop the current context restoring the previous context state. +/** \param config The config object. + */ void m_config_pop(m_config_t* config); +/// Register some options to be used. +/** \param config The config object. + * \param args An array of \ref m_option struct. + * \return 1 on success, 0 on failure. + */ int m_config_register_options(m_config_t *config, struct m_option *args); +/// Set an option. +/** \param config The config object. + * \param arg The option's name. + * \param param The value of the option, can be NULL. + * \return See \ref OptionParserReturn. + */ int m_config_set_option(m_config_t *config, char* arg, char* param); +/// Check if an option setting is valid. +/** \param config The config object. + * \param arg The option's name. + * \param param The value of the option, can be NULL. + * \return See \ref OptionParserReturn. + */ int m_config_check_option(m_config_t *config, char* arg, char* param); +/// Get the option matching the given name. +/** \param config The config object. + * \param arg The option's name. + */ struct m_option* m_config_get_option(m_config_t *config, char* arg); +/// Print a list of all registered options. +/** \param config The config object. + */ void m_config_print_option_list(m_config_t *config); +/// \addtogroup ConfigProfiles +///@{ + +/// Find the profile with the given name. +/** \param config The config object. + * \param arg The profile's name. + * \return The profile object or NULL. + */ m_profile_t* m_config_get_profile(m_config_t* config, char* name); +/// Get the profile with the given name, creating it if necessary. +/** \param config The config object. + * \param arg The profile's name. + * \return The profile object. + */ m_profile_t* m_config_add_profile(m_config_t* config, char* name); +/// Set the description of a profile. +/** This is used by the config file parser when defining a profile. + * + * \param p The profile object. + * \param arg The profile's name. + */ void m_profile_set_desc(m_profile_t* p, char* desc); +/// Add an option to a profile. +/** This is used by the config file parser when defining a profile. + * + * \param config The config object. + * \param p The profile object. + * \param name The option's name. + * \param val The option's value. + */ int m_config_set_profile_option(m_config_t* config, m_profile_t* p, char* name, char* val); +///@} + +///@} + #endif /* _M_CONFIG_H */
--- a/m_option.c Mon Apr 24 19:14:16 2006 +0000 +++ b/m_option.c Mon Apr 24 19:20:04 2006 +0000 @@ -1,3 +1,7 @@ + +/// \file +/// \ingroup Options + #include "config.h" #include <stdlib.h>
--- a/m_option.h Mon Apr 24 19:14:16 2006 +0000 +++ b/m_option.h Mon Apr 24 19:20:04 2006 +0000 @@ -1,10 +1,23 @@ #ifndef _M_OPTION_H #define _M_OPTION_H +/// \defgroup Options +/// m_option allow to parse, print and copy data of various types. +/// It is the base of the \ref OptionsStruct, \ref Config and +/// \ref Properties APIs. +///@{ + +/// \file m_option.h + +/// \ingroup OptionTypes typedef struct m_option_type m_option_type_t; typedef struct m_option m_option_t; struct m_struct_st; +/// \defgroup OptionTypes Options types +/// \ingroup Options +///@{ + ///////////////////////////// Options types declarations //////////////////////////// // Simple types @@ -28,52 +41,99 @@ extern m_option_type_t m_option_type_func_param; extern m_option_type_t m_option_type_func; +/// Callback used to reset func options. typedef void (*m_opt_default_func_t)(m_option_t *, char*); + +/// Callback used by m_option_type_func_full options. typedef int (*m_opt_func_full_t)(m_option_t *, char *, char *); + +/// Callback used by m_option_type_func_param options. typedef int (*m_opt_func_param_t)(m_option_t *, char *); + +/// Callback used by m_option_type_func options. typedef int (*m_opt_func_t)(m_option_t *); -///////////// Backward compat + +// Backward compat typedef m_opt_default_func_t cfg_default_func_t; typedef m_opt_func_full_t cfg_func_arg_param_t; typedef m_opt_func_param_t cfg_func_param_t; typedef m_opt_func_t cfg_func_t; +/// Extra definition needed for \ref m_option_type_obj_settings_list options. typedef struct { + /// Pointer to an array of pointer to some object type description struct. void** list; + /// Offset of the object type name (char*) in the description struct. void* name_off; + /// Offset of the object type info string (char*) in the description struct. void* info_off; + /// \brief Offset of the object type parameter description (\ref m_struct_st) + /// in the description struct. void* desc_off; } m_obj_list_t; -typedef struct { +/// The data type used by \ref m_option_type_obj_settings_list. +typedef struct m_obj_settings { + /// Type of the object. char* name; + /// NULL terminated array of parameter/value pairs. char** attribs; } m_obj_settings_t; + +/// A parser to setup a list of objects. +/** It create a NULL terminated array \ref m_obj_settings. The option priv + * field (\ref m_option::priv) must point to a \ref m_obj_list_t describing + * the available object types. + */ extern m_option_type_t m_option_type_obj_settings_list; -// Presets are mean to be used with options struct - - +/// Extra definition needed for \ref m_option_type_obj_presets options. typedef struct { + /// Description of the struct holding the presets. struct m_struct_st* in_desc; + /// Description of the struct that should be set by the presets. struct m_struct_st* out_desc; - void* presets; // Pointer to an arry of struct defined by in_desc - void* name_off; // Offset of the preset name inside the in_struct + /// Pointer to an array of struct defining the various presets. + void* presets; + /// Offset of the preset's name inside the in_struct. + void* name_off; } m_obj_presets_t; + +/// Set several fields in a struct at once. +/** For this two struct description are used. One for the struct holding the + * preset and one for the struct beeing set. Every field present in both + * struct will be copied from the preset struct to the destination one. + * The option priv field (\ref m_option::priv) must point to a correctly + * filled \ref m_obj_presets_t. + */ extern m_option_type_t m_option_type_obj_presets; +/// Parse an URL into a struct. +/** The option priv field (\ref m_option::priv) must point to a + * \ref m_struct_st describing which fields of the URL must be used. + */ extern m_option_type_t m_option_type_custom_url; +/// Extra definition needed for \ref m_option_type_obj_params options. typedef struct { - struct m_struct_st* desc; // Fields description - char separator; // Field separator to use + /// Fields description. + struct m_struct_st* desc; + /// Field separator to use. + char separator; } m_obj_params_t; + +/// Parse a set of parameters. +/** Parameters are separated by the given separator and each one + * successively set a field from the struct. The option priv field + * (\ref m_option::priv) must point to a \ref m_obj_params_t. + */ extern m_option_type_t m_option_type_obj_params; typedef struct { int start; int end; } m_span_t; +/// Ready made settings to parse a \ref m_span_t with a start-end syntax. extern m_obj_params_t m_span_params_def; @@ -102,67 +162,155 @@ ///////////////////////////////////////////////////////////////////////////////////////////// +/// Option type description struct m_option_type { char* name; - char* comments; // syntax desc, etc - unsigned int size; // size needed for a save slot + /// Syntax desc, etc + char* comments; + /// Size needed for the data. + unsigned int size; + /// See \ref OptionTypeFlags. unsigned int flags; - - // parse is the only requiered function all others can be NULL - // If dst if non-NULL it should create/update the save slot - // If dst is NULL it should just test the validity of the arg if possible - // Src tell from where come this setting (ie cfg file, command line, playlist, .... - // It should return 1 if param was used, 0 if not. - // On error it must return 1 of the error code below + + /// Parse the data from a string. + /** It is the only required function, all others can be NULL. + * + * \param opt The option that is parsed. + * \param name The full option name. + * \param param The parameter to parse. + * \param dst Pointer to the memory where the data should be writen. + * If NULL the parameter validity should still be checked. + * \param src Source of the option, see \ref OptionParserModes. + * \return On error a negative value is returned, on success the number of argument + * consumed. For details see \ref OptionParserReturn. + */ int (*parse)(m_option_t* opt,char *name, char *param, void* dst, int src); - // Print back a value in human form + + /// Print back a value in string form. + /** \param opt The option to print. + * \param val Pointer to the memory holding the data to be printed. + * \return An allocated string containing the text value or (void*)-1 + * on error. + */ char* (*print)(m_option_t* opt, void* val); - // These 3 will be a memcpy in 50% of the case, it's called to save/restore the status of - // the var it's there for complex type like CONF_TYPE_FUNC* - // update a save slot (dst) from the current value in the prog (src) + /** \name + * These functions are called to save/set/restore the status of the + * variables. The difference between the 3 only matter for types like + * \ref m_option_type_func where 'setting' need to do more than just + * copying some data. + */ + //@{ + + /// Update a save slot (dst) from the current value in the prog (src). + /** \param opt The option to copy. + * \param dst Pointer to the destination memory. + * \param src Pointer to the source memory. + */ void (*save)(m_option_t* opt,void* dst, void* src); - // set the current value (dst) from a save slot + + /// Set the value in the prog (dst) from a save slot. + /** \param opt The option to copy. + * \param dst Pointer to the destination memory. + * \param src Pointer to the source memory. + */ void (*set)(m_option_t* opt,void* dst, void* src); - // Copy betewen 2 slot (if NULL and size > 0 a memcpy will be used + + /// Copy the data between two save slots. If NULL and size is > 0 a memcpy will be used. + /** \param opt The option to copy. + * \param dst Pointer to the destination memory. + * \param src Pointer to the source memory. + */ void (*copy)(m_option_t* opt,void* dst, void* src); - // Free the data allocated for a save slot if needed + //@} + + /// Free the data allocated for a save slot. + /** This is only needed for dynamic types like strings. + * \param dst Pointer to the data, usually a pointer that should be freed and + * set to NULL. + */ void (*free)(void* dst); }; +///@} + +/// Option description +/** \ingroup Options + */ struct m_option { + /// Option name. char *name; - void *p; + + /// Reserved for higher level APIs, it shouldn't be used by parsers. + /** The suboption parser and func types do use it. They should instead + * use the priv field but this was herited from older versions of the + * config code. + */ + void *p; + + /// Option type. m_option_type_t* type; + + /// See \ref OptionFlags. unsigned int flags; - double min,max; - // This used to be function pointer to hold a 'reverse to defaults' func. - // Nom it can be used to pass any type of extra args. - // Passing a 'default func' is still valid for all func based option types - void* priv; // Type dependent data (for all kind of extended setting) + + /// \brief Mostly usefull for numeric types, the \ref M_OPT_MIN flags must + /// also be set. + double min; + + /// \brief Mostly usefull for numeric types, the \ref M_OPT_MAX flags must + /// also be set. + double max; + + /// Type dependent data (for all kind of extended setting). + /** This used to be function pointer to hold a 'reverse to defaults' func. + * Now it can be used to pass any type of extra args needed by the parser. + * Passing a 'default func' is still valid for all func based option types + */ + void* priv; }; -//////////////////////////////// Option flags ///////////////////////////////// +/// \defgroup OptionFlags Option flags +///@{ -// Option flags +/// The option have a minimum set in \ref m_option::min. #define M_OPT_MIN (1<<0) + +/// The option have a maximum set in \ref m_option::max. #define M_OPT_MAX (1<<1) + +/// The option have a minimum and maximum in \ref m_option::min and \ref m_option::max. #define M_OPT_RANGE (M_OPT_MIN|M_OPT_MAX) + +/// The option is forbidden in config files. #define M_OPT_NOCFG (1<<2) + +/// The option is forbiden on the command line. #define M_OPT_NOCMD (1<<3) -// This option is global : it won't be saved on push and the command -// line parser will set it when it's parsed (ie. it won't be set later) -// e.g options : -v, -quiet + +/// The option is global in the \ref Config. +/** It won't be saved on push and the command line parser will set it when + * it's parsed (ie. it won't be set later) + * e.g options : -v, -quiet + */ #define M_OPT_GLOBAL (1<<4) -// Do not save this option : it won't be saved on push but the command -// line parser will put it with it's entry (ie : it may be set later) -// e.g options : -include + +/// The \ref Config won't save this option on push. +/** It won't be saved on push but the command line parser will put it with + * it's entry (ie : it may be set later) + * e.g options : -include + */ #define M_OPT_NOSAVE (1<<5) -// Emulate old behaviour by pushing the option only if it was set by the user + +/// \brief The \ref Config will emulate the old behaviour by pushing the +/// option only if it was set by the user. #define M_OPT_OLD (1<<6) -// FIXME: backward compatibility +/// \defgroup OldOptionFlags Backward compatibility +/// +/// Those are kept for compatibility with older code. +/// @{ #define CONF_MIN M_OPT_MIN #define CONF_MAX M_OPT_MAX #define CONF_RANGE M_OPT_RANGE @@ -171,73 +319,135 @@ #define CONF_GLOBAL M_OPT_GLOBAL #define CONF_NOSAVE M_OPT_NOSAVE #define CONF_OLD M_OPT_OLD - - -///////////////////////////// Option type flags /////////////////////////////////// +///@} -// These flags are for the parsers. The description here apply to the m_config_t -// based parsers (ie. cmd line and config file parsers) -// Some parser will refuse option types that have some of these flags +///@} -// This flag is used for the subconfig -// When this flag is set, opt->p should point to another m_option_t array -// Only the parse function will be called. If dst is set, it should create/update -// an array of char* containg opt/val pairs. -// Then the options in the child array will then be set automaticly. -// You can only affect the way suboption are parsed. -// Also note that suboptions may be directly accessed by using -option:subopt blah :-) +/// \defgroup OptionTypeFlags Option type flags +/// \ingroup OptionTypes +/// +/// These flags are used to describe special parser capabilities or behaviour. +/// +///@{ + +/// Suboption parser flag. +/** When this flag is set, m_option::p should point to another m_option + * array. Only the parse function will be called. If dst is set, it should + * create/update an array of char* containg opt/val pairs. The options in + * the child array will then be set automatically by the \ref Config. + * Also note that sub options may be directly accessed by using + * -option:subopt blah. + */ #define M_OPT_TYPE_HAS_CHILD (1<<0) -// If this flag is set the option type support option name with * at the end (used for -aa*) -// This only affect the option name matching, the option type have to implement -// the needed stuff. + +/// Wildcard matching flag. +/** If set the option type have a use for option name ending with a * + * (used for -aa*), this only affect the option name matching. + */ #define M_OPT_TYPE_ALLOW_WILDCARD (1<<1) -// This flag indicate that the data is dynamicly allocated (opt->p point to a pointer) -// It enable a little hack wich replace the initial value by a dynamic copy -// in case the initial value is staticly allocated (pretty common with strings) + +/// Dynamic data type. +/** This flag indicate that the data is dynamicly allocated (m_option::p point + * to a pointer). It enable a little hack in the \ref Config wich replace + * the initial value of such variables with a dynamic copy in case the + * initial value is staticaly allocated (pretty common with strings). + */ #define M_OPT_TYPE_DYNAMIC (1<<2) -/// If this is set the parse function doesn't directly return -// the wanted thing. Options use this if for some reasons they have to wait -// until the set call to be able to correctly set the target var. -// So for those types you have to first parse and then set the target var -// If this flag isn't set you can parse directly to the target var -// It's used for the callback based option as the callback call may append -// later on. + +/// Indirect option type. +/** If this is set the parse function doesn't directly return + * the wanted thing. Options use this if for some reasons they have to wait + * until the set call to be able to correctly set the target var. + * So for those types new values must first be parsed, then set to the target + * var. If this flag isn't set then new values can be parsed directly to the + * target var. It's used by the callback based option as the callback call + * may append later on. + */ #define M_OPT_TYPE_INDIRECT (1<<3) +///@} ///////////////////////////// Parser flags //////////////////////////////////////// -// Config mode : some parser type behave differently depending -// on config->mode value wich is passed in the src param of parse() +/// \defgroup OptionParserModes Option parser modes +/// \ingroup Options +/// +/// Some parser behave differently depending on the mode passed in the src +/// parameter of m_option_type::parse. For example the flag type doesn't take +/// an argument when parsing from the command line. +///@{ + +/// Set when parsing from a config file. #define M_CONFIG_FILE 0 +/// Set when parsing command line arguments. #define M_COMMAND_LINE 1 -// Option parser error code +///@} + +/// \defgroup OptionParserReturn Option parser return code +/// \ingroup Options +/// +/// On sucess parsers return the number of arguments consumed: 0 or 1. +/// +/// To indicate that mplayer should exit without playing anything, +/// parsers return M_OPT_EXIT minus the number of parameters they +/// consumed: \ref M_OPT_EXIT or \ref M_OPT_EXIT-1. +/// +/// On error one of the following (negative) error code is returned: +///@{ + +/// For use by higer level APIs when the option name is invalid. #define M_OPT_UNKNOWN -1 + +/// Returned when a parameter is needed but wasn't provided. #define M_OPT_MISSING_PARAM -2 + +/// Returned when the given parameter couldn't be parsed. #define M_OPT_INVALID -3 + +/// \brief Returned if the value is "out of range". The exact meaning may +/// vary from type to type. #define M_OPT_OUT_OF_RANGE -4 + +/// Returned if the parser failed for any other reason than a bad parameter. #define M_OPT_PARSER_ERR -5 + +/// Returned when MPlayer should exit. Used by various help stuff. +/** M_OPT_EXIT must be the lowest number on this list. + */ #define M_OPT_EXIT -6 -// M_OPT_EXIT must be the lowest number on this list. -// To indicate that mplayer should exit without playing anything, -// a parsing function needs to return M_OPT_EXIT less the number -// of additional command line parameters it consumed. -// Generally it will return either M_OPT_EXIT or M_OPT_EXIT - 1. -// FIXME: backward compatibility +/// \defgroup OldOptionParserReturn Backward compatibility +/// +/// Those are kept for compatibility with older code. +/// +///@{ #define ERR_NOT_AN_OPTION M_OPT_UNKNOWN #define ERR_MISSING_PARAM M_OPT_MISSING_PARAM #define ERR_OUT_OF_RANGE M_OPT_OUT_OF_RANGE #define ERR_FUNC_ERR M_OPT_PARSER_ERR +///@} +///@} + +/// Find the option matching the given name in the list. +/** \ingroup Options + * This function take the possible wildcards in account (see + * \ref M_OPT_TYPE_ALLOW_WILDCARD). + * + * \param list Pointer to an array of \ref m_option. + * \param name Name of the option. + * \return The matching option or NULL. + */ m_option_t* m_option_list_find(m_option_t* list,char* name); +/// Helper to parse options, see \ref m_option_type::parse. inline static int m_option_parse(m_option_t* opt,char *name, char *param, void* dst, int src) { return opt->type->parse(opt,name,param,dst,src); } +/// Helper to print options, see \ref m_option_type::print. inline static char* m_option_print(m_option_t* opt, void* val_ptr) { if(opt->type->print) @@ -246,18 +456,21 @@ return (char*)-1; } +/// Helper around \ref m_option_type::save. inline static void m_option_save(m_option_t* opt,void* dst, void* src) { if(opt->type->save) opt->type->save(opt,dst,src); } +/// Helper around \ref m_option_type::set. inline static void m_option_set(m_option_t* opt,void* dst, void* src) { if(opt->type->set) opt->type->set(opt,dst,src); } +/// Helper around \ref m_option_type::copy. inline static void m_option_copy(m_option_t* opt,void* dst, void* src) { if(opt->type->copy) @@ -266,10 +479,13 @@ memcpy(dst,src,opt->type->size); } +/// Helper around \ref m_option_type::free. inline static void m_option_free(m_option_t* opt,void* dst) { if(opt->type->free) opt->type->free(dst); } +/*@}*/ + #endif /* _M_OPTION_H */
--- a/m_property.c Mon Apr 24 19:14:16 2006 +0000 +++ b/m_property.c Mon Apr 24 19:20:04 2006 +0000 @@ -1,3 +1,6 @@ + +/// \file +/// \ingroup Properties #include "config.h"
--- a/m_property.h Mon Apr 24 19:14:16 2006 +0000 +++ b/m_property.h Mon Apr 24 19:20:04 2006 +0000 @@ -1,50 +1,136 @@ -// Get the current value -#define M_PROPERTY_GET 0 -// Get a string representing the current value -#define M_PROPERTY_PRINT 1 -// Set a new value -#define M_PROPERTY_SET 2 -// Set a new value from a string -#define M_PROPERTY_PARSE 3 -// Increment the property -#define M_PROPERTY_STEP_UP 4 -// Decrement the property -#define M_PROPERTY_STEP_DOWN 5 +/// \defgroup Properties +/// +/// Properties provide an interface to query and set the state of various +/// things in MPlayer. The API is based on the \ref Options API like the +/// \ref Config, but instead of using variables, properties use an ioctl like +/// function. The function is used to perform various actions like get and set +/// (see \ref PropertyActions). +///@{ + +/// \file + +/// \defgroup PropertyActions Property actions +/// \ingroup Properties +///@{ + +/// Get the current value. +/** \param arg Pointer to a variable of the right type. + */ +#define M_PROPERTY_GET 0 + +/// Get a string representing the current value. +/** Set the variable to a newly allocated string or NULL. + * \param arg Pointer to a char* variable. + */ +#define M_PROPERTY_PRINT 1 + +/// Set a new value. +/** The variable is updated to the value actually set. + * \param arg Pointer to a variable of the right type. + */ +#define M_PROPERTY_SET 2 + +/// Set a new value from a string. +/** \param arg String containing the value. + */ +#define M_PROPERTY_PARSE 3 -// Return values for the control function +/// Increment the current value. +/** The sign of the argument is also taken into account if applicable. + * \param arg Pointer to a variable of the right type or NULL. + */ +#define M_PROPERTY_STEP_UP 4 + +/// Decrement the current value. +/** The sign of the argument is also taken into account if applicable. + * \param arg Pointer to a variable of the right type or NULL. + */ +#define M_PROPERTY_STEP_DOWN 5 + +///@} + +/// \defgroup PropertyActionsReturn Property actions return code +/// \ingroup Properties +/// \brief Return values for the control function. +///@{ + +/// Returned on success. #define M_PROPERTY_OK 1 + +/// Returned on error. #define M_PROPERTY_ERROR 0 -// Returned when the property can't be used, for ex something about -// the subs while playing audio only + +/// \brief Returned when the property can't be used, for ex something about +/// the subs while playing audio only #define M_PROPERTY_UNAVAILABLE -1 -// Returned if the requested action is not implemented + +/// Returned if the requested action is not implemented. #define M_PROPERTY_NOT_IMPLEMENTED -2 -// Returned when asking for a property that doesn't exist + +/// Returned when asking for a property that doesn't exist. #define M_PROPERTY_UNKNOWN -3 -// Returned when the action can't be done (like setting the volume when edl mute) + +/// Returned when the action can't be done (like setting the volume when edl mute). #define M_PROPERTY_DISABLED -4 +///@} + +/// \ingroup Properties +/// \brief Property action callback. typedef int(*m_property_ctrl_f)(m_option_t* prop,int action,void* arg); +/// Do an action on a property. +/** \param prop The property. + * \param action See \ref PropertyActions. + * \param arg Argument, usually a pointer to the data type used by the property. + * \return See \ref PropertyActionsReturn. + */ int m_property_do(m_option_t* prop, int action, void* arg); +/// Print the current value of a property. +/** \param prop The property. + * \return A newly allocated string with current value or NULL on error. + */ char* m_property_print(m_option_t* prop); +/// Set a property. +/** \param prop The property. + * \param txt The value to set. + * \return 1 on success, 0 on error. + */ int m_property_parse(m_option_t* prop, char* txt); +/// Print a list of properties. void m_properties_print_help_list(m_option_t* list); +/// Expand a property string. +/** This function allow to print strings containing property values. + * ${NAME} is expanded to the value of property NAME or an empty + * string in case of error. $(NAME:STR) expand STR only if the property + * NAME is available. + * + * \param prop_list An array of \ref m_option describing the available + * properties. + * \param str The string to expand. + * \return The newly allocated expanded string. + */ char* m_properties_expand_string(m_option_t* prop_list,char* str); // Helpers to use MPlayer's properties +/// Get an MPlayer property. m_option_t* mp_property_find(char* name); +/// Do an action with an MPlayer property. int mp_property_do(char* name,int action, void* val); -// Helpers for property implementations +/// \defgroup PropertyImplHelper Property implementation helpers +/// \ingroup Properties +/// \brief Helper functions for common property types. +///@{ +/// Clamp a value according to \ref m_option::min and \ref m_option::max. #define M_PROPERTY_CLAMP(prop,val) do { \ if(((prop)->flags & M_OPT_MIN) && (val) < (prop)->min) \ (val) = (prop)->min; \ @@ -52,37 +138,41 @@ (val) = (prop)->max; \ } while(0) -// Implement get +/// Implement get. int m_property_int_ro(m_option_t* prop,int action, void* arg,int var); -// Implement set, get and step up/down +/// Implement set, get and step up/down. int m_property_int_range(m_option_t* prop,int action, void* arg,int* var); -// Same but cycle +/// Same as m_property_int_range but cycle. int m_property_choice(m_option_t* prop,int action, void* arg,int* var); -// Switch betwen min and max +/// Switch betwen min and max. int m_property_flag(m_option_t* prop,int action, void* arg,int* var); -// Implement get, print +/// Implement get, print. int m_property_float_ro(m_option_t* prop,int action, void* arg,float var); -// Implement set, get and step up/down +/// Implement set, get and step up/down int m_property_float_range(m_option_t* prop,int action, void* arg,float* var); -// float with a print function which print the time in ms +/// float with a print function which print the time in ms int m_property_delay(m_option_t* prop,int action, void* arg,float* var); -// Implement get, print +/// Implement get, print int m_property_double_ro(m_option_t* prop,int action, void* arg,double var); -// get/print the string +/// get/print the string int m_property_string_ro(m_option_t* prop,int action,void* arg, char* str); + +///@} + +///@}
--- a/m_struct.c Mon Apr 24 19:14:16 2006 +0000 +++ b/m_struct.c Mon Apr 24 19:20:04 2006 +0000 @@ -1,3 +1,7 @@ + +/// \file +/// \ingroup OptionsStruct + #include "config.h" #include <stdlib.h>
--- a/m_struct.h Mon Apr 24 19:14:16 2006 +0000 +++ b/m_struct.h Mon Apr 24 19:20:04 2006 +0000 @@ -1,48 +1,108 @@ #ifndef _M_STRUCT_H #define _M_STRUCT_H -///////////////////// A struct setter //////////////////////// +/// \defgroup OptionsStruct Options struct +/// \ingroup Options +/// An API to manipulate structs using m_option. +///@{ + +/// \file m_struct.h struct m_option; /// Struct definition typedef struct m_struct_st { - char* name; // For error msg and debuging - unsigned int size; // size of the whole struct - void* defaults; // Pointer to a struct filled with the default settings - struct m_option* fields; // settable fields + /// For error msg and debuging + char* name; + /// size of the whole struct + unsigned int size; + /// Pointer to a struct filled with the default settings + void* defaults; + /// Field list. + /** The p field of the \ref m_option struct must contain the offset + * of the member in the struct (use M_ST_OFF macro for this). + */ + struct m_option* fields; } m_struct_t; -// Note : the p field of the m_option_t struct must contain the offset -// of the member in the struct (use M_ST_OFF macro for this). // From glib.h (modified ;-) + +/// Get the offset of a struct field. +/** \param struct_type Struct type. + * \param member Name of the field. + * \return The offset of the field in bytes. + */ #define M_ST_OFF(struct_type, member) \ ((void*) &((struct_type*) 0)->member) + +/// Get a pointer to a struct field. +/** \param struct_p Pointer to the struct. + * \param struct_offset Offset of the field in the struct. + * \return Pointer to the struct field. + */ #define M_ST_MB_P(struct_p, struct_offset) \ ((void*) (struct_p) + (unsigned long) (struct_offset)) + +/// Acces a struct field at a given offset. +/** \param member_type Type of the field. + * \param struct_p Pointer to the struct. + * \param struct_offset Offset of the field in the struct. + * \return The struct field at the given offset. + */ #define M_ST_MB(member_type, struct_p, struct_offset) \ (*(member_type*) M_ST_MB_P ((struct_p), (struct_offset))) -/// Allocate the struct and set it to the defaults +/// Allocate the struct and set it to the defaults. +/** \param st Struct definition. + * \return The newly allocated object set to default. + */ void* m_struct_alloc(m_struct_t* st); -/// Set a field of the struct + +/// Set a field of the struct. +/** \param st Struct definition. + * \param obj Pointer to the struct to set. + * \param field Name of the field to set. + * \param param New value of the field. + * \return 0 on error, 1 on success. + */ int m_struct_set(m_struct_t* st, void* obj, char* field, char* param); -/// Reset a field (or all if field == NULL) to defaults + +/// Reset a field (or all if field == NULL) to defaults. +/** \param st Struct definiton. + * \param obj Pointer to the struct to set. + * \param field Name of the field to reset, if NULL all fields are reseted. + */ void m_struct_reset(m_struct_t* st, void* obj, char* field); -/// Create a copy of an existing struct + +/// Create a copy of an existing struct. +/** \param st Struct definiton. + * \param obj Pointer to the struct to copy. + * \return Newly allocated copy of obj. + */ void* m_struct_copy(m_struct_t* st, void* obj); -/// Free an allocated struct + +/// Free an allocated struct. +/** \param st Struct definiton. + * \param obj Pointer to the struct to copy. + */ void m_struct_free(m_struct_t* st, void* obj); -/// Get a field description + +/// Get a field description. +/** \param st Struct definiton. + * \param f Name of the field. + * \return The \ref m_option struct describing the field or NULL if not found. + */ struct m_option* m_struct_get_field(m_struct_t* st,char* f); +///@} + #endif /* _M_STRUCT_H */