vlc_variables.h 26.3 KB
Newer Older
1
/*****************************************************************************
Pere Orga's avatar
Pere Orga committed
2
 * vlc_variables.h: variables handling
3
 *****************************************************************************
Jean-Baptiste Kempf's avatar
Jean-Baptiste Kempf committed
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
 *
Jean-Baptiste Kempf's avatar
Jean-Baptiste Kempf committed
10 11 12
 * This program is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 of the License, or
13
 * (at your option) any later version.
14
 *
15 16
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
Jean-Baptiste Kempf's avatar
Jean-Baptiste Kempf committed
17 18
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
19
 *
Jean-Baptiste Kempf's avatar
Jean-Baptiste Kempf committed
20 21 22
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
23 24
 *****************************************************************************/

25 26
#ifndef VLC_VARIABLES_H
#define VLC_VARIABLES_H 1
27

Sigmund Augdal Helberg's avatar
Sigmund Augdal Helberg committed
28 29
/**
 * \defgroup variables Variables
30
 * \ingroup vlc_object
Sigmund Augdal Helberg's avatar
Sigmund Augdal Helberg committed
31
 *
32
 * VLC object variables and callbacks
Sigmund Augdal Helberg's avatar
Sigmund Augdal Helberg committed
33 34
 *
 * @{
35 36
 * \file
 * VLC object variables and callbacks interface
Sigmund Augdal Helberg's avatar
Sigmund Augdal Helberg committed
37 38
 */

39
#define VLC_VAR_TYPE      0x00ff
40
#define VLC_VAR_CLASS     0x00f0
41 42
#define VLC_VAR_FLAGS     0xff00

43 44 45 46 47 48 49 50 51 52 53 54 55 56
/**
 * \defgroup var_type Variable types
 * These are the different types a vlc variable can have.
 * @{
 */
#define VLC_VAR_VOID      0x0010
#define VLC_VAR_BOOL      0x0020
#define VLC_VAR_INTEGER   0x0030
#define VLC_VAR_STRING    0x0040
#define VLC_VAR_FLOAT     0x0050
#define VLC_VAR_ADDRESS   0x0070
#define VLC_VAR_COORDS    0x00A0
/**@}*/

Sigmund Augdal Helberg's avatar
Sigmund Augdal Helberg committed
57 58
/** \defgroup var_flags Additive flags
 * 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
Sigmund Augdal Helberg's avatar
Sigmund Augdal Helberg committed
60 61
 * @{
 */
62
#define VLC_VAR_HASCHOICE 0x0100
63

64
#define VLC_VAR_ISCOMMAND 0x2000
65

Sigmund Augdal Helberg's avatar
Sigmund Augdal Helberg committed
66
/** Creation flag */
basos G's avatar
basos G committed
67 68
/* If the variable is not found on the current module
   search all parents and finally module config until found */
69
#define VLC_VAR_DOINHERIT 0x8000
Sigmund Augdal Helberg's avatar
Sigmund Augdal Helberg committed
70
/**@}*/
71

Sigmund Augdal Helberg's avatar
Sigmund Augdal Helberg committed
72 73
/**
 * \defgroup var_action Variable actions
74
 * These are the different actions that can be used with var_Change().
Sigmund Augdal Helberg's avatar
Sigmund Augdal Helberg committed
75
 * The parameters given are the meaning of the two last parameters of
76
 * var_Change() when this action is being used.
Sigmund Augdal Helberg's avatar
Sigmund Augdal Helberg committed
77 78 79
 * @{
 */

Derk-Jan Hartman's avatar
Derk-Jan Hartman committed
80
#define VLC_VAR_SETSTEP             0x0012
81

Sigmund Augdal Helberg's avatar
Sigmund Augdal Helberg committed
82 83 84 85 86
/**
 * Set the value of this variable without triggering any callbacks
 * \param p_val The new value
 * \param p_val2 Unused
 */
Derk-Jan Hartman's avatar
Derk-Jan Hartman committed
87 88 89 90 91
#define VLC_VAR_SETVALUE            0x0013

#define VLC_VAR_SETTEXT             0x0014
#define VLC_VAR_GETTEXT             0x0015

92 93 94 95
#define VLC_VAR_GETMIN              0x0016
#define VLC_VAR_GETMAX              0x0017
#define VLC_VAR_GETSTEP             0x0018

