VLC  4.0.0-dev
vlc_variables.h
Go to the documentation of this file.
1 /*****************************************************************************
2  * vlc_variables.h: variables handling
3  *****************************************************************************
4  * Copyright (C) 2002-2004 VLC authors and VideoLAN
5  *
6  * Authors: Samuel Hocevar <sam@zoy.org>
7  * Gildas Bazin <gbazin@netcourrier.com>
8  *
9  * This program is free software; you can redistribute it and/or modify it
10  * under the terms of the GNU Lesser General Public License as published by
11  * the Free Software Foundation; either version 2.1 of the License, or
12  * (at your option) any later version.
13  *
14  * This program is distributed in the hope that it will be useful,
15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17  * GNU Lesser General Public License for more details.
18  *
19  * You should have received a copy of the GNU Lesser General Public License
20  * along with this program; if not, write to the Free Software Foundation,
21  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
22  *****************************************************************************/
23 
24 #ifndef VLC_VARIABLES_H
25 #define VLC_VARIABLES_H 1
26 
27 /**
28  * \defgroup variables Variables
29  * \ingroup vlc_object
30  *
31  * VLC object variables and callbacks
32  *
33  * @{
34  * \file
35  * VLC object variables and callbacks interface
36  */
37 
38 #define VLC_VAR_TYPE 0x00ff
39 #define VLC_VAR_CLASS 0x00f0
40 #define VLC_VAR_FLAGS 0xff00
41 
42 /**
43  * \defgroup var_type Variable types
44  * These are the different types a vlc variable can have.
45  * @{
46  */
47 #define VLC_VAR_VOID 0x0010
48 #define VLC_VAR_BOOL 0x0020
49 #define VLC_VAR_INTEGER 0x0030
50 #define VLC_VAR_STRING 0x0040
51 #define VLC_VAR_FLOAT 0x0050
52 #define VLC_VAR_ADDRESS 0x0070
53 #define VLC_VAR_COORDS 0x00A0
54 /**@}*/
55 
56 /** \defgroup var_flags Additive flags
57  * These flags are added to the type field of the variable. Most as a result of
58  * a var_Change() call, but some may be added at creation time
59  * @{
60  */
61 #define VLC_VAR_HASCHOICE 0x0100
62 
63 #define VLC_VAR_ISCOMMAND 0x2000
64 
65 /** Creation flag */
66 /* If the variable is not found on the current module
67  search all parents and finally module config until found */
68 #define VLC_VAR_DOINHERIT 0x8000
69 /**@}*/
70 
71 /**
72  * \defgroup var_action Variable actions
73  * These are the different actions that can be used with var_Change().
74  * The parameters given are the meaning of the two last parameters of
75  * var_Change() when this action is being used.
76  * @{
77  */
78 
79 #define VLC_VAR_SETSTEP 0x0012
80 
81 /**
82  * Set the value of this variable without triggering any callbacks
83  * \param p_val The new value
84  * \param p_val2 Unused
85  */
86 #define VLC_VAR_SETVALUE 0x0013
87 
88 #define VLC_VAR_SETTEXT 0x0014
89 #define VLC_VAR_GETTEXT 0x0015
90 
91 #define VLC_VAR_GETMIN 0x0016
92 #define VLC_VAR_GETMAX 0x0017
93 #define VLC_VAR_GETSTEP 0x0018
94 
95 #define VLC_VAR_ADDCHOICE 0x0020
96 #define VLC_VAR_DELCHOICE 0x0021
97 #define VLC_VAR_CLEARCHOICES 0x0022
98 #define VLC_VAR_GETCHOICES 0x0024
99 
100 #define VLC_VAR_CHOICESCOUNT 0x0026
101 #define VLC_VAR_SETMINMAX 0x0027
103 /**@}*/
104 
105 /**
106  * Variable actions.
107  *
108  * These are the different actions that can be used with var_GetAndSet().
109  */
110 enum vlc_var_atomic_op {
111  VLC_VAR_BOOL_TOGGLE, /**< Invert a boolean value (param ignored) */
112  VLC_VAR_INTEGER_ADD, /**< Add parameter to an integer value */
113  VLC_VAR_INTEGER_OR, /**< Binary OR over an integer bits field */
114  VLC_VAR_INTEGER_NAND,/**< Binary NAND over an integer bits field */
115 };
116 
117 /**
118  * Creates a VLC object variable.
119  *
120  * This function creates a named variable within a VLC object.
121  * If a variable already exists with the same name within the same object, its
122  * reference count is incremented instead.
123  *
124  * \param obj Object to hold the variable
125  * \param name Variable name
126  * \param type Variable type. Must be one of \ref var_type combined with
127  * zero or more \ref var_flags
128  */
129 VLC_API int var_Create(vlc_object_t *obj, const char *name, int type);
130 
131 /**
132  * Destroys a VLC object variable.
133  *
134  * This function decrements the reference count of a named variable within a
135  * VLC object. If the reference count reaches zero, the variable is destroyed.
136  *
137  * \param obj Object holding the variable
138  * \param name Variable name
139  */
140 VLC_API void var_Destroy(vlc_object_t *obj, const char *name);
141 
142 /**
143  * Performs a special action on a variable.
144  *
145  * \param obj Object holding the variable
146  * \param name Variable name
147  * \param action Action to perform. Must be one of \ref var_action
148  */
149 VLC_API int var_Change(vlc_object_t *obj, const char *name, int action, ...);
150 
151 /**
152  * Get the type of a variable.
153  *
154  * \see var_type
155  *
156  * \return The variable type if it exists
157  * or 0 if the variable could not be found.
158  */
159 VLC_API int var_Type(vlc_object_t *obj, const char *name) VLC_USED;
160 
161 /**
162  * Sets a variable value.
163  *
164  * \param obj Object holding the variable
165  * \param name Variable name
166  * \param val Variable value to set
167  */
168 VLC_API int var_Set(vlc_object_t *obj, const char *name, vlc_value_t val);
169 
170 /**
171  * Gets a variable value.
172  *
173  * \param obj Object holding the variable
174  * \param name Variable name
175  * \param valp Pointer to a \ref vlc_value_t object to hold the value [OUT]
176  */
177 VLC_API int var_Get(vlc_object_t *obj, const char *name, vlc_value_t *valp);
178 
179 VLC_API int var_SetChecked( vlc_object_t *, const char *, int, vlc_value_t );
180 VLC_API int var_GetChecked( vlc_object_t *, const char *, int, vlc_value_t * );
181 
182 /**
183  * Perform an atomic read-modify-write of a variable.
184  *
185  * \param obj object holding the variable
186  * \param name variable name
187  * \param op read-modify-write operation to perform
188  * (see \ref vlc_var_atomic_op)
189  * \param value value of the variable after the modification
190  * \retval VLC_SUCCESS Operation successful
191  * \retval VLC_ENOVAR Variable not found
192  *
193  * \bug The modified value is returned rather than the original value.
194  * As such, the original value cannot be known in the case of non-reversible
195  * operation such as \ref VLC_VAR_INTEGER_OR and \ref VLC_VAR_INTEGER_NAND.
196  */
197 VLC_API int var_GetAndSet(vlc_object_t *obj, const char *name, int op,
198  vlc_value_t *value);
199 
200 /**
201  * Finds the value of a variable.
202  *
203  * If the specified object does not hold a variable with the specified name,
204  * try the parent object, and iterate until the top of the objects tree. If no
205  * match is found, the value is read from the configuration.
206  */
207 VLC_API int var_Inherit( vlc_object_t *, const char *, int, vlc_value_t * );
208 
209 
210 /*****************************************************************************
211  * Variable callbacks
212  *****************************************************************************
213  * int MyCallback( vlc_object_t *p_this,
214  * char const *psz_variable,
215  * vlc_value_t oldvalue,
216  * vlc_value_t newvalue,
217  * void *p_data);
218  *****************************************************************************/
219 
220 /**
221  * Registers a callback for a variable.
222  *
223  * We store a function pointer that will be called upon variable
224  * modification.
225  *
226  * \param obj Object holding the variable
227  * \param name Variable name
228  * \param callback Callback function pointer
229  * \param opaque Opaque data pointer for use by the callback.
230  *
231  * \warning The callback function is run in the thread that calls var_Set() on
232  * the variable. Use proper locking. This thread may not have much
233  * time to spare, so keep callback functions short.
234  *
235  * \bug It is not possible to atomically retrieve the current value and
236  * register a callback. As a consequence, extreme care must be taken to ensure
237  * that the variable value cannot change before the callback is registered.
238  * Failure to do so will result in intractable race conditions.
239  */
240 VLC_API void var_AddCallback(vlc_object_t *obj, const char *name,
241  vlc_callback_t callback, void *opaque);
242 
243 /**
244  * Deregisters a callback from a variable.
245  *
246  * The callback and opaque pointer must be supplied again, as the same callback
247  * function might have been registered more than once.
248  */
249 VLC_API void var_DelCallback(vlc_object_t *obj, const char *name,
250  vlc_callback_t callback, void *opaque);
251 
252 /**
253  * Triggers callbacks on a variable.
254  *
255  * This triggers any callbacks registered on the named variable without
256  * actually modifying the variable value. This is primarily useful for
257  * variables with \ref VLC_VAR_VOID type (which do not have a value).
258  *
259  * \param obj Object holding the variable
260  * \param name Variable name
261  */
262 VLC_API void var_TriggerCallback(vlc_object_t *obj, const char *name);
263 
264 /**
265  * Register a callback for a list variable
266  *
267  * The callback is triggered when an element is added/removed from the
268  * list or when the list is cleared.
269  *
270  * See var_AddCallback().
271  */
272 VLC_API void var_AddListCallback( vlc_object_t *, const char *, vlc_list_callback_t, void * );
273 
274 /**
275  * Remove a callback from a list variable
276  *
277  * See var_DelCallback().
278  */
279 VLC_API void var_DelListCallback( vlc_object_t *, const char *, vlc_list_callback_t, void * );
280 
281 /*****************************************************************************
282  * helpers functions
283  *****************************************************************************/
284 
285 /**
286  * Set the value of an integer variable
287  *
288  * \param p_obj The object that holds the variable
289  * \param psz_name The name of the variable
290  * \param i The new integer value of this variable
291  */
292 static inline int var_SetInteger( vlc_object_t *p_obj, const char *psz_name,
293  int64_t i )
294 {
295  vlc_value_t val;
296  val.i_int = i;
297  return var_SetChecked( p_obj, psz_name, VLC_VAR_INTEGER, val );
298 }
299 
300 /**
301  * Set the value of an boolean variable
302  *
303  * \param p_obj The object that holds the variable
304  * \param psz_name The name of the variable
305  * \param b The new boolean value of this variable
306  */
307 static inline int var_SetBool( vlc_object_t *p_obj, const char *psz_name, bool b )
308 {
309  vlc_value_t val;
310  val.b_bool = b;
311  return var_SetChecked( p_obj, psz_name, VLC_VAR_BOOL, val );
312 }
313 
314 static inline int var_SetCoords( vlc_object_t *obj, const char *name,
315  int32_t x, int32_t y )
316 {
317  vlc_value_t val;
318  val.coords.x = x;
319  val.coords.y = y;
320  return var_SetChecked (obj, name, VLC_VAR_COORDS, val);
321 }
322 
323 /**
324  * Set the value of a float variable
325  *
326  * \param p_obj The object that holds the variable
327  * \param psz_name The name of the variable
328  * \param f The new float value of this variable
329  */
330 static inline int var_SetFloat( vlc_object_t *p_obj, const char *psz_name, float f )
331 {
332  vlc_value_t val;
333  val.f_float = f;
334  return var_SetChecked( p_obj, psz_name, VLC_VAR_FLOAT, val );
335 }
336 
337 /**
338  * Set the value of a string variable
339  *
340  * \param p_obj The object that holds the variable
341  * \param psz_name The name of the variable
342  * \param psz_string The new string value of this variable
343  */
344 static inline int var_SetString( vlc_object_t *p_obj, const char *psz_name, const char *psz_string )
345 {
346  vlc_value_t val;
347  val.psz_string = (char *)psz_string;
348  return var_SetChecked( p_obj, psz_name, VLC_VAR_STRING, val );
349 }
350 
351 /**
352  * Set the value of a pointer variable
353  *
354  * \param p_obj The object that holds the variable
355  * \param psz_name The name of the variable
356  * \param ptr The new pointer value of this variable
357  */
358 static inline
359 int var_SetAddress( vlc_object_t *p_obj, const char *psz_name, void *ptr )
360 {
361  vlc_value_t val;
362  val.p_address = ptr;
363  return var_SetChecked( p_obj, psz_name, VLC_VAR_ADDRESS, val );
364 }
365 
366 /**
367  * Get an integer value
368 *
369  * \param p_obj The object that holds the variable
370  * \param psz_name The name of the variable
371  */
372 VLC_USED
373 static inline int64_t var_GetInteger( vlc_object_t *p_obj, const char *psz_name )
374 {
375  vlc_value_t val;
376  if( !var_GetChecked( p_obj, psz_name, VLC_VAR_INTEGER, &val ) )
377  return val.i_int;
378  else
379  return 0;
380 }
381 
382 /**
383  * Get a boolean value
384  *
385  * \param p_obj The object that holds the variable
386  * \param psz_name The name of the variable
387  */
388 VLC_USED
389 static inline bool var_GetBool( vlc_object_t *p_obj, const char *psz_name )
390 {
391  vlc_value_t val; val.b_bool = false;
392 
393  if( !var_GetChecked( p_obj, psz_name, VLC_VAR_BOOL, &val ) )
394  return val.b_bool;
395  else
396  return false;
397 }
398 
399 static inline void var_GetCoords( vlc_object_t *obj, const char *name,
400  int32_t *px, int32_t *py )
401 {
402  vlc_value_t val;
403 
404  if (likely(!var_GetChecked (obj, name, VLC_VAR_COORDS, &val)))
405  {
406  *px = val.coords.x;
407  *py = val.coords.y;
408  }
409  else
410  *px = *py = 0;
411 }
412 
413 /**
414  * Get a float value
415  *
416  * \param p_obj The object that holds the variable
417  * \param psz_name The name of the variable
418  */
419 VLC_USED
420 static inline float var_GetFloat( vlc_object_t *p_obj, const char *psz_name )
421 {
422  vlc_value_t val; val.f_float = 0.0;
423  if( !var_GetChecked( p_obj, psz_name, VLC_VAR_FLOAT, &val ) )
424  return val.f_float;
425  else
426  return 0.0;
427 }
428 
429 /**
430  * Get a string value
431  *
432  * \param p_obj The object that holds the variable
433  * \param psz_name The name of the variable
434  */
436 static inline char *var_GetString( vlc_object_t *p_obj, const char *psz_name )
437 {
438  vlc_value_t val; val.psz_string = NULL;
439  if( var_GetChecked( p_obj, psz_name, VLC_VAR_STRING, &val ) )
440  return NULL;
441  else
442  return val.psz_string;
443 }
444 
446 static inline char *var_GetNonEmptyString( vlc_object_t *p_obj, const char *psz_name )
447 {
448  vlc_value_t val;
449  if( var_GetChecked( p_obj, psz_name, VLC_VAR_STRING, &val ) )
450  return NULL;
451  if( val.psz_string && *val.psz_string )
452  return val.psz_string;
453  free( val.psz_string );
454  return NULL;
455 }
456 
457 VLC_USED
458 static inline void *var_GetAddress( vlc_object_t *p_obj, const char *psz_name )
459 {
460  vlc_value_t val;
461  if( var_GetChecked( p_obj, psz_name, VLC_VAR_ADDRESS, &val ) )
462  return NULL;
463  else
464  return val.p_address;
465 }
466 
467 /**
468  * Increment an integer variable
469  * \param p_obj the object that holds the variable
470  * \param psz_name the name of the variable
471  */
472 static inline int64_t var_IncInteger( vlc_object_t *p_obj, const char *psz_name )
473 {
474  vlc_value_t val;
475  val.i_int = 1;
476  if( var_GetAndSet( p_obj, psz_name, VLC_VAR_INTEGER_ADD, &val ) )
477  return 0;
478  return val.i_int;
479 }
480 
481 /**
482  * Decrement an integer variable
483  * \param p_obj the object that holds the variable
484  * \param psz_name the name of the variable
485  */
486 static inline int64_t var_DecInteger( vlc_object_t *p_obj, const char *psz_name )
487 {
488  vlc_value_t val;
489  val.i_int = -1;
490  if( var_GetAndSet( p_obj, psz_name, VLC_VAR_INTEGER_ADD, &val ) )
491  return 0;
492  return val.i_int;
493 }
494 
495 static inline uint64_t var_OrInteger( vlc_object_t *obj, const char *name,
496  unsigned v )
497 {
498  vlc_value_t val;
499  val.i_int = v;
500  if( var_GetAndSet( obj, name, VLC_VAR_INTEGER_OR, &val ) )
501  return 0;
502  return val.i_int;
503 }
504 
505 static inline uint64_t var_NAndInteger( vlc_object_t *obj, const char *name,
506  unsigned v )
507 {
508  vlc_value_t val;
509  val.i_int = v;
510  if( var_GetAndSet( obj, name, VLC_VAR_INTEGER_NAND, &val ) )
511  return 0;
512  return val.i_int;
513 }
514 
515 /**
516  * Create a integer variable with inherit and get its value.
517  *
518  * \param p_obj The object that holds the variable
519  * \param psz_name The name of the variable
520  */
521 VLC_USED
522 static inline int64_t var_CreateGetInteger( vlc_object_t *p_obj, const char *psz_name )
523 {
524  var_Create( p_obj, psz_name, VLC_VAR_INTEGER | VLC_VAR_DOINHERIT );
525  return var_GetInteger( p_obj, psz_name );
526 }
527 
528 /**
529  * Create a boolean variable with inherit and get its value.
530  *
531  * \param p_obj The object that holds the variable
532  * \param psz_name The name of the variable
533  */
534 VLC_USED
535 static inline bool var_CreateGetBool( vlc_object_t *p_obj, const char *psz_name )
536 {
537  var_Create( p_obj, psz_name, VLC_VAR_BOOL | VLC_VAR_DOINHERIT );
538  return var_GetBool( p_obj, psz_name );
539 }
540 
541 /**
542  * Create a float variable with inherit and get its value.
543  *
544  * \param p_obj The object that holds the variable
545  * \param psz_name The name of the variable
546  */
547 VLC_USED
548 static inline float var_CreateGetFloat( vlc_object_t *p_obj, const char *psz_name )
549 {
550  var_Create( p_obj, psz_name, VLC_VAR_FLOAT | VLC_VAR_DOINHERIT );
551  return var_GetFloat( p_obj, psz_name );
552 }
553 
554 /**
555  * Create a string variable with inherit and get its value.
556  *
557  * \param p_obj The object that holds the variable
558  * \param psz_name The name of the variable
559  */
561 static inline char *var_CreateGetString( vlc_object_t *p_obj,
562  const char *psz_name )
563 {
565  return var_GetString( p_obj, psz_name );
566 }
567 
569 static inline char *var_CreateGetNonEmptyString( vlc_object_t *p_obj,
570  const char *psz_name )
571 {
573  return var_GetNonEmptyString( p_obj, psz_name );
574 }
575 
576 /**
577  * Create an address 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 VLC_USED
583 static inline void *var_CreateGetAddress( vlc_object_t *p_obj,
584  const char *psz_name )
585 {
587  return var_GetAddress( p_obj, psz_name );
588 }
589 
590 /**
591  * Create a integer 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 VLC_USED
597 static inline int64_t var_CreateGetIntegerCommand( vlc_object_t *p_obj, const char *psz_name )
598 {
599  var_Create( p_obj, psz_name, VLC_VAR_INTEGER | VLC_VAR_DOINHERIT
600  | VLC_VAR_ISCOMMAND );
601  return var_GetInteger( p_obj, psz_name );
602 }
603 
604 /**
605  * Create a boolean command variable with inherit and get its value.
606  *
607  * \param p_obj The object that holds the variable
608  * \param psz_name The name of the variable
609  */
610 VLC_USED
611 static inline bool var_CreateGetBoolCommand( vlc_object_t *p_obj, const char *psz_name )
612 {
613  var_Create( p_obj, psz_name, VLC_VAR_BOOL | VLC_VAR_DOINHERIT
614  | VLC_VAR_ISCOMMAND );
615  return var_GetBool( p_obj, psz_name );
616 }
617 
618 /**
619  * Create a float command variable with inherit and get its value.
620  *
621  * \param p_obj The object that holds the variable
622  * \param psz_name The name of the variable
623  */
624 VLC_USED
625 static inline float var_CreateGetFloatCommand( vlc_object_t *p_obj, const char *psz_name )
626 {
627  var_Create( p_obj, psz_name, VLC_VAR_FLOAT | VLC_VAR_DOINHERIT
628  | VLC_VAR_ISCOMMAND );
629  return var_GetFloat( p_obj, psz_name );
630 }
631 
632 /**
633  * Create a string command variable with inherit and get its value.
634  *
635  * \param p_obj The object that holds the variable
636  * \param psz_name The name of the variable
637  */
639 static inline char *var_CreateGetStringCommand( vlc_object_t *p_obj,
640  const char *psz_name )
641 {
643  | VLC_VAR_ISCOMMAND );
644  return var_GetString( p_obj, psz_name );
645 }
646 
648 static inline char *var_CreateGetNonEmptyStringCommand( vlc_object_t *p_obj,
649  const char *psz_name )
650 {
652  | VLC_VAR_ISCOMMAND );
653  return var_GetNonEmptyString( p_obj, psz_name );
654 }
655 
656 VLC_USED
657 static inline int var_CountChoices( vlc_object_t *p_obj, const char *psz_name )
658 {
659  size_t count;
660  if( var_Change( p_obj, psz_name, VLC_VAR_CHOICESCOUNT, &count ) )
661  return 0;
662  return count;
663 }
664 
665 static inline bool var_ToggleBool( vlc_object_t *p_obj, const char *psz_name )
666 {
667  vlc_value_t val;
668  if( var_GetAndSet( p_obj, psz_name, VLC_VAR_BOOL_TOGGLE, &val ) )
669  return false;
670  return val.b_bool;
671 }
672 
673 VLC_USED
674 static inline bool var_InheritBool( vlc_object_t *obj, const char *name )
675 {
676  vlc_value_t val;
677 
678  if( var_Inherit( obj, name, VLC_VAR_BOOL, &val ) )
679  val.b_bool = false;
680  return val.b_bool;
681 }
682 
683 VLC_USED
684 static inline int64_t var_InheritInteger( vlc_object_t *obj, const char *name )
685 {
686  vlc_value_t val;
687 
688  if( var_Inherit( obj, name, VLC_VAR_INTEGER, &val ) )
689  val.i_int = 0;
690  return val.i_int;
691 }
692 
693 VLC_USED
694 static inline float var_InheritFloat( vlc_object_t *obj, const char *name )
695 {
696  vlc_value_t val;
697 
698  if( var_Inherit( obj, name, VLC_VAR_FLOAT, &val ) )
699  val.f_float = 0.;
700  return val.f_float;
701 }
702 
704 static inline char *var_InheritString( vlc_object_t *obj, const char *name )
705 {
706  vlc_value_t val;
707 
708  if( var_Inherit( obj, name, VLC_VAR_STRING, &val ) )
709  val.psz_string = NULL;
710  else if( val.psz_string && !*val.psz_string )
711  {
712  free( val.psz_string );
713  val.psz_string = NULL;
714  }
715  return val.psz_string;
716 }
717 
718 VLC_USED
719 static inline void *var_InheritAddress( vlc_object_t *obj, const char *name )
720 {
721  vlc_value_t val;
722 
723  if( var_Inherit( obj, name, VLC_VAR_ADDRESS, &val ) )
724  val.p_address = NULL;
725  return val.p_address;
726 }
727 
728 
729 /**
730  * Inherit a string as a fractional value.
731  *
732  * This function inherits a string, and interprets it as an unsigned rational
733  * number, i.e. a fraction. It also accepts a normally formatted floating point
734  * number.
735  *
736  * \warning The caller shall perform any and all necessary boundary checks.
737  *
738  * \note The rational number is always reduced,
739  * i.e. the returned numerator and denominator are always co-prime numbers.
740  *
741  * \note Fraction with zero as denominator are considered valid,
742  * including the undefined form zero-by-zero.
743  *
744  * \return Zero on success, an error if parsing fails.
745  */
746 VLC_API int var_InheritURational(vlc_object_t *obj, unsigned *num,
747  unsigned *den, const char *name);
748 
749 /**
750  * Parses a string with multiple options.
751  *
752  * Parses a set of colon-separated or semicolon-separated
753  * <code>name=value</code> pairs.
754  * Some access (or access_demux) plugins uses this scheme
755  * in media resource location.
756  * @note Only trusted/safe variables are allowed. This is intended.
757  *
758  * @warning Only use this for plugins implementing VLC-specific resource
759  * location schemes. This would not make any sense for standardized ones.
760  *
761  * @param obj VLC object on which to set variables (and emit error messages)
762  * @param mrl string to parse
763  * @param pref prefix to prepend to option names in the string
764  *
765  * @return VLC_ENOMEM on error, VLC_SUCCESS on success.
766  */
767 VLC_API int var_LocationParse(vlc_object_t *, const char *mrl, const char *prefix);
768 
769 #ifndef DOC
770 #define var_Create(a,b,c) var_Create(VLC_OBJECT(a), b, c)
771 #define var_Destroy(a,b) var_Destroy(VLC_OBJECT(a), b)
772 #define var_Change(a,b,...) var_Change(VLC_OBJECT(a), b, __VA_ARGS__)
773 #define var_Type(a,b) var_Type(VLC_OBJECT(a), b)
774 #define var_Set(a,b,c) var_Set(VLC_OBJECT(a), b, c)
775 #define var_Get(a,b,c) var_Get(VLC_OBJECT(a), b, c)
776 #define var_SetChecked(o,n,t,v) var_SetChecked(VLC_OBJECT(o), n, t, v)
777 #define var_GetChecked(o,n,t,v) var_GetChecked(VLC_OBJECT(o), n, t, v)
778 
779 #define var_AddCallback(a,b,c,d) var_AddCallback(VLC_OBJECT(a), b, c, d)
780 #define var_DelCallback(a,b,c,d) var_DelCallback(VLC_OBJECT(a), b, c, d)
781 #define var_TriggerCallback(a,b) var_TriggerCallback(VLC_OBJECT(a), b)
782 #define var_AddListCallback(a,b,c,d) \
783  var_AddListCallback(VLC_OBJECT(a), b, c, d)
784 #define var_DelListCallback(a,b,c,d) \
785  var_DelListCallback(VLC_OBJECT(a), b, c, d)
786 
787 #define var_SetInteger(a,b,c) var_SetInteger(VLC_OBJECT(a), b, c)
788 #define var_SetBool(a,b,c) var_SetBool(VLC_OBJECT(a), b, c)
789 #define var_SetCoords(o,n,x,y) var_SetCoords(VLC_OBJECT(o), n, x, y)
790 #define var_SetFloat(a,b,c) var_SetFloat(VLC_OBJECT(a), b, c)
791 #define var_SetString(a,b,c) var_SetString(VLC_OBJECT(a), b, c)
792 #define var_SetAddress(o, n, p) var_SetAddress(VLC_OBJECT(o), n, p)
793 
794 #define var_GetCoords(o,n,x,y) var_GetCoords(VLC_OBJECT(o), n, x, y)
795 
796 #define var_IncInteger(a,b) var_IncInteger(VLC_OBJECT(a), b)
797 #define var_DecInteger(a,b) var_DecInteger(VLC_OBJECT(a), b)
798 #define var_OrInteger(a,b,c) var_OrInteger(VLC_OBJECT(a), b, c)
799 #define var_NAndInteger(a,b,c) var_NAndInteger(VLC_OBJECT(a), b, c)
800 
801 #define var_CreateGetInteger(a,b) var_CreateGetInteger(VLC_OBJECT(a), b)
802 #define var_CreateGetBool(a,b) var_CreateGetBool(VLC_OBJECT(a), b)
803 #define var_CreateGetFloat(a,b) var_CreateGetFloat(VLC_OBJECT(a), b)
804 #define var_CreateGetString(a,b) var_CreateGetString(VLC_OBJECT(a), b)
805 #define var_CreateGetNonEmptyString(a,b) \
806  var_CreateGetNonEmptyString(VLC_OBJECT(a), b)
807 #define var_CreateGetAddress(a,b) var_CreateGetAddress( VLC_OBJECT(a), b)
808 
809 #define var_CreateGetIntegerCommand(a,b) var_CreateGetIntegerCommand( VLC_OBJECT(a),b)
810 #define var_CreateGetBoolCommand(a,b) var_CreateGetBoolCommand( VLC_OBJECT(a),b)
811 #define var_CreateGetFloatCommand(a,b) var_CreateGetFloatCommand( VLC_OBJECT(a),b)
812 #define var_CreateGetStringCommand(a,b) var_CreateGetStringCommand( VLC_OBJECT(a),b)
813 #define var_CreateGetNonEmptyStringCommand(a,b) var_CreateGetNonEmptyStringCommand( VLC_OBJECT(a),b)
814 
815 #define var_CountChoices(a,b) var_CountChoices(VLC_OBJECT(a),b)
816 #define var_ToggleBool(a,b) var_ToggleBool(VLC_OBJECT(a),b )
817 
818 #define var_InheritBool(o, n) var_InheritBool(VLC_OBJECT(o), n)
819 #define var_InheritInteger(o, n) var_InheritInteger(VLC_OBJECT(o), n)
820 #define var_InheritFloat(o, n) var_InheritFloat(VLC_OBJECT(o), n)
821 #define var_InheritString(o, n) var_InheritString(VLC_OBJECT(o), n)
822 #define var_InheritAddress(o, n) var_InheritAddress(VLC_OBJECT(o), n)
823 #define var_InheritURational(a,b,c,d) var_InheritURational(VLC_OBJECT(a), b, c, d)
824 
825 #define var_GetInteger(a,b) var_GetInteger(VLC_OBJECT(a),b)
826 #define var_GetBool(a,b) var_GetBool(VLC_OBJECT(a),b)
827 #define var_GetFloat(a,b) var_GetFloat(VLC_OBJECT(a),b)
828 #define var_GetString(a,b) var_GetString(VLC_OBJECT(a),b)
829 #define var_GetNonEmptyString(a,b) var_GetNonEmptyString( VLC_OBJECT(a),b)
830 #define var_GetAddress(a,b) var_GetAddress(VLC_OBJECT(a),b)
831 
832 #define var_LocationParse(o, m, p) var_LocationParse(VLC_OBJECT(o), m, p)
833 #endif
834 
835 /**
836  * @}
837  */
838 #endif /* _VLC_VARIABLES_H */
static void * var_CreateGetAddress(vlc_object_t *p_obj, const char *psz_name)
Create an address variable with inherit and get its value.
Definition: vlc_variables.h:584
static int var_CountChoices(vlc_object_t *p_obj, const char *psz_name)
Definition: vlc_variables.h:658
struct vlc_value_t::@197 coords
int32_t x
Definition: vlc_common.h:462
void var_TriggerCallback(vlc_object_t *obj, const char *name)
Triggers callbacks on a variable.
Definition: variables.c:862
void var_AddCallback(vlc_object_t *obj, const char *name, vlc_callback_t callback, void *opaque)
Registers a callback for a variable.
Definition: variables.c:799
#define VLC_VAR_ADDRESS
Definition: vlc_variables.h:53
static char * var_GetString(vlc_object_t *p_obj, const char *psz_name)
Get a string value.
Definition: vlc_variables.h:437
#define VLC_VAR_ISCOMMAND
Definition: vlc_variables.h:64
int var_Change(vlc_object_t *obj, const char *name, int action,...)
Performs a special action on a variable.
Definition: variables.c:421
#define VLC_VAR_INTEGER
Definition: vlc_variables.h:50
static void var_GetCoords(vlc_object_t *obj, const char *name, int32_t *px, int32_t *py)
Definition: vlc_variables.h:400
static int64_t var_GetInteger(vlc_object_t *p_obj, const char *psz_name)
Get an integer value.
Definition: vlc_variables.h:374
static char * var_InheritString(vlc_object_t *obj, const char *name)
Definition: vlc_variables.h:705
int var_Type(vlc_object_t *obj, const char *name)
Get the type of a variable.
Definition: variables.c:653
static int64_t var_DecInteger(vlc_object_t *p_obj, const char *psz_name)
Decrement an integer variable.
Definition: vlc_variables.h:487
vlc_var_atomic_op
Variable actions.
Definition: vlc_variables.h:111
static char * var_CreateGetNonEmptyStringCommand(vlc_object_t *p_obj, const char *psz_name)
Definition: vlc_variables.h:649
#define VLC_VAR_BOOL
Definition: vlc_variables.h:49
VLC value structure.
Definition: vlc_common.h:455
static char * var_GetNonEmptyString(vlc_object_t *p_obj, const char *psz_name)
Definition: vlc_variables.h:447
static int var_SetBool(vlc_object_t *p_obj, const char *psz_name, bool b)
Set the value of an boolean variable.
Definition: vlc_variables.h:308
static char * var_CreateGetString(vlc_object_t *p_obj, const char *psz_name)
Create a string variable with inherit and get its value.
Definition: vlc_variables.h:562
void var_DelCallback(vlc_object_t *obj, const char *name, vlc_callback_t callback, void *opaque)
Deregisters a callback from a variable.
Definition: variables.c:852
const char * psz_name
Definition: text_style.c:33
static float var_GetFloat(vlc_object_t *p_obj, const char *psz_name)
Get a float value.
Definition: vlc_variables.h:421
void var_Destroy(vlc_object_t *obj, const char *name)
Destroys a VLC object variable.
Definition: variables.c:380
static int64_t var_CreateGetInteger(vlc_object_t *p_obj, const char *psz_name)
Create a integer variable with inherit and get its value.
Definition: vlc_variables.h:523
int var_Set(vlc_object_t *obj, const char *name, vlc_value_t val)
Sets a variable value.
Definition: variables.c:719
Add parameter to an integer value.
Definition: vlc_variables.h:113
#define VLC_MALLOC
Heap allocated result function annotation.
Definition: vlc_common.h:167
static bool var_CreateGetBoolCommand(vlc_object_t *p_obj, const char *psz_name)
Create a boolean command variable with inherit and get its value.
Definition: vlc_variables.h:612
#define VLC_VAR_DOINHERIT
Creation flag.
Definition: vlc_variables.h:69
static char * var_CreateGetNonEmptyString(vlc_object_t *p_obj, const char *psz_name)
Definition: vlc_variables.h:570
static uint64_t var_NAndInteger(vlc_object_t *obj, const char *name, unsigned v)
Definition: vlc_variables.h:506
Binary OR over an integer bits field.
Definition: vlc_variables.h:114
int var_GetAndSet(vlc_object_t *obj, const char *name, int op, vlc_value_t *value)
Perform an atomic read-modify-write of a variable.
Definition: variables.c:592
size_t count
Definition: core.c:402
float f_float
Definition: vlc_common.h:459
int32_t y
Definition: vlc_common.h:462
static int var_SetCoords(vlc_object_t *obj, const char *name, int32_t x, int32_t y)
Definition: vlc_variables.h:315
#define likely(p)
Predicted true condition.
Definition: vlc_common.h:214
int(* vlc_list_callback_t)(vlc_object_t *, char const *, int, vlc_value_t *, void *)
Definition: vlc_common.h:500
static bool var_ToggleBool(vlc_object_t *p_obj, const char *psz_name)
Definition: vlc_variables.h:666
static int64_t var_CreateGetIntegerCommand(vlc_object_t *p_obj, const char *psz_name)
Create a integer command variable with inherit and get its value.
Definition: vlc_variables.h:598
const char name[16]
Definition: httpd.c:1269
static char * var_CreateGetStringCommand(vlc_object_t *p_obj, const char *psz_name)
Create a string command variable with inherit and get its value.
Definition: vlc_variables.h:640
bool b_bool
Definition: vlc_common.h:458
static uint64_t var_OrInteger(vlc_object_t *obj, const char *name, unsigned v)
Definition: vlc_variables.h:496
static int64_t var_InheritInteger(vlc_object_t *obj, const char *name)
Definition: vlc_variables.h:685
#define VLC_API
Definition: fourcc_gen.c:31
#define VLC_VAR_STRING
Definition: vlc_variables.h:51
static float var_CreateGetFloatCommand(vlc_object_t *p_obj, const char *psz_name)
Create a float command variable with inherit and get its value.
Definition: vlc_variables.h:626
static void * var_GetAddress(vlc_object_t *p_obj, const char *psz_name)
Definition: vlc_variables.h:459
static bool var_CreateGetBool(vlc_object_t *p_obj, const char *psz_name)
Create a boolean variable with inherit and get its value.
Definition: vlc_variables.h:536
static int var_SetFloat(vlc_object_t *p_obj, const char *psz_name, float f)
Set the value of a float variable.
Definition: vlc_variables.h:331
Binary NAND over an integer bits field.
Definition: vlc_variables.h:115
int(* vlc_callback_t)(vlc_object_t *, char const *, vlc_value_t, vlc_value_t, void *)
Definition: vlc_common.h:491
int var_Get(vlc_object_t *obj, const char *name, vlc_value_t *valp)
Gets a variable value.
Definition: variables.c:753
static void * var_InheritAddress(vlc_object_t *obj, const char *name)
Definition: vlc_variables.h:720
void var_AddListCallback(vlc_object_t *, const char *, vlc_list_callback_t, void *)
Register a callback for a list variable.
Definition: variables.c:877
static bool var_GetBool(vlc_object_t *p_obj, const char *psz_name)
Get a boolean value.
Definition: vlc_variables.h:390
int var_LocationParse(vlc_object_t *, const char *mrl, const char *prefix)
Parses a string with multiple options.
Definition: variables.c:1008
Invert a boolean value (param ignored)
Definition: vlc_variables.h:112
static int var_SetString(vlc_object_t *p_obj, const char *psz_name, const char *psz_string)
Set the value of a string variable.
Definition: vlc_variables.h:345
int var_Inherit(vlc_object_t *, const char *, int, vlc_value_t *)
Finds the value of a variable.
Definition: variables.c:1037
int64_t i_int
Definition: vlc_common.h:457
#define VLC_VAR_CHOICESCOUNT
Definition: vlc_variables.h:101
#define VLC_VAR_COORDS
Definition: vlc_variables.h:54
void * p_address
Definition: vlc_common.h:461
int var_InheritURational(vlc_object_t *obj, unsigned *num, unsigned *den, const char *name)
Inherit a string as a fractional value.
Definition: variables.c:1071
static int var_SetAddress(vlc_object_t *p_obj, const char *psz_name, void *ptr)
Set the value of a pointer variable.
Definition: vlc_variables.h:360
static bool var_InheritBool(vlc_object_t *obj, const char *name)
Definition: vlc_variables.h:675
static float var_CreateGetFloat(vlc_object_t *p_obj, const char *psz_name)
Create a float variable with inherit and get its value.
Definition: vlc_variables.h:549
int var_Create(vlc_object_t *obj, const char *name, int type)
Creates a VLC object variable.
Definition: variables.c:289
int var_GetChecked(vlc_object_t *, const char *, int, vlc_value_t *)
Definition: variables.c:724
int var_SetChecked(vlc_object_t *, const char *, int, vlc_value_t)
Definition: variables.c:674
VLC object common members.
Definition: vlc_objects.h:43
char * psz_string
Definition: vlc_common.h:460
#define VLC_USED
Definition: fourcc_gen.c:32
static float var_InheritFloat(vlc_object_t *obj, const char *name)
Definition: vlc_variables.h:695
void var_DelListCallback(vlc_object_t *, const char *, vlc_list_callback_t, void *)
Remove a callback from a list variable.
Definition: variables.c:887
static int var_SetInteger(vlc_object_t *p_obj, const char *psz_name, int64_t i)
Set the value of an integer variable.
Definition: vlc_variables.h:293
static int64_t var_IncInteger(vlc_object_t *p_obj, const char *psz_name)
Increment an integer variable.
Definition: vlc_variables.h:473
#define VLC_VAR_FLOAT
Definition: vlc_variables.h:52