Next: , Previous: GstMiniObject, Up: Top

23 GstObject

Base class for the GStreamer object hierarchy

23.1 Overview

<gst-object> provides a root for the object hierarchy tree filed in by the GStreamer library. It is currently a thin wrapper on top of <gobject>. It is an abstract class that is not very usable on its own.

<gst-object> gives us basic refcounting, parenting functionality and locking. Most of the function are just extended for special GStreamer needs and can be found under the same name in the base class of <gst-object> which is <gobject> (e.g. g-object-ref becomes gst-object-ref).

The most interesting difference between <gst-object> and <gobject> is the "floating" reference count. A <gobject> is created with a reference count of 1, owned by the creator of the <gobject>. (The owner of a reference is the code section that has the right to call gst-object-unref in order to remove that reference.) A <gst-object> is created with a reference count of 1 also, but it isn't owned by anyone; Instead, the initial reference count of a <gst-object> is "floating". The floating reference can be removed by anyone at any time, by calling gst-object-sink. gst-object-sink does nothing if an object is already sunk (has no floating reference).

When you add a <gst-element> to its parent container, the parent container will do this: This means that the container now owns a reference to the child element (since it called gst-object-ref), and the child element has no floating reference. 

     
       gst_object_ref (GST_OBJECT (child_element));
       gst_object_sink (GST_OBJECT (child_element));

The purpose of the floating reference is to keep the child element alive until you add it to a parent container, which then manages the lifetime of the object itself: 

     
        element = gst_element_factory_make (factoryname, name);
        // element has one floating reference to keep it alive
        gst_bin_add (GST_BIN (bin), element);
        // element has one non-floating reference owned by the container

Another effect of this is, that calling gst-object-unref on a bin object, will also destoy all the <gst-element> objects in it. The same is true for calling gst-bin-remove.

Special care has to be taken for all methods that gst-object-sink an object since if the caller of those functions had a floating reference to the object, the object reference is now invalid.

In contrast to <gobject> instances, <gst-object> adds a name property. The functions gst-object-set-name and gst-object-get-name are used to set/get the name of the object.

Last reviewed on 2005-11-09 (0.9.4)

23.2 Usage

— Class: <gst-object>

This <gobject> class defines the following properties:

name
The name of the object
— Signal on <gst-object>: parent-set (arg0 <gobject>)

Emitted when the parent of an object is set.

— Signal on <gst-object>: parent-unset (arg0 <gobject>)

Emitted when the parent of an object is unset.

— Signal on <gst-object>: object-saved (arg0 <gpointer>)

Trigered whenever a new object is saved to XML. You can connect to this signal to insert custom XML tags into the core XML.

— Signal on <gst-object>: deep-notify (arg0 <gst-object>) (arg1 <gparam>)

The deep notify signal is used to be notified of property changes. It is typically attached to the toplevel bin to receive notifications from all the elements contained in that bin.

— Function: gst-object-set-name (self <gst-object>) (name mchars)   (ret bool)
— Method: set-name

Sets the name of object, or gives object a guaranteed unique name (if name is NULL). This function makes a copy of the provided name, so the caller retains ownership of the name it sent.

object
a <gst-object>
name
new name of object
ret
TRUE if the name could be set. Since Objects that have a parent cannot be renamed, this function returns FALSE in those cases. MT safe. This function grabs and releases object's LOCK.
— Function: gst-object-get-name (self <gst-object>)   (ret mchars)
— Method: get-name

Returns a copy of the name of object. Caller should g-free the return value after usage. For a nameless object, this returns NULL, which you can safely g-free as well.

object
a <gst-object>
ret
the name of object. g-free after usage. MT safe. This function grabs and releases object's LOCK.
— Function: gst-object-set-parent (self <gst-object>) (parent <gst-object>)   (ret bool)
— Method: set-parent

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

This function causes the parent-set signal to be emitted when the parent was successfully set.

object
a <gst-object>
parent
new parent of object
ret
TRUE if parent could be set or FALSE when object already had a parent or object and parent are the same. MT safe. Grabs and releases object's LOCK.
— Function: gst-object-get-parent (self <gst-object>)   (ret <gst-object>)
— Method: get-parent

Returns the parent of object. This function increases the refcount of the parent object so you should gst-object-unref it after usage.

object
a <gst-object>
ret
parent of object, this can be NULL if object has no parent. unref after usage. MT safe. Grabs and releases object's LOCK.
— Function: gst-object-unparent (self <gst-object>)
— Method: unparent

Clear the parent of object, removing the associated reference. This function decreases the refcount of object.

MT safe. Grabs and releases object's lock.

object
a <gst-object> to unparent
— Function: gst-object-get-name-prefix (self <gst-object>)   (ret mchars)
— Method: get-name-prefix

Returns a copy of the name prefix of object. Caller should g-free the return value after usage. For a prefixless object, this returns NULL, which you can safely g-free as well.

object
a <gst-object>
ret
the name prefix of object. g-free after usage. MT safe. This function grabs and releases object's LOCK.
— Function: gst-object-set-name-prefix (self <gst-object>) (name_prefix mchars)
— Method: set-name-prefix

Sets the name prefix of object to name-prefix. This function makes a copy of the provided name prefix, so the caller retains ownership of the name prefix it sent.

MT safe. This function grabs and releases object's LOCK.

object
a <gst-object>
name-prefix
new name prefix of object
— Function: gst-object-default-error (self <gst-object>) (error <g-error*>) (debug mchars)
— Method: default-error

A default error function.

The default handler will simply print the error string using g_print.

source
the <gst-object> that initiated the error.
error
the GError.
debug
an additional debug information string, or NULL.
— Function: gst-object-check-uniqueness (list glist-of) (name mchars)   (ret bool)

Checks to see if there is any object named name in list. This function does not do any locking of any kind. You might want to protect the provided list with the lock of the owner of the list. This function will lock each <gst-object> in the list to compare the name, so be carefull when passing a list with a locked object.

list
a list of <gst-object> to check through
name
the name to search for
ret
TRUE if a <gst-object> named name does not appear in list, FALSE if it does. MT safe. Grabs and releases the LOCK of each object in the list.
— Function: gst-object-has-ancestor (self <gst-object>) (ancestor <gst-object>)   (ret bool)
— Method: has-ancestor

Check if object has an ancestor ancestor somewhere up in the hierarchy.

object
a <gst-object> to check
ancestor
a <gst-object> to check as ancestor
ret
TRUE if ancestor is an ancestor of object. MT safe. Grabs and releases object's locks.
— Function: gst-object-save-thyself (self <gst-object>) (parent <xml-node-ptr>)   (ret <xml-node-ptr>)
— Method: save-thyself

Saves object into the parent XML node.

object
a <gst-object> to save
parent
The parent XML node to save object into
ret
the new xmlNodePtr with the saved object
— Function: gst-object-restore-thyself (self <gst-object>) (self <xml-node-ptr>)
— Method: restore-thyself

Restores object with the data from the parent XML node.

object
a <gst-object> to load into
self
The XML node to load object from
— Function: gst-object-get-path-string (self <gst-object>)   (ret mchars)
— Method: get-path-string

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

object
a <gst-object>
ret
a string describing the path of object. You must g-free the string after usage. MT safe. Grabs and releases the <gst-object>'s LOCK for all objects in the hierarchy.