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 #ifdef GST_DISABLE_LOADSAVE

    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 #Object.

   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: used for debugging

   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;

   200 

   201   /*< public >*/ /* with LOCK */

   202   GMutex        *lock;        /* object LOCK */

   203   gchar         *name;        /* object name */

   204   gchar         *name_prefix; /* used for debugging */

   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 #define GST_CLASS_GET_LOCK(obj)         (GST_OBJECT_CLASS_CAST(obj)->lock)

   220 /**

   221  * GST_CLASS_LOCK:

   222  * @obj: a #GstObjectClass

   223  *

   224  * Lock the class.

   225  */

   226 #define GST_CLASS_LOCK(obj)             (g_static_rec_mutex_lock(GST_CLASS_GET_LOCK(obj)))

   227 /**

   228  * GST_CLASS_TRYLOCK:

   229  * @obj: a #GstObjectClass

   230  *

   231  * Try to lock the class, returns TRUE if class could be locked.

   232  */

   233 #define GST_CLASS_TRYLOCK(obj)          (g_static_rec_mutex_trylock(GST_CLASS_GET_LOCK(obj)))

   234 /**

   235  * GST_CLASS_UNLOCK:

   236  * @obj: a #GstObjectClass

   237  *

   238  * Unlock the class.

   239  */

   240 #define GST_CLASS_UNLOCK(obj)           (g_static_rec_mutex_unlock(GST_CLASS_GET_LOCK(obj)))

   241 

   242 /*

   243  * GstObjectClass:

   244  *

   245  * @signal_object: is used to signal to the whole class

   246  * @save_thyself: xml serialisation

   247  * @restore_thyself: xml de-serialisation

   248  */

   249 struct _GstObjectClass {

   250   GObjectClass	parent_class;

   251 

   252   gchar		*path_string_separator;

   253   GObject	*signal_object;

   254 

   255   GStaticRecMutex *lock;

   256 

   257   /* signals */

   258   void          (*parent_set)       (GstObject * object, GstObject * parent);

   259   void          (*parent_unset)     (GstObject * object, GstObject * parent);

   260   void          (*object_saved)     (GstObject * object, GstXmlNodePtr parent);

   261   void          (*deep_notify)      (GstObject * object, GstObject * orig, GParamSpec * pspec);

   262 

   263   /*< public >*/

   264   /* virtual methods for subclasses */

   265   GstXmlNodePtr (*save_thyself)     (GstObject * object, GstXmlNodePtr parent);

   266   void          (*restore_thyself)  (GstObject * object, GstXmlNodePtr self);

   267 

   268   /*< private >*/

   269   gpointer _gst_reserved[GST_PADDING];

   270 };

   271 

   272 /* normal GObject stuff */

   273 #ifdef __SYMBIAN32__

   274 IMPORT_C

   275 #endif

   276 

   277 GType		gst_object_get_type		(void);

   278 

   279 /* name routines */

   280 #ifdef __SYMBIAN32__

   281 IMPORT_C

   282 #endif

   283 

   284 gboolean	gst_object_set_name		(GstObject *object, const gchar *name);

   285 #ifdef __SYMBIAN32__

   286 IMPORT_C

   287 #endif

   288 

   289 gchar*		gst_object_get_name		(GstObject *object);

   290 #ifdef __SYMBIAN32__

   291 IMPORT_C

   292 #endif

   293 

   294 void		gst_object_set_name_prefix	(GstObject *object, const gchar *name_prefix);

   295 #ifdef __SYMBIAN32__

   296 IMPORT_C

   297 #endif

   298 

   299 gchar*		gst_object_get_name_prefix	(GstObject *object);

   300 

   301 /* parentage routines */

   302 #ifdef __SYMBIAN32__

   303 IMPORT_C

   304 #endif

   305 

   306 gboolean	gst_object_set_parent		(GstObject *object, GstObject *parent);

   307 #ifdef __SYMBIAN32__

   308 IMPORT_C

   309 #endif

   310 

   311 GstObject*	gst_object_get_parent		(GstObject *object);

   312 #ifdef __SYMBIAN32__

   313 IMPORT_C

   314 #endif

   315 

   316 void		gst_object_unparent		(GstObject *object);

   317 #ifdef __SYMBIAN32__

   318 IMPORT_C

   319 #endif

   320 

   321 gboolean	gst_object_has_ancestor		(GstObject *object, GstObject *ancestor);

   322 #ifdef __SYMBIAN32__

   323 IMPORT_C

   324 #endif

   325 

   326 

   327 void            gst_object_default_deep_notify 	(GObject *object, GstObject *orig,

   328                                                  GParamSpec *pspec, gchar **excluded_props);

   329 

   330 /* refcounting + life cycle */

   331 #ifdef __SYMBIAN32__

   332 IMPORT_C

   333 #endif

   334 

   335 gpointer	gst_object_ref			(gpointer object);

   336 #ifdef __SYMBIAN32__

   337 IMPORT_C

   338 #endif

   339 

   340 void		gst_object_unref		(gpointer object);

   341 #ifdef __SYMBIAN32__

   342 IMPORT_C

   343 #endif

   344 

   345 void 		gst_object_sink			(gpointer object);

   346 

   347 /* replace object pointer */

   348 #ifdef __SYMBIAN32__

   349 IMPORT_C

   350 #endif

   351 

   352 void 		gst_object_replace		(GstObject **oldobj, GstObject *newobj);

   353 

   354 /* printing out the 'path' of the object */

   355 #ifdef __SYMBIAN32__

   356 IMPORT_C

   357 #endif

   358 

   359 gchar *		gst_object_get_path_string	(GstObject *object);

   360 

   361 /* misc utils */

   362 #ifdef __SYMBIAN32__

   363 IMPORT_C

   364 #endif

   365 

   366 gboolean	gst_object_check_uniqueness	(GList *list, const gchar *name);

   367 

   368 /* load/save */

   369 #ifndef GST_DISABLE_LOADSAVE

   370 GstXmlNodePtr   gst_object_save_thyself    (GstObject *object, GstXmlNodePtr parent);

   371 void            gst_object_restore_thyself (GstObject *object, GstXmlNodePtr self);

   372 #else

   373 #if defined _GNUC_ && _GNUC_ >= 3

   374 #pragma GCC poison gst_object_save_thyself

   375 #pragma GCC poison gst_object_restore_thyself

   376 #endif

   377 #endif

   378 

   379 /* class signal stuff */

   380 #ifdef __SYMBIAN32__

   381 IMPORT_C

   382 #endif

   383 

   384 guint		gst_class_signal_connect	(GstObjectClass	*klass,

   385 						 const gchar	*name,

   386 						 gpointer	 func,

   387 						 gpointer	 func_data);

   388 

   389 #ifndef GST_DISABLE_LOADSAVE

   390 void        gst_class_signal_emit_by_name   (GstObject     * object,

   391                                              const gchar   * name,

   392                                              GstXmlNodePtr   self);

   393 #else

   394 #if defined _GNUC_ && _GNUC_ >= 3

   395 #pragma GCC poison gst_class_signal_emit_by_name

   396 #endif

   397 #endif

   398 

   399 

   400 G_END_DECLS

   401 

   402 #endif /* __GST_OBJECT_H__ */

   403