GstObject

GstObject — Base class for the GStreamer object hierarchy

Synopsis




#define     GST_OBJECT_CLASS                (klass)
#define     xmlNodePtr
enum        GstObjectFlags;
#define     GST_FLAGS                       (obj)
#define     GST_FLAG_IS_SET                 (obj,flag)
#define     GST_FLAG_SET                    (obj,flag)
#define     GST_FLAG_UNSET                  (obj,flag)
#define     GST_OBJECT_NAME                 (obj)
#define     GST_OBJECT_PARENT               (obj)
#define     GST_OBJECT_DESTROYED            (obj)
#define     GST_OBJECT_FLOATING             (obj)
#define     GST_LOCK                        (obj)
#define     GST_TRYLOCK                     (obj)
#define     GST_UNLOCK                      (obj)
#define     GST_GET_LOCK                    (obj)
void        gst_object_set_name             (GstObject *object,
                                             const gchar *name);
G_CONST_RETURN gchar* gst_object_get_name   (GstObject *object);
void        gst_object_set_parent           (GstObject *object,
                                             GstObject *parent);
GstObject*  gst_object_get_parent           (GstObject *object);
void        gst_object_unparent             (GstObject *object);
void        gst_object_default_deep_notify  (GObject *object,
                                             GstObject *orig,
                                             GParamSpec *pspec,
                                             gchar **excluded_props);
gboolean    gst_object_check_uniqueness     (GList *list,
                                             const gchar *name);
xmlNodePtr  gst_object_save_thyself         (GstObject *object,
                                             xmlNodePtr parent);
void        gst_object_restore_thyself      (GstObject *object,
                                             xmlNodePtr self);
GstObject*  gst_object_ref                  (GstObject *object);
void        gst_object_unref                (GstObject *object);
void        gst_object_sink                 (GstObject *object);
void        gst_object_replace              (GstObject **oldobj,
                                             GstObject *newobj);
gchar*      gst_object_get_path_string      (GstObject *object);
guint       gst_class_signal_connect        (GstObjectClass *klass,
                                             const gchar *name,
                                             gpointer func,
                                             gpointer func_data);
void        gst_class_signal_emit_by_name   (GstObject *object,
                                             const gchar *name,
                                             xmlNodePtr self);

Description

GstObject provides a root for the object hierarchy tree filed in by the GST library. It is currently a thin wrapper on top of GObject. It is an abstract class that is not very usable on its own.

GstObject gives us basic refcounting, parenting functionality and locking.

gst_object_set_name() and gst_object_get_name() are used to set/get the name of the object.

Details

GST_OBJECT_CLASS()

#define GST_OBJECT_CLASS(klass)		(G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_OBJECT, GstObjectClass))

klass :

xmlNodePtr

#define xmlNodePtr	gpointer


enum GstObjectFlags

typedef enum
{
  GST_DESTROYED   = 0,
  GST_FLOATING,

  GST_OBJECT_FLAG_LAST   = 4
} GstObjectFlags;

Flags for an object

GST_DESTROYEDThe object is flagged for destruction
GST_FLOATINGThe object is created but has no parent yet to manage it
GST_OBJECT_FLAG_LASTsubclasses can add additional flags starting from this flag

GST_FLAGS()

#define GST_FLAGS(obj)			(GST_OBJECT (obj)->flags)

This macro returns the entire set of flags for the object.

obj :Object to return flags for.

GST_FLAG_IS_SET()

#define GST_FLAG_IS_SET(obj,flag)	(GST_FLAGS (obj) & (1<<(flag)))

This macro checks to see if the given flag is set.

obj :GstSrc to check for flag in.
flag :Flag to check for, must be a single bit in guint32.

GST_FLAG_SET()

#define GST_FLAG_SET(obj,flag)		G_STMT_START{ (GST_FLAGS (obj) |= (1<<(flag))); }G_STMT_END

This macro sets the given bits.

obj :Object to set flag in.
flag :Flag to set, can by any number of bits in guint32.

GST_FLAG_UNSET()

#define GST_FLAG_UNSET(obj,flag)	G_STMT_START{ (GST_FLAGS (obj) &= ~(1<<(flag))); }G_STMT_END

This macro usets the given bits.

obj :Object to unset flag in.
flag :Flag to set, must be a single bit in guint32.

GST_OBJECT_NAME()

#define GST_OBJECT_NAME(obj)		(const gchar*)(((GstObject *)(obj))->name)

Get the name of this object

obj :Object to get the name of.

GST_OBJECT_PARENT()

#define GST_OBJECT_PARENT(obj)		(((GstObject *)(obj))->parent)

Get the parent of this object

obj :Object to get the parent of.

GST_OBJECT_DESTROYED()

#define GST_OBJECT_DESTROYED(obj)	(GST_FLAG_IS_SET (obj, GST_DESTROYED))

Check if the object has been destroyed.

obj :The Object to check

GST_OBJECT_FLOATING()

#define GST_OBJECT_FLOATING(obj)	(GST_FLAG_IS_SET (obj, GST_FLOATING))

