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