include/vlc_variables.h

   1 /*****************************************************************************
   2  * vlc_variables.h: variables handling
   3  *****************************************************************************
   4  * Copyright (C) 2002-2004 VLC authors and VideoLAN
   5  *
   6  * Authors: Samuel Hocevar <sam@zoy.org>
   7  *          Gildas Bazin <gbazin@netcourrier.com>
   8  *
   9  * This program is free software; you can redistribute it and/or modify it
  10  * under the terms of the GNU Lesser General Public License as published by
  11  * the Free Software Foundation; either version 2.1 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  17  * GNU Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public License
  20  * along with this program; if not, write to the Free Software Foundation,
  21  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  22  *****************************************************************************/
  23
  24 #ifndef VLC_VARIABLES_H
  25 #define VLC_VARIABLES_H 1
  26
  27 /**
  28  * \defgroup variables Variables
  29  * \ingroup vlc_object
  30  *
  31  * VLC object variables and callbacks
  32  *
  33  * @{
  34  * \file
  35  * VLC object variables and callbacks interface
  36  */
  37
  38 #define VLC_VAR_TYPE      0x00ff
  39 #define VLC_VAR_CLASS     0x00f0
  40 #define VLC_VAR_FLAGS     0xff00
  41
  42 /**
  43  * \defgroup var_type Variable types
  44  * These are the different types a vlc variable can have.
  45  * @{
  46  */
  47 #define VLC_VAR_VOID      0x0010
  48 #define VLC_VAR_BOOL      0x0020
  49 #define VLC_VAR_INTEGER   0x0030
  50 #define VLC_VAR_STRING    0x0040
  51 #define VLC_VAR_FLOAT     0x0050
  52 #define VLC_VAR_ADDRESS   0x0070
  53 #define VLC_VAR_COORDS    0x00A0
  54 /**@}*/
  55
  56 /** \defgroup var_flags Additive flags
  57  * These flags are added to the type field of the variable. Most as a result of
  58  * a var_Change() call, but some may be added at creation time
  59  * @{
  60  */
  61 #define VLC_VAR_HASCHOICE 0x0100
  62
  63 #define VLC_VAR_ISCOMMAND 0x2000
  64
  65 /** Creation flag */
  66 /* If the variable is not found on the current module
  67    search all parents and finally module config until found */
  68 #define VLC_VAR_DOINHERIT 0x8000
  69 /**@}*/
  70
  71 /**
  72  * \defgroup var_action Variable actions
  73  * These are the different actions that can be used with var_Change().
  74  * The parameters given are the meaning of the two last parameters of
  75  * var_Change() when this action is being used.
  76  * @{
  77  */
  78
  79 #define VLC_VAR_SETSTEP             0x0012
  80
  81 /**
  82  * Set the value of this variable without triggering any callbacks
  83  * \param p_val The new value
  84  * \param p_val2 Unused
  85  */
  86 #define VLC_VAR_SETVALUE            0x0013
  87
  88 #define VLC_VAR_SETTEXT             0x0014
  89 #define VLC_VAR_GETTEXT             0x0015
  90
  91 #define VLC_VAR_GETMIN              0x0016
  92 #define VLC_VAR_GETMAX              0x0017
  93 #define VLC_VAR_GETSTEP             0x0018
  94
  95 #define VLC_VAR_ADDCHOICE           0x0020
  96 #define VLC_VAR_DELCHOICE           0x0021
  97 #define VLC_VAR_CLEARCHOICES        0x0022
  98 #define VLC_VAR_GETCHOICES          0x0024
  99
 100 #define VLC_VAR_CHOICESCOUNT        0x0026
 101 #define VLC_VAR_SETMINMAX           0x0027
 102
 103 /**@}*/
 104
 105 /**
 106  * Variable actions.
 107  *
 108  * These are the different actions that can be used with var_GetAndSet().
 109  */
 110 enum vlc_var_atomic_op {
 111     VLC_VAR_BOOL_TOGGLE, /**< Invert a boolean value (param ignored) */
 112     VLC_VAR_INTEGER_ADD, /**< Add parameter to an integer value */
 113     VLC_VAR_INTEGER_OR,  /**< Binary OR over an integer bits field */
 114     VLC_VAR_INTEGER_NAND,/**< Binary NAND over an integer bits field */
 115 };
 116
 117 /**
 118  * Creates a VLC object variable.
 119  *
 120  * This function creates a named variable within a VLC object.
 121  * If a variable already exists with the same name within the same object, its
 122  * reference count is incremented instead.
 123  *
 124  * \param obj Object to hold the variable
 125  * \param name Variable name
 126  * \param type Variable type. Must be one of \ref var_type combined with
 127  *               zero or more \ref var_flags
 128  */
 129 VLC_API int var_Create(vlc_object_t *obj, const char *name, int type);
 130
 131 /**
 132  * Destroys a VLC object variable.
 133  *
 134  * This function decrements the reference count of a named variable within a
 135  * VLC object. If the reference count reaches zero, the variable is destroyed.
 136  *
 137  * \param obj Object holding the variable
 138  * \param name Variable name
 139  */
 140 VLC_API void var_Destroy(vlc_object_t *obj, const char *name);
 141
 142 /**
 143  * Performs a special action on a variable.
 144  *
 145  * \param obj Object holding the variable
 146  * \param name Variable name
 147  * \param action Action to perform. Must be one of \ref var_action
 148  */
 149 VLC_API int var_Change(vlc_object_t *obj, const char *name, int action, ...);
 150
 151 /**
 152  * Get the type of a variable.
 153  *
 154  * \see var_type
 155  *
 156  * \return The variable type if it exists
 157  *         or 0 if the variable could not be found.
 158  */
 159 VLC_API int var_Type(vlc_object_t *obj, const char *name) VLC_USED;
 160
 161 /**
 162  * Sets a variable value.
 163  *
 164  * \param obj Object holding the variable
 165  * \param name Variable name
 166  * \param val Variable value to set
 167  */
 168 VLC_API int var_Set(vlc_object_t *obj, const char *name, vlc_value_t val);
 169
 170 /**
 171  * Gets a variable value.
 172  *
 173  * \param obj Object holding the variable
 174  * \param name Variable name
 175  * \param valp Pointer to a \ref vlc_value_t object to hold the value [OUT]
 176  */
 177 VLC_API int var_Get(vlc_object_t *obj, const char *name, vlc_value_t *valp);
 178
 179 VLC_API int var_SetChecked( vlc_object_t *, const char *, int, vlc_value_t );
 180 VLC_API int var_GetChecked( vlc_object_t *, const char *, int, vlc_value_t * );
 181
 182 /**
 183  * Perform an atomic read-modify-write of a variable.
 184  *
 185  * \param obj object holding the variable
 186  * \param name variable name
 187  * \param op read-modify-write operation to perform
 188  *           (see \ref vlc_var_atomic_op)
 189  * \param value value of the variable after the modification
 190  * \retval VLC_SUCCESS Operation successful
 191  * \retval VLC_ENOVAR Variable not found
 192  *
 193  * \bug The modified value is returned rather than the original value.
 194  * As such, the original value cannot be known in the case of non-reversible
 195  * operation such as \ref VLC_VAR_INTEGER_OR and \ref VLC_VAR_INTEGER_NAND.
 196  */
 197 VLC_API int var_GetAndSet(vlc_object_t *obj, const char *name, int op,
 198                           vlc_value_t *value);
 199
 200 /**
 201  * Finds the value of a variable.
 202  *
 203  * If the specified object does not hold a variable with the specified name,
 204  * try the parent object, and iterate until the top of the objects tree. If no
 205  * match is found, the value is read from the configuration.
 206  */
 207 VLC_API int var_Inherit( vlc_object_t *, const char *, int, vlc_value_t * );
 208
 209
 210 /*****************************************************************************
 211  * Variable callbacks
 212  *****************************************************************************
 213  * int MyCallback( vlc_object_t *p_this,
 214  *                 char const *psz_variable,
 215  *                 vlc_value_t oldvalue,
 216  *                 vlc_value_t newvalue,
 217  *                 void *p_data);
 218  *****************************************************************************/
 219
 220 /**
 221  * Registers a callback for a variable.
 222  *
 223  * We store a function pointer that will be called upon variable
 224  * modification.
 225  *
 226  * \param obj Object holding the variable
 227  * \param name Variable name
 228  * \param callback Callback function pointer
 229  * \param opaque Opaque data pointer for use by the callback.
 230  *
 231  * \warning The callback function is run in the thread that calls var_Set() on
 232  *          the variable. Use proper locking. This thread may not have much
 233  *          time to spare, so keep callback functions short.
 234  *
 235  * \bug It is not possible to atomically retrieve the current value and
 236  * register a callback. As a consequence, extreme care must be taken to ensure
 237  * that the variable value cannot change before the callback is registered.
 238  * Failure to do so will result in intractable race conditions.
 239  */
 240 VLC_API void var_AddCallback(vlc_object_t *obj, const char *name,
 241                              vlc_callback_t callback, void *opaque);
 242
 243 /**
 244  * Deregisters a callback from a variable.
 245  *
 246  * The callback and opaque pointer must be supplied again, as the same callback
 247  * function might have been registered more than once.
 248  */
 249 VLC_API void var_DelCallback(vlc_object_t *obj, const char *name,
 250                              vlc_callback_t callback, void *opaque);
 251
 252 /**
 253  * Triggers callbacks on a variable.
 254  *
 255  * This triggers any callbacks registered on the named variable without
 256  * actually modifying the variable value. This is primarily useful for
 257  * variables with \ref VLC_VAR_VOID type (which do not have a value).
 258  *
 259  * \param obj Object holding the variable
 260  * \param name Variable name
 261  */
 262 VLC_API void var_TriggerCallback(vlc_object_t *obj, const char *name);
 263
 264 /**
 265  * Register a callback for a list variable
 266  *
 267  * The callback is triggered when an element is added/removed from the
 268  * list or when the list is cleared.
 269  *
 270  * See var_AddCallback().
 271  */
 272 VLC_API void var_AddListCallback( vlc_object_t *, const char *, vlc_list_callback_t, void * );
 273
 274 /**
 275  * Remove a callback from a list variable
 276  *
 277  * See var_DelCallback().
 278  */
 279 VLC_API void var_DelListCallback( vlc_object_t *, const char *, vlc_list_callback_t, void * );
 280
 281 /*****************************************************************************
 282  * helpers functions
 283  *****************************************************************************/
 284
 285 /**
 286  * Set the value of an integer variable
 287  *
 288  * \param p_obj The object that holds the variable
 289  * \param psz_name The name of the variable
 290  * \param i The new integer value of this variable
 291  */
 292 static inline int var_SetInteger( vlc_object_t *p_obj, const char *psz_name,
 293                                   int64_t i )
 294 {
 295     vlc_value_t val;
 296     val.i_int = i;
 297     return var_SetChecked( p_obj, psz_name, VLC_VAR_INTEGER, val );
 298 }
 299
 300 /**
 301  * Set the value of an boolean variable
 302  *
 303  * \param p_obj The object that holds the variable
 304  * \param psz_name The name of the variable
 305  * \param b The new boolean value of this variable
 306  */
 307 static inline int var_SetBool( vlc_object_t *p_obj, const char *psz_name, bool b )
 308 {
 309     vlc_value_t val;
 310     val.b_bool = b;
 311     return var_SetChecked( p_obj, psz_name, VLC_VAR_BOOL, val );
 312 }
 313
 314 static inline int var_SetCoords( vlc_object_t *obj, const char *name,
 315                                  int32_t x, int32_t y )
 316 {
 317     vlc_value_t val;
 318     val.coords.x = x;
 319     val.coords.y = y;
 320     return var_SetChecked (obj, name, VLC_VAR_COORDS, val);
 321 }
 322
 323 /**
 324  * Set the value of a float variable
 325  *
 326  * \param p_obj The object that holds the variable
 327  * \param psz_name The name of the variable
 328  * \param f The new float value of this variable
 329  */
 330 static inline int var_SetFloat( vlc_object_t *p_obj, const char *psz_name, float f )
 331 {
 332     vlc_value_t val;
 333     val.f_float = f;
 334     return var_SetChecked( p_obj, psz_name, VLC_VAR_FLOAT, val );
 335 }
 336
 337 /**
 338  * Set the value of a string variable
 339  *
 340  * \param p_obj The object that holds the variable
 341  * \param psz_name The name of the variable
 342  * \param psz_string The new string value of this variable
 343  */
 344 static inline int var_SetString( vlc_object_t *p_obj, const char *psz_name, const char *psz_string )
 345 {
 346     vlc_value_t val;
 347     val.psz_string = (char *)psz_string;
 348     return var_SetChecked( p_obj, psz_name, VLC_VAR_STRING, val );
 349 }
 350
 351 /**
 352  * Set the value of a pointer variable
 353  *
 354  * \param p_obj The object that holds the variable
 355  * \param psz_name The name of the variable
 356  * \param ptr The new pointer value of this variable
 357  */
 358 static inline
 359 int var_SetAddress( vlc_object_t *p_obj, const char *psz_name, void *ptr )
 360 {
 361     vlc_value_t val;
 362     val.p_address = ptr;
 363     return var_SetChecked( p_obj, psz_name, VLC_VAR_ADDRESS, val );
 364 }
 365
 366 /**
 367  * Get an integer value
 368 *
 369  * \param p_obj The object that holds the variable
 370  * \param psz_name The name of the variable
 371  */
 372 VLC_USED
 373 static inline int64_t var_GetInteger( vlc_object_t *p_obj, const char *psz_name )
 374 {
 375     vlc_value_t val;
 376     if( !var_GetChecked( p_obj, psz_name, VLC_VAR_INTEGER, &val ) )
 377         return val.i_int;
 378     else
 379         return 0;
 380 }
 381
 382 /**
 383  * Get a boolean value
 384  *
 385  * \param p_obj The object that holds the variable
 386  * \param psz_name The name of the variable
 387  */
 388 VLC_USED
 389 static inline bool var_GetBool( vlc_object_t *p_obj, const char *psz_name )
 390 {
 391     vlc_value_t val; val.b_bool = false;
 392
 393     if( !var_GetChecked( p_obj, psz_name, VLC_VAR_BOOL, &val ) )
 394         return val.b_bool;
 395     else
 396         return false;
 397 }
 398
 399 static inline void var_GetCoords( vlc_object_t *obj, const char *name,
 400                                   int32_t *px, int32_t *py )
 401 {
 402     vlc_value_t val;
 403
 404     if (likely(!var_GetChecked (obj, name, VLC_VAR_COORDS, &val)))
 405     {
 406         *px = val.coords.x;
 407         *py = val.coords.y;
 408     }
 409     else
 410         *px = *py = 0;
 411 }
 412
 413 /**
 414  * Get a float value
 415  *
 416  * \param p_obj The object that holds the variable
 417  * \param psz_name The name of the variable
 418  */
 419 VLC_USED
 420 static inline float var_GetFloat( vlc_object_t *p_obj, const char *psz_name )
 421 {
 422     vlc_value_t val; val.f_float = 0.0;
 423     if( !var_GetChecked( p_obj, psz_name, VLC_VAR_FLOAT, &val ) )
 424         return val.f_float;
 425     else
 426         return 0.0;
 427 }
 428
 429 /**
 430  * Get a string value
 431  *
 432  * \param p_obj The object that holds the variable
 433  * \param psz_name The name of the variable
 434  */
 435 VLC_USED VLC_MALLOC
 436 static inline char *var_GetString( vlc_object_t *p_obj, const char *psz_name )
 437 {
 438     vlc_value_t val; val.psz_string = NULL;
 439     if( var_GetChecked( p_obj, psz_name, VLC_VAR_STRING, &val ) )
 440         return NULL;
 441     else
 442         return val.psz_string;
 443 }
 444
 445 VLC_USED VLC_MALLOC
 446 static inline char *var_GetNonEmptyString( vlc_object_t *p_obj, const char *psz_name )
 447 {
 448     vlc_value_t val;
 449     if( var_GetChecked( p_obj, psz_name, VLC_VAR_STRING, &val ) )
 450         return NULL;
 451     if( val.psz_string && *val.psz_string )
 452         return val.psz_string;
 453     free( val.psz_string );
 454     return NULL;
 455 }
 456
 457 VLC_USED
 458 static inline void *var_GetAddress( vlc_object_t *p_obj, const char *psz_name )
 459 {
 460     vlc_value_t val;
 461     if( var_GetChecked( p_obj, psz_name, VLC_VAR_ADDRESS, &val ) )
 462         return NULL;
 463     else
 464         return val.p_address;
 465 }
 466
 467 /**
 468  * Increment an integer variable
 469  * \param p_obj the object that holds the variable
 470  * \param psz_name the name of the variable
 471  */
 472 static inline int64_t var_IncInteger( vlc_object_t *p_obj, const char *psz_name )
 473 {
 474     vlc_value_t val;
 475     val.i_int = 1;
 476     if( var_GetAndSet( p_obj, psz_name, VLC_VAR_INTEGER_ADD, &val ) )
 477         return 0;
 478     return val.i_int;
 479 }
 480
 481 /**
 482  * Decrement an integer variable
 483  * \param p_obj the object that holds the variable
 484  * \param psz_name the name of the variable
 485  */
 486 static inline int64_t var_DecInteger( vlc_object_t *p_obj, const char *psz_name )
 487 {
 488     vlc_value_t val;
 489     val.i_int = -1;
 490     if( var_GetAndSet( p_obj, psz_name, VLC_VAR_INTEGER_ADD, &val ) )
 491         return 0;
 492     return val.i_int;
 493 }
 494
 495 static inline uint64_t var_OrInteger( vlc_object_t *obj, const char *name,
 496                                       unsigned v )
 497 {
 498     vlc_value_t val;
 499     val.i_int = v;
 500     if( var_GetAndSet( obj, name, VLC_VAR_INTEGER_OR, &val ) )
 501         return 0;
 502     return val.i_int;
 503 }
 504
 505 static inline uint64_t var_NAndInteger( vlc_object_t *obj, const char *name,
 506                                         unsigned v )
 507 {
 508     vlc_value_t val;
 509     val.i_int = v;
 510     if( var_GetAndSet( obj, name, VLC_VAR_INTEGER_NAND, &val ) )
 511         return 0;
 512     return val.i_int;
 513 }
 514
 515 /**
 516  * Create a integer variable with inherit and get its value.
 517  *
 518  * \param p_obj The object that holds the variable
 519  * \param psz_name The name of the variable
 520  */
 521 VLC_USED
 522 static inline int64_t var_CreateGetInteger( vlc_object_t *p_obj, const char *psz_name )
 523 {
 524     var_Create( p_obj, psz_name, VLC_VAR_INTEGER | VLC_VAR_DOINHERIT );
 525     return var_GetInteger( p_obj, psz_name );
 526 }
 527
 528 /**
 529  * Create a boolean variable with inherit and get its value.
 530  *
 531  * \param p_obj The object that holds the variable
 532  * \param psz_name The name of the variable
 533  */
 534 VLC_USED
 535 static inline bool var_CreateGetBool( vlc_object_t *p_obj, const char *psz_name )
 536 {
 537     var_Create( p_obj, psz_name, VLC_VAR_BOOL | VLC_VAR_DOINHERIT );
 538     return var_GetBool( p_obj, psz_name );
 539 }
 540
 541 /**
 542  * Create a float variable with inherit and get its value.
 543  *
 544  * \param p_obj The object that holds the variable
 545  * \param psz_name The name of the variable
 546  */
 547 VLC_USED
 548 static inline float var_CreateGetFloat( vlc_object_t *p_obj, const char *psz_name )
 549 {
 550     var_Create( p_obj, psz_name, VLC_VAR_FLOAT | VLC_VAR_DOINHERIT );
 551     return var_GetFloat( p_obj, psz_name );
 552 }
 553
 554 /**
 555  * Create a string variable with inherit and get its value.
 556  *
 557  * \param p_obj The object that holds the variable
 558  * \param psz_name The name of the variable
 559  */
 560 VLC_USED VLC_MALLOC
 561 static inline char *var_CreateGetString( vlc_object_t *p_obj,
 562                                            const char *psz_name )
 563 {
 564     var_Create( p_obj, psz_name, VLC_VAR_STRING | VLC_VAR_DOINHERIT );
 565     return var_GetString( p_obj, psz_name );
 566 }
 567
 568 VLC_USED VLC_MALLOC
 569 static inline char *var_CreateGetNonEmptyString( vlc_object_t *p_obj,
 570                                                    const char *psz_name )
 571 {
 572     var_Create( p_obj, psz_name, VLC_VAR_STRING | VLC_VAR_DOINHERIT );
 573     return var_GetNonEmptyString( p_obj, psz_name );
 574 }
 575
 576 /**
 577  * Create an address variable with inherit and get its value.
 578  *
 579  * \param p_obj The object that holds the variable
 580  * \param psz_name The name of the variable
 581  */
 582 VLC_USED
 583 static inline void *var_CreateGetAddress( vlc_object_t *p_obj,
 584                                            const char *psz_name )
 585 {
 586     var_Create( p_obj, psz_name, VLC_VAR_ADDRESS | VLC_VAR_DOINHERIT );
 587     return var_GetAddress( p_obj, psz_name );
 588 }
 589
 590 /**
 591  * Create a integer command variable with inherit and get its value.
 592  *
 593  * \param p_obj The object that holds the variable
 594  * \param psz_name The name of the variable
 595  */
 596 VLC_USED
 597 static inline int64_t var_CreateGetIntegerCommand( vlc_object_t *p_obj, const char *psz_name )
 598 {
 599     var_Create( p_obj, psz_name, VLC_VAR_INTEGER | VLC_VAR_DOINHERIT
 600                                    | VLC_VAR_ISCOMMAND );
 601     return var_GetInteger( p_obj, psz_name );
 602 }
 603
 604 /**
 605  * Create a boolean command variable with inherit and get its value.
 606  *
 607  * \param p_obj The object that holds the variable
 608  * \param psz_name The name of the variable
 609  */
 610 VLC_USED
 611 static inline bool var_CreateGetBoolCommand( vlc_object_t *p_obj, const char *psz_name )
 612 {
 613     var_Create( p_obj, psz_name, VLC_VAR_BOOL | VLC_VAR_DOINHERIT
 614                                    | VLC_VAR_ISCOMMAND );
 615     return var_GetBool( p_obj, psz_name );
 616 }
 617
 618 /**
 619  * Create a float command variable with inherit and get its value.
 620  *
 621  * \param p_obj The object that holds the variable
 622  * \param psz_name The name of the variable
 623  */
 624 VLC_USED
 625 static inline float var_CreateGetFloatCommand( vlc_object_t *p_obj, const char *psz_name )
 626 {
 627     var_Create( p_obj, psz_name, VLC_VAR_FLOAT | VLC_VAR_DOINHERIT
 628                                    | VLC_VAR_ISCOMMAND );
 629     return var_GetFloat( p_obj, psz_name );
 630 }
 631
 632 /**
 633  * Create a string command variable with inherit and get its value.
 634  *
 635  * \param p_obj The object that holds the variable
 636  * \param psz_name The name of the variable
 637  */
 638 VLC_USED VLC_MALLOC
 639 static inline char *var_CreateGetStringCommand( vlc_object_t *p_obj,
 640                                            const char *psz_name )
 641 {
 642     var_Create( p_obj, psz_name, VLC_VAR_STRING | VLC_VAR_DOINHERIT
 643                                    | VLC_VAR_ISCOMMAND );
 644     return var_GetString( p_obj, psz_name );
 645 }
 646
 647 VLC_USED VLC_MALLOC
 648 static inline char *var_CreateGetNonEmptyStringCommand( vlc_object_t *p_obj,
 649                                                    const char *psz_name )
 650 {
 651     var_Create( p_obj, psz_name, VLC_VAR_STRING | VLC_VAR_DOINHERIT
 652                                    | VLC_VAR_ISCOMMAND );
 653     return var_GetNonEmptyString( p_obj, psz_name );
 654 }
 655
 656 VLC_USED
 657 static inline int var_CountChoices( vlc_object_t *p_obj, const char *psz_name )
 658 {
 659     size_t count;
 660     if( var_Change( p_obj, psz_name, VLC_VAR_CHOICESCOUNT, &count ) )
 661         return 0;
 662     return count;
 663 }
 664
 665 static inline bool var_ToggleBool( vlc_object_t *p_obj, const char *psz_name )
 666 {
 667     vlc_value_t val;
 668     if( var_GetAndSet( p_obj, psz_name, VLC_VAR_BOOL_TOGGLE, &val ) )
 669         return false;
 670     return val.b_bool;
 671 }
 672
 673 VLC_USED
 674 static inline bool var_InheritBool( vlc_object_t *obj, const char *name )
 675 {
 676     vlc_value_t val;
 677
 678     if( var_Inherit( obj, name, VLC_VAR_BOOL, &val ) )
 679         val.b_bool = false;
 680     return val.b_bool;
 681 }
 682
 683 VLC_USED
 684 static inline int64_t var_InheritInteger( vlc_object_t *obj, const char *name )
 685 {
 686     vlc_value_t val;
 687
 688     if( var_Inherit( obj, name, VLC_VAR_INTEGER, &val ) )
 689         val.i_int = 0;
 690     return val.i_int;
 691 }
 692
 693 VLC_USED
 694 static inline float var_InheritFloat( vlc_object_t *obj, const char *name )
 695 {
 696     vlc_value_t val;
 697
 698     if( var_Inherit( obj, name, VLC_VAR_FLOAT, &val ) )
 699         val.f_float = 0.;
 700     return val.f_float;
 701 }
 702
 703 VLC_USED VLC_MALLOC
 704 static inline char *var_InheritString( vlc_object_t *obj, const char *name )
 705 {
 706     vlc_value_t val;
 707
 708     if( var_Inherit( obj, name, VLC_VAR_STRING, &val ) )
 709         val.psz_string = NULL;
 710     else if( val.psz_string && !*val.psz_string )
 711     {
 712         free( val.psz_string );
 713         val.psz_string = NULL;
 714     }
 715     return val.psz_string;
 716 }
 717
 718 VLC_USED
 719 static inline void *var_InheritAddress( vlc_object_t *obj, const char *name )
 720 {
 721     vlc_value_t val;
 722
 723     if( var_Inherit( obj, name, VLC_VAR_ADDRESS, &val ) )
 724         val.p_address = NULL;
 725     return val.p_address;
 726 }
 727
 728
 729 /**
 730  * Inherit a string as a fractional value.
 731  *
 732  * This function inherits a string, and interprets it as an unsigned rational
 733  * number, i.e. a fraction. It also accepts a normally formatted floating point
 734  * number.
 735  *
 736  * \warning The caller shall perform any and all necessary boundary checks.
 737  *
 738  * \note The rational number is always reduced,
 739  * i.e. the returned numerator and denominator are always co-prime numbers.
 740  *
 741  * \note Fraction with zero as denominator are considered valid,
 742  * including the undefined form zero-by-zero.
 743  *
 744  * \return Zero on success, an error if parsing fails.
 745   */
 746 VLC_API int var_InheritURational(vlc_object_t *obj, unsigned *num,
 747                                  unsigned *den, const char *name);
 748
 749 /**
 750  * Parses a string with multiple options.
 751  *
 752  * Parses a set of colon-separated or semicolon-separated
 753  * <code>name=value</code> pairs.
 754  * Some access (or access_demux) plugins uses this scheme
 755  * in media resource location.
 756  * @note Only trusted/safe variables are allowed. This is intended.
 757  *
 758  * @warning Only use this for plugins implementing VLC-specific resource
 759  * location schemes. This would not make any sense for standardized ones.
 760  *
 761  * @param obj VLC object on which to set variables (and emit error messages)
 762  * @param mrl string to parse
 763  * @param pref prefix to prepend to option names in the string
 764  *
 765  * @return VLC_ENOMEM on error, VLC_SUCCESS on success.
 766  */
 767 VLC_API int var_LocationParse(vlc_object_t *, const char *mrl, const char *prefix);
 768
 769 #ifndef DOC
 770 #define var_Create(a,b,c) var_Create(VLC_OBJECT(a), b, c)
 771 #define var_Destroy(a,b) var_Destroy(VLC_OBJECT(a), b)
 772 #define var_Change(a,b,...) var_Change(VLC_OBJECT(a), b, __VA_ARGS__)
 773 #define var_Type(a,b) var_Type(VLC_OBJECT(a), b)
 774 #define var_Set(a,b,c) var_Set(VLC_OBJECT(a), b, c)
 775 #define var_Get(a,b,c) var_Get(VLC_OBJECT(a), b, c)
 776 #define var_SetChecked(o,n,t,v) var_SetChecked(VLC_OBJECT(o), n, t, v)
 777 #define var_GetChecked(o,n,t,v) var_GetChecked(VLC_OBJECT(o), n, t, v)
 778
 779 #define var_AddCallback(a,b,c,d) var_AddCallback(VLC_OBJECT(a), b, c, d)
 780 #define var_DelCallback(a,b,c,d) var_DelCallback(VLC_OBJECT(a), b, c, d)
 781 #define var_TriggerCallback(a,b) var_TriggerCallback(VLC_OBJECT(a), b)
 782 #define var_AddListCallback(a,b,c,d) \
 783         var_AddListCallback(VLC_OBJECT(a), b, c, d)
 784 #define var_DelListCallback(a,b,c,d) \
 785         var_DelListCallback(VLC_OBJECT(a), b, c, d)
 786
 787 #define var_SetInteger(a,b,c) var_SetInteger(VLC_OBJECT(a), b, c)
 788 #define var_SetBool(a,b,c) var_SetBool(VLC_OBJECT(a), b, c)
 789 #define var_SetCoords(o,n,x,y) var_SetCoords(VLC_OBJECT(o), n, x, y)
 790 #define var_SetFloat(a,b,c) var_SetFloat(VLC_OBJECT(a), b, c)
 791 #define var_SetString(a,b,c) var_SetString(VLC_OBJECT(a), b, c)
 792 #define var_SetAddress(o, n, p) var_SetAddress(VLC_OBJECT(o), n, p)
 793
 794 #define var_GetCoords(o,n,x,y) var_GetCoords(VLC_OBJECT(o), n, x, y)
 795
 796 #define var_IncInteger(a,b) var_IncInteger(VLC_OBJECT(a), b)
 797 #define var_DecInteger(a,b) var_DecInteger(VLC_OBJECT(a), b)
 798 #define var_OrInteger(a,b,c) var_OrInteger(VLC_OBJECT(a), b, c)
 799 #define var_NAndInteger(a,b,c) var_NAndInteger(VLC_OBJECT(a), b, c)
 800
 801 #define var_CreateGetInteger(a,b) var_CreateGetInteger(VLC_OBJECT(a), b)
 802 #define var_CreateGetBool(a,b) var_CreateGetBool(VLC_OBJECT(a), b)
 803 #define var_CreateGetFloat(a,b) var_CreateGetFloat(VLC_OBJECT(a), b)
 804 #define var_CreateGetString(a,b) var_CreateGetString(VLC_OBJECT(a), b)
 805 #define var_CreateGetNonEmptyString(a,b) \
 806         var_CreateGetNonEmptyString(VLC_OBJECT(a), b)
 807 #define var_CreateGetAddress(a,b) var_CreateGetAddress( VLC_OBJECT(a), b)
 808
 809 #define var_CreateGetIntegerCommand(a,b)   var_CreateGetIntegerCommand( VLC_OBJECT(a),b)
 810 #define var_CreateGetBoolCommand(a,b)   var_CreateGetBoolCommand( VLC_OBJECT(a),b)
 811 #define var_CreateGetFloatCommand(a,b)   var_CreateGetFloatCommand( VLC_OBJECT(a),b)
 812 #define var_CreateGetStringCommand(a,b)   var_CreateGetStringCommand( VLC_OBJECT(a),b)
 813 #define var_CreateGetNonEmptyStringCommand(a,b)   var_CreateGetNonEmptyStringCommand( VLC_OBJECT(a),b)
 814
 815 #define var_CountChoices(a,b) var_CountChoices(VLC_OBJECT(a),b)
 816 #define var_ToggleBool(a,b) var_ToggleBool(VLC_OBJECT(a),b )
 817
 818 #define var_InheritBool(o, n) var_InheritBool(VLC_OBJECT(o), n)
 819 #define var_InheritInteger(o, n) var_InheritInteger(VLC_OBJECT(o), n)
 820 #define var_InheritFloat(o, n) var_InheritFloat(VLC_OBJECT(o), n)
 821 #define var_InheritString(o, n) var_InheritString(VLC_OBJECT(o), n)
 822 #define var_InheritAddress(o, n) var_InheritAddress(VLC_OBJECT(o), n)
 823 #define var_InheritURational(a,b,c,d) var_InheritURational(VLC_OBJECT(a), b, c, d)
 824
 825 #define var_GetInteger(a,b) var_GetInteger(VLC_OBJECT(a),b)
 826 #define var_GetBool(a,b) var_GetBool(VLC_OBJECT(a),b)
 827 #define var_GetFloat(a,b) var_GetFloat(VLC_OBJECT(a),b)
 828 #define var_GetString(a,b) var_GetString(VLC_OBJECT(a),b)
 829 #define var_GetNonEmptyString(a,b) var_GetNonEmptyString( VLC_OBJECT(a),b)
 830 #define var_GetAddress(a,b) var_GetAddress(VLC_OBJECT(a),b)
 831
 832 #define var_LocationParse(o, m, p) var_LocationParse(VLC_OBJECT(o), m, p)
 833 #endif
 834
 835 /**
 836  * @}
 837  */
 838 #endif /*  _VLC_VARIABLES_H */