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