Derk-Jan Hartman's avatar
Derk-Jan Hartman committed
96 97 98 99
#define VLC_VAR_ADDCHOICE           0x0020
#define VLC_VAR_DELCHOICE           0x0021
#define VLC_VAR_CLEARCHOICES        0x0022
#define VLC_VAR_GETCHOICES          0x0024
100

Rémi Duraffort's avatar
Rémi Duraffort committed
101
#define VLC_VAR_CHOICESCOUNT        0x0026
102
#define VLC_VAR_SETMINMAX           0x0027
Derk-Jan Hartman's avatar
Derk-Jan Hartman committed
103

Sigmund Augdal Helberg's avatar
Sigmund Augdal Helberg committed
104
/**@}*/
105

106 107 108 109
/**
 * Variable actions.
 *
 * These are the different actions that can be used with var_GetAndSet().
110
 */
111
enum vlc_var_atomic_op {
112 113 114 115 116
    VLC_VAR_BOOL_TOGGLE, /**< Invert a boolean value (param ignored) */
    VLC_VAR_INTEGER_ADD, /**< Add parameter to an integer value */
    VLC_VAR_INTEGER_OR,  /**< Binary OR over an integer bits field */
    VLC_VAR_INTEGER_NAND,/**< Binary NAND over an integer bits field */
};
117

118 119 120 121 122 123 124 125 126 127 128 129 130
/**
 * Creates a VLC object variable.
 *
 * This function creates a named variable within a VLC object.
 * If a variable already exists with the same name within the same object, its
 * reference count is incremented instead.
 *
 * \param obj Object to hold the variable
 * \param name Variable name
 * \param type Variable type. Must be one of \ref var_type combined with
 *               zero or more \ref var_flags
 */
VLC_API int var_Create(vlc_object_t *obj, const char *name, int type);
131

132 133 134 135 136 137 138 139 140 141
/**
 * Destroys a VLC object variable.
 *
 * This function decrements the reference count of a named variable within a
 * VLC object. If the reference count reaches zero, the variable is destroyed.
 *
 * \param obj Object holding the variable
 * \param name Variable name
 */
VLC_API void var_Destroy(vlc_object_t *obj, const char *name);
142

143 144 145 146 147 148 149
/**
 * Performs a special action on a variable.
 *
 * \param obj Object holding the variable
 * \param name Variable name
 * \param action Action to perform. Must be one of \ref var_action
 */
150
VLC_API int var_Change(vlc_object_t *obj, const char *name, int action, ...);
151

152 153 154 155 156 157 158 159 160
/**
 * Get the type of a variable.
 *
 * \see var_type
 *
 * \return The variable type if it exists
 *         or 0 if the variable could not be found.
 */
VLC_API int var_Type(vlc_object_t *obj, const char *name) VLC_USED;
161

162 163 164 165 166 167 168 169
/**
 * Sets a variable value.
 *
 * \param obj Object holding the variable
 * \param name Variable name
 * \param val Variable value to set
 */
VLC_API int var_Set(vlc_object_t *obj, const char *name, vlc_value_t val);
170

171 172 173 174 175 176 177 178
/**
 * Gets a variable value.
 *
 * \param obj Object holding the variable
 * \param name Variable name
 * \param valp Pointer to a \ref vlc_value_t object to hold the value [OUT]
 */
VLC_API int var_Get(vlc_object_t *obj, const char *name, vlc_value_t *valp);
179

180 181
VLC_API int var_SetChecked( vlc_object_t *, const char *, int, vlc_value_t );
VLC_API int var_GetChecked( vlc_object_t *, const char *, int, vlc_value_t * );
182

183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207
/**
 * Perform an atomic read-modify-write of a variable.
 *
 * \param obj object holding the variable
 * \param name variable name
 * \param op read-modify-write operation to perform
 *           (see \ref vlc_var_atomic_op)
 * \param value value of the variable after the modification
 * \retval VLC_SUCCESS Operation successful
 * \retval VLC_ENOVAR Variable not found
 *
 * \bug The modified value is returned rather than the original value.
 * As such, the original value cannot be known in the case of non-reversible
 * operation such as \ref VLC_VAR_INTEGER_OR and \ref VLC_VAR_INTEGER_NAND.
 */
VLC_API int var_GetAndSet(vlc_object_t *obj, const char *name, int op,
                          vlc_value_t *value);

/**
 * Finds the value of a variable.
 *
 * If the specified object does not hold a variable with the specified name,
 * try the parent object, and iterate until the top of the objects tree. If no
 * match is found, the value is read from the configuration.
 */
