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