Gst::Object Class Reference
gstreamermm Base Classes

A base class for the GStreamer object hierarchy. More...

`#include <gstreamermm/object.h>`

Inheritance diagram for Gst::Object:
[legend]

## Public Member Functions

| Object (Object&& src) noexcept
Object& | operator= (Object&& src) noexcept
| ~Object () noexcept override
GstObject* | gobj ()
| Provides access to the underlying C GObject. More...
const GstObject* | gobj () const
| Provides access to the underlying C GObject. More...
GstObject* | gobj_copy ()
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs. More...
bool | is_element () const
bool | is_element_factory () const
bool | is_pad () const
bool | is_pad_template () const
bool | is_bin () const
guint32 | get_flags () const
| Returns the entire set of flags for the object. More...
bool | set_name (const Glib::ustring& name)
| Sets the name of object, or gives object a guaranteed unique name (if name is `nullptr`). More...
Glib::ustring | get_name () const
| Returns a copy of the name of object. More...
bool | set_parent (const Glib::RefPtr< Gst::Object >& parent)
| Sets the parent of object to parent. More...
Glib::RefPtr< Gst::Object > | get_parent ()
| Returns the parent of object. More...
Glib::RefPtr< const Gst::Object > | get_parent () const
| Returns the parent of object. More...
void | unparent ()
| Clear the parent of object, removing the associated reference. More...
void | set_control_rate (Gst::ClockTime control_rate)
| Change the control-rate for this object. More...
Gst::ClockTime | get_control_rate () const
| Obtain the control-rate for this object. More...
Gst::ClockTime | suggest_next_sync () const
| Returns a suggestion for timestamps where buffers should be split to get best controller results. More...
bool | sync_values (Gst::ClockTime timestamp)
| Sets the properties of the object, according to the Gst::ControlSources that (maybe) handle them and for the given timestamp. More...
void | set_control_bindings_disabled (bool disabled)
| This function is used to disable all controlled properties of the object for some time, i.e. sync_values() will do nothing. More...
bool | has_asctive_control_bindings () const
| Check if the object has an active controlled properties. More...
bool | has_ancestor (const Glib::RefPtr< const Gst::Object >& ancestor) const
| Check if object has an ancestor ancestor somewhere up in the hierarchy. More...
bool | has_as_ancestor (const Glib::RefPtr< Gst::Object >& ancestor) const
| Check if object has an ancestor ancestor somewhere up in the hierarchy. More...
bool | has_as_parent (const Glib::RefPtr< Gst::Object >& parent) const
| Check if parent is the parent of object. More...
Glib::ustring | get_path_string ()
| Generates a string describing the path of object in the object hierarchy. More...
Glib::PropertyProxy< Glib::ustring > | property_name ()
| The name of the object. More...
Glib::PropertyProxy_ReadOnly< Glib::ustring > | property_name () const
| The name of the object. More...
Glib::PropertyProxy< Glib::RefPtr< Gst::Object > > | property_parent ()
| The parent of the object. More...
Glib::PropertyProxy_ReadOnly< Glib::RefPtr< Gst::Object > > | property_parent () const
| The parent of the object. More...
Glib::SignalProxy< void, const Glib::RefPtr< Gst::Object >&, GParamSpec*> | signal_deep_notify ()
int | get_refcount () const

## Static Public Member Functions

static GType | get_type ()
| Get the GType for this class, for use with the underlying GObject type system. More...
static bool | check_uniqueness (const Glib::ListHandle< const Gst::Object >& list, const Glib::ustring& name)
| Checks to see if there is any object named name in list. More...

## Protected Member Functions

virtual void | on_deep_notify (const Glib::RefPtr< Gst::Object >& prop_object, GParamSpec* prop)
| This is a default handler for the signal signal_deep_notify(). More...

## Related Functions

(Note that these are not member functions.)
Glib::RefPtr< Gst::Object > | wrap (GstObject* object, bool take_copy=false)
| A Glib::wrap() method for this object. More...

## Detailed Description

