var_*Bool return a boolean.
[vlc.git] / 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_CLASS     0x00f0
49 #define VLC_VAR_FLAGS     0xff00
50
51 /** \defgroup var_flags Additive flags
52  * These flags are added to the type field of the variable. Most as a result of
53  * a __var_Change() call, but some may be added at creation time
54  * @{
55  */
56 #define VLC_VAR_HASCHOICE 0x0100
57 #define VLC_VAR_HASMIN    0x0200
58 #define VLC_VAR_HASMAX    0x0400
59 #define VLC_VAR_HASSTEP   0x0800
60
61 #define VLC_VAR_ISCOMMAND 0x2000
62
63 /** Creation flag */
64 #define VLC_VAR_DOINHERIT 0x8000
65 /**@}*/
66
67 /**
68  * \defgroup var_action Variable actions
69  * These are the different actions that can be used with __var_Change().
70  * The parameters given are the meaning of the two last parameters of
71  * __var_Change() when this action is being used.
72  * @{
73  */
74
75 /**
76  * Set the minimum value of this variable
77  * \param p_val The new minimum value
78  * \param p_val2 Unused
79  */
80 #define VLC_VAR_SETMIN              0x0010
81 /**
82  * Set the maximum value of this variable
83  * \param p_val The new maximum value
84  * \param p_val2 Unused
85  */
86 #define VLC_VAR_SETMAX              0x0011
87 #define VLC_VAR_SETSTEP             0x0012
88
89 /**
90  * Set the value of this variable without triggering any callbacks
91  * \param p_val The new value
92  * \param p_val2 Unused
93  */
94 #define VLC_VAR_SETVALUE            0x0013
95
96 #define VLC_VAR_SETTEXT             0x0014
97 #define VLC_VAR_GETTEXT             0x0015
98
99 #define VLC_VAR_GETMIN              0x0016
100 #define VLC_VAR_GETMAX              0x0017
101 #define VLC_VAR_GETSTEP             0x0018
102
103 #define VLC_VAR_ADDCHOICE           0x0020
104 #define VLC_VAR_DELCHOICE           0x0021
105 #define VLC_VAR_CLEARCHOICES        0x0022
106 #define VLC_VAR_SETDEFAULT          0x0023
107 #define VLC_VAR_GETCHOICES          0x0024
108 #define VLC_VAR_FREECHOICES         0x0025
109 #define VLC_VAR_GETLIST             0x0026
110 #define VLC_VAR_FREELIST            0x0027
111 #define VLC_VAR_CHOICESCOUNT        0x0028
112
113 #define VLC_VAR_INHERITVALUE        0x0030
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 * ) LIBVLC_USED );
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 VLC_EXPORT( int, var_SetChecked, ( vlc_object_t *, const char *, int, vlc_value_t ) );
130 VLC_EXPORT( int, var_GetChecked, ( vlc_object_t *, const char *, int, vlc_value_t * ) );
131
132 #define var_Command(a,b,c,d,e) __var_Command( VLC_OBJECT( a ), b, c, d, e )
133 VLC_EXPORT( int, __var_Command, ( vlc_object_t *, const char *, const char *, const char *, 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_SetChecked( p_obj, psz_name, VLC_VAR_INTEGER, 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_SetChecked( p_obj, psz_name, VLC_VAR_BOOL, 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_SetChecked( p_obj, psz_name, VLC_VAR_TIME, 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_SetChecked( p_obj, psz_name, VLC_VAR_FLOAT, 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_SetChecked( p_obj, psz_name, VLC_VAR_STRING, 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_SetChecked( p_obj, psz_name, VLC_VAR_VOID, 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 LIBVLC_USED
303 static inline int __var_GetInteger( vlc_object_t *p_obj, const char *psz_name )
304 {
305     vlc_value_t val;
306     if( !var_GetChecked( p_obj, psz_name, VLC_VAR_INTEGER, &val ) )
307         return val.i_int;
308     else
309         return 0;
310 }
311
312 /**
313  * Get a boolean value
314  *
315  * \param p_obj The object that holds the variable
316  * \param psz_name The name of the variable
317  */
318 LIBVLC_USED
319 static inline bool __var_GetBool( vlc_object_t *p_obj, const char *psz_name )
320 {
321     vlc_value_t val; val.b_bool = false;
322
323     if( !var_GetChecked( p_obj, psz_name, VLC_VAR_BOOL, &val ) )
324         return val.b_bool;
325     else
326         return false;
327 }
328
329 /**
330  * Get a time value
331  *
332  * \param p_obj The object that holds the variable
333  * \param psz_name The name of the variable
334  */
335 LIBVLC_USED
336 static inline int64_t __var_GetTime( vlc_object_t *p_obj, const char *psz_name )
337 {
338     vlc_value_t val; val.i_time = 0L;
339     if( !var_GetChecked( p_obj, psz_name, VLC_VAR_TIME, &val ) )
340         return val.i_time;
341     else
342         return 0;
343 }
344
345 /**
346  * Get a float value
347  *
348  * \param p_obj The object that holds the variable
349  * \param psz_name The name of the variable
350  */
351 LIBVLC_USED
352 static inline float __var_GetFloat( vlc_object_t *p_obj, const char *psz_name )
353 {
354     vlc_value_t val; val.f_float = 0.0;
355     if( !var_GetChecked( p_obj, psz_name, VLC_VAR_FLOAT, &val ) )
356         return val.f_float;
357     else
358         return 0.0;
359 }
360
361 /**
362  * Get a string value
363  *
364  * \param p_obj The object that holds the variable
365  * \param psz_name The name of the variable
366  */
367 LIBVLC_USED
368 static inline char *__var_GetString( vlc_object_t *p_obj, const char *psz_name )
369 {
370     vlc_value_t val; val.psz_string = NULL;
371     if( var_GetChecked( p_obj, psz_name, VLC_VAR_STRING, &val ) )
372         return NULL;
373     else
374         return val.psz_string;
375 }
376
377 LIBVLC_USED
378 static inline char *__var_GetNonEmptyString( vlc_object_t *p_obj, const char *psz_name )
379 {
380     vlc_value_t val;
381     if( var_GetChecked( p_obj, psz_name, VLC_VAR_STRING, &val ) )
382         return NULL;
383     if( *val.psz_string )
384         return val.psz_string;
385     free( val.psz_string );
386     return NULL;
387 }
388
389
390 /**
391  * __var_GetInteger() with automatic casting
392  */
393 #define var_GetInteger(a,b)   __var_GetInteger( VLC_OBJECT(a),b)
394 /**
395  * __var_GetBool() with automatic casting
396  */
397 #define var_GetBool(a,b)   __var_GetBool( VLC_OBJECT(a),b)
398 /**
399  * __var_GetTime() with automatic casting
400  */
401 #define var_GetTime(a,b)   __var_GetTime( VLC_OBJECT(a),b)
402 /**
403  * __var_GetFloat() with automatic casting
404  */
405 #define var_GetFloat(a,b)   __var_GetFloat( VLC_OBJECT(a),b)
406 /**
407  * __var_GetString() with automatic casting
408  */
409 #define var_GetString(a,b)   __var_GetString( VLC_OBJECT(a),b)
410 #define var_GetNonEmptyString(a,b)   __var_GetNonEmptyString( VLC_OBJECT(a),b)
411
412
413
414 /**
415  * Increment an integer variable
416  * \param p_obj the object that holds the variable
417  * \param psz_name the name of the variable
418  */
419 static inline void __var_IncInteger( vlc_object_t *p_obj, const char *psz_name )
420 {
421     int i_val = __var_GetInteger( p_obj, psz_name );
422     __var_SetInteger( p_obj, psz_name, ++i_val );
423 }
424 #define var_IncInteger(a,b) __var_IncInteger( VLC_OBJECT(a), b )
425
426 /**
427  * Decrement an integer variable
428  * \param p_obj the object that holds the variable
429  * \param psz_name the name of the variable
430  */
431 static inline void __var_DecInteger( vlc_object_t *p_obj, const char *psz_name )
432 {
433     int i_val = __var_GetInteger( p_obj, psz_name );
434     __var_SetInteger( p_obj, psz_name, --i_val );
435 }
436 #define var_DecInteger(a,b) __var_DecInteger( VLC_OBJECT(a), b )
437
438 /**
439  * Create a integer variable with inherit and get its value.
440  *
441  * \param p_obj The object that holds the variable
442  * \param psz_name The name of the variable
443  */
444 LIBVLC_USED
445 static inline int __var_CreateGetInteger( vlc_object_t *p_obj, const char *psz_name )
446 {
447     __var_Create( p_obj, psz_name, VLC_VAR_INTEGER | VLC_VAR_DOINHERIT );
448     return __var_GetInteger( p_obj, psz_name );
449 }
450
451 /**
452  * Create a boolean variable with inherit and get its value.
453  *
454  * \param p_obj The object that holds the variable
455  * \param psz_name The name of the variable
456  */
457 LIBVLC_USED
458 static inline bool __var_CreateGetBool( vlc_object_t *p_obj, const char *psz_name )
459 {
460     __var_Create( p_obj, psz_name, VLC_VAR_BOOL | VLC_VAR_DOINHERIT );
461     return __var_GetBool( p_obj, psz_name );
462 }
463
464 /**
465  * Create a time variable with inherit and get its value.
466  *
467  * \param p_obj The object that holds the variable
468  * \param psz_name The name of the variable
469  */
470 LIBVLC_USED
471 static inline int64_t __var_CreateGetTime( vlc_object_t *p_obj, const char *psz_name )
472 {
473     __var_Create( p_obj, psz_name, VLC_VAR_TIME | VLC_VAR_DOINHERIT );
474     return __var_GetTime( p_obj, psz_name );
475 }
476
477 /**
478  * Create a float variable with inherit and get its value.
479  *
480  * \param p_obj The object that holds the variable
481  * \param psz_name The name of the variable
482  */
483 LIBVLC_USED
484 static inline float __var_CreateGetFloat( vlc_object_t *p_obj, const char *psz_name )
485 {
486     __var_Create( p_obj, psz_name, VLC_VAR_FLOAT | VLC_VAR_DOINHERIT );
487     return __var_GetFloat( p_obj, psz_name );
488 }
489
490 /**
491  * Create a string variable with inherit and get its value.
492  *
493  * \param p_obj The object that holds the variable
494  * \param psz_name The name of the variable
495  */
496 LIBVLC_USED
497 static inline char *__var_CreateGetString( vlc_object_t *p_obj,
498                                            const char *psz_name )
499 {
500     __var_Create( p_obj, psz_name, VLC_VAR_STRING | VLC_VAR_DOINHERIT );
501     return __var_GetString( p_obj, psz_name );
502 }
503
504 LIBVLC_USED
505 static inline char *__var_CreateGetNonEmptyString( vlc_object_t *p_obj,
506                                                    const char *psz_name )
507 {
508     __var_Create( p_obj, psz_name, VLC_VAR_STRING | VLC_VAR_DOINHERIT );
509     return __var_GetNonEmptyString( p_obj, psz_name );
510 }
511
512 /**
513  * __var_CreateGetInteger() with automatic casting
514  */
515 #define var_CreateGetInteger(a,b)   __var_CreateGetInteger( VLC_OBJECT(a),b)
516 /**
517  * __var_CreateGetBool() with automatic casting
518  */
519 #define var_CreateGetBool(a,b)   __var_CreateGetBool( VLC_OBJECT(a),b)
520 /**
521  * __var_CreateGetTime() with automatic casting
522  */
523 #define var_CreateGetTime(a,b)   __var_CreateGetTime( VLC_OBJECT(a),b)
524 /**
525  * __var_CreateGetFloat() with automatic casting
526  */
527 #define var_CreateGetFloat(a,b)   __var_CreateGetFloat( VLC_OBJECT(a),b)
528 /**
529  * __var_CreateGetString() with automatic casting
530  */
531 #define var_CreateGetString(a,b)   __var_CreateGetString( VLC_OBJECT(a),b)
532 #define var_CreateGetNonEmptyString(a,b)   __var_CreateGetNonEmptyString( VLC_OBJECT(a),b)
533
534 /**
535  * Create a integer 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 LIBVLC_USED
541 static inline int __var_CreateGetIntegerCommand( vlc_object_t *p_obj, const char *psz_name )
542 {
543     __var_Create( p_obj, psz_name, VLC_VAR_INTEGER | VLC_VAR_DOINHERIT
544                                    | VLC_VAR_ISCOMMAND );
545     return __var_GetInteger( p_obj, psz_name );
546 }
547
548 /**
549  * Create a boolean command variable with inherit and get its value.
550  *
551  * \param p_obj The object that holds the variable
552  * \param psz_name The name of the variable
553  */
554 LIBVLC_USED
555 static inline bool __var_CreateGetBoolCommand( vlc_object_t *p_obj, const char *psz_name )
556 {
557     __var_Create( p_obj, psz_name, VLC_VAR_BOOL | VLC_VAR_DOINHERIT
558                                    | VLC_VAR_ISCOMMAND );
559     return __var_GetBool( p_obj, psz_name );
560 }
561
562 /**
563  * Create a time command variable with inherit and get its value.
564  *
565  * \param p_obj The object that holds the variable
566  * \param psz_name The name of the variable
567  */
568 LIBVLC_USED
569 static inline int64_t __var_CreateGetTimeCommand( vlc_object_t *p_obj, const char *psz_name )
570 {
571     __var_Create( p_obj, psz_name, VLC_VAR_TIME | VLC_VAR_DOINHERIT
572                                    | VLC_VAR_ISCOMMAND );
573     return __var_GetTime( p_obj, psz_name );
574 }
575
576 /**
577  * Create a float command 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 LIBVLC_USED
583 static inline float __var_CreateGetFloatCommand( vlc_object_t *p_obj, const char *psz_name )
584 {
585     __var_Create( p_obj, psz_name, VLC_VAR_FLOAT | VLC_VAR_DOINHERIT
586                                    | VLC_VAR_ISCOMMAND );
587     return __var_GetFloat( p_obj, psz_name );
588 }
589
590 /**
591  * Create a string 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 LIBVLC_USED
597 static inline char *__var_CreateGetStringCommand( vlc_object_t *p_obj,
598                                            const char *psz_name )
599 {
600     __var_Create( p_obj, psz_name, VLC_VAR_STRING | VLC_VAR_DOINHERIT
601                                    | VLC_VAR_ISCOMMAND );
602     return __var_GetString( p_obj, psz_name );
603 }
604
605 LIBVLC_USED
606 static inline char *__var_CreateGetNonEmptyStringCommand( vlc_object_t *p_obj,
607                                                    const char *psz_name )
608 {
609     __var_Create( p_obj, psz_name, VLC_VAR_STRING | VLC_VAR_DOINHERIT
610                                    | VLC_VAR_ISCOMMAND );
611     return __var_GetNonEmptyString( p_obj, psz_name );
612 }
613
614 /**
615  * __var_CreateGetInteger() with automatic casting
616  */
617 #define var_CreateGetIntegerCommand(a,b)   __var_CreateGetIntegerCommand( VLC_OBJECT(a),b)
618 /**
619  * __var_CreateGetBoolCommand() with automatic casting
620  */
621 #define var_CreateGetBoolCommand(a,b)   __var_CreateGetBoolCommand( VLC_OBJECT(a),b)
622 /**
623  * __var_CreateGetTimeCommand() with automatic casting
624  */
625 #define var_CreateGetTimeCommand(a,b)   __var_CreateGetTimeCommand( VLC_OBJECT(a),b)
626 /**
627  * __var_CreateGetFloat() with automatic casting
628  */
629 #define var_CreateGetFloatCommand(a,b)   __var_CreateGetFloatCommand( VLC_OBJECT(a),b)
630 /**
631  * __var_CreateGetStringCommand() with automatic casting
632  */
633 #define var_CreateGetStringCommand(a,b)   __var_CreateGetStringCommand( VLC_OBJECT(a),b)
634 #define var_CreateGetNonEmptyStringCommand(a,b)   __var_CreateGetNonEmptyStringCommand( VLC_OBJECT(a),b)
635 /**
636  * @}
637  */
638 #endif /*  _VLC_VARIABLES_H */