208
VLC_API int var_Inherit( vlc_object_t *, const char *, int, vlc_value_t * );
209

210 211 212 213 214
/**
 * Frees a list and the associated strings.
 * @param p_val: the list variable
 * @param p_val2: the variable associated or NULL
 */
215
VLC_API void var_FreeList( vlc_list_t *, char *** );
216

217

218 219 220 221 222 223 224 225 226
/*****************************************************************************
 * Variable callbacks
 *****************************************************************************
 * int MyCallback( vlc_object_t *p_this,
 *                 char const *psz_variable,
 *                 vlc_value_t oldvalue,
 *                 vlc_value_t newvalue,
 *                 void *p_data);
 *****************************************************************************/
227

228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270
/**
 * Registers a callback for a variable.
 *
 * We store a function pointer that will be called upon variable
 * modification.
 *
 * \param obj Object holding the variable
 * \param name Variable name
 * \param callback Callback function pointer
 * \param opaque Opaque data pointer for use by the callback.
 *
 * \warning The callback function is run in the thread that calls var_Set() on
 *          the variable. Use proper locking. This thread may not have much
 *          time to spare, so keep callback functions short.
 *
 * \bug It is not possible to atomically retrieve the current value and
 * register a callback. As a consequence, extreme care must be taken to ensure
 * that the variable value cannot change before the callback is registered.
 * Failure to do so will result in intractable race conditions.
 */
VLC_API void var_AddCallback(vlc_object_t *obj, const char *name,
                             vlc_callback_t callback, void *opaque);

/**
 * Deregisters a callback from a variable.
 *
 * The callback and opaque pointer must be supplied again, as the same callback
 * function might have been registered more than once.
 */
VLC_API void var_DelCallback(vlc_object_t *obj, const char *name,
                             vlc_callback_t callback, void *opaque);

/**
 * Triggers callbacks on a variable.
 *
 * This triggers any callbacks registered on the named variable without
 * actually modifying the variable value. This is primarily useful for
 * variables with \ref VLC_VAR_VOID type (which do not have a value).
 *
 * \param obj Object holding the variable
 * \param name Variable name
 */
VLC_API void var_TriggerCallback(vlc_object_t *obj, const char *name);
271

272 273 274 275 276 277 278 279 280
/**
 * Register a callback for a list variable
 *
 * The callback is triggered when an element is added/removed from the
 * list or when the list is cleared.
 *
 * See var_AddCallback().
 */
VLC_API void var_AddListCallback( vlc_object_t *, const char *, vlc_list_callback_t, void * );
281

282 283 284 285 286 287
/**
 * Remove a callback from a list variable
 *
 * See var_DelCallback().
 */
VLC_API void var_DelListCallback( vlc_object_t *, const char *, vlc_list_callback_t, void * );
288

289 290 291
/*****************************************************************************
 * helpers functions
 *****************************************************************************/
Sigmund Augdal Helberg's avatar
Sigmund Augdal Helberg committed
292 293 294 295 296 297 298 299

/**
 * Set the value of an integer variable
 *
 * \param p_obj The object that holds the variable
 * \param psz_name The name of the variable
 * \param i The new integer value of this variable
 */
300 301
static inline int var_SetInteger( vlc_object_t *p_obj, const char *psz_name,
                                  int64_t i )
302 303 304
{
    vlc_value_t val;
    val.i_int = i;
305
    return var_SetChecked( p_obj, psz_name, VLC_VAR_INTEGER, val );
306
}
Rémi Duraffort's avatar
Rémi Duraffort committed
307

308 309 310 311 312
/**
 * Set the value of an boolean variable
 *
 * \param p_obj The object that holds the variable
 * \param psz_name The name of the variable
313
 * \param b The new boolean value of this variable
314
 */
315
static inline int var_SetBool( vlc_object_t *p_obj, const char *psz_name, bool b )
316 317 318
{
    vlc_value_t val;
    val.b_bool = b;
319
    return var_SetChecked( p_obj, psz_name, VLC_VAR_BOOL, val );
320 321
}

322 323 324 325 326 327 328 329 330
static inline int var_SetCoords( vlc_object_t *obj, const char *name,
                                 int32_t x, int32_t y )
{
    vlc_value_t val;
    val.coords.x = x;
    val.coords.y = y;
    return var_SetChecked (obj, name, VLC_VAR_COORDS, val);
}

