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>
6 * gstobject.h: Header for base GstObject
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.
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.
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.
24 #ifndef __GST_OBJECT_H__
25 #define __GST_OBJECT_H__
27 #include <gst/gstconfig.h>
29 #include <glib-object.h>
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))
42 /* make sure we don't change the object size but still make it compile
44 #if defined(GST_DISABLE_LOADSAVE) || defined(GST_DISABLE_DEPRECATED)
45 #define GstXmlNodePtr gpointer
47 #define GstXmlNodePtr xmlNodePtr
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
57 * The standard flags that an gstobject may have.
61 GST_OBJECT_DISPOSING = (1<<0),
62 GST_OBJECT_FLOATING = (1<<1),
64 GST_OBJECT_FLAG_LAST = (1<<4)
68 * GST_OBJECT_REFCOUNT:
71 * Get access to the reference count field of the object.
73 #define GST_OBJECT_REFCOUNT(obj) (((GObject*)(obj))->ref_count)
75 * GST_OBJECT_REFCOUNT_VALUE:
78 * Get the reference count value of the object.
80 #define GST_OBJECT_REFCOUNT_VALUE(obj) g_atomic_int_get ((gint *) &GST_OBJECT_REFCOUNT(obj))
82 /* we do a GST_OBJECT_CAST to avoid type checking, better call these
83 * function with a valid object! */
86 * GST_OBJECT_GET_LOCK:
89 * Acquire a reference to the mutex of this object.
91 #define GST_OBJECT_GET_LOCK(obj) (GST_OBJECT_CAST(obj)->lock)
94 * @obj: a #GstObject to lock
96 * This macro will obtain a lock on the object, making serialization possible.
97 * It blocks until the lock can be obtained.
99 #define GST_OBJECT_LOCK(obj) g_mutex_lock(GST_OBJECT_GET_LOCK(obj))
101 * GST_OBJECT_TRYLOCK:
102 * @obj: a #GstObject.
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.
107 #define GST_OBJECT_TRYLOCK(obj) g_mutex_trylock(GST_OBJECT_GET_LOCK(obj))
110 * @obj: a #GstObject to unlock.
112 * This macro releases a lock on the object.
114 #define GST_OBJECT_UNLOCK(obj) g_mutex_unlock(GST_OBJECT_GET_LOCK(obj))
121 * Get the name of this object
123 #define GST_OBJECT_NAME(obj) (GST_OBJECT_CAST(obj)->name)
128 * Get the parent of this object
130 #define GST_OBJECT_PARENT(obj) (GST_OBJECT_CAST(obj)->parent)
137 * This macro returns the entire set of flags for the object.
139 #define GST_OBJECT_FLAGS(obj) (GST_OBJECT_CAST (obj)->flags)
141 * GST_OBJECT_FLAG_IS_SET:
143 * @flag: Flag to check for
145 * This macro checks to see if the given flag is set.
147 #define GST_OBJECT_FLAG_IS_SET(obj,flag) ((GST_OBJECT_FLAGS (obj) & (flag)) == (flag))
149 * GST_OBJECT_FLAG_SET:
153 * This macro sets the given bits.
155 #define GST_OBJECT_FLAG_SET(obj,flag) (GST_OBJECT_FLAGS (obj) |= (flag))
157 * GST_OBJECT_FLAG_UNSET:
161 * This macro usets the given bits.
163 #define GST_OBJECT_FLAG_UNSET(obj,flag) (GST_OBJECT_FLAGS (obj) &= ~(flag))
167 * GST_OBJECT_IS_DISPOSING:
170 * Check if the given object is beeing destroyed.
172 #define GST_OBJECT_IS_DISPOSING(obj) (GST_OBJECT_FLAG_IS_SET (obj, GST_OBJECT_DISPOSING))
174 * GST_OBJECT_IS_FLOATING:
177 * Check if the given object is floating (has no owner).
179 #define GST_OBJECT_IS_FLOATING(obj) (GST_OBJECT_FLAG_IS_SET (obj, GST_OBJECT_FLOATING))
181 typedef struct _GstObject GstObject;
182 typedef struct _GstObjectClass GstObjectClass;
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
193 * GStreamer base object class.
199 gint refcount; /* unused (FIXME 0.11: remove) */
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 */
209 gpointer _gst_reserved;
213 * GST_CLASS_GET_LOCK:
214 * @obj: a #GstObjectClass
216 * This macro will return the class lock used to protect deep_notify signal
217 * emission on thread-unsafe glib versions (glib < 2.8).
219 #define GST_CLASS_GET_LOCK(obj) (GST_OBJECT_CLASS_CAST(obj)->lock)
222 * @obj: a #GstObjectClass
226 #define GST_CLASS_LOCK(obj) (g_static_rec_mutex_lock(GST_CLASS_GET_LOCK(obj)))
229 * @obj: a #GstObjectClass
231 * Try to lock the class, returns TRUE if class could be locked.
233 #define GST_CLASS_TRYLOCK(obj) (g_static_rec_mutex_trylock(GST_CLASS_GET_LOCK(obj)))
236 * @obj: a #GstObjectClass
240 #define GST_CLASS_UNLOCK(obj) (g_static_rec_mutex_unlock(GST_CLASS_GET_LOCK(obj)))
244 * @parent_class: parent
245 * @path_string_separator: separator used by gst_object_get_path_string()
246 * @signal_object: is used to signal to the whole class
247 * @lock: class lock to be used with GST_CLASS_GET_LOCK(), GST_CLASS_LOCK(), GST_CLASS_UNLOCK() and others.
248 * @parent_set: default signal handler
249 * @parent_unset: default signal handler
250 * @object_saved: default signal handler
251 * @deep_notify: default signal handler
252 * @save_thyself: xml serialisation
253 * @restore_thyself: xml de-serialisation
255 * GStreamer base object class.
257 struct _GstObjectClass {
258 GObjectClass parent_class;
260 const gchar *path_string_separator;
261 GObject *signal_object;
263 /* FIXME-0.11: remove this, plus the above GST_CLASS_*_LOCK macros */
264 GStaticRecMutex *lock;
267 /* FIXME-0.11: remove, and pass NULL in g_signal_new(), we never used them */
268 void (*parent_set) (GstObject * object, GstObject * parent);
269 void (*parent_unset) (GstObject * object, GstObject * parent);
270 /* FIXME 0.11: Remove this, it's deprecated */
271 void (*object_saved) (GstObject * object, GstXmlNodePtr parent);
272 void (*deep_notify) (GstObject * object, GstObject * orig, GParamSpec * pspec);
275 /* virtual methods for subclasses */
276 /* FIXME 0.11: Remove this, it's deprecated */
277 GstXmlNodePtr (*save_thyself) (GstObject * object, GstXmlNodePtr parent);
278 void (*restore_thyself) (GstObject * object, GstXmlNodePtr self);
281 gpointer _gst_reserved[GST_PADDING];
284 /* normal GObject stuff */
285 GType gst_object_get_type (void);
288 gboolean gst_object_set_name (GstObject *object, const gchar *name);
289 gchar* gst_object_get_name (GstObject *object);
291 #ifndef GST_DISABLE_DEPRECATED
292 void gst_object_set_name_prefix (GstObject *object, const gchar *name_prefix);
293 gchar* gst_object_get_name_prefix (GstObject *object);
296 /* parentage routines */
297 gboolean gst_object_set_parent (GstObject *object, GstObject *parent);
298 GstObject* gst_object_get_parent (GstObject *object);
299 void gst_object_unparent (GstObject *object);
300 gboolean gst_object_has_ancestor (GstObject *object, GstObject *ancestor);
302 void gst_object_default_deep_notify (GObject *object, GstObject *orig,
303 GParamSpec *pspec, gchar **excluded_props);
305 /* refcounting + life cycle */
306 gpointer gst_object_ref (gpointer object);
307 void gst_object_unref (gpointer object);
308 void gst_object_ref_sink (gpointer object);
309 void gst_object_sink (gpointer object);
311 /* replace object pointer */
312 void gst_object_replace (GstObject **oldobj, GstObject *newobj);
314 /* printing out the 'path' of the object */
315 gchar * gst_object_get_path_string (GstObject *object);
318 gboolean gst_object_check_uniqueness (GList *list, const gchar *name);
321 #ifndef GST_DISABLE_DEPRECATED
322 #ifndef GST_DISABLE_LOADSAVE
323 GstXmlNodePtr gst_object_save_thyself (GstObject *object, GstXmlNodePtr parent);
324 void gst_object_restore_thyself (GstObject *object, GstXmlNodePtr self);
326 #if defined __GNUC__ && __GNUC__ >= 3
327 #pragma GCC poison gst_object_save_thyself
328 #pragma GCC poison gst_object_restore_thyself
333 /* class signal stuff */
334 guint gst_class_signal_connect (GstObjectClass *klass,
339 #ifndef GST_DISABLE_DEPRECATED
340 #ifndef GST_DISABLE_LOADSAVE
341 void gst_class_signal_emit_by_name (GstObject * object,
345 #if defined __GNUC__ && __GNUC__ >= 3
346 #pragma GCC poison gst_class_signal_emit_by_name
353 #endif /* __GST_OBJECT_H__ */