m_property.h

   1 #ifndef M_PROPERTY_H
   2 #define M_PROPERTY_H
   3
   4 /// \defgroup Properties
   5 ///
   6 /// Properties provide an interface to query and set the state of various
   7 /// things in MPlayer. The API is based on the \ref Options API like the
   8 /// \ref Config, but instead of using variables, properties use an ioctl like
   9 /// function. The function is used to perform various actions like get and set
  10 /// (see \ref PropertyActions).
  11 ///@{
  12
  13 /// \file
  14
  15 /// \defgroup PropertyActions Property actions
  16 /// \ingroup Properties
  17 ///@{
  18
  19 /// Get the current value.
  20 /** \param arg Pointer to a variable of the right type.
  21  */
  22 #define M_PROPERTY_GET         0
  23
  24 /// Get a string representing the current value.
  25 /** Set the variable to a newly allocated string or NULL.
  26  *  \param arg Pointer to a char* variable.
  27  */
  28 #define M_PROPERTY_PRINT       1
  29
  30 /// Set a new value.
  31 /** The variable is updated to the value actually set.
  32  *  \param arg Pointer to a variable of the right type.
  33  */
  34 #define M_PROPERTY_SET         2
  35
  36 /// Set a new value from a string.
  37 /** \param arg String containing the value.
  38  */
  39 #define M_PROPERTY_PARSE       3
  40
  41 /// Increment the current value.
  42 /** The sign of the argument is also taken into account if applicable.
  43  *  \param arg Pointer to a variable of the right type or NULL.
  44  */
  45 #define M_PROPERTY_STEP_UP     4
  46
  47 /// Decrement the current value.
  48 /** The sign of the argument is also taken into account if applicable.
  49  *  \param arg Pointer to a variable of the right type or NULL.
  50  */
  51 #define M_PROPERTY_STEP_DOWN   5
  52
  53 /// Get a string containg a parsable representation.
  54 /** Set the variable to a newly allocated string or NULL.
  55  *  \param arg Pointer to a char* variable.
  56  */
  57 #define M_PROPERTY_TO_STRING   6
  58
  59 /// Pass down an action to a sub-property.
  60 #define M_PROPERTY_KEY_ACTION  7
  61
  62 /// Get a m_option describing the property.
  63 #define M_PROPERTY_GET_TYPE    8
  64
  65 ///@}
  66
  67 /// \defgroup PropertyActionsArg Property actions argument type
  68 /// \ingroup Properties
  69 /// \brief  Types used as action argument.
  70 ///@{
  71
  72 /// Argument for \ref M_PROPERTY_KEY_ACTION
  73 typedef struct {
  74     const char* key;
  75     int action;
  76     void* arg;
  77 } m_property_action_t;
  78
  79 ///@}
  80
  81 /// \defgroup PropertyActionsReturn Property actions return code
  82 /// \ingroup Properties
  83 /// \brief  Return values for the control function.
  84 ///@{
  85
  86 /// Returned on success.
  87 #define M_PROPERTY_OK                1
  88
  89 /// Returned on error.
  90 #define M_PROPERTY_ERROR             0
  91
  92 /// \brief Returned when the property can't be used, for example something about
  93 /// the subs while playing audio only
  94 #define M_PROPERTY_UNAVAILABLE      -1
  95
  96 /// Returned if the requested action is not implemented.
  97 #define M_PROPERTY_NOT_IMPLEMENTED  -2
  98
  99 /// Returned when asking for a property that doesn't exist.
 100 #define M_PROPERTY_UNKNOWN          -3
 101
 102 /// Returned when the action can't be done (like setting the volume when edl mute).
 103 #define M_PROPERTY_DISABLED         -4
 104
 105 ///@}
 106
 107 /// \ingroup Properties
 108 /// \brief Property action callback.
 109 typedef int(*m_property_ctrl_f)(const m_option_t* prop,int action,void* arg,void *ctx);
 110
 111 /// Do an action on a property.
 112 /** \param prop_list The list of properties.
 113  *  \param prop The path of the property.
 114  *  \param action See \ref PropertyActions.
 115  *  \param arg Argument, usually a pointer to the data type used by the property.
 116  *  \return See \ref PropertyActionsReturn.
 117  */
 118 int m_property_do(const m_option_t* prop_list, const char* prop,
 119                   int action, void* arg, void *ctx);
 120
 121 /// Print a list of properties.
 122 void m_properties_print_help_list(const m_option_t* list);
 123
 124 /// Expand a property string.
 125 /** This function allows to print strings containing property values.
 126  *  ${NAME} is expanded to the value of property NAME or an empty
 127  *  string in case of error. $(NAME:STR) expand STR only if the property
 128  *  NAME is available.
 129  *
 130  *  \param prop_list An array of \ref m_option describing the available
 131  *                   properties.
 132  *  \param str The string to expand.
 133  *  \return The newly allocated expanded string.
 134  */
 135 char* m_properties_expand_string(const m_option_t* prop_list,char* str, void *ctx);
 136
 137 // Helpers to use MPlayer's properties
 138
 139 /// Do an action with an MPlayer property.
 140 int mp_property_do(const char* name,int action, void* val, void *ctx);
 141
 142 /// Get the value of a property as a string suitable for display in an UI.
 143 char* mp_property_print(const char *name, void* ctx);
 144
 145 /// \defgroup PropertyImplHelper Property implementation helpers
 146 /// \ingroup Properties
 147 /// \brief Helper functions for common property types.
 148 ///@{
 149
 150 /// Clamp a value according to \ref m_option::min and \ref m_option::max.
 151 #define M_PROPERTY_CLAMP(prop,val) do {                                 \
 152         if(((prop)->flags & M_OPT_MIN) && (val) < (prop)->min)          \
 153             (val) = (prop)->min;                                        \
 154         else if(((prop)->flags & M_OPT_MAX) && (val) > (prop)->max)     \
 155             (val) = (prop)->max;                                        \
 156     } while(0)
 157
 158 /// Implement get.
 159 int m_property_int_ro(const m_option_t* prop,int action,
 160                       void* arg,int var);
 161
 162 /// Implement set, get and step up/down.
 163 int m_property_int_range(const m_option_t* prop,int action,
 164                          void* arg,int* var);
 165
 166 /// Same as m_property_int_range but cycle.
 167 int m_property_choice(const m_option_t* prop,int action,
 168                       void* arg,int* var);
 169
 170 /// Switch betwen min and max.
 171 int m_property_flag(const m_option_t* prop,int action,
 172                     void* arg,int* var);
 173
 174 /// Implement get, print.
 175 int m_property_float_ro(const m_option_t* prop,int action,
 176                         void* arg,float var);
 177
 178 /// Implement set, get and step up/down
 179 int m_property_float_range(const m_option_t* prop,int action,
 180                            void* arg,float* var);
 181
 182 /// float with a print function which print the time in ms
 183 int m_property_delay(const m_option_t* prop,int action,
 184                      void* arg,float* var);
 185
 186 /// Implement get, print
 187 int m_property_double_ro(const m_option_t* prop,int action,
 188                          void* arg,double var);
 189
 190 /// Implement print
 191 int m_property_time_ro(const m_option_t* prop,int action,
 192                        void* arg,double var);
 193
 194 /// get/print the string
 195 int m_property_string_ro(const m_option_t* prop,int action,void* arg, char* str);
 196
 197 /// get/print a bitrate
 198 int m_property_bitrate(const m_option_t* prop,int action,void* arg,int rate);
 199
 200 ///@}
 201
 202 ///@}
 203
 204 #endif /* M_PROPERTY_H */