A base class for the GStreamer object hierarchy.

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 Glib::Object. 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 Glib::Object (e.g. Glib::Object::reference() becomes Gst:Object::reference().

In contrast to Glib::Object instances, Gst::Object adds a name property. The functions set_name() and get_name() are used to set/get the name of the object.

Last reviewed on 2016-06-06 (1.8.0)

## Constructor & Destructor Documentation

## Object()

Gst::Object::Object | ( | Object&& | src | ) |

noexcept

## ~Object()

Gst::Object::~Object | ( |  | ) |

override noexcept

## Member Function Documentation

## check_uniqueness()

static bool Gst::Object::check_uniqueness | ( | const Glib::ListHandle< const Gst::Object >& | list,
|  | const Glib::ustring & | name
| ) |  |

static

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 careful when passing a list with a locked object.

Parameters

  list | A list of Gst::Object to check through.
  name | The name to search for.

Returns
  `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.

## get_control_rate()

Gst::ClockTime Gst::Object::get_control_rate | ( |  | ) | const

Obtain the control-rate for this object.

Audio processing Gst::Element objects will use this rate to sub-divide their processing loop and call sync_values() inbetween. The length of the processing segment should be up to control-rate nanoseconds.

If the object is not under property control, this will return Gst::CLOCK_TIME_NONE. This allows the element to avoid the sub-dividing.

The control-rate is not expected to change if the element is in Gst::STATE_PAUSED or Gst::STATE_PLAYING.

Returns
  The control rate in nanoseconds.

## get_flags()

guint32 Gst::Object::get_flags | ( |  | ) | const

Returns the entire set of flags for the object.

## get_name()

Glib::ustring Gst::Object::get_name | ( |  | ) | const

Returns a copy of the name of object.

For a nameless object, this returns `nullptr`, which you can safely Glib::free() as well.

Free-function: g_free

Returns
  The name of object.

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

Examples:
  basics/bin.cc.

## get_parent() [1/2]

Glib::RefPtr<Gst::Object> Gst::Object::get_parent | ( |  | ) |

Returns the parent of object.

This function increases the refcount of the parent object so you should unref() it after usage.

Returns
  Parent of object, this can be `nullptr` if object has no parent. unref after usage.

MT safe. Grabs and releases object's LOCK.

## get_parent() [2/2]

Glib::RefPtr<const Gst::Object> Gst::Object::get_parent | ( |  | ) | const

Returns the parent of object.

This function increases the refcount of the parent object so you should unref() it after usage.

Returns
  Parent of object, this can be `nullptr` if object has no parent. unref after usage.

MT safe. Grabs and releases object's LOCK.

## get_path_string()

Glib::ustring Gst::Object::get_path_string | ( |  | ) |

Generates a string describing the path of object in the object hierarchy.

Only useful (or used) for debugging.

Returns
  A string describing the path of object.

MT safe. Grabs and releases the Gst::Object's LOCK for all objects in the hierarchy.

## get_refcount()

int Gst::Object::get_refcount | ( |  | ) | const

## get_type()

static GType Gst::Object::get_type | ( |  | ) |

static

Get the GType for this class, for use with the underlying GObject type system.

## gobj() [1/2]

GstObject* Gst::Object::gobj | ( |  | ) |

inline

Provides access to the underlying C GObject.

## gobj() [2/2]

const GstObject* Gst::Object::gobj | ( |  | ) | const

inline

Provides access to the underlying C GObject.

## gobj_copy()

GstObject* Gst::Object::gobj_copy | ( |  | ) |

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

## has_ancestor()

bool Gst::Object::has_ancestor | ( | const Glib::RefPtr< const Gst::Object >& | ancestor | ) | const

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

One can e.g. check if a Gst::Element is inside a Gst::Pipeline.

Deprecated: Use has_as_ancestor() instead.

MT safe. Grabs and releases object's locks.

Parameters

  ancestor | A Gst::Object to check as ancestor.

Returns
  `true` if ancestor is an ancestor of object.

## has_as_ancestor()

bool Gst::Object::has_as_ancestor | ( | const Glib::RefPtr< Gst::Object >& | ancestor | ) | const

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

One can e.g. check if a Gst::Element is inside a Gst::Pipeline.

Parameters

  ancestor | A Gst::Object to check as ancestor.

Returns
  `true` if ancestor is an ancestor of object.

MT safe. Grabs and releases object's locks.

## has_as_parent()

bool Gst::Object::has_as_parent | ( | const Glib::RefPtr< Gst::Object >& | parent | ) | const

Check if parent is the parent of object.

E.g. a Gst::Element can check if it owns a given Gst::Pad.

Parameters

  parent | A Gst::Object to check as parent.

Returns
  `false` if either object or parent is `nullptr`. `true` if parent is the parent of object. Otherwise `false`.

MT safe. Grabs and releases object's locks.

## has_asctive_control_bindings()

bool Gst::Object::has_asctive_control_bindings | ( |  | ) | const

Check if the object has an active controlled properties.

Returns
  `true` if the object has active controlled properties.

## is_bin()

bool Gst::Object::is_bin | ( |  | ) | const

## is_element()

bool Gst::Object::is_element | ( |  | ) | const

## is_element_factory()

bool Gst::Object::is_element_factory | ( |  | ) | const

## is_pad()

bool Gst::Object::is_pad | ( |  | ) | const

## is_pad_template()

bool Gst::Object::is_pad_template | ( |  | ) | const

## on_deep_notify()

virtual void Gst::Object::on_deep_notify | ( | const Glib::RefPtr< Gst::Object >& | prop_object,
|  | GParamSpec * | prop
| ) |  |

protected virtual

This is a default handler for the signal signal_deep_notify().

## operator=()

Object& Gst::Object::operator= | ( | Object&& | src | ) |

noexcept

## property_name() [1/2]

Glib::PropertyProxy< Glib::ustring > Gst::Object::property_name | ( |  | ) |

The name of the object.

Returns
  A PropertyProxy that allows you to get or set the value of the property, or receive notification when the value of the property changes.

## property_name() [2/2]

Glib::PropertyProxy_ReadOnly< Glib::ustring > Gst::Object::property_name | ( |  | ) | const

The name of the object.

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

## property_parent() [1/2]

Glib::PropertyProxy< Glib::RefPtr<Gst::Object> > Gst::Object::property_parent | ( |  | ) |

The parent of the object.

Returns
  A PropertyProxy that allows you to get or set the value of the property, or receive notification when the value of the property changes.

## property_parent() [2/2]

Glib::PropertyProxy_ReadOnly< Glib::RefPtr<Gst::Object> > Gst::Object::property_parent | ( |  | ) | const

The parent of the object.

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

## set_control_bindings_disabled()

void Gst::Object::set_control_bindings_disabled | ( | bool | disabled | ) |

This function is used to disable all controlled properties of the object for some time, i.e. sync_values() will do nothing.

Parameters

  disabled | Boolean that specifies whether to disable the controller or not.

## set_control_rate()

void Gst::Object::set_control_rate | ( | Gst::ClockTime | control_rate | ) |

Change the control-rate for this object.

Audio processing Gst::Element objects will use this rate to sub-divide their processing loop and call sync_values() inbetween. The length of the processing segment should be up to control-rate nanoseconds.

The control-rate should not change if the element is in Gst::STATE_PAUSED or Gst::STATE_PLAYING.

Parameters

  control_rate | The new control-rate in nanoseconds.

## set_name()

bool Gst::Object::set_name | ( | const Glib::ustring & | name | ) |

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

This function makes a copy of the provided name, so the caller retains ownership of the name it sent.

Parameters

  name | New name of object.

Returns
  `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.

## set_parent()

bool Gst::Object::set_parent | ( | const Glib::RefPtr< Gst::Object >& | parent | ) |

Sets the parent of object to parent.

The object's reference count will be incremented, and any floating reference will be removed (see ref_sink()).

Parameters

  parent | New parent of object.

Returns
  `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.

## signal_deep_notify()

Glib::SignalProxy< void,const Glib::RefPtr<Gst::Object>&,GParamSpec* > Gst::Object::signal_deep_notify | ( |  | ) |

Slot Prototype:
  `void on_my_deep_notify(const Glib::RefPtr<Gst::Object>& prop_object, GParamSpec* prop)`

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.

Parameters

  prop_object | The object that originated the signal.
  prop | The property that changed.

## suggest_next_sync()

Gst::ClockTime Gst::Object::suggest_next_sync | ( |  | ) | const

Returns a suggestion for timestamps where buffers should be split to get best controller results.

Returns
  Returns the suggested timestamp or Gst::CLOCK_TIME_NONE if no control-rate was set.

## sync_values()

bool Gst::Object::sync_values | ( | Gst::ClockTime | timestamp | ) |

Sets the properties of the object, according to the Gst::ControlSources that (maybe) handle them and for the given timestamp.

If this function fails, it is most likely the application developers fault. Most probably the control sources are not setup correctly.

Parameters

  timestamp | The time that should be processed.

Returns
  `true` if the controller values could be applied to the object properties, `false` otherwise.

## unparent()

void Gst::Object::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.

## Friends And Related Function Documentation

## wrap()

Glib::RefPtr< Gst::Object > wrap | ( | GstObject * | object,
|  | bool | take_copy = `false`
| ) |  |

related

A Glib::wrap() method for this object.

Parameters

  object | The C instance.
  take_copy | False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns
  A C++ instance that wraps this C instance.