include/vlc_variables.h

   1 /*****************************************************************************
   2  * variables.h: variables handling
   3  *****************************************************************************
   4  * Copyright (C) 2002-2004 the VideoLAN team
   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
  11  * it under the terms of the GNU General Public License as published by
  12  * the Free Software Foundation; either version 2 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 General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public License
  21  * along with this program; if not, write to the Free Software
  22  * Foundation, 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  * \file
  30  * This file defines functions and structures for dynamic variables in vlc
  31  */
  32
  33 /**
  34  * \defgroup variables Variables
  35  *
  36  * Functions for using the object variables in vlc.
  37  *
  38  * Vlc have a very powerful "object variable" infrastructure useful
  39  * for many things.
  40  *
  41  * @{
  42  */
  43
  44 /*****************************************************************************
  45  * Variable types - probably very incomplete
  46  *****************************************************************************/
  47 #define VLC_VAR_TYPE      0x00ff
  48 #define VLC_VAR_FLAGS     0xff00
  49
  50 /** \defgroup var_flags Additive flags
  51  * These flags are added to the type field of the variable. Most as a result of
  52  * a __var_Change() call, but some may be added at creation time
  53  * @{
  54  */
  55 #define VLC_VAR_HASCHOICE 0x0100
  56 #define VLC_VAR_HASMIN    0x0200
  57 #define VLC_VAR_HASMAX    0x0400
  58 #define VLC_VAR_HASSTEP   0x0800
  59
  60 #define VLC_VAR_ISCOMMAND 0x2000
  61
  62 /** Creation flag */
  63 #define VLC_VAR_DOINHERIT 0x8000
  64 /**@}*/
  65
  66 /**
  67  * \defgroup var_action Variable actions
  68  * These are the different actions that can be used with __var_Change().
  69  * The parameters given are the meaning of the two last parameters of
  70  * __var_Change() when this action is being used.
  71  * @{
  72  */
  73
  74 /**
  75  * Set the minimum value of this variable
  76  * \param p_val The new minimum value
  77  * \param p_val2 Unused
  78  */
  79 #define VLC_VAR_SETMIN              0x0010
  80 /**
  81  * Set the maximum value of this variable
  82  * \param p_val The new maximum value
  83  * \param p_val2 Unused
  84  */
  85 #define VLC_VAR_SETMAX              0x0011
  86 #define VLC_VAR_SETSTEP             0x0012
  87
  88 /**
  89  * Set the value of this variable without triggering any callbacks
  90  * \param p_val The new value
  91  * \param p_val2 Unused
  92  */
  93 #define VLC_VAR_SETVALUE            0x0013
  94
  95 #define VLC_VAR_SETTEXT             0x0014
  96 #define VLC_VAR_GETTEXT             0x0015
  97
  98 #define VLC_VAR_GETMIN              0x0016
  99 #define VLC_VAR_GETMAX              0x0017
 100 #define VLC_VAR_GETSTEP             0x0018
 101
 102 #define VLC_VAR_ADDCHOICE           0x0020
 103 #define VLC_VAR_DELCHOICE           0x0021
 104 #define VLC_VAR_CLEARCHOICES        0x0022
 105 #define VLC_VAR_SETDEFAULT          0x0023
 106 #define VLC_VAR_GETCHOICES          0x0024
 107 #define VLC_VAR_FREECHOICES         0x0025
 108 #define VLC_VAR_GETLIST             0x0026
 109 #define VLC_VAR_FREELIST            0x0027
 110 #define VLC_VAR_CHOICESCOUNT        0x0028
 111
 112 #define VLC_VAR_INHERITVALUE        0x0030
 113 #define VLC_VAR_TRIGGER_CALLBACKS   0x0035
 114
 115 #define VLC_VAR_SETISCOMMAND        0x0040
 116 /**@}*/
 117
 118 /*****************************************************************************
 119  * Prototypes
 120  *****************************************************************************/
 121 VLC_EXPORT( int, __var_Create, ( vlc_object_t *, const char *, int ) );
 122 VLC_EXPORT( int, __var_Destroy, ( vlc_object_t *, const char * ) );
 123
 124 VLC_EXPORT( int, __var_Change, ( vlc_object_t *, const char *, int, vlc_value_t *, vlc_value_t * ) );
 125
 126 VLC_EXPORT( int, __var_Type, ( vlc_object_t *, const char * ) );
 127 VLC_EXPORT( int, __var_Set, ( vlc_object_t *, const char *, vlc_value_t ) );
 128 VLC_EXPORT( int, __var_Get, ( vlc_object_t *, const char *, vlc_value_t * ) );
 129
 130 #define var_Command(a,b,c,d,e) __var_Command( VLC_OBJECT( a ), b, c, d, e )
 131 VLC_EXPORT( int, __var_Command, ( vlc_object_t *, const char *, const char *, const char *, char ** ) );
 132
 133 VLC_EXPORT( vlc_mutex_t *, var_AcquireMutex, ( const char * ) );
 134
 135 /**
 136  * __var_Create() with automatic casting.
 137  */
 138 #define var_Create(a,b,c) __var_Create( VLC_OBJECT(a), b, c )
 139 /**
 140  * __var_Destroy() with automatic casting
 141  */
 142 #define var_Destroy(a,b) __var_Destroy( VLC_OBJECT(a), b )
 143
 144 /**
 145  * __var_Change() with automatic casting
 146  */
 147 #define var_Change(a,b,c,d,e) __var_Change( VLC_OBJECT(a), b, c, d, e )
 148
 149 /**
 150  * __var_Type() with automatic casting
 151  */
 152 #define var_Type(a,b) __var_Type( VLC_OBJECT(a), b )
 153 /**
 154  * __var_Set() with automatic casting
 155  */
 156 #define var_Set(a,b,c) __var_Set( VLC_OBJECT(a), b, c )
 157 /**
 158  * __var_Get() with automatic casting
 159  */
 160 #define var_Get(a,b,c) __var_Get( VLC_OBJECT(a), b, c )
 161
 162 /*****************************************************************************
 163  * Variable callbacks
 164  *****************************************************************************
 165  * int MyCallback( vlc_object_t *p_this,
 166  *                 char const *psz_variable,
 167  *                 vlc_value_t oldvalue,
 168  *                 vlc_value_t newvalue,
 169  *                 void *p_data);
 170  *****************************************************************************/
 171 VLC_EXPORT( int, __var_AddCallback, ( vlc_object_t *, const char *, vlc_callback_t, void * ) );
 172 VLC_EXPORT( int, __var_DelCallback, ( vlc_object_t *, const char *, vlc_callback_t, void * ) );
 173 VLC_EXPORT( int, __var_TriggerCallback, ( vlc_object_t *, const char * ) );
 174
 175 /**
 176  * __var_AddCallback() with automatic casting
 177  */
 178 #define var_AddCallback(a,b,c,d) __var_AddCallback( VLC_OBJECT(a), b, c, d )
 179
 180 /**
 181  * __var_DelCallback() with automatic casting
 182  */
 183 #define var_DelCallback(a,b,c,d) __var_DelCallback( VLC_OBJECT(a), b, c, d )
 184
 185 /**
 186  * __var_TriggerCallback() with automatic casting
 187  */
 188 #define var_TriggerCallback(a,b) __var_TriggerCallback( VLC_OBJECT(a), b )
 189
 190 /*****************************************************************************
 191  * helpers functions
 192  *****************************************************************************/
 193
 194 /**
 195  * Set the value of an integer variable
 196  *
 197  * \param p_obj The object that holds the variable
 198  * \param psz_name The name of the variable
 199  * \param i The new integer value of this variable
 200  */
 201 static inline int __var_SetInteger( vlc_object_t *p_obj, const char *psz_name, int i )
 202 {
 203     vlc_value_t val;
 204     val.i_int = i;
 205     return __var_Set( p_obj, psz_name, val );
 206 }
 207 #define var_SetInteger(a,b,c)   __var_SetInteger( VLC_OBJECT(a),b,c)
 208 /**
 209  * Set the value of an boolean variable
 210  *
 211  * \param p_obj The object that holds the variable
 212  * \param psz_name The name of the variable
 213  * \param b The new boolean value of this variable
 214  */
 215 static inline int __var_SetBool( vlc_object_t *p_obj, const char *psz_name, bool b )
 216 {
 217     vlc_value_t val;
 218     val.b_bool = b;
 219     return __var_Set( p_obj, psz_name, val );
 220 }
 221
 222 /**
 223  * Set the value of a time variable
 224  *
 225  * \param p_obj The object that holds the variable
 226  * \param psz_name The name of the variable
 227  * \param i The new time value of this variable
 228  */
 229 static inline int __var_SetTime( vlc_object_t *p_obj, const char *psz_name, int64_t i )
 230 {
 231     vlc_value_t val;
 232     val.i_time = i;
 233     return __var_Set( p_obj, psz_name, val );
 234 }
 235
 236 /**
 237  * Set the value of a float variable
 238  *
 239  * \param p_obj The object that holds the variable
 240  * \param psz_name The name of the variable
 241  * \param f The new float value of this variable
 242  */
 243 static inline int __var_SetFloat( vlc_object_t *p_obj, const char *psz_name, float f )
 244 {
 245     vlc_value_t val;
 246     val.f_float = f;
 247     return __var_Set( p_obj, psz_name, val );
 248 }
 249
 250 /**
 251  * Set the value of a string variable
 252  *
 253  * \param p_obj The object that holds the variable
 254  * \param psz_name The name of the variable
 255  * \param psz_string The new string value of this variable
 256  */
 257 static inline int __var_SetString( vlc_object_t *p_obj, const char *psz_name, const char *psz_string )
 258 {
 259     vlc_value_t val;
 260     val.psz_string = (char *)psz_string;
 261     return __var_Set( p_obj, psz_name, val );
 262 }
 263
 264 /**
 265  * Trigger the callbacks on a void variable
 266  *
 267  * \param p_obj The object that holds the variable
 268  * \param psz_name The name of the variable
 269  */
 270 static inline int __var_SetVoid( vlc_object_t *p_obj, const char *psz_name )
 271 {
 272     vlc_value_t val;
 273     val.b_bool = true;
 274     return __var_Set( p_obj, psz_name, val );
 275 }
 276 #define var_SetVoid(a,b)        __var_SetVoid( VLC_OBJECT(a),b)
 277
 278 /**
 279  * __var_SetBool() with automatic casting
 280  */
 281 #define var_SetBool(a,b,c)   __var_SetBool( VLC_OBJECT(a),b,c)
 282
 283 /**
 284  * __var_SetTime() with automatic casting
 285  */
 286 #define var_SetTime(a,b,c)      __var_SetTime( VLC_OBJECT(a),b,c)
 287 /**
 288  * __var_SetFloat() with automatic casting
 289  */
 290 #define var_SetFloat(a,b,c)     __var_SetFloat( VLC_OBJECT(a),b,c)
 291 /**
 292  * __var_SetString() with automatic casting
 293  */
 294 #define var_SetString(a,b,c)     __var_SetString( VLC_OBJECT(a),b,c)
 295
 296 /**
 297  * Get an integer value
 298 *
 299  * \param p_obj The object that holds the variable
 300  * \param psz_name The name of the variable
 301  */
 302 static inline int __var_GetInteger( vlc_object_t *p_obj, const char *psz_name )
 303 {
 304     vlc_value_t val;val.i_int = 0;
 305     if( !__var_Get( p_obj, psz_name, &val ) )
 306         return val.i_int;
 307     else
 308         return 0;
 309 }
 310
 311 /**
 312  * Get a boolean value
 313  *
 314  * \param p_obj The object that holds the variable
 315  * \param psz_name The name of the variable
 316  */
 317 static inline int __var_GetBool( vlc_object_t *p_obj, const char *psz_name )
 318 {
 319     vlc_value_t val; val.b_bool = false;
 320     if( !__var_Get( p_obj, psz_name, &val ) )
 321         return val.b_bool;
 322     else
 323         return false;
 324 }
 325
 326 /**
 327  * Get a time value
 328  *
 329  * \param p_obj The object that holds the variable
 330  * \param psz_name The name of the variable
 331  */
 332 static inline int64_t __var_GetTime( vlc_object_t *p_obj, const char *psz_name )
 333 {
 334     vlc_value_t val; val.i_time = 0L;
 335     if( !__var_Get( p_obj, psz_name, &val ) )
 336         return val.i_time;
 337     else
 338         return 0;
 339 }
 340
 341 /**
 342  * Get a float value
 343  *
 344  * \param p_obj The object that holds the variable
 345  * \param psz_name The name of the variable
 346  */
 347 static inline float __var_GetFloat( vlc_object_t *p_obj, const char *psz_name )
 348 {
 349     vlc_value_t val; val.f_float = 0.0;
 350     if( !__var_Get( p_obj, psz_name, &val ) )
 351         return val.f_float;
 352     else
 353         return 0.0;
 354 }
 355
 356 /**
 357  * Get a string value
 358  *
 359  * \param p_obj The object that holds the variable
 360  * \param psz_name The name of the variable
 361  */
 362 static inline char *__var_GetString( vlc_object_t *p_obj, const char *psz_name )
 363 {
 364     vlc_value_t val; val.psz_string = NULL;
 365     if( __var_Get( p_obj, psz_name, &val ) )
 366         return NULL;
 367     else
 368         return val.psz_string;
 369 }
 370
 371 static inline char *__var_GetNonEmptyString( vlc_object_t *obj, const char *name )
 372 {
 373     vlc_value_t val;
 374     if( __var_Get( obj, name, &val ) )
 375         return NULL;
 376     if( *val.psz_string )
 377         return val.psz_string;
 378     free( val.psz_string );
 379     return NULL;
 380 }
 381
 382
 383 /**
 384  * __var_GetInteger() with automatic casting
 385  */
 386 #define var_GetInteger(a,b)   __var_GetInteger( VLC_OBJECT(a),b)
 387 /**
 388  * __var_GetBool() with automatic casting
 389  */
 390 #define var_GetBool(a,b)   __var_GetBool( VLC_OBJECT(a),b)
 391 /**
 392  * __var_GetTime() with automatic casting
 393  */
 394 #define var_GetTime(a,b)   __var_GetTime( VLC_OBJECT(a),b)
 395 /**
 396  * __var_GetFloat() with automatic casting
 397  */
 398 #define var_GetFloat(a,b)   __var_GetFloat( VLC_OBJECT(a),b)
 399 /**
 400  * __var_GetString() with automatic casting
 401  */
 402 #define var_GetString(a,b)   __var_GetString( VLC_OBJECT(a),b)
 403 #define var_GetNonEmptyString(a,b)   __var_GetNonEmptyString( VLC_OBJECT(a),b)
 404
 405
 406
 407 /**
 408  * Increment an integer variable
 409  * \param p_obj the object that holds the variable
 410  * \param psz_name the name of the variable
 411  */
 412 static inline void __var_IncInteger( vlc_object_t *p_obj, const char *psz_name )
 413 {
 414     int i_val = __var_GetInteger( p_obj, psz_name );
 415     __var_SetInteger( p_obj, psz_name, ++i_val );
 416 }
 417 #define var_IncInteger(a,b) __var_IncInteger( VLC_OBJECT(a), b )
 418
 419 /**
 420  * Decrement an integer variable
 421  * \param p_obj the object that holds the variable
 422  * \param psz_name the name of the variable
 423  */
 424 static inline void __var_DecInteger( vlc_object_t *p_obj, const char *psz_name )
 425 {
 426     int i_val = __var_GetInteger( p_obj, psz_name );
 427     __var_SetInteger( p_obj, psz_name, --i_val );
 428 }
 429 #define var_DecInteger(a,b) __var_DecInteger( VLC_OBJECT(a), b )
 430
 431 /**
 432  * Create a integer variable with inherit and get its value.
 433  *
 434  * \param p_obj The object that holds the variable
 435  * \param psz_name The name of the variable
 436  */
 437 static inline int __var_CreateGetInteger( vlc_object_t *p_obj, const char *psz_name )
 438 {
 439     __var_Create( p_obj, psz_name, VLC_VAR_INTEGER | VLC_VAR_DOINHERIT );
 440     return __var_GetInteger( p_obj, psz_name );
 441 }
 442
 443 /**
 444  * Create a boolean variable with inherit and get its value.
 445  *
 446  * \param p_obj The object that holds the variable
 447  * \param psz_name The name of the variable
 448  */
 449 static inline int __var_CreateGetBool( vlc_object_t *p_obj, const char *psz_name )
 450 {
 451     __var_Create( p_obj, psz_name, VLC_VAR_BOOL | VLC_VAR_DOINHERIT );
 452     return __var_GetBool( p_obj, psz_name );
 453 }
 454
 455 /**
 456  * Create a time variable with inherit and get its value.
 457  *
 458  * \param p_obj The object that holds the variable
 459  * \param psz_name The name of the variable
 460  */
 461 static inline int64_t __var_CreateGetTime( vlc_object_t *p_obj, const char *psz_name )
 462 {
 463     __var_Create( p_obj, psz_name, VLC_VAR_TIME | VLC_VAR_DOINHERIT );
 464     return __var_GetTime( p_obj, psz_name );
 465 }
 466
 467 /**
 468  * Create a float variable with inherit and get its value.
 469  *
 470  * \param p_obj The object that holds the variable
 471  * \param psz_name The name of the variable
 472  */
 473 static inline float __var_CreateGetFloat( vlc_object_t *p_obj, const char *psz_name )
 474 {
 475     __var_Create( p_obj, psz_name, VLC_VAR_FLOAT | VLC_VAR_DOINHERIT );
 476     return __var_GetFloat( p_obj, psz_name );
 477 }
 478
 479 /**
 480  * Create a string variable with inherit and get its value.
 481  *
 482  * \param p_obj The object that holds the variable
 483  * \param psz_name The name of the variable
 484  */
 485 static inline char *__var_CreateGetString( vlc_object_t *p_obj,
 486                                            const char *psz_name )
 487 {
 488     __var_Create( p_obj, psz_name, VLC_VAR_STRING | VLC_VAR_DOINHERIT );
 489     return __var_GetString( p_obj, psz_name );
 490 }
 491
 492 static inline char *__var_CreateGetNonEmptyString( vlc_object_t *p_obj,
 493                                                    const char *psz_name )
 494 {
 495     __var_Create( p_obj, psz_name, VLC_VAR_STRING | VLC_VAR_DOINHERIT );
 496     return __var_GetNonEmptyString( p_obj, psz_name );
 497 }
 498
 499 /**
 500  * __var_CreateGetInteger() with automatic casting
 501  */
 502 #define var_CreateGetInteger(a,b)   __var_CreateGetInteger( VLC_OBJECT(a),b)
 503 /**
 504  * __var_CreateGetBool() with automatic casting
 505  */
 506 #define var_CreateGetBool(a,b)   __var_CreateGetBool( VLC_OBJECT(a),b)
 507 /**
 508  * __var_CreateGetTime() with automatic casting
 509  */
 510 #define var_CreateGetTime(a,b)   __var_CreateGetTime( VLC_OBJECT(a),b)
 511 /**
 512  * __var_CreateGetFloat() with automatic casting
 513  */
 514 #define var_CreateGetFloat(a,b)   __var_CreateGetFloat( VLC_OBJECT(a),b)
 515 /**
 516  * __var_CreateGetString() with automatic casting
 517  */
 518 #define var_CreateGetString(a,b)   __var_CreateGetString( VLC_OBJECT(a),b)
 519 #define var_CreateGetNonEmptyString(a,b)   __var_CreateGetNonEmptyString( VLC_OBJECT(a),b)
 520
 521 /**
 522  * Create a integer command variable with inherit and get its value.
 523  *
 524  * \param p_obj The object that holds the variable
 525  * \param psz_name The name of the variable
 526  */
 527 static inline int __var_CreateGetIntegerCommand( vlc_object_t *p_obj, const char *psz_name )
 528 {
 529     __var_Create( p_obj, psz_name, VLC_VAR_INTEGER | VLC_VAR_DOINHERIT
 530                                    | VLC_VAR_ISCOMMAND );
 531     return __var_GetInteger( p_obj, psz_name );
 532 }
 533
 534 /**
 535  * Create a boolean command variable with inherit and get its value.
 536  *
 537  * \param p_obj The object that holds the variable
 538  * \param psz_name The name of the variable
 539  */
 540 static inline int __var_CreateGetBoolCommand( vlc_object_t *p_obj, const char *psz_name )
 541 {
 542     __var_Create( p_obj, psz_name, VLC_VAR_BOOL | VLC_VAR_DOINHERIT
 543                                    | VLC_VAR_ISCOMMAND );
 544     return __var_GetBool( p_obj, psz_name );
 545 }
 546
 547 /**
 548  * Create a time command variable with inherit and get its value.
 549  *
 550  * \param p_obj The object that holds the variable
 551  * \param psz_name The name of the variable
 552  */
 553 static inline int64_t __var_CreateGetTimeCommand( vlc_object_t *p_obj, const char *psz_name )
 554 {
 555     __var_Create( p_obj, psz_name, VLC_VAR_TIME | VLC_VAR_DOINHERIT
 556                                    | VLC_VAR_ISCOMMAND );
 557     return __var_GetTime( p_obj, psz_name );
 558 }
 559
 560 /**
 561  * Create a float command variable with inherit and get its value.
 562  *
 563  * \param p_obj The object that holds the variable
 564  * \param psz_name The name of the variable
 565  */
 566 static inline float __var_CreateGetFloatCommand( vlc_object_t *p_obj, const char *psz_name )
 567 {
 568     __var_Create( p_obj, psz_name, VLC_VAR_FLOAT | VLC_VAR_DOINHERIT
 569                                    | VLC_VAR_ISCOMMAND );
 570     return __var_GetFloat( p_obj, psz_name );
 571 }
 572
 573 /**
 574  * Create a string command variable with inherit and get its value.
 575  *
 576  * \param p_obj The object that holds the variable
 577  * \param psz_name The name of the variable
 578  */
 579 static inline char *__var_CreateGetStringCommand( vlc_object_t *p_obj,
 580                                            const char *psz_name )
 581 {
 582     __var_Create( p_obj, psz_name, VLC_VAR_STRING | VLC_VAR_DOINHERIT
 583                                    | VLC_VAR_ISCOMMAND );
 584     return __var_GetString( p_obj, psz_name );
 585 }
 586
 587 static inline char *__var_CreateGetNonEmptyStringCommand( vlc_object_t *p_obj,
 588                                                    const char *psz_name )
 589 {
 590     __var_Create( p_obj, psz_name, VLC_VAR_STRING | VLC_VAR_DOINHERIT
 591                                    | VLC_VAR_ISCOMMAND );
 592     return __var_GetNonEmptyString( p_obj, psz_name );
 593 }
 594
 595 /**
 596  * __var_CreateGetInteger() with automatic casting
 597  */
 598 #define var_CreateGetIntegerCommand(a,b)   __var_CreateGetIntegerCommand( VLC_OBJECT(a),b)
 599 /**
 600  * __var_CreateGetBoolCommand() with automatic casting
 601  */
 602 #define var_CreateGetBoolCommand(a,b)   __var_CreateGetBoolCommand( VLC_OBJECT(a),b)
 603 /**
 604  * __var_CreateGetTimeCommand() with automatic casting
 605  */
 606 #define var_CreateGetTimeCommand(a,b)   __var_CreateGetTimeCommand( VLC_OBJECT(a),b)
 607 /**
 608  * __var_CreateGetFloat() with automatic casting
 609  */
 610 #define var_CreateGetFloatCommand(a,b)   __var_CreateGetFloatCommand( VLC_OBJECT(a),b)
 611 /**
 612  * __var_CreateGetStringCommand() with automatic casting
 613  */
 614 #define var_CreateGetStringCommand(a,b)   __var_CreateGetStringCommand( VLC_OBJECT(a),b)
 615 #define var_CreateGetNonEmptyStringCommand(a,b)   __var_CreateGetNonEmptyStringCommand( VLC_OBJECT(a),b)
 616 /**
 617  * @}
 618  */
 619 #endif /*  _VLC_VARIABLES_H */