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