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