m_property.h

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