Sigmund Augdal Helberg's avatar
Sigmund Augdal Helberg committed
331 332 333 334 335 336 337
/**
 * Set the value of a float variable
 *
 * \param p_obj The object that holds the variable
 * \param psz_name The name of the variable
 * \param f The new float value of this variable
 */
338
static inline int var_SetFloat( vlc_object_t *p_obj, const char *psz_name, float f )
339 340 341
{
    vlc_value_t val;
    val.f_float = f;
342
    return var_SetChecked( p_obj, psz_name, VLC_VAR_FLOAT, val );
343
}
Sigmund Augdal Helberg's avatar
Sigmund Augdal Helberg committed
344

345 346 347 348 349 350 351
/**
 * Set the value of a string variable
 *
 * \param p_obj The object that holds the variable
 * \param psz_name The name of the variable
 * \param psz_string The new string value of this variable
 */
352
static inline int var_SetString( vlc_object_t *p_obj, const char *psz_name, const char *psz_string )
353 354
{
    vlc_value_t val;
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
355
    val.psz_string = (char *)psz_string;
356
    return var_SetChecked( p_obj, psz_name, VLC_VAR_STRING, val );
357 358
}

359 360 361 362 363 364 365 366
/**
 * Set the value of a pointer variable
 *
 * \param p_obj The object that holds the variable
 * \param psz_name The name of the variable
 * \param ptr The new pointer value of this variable
 */
static inline
367
int var_SetAddress( vlc_object_t *p_obj, const char *psz_name, void *ptr )
368 369 370 371 372 373
{
    vlc_value_t val;
    val.p_address = ptr;
    return var_SetChecked( p_obj, psz_name, VLC_VAR_ADDRESS, val );
}

374
/**
375 376
 * Get an integer value
*
377 378 379
 * \param p_obj The object that holds the variable
 * \param psz_name The name of the variable
 */
380
VLC_USED
381
static inline int64_t var_GetInteger( vlc_object_t *p_obj, const char *psz_name )
382
{
383 384
    vlc_value_t val;
    if( !var_GetChecked( p_obj, psz_name, VLC_VAR_INTEGER, &val ) )
385 386 387 388 389
        return val.i_int;
    else
        return 0;
}

390 391 392 393 394 395
/**
 * Get a boolean value
 *
 * \param p_obj The object that holds the variable
 * \param psz_name The name of the variable
 */
396
VLC_USED
397
static inline bool var_GetBool( vlc_object_t *p_obj, const char *psz_name )
398
{
399
    vlc_value_t val; val.b_bool = false;
400

401
    if( !var_GetChecked( p_obj, psz_name, VLC_VAR_BOOL, &val ) )
402 403
        return val.b_bool;
    else
404
        return false;
405 406
}

407 408 409 410 411 412 413 414 415 416 417 418 419 420
static inline void var_GetCoords( vlc_object_t *obj, const char *name,
                                  int32_t *px, int32_t *py )
{
    vlc_value_t val;

    if (likely(!var_GetChecked (obj, name, VLC_VAR_COORDS, &val)))
    {
        *px = val.coords.x;
        *py = val.coords.y;
    }
    else
        *px = *py = 0;
}

421 422 423 424 425 426
/**
 * Get a float value
 *
 * \param p_obj The object that holds the variable
 * \param psz_name The name of the variable
 */
427
VLC_USED
428
static inline float var_GetFloat( vlc_object_t *p_obj, const char *psz_name )
429
{
Clément Stenac's avatar
Clément Stenac committed
430
    vlc_value_t val; val.f_float = 0.0;
431
    if( !var_GetChecked( p_obj, psz_name, VLC_VAR_FLOAT, &val ) )
432 433 434 435 436 437 438 439 440 441 442
        return val.f_float;
    else
        return 0.0;
}

/**
 * Get a string value
 *
 * \param p_obj The object that holds the variable
 * \param psz_name The name of the variable
 */
443
VLC_USED VLC_MALLOC
444
static inline char *var_GetString( vlc_object_t *p_obj, const char *psz_name )
445
{
Clément Stenac's avatar
Clément Stenac committed
446
    vlc_value_t val; val.psz_string = NULL;
447
    if( var_GetChecked( p_obj, psz_name, VLC_VAR_STRING, &val ) )
448
        return NULL;
449
    else
450
        return val.psz_string;
451 452
}

