gst/gstobject.h

   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 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
 328 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstObject, gst_object_unref)
 329 #endif
 330
 331 G_END_DECLS
 332
 333 #endif /* __GST_OBJECT_H__ */
 334