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., 59 Temple Place - Suite 330, |
21 | * Boston, MA 02111-1307, 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 | /* make sure we don't change the object size but still make it compile |
43 | * without libxml */ |
44 | #if defined(GST_DISABLE_LOADSAVE) || defined(GST_DISABLE_DEPRECATED) |
45 | #define GstXmlNodePtr gpointer |
46 | #else |
47 | #define GstXmlNodePtr xmlNodePtr |
48 | #endif |
49 | |
50 | /** |
51 | * GstObjectFlags: |
52 | * @GST_OBJECT_DISPOSING: the object is been destroyed, don't use it anymore |
53 | * @GST_OBJECT_FLOATING: the object has a floating reference count (e.g. its |
54 | * not assigned to a bin) |
55 | * @GST_OBJECT_FLAG_LAST: subclasses can add additional flags starting from this flag |
56 | * |
57 | * The standard flags that an gstobject may have. |
58 | */ |
59 | typedef enum |
60 | { |
61 | GST_OBJECT_DISPOSING = (1<<0), |
62 | GST_OBJECT_FLOATING = (1<<1), |
63 | /* padding */ |
64 | GST_OBJECT_FLAG_LAST = (1<<4) |
65 | } GstObjectFlags; |
66 | |
67 | /** |
68 | * GST_OBJECT_REFCOUNT: |
69 | * @obj: a #GstObject |
70 | * |
71 | * Get access to the reference count field of the object. |
72 | */ |
73 | #define GST_OBJECT_REFCOUNT(obj) (((GObject*)(obj))->ref_count) |
74 | /** |
75 | * GST_OBJECT_REFCOUNT_VALUE: |
76 | * @obj: a #GstObject |
77 | * |
78 | * Get the reference count value of the object. |
79 | */ |
80 | #define GST_OBJECT_REFCOUNT_VALUE(obj) g_atomic_int_get ((gint *) &GST_OBJECT_REFCOUNT(obj)) |
81 | |
82 | /* we do a GST_OBJECT_CAST to avoid type checking, better call these |
83 | * function with a valid object! */ |
84 | |
85 | /** |
86 | * GST_OBJECT_GET_LOCK: |
87 | * @obj: a #GstObject |
88 | * |
89 | * Acquire a reference to the mutex of this object. |
90 | */ |
91 | #define GST_OBJECT_GET_LOCK(obj) (GST_OBJECT_CAST(obj)->lock) |
92 | /** |
93 | * GST_OBJECT_LOCK: |
94 | * @obj: a #GstObject to lock |
95 | * |
96 | * This macro will obtain a lock on the object, making serialization possible. |
97 | * It blocks until the lock can be obtained. |
98 | */ |
99 | #define GST_OBJECT_LOCK(obj) g_mutex_lock(GST_OBJECT_GET_LOCK(obj)) |
100 | /** |
101 | * GST_OBJECT_TRYLOCK: |
102 | * @obj: a #GstObject. |
103 | * |
104 | * This macro will try to obtain a lock on the object, but will return with |
105 | * FALSE if it can't get it immediately. |
106 | */ |
107 | #define GST_OBJECT_TRYLOCK(obj) g_mutex_trylock(GST_OBJECT_GET_LOCK(obj)) |
108 | /** |
109 | * GST_OBJECT_UNLOCK: |
110 | * @obj: a #GstObject to unlock. |
111 | * |
112 | * This macro releases a lock on the object. |
113 | */ |
114 | #define GST_OBJECT_UNLOCK(obj) g_mutex_unlock(GST_OBJECT_GET_LOCK(obj)) |
115 | |
116 | |
117 | /** |
118 | * GST_OBJECT_NAME: |
119 | * @obj: a #GstObject |
120 | * |
121 | * Get the name of this object |
122 | */ |
123 | #define GST_OBJECT_NAME(obj) (GST_OBJECT_CAST(obj)->name) |
124 | /** |
125 | * GST_OBJECT_PARENT: |
126 | * @obj: a #GstObject |
127 | * |
128 | * Get the parent of this object |
129 | */ |
130 | #define GST_OBJECT_PARENT(obj) (GST_OBJECT_CAST(obj)->parent) |
131 | |
132 | |
133 | /** |
134 | * GST_OBJECT_FLAGS: |
135 | * @obj: a #GstObject |
136 | * |
137 | * This macro returns the entire set of flags for the object. |
138 | */ |
139 | #define GST_OBJECT_FLAGS(obj) (GST_OBJECT_CAST (obj)->flags) |
140 | /** |
141 | * GST_OBJECT_FLAG_IS_SET: |
142 | * @obj: a #GstObject |
143 | * @flag: Flag to check for |
144 | * |
145 | * This macro checks to see if the given flag is set. |
146 | */ |
147 | #define GST_OBJECT_FLAG_IS_SET(obj,flag) ((GST_OBJECT_FLAGS (obj) & (flag)) == (flag)) |
148 | /** |
149 | * GST_OBJECT_FLAG_SET: |
150 | * @obj: a #GstObject |
151 | * @flag: Flag to set |
152 | * |
153 | * This macro sets the given bits. |
154 | */ |
155 | #define GST_OBJECT_FLAG_SET(obj,flag) (GST_OBJECT_FLAGS (obj) |= (flag)) |
156 | /** |
157 | * GST_OBJECT_FLAG_UNSET: |
158 | * @obj: a #GstObject |
159 | * @flag: Flag to set |
160 | * |
161 | * This macro usets the given bits. |
162 | */ |
163 | #define GST_OBJECT_FLAG_UNSET(obj,flag) (GST_OBJECT_FLAGS (obj) &= ~(flag)) |
164 | |
165 | |
166 | /** |
167 | * GST_OBJECT_IS_DISPOSING: |
168 | * @obj: a #GstObject |
169 | * |
170 | * Check if the given object is beeing destroyed. |
171 | */ |
172 | #define GST_OBJECT_IS_DISPOSING(obj) (GST_OBJECT_FLAG_IS_SET (obj, GST_OBJECT_DISPOSING)) |
173 | /** |
174 | * GST_OBJECT_IS_FLOATING: |
175 | * @obj: a #GstObject |
176 | * |
177 | * Check if the given object is floating (has no owner). |
178 | */ |
179 | #define GST_OBJECT_IS_FLOATING(obj) (GST_OBJECT_FLAG_IS_SET (obj, GST_OBJECT_FLOATING)) |
180 | |
181 | typedef struct _GstObject GstObject; |
182 | typedef struct _GstObjectClass GstObjectClass; |
183 | |
184 | /** |
185 | * GstObject: |
186 | * @refcount: unused |
187 | * @lock: object LOCK |
188 | * @name: The name of the object |
189 | * @name_prefix: unused |
190 | * @parent: this object's parent, weak ref |
191 | * @flags: use GST_OBJECT_IS_XXX macros to access the flags |
192 | * |
193 | * GStreamer base object class. |
194 | */ |
195 | struct _GstObject { |
196 | GObject object; |
197 | |
198 | /*< public >*/ |
199 | gint refcount; /* unused (FIXME 0.11: remove) */ |
200 | |
201 | /*< public >*/ /* with LOCK */ |
202 | GMutex *lock; /* object LOCK */ |
203 | gchar *name; /* object name */ |
204 | gchar *name_prefix; /* (un)used for debugging (FIXME 0.11: remove) */ |
205 | GstObject *parent; /* this object's parent, weak ref */ |
206 | guint32 flags; |
207 | |
208 | /*< private >*/ |
209 | gpointer _gst_reserved; |
210 | }; |
211 | |
212 | /** |
213 | * GST_CLASS_GET_LOCK: |
214 | * @obj: a #GstObjectClass |
215 | * |
216 | * This macro will return the class lock used to protect deep_notify signal |
217 | * emission on thread-unsafe glib versions (glib < 2.8). |
218 | * |
219 | * Deprecated: 0.10.36: Don't use this, it's not needed any longer. |
220 | */ |
221 | #ifndef GST_DISABLE_DEPRECATED |
222 | #define GST_CLASS_GET_LOCK(obj) (GST_OBJECT_CLASS_CAST(obj)->lock) |
223 | #endif |
224 | |
225 | /** |
226 | * GST_CLASS_LOCK: |
227 | * @obj: a #GstObjectClass |
228 | * |
229 | * Lock the class. |
230 | * |
231 | * Deprecated: 0.10.36: Don't use this, it's not needed any longer. |
232 | */ |
233 | #ifndef GST_DISABLE_DEPRECATED |
234 | #define GST_CLASS_LOCK(obj) (g_static_rec_mutex_lock(GST_CLASS_GET_LOCK(obj))) |
235 | #endif |
236 | |
237 | /** |
238 | * GST_CLASS_TRYLOCK: |
239 | * @obj: a #GstObjectClass |
240 | * |
241 | * Try to lock the class, returns TRUE if class could be locked. |
242 | * |
243 | * Deprecated: 0.10.36: Don't use this, it's not needed any longer. |
244 | */ |
245 | #ifndef GST_DISABLE_DEPRECATED |
246 | #define GST_CLASS_TRYLOCK(obj) (g_static_rec_mutex_trylock(GST_CLASS_GET_LOCK(obj))) |
247 | #endif |
248 | |
249 | /** |
250 | * GST_CLASS_UNLOCK: |
251 | * @obj: a #GstObjectClass |
252 | * |
253 | * Unlock the class. |
254 | * |
255 | * Deprecated: 0.10.36: Don't use this, it's not needed any longer. |
256 | */ |
257 | #ifndef GST_DISABLE_DEPRECATED |
258 | #define GST_CLASS_UNLOCK(obj) (g_static_rec_mutex_unlock(GST_CLASS_GET_LOCK(obj))) |
259 | #endif |
260 | |
261 | /** |
262 | * GstObjectClass: |
263 | * @parent_class: parent |
264 | * @path_string_separator: separator used by gst_object_get_path_string() |
265 | * @signal_object: is used to signal to the whole class |
266 | * @lock: class lock to be used with GST_CLASS_GET_LOCK(), GST_CLASS_LOCK(), GST_CLASS_UNLOCK() and others. |
267 | * @parent_set: default signal handler |
268 | * @parent_unset: default signal handler |
269 | * @object_saved: default signal handler |
270 | * @deep_notify: default signal handler |
271 | * @save_thyself: xml serialisation |
272 | * @restore_thyself: xml de-serialisation |
273 | * |
274 | * GStreamer base object class. |
275 | */ |
276 | struct _GstObjectClass { |
277 | GObjectClass parent_class; |
278 | |
279 | const gchar *path_string_separator; |
280 | GObject *signal_object; |
281 | |
282 | /* FIXME-0.11: remove this, plus the above GST_CLASS_*_LOCK macros */ |
283 | GStaticRecMutex *lock; |
284 | |
285 | /* signals */ |
286 | /* FIXME-0.11: remove, and pass NULL in g_signal_new(), we never used them */ |
287 | void (*parent_set) (GstObject * object, GstObject * parent); |
288 | void (*parent_unset) (GstObject * object, GstObject * parent); |
289 | /* FIXME 0.11: Remove this, it's deprecated */ |
290 | void (*object_saved) (GstObject * object, GstXmlNodePtr parent); |
291 | void (*deep_notify) (GstObject * object, GstObject * orig, GParamSpec * pspec); |
292 | |
293 | /*< public >*/ |
294 | /* virtual methods for subclasses */ |
295 | /* FIXME 0.11: Remove this, it's deprecated */ |
296 | GstXmlNodePtr (*save_thyself) (GstObject * object, GstXmlNodePtr parent); |
297 | void (*restore_thyself) (GstObject * object, GstXmlNodePtr self); |
298 | |
299 | /*< private >*/ |
300 | gpointer _gst_reserved[GST_PADDING]; |
301 | }; |
302 | |
303 | /* normal GObject stuff */ |
304 | GType gst_object_get_type (void); |
305 | |
306 | /* name routines */ |
307 | gboolean gst_object_set_name (GstObject *object, const gchar *name); |
308 | gchar* gst_object_get_name (GstObject *object); |
309 | |
310 | #ifndef GST_DISABLE_DEPRECATED |
311 | void gst_object_set_name_prefix (GstObject *object, const gchar *name_prefix); |
312 | gchar* gst_object_get_name_prefix (GstObject *object); |
313 | #endif |
314 | |
315 | /* parentage routines */ |
316 | gboolean gst_object_set_parent (GstObject *object, GstObject *parent); |
317 | GstObject* gst_object_get_parent (GstObject *object); |
318 | void gst_object_unparent (GstObject *object); |
319 | gboolean gst_object_has_ancestor (GstObject *object, GstObject *ancestor); |
320 | |
321 | void gst_object_default_deep_notify (GObject *object, GstObject *orig, |
322 | GParamSpec *pspec, gchar **excluded_props); |
323 | |
324 | /* refcounting + life cycle */ |
325 | gpointer gst_object_ref (gpointer object); |
326 | void gst_object_unref (gpointer object); |
327 | void gst_object_ref_sink (gpointer object); |
328 | void gst_object_sink (gpointer object); |
329 | |
330 | /* replace object pointer */ |
331 | void gst_object_replace (GstObject **oldobj, GstObject *newobj); |
332 | |
333 | /* printing out the 'path' of the object */ |
334 | gchar * gst_object_get_path_string (GstObject *object); |
335 | |
336 | /* misc utils */ |
337 | gboolean gst_object_check_uniqueness (GList *list, const gchar *name); |
338 | |
339 | /* load/save */ |
340 | #ifndef GST_DISABLE_DEPRECATED |
341 | #ifndef GST_DISABLE_LOADSAVE |
342 | GstXmlNodePtr gst_object_save_thyself (GstObject *object, GstXmlNodePtr parent); |
343 | void gst_object_restore_thyself (GstObject *object, GstXmlNodePtr self); |
344 | #else |
345 | #if defined __GNUC__ && __GNUC__ >= 3 |
346 | #pragma GCC poison gst_object_save_thyself |
347 | #pragma GCC poison gst_object_restore_thyself |
348 | #endif |
349 | #endif |
350 | #endif |
351 | |
352 | /* class signal stuff */ |
353 | guint gst_class_signal_connect (GstObjectClass *klass, |
354 | const gchar *name, |
355 | gpointer func, |
356 | gpointer func_data); |
357 | |
358 | #ifndef GST_DISABLE_DEPRECATED |
359 | #ifndef GST_DISABLE_LOADSAVE |
360 | void gst_class_signal_emit_by_name (GstObject * object, |
361 | const gchar * name, |
362 | GstXmlNodePtr self); |
363 | #else |
364 | #if defined __GNUC__ && __GNUC__ >= 3 |
365 | #pragma GCC poison gst_class_signal_emit_by_name |
366 | #endif |
367 | #endif |
368 | #endif |
369 | |
370 | G_END_DECLS |
371 | |
372 | #endif /* __GST_OBJECT_H__ */ |
373 | |
374 | |