453
VLC_USED VLC_MALLOC
454
static inline char *var_GetNonEmptyString( vlc_object_t *p_obj, const char *psz_name )
455 456
{
    vlc_value_t val;
457
    if( var_GetChecked( p_obj, psz_name, VLC_VAR_STRING, &val ) )
458
        return NULL;
459
    if( val.psz_string && *val.psz_string )
460
        return val.psz_string;
461
    free( val.psz_string );
462 463 464
    return NULL;
}

465
VLC_USED
466
static inline void *var_GetAddress( vlc_object_t *p_obj, const char *psz_name )
467 468 469 470 471 472 473
{
    vlc_value_t val;
    if( var_GetChecked( p_obj, psz_name, VLC_VAR_ADDRESS, &val ) )
        return NULL;
    else
        return val.p_address;
}
474

475 476 477 478 479
/**
 * Increment an integer variable
 * \param p_obj the object that holds the variable
 * \param psz_name the name of the variable
 */
480
static inline int64_t var_IncInteger( vlc_object_t *p_obj, const char *psz_name )
481
{
482 483
    vlc_value_t val;
    val.i_int = 1;
484 485
    if( var_GetAndSet( p_obj, psz_name, VLC_VAR_INTEGER_ADD, &val ) )
        return 0;
486
    return val.i_int;
487 488 489 490 491 492 493
}

/**
 * Decrement an integer variable
 * \param p_obj the object that holds the variable
 * \param psz_name the name of the variable
 */
494
static inline int64_t var_DecInteger( vlc_object_t *p_obj, const char *psz_name )
495
{
496 497
    vlc_value_t val;
    val.i_int = -1;
498 499
    if( var_GetAndSet( p_obj, psz_name, VLC_VAR_INTEGER_ADD, &val ) )
        return 0;
500
    return val.i_int;
501 502
}

503
static inline uint64_t var_OrInteger( vlc_object_t *obj, const char *name,
504 505 506 507
                                      unsigned v )
{
    vlc_value_t val;
    val.i_int = v;
508 509
    if( var_GetAndSet( obj, name, VLC_VAR_INTEGER_OR, &val ) )
        return 0;
510 511 512
    return val.i_int;
}

513
static inline uint64_t var_NAndInteger( vlc_object_t *obj, const char *name,
514 515 516 517
                                        unsigned v )
{
    vlc_value_t val;
    val.i_int = v;
518 519
    if( var_GetAndSet( obj, name, VLC_VAR_INTEGER_NAND, &val ) )
        return 0;
520 521 522
    return val.i_int;
}

523 524 525 526 527 528
/**
 * Create a integer variable with inherit and get its value.
 *
 * \param p_obj The object that holds the variable
 * \param psz_name The name of the variable
 */
529
VLC_USED
530
static inline int64_t var_CreateGetInteger( vlc_object_t *p_obj, const char *psz_name )
531
{
532 533
    var_Create( p_obj, psz_name, VLC_VAR_INTEGER | VLC_VAR_DOINHERIT );
    return var_GetInteger( p_obj, psz_name );
534 535
}

536 537 538 539 540 541
/**
 * Create a boolean variable with inherit and get its value.
 *
 * \param p_obj The object that holds the variable
 * \param psz_name The name of the variable
 */
542
VLC_USED
543
static inline bool var_CreateGetBool( vlc_object_t *p_obj, const char *psz_name )
544
{
545 546
    var_Create( p_obj, psz_name, VLC_VAR_BOOL | VLC_VAR_DOINHERIT );
    return var_GetBool( p_obj, psz_name );
547 548
}

549 550 551 552 553 554
/**
 * Create a float variable with inherit and get its value.
 *
 * \param p_obj The object that holds the variable
 * \param psz_name The name of the variable
 */
555
VLC_USED
556
static inline float var_CreateGetFloat( vlc_object_t *p_obj, const char *psz_name )
557
{
558 559
    var_Create( p_obj, psz_name, VLC_VAR_FLOAT | VLC_VAR_DOINHERIT );
    return var_GetFloat( p_obj, psz_name );
560 561 562 563 564 565 566 567
}

/**
 * Create a string variable with inherit and get its value.
 *
 * \param p_obj The object that holds the variable
 * \param psz_name The name of the variable
 */
568
VLC_USED VLC_MALLOC
569
static inline char *var_CreateGetString( vlc_object_t *p_obj,
570
                                           const char *psz_name )
571
{
572 573
    var_Create( p_obj, psz_name, VLC_VAR_STRING | VLC_VAR_DOINHERIT );
    return var_GetString( p_obj, psz_name );
574
}
575

