wearable/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., 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