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