gst/gstobject.c

   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.c: Fundamental class used for all of GStreamer
   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., 51 Franklin St, Fifth Floor,
  21  * Boston, MA 02110-1301, USA.
  22  */
  23
  24 /**
  25  * SECTION:gstobject
  26  * @short_description: Base class for the GStreamer object hierarchy
  27  *
  28  * #GstObject provides a root for the object hierarchy tree filed in by the
  29  * GStreamer library.  It is currently a thin wrapper on top of
  30  * #GInitiallyUnowned. It is an abstract class that is not very usable on its own.
  31  *
  32  * #GstObject gives us basic refcounting, parenting functionality and locking.
  33  * Most of the functions are just extended for special GStreamer needs and can be
  34  * found under the same name in the base class of #GstObject which is #GObject
  35  * (e.g. g_object_ref() becomes gst_object_ref()).
  36  *
  37  * Since #GstObject derives from #GInitiallyUnowned, it also inherits the
  38  * floating reference. Be aware that functions such as gst_bin_add() and
  39  * gst_element_add_pad() take ownership of the floating reference.
  40  *
  41  * In contrast to #GObject instances, #GstObject adds a name property. The functions
  42  * gst_object_set_name() and gst_object_get_name() are used to set/get the name
  43  * of the object.
  44  *
  45  * <refsect2>
  46  * <title>controlled properties</title>
  47  * <para>
  48  * Controlled properties offers a lightweight way to adjust gobject properties
  49  * over stream-time. It works by using time-stamped value pairs that are queued
  50  * for element-properties. At run-time the elements continuously pull value
  51  * changes for the current stream-time.
  52  *
  53  * What needs to be changed in a #GstElement?
  54  * Very little - it is just two steps to make a plugin controllable!
  55  * <orderedlist>
  56  *   <listitem><para>
  57  *     mark gobject-properties paramspecs that make sense to be controlled,
  58  *     by GST_PARAM_CONTROLLABLE.
  59  *   </para></listitem>
  60  *   <listitem><para>
  61  *     when processing data (get, chain, loop function) at the beginning call
  62  *     gst_object_sync_values(element,timestamp).
  63  *     This will make the controller update all GObject properties that are
  64  *     under its control with the current values based on the timestamp.
  65  *   </para></listitem>
  66  * </orderedlist>
  67  *
  68  * What needs to be done in applications?
  69  * Again it's not a lot to change.
  70  * <orderedlist>
  71  *   <listitem><para>
  72  *     create a #GstControlSource.
  73  *     csource = gst_interpolation_control_source_new ();
  74  *     g_object_set (csource, "mode", GST_INTERPOLATION_MODE_LINEAR, NULL);
  75  *   </para></listitem>
  76  *   <listitem><para>
  77  *     Attach the #GstControlSource on the controller to a property.
  78  *     gst_object_add_control_binding (object, gst_direct_control_binding_new (object, "prop1", csource));
  79  *   </para></listitem>
  80  *   <listitem><para>
  81  *     Set the control values
  82  *     gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,0 * GST_SECOND, value1);
  83  *     gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,1 * GST_SECOND, value2);
  84  *   </para></listitem>
  85  *   <listitem><para>
  86  *     start your pipeline
  87  *   </para></listitem>
  88  * </orderedlist>
  89  * </para>
  90  * </refsect2>
  91  */
  92
  93 #include "gst_private.h"
  94 #include "glib-compat-private.h"
  95
  96 #include "gstobject.h"
  97 #include "gstclock.h"
  98 #include "gstcontrolbinding.h"
  99 #include "gstcontrolsource.h"
 100 #include "gstinfo.h"
 101 #include "gstparamspecs.h"
 102 #include "gstutils.h"
 103
 104 #define DEBUG_REFCOUNT
 105
 106 /* Object signals and args */
 107 enum
 108 {
 109   DEEP_NOTIFY,
 110   LAST_SIGNAL
 111 };
 112
 113 enum
 114 {
 115   PROP_0,
 116   PROP_NAME,
 117   PROP_PARENT,
 118   PROP_LAST
 119 };
 120
 121 enum
 122 {
 123   SO_OBJECT_LOADED,
 124   SO_LAST_SIGNAL
 125 };
 126
 127 /* maps type name quark => count */
 128 static GData *object_name_counts = NULL;
 129
 130 G_LOCK_DEFINE_STATIC (object_name_mutex);
 131
 132 static void gst_object_set_property (GObject * object, guint prop_id,
 133     const GValue * value, GParamSpec * pspec);
 134 static void gst_object_get_property (GObject * object, guint prop_id,
 135     GValue * value, GParamSpec * pspec);
 136
 137 static void gst_object_dispatch_properties_changed (GObject * object,
 138     guint n_pspecs, GParamSpec ** pspecs);
 139
 140 static void gst_object_dispose (GObject * object);
 141 static void gst_object_finalize (GObject * object);
 142
 143 static gboolean gst_object_set_name_default (GstObject * object);
 144
 145 static guint gst_object_signals[LAST_SIGNAL] = { 0 };
 146
 147 static GParamSpec *properties[PROP_LAST];
 148
 149 G_DEFINE_ABSTRACT_TYPE (GstObject, gst_object, G_TYPE_INITIALLY_UNOWNED);
 150
 151 static void
 152 gst_object_constructed (GObject * object)
 153 {
 154   GST_TRACER_OBJECT_CREATED (GST_OBJECT_CAST (object));
 155
 156   ((GObjectClass *) gst_object_parent_class)->constructed (object);
 157 }
 158
 159 static void
 160 gst_object_class_init (GstObjectClass * klass)
 161 {
 162   GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
 163
 164   gobject_class->set_property = gst_object_set_property;
 165   gobject_class->get_property = gst_object_get_property;
 166
 167   properties[PROP_NAME] =
 168       g_param_spec_string ("name", "Name", "The name of the object", NULL,
 169       G_PARAM_READWRITE | G_PARAM_CONSTRUCT | G_PARAM_STATIC_STRINGS);
 170
 171   /**
 172    * GstObject:parent:
 173    *
 174    * The parent of the object. Please note, that when changing the 'parent'
 175    * property, we don't emit #GObject::notify and #GstObject::deep-notify
 176    * signals due to locking issues. In some cases one can use
 177    * #GstBin::element-added or #GstBin::element-removed signals on the parent to
 178    * achieve a similar effect.
 179    */
 180   properties[PROP_PARENT] =
 181       g_param_spec_object ("parent", "Parent", "The parent of the object",
 182       GST_TYPE_OBJECT, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
 183
 184   g_object_class_install_properties (gobject_class, PROP_LAST, properties);
 185
 186   /**
 187    * GstObject::deep-notify:
 188    * @gstobject: a #GstObject
 189    * @prop_object: the object that originated the signal
 190    * @prop: the property that changed
 191    *
 192    * The deep notify signal is used to be notified of property changes. It is
 193    * typically attached to the toplevel bin to receive notifications from all
 194    * the elements contained in that bin.
 195    */
 196   gst_object_signals[DEEP_NOTIFY] =
 197       g_signal_new ("deep-notify", G_TYPE_FROM_CLASS (klass),
 198       G_SIGNAL_RUN_FIRST | G_SIGNAL_NO_RECURSE | G_SIGNAL_DETAILED |
 199       G_SIGNAL_NO_HOOKS, G_STRUCT_OFFSET (GstObjectClass, deep_notify), NULL,
 200       NULL, g_cclosure_marshal_generic, G_TYPE_NONE, 2, GST_TYPE_OBJECT,
 201       G_TYPE_PARAM);
 202
 203   klass->path_string_separator = "/";
 204
 205   /* see the comments at gst_object_dispatch_properties_changed */
 206   gobject_class->dispatch_properties_changed
 207       = GST_DEBUG_FUNCPTR (gst_object_dispatch_properties_changed);
 208
 209   gobject_class->constructed = gst_object_constructed;
 210   gobject_class->dispose = gst_object_dispose;
 211   gobject_class->finalize = gst_object_finalize;
 212 }
 213
 214 static void
 215 gst_object_init (GstObject * object)
 216 {
 217   g_mutex_init (&object->lock);
 218   object->parent = NULL;
 219   object->name = NULL;
 220   GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object, "%p new", object);
 221
 222   object->flags = 0;
 223
 224   object->control_rate = 100 * GST_MSECOND;
 225   object->last_sync = GST_CLOCK_TIME_NONE;
 226 }
 227
 228 /**
 229  * gst_object_ref:
 230  * @object: (type Gst.Object): a #GstObject to reference
 231  *
 232  * Increments the reference count on @object. This function
 233  * does not take the lock on @object because it relies on
 234  * atomic refcounting.
 235  *
 236  * This object returns the input parameter to ease writing
 237  * constructs like :
 238  *  result = gst_object_ref (object->parent);
 239  *
 240  * Returns: (transfer full) (type Gst.Object): A pointer to @object
 241  */
 242 gpointer
 243 gst_object_ref (gpointer object)
 244 {
 245   g_return_val_if_fail (object != NULL, NULL);
 246
 247   GST_TRACER_OBJECT_REFFED (object, ((GObject *) object)->ref_count + 1);
 248 #ifdef DEBUG_REFCOUNT
 249   GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object, "%p ref %d->%d", object,
 250       ((GObject *) object)->ref_count, ((GObject *) object)->ref_count + 1);
 251 #endif
 252   g_object_ref (object);
 253
 254   return object;
 255 }
 256
 257 /**
 258  * gst_object_unref:
 259  * @object: (type Gst.Object): a #GstObject to unreference
 260  *
 261  * Decrements the reference count on @object.  If reference count hits
 262  * zero, destroy @object. This function does not take the lock
 263  * on @object as it relies on atomic refcounting.
 264  *
 265  * The unref method should never be called with the LOCK held since
 266  * this might deadlock the dispose function.
 267  */
 268 void
 269 gst_object_unref (gpointer object)
 270 {
 271   g_return_if_fail (object != NULL);
 272   g_return_if_fail (((GObject *) object)->ref_count > 0);
 273
 274   GST_TRACER_OBJECT_UNREFFED (object, ((GObject *) object)->ref_count - 1);
 275 #ifdef DEBUG_REFCOUNT
 276   GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object, "%p unref %d->%d", object,
 277       ((GObject *) object)->ref_count, ((GObject *) object)->ref_count - 1);
 278 #endif
 279   g_object_unref (object);
 280 }
 281
 282 /**
 283  * gst_object_ref_sink: (skip)
 284  * @object: a #GstObject to sink
 285  *
 286  * Increase the reference count of @object, and possibly remove the floating
 287  * reference, if @object has a floating reference.
 288  *
 289  * In other words, if the object is floating, then this call "assumes ownership"
 290  * of the floating reference, converting it to a normal reference by clearing
 291  * the floating flag while leaving the reference count unchanged. If the object
 292  * is not floating, then this call adds a new normal reference increasing the
 293  * reference count by one.
 294  */
 295 gpointer
 296 gst_object_ref_sink (gpointer object)
 297 {
 298   g_return_val_if_fail (object != NULL, NULL);
 299
 300 #ifdef DEBUG_REFCOUNT
 301   GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object, "%p ref_sink %d->%d",
 302       object, ((GObject *) object)->ref_count,
 303       ((GObject *) object)->ref_count + 1);
 304 #endif
 305   return g_object_ref_sink (object);
 306 }
 307
 308 /**
 309  * gst_object_replace:
 310  * @oldobj: (inout) (transfer full) (nullable): pointer to a place of
 311  *     a #GstObject to replace
 312  * @newobj: (transfer none) (allow-none): a new #GstObject
 313  *
 314  * Atomically modifies a pointer to point to a new object.
 315  * The reference count of @oldobj is decreased and the reference count of
 316  * @newobj is increased.
 317  *
 318  * Either @newobj and the value pointed to by @oldobj may be %NULL.
 319  *
 320  * Returns: %TRUE if @newobj was different from @oldobj
 321  */
 322 gboolean
 323 gst_object_replace (GstObject ** oldobj, GstObject * newobj)
 324 {
 325   GstObject *oldptr;
 326
 327   g_return_val_if_fail (oldobj != NULL, FALSE);
 328
 329 #ifdef DEBUG_REFCOUNT
 330   GST_CAT_TRACE (GST_CAT_REFCOUNTING, "replace %p %s (%d) with %p %s (%d)",
 331       *oldobj, *oldobj ? GST_STR_NULL (GST_OBJECT_NAME (*oldobj)) : "(NONE)",
 332       *oldobj ? G_OBJECT (*oldobj)->ref_count : 0,
 333       newobj, newobj ? GST_STR_NULL (GST_OBJECT_NAME (newobj)) : "(NONE)",
 334       newobj ? G_OBJECT (newobj)->ref_count : 0);
 335 #endif
 336
 337   oldptr = g_atomic_pointer_get ((gpointer *) oldobj);
 338
 339   if (G_UNLIKELY (oldptr == newobj))
 340     return FALSE;
 341
 342   if (newobj)
 343     gst_object_ref (newobj);
 344
 345   while (G_UNLIKELY (!g_atomic_pointer_compare_and_exchange ((gpointer *)
 346               oldobj, oldptr, newobj))) {
 347     oldptr = g_atomic_pointer_get ((gpointer *) oldobj);
 348     if (G_UNLIKELY (oldptr == newobj))
 349       break;
 350   }
 351
 352   if (oldptr)
 353     gst_object_unref (oldptr);
 354
 355   return oldptr != newobj;
 356 }
 357
 358 /* dispose is called when the object has to release all links
 359  * to other objects */
 360 static void
 361 gst_object_dispose (GObject * object)
 362 {
 363   GstObject *self = (GstObject *) object;
 364   GstObject *parent;
 365
 366   GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object, "%p dispose", object);
 367
 368   GST_OBJECT_LOCK (object);
 369   if ((parent = GST_OBJECT_PARENT (object)))
 370     goto have_parent;
 371   GST_OBJECT_PARENT (object) = NULL;
 372   GST_OBJECT_UNLOCK (object);
 373
 374   if (self->control_bindings) {
 375     GList *node;
 376
 377     for (node = self->control_bindings; node; node = g_list_next (node)) {
 378       gst_object_unparent (node->data);
 379     }
 380     g_list_free (self->control_bindings);
 381     self->control_bindings = NULL;
 382   }
 383
 384   ((GObjectClass *) gst_object_parent_class)->dispose (object);
 385
 386   return;
 387
 388   /* ERRORS */
 389 have_parent:
 390   {
 391     g_critical ("\nTrying to dispose object \"%s\", but it still has a "
 392         "parent \"%s\".\nYou need to let the parent manage the "
 393         "object instead of unreffing the object directly.\n",
 394         GST_OBJECT_NAME (object), GST_OBJECT_NAME (parent));
 395     GST_OBJECT_UNLOCK (object);
 396     /* ref the object again to revive it in this error case */
 397     gst_object_ref (object);
 398     return;
 399   }
 400 }
 401
 402 /* finalize is called when the object has to free its resources */
 403 static void
 404 gst_object_finalize (GObject * object)
 405 {
 406   GstObject *gstobject = GST_OBJECT_CAST (object);
 407
 408   GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object, "%p finalize", object);
 409
 410   g_signal_handlers_destroy (object);
 411
 412   g_free (gstobject->name);
 413   g_mutex_clear (&gstobject->lock);
 414
 415   GST_TRACER_OBJECT_DESTROYED (gstobject);
 416
 417   ((GObjectClass *) gst_object_parent_class)->finalize (object);
 418 }
 419
 420 /* Changing a GObject property of a GstObject will result in "deep-notify"
 421  * signals being emitted by the object itself, as well as in each parent
 422  * object. This is so that an application can connect a listener to the
 423  * top-level bin to catch property-change notifications for all contained
 424  * elements.
 425  *
 426  * MT safe.
 427  */
 428 static void
 429 gst_object_dispatch_properties_changed (GObject * object,
 430     guint n_pspecs, GParamSpec ** pspecs)
 431 {
 432   GstObject *gst_object, *parent, *old_parent;
 433   guint i;
 434 #ifndef GST_DISABLE_GST_DEBUG
 435   gchar *name = NULL;
 436   const gchar *debug_name;
 437 #endif
 438
 439   /* do the standard dispatching */
 440   ((GObjectClass *)
 441       gst_object_parent_class)->dispatch_properties_changed (object, n_pspecs,
 442       pspecs);
 443
 444   gst_object = GST_OBJECT_CAST (object);
 445 #ifndef GST_DISABLE_GST_DEBUG
 446   if (G_UNLIKELY (_gst_debug_min >= GST_LEVEL_LOG)) {
 447     name = gst_object_get_name (gst_object);
 448     debug_name = GST_STR_NULL (name);
 449   } else
 450     debug_name = "";
 451 #endif
 452
 453   /* now let the parent dispatch those, too */
 454   parent = gst_object_get_parent (gst_object);
 455   while (parent) {
 456     for (i = 0; i < n_pspecs; i++) {
 457       GST_CAT_LOG_OBJECT (GST_CAT_PROPERTIES, parent,
 458           "deep notification from %s (%s)", debug_name, pspecs[i]->name);
 459
 460       g_signal_emit (parent, gst_object_signals[DEEP_NOTIFY],
 461           g_quark_from_string (pspecs[i]->name), gst_object, pspecs[i]);
 462     }
 463
 464     old_parent = parent;
 465     parent = gst_object_get_parent (old_parent);
 466     gst_object_unref (old_parent);
 467   }
 468 #ifndef GST_DISABLE_GST_DEBUG
 469   g_free (name);
 470 #endif
 471 }
 472
 473 /**
 474  * gst_object_default_deep_notify:
 475  * @object: the #GObject that signalled the notify.
 476  * @orig: a #GstObject that initiated the notify.
 477  * @pspec: a #GParamSpec of the property.
 478  * @excluded_props: (array zero-terminated=1) (element-type gchar*) (allow-none):
 479  *     a set of user-specified properties to exclude or %NULL to show
 480  *     all changes.
 481  *
 482  * A default deep_notify signal callback for an object. The user data
 483  * should contain a pointer to an array of strings that should be excluded
 484  * from the notify. The default handler will print the new value of the property
 485  * using g_print.
 486  *
 487  * MT safe. This function grabs and releases @object's LOCK for getting its
 488  *          path string.
 489  */
 490 void
 491 gst_object_default_deep_notify (GObject * object, GstObject * orig,
 492     GParamSpec * pspec, gchar ** excluded_props)
 493 {
 494   GValue value = { 0, };        /* the important thing is that value.type = 0 */
 495   gchar *str = NULL;
 496   gchar *name = NULL;
 497
 498   if (pspec->flags & G_PARAM_READABLE) {
 499     /* let's not print these out for excluded properties... */
 500     while (excluded_props != NULL && *excluded_props != NULL) {
 501       if (strcmp (pspec->name, *excluded_props) == 0)
 502         return;
 503       excluded_props++;
 504     }
 505     g_value_init (&value, pspec->value_type);
 506     g_object_get_property (G_OBJECT (orig), pspec->name, &value);
 507
 508     if (G_VALUE_HOLDS_STRING (&value))
 509       str = g_value_dup_string (&value);
 510     else
 511       str = gst_value_serialize (&value);
 512     name = gst_object_get_path_string (orig);
 513     g_print ("%s: %s = %s\n", name, pspec->name, str);
 514     g_free (name);
 515     g_free (str);
 516     g_value_unset (&value);
 517   } else {
 518     name = gst_object_get_path_string (orig);
 519     g_warning ("Parameter %s not readable in %s.", pspec->name, name);
 520     g_free (name);
 521   }
 522 }
 523
 524 static gboolean
 525 gst_object_set_name_default (GstObject * object)
 526 {
 527   const gchar *type_name;
 528   gint count;
 529   gchar *name;
 530   GQuark q;
 531   guint i, l;
 532
 533   /* to ensure guaranteed uniqueness across threads, only one thread
 534    * may ever assign a name */
 535   G_LOCK (object_name_mutex);
 536
 537   if (!object_name_counts) {
 538     g_datalist_init (&object_name_counts);
 539   }
 540
 541   q = g_type_qname (G_OBJECT_TYPE (object));
 542   count = GPOINTER_TO_INT (g_datalist_id_get_data (&object_name_counts, q));
 543   g_datalist_id_set_data (&object_name_counts, q, GINT_TO_POINTER (count + 1));
 544
 545   G_UNLOCK (object_name_mutex);
 546
 547   /* GstFooSink -> foosink<N> */
 548   type_name = g_quark_to_string (q);
 549   if (strncmp (type_name, "Gst", 3) == 0)
 550     type_name += 3;
 551   /* give the 20th "queue" element and the first "queue2" different names */
 552   l = strlen (type_name);
 553   if (l > 0 && g_ascii_isdigit (type_name[l - 1])) {
 554     name = g_strdup_printf ("%s-%d", type_name, count);
 555   } else {
 556     name = g_strdup_printf ("%s%d", type_name, count);
 557   }
 558
 559   l = strlen (name);
 560   for (i = 0; i < l; i++)
 561     name[i] = g_ascii_tolower (name[i]);
 562
 563   GST_OBJECT_LOCK (object);
 564   if (G_UNLIKELY (object->parent != NULL))
 565     goto had_parent;
 566
 567   g_free (object->name);
 568   object->name = name;
 569
 570   GST_OBJECT_UNLOCK (object);
 571
 572   return TRUE;
 573
 574 had_parent:
 575   {
 576     g_free (name);
 577     GST_WARNING ("parented objects can't be renamed");
 578     GST_OBJECT_UNLOCK (object);
 579     return FALSE;
 580   }
 581 }
 582
 583 /**
 584  * gst_object_set_name:
 585  * @object: a #GstObject
 586  * @name: (allow-none): new name of object
 587  *
 588  * Sets the name of @object, or gives @object a guaranteed unique
 589  * name (if @name is %NULL).
 590  * This function makes a copy of the provided name, so the caller
 591  * retains ownership of the name it sent.
 592  *
 593  * Returns: %TRUE if the name could be set. Since Objects that have
 594  * a parent cannot be renamed, this function returns %FALSE in those
 595  * cases.
 596  *
 597  * MT safe.  This function grabs and releases @object's LOCK.
 598  */
 599 gboolean
 600 gst_object_set_name (GstObject * object, const gchar * name)
 601 {
 602   gboolean result;
 603
 604   g_return_val_if_fail (GST_IS_OBJECT (object), FALSE);
 605
 606   GST_OBJECT_LOCK (object);
 607
 608   /* parented objects cannot be renamed */
 609   if (G_UNLIKELY (object->parent != NULL))
 610     goto had_parent;
 611
 612   if (name != NULL) {
 613     g_free (object->name);
 614     object->name = g_strdup (name);
 615     GST_OBJECT_UNLOCK (object);
 616     result = TRUE;
 617   } else {
 618     GST_OBJECT_UNLOCK (object);
 619     result = gst_object_set_name_default (object);
 620   }
 621
 622   g_object_notify (G_OBJECT (object), "name");
 623   return result;
 624
 625   /* error */
 626 had_parent:
 627   {
 628     GST_WARNING ("parented objects can't be renamed");
 629     GST_OBJECT_UNLOCK (object);
 630     return FALSE;
 631   }
 632 }
 633
 634 /**
 635  * gst_object_get_name:
 636  * @object: a #GstObject
 637  *
 638  * Returns a copy of the name of @object.
 639  * Caller should g_free() the return value after usage.
 640  * For a nameless object, this returns %NULL, which you can safely g_free()
 641  * as well.
 642  *
 643  * Free-function: g_free
 644  *
 645  * Returns: (transfer full) (nullable): the name of @object. g_free()
 646  * after usage.
 647  *
 648  * MT safe. This function grabs and releases @object's LOCK.
 649  */
 650 gchar *
 651 gst_object_get_name (GstObject * object)
 652 {
 653   gchar *result = NULL;
 654
 655   g_return_val_if_fail (GST_IS_OBJECT (object), NULL);
 656
 657   GST_OBJECT_LOCK (object);
 658   result = g_strdup (object->name);
 659   GST_OBJECT_UNLOCK (object);
 660
 661   return result;
 662 }
 663
 664 /**
 665  * gst_object_set_parent:
 666  * @object: a #GstObject
 667  * @parent: new parent of object
 668  *
 669  * Sets the parent of @object to @parent. The object's reference count will
 670  * be incremented, and any floating reference will be removed (see gst_object_ref_sink()).
 671  *
 672  * Returns: %TRUE if @parent could be set or %FALSE when @object
 673  * already had a parent or @object and @parent are the same.
 674  *
 675  * MT safe. Grabs and releases @object's LOCK.
 676  */
 677 gboolean
 678 gst_object_set_parent (GstObject * object, GstObject * parent)
 679 {
 680   g_return_val_if_fail (GST_IS_OBJECT (object), FALSE);
 681   g_return_val_if_fail (GST_IS_OBJECT (parent), FALSE);
 682   g_return_val_if_fail (object != parent, FALSE);
 683
 684   GST_CAT_DEBUG_OBJECT (GST_CAT_REFCOUNTING, object,
 685       "set parent (ref and sink)");
 686
 687   GST_OBJECT_LOCK (object);
 688   if (G_UNLIKELY (object->parent != NULL))
 689     goto had_parent;
 690
 691   object->parent = parent;
 692   gst_object_ref_sink (object);
 693   GST_OBJECT_UNLOCK (object);
 694
 695   /* FIXME-2.0: this does not work, the deep notify takes the lock from the
 696    * parent object and deadlocks when the parent holds its lock when calling
 697    * this function (like _element_add_pad()), we need to use a GRecMutex
 698    * for locking the parent instead.
 699    */
 700   /* g_object_notify_by_pspec ((GObject *)object, properties[PROP_PARENT]); */
 701
 702   return TRUE;
 703
 704   /* ERROR handling */
 705 had_parent:
 706   {
 707     GST_CAT_DEBUG_OBJECT (GST_CAT_REFCOUNTING, object,
 708         "set parent failed, object already had a parent");
 709     GST_OBJECT_UNLOCK (object);
 710     return FALSE;
 711   }
 712 }
 713
 714 /**
 715  * gst_object_get_parent:
 716  * @object: a #GstObject
 717  *
 718  * Returns the parent of @object. This function increases the refcount
 719  * of the parent object so you should gst_object_unref() it after usage.
 720  *
 721  * Returns: (transfer full) (nullable): parent of @object, this can be
 722  *   %NULL if @object has no parent. unref after usage.
 723  *
 724  * MT safe. Grabs and releases @object's LOCK.
 725  */
 726 GstObject *
 727 gst_object_get_parent (GstObject * object)
 728 {
 729   GstObject *result = NULL;
 730
 731   g_return_val_if_fail (GST_IS_OBJECT (object), NULL);
 732
 733   GST_OBJECT_LOCK (object);
 734   result = object->parent;
 735   if (G_LIKELY (result))
 736     gst_object_ref (result);
 737   GST_OBJECT_UNLOCK (object);
 738
 739   return result;
 740 }
 741
 742 /**
 743  * gst_object_unparent:
 744  * @object: a #GstObject to unparent
 745  *
 746  * Clear the parent of @object, removing the associated reference.
 747  * This function decreases the refcount of @object.
 748  *
 749  * MT safe. Grabs and releases @object's lock.
 750  */
 751 void
 752 gst_object_unparent (GstObject * object)
 753 {
 754   GstObject *parent;
 755
 756   g_return_if_fail (GST_IS_OBJECT (object));
 757
 758   GST_OBJECT_LOCK (object);
 759   parent = object->parent;
 760
 761   if (G_LIKELY (parent != NULL)) {
 762     GST_CAT_TRACE_OBJECT (GST_CAT_REFCOUNTING, object, "unparent");
 763     object->parent = NULL;
 764     GST_OBJECT_UNLOCK (object);
 765
 766     /* g_object_notify_by_pspec ((GObject *)object, properties[PROP_PARENT]); */
 767
 768     gst_object_unref (object);
 769   } else {
 770     GST_OBJECT_UNLOCK (object);
 771   }
 772 }
 773
 774 /**
 775  * gst_object_has_as_parent:
 776  * @object: a #GstObject to check
 777  * @parent: a #GstObject to check as parent
 778  *
 779  * Check if @parent is the parent of @object.
 780  * E.g. a #GstElement can check if it owns a given #GstPad.
 781  *
 782  * Returns: %FALSE if either @object or @parent is %NULL. %TRUE if @parent is
 783  *          the parent of @object. Otherwise %FALSE.
 784  *
 785  * MT safe. Grabs and releases @object's locks.
 786  * Since: 1.6
 787  */
 788 gboolean
 789 gst_object_has_as_parent (GstObject * object, GstObject * parent)
 790 {
 791   gboolean result = FALSE;
 792
 793   if (G_LIKELY (GST_IS_OBJECT (object) && GST_IS_OBJECT (parent))) {
 794     GST_OBJECT_LOCK (object);
 795     result = GST_OBJECT_PARENT (object) == parent;
 796     GST_OBJECT_UNLOCK (object);
 797   }
 798
 799   return result;
 800 }
 801
 802 /**
 803  * gst_object_has_as_ancestor:
 804  * @object: a #GstObject to check
 805  * @ancestor: a #GstObject to check as ancestor
 806  *
 807  * Check if @object has an ancestor @ancestor somewhere up in
 808  * the hierarchy. One can e.g. check if a #GstElement is inside a #GstPipeline.
 809  *
 810  * Returns: %TRUE if @ancestor is an ancestor of @object.
 811  *
 812  * MT safe. Grabs and releases @object's locks.
 813  */
 814 gboolean
 815 gst_object_has_as_ancestor (GstObject * object, GstObject * ancestor)
 816 {
 817   GstObject *parent, *tmp;
 818
 819   if (!ancestor || !object)
 820     return FALSE;
 821
 822   parent = gst_object_ref (object);
 823   do {
 824     if (parent == ancestor) {
 825       gst_object_unref (parent);
 826       return TRUE;
 827     }
 828
 829     tmp = gst_object_get_parent (parent);
 830     gst_object_unref (parent);
 831     parent = tmp;
 832   } while (parent);
 833
 834   return FALSE;
 835 }
 836
 837 /**
 838  * gst_object_has_ancestor:
 839  * @object: a #GstObject to check
 840  * @ancestor: a #GstObject to check as ancestor
 841  *
 842  * Check if @object has an ancestor @ancestor somewhere up in
 843  * the hierarchy. One can e.g. check if a #GstElement is inside a #GstPipeline.
 844  *
 845  * Returns: %TRUE if @ancestor is an ancestor of @object.
 846  *
 847  * Deprecated: Use gst_object_has_as_ancestor() instead.
 848  *
 849  * MT safe. Grabs and releases @object's locks.
 850  */
 851 /* FIXME 2.0: remove */
 852 #ifndef GST_REMOVE_DEPRECATED
 853 #ifdef GST_DISABLE_DEPRECATED
 854 gboolean gst_object_has_ancestor (GstObject * object, GstObject * ancestor);
 855 #endif
 856 gboolean
 857 gst_object_has_ancestor (GstObject * object, GstObject * ancestor)
 858 {
 859   return gst_object_has_as_ancestor (object, ancestor);
 860 }
 861 #endif
 862
 863 /**
 864  * gst_object_check_uniqueness:
 865  * @list: (transfer none) (element-type Gst.Object): a list of #GstObject to
 866  *      check through
 867  * @name: the name to search for
 868  *
 869  * Checks to see if there is any object named @name in @list. This function
 870  * does not do any locking of any kind. You might want to protect the
 871  * provided list with the lock of the owner of the list. This function
 872  * will lock each #GstObject in the list to compare the name, so be
 873  * careful when passing a list with a locked object.
 874  *
 875  * Returns: %TRUE if a #GstObject named @name does not appear in @list,
 876  * %FALSE if it does.
 877  *
 878  * MT safe. Grabs and releases the LOCK of each object in the list.
 879  */
 880 gboolean
 881 gst_object_check_uniqueness (GList * list, const gchar * name)
 882 {
 883   gboolean result = TRUE;
 884
 885   g_return_val_if_fail (name != NULL, FALSE);
 886
 887   for (; list; list = g_list_next (list)) {
 888     GstObject *child;
 889     gboolean eq;
 890
 891     child = GST_OBJECT_CAST (list->data);
 892
 893     GST_OBJECT_LOCK (child);
 894     eq = strcmp (GST_OBJECT_NAME (child), name) == 0;
 895     GST_OBJECT_UNLOCK (child);
 896
 897     if (G_UNLIKELY (eq)) {
 898       result = FALSE;
 899       break;
 900     }
 901   }
 902   return result;
 903 }
 904
 905
 906 static void
 907 gst_object_set_property (GObject * object, guint prop_id,
 908     const GValue * value, GParamSpec * pspec)
 909 {
 910   GstObject *gstobject;
 911
 912   gstobject = GST_OBJECT_CAST (object);
 913
 914   switch (prop_id) {
 915     case PROP_NAME:
 916       gst_object_set_name (gstobject, g_value_get_string (value));
 917       break;
 918     case PROP_PARENT:
 919       gst_object_set_parent (gstobject, g_value_get_object (value));
 920       break;
 921     default:
 922       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 923       break;
 924   }
 925 }
 926
 927 static void
 928 gst_object_get_property (GObject * object, guint prop_id,
 929     GValue * value, GParamSpec * pspec)
 930 {
 931   GstObject *gstobject;
 932
 933   gstobject = GST_OBJECT_CAST (object);
 934
 935   switch (prop_id) {
 936     case PROP_NAME:
 937       g_value_take_string (value, gst_object_get_name (gstobject));
 938       break;
 939     case PROP_PARENT:
 940       g_value_take_object (value, gst_object_get_parent (gstobject));
 941       break;
 942     default:
 943       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 944       break;
 945   }
 946 }
 947
 948 /**
 949  * gst_object_get_path_string:
 950  * @object: a #GstObject
 951  *
 952  * Generates a string describing the path of @object in
 953  * the object hierarchy. Only useful (or used) for debugging.
 954  *
 955  * Free-function: g_free
 956  *
 957  * Returns: (transfer full): a string describing the path of @object. You must
 958  *          g_free() the string after usage.
 959  *
 960  * MT safe. Grabs and releases the #GstObject's LOCK for all objects
 961  *          in the hierarchy.
 962  */
 963 gchar *
 964 gst_object_get_path_string (GstObject * object)
 965 {
 966   GSList *parentage;
 967   GSList *parents;
 968   void *parent;
 969   gchar *prevpath, *path;
 970   const gchar *typename;
 971   gchar *component;
 972   const gchar *separator;
 973
 974   /* ref object before adding to list */
 975   gst_object_ref (object);
 976   parentage = g_slist_prepend (NULL, object);
 977
 978   path = g_strdup ("");
 979
 980   /* first walk the object hierarchy to build a list of the parents,
 981    * be careful here with refcounting. */
 982   do {
 983     if (GST_IS_OBJECT (object)) {
 984       parent = gst_object_get_parent (object);
 985       /* add parents to list, refcount remains increased while
 986        * we handle the object */
 987       if (parent)
 988         parentage = g_slist_prepend (parentage, parent);
 989     } else {
 990       break;
 991     }
 992     object = parent;
 993   } while (object != NULL);
 994
 995   /* then walk the parent list and print them out. we need to
 996    * decrease the refcounting on each element after we handled
 997    * it. */
 998   for (parents = parentage; parents; parents = g_slist_next (parents)) {
 999     if (G_IS_OBJECT (parents->data)) {
1000       typename = G_OBJECT_TYPE_NAME (parents->data);
1001     } else {
1002       typename = NULL;
1003     }
1004     if (GST_IS_OBJECT (parents->data)) {
1005       GstObject *item = GST_OBJECT_CAST (parents->data);
1006       GstObjectClass *oclass = GST_OBJECT_GET_CLASS (item);
1007       gchar *objname = gst_object_get_name (item);
1008
1009       component = g_strdup_printf ("%s:%s", typename, objname);
1010       separator = oclass->path_string_separator;
1011       /* and unref now */
1012       gst_object_unref (item);
1013       g_free (objname);
1014     } else {
1015       if (typename) {
1016         component = g_strdup_printf ("%s:%p", typename, parents->data);
1017       } else {
1018         component = g_strdup_printf ("%p", parents->data);
1019       }
1020       separator = "/";
1021     }
1022
1023     prevpath = path;
1024     path = g_strjoin (separator, prevpath, component, NULL);
1025     g_free (prevpath);
1026     g_free (component);
1027   }
1028
1029   g_slist_free (parentage);
1030
1031   return path;
1032 }
1033
1034 /* controller helper functions */
1035
1036 /*
1037  * gst_object_find_control_binding:
1038  * @self: the gobject to search for a property in
1039  * @name: the gobject property name to look for
1040  *
1041  * Searches the list of properties under control.
1042  *
1043  * Returns: (nullable): a #GstControlBinding or %NULL if the property
1044  * is not being controlled.
1045  */
1046 static GstControlBinding *
1047 gst_object_find_control_binding (GstObject * self, const gchar * name)
1048 {
1049   GstControlBinding *binding;
1050   GList *node;
1051
1052   for (node = self->control_bindings; node; node = g_list_next (node)) {
1053     binding = node->data;
1054     /* FIXME: eventually use GQuark to speed it up */
1055     if (!strcmp (binding->name, name)) {
1056       GST_DEBUG_OBJECT (self, "found control binding for property '%s'", name);
1057       return binding;
1058     }
1059   }
1060   GST_DEBUG_OBJECT (self, "controller does not manage property '%s'", name);
1061
1062   return NULL;
1063 }
1064
1065 /* controller functions */
1066
1067 /**
1068  * gst_object_suggest_next_sync:
1069  * @object: the object that has controlled properties
1070  *
1071  * Returns a suggestion for timestamps where buffers should be split
1072  * to get best controller results.
1073  *
1074  * Returns: Returns the suggested timestamp or %GST_CLOCK_TIME_NONE
1075  * if no control-rate was set.
1076  */
1077 GstClockTime
1078 gst_object_suggest_next_sync (GstObject * object)
1079 {
1080   GstClockTime ret;
1081
1082   g_return_val_if_fail (GST_IS_OBJECT (object), GST_CLOCK_TIME_NONE);
1083   g_return_val_if_fail (object->control_rate != GST_CLOCK_TIME_NONE,
1084       GST_CLOCK_TIME_NONE);
1085
1086   GST_OBJECT_LOCK (object);
1087
1088   /* TODO: Implement more logic, depending on interpolation mode and control
1089    * points
1090    * FIXME: we need playback direction
1091    */
1092   ret = object->last_sync + object->control_rate;
1093
1094   GST_OBJECT_UNLOCK (object);
1095
1096   return ret;
1097 }
1098
1099 /**
1100  * gst_object_sync_values:
1101  * @object: the object that has controlled properties
1102  * @timestamp: the time that should be processed
1103  *
1104  * Sets the properties of the object, according to the #GstControlSources that
1105  * (maybe) handle them and for the given timestamp.
1106  *
1107  * If this function fails, it is most likely the application developers fault.
1108  * Most probably the control sources are not setup correctly.
1109  *
1110  * Returns: %TRUE if the controller values could be applied to the object
1111  * properties, %FALSE otherwise
1112  */
1113 gboolean
1114 gst_object_sync_values (GstObject * object, GstClockTime timestamp)
1115 {
1116   GList *node;
1117   gboolean ret = TRUE;
1118
1119   g_return_val_if_fail (GST_IS_OBJECT (object), FALSE);
1120   g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (timestamp), FALSE);
1121
1122   GST_LOG_OBJECT (object, "sync_values");
1123   if (!object->control_bindings)
1124     return TRUE;
1125
1126   /* FIXME: this deadlocks */
1127   /* GST_OBJECT_LOCK (object); */
1128   g_object_freeze_notify ((GObject *) object);
1129   for (node = object->control_bindings; node; node = g_list_next (node)) {
1130     ret &= gst_control_binding_sync_values ((GstControlBinding *) node->data,
1131         object, timestamp, object->last_sync);
1132   }
1133   object->last_sync = timestamp;
1134   g_object_thaw_notify ((GObject *) object);
1135   /* GST_OBJECT_UNLOCK (object); */
1136
1137   return ret;
1138 }
1139
1140
1141 /**
1142  * gst_object_has_active_control_bindings:
1143  * @object: the object that has controlled properties
1144  *
1145  * Check if the @object has active controlled properties.
1146  *
1147  * Returns: %TRUE if the object has active controlled properties
1148  */
1149 gboolean
1150 gst_object_has_active_control_bindings (GstObject * object)
1151 {
1152   gboolean res = FALSE;
1153   GList *node;
1154
1155   g_return_val_if_fail (GST_IS_OBJECT (object), FALSE);
1156
1157   GST_OBJECT_LOCK (object);
1158   for (node = object->control_bindings; node; node = g_list_next (node)) {
1159     res |= !gst_control_binding_is_disabled ((GstControlBinding *) node->data);
1160   }
1161   GST_OBJECT_UNLOCK (object);
1162   return res;
1163 }
1164
1165 /**
1166  * gst_object_set_control_bindings_disabled:
1167  * @object: the object that has controlled properties
1168  * @disabled: boolean that specifies whether to disable the controller
1169  * or not.
1170  *
1171  * This function is used to disable all controlled properties of the @object for
1172  * some time, i.e. gst_object_sync_values() will do nothing.
1173  */
1174 void
1175 gst_object_set_control_bindings_disabled (GstObject * object, gboolean disabled)
1176 {
1177   GList *node;
1178
1179   g_return_if_fail (GST_IS_OBJECT (object));
1180
1181   GST_OBJECT_LOCK (object);
1182   for (node = object->control_bindings; node; node = g_list_next (node)) {
1183     gst_control_binding_set_disabled ((GstControlBinding *) node->data,
1184         disabled);
1185   }
1186   GST_OBJECT_UNLOCK (object);
1187 }
1188
1189 /**
1190  * gst_object_set_control_binding_disabled:
1191  * @object: the object that has controlled properties
1192  * @property_name: property to disable
1193  * @disabled: boolean that specifies whether to disable the controller
1194  * or not.
1195  *
1196  * This function is used to disable the control bindings on a property for
1197  * some time, i.e. gst_object_sync_values() will do nothing for the
1198  * property.
1199  */
1200 void
1201 gst_object_set_control_binding_disabled (GstObject * object,
1202     const gchar * property_name, gboolean disabled)
1203 {
1204   GstControlBinding *binding;
1205
1206   g_return_if_fail (GST_IS_OBJECT (object));
1207   g_return_if_fail (property_name);
1208
1209   GST_OBJECT_LOCK (object);
1210   if ((binding = gst_object_find_control_binding (object, property_name))) {
1211     gst_control_binding_set_disabled (binding, disabled);
1212   }
1213   GST_OBJECT_UNLOCK (object);
1214 }
1215
1216
1217 /**
1218  * gst_object_add_control_binding:
1219  * @object: the controller object
1220  * @binding: (transfer full): the #GstControlBinding that should be used
1221  *
1222  * Attach the #GstControlBinding to the object. If there already was a
1223  * #GstControlBinding for this property it will be replaced.
1224  *
1225  * The @object will take ownership of the @binding.
1226  *
1227  * Returns: %FALSE if the given @binding has not been setup for this object or
1228  * has been setup for a non suitable property, %TRUE otherwise.
1229  */
1230 gboolean
1231 gst_object_add_control_binding (GstObject * object, GstControlBinding * binding)
1232 {
1233   GstControlBinding *old;
1234
1235   g_return_val_if_fail (GST_IS_OBJECT (object), FALSE);
1236   g_return_val_if_fail (GST_IS_CONTROL_BINDING (binding), FALSE);
1237   g_return_val_if_fail (binding->pspec, FALSE);
1238
1239   GST_OBJECT_LOCK (object);
1240   if ((old = gst_object_find_control_binding (object, binding->name))) {
1241     GST_DEBUG_OBJECT (object, "controlled property %s removed", old->name);
1242     object->control_bindings = g_list_remove (object->control_bindings, old);
1243     gst_object_unparent (GST_OBJECT_CAST (old));
1244   }
1245   object->control_bindings = g_list_prepend (object->control_bindings, binding);
1246   gst_object_set_parent (GST_OBJECT_CAST (binding), object);
1247   GST_DEBUG_OBJECT (object, "controlled property %s added", binding->name);
1248   GST_OBJECT_UNLOCK (object);
1249
1250   return TRUE;
1251 }
1252
1253 /**
1254  * gst_object_get_control_binding:
1255  * @object: the object
1256  * @property_name: name of the property
1257  *
1258  * Gets the corresponding #GstControlBinding for the property. This should be
1259  * unreferenced again after use.
1260  *
1261  * Returns: (transfer full) (nullable): the #GstControlBinding for
1262  * @property_name or %NULL if the property is not controlled.
1263  */
1264 GstControlBinding *
1265 gst_object_get_control_binding (GstObject * object, const gchar * property_name)
1266 {
1267   GstControlBinding *binding;
1268
1269   g_return_val_if_fail (GST_IS_OBJECT (object), NULL);
1270   g_return_val_if_fail (property_name, NULL);
1271
1272   GST_OBJECT_LOCK (object);
1273   if ((binding = gst_object_find_control_binding (object, property_name))) {
1274     gst_object_ref (binding);
1275   }
1276   GST_OBJECT_UNLOCK (object);
1277
1278   return binding;
1279 }
1280
1281 /**
1282  * gst_object_remove_control_binding:
1283  * @object: the object
1284  * @binding: the binding
1285  *
1286  * Removes the corresponding #GstControlBinding. If it was the
1287  * last ref of the binding, it will be disposed.
1288  *
1289  * Returns: %TRUE if the binding could be removed.
1290  */
1291 gboolean
1292 gst_object_remove_control_binding (GstObject * object,
1293     GstControlBinding * binding)
1294 {
1295   GList *node;
1296   gboolean ret = FALSE;
1297
1298   g_return_val_if_fail (GST_IS_OBJECT (object), FALSE);
1299   g_return_val_if_fail (GST_IS_CONTROL_BINDING (binding), FALSE);
1300
1301   GST_OBJECT_LOCK (object);
1302   if ((node = g_list_find (object->control_bindings, binding))) {
1303     GST_DEBUG_OBJECT (object, "controlled property %s removed", binding->name);
1304     object->control_bindings =
1305         g_list_delete_link (object->control_bindings, node);
1306     gst_object_unparent (GST_OBJECT_CAST (binding));
1307     ret = TRUE;
1308   }
1309   GST_OBJECT_UNLOCK (object);
1310
1311   return ret;
1312 }
1313
1314 /**
1315  * gst_object_get_value:
1316  * @object: the object that has controlled properties
1317  * @property_name: the name of the property to get
1318  * @timestamp: the time the control-change should be read from
1319  *
1320  * Gets the value for the given controlled property at the requested time.
1321  *
1322  * Returns: (nullable): the GValue of the property at the given time,
1323  * or %NULL if the property isn't controlled.
1324  */
1325 GValue *
1326 gst_object_get_value (GstObject * object, const gchar * property_name,
1327     GstClockTime timestamp)
1328 {
1329   GstControlBinding *binding;
1330   GValue *val = NULL;
1331
1332   g_return_val_if_fail (GST_IS_OBJECT (object), NULL);
1333   g_return_val_if_fail (property_name, NULL);
1334   g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (timestamp), NULL);
1335
1336   GST_OBJECT_LOCK (object);
1337   if ((binding = gst_object_find_control_binding (object, property_name))) {
1338     val = gst_control_binding_get_value (binding, timestamp);
1339   }
1340   GST_OBJECT_UNLOCK (object);
1341
1342   return val;
1343 }
1344
1345 /**
1346  * gst_object_get_value_array:
1347  * @object: the object that has controlled properties
1348  * @property_name: the name of the property to get
1349  * @timestamp: the time that should be processed
1350  * @interval: the time spacing between subsequent values
1351  * @n_values: the number of values
1352  * @values: array to put control-values in
1353  *
1354  * Gets a number of values for the given controlled property starting at the
1355  * requested time. The array @values need to hold enough space for @n_values of
1356  * the same type as the objects property's type.
1357  *
1358  * This function is useful if one wants to e.g. draw a graph of the control
1359  * curve or apply a control curve sample by sample.
1360  *
1361  * The values are unboxed and ready to be used. The similar function
1362  * gst_object_get_g_value_array() returns the array as #GValues and is
1363  * better suites for bindings.
1364  *
1365  * Returns: %TRUE if the given array could be filled, %FALSE otherwise
1366  */
1367 gboolean
1368 gst_object_get_value_array (GstObject * object, const gchar * property_name,
1369     GstClockTime timestamp, GstClockTime interval, guint n_values,
1370     gpointer values)
1371 {
1372   gboolean res = FALSE;
1373   GstControlBinding *binding;
1374
1375   g_return_val_if_fail (GST_IS_OBJECT (object), FALSE);
1376   g_return_val_if_fail (property_name, FALSE);
1377   g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (timestamp), FALSE);
1378   g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (interval), FALSE);
1379   g_return_val_if_fail (values, FALSE);
1380
1381   GST_OBJECT_LOCK (object);
1382   if ((binding = gst_object_find_control_binding (object, property_name))) {
1383     res = gst_control_binding_get_value_array (binding, timestamp, interval,
1384         n_values, values);
1385   }
1386   GST_OBJECT_UNLOCK (object);
1387   return res;
1388 }
1389
1390 /**
1391  * gst_object_get_g_value_array:
1392  * @object: the object that has controlled properties
1393  * @property_name: the name of the property to get
1394  * @timestamp: the time that should be processed
1395  * @interval: the time spacing between subsequent values
1396  * @n_values: the number of values
1397  * @values: array to put control-values in
1398  *
1399  * Gets a number of #GValues for the given controlled property starting at the
1400  * requested time. The array @values need to hold enough space for @n_values of
1401  * #GValue.
1402  *
1403  * This function is useful if one wants to e.g. draw a graph of the control
1404  * curve or apply a control curve sample by sample.
1405  *
1406  * Returns: %TRUE if the given array could be filled, %FALSE otherwise
1407  */
1408 gboolean
1409 gst_object_get_g_value_array (GstObject * object, const gchar * property_name,
1410     GstClockTime timestamp, GstClockTime interval, guint n_values,
1411     GValue * values)
1412 {
1413   gboolean res = FALSE;
1414   GstControlBinding *binding;
1415
1416   g_return_val_if_fail (GST_IS_OBJECT (object), FALSE);
1417   g_return_val_if_fail (property_name, FALSE);
1418   g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (timestamp), FALSE);
1419   g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (interval), FALSE);
1420   g_return_val_if_fail (values, FALSE);
1421
1422   GST_OBJECT_LOCK (object);
1423   if ((binding = gst_object_find_control_binding (object, property_name))) {
1424     res = gst_control_binding_get_g_value_array (binding, timestamp, interval,
1425         n_values, values);
1426   }
1427   GST_OBJECT_UNLOCK (object);
1428   return res;
1429 }
1430
1431
1432 /**
1433  * gst_object_get_control_rate:
1434  * @object: the object that has controlled properties
1435  *
1436  * Obtain the control-rate for this @object. Audio processing #GstElement
1437  * objects will use this rate to sub-divide their processing loop and call
1438  * gst_object_sync_values() inbetween. The length of the processing segment
1439  * should be up to @control-rate nanoseconds.
1440  *
1441  * If the @object is not under property control, this will return
1442  * %GST_CLOCK_TIME_NONE. This allows the element to avoid the sub-dividing.
1443  *
1444  * The control-rate is not expected to change if the element is in
1445  * %GST_STATE_PAUSED or %GST_STATE_PLAYING.
1446  *
1447  * Returns: the control rate in nanoseconds
1448  */
1449 GstClockTime
1450 gst_object_get_control_rate (GstObject * object)
1451 {
1452   g_return_val_if_fail (GST_IS_OBJECT (object), FALSE);
1453
1454   return object->control_rate;
1455 }
1456
1457 /**
1458  * gst_object_set_control_rate:
1459  * @object: the object that has controlled properties
1460  * @control_rate: the new control-rate in nanoseconds.
1461  *
1462  * Change the control-rate for this @object. Audio processing #GstElement
1463  * objects will use this rate to sub-divide their processing loop and call
1464  * gst_object_sync_values() inbetween. The length of the processing segment
1465  * should be up to @control-rate nanoseconds.
1466  *
1467  * The control-rate should not change if the element is in %GST_STATE_PAUSED or
1468  * %GST_STATE_PLAYING.
1469  */
1470 void
1471 gst_object_set_control_rate (GstObject * object, GstClockTime control_rate)
1472 {
1473   g_return_if_fail (GST_IS_OBJECT (object));
1474
1475   object->control_rate = control_rate;
1476 }