vlc_objects.h 8.91 KB
Newer Older
1
/*****************************************************************************
2
 * vlc_objects.h: vlc_object_t definition and manipulation methods
3
 *****************************************************************************
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
4
 * Copyright (C) 2002-2008 VLC authors and VideoLAN
5 6 7
 *
 * Authors: Samuel Hocevar <sam@zoy.org>
 *
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
8 9 10
 * This program is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 of the License, or
11
 * (at your option) any later version.
12
 *
13 14
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
15 16
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
17
 *
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
18 19 20
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
21 22
 *****************************************************************************/

Clément Stenac's avatar
Clément Stenac committed
23
/**
24
 * \defgroup vlc_object VLC objects
25
 * \ingroup vlc
Clément Stenac's avatar
Clément Stenac committed
26
 * @{
27 28
 * \file
 * Common VLC object defintions
Clément Stenac's avatar
Clément Stenac committed
29 30
 */

31
struct vlc_logger;
32
struct vlc_object_internals;
33
struct vlc_object_marker;
34

35 36 37 38 39 40 41
/**
 * VLC object common members
 *
 * Common public properties for all VLC objects.
 * Object also have private properties maintained by the core, see
 * \ref vlc_object_internals_t
 */
42
struct vlc_object_t
43
{
44
    struct vlc_logger *logger;
45 46 47 48
    union {
        struct vlc_object_internals *priv;
        struct vlc_object_marker *obj;
    };
49

50
    bool no_interact;
51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70

    /** Module probe flag
     *
     * A boolean during module probing when the probe is "forced".
     * See \ref module_need().
     */
    bool force;
};

/**
 * Type-safe vlc_object_t cast
 *
 * This macro attempts to cast a pointer to a compound type to a
 * \ref vlc_object_t pointer in a type-safe manner.
 * It checks if the compound type actually starts with an embedded
 * \ref vlc_object_t structure.
 */
#if !defined(__cplusplus)
# define VLC_OBJECT(x) \
    _Generic((x)->obj, \
71 72
        struct vlc_object_marker *: (x), \
        default: (&((x)->obj)) \
73
    )
74
# define vlc_object_cast(t)
75
#else
76 77 78 79 80
static inline vlc_object_t *VLC_OBJECT(vlc_object_t *o)
{
    return o;
}

81 82 83 84 85 86
# define vlc_object_cast(t) \
struct t; \
static inline struct vlc_object_t *VLC_OBJECT(struct t *d) \
{ \
    return (struct vlc_object_t *)d; \
}
87 88
#endif

89 90 91 92 93
vlc_object_cast(libvlc_int_t)
vlc_object_cast(intf_thread_t)
vlc_object_cast(vlc_player_t)
vlc_object_cast(playlist_t)
vlc_object_cast(stream_t)
94 95
vlc_object_cast(stream_directory_t)
vlc_object_cast(stream_extractor_t)
96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112
vlc_object_cast(decoder_t)
vlc_object_cast(filter_t)
vlc_object_cast(audio_output)
vlc_object_cast(vout_thread_t)
vlc_object_cast(vout_display_t)
vlc_object_cast(vout_window_t)
vlc_object_cast(sout_instance_t)
vlc_object_cast(sout_stream_t)
vlc_object_cast(sout_access_out_t)
vlc_object_cast(extensions_manager_t)
vlc_object_cast(fingerprinter_thread_t)
vlc_object_cast(demux_meta_t)
vlc_object_cast(xml_t)
vlc_object_cast(services_discovery_t)
vlc_object_cast(vlc_renderer_discovery_t)
vlc_object_cast(vlc_medialibrary_module_t)

113 114 115
/* The root object */
struct libvlc_int_t
{
116
    struct vlc_object_t obj;
117 118
};

119 120 121 122 123 124 125
/**
 * Allocates and initializes a vlc object.
 *
 * @param i_size object byte size
 *
 * @return the new object, or NULL on error.
 */
126
VLC_API void *vlc_object_create( vlc_object_t *, size_t ) VLC_MALLOC VLC_USED;
127

128 129 130 131 132 133 134
/**
 * Drops the strong reference to an object.
 *
 * This removes the initial strong reference to a given object. This must be
 * called exactly once per allocated object after it is no longer needed,
 * matching vlc_object_create() or vlc_custom_create().
 */
135
VLC_API void vlc_object_delete(vlc_object_t *obj);
136 137
#define vlc_object_delete(obj) vlc_object_delete(VLC_OBJECT(obj))

138
VLC_API size_t vlc_list_children(vlc_object_t *, vlc_object_t **, size_t) VLC_USED;
139 140 141 142 143 144 145 146 147 148 149

/**
 * Returns the object type name.
 *
 * This returns a nul-terminated string identifying the object type.
 * The string is valid for at least as long as the object reference.
 *
 * \param obj object whose type name to get
 */
VLC_API const char *vlc_object_typename(const vlc_object_t *obj) VLC_USED;

150 151 152 153 154 155 156 157 158 159
/**
 * Gets the parent of an object.
 *
 * \return the parent object (NULL if none)
 *
 * \note The returned parent object pointer is valid as long as the child is.
 */
