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