m_property.h

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