VLC_API vlc_object_t *vlc_object_parent(vlc_object_t *obj) VLC_USED;
#define vlc_object_parent(o) vlc_object_parent(VLC_OBJECT(o))

160 161
static inline struct vlc_logger *vlc_object_logger(vlc_object_t *obj)
{
162
    return obj->logger;
163 164 165
}
#define vlc_object_logger(o) vlc_object_logger(VLC_OBJECT(o))

166 167 168 169 170 171 172 173 174 175 176 177
/**
 * Tries to get the name of module bound to an object.
 *
 * \warning This function is intrinsically race-prone, as a module may be
 * bound or unbound asynchronously by another thread.
 * Do not trust the result for any purpose other than debugging/tracing.
 *
 * \return Normally, this returns a heap-allocated nul-terminated string
 * which is the name of the module. If no module are bound to the object, it
 * returns NULL. It also returns NULL on error.
 */
#define vlc_object_get_name(obj) var_GetString(obj, "module-name")
178

179
#define vlc_object_create(a,b) vlc_object_create( VLC_OBJECT(a), b )
180

181 182
#define vlc_object_find_name(a,b) \
    vlc_object_find_name( VLC_OBJECT(a),b)
183

184 185 186
VLC_USED
static inline libvlc_int_t *vlc_object_instance(vlc_object_t *obj)
{
187 188 189 190 191 192 193
    vlc_object_t *parent;

    do
        parent = obj;
    while ((obj = vlc_object_parent(obj)) != NULL);

    return (libvlc_int_t *)parent;
194 195 196
}
#define vlc_object_instance(o) vlc_object_instance(VLC_OBJECT(o))

197
/* Here for backward compatibility. TODO: Move to <vlc_vout.h>! */
198 199
VLC_API vout_thread_t *vout_Hold(vout_thread_t *vout);
VLC_API void vout_Release(vout_thread_t *vout);
200

201
/* Here for backward compatibility. TODO: Move to <vlc_aout.h>! */
202 203
VLC_API audio_output_t *aout_Hold(audio_output_t *aout);
VLC_API void aout_Release(audio_output_t *aout);
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 209 210 211 212 213 214 215 216
{
    const char *tn = vlc_object_typename(o);

    if (!strcmp(tn, "audio output"))
        aout_Hold((audio_output_t *)o);
    if (!strcmp(tn, "video output"))
        vout_Hold((vout_thread_t *)o);
    return o;
}

217
static inline void vlc_object_release(vlc_object_t *o)
218 219 220 221 222 223 224 225 226
{
    const char *tn = vlc_object_typename(o);

    if (!strcmp(tn, "audio output"))
        aout_Release((audio_output_t *)o);
    if (!strcmp(tn, "video output"))
        vout_Release((vout_thread_t *)o);
}

227 228 229 230 231 232 233 234 235
/**
 * @defgroup objres Object resources
 *
 * The object resource functions tie resource allocation to an instance of
 * a module through a VLC object.
 * Such resource will be automatically freed, in first in last out order,
 * when the module instance associated with the VLC object is terminated.
 *
 * Specifically, if the module instance activation/probe function fails, the
236 237
 * resource will be freed immediately after the failure. If the activation
 * succeeds, the resource will be freed when the module instance is terminated.
238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256
 *
 * This is a convenience mechanism to save explicit clean-up function calls
 * in modules.
 *
 * @{
 */

/**
 * Allocates memory for a module.
 *
 * This function allocates memory from the heap for a module instance.
 * The memory is uninitialized.
 *
 * @param obj VLC object to tie the memory allocation to
 * @param size byte size of the memory allocation
 *
 * @return a pointer to the allocated memory, or NULL on error (errno is set).
 */
VLC_API VLC_MALLOC void *vlc_obj_malloc(vlc_object_t *obj, size_t size);
257

258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298
/**
 * Allocates a zero-initialized table for a module.
 *
 * This function allocates a table from the heap for a module instance.
 * The memory is initialized to all zeroes.
 *
 * @param obj VLC object to tie the memory allocation to
 * @param nmemb number of table entries
 * @param size byte size of a table entry
 *
 * @return a pointer to the allocated memory, or NULL on error (errno is set).
 */
VLC_API VLC_MALLOC void *vlc_obj_calloc(vlc_object_t *obj, size_t nmemb,
                                        size_t size);

/**
 * Duplicates a string for a module.
 *
 * This function allocates a copy of a nul-terminated string for a module
 * instance.
 *
 * @param obj VLC object to tie the memory allocation to
 * @param str string to copy
 *
 * @return a pointer to the copy, or NULL on error (errno is set).
 */
VLC_API VLC_MALLOC char *vlc_obj_strdup(vlc_object_t *obj, const char *str);

/**
 * Manually frees module memory.
 *
 * This function manually frees a resource allocated with vlc_obj_malloc(),
 * vlc_obj_calloc() or vlc_obj_strdup() before the module instance is
 * terminated. This is seldom necessary.
 *
 * @param obj VLC object that the allocation was tied to
 * @param ptr pointer to the allocated resource
 */
VLC_API void vlc_obj_free(vlc_object_t *obj, void *ptr);

/** @} */
Rémi Denis-Courmont's avatar
Rémi Denis-Courmont committed
299
/** @} */