m_property.h

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