include/vlc_variables.h

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