gst/gstutils.c

   1 /* GStreamer
   2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
   3  *                    2000 Wim Taymans <wtay@chello.be>
   4  *
   5  * gstutils.c: Utility functions: gtk_get_property stuff, etc.
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Library General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library General Public
  18  * License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22 /**
  23  * SECTION:gstutils
  24  * @short_description: Various utility functions
  25  *
  26  * When defining own plugins, use the GST_BOILERPLATE ease gobject creation.
  27  */
  28
  29 #include <stdio.h>
  30 #include <string.h>
  31
  32 #include "gst_private.h"
  33 #include "gstghostpad.h"
  34 #include "gstutils.h"
  35 #include "gsturitype.h"
  36 #include "gstinfo.h"
  37 #include "gst-i18n-lib.h"
  38
  39
  40 /**
  41  * gst_util_dump_mem:
  42  * @mem: a pointer to the memory to dump
  43  * @size: the size of the memory block to dump
  44  *
  45  * Dumps the memory block into a hex representation. Useful for debugging.
  46  */
  47 void
  48 gst_util_dump_mem (const guchar * mem, guint size)
  49 {
  50   guint i, j;
  51   GString *string = g_string_sized_new (50);
  52   GString *chars = g_string_sized_new (18);
  53
  54   i = j = 0;
  55   while (i < size) {
  56     if (g_ascii_isprint (mem[i]))
  57       g_string_append_printf (chars, "%c", mem[i]);
  58     else
  59       g_string_append_printf (chars, ".");
  60
  61     g_string_append_printf (string, "%02x ", mem[i]);
  62
  63     j++;
  64     i++;
  65
  66     if (j == 16 || i == size) {
  67       g_print ("%08x (%p): %-48.48s %-16.16s\n", i - j, mem + i - j,
  68           string->str, chars->str);
  69       g_string_set_size (string, 0);
  70       g_string_set_size (chars, 0);
  71       j = 0;
  72     }
  73   }
  74   g_string_free (string, TRUE);
  75   g_string_free (chars, TRUE);
  76 }
  77
  78
  79 /**
  80  * gst_util_set_value_from_string:
  81  * @value: the value to set
  82  * @value_str: the string to get the value from
  83  *
  84  * Converts the string to the type of the value and
  85  * sets the value with it.
  86  */
  87 void
  88 gst_util_set_value_from_string (GValue * value, const gchar * value_str)
  89 {
  90   gint sscanf_ret;
  91
  92   g_return_if_fail (value != NULL);
  93   g_return_if_fail (value_str != NULL);
  94
  95   GST_CAT_DEBUG (GST_CAT_PARAMS, "parsing '%s' to type %s", value_str,
  96       g_type_name (G_VALUE_TYPE (value)));
  97
  98   switch (G_VALUE_TYPE (value)) {
  99     case G_TYPE_STRING:
 100       g_value_set_string (value, g_strdup (value_str));
 101       break;
 102     case G_TYPE_ENUM:
 103     case G_TYPE_INT:{
 104       gint i;
 105
 106       sscanf_ret = sscanf (value_str, "%d", &i);
 107       g_return_if_fail (sscanf_ret == 1);
 108       g_value_set_int (value, i);
 109       break;
 110     }
 111     case G_TYPE_UINT:{
 112       guint i;
 113
 114       sscanf_ret = sscanf (value_str, "%u", &i);
 115       g_return_if_fail (sscanf_ret == 1);
 116       g_value_set_uint (value, i);
 117       break;
 118     }
 119     case G_TYPE_LONG:{
 120       glong i;
 121
 122       sscanf_ret = sscanf (value_str, "%ld", &i);
 123       g_return_if_fail (sscanf_ret == 1);
 124       g_value_set_long (value, i);
 125       break;
 126     }
 127     case G_TYPE_ULONG:{
 128       gulong i;
 129
 130       sscanf_ret = sscanf (value_str, "%lu", &i);
 131       g_return_if_fail (sscanf_ret == 1);
 132       g_value_set_ulong (value, i);
 133       break;
 134     }
 135     case G_TYPE_BOOLEAN:{
 136       gboolean i = FALSE;
 137
 138       if (!g_ascii_strncasecmp ("true", value_str, 4))
 139         i = TRUE;
 140       g_value_set_boolean (value, i);
 141       break;
 142     }
 143     case G_TYPE_CHAR:{
 144       gchar i;
 145
 146       sscanf_ret = sscanf (value_str, "%c", &i);
 147       g_return_if_fail (sscanf_ret == 1);
 148       g_value_set_char (value, i);
 149       break;
 150     }
 151     case G_TYPE_UCHAR:{
 152       guchar i;
 153
 154       sscanf_ret = sscanf (value_str, "%c", &i);
 155       g_return_if_fail (sscanf_ret == 1);
 156       g_value_set_uchar (value, i);
 157       break;
 158     }
 159     case G_TYPE_FLOAT:{
 160       gfloat i;
 161
 162       sscanf_ret = sscanf (value_str, "%f", &i);
 163       g_return_if_fail (sscanf_ret == 1);
 164       g_value_set_float (value, i);
 165       break;
 166     }
 167     case G_TYPE_DOUBLE:{
 168       gfloat i;
 169
 170       sscanf_ret = sscanf (value_str, "%g", &i);
 171       g_return_if_fail (sscanf_ret == 1);
 172       g_value_set_double (value, (gdouble) i);
 173       break;
 174     }
 175     default:
 176       break;
 177   }
 178 }
 179
 180 /**
 181  * gst_util_set_object_arg:
 182  * @object: the object to set the argument of
 183  * @name: the name of the argument to set
 184  * @value: the string value to set
 185  *
 186  * Convertes the string value to the type of the objects argument and
 187  * sets the argument with it.
 188  */
 189 void
 190 gst_util_set_object_arg (GObject * object, const gchar * name,
 191     const gchar * value)
 192 {
 193   gboolean sscanf_ret;
 194
 195   if (name && value) {
 196     GParamSpec *paramspec;
 197
 198     paramspec =
 199         g_object_class_find_property (G_OBJECT_GET_CLASS (object), name);
 200
 201     if (!paramspec) {
 202       return;
 203     }
 204
 205     GST_DEBUG ("paramspec->flags is %d, paramspec->value_type is %d",
 206         paramspec->flags, (gint) paramspec->value_type);
 207
 208     if (paramspec->flags & G_PARAM_WRITABLE) {
 209       switch (paramspec->value_type) {
 210         case G_TYPE_STRING:
 211           g_object_set (G_OBJECT (object), name, value, NULL);
 212           break;
 213         case G_TYPE_ENUM:
 214         case G_TYPE_INT:{
 215           gint i;
 216
 217           sscanf_ret = sscanf (value, "%d", &i);
 218           g_return_if_fail (sscanf_ret == 1);
 219           g_object_set (G_OBJECT (object), name, i, NULL);
 220           break;
 221         }
 222         case G_TYPE_UINT:{
 223           guint i;
 224
 225           sscanf_ret = sscanf (value, "%u", &i);
 226           g_return_if_fail (sscanf_ret == 1);
 227           g_object_set (G_OBJECT (object), name, i, NULL);
 228           break;
 229         }
 230         case G_TYPE_LONG:{
 231           glong i;
 232
 233           sscanf_ret = sscanf (value, "%ld", &i);
 234           g_return_if_fail (sscanf_ret == 1);
 235           g_object_set (G_OBJECT (object), name, i, NULL);
 236           break;
 237         }
 238         case G_TYPE_ULONG:{
 239           gulong i;
 240
 241           sscanf_ret = sscanf (value, "%lu", &i);
 242           g_return_if_fail (sscanf_ret == 1);
 243           g_object_set (G_OBJECT (object), name, i, NULL);
 244           break;
 245         }
 246         case G_TYPE_BOOLEAN:{
 247           gboolean i = FALSE;
 248
 249           if (!g_ascii_strncasecmp ("true", value, 4))
 250             i = TRUE;
 251           g_object_set (G_OBJECT (object), name, i, NULL);
 252           break;
 253         }
 254         case G_TYPE_CHAR:{
 255           gchar i;
 256
 257           sscanf_ret = sscanf (value, "%c", &i);
 258           g_return_if_fail (sscanf_ret == 1);
 259           g_object_set (G_OBJECT (object), name, i, NULL);
 260           break;
 261         }
 262         case G_TYPE_UCHAR:{
 263           guchar i;
 264
 265           sscanf_ret = sscanf (value, "%c", &i);
 266           g_return_if_fail (sscanf_ret == 1);
 267           g_object_set (G_OBJECT (object), name, i, NULL);
 268           break;
 269         }
 270         case G_TYPE_FLOAT:{
 271           gfloat i;
 272
 273           sscanf_ret = sscanf (value, "%f", &i);
 274           g_return_if_fail (sscanf_ret == 1);
 275           g_object_set (G_OBJECT (object), name, i, NULL);
 276           break;
 277         }
 278         case G_TYPE_DOUBLE:{
 279           gfloat i;
 280
 281           sscanf_ret = sscanf (value, "%g", &i);
 282           g_return_if_fail (sscanf_ret == 1);
 283           g_object_set (G_OBJECT (object), name, (gdouble) i, NULL);
 284           break;
 285         }
 286         default:
 287           if (G_IS_PARAM_SPEC_ENUM (paramspec)) {
 288             gint i;
 289
 290             sscanf_ret = sscanf (value, "%d", &i);
 291             g_return_if_fail (sscanf_ret == 1);
 292             g_object_set (G_OBJECT (object), name, i, NULL);
 293           } else if (paramspec->value_type == GST_TYPE_URI) {
 294             g_object_set (G_OBJECT (object), name, value, NULL);
 295           }
 296           break;
 297       }
 298     }
 299   }
 300 }
 301
 302 /**
 303  * gst_util_uint64_scale:
 304  * @val: the number to scale
 305  * @num: the numerator of the scale ratio
 306  * @denom: the denominator of the scale ratio
 307  *
 308  * Scale @val by @num / @denom, trying to avoid overflows.
 309  *
 310  * Returns: @val * @num / @denom, trying to avoid overflows.
 311  */
 312 guint64
 313 gst_util_uint64_scale (guint64 val, guint64 num, guint64 denom)
 314 {
 315   /* implement me with fixed point, if you care */
 316   return val * (((double) num) / denom);
 317 }
 318
 319 /* -----------------------------------------------------
 320  *
 321  *  The following code will be moved out of the main
 322  * gstreamer library someday.
 323  */
 324
 325 #include "gstpad.h"
 326
 327 static void
 328 string_append_indent (GString * str, gint count)
 329 {
 330   gint xx;
 331
 332   for (xx = 0; xx < count; xx++)
 333     g_string_append_c (str, ' ');
 334 }
 335
 336 /**
 337  * gst_print_pad_caps:
 338  * @buf: the buffer to print the caps in
 339  * @indent: initial indentation
 340  * @pad: the pad to print the caps from
 341  *
 342  * Write the pad capabilities in a human readable format into
 343  * the given GString.
 344  */
 345 void
 346 gst_print_pad_caps (GString * buf, gint indent, GstPad * pad)
 347 {
 348   GstCaps *caps;
 349
 350   caps = pad->caps;
 351
 352   if (!caps) {
 353     string_append_indent (buf, indent);
 354     g_string_printf (buf, "%s:%s has no capabilities",
 355         GST_DEBUG_PAD_NAME (pad));
 356   } else {
 357     char *s;
 358
 359     s = gst_caps_to_string (caps);
 360     g_string_append (buf, s);
 361     g_free (s);
 362   }
 363 }
 364
 365 /**
 366  * gst_print_element_args:
 367  * @buf: the buffer to print the args in
 368  * @indent: initial indentation
 369  * @element: the element to print the args of
 370  *
 371  * Print the element argument in a human readable format in the given
 372  * GString.
 373  */
 374 void
 375 gst_print_element_args (GString * buf, gint indent, GstElement * element)
 376 {
 377   guint width;
 378   GValue value = { 0, };        /* the important thing is that value.type = 0 */
 379   gchar *str = NULL;
 380   GParamSpec *spec, **specs, **walk;
 381
 382   specs = g_object_class_list_properties (G_OBJECT_GET_CLASS (element), NULL);
 383
 384   width = 0;
 385   for (walk = specs; *walk; walk++) {
 386     spec = *walk;
 387     if (width < strlen (spec->name))
 388       width = strlen (spec->name);
 389   }
 390
 391   for (walk = specs; *walk; walk++) {
 392     spec = *walk;
 393
 394     if (spec->flags & G_PARAM_READABLE) {
 395       g_value_init (&value, G_PARAM_SPEC_VALUE_TYPE (spec));
 396       g_object_get_property (G_OBJECT (element), spec->name, &value);
 397       str = g_strdup_value_contents (&value);
 398       g_value_unset (&value);
 399     } else {
 400       str = g_strdup ("Parameter not readable.");
 401     }
 402
 403     string_append_indent (buf, indent);
 404     g_string_append (buf, spec->name);
 405     string_append_indent (buf, 2 + width - strlen (spec->name));
 406     g_string_append (buf, str);
 407     g_string_append_c (buf, '\n');
 408
 409     g_free (str);
 410   }
 411
 412   g_free (specs);
 413 }
 414
 415 /**
 416  * gst_element_create_all_pads:
 417  * @element: a #GstElement to create pads for
 418  *
 419  * Creates a pad for each pad template that is always available.
 420  * This function is only useful during object intialization of
 421  * subclasses of #GstElement.
 422  */
 423 void
 424 gst_element_create_all_pads (GstElement * element)
 425 {
 426   GList *padlist;
 427
 428   /* FIXME: lock element */
 429
 430   padlist =
 431       gst_element_class_get_pad_template_list (GST_ELEMENT_CLASS
 432       (G_OBJECT_GET_CLASS (element)));
 433
 434   while (padlist) {
 435     GstPadTemplate *padtempl = (GstPadTemplate *) padlist->data;
 436
 437     if (padtempl->presence == GST_PAD_ALWAYS) {
 438       GstPad *pad;
 439
 440       pad = gst_pad_new_from_template (padtempl, padtempl->name_template);
 441
 442       gst_element_add_pad (element, pad);
 443     }
 444     padlist = padlist->next;
 445   }
 446 }
 447
 448 /**
 449  * gst_element_get_compatible_pad_template:
 450  * @element: a #GstElement to get a compatible pad template for.
 451  * @compattempl: the #GstPadTemplate to find a compatible template for.
 452  *
 453  * Retrieves a pad template from @element that is compatible with @compattempl.
 454  * Pads from compatible templates can be linked together.
 455  *
 456  * Returns: a compatible #GstPadTemplate, or NULL if none was found. No
 457  * unreferencing is necessary.
 458  */
 459 GstPadTemplate *
 460 gst_element_get_compatible_pad_template (GstElement * element,
 461     GstPadTemplate * compattempl)
 462 {
 463   GstPadTemplate *newtempl = NULL;
 464   GList *padlist;
 465   GstElementClass *class;
 466
 467   g_return_val_if_fail (element != NULL, NULL);
 468   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
 469   g_return_val_if_fail (compattempl != NULL, NULL);
 470
 471   class = GST_ELEMENT_GET_CLASS (element);
 472
 473   padlist = gst_element_class_get_pad_template_list (class);
 474
 475   GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS,
 476       "Looking for a suitable pad template in %s out of %d templates...",
 477       GST_ELEMENT_NAME (element), g_list_length (padlist));
 478
 479   while (padlist) {
 480     GstPadTemplate *padtempl = (GstPadTemplate *) padlist->data;
 481     GstCaps *intersection;
 482
 483     /* Ignore name
 484      * Ignore presence
 485      * Check direction (must be opposite)
 486      * Check caps
 487      */
 488     GST_CAT_LOG (GST_CAT_CAPS,
 489         "checking pad template %s", padtempl->name_template);
 490     if (padtempl->direction != compattempl->direction) {
 491       GST_CAT_DEBUG (GST_CAT_CAPS,
 492           "compatible direction: found %s pad template \"%s\"",
 493           padtempl->direction == GST_PAD_SRC ? "src" : "sink",
 494           padtempl->name_template);
 495
 496       GST_CAT_DEBUG (GST_CAT_CAPS,
 497           "intersecting %" GST_PTR_FORMAT, GST_PAD_TEMPLATE_CAPS (compattempl));
 498       GST_CAT_DEBUG (GST_CAT_CAPS,
 499           "..and %" GST_PTR_FORMAT, GST_PAD_TEMPLATE_CAPS (padtempl));
 500
 501       intersection = gst_caps_intersect (GST_PAD_TEMPLATE_CAPS (compattempl),
 502           GST_PAD_TEMPLATE_CAPS (padtempl));
 503
 504       GST_CAT_DEBUG (GST_CAT_CAPS, "caps are %scompatible %" GST_PTR_FORMAT,
 505           (intersection ? "" : "not "), intersection);
 506
 507       if (!gst_caps_is_empty (intersection))
 508         newtempl = padtempl;
 509       gst_caps_unref (intersection);
 510       if (newtempl)
 511         break;
 512     }
 513
 514     padlist = g_list_next (padlist);
 515   }
 516   if (newtempl)
 517     GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS,
 518         "Returning new pad template %p", newtempl);
 519   else
 520     GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "No compatible pad template found");
 521
 522   return newtempl;
 523 }
 524
 525 static GstPad *
 526 gst_element_request_pad (GstElement * element, GstPadTemplate * templ,
 527     const gchar * name)
 528 {
 529   GstPad *newpad = NULL;
 530   GstElementClass *oclass;
 531
 532   oclass = GST_ELEMENT_GET_CLASS (element);
 533
 534   if (oclass->request_new_pad)
 535     newpad = (oclass->request_new_pad) (element, templ, name);
 536
 537   if (newpad)
 538     gst_object_ref (newpad);
 539
 540   return newpad;
 541 }
 542
 543
 544
 545 /**
 546  * gst_element_get_pad_from_template:
 547  * @element: a #GstElement.
 548  * @templ: a #GstPadTemplate belonging to @element.
 549  *
 550  * Gets a pad from @element described by @templ. If the presence of @templ is
 551  * #GST_PAD_REQUEST, requests a new pad. Can return %NULL for #GST_PAD_SOMETIMES
 552  * templates.
 553  *
 554  * Returns: the #GstPad, or NULL if one could not be found or created.
 555  */
 556 static GstPad *
 557 gst_element_get_pad_from_template (GstElement * element, GstPadTemplate * templ)
 558 {
 559   GstPad *ret = NULL;
 560   GstPadPresence presence;
 561
 562   /* If this function is ever exported, we need check the validity of `element'
 563    * and `templ', and to make sure the template actually belongs to the
 564    * element. */
 565
 566   presence = GST_PAD_TEMPLATE_PRESENCE (templ);
 567
 568   switch (presence) {
 569     case GST_PAD_ALWAYS:
 570     case GST_PAD_SOMETIMES:
 571       ret = gst_element_get_static_pad (element, templ->name_template);
 572       if (!ret && presence == GST_PAD_ALWAYS)
 573         g_warning
 574             ("Element %s has an ALWAYS template %s, but no pad of the same name",
 575             GST_OBJECT_NAME (element), templ->name_template);
 576       break;
 577
 578     case GST_PAD_REQUEST:
 579       ret = gst_element_request_pad (element, templ, NULL);
 580       break;
 581   }
 582
 583   return ret;
 584 }
 585
 586 /**
 587  * gst_element_request_compatible_pad:
 588  * @element: a #GstElement.
 589  * @templ: the #GstPadTemplate to which the new pad should be able to link.
 590  *
 591  * Requests a pad from @element. The returned pad should be unlinked and
 592  * compatible with @templ. Might return an existing pad, or request a new one.
 593  *
 594  * Returns: a #GstPad, or %NULL if one could not be found or created.
 595  */
 596 GstPad *
 597 gst_element_request_compatible_pad (GstElement * element,
 598     GstPadTemplate * templ)
 599 {
 600   GstPadTemplate *templ_new;
 601   GstPad *pad = NULL;
 602
 603   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
 604   g_return_val_if_fail (GST_IS_PAD_TEMPLATE (templ), NULL);
 605
 606   /* FIXME: should really loop through the templates, testing each for
 607    *      compatibility and pad availability. */
 608   templ_new = gst_element_get_compatible_pad_template (element, templ);
 609   if (templ_new)
 610     pad = gst_element_get_pad_from_template (element, templ_new);
 611
 612   /* This can happen for non-request pads. No need to unref. */
 613   if (pad && GST_PAD_PEER (pad))
 614     pad = NULL;
 615
 616   return pad;
 617 }
 618
 619 /**
 620  * gst_element_get_compatible_pad:
 621  * @element: a #GstElement in which the pad should be found.
 622  * @pad: the #GstPad to find a compatible one for.
 623  * @caps: the #GstCaps to use as a filter.
 624  *
 625  * Looks for an unlinked pad to which the given pad can link. It is not
 626  * guaranteed that linking the pads will work, though it should work in most
 627  * cases.
 628  *
 629  * Returns: the #GstPad to which a link can be made, or %NULL if one cannot be
 630  * found.
 631  */
 632 GstPad *
 633 gst_element_get_compatible_pad (GstElement * element, GstPad * pad,
 634     const GstCaps * caps)
 635 {
 636   GstIterator *pads;
 637   GstPadTemplate *templ;
 638   GstCaps *templcaps;
 639   GstPad *foundpad = NULL;
 640   gboolean done;
 641
 642   /* FIXME check for caps compatibility */
 643
 644   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
 645   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
 646
 647   GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS,
 648       "finding pad in %s compatible with %s:%s",
 649       GST_ELEMENT_NAME (element), GST_DEBUG_PAD_NAME (pad));
 650
 651   g_return_val_if_fail (GST_PAD_PEER (pad) == NULL, NULL);
 652
 653   done = FALSE;
 654   /* try to get an existing unlinked pad */
 655   pads = gst_element_iterate_pads (element);
 656   while (!done) {
 657     gpointer padptr;
 658
 659     switch (gst_iterator_next (pads, &padptr)) {
 660       case GST_ITERATOR_OK:
 661       {
 662         GstPad *peer;
 663         GstPad *current;
 664
 665         current = GST_PAD (padptr);
 666
 667         GST_CAT_LOG (GST_CAT_ELEMENT_PADS, "examining pad %s:%s",
 668             GST_DEBUG_PAD_NAME (current));
 669
 670         peer = gst_pad_get_peer (current);
 671
 672         if (peer == NULL && gst_pad_can_link (pad, current)) {
 673
 674           GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS,
 675               "found existing unlinked pad %s:%s",
 676               GST_DEBUG_PAD_NAME (current));
 677
 678           gst_iterator_free (pads);
 679
 680           return current;
 681         } else {
 682           GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "unreffing pads");
 683
 684           gst_object_unref (current);
 685           if (peer)
 686             gst_object_unref (peer);
 687         }
 688         break;
 689       }
 690       case GST_ITERATOR_DONE:
 691         done = TRUE;
 692         break;
 693       case GST_ITERATOR_RESYNC:
 694         gst_iterator_resync (pads);
 695         break;
 696       case GST_ITERATOR_ERROR:
 697         g_assert_not_reached ();
 698         break;
 699     }
 700   }
 701   gst_iterator_free (pads);
 702
 703   /* try to create a new one */
 704   /* requesting is a little crazy, we need a template. Let's create one */
 705   templcaps = gst_pad_get_caps (pad);
 706
 707   templ = gst_pad_template_new ((gchar *) GST_PAD_NAME (pad),
 708       GST_PAD_DIRECTION (pad), GST_PAD_ALWAYS, templcaps);
 709   foundpad = gst_element_request_compatible_pad (element, templ);
 710   gst_object_unref (templ);
 711
 712   if (foundpad) {
 713     GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS,
 714         "found existing request pad %s:%s", GST_DEBUG_PAD_NAME (foundpad));
 715     return foundpad;
 716   }
 717
 718   GST_CAT_INFO_OBJECT (GST_CAT_ELEMENT_PADS, element,
 719       "Could not find a compatible pad to link to %s:%s",
 720       GST_DEBUG_PAD_NAME (pad));
 721   return NULL;
 722 }
 723
 724 /**
 725  * gst_element_state_get_name:
 726  * @state: a #GstState to get the name of.
 727  *
 728  * Gets a string representing the given state.
 729  *
 730  * Returns: a string with the name of the state.
 731  */
 732 const gchar *
 733 gst_element_state_get_name (GstState state)
 734 {
 735   switch (state) {
 736 #ifdef GST_DEBUG_COLOR
 737     case GST_STATE_VOID_PENDING:
 738       return "VOID_PENDING";
 739       break;
 740     case GST_STATE_NULL:
 741       return "\033[01;34mNULL\033[00m";
 742       break;
 743     case GST_STATE_READY:
 744       return "\033[01;31mREADY\033[00m";
 745       break;
 746     case GST_STATE_PLAYING:
 747       return "\033[01;32mPLAYING\033[00m";
 748       break;
 749     case GST_STATE_PAUSED:
 750       return "\033[01;33mPAUSED\033[00m";
 751       break;
 752     default:
 753       /* This is a memory leak */
 754       return g_strdup_printf ("\033[01;35;41mUNKNOWN!\033[00m(%d)", state);
 755 #else
 756     case GST_STATE_VOID_PENDING:
 757       return "VOID_PENDING";
 758       break;
 759     case GST_STATE_NULL:
 760       return "NULL";
 761       break;
 762     case GST_STATE_READY:
 763       return "READY";
 764       break;
 765     case GST_STATE_PLAYING:
 766       return "PLAYING";
 767       break;
 768     case GST_STATE_PAUSED:
 769       return "PAUSED";
 770       break;
 771     default:
 772       /* This is a memory leak */
 773       return g_strdup_printf ("UNKNOWN!(%d)", state);
 774 #endif
 775   }
 776   return "";
 777 }
 778
 779 /**
 780  * gst_element_factory_can_src_caps :
 781  * @factory: factory to query
 782  * @caps: the caps to check
 783  *
 784  * Checks if the factory can source the given capability.
 785  *
 786  * Returns: true if it can src the capabilities
 787  */
 788 gboolean
 789 gst_element_factory_can_src_caps (GstElementFactory * factory,
 790     const GstCaps * caps)
 791 {
 792   GList *templates;
 793
 794   g_return_val_if_fail (factory != NULL, FALSE);
 795   g_return_val_if_fail (caps != NULL, FALSE);
 796
 797   templates = factory->staticpadtemplates;
 798
 799   while (templates) {
 800     GstStaticPadTemplate *template = (GstStaticPadTemplate *) templates->data;
 801
 802     if (template->direction == GST_PAD_SRC) {
 803       if (gst_caps_is_always_compatible (gst_static_caps_get (&template->
 804                   static_caps), caps))
 805         return TRUE;
 806     }
 807     templates = g_list_next (templates);
 808   }
 809
 810   return FALSE;
 811 }
 812
 813 /**
 814  * gst_element_factory_can_sink_caps :
 815  * @factory: factory to query
 816  * @caps: the caps to check
 817  *
 818  * Checks if the factory can sink the given capability.
 819  *
 820  * Returns: true if it can sink the capabilities
 821  */
 822 gboolean
 823 gst_element_factory_can_sink_caps (GstElementFactory * factory,
 824     const GstCaps * caps)
 825 {
 826   GList *templates;
 827
 828   g_return_val_if_fail (factory != NULL, FALSE);
 829   g_return_val_if_fail (caps != NULL, FALSE);
 830
 831   templates = factory->staticpadtemplates;
 832
 833   while (templates) {
 834     GstStaticPadTemplate *template = (GstStaticPadTemplate *) templates->data;
 835
 836     if (template->direction == GST_PAD_SINK) {
 837       if (gst_caps_is_always_compatible (caps,
 838               gst_static_caps_get (&template->static_caps)))
 839         return TRUE;
 840     }
 841     templates = g_list_next (templates);
 842   }
 843
 844   return FALSE;
 845 }
 846
 847
 848 /* if return val is true, *direct_child is a caller-owned ref on the direct
 849  * child of ancestor that is part of object's ancestry */
 850 static gboolean
 851 object_has_ancestor (GstObject * object, GstObject * ancestor,
 852     GstObject ** direct_child)
 853 {
 854   GstObject *child, *parent;
 855
 856   if (direct_child)
 857     *direct_child = NULL;
 858
 859   child = gst_object_ref (object);
 860   parent = gst_object_get_parent (object);
 861
 862   while (parent) {
 863     if (ancestor == parent) {
 864       if (direct_child)
 865         *direct_child = child;
 866       else
 867         gst_object_unref (child);
 868       gst_object_unref (parent);
 869       return TRUE;
 870     }
 871
 872     gst_object_unref (child);
 873     child = parent;
 874     parent = gst_object_get_parent (parent);
 875   }
 876
 877   gst_object_unref (child);
 878
 879   return FALSE;
 880 }
 881
 882 /* caller owns return */
 883 static GstObject *
 884 find_common_root (GstObject * o1, GstObject * o2)
 885 {
 886   GstObject *top = o1;
 887   GstObject *kid1, *kid2;
 888   GstObject *root = NULL;
 889
 890   while (GST_OBJECT_PARENT (top))
 891     top = GST_OBJECT_PARENT (top);
 892
 893   /* the itsy-bitsy spider... */
 894
 895   if (!object_has_ancestor (o2, top, &kid2))
 896     return NULL;
 897
 898   root = gst_object_ref (top);
 899   while (TRUE) {
 900     if (!object_has_ancestor (o1, kid2, &kid1)) {
 901       gst_object_unref (kid2);
 902       return root;
 903     }
 904     root = kid2;
 905     if (!object_has_ancestor (o2, kid1, &kid2)) {
 906       gst_object_unref (kid1);
 907       return root;
 908     }
 909     root = kid1;
 910   }
 911 }
 912
 913 /* caller does not own return */
 914 static GstPad *
 915 ghost_up (GstElement * e, GstPad * pad)
 916 {
 917   static gint ghost_pad_index = 0;
 918   GstPad *gpad;
 919   gchar *name;
 920   GstObject *parent = GST_OBJECT_PARENT (e);
 921
 922   name = g_strdup_printf ("ghost%d", ghost_pad_index++);
 923   gpad = gst_ghost_pad_new (name, pad);
 924   g_free (name);
 925
 926   if (!gst_element_add_pad ((GstElement *) parent, gpad)) {
 927     g_warning ("Pad named %s already exists in element %s\n",
 928         GST_OBJECT_NAME (gpad), GST_OBJECT_NAME (parent));
 929     gst_object_unref ((GstObject *) gpad);
 930     return NULL;
 931   }
 932
 933   return gpad;
 934 }
 935
 936 static void
 937 remove_pad (gpointer ppad, gpointer unused)
 938 {
 939   GstPad *pad = ppad;
 940
 941   if (!gst_element_remove_pad ((GstElement *) GST_OBJECT_PARENT (pad), pad))
 942     g_warning ("Couldn't remove pad %s from element %s",
 943         GST_OBJECT_NAME (pad), GST_OBJECT_NAME (GST_OBJECT_PARENT (pad)));
 944 }
 945
 946 static gboolean
 947 prepare_link_maybe_ghosting (GstPad ** src, GstPad ** sink,
 948     GSList ** pads_created)
 949 {
 950   GstObject *root;
 951   GstObject *e1, *e2;
 952   GSList *pads_created_local = NULL;
 953
 954   g_assert (pads_created);
 955
 956   e1 = GST_OBJECT_PARENT (*src);
 957   e2 = GST_OBJECT_PARENT (*sink);
 958
 959   if (GST_OBJECT_PARENT (e1) == GST_OBJECT_PARENT (e2)) {
 960     GST_CAT_INFO (GST_CAT_PADS, "%s and %s in same bin, no need for ghost pads",
 961         GST_OBJECT_NAME (e1), GST_OBJECT_NAME (e2));
 962     return TRUE;
 963   }
 964
 965   GST_CAT_INFO (GST_CAT_PADS, "%s and %s not in same bin, making ghost pads",
 966       GST_OBJECT_NAME (e1), GST_OBJECT_NAME (e2));
 967
 968   /* we need to setup some ghost pads */
 969   root = find_common_root (e1, e2);
 970   if (!root) {
 971     g_warning
 972         ("Trying to connect elements that don't share a common ancestor: %s and %s\n",
 973         GST_ELEMENT_NAME (e1), GST_ELEMENT_NAME (e2));
 974     return FALSE;
 975   }
 976
 977   while (GST_OBJECT_PARENT (e1) != root) {
 978     *src = ghost_up ((GstElement *) e1, *src);
 979     if (!*src)
 980       goto cleanup_fail;
 981     e1 = GST_OBJECT_PARENT (*src);
 982     pads_created_local = g_slist_prepend (pads_created_local, *src);
 983   }
 984   while (GST_OBJECT_PARENT (e2) != root) {
 985     *sink = ghost_up ((GstElement *) e2, *sink);
 986     if (!*sink)
 987       goto cleanup_fail;
 988     e2 = GST_OBJECT_PARENT (*sink);
 989     pads_created_local = g_slist_prepend (pads_created_local, *sink);
 990   }
 991
 992   gst_object_unref (root);
 993   *pads_created = g_slist_concat (*pads_created, pads_created_local);
 994   return TRUE;
 995
 996 cleanup_fail:
 997   gst_object_unref (root);
 998   g_slist_foreach (pads_created_local, remove_pad, NULL);
 999   g_slist_free (pads_created_local);
1000   return FALSE;
1001 }
1002
1003 static gboolean
1004 pad_link_maybe_ghosting (GstPad * src, GstPad * sink)
1005 {
1006   GSList *pads_created = NULL;
1007   gboolean ret;
1008
1009   if (!prepare_link_maybe_ghosting (&src, &sink, &pads_created)) {
1010     ret = FALSE;
1011   } else {
1012     ret = (gst_pad_link (src, sink) == GST_PAD_LINK_OK);
1013   }
1014
1015   if (!ret) {
1016     g_slist_foreach (pads_created, remove_pad, NULL);
1017   }
1018   g_slist_free (pads_created);
1019
1020   return ret;
1021 }
1022
1023 /**
1024  * gst_element_link_pads:
1025  * @src: a #GstElement containing the source pad.
1026  * @srcpadname: the name of the #GstPad in source element or NULL for any pad.
1027  * @dest: the #GstElement containing the destination pad.
1028  * @destpadname: the name of the #GstPad in destination element,
1029  * or NULL for any pad.
1030  *
1031  * Links the two named pads of the source and destination elements.
1032  * Side effect is that if one of the pads has no parent, it becomes a
1033  * child of the parent of the other element.  If they have different
1034  * parents, the link fails.
1035  *
1036  * Returns: TRUE if the pads could be linked, FALSE otherwise.
1037  */
1038 gboolean
1039 gst_element_link_pads (GstElement * src, const gchar * srcpadname,
1040     GstElement * dest, const gchar * destpadname)
1041 {
1042   const GList *srcpads, *destpads, *srctempls, *desttempls, *l;
1043   GstPad *srcpad, *destpad;
1044   GstPadTemplate *srctempl, *desttempl;
1045   GstElementClass *srcclass, *destclass;
1046
1047   /* checks */
1048   g_return_val_if_fail (GST_IS_ELEMENT (src), FALSE);
1049   g_return_val_if_fail (GST_IS_ELEMENT (dest), FALSE);
1050
1051   srcclass = GST_ELEMENT_GET_CLASS (src);
1052   destclass = GST_ELEMENT_GET_CLASS (dest);
1053
1054   GST_CAT_INFO (GST_CAT_ELEMENT_PADS,
1055       "trying to link element %s:%s to element %s:%s", GST_ELEMENT_NAME (src),
1056       srcpadname ? srcpadname : "(any)", GST_ELEMENT_NAME (dest),
1057       destpadname ? destpadname : "(any)");
1058
1059   /* get a src pad */
1060   if (srcpadname) {
1061     /* name specified, look it up */
1062     srcpad = gst_element_get_pad (src, srcpadname);
1063     if (!srcpad) {
1064       GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "no pad %s:%s",
1065           GST_ELEMENT_NAME (src), srcpadname);
1066       return FALSE;
1067     } else {
1068       if (!(GST_PAD_DIRECTION (srcpad) == GST_PAD_SRC)) {
1069         GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "pad %s:%s is no src pad",
1070             GST_DEBUG_PAD_NAME (srcpad));
1071         gst_object_unref (srcpad);
1072         return FALSE;
1073       }
1074       if (GST_PAD_PEER (srcpad) != NULL) {
1075         GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "pad %s:%s is already linked",
1076             GST_DEBUG_PAD_NAME (srcpad));
1077         gst_object_unref (srcpad);
1078         return FALSE;
1079       }
1080     }
1081     srcpads = NULL;
1082   } else {
1083     /* no name given, get the first available pad */
1084     GST_LOCK (src);
1085     srcpads = GST_ELEMENT_PADS (src);
1086     srcpad = srcpads ? GST_PAD_CAST (srcpads->data) : NULL;
1087     if (srcpad)
1088       gst_object_ref (srcpad);
1089     GST_UNLOCK (src);
1090   }
1091
1092   /* get a destination pad */
1093   if (destpadname) {
1094     /* name specified, look it up */
1095     destpad = gst_element_get_pad (dest, destpadname);
1096     if (!destpad) {
1097       GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "no pad %s:%s",
1098           GST_ELEMENT_NAME (dest), destpadname);
1099       return FALSE;
1100     } else {
1101       if (!(GST_PAD_DIRECTION (destpad) == GST_PAD_SINK)) {
1102         GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "pad %s:%s is no sink pad",
1103             GST_DEBUG_PAD_NAME (destpad));
1104         gst_object_unref (destpad);
1105         return FALSE;
1106       }
1107       if (GST_PAD_PEER (destpad) != NULL) {
1108         GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "pad %s:%s is already linked",
1109             GST_DEBUG_PAD_NAME (destpad));
1110         gst_object_unref (destpad);
1111         return FALSE;
1112       }
1113     }
1114     destpads = NULL;
1115   } else {
1116     /* no name given, get the first available pad */
1117     GST_LOCK (dest);
1118     destpads = GST_ELEMENT_PADS (dest);
1119     destpad = destpads ? GST_PAD_CAST (destpads->data) : NULL;
1120     if (destpad)
1121       gst_object_ref (destpad);
1122     GST_UNLOCK (dest);
1123   }
1124
1125   if (srcpadname && destpadname) {
1126     gboolean result;
1127
1128     /* two explicitly specified pads */
1129     result = pad_link_maybe_ghosting (srcpad, destpad);
1130
1131     gst_object_unref (srcpad);
1132     gst_object_unref (destpad);
1133
1134     return result;
1135   }
1136
1137   if (srcpad) {
1138     /* loop through the allowed pads in the source, trying to find a
1139      * compatible destination pad */
1140     GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS,
1141         "looping through allowed src and dest pads");
1142     do {
1143       GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "trying src pad %s:%s",
1144           GST_DEBUG_PAD_NAME (srcpad));
1145       if ((GST_PAD_DIRECTION (srcpad) == GST_PAD_SRC) &&
1146           (GST_PAD_PEER (srcpad) == NULL)) {
1147         GstPad *temp;
1148
1149         if (destpadname) {
1150           temp = destpad;
1151           gst_object_ref (temp);
1152         } else {
1153           temp = gst_element_get_compatible_pad (dest, srcpad, NULL);
1154         }
1155
1156         if (temp && pad_link_maybe_ghosting (srcpad, temp)) {
1157           GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "linked pad %s:%s to pad %s:%s",
1158               GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (temp));
1159           if (destpad)
1160             gst_object_unref (destpad);
1161           gst_object_unref (srcpad);
1162           gst_object_unref (temp);
1163           return TRUE;
1164         }
1165
1166         if (temp) {
1167           gst_object_unref (temp);
1168         }
1169       }
1170       /* find a better way for this mess */
1171       if (srcpads) {
1172         srcpads = g_list_next (srcpads);
1173         if (srcpads) {
1174           gst_object_unref (srcpad);
1175           srcpad = GST_PAD_CAST (srcpads->data);
1176           gst_object_ref (srcpad);
1177         }
1178       }
1179     } while (srcpads);
1180   }
1181   if (srcpadname) {
1182     GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "no link possible from %s:%s to %s",
1183         GST_DEBUG_PAD_NAME (srcpad), GST_ELEMENT_NAME (dest));
1184     if (srcpad)
1185       gst_object_unref (srcpad);
1186     srcpad = NULL;
1187     if (destpad)
1188       gst_object_unref (destpad);
1189     destpad = NULL;
1190   } else {
1191     if (srcpad)
1192       gst_object_unref (srcpad);
1193     srcpad = NULL;
1194   }
1195
1196   if (destpad) {
1197     /* loop through the existing pads in the destination */
1198     do {
1199       GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "trying dest pad %s:%s",
1200           GST_DEBUG_PAD_NAME (destpad));
1201       if ((GST_PAD_DIRECTION (destpad) == GST_PAD_SINK) &&
1202           (GST_PAD_PEER (destpad) == NULL)) {
1203         GstPad *temp = gst_element_get_compatible_pad (src, destpad, NULL);
1204
1205         if (temp && pad_link_maybe_ghosting (temp, destpad)) {
1206           GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "linked pad %s:%s to pad %s:%s",
1207               GST_DEBUG_PAD_NAME (temp), GST_DEBUG_PAD_NAME (destpad));
1208           gst_object_unref (temp);
1209           gst_object_unref (destpad);
1210           if (srcpad)
1211             gst_object_unref (srcpad);
1212           return TRUE;
1213         }
1214         if (temp) {
1215           gst_object_unref (temp);
1216         }
1217       }
1218       if (destpads) {
1219         destpads = g_list_next (destpads);
1220         if (destpads) {
1221           gst_object_unref (destpad);
1222           destpad = GST_PAD_CAST (destpads->data);
1223           gst_object_ref (destpad);
1224         }
1225       }
1226     } while (destpads);
1227   }
1228
1229   if (destpadname) {
1230     GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "no link possible from %s to %s:%s",
1231         GST_ELEMENT_NAME (src), GST_DEBUG_PAD_NAME (destpad));
1232     gst_object_unref (destpad);
1233     if (srcpad)
1234       gst_object_unref (srcpad);
1235     return FALSE;
1236   } else {
1237     if (srcpad)
1238       gst_object_unref (srcpad);
1239     srcpad = NULL;
1240     if (destpad)
1241       gst_object_unref (destpad);
1242     destpad = NULL;
1243   }
1244
1245   GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS,
1246       "we might have request pads on both sides, checking...");
1247   srctempls = gst_element_class_get_pad_template_list (srcclass);
1248   desttempls = gst_element_class_get_pad_template_list (destclass);
1249
1250   if (srctempls && desttempls) {
1251     while (srctempls) {
1252       srctempl = (GstPadTemplate *) srctempls->data;
1253       if (srctempl->presence == GST_PAD_REQUEST) {
1254         for (l = desttempls; l; l = l->next) {
1255           desttempl = (GstPadTemplate *) l->data;
1256           if (desttempl->presence == GST_PAD_REQUEST &&
1257               desttempl->direction != srctempl->direction) {
1258             if (gst_caps_is_always_compatible (gst_pad_template_get_caps
1259                     (srctempl), gst_pad_template_get_caps (desttempl))) {
1260               srcpad =
1261                   gst_element_get_request_pad (src, srctempl->name_template);
1262               destpad =
1263                   gst_element_get_request_pad (dest, desttempl->name_template);
1264               if (pad_link_maybe_ghosting (srcpad, destpad)) {
1265                 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS,
1266                     "linked pad %s:%s to pad %s:%s",
1267                     GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (destpad));
1268                 gst_object_unref (srcpad);
1269                 gst_object_unref (destpad);
1270                 return TRUE;
1271               }
1272               /* it failed, so we release the request pads */
1273               gst_element_release_request_pad (src, srcpad);
1274               gst_element_release_request_pad (dest, destpad);
1275             }
1276           }
1277         }
1278       }
1279       srctempls = srctempls->next;
1280     }
1281   }
1282
1283   GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "no link possible from %s to %s",
1284       GST_ELEMENT_NAME (src), GST_ELEMENT_NAME (dest));
1285   return FALSE;
1286 }
1287
1288 /**
1289  * gst_element_link_pads_filtered:
1290  * @src: a #GstElement containing the source pad.
1291  * @srcpadname: the name of the #GstPad in source element or NULL for any pad.
1292  * @dest: the #GstElement containing the destination pad.
1293  * @destpadname: the name of the #GstPad in destination element or NULL for any pad.
1294  * @filter: the #GstCaps to filter the link, or #NULL for no filter.
1295  *
1296  * Links the two named pads of the source and destination elements. Side effect
1297  * is that if one of the pads has no parent, it becomes a child of the parent of
1298  * the other element. If they have different parents, the link fails. If @caps
1299  * is not #NULL, makes sure that the caps of the link is a subset of @caps.
1300  *
1301  * Returns: TRUE if the pads could be linked, FALSE otherwise.
1302  */
1303 gboolean
1304 gst_element_link_pads_filtered (GstElement * src, const gchar * srcpadname,
1305     GstElement * dest, const gchar * destpadname, GstCaps * filter)
1306 {
1307   /* checks */
1308   g_return_val_if_fail (GST_IS_ELEMENT (src), FALSE);
1309   g_return_val_if_fail (GST_IS_ELEMENT (dest), FALSE);
1310   g_return_val_if_fail (filter == NULL || GST_IS_CAPS (filter), FALSE);
1311
1312   if (filter) {
1313     GstElement *capsfilter;
1314     GstObject *parent;
1315     GstState state, pending;
1316     GTimeVal tv;
1317
1318     capsfilter = gst_element_factory_make ("capsfilter", NULL);
1319     if (!capsfilter) {
1320       GST_ERROR ("Could not make a capsfilter");
1321       return FALSE;
1322     }
1323
1324     parent = gst_object_get_parent (GST_OBJECT (src));
1325     g_return_val_if_fail (GST_IS_BIN (parent), FALSE);
1326
1327     GST_TIME_TO_TIMEVAL (0, tv);
1328     gst_element_get_state (GST_ELEMENT_CAST (parent), &state, &pending, &tv);
1329
1330     if (!gst_bin_add (GST_BIN (parent), capsfilter)) {
1331       GST_ERROR ("Could not add capsfilter");
1332       gst_object_unref (capsfilter);
1333       gst_object_unref (parent);
1334       return FALSE;
1335     }
1336
1337     if (pending != GST_STATE_VOID_PENDING)
1338       state = pending;
1339
1340     gst_element_set_state (capsfilter, state);
1341
1342     gst_object_unref (parent);
1343
1344     g_object_set (capsfilter, "caps", filter, NULL);
1345
1346     if (gst_element_link_pads (src, srcpadname, capsfilter, "sink")
1347         && gst_element_link_pads (capsfilter, "src", dest, destpadname)) {
1348       return TRUE;
1349     } else {
1350       GST_INFO ("Could not link elements");
1351       gst_bin_remove (GST_BIN (GST_OBJECT_PARENT (capsfilter)), capsfilter);
1352       /* will unref and unlink as appropriate */
1353       return FALSE;
1354     }
1355   } else {
1356     return gst_element_link_pads (src, srcpadname, dest, destpadname);
1357   }
1358 }
1359
1360 /**
1361  * gst_element_link:
1362  * @src: a #GstElement containing the source pad.
1363  * @dest: the #GstElement containing the destination pad.
1364  *
1365  * Links @src to @dest. The link must be from source to
1366  * destination; the other direction will not be tried. The function looks for
1367  * existing pads that aren't linked yet. It will request new pads if necessary.
1368  * If multiple links are possible, only one is established.
1369  *
1370  * Returns: TRUE if the elements could be linked, FALSE otherwise.
1371  */
1372 gboolean
1373 gst_element_link (GstElement * src, GstElement * dest)
1374 {
1375   return gst_element_link_pads_filtered (src, NULL, dest, NULL, NULL);
1376 }
1377
1378 /**
1379  * gst_element_link_many:
1380  * @element_1: the first #GstElement in the link chain.
1381  * @element_2: the second #GstElement in the link chain.
1382  * @...: the NULL-terminated list of elements to link in order.
1383  *
1384  * Chain together a series of elements. Uses gst_element_link().
1385  *
1386  * Returns: TRUE on success, FALSE otherwise.
1387  */
1388 gboolean
1389 gst_element_link_many (GstElement * element_1, GstElement * element_2, ...)
1390 {
1391   va_list args;
1392
1393   g_return_val_if_fail (GST_IS_ELEMENT (element_1), FALSE);
1394   g_return_val_if_fail (GST_IS_ELEMENT (element_2), FALSE);
1395
1396   va_start (args, element_2);
1397
1398   while (element_2) {
1399     if (!gst_element_link (element_1, element_2))
1400       return FALSE;
1401
1402     element_1 = element_2;
1403     element_2 = va_arg (args, GstElement *);
1404   }
1405
1406   va_end (args);
1407
1408   return TRUE;
1409 }
1410
1411 /**
1412  * gst_element_link_filtered:
1413  * @src: a #GstElement containing the source pad.
1414  * @dest: the #GstElement containing the destination pad.
1415  * @filter: the #GstCaps to filter the link, or #NULL for no filter.
1416  *
1417  * Links @src to @dest using the given caps as filtercaps.
1418  * The link must be from source to
1419  * destination; the other direction will not be tried. The function looks for
1420  * existing pads that aren't linked yet. It will request new pads if necessary.
1421  * If multiple links are possible, only one is established.
1422  *
1423  * Returns: TRUE if the pads could be linked, FALSE otherwise.
1424  */
1425 gboolean
1426 gst_element_link_filtered (GstElement * src, GstElement * dest,
1427     GstCaps * filter)
1428 {
1429   return gst_element_link_pads_filtered (src, NULL, dest, NULL, filter);
1430 }
1431
1432 /**
1433  * gst_element_unlink_pads:
1434  * @src: a #GstElement containing the source pad.
1435  * @srcpadname: the name of the #GstPad in source element.
1436  * @dest: a #GstElement containing the destination pad.
1437  * @destpadname: the name of the #GstPad in destination element.
1438  *
1439  * Unlinks the two named pads of the source and destination elements.
1440  */
1441 void
1442 gst_element_unlink_pads (GstElement * src, const gchar * srcpadname,
1443     GstElement * dest, const gchar * destpadname)
1444 {
1445   GstPad *srcpad, *destpad;
1446
1447   g_return_if_fail (src != NULL);
1448   g_return_if_fail (GST_IS_ELEMENT (src));
1449   g_return_if_fail (srcpadname != NULL);
1450   g_return_if_fail (dest != NULL);
1451   g_return_if_fail (GST_IS_ELEMENT (dest));
1452   g_return_if_fail (destpadname != NULL);
1453
1454   /* obtain the pads requested */
1455   srcpad = gst_element_get_pad (src, srcpadname);
1456   if (srcpad == NULL) {
1457     GST_WARNING_OBJECT (src, "source element has no pad \"%s\"", srcpadname);
1458     return;
1459   }
1460   destpad = gst_element_get_pad (dest, destpadname);
1461   if (srcpad == NULL) {
1462     GST_WARNING_OBJECT (dest, "destination element has no pad \"%s\"",
1463         destpadname);
1464     return;
1465   }
1466
1467   /* we're satisified they can be unlinked, let's do it */
1468   gst_pad_unlink (srcpad, destpad);
1469 }
1470
1471 /**
1472  * gst_element_unlink_many:
1473  * @element_1: the first #GstElement in the link chain.
1474  * @element_2: the second #GstElement in the link chain.
1475  * @...: the NULL-terminated list of elements to unlink in order.
1476  *
1477  * Unlinks a series of elements. Uses gst_element_unlink().
1478  */
1479 void
1480 gst_element_unlink_many (GstElement * element_1, GstElement * element_2, ...)
1481 {
1482   va_list args;
1483
1484   g_return_if_fail (element_1 != NULL && element_2 != NULL);
1485   g_return_if_fail (GST_IS_ELEMENT (element_1) && GST_IS_ELEMENT (element_2));
1486
1487   va_start (args, element_2);
1488
1489   while (element_2) {
1490     gst_element_unlink (element_1, element_2);
1491
1492     element_1 = element_2;
1493     element_2 = va_arg (args, GstElement *);
1494   }
1495
1496   va_end (args);
1497 }
1498
1499 /**
1500  * gst_element_unlink:
1501  * @src: the source #GstElement to unlink.
1502  * @dest: the sink #GstElement to unlink.
1503  *
1504  * Unlinks all source pads of the source element with all sink pads
1505  * of the sink element to which they are linked.
1506  */
1507 void
1508 gst_element_unlink (GstElement * src, GstElement * dest)
1509 {
1510   GstIterator *pads;
1511   gboolean done = FALSE;
1512
1513   g_return_if_fail (GST_IS_ELEMENT (src));
1514   g_return_if_fail (GST_IS_ELEMENT (dest));
1515
1516   GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "unlinking \"%s\" and \"%s\"",
1517       GST_ELEMENT_NAME (src), GST_ELEMENT_NAME (dest));
1518
1519   pads = gst_element_iterate_pads (src);
1520   while (!done) {
1521     gpointer data;
1522
1523     switch (gst_iterator_next (pads, &data)) {
1524       case GST_ITERATOR_OK:
1525       {
1526         GstPad *pad = GST_PAD_CAST (data);
1527
1528         if (GST_PAD_IS_SRC (pad)) {
1529           GstPad *peerpad = gst_pad_get_peer (pad);
1530
1531           /* see if the pad is connected and is really a pad
1532            * of dest */
1533           if (peerpad) {
1534             GstElement *peerelem;
1535
1536             peerelem = gst_pad_get_parent_element (peerpad);
1537
1538             if (peerelem == dest) {
1539               gst_pad_unlink (pad, peerpad);
1540             }
1541             if (peerelem)
1542               gst_object_unref (peerelem);
1543
1544             gst_object_unref (peerpad);
1545           }
1546         }
1547         gst_object_unref (pad);
1548         break;
1549       }
1550       case GST_ITERATOR_RESYNC:
1551         gst_iterator_resync (pads);
1552         break;
1553       case GST_ITERATOR_DONE:
1554         done = TRUE;
1555         break;
1556       default:
1557         g_assert_not_reached ();
1558         break;
1559     }
1560   }
1561 }
1562
1563 gboolean
1564 gst_element_query_position (GstElement * element, GstFormat * format,
1565     gint64 * cur, gint64 * end)
1566 {
1567   GstQuery *query;
1568   gboolean ret;
1569
1570   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1571   g_return_val_if_fail (format != NULL, FALSE);
1572
1573   query = gst_query_new_position (*format);
1574   ret = gst_element_query (element, query);
1575
1576   if (ret)
1577     gst_query_parse_position (query, format, cur, end);
1578
1579   gst_query_unref (query);
1580
1581   return ret;
1582 }
1583
1584 gboolean
1585 gst_element_query_convert (GstElement * element, GstFormat src_format,
1586     gint64 src_val, GstFormat * dest_fmt, gint64 * dest_val)
1587 {
1588   GstQuery *query;
1589   gboolean ret;
1590
1591   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1592   g_return_val_if_fail (dest_fmt != NULL, FALSE);
1593   g_return_val_if_fail (dest_val != NULL, FALSE);
1594
1595   if (*dest_fmt == src_format) {
1596     *dest_val = src_val;
1597     return TRUE;
1598   }
1599
1600   query = gst_query_new_convert (src_format, src_val, *dest_fmt);
1601   ret = gst_element_query (element, query);
1602
1603   if (ret)
1604     gst_query_parse_convert (query, NULL, NULL, dest_fmt, dest_val);
1605
1606   gst_query_unref (query);
1607
1608   return ret;
1609 }
1610
1611
1612 /**
1613  * gst_pad_can_link:
1614  * @srcpad: the source #GstPad to link.
1615  * @sinkpad: the sink #GstPad to link.
1616  *
1617  * Checks if the source pad and the sink pad can be linked.
1618  * Both @srcpad and @sinkpad must be unlinked.
1619  *
1620  * Returns: TRUE if the pads can be linked, FALSE otherwise.
1621  */
1622 gboolean
1623 gst_pad_can_link (GstPad * srcpad, GstPad * sinkpad)
1624 {
1625   /* FIXME This function is gross.  It's almost a direct copy of
1626    * gst_pad_link_filtered().  Any decent programmer would attempt
1627    * to merge the two functions, which I will do some day. --ds
1628    */
1629
1630   /* generic checks */
1631   g_return_val_if_fail (GST_IS_PAD (srcpad), FALSE);
1632   g_return_val_if_fail (GST_IS_PAD (sinkpad), FALSE);
1633
1634   GST_CAT_INFO (GST_CAT_PADS, "trying to link %s:%s and %s:%s",
1635       GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
1636
1637   /* FIXME: shouldn't we convert this to g_return_val_if_fail? */
1638   if (GST_PAD_PEER (srcpad) != NULL) {
1639     GST_CAT_INFO (GST_CAT_PADS, "Source pad %s:%s has a peer, failed",
1640         GST_DEBUG_PAD_NAME (srcpad));
1641     return FALSE;
1642   }
1643   if (GST_PAD_PEER (sinkpad) != NULL) {
1644     GST_CAT_INFO (GST_CAT_PADS, "Sink pad %s:%s has a peer, failed",
1645         GST_DEBUG_PAD_NAME (sinkpad));
1646     return FALSE;
1647   }
1648   if (!GST_PAD_IS_SRC (srcpad)) {
1649     GST_CAT_INFO (GST_CAT_PADS, "Src pad %s:%s is not source pad, failed",
1650         GST_DEBUG_PAD_NAME (srcpad));
1651     return FALSE;
1652   }
1653   if (!GST_PAD_IS_SINK (sinkpad)) {
1654     GST_CAT_INFO (GST_CAT_PADS, "Sink pad %s:%s is not sink pad, failed",
1655         GST_DEBUG_PAD_NAME (sinkpad));
1656     return FALSE;
1657   }
1658   if (GST_PAD_PARENT (srcpad) == NULL) {
1659     GST_CAT_INFO (GST_CAT_PADS, "Src pad %s:%s has no parent, failed",
1660         GST_DEBUG_PAD_NAME (srcpad));
1661     return FALSE;
1662   }
1663   if (GST_PAD_PARENT (sinkpad) == NULL) {
1664     GST_CAT_INFO (GST_CAT_PADS, "Sink pad %s:%s has no parent, failed",
1665         GST_DEBUG_PAD_NAME (srcpad));
1666     return FALSE;
1667   }
1668
1669   return TRUE;
1670 }
1671
1672 /**
1673  * gst_pad_use_fixed_caps:
1674  * @pad: the pad to use
1675  *
1676  * A helper function you can use that sets the
1677  * @gst_pad_get_fixed_caps_func as the gstcaps function for the
1678  * pad. This way the function will always return the negotiated caps
1679  * or in case the pad is not negotiated, the padtemplate caps.
1680  *
1681  * Use this function on a pad that, once _set_caps() has been called
1682  * on it, it cannot be renegotiated to something else.
1683  */
1684 void
1685 gst_pad_use_fixed_caps (GstPad * pad)
1686 {
1687   gst_pad_set_getcaps_function (pad, gst_pad_get_fixed_caps_func);
1688 }
1689
1690 /**
1691  * gst_pad_get_fixed_caps_func:
1692  * @pad: the pad to use
1693  *
1694  * A helper function you can use as a GetCaps function that
1695  * will return the currently negotiated caps or the padtemplate
1696  * when NULL.
1697  *
1698  * Returns: The currently negotiated caps or the padtemplate.
1699  */
1700 GstCaps *
1701 gst_pad_get_fixed_caps_func (GstPad * pad)
1702 {
1703   GstCaps *result;
1704
1705   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1706
1707   if (GST_PAD_CAPS (pad)) {
1708     result = GST_PAD_CAPS (pad);
1709
1710     GST_CAT_DEBUG (GST_CAT_CAPS,
1711         "using pad caps %p %" GST_PTR_FORMAT, result, result);
1712
1713     result = gst_caps_ref (result);
1714     goto done;
1715   }
1716   if (GST_PAD_PAD_TEMPLATE (pad)) {
1717     GstPadTemplate *templ = GST_PAD_PAD_TEMPLATE (pad);
1718
1719     result = GST_PAD_TEMPLATE_CAPS (templ);
1720     GST_CAT_DEBUG (GST_CAT_CAPS,
1721         "using pad template %p with caps %p %" GST_PTR_FORMAT, templ, result,
1722         result);
1723
1724     result = gst_caps_ref (result);
1725     goto done;
1726   }
1727   GST_CAT_DEBUG (GST_CAT_CAPS, "pad has no caps");
1728   result = gst_caps_new_empty ();
1729
1730 done:
1731   return result;
1732 }
1733
1734 /**
1735  * gst_pad_get_parent_element:
1736  * @pad: a pad
1737  *
1738  * Gets the parent of @pad, cast to a #GstElement. If a @pad has no parent or
1739  * its parent is not an element, return NULL.
1740  *
1741  * Returns: The parent of the pad. The caller has a reference on the parent, so
1742  * unref when you're finished with it.
1743  *
1744  * MT safe.
1745  */
1746 GstElement *
1747 gst_pad_get_parent_element (GstPad * pad)
1748 {
1749   GstObject *p;
1750
1751   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1752
1753   p = gst_object_get_parent (GST_OBJECT_CAST (pad));
1754
1755   if (p && !GST_IS_ELEMENT (p)) {
1756     gst_object_unref (p);
1757     p = NULL;
1758   }
1759   return GST_ELEMENT_CAST (p);
1760 }
1761
1762 /**
1763  * gst_flow_get_name:
1764  * @ret: a #GstFlowReturn to get the name of.
1765  *
1766  * Gets a string representing the given flow return.
1767  *
1768  * Returns: a string with the name of the flow return.
1769  */
1770 G_CONST_RETURN gchar *
1771 gst_flow_get_name (GstFlowReturn ret)
1772 {
1773   switch (ret) {
1774     case GST_FLOW_RESEND:
1775       return "RESEND_BUFFER";
1776     case GST_FLOW_OK:
1777       return "OK";
1778       /* expected failures */
1779     case GST_FLOW_NOT_LINKED:
1780       return "NOT_LINKED";
1781     case GST_FLOW_WRONG_STATE:
1782       return "WRONG_STATE";
1783       /* error cases */
1784     case GST_FLOW_UNEXPECTED:
1785       return "UNEXPECTED";
1786     case GST_FLOW_NOT_NEGOTIATED:
1787       return "NOT_NEGOTIATED";
1788     case GST_FLOW_ERROR:
1789       return "ERROR";
1790     case GST_FLOW_NOT_SUPPORTED:
1791       return "NOT_SUPPORTED";
1792     default:
1793       return "UNKNOWN error";
1794   }
1795 }
1796
1797 /**
1798  * gst_object_default_error:
1799  * @source: the #GstObject that initiated the error.
1800  * @error: the GError.
1801  * @debug: an additional debug information string, or NULL.
1802  *
1803  * A default error function.
1804  *
1805  * The default handler will simply print the error string using g_print.
1806  */
1807 void
1808 gst_object_default_error (GstObject * source, GError * error, gchar * debug)
1809 {
1810   gchar *name = gst_object_get_path_string (source);
1811
1812   g_print (_("ERROR: from element %s: %s\n"), name, error->message);
1813   if (debug)
1814     g_print (_("Additional debug info:\n%s\n"), debug);
1815
1816   g_free (name);
1817 }
1818
1819 #ifdef GST_COMPILE_STATIC_REC_COND_WAIT
1820
1821 #if GLIB_SIZEOF_SYSTEM_THREAD == SIZEOF_VOID_P
1822 # define g_system_thread_equal_simple(thread1, thread2)                 \
1823    ((thread1).dummy_pointer == (thread2).dummy_pointer)
1824 # define g_system_thread_assign(dest, src)                              \
1825    ((dest).dummy_pointer = (src).dummy_pointer)
1826 #else /* GLIB_SIZEOF_SYSTEM_THREAD != SIZEOF_VOID_P */
1827 # define g_system_thread_equal_simple(thread1, thread2)                 \
1828    (memcmp (&(thread1), &(thread2), GLIB_SIZEOF_SYSTEM_THREAD) == 0)
1829 # define g_system_thread_assign(dest, src)                              \
1830    (memcpy (&(dest), &(src), GLIB_SIZEOF_SYSTEM_THREAD))
1831 #endif /* GLIB_SIZEOF_SYSTEM_THREAD == SIZEOF_VOID_P */
1832
1833 #define g_system_thread_equal(thread1, thread2)                         \
1834   (g_thread_functions_for_glib_use.thread_equal ?                       \
1835    g_thread_functions_for_glib_use.thread_equal (&(thread1), &(thread2)) :\
1836    g_system_thread_equal_simple((thread1), (thread2)))
1837
1838 static GSystemThread zero_thread;
1839
1840 gboolean
1841 g_static_rec_cond_timed_wait (GCond * cond,
1842     GStaticRecMutex * mutex, GTimeVal * end_time)
1843 {
1844   GMutex *smutex;
1845   guint depth;
1846   GSystemThread self;
1847   gboolean res;
1848
1849   if (!g_thread_supported ())
1850     return FALSE;
1851
1852   G_THREAD_UF (thread_self, (&self));
1853
1854   g_return_val_if_fail (g_system_thread_equal (self, mutex->owner), FALSE);
1855
1856   depth = mutex->depth;
1857
1858   g_system_thread_assign (mutex->owner, zero_thread);
1859   mutex->depth = 0;
1860   smutex = g_static_mutex_get_mutex (&mutex->mutex);
1861
1862   res = g_cond_timed_wait (cond, smutex, end_time);
1863
1864   g_system_thread_assign (mutex->owner, self);
1865   mutex->depth = depth;
1866
1867   return res;
1868 }
1869
1870 void
1871 g_static_rec_cond_wait (GCond * cond, GStaticRecMutex * mutex)
1872 {
1873   g_static_rec_cond_timed_wait (cond, mutex, NULL);
1874 }
1875
1876 #endif /* GST_COMPILE_STATIC_REC_COND_WAIT */
1877
1878 /**
1879  * gst_bin_add_many:
1880  * @bin: the bin to add the elements to
1881  * @element_1: the first element to add to the bin
1882  * @...: additional elements to add to the bin
1883  *
1884  * Adds a NULL-terminated list of elements to a bin.  This function is
1885  * equivalent to calling gst_bin_add() for each member of the list.
1886  */
1887 void
1888 gst_bin_add_many (GstBin * bin, GstElement * element_1, ...)
1889 {
1890   va_list args;
1891
1892   g_return_if_fail (GST_IS_BIN (bin));
1893   g_return_if_fail (GST_IS_ELEMENT (element_1));
1894
1895   va_start (args, element_1);
1896
1897   while (element_1) {
1898     gst_bin_add (bin, element_1);
1899
1900     element_1 = va_arg (args, GstElement *);
1901   }
1902
1903   va_end (args);
1904 }
1905
1906 /**
1907  * gst_bin_remove_many:
1908  * @bin: the bin to remove the elements from
1909  * @element_1: the first element to remove from the bin
1910  * @...: NULL-terminated list of elements to remove from the bin
1911  *
1912  * Remove a list of elements from a bin. This function is equivalent
1913  * to calling gst_bin_remove() with each member of the list.
1914  */
1915 void
1916 gst_bin_remove_many (GstBin * bin, GstElement * element_1, ...)
1917 {
1918   va_list args;
1919
1920   g_return_if_fail (GST_IS_BIN (bin));
1921   g_return_if_fail (GST_IS_ELEMENT (element_1));
1922
1923   va_start (args, element_1);
1924
1925   while (element_1) {
1926     gst_bin_remove (bin, element_1);
1927
1928     element_1 = va_arg (args, GstElement *);
1929   }
1930
1931   va_end (args);
1932 }
1933
1934 static void
1935 get_state_func (GstElement * element, gpointer unused)
1936 {
1937   GstStateChangeReturn ret = GST_STATE_CHANGE_ASYNC;
1938
1939   GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
1940       "new thread waiting on state change");
1941
1942   /* wait indefinitely */
1943   while (ret == GST_STATE_CHANGE_ASYNC)
1944     ret = gst_element_get_state (element, NULL, NULL, NULL);
1945
1946   GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
1947       "thread done waiting on state change");
1948
1949   gst_object_unref (element);
1950 }
1951
1952 /**
1953  * gst_bin_watch_for_state_change:
1954  * @bin: the bin to watch for state changes
1955  *
1956  * Spawns a thread calling gst_element_get_state on @bin with infinite timeout.
1957  *
1958  * In practice this is done because if a bin returns %GST_STATE_CHANGE_ASYNC
1959  * from a state change, it will not commit its state until someone calls
1960  * gst_element_get_state() on it. Thus having another thread checking the bin's
1961  * state will ensure that a state-changed message gets posted on the bus
1962  * eventually.
1963  *
1964  * This function is admittedly a bit of a hack. Bins should always post
1965  * messages. However this behavior was broken out into this function to avoid
1966  * spawning threads when scrubbing, when the bin's state is changing quickly and
1967  * asynchronously.
1968  */
1969 void
1970 gst_bin_watch_for_state_change (GstBin * bin)
1971 {
1972   static GThreadPool *pool = NULL;
1973   static GStaticMutex mutex = G_STATIC_MUTEX_INIT;
1974
1975   g_static_mutex_lock (&mutex);
1976   if (pool == NULL)
1977     pool = g_thread_pool_new ((GFunc) get_state_func, NULL, -1, FALSE, NULL);
1978   g_static_mutex_unlock (&mutex);
1979
1980   g_thread_pool_push (pool, gst_object_ref (bin), NULL);
1981 }
1982
1983 struct _GstAsyncThreadData
1984 {
1985   GstElement *element;
1986   GstState state;
1987 };
1988
1989 static void
1990 set_state_async_thread_func (struct _GstAsyncThreadData *data, gpointer unused)
1991 {
1992   GstState current, pending;
1993   GstStateChangeReturn ret = GST_STATE_CHANGE_ASYNC;
1994
1995   GST_CAT_INFO_OBJECT (GST_CAT_STATES, data->element,
1996       "new thread ensuring state change to %s",
1997       gst_element_state_get_name (data->state));
1998
1999   while (TRUE) {
2000     /* wait indefinitely */
2001     ret = gst_element_get_state (data->element, &current, &pending, NULL);
2002     GST_CAT_INFO_OBJECT (GST_CAT_STATES, data->element,
2003         "get_state returned %d, current %s, pending %s", ret,
2004         gst_element_state_get_name (current),
2005         gst_element_state_get_name (pending));
2006
2007     /* can only be SUCCESS or FAILURE */
2008     if (ret == GST_STATE_CHANGE_FAILURE) {
2009       /* we can only break, hopefully an error message was posted as well */
2010       GST_CAT_INFO_OBJECT (GST_CAT_STATES, data->element,
2011           "FAILURE during state change");
2012       break;
2013     } else if (ret == GST_STATE_CHANGE_SUCCESS) {
2014       if (current == data->state) {
2015         GST_CAT_INFO_OBJECT (GST_CAT_STATES, data->element,
2016             "successfully reached final state");
2017         break;
2018       }
2019       GST_CAT_INFO_OBJECT (GST_CAT_STATES, data->element,
2020           "setting target state %s again",
2021           gst_element_state_get_name (data->state));
2022       gst_element_set_state (data->element, data->state);
2023     } else {
2024       g_assert_not_reached ();
2025     }
2026   }
2027
2028   GST_CAT_INFO_OBJECT (GST_CAT_STATES, data->element,
2029       "thread done waiting on state change");
2030
2031   gst_object_unref (data->element);
2032   g_free (data);
2033 }
2034
2035 /**
2036  * gst_element_set_state_async:
2037  * @element: a #GstElement to change state of
2038  * @state: the element's new #GstState
2039  *
2040  * Sets the state of the element. This function will try to set the
2041  * requested state by going through all the intermediary states and calling
2042  * the class's state change function for each.  If the state change returns
2043  * #GST_STATE_CHANGE_ASYNC at any time, a thread will be started to
2044  * monitor the state change and make sure the element is brought to the
2045  * requested state.
2046  *
2047  * Returns: Result of the state change using #GstStateChangeReturn.
2048  *
2049  * MT safe.
2050  */
2051 GstStateChangeReturn
2052 gst_element_set_state_async (GstElement * element, GstState state)
2053 {
2054   GstStateChangeReturn ret;
2055   struct _GstAsyncThreadData *data;
2056
2057   ret = gst_element_set_state (element, state);
2058   if (ret == GST_STATE_CHANGE_ASYNC) {
2059     static GThreadPool *pool = NULL;
2060     static GStaticMutex mutex = G_STATIC_MUTEX_INIT;
2061
2062     GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2063         "starting new thread to ensure state change to %s",
2064         gst_element_state_get_name (state));
2065     g_static_mutex_lock (&mutex);
2066     if (pool == NULL)
2067       pool = g_thread_pool_new ((GFunc) set_state_async_thread_func,
2068           NULL, -1, FALSE, NULL);
2069     g_static_mutex_unlock (&mutex);
2070
2071     data = g_new0 (struct _GstAsyncThreadData, 1);
2072
2073     gst_object_ref (element);
2074     data->element = element;
2075     data->state = state;
2076     g_thread_pool_push (pool, data, NULL);
2077   }
2078
2079   return ret;
2080 }
2081
2082 static void
2083 gst_element_populate_std_props (GObjectClass * klass, const gchar * prop_name,
2084     guint arg_id, GParamFlags flags)
2085 {
2086   GQuark prop_id = g_quark_from_string (prop_name);
2087   GParamSpec *pspec;
2088
2089   static GQuark fd_id = 0;
2090   static GQuark blocksize_id;
2091   static GQuark bytesperread_id;
2092   static GQuark dump_id;
2093   static GQuark filesize_id;
2094   static GQuark mmapsize_id;
2095   static GQuark location_id;
2096   static GQuark offset_id;
2097   static GQuark silent_id;
2098   static GQuark touch_id;
2099
2100   if (!fd_id) {
2101     fd_id = g_quark_from_static_string ("fd");
2102     blocksize_id = g_quark_from_static_string ("blocksize");
2103     bytesperread_id = g_quark_from_static_string ("bytesperread");
2104     dump_id = g_quark_from_static_string ("dump");
2105     filesize_id = g_quark_from_static_string ("filesize");
2106     mmapsize_id = g_quark_from_static_string ("mmapsize");
2107     location_id = g_quark_from_static_string ("location");
2108     offset_id = g_quark_from_static_string ("offset");
2109     silent_id = g_quark_from_static_string ("silent");
2110     touch_id = g_quark_from_static_string ("touch");
2111   }
2112
2113   if (prop_id == fd_id) {
2114     pspec = g_param_spec_int ("fd", "File-descriptor",
2115         "File-descriptor for the file being read", 0, G_MAXINT, 0, flags);
2116   } else if (prop_id == blocksize_id) {
2117     pspec = g_param_spec_ulong ("blocksize", "Block Size",
2118         "Block size to read per buffer", 0, G_MAXULONG, 4096, flags);
2119
2120   } else if (prop_id == bytesperread_id) {
2121     pspec = g_param_spec_int ("bytesperread", "Bytes per read",
2122         "Number of bytes to read per buffer", G_MININT, G_MAXINT, 0, flags);
2123
2124   } else if (prop_id == dump_id) {
2125     pspec = g_param_spec_boolean ("dump", "Dump",
2126         "Dump bytes to stdout", FALSE, flags);
2127
2128   } else if (prop_id == filesize_id) {
2129     pspec = g_param_spec_int64 ("filesize", "File Size",
2130         "Size of the file being read", 0, G_MAXINT64, 0, flags);
2131
2132   } else if (prop_id == mmapsize_id) {
2133     pspec = g_param_spec_ulong ("mmapsize", "mmap() Block Size",
2134         "Size in bytes of mmap()d regions", 0, G_MAXULONG, 4 * 1048576, flags);
2135
2136   } else if (prop_id == location_id) {
2137     pspec = g_param_spec_string ("location", "File Location",
2138         "Location of the file to read", NULL, flags);
2139
2140   } else if (prop_id == offset_id) {
2141     pspec = g_param_spec_int64 ("offset", "File Offset",
2142         "Byte offset of current read pointer", 0, G_MAXINT64, 0, flags);
2143
2144   } else if (prop_id == silent_id) {
2145     pspec = g_param_spec_boolean ("silent", "Silent", "Don't produce events",
2146         FALSE, flags);
2147
2148   } else if (prop_id == touch_id) {
2149     pspec = g_param_spec_boolean ("touch", "Touch read data",
2150         "Touch data to force disk read before " "push ()", TRUE, flags);
2151   } else {
2152     g_warning ("Unknown - 'standard' property '%s' id %d from klass %s",
2153         prop_name, arg_id, g_type_name (G_OBJECT_CLASS_TYPE (klass)));
2154     pspec = NULL;
2155   }
2156
2157   if (pspec) {
2158     g_object_class_install_property (klass, arg_id, pspec);
2159   }
2160 }
2161
2162 /**
2163  * gst_element_class_install_std_props:
2164  * @klass: the #GstElementClass to add the properties to.
2165  * @first_name: the name of the first property.
2166  * in a NULL terminated
2167  * @...: the id and flags of the first property, followed by
2168  * further 'name', 'id', 'flags' triplets and terminated by NULL.
2169  *
2170  * Adds a list of standardized properties with types to the @klass.
2171  * the id is for the property switch in your get_prop method, and
2172  * the flags determine readability / writeability.
2173  **/
2174 void
2175 gst_element_class_install_std_props (GstElementClass * klass,
2176     const gchar * first_name, ...)
2177 {
2178   const char *name;
2179
2180   va_list args;
2181
2182   g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
2183
2184   va_start (args, first_name);
2185
2186   name = first_name;
2187
2188   while (name) {
2189     int arg_id = va_arg (args, int);
2190     int flags = va_arg (args, int);
2191
2192     gst_element_populate_std_props ((GObjectClass *) klass, name, arg_id,
2193         flags);
2194
2195     name = va_arg (args, char *);
2196   }
2197
2198   va_end (args);
2199 }
2200
2201
2202 /**
2203  * gst_buffer_merge:
2204  * @buf1: a first source #GstBuffer to merge.
2205  * @buf2: the second source #GstBuffer to merge.
2206  *
2207  * Create a new buffer that is the concatenation of the two source
2208  * buffers.  The original source buffers will not be modified or
2209  * unref'd.  Make sure you unref the source buffers if they are not used
2210  * anymore afterwards.
2211  *
2212  * If the buffers point to contiguous areas of memory, the buffer
2213  * is created without copying the data.
2214  *
2215  * Returns: the new #GstBuffer that's the concatenation of the source buffers.
2216  */
2217 GstBuffer *
2218 gst_buffer_merge (GstBuffer * buf1, GstBuffer * buf2)
2219 {
2220   GstBuffer *result;
2221
2222   /* we're just a specific case of the more general gst_buffer_span() */
2223   result = gst_buffer_span (buf1, 0, buf2, buf1->size + buf2->size);
2224
2225   return result;
2226 }
2227
2228 /**
2229  * gst_buffer_join:
2230  * @buf1: a first source #GstBuffer to join.
2231  * @buf2: the second source #GstBuffer to join.
2232  *
2233  * Create a new buffer that is the concatenation of the two source
2234  * buffers, and takes ownership of the original source buffers.
2235  *
2236  * If the buffers point to contiguous areas of memory, the buffer
2237  * is created without copying the data.
2238  *
2239  * Returns: the new #GstBuffer that's the concatenation of the source buffers.
2240  */
2241 GstBuffer *
2242 gst_buffer_join (GstBuffer * buf1, GstBuffer * buf2)
2243 {
2244   GstBuffer *result;
2245
2246   result = gst_buffer_span (buf1, 0, buf2, buf1->size + buf2->size);
2247   gst_buffer_unref (buf1);
2248   gst_buffer_unref (buf2);
2249
2250   return result;
2251 }
2252
2253
2254 /**
2255  * gst_buffer_stamp:
2256  * @dest: buffer to stamp
2257  * @src: buffer to stamp from
2258  *
2259  * Copies additional information (timestamps and offsets) from one buffer to
2260  * the other.
2261  */
2262 void
2263 gst_buffer_stamp (GstBuffer * dest, const GstBuffer * src)
2264 {
2265   g_return_if_fail (dest != NULL);
2266   g_return_if_fail (src != NULL);
2267
2268   GST_BUFFER_TIMESTAMP (dest) = GST_BUFFER_TIMESTAMP (src);
2269   GST_BUFFER_DURATION (dest) = GST_BUFFER_DURATION (src);
2270   GST_BUFFER_OFFSET (dest) = GST_BUFFER_OFFSET (src);
2271   GST_BUFFER_OFFSET_END (dest) = GST_BUFFER_OFFSET_END (src);
2272 }
2273
2274 static gboolean
2275 intersect_caps_func (GstPad * pad, GValue * ret, GstPad * orig)
2276 {
2277   if (pad != orig) {
2278     GstCaps *peercaps, *existing;
2279
2280     existing = g_value_get_pointer (ret);
2281     peercaps = gst_pad_peer_get_caps (pad);
2282     if (peercaps == NULL)
2283       peercaps = gst_caps_new_any ();
2284     g_value_set_pointer (ret, gst_caps_intersect (existing, peercaps));
2285     gst_caps_unref (existing);
2286     gst_caps_unref (peercaps);
2287   }
2288   gst_object_unref (pad);
2289   return TRUE;
2290 }
2291
2292 /**
2293  * gst_pad_proxy_getcaps:
2294  * @pad: a #GstPad to proxy.
2295  *
2296  * Calls gst_pad_get_allowed_caps() for every other pad belonging to the
2297  * same element as @pad, and returns the intersection of the results.
2298  *
2299  * This function is useful as a default getcaps function for an element
2300  * that can handle any stream format, but requires all its pads to have
2301  * the same caps.  Two such elements are tee and aggregator.
2302  *
2303  * Returns: the intersection of the other pads' allowed caps.
2304  */
2305 GstCaps *
2306 gst_pad_proxy_getcaps (GstPad * pad)
2307 {
2308   GstElement *element;
2309   GstCaps *caps, *intersected;
2310   GstIterator *iter;
2311   GstIteratorResult res;
2312   GValue ret = { 0, };
2313
2314   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2315
2316   GST_DEBUG ("proxying getcaps for %s:%s", GST_DEBUG_PAD_NAME (pad));
2317
2318   element = gst_pad_get_parent_element (pad);
2319   if (element == NULL)
2320     return NULL;
2321
2322   iter = gst_element_iterate_pads (element);
2323
2324   g_value_init (&ret, G_TYPE_POINTER);
2325   g_value_set_pointer (&ret, gst_caps_new_any ());
2326
2327   res = gst_iterator_fold (iter, (GstIteratorFoldFunction) intersect_caps_func,
2328       &ret, pad);
2329   gst_iterator_free (iter);
2330
2331   if (res != GST_ITERATOR_DONE)
2332     goto pads_changed;
2333
2334   gst_object_unref (element);
2335
2336   caps = g_value_get_pointer (&ret);
2337   g_value_unset (&ret);
2338
2339   intersected = gst_caps_intersect (caps, gst_pad_get_pad_template_caps (pad));
2340   gst_caps_unref (caps);
2341
2342   return intersected;
2343
2344   /* ERRORS */
2345 pads_changed:
2346   {
2347     g_warning ("Pad list changed during capsnego for element %s",
2348         GST_ELEMENT_NAME (element));
2349     gst_object_unref (element);
2350     return NULL;
2351   }
2352 }
2353
2354 typedef struct
2355 {
2356   GstPad *orig;
2357   GstCaps *caps;
2358 } LinkData;
2359
2360 static gboolean
2361 link_fold_func (GstPad * pad, GValue * ret, LinkData * data)
2362 {
2363   gboolean success = TRUE;
2364
2365   if (pad != data->orig) {
2366     success = gst_pad_set_caps (pad, data->caps);
2367     g_value_set_boolean (ret, success);
2368   }
2369   gst_object_unref (pad);
2370
2371   return success;
2372 }
2373
2374 /**
2375  * gst_pad_proxy_setcaps
2376  * @pad: a #GstPad to proxy from
2377  * @caps: the #GstCaps to link with
2378  *
2379  * Calls gst_pad_set_caps() for every other pad belonging to the
2380  * same element as @pad.  If gst_pad_set_caps() fails on any pad,
2381  * the proxy setcaps fails. May be used only during negotiation.
2382  *
2383  * Returns: TRUE if sucessful
2384  */
2385 gboolean
2386 gst_pad_proxy_setcaps (GstPad * pad, GstCaps * caps)
2387 {
2388   GstElement *element;
2389   GstIterator *iter;
2390   GstIteratorResult res;
2391   GValue ret = { 0, };
2392   LinkData data;
2393
2394   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2395   g_return_val_if_fail (caps != NULL, FALSE);
2396
2397   GST_DEBUG ("proxying pad link for %s:%s", GST_DEBUG_PAD_NAME (pad));
2398
2399   element = gst_pad_get_parent_element (pad);
2400   if (element == NULL)
2401     return FALSE;
2402
2403   iter = gst_element_iterate_pads (element);
2404
2405   g_value_init (&ret, G_TYPE_BOOLEAN);
2406   g_value_set_boolean (&ret, TRUE);
2407   data.orig = pad;
2408   data.caps = caps;
2409
2410   res = gst_iterator_fold (iter, (GstIteratorFoldFunction) link_fold_func,
2411       &ret, &data);
2412   gst_iterator_free (iter);
2413
2414   if (res != GST_ITERATOR_DONE)
2415     goto pads_changed;
2416
2417   gst_object_unref (element);
2418
2419   /* ok not to unset the gvalue */
2420   return g_value_get_boolean (&ret);
2421
2422   /* ERRORS */
2423 pads_changed:
2424   {
2425     g_warning ("Pad list changed during proxy_pad_link for element %s",
2426         GST_ELEMENT_NAME (element));
2427     gst_object_unref (element);
2428     return FALSE;
2429   }
2430 }
2431
2432 /**
2433  * gst_pad_query_position:
2434  * @pad: a #GstPad to invoke the position query on.
2435  * @format: a pointer to the #GstFormat asked for.
2436  *          On return contains the #GstFormat used.
2437  * @cur: A location in which to store the current position, or NULL.
2438  * @end: A location in which to store the end position (length), or NULL.
2439  *
2440  * Queries a pad for the stream position and length.
2441  *
2442  * Returns: TRUE if the query could be performed.
2443  */
2444 gboolean
2445 gst_pad_query_position (GstPad * pad, GstFormat * format, gint64 * cur,
2446     gint64 * end)
2447 {
2448   GstQuery *query;
2449   gboolean ret;
2450
2451   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2452   g_return_val_if_fail (format != NULL, FALSE);
2453
2454   query = gst_query_new_position (*format);
2455   ret = gst_pad_query (pad, query);
2456
2457   if (ret)
2458     gst_query_parse_position (query, format, cur, end);
2459
2460   gst_query_unref (query);
2461
2462   return ret;
2463 }
2464
2465 /**
2466  * gst_pad_query_convert:
2467  * @pad: a #GstPad to invoke the convert query on.
2468  * @src_format: a #GstFormat to convert from.
2469  * @src_val: a value to convert.
2470  * @dest_format: a pointer to the #GstFormat to convert to.
2471  * @dest_val: a pointer to the result.
2472  *
2473  * Queries a pad to convert @src_val in @src_format to @dest_format.
2474  *
2475  * Returns: TRUE if the query could be performed.
2476  */
2477 gboolean
2478 gst_pad_query_convert (GstPad * pad, GstFormat src_format, gint64 src_val,
2479     GstFormat * dest_format, gint64 * dest_val)
2480 {
2481   GstQuery *query;
2482   gboolean ret;
2483
2484   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2485   g_return_val_if_fail (src_val >= 0, FALSE);
2486   g_return_val_if_fail (dest_format != NULL, FALSE);
2487   g_return_val_if_fail (dest_val != NULL, FALSE);
2488
2489   if (*dest_format == src_format) {
2490     *dest_val = src_val;
2491     return TRUE;
2492   }
2493
2494   query = gst_query_new_convert (src_format, src_val, *dest_format);
2495   ret = gst_pad_query (pad, query);
2496
2497   if (ret)
2498     gst_query_parse_convert (query, NULL, NULL, dest_format, dest_val);
2499
2500   gst_query_unref (query);
2501
2502   return ret;
2503 }
2504
2505 /**
2506  * gst_atomic_int_set:
2507  * @atomic_int: pointer to an atomic integer
2508  * @value: value to set
2509  *
2510  * Unconditionally sets the atomic integer to @value.
2511  */
2512 void
2513 gst_atomic_int_set (gint * atomic_int, gint value)
2514 {
2515   int ignore;
2516
2517   *atomic_int = value;
2518   /* read acts as a memory barrier */
2519   ignore = g_atomic_int_get (atomic_int);
2520 }
2521
2522 /**
2523  * gst_pad_add_data_probe:
2524  * @pad: pad to add the data probe handler to
2525  * @handler: function to call when data is passed over pad
2526  * @data: data to pass along with the handler
2527  *
2528  * Adds a "data probe" to a pad. This function will be called whenever data
2529  * passes through a pad. In this case data means both events and buffers. The
2530  * probe will be called with the data as an argument. Note that the data will
2531  * have a reference count greater than 1, so it will be immutable -- you must
2532  * not change it.
2533  *
2534  * For source pads, the probe will be called after the blocking function, if any
2535  * (see gst_pad_set_blocked_async()), but before looking up the peer to chain
2536  * to. For sink pads, the probe function will be called before configuring the
2537  * sink with new caps, if any, and before calling the pad's chain function.
2538  *
2539  * Your data probe should return TRUE to let the data continue to flow, or FALSE
2540  * to drop it. Dropping data is rarely useful, but occasionally comes in handy
2541  * with events.
2542  *
2543  * Although probes are implemented internally by connecting @handler to the
2544  * have-data signal on the pad, if you want to remove a probe it is insufficient
2545  * to only call g_signal_handler_disconnect on the returned handler id. To
2546  * remove a probe, use the appropriate function, such as
2547  * gst_pad_remove_data_probe().
2548  *
2549  * Returns: The handler id.
2550  */
2551 gulong
2552 gst_pad_add_data_probe (GstPad * pad, GCallback handler, gpointer data)
2553 {
2554   gulong sigid;
2555
2556   g_return_val_if_fail (GST_IS_PAD (pad), 0);
2557   g_return_val_if_fail (handler != NULL, 0);
2558
2559   GST_LOCK (pad);
2560   sigid = g_signal_connect (pad, "have-data", handler, data);
2561   GST_PAD_DO_EVENT_SIGNALS (pad)++;
2562   GST_PAD_DO_BUFFER_SIGNALS (pad)++;
2563   GST_DEBUG ("adding data probe to pad %s:%s, now %d data, %d event probes",
2564       GST_DEBUG_PAD_NAME (pad),
2565       GST_PAD_DO_BUFFER_SIGNALS (pad), GST_PAD_DO_EVENT_SIGNALS (pad));
2566   GST_UNLOCK (pad);
2567
2568   return sigid;
2569 }
2570
2571 /**
2572  * gst_pad_add_event_probe:
2573  * @pad: pad to add the event probe handler to
2574  * @handler: function to call when data is passed over pad
2575  * @data: data to pass along with the handler
2576  *
2577  * Adds a probe that will be called for all events passing through a pad. See
2578  * gst_pad_add_data_probe() for more information.
2579  *
2580  * Returns: The handler id
2581  */
2582 gulong
2583 gst_pad_add_event_probe (GstPad * pad, GCallback handler, gpointer data)
2584 {
2585   gulong sigid;
2586
2587   g_return_val_if_fail (GST_IS_PAD (pad), 0);
2588   g_return_val_if_fail (handler != NULL, 0);
2589
2590   GST_LOCK (pad);
2591   sigid = g_signal_connect (pad, "have-data::event", handler, data);
2592   GST_PAD_DO_EVENT_SIGNALS (pad)++;
2593   GST_DEBUG ("adding event probe to pad %s:%s, now %d probes",
2594       GST_DEBUG_PAD_NAME (pad), GST_PAD_DO_EVENT_SIGNALS (pad));
2595   GST_UNLOCK (pad);
2596
2597   return sigid;
2598 }
2599
2600 /**
2601  * gst_pad_add_buffer_probe:
2602  * @pad: pad to add the buffer probe handler to
2603  * @handler: function to call when data is passed over pad
2604  * @data: data to pass along with the handler
2605  *
2606  * Adds a probe that will be called for all buffers passing through a pad. See
2607  * gst_pad_add_data_probe() for more information.
2608  *
2609  * Returns: The handler id
2610  */
2611 gulong
2612 gst_pad_add_buffer_probe (GstPad * pad, GCallback handler, gpointer data)
2613 {
2614   gulong sigid;
2615
2616   g_return_val_if_fail (GST_IS_PAD (pad), 0);
2617   g_return_val_if_fail (handler != NULL, 0);
2618
2619   GST_LOCK (pad);
2620   sigid = g_signal_connect (pad, "have-data::buffer", handler, data);
2621   GST_PAD_DO_BUFFER_SIGNALS (pad)++;
2622   GST_DEBUG ("adding buffer probe to pad %s:%s, now %d probes",
2623       GST_DEBUG_PAD_NAME (pad), GST_PAD_DO_BUFFER_SIGNALS (pad));
2624   GST_UNLOCK (pad);
2625
2626   return sigid;
2627 }
2628
2629 /**
2630  * gst_pad_remove_data_probe:
2631  * @pad: pad to remove the data probe handler from
2632  * @handler_id: handler id returned from gst_pad_add_data_probe
2633  *
2634  * Removes a data probe from @pad.
2635  */
2636 void
2637 gst_pad_remove_data_probe (GstPad * pad, guint handler_id)
2638 {
2639   g_return_if_fail (GST_IS_PAD (pad));
2640   g_return_if_fail (handler_id > 0);
2641
2642   GST_LOCK (pad);
2643   g_signal_handler_disconnect (pad, handler_id);
2644   GST_PAD_DO_BUFFER_SIGNALS (pad)--;
2645   GST_PAD_DO_EVENT_SIGNALS (pad)--;
2646   GST_DEBUG
2647       ("removed data probe from pad %s:%s, now %d event, %d buffer probes",
2648       GST_DEBUG_PAD_NAME (pad), GST_PAD_DO_EVENT_SIGNALS (pad),
2649       GST_PAD_DO_BUFFER_SIGNALS (pad));
2650   GST_UNLOCK (pad);
2651 }
2652
2653 /**
2654  * gst_pad_remove_event_probe:
2655  * @pad: pad to remove the event probe handler from
2656  * @handler_id: handler id returned from gst_pad_add_event_probe
2657  *
2658  * Removes an event probe from @pad.
2659  */
2660 void
2661 gst_pad_remove_event_probe (GstPad * pad, guint handler_id)
2662 {
2663   g_return_if_fail (GST_IS_PAD (pad));
2664   g_return_if_fail (handler_id > 0);
2665
2666   GST_LOCK (pad);
2667   g_signal_handler_disconnect (pad, handler_id);
2668   GST_PAD_DO_EVENT_SIGNALS (pad)--;
2669   GST_DEBUG ("removed event probe from pad %s:%s, now %d event probes",
2670       GST_DEBUG_PAD_NAME (pad), GST_PAD_DO_EVENT_SIGNALS (pad));
2671   GST_UNLOCK (pad);
2672 }
2673
2674 /**
2675  * gst_pad_remove_buffer_probe:
2676  * @pad: pad to remove the buffer probe handler from
2677  * @handler_id: handler id returned from gst_pad_add_buffer_probe
2678  *
2679  * Removes a buffer probe from @pad.
2680  */
2681 void
2682 gst_pad_remove_buffer_probe (GstPad * pad, guint handler_id)
2683 {
2684   g_return_if_fail (GST_IS_PAD (pad));
2685   g_return_if_fail (handler_id > 0);
2686
2687   GST_LOCK (pad);
2688   g_signal_handler_disconnect (pad, handler_id);
2689   GST_PAD_DO_BUFFER_SIGNALS (pad)--;
2690   GST_DEBUG ("removed buffer probe from pad %s:%s, now %d buffer probes",
2691       GST_DEBUG_PAD_NAME (pad), GST_PAD_DO_BUFFER_SIGNALS (pad));
2692   GST_UNLOCK (pad);
2693 }
2694
2695 /**
2696  * gst_element_found_tags_for_pad:
2697  * @element: element for which to post taglist to bus.
2698  * @pad: pad on which to push tag-event.
2699  * @list: the taglist to post on the bus and create event from.
2700  *
2701  * Posts a message to the bus that new tags were found and pushes the
2702  * tags as event. Takes ownership of the taglist.
2703  */
2704 void
2705 gst_element_found_tags_for_pad (GstElement * element,
2706     GstPad * pad, GstTagList * list)
2707 {
2708   g_return_if_fail (element != NULL);
2709   g_return_if_fail (pad != NULL);
2710   g_return_if_fail (list != NULL);
2711
2712   gst_pad_push_event (pad, gst_event_new_tag (gst_tag_list_copy (list)));
2713   gst_element_post_message (element,
2714       gst_message_new_tag (GST_OBJECT (element), list));
2715 }
2716
2717 static void
2718 push_and_ref (GstPad * pad, GstEvent * event)
2719 {
2720   gst_pad_push_event (pad, gst_event_ref (event));
2721 }
2722
2723 /**
2724  * gst_element_found_tags:
2725  * @element: element for which we found the tags.
2726  * @list: list of tags.
2727  *
2728  * Posts a message to the bus that new tags were found, and pushes an event
2729  * to all sourcepads. Takes ownership of the taglist.
2730  */
2731 void
2732 gst_element_found_tags (GstElement * element, GstTagList * list)
2733 {
2734   GstIterator *iter;
2735   GstEvent *event;
2736
2737   g_return_if_fail (element != NULL);
2738   g_return_if_fail (list != NULL);
2739
2740   iter = gst_element_iterate_src_pads (element);
2741   event = gst_event_new_tag (gst_tag_list_copy (list));
2742   gst_iterator_foreach (iter, (GFunc) push_and_ref, event);
2743   gst_iterator_free (iter);
2744   gst_event_unref (event);
2745
2746   gst_element_post_message (element,
2747       gst_message_new_tag (GST_OBJECT (element), list));
2748 }