576
VLC_USED VLC_MALLOC
577
static inline char *var_CreateGetNonEmptyString( vlc_object_t *p_obj,
578 579
                                                   const char *psz_name )
{
580 581
    var_Create( p_obj, psz_name, VLC_VAR_STRING | VLC_VAR_DOINHERIT );
    return var_GetNonEmptyString( p_obj, psz_name );
582 583
}

584 585 586 587 588 589
/**
 * Create an address variable with inherit and get its value.
 *
 * \param p_obj The object that holds the variable
 * \param psz_name The name of the variable
 */
590
VLC_USED
591
static inline void *var_CreateGetAddress( vlc_object_t *p_obj,
592 593
                                           const char *psz_name )
{
594 595
    var_Create( p_obj, psz_name, VLC_VAR_ADDRESS | VLC_VAR_DOINHERIT );
    return var_GetAddress( p_obj, psz_name );
596 597
}

598 599 600 601 602 603
/**
 * Create a integer command variable with inherit and get its value.
 *
 * \param p_obj The object that holds the variable
 * \param psz_name The name of the variable
 */
604
VLC_USED
605
static inline int64_t var_CreateGetIntegerCommand( vlc_object_t *p_obj, const char *psz_name )
606
{
607
    var_Create( p_obj, psz_name, VLC_VAR_INTEGER | VLC_VAR_DOINHERIT
608
                                   | VLC_VAR_ISCOMMAND );
609
    return var_GetInteger( p_obj, psz_name );
610 611 612 613 614 615 616 617
}

/**
 * Create a boolean command variable with inherit and get its value.
 *
 * \param p_obj The object that holds the variable
 * \param psz_name The name of the variable
 */
618
VLC_USED
619
static inline bool var_CreateGetBoolCommand( vlc_object_t *p_obj, const char *psz_name )
620
{
621
    var_Create( p_obj, psz_name, VLC_VAR_BOOL | VLC_VAR_DOINHERIT
622
                                   | VLC_VAR_ISCOMMAND );
623
    return var_GetBool( p_obj, psz_name );
624 625 626 627 628 629 630 631
}

/**
 * Create a float command variable with inherit and get its value.
 *
 * \param p_obj The object that holds the variable
 * \param psz_name The name of the variable
 */
632
VLC_USED
633
static inline float var_CreateGetFloatCommand( vlc_object_t *p_obj, const char *psz_name )
634
{
635
    var_Create( p_obj, psz_name, VLC_VAR_FLOAT | VLC_VAR_DOINHERIT
636
                                   | VLC_VAR_ISCOMMAND );
637
    return var_GetFloat( p_obj, psz_name );
638 639 640 641 642 643 644 645
}

/**
 * Create a string command variable with inherit and get its value.
 *
 * \param p_obj The object that holds the variable
 * \param psz_name The name of the variable
 */
646
VLC_USED VLC_MALLOC
647
static inline char *var_CreateGetStringCommand( vlc_object_t *p_obj,
648 649
                                           const char *psz_name )
{
650
    var_Create( p_obj, psz_name, VLC_VAR_STRING | VLC_VAR_DOINHERIT
651
                                   | VLC_VAR_ISCOMMAND );
652
    return var_GetString( p_obj, psz_name );
653 654
}

655
VLC_USED VLC_MALLOC
656
static inline char *var_CreateGetNonEmptyStringCommand( vlc_object_t *p_obj,
657 658
                                                   const char *psz_name )
{
659
    var_Create( p_obj, psz_name, VLC_VAR_STRING | VLC_VAR_DOINHERIT
660
                                   | VLC_VAR_ISCOMMAND );
661
    return var_GetNonEmptyString( p_obj, psz_name );
662 663
}

664
VLC_USED
665
static inline int var_CountChoices( vlc_object_t *p_obj, const char *psz_name )
666
{
667
    size_t count;
668
    if( var_Change( p_obj, psz_name, VLC_VAR_CHOICESCOUNT, &count ) )
669
        return 0;
670
    return count;
671
}
672

673
static inline bool var_ToggleBool( vlc_object_t *p_obj, const char *psz_name )
674 675
{
    vlc_value_t val;
676 677
    if( var_GetAndSet( p_obj, psz_name, VLC_VAR_BOOL_TOGGLE, &val ) )
        return false;
678
    return val.b_bool;
679
}
Laurent Aimar's avatar
Laurent Aimar committed
680

