1/* GStreamer
2 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
3 * 2000 Wim Taymans <wtay@chello.be>
4 * 2005 Wim Taymans <wim@fluendo.com>
5 *
6 * gstobject.h: Header for base GstObject
7 *
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Library General Public
10 * License as published by the Free Software Foundation; either
11 * version 2 of the License, or (at your option) any later version.
12 *
13 * This library 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 GNU
16 * Library General Public License for more details.
17 *
18 * You should have received a copy of the GNU Library General Public
19 * License along with this library; if not, write to the
20 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
21 * Boston, MA 02110-1301, USA.
22 */
23
24#ifndef __GST_OBJECT_H__
25#define __GST_OBJECT_H__
26
27#include <gst/gstconfig.h>
28
29#include <glib-object.h>
30
31G_BEGIN_DECLS
32
33#define GST_TYPE_OBJECT (gst_object_get_type ())
34#define GST_IS_OBJECT(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_OBJECT))
35#define GST_IS_OBJECT_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_OBJECT))
36#define GST_OBJECT_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_OBJECT, GstObjectClass))
37#define GST_OBJECT(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_OBJECT, GstObject))
38#define GST_OBJECT_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_OBJECT, GstObjectClass))
39#define GST_OBJECT_CAST(obj) ((GstObject*)(obj))
40#define GST_OBJECT_CLASS_CAST(klass) ((GstObjectClass*)(klass))
41
42/**
43 * GST_OBJECT_FLAG_CONSTRUCTED:
44 *
45 * Flag that's set when the object has been constructed. This can be used by
46 * API such as base class setters to differentiate between the case where
47 * they're called from a subclass's instance init function (and where the
48 * object isn't fully constructed yet, and so one shouldn't do anything but
49 * set values in the instance structure), and the case where the object is
50 * constructed.
51 *
52 * Since: 1.24
53 */
54
55/**
56 * GstObjectFlags:
57 * @GST_OBJECT_FLAG_MAY_BE_LEAKED: the object is expected to stay alive even
58 * after gst_deinit() has been called and so should be ignored by leak
59 * detection tools. (Since: 1.10)
60 * @GST_OBJECT_FLAG_CONSTRUCTED: flag that's set when the object has been
61 * constructed. This can be used by API such as base class setters to
62 * differentiate between the case where they're called from a subclass's
63 * instance init function (and where the object isn't fully constructed yet,
64 * and so one shouldn't do anything but set values in the instance structure),
65 * and the case where the object is constructed. (Since: 1.24)
66 * @GST_OBJECT_FLAG_LAST: subclasses can add additional flags starting from this flag
67 *
68 * The standard flags that an gstobject may have.
69 */
70typedef enum
71{
72 GST_OBJECT_FLAG_MAY_BE_LEAKED = (1 << 0),
73 GST_OBJECT_FLAG_CONSTRUCTED = (1 << 1),
74 /* padding */
75 GST_OBJECT_FLAG_LAST = (1<<4)
76} GstObjectFlags;
77
78/**
79 * GST_OBJECT_REFCOUNT:
80 * @obj: a #GstObject
81 *
82 * Get access to the reference count field of the object.
83 */
84#define GST_OBJECT_REFCOUNT(obj) (((GObject*)(obj))->ref_count)
85/**
86 * GST_OBJECT_REFCOUNT_VALUE:
87 * @obj: a #GstObject
88 *
89 * Get the reference count value of the object.
90 */
91#define GST_OBJECT_REFCOUNT_VALUE(obj) g_atomic_int_get ((gint *) &GST_OBJECT_REFCOUNT(obj))
92
93/* we do a GST_OBJECT_CAST to avoid type checking, better call these
94 * function with a valid object! */
95
96/**
97 * GST_OBJECT_GET_LOCK:
98 * @obj: a #GstObject
99 *
100 * Acquire a reference to the mutex of this object.
101 */
102#define GST_OBJECT_GET_LOCK(obj) (&GST_OBJECT_CAST(obj)->lock)
103/**
104 * GST_OBJECT_LOCK:
105 * @obj: a #GstObject to lock
106 *
107 * This macro will obtain a lock on the object, making serialization possible.
108 * It blocks until the lock can be obtained.
109 */
110#define GST_OBJECT_LOCK(obj) g_mutex_lock(GST_OBJECT_GET_LOCK(obj))
111
112/**
113 * GST_OBJECT_AUTO_LOCK:
114 * @obj: a #GstObject to lock
115 * @var: a variable name to be declared
116 *
117 * Declare a #GMutexLocker variable with g_autoptr() and lock the object. The
118 * mutex will be unlocked automatically when leaving the scope.
119 *
120 * ``` c
121 * {
122 * GST_OBJECT_AUTO_LOCK (obj, locker);
123 *
124 * obj->stuff_with_lock();
125 * if (cond) {
126 * // No need to unlock
127 * return;
128 * }
129 *
130 * // Unlock before end of scope
131 * g_clear_pointer (&locker, g_mutex_locker_free);
132 * obj->stuff_without_lock();
133 * }
134 * ```
135 * Since: 1.24.0
136 */
137#define GST_OBJECT_AUTO_LOCK(obj, var) g_autoptr(GMutexLocker) G_GNUC_UNUSED var = g_mutex_locker_new(GST_OBJECT_GET_LOCK(obj))
138
139/**
140 * GST_OBJECT_TRYLOCK:
141 * @obj: a #GstObject.
142 *
143 * This macro will try to obtain a lock on the object, but will return with
144 * %FALSE if it can't get it immediately.
145 */
146#define GST_OBJECT_TRYLOCK(obj) g_mutex_trylock(GST_OBJECT_GET_LOCK(obj))
147/**
148 * GST_OBJECT_UNLOCK:
149 * @obj: a #GstObject to unlock.
150 *
151 * This macro releases a lock on the object.
152 */
153#define GST_OBJECT_UNLOCK(obj) g_mutex_unlock(GST_OBJECT_GET_LOCK(obj))
154
155
156/**
157 * GST_OBJECT_NAME:
158 * @obj: a #GstObject
159 *
160 * Get the name of this object. This is not thread-safe by default
161 * (i.e. you will have to make sure the object lock is taken yourself).
162 * If in doubt use gst_object_get_name() instead.
163 */
164#define GST_OBJECT_NAME(obj) (GST_OBJECT_CAST(obj)->name)
165/**
166 * GST_OBJECT_PARENT:
167 * @obj: a #GstObject
168 *
169 * Get the parent of this object. This is not thread-safe by default
170 * (i.e. you will have to make sure the object lock is taken yourself).
171 * If in doubt use gst_object_get_parent() instead.
172 */
173#define GST_OBJECT_PARENT(obj) (GST_OBJECT_CAST(obj)->parent)
174
175
176/**
177 * GST_OBJECT_FLAGS:
178 * @obj: a #GstObject
179 *
180 * This macro returns the entire set of flags for the object.
181 */
182#define GST_OBJECT_FLAGS(obj) (GST_OBJECT_CAST (obj)->flags)
183/**
184 * GST_OBJECT_FLAG_IS_SET:
185 * @obj: a #GstObject
186 * @flag: Flag to check for
187 *
188 * This macro checks to see if the given flag is set.
189 */
190#define GST_OBJECT_FLAG_IS_SET(obj,flag) ((GST_OBJECT_FLAGS (obj) & (flag)) == (flag))
191/**
192 * GST_OBJECT_FLAG_SET:
193 * @obj: a #GstObject
194 * @flag: Flag to set
195 *
196 * This macro sets the given bits.
197 */
198#define GST_OBJECT_FLAG_SET(obj,flag) (GST_OBJECT_FLAGS (obj) |= (flag))
199/**
200 * GST_OBJECT_FLAG_UNSET:
201 * @obj: a #GstObject
202 * @flag: Flag to set
203 *
204 * This macro unsets the given bits.
205 */
206#define GST_OBJECT_FLAG_UNSET(obj,flag) (GST_OBJECT_FLAGS (obj) &= ~(flag))
207
208typedef struct _GstObject GstObject;
209typedef struct _GstObjectClass GstObjectClass;
210
211/**
212 * GstObject:
213 * @lock: object LOCK
214 * @name: The name of the object
215 * @parent: this object's parent, weak ref
216 * @flags: flags for this object
217 *
218 * GStreamer base object class.
219 */
220struct _GstObject {
221 GInitiallyUnowned object;
222
223 /*< public >*/ /* with LOCK */
224 GMutex lock; /* object LOCK */
225 gchar *name; /* object name */
226 GstObject *parent; /* this object's parent, weak ref */
227 guint32 flags;
228
229 /*< private >*/
230 GList *control_bindings; /* List of GstControlBinding */
231 guint64 control_rate;
232 guint64 last_sync;
233
234 gpointer _gst_reserved;
235};
236
237/**
238 * GstObjectClass:
239 * @parent_class: parent
240 * @path_string_separator: separator used by gst_object_get_path_string()
241 * @deep_notify: default signal handler
242 *
243 * GStreamer base object class.
244 */
245struct _GstObjectClass {
246 GInitiallyUnownedClass parent_class;
247
248 const gchar *path_string_separator;
249
250 /* signals */
251 void (*deep_notify) (GstObject * object, GstObject * orig, GParamSpec * pspec);
252
253 /*< public >*/
254 /* virtual methods for subclasses */
255
256 /*< private >*/
257 gpointer _gst_reserved[GST_PADDING];
258};
259
260/* normal GObject stuff */
261
262GST_API
263GType gst_object_get_type (void);
264
265/* name routines */
266
267GST_API
268gboolean gst_object_set_name (GstObject *object, const gchar *name);
269
270GST_API
271gchar* gst_object_get_name (GstObject *object);
272
273/* parentage routines */
274
275GST_API
276gboolean gst_object_set_parent (GstObject *object, GstObject *parent);
277
278GST_API
279GstObject* gst_object_get_parent (GstObject *object);
280
281GST_API
282void gst_object_unparent (GstObject *object);
283
284GST_API
285gboolean gst_object_has_as_parent (GstObject *object, GstObject *parent);
286
287GST_API
288gboolean gst_object_has_as_ancestor (GstObject *object, GstObject *ancestor);
289
290GST_DEPRECATED_FOR(gst_object_has_as_ancestor)
291gboolean gst_object_has_ancestor (GstObject *object, GstObject *ancestor);
292
293GST_API
294void gst_object_default_deep_notify (GObject *object, GstObject *orig,
295 GParamSpec *pspec, gchar **excluded_props);
296
297/* refcounting + life cycle */
298
299GST_API
300gpointer gst_object_ref (gpointer object);
301
302GST_API
303void gst_object_unref (gpointer object);
304
305GST_API
306void gst_clear_object (GstObject **object_ptr);
307#define gst_clear_object(object_ptr) g_clear_pointer ((object_ptr), gst_object_unref)
308
309GST_API
310gpointer gst_object_ref_sink (gpointer object);
311
312/* replace object pointer */
313
314GST_API
315gboolean gst_object_replace (GstObject **oldobj, GstObject *newobj);
316
317/* printing out the 'path' of the object */
318
319GST_API
320gchar * gst_object_get_path_string (GstObject *object);
321
322/* misc utils */
323
324GST_API
325gboolean gst_object_check_uniqueness (GList *list, const gchar *name);
326
327/* controller functions */
328#include <gst/gstcontrolbinding.h>
329#include <gst/gstcontrolsource.h>
330
331GST_API
332GstClockTime gst_object_suggest_next_sync (GstObject * object);
333
334GST_API
335gboolean gst_object_sync_values (GstObject * object, GstClockTime timestamp);
336
337GST_API
338gboolean gst_object_has_active_control_bindings (GstObject *object);
339
340GST_API
341void gst_object_set_control_bindings_disabled (GstObject *object, gboolean disabled);
342
343GST_API
344void gst_object_set_control_binding_disabled (GstObject *object,
345 const gchar * property_name,
346 gboolean disabled);
347
348GST_API
349gboolean gst_object_add_control_binding (GstObject * object, GstControlBinding * binding);
350
351GST_API
352GstControlBinding *
353 gst_object_get_control_binding (GstObject *object, const gchar * property_name);
354
355GST_API
356gboolean gst_object_remove_control_binding (GstObject * object, GstControlBinding * binding);
357
358GST_API
359GValue * gst_object_get_value (GstObject * object, const gchar * property_name,
360 GstClockTime timestamp);
361GST_API
362gboolean gst_object_get_value_array (GstObject * object, const gchar * property_name,
363 GstClockTime timestamp, GstClockTime interval,
364 guint n_values, gpointer values);
365GST_API
366gboolean gst_object_get_g_value_array (GstObject * object, const gchar * property_name,
367 GstClockTime timestamp, GstClockTime interval,
368 guint n_values, GValue *values);
369GST_API
370GstClockTime gst_object_get_control_rate (GstObject * object);
371
372GST_API
373void gst_object_set_control_rate (GstObject * object, GstClockTime control_rate);
374
375G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstObject, gst_object_unref)
376
377G_END_DECLS
378
379#endif /* __GST_OBJECT_H__ */
380
381

source code of include/gstreamer-1.0/gst/gstobject.h