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 /**
  43  * GstObjectFlags:
  44  * @GST_OBJECT_FLAG_LAST: subclasses can add additional flags starting from this flag
  45  *
  46  * The standard flags that an gstobject may have.
  47  */
  48 typedef enum
  49 {
  50   /* padding */
  51   GST_OBJECT_FLAG_LAST = (1<<4)
  52 } GstObjectFlags;
  53
  54 /**
  55  * GST_OBJECT_REFCOUNT:
  56  * @obj: a #GstObject
  57  *
  58  * Get access to the reference count field of the object.
  59  */
  60 #define GST_OBJECT_REFCOUNT(obj)                (((GObject*)(obj))->ref_count)
  61 /**
  62  * GST_OBJECT_REFCOUNT_VALUE:
  63  * @obj: a #GstObject
  64  *
  65  * Get the reference count value of the object.
  66  */
  67 #define GST_OBJECT_REFCOUNT_VALUE(obj)          g_atomic_int_get ((gint *) &GST_OBJECT_REFCOUNT(obj))
  68
  69 /* we do a GST_OBJECT_CAST to avoid type checking, better call these
  70  * function with a valid object! */
  71
  72 /**
  73  * GST_OBJECT_GET_LOCK:
  74  * @obj: a #GstObject
  75  *
  76  * Acquire a reference to the mutex of this object.
  77  */
  78 #define GST_OBJECT_GET_LOCK(obj)               (GST_OBJECT_CAST(obj)->lock)
  79 /**
  80  * GST_OBJECT_LOCK:
  81  * @obj: a #GstObject to lock
  82  *
  83  * This macro will obtain a lock on the object, making serialization possible.
  84  * It blocks until the lock can be obtained.
  85  */
  86 #define GST_OBJECT_LOCK(obj)                   g_mutex_lock(GST_OBJECT_GET_LOCK(obj))
  87 /**
  88  * GST_OBJECT_TRYLOCK:
  89  * @obj: a #GstObject.
  90  *
  91  * This macro will try to obtain a lock on the object, but will return with
  92  * FALSE if it can't get it immediately.
  93  */
  94 #define GST_OBJECT_TRYLOCK(obj)                g_mutex_trylock(GST_OBJECT_GET_LOCK(obj))
  95 /**
  96  * GST_OBJECT_UNLOCK:
  97  * @obj: a #GstObject to unlock.
  98  *
  99  * This macro releases a lock on the object.
 100  */
 101 #define GST_OBJECT_UNLOCK(obj)                 g_mutex_unlock(GST_OBJECT_GET_LOCK(obj))
 102
 103
 104 /**
 105  * GST_OBJECT_NAME:
 106  * @obj: a #GstObject
 107  *
 108  * Get the name of this object
 109  */
 110 #define GST_OBJECT_NAME(obj)            (GST_OBJECT_CAST(obj)->name)
 111 /**
 112  * GST_OBJECT_PARENT:
 113  * @obj: a #GstObject
 114  *
 115  * Get the parent of this object
 116  */
 117 #define GST_OBJECT_PARENT(obj)          (GST_OBJECT_CAST(obj)->parent)
 118
 119
 120 /**
 121  * GST_OBJECT_FLAGS:
 122  * @obj: a #GstObject
 123  *
 124  * This macro returns the entire set of flags for the object.
 125  */
 126 #define GST_OBJECT_FLAGS(obj)                  (GST_OBJECT_CAST (obj)->flags)
 127 /**
 128  * GST_OBJECT_FLAG_IS_SET:
 129  * @obj: a #GstObject
 130  * @flag: Flag to check for
 131  *
 132  * This macro checks to see if the given flag is set.
 133  */
 134 #define GST_OBJECT_FLAG_IS_SET(obj,flag)       ((GST_OBJECT_FLAGS (obj) & (flag)) == (flag))
 135 /**
 136  * GST_OBJECT_FLAG_SET:
 137  * @obj: a #GstObject
 138  * @flag: Flag to set
 139  *
 140  * This macro sets the given bits.
 141  */
 142 #define GST_OBJECT_FLAG_SET(obj,flag)          (GST_OBJECT_FLAGS (obj) |= (flag))
 143 /**
 144  * GST_OBJECT_FLAG_UNSET:
 145  * @obj: a #GstObject
 146  * @flag: Flag to set
 147  *
 148  * This macro usets the given bits.
 149  */
 150 #define GST_OBJECT_FLAG_UNSET(obj,flag)        (GST_OBJECT_FLAGS (obj) &= ~(flag))
 151
 152
 153 typedef struct _GstObject GstObject;
 154 typedef struct _GstObjectClass GstObjectClass;
 155
 156 /**
 157  * GstObject:
 158  * @lock: object LOCK
 159  * @name: The name of the object
 160  * @parent: this object's parent, weak ref
 161  * @flags: flags for this object
 162  *
 163  * GStreamer base object class.
 164  */
 165 struct _GstObject {
 166   GInitiallyUnowned object;
 167
 168   /*< public >*/ /* with LOCK */
 169   GMutex        *lock;        /* object LOCK */
 170   gchar         *name;        /* object name */
 171   GstObject     *parent;      /* this object's parent, weak ref */
 172   guint32        flags;
 173
 174   /*< private >*/
 175   gpointer _gst_reserved;
 176 };
 177
 178 /**
 179  * GstObjectClass:
 180  * @parent_class: parent
 181  * @path_string_separator: separator used by gst_object_get_path_string()
 182  * @deep_notify: default signal handler
 183  *
 184  * GStreamer base object class.
 185  */
 186 struct _GstObjectClass {
 187   GInitiallyUnownedClass parent_class;
 188
 189   const gchar   *path_string_separator;
 190
 191   /* signals */
 192   void          (*deep_notify)      (GstObject * object, GstObject * orig, GParamSpec * pspec);
 193
 194   /*< public >*/
 195   /* virtual methods for subclasses */
 196
 197   /*< private >*/
 198   gpointer _gst_reserved[GST_PADDING];
 199 };
 200
 201 /* normal GObject stuff */
 202 GType           gst_object_get_type             (void);
 203
 204 /* name routines */
 205 gboolean        gst_object_set_name             (GstObject *object, const gchar *name);
 206 gchar*          gst_object_get_name             (GstObject *object);
 207
 208 /* parentage routines */
 209 gboolean        gst_object_set_parent           (GstObject *object, GstObject *parent);
 210 GstObject*      gst_object_get_parent           (GstObject *object);
 211 void            gst_object_unparent             (GstObject *object);
 212 gboolean        gst_object_has_ancestor         (GstObject *object, GstObject *ancestor);
 213
 214 void            gst_object_default_deep_notify  (GObject *object, GstObject *orig,
 215                                                  GParamSpec *pspec, gchar **excluded_props);
 216
 217 /* refcounting + life cycle */
 218 gpointer        gst_object_ref                  (gpointer object);
 219 void            gst_object_unref                (gpointer object);
 220 gpointer        gst_object_ref_sink             (gpointer object);
 221
 222 /* replace object pointer */
 223 gboolean        gst_object_replace              (GstObject **oldobj, GstObject *newobj);
 224
 225 /* printing out the 'path' of the object */
 226 gchar *         gst_object_get_path_string      (GstObject *object);
 227
 228 /* misc utils */
 229 gboolean        gst_object_check_uniqueness     (GList *list, const gchar *name);
 230
 231 G_END_DECLS
 232
 233 #endif /* __GST_OBJECT_H__ */
 234