VLC  4.0.0-dev
vlc_objects.h
Go to the documentation of this file.
1 /*****************************************************************************
2  * vlc_objects.h: vlc_object_t definition and manipulation methods
3  *****************************************************************************
4  * Copyright (C) 2002-2008 VLC authors and VideoLAN
5  *
6  * Authors: Samuel Hocevar <sam@zoy.org>
7  *
8  * This program is free software; you can redistribute it and/or modify it
9  * under the terms of the GNU Lesser General Public License as published by
10  * the Free Software Foundation; either version 2.1 of the License, or
11  * (at your option) any later version.
12  *
13  * This program is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16  * GNU Lesser General Public License for more details.
17  *
18  * You should have received a copy of the GNU Lesser General Public License
19  * along with this program; if not, write to the Free Software Foundation,
20  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
21  *****************************************************************************/
22 
23 /**
24  * \defgroup vlc_object VLC objects
25  * \ingroup vlc
26  * @{
27  * \file
28  * Common VLC object defintions
29  */
30 
31 struct vlc_logger;
33 struct vlc_object_marker;
34 
35 /**
36  * VLC object common members
37  *
38  * Common public properties for all VLC objects.
39  * Object also have private properties maintained by the core, see
40  * \ref vlc_object_internals_t
41  */
42 struct vlc_object_t
43 {
44  struct vlc_logger *logger;
45  union {
46  struct vlc_object_internals *priv;
47  struct vlc_object_marker *obj;
48  };
49 
50  bool no_interact;
51 
52  /** Module probe flag
53  *
54  * A boolean during module probing when the probe is "forced".
55  * See \ref module_need().
56  */
57  bool force;
58 };
59 
60 /**
61  * Type-safe vlc_object_t cast
62  *
63  * This macro attempts to cast a pointer to a compound type to a
64  * \ref vlc_object_t pointer in a type-safe manner.
65  * It checks if the compound type actually starts with an embedded
66  * \ref vlc_object_t structure.
67  */
68 #if !defined(__cplusplus)
69 # define VLC_OBJECT(x) \
70  _Generic((x)->obj, \
71  struct vlc_object_marker *: (x), \
72  default: (&((x)->obj)) \
73  )
74 # define vlc_object_cast(t)
75 #else
76 static inline vlc_object_t *VLC_OBJECT(vlc_object_t *o)
77 {
78  return o;
79 }
80 
81 # define vlc_object_cast(t) \
82 struct t; \
83 static inline struct vlc_object_t *VLC_OBJECT(struct t *d) \
84 { \
85  return (struct vlc_object_t *)d; \
86 }
87 #endif
88 
112 
113 /* The root object */
114 struct libvlc_int_t
115 {
116  struct vlc_object_t obj;
117 };
118 
119 /**
120  * Allocates and initializes a vlc object.
121  *
122  * @param i_size object byte size
123  *
124  * @return the new object, or NULL on error.
125  */
127 
128 /**
129  * Drops the strong reference to an object.
130  *
131  * This removes the initial strong reference to a given object. This must be
132  * called exactly once per allocated object after it is no longer needed,
133  * matching vlc_object_create() or vlc_custom_create().
134  */
136 #define vlc_object_delete(obj) vlc_object_delete(VLC_OBJECT(obj))
139 
140 /**
141  * Returns the object type name.
142  *
143  * This returns a nul-terminated string identifying the object type.
144  * The string is valid for at least as long as the object reference.
145  *
146  * \param obj object whose type name to get
147  */
148 VLC_API const char *vlc_object_typename(const vlc_object_t *obj) VLC_USED;
149 
150 /**
151  * Gets the parent of an object.
152  *
153  * \return the parent object (NULL if none)
154  *
155  * \note The returned parent object pointer is valid as long as the child is.
156  */
158 #define vlc_object_parent(o) vlc_object_parent(VLC_OBJECT(o))
160 static inline struct vlc_logger *vlc_object_logger(vlc_object_t *obj)
161 {
162  return obj->logger;
163 }
164 #define vlc_object_logger(o) vlc_object_logger(VLC_OBJECT(o))
166 /**
167  * Tries to get the name of module bound to an object.
168  *
169  * \warning This function is intrinsically race-prone, as a module may be
170  * bound or unbound asynchronously by another thread.
171  * Do not trust the result for any purpose other than debugging/tracing.
172  *
173  * \return Normally, this returns a heap-allocated nul-terminated string
174  * which is the name of the module. If no module are bound to the object, it
175  * returns NULL. It also returns NULL on error.
176  */
177 #define vlc_object_get_name(obj) var_GetString(obj, "module-name")
179 #define vlc_object_create(a,b) vlc_object_create( VLC_OBJECT(a), b )
181 #define vlc_object_find_name(a,b) \
182  vlc_object_find_name( VLC_OBJECT(a),b)
183 
184 VLC_USED
185 static inline libvlc_int_t *vlc_object_instance(vlc_object_t *obj)
186 {
187  vlc_object_t *parent;
188 
189  do
190  parent = obj;
191  while ((obj = vlc_object_parent(obj)) != NULL);
192 
193  return (libvlc_int_t *)parent;
194 }
195 #define vlc_object_instance(o) vlc_object_instance(VLC_OBJECT(o))
197 /* Here for backward compatibility. TODO: Move to <vlc_vout.h>! */
200 
201 /* Here for backward compatibility. TODO: Move to <vlc_aout.h>! */
204 
205 /* TODO: remove vlc_object_hold/_release() for GUIs, remove this */
206 VLC_DEPRECATED static inline void *vlc_object_hold(vlc_object_t *o)
207 {
208  const char *tn = vlc_object_typename(o);
209 
210  if (!strcmp(tn, "audio output"))
212  if (!strcmp(tn, "video output"))
213  vout_Hold((vout_thread_t *)o);
214  return o;
215 }
216 
217 static inline void vlc_object_release(vlc_object_t *o)
218 {
219  const char *tn = vlc_object_typename(o);
220 
221  if (!strcmp(tn, "audio output"))
223  if (!strcmp(tn, "video output"))
225 }
226 
227 /**
228  * @defgroup objres Object resources
229  *
230  * The object resource functions tie resource allocation to an instance of
231  * a module through a VLC object.
232  * Such resource will be automatically freed, in first in last out order,
233  * when the module instance associated with the VLC object is terminated.
234  *
235  * Specifically, if the module instance activation/probe function fails, the
236  * resource will be freed immediately after the failure. If the activation
237  * succeeds, the resource will be freed when the module instance is terminated.
238  *
239  * This is a convenience mechanism to save explicit clean-up function calls
240  * in modules.
241  *
242  * @{
243  */
244 
245 /**
246  * Allocates memory for a module.
247  *
248  * This function allocates memory from the heap for a module instance.
249  * The memory is uninitialized.
250  *
251  * @param obj VLC object to tie the memory allocation to
252  * @param size byte size of the memory allocation
253  *
254  * @return a pointer to the allocated memory, or NULL on error (errno is set).
255  */
256 VLC_API VLC_MALLOC void *vlc_obj_malloc(vlc_object_t *obj, size_t size);
257 
258 /**
259  * Allocates a zero-initialized table for a module.
260  *
261  * This function allocates a table from the heap for a module instance.
262  * The memory is initialized to all zeroes.
263  *
264  * @param obj VLC object to tie the memory allocation to
265  * @param nmemb number of table entries
266  * @param size byte size of a table entry
267  *
268  * @return a pointer to the allocated memory, or NULL on error (errno is set).
269  */
270 VLC_API VLC_MALLOC void *vlc_obj_calloc(vlc_object_t *obj, size_t nmemb,
271  size_t size);
272 
273 /**
274  * Duplicates a string for a module.
275  *
276  * This function allocates a copy of a nul-terminated string for a module
277  * instance.
278  *
279  * @param obj VLC object to tie the memory allocation to
280  * @param str string to copy
281  *
282  * @return a pointer to the copy, or NULL on error (errno is set).
283  */
284 VLC_API VLC_MALLOC char *vlc_obj_strdup(vlc_object_t *obj, const char *str);
285 
286 /**
287  * Manually frees module memory.
288  *
289  * This function manually frees a resource allocated with vlc_obj_malloc(),
290  * vlc_obj_calloc() or vlc_obj_strdup() before the module instance is
291  * terminated. This is seldom necessary.
292  *
293  * @param obj VLC object that the allocation was tied to
294  * @param ptr pointer to the allocated resource
295  */
296 VLC_API void vlc_obj_free(vlc_object_t *obj, void *ptr);
297 
298 /** @} */
299 /** @} */
#define vlc_object_logger(o)
Definition: vlc_objects.h:165
static void vlc_object_release(vlc_object_t *o)
Definition: vlc_objects.h:218
bool no_interact
Definition: vlc_objects.h:51
Definition: player.h:208
#define vlc_object_cast(t)
Definition: vlc_objects.h:75
void aout_Release(audio_output_t *aout)
Definition: output.c:380
static void * vlc_object_hold(vlc_object_t *o)
Definition: vlc_objects.h:207
#define VLC_DEPRECATED
Deprecated functions or compound members annotation.
Definition: vlc_common.h:119
void vout_Release(vout_thread_t *vout)
Definition: video_output.c:1820
Definition: vlc_objects.h:115
Main service discovery structure to build a SD module.
Definition: vlc_services_discovery.h:59
size_t vlc_list_children(vlc_object_t *, vlc_object_t **, size_t)
void * vlc_obj_malloc(vlc_object_t *obj, size_t size)
Allocates memory for a module.
Definition: objres.c:137
Definition: variables.h:35
struct vlc_object_internals * priv
Definition: vlc_objects.h:47
#define VLC_MALLOC
Heap allocated result function annotation.
Definition: vlc_common.h:167
Stream output access_output.
Definition: vlc_sout.h:69
const char * vlc_object_typename(const vlc_object_t *obj)
Returns the object type name.
Definition: objects.c:110
struct vlc_object_marker * obj
Definition: vlc_objects.h:48
audio_output_t * aout_Hold(audio_output_t *aout)
Definition: output.c:347
Video output thread descriptor.
Definition: vlc_vout.h:60
Definition: vlc_stream_extractor.h:51
struct playlist_t playlist_t
Definition: vlc_common.h:344
#define vlc_object_create(a, b)
Definition: vlc_objects.h:180
Describe all interface-specific data of the interface thread.
Definition: vlc_interface.h:48
Definition: vlc_fingerprinter.h:70
Definition: vlc_demux.h:55
Definition: vlc_media_library.h:741
vout_thread_t * vout_Hold(vout_thread_t *vout)
Definition: video_output.c:1959
Definition: messages.c:54
char * vlc_obj_strdup(vlc_object_t *obj, const char *str)
Duplicates a string for a module.
Definition: objres.c:168
Definition: vlc_sout.h:200
#define VLC_API
Definition: fourcc_gen.c:31
#define VLC_OBJECT(x)
Type-safe vlc_object_t cast.
Definition: vlc_objects.h:70
Audio output object.
Definition: vlc_aout.h:140
stream_t definition
Definition: vlc_stream.h:46
Definition: vlc_codec.h:103
Structure describing a filter.
Definition: vlc_filter.h:72
Definition: vlc_renderer_discovery.h:165
#define vlc_object_instance(o)
Definition: vlc_objects.h:196
#define vlc_object_delete(obj)
Definition: vlc_objects.h:137
Definition: vlc_xml.h:37
Stream output instance (FIXME: should be private to src/ to avoid invalid unsynchronized access) ...
Definition: vlc_sout.h:48
bool force
Module probe flag.
Definition: vlc_objects.h:58
struct vlc_logger * logger
Definition: vlc_objects.h:45
Window object.
Definition: vlc_vout_window.h:336
Extensions manager object.
Definition: vlc_extensions.h:53
VLC object common members.
Definition: vlc_objects.h:43
void vlc_obj_free(vlc_object_t *obj, void *ptr)
Manually frees module memory.
Definition: objres.c:173
void * vlc_obj_calloc(vlc_object_t *obj, size_t nmemb, size_t size)
Allocates a zero-initialized table for a module.
Definition: objres.c:145
Definition: vlc_vout_display.h:272
Definition: vlc_stream_extractor.h:74
#define vlc_object_parent(o)
Definition: vlc_objects.h:159
#define VLC_USED
Definition: fourcc_gen.c:32