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
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/* 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 */
59typedef 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
181typedef struct _GstObject GstObject;
182typedef 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 */
195struct _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 */
276struct _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 */
304GType gst_object_get_type (void);
305
306/* name routines */
307gboolean gst_object_set_name (GstObject *object, const gchar *name);
308gchar* gst_object_get_name (GstObject *object);
309
310#ifndef GST_DISABLE_DEPRECATED
311void gst_object_set_name_prefix (GstObject *object, const gchar *name_prefix);
312gchar* gst_object_get_name_prefix (GstObject *object);
313#endif
314
315/* parentage routines */
316gboolean gst_object_set_parent (GstObject *object, GstObject *parent);
317GstObject* gst_object_get_parent (GstObject *object);
318void gst_object_unparent (GstObject *object);
319gboolean gst_object_has_ancestor (GstObject *object, GstObject *ancestor);
320
321void gst_object_default_deep_notify (GObject *object, GstObject *orig,
322 GParamSpec *pspec, gchar **excluded_props);
323
324/* refcounting + life cycle */
325gpointer gst_object_ref (gpointer object);
326void gst_object_unref (gpointer object);
327void gst_object_ref_sink (gpointer object);
328void gst_object_sink (gpointer object);
329
330/* replace object pointer */
331void gst_object_replace (GstObject **oldobj, GstObject *newobj);
332
333/* printing out the 'path' of the object */
334gchar * gst_object_get_path_string (GstObject *object);
335
336/* misc utils */
337gboolean gst_object_check_uniqueness (GList *list, const gchar *name);
338
339/* load/save */
340#ifndef GST_DISABLE_DEPRECATED
341#ifndef GST_DISABLE_LOADSAVE
342GstXmlNodePtr gst_object_save_thyself (GstObject *object, GstXmlNodePtr parent);
343void 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 */
353guint 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
360void 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
370G_END_DECLS
371
372#endif /* __GST_OBJECT_H__ */
373
374