Check if the object is floating.

obj :The Object to check

GST_LOCK()

#define GST_LOCK(obj)			(g_mutex_lock(GST_OBJECT(obj)->lock))

This macro will obtain a lock on the object, making serialization possible.

obj :Object to lock.

GST_TRYLOCK()

#define GST_TRYLOCK(obj)		(g_mutex_trylock(GST_OBJECT(obj)->lock))

This macro will try to obtain a lock on the object, but will return with FALSE if it can't get it immediately.

obj :Object to try to get a lock on.

GST_UNLOCK()

#define GST_UNLOCK(obj)			(g_mutex_unlock(GST_OBJECT(obj)->lock))

This macro releases a lock on the object.

obj :Object to unlock.

GST_GET_LOCK()

#define GST_GET_LOCK(obj)		(GST_OBJECT(obj)->lock)

Acquire a reference to the mutex of this object.

obj :Object to get the mutex of.

gst_object_set_name ()

void        gst_object_set_name             (GstObject *object,
                                             const gchar *name);

Sets the name of the object, or gives the element a guaranteed unique name (if name is NULL).

object : GstObject to set the name of
name : new name of object

gst_object_get_name ()

G_CONST_RETURN gchar* gst_object_get_name   (GstObject *object);

Get the name of the object.

object : GstObject to get the name of
Returns : name of the object

gst_object_set_parent ()

void        gst_object_set_parent           (GstObject *object,
                                             GstObject *parent);

Sets the parent of object. The object's reference count will be incremented, and any floating reference will be removed (see gst_object_sink()).

Causes the parent-set signal to be emitted.

object : GstObject to set parent of
parent : new parent of object

gst_object_get_parent ()

GstObject*  gst_object_get_parent           (GstObject *object);

Returns the parent of object.

object : GstObject to get parent of
Returns : parent of the object

gst_object_unparent ()

void        gst_object_unparent             (GstObject *object);

Clear the parent of object, removing the associated reference.

object : GstObject to unparent

gst_object_default_deep_notify ()

void        gst_object_default_deep_notify  (GObject *object,
                                             GstObject *orig,
                                             GParamSpec *pspec,
                                             gchar **excluded_props);

Adds a default deep_notify signal callback to an element. The user data should contain a pointer to an array of strings that should be excluded from the notify. The default handler will print the new value of the property using g_print.

object : the GObject that signalled the notify.
orig : a GstObject that initiated the notify.
pspec : a GParamSpec of the property.
excluded_props : a set of user-specified properties to exclude or NULL to show all changes.

gst_object_check_uniqueness ()

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

Checks to see if there is any object named name in list.

list : a list of GstObject to check through
name : the name to search for
Returns : TRUE if the name does not appear in the list, FALSE if it does.

gst_object_save_thyself ()

xmlNodePtr  gst_object_save_thyself         (GstObject *object,
                                             xmlNodePtr parent);

Saves the given object into the parent XML node.

object : GstObject to save
parent : The parent XML node to save the object into
Returns : the new xmlNodePtr with the saved object

gst_object_restore_thyself ()

void        gst_object_restore_thyself      (GstObject *object,
                                             xmlNodePtr self);

Restores the given object with the data from the parent XML node.

object : GstObject to load into
self : The XML node to load the object from

gst_object_ref ()

GstObject*  gst_object_ref                  (GstObject *object);

Increments the refence count on the object.

object : GstObject to reference
Returns : A pointer to the object

gst_object_unref ()

void        gst_object_unref                (GstObject *object);

Decrements the refence count on the object. If reference count hits zero, destroy the object.

object : GstObject to unreference

gst_object_sink ()

void        gst_object_sink                 (GstObject *object);

Removes floating reference on an object. Any newly created object has a refcount of 1 and is FLOATING. This function should be used when creating a new object to symbolically 'take ownership' of the object. Use gst_object_set_parent to have this done for you.

object : GstObject to sink

gst_object_replace ()

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

Unrefs the object pointer to by oldobj, refs the newobj and puts the newobj in *oldobj.

oldobj : pointer to place of old GstObject
newobj : new GstObject

gst_object_get_path_string ()

gchar*      gst_object_get_path_string      (GstObject *object);

Generates a string describing the path of the object in the object hierarchy. Only useful (or used) for debugging.

object : GstObject to get the path from
Returns : a string describing the path of the object

gst_class_signal_connect ()

guint       gst_class_signal_connect        (GstObjectClass *klass,
                                             const gchar *name,
                                             gpointer func,
                                             gpointer func_data);

Connect to a class signal.

klass : the GstObjectClass to attach the signal to
name : the name of the signal to attach to
func : the signal function
func_data : a pointer to user data
Returns : the signal id.

gst_class_signal_emit_by_name ()

void        gst_class_signal_emit_by_name   (GstObject *object,
                                             const gchar *name,
                                             xmlNodePtr self);

emits the named class signal.

object : the object that sends the signal
name : the name of the signal to emit
self : data for the signal