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 | |
31 | G_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 | * GstObjectFlags: |
44 | * @GST_OBJECT_FLAG_MAY_BE_LEAKED: the object is expected to stay alive even |
45 | * after gst_deinit() has been called and so should be ignored by leak |
46 | * detection tools. (Since: 1.10) |
47 | * @GST_OBJECT_FLAG_LAST: subclasses can add additional flags starting from this flag |
48 | * |
49 | * The standard flags that an gstobject may have. |
50 | */ |
51 | typedef enum |
52 | { |
53 | GST_OBJECT_FLAG_MAY_BE_LEAKED = (1 << 0), |
54 | /* padding */ |
55 | GST_OBJECT_FLAG_LAST = (1<<4) |
56 | } GstObjectFlags; |
57 | |
58 | /** |
59 | * GST_OBJECT_REFCOUNT: |
60 | * @obj: a #GstObject |
61 | * |
62 | * Get access to the reference count field of the object. |
63 | */ |
64 | #define GST_OBJECT_REFCOUNT(obj) (((GObject*)(obj))->ref_count) |
65 | /** |
66 | * GST_OBJECT_REFCOUNT_VALUE: |
67 | * @obj: a #GstObject |
68 | * |
69 | * Get the reference count value of the object. |
70 | */ |
71 | #define GST_OBJECT_REFCOUNT_VALUE(obj) g_atomic_int_get ((gint *) &GST_OBJECT_REFCOUNT(obj)) |
72 | |
73 | /* we do a GST_OBJECT_CAST to avoid type checking, better call these |
74 | * function with a valid object! */ |
75 | |
76 | /** |
77 | * GST_OBJECT_GET_LOCK: |
78 | * @obj: a #GstObject |
79 | * |
80 | * Acquire a reference to the mutex of this object. |
81 | */ |
82 | #define GST_OBJECT_GET_LOCK(obj) (&GST_OBJECT_CAST(obj)->lock) |
83 | /** |
84 | * GST_OBJECT_LOCK: |
85 | * @obj: a #GstObject to lock |
86 | * |
87 | * This macro will obtain a lock on the object, making serialization possible. |
88 | * It blocks until the lock can be obtained. |
89 | */ |
90 | #define GST_OBJECT_LOCK(obj) g_mutex_lock(GST_OBJECT_GET_LOCK(obj)) |
91 | /** |
92 | * GST_OBJECT_TRYLOCK: |
93 | * @obj: a #GstObject. |
94 | * |
95 | * This macro will try to obtain a lock on the object, but will return with |
96 | * %FALSE if it can't get it immediately. |
97 | */ |
98 | #define GST_OBJECT_TRYLOCK(obj) g_mutex_trylock(GST_OBJECT_GET_LOCK(obj)) |
99 | /** |
100 | * GST_OBJECT_UNLOCK: |
101 | * @obj: a #GstObject to unlock. |
102 | * |
103 | * This macro releases a lock on the object. |
104 | */ |
105 | #define GST_OBJECT_UNLOCK(obj) g_mutex_unlock(GST_OBJECT_GET_LOCK(obj)) |
106 | |
107 | |
108 | /** |
109 | * GST_OBJECT_NAME: |
110 | * @obj: a #GstObject |
111 | * |
112 | * Get the name of this object. This is not thread-safe by default |
113 | * (i.e. you will have to make sure the object lock is taken yourself). |
114 | * If in doubt use gst_object_get_name() instead. |
115 | */ |
116 | #define GST_OBJECT_NAME(obj) (GST_OBJECT_CAST(obj)->name) |
117 | /** |
118 | * GST_OBJECT_PARENT: |
119 | * @obj: a #GstObject |
120 | * |
121 | * Get the parent of this object. This is not thread-safe by default |
122 | * (i.e. you will have to make sure the object lock is taken yourself). |
123 | * If in doubt use gst_object_get_parent() instead. |
124 | */ |
125 | #define GST_OBJECT_PARENT(obj) (GST_OBJECT_CAST(obj)->parent) |
126 | |
127 | |
128 | /** |
129 | * GST_OBJECT_FLAGS: |
130 | * @obj: a #GstObject |
131 | * |
132 | * This macro returns the entire set of flags for the object. |
133 | */ |
134 | #define GST_OBJECT_FLAGS(obj) (GST_OBJECT_CAST (obj)->flags) |
135 | /** |
136 | * GST_OBJECT_FLAG_IS_SET: |
137 | * @obj: a #GstObject |
138 | * @flag: Flag to check for |
139 | * |
140 | * This macro checks to see if the given flag is set. |
141 | */ |
142 | #define GST_OBJECT_FLAG_IS_SET(obj,flag) ((GST_OBJECT_FLAGS (obj) & (flag)) == (flag)) |
143 | /** |
144 | * GST_OBJECT_FLAG_SET: |
145 | * @obj: a #GstObject |
146 | * @flag: Flag to set |
147 | * |
148 | * This macro sets the given bits. |
149 | */ |
150 | #define GST_OBJECT_FLAG_SET(obj,flag) (GST_OBJECT_FLAGS (obj) |= (flag)) |
151 | /** |
152 | * GST_OBJECT_FLAG_UNSET: |
153 | * @obj: a #GstObject |
154 | * @flag: Flag to set |
155 | * |
156 | * This macro unsets the given bits. |
157 | */ |
158 | #define GST_OBJECT_FLAG_UNSET(obj,flag) (GST_OBJECT_FLAGS (obj) &= ~(flag)) |
159 | |
160 | typedef struct _GstObject GstObject; |
161 | typedef struct _GstObjectClass GstObjectClass; |
162 | |
163 | /** |
164 | * GstObject: |
165 | * @lock: object LOCK |
166 | * @name: The name of the object |
167 | * @parent: this object's parent, weak ref |
168 | * @flags: flags for this object |
169 | * |
170 | * GStreamer base object class. |
171 | */ |
172 | struct _GstObject { |
173 | GInitiallyUnowned object; |
174 | |
175 | /*< public >*/ /* with LOCK */ |
176 | GMutex lock; /* object LOCK */ |
177 | gchar *name; /* object name */ |
178 | GstObject *parent; /* this object's parent, weak ref */ |
179 | guint32 flags; |
180 | |
181 | /*< private >*/ |
182 | GList *control_bindings; /* List of GstControlBinding */ |
183 | guint64 control_rate; |
184 | guint64 last_sync; |
185 | |
186 | gpointer _gst_reserved; |
187 | }; |
188 | |
189 | /** |
190 | * GstObjectClass: |
191 | * @parent_class: parent |
192 | * @path_string_separator: separator used by gst_object_get_path_string() |
193 | * @deep_notify: default signal handler |
194 | * |
195 | * GStreamer base object class. |
196 | */ |
197 | struct _GstObjectClass { |
198 | GInitiallyUnownedClass parent_class; |
199 | |
200 | const gchar *path_string_separator; |
201 | |
202 | /* signals */ |
203 | void (*deep_notify) (GstObject * object, GstObject * orig, GParamSpec * pspec); |
204 | |
205 | /*< public >*/ |
206 | /* virtual methods for subclasses */ |
207 | |
208 | /*< private >*/ |
209 | gpointer _gst_reserved[GST_PADDING]; |
210 | }; |
211 | |
212 | /* normal GObject stuff */ |
213 | |
214 | GST_API |
215 | GType gst_object_get_type (void); |
216 | |
217 | /* name routines */ |
218 | |
219 | GST_API |
220 | gboolean gst_object_set_name (GstObject *object, const gchar *name); |
221 | |
222 | GST_API |
223 | gchar* gst_object_get_name (GstObject *object); |
224 | |
225 | /* parentage routines */ |
226 | |
227 | GST_API |
228 | gboolean gst_object_set_parent (GstObject *object, GstObject *parent); |
229 | |
230 | GST_API |
231 | GstObject* gst_object_get_parent (GstObject *object); |
232 | |
233 | GST_API |
234 | void gst_object_unparent (GstObject *object); |
235 | |
236 | GST_API |
237 | gboolean gst_object_has_as_parent (GstObject *object, GstObject *parent); |
238 | |
239 | GST_API |
240 | gboolean gst_object_has_as_ancestor (GstObject *object, GstObject *ancestor); |
241 | |
242 | GST_DEPRECATED_FOR(gst_object_has_as_ancestor) |
243 | gboolean gst_object_has_ancestor (GstObject *object, GstObject *ancestor); |
244 | |
245 | GST_API |
246 | void gst_object_default_deep_notify (GObject *object, GstObject *orig, |
247 | GParamSpec *pspec, gchar **excluded_props); |
248 | |
249 | /* refcounting + life cycle */ |
250 | |
251 | GST_API |
252 | gpointer gst_object_ref (gpointer object); |
253 | |
254 | GST_API |
255 | void gst_object_unref (gpointer object); |
256 | |
257 | GST_API |
258 | void gst_clear_object (GstObject **object_ptr); |
259 | #define gst_clear_object(object_ptr) g_clear_pointer ((object_ptr), gst_object_unref) |
260 | |
261 | GST_API |
262 | gpointer gst_object_ref_sink (gpointer object); |
263 | |
264 | /* replace object pointer */ |
265 | |
266 | GST_API |
267 | gboolean gst_object_replace (GstObject **oldobj, GstObject *newobj); |
268 | |
269 | /* printing out the 'path' of the object */ |
270 | |
271 | GST_API |
272 | gchar * gst_object_get_path_string (GstObject *object); |
273 | |
274 | /* misc utils */ |
275 | |
276 | GST_API |
277 | gboolean gst_object_check_uniqueness (GList *list, const gchar *name); |
278 | |
279 | /* controller functions */ |
280 | #include <gst/gstcontrolbinding.h> |
281 | #include <gst/gstcontrolsource.h> |
282 | |
283 | GST_API |
284 | GstClockTime gst_object_suggest_next_sync (GstObject * object); |
285 | |
286 | GST_API |
287 | gboolean gst_object_sync_values (GstObject * object, GstClockTime timestamp); |
288 | |
289 | GST_API |
290 | gboolean gst_object_has_active_control_bindings (GstObject *object); |
291 | |
292 | GST_API |
293 | void gst_object_set_control_bindings_disabled (GstObject *object, gboolean disabled); |
294 | |
295 | GST_API |
296 | void gst_object_set_control_binding_disabled (GstObject *object, |
297 | const gchar * property_name, |
298 | gboolean disabled); |
299 | |
300 | GST_API |
301 | gboolean gst_object_add_control_binding (GstObject * object, GstControlBinding * binding); |
302 | |
303 | GST_API |
304 | GstControlBinding * |
305 | gst_object_get_control_binding (GstObject *object, const gchar * property_name); |
306 | |
307 | GST_API |
308 | gboolean gst_object_remove_control_binding (GstObject * object, GstControlBinding * binding); |
309 | |
310 | GST_API |
311 | GValue * gst_object_get_value (GstObject * object, const gchar * property_name, |
312 | GstClockTime timestamp); |
313 | GST_API |
314 | gboolean gst_object_get_value_array (GstObject * object, const gchar * property_name, |
315 | GstClockTime timestamp, GstClockTime interval, |
316 | guint n_values, gpointer values); |
317 | GST_API |
318 | gboolean gst_object_get_g_value_array (GstObject * object, const gchar * property_name, |
319 | GstClockTime timestamp, GstClockTime interval, |
320 | guint n_values, GValue *values); |
321 | GST_API |
322 | GstClockTime gst_object_get_control_rate (GstObject * object); |
323 | |
324 | GST_API |
325 | void gst_object_set_control_rate (GstObject * object, GstClockTime control_rate); |
326 | |
327 | G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstObject, gst_object_unref) |
328 | |
329 | G_END_DECLS |
330 | |
331 | #endif /* __GST_OBJECT_H__ */ |
332 | |
333 | |