gst/gstpad.c

   1 /* GStreamer
   2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
   3  *                    2000 Wim Taymans <wtay@chello.be>
   4  *
   5  * gstpad.c: Pads for connecting elements together
   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 /* #define GST_DEBUG_ENABLED */
  24 #include "gst_private.h"
  25
  26 #include "gstpad.h"
  27 #include "gstutils.h"
  28 #include "gstelement.h"
  29 #include "gsttype.h"
  30 #include "gstbin.h"
  31 #include "gstscheduler.h"
  32 #include "gstevent.h"
  33 #include "gstlog.h"
  34
  35 enum {
  36   TEMPL_PAD_CREATED,
  37   /* FILL ME */
  38   TEMPL_LAST_SIGNAL
  39 };
  40
  41 static GstObject *padtemplate_parent_class = NULL;
  42 static guint gst_pad_template_signals[TEMPL_LAST_SIGNAL] = { 0 };
  43
  44 GType _gst_pad_type = 0;
  45
  46 /***** Start with the base GstPad class *****/
  47 static void             gst_pad_class_init              (GstPadClass *klass);
  48 static void             gst_pad_init                    (GstPad *pad);
  49
  50 static gboolean         gst_pad_try_reconnect_filtered_func (GstRealPad *srcpad, GstRealPad *sinkpad,
  51                                                          GstCaps *caps, gboolean clear);
  52
  53 #ifndef GST_DISABLE_LOADSAVE
  54 static xmlNodePtr       gst_pad_save_thyself            (GstObject *object, xmlNodePtr parent);
  55 #endif
  56
  57 static GstObject *pad_parent_class = NULL;
  58
  59 GType
  60 gst_pad_get_type (void)
  61 {
  62   if (!_gst_pad_type) {
  63     static const GTypeInfo pad_info = {
  64       sizeof (GstPadClass), NULL, NULL,
  65       (GClassInitFunc) gst_pad_class_init, NULL, NULL,
  66       sizeof (GstPad),
  67       32,
  68       (GInstanceInitFunc) gst_pad_init, NULL
  69     };
  70     _gst_pad_type = g_type_register_static (GST_TYPE_OBJECT, "GstPad",
  71                                             &pad_info, 0);
  72   }
  73   return _gst_pad_type;
  74 }
  75
  76 static void
  77 gst_pad_class_init (GstPadClass *klass)
  78 {
  79   pad_parent_class = g_type_class_ref (GST_TYPE_OBJECT);
  80 }
  81
  82 static void
  83 gst_pad_init (GstPad *pad)
  84 {
  85   pad->element_private = NULL;
  86
  87   pad->padtemplate = NULL;
  88 }
  89
  90
  91
  92 /***** Then do the Real Pad *****/
  93 /* Pad signals and args */
  94 enum {
  95   REAL_CAPS_NEGO_FAILED,
  96   REAL_CONNECTED,
  97   REAL_DISCONNECTED,
  98   /* FILL ME */
  99   REAL_LAST_SIGNAL
 100 };
 101
 102 enum {
 103   REAL_ARG_0,
 104   REAL_ARG_CAPS,
 105   REAL_ARG_ACTIVE,
 106   /* FILL ME */
 107 };
 108
 109 static void     gst_real_pad_class_init         (GstRealPadClass *klass);
 110 static void     gst_real_pad_init               (GstRealPad *pad);
 111
 112 static void     gst_real_pad_set_property       (GObject *object, guint prop_id,
 113                                                  const GValue *value,
 114                                                  GParamSpec *pspec);
 115 static void     gst_real_pad_get_property       (GObject *object, guint prop_id,
 116                                                  GValue *value,
 117                                                  GParamSpec *pspec);
 118
 119 static void     gst_real_pad_dispose            (GObject *object);
 120
 121 GType _gst_real_pad_type = 0;
 122
 123 static GstPad *real_pad_parent_class = NULL;
 124 static guint gst_real_pad_signals[REAL_LAST_SIGNAL] = { 0 };
 125
 126 GType
 127 gst_real_pad_get_type (void) {
 128   if (!_gst_real_pad_type) {
 129     static const GTypeInfo pad_info = {
 130       sizeof (GstRealPadClass), NULL, NULL,
 131       (GClassInitFunc) gst_real_pad_class_init, NULL, NULL,
 132       sizeof (GstRealPad),
 133       32,
 134       (GInstanceInitFunc) gst_real_pad_init, NULL
 135     };
 136     _gst_real_pad_type = g_type_register_static (GST_TYPE_PAD, "GstRealPad",
 137                                                  &pad_info, 0);
 138   }
 139   return _gst_real_pad_type;
 140 }
 141
 142 static void
 143 gst_real_pad_class_init (GstRealPadClass *klass)
 144 {
 145   GObjectClass *gobject_class;
 146   GstObjectClass *gstobject_class;
 147
 148   gobject_class = (GObjectClass*) klass;
 149   gstobject_class = (GstObjectClass*) klass;
 150
 151   real_pad_parent_class = g_type_class_ref (GST_TYPE_PAD);
 152
 153   gobject_class->dispose  = GST_DEBUG_FUNCPTR (gst_real_pad_dispose);
 154   gobject_class->set_property  = GST_DEBUG_FUNCPTR (gst_real_pad_set_property);
 155   gobject_class->get_property  = GST_DEBUG_FUNCPTR (gst_real_pad_get_property);
 156
 157   gst_real_pad_signals[REAL_CAPS_NEGO_FAILED] =
 158     g_signal_new ("caps_nego_failed", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 159                   G_STRUCT_OFFSET (GstRealPadClass, caps_nego_failed), NULL, NULL,
 160                   gst_marshal_VOID__POINTER, G_TYPE_NONE, 1,
 161                   G_TYPE_POINTER);
 162   gst_real_pad_signals[REAL_CONNECTED] =
 163     g_signal_new ("connected", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 164                   G_STRUCT_OFFSET (GstRealPadClass, connected), NULL, NULL,
 165                   gst_marshal_VOID__POINTER, G_TYPE_NONE, 1,
 166                   G_TYPE_POINTER);
 167   gst_real_pad_signals[REAL_DISCONNECTED] =
 168     g_signal_new ("disconnected", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 169                   G_STRUCT_OFFSET (GstRealPadClass, disconnected), NULL, NULL,
 170                   gst_marshal_VOID__POINTER, G_TYPE_NONE, 1,
 171                   G_TYPE_POINTER);
 172
 173 /*  gtk_object_add_arg_type ("GstRealPad::active", G_TYPE_BOOLEAN, */
 174 /*                           GTK_ARG_READWRITE, REAL_ARG_ACTIVE); */
 175   g_object_class_install_property (G_OBJECT_CLASS (klass), REAL_ARG_ACTIVE,
 176     g_param_spec_boolean ("active", "Active", "Whether the pad is active.",
 177                           TRUE, G_PARAM_READWRITE));
 178   g_object_class_install_property (G_OBJECT_CLASS (klass), REAL_ARG_CAPS,
 179     g_param_spec_boxed ("caps", "Caps", "The capabilities of the pad",
 180                         GST_TYPE_CAPS, G_PARAM_READABLE));
 181
 182 #ifndef GST_DISABLE_LOADSAVE
 183   gstobject_class->save_thyself = GST_DEBUG_FUNCPTR (gst_pad_save_thyself);
 184 #endif
 185   gstobject_class->path_string_separator = ".";
 186 }
 187
 188 static void
 189 gst_real_pad_init (GstRealPad *pad)
 190 {
 191   pad->direction = GST_PAD_UNKNOWN;
 192   pad->peer = NULL;
 193
 194   pad->chainfunc = NULL;
 195   pad->getfunc = NULL;
 196
 197   pad->chainhandler = NULL;
 198   pad->gethandler = NULL;
 199
 200   pad->bufferpoolfunc = NULL;
 201   pad->ghostpads = NULL;
 202   pad->caps = NULL;
 203
 204   pad->connectfunc = NULL;
 205   pad->getcapsfunc = NULL;
 206
 207   pad->convertfunc      = gst_pad_convert_default;
 208   pad->eventfunc        = gst_pad_event_default;
 209   pad->convertfunc      = gst_pad_convert_default;
 210   pad->queryfunc        = gst_pad_query_default;
 211   pad->intconnfunc      = gst_pad_get_internal_connections_default;
 212
 213   pad->eventmaskfunc    = gst_pad_get_event_masks_default;
 214   pad->formatsfunc      = gst_pad_get_formats_default;
 215   pad->querytypefunc    = gst_pad_get_query_types_default;
 216
 217   gst_probe_dispatcher_init (&pad->probedisp);
 218 }
 219
 220 static void
 221 gst_real_pad_set_property (GObject *object, guint prop_id,
 222                            const GValue *value, GParamSpec *pspec)
 223 {
 224   g_return_if_fail (GST_IS_PAD (object));
 225
 226   switch (prop_id) {
 227     case REAL_ARG_ACTIVE:
 228       gst_pad_set_active (GST_PAD (object), g_value_get_boolean (value));
 229       break;
 230     default:
 231       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 232       break;
 233   }
 234 }
 235
 236 static void
 237 gst_real_pad_get_property (GObject *object, guint prop_id,
 238                            GValue *value, GParamSpec *pspec)
 239 {
 240   g_return_if_fail (GST_IS_PAD (object));
 241
 242   switch (prop_id) {
 243     case REAL_ARG_ACTIVE:
 244       g_value_set_boolean (value, !GST_FLAG_IS_SET (object, GST_PAD_DISABLED));
 245       break;
 246     case REAL_ARG_CAPS:
 247       g_value_set_boxed (value, GST_PAD_CAPS (GST_REAL_PAD (object)));
 248       break;
 249     default:
 250       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 251       break;
 252   }
 253 }
 254
 255
 256 /**
 257  * gst_pad_custom_new:
 258  * @type: the #Gtype of the pad.
 259  * @name: the name of the new pad.
 260  * @direction: the #GstPadDirection of the pad.
 261  *
 262  * Creates a new pad with the given name and type in the given direction.
 263  * If name is NULL, a guaranteed unique name (across all pads)
 264  * will be assigned.
 265  *
 266  * Returns: a new #GstPad, or NULL in case of an error.
 267  */
 268 GstPad*
 269 gst_pad_custom_new (GType type, const gchar *name,
 270                     GstPadDirection direction)
 271 {
 272   GstRealPad *pad;
 273
 274   g_return_val_if_fail (direction != GST_PAD_UNKNOWN, NULL);
 275
 276   pad = g_object_new (type, NULL);
 277   gst_object_set_name (GST_OBJECT (pad), name);
 278   GST_RPAD_DIRECTION (pad) = direction;
 279
 280   return GST_PAD (pad);
 281 }
 282
 283 /**
 284  * gst_pad_new:
 285  * @name: the name of the new pad.
 286  * @direction: the #GstPadDirection of the pad.
 287  *
 288  * Creates a new real pad with the given name in the given direction.
 289  * If name is NULL, a guaranteed unique name (across all pads)
 290  * will be assigned.
 291  *
 292  * Returns: a new #GstPad, or NULL in case of an error.
 293  */
 294 GstPad*
 295 gst_pad_new (const gchar *name,
 296              GstPadDirection direction)
 297 {
 298   return gst_pad_custom_new (gst_real_pad_get_type (), name, direction);
 299 }
 300
 301 /**
 302  * gst_pad_custom_new_from_template:
 303  * @type: the custom #GType of the pad.
 304  * @templ: the #GstPadTemplate to instantiate from.
 305  * @name: the name of the new pad.
 306  *
 307  * Creates a new custom pad with the given name from the given template.
 308  * If name is NULL, a guaranteed unique name (across all pads)
 309  * will be assigned.
 310  *
 311  * Returns: a new #GstPad, or NULL in case of an error.
 312  */
 313 GstPad*
 314 gst_pad_custom_new_from_template (GType type, GstPadTemplate *templ,
 315                                   const gchar *name)
 316 {
 317   GstPad *pad;
 318
 319   g_return_val_if_fail (templ != NULL, NULL);
 320
 321   pad = gst_pad_new (name, templ->direction);
 322
 323   gst_object_ref (GST_OBJECT (templ));
 324   GST_PAD_PAD_TEMPLATE (pad) = templ;
 325
 326   g_signal_emit (G_OBJECT (templ), gst_pad_template_signals[TEMPL_PAD_CREATED], 0, pad);
 327
 328   return pad;
 329 }
 330
 331 /**
 332  * gst_pad_new_from_template:
 333  * @templ: the pad template to use
 334  * @name: the name of the element
 335  *
 336  * Creates a new real pad with the given name from the given template.
 337  * If name is NULL, a guaranteed unique name (across all pads)
 338  * will be assigned.
 339  *
 340  * Returns: a new #GstPad, or NULL in case of an error.
 341  */
 342 GstPad*
 343 gst_pad_new_from_template (GstPadTemplate *templ, const gchar *name)
 344 {
 345   return gst_pad_custom_new_from_template (gst_real_pad_get_type (),
 346                                            templ, name);
 347 }
 348
 349 /**
 350  * gst_pad_get_direction:
 351  * @pad: a #GstPad to get the direction of.
 352  *
 353  * Gets the direction of the pad.
 354  *
 355  * Returns: the #GstPadDirection of the pad.
 356  */
 357 GstPadDirection
 358 gst_pad_get_direction (GstPad *pad)
 359 {
 360   g_return_val_if_fail (GST_IS_PAD (pad), GST_PAD_UNKNOWN);
 361
 362   return GST_PAD_DIRECTION (pad);
 363 }
 364
 365 /**
 366  * gst_pad_set_active:
 367  * @pad: the #GstPad to activate or deactivate.
 368  * @active: TRUE to activate the pad.
 369  *
 370  * Activates or deactivates the given pad.
 371  */
 372 void
 373 gst_pad_set_active (GstPad *pad, gboolean active)
 374 {
 375   GstRealPad *realpad;
 376   gboolean old;
 377
 378   g_return_if_fail (GST_IS_PAD (pad));
 379
 380   old = GST_PAD_IS_ACTIVE (pad);
 381
 382   if (old == active)
 383     return;
 384
 385   realpad = GST_PAD_REALIZE (pad);
 386
 387   if (active) {
 388     GST_DEBUG (GST_CAT_PADS, "activating pad %s:%s",
 389                GST_DEBUG_PAD_NAME (realpad));
 390     GST_FLAG_UNSET (realpad, GST_PAD_DISABLED);
 391   } else {
 392     GST_DEBUG (GST_CAT_PADS, "de-activating pad %s:%s",
 393                GST_DEBUG_PAD_NAME (realpad));
 394     GST_FLAG_SET (realpad, GST_PAD_DISABLED);
 395   }
 396   if (old != active)
 397     g_object_notify (G_OBJECT (realpad), "active");
 398 }
 399
 400 /**
 401  * gst_pad_is_active:
 402  * @pad: the #GstPad to query
 403  *
 404  * Query if a pad is active
 405  *
 406  * Returns: TRUE if the pad is active.
 407  */
 408 gboolean
 409 gst_pad_is_active (GstPad *pad)
 410 {
 411   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
 412
 413   return !GST_FLAG_IS_SET (pad, GST_PAD_DISABLED);
 414 }
 415
 416 /**
 417  * gst_pad_set_name:
 418  * @pad: a #GstPad to set the name of.
 419  * @name: the name of the pad.
 420  *
 421  * Sets the name of a pad.  If name is NULL, then a guaranteed unique
 422  * name will be assigned.
 423  */
 424 void
 425 gst_pad_set_name (GstPad *pad, const gchar *name)
 426 {
 427   g_return_if_fail (GST_IS_PAD (pad));
 428
 429   gst_object_set_name (GST_OBJECT (pad), name);
 430 }
 431
 432 /**
 433  * gst_pad_get_name:
 434  * @pad: a #GstPad to get the name of.
 435  *
 436  * Gets the name of a pad.
 437  *
 438  * Returns: the name of the pad.  This is not a newly allocated pointer
 439  * so you must not free it.
 440  */
 441 const gchar*
 442 gst_pad_get_name (GstPad *pad)
 443 {
 444   g_return_val_if_fail (pad != NULL, NULL);
 445   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
 446
 447   return GST_OBJECT_NAME (pad);
 448 }
 449
 450 /**
 451  * gst_pad_set_chain_function:
 452  * @pad: a #GstPad to set the chain function for.
 453  * @chain: the #GstPadChainFunction to set.
 454  *
 455  * Sets the given chain function for the pad.
 456  */
 457 void
 458 gst_pad_set_chain_function (GstPad *pad, GstPadChainFunction chain)
 459 {
 460   g_return_if_fail (pad != NULL);
 461   g_return_if_fail (GST_IS_REAL_PAD (pad));
 462
 463   GST_RPAD_CHAINFUNC (pad) = chain;
 464   GST_DEBUG (GST_CAT_PADS, "chainfunc for %s:%s set to %s",
 465              GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (chain));
 466 }
 467
 468 /**
 469  * gst_pad_set_get_function:
 470  * @pad: a #GstPad to set the get function for.
 471  * @get: the #GstPadGetFunction to set.
 472  *
 473  * Sets the given get function for the pad.
 474  */
 475 void
 476 gst_pad_set_get_function (GstPad *pad,
 477                           GstPadGetFunction get)
 478 {
 479   g_return_if_fail (pad != NULL);
 480   g_return_if_fail (GST_IS_REAL_PAD (pad));
 481
 482   GST_RPAD_GETFUNC (pad) = get;
 483
 484   GST_DEBUG (GST_CAT_PADS, "getfunc for %s:%s  set to %s",
 485              GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (get));
 486 }
 487
 488 /**
 489  * gst_pad_set_event_function:
 490  * @pad: a #GstPad to set the event handler for.
 491  * @event: the #GstPadEventFunction to set.
 492  *
 493  * Sets the given event handler for the pad.
 494  */
 495 void
 496 gst_pad_set_event_function (GstPad *pad,
 497                             GstPadEventFunction event)
 498 {
 499   g_return_if_fail (GST_IS_REAL_PAD (pad));
 500
 501   GST_RPAD_EVENTFUNC (pad) = event;
 502
 503   GST_DEBUG (GST_CAT_PADS, "eventfunc for %s:%s  set to %s",
 504              GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (event));
 505 }
 506
 507 /**
 508  * gst_pad_set_event_mask_function:
 509  * @pad: a #GstPad to set the event mask function for.
 510  * @mask_func: the #GstPadEventMaskFunction to set.
 511  *
 512  * Sets the given event mask function for the pad.
 513  */
 514 void
 515 gst_pad_set_event_mask_function (GstPad *pad,
 516                                  GstPadEventMaskFunction mask_func)
 517 {
 518   g_return_if_fail (GST_IS_REAL_PAD (pad));
 519
 520   GST_RPAD_EVENTMASKFUNC (pad) = mask_func;
 521
 522   GST_DEBUG (GST_CAT_PADS, "eventmaskfunc for %s:%s  set to %s",
 523              GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (mask_func));
 524 }
 525
 526 /**
 527  * gst_pad_get_event_masks:
 528  * @pad: a #GstPad to get the event mask for.
 529  *
 530  * Gets the array of eventmasks from the given pad.
 531  *
 532  * Returns: an array with eventmasks, the list is ended
 533  * with 0
 534  */
 535 const GstEventMask*
 536 gst_pad_get_event_masks (GstPad *pad)
 537 {
 538   GstRealPad *rpad;
 539
 540   if (pad == NULL)
 541     return FALSE;
 542
 543   rpad = GST_PAD_REALIZE (pad);
 544
 545   g_return_val_if_fail (rpad, FALSE);
 546
 547   if (GST_RPAD_EVENTMASKFUNC (rpad))
 548     return GST_RPAD_EVENTMASKFUNC (rpad) (GST_PAD_CAST (pad));
 549
 550   return NULL;
 551 }
 552
 553 static gboolean
 554 gst_pad_get_event_masks_dispatcher (GstPad *pad, const GstEventMask **data)
 555 {
 556   *data = gst_pad_get_event_masks (pad);
 557
 558   return TRUE;
 559 }
 560
 561 /**
 562  * gst_pad_get_event_masks_default:
 563  * @pad: a #GstPad to get the event mask for.
 564  *
 565  * Invokes the default event masks dispatcher on the pad.
 566  *
 567  * Returns: an array with eventmasks, the list is ended
 568  * with 0
 569  */
 570 const GstEventMask*
 571 gst_pad_get_event_masks_default (GstPad *pad)
 572 {
 573   GstEventMask *result = NULL;
 574
 575   gst_pad_dispatcher (pad, (GstPadDispatcherFunction)
 576                            gst_pad_get_event_masks_dispatcher, &result);
 577
 578   return result;
 579 }
 580
 581 /**
 582  * gst_pad_handles_event:
 583  * @pad: a #GstPad to check
 584  * @mask: the mask to check
 585  *
 586  * Checks if the pad can handle the given eventmask.
 587  *
 588  * Returns: TRUE if the pad can handle the given eventmask
 589  */
 590 gboolean
 591 gst_pad_handles_event (GstPad *pad, GstEventMask *mask)
 592 {
 593   const GstEventMask *masks;
 594
 595   g_return_val_if_fail (pad != NULL, FALSE);
 596   g_return_val_if_fail (mask != NULL, FALSE);
 597
 598   masks = gst_pad_get_event_masks (pad);
 599   if (!masks)
 600     return FALSE;
 601
 602   while (masks->type) {
 603     if (masks->type == mask->type &&
 604         (masks->flags & mask->flags) == mask->flags)
 605       return TRUE;
 606
 607     masks++;
 608   }
 609
 610   return FALSE;
 611 }
 612
 613 /**
 614  * gst_pad_set_convert_function:
 615  * @pad: a #GstPad to set the convert function for.
 616  * @convert: the #GstPadConvertFunction to set.
 617  *
 618  * Sets the given convert function for the pad.
 619  */
 620 void
 621 gst_pad_set_convert_function (GstPad *pad,
 622                               GstPadConvertFunction convert)
 623 {
 624   g_return_if_fail (pad != NULL);
 625   g_return_if_fail (GST_IS_REAL_PAD (pad));
 626
 627   GST_RPAD_CONVERTFUNC (pad) = convert;
 628
 629   GST_DEBUG (GST_CAT_PADS, "convertfunc for %s:%s  set to %s",
 630              GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (convert));
 631 }
 632
 633 /**
 634  * gst_pad_set_query_function:
 635  * @pad: the #GstPad to set the query function for.
 636  * @query: the #GstPadQueryFunction to set.
 637  *
 638  * Set the given query function for the pad.
 639  */
 640 void
 641 gst_pad_set_query_function (GstPad *pad, GstPadQueryFunction query)
 642 {
 643   g_return_if_fail (pad != NULL);
 644   g_return_if_fail (GST_IS_REAL_PAD (pad));
 645
 646   GST_RPAD_QUERYFUNC (pad) = query;
 647
 648   GST_DEBUG (GST_CAT_PADS, "queryfunc for %s:%s  set to %s",
 649              GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (query));
 650 }
 651
 652 /**
 653  * gst_pad_set_query_type_function:
 654  * @pad: the #GstPad to set the query type function for.
 655  * @type_func: the #GstPadQueryTypeFunction to set.
 656  *
 657  * Set the given query type function for the pad.
 658  */
 659 void
 660 gst_pad_set_query_type_function (GstPad *pad, GstPadQueryTypeFunction type_func)
 661 {
 662   g_return_if_fail (pad != NULL);
 663   g_return_if_fail (GST_IS_REAL_PAD (pad));
 664
 665   GST_RPAD_QUERYTYPEFUNC (pad) = type_func;
 666
 667   GST_DEBUG (GST_CAT_PADS, "querytypefunc for %s:%s  set to %s",
 668              GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (type_func));
 669 }
 670
 671 /**
 672  * gst_pad_get_query_types:
 673  * @pad: the #GstPad to query
 674  *
 675  * Get an array of supported queries that can be performed
 676  * on this pad.
 677  *
 678  * Returns: an array of querytypes anded with 0.
 679  */
 680 const GstPadQueryType*
 681 gst_pad_get_query_types (GstPad *pad)
 682 {
 683   GstRealPad *rpad;
 684
 685   if (pad == NULL)
 686     return FALSE;
 687
 688   rpad = GST_PAD_REALIZE (pad);
 689
 690   g_return_val_if_fail (rpad, FALSE);
 691
 692   if (GST_RPAD_QUERYTYPEFUNC (rpad))
 693     return GST_RPAD_QUERYTYPEFUNC (rpad) (GST_PAD_CAST (pad));
 694
 695   return NULL;
 696 }
 697
 698 static gboolean
 699 gst_pad_get_query_types_dispatcher (GstPad *pad, const GstPadQueryType **data)
 700 {
 701   *data = gst_pad_get_query_types (pad);
 702
 703   return TRUE;
 704 }
 705
 706 /**
 707  * gst_pad_get_query_types_default:
 708  * @pad: the #GstPad to query
 709  *
 710  * Invoke the default dispatcher for the query types on
 711  * the pad.
 712  *
 713  * Returns: an array of querytypes anded with 0.
 714  */
 715 const GstPadQueryType*
 716 gst_pad_get_query_types_default (GstPad *pad)
 717 {
 718   GstPadQueryType *result = NULL;
 719
 720   gst_pad_dispatcher (pad, (GstPadDispatcherFunction)
 721                            gst_pad_get_query_types_dispatcher, &result);
 722
 723   return result;
 724 }
 725
 726 /**
 727  * gst_pad_set_internal_connection_function:
 728  * @pad: a #GstPad to set the internal connection function for.
 729  * @intconn: the #GstPadIntConnFunction to set.
 730  *
 731  * Sets the given internal connection function for the pad.
 732  */
 733 void
 734 gst_pad_set_internal_connection_function (GstPad *pad,
 735                                           GstPadIntConnFunction intconn)
 736 {
 737   g_return_if_fail (pad != NULL);
 738   g_return_if_fail (GST_IS_REAL_PAD (pad));
 739
 740   GST_RPAD_INTCONNFUNC (pad) = intconn;
 741   GST_DEBUG (GST_CAT_PADS, "internal connection for %s:%s  set to %s",
 742              GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (intconn));
 743 }
 744
 745 /**
 746  * gst_pad_set_formats_function:
 747  * @pad: the #GstPad to set the formats function for.
 748  * @formats: the #GstPadFormatsFunction to set.
 749  *
 750  * Sets the given formats function for the pad.
 751  */
 752 void
 753 gst_pad_set_formats_function (GstPad *pad, GstPadFormatsFunction formats)
 754 {
 755   g_return_if_fail (pad != NULL);
 756   g_return_if_fail (GST_IS_REAL_PAD (pad));
 757
 758   GST_RPAD_FORMATSFUNC (pad) = formats;
 759   GST_DEBUG (GST_CAT_PADS, "formats function for %s:%s  set to %s",
 760              GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (formats));
 761 }
 762
 763 /**
 764  * gst_pad_set_connect_function:
 765  * @pad: a #GstPad to set the connect function for.
 766  * @connect: the #GstPadConnectFunction to set.
 767  *
 768  * Sets the given connect function for the pad. It will be called
 769  * when the pad is connected or reconnected with caps.
 770  */
 771 void
 772 gst_pad_set_connect_function (GstPad *pad,
 773                               GstPadConnectFunction connect)
 774 {
 775   g_return_if_fail (pad != NULL);
 776   g_return_if_fail (GST_IS_REAL_PAD (pad));
 777
 778   GST_RPAD_CONNECTFUNC (pad) = connect;
 779   GST_DEBUG (GST_CAT_PADS, "connectfunc for %s:%s set to %s",
 780              GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (connect));
 781 }
 782
 783 /**
 784  * gst_pad_set_getcaps_function:
 785  * @pad: a #GstPad to set the getcaps function for.
 786  * @getcaps: the #GstPadGetCapsFunction to set.
 787  *
 788  * Sets the given getcaps function for the pad.
 789  */
 790 void
 791 gst_pad_set_getcaps_function (GstPad *pad,
 792                               GstPadGetCapsFunction getcaps)
 793 {
 794   g_return_if_fail (pad != NULL);
 795   g_return_if_fail (GST_IS_REAL_PAD (pad));
 796
 797   GST_RPAD_GETCAPSFUNC (pad) = getcaps;
 798   GST_DEBUG (GST_CAT_PADS, "getcapsfunc for %s:%s set to %s",
 799              GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (getcaps));
 800 }
 801 /**
 802  * gst_pad_set_bufferpool_function:
 803  * @pad: a #GstPad to set the bufferpool function for.
 804  * @bufpool: the #GstPadBufferPoolFunction to set.
 805  *
 806  * Sets the given bufferpool function for the pad. Note that the
 807  * bufferpool function can only be set on sinkpads.
 808  */
 809 void
 810 gst_pad_set_bufferpool_function (GstPad *pad,
 811                                  GstPadBufferPoolFunction bufpool)
 812 {
 813   g_return_if_fail (pad != NULL);
 814   g_return_if_fail (GST_IS_REAL_PAD (pad));
 815   g_return_if_fail (GST_PAD_IS_SINK (pad));
 816
 817   GST_RPAD_BUFFERPOOLFUNC (pad) = bufpool;
 818   GST_DEBUG (GST_CAT_PADS, "bufferpoolfunc for %s:%s set to %s",
 819              GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (bufpool));
 820 }
 821
 822 /**
 823  * gst_pad_disconnect:
 824  * @srcpad: the source #GstPad to disconnect.
 825  * @sinkpad: the sink #GstPad to disconnect.
 826  *
 827  * Disconnects the source pad from the sink pad.
 828  */
 829 void
 830 gst_pad_disconnect (GstPad *srcpad,
 831                     GstPad *sinkpad)
 832 {
 833   GstRealPad *realsrc, *realsink;
 834   GstScheduler *src_sched, *sink_sched;
 835
 836   /* generic checks */
 837   g_return_if_fail (srcpad != NULL);
 838   g_return_if_fail (GST_IS_PAD (srcpad));
 839   g_return_if_fail (sinkpad != NULL);
 840   g_return_if_fail (GST_IS_PAD (sinkpad));
 841
 842   GST_INFO (GST_CAT_ELEMENT_PADS, "disconnecting %s:%s(%p) and %s:%s(%p)",
 843             GST_DEBUG_PAD_NAME (srcpad), srcpad,
 844             GST_DEBUG_PAD_NAME (sinkpad), sinkpad);
 845
 846   /* now we need to deal with the real/ghost stuff */
 847   realsrc = GST_PAD_REALIZE (srcpad);
 848   realsink = GST_PAD_REALIZE (sinkpad);
 849
 850   g_return_if_fail (GST_RPAD_PEER (realsrc) != NULL);
 851   g_return_if_fail (GST_RPAD_PEER (realsink) == realsrc);
 852
 853   if ((GST_RPAD_DIRECTION (realsrc) == GST_PAD_SINK) &&
 854       (GST_RPAD_DIRECTION (realsink) == GST_PAD_SRC)) {
 855     GstRealPad *temppad;
 856
 857     temppad = realsrc;
 858     realsrc = realsink;
 859     realsink = temppad;
 860   }
 861   g_return_if_fail ((GST_RPAD_DIRECTION (realsrc) == GST_PAD_SRC) &&
 862                     (GST_RPAD_DIRECTION (realsink) == GST_PAD_SINK));
 863
 864   /* get the schedulers before we disconnect */
 865   src_sched = gst_pad_get_scheduler (GST_PAD_CAST (realsrc));
 866   sink_sched = gst_pad_get_scheduler (GST_PAD_CAST (realsink));
 867
 868   /* first clear peers */
 869   GST_RPAD_PEER (realsrc) = NULL;
 870   GST_RPAD_PEER (realsink) = NULL;
 871
 872   /* reset the filters, both filters are refcounted once */
 873   if (GST_RPAD_FILTER (realsrc)) {
 874     gst_caps_unref (GST_RPAD_FILTER (realsrc));
 875     GST_RPAD_FILTER (realsink) = NULL;
 876     GST_RPAD_FILTER (realsrc) = NULL;
 877   }
 878
 879   /* now tell the scheduler */
 880   if (src_sched && src_sched == sink_sched) {
 881     gst_scheduler_pad_disconnect (src_sched,
 882                                   GST_PAD_CAST (realsrc), GST_PAD_CAST (realsink));
 883   }
 884
 885   /* hold a reference, as they can go away in the signal handlers */
 886   gst_object_ref (GST_OBJECT (realsrc));
 887   gst_object_ref (GST_OBJECT (realsink));
 888
 889   /* fire off a signal to each of the pads telling them
 890    * that they've been disconnected */
 891   g_signal_emit (G_OBJECT (realsrc), gst_real_pad_signals[REAL_DISCONNECTED],
 892                  0, realsink);
 893   g_signal_emit (G_OBJECT (realsink), gst_real_pad_signals[REAL_DISCONNECTED],
 894                  0, realsrc);
 895
 896   GST_INFO (GST_CAT_ELEMENT_PADS, "disconnected %s:%s and %s:%s",
 897             GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
 898
 899   gst_object_unref (GST_OBJECT (realsrc));
 900   gst_object_unref (GST_OBJECT (realsink));
 901 }
 902
 903 static gboolean
 904 gst_pad_check_schedulers (GstRealPad *realsrc, GstRealPad *realsink)
 905 {
 906   GstScheduler *src_sched, *sink_sched;
 907   gint num_decoupled = 0;
 908
 909   src_sched = gst_pad_get_scheduler (GST_PAD_CAST (realsrc));
 910   sink_sched = gst_pad_get_scheduler (GST_PAD_CAST (realsink));
 911
 912   if (src_sched && sink_sched) {
 913     if (GST_FLAG_IS_SET (GST_PAD_PARENT (realsrc), GST_ELEMENT_DECOUPLED))
 914       num_decoupled++;
 915     if (GST_FLAG_IS_SET (GST_PAD_PARENT (realsink), GST_ELEMENT_DECOUPLED))
 916       num_decoupled++;
 917
 918     if (src_sched != sink_sched && num_decoupled != 1) {
 919       return FALSE;
 920     }
 921   }
 922   return TRUE;
 923 }
 924
 925 /**
 926  * gst_pad_can_connect_filtered:
 927  * @srcpad: the source #GstPad to connect.
 928  * @sinkpad: the sink #GstPad to connect.
 929  * @filtercaps: the filter #GstCaps.
 930  *
 931  * Checks if the source pad and the sink pad can be connected when constrained
 932  * by the given filter caps.
 933  *
 934  * Returns: TRUE if the pads can be connected, FALSE otherwise.
 935  */
 936 gboolean
 937 gst_pad_can_connect_filtered (GstPad *srcpad, GstPad *sinkpad,
 938                               GstCaps *filtercaps)
 939 {
 940   GstRealPad *realsrc, *realsink;
 941
 942   /* generic checks */
 943   g_return_val_if_fail (srcpad != NULL, FALSE);
 944   g_return_val_if_fail (GST_IS_PAD (srcpad), FALSE);
 945   g_return_val_if_fail (sinkpad != NULL, FALSE);
 946   g_return_val_if_fail (GST_IS_PAD (sinkpad), FALSE);
 947
 948   /* now we need to deal with the real/ghost stuff */
 949   realsrc = GST_PAD_REALIZE (srcpad);
 950   realsink = GST_PAD_REALIZE (sinkpad);
 951
 952   g_return_val_if_fail (GST_RPAD_PEER (realsrc) == NULL, FALSE);
 953   g_return_val_if_fail (GST_RPAD_PEER (realsink) == NULL, FALSE);
 954   g_return_val_if_fail (GST_PAD_PARENT (realsrc) != NULL, FALSE);
 955   g_return_val_if_fail (GST_PAD_PARENT (realsink) != NULL, FALSE);
 956
 957   if (!gst_pad_check_schedulers (realsrc, realsink)) {
 958     g_warning ("connecting pads with different scheds requires "
 959                "exactly one decoupled element (queue)");
 960     return FALSE;
 961   }
 962
 963   /* check if the directions are compatible */
 964   if (!(((GST_RPAD_DIRECTION (realsrc) == GST_PAD_SINK) &&
 965          (GST_RPAD_DIRECTION (realsink) == GST_PAD_SRC)) ||
 966         ((GST_RPAD_DIRECTION (realsrc) == GST_PAD_SRC) &&
 967          (GST_RPAD_DIRECTION (realsink) == GST_PAD_SINK))))
 968     return FALSE;
 969
 970   return TRUE;
 971 }
 972 /**
 973  * gst_pad_can_connect:
 974  * @srcpad: the source #GstPad to connect.
 975  * @sinkpad: the sink #GstPad to connect.
 976  *
 977  * Checks if the source pad and the sink pad can be connected.
 978  *
 979  * Returns: TRUE if the pads can be connected, FALSE otherwise.
 980  */
 981 gboolean
 982 gst_pad_can_connect (GstPad *srcpad, GstPad *sinkpad)
 983 {
 984   return gst_pad_can_connect_filtered (srcpad, sinkpad, NULL);
 985 }
 986
 987 /**
 988  * gst_pad_connect_filtered:
 989  * @srcpad: the source #GstPad to connect.
 990  * @sinkpad: the sink #GstPad to connect.
 991  * @filtercaps: the filter #GstCaps.
 992  *
 993  * Connects the source pad and the sink pad can be connected, constrained
 994  * by the given filter caps.
 995  *
 996  * Returns: TRUE if the pads have been connected, FALSE otherwise.
 997  */
 998 gboolean
 999 gst_pad_connect_filtered (GstPad *srcpad, GstPad *sinkpad, GstCaps *filtercaps)
1000 {
1001   GstRealPad *realsrc, *realsink;
1002   GstScheduler *src_sched, *sink_sched;
1003
1004   /* generic checks */
1005   g_return_val_if_fail (srcpad != NULL, FALSE);
1006   g_return_val_if_fail (GST_IS_PAD (srcpad), FALSE);
1007   g_return_val_if_fail (sinkpad != NULL, FALSE);
1008   g_return_val_if_fail (GST_IS_PAD (sinkpad), FALSE);
1009
1010   GST_INFO (GST_CAT_PADS, "trying to connect %s:%s and %s:%s",
1011             GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
1012
1013   /* now we need to deal with the real/ghost stuff */
1014   realsrc = GST_PAD_REALIZE (srcpad);
1015   realsink = GST_PAD_REALIZE (sinkpad);
1016
1017   if ((GST_PAD (realsrc) != srcpad) || (GST_PAD (realsink) != sinkpad)) {
1018     GST_INFO (GST_CAT_PADS, "*actually* connecting %s:%s and %s:%s",
1019               GST_DEBUG_PAD_NAME (realsrc), GST_DEBUG_PAD_NAME (realsink));
1020   }
1021   if (GST_RPAD_PEER (realsrc) != NULL)
1022   {
1023     GST_INFO (GST_CAT_PADS, "Real source pad %s:%s has a peer, failed",
1024               GST_DEBUG_PAD_NAME (realsrc));
1025     return FALSE;
1026   }
1027   if (GST_RPAD_PEER (realsink) != NULL)
1028   {
1029     GST_INFO (GST_CAT_PADS, "Real sink pad %s:%s has a peer, failed",
1030               GST_DEBUG_PAD_NAME (realsink));
1031     return FALSE;
1032   }
1033   if (GST_PAD_PARENT (realsrc) == NULL)
1034   {
1035     GST_INFO (GST_CAT_PADS, "Real src pad %s:%s has no parent, failed",
1036               GST_DEBUG_PAD_NAME (realsrc));
1037     return FALSE;
1038   }
1039   if (GST_PAD_PARENT (realsink) == NULL)
1040   {
1041     GST_INFO (GST_CAT_PADS, "Real src pad %s:%s has no parent, failed",
1042               GST_DEBUG_PAD_NAME (realsrc));
1043     return FALSE;
1044   }
1045
1046   if (!gst_pad_check_schedulers (realsrc, realsink)) {
1047     g_warning ("connecting pads with different scheds requires "
1048                "exactly one decoupled element (such as queue)");
1049     return FALSE;
1050   }
1051
1052   /* check for reversed directions and swap if necessary */
1053   if ((GST_RPAD_DIRECTION (realsrc) == GST_PAD_SINK) &&
1054       (GST_RPAD_DIRECTION (realsink) == GST_PAD_SRC)) {
1055     GstRealPad *temppad;
1056
1057     temppad = realsrc;
1058     realsrc = realsink;
1059     realsink = temppad;
1060   }
1061   if (GST_PAD_PARENT (realsink) == NULL)
1062   if (GST_RPAD_DIRECTION (realsrc) != GST_PAD_SRC)
1063   {
1064     GST_INFO (GST_CAT_PADS, "Real src pad %s:%s is not a source pad, failed",
1065               GST_DEBUG_PAD_NAME (realsrc));
1066     return FALSE;
1067   }
1068   if (GST_RPAD_DIRECTION (realsink) != GST_PAD_SINK)
1069   {
1070     GST_INFO (GST_CAT_PADS, "Real sink pad %s:%s is not a sink pad, failed",
1071               GST_DEBUG_PAD_NAME (realsink));
1072     return FALSE;
1073   }
1074   /* first set peers */
1075   GST_RPAD_PEER (realsrc) = realsink;
1076   GST_RPAD_PEER (realsink) = realsrc;
1077
1078   /* try to negotiate the pads, we don't need to clear the caps here */
1079   if (!gst_pad_try_reconnect_filtered_func (realsrc, realsink,
1080                                             filtercaps, FALSE)) {
1081     GST_DEBUG (GST_CAT_CAPS, "reconnect_filtered_func failed, can't connect");
1082
1083     GST_RPAD_PEER (realsrc) = NULL;
1084     GST_RPAD_PEER (realsink) = NULL;
1085
1086     return FALSE;
1087   }
1088
1089   /* fire off a signal to each of the pads telling them
1090    * that they've been connected */
1091   g_signal_emit (G_OBJECT (realsrc), gst_real_pad_signals[REAL_CONNECTED],
1092                  0, realsink);
1093   g_signal_emit (G_OBJECT (realsink), gst_real_pad_signals[REAL_CONNECTED],
1094                  0, realsrc);
1095
1096   src_sched = gst_pad_get_scheduler (GST_PAD_CAST (realsrc));
1097   sink_sched = gst_pad_get_scheduler (GST_PAD_CAST (realsink));
1098
1099   /* now tell the scheduler */
1100   if (src_sched && src_sched == sink_sched) {
1101     gst_scheduler_pad_connect (src_sched,
1102                                GST_PAD_CAST (realsrc), GST_PAD_CAST (realsink));
1103   }
1104
1105   GST_INFO (GST_CAT_PADS, "connected %s:%s and %s:%s, successful",
1106             GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
1107   gst_caps_debug (gst_pad_get_caps (GST_PAD_CAST (realsrc)),
1108                   "caps of newly connected src pad");
1109
1110   return TRUE;
1111 }
1112
1113 /**
1114  * gst_pad_connect:
1115  * @srcpad: the source #GstPad to connect.
1116  * @sinkpad: the sink #GstPad to connect.
1117  *
1118  * Connects the source pad to the sink pad.
1119  *
1120  * Returns: TRUE if the pad could be connected, FALSE otherwise.
1121  */
1122 gboolean
1123 gst_pad_connect (GstPad *srcpad, GstPad *sinkpad)
1124 {
1125   return gst_pad_connect_filtered (srcpad, sinkpad, NULL);
1126 }
1127
1128 /**
1129  * gst_pad_set_parent:
1130  * @pad: a #GstPad to set the parent of.
1131  * @parent: the new parent #GstElement.
1132  *
1133  * Sets the parent object of a pad.
1134  */
1135 void
1136 gst_pad_set_parent (GstPad *pad, GstElement *parent)
1137 {
1138   g_return_if_fail (pad != NULL);
1139   g_return_if_fail (GST_IS_PAD (pad));
1140   g_return_if_fail (GST_PAD_PARENT (pad) == NULL);
1141   g_return_if_fail (parent != NULL);
1142   g_return_if_fail (GST_IS_OBJECT (parent));
1143   g_return_if_fail ((gpointer) pad != (gpointer) parent);
1144
1145   gst_object_set_parent (GST_OBJECT (pad), GST_OBJECT (parent));
1146 }
1147
1148 /**
1149  * gst_pad_get_parent:
1150  * @pad: the #GstPad to get the parent of.
1151  *
1152  * Gets the parent object of this pad.
1153  *
1154  * Returns: the parent #GstElement.
1155  */
1156 GstElement*
1157 gst_pad_get_parent (GstPad *pad)
1158 {
1159   g_return_val_if_fail (pad != NULL, NULL);
1160   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1161
1162   return GST_PAD_PARENT (pad);
1163 }
1164
1165 /**
1166  * gst_pad_get_pad_template:
1167  * @pad: a #GstPad to get the pad template of.
1168  *
1169  * Gets the pad template object of this pad.
1170  *
1171  * Returns: the #GstPadTemplate from which this pad was instantiated.
1172  */
1173 GstPadTemplate*
1174 gst_pad_get_pad_template (GstPad *pad)
1175 {
1176   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1177
1178   return GST_PAD_PAD_TEMPLATE (pad);
1179 }
1180
1181
1182 /**
1183  * gst_pad_get_scheduler:
1184  * @pad: a #GstPad to get the scheduler of.
1185  *
1186  * Gets the scheduler of the pad. Since the pad does not
1187  * have a scheduler of its own, the scheduler of the parent
1188  * is taken. For decoupled pads, the scheduler of the peer
1189  * parent is taken.
1190  *
1191  * Returns: the #GstScheduler of the pad.
1192  */
1193 GstScheduler*
1194 gst_pad_get_scheduler (GstPad *pad)
1195 {
1196   GstScheduler *scheduler = NULL;
1197   GstElement *parent;
1198
1199   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1200
1201   parent = gst_pad_get_parent (pad);
1202   if (parent) {
1203     if (GST_FLAG_IS_SET (parent, GST_ELEMENT_DECOUPLED)) {
1204       GstRealPad *peer = GST_RPAD_PEER (pad);
1205
1206       if (peer) {
1207         scheduler = gst_element_get_scheduler (gst_pad_get_parent (GST_PAD_CAST (peer)));
1208       }
1209     }
1210     else {
1211       scheduler = gst_element_get_scheduler (parent);
1212     }
1213   }
1214
1215   return scheduler;
1216 }
1217
1218 /**
1219  * gst_pad_get_real_parent:
1220  * @pad: a #GstPad to get the real parent of.
1221  *
1222  * Gets the real parent object of this pad. If the pad
1223  * is a ghost pad, the actual owner of the real pad is
1224  * returned, as opposed to #gst_pad_get_parent().
1225  *
1226  * Returns: the parent #GstElement.
1227  */
1228 GstElement*
1229 gst_pad_get_real_parent (GstPad *pad)
1230 {
1231   g_return_val_if_fail (pad != NULL, NULL);
1232   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1233
1234   return GST_PAD_PARENT (GST_PAD (GST_PAD_REALIZE (pad)));
1235 }
1236
1237 /**
1238  * gst_pad_add_ghost_pad:
1239  * @pad: a #GstPad to attach the ghost pad to.
1240  * @ghostpad: the ghost #GstPad to to the pad.
1241  *
1242  * Adds a ghost pad to a pad.
1243  */
1244 void
1245 gst_pad_add_ghost_pad (GstPad *pad,
1246                        GstPad *ghostpad)
1247 {
1248   GstRealPad *realpad;
1249
1250   g_return_if_fail (pad != NULL);
1251   g_return_if_fail (GST_IS_PAD (pad));
1252   g_return_if_fail (ghostpad != NULL);
1253   g_return_if_fail (GST_IS_GHOST_PAD (ghostpad));
1254
1255   realpad = GST_PAD_REALIZE (pad);
1256
1257   realpad->ghostpads = g_list_prepend (realpad->ghostpads, ghostpad);
1258 }
1259
1260
1261 /**
1262  * gst_pad_remove_ghost_pad:
1263  * @pad: a #GstPad to remove the ghost pad from.
1264  * @ghostpad: the ghost #GstPad to remove from the pad.
1265  *
1266  * Removes a ghost pad from a pad.
1267  */
1268 void
1269 gst_pad_remove_ghost_pad (GstPad *pad,
1270                           GstPad *ghostpad)
1271 {
1272   GstRealPad *realpad;
1273
1274   g_return_if_fail (pad != NULL);
1275   g_return_if_fail (GST_IS_PAD (pad));
1276   g_return_if_fail (ghostpad != NULL);
1277   g_return_if_fail (GST_IS_GHOST_PAD (ghostpad));
1278
1279   realpad = GST_PAD_REALIZE (pad);
1280
1281   realpad->ghostpads = g_list_remove (realpad->ghostpads, ghostpad);
1282 }
1283
1284 /**
1285  * gst_pad_get_ghost_pad_list:
1286  * @pad: a #GstPad to get the ghost pads of.
1287  *
1288  * Gets the ghost pads of this pad.
1289  *
1290  * Returns: a #GList of ghost pads.
1291  */
1292 GList*
1293 gst_pad_get_ghost_pad_list (GstPad *pad)
1294 {
1295   g_return_val_if_fail (pad != NULL, NULL);
1296   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1297
1298   return GST_PAD_REALIZE(pad)->ghostpads;
1299 }
1300
1301 /* an internal caps negotiation helper function:
1302  *
1303  * 1. optionally calls the pad connect function with the provided caps
1304  * 2. deals with the result code of the connect function
1305  * 3. sets fixed caps on the pad.
1306  */
1307 static GstPadConnectReturn
1308 gst_pad_try_set_caps_func (GstRealPad *pad, GstCaps *caps, gboolean notify)
1309 {
1310   GstCaps *oldcaps, *allowed = NULL;
1311   GstPadTemplate *template;
1312   GstElement *parent = GST_PAD_PARENT (pad);
1313
1314   g_return_val_if_fail (pad != NULL, GST_PAD_CONNECT_REFUSED);
1315   g_return_val_if_fail (GST_IS_PAD (pad), GST_PAD_CONNECT_REFUSED);
1316
1317   /* if this pad has a parent and the parent is not READY, delay the
1318    * negotiation */
1319   if (parent && GST_STATE (parent) < GST_STATE_READY)
1320   {
1321     GST_DEBUG (GST_CAT_CAPS, "parent %s of pad %s:%s is not READY",
1322                GST_ELEMENT_NAME (parent), GST_DEBUG_PAD_NAME (pad));
1323     return GST_PAD_CONNECT_DELAYED;
1324   }
1325
1326   GST_INFO (GST_CAT_CAPS, "trying to set caps %p on pad %s:%s",
1327             caps, GST_DEBUG_PAD_NAME (pad));
1328
1329   /* first see if we have to check against a filter */
1330   if (!(allowed = GST_RPAD_FILTER (pad))) {
1331     /* no filter, make sure we check against the padtemplate then */
1332     if ((template = gst_pad_get_pad_template (GST_PAD_CAST (pad)))) {
1333       allowed = gst_pad_template_get_caps (template);
1334     }
1335   }
1336
1337   /* do we have to check the caps against something? */
1338   if (allowed) {
1339     GstCaps *intersection;
1340
1341     /* check against calculated caps */
1342     intersection = gst_caps_intersect (caps, allowed);
1343
1344     /* oops, empty intersection, caps don"t have anything in common */
1345     if (!intersection) {
1346       GST_INFO (GST_CAT_CAPS, "caps did not intersect with %s:%s's allowed caps",
1347                 GST_DEBUG_PAD_NAME (pad));
1348       gst_caps_debug (caps, "caps themselves (attemped to set)");
1349       gst_caps_debug (allowed,
1350                       "allowed caps that did not agree with caps");
1351       return GST_PAD_CONNECT_REFUSED;
1352     }
1353     /* caps checks out fine, we can unref the intersection now */
1354     gst_caps_unref (intersection);
1355     /* given that the caps are fixed, we know that their intersection with the
1356      * padtemplate caps is the same as caps itself */
1357   }
1358
1359   /* we need to notify the connect function */
1360   if (notify && GST_RPAD_CONNECTFUNC (pad)) {
1361     GstPadConnectReturn res;
1362     gchar *debug_string;
1363
1364     GST_INFO (GST_CAT_CAPS, "calling connect function on pad %s:%s",
1365             GST_DEBUG_PAD_NAME (pad));
1366
1367     /* call the connect function */
1368     res = GST_RPAD_CONNECTFUNC (pad) (GST_PAD (pad), caps);
1369
1370     switch (res) {
1371       case GST_PAD_CONNECT_REFUSED:
1372         debug_string = "REFUSED";
1373         break;
1374       case GST_PAD_CONNECT_OK:
1375         debug_string = "OK";
1376         break;
1377       case GST_PAD_CONNECT_DONE:
1378         debug_string = "DONE";
1379         break;
1380       case GST_PAD_CONNECT_DELAYED:
1381         debug_string = "DELAYED";
1382         break;
1383       default:
1384         g_warning ("unknown return code from connect function of pad %s:%s %d",
1385                    GST_DEBUG_PAD_NAME (pad), res);
1386         return GST_PAD_CONNECT_REFUSED;
1387     }
1388
1389     GST_INFO (GST_CAT_CAPS,
1390               "got reply %s (%d) from connect function on pad %s:%s",
1391               debug_string, res, GST_DEBUG_PAD_NAME (pad));
1392
1393     /* done means the connect function called another caps negotiate function
1394      * on this pad that succeeded, we dont need to continue */
1395     if (res == GST_PAD_CONNECT_DONE) {
1396       GST_INFO (GST_CAT_CAPS, "pad %s:%s is done", GST_DEBUG_PAD_NAME (pad));
1397       return GST_PAD_CONNECT_DONE;
1398     }
1399     if (res == GST_PAD_CONNECT_REFUSED) {
1400       GST_INFO (GST_CAT_CAPS, "pad %s:%s doesn't accept caps",
1401                 GST_DEBUG_PAD_NAME (pad));
1402       return GST_PAD_CONNECT_REFUSED;
1403     }
1404   }
1405   /* we can only set caps on the pad if they are fixed */
1406   if (GST_CAPS_IS_FIXED (caps)) {
1407
1408     GST_INFO (GST_CAT_CAPS, "setting caps on pad %s:%s",
1409               GST_DEBUG_PAD_NAME (pad));
1410     /* if we got this far all is ok, remove the old caps, set the new one */
1411     oldcaps = GST_PAD_CAPS (pad);
1412     if (caps) gst_caps_ref (caps);
1413     GST_PAD_CAPS (pad) = caps;
1414     if (oldcaps) gst_caps_unref (oldcaps);
1415
1416     g_object_notify (G_OBJECT (pad), "caps");
1417   }
1418   else {
1419     GST_INFO (GST_CAT_CAPS,
1420               "caps are not fixed on pad %s:%s, not setting them yet",
1421               GST_DEBUG_PAD_NAME (pad));
1422   }
1423   return GST_PAD_CONNECT_OK;
1424 }
1425
1426 /**
1427  * gst_pad_try_set_caps:
1428  * @pad: a #GstPad to try to set the caps on.
1429  * @caps: the #GstCaps to set.
1430  *
1431  * Tries to set the caps on the given pad.
1432  *
1433  * Returns: A GstPadConnectReturn value indicating whether the caps
1434  *              could be set.
1435  */
1436 GstPadConnectReturn
1437 gst_pad_try_set_caps (GstPad *pad, GstCaps *caps)
1438 {
1439   GstRealPad *peer, *realpad;
1440   GstPadConnectReturn set_retval;
1441
1442   realpad = GST_PAD_REALIZE (pad);
1443   peer = GST_RPAD_PEER (realpad);
1444
1445   GST_INFO (GST_CAT_CAPS, "trying to set caps %p on pad %s:%s",
1446             caps, GST_DEBUG_PAD_NAME (realpad));
1447
1448   gst_caps_debug (caps, "caps that we are trying to set");
1449
1450   /* setting non fixed caps on a pad is not allowed */
1451   if (!GST_CAPS_IS_FIXED (caps)) {
1452   GST_INFO (GST_CAT_CAPS,
1453             "trying to set unfixed caps on pad %s:%s, not allowed",
1454             GST_DEBUG_PAD_NAME (realpad));
1455     g_warning ("trying to set non fixed caps on pad %s:%s, not allowed",
1456                GST_DEBUG_PAD_NAME (realpad));
1457     gst_caps_debug (caps, "unfixed caps");
1458     return GST_PAD_CONNECT_DELAYED;
1459   }
1460
1461   /* if we have a peer try to set the caps, notifying the peerpad
1462    * if it has a connect function */
1463   if (peer && ((set_retval = gst_pad_try_set_caps_func (peer, caps, TRUE)) <= 0))
1464   {
1465     GST_INFO (GST_CAT_CAPS, "tried to set caps on peerpad %s:%s but couldn't, return value %d",
1466               GST_DEBUG_PAD_NAME (peer), set_retval);
1467     return set_retval;
1468   }
1469
1470   /* then try to set our own caps, we don't need to be notified */
1471   if ((set_retval = gst_pad_try_set_caps_func (realpad, caps, FALSE)) <= 0)
1472   {
1473     GST_INFO (GST_CAT_CAPS, "tried to set own caps on pad %s:%s but couldn't, return value %d",
1474               GST_DEBUG_PAD_NAME (realpad), set_retval);
1475     return set_retval;
1476   }
1477   GST_INFO (GST_CAT_CAPS, "succeeded setting caps %p on pad %s:%s, return value %d",
1478             caps, GST_DEBUG_PAD_NAME (realpad), set_retval);
1479   g_assert (GST_PAD_CAPS (pad));
1480
1481   return set_retval;
1482 }
1483
1484 /* this is a caps negotiation convenience routine, it:
1485  *
1486  * 1. optionally clears any pad caps.
1487  * 2. calculates the intersection between the two pad tamplate/getcaps caps.
1488  * 3. calculates the intersection with the (optional) filtercaps.
1489  * 4. stores the intersection in the pad filter.
1490  * 5. stores the app filtercaps in the pad appfilter.
1491  * 6. starts the caps negotiation.
1492  */
1493 static gboolean
1494 gst_pad_try_reconnect_filtered_func (GstRealPad *srcpad, GstRealPad *sinkpad,
1495                                      GstCaps *filtercaps, gboolean clear)
1496 {
1497   GstCaps *srccaps, *sinkcaps;
1498   GstCaps *intersection = NULL;
1499   GstRealPad *realsrc, *realsink;
1500
1501   realsrc = GST_PAD_REALIZE (srcpad);
1502   realsink = GST_PAD_REALIZE (sinkpad);
1503
1504   g_return_val_if_fail (GST_RPAD_PEER (realsrc) != NULL, FALSE);
1505   g_return_val_if_fail (GST_RPAD_PEER (realsink) == realsrc, FALSE);
1506
1507   /* optinally clear the caps */
1508   if (clear) {
1509     GST_INFO (GST_CAT_PADS,
1510               "start reconnect filtered %s:%s and %s:%s, clearing caps",
1511               GST_DEBUG_PAD_NAME (realsrc), GST_DEBUG_PAD_NAME (realsink));
1512
1513     GST_PAD_CAPS (GST_PAD (realsrc)) = NULL;
1514     GST_PAD_CAPS (GST_PAD (realsink)) = NULL;
1515   }
1516   else {
1517     GST_INFO (GST_CAT_PADS, "start reconnect filtered %s:%s and %s:%s",
1518         GST_DEBUG_PAD_NAME (realsrc), GST_DEBUG_PAD_NAME (realsink));
1519   }
1520
1521   srccaps = gst_pad_get_caps (GST_PAD (realsrc));
1522   GST_DEBUG (GST_CAT_PADS, "dumping caps of pad %s:%s",
1523              GST_DEBUG_PAD_NAME (realsrc));
1524   gst_caps_debug (srccaps, "caps of src pad (pre-reconnect)");
1525   sinkcaps = gst_pad_get_caps (GST_PAD (realsink));
1526   GST_DEBUG (GST_CAT_PADS, "dumping caps of pad %s:%s",
1527              GST_DEBUG_PAD_NAME (realsink));
1528   gst_caps_debug (sinkcaps, "caps of sink pad (pre-reconnect)");
1529
1530   /* first take the intersection of the pad caps */
1531   intersection = gst_caps_intersect (srccaps, sinkcaps);
1532   gst_caps_debug (intersection, "caps of intersection");
1533
1534   /* if we have no intersection but one of the caps was not NULL.. */
1535   if (!intersection && (srccaps || sinkcaps)) {
1536     /* the intersection is NULL but the pad caps were not both NULL,
1537      * this means they have no common format */
1538     GST_INFO (GST_CAT_PADS, "pads %s:%s and %s:%s have no common type",
1539               GST_DEBUG_PAD_NAME (realsrc), GST_DEBUG_PAD_NAME (realsink));
1540     return FALSE;
1541   } else if (intersection) {
1542     GST_INFO (GST_CAT_PADS, "pads %s:%s and %s:%s intersected to %s caps",
1543          GST_DEBUG_PAD_NAME (realsrc), GST_DEBUG_PAD_NAME (realsink),
1544          ((intersection && GST_CAPS_IS_FIXED (intersection)) ? "fixed" : "variable"));
1545
1546     /* then filter this against the app filter */
1547     if (filtercaps) {
1548       GstCaps *filtered_intersection = gst_caps_intersect (intersection,
1549                                                            filtercaps);
1550
1551       /* get rid of the old intersection here */
1552       gst_caps_unref (intersection);
1553
1554       if (!filtered_intersection) {
1555         GST_INFO (GST_CAT_PADS,
1556                   "filtered connection between pads %s:%s and %s:%s is empty",
1557                   GST_DEBUG_PAD_NAME (realsrc), GST_DEBUG_PAD_NAME (realsink));
1558         return FALSE;
1559       }
1560       intersection = filtered_intersection;
1561
1562       /* keep a reference to the app caps */
1563       GST_RPAD_APPFILTER (realsink) = filtercaps;
1564       GST_RPAD_APPFILTER (realsrc) = filtercaps;
1565     }
1566   }
1567   GST_DEBUG (GST_CAT_CAPS, "setting filter for connection to:");
1568   gst_caps_debug (intersection, "filter for connection");
1569
1570   /* both the app filter and the filter, while stored on both peer pads,
1571    * are equal to the same thing on both */
1572   GST_RPAD_FILTER (realsrc) = intersection;
1573   GST_RPAD_FILTER (realsink) = intersection;
1574
1575   return gst_pad_perform_negotiate (GST_PAD (realsrc), GST_PAD (realsink));
1576 }
1577
1578 /**
1579  * gst_pad_perform_negotiate:
1580  * @srcpad: the source #GstPad.
1581  * @sinkpad: the sink #GstPad.
1582  *
1583  * Tries to negotiate the pads.
1584  *
1585  * Returns: TRUE if the pads were succesfully negotiated, FALSE otherwise.
1586  */
1587 gboolean
1588 gst_pad_perform_negotiate (GstPad *srcpad, GstPad *sinkpad)
1589 {
1590   GstCaps *intersection, *filtered_intersection;
1591   GstRealPad *realsrc, *realsink;
1592   GstCaps *srccaps, *sinkcaps, *filter;
1593
1594   g_return_val_if_fail (srcpad != NULL, FALSE);
1595   g_return_val_if_fail (sinkpad != NULL, FALSE);
1596
1597   realsrc = GST_PAD_REALIZE (srcpad);
1598   realsink = GST_PAD_REALIZE (sinkpad);
1599
1600   g_return_val_if_fail (GST_RPAD_PEER (realsrc) != NULL, FALSE);
1601   g_return_val_if_fail (GST_RPAD_PEER (realsink) == realsrc, FALSE);
1602
1603   filter = GST_RPAD_APPFILTER (realsrc);
1604   if (filter) {
1605     GST_INFO (GST_CAT_PADS, "dumping filter for connection %s:%s-%s:%s",
1606               GST_DEBUG_PAD_NAME (realsrc), GST_DEBUG_PAD_NAME (realsink));
1607     gst_caps_debug (filter, "connection filter caps");
1608   }
1609
1610   /* calculate the new caps here */
1611   srccaps = gst_pad_get_caps (GST_PAD (realsrc));
1612   GST_DEBUG (GST_CAT_PADS, "dumping caps of pad %s:%s",
1613              GST_DEBUG_PAD_NAME (realsrc));
1614   gst_caps_debug (srccaps,
1615                   "src caps, awaiting negotiation, after applying filter");
1616   sinkcaps = gst_pad_get_caps (GST_PAD (realsink));
1617   GST_DEBUG (GST_CAT_PADS, "dumping caps of pad %s:%s",
1618              GST_DEBUG_PAD_NAME (realsink));
1619   gst_caps_debug (sinkcaps,
1620                   "sink caps, awaiting negotiation, after applying filter");
1621   intersection = gst_caps_intersect (srccaps, sinkcaps);
1622   filtered_intersection = gst_caps_intersect (intersection, filter);
1623   if (filtered_intersection) {
1624     gst_caps_unref (intersection);
1625     intersection = filtered_intersection;
1626   }
1627
1628   /* no negotiation is performed if the pads have filtercaps */
1629   if (intersection) {
1630     GstPadConnectReturn res;
1631
1632     res = gst_pad_try_set_caps_func (realsrc, intersection, TRUE);
1633     if (res == GST_PAD_CONNECT_REFUSED)
1634       return FALSE;
1635     if (res == GST_PAD_CONNECT_DONE)
1636       return TRUE;
1637
1638     res = gst_pad_try_set_caps_func (realsink, intersection, TRUE);
1639     if (res == GST_PAD_CONNECT_REFUSED)
1640       return FALSE;
1641     if (res == GST_PAD_CONNECT_DONE)
1642       return TRUE;
1643   }
1644   return TRUE;
1645 }
1646
1647 /**
1648  * gst_pad_try_reconnect_filtered:
1649  * @srcpad: the source #GstPad to reconnect.
1650  * @sinkpad: the sink #GstPad to reconnect.
1651  * @filtercaps: the #GstPad to use as a filter in the reconnection.
1652  *
1653  * Tries to reconnect the given source and sink pad, constrained by the given
1654  * capabilities.
1655  *
1656  * Returns: TRUE if the pads were succesfully renegotiated, FALSE otherwise.
1657  */
1658 gboolean
1659 gst_pad_try_reconnect_filtered (GstPad *srcpad, GstPad *sinkpad,
1660                                 GstCaps *filtercaps)
1661 {
1662   GstRealPad *realsrc, *realsink;
1663
1664   g_return_val_if_fail (srcpad != NULL, FALSE);
1665   g_return_val_if_fail (sinkpad != NULL, FALSE);
1666
1667   realsrc = GST_PAD_REALIZE (srcpad);
1668   realsink = GST_PAD_REALIZE (sinkpad);
1669
1670   g_return_val_if_fail (GST_RPAD_PEER (realsrc) != NULL, FALSE);
1671   g_return_val_if_fail (GST_RPAD_PEER (realsink) == realsrc, FALSE);
1672
1673   return gst_pad_try_reconnect_filtered_func (realsrc, realsink,
1674                                               filtercaps, TRUE);
1675 }
1676
1677 /**
1678  * gst_pad_reconnect_filtered:
1679  * @srcpad: the source #GstPad to reconnect.
1680  * @sinkpad: the sink #GstPad to reconnect.
1681  * @filtercaps: the #GstPad to use as a filter in the reconnection.
1682  *
1683  * Reconnects the given source and sink pad, constrained by the given
1684  * capabilities.  If the reconnection fails, the pads are disconnected
1685  * and FALSE is returned.
1686  *
1687  * Returns: TRUE if the pads were succesfully reconnected, FALSE otherwise.
1688  */
1689 gboolean
1690 gst_pad_reconnect_filtered (GstPad *srcpad, GstPad *sinkpad,
1691                             GstCaps *filtercaps)
1692 {
1693   GstRealPad *realsrc, *realsink;
1694
1695   g_return_val_if_fail (srcpad != NULL, FALSE);
1696   g_return_val_if_fail (sinkpad != NULL, FALSE);
1697
1698   realsrc = GST_PAD_REALIZE (srcpad);
1699   realsink = GST_PAD_REALIZE (sinkpad);
1700
1701   g_return_val_if_fail (GST_RPAD_PEER (realsrc) != NULL, FALSE);
1702   g_return_val_if_fail (GST_RPAD_PEER (realsink) == realsrc, FALSE);
1703
1704   if (! gst_pad_try_reconnect_filtered_func (realsrc, realsink,
1705                                              filtercaps, TRUE)) {
1706     gst_pad_disconnect (srcpad, GST_PAD (GST_PAD_PEER (srcpad)));
1707     return FALSE;
1708   }
1709   return TRUE;
1710 }
1711
1712 /**
1713  * gst_pad_proxy_connect:
1714  * @pad: a #GstPad to proxy to.
1715  * @caps: the #GstCaps to use in proxying.
1716  *
1717  * Proxies the connect function to the specified pad.
1718  *
1719  * Returns: TRUE if the peer pad accepted the caps, FALSE otherwise.
1720  */
1721 GstPadConnectReturn
1722 gst_pad_proxy_connect (GstPad *pad, GstCaps *caps)
1723 {
1724   GstRealPad *peer, *realpad;
1725
1726   realpad = GST_PAD_REALIZE (pad);
1727
1728   peer = GST_RPAD_PEER (realpad);
1729
1730   GST_INFO (GST_CAT_CAPS, "proxy connect to pad %s:%s",
1731             GST_DEBUG_PAD_NAME (realpad));
1732
1733   if (peer && gst_pad_try_set_caps_func (peer, caps, TRUE) < 0)
1734     return GST_PAD_CONNECT_REFUSED;
1735   if (gst_pad_try_set_caps_func (realpad, caps, FALSE) < 0)
1736     return GST_PAD_CONNECT_REFUSED;
1737
1738   return GST_PAD_CONNECT_OK;
1739 }
1740
1741 /**
1742  * gst_pad_get_caps:
1743  * @pad: a  #GstPad to get the capabilities of.
1744  *
1745  * Gets the capabilities of this pad.
1746  *
1747  * Returns: the #GstCaps of this pad.
1748  */
1749 GstCaps*
1750 gst_pad_get_caps (GstPad *pad)
1751 {
1752   GstRealPad *realpad;
1753
1754   g_return_val_if_fail (pad != NULL, NULL);
1755   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1756
1757   realpad = GST_PAD_REALIZE (pad);
1758
1759   GST_DEBUG (GST_CAT_CAPS, "get pad caps of %s:%s (%p)",
1760             GST_DEBUG_PAD_NAME (realpad), realpad);
1761
1762   if (GST_PAD_CAPS (realpad)) {
1763     GST_DEBUG (GST_CAT_CAPS, "using pad real caps %p", GST_PAD_CAPS (realpad));
1764     return GST_PAD_CAPS (realpad);
1765   }
1766   else if GST_RPAD_GETCAPSFUNC (realpad) {
1767     GST_DEBUG (GST_CAT_CAPS, "using pad get function");
1768     return GST_RPAD_GETCAPSFUNC (realpad) (GST_PAD_CAST (realpad), NULL);
1769   }
1770   else if (GST_PAD_PAD_TEMPLATE (realpad)) {
1771     GstPadTemplate *templ = GST_PAD_PAD_TEMPLATE (realpad);
1772     GST_DEBUG (GST_CAT_CAPS, "using pad template %p with caps %p",
1773                templ, GST_PAD_TEMPLATE_CAPS (templ));
1774     return GST_PAD_TEMPLATE_CAPS (templ);
1775   }
1776   GST_DEBUG (GST_CAT_CAPS, "pad has no caps");
1777
1778   return NULL;
1779 }
1780
1781 /**
1782  * gst_pad_get_pad_template_caps:
1783  * @pad: a #GstPad to get the template capabilities from.
1784  *
1785  * Gets the template capabilities of this pad.
1786  *
1787  * Returns: the template #GstCaps of this pad.
1788  */
1789 GstCaps*
1790 gst_pad_get_pad_template_caps (GstPad *pad)
1791 {
1792   g_return_val_if_fail (pad != NULL, NULL);
1793   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1794
1795   if (GST_PAD_PAD_TEMPLATE (pad))
1796     return GST_PAD_TEMPLATE_CAPS (GST_PAD_PAD_TEMPLATE (pad));
1797
1798   return NULL;
1799 }
1800
1801 /**
1802  * gst_pad_template_get_caps_by_name:
1803  * @templ: a #GstPadTemplate to get the capabilities of.
1804  * @name: the name of the capability to get.
1805  *
1806  * Gets the capability with the given name from this pad template.
1807  *
1808  * Returns: the #GstCaps, or NULL if not found or in case of an error.
1809  */
1810 GstCaps*
1811 gst_pad_template_get_caps_by_name (GstPadTemplate *templ, const gchar *name)
1812 {
1813   GstCaps *caps;
1814
1815   g_return_val_if_fail (templ != NULL, NULL);
1816
1817   caps = GST_PAD_TEMPLATE_CAPS (templ);
1818   if (!caps)
1819     return NULL;
1820
1821   return gst_caps_get_by_name (caps, name);
1822 }
1823
1824 /**
1825  * gst_pad_check_compatibility:
1826  * @srcpad: the source #GstPad to check.
1827  * @sinkpad: the sink #GstPad to check against.
1828  *
1829  * Checks if two pads have compatible capabilities.
1830  *
1831  * Returns: TRUE if they are compatible or if the capabilities
1832  * could not be checked
1833  */
1834 gboolean
1835 gst_pad_check_compatibility (GstPad *srcpad, GstPad *sinkpad)
1836 {
1837   g_return_val_if_fail (srcpad != NULL, FALSE);
1838   g_return_val_if_fail (GST_IS_PAD (srcpad), FALSE);
1839   g_return_val_if_fail (sinkpad != NULL, FALSE);
1840   g_return_val_if_fail (GST_IS_PAD (sinkpad), FALSE);
1841
1842   if (GST_PAD_CAPS (srcpad) && GST_PAD_CAPS (sinkpad)) {
1843     if (!gst_caps_is_always_compatible (GST_PAD_CAPS (srcpad),
1844                                         GST_PAD_CAPS (sinkpad))) {
1845       return FALSE;
1846     }
1847     else {
1848       return TRUE;
1849     }
1850   }
1851   else {
1852     GST_DEBUG (GST_CAT_PADS,
1853                "could not check capabilities of pads (%s:%s) and (%s:%s) %p %p",
1854                GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad),
1855                GST_PAD_CAPS (srcpad), GST_PAD_CAPS (sinkpad));
1856     return TRUE;
1857   }
1858 }
1859
1860 /**
1861  * gst_pad_get_peer:
1862  * @pad: a #GstPad to get the peer of.
1863  *
1864  * Gets the peer pad of this pad.
1865  *
1866  * Returns: the peer #GstPad.
1867  */
1868 GstPad*
1869 gst_pad_get_peer (GstPad *pad)
1870 {
1871   g_return_val_if_fail (pad != NULL, NULL);
1872   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1873
1874   return GST_PAD (GST_PAD_PEER (pad));
1875 }
1876
1877 /**
1878  * gst_pad_get_allowed_caps:
1879  * @pad: a #GstPad to get the allowed caps of.
1880  *
1881  * Gets the capabilities of the allowed media types that can
1882  * flow through this pad.  The caller must free the resulting caps.
1883  *
1884  * Returns: a newly allocated copy of the allowed #GstCaps.
1885  */
1886 GstCaps*
1887 gst_pad_get_allowed_caps (GstPad *pad)
1888 {
1889   g_return_val_if_fail (pad != NULL, NULL);
1890   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1891
1892   GST_DEBUG (GST_CAT_PROPERTIES, "get allowed caps of %s:%s",
1893              GST_DEBUG_PAD_NAME (pad));
1894
1895   return gst_caps_copy (GST_RPAD_FILTER (pad));
1896 }
1897
1898 /**
1899  * gst_pad_recalc_allowed_caps:
1900  * @pad: a #GstPad to recalculate the capablities of.
1901  *
1902  * Attempts to reconnect the pad to its peer through its filter,
1903  * set with gst_pad_[re]connect_filtered. This function is useful when a
1904  * plug-in has new capabilities on a pad and wants to notify the peer.
1905  *
1906  * Returns: TRUE on success, FALSE otherwise.
1907  */
1908 gboolean
1909 gst_pad_recalc_allowed_caps (GstPad *pad)
1910 {
1911   GstRealPad *peer;
1912
1913   g_return_val_if_fail (pad != NULL, FALSE);
1914   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
1915
1916   GST_DEBUG (GST_CAT_PROPERTIES, "set allowed caps of %s:%s",
1917              GST_DEBUG_PAD_NAME (pad));
1918
1919   peer = GST_RPAD_PEER (pad);
1920   if (peer)
1921     return gst_pad_try_reconnect_filtered (pad, GST_PAD (peer),
1922                                            GST_RPAD_APPFILTER (pad));
1923
1924   return TRUE;
1925 }
1926
1927 /**
1928  * gst_pad_get_bufferpool:
1929  * @pad: a #GstPad to get the bufferpool from.
1930  *
1931  * Gets the bufferpool of the peer pad of the given pad.Note that
1932  * a bufferpool can only be obtained from a srcpad.
1933  *
1934  * Returns: the #GstBufferPool, or NULL in case of an error.
1935  */
1936 GstBufferPool*
1937 gst_pad_get_bufferpool (GstPad *pad)
1938 {
1939   GstRealPad *peer;
1940
1941   g_return_val_if_fail (pad != NULL, NULL);
1942   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1943   g_return_val_if_fail (GST_PAD_IS_SRC (pad), NULL);
1944
1945   peer = GST_RPAD_PEER (pad);
1946
1947   if (!peer)
1948     return NULL;
1949
1950   GST_DEBUG_ENTER ("(%s:%s)", GST_DEBUG_PAD_NAME (pad));
1951
1952   if (peer->bufferpoolfunc) {
1953     GST_DEBUG (GST_CAT_PADS,
1954                "calling bufferpoolfunc &%s (@%p) of peer pad %s:%s",
1955                GST_DEBUG_FUNCPTR_NAME (peer->bufferpoolfunc),
1956                &peer->bufferpoolfunc, GST_DEBUG_PAD_NAME (((GstPad*) peer)));
1957     return (peer->bufferpoolfunc) (((GstPad*) peer));
1958   } else {
1959     GST_DEBUG (GST_CAT_PADS, "no bufferpoolfunc for peer pad %s:%s at %p",
1960                GST_DEBUG_PAD_NAME (((GstPad*) peer)), &peer->bufferpoolfunc);
1961     return NULL;
1962   }
1963 }
1964
1965 static void
1966 gst_real_pad_dispose (GObject *object)
1967 {
1968   GstPad *pad = GST_PAD (object);
1969
1970   /* No connected pad can ever be disposed.
1971    * It has to have a parent to be connected
1972    * and a parent would hold a reference */
1973   g_assert (GST_PAD_PEER (pad) == NULL);
1974
1975   GST_DEBUG (GST_CAT_REFCOUNTING, "dispose %s:%s", GST_DEBUG_PAD_NAME(pad));
1976
1977   if (GST_PAD_PAD_TEMPLATE (pad)){
1978     GST_DEBUG (GST_CAT_REFCOUNTING, "unreffing padtemplate'%s'",
1979                GST_OBJECT_NAME (GST_PAD_PAD_TEMPLATE (pad)));
1980     gst_object_unref (GST_OBJECT (GST_PAD_PAD_TEMPLATE (pad)));
1981     GST_PAD_PAD_TEMPLATE (pad) = NULL;
1982   }
1983
1984   /* we destroy the ghostpads, because they are nothing without the real pad */
1985   if (GST_REAL_PAD (pad)->ghostpads) {
1986     GList *orig, *ghostpads;
1987
1988     orig = ghostpads = g_list_copy (GST_REAL_PAD (pad)->ghostpads);
1989
1990     while (ghostpads) {
1991       GstPad *ghostpad = GST_PAD (ghostpads->data);
1992
1993       if (GST_IS_ELEMENT (GST_OBJECT_PARENT (ghostpad))){
1994         GST_DEBUG (GST_CAT_REFCOUNTING, "removing ghost pad from element '%s'",
1995                    GST_OBJECT_NAME (GST_OBJECT_PARENT (ghostpad)));
1996
1997         gst_element_remove_ghost_pad (GST_ELEMENT (GST_OBJECT_PARENT (ghostpad)), GST_PAD (ghostpad));
1998       }
1999       ghostpads = g_list_next (ghostpads);
2000     }
2001     g_list_free (orig);
2002     g_list_free (GST_REAL_PAD(pad)->ghostpads);
2003   }
2004
2005   if (GST_IS_ELEMENT (GST_OBJECT_PARENT (pad))) {
2006     GST_DEBUG (GST_CAT_REFCOUNTING, "removing pad from element '%s'",
2007                GST_OBJECT_NAME (GST_OBJECT (GST_ELEMENT (GST_OBJECT_PARENT (pad)))));
2008
2009     gst_element_remove_pad (GST_ELEMENT (GST_OBJECT_PARENT (pad)), pad);
2010   }
2011
2012   G_OBJECT_CLASS (real_pad_parent_class)->dispose (object);
2013 }
2014
2015
2016 #ifndef GST_DISABLE_LOADSAVE
2017 /* FIXME: why isn't this on a GstElement ? */
2018 /**
2019  * gst_pad_load_and_connect:
2020  * @self: an #xmlNodePtr to read the description from.
2021  * @parent: the #GstObject element that owns the pad.
2022  *
2023  * Reads the pad definition from the XML node and connects the given pad
2024  * in the element to a pad of an element up in the hierarchy.
2025  */
2026 void
2027 gst_pad_load_and_connect (xmlNodePtr self, GstObject *parent)
2028 {
2029   xmlNodePtr field = self->xmlChildrenNode;
2030   GstPad *pad = NULL, *targetpad;
2031   gchar *peer = NULL;
2032   gchar **split;
2033   GstElement *target;
2034   GstObject *grandparent;
2035
2036   while (field) {
2037     if (!strcmp (field->name, "name")) {
2038       pad = gst_element_get_pad (GST_ELEMENT (parent),
2039                                  xmlNodeGetContent (field));
2040     }
2041     else if (!strcmp(field->name, "peer")) {
2042       peer = xmlNodeGetContent (field);
2043     }
2044     field = field->next;
2045   }
2046   g_return_if_fail (pad != NULL);
2047
2048   if (peer == NULL) return;
2049
2050   split = g_strsplit (peer, ".", 2);
2051
2052   if (split[0] == NULL || split[1] == NULL) {
2053     GST_DEBUG (GST_CAT_XML,
2054                "Could not parse peer '%s' for pad %s:%s, leaving unconnected",
2055                peer, GST_DEBUG_PAD_NAME (pad));
2056     return;
2057   }
2058
2059   g_return_if_fail (split[0] != NULL);
2060   g_return_if_fail (split[1] != NULL);
2061
2062   grandparent = gst_object_get_parent (parent);
2063
2064   if (grandparent && GST_IS_BIN (grandparent)) {
2065     target = gst_bin_get_by_name_recurse_up (GST_BIN (grandparent), split[0]);
2066   }
2067   else
2068     goto cleanup;
2069
2070   if (target == NULL) goto cleanup;
2071
2072   targetpad = gst_element_get_pad (target, split[1]);
2073
2074   if (targetpad == NULL) goto cleanup;
2075
2076   gst_pad_connect (pad, targetpad);
2077
2078 cleanup:
2079   g_strfreev (split);
2080 }
2081
2082 /**
2083  * gst_pad_save_thyself:
2084  * @pad: a #GstPad to save.
2085  * @parent: the parent #xmlNodePtr to save the description in.
2086  *
2087  * Saves the pad into an xml representation.
2088  *
2089  * Returns: the #xmlNodePtr representation of the pad.
2090  */
2091 static xmlNodePtr
2092 gst_pad_save_thyself (GstObject *object, xmlNodePtr parent)
2093 {
2094   GstRealPad *realpad;
2095   GstPad *peer;
2096
2097   g_return_val_if_fail (GST_IS_REAL_PAD (object), NULL);
2098
2099   realpad = GST_REAL_PAD (object);
2100
2101   xmlNewChild (parent, NULL, "name", GST_PAD_NAME (realpad));
2102   if (GST_RPAD_PEER (realpad) != NULL) {
2103     gchar *content;
2104
2105     peer = GST_PAD (GST_RPAD_PEER (realpad));
2106     /* first check to see if the peer's parent's parent is the same */
2107     /* we just save it off */
2108     content = g_strdup_printf ("%s.%s",
2109                                GST_OBJECT_NAME (GST_PAD_PARENT (peer)),
2110                                GST_PAD_NAME (peer));
2111     xmlNewChild (parent, NULL, "peer", content);
2112     g_free (content);
2113   } else
2114     xmlNewChild (parent, NULL, "peer", "");
2115
2116   return parent;
2117 }
2118
2119 /* FIXME: shouldn't pad and ghost be switched ?
2120  */
2121 /**
2122  * gst_ghost_pad_save_thyself:
2123  * @pad: a ghost #GstPad to save.
2124  * @parent: the parent #xmlNodePtr to save the description in.
2125  *
2126  * Saves the ghost pad into an xml representation.
2127  *
2128  * Returns: the #xmlNodePtr representation of the pad.
2129  */
2130 xmlNodePtr
2131 gst_ghost_pad_save_thyself (GstPad *pad, xmlNodePtr parent)
2132 {
2133   xmlNodePtr self;
2134
2135   g_return_val_if_fail (GST_IS_GHOST_PAD (pad), NULL);
2136
2137   self = xmlNewChild (parent, NULL, "ghostpad", NULL);
2138   xmlNewChild (self, NULL, "name", GST_PAD_NAME (pad));
2139   xmlNewChild (self, NULL, "parent", GST_OBJECT_NAME (GST_PAD_PARENT (pad)));
2140
2141   /* FIXME FIXME FIXME! */
2142
2143   return self;
2144 }
2145 #endif /* GST_DISABLE_LOADSAVE */
2146
2147 /**
2148  * gst_pad_push:
2149  * @pad: a #GstPad to push the buffer out of.
2150  * @buf: the #GstBuffer to push.
2151  *
2152  * Pushes a buffer to the peer of the pad.
2153  */
2154 void
2155 gst_pad_push (GstPad *pad, GstBuffer *buf)
2156 {
2157   GstRealPad *peer = GST_RPAD_PEER (pad);
2158
2159   GST_DEBUG_ENTER ("(%s:%s)", GST_DEBUG_PAD_NAME (pad));
2160
2161   g_return_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SRC);
2162
2163   if (!gst_probe_dispatcher_dispatch (&(GST_REAL_PAD (pad)->probedisp), GST_DATA (buf)))
2164     return;
2165
2166   if (!peer) {
2167     g_warning ("push on pad %s:%s but it is unconnected",
2168                GST_DEBUG_PAD_NAME (pad));
2169   }
2170   else {
2171     if (peer->chainhandler) {
2172       if (buf) {
2173         GST_DEBUG (GST_CAT_DATAFLOW,
2174                    "calling chainhandler &%s of peer pad %s:%s",
2175                    GST_DEBUG_FUNCPTR_NAME (peer->chainhandler),
2176                    GST_DEBUG_PAD_NAME (GST_PAD (peer)));
2177         if (!gst_probe_dispatcher_dispatch (&peer->probedisp, GST_DATA (buf)))
2178           return;
2179
2180         (peer->chainhandler) (GST_PAD_CAST (peer), buf);
2181         return;
2182       }
2183       else {
2184         g_warning ("trying to push a NULL buffer on pad %s:%s",
2185                    GST_DEBUG_PAD_NAME (peer));
2186         return;
2187       }
2188     }
2189     else {
2190       g_warning ("internal error: push on pad %s:%s but it has no chainhandler",
2191                  GST_DEBUG_PAD_NAME (peer));
2192     }
2193   }
2194   /* clean up the mess here */
2195   if (buf != NULL) gst_data_unref (GST_DATA (buf));
2196 }
2197
2198 /**
2199  * gst_pad_pull:
2200  * @pad: a #GstPad to pull a buffer from.
2201  *
2202  * Pulls a buffer from the peer pad.
2203  *
2204  * Returns: a new #GstBuffer from the peer pad.
2205  */
2206 GstBuffer*
2207 gst_pad_pull (GstPad *pad)
2208 {
2209   GstRealPad *peer;
2210
2211   peer = GST_RPAD_PEER (pad);
2212
2213   GST_DEBUG_ENTER("(%s:%s)",GST_DEBUG_PAD_NAME(pad));
2214
2215   g_return_val_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SINK, NULL);
2216
2217   if (!peer) {
2218     gst_element_error (GST_PAD_PARENT (pad),
2219                        "pull on pad %s:%s but it was unconnected",
2220                        GST_ELEMENT_NAME (GST_PAD_PARENT (pad)),
2221                        GST_PAD_NAME (pad), NULL);
2222   }
2223   else {
2224     if (peer->gethandler) {
2225       GstBuffer *buf;
2226
2227       GST_DEBUG (GST_CAT_DATAFLOW, "calling gethandler %s of peer pad %s:%s",
2228                  GST_DEBUG_FUNCPTR_NAME (peer->gethandler),
2229                  GST_DEBUG_PAD_NAME (peer));
2230
2231       buf = (peer->gethandler) (GST_PAD_CAST (peer));
2232
2233       if (buf) {
2234         if (!gst_probe_dispatcher_dispatch (&peer->probedisp, GST_DATA (buf)))
2235           return NULL;
2236
2237         return buf;
2238       }
2239
2240       /* no null buffers allowed */
2241       gst_element_error (GST_PAD_PARENT (pad),
2242                          "NULL buffer during pull on %s:%s",
2243                          GST_DEBUG_PAD_NAME (pad), NULL);
2244
2245     } else {
2246       gst_element_error (GST_PAD_PARENT (pad),
2247                          "internal error: pull on pad %s:%s "
2248                          "but the peer pad %s:%s has no gethandler",
2249                          GST_DEBUG_PAD_NAME (pad), GST_DEBUG_PAD_NAME (peer),
2250                          NULL);
2251     }
2252   }
2253   return NULL;
2254 }
2255
2256 /**
2257  * gst_pad_select:
2258  * @padlist: a #GList of pads.
2259  *
2260  * Waits for a buffer on any of the list of pads.
2261  *
2262  * Returns: the #GstPad that has a buffer available.
2263  * Use #gst_pad_pull() to get the buffer.
2264  */
2265 GstPad*
2266 gst_pad_select (GList *padlist)
2267 {
2268   GstPad *pad;
2269
2270   pad = gst_scheduler_pad_select (GST_PAD_PARENT (padlist->data)->sched,
2271                                   padlist);
2272   return pad;
2273 }
2274
2275 /**
2276  * gst_pad_selectv:
2277  * @pad: a first #GstPad to perform the select on.
2278  * @...: A NULL-terminated list of more pads to select on.
2279  *
2280  * Waits for a buffer on the given set of pads.
2281  *
2282  * Returns: the #GstPad that has a buffer available.
2283  * Use #gst_pad_pull() to get the buffer.
2284  */
2285 GstPad*
2286 gst_pad_selectv (GstPad *pad, ...)
2287 {
2288   GstPad *result;
2289   GList *padlist = NULL;
2290   va_list var_args;
2291
2292   if (pad == NULL)
2293     return NULL;
2294
2295   va_start (var_args, pad);
2296
2297   while (pad) {
2298     padlist = g_list_prepend (padlist, pad);
2299     pad = va_arg (var_args, GstPad *);
2300   }
2301   result = gst_pad_select (padlist);
2302   g_list_free (padlist);
2303
2304   va_end (var_args);
2305
2306   return result;
2307 }
2308
2309 /************************************************************************
2310  *
2311  * templates
2312  *
2313  */
2314 static void             gst_pad_template_class_init     (GstPadTemplateClass *klass);
2315 static void             gst_pad_template_init           (GstPadTemplate *templ);
2316
2317 GType
2318 gst_pad_template_get_type (void)
2319 {
2320   static GType padtemplate_type = 0;
2321
2322   if (!padtemplate_type) {
2323     static const GTypeInfo padtemplate_info = {
2324       sizeof (GstPadTemplateClass), NULL, NULL,
2325       (GClassInitFunc) gst_pad_template_class_init, NULL, NULL,
2326       sizeof (GstPadTemplate),
2327       32,
2328       (GInstanceInitFunc) gst_pad_template_init, NULL
2329     };
2330     padtemplate_type = g_type_register_static(GST_TYPE_OBJECT, "GstPadTemplate",
2331                                               &padtemplate_info, 0);
2332   }
2333   return padtemplate_type;
2334 }
2335
2336 static void
2337 gst_pad_template_class_init (GstPadTemplateClass *klass)
2338 {
2339   GObjectClass *gobject_class;
2340   GstObjectClass *gstobject_class;
2341
2342   gobject_class = (GObjectClass*) klass;
2343   gstobject_class = (GstObjectClass*) klass;
2344
2345   padtemplate_parent_class = g_type_class_ref (GST_TYPE_OBJECT);
2346
2347   gst_pad_template_signals[TEMPL_PAD_CREATED] =
2348     g_signal_new ("pad_created", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
2349                   G_STRUCT_OFFSET (GstPadTemplateClass, pad_created),
2350                   NULL, NULL, gst_marshal_VOID__POINTER, G_TYPE_NONE, 1,
2351                   G_TYPE_POINTER);
2352
2353   gstobject_class->path_string_separator = "*";
2354 }
2355
2356 static void
2357 gst_pad_template_init (GstPadTemplate *templ)
2358 {
2359 }
2360
2361 /* ALWAYS padtemplates cannot have conversion specifications, it doesn't make
2362  * sense.
2363  * SOMETIMES padtemplates can do whatever they want, they are provided by the
2364  * element.
2365  * REQUEST padtemplates can be reverse-parsed (the user asks for 'sink1', the
2366  * 'sink%d' template is automatically selected), so we need to restrict their
2367  * naming.
2368  */
2369 static gboolean
2370 name_is_valid (const gchar *name, GstPadPresence presence)
2371 {
2372   const gchar *str;
2373
2374   if (presence == GST_PAD_ALWAYS) {
2375     if (strchr (name, '%')) {
2376       g_warning ("invalid name template %s: conversion specifications are not"
2377                  " allowed for GST_PAD_ALWAYS padtemplates", name);
2378       return FALSE;
2379     }
2380   } else if (presence == GST_PAD_REQUEST) {
2381     if ((str = strchr (name, '%')) && strchr (str + 1, '%')) {
2382       g_warning ("invalid name template %s: only one conversion specification"
2383                  " allowed in GST_PAD_REQUEST padtemplate", name);
2384       return FALSE;
2385     }
2386     if (str && (*(str+1) != 's' && *(str+1) != 'd')) {
2387       g_warning ("invalid name template %s: conversion specification must be of"
2388                  " type '%%d' or '%%s' for GST_PAD_REQUEST padtemplate", name);
2389       return FALSE;
2390     }
2391     if (str && (*(str+2) != '\0')) {
2392       g_warning ("invalid name template %s: conversion specification must"
2393                  " appear at the end of the GST_PAD_REQUEST padtemplate name",
2394                  name);
2395       return FALSE;
2396     }
2397   }
2398
2399   return TRUE;
2400 }
2401
2402 /**
2403  * gst_pad_template_new:
2404  * @name_template: the name template.
2405  * @direction: the #GstPadDirection of the template.
2406  * @presence: the #GstPadPresence of the pad.
2407  * @caps: a #GstCaps set for the template.
2408  * @...: a NULL-terminated list of #GstCaps.
2409  *
2410  * Creates a new pad template with a name according to the given template
2411  * and with the given arguments.
2412  *
2413  * Returns: a new #GstPadTemplate.
2414  */
2415 GstPadTemplate*
2416 gst_pad_template_new (const gchar *name_template,
2417                      GstPadDirection direction, GstPadPresence presence,
2418                      GstCaps *caps, ...)
2419 {
2420   GstPadTemplate *new;
2421   va_list var_args;
2422   GstCaps *thecaps = NULL;
2423
2424   g_return_val_if_fail (name_template != NULL, NULL);
2425
2426   if (!name_is_valid (name_template, presence))
2427     return NULL;
2428
2429   new = g_object_new (gst_pad_template_get_type (),
2430                       "name", name_template,
2431                       NULL);
2432
2433   GST_PAD_TEMPLATE_NAME_TEMPLATE (new) = g_strdup (name_template);
2434   GST_PAD_TEMPLATE_DIRECTION (new) = direction;
2435   GST_PAD_TEMPLATE_PRESENCE (new) = presence;
2436
2437   va_start (var_args, caps);
2438
2439   while (caps) {
2440     new->fixed &= caps->fixed;
2441     thecaps = gst_caps_append (thecaps, gst_caps_ref (caps));
2442     caps = va_arg (var_args, GstCaps*);
2443   }
2444   va_end (var_args);
2445
2446   GST_PAD_TEMPLATE_CAPS (new) = thecaps;
2447
2448   return new;
2449 }
2450
2451 /**
2452  * gst_pad_template_get_caps:
2453  * @templ: a #GstPadTemplate to get capabilities of.
2454  *
2455  * Gets the capabilities of the pad template.
2456  *
2457  * Returns: the #GstCaps of the pad template.
2458  */
2459 GstCaps*
2460 gst_pad_template_get_caps (GstPadTemplate *templ)
2461 {
2462   g_return_val_if_fail (templ != NULL, NULL);
2463
2464   return GST_PAD_TEMPLATE_CAPS (templ);
2465 }
2466
2467 /**
2468  * gst_pad_set_element_private:
2469  * @pad: the #GstPad to set the private data of.
2470  * @priv: The private data to attach to the pad.
2471  *
2472  * Set the given private data gpointer on the pad.
2473  * This function can only be used by the element that owns the pad.
2474  */
2475 void
2476 gst_pad_set_element_private (GstPad *pad, gpointer priv)
2477 {
2478   pad->element_private = priv;
2479 }
2480
2481 /**
2482  * gst_pad_get_element_private:
2483  * @pad: the #GstPad to get the private data of.
2484  *
2485  * Gets the private data of a pad.
2486  *
2487  * Returns: a #gpointer to the private data.
2488  */
2489 gpointer
2490 gst_pad_get_element_private (GstPad *pad)
2491 {
2492   return pad->element_private;
2493 }
2494
2495
2496 /***** ghost pads *****/
2497 GType _gst_ghost_pad_type = 0;
2498
2499 static void     gst_ghost_pad_class_init         (GstGhostPadClass *klass);
2500 static void     gst_ghost_pad_init               (GstGhostPad *pad);
2501
2502 static GstPad *ghost_pad_parent_class = NULL;
2503 /* static guint gst_ghost_pad_signals[LAST_SIGNAL] = { 0 }; */
2504
2505 GType
2506 gst_ghost_pad_get_type (void)
2507 {
2508   if (!_gst_ghost_pad_type) {
2509     static const GTypeInfo pad_info = {
2510       sizeof (GstGhostPadClass), NULL, NULL,
2511       (GClassInitFunc) gst_ghost_pad_class_init, NULL, NULL,
2512       sizeof (GstGhostPad),
2513       8,
2514       (GInstanceInitFunc) gst_ghost_pad_init,
2515       NULL
2516     };
2517     _gst_ghost_pad_type = g_type_register_static (GST_TYPE_PAD, "GstGhostPad",
2518                                                   &pad_info, 0);
2519   }
2520   return _gst_ghost_pad_type;
2521 }
2522
2523 static void
2524 gst_ghost_pad_class_init (GstGhostPadClass *klass)
2525 {
2526   GObjectClass *gobject_class;
2527
2528   gobject_class = (GObjectClass*) klass;
2529
2530   ghost_pad_parent_class = g_type_class_ref (GST_TYPE_PAD);
2531 }
2532
2533 static void
2534 gst_ghost_pad_init (GstGhostPad *pad)
2535 {
2536   pad->realpad = NULL;
2537 }
2538
2539 /**
2540  * gst_ghost_pad_new:
2541  * @name: the name of the new ghost pad.
2542  * @pad: the #GstPad to create a ghost pad for.
2543  *
2544  * Creates a new ghost pad associated with the given pad, and names it with
2545  * the given name.  If name is NULL, a guaranteed unique name (across all
2546  * ghost pads) will be assigned (most likely of the form ghostpad&perc;d).
2547  *
2548  * Returns: a new ghost #GstPad, or NULL in case of an error.
2549  */
2550
2551 GstPad*
2552 gst_ghost_pad_new (const gchar *name,
2553                    GstPad *pad)
2554 {
2555   GstGhostPad *ghostpad;
2556   GstRealPad *realpad;
2557
2558   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2559
2560   ghostpad = g_object_new (gst_ghost_pad_get_type () ,NULL);
2561   gst_pad_set_name (GST_PAD (ghostpad), name);
2562
2563   realpad = (GstRealPad *) pad;
2564
2565   while (!GST_IS_REAL_PAD (realpad)) {
2566     realpad = GST_PAD_REALIZE (realpad);
2567   }
2568   GST_GPAD_REALPAD (ghostpad) = realpad;
2569   GST_PAD_PAD_TEMPLATE (ghostpad) = GST_PAD_PAD_TEMPLATE (pad);
2570
2571   /* add ourselves to the real pad's list of ghostpads */
2572   gst_pad_add_ghost_pad (pad, GST_PAD (ghostpad));
2573
2574   /* FIXME need to ref the real pad here... ? */
2575
2576   GST_DEBUG (GST_CAT_PADS, "created ghost pad \"%s\"",
2577              gst_pad_get_name (GST_PAD (ghostpad)));
2578
2579   return GST_PAD (ghostpad);
2580 }
2581
2582 /**
2583  * gst_pad_get_internal_connections_default:
2584  * @pad: the #GstPad to get the internal connections of.
2585  *
2586  * Gets a list of pads to which the given pad is connected to
2587  * inside of the parent element.
2588  * This is the default handler, and thus returns a list of all of the
2589  * pads inside the parent element with opposite direction.
2590  * The caller must free this list after use.
2591  *
2592  * Returns: a newly allocated #GList of pads.
2593  */
2594 GList*
2595 gst_pad_get_internal_connections_default (GstPad *pad)
2596 {
2597   GList *res = NULL;
2598   GstElement *parent;
2599   GList *parent_pads;
2600   GstPadDirection direction;
2601   GstRealPad *rpad;
2602
2603   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2604
2605   rpad = GST_PAD_REALIZE (pad);
2606   direction = rpad->direction;
2607
2608   parent = GST_PAD_PARENT (rpad);
2609   parent_pads = parent->pads;
2610
2611   while (parent_pads) {
2612     GstRealPad *parent_pad = GST_PAD_REALIZE (parent_pads->data);
2613
2614     if (parent_pad->direction != direction) {
2615       res = g_list_prepend (res, parent_pad);
2616     }
2617
2618     parent_pads = g_list_next (parent_pads);
2619   }
2620
2621   return res;
2622 }
2623
2624 /**
2625  * gst_pad_get_internal_connections:
2626  * @pad: the #GstPad to get the internal connections of.
2627  *
2628  * Gets a list of pads to which the given pad is connected to
2629  * inside of the parent element.
2630  * The caller must free this list after use.
2631  *
2632  * Returns: a newly allocated #GList of pads.
2633  */
2634 GList*
2635 gst_pad_get_internal_connections (GstPad *pad)
2636 {
2637   GList *res = NULL;
2638   GstRealPad *rpad;
2639
2640   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2641
2642   rpad = GST_PAD_REALIZE (pad);
2643
2644   if (GST_RPAD_INTCONNFUNC (rpad))
2645     res = GST_RPAD_INTCONNFUNC (rpad) (GST_PAD_CAST (rpad));
2646
2647   return res;
2648 }
2649
2650
2651 static gboolean
2652 gst_pad_event_default_dispatch (GstPad *pad, GstElement *element,
2653                                 GstEvent *event)
2654 {
2655   GList *pads = element->pads;
2656
2657   while (pads) {
2658     GstPad *eventpad = GST_PAD (pads->data);
2659     pads = g_list_next (pads);
2660
2661     /* for all pads in the opposite direction that are connected */
2662     if (GST_PAD_DIRECTION (eventpad) != GST_PAD_DIRECTION (pad)
2663      && GST_PAD_IS_USABLE (eventpad)) {
2664       if (GST_PAD_DIRECTION (eventpad) == GST_PAD_SRC) {
2665         /* increase the refcount */
2666         gst_event_ref (event);
2667         gst_pad_push (eventpad, GST_BUFFER (event));
2668       }
2669       else {
2670         GstPad *peerpad = GST_PAD_CAST (GST_RPAD_PEER (eventpad));
2671
2672         /* we only send the event on one pad, multi-sinkpad elements
2673          * should implement a handler */
2674         return gst_pad_send_event (peerpad, event);
2675       }
2676     }
2677   }
2678   gst_event_unref (event);
2679   return TRUE;
2680 }
2681
2682 /**
2683  * gst_pad_event_default:
2684  * @pad: a #GstPad to call the default event handler on.
2685  * @event: the #GstEvent to handle.
2686  *
2687  * Invokes the default event handler for the given pad.
2688  *
2689  * Returns: TRUE if the event was sent succesfully.
2690  */
2691 gboolean
2692 gst_pad_event_default (GstPad *pad, GstEvent *event)
2693 {
2694   GstElement *element;
2695
2696   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2697   g_return_val_if_fail (event, FALSE);
2698
2699   element = GST_PAD_PARENT (pad);
2700
2701   switch (GST_EVENT_TYPE (event)) {
2702     case GST_EVENT_EOS:
2703       gst_pad_event_default_dispatch (pad, element, event);
2704       gst_element_set_eos (element);
2705       /* we have to try to schedule another element
2706        * because this one is disabled */
2707       gst_element_yield (element);
2708       break;
2709     case GST_EVENT_DISCONTINUOUS:
2710     case GST_EVENT_FLUSH:
2711     default:
2712       return gst_pad_event_default_dispatch (pad, element, event);
2713   }
2714   return TRUE;
2715 }
2716
2717 /**
2718  * gst_pad_dispatcher:
2719  * @pad: a #GstPad to dispatch.
2720  * @dispatch: the #GstDispatcherFunction to call.
2721  * @data: gpointer user data passed to the dispatcher function.
2722  *
2723  * Invokes the given dispatcher function on all pads that are
2724  * internally connected to the given pad.
2725  * The GstPadDispatcherFunction should return TRUE when no further pads
2726  * need to be processed.
2727  *
2728  * Returns: TRUE if one of the dispatcher functions returned TRUE.
2729  */
2730 gboolean
2731 gst_pad_dispatcher (GstPad *pad, GstPadDispatcherFunction dispatch,
2732                     gpointer data)
2733 {
2734   gboolean res = FALSE;
2735   GList *int_pads, *orig;
2736
2737   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2738   g_return_val_if_fail (data, FALSE);
2739
2740   orig = int_pads = gst_pad_get_internal_connections (pad);
2741
2742   while (int_pads) {
2743     GstRealPad *int_rpad = GST_PAD_REALIZE (int_pads->data);
2744     GstRealPad *int_peer = GST_RPAD_PEER (int_rpad);
2745
2746     if (int_peer && GST_PAD_IS_USABLE (int_peer)) {
2747       res = dispatch (GST_PAD_CAST (int_peer), data);
2748       if (res)
2749         break;
2750     }
2751     int_pads = g_list_next (int_pads);
2752   }
2753
2754   g_list_free (orig);
2755
2756   return res;
2757 }
2758
2759 /**
2760  * gst_pad_send_event:
2761  * @pad: a #GstPad to send the event to.
2762  * @event: the #GstEvent to send to the pad.
2763  *
2764  * Sends the event to the pad.
2765  *
2766  * Returns: TRUE if the event was handled.
2767  */
2768 gboolean
2769 gst_pad_send_event (GstPad *pad, GstEvent *event)
2770 {
2771   gboolean success = FALSE;
2772   GstRealPad *rpad;
2773
2774   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2775   g_return_val_if_fail (event, FALSE);
2776
2777   rpad = GST_PAD_REALIZE (pad);
2778
2779   /* don't send events on usuable pads */
2780   if (GST_PAD_IS_SINK (rpad) && !GST_PAD_IS_USABLE (rpad)) {
2781     GST_DEBUG (GST_CAT_EVENT, "pad %s:%s is not usable",
2782                GST_DEBUG_PAD_NAME (rpad));
2783     return FALSE;
2784   }
2785
2786   if (GST_EVENT_SRC (event) == NULL)
2787     GST_EVENT_SRC (event) = gst_object_ref (GST_OBJECT (rpad));
2788
2789   GST_DEBUG (GST_CAT_EVENT, "have event %d on pad %s:%s",
2790                   GST_EVENT_TYPE (event), GST_DEBUG_PAD_NAME (rpad));
2791
2792   if (GST_RPAD_EVENTFUNC (rpad))
2793     success = GST_RPAD_EVENTFUNC (rpad) (GST_PAD_CAST (rpad), event);
2794   else {
2795     GST_DEBUG (GST_CAT_EVENT, "there's no event function for pad %s:%s",
2796                GST_DEBUG_PAD_NAME (rpad));
2797     gst_event_unref (event);
2798   }
2799
2800   return success;
2801 }
2802
2803 typedef struct
2804 {
2805   GstFormat      src_format;
2806   gint64         src_value;
2807   GstFormat      *dest_format;
2808   gint64         *dest_value;
2809 } GstPadConvertData;
2810
2811 static gboolean
2812 gst_pad_convert_dispatcher (GstPad *pad, GstPadConvertData *data)
2813 {
2814   return gst_pad_convert (pad, data->src_format, data->src_value,
2815                                data->dest_format, data->dest_value);
2816 }
2817
2818 /**
2819  * gst_pad_convert_default:
2820  * @pad: a #GstPad to invoke the default converter on.
2821  * @src_format: the source #GstFormat.
2822  * @src_value: the source value.
2823  * @dest_format: a pointer to the destination #GstFormat.
2824  * @dest_value: a pointer to the destination value.
2825  *
2826  * Invokes the default converter on a pad.
2827  * This will forward the call to the pad obtained
2828  * using the internal connection of
2829  * the element.
2830  *
2831  * Returns: TRUE if the conversion could be performed.
2832  */
2833 gboolean
2834 gst_pad_convert_default (GstPad *pad,
2835                          GstFormat src_format,  gint64  src_value,
2836                          GstFormat *dest_format, gint64 *dest_value)
2837 {
2838   GstPadConvertData data;
2839
2840   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2841   g_return_val_if_fail (dest_format, FALSE);
2842   g_return_val_if_fail (dest_value, FALSE);
2843
2844   data.src_format = src_format;
2845   data.src_value = src_value;
2846   data.dest_format = dest_format;
2847   data.dest_value = dest_value;
2848
2849   return gst_pad_dispatcher (pad, (GstPadDispatcherFunction)
2850                                     gst_pad_convert_dispatcher, &data);
2851 }
2852
2853 /**
2854  * gst_pad_convert:
2855  * @pad: a #GstPad to invoke the default converter on.
2856  * @src_format: the source #GstFormat.
2857  * @src_value: the source value.
2858  * @dest_format: a pointer to the destination #GstFormat.
2859  * @dest_value: a pointer to the destination value.
2860  *
2861  * Invokes a conversion on the pad.
2862  *
2863  * Returns: TRUE if the conversion could be performed.
2864  */
2865 gboolean
2866 gst_pad_convert (GstPad *pad,
2867                  GstFormat src_format,  gint64  src_value,
2868                  GstFormat *dest_format, gint64 *dest_value)
2869 {
2870   GstRealPad *rpad;
2871
2872   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2873   g_return_val_if_fail (dest_format, FALSE);
2874   g_return_val_if_fail (dest_value, FALSE);
2875
2876   if (src_format == *dest_format) {
2877     *dest_value = src_value;
2878     return TRUE;
2879   }
2880
2881   rpad = GST_PAD_REALIZE (pad);
2882
2883   if (GST_RPAD_CONVERTFUNC (rpad)) {
2884     return GST_RPAD_CONVERTFUNC (rpad) (GST_PAD_CAST (rpad), src_format,
2885                                         src_value, dest_format, dest_value);
2886   }
2887
2888   return FALSE;
2889 }
2890
2891 typedef struct
2892 {
2893   GstPadQueryType type;
2894   GstFormat      *format;
2895   gint64         *value;
2896 } GstPadQueryData;
2897
2898 static gboolean
2899 gst_pad_query_dispatcher (GstPad *pad, GstPadQueryData *data)
2900 {
2901   return gst_pad_query (pad, data->type, data->format, data->value);
2902 }
2903
2904 /**
2905  * gst_pad_query_default:
2906  * @pad: a #GstPad to invoke the default query on.
2907  * @type: the #GstPadQueryType of the query to perform.
2908  * @format: a pointer to the #GstFormat of the result.
2909  * @value: a pointer to the result.
2910  *
2911  * Invokes the default query function on a pad.
2912  *
2913  * Returns: TRUE if the query could be performed.
2914  */
2915 gboolean
2916 gst_pad_query_default (GstPad *pad, GstPadQueryType type,
2917                        GstFormat *format,  gint64 *value)
2918 {
2919   GstPadQueryData data;
2920
2921   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2922   g_return_val_if_fail (format, FALSE);
2923   g_return_val_if_fail (value, FALSE);
2924
2925   data.type = type;
2926   data.format = format;
2927   data.value = value;
2928
2929   return gst_pad_dispatcher (pad, (GstPadDispatcherFunction)
2930                                    gst_pad_query_dispatcher, &data);
2931 }
2932
2933 /**
2934  * gst_pad_query:
2935  * @pad: a #GstPad to invoke the default query on.
2936  * @type: the #GstPadQueryType of the query to perform.
2937  * @format: a pointer to the #GstFormat of the result.
2938  * @value: a pointer to the result.
2939  *
2940  * Queries a pad for one of the available properties.
2941  *
2942  * Returns: TRUE if the query could be performed.
2943  */
2944 gboolean
2945 gst_pad_query (GstPad *pad, GstPadQueryType type,
2946                GstFormat *format, gint64 *value)
2947 {
2948   GstRealPad *rpad;
2949
2950   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2951   g_return_val_if_fail (format, FALSE);
2952   g_return_val_if_fail (value, FALSE);
2953
2954   rpad = GST_PAD_REALIZE (pad);
2955
2956   g_return_val_if_fail (rpad, FALSE);
2957
2958   if (GST_RPAD_QUERYFUNC (rpad))
2959     return GST_RPAD_QUERYFUNC (rpad) (GST_PAD_CAST (pad), type, format, value);
2960
2961   return FALSE;
2962 }
2963
2964 /**
2965  * gst_pad_handles_format:
2966  * @pad: a #GstPad to check
2967  * @format: the format to check
2968  *
2969  * Checks if the pad can handle the given format.
2970  *
2971  * Returns: TRUE if the pad can handle the given format
2972  */
2973 gboolean
2974 gst_pad_handles_format (GstPad *pad, GstFormat format)
2975 {
2976   const GstFormat *formats;
2977
2978   formats = gst_pad_get_formats (pad);
2979   if (!formats)
2980     return FALSE;
2981
2982   while (*formats) {
2983     if (*formats == format)
2984       return TRUE;
2985
2986     formats++;
2987   }
2988
2989   return FALSE;
2990 }
2991
2992 static gboolean
2993 gst_pad_get_formats_dispatcher (GstPad *pad, const GstFormat **data)
2994 {
2995   *data = gst_pad_get_formats (pad);
2996
2997   return TRUE;
2998 }
2999
3000 /**
3001  * gst_pad_get_formats_default:
3002  * @pad: a #GstPad to query
3003  *
3004  * Invoke the default format dispatcher for the pad.
3005  *
3006  * Returns: An array of GstFormats ended with a 0 value.
3007  */
3008 const GstFormat*
3009 gst_pad_get_formats_default (GstPad *pad)
3010 {
3011   GstFormat *result = NULL;
3012
3013   gst_pad_dispatcher (pad, (GstPadDispatcherFunction)
3014                       gst_pad_get_formats_dispatcher, &result);
3015
3016   return result;
3017 }
3018
3019 /**
3020  * gst_pad_get_formats:
3021  * @pad: a #GstPad to query
3022  *
3023  * Gets the list of supported formats from the pad.
3024  *
3025  * Returns: An array of GstFormats ended with a 0 value.
3026  */
3027 const GstFormat*
3028 gst_pad_get_formats (GstPad *pad)
3029 {
3030   GstRealPad *rpad;
3031
3032   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3033
3034   rpad = GST_PAD_REALIZE (pad);
3035
3036   if (GST_RPAD_FORMATSFUNC (rpad))
3037     return GST_RPAD_FORMATSFUNC (rpad) (GST_PAD_CAST (pad));
3038
3039   return NULL;
3040 }
3041