681
VLC_USED
Laurent Aimar's avatar
Laurent Aimar committed
682 683 684 685 686 687 688 689 690
static inline bool var_InheritBool( vlc_object_t *obj, const char *name )
{
    vlc_value_t val;

    if( var_Inherit( obj, name, VLC_VAR_BOOL, &val ) )
        val.b_bool = false;
    return val.b_bool;
}

691
VLC_USED
692
static inline int64_t var_InheritInteger( vlc_object_t *obj, const char *name )
693 694 695 696 697 698 699 700
{
    vlc_value_t val;

    if( var_Inherit( obj, name, VLC_VAR_INTEGER, &val ) )
        val.i_int = 0;
    return val.i_int;
}

701
VLC_USED
702 703 704 705 706 707 708 709 710
static inline float var_InheritFloat( vlc_object_t *obj, const char *name )
{
    vlc_value_t val;

    if( var_Inherit( obj, name, VLC_VAR_FLOAT, &val ) )
        val.f_float = 0.;
    return val.f_float;
}

711
VLC_USED VLC_MALLOC
712 713 714 715 716 717 718 719 720 721 722 723 724 725
static inline char *var_InheritString( vlc_object_t *obj, const char *name )
{
    vlc_value_t val;

    if( var_Inherit( obj, name, VLC_VAR_STRING, &val ) )
        val.psz_string = NULL;
    else if( val.psz_string && !*val.psz_string )
    {
        free( val.psz_string );
        val.psz_string = NULL;
    }
    return val.psz_string;
}

726
VLC_USED
727 728 729 730 731 732 733 734 735
static inline void *var_InheritAddress( vlc_object_t *obj, const char *name )
{
    vlc_value_t val;

    if( var_Inherit( obj, name, VLC_VAR_ADDRESS, &val ) )
        val.p_address = NULL;
    return val.p_address;
}

736

737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755
/**
 * Inherit a string as a fractional value.
 *
 * This function inherits a string, and interprets it as an unsigned rational
 * number, i.e. a fraction. It also accepts a normally formatted floating point
 * number.
 *
 * \warning The caller shall perform any and all necessary boundary checks.
 *
 * \note The rational number is always reduced,
 * i.e. the returned numerator and denominator are always co-prime numbers.
 *
 * \note Fraction with zero as denominator are considered valid,
 * including the undefined form zero-by-zero.
 *
 * \return Zero on success, an error if parsing fails.
  */
VLC_API int var_InheritURational(vlc_object_t *obj, unsigned *num,
                                 unsigned *den, const char *name);
756

757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774
/**
 * Parses a string with multiple options.
 *
 * Parses a set of colon-separated or semicolon-separated
 * <code>name=value</code> pairs.
 * Some access (or access_demux) plugins uses this scheme
 * in media resource location.
 * @note Only trusted/safe variables are allowed. This is intended.
 *
 * @warning Only use this for plugins implementing VLC-specific resource
 * location schemes. This would not make any sense for standardized ones.
 *
 * @param obj VLC object on which to set variables (and emit error messages)
 * @param mrl string to parse
 * @param pref prefix to prepend to option names in the string
 *
 * @return VLC_ENOMEM on error, VLC_SUCCESS on success.
 */
775
VLC_API int var_LocationParse(vlc_object_t *, const char *mrl, const char *prefix);
776 777 778 779

#ifndef DOC
#define var_Create(a,b,c) var_Create(VLC_OBJECT(a), b, c)
#define var_Destroy(a,b) var_Destroy(VLC_OBJECT(a), b)
780
#define var_Change(a,b,...) var_Change(VLC_OBJECT(a), b, __VA_ARGS__)
781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839
#define var_Type(a,b) var_Type(VLC_OBJECT(a), b)
#define var_Set(a,b,c) var_Set(VLC_OBJECT(a), b, c)
#define var_Get(a,b,c) var_Get(VLC_OBJECT(a), b, c)
#define var_SetChecked(o,n,t,v) var_SetChecked(VLC_OBJECT(o), n, t, v)
#define var_GetChecked(o,n,t,v) var_GetChecked(VLC_OBJECT(o), n, t, v)

#define var_AddCallback(a,b,c,d) var_AddCallback(VLC_OBJECT(a), b, c, d)
#define var_DelCallback(a,b,c,d) var_DelCallback(VLC_OBJECT(a), b, c, d)
#define var_TriggerCallback(a,b) var_TriggerCallback(VLC_OBJECT(a), b)
#define var_AddListCallback(a,b,c,d) \
        var_AddListCallback(VLC_OBJECT(a), b, c, d)
#define var_DelListCallback(a,b,c,d) \
        var_DelListCallback(VLC_OBJECT(a), b, c, d)

#define var_SetInteger(a,b,c) var_SetInteger(VLC_OBJECT(a), b, c)
#define var_SetBool(a,b,c) var_SetBool(VLC_OBJECT(a), b, c)
#define var_SetCoords(o,n,x,y) var_SetCoords(VLC_OBJECT(o), n, x, y)
#define var_SetFloat(a,b,c) var_SetFloat(VLC_OBJECT(a), b, c)
#define var_SetString(a,b,c) var_SetString(VLC_OBJECT(a), b, c)
#define var_SetAddress(o, n, p) var_SetAddress(VLC_OBJECT(o), n, p)

#define var_GetCoords(o,n,x,y) var_GetCoords(VLC_OBJECT(o), n, x, y)

#define var_IncInteger(a,b) var_IncInteger(VLC_OBJECT(a), b)
#define var_DecInteger(a,b) var_DecInteger(VLC_OBJECT(a), b)
#define var_OrInteger(a,b,c) var_OrInteger(VLC_OBJECT(a), b, c)
#define var_NAndInteger(a,b,c) var_NAndInteger(VLC_OBJECT(a), b, c)

#define var_CreateGetInteger(a,b) var_CreateGetInteger(VLC_OBJECT(a), b)
#define var_CreateGetBool(a,b) var_CreateGetBool(VLC_OBJECT(a), b)
#define var_CreateGetFloat(a,b) var_CreateGetFloat(VLC_OBJECT(a), b)
#define var_CreateGetString(a,b) var_CreateGetString(VLC_OBJECT(a), b)
#define var_CreateGetNonEmptyString(a,b) \
        var_CreateGetNonEmptyString(VLC_OBJECT(a), b)
#define var_CreateGetAddress(a,b) var_CreateGetAddress( VLC_OBJECT(a), b)

#define var_CreateGetIntegerCommand(a,b)   var_CreateGetIntegerCommand( VLC_OBJECT(a),b)
#define var_CreateGetBoolCommand(a,b)   var_CreateGetBoolCommand( VLC_OBJECT(a),b)
#define var_CreateGetFloatCommand(a,b)   var_CreateGetFloatCommand( VLC_OBJECT(a),b)
#define var_CreateGetStringCommand(a,b)   var_CreateGetStringCommand( VLC_OBJECT(a),b)
#define var_CreateGetNonEmptyStringCommand(a,b)   var_CreateGetNonEmptyStringCommand( VLC_OBJECT(a),b)

#define var_CountChoices(a,b) var_CountChoices(VLC_OBJECT(a),b)
#define var_ToggleBool(a,b) var_ToggleBool(VLC_OBJECT(a),b )

#define var_InheritBool(o, n) var_InheritBool(VLC_OBJECT(o), n)
#define var_InheritInteger(o, n) var_InheritInteger(VLC_OBJECT(o), n)
#define var_InheritFloat(o, n) var_InheritFloat(VLC_OBJECT(o), n)
#define var_InheritString(o, n) var_InheritString(VLC_OBJECT(o), n)
#define var_InheritAddress(o, n) var_InheritAddress(VLC_OBJECT(o), n)
#define var_InheritURational(a,b,c,d) var_InheritURational(VLC_OBJECT(a), b, c, d)

#define var_GetInteger(a,b) var_GetInteger(VLC_OBJECT(a),b)
#define var_GetBool(a,b) var_GetBool(VLC_OBJECT(a),b)
#define var_GetFloat(a,b) var_GetFloat(VLC_OBJECT(a),b)
#define var_GetString(a,b) var_GetString(VLC_OBJECT(a),b)
#define var_GetNonEmptyString(a,b) var_GetNonEmptyString( VLC_OBJECT(a),b)
#define var_GetAddress(a,b) var_GetAddress(VLC_OBJECT(a),b)

840
#define var_LocationParse(o, m, p) var_LocationParse(VLC_OBJECT(o), m, p)
841
#endif
842

Sigmund Augdal Helberg's avatar
Sigmund Augdal Helberg committed
843 844 845
/**
 * @}
 */
846
#endif /*  _VLC_VARIABLES_H */