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 
111 
112 /* The root object */
113 struct libvlc_int_t
114 {
115  struct vlc_object_t obj;
116 };
117 
118 /**
119  * Allocates and initializes a vlc object.
120  *
121  * @param i_size object byte size
122  *
123  * @return the new object, or NULL on error.
124  */
126 
127 /**
128  * Drops the strong reference to an object.
129  *
130  * This removes the initial strong reference to a given object. This must be
131  * called exactly once per allocated object after it is no longer needed,
132  * matching vlc_object_create() or vlc_custom_create().
133  */
135 #define vlc_object_delete(obj) vlc_object_delete(VLC_OBJECT(obj))
136 
138 
139 /**
140  * Returns the object type name.
141  *
142  * This returns a nul-terminated string identifying the object type.
143  * The string is valid for at least as long as the object reference.
144  *
145  * \param obj object whose type name to get
146  */
148 
149 /**
150  * Gets the parent of an object.
151  *
152  * \return the parent object (NULL if none)
153  *
154  * \note The returned parent object pointer is valid as long as the child is.
155  */
157 #define vlc_object_parent(o) vlc_object_parent(VLC_OBJECT(o))
158 
159 static inline struct vlc_logger *vlc_object_logger(vlc_object_t *obj)
160 {
161  return obj->logger;
162 }
163 #define vlc_object_logger(o) vlc_object_logger(VLC_OBJECT(o))
164 
165 /**
166  * Tries to get the name of module bound to an object.
167  *
168  * \warning This function is intrinsically race-prone, as a module may be
169  * bound or unbound asynchronously by another thread.
170  * Do not trust the result for any purpose other than debugging/tracing.
171  *
172  * \return Normally, this returns a heap-allocated nul-terminated string
173  * which is the name of the module. If no module are bound to the object, it
174  * returns NULL. It also returns NULL on error.
175  */
176 #define vlc_object_get_name(obj) var_GetString(obj, "module-name")
177 
178 #define vlc_object_create(a,b) vlc_object_create( VLC_OBJECT(a), b )
179 
180 #define vlc_object_find_name(a,b) \
181  vlc_object_find_name( VLC_OBJECT(a),b)
182 
183 VLC_USED
184 static inline libvlc_int_t *vlc_object_instance(vlc_object_t *obj)
185 {
186  vlc_object_t *parent;
187 
188  do
189  parent = obj;
190  while ((obj = vlc_object_parent(obj)) != NULL);
191 
192  return (libvlc_int_t *)parent;
193 }
194 #define vlc_object_instance(o) vlc_object_instance(VLC_OBJECT(o))
195 
196 /* Here for backward compatibility. TODO: Move to <vlc_vout.h>! */
199 
200 /* Here for backward compatibility. TODO: Move to <vlc_aout.h>! */
203 
204 /* TODO: remove vlc_object_hold/_release() for GUIs, remove this */
205 VLC_DEPRECATED static inline void *vlc_object_hold(vlc_object_t *o)
206 {
207  const char *tn = vlc_object_typename(o);
208 
209  if (!strcmp(tn, "audio output"))
211  if (!strcmp(tn, "video output"))
212  vout_Hold((vout_thread_t *)o);
213  return o;
214 }
215 
216 static inline void vlc_object_release(vlc_object_t *o)
217 {
218  const char *tn = vlc_object_typename(o);
219 
220  if (!strcmp(tn, "audio output"))
222  if (!strcmp(tn, "video output"))
224 }
225 
226 /**
227  * @defgroup objres Object resources
228  *
229  * The object resource functions tie resource allocation to an instance of
230  * a module through a VLC object.
231  * Such resource will be automatically freed, in first in last out order,
232  * when the module instance associated with the VLC object is terminated.
233  *
234  * Specifically, if the module instance activation/probe function fails, the
235  * resource will be freed immediately after the failure. If the activation
236  * succeeds, the resource will be freed when the module instance is terminated.
237  *
238  * This is a convenience mechanism to save explicit clean-up function calls
239  * in modules.
240  *
241  * @{
242  */
243 
244 /**
245  * Allocates memory for a module.
246  *
247  * This function allocates memory from the heap for a module instance.
248  * The memory is uninitialized.
249  *
250  * @param obj VLC object to tie the memory allocation to
251  * @param size byte size of the memory allocation
252  *
253  * @return a pointer to the allocated memory, or NULL on error (errno is set).
254  */
255 VLC_API VLC_MALLOC void *vlc_obj_malloc(vlc_object_t *obj, size_t size);
256 
257 /**
258  * Allocates a zero-initialized table for a module.
259  *
260  * This function allocates a table from the heap for a module instance.
261  * The memory is initialized to all zeroes.
262  *
263  * @param obj VLC object to tie the memory allocation to
264  * @param nmemb number of table entries
265  * @param size byte size of a table entry
266  *
267  * @return a pointer to the allocated memory, or NULL on error (errno is set).
268  */
269 VLC_API VLC_MALLOC void *vlc_obj_calloc(vlc_object_t *obj, size_t nmemb,
270  size_t size);
271 
272 /**
273  * Duplicates a string for a module.
274  *
275  * This function allocates a copy of a nul-terminated string for a module
276  * instance.
277  *
278  * @param obj VLC object to tie the memory allocation to
279  * @param str string to copy
280  *
281  * @return a pointer to the copy, or NULL on error (errno is set).
282  */
283 VLC_API VLC_MALLOC char *vlc_obj_strdup(vlc_object_t *obj, const char *str);
284 
285 /**
286  * Manually frees module memory.
287  *
288  * This function manually frees a resource allocated with vlc_obj_malloc(),
289  * vlc_obj_calloc() or vlc_obj_strdup() before the module instance is
290  * terminated. This is seldom necessary.
291  *
292  * @param obj VLC object that the allocation was tied to
293  * @param ptr pointer to the allocated resource
294  */
295 VLC_API void vlc_obj_free(vlc_object_t *obj, void *ptr);
296 
297 /** @} */
298 /** @} */
vlc_player_t
Definition: player.h:227
vlc_object_cast
#define vlc_object_cast(t)
Definition: vlc_objects.h:75
VLC_API
#define VLC_API
Definition: fourcc_gen.c:31
vlc_obj_strdup
VLC_EXPORT char * vlc_obj_strdup(vlc_object_t *obj, const char *str)
Duplicates a string for a module.
Definition: objres.c:168
vlc_object_release
static void vlc_object_release(vlc_object_t *o)
Definition: vlc_objects.h:217
vlc_object_t::obj
struct vlc_object_marker * obj
Definition: vlc_objects.h:48
services_discovery_t
Main service discovery structure to build a SD module.
Definition: vlc_services_discovery.h:59
vout_window_t
Window object.
Definition: vlc_vout_window.h:358
vlc_list_children
VLC_EXPORT size_t vlc_list_children(vlc_object_t *, vlc_object_t **, size_t)
libvlc_int_t
Definition: vlc_objects.h:114
vlc_common.h
fingerprinter_thread_t
Definition: vlc_fingerprinter.h:70
vlc_logger
Definition: messages.c:54
vlc_object_t::priv
struct vlc_object_internals * priv
Definition: vlc_objects.h:47
sout_stream_t
Definition: vlc_sout.h:184
vlc_object_t::logger
struct vlc_logger * logger
Definition: vlc_objects.h:45
vlc_obj_malloc
VLC_EXPORT void * vlc_obj_malloc(vlc_object_t *obj, size_t size)
Allocates memory for a module.
Definition: objres.c:137
VLC_MALLOC
#define VLC_MALLOC
Heap allocated result function annotation.
Definition: vlc_common.h:167
vout_Release
VLC_EXPORT void vout_Release(vout_thread_t *vout)
Definition: video_output.c:1915
decoder_t
Definition: vlc_codec.h:101
sout_access_out_t
Stream output access_output.
Definition: vlc_sout.h:53
vlc_object_create
#define vlc_object_create(a, b)
Definition: vlc_objects.h:179
aout_Release
VLC_EXPORT void aout_Release(audio_output_t *aout)
Definition: output.c:404
audio_output
Audio output object.
Definition: vlc_aout.h:148
filter_t
Structure describing a filter.
Definition: vlc_filter.h:215
extensions_manager_t
Extensions manager object.
Definition: vlc_extensions.h:53
VLC_DEPRECATED
#define VLC_DEPRECATED
Deprecated functions or compound members annotation.
Definition: vlc_common.h:119
vout_Hold
VLC_EXPORT vout_thread_t * vout_Hold(vout_thread_t *vout)
Definition: video_output.c:2056
stream_t
stream_t definition
Definition: vlc_stream.h:46
xml_t
Definition: vlc_xml.h:37
stream_extractor_t
Definition: vlc_stream_extractor.h:51
aout_Hold
VLC_EXPORT audio_output_t * aout_Hold(audio_output_t *aout)
Definition: output.c:369
vlc_object_t::no_interact
bool no_interact
Definition: vlc_objects.h:51
vlc_object_t
VLC object common members.
Definition: vlc_objects.h:43
VLC_USED
#define VLC_USED
Definition: fourcc_gen.c:32
vlc_object_t::force
bool force
Module probe flag.
Definition: vlc_objects.h:58
vlc_obj_free
VLC_EXPORT void vlc_obj_free(vlc_object_t *obj, void *ptr)
Manually frees module memory.
Definition: objres.c:173
vlc_object_parent
#define vlc_object_parent(o)
Definition: vlc_objects.h:158
libvlc_int_t::obj
struct vlc_object_t obj
Definition: vlc_objects.h:116
vlc_object_typename
const VLC_EXPORT char * vlc_object_typename(const vlc_object_t *obj)
Returns the object type name.
Definition: objects.c:109
vlc_obj_calloc
VLC_EXPORT 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
vlc_object_delete
#define vlc_object_delete(obj)
Definition: vlc_objects.h:136
demux_meta_t
Definition: vlc_demux.h:58
VLC_OBJECT
#define VLC_OBJECT(x)
Type-safe vlc_object_t cast.
Definition: vlc_objects.h:70
vout_thread_t
Video output thread descriptor.
Definition: vlc_vout.h:55
stream_directory_t
Definition: vlc_stream_extractor.h:74
vout_display_t
Definition: vlc_vout_display.h:316
vlc_object_logger
#define vlc_object_logger(o)
Definition: vlc_objects.h:164
sout_instance_t
Stream output instance.
Definition: stream_output.h:33
vlc_object_hold
static void * vlc_object_hold(vlc_object_t *o)
Definition: vlc_objects.h:206
vlc_object_instance
#define vlc_object_instance(o)
Definition: vlc_objects.h:195
vlc_renderer_discovery_t
Definition: vlc_renderer_discovery.h:165
vlc_medialibrary_module_t
Definition: vlc_media_library.h:813
intf_thread_t
Describe all interface-specific data of the interface thread.
Definition: vlc_interface.h:48
vlc_object_internals
Definition: variables.h:35