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 linking 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  * SECTION:gstpad
  24  * @short_description: Object contained by elements that allows links to
  25  *                     other elements
  26  * @see_also: #GstPadTemplate, #GstElement, #GstEvent
  27  *
  28  * A #GstElement is linked to other elements via "pads", which are extremely
  29  * light-weight generic link points.
  30  * After two pads are retrieved from an element with gst_element_get_pad(),
  31  * the pads can be link with gst_pad_link(). (For quick links,
  32  * you can also use gst_element_link(), which will make the obvious
  33  * link for you if it's straightforward.)
  34  *
  35  * Pads are typically created from a #GstPadTemplate with
  36  * gst_pad_new_from_template().
  37  *
  38  * Pads have #GstCaps attached to it to describe the media type they are
  39  * capable of dealing with.  gst_pad_get_caps() and gst_pad_set_caps() are
  40  * used to manipulate the caps of the pads.
  41  * Pads created from a pad template cannot set capabilities that are
  42  * incompatible with the pad template capabilities.
  43  *
  44  * Pads without pad templates can be created with gst_pad_new(),
  45  * which takes a direction and a name as an argument.  If the name is NULL,
  46  * then a guaranteed unique name will be assigned to it.
  47  *
  48  * gst_pad_get_parent() will retrieve the #GstElement that owns the pad.
  49  *
  50  * A #GstElement creating a pad will typically use the various
  51  * gst_pad_set_*_function() calls to register callbacks for various events
  52  * on the pads.
  53  *
  54  * GstElements will use gst_pad_push() and gst_pad_pull_range() to push out
  55  * or pull in a buffer.
  56  *
  57  * To send a #GstEvent on a pad, use gst_pad_send_event() and
  58  * gst_pad_push_event().
  59  *
  60  * Last reviewed on 2006-07-06 (0.10.9)
  61  */
  62
  63 #include "gst_private.h"
  64
  65 #include "gstpad.h"
  66 #include "gstpadtemplate.h"
  67 #include "gstenumtypes.h"
  68 #include "gstmarshal.h"
  69 #include "gstutils.h"
  70 #include "gstinfo.h"
  71 #include "gsterror.h"
  72 #include "gstvalue.h"
  73 #include "glib-compat-private.h"
  74
  75 GST_DEBUG_CATEGORY_STATIC (debug_dataflow);
  76 #define GST_CAT_DEFAULT GST_CAT_PADS
  77
  78 /* Pad signals and args */
  79 enum
  80 {
  81   PAD_LINKED,
  82   PAD_UNLINKED,
  83   PAD_REQUEST_LINK,
  84   PAD_HAVE_DATA,
  85   /* FILL ME */
  86   LAST_SIGNAL
  87 };
  88
  89 enum
  90 {
  91   PAD_PROP_0,
  92   PAD_PROP_CAPS,
  93   PAD_PROP_DIRECTION,
  94   PAD_PROP_TEMPLATE,
  95   /* FILL ME */
  96 };
  97
  98 static void gst_pad_class_init (GstPadClass * klass);
  99 static void gst_pad_init (GstPad * pad);
 100 static void gst_pad_dispose (GObject * object);
 101 static void gst_pad_finalize (GObject * object);
 102 static void gst_pad_set_property (GObject * object, guint prop_id,
 103     const GValue * value, GParamSpec * pspec);
 104 static void gst_pad_get_property (GObject * object, guint prop_id,
 105     GValue * value, GParamSpec * pspec);
 106
 107 static GstFlowReturn handle_pad_block (GstPad * pad);
 108 static GstCaps *gst_pad_get_caps_unlocked (GstPad * pad);
 109 static void gst_pad_set_pad_template (GstPad * pad, GstPadTemplate * templ);
 110 static gboolean gst_pad_activate_default (GstPad * pad);
 111 static gboolean gst_pad_acceptcaps_default (GstPad * pad, GstCaps * caps);
 112
 113 #ifndef GST_DISABLE_LOADSAVE
 114 static xmlNodePtr gst_pad_save_thyself (GstObject * object, xmlNodePtr parent);
 115 #endif
 116
 117 static GstObjectClass *parent_class = NULL;
 118 static guint gst_pad_signals[LAST_SIGNAL] = { 0 };
 119
 120 /* quarks for probe signals */
 121 static GQuark buffer_quark;
 122 static GQuark event_quark;
 123
 124 typedef struct
 125 {
 126   const gint ret;
 127   const gchar *name;
 128   GQuark quark;
 129 } GstFlowQuarks;
 130
 131 static GstFlowQuarks flow_quarks[] = {
 132   {GST_FLOW_CUSTOM_SUCCESS, "custom-success", 0},
 133   {GST_FLOW_RESEND, "resend", 0},
 134   {GST_FLOW_OK, "ok", 0},
 135   {GST_FLOW_NOT_LINKED, "not-linked", 0},
 136   {GST_FLOW_WRONG_STATE, "wrong-state", 0},
 137   {GST_FLOW_UNEXPECTED, "unexpected", 0},
 138   {GST_FLOW_NOT_NEGOTIATED, "not-negotiated", 0},
 139   {GST_FLOW_ERROR, "error", 0},
 140   {GST_FLOW_NOT_SUPPORTED, "not-supported", 0},
 141   {GST_FLOW_CUSTOM_ERROR, "custom-error", 0},
 142
 143   {0, NULL, 0}
 144 };
 145
 146 /**
 147  * gst_flow_get_name:
 148  * @ret: a #GstFlowReturn to get the name of.
 149  *
 150  * Gets a string representing the given flow return.
 151  *
 152  * Returns: a static string with the name of the flow return.
 153  */
 154 G_CONST_RETURN gchar *
 155 gst_flow_get_name (GstFlowReturn ret)
 156 {
 157   gint i;
 158
 159   ret = CLAMP (ret, GST_FLOW_CUSTOM_ERROR, GST_FLOW_CUSTOM_SUCCESS);
 160
 161   for (i = 0; flow_quarks[i].name; i++) {
 162     if (ret == flow_quarks[i].ret)
 163       return flow_quarks[i].name;
 164   }
 165   return "unknown";
 166 }
 167
 168 /**
 169  * gst_flow_to_quark:
 170  * @ret: a #GstFlowReturn to get the quark of.
 171  *
 172  * Get the unique quark for the given GstFlowReturn.
 173  *
 174  * Returns: the quark associated with the flow return or 0 if an
 175  * invalid return was specified.
 176  */
 177 GQuark
 178 gst_flow_to_quark (GstFlowReturn ret)
 179 {
 180   gint i;
 181
 182   ret = CLAMP (ret, GST_FLOW_CUSTOM_ERROR, GST_FLOW_CUSTOM_SUCCESS);
 183
 184   for (i = 0; flow_quarks[i].name; i++) {
 185     if (ret == flow_quarks[i].ret)
 186       return flow_quarks[i].quark;
 187   }
 188   return 0;
 189 }
 190
 191 GType
 192 gst_pad_get_type (void)
 193 {
 194   static GType gst_pad_type = 0;
 195
 196   if (G_UNLIKELY (gst_pad_type == 0)) {
 197     static const GTypeInfo pad_info = {
 198       sizeof (GstPadClass), NULL, NULL,
 199       (GClassInitFunc) gst_pad_class_init, NULL, NULL,
 200       sizeof (GstPad),
 201       0,
 202       (GInstanceInitFunc) gst_pad_init, NULL
 203     };
 204     gint i;
 205
 206     gst_pad_type = g_type_register_static (GST_TYPE_OBJECT, "GstPad",
 207         &pad_info, 0);
 208
 209     buffer_quark = g_quark_from_static_string ("buffer");
 210     event_quark = g_quark_from_static_string ("event");
 211
 212     for (i = 0; flow_quarks[i].name; i++) {
 213       flow_quarks[i].quark = g_quark_from_static_string (flow_quarks[i].name);
 214     }
 215
 216     GST_DEBUG_CATEGORY_INIT (debug_dataflow, "GST_DATAFLOW",
 217         GST_DEBUG_BOLD | GST_DEBUG_FG_GREEN, "dataflow inside pads");
 218   }
 219   return gst_pad_type;
 220 }
 221
 222 static gboolean
 223 _gst_do_pass_data_accumulator (GSignalInvocationHint * ihint,
 224     GValue * return_accu, const GValue * handler_return, gpointer dummy)
 225 {
 226   gboolean ret = g_value_get_boolean (handler_return);
 227
 228   GST_DEBUG ("accumulated %d", ret);
 229   g_value_set_boolean (return_accu, ret);
 230
 231   return ret;
 232 }
 233
 234 static gboolean
 235 default_have_data (GstPad * pad, GstMiniObject * o)
 236 {
 237   return TRUE;
 238 }
 239
 240 static void
 241 gst_pad_class_init (GstPadClass * klass)
 242 {
 243   GObjectClass *gobject_class;
 244   GstObjectClass *gstobject_class;
 245
 246   gobject_class = G_OBJECT_CLASS (klass);
 247   gstobject_class = GST_OBJECT_CLASS (klass);
 248
 249   parent_class = g_type_class_peek_parent (klass);
 250
 251   gobject_class->dispose = GST_DEBUG_FUNCPTR (gst_pad_dispose);
 252   gobject_class->finalize = GST_DEBUG_FUNCPTR (gst_pad_finalize);
 253   gobject_class->set_property = GST_DEBUG_FUNCPTR (gst_pad_set_property);
 254   gobject_class->get_property = GST_DEBUG_FUNCPTR (gst_pad_get_property);
 255
 256   /**
 257    * GstPad::linked:
 258    * @pad: the pad that emitted the signal
 259    * @peer: the peer pad that has been connected
 260    *
 261    * Signals that a pad has been linked to the peer pad.
 262    */
 263   gst_pad_signals[PAD_LINKED] =
 264       g_signal_new ("linked", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 265       G_STRUCT_OFFSET (GstPadClass, linked), NULL, NULL,
 266       gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_PAD);
 267   /**
 268    * GstPad::unlinked:
 269    * @pad: the pad that emitted the signal
 270    * @peer: the peer pad that has been disconnected
 271    *
 272    * Signals that a pad has been unlinked from the peer pad.
 273    */
 274   gst_pad_signals[PAD_UNLINKED] =
 275       g_signal_new ("unlinked", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 276       G_STRUCT_OFFSET (GstPadClass, unlinked), NULL, NULL,
 277       gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_PAD);
 278   /**
 279    * GstPad::request-link:
 280    * @pad: the pad that emitted the signal
 281    * @peer: the peer pad for which a connection is requested
 282    *
 283    * Signals that a pad connection has been requested.
 284    */
 285   gst_pad_signals[PAD_REQUEST_LINK] =
 286       g_signal_new ("request-link", G_TYPE_FROM_CLASS (klass),
 287       G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstPadClass, request_link), NULL,
 288       NULL, gst_marshal_VOID__OBJECT, G_TYPE_NONE, 0);
 289
 290   /**
 291    * GstPad::have-data:
 292    * @pad: the pad that emitted the signal
 293    * @mini_obj: new data
 294    *
 295    * Signals that new data is available on the pad. This signal is used
 296    * internally for implementing pad probes.
 297    * See gst_pad_add_*_probe functions.
 298    *
 299    * Returns: %TRUE to keep the data, %FALSE to drop it
 300    */
 301   gst_pad_signals[PAD_HAVE_DATA] =
 302       g_signal_new ("have-data", G_TYPE_FROM_CLASS (klass),
 303       G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
 304       G_STRUCT_OFFSET (GstPadClass, have_data),
 305       _gst_do_pass_data_accumulator,
 306       NULL, gst_marshal_BOOLEAN__POINTER, G_TYPE_BOOLEAN, 1,
 307       GST_TYPE_MINI_OBJECT);
 308
 309   g_object_class_install_property (gobject_class, PAD_PROP_CAPS,
 310       g_param_spec_boxed ("caps", "Caps", "The capabilities of the pad",
 311           GST_TYPE_CAPS, G_PARAM_READABLE));
 312   g_object_class_install_property (gobject_class, PAD_PROP_DIRECTION,
 313       g_param_spec_enum ("direction", "Direction", "The direction of the pad",
 314           GST_TYPE_PAD_DIRECTION, GST_PAD_UNKNOWN,
 315           G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
 316   g_object_class_install_property (gobject_class, PAD_PROP_TEMPLATE,
 317       g_param_spec_object ("template", "Template",
 318           "The GstPadTemplate of this pad", GST_TYPE_PAD_TEMPLATE,
 319           G_PARAM_READWRITE));
 320
 321 #ifndef GST_DISABLE_LOADSAVE
 322   gstobject_class->save_thyself = GST_DEBUG_FUNCPTR (gst_pad_save_thyself);
 323 #endif
 324   gstobject_class->path_string_separator = ".";
 325
 326   klass->have_data = default_have_data;
 327 }
 328
 329 static void
 330 gst_pad_init (GstPad * pad)
 331 {
 332   GST_PAD_DIRECTION (pad) = GST_PAD_UNKNOWN;
 333   GST_PAD_PEER (pad) = NULL;
 334
 335   GST_PAD_CHAINFUNC (pad) = NULL;
 336
 337   GST_PAD_LINKFUNC (pad) = NULL;
 338
 339   GST_PAD_CAPS (pad) = NULL;
 340   GST_PAD_GETCAPSFUNC (pad) = NULL;
 341
 342   GST_PAD_ACTIVATEFUNC (pad) = GST_DEBUG_FUNCPTR (gst_pad_activate_default);
 343   GST_PAD_EVENTFUNC (pad) = GST_DEBUG_FUNCPTR (gst_pad_event_default);
 344   GST_PAD_QUERYTYPEFUNC (pad) =
 345       GST_DEBUG_FUNCPTR (gst_pad_get_query_types_default);
 346   GST_PAD_QUERYFUNC (pad) = GST_DEBUG_FUNCPTR (gst_pad_query_default);
 347   GST_PAD_INTLINKFUNC (pad) =
 348       GST_DEBUG_FUNCPTR (gst_pad_get_internal_links_default);
 349   GST_PAD_ACCEPTCAPSFUNC (pad) = GST_DEBUG_FUNCPTR (gst_pad_acceptcaps_default);
 350
 351   pad->do_buffer_signals = 0;
 352   pad->do_event_signals = 0;
 353
 354   /* FIXME, should be set flushing initially, see #339326 */
 355   GST_PAD_UNSET_FLUSHING (pad);
 356
 357   pad->preroll_lock = g_mutex_new ();
 358   pad->preroll_cond = g_cond_new ();
 359
 360   pad->stream_rec_lock = g_new (GStaticRecMutex, 1);
 361   g_static_rec_mutex_init (pad->stream_rec_lock);
 362
 363   pad->block_cond = g_cond_new ();
 364 }
 365
 366 static void
 367 gst_pad_dispose (GObject * object)
 368 {
 369   GstPad *pad = GST_PAD (object);
 370
 371   GST_CAT_DEBUG (GST_CAT_REFCOUNTING, "dispose %s:%s",
 372       GST_DEBUG_PAD_NAME (pad));
 373
 374   /* we don't hold a ref to the peer so we can just set the
 375    * peer to NULL. */
 376   GST_PAD_PEER (pad) = NULL;
 377
 378   /* clear the caps */
 379   gst_caps_replace (&GST_PAD_CAPS (pad), NULL);
 380
 381   gst_pad_set_pad_template (pad, NULL);
 382
 383   G_OBJECT_CLASS (parent_class)->dispose (object);
 384 }
 385
 386 static void
 387 gst_pad_finalize (GObject * object)
 388 {
 389   GstPad *pad = GST_PAD (object);
 390   GstTask *task;
 391
 392   /* in case the task is still around, clean it up */
 393   if ((task = GST_PAD_TASK (pad))) {
 394     gst_task_join (task);
 395     GST_PAD_TASK (pad) = NULL;
 396     gst_object_unref (task);
 397   }
 398
 399   if (pad->stream_rec_lock) {
 400     g_static_rec_mutex_free (pad->stream_rec_lock);
 401     g_free (pad->stream_rec_lock);
 402     pad->stream_rec_lock = NULL;
 403   }
 404   if (pad->preroll_lock) {
 405     g_mutex_free (pad->preroll_lock);
 406     g_cond_free (pad->preroll_cond);
 407     pad->preroll_lock = NULL;
 408     pad->preroll_cond = NULL;
 409   }
 410   if (pad->block_cond) {
 411     g_cond_free (pad->block_cond);
 412     pad->block_cond = NULL;
 413   }
 414
 415   G_OBJECT_CLASS (parent_class)->finalize (object);
 416 }
 417
 418 static void
 419 gst_pad_set_property (GObject * object, guint prop_id,
 420     const GValue * value, GParamSpec * pspec)
 421 {
 422   g_return_if_fail (GST_IS_PAD (object));
 423
 424   switch (prop_id) {
 425     case PAD_PROP_DIRECTION:
 426       GST_PAD_DIRECTION (object) = g_value_get_enum (value);
 427       break;
 428     case PAD_PROP_TEMPLATE:
 429       gst_pad_set_pad_template (GST_PAD_CAST (object),
 430           (GstPadTemplate *) g_value_get_object (value));
 431       break;
 432     default:
 433       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 434       break;
 435   }
 436 }
 437
 438 static void
 439 gst_pad_get_property (GObject * object, guint prop_id,
 440     GValue * value, GParamSpec * pspec)
 441 {
 442   g_return_if_fail (GST_IS_PAD (object));
 443
 444   switch (prop_id) {
 445     case PAD_PROP_CAPS:
 446       g_value_set_boxed (value, GST_PAD_CAPS (object));
 447       break;
 448     case PAD_PROP_DIRECTION:
 449       g_value_set_enum (value, GST_PAD_DIRECTION (object));
 450       break;
 451     case PAD_PROP_TEMPLATE:
 452       g_value_set_object (value, GST_PAD_PAD_TEMPLATE (object));
 453       break;
 454     default:
 455       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 456       break;
 457   }
 458 }
 459
 460 /**
 461  * gst_pad_new:
 462  * @name: the name of the new pad.
 463  * @direction: the #GstPadDirection of the pad.
 464  *
 465  * Creates a new pad with the given name in the given direction.
 466  * If name is NULL, a guaranteed unique name (across all pads)
 467  * will be assigned.
 468  * This function makes a copy of the name so you can safely free the name.
 469  *
 470  * Returns: a new #GstPad, or NULL in case of an error.
 471  *
 472  * MT safe.
 473  */
 474 GstPad *
 475 gst_pad_new (const gchar * name, GstPadDirection direction)
 476 {
 477   return g_object_new (GST_TYPE_PAD,
 478       "name", name, "direction", direction, NULL);
 479 }
 480
 481 /**
 482  * gst_pad_new_from_template:
 483  * @templ: the pad template to use
 484  * @name: the name of the element
 485  *
 486  * Creates a new pad with the given name from the given template.
 487  * If name is NULL, a guaranteed unique name (across all pads)
 488  * will be assigned.
 489  * This function makes a copy of the name so you can safely free the name.
 490  *
 491  * Returns: a new #GstPad, or NULL in case of an error.
 492  */
 493 GstPad *
 494 gst_pad_new_from_template (GstPadTemplate * templ, const gchar * name)
 495 {
 496   g_return_val_if_fail (GST_IS_PAD_TEMPLATE (templ), NULL);
 497
 498   return g_object_new (GST_TYPE_PAD,
 499       "name", name, "direction", templ->direction, "template", templ, NULL);
 500 }
 501
 502 /**
 503  * gst_pad_new_from_static_template:
 504  * @templ: the #GstStaticPadTemplate to use
 505  * @name: the name of the element
 506  *
 507  * Creates a new pad with the given name from the given static template.
 508  * If name is NULL, a guaranteed unique name (across all pads)
 509  * will be assigned.
 510  * This function makes a copy of the name so you can safely free the name.
 511  *
 512  * Returns: a new #GstPad, or NULL in case of an error.
 513  */
 514 GstPad *
 515 gst_pad_new_from_static_template (GstStaticPadTemplate * templ,
 516     const gchar * name)
 517 {
 518   GstPad *pad;
 519   GstPadTemplate *template;
 520
 521   template = gst_static_pad_template_get (templ);
 522   pad = gst_pad_new_from_template (template, name);
 523   gst_object_unref (template);
 524   return pad;
 525 }
 526
 527 /**
 528  * gst_pad_get_direction:
 529  * @pad: a #GstPad to get the direction of.
 530  *
 531  * Gets the direction of the pad. The direction of the pad is
 532  * decided at construction time so this function does not take
 533  * the LOCK.
 534  *
 535  * Returns: the #GstPadDirection of the pad.
 536  *
 537  * MT safe.
 538  */
 539 GstPadDirection
 540 gst_pad_get_direction (GstPad * pad)
 541 {
 542   GstPadDirection result;
 543
 544   /* PAD_UNKNOWN is a little silly but we need some sort of
 545    * error return value */
 546   g_return_val_if_fail (GST_IS_PAD (pad), GST_PAD_UNKNOWN);
 547
 548   GST_OBJECT_LOCK (pad);
 549   result = GST_PAD_DIRECTION (pad);
 550   GST_OBJECT_UNLOCK (pad);
 551
 552   return result;
 553 }
 554
 555 static gboolean
 556 gst_pad_activate_default (GstPad * pad)
 557 {
 558   return gst_pad_activate_push (pad, TRUE);
 559 }
 560
 561 static void
 562 pre_activate (GstPad * pad, GstActivateMode new_mode)
 563 {
 564   switch (new_mode) {
 565     case GST_ACTIVATE_PUSH:
 566     case GST_ACTIVATE_PULL:
 567       GST_OBJECT_LOCK (pad);
 568       GST_DEBUG_OBJECT (pad, "setting ACTIVATE_MODE %d, unset flushing",
 569           new_mode);
 570       GST_PAD_UNSET_FLUSHING (pad);
 571       GST_PAD_ACTIVATE_MODE (pad) = new_mode;
 572       GST_OBJECT_UNLOCK (pad);
 573       break;
 574     case GST_ACTIVATE_NONE:
 575       GST_OBJECT_LOCK (pad);
 576       GST_DEBUG_OBJECT (pad, "setting ACTIVATE_MODE NONE, set flushing",
 577           new_mode);
 578       GST_PAD_SET_FLUSHING (pad);
 579       /* unlock blocked pads so element can resume and stop */
 580       GST_PAD_BLOCK_SIGNAL (pad);
 581       GST_OBJECT_UNLOCK (pad);
 582       break;
 583   }
 584 }
 585
 586 static void
 587 post_activate (GstPad * pad, GstActivateMode new_mode)
 588 {
 589   switch (new_mode) {
 590     case GST_ACTIVATE_PUSH:
 591     case GST_ACTIVATE_PULL:
 592       /* nop */
 593       break;
 594     case GST_ACTIVATE_NONE:
 595       /* ensures that streaming stops */
 596       GST_PAD_STREAM_LOCK (pad);
 597       /* while we're at it set activation mode */
 598       GST_OBJECT_LOCK (pad);
 599       GST_DEBUG_OBJECT (pad, "setting ACTIVATE_MODE %d", new_mode);
 600       GST_PAD_ACTIVATE_MODE (pad) = new_mode;
 601       GST_OBJECT_UNLOCK (pad);
 602       GST_PAD_STREAM_UNLOCK (pad);
 603       break;
 604   }
 605 }
 606
 607 /**
 608  * gst_pad_set_active:
 609  * @pad: the #GstPad to activate or deactivate.
 610  * @active: whether or not the pad should be active.
 611  *
 612  * Activates or deactivates the given pad.
 613  * Normally called from within core state change functions.
 614  *
 615  * If @active, makes sure the pad is active. If it is already active, either in
 616  * push or pull mode, just return. Otherwise dispatches to the pad's activate
 617  * function to perform the actual activation.
 618  *
 619  * If not @active, checks the pad's current mode and calls
 620  * gst_pad_activate_push() or gst_pad_activate_pull(), as appropriate, with a
 621  * FALSE argument.
 622  *
 623  * Returns: #TRUE if the operation was successful.
 624  *
 625  * MT safe.
 626  */
 627 gboolean
 628 gst_pad_set_active (GstPad * pad, gboolean active)
 629 {
 630   GstActivateMode old;
 631   gboolean ret = FALSE;
 632
 633   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
 634
 635   GST_OBJECT_LOCK (pad);
 636   old = GST_PAD_ACTIVATE_MODE (pad);
 637   GST_OBJECT_UNLOCK (pad);
 638
 639   if (active) {
 640     switch (old) {
 641       case GST_ACTIVATE_PUSH:
 642       case GST_ACTIVATE_PULL:
 643         ret = TRUE;
 644         break;
 645       case GST_ACTIVATE_NONE:
 646         ret = (GST_PAD_ACTIVATEFUNC (pad)) (pad);
 647         break;
 648     }
 649   } else {
 650     switch (old) {
 651       case GST_ACTIVATE_PUSH:
 652         ret = gst_pad_activate_push (pad, FALSE);
 653         break;
 654       case GST_ACTIVATE_PULL:
 655         ret = gst_pad_activate_pull (pad, FALSE);
 656         break;
 657       case GST_ACTIVATE_NONE:
 658         ret = TRUE;
 659         break;
 660     }
 661   }
 662
 663   if (!active && !ret) {
 664     GST_OBJECT_LOCK (pad);
 665     g_critical ("Failed to deactivate pad %s:%s, very bad",
 666         GST_DEBUG_PAD_NAME (pad));
 667     GST_OBJECT_UNLOCK (pad);
 668   }
 669
 670   return ret;
 671 }
 672
 673 /**
 674  * gst_pad_activate_pull:
 675  * @pad: the #GstPad to activate or deactivate.
 676  * @active: whether or not the pad should be active.
 677  *
 678  * Activates or deactivates the given pad in pull mode via dispatching to the
 679  * pad's activatepullfunc. For use from within pad activation functions only.
 680  * When called on sink pads, will first proxy the call to the peer pad, which is
 681  * expected to activate its internally linked pads from within its activate_pull
 682  * function.
 683  *
 684  * If you don't know what this is, you probably don't want to call it.
 685  *
 686  * Returns: TRUE if the operation was successful.
 687  *
 688  * MT safe.
 689  */
 690 gboolean
 691 gst_pad_activate_pull (GstPad * pad, gboolean active)
 692 {
 693   GstActivateMode old, new;
 694   GstPad *peer;
 695
 696   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
 697
 698   GST_OBJECT_LOCK (pad);
 699   old = GST_PAD_ACTIVATE_MODE (pad);
 700   GST_OBJECT_UNLOCK (pad);
 701
 702   if (active) {
 703     switch (old) {
 704       case GST_ACTIVATE_PULL:
 705         goto was_ok;
 706       case GST_ACTIVATE_PUSH:
 707         /* pad was activate in the wrong direction, deactivate it
 708          * and reactivate it in pull mode */
 709         if (G_UNLIKELY (!gst_pad_activate_push (pad, FALSE)))
 710           goto deactivate_failed;
 711         /* fallthrough, pad is deactivated now. */
 712       case GST_ACTIVATE_NONE:
 713         break;
 714     }
 715   } else {
 716     switch (old) {
 717       case GST_ACTIVATE_NONE:
 718         goto was_ok;
 719       case GST_ACTIVATE_PUSH:
 720         /* pad was activated in the other direction, deactivate it
 721          * in push mode, this should not happen... */
 722         if (G_UNLIKELY (!gst_pad_activate_push (pad, FALSE)))
 723           goto deactivate_failed;
 724         /* everything is fine now */
 725         goto was_ok;
 726       case GST_ACTIVATE_PULL:
 727         break;
 728     }
 729   }
 730
 731   if (gst_pad_get_direction (pad) == GST_PAD_SINK) {
 732     if ((peer = gst_pad_get_peer (pad))) {
 733       if (G_UNLIKELY (!gst_pad_activate_pull (peer, active)))
 734         goto peer_failed;
 735       gst_object_unref (peer);
 736     }
 737   } else {
 738     if (G_UNLIKELY (GST_PAD_GETRANGEFUNC (pad) == NULL))
 739       goto failure;             /* Can't activate pull on a src without a
 740                                    getrange function */
 741   }
 742
 743   new = active ? GST_ACTIVATE_PULL : GST_ACTIVATE_NONE;
 744   pre_activate (pad, new);
 745
 746   if (GST_PAD_ACTIVATEPULLFUNC (pad)) {
 747     if (G_UNLIKELY (!GST_PAD_ACTIVATEPULLFUNC (pad) (pad, active)))
 748       goto failure;
 749   } else {
 750     /* can happen for sinks of passthrough elements */
 751   }
 752
 753   post_activate (pad, new);
 754
 755   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "%s in pull mode",
 756       active ? "activated" : "deactivated");
 757
 758   return TRUE;
 759
 760 was_ok:
 761   {
 762     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "already %s in pull mode",
 763         active ? "activated" : "deactivated");
 764     return TRUE;
 765   }
 766 deactivate_failed:
 767   {
 768     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
 769         "failed to %s pad (%s:%s) in switch to pull from mode %d",
 770         (active ? "activate" : "deactivate"), GST_DEBUG_PAD_NAME (pad), old);
 771     return FALSE;
 772   }
 773 peer_failed:
 774   {
 775     GST_OBJECT_LOCK (peer);
 776     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
 777         "activate_pull on peer (%s:%s) failed", GST_DEBUG_PAD_NAME (peer));
 778     GST_OBJECT_UNLOCK (peer);
 779     gst_object_unref (peer);
 780     return FALSE;
 781   }
 782 failure:
 783   {
 784     GST_CAT_INFO_OBJECT (GST_CAT_PADS, pad, "failed to %s in pull mode",
 785         active ? "activate" : "deactivate");
 786     pre_activate (pad, GST_ACTIVATE_NONE);
 787     post_activate (pad, GST_ACTIVATE_NONE);
 788     return FALSE;
 789   }
 790 }
 791
 792 /**
 793  * gst_pad_activate_push:
 794  * @pad: the #GstPad to activate or deactivate.
 795  * @active: whether the pad should be active or not.
 796  *
 797  * Activates or deactivates the given pad in push mode via dispatching to the
 798  * pad's activatepushfunc. For use from within pad activation functions only.
 799  *
 800  * If you don't know what this is, you probably don't want to call it.
 801  *
 802  * Returns: %TRUE if the operation was successful.
 803  *
 804  * MT safe.
 805  */
 806 gboolean
 807 gst_pad_activate_push (GstPad * pad, gboolean active)
 808 {
 809   GstActivateMode old, new;
 810
 811   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
 812   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "trying to set %s in push mode",
 813       active ? "activated" : "deactivated");
 814
 815   GST_OBJECT_LOCK (pad);
 816   old = GST_PAD_ACTIVATE_MODE (pad);
 817   GST_OBJECT_UNLOCK (pad);
 818
 819   if (active) {
 820     switch (old) {
 821       case GST_ACTIVATE_PUSH:
 822         goto was_ok;
 823       case GST_ACTIVATE_PULL:
 824         /* pad was activate in the wrong direction, deactivate it
 825          * an reactivate it in push mode */
 826         if (G_UNLIKELY (!gst_pad_activate_pull (pad, FALSE)))
 827           goto deactivate_failed;
 828         /* fallthrough, pad is deactivated now. */
 829       case GST_ACTIVATE_NONE:
 830         break;
 831     }
 832   } else {
 833     switch (old) {
 834       case GST_ACTIVATE_NONE:
 835         goto was_ok;
 836       case GST_ACTIVATE_PULL:
 837         /* pad was activated in the other direction, deactivate it
 838          * in pull mode, this should not happen... */
 839         if (G_UNLIKELY (!gst_pad_activate_pull (pad, FALSE)))
 840           goto deactivate_failed;
 841         /* everything is fine now */
 842         goto was_ok;
 843       case GST_ACTIVATE_PUSH:
 844         break;
 845     }
 846   }
 847
 848   new = active ? GST_ACTIVATE_PUSH : GST_ACTIVATE_NONE;
 849   pre_activate (pad, new);
 850
 851   if (GST_PAD_ACTIVATEPUSHFUNC (pad)) {
 852     if (G_UNLIKELY (!GST_PAD_ACTIVATEPUSHFUNC (pad) (pad, active))) {
 853       goto failure;
 854     }
 855   } else {
 856     /* quite ok, element relies on state change func to prepare itself */
 857   }
 858
 859   post_activate (pad, new);
 860
 861   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "%s in push mode",
 862       active ? "activated" : "deactivated");
 863   return TRUE;
 864
 865 was_ok:
 866   {
 867     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "already %s in push mode",
 868         active ? "activated" : "deactivated");
 869     return TRUE;
 870   }
 871 deactivate_failed:
 872   {
 873     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
 874         "failed to %s pad (%s:%s) in switch to push from mode %d",
 875         (active ? "activate" : "deactivate"), GST_DEBUG_PAD_NAME (pad), old);
 876     return FALSE;
 877   }
 878 failure:
 879   {
 880     GST_CAT_INFO_OBJECT (GST_CAT_PADS, pad, "failed to %s in push mode",
 881         active ? "activate" : "deactivate");
 882     pre_activate (pad, GST_ACTIVATE_NONE);
 883     post_activate (pad, GST_ACTIVATE_NONE);
 884     return FALSE;
 885   }
 886 }
 887
 888 /**
 889  * gst_pad_is_active:
 890  * @pad: the #GstPad to query
 891  *
 892  * Query if a pad is active
 893  *
 894  * Returns: TRUE if the pad is active.
 895  *
 896  * MT safe.
 897  */
 898 gboolean
 899 gst_pad_is_active (GstPad * pad)
 900 {
 901   gboolean result = FALSE;
 902
 903   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
 904
 905   GST_OBJECT_LOCK (pad);
 906   result = GST_PAD_MODE_ACTIVATE (GST_PAD_ACTIVATE_MODE (pad));
 907   GST_OBJECT_UNLOCK (pad);
 908
 909   return result;
 910 }
 911
 912 /**
 913  * gst_pad_set_blocked_async:
 914  * @pad: the #GstPad to block or unblock
 915  * @blocked: boolean indicating whether the pad should be blocked or unblocked
 916  * @callback: #GstPadBlockCallback that will be called when the
 917  *            operation succeeds
 918  * @user_data: user data passed to the callback
 919  *
 920  * Blocks or unblocks the dataflow on a pad. The provided callback
 921  * is called when the operation succeeds; this happens right before the next
 922  * attempt at pushing a buffer on the pad.
 923  *
 924  * This can take a while as the pad can only become blocked when real dataflow
 925  * is happening.
 926  * When the pipeline is stalled, for example in PAUSED, this can
 927  * take an indeterminate amount of time.
 928  * You can pass NULL as the callback to make this call block. Be careful with
 929  * this blocking call as it might not return for reasons stated above.
 930  *
 931  * Returns: TRUE if the pad could be blocked. This function can fail
 932  *   if wrong parameters were passed or the pad was already in the
 933  *   requested state.
 934  *
 935  * MT safe.
 936  */
 937 gboolean
 938 gst_pad_set_blocked_async (GstPad * pad, gboolean blocked,
 939     GstPadBlockCallback callback, gpointer user_data)
 940 {
 941   gboolean was_blocked = FALSE;
 942
 943   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
 944
 945   GST_OBJECT_LOCK (pad);
 946
 947   was_blocked = GST_PAD_IS_BLOCKED (pad);
 948
 949   if (G_UNLIKELY (was_blocked == blocked))
 950     goto had_right_state;
 951
 952   if (blocked) {
 953     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "blocking pad %s:%s",
 954         GST_DEBUG_PAD_NAME (pad));
 955
 956     GST_OBJECT_FLAG_SET (pad, GST_PAD_BLOCKED);
 957     pad->block_callback = callback;
 958     pad->block_data = user_data;
 959     if (!callback) {
 960       GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "waiting for block");
 961       GST_PAD_BLOCK_WAIT (pad);
 962       GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "blocked");
 963     }
 964   } else {
 965     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "unblocking pad %s:%s",
 966         GST_DEBUG_PAD_NAME (pad));
 967
 968     GST_OBJECT_FLAG_UNSET (pad, GST_PAD_BLOCKED);
 969
 970     pad->block_callback = callback;
 971     pad->block_data = user_data;
 972
 973     if (callback) {
 974       GST_PAD_BLOCK_SIGNAL (pad);
 975     } else {
 976       GST_PAD_BLOCK_SIGNAL (pad);
 977       GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "waiting for unblock");
 978       GST_PAD_BLOCK_WAIT (pad);
 979       GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "unblocked");
 980     }
 981   }
 982   GST_OBJECT_UNLOCK (pad);
 983
 984   return TRUE;
 985
 986 had_right_state:
 987   {
 988     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
 989         "pad %s:%s was in right state (%d)", GST_DEBUG_PAD_NAME (pad),
 990         was_blocked);
 991     GST_OBJECT_UNLOCK (pad);
 992
 993     return FALSE;
 994   }
 995 }
 996
 997 /**
 998  * gst_pad_set_blocked:
 999  * @pad: the #GstPad to block or unblock
1000  * @blocked: boolean indicating we should block or unblock
1001  *
1002  * Blocks or unblocks the dataflow on a pad. This function is
1003  * a shortcut for gst_pad_set_blocked_async() with a NULL
1004  * callback.
1005  *
1006  * Returns: TRUE if the pad could be blocked. This function can fail
1007  *   wrong parameters were passed or the pad was already in the
1008  *   requested state.
1009  *
1010  * MT safe.
1011  */
1012 gboolean
1013 gst_pad_set_blocked (GstPad * pad, gboolean blocked)
1014 {
1015   return gst_pad_set_blocked_async (pad, blocked, NULL, NULL);
1016 }
1017
1018 /**
1019  * gst_pad_is_blocked:
1020  * @pad: the #GstPad to query
1021  *
1022  * Checks if the pad is blocked or not. This function returns the
1023  * last requested state of the pad. It is not certain that the pad
1024  * is actually blocked at this point.
1025  *
1026  * Returns: TRUE if the pad is blocked.
1027  *
1028  * MT safe.
1029  */
1030 gboolean
1031 gst_pad_is_blocked (GstPad * pad)
1032 {
1033   gboolean result = FALSE;
1034
1035   g_return_val_if_fail (GST_IS_PAD (pad), result);
1036
1037   GST_OBJECT_LOCK (pad);
1038   result = GST_OBJECT_FLAG_IS_SET (pad, GST_PAD_BLOCKED);
1039   GST_OBJECT_UNLOCK (pad);
1040
1041   return result;
1042 }
1043
1044 /**
1045  * gst_pad_set_activate_function:
1046  * @pad: a #GstPad.
1047  * @activate: the #GstPadActivateFunction to set.
1048  *
1049  * Sets the given activate function for @pad. The activate function will
1050  * dispatch to gst_pad_activate_push() or gst_pad_activate_pull() to perform
1051  * the actual activation. Only makes sense to set on sink pads.
1052  *
1053  * Call this function if your sink pad can start a pull-based task.
1054  */
1055 void
1056 gst_pad_set_activate_function (GstPad * pad, GstPadActivateFunction activate)
1057 {
1058   g_return_if_fail (GST_IS_PAD (pad));
1059
1060   GST_PAD_ACTIVATEFUNC (pad) = activate;
1061   GST_CAT_DEBUG (GST_CAT_PADS, "activatefunc for %s:%s set to %s",
1062       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (activate));
1063 }
1064
1065 /**
1066  * gst_pad_set_activatepull_function:
1067  * @pad: a #GstPad.
1068  * @activatepull: the #GstPadActivateModeFunction to set.
1069  *
1070  * Sets the given activate_pull function for the pad. An activate_pull function
1071  * prepares the element and any upstream connections for pulling. See XXX
1072  * part-activation.txt for details.
1073  */
1074 void
1075 gst_pad_set_activatepull_function (GstPad * pad,
1076     GstPadActivateModeFunction activatepull)
1077 {
1078   g_return_if_fail (GST_IS_PAD (pad));
1079
1080   GST_PAD_ACTIVATEPULLFUNC (pad) = activatepull;
1081   GST_CAT_DEBUG (GST_CAT_PADS, "activatepullfunc for %s:%s set to %s",
1082       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (activatepull));
1083 }
1084
1085 /**
1086  * gst_pad_set_activatepush_function:
1087  * @pad: a #GstPad.
1088  * @activatepush: the #GstPadActivateModeFunction to set.
1089  *
1090  * Sets the given activate_push function for the pad. An activate_push function
1091  * prepares the element for pushing. See XXX part-activation.txt for details.
1092  */
1093 void
1094 gst_pad_set_activatepush_function (GstPad * pad,
1095     GstPadActivateModeFunction activatepush)
1096 {
1097   g_return_if_fail (GST_IS_PAD (pad));
1098
1099   GST_PAD_ACTIVATEPUSHFUNC (pad) = activatepush;
1100   GST_CAT_DEBUG (GST_CAT_PADS, "activatepushfunc for %s:%s set to %s",
1101       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (activatepush));
1102 }
1103
1104 /**
1105  * gst_pad_set_chain_function:
1106  * @pad: a sink #GstPad.
1107  * @chain: the #GstPadChainFunction to set.
1108  *
1109  * Sets the given chain function for the pad. The chain function is called to
1110  * process a #GstBuffer input buffer. see #GstPadChainFunction for more details.
1111  */
1112 void
1113 gst_pad_set_chain_function (GstPad * pad, GstPadChainFunction chain)
1114 {
1115   g_return_if_fail (GST_IS_PAD (pad));
1116   g_return_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SINK);
1117
1118   GST_PAD_CHAINFUNC (pad) = chain;
1119   GST_CAT_DEBUG (GST_CAT_PADS, "chainfunc for %s:%s set to %s",
1120       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (chain));
1121 }
1122
1123 /**
1124  * gst_pad_set_getrange_function:
1125  * @pad: a source #GstPad.
1126  * @get: the #GstPadGetRangeFunction to set.
1127  *
1128  * Sets the given getrange function for the pad. The getrange function is called to
1129  * produce a new #GstBuffer to start the processing pipeline. see
1130  * #GstPadGetRangeFunction for a description of the getrange function.
1131  */
1132 void
1133 gst_pad_set_getrange_function (GstPad * pad, GstPadGetRangeFunction get)
1134 {
1135   g_return_if_fail (GST_IS_PAD (pad));
1136   g_return_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SRC);
1137
1138   GST_PAD_GETRANGEFUNC (pad) = get;
1139
1140   GST_CAT_DEBUG (GST_CAT_PADS, "getrangefunc for %s:%s  set to %s",
1141       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (get));
1142 }
1143
1144 /**
1145  * gst_pad_set_checkgetrange_function:
1146  * @pad: a source #GstPad.
1147  * @check: the #GstPadCheckGetRangeFunction to set.
1148  *
1149  * Sets the given checkgetrange function for the pad. Implement this function on
1150  * a pad if you dynamically support getrange based scheduling on the pad.
1151  */
1152 void
1153 gst_pad_set_checkgetrange_function (GstPad * pad,
1154     GstPadCheckGetRangeFunction check)
1155 {
1156   g_return_if_fail (GST_IS_PAD (pad));
1157   g_return_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SRC);
1158
1159   GST_PAD_CHECKGETRANGEFUNC (pad) = check;
1160
1161   GST_CAT_DEBUG (GST_CAT_PADS, "checkgetrangefunc for %s:%s  set to %s",
1162       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (check));
1163 }
1164
1165 /**
1166  * gst_pad_set_event_function:
1167  * @pad: a source #GstPad.
1168  * @event: the #GstPadEventFunction to set.
1169  *
1170  * Sets the given event handler for the pad.
1171  */
1172 void
1173 gst_pad_set_event_function (GstPad * pad, GstPadEventFunction event)
1174 {
1175   g_return_if_fail (GST_IS_PAD (pad));
1176
1177   GST_PAD_EVENTFUNC (pad) = event;
1178
1179   GST_CAT_DEBUG (GST_CAT_PADS, "eventfunc for %s:%s  set to %s",
1180       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (event));
1181 }
1182
1183 /**
1184  * gst_pad_set_query_function:
1185  * @pad: a #GstPad of either direction.
1186  * @query: the #GstPadQueryFunction to set.
1187  *
1188  * Set the given query function for the pad.
1189  */
1190 void
1191 gst_pad_set_query_function (GstPad * pad, GstPadQueryFunction query)
1192 {
1193   g_return_if_fail (GST_IS_PAD (pad));
1194
1195   GST_PAD_QUERYFUNC (pad) = query;
1196
1197   GST_CAT_DEBUG (GST_CAT_PADS, "queryfunc for %s:%s  set to %s",
1198       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (query));
1199 }
1200
1201 /**
1202  * gst_pad_set_query_type_function:
1203  * @pad: a #GstPad of either direction.
1204  * @type_func: the #GstPadQueryTypeFunction to set.
1205  *
1206  * Set the given query type function for the pad.
1207  */
1208 void
1209 gst_pad_set_query_type_function (GstPad * pad,
1210     GstPadQueryTypeFunction type_func)
1211 {
1212   g_return_if_fail (GST_IS_PAD (pad));
1213
1214   GST_PAD_QUERYTYPEFUNC (pad) = type_func;
1215
1216   GST_CAT_DEBUG (GST_CAT_PADS, "querytypefunc for %s:%s  set to %s",
1217       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (type_func));
1218 }
1219
1220 /**
1221  * gst_pad_get_query_types:
1222  * @pad: a #GstPad.
1223  *
1224  * Get an array of supported queries that can be performed
1225  * on this pad.
1226  *
1227  * Returns: a zero-terminated array of #GstQueryType.
1228  */
1229 const GstQueryType *
1230 gst_pad_get_query_types (GstPad * pad)
1231 {
1232   GstPadQueryTypeFunction func;
1233
1234   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1235
1236   if (G_UNLIKELY ((func = GST_PAD_QUERYTYPEFUNC (pad)) == NULL))
1237     goto no_func;
1238
1239   return func (pad);
1240
1241 no_func:
1242   {
1243     return NULL;
1244   }
1245 }
1246
1247 static gboolean
1248 gst_pad_get_query_types_dispatcher (GstPad * pad, const GstQueryType ** data)
1249 {
1250   *data = gst_pad_get_query_types (pad);
1251
1252   return TRUE;
1253 }
1254
1255 /**
1256  * gst_pad_get_query_types_default:
1257  * @pad: a #GstPad.
1258  *
1259  * Invoke the default dispatcher for the query types on
1260  * the pad.
1261  *
1262  * Returns: an zero-terminated array of #GstQueryType, or NULL if none of the
1263  * internally-linked pads has a query types function.
1264  */
1265 const GstQueryType *
1266 gst_pad_get_query_types_default (GstPad * pad)
1267 {
1268   GstQueryType *result = NULL;
1269
1270   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1271
1272   gst_pad_dispatcher (pad, (GstPadDispatcherFunction)
1273       gst_pad_get_query_types_dispatcher, &result);
1274
1275   return result;
1276 }
1277
1278 /**
1279  * gst_pad_set_internal_link_function:
1280  * @pad: a #GstPad of either direction.
1281  * @intlink: the #GstPadIntLinkFunction to set.
1282  *
1283  * Sets the given internal link function for the pad.
1284  */
1285 void
1286 gst_pad_set_internal_link_function (GstPad * pad, GstPadIntLinkFunction intlink)
1287 {
1288   g_return_if_fail (GST_IS_PAD (pad));
1289
1290   GST_PAD_INTLINKFUNC (pad) = intlink;
1291   GST_CAT_DEBUG (GST_CAT_PADS, "internal link for %s:%s  set to %s",
1292       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (intlink));
1293 }
1294
1295 /**
1296  * gst_pad_set_link_function:
1297  * @pad: a #GstPad.
1298  * @link: the #GstPadLinkFunction to set.
1299  *
1300  * Sets the given link function for the pad. It will be called when
1301  * the pad is linked with another pad.
1302  *
1303  * The return value #GST_PAD_LINK_OK should be used when the connection can be
1304  * made.
1305  *
1306  * The return value #GST_PAD_LINK_REFUSED should be used when the connection
1307  * cannot be made for some reason.
1308  *
1309  * If @link is installed on a source pad, it should call the #GstPadLinkFunction
1310  * of the peer sink pad, if present.
1311  */
1312 void
1313 gst_pad_set_link_function (GstPad * pad, GstPadLinkFunction link)
1314 {
1315   g_return_if_fail (GST_IS_PAD (pad));
1316
1317   GST_PAD_LINKFUNC (pad) = link;
1318   GST_CAT_DEBUG (GST_CAT_PADS, "linkfunc for %s:%s set to %s",
1319       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (link));
1320 }
1321
1322 /**
1323  * gst_pad_set_unlink_function:
1324  * @pad: a #GstPad.
1325  * @unlink: the #GstPadUnlinkFunction to set.
1326  *
1327  * Sets the given unlink function for the pad. It will be called
1328  * when the pad is unlinked.
1329  */
1330 void
1331 gst_pad_set_unlink_function (GstPad * pad, GstPadUnlinkFunction unlink)
1332 {
1333   g_return_if_fail (GST_IS_PAD (pad));
1334
1335   GST_PAD_UNLINKFUNC (pad) = unlink;
1336   GST_CAT_DEBUG (GST_CAT_PADS, "unlinkfunc for %s:%s set to %s",
1337       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (unlink));
1338 }
1339
1340 /**
1341  * gst_pad_set_getcaps_function:
1342  * @pad: a #GstPad.
1343  * @getcaps: the #GstPadGetCapsFunction to set.
1344  *
1345  * Sets the given getcaps function for the pad. @getcaps should return the
1346  * allowable caps for a pad in the context of the element's state, its link to
1347  * other elements, and the devices or files it has opened. These caps must be a
1348  * subset of the pad template caps. In the NULL state with no links, @getcaps
1349  * should ideally return the same caps as the pad template. In rare
1350  * circumstances, an object property can affect the caps returned by @getcaps,
1351  * but this is discouraged.
1352  *
1353  * You do not need to call this function if @pad's allowed caps are always the
1354  * same as the pad template caps. This can only be true if the padtemplate
1355  * has fixed simple caps.
1356  *
1357  * For most filters, the caps returned by @getcaps is directly affected by the
1358  * allowed caps on other pads. For demuxers and decoders, the caps returned by
1359  * the srcpad's getcaps function is directly related to the stream data. Again,
1360  * @getcaps should return the most specific caps it reasonably can, since this
1361  * helps with autoplugging.
1362  *
1363  * Note that the return value from @getcaps is owned by the caller, so the caller
1364  * should unref the caps after usage.
1365  */
1366 void
1367 gst_pad_set_getcaps_function (GstPad * pad, GstPadGetCapsFunction getcaps)
1368 {
1369   g_return_if_fail (GST_IS_PAD (pad));
1370
1371   GST_PAD_GETCAPSFUNC (pad) = getcaps;
1372   GST_CAT_DEBUG (GST_CAT_PADS, "getcapsfunc for %s:%s set to %s",
1373       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (getcaps));
1374 }
1375
1376 /**
1377  * gst_pad_set_acceptcaps_function:
1378  * @pad: a #GstPad.
1379  * @acceptcaps: the #GstPadAcceptCapsFunction to set.
1380  *
1381  * Sets the given acceptcaps function for the pad.  The acceptcaps function
1382  * will be called to check if the pad can accept the given caps. Setting the
1383  * acceptcaps function to NULL restores the default behaviour of allowing
1384  * any caps that matches the caps from gst_pad_get_caps.
1385  */
1386 void
1387 gst_pad_set_acceptcaps_function (GstPad * pad,
1388     GstPadAcceptCapsFunction acceptcaps)
1389 {
1390   g_return_if_fail (GST_IS_PAD (pad));
1391
1392   GST_PAD_ACCEPTCAPSFUNC (pad) = acceptcaps;
1393   GST_CAT_DEBUG (GST_CAT_PADS, "acceptcapsfunc for %s:%s set to %s",
1394       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (acceptcaps));
1395 }
1396
1397 /**
1398  * gst_pad_set_fixatecaps_function:
1399  * @pad: a #GstPad.
1400  * @fixatecaps: the #GstPadFixateCapsFunction to set.
1401  *
1402  * Sets the given fixatecaps function for the pad.  The fixatecaps function
1403  * will be called whenever the default values for a GstCaps needs to be
1404  * filled in.
1405  */
1406 void
1407 gst_pad_set_fixatecaps_function (GstPad * pad,
1408     GstPadFixateCapsFunction fixatecaps)
1409 {
1410   g_return_if_fail (GST_IS_PAD (pad));
1411
1412   GST_PAD_FIXATECAPSFUNC (pad) = fixatecaps;
1413   GST_CAT_DEBUG (GST_CAT_PADS, "fixatecapsfunc for %s:%s set to %s",
1414       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (fixatecaps));
1415 }
1416
1417 /**
1418  * gst_pad_set_setcaps_function:
1419  * @pad: a #GstPad.
1420  * @setcaps: the #GstPadSetCapsFunction to set.
1421  *
1422  * Sets the given setcaps function for the pad.  The setcaps function
1423  * will be called whenever a buffer with a new media type is pushed or
1424  * pulled from the pad. The pad/element needs to update its internal
1425  * structures to process the new media type. If this new type is not
1426  * acceptable, the setcaps function should return FALSE.
1427  */
1428 void
1429 gst_pad_set_setcaps_function (GstPad * pad, GstPadSetCapsFunction setcaps)
1430 {
1431   g_return_if_fail (GST_IS_PAD (pad));
1432
1433   GST_PAD_SETCAPSFUNC (pad) = setcaps;
1434   GST_CAT_DEBUG (GST_CAT_PADS, "setcapsfunc for %s:%s set to %s",
1435       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (setcaps));
1436 }
1437
1438 /**
1439  * gst_pad_set_bufferalloc_function:
1440  * @pad: a sink #GstPad.
1441  * @bufalloc: the #GstPadBufferAllocFunction to set.
1442  *
1443  * Sets the given bufferalloc function for the pad. Note that the
1444  * bufferalloc function can only be set on sinkpads.
1445  */
1446 void
1447 gst_pad_set_bufferalloc_function (GstPad * pad,
1448     GstPadBufferAllocFunction bufalloc)
1449 {
1450   g_return_if_fail (GST_IS_PAD (pad));
1451   g_return_if_fail (GST_PAD_IS_SINK (pad));
1452
1453   GST_PAD_BUFFERALLOCFUNC (pad) = bufalloc;
1454   GST_CAT_DEBUG (GST_CAT_PADS, "bufferallocfunc for %s:%s set to %s",
1455       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (bufalloc));
1456 }
1457
1458 /**
1459  * gst_pad_unlink:
1460  * @srcpad: the source #GstPad to unlink.
1461  * @sinkpad: the sink #GstPad to unlink.
1462  *
1463  * Unlinks the source pad from the sink pad. Will emit the "unlinked" signal on
1464  * both pads.
1465  *
1466  * Returns: TRUE if the pads were unlinked. This function returns FALSE if
1467  * the pads were not linked together.
1468  *
1469  * MT safe.
1470  */
1471 gboolean
1472 gst_pad_unlink (GstPad * srcpad, GstPad * sinkpad)
1473 {
1474   g_return_val_if_fail (GST_IS_PAD (srcpad), FALSE);
1475   g_return_val_if_fail (GST_IS_PAD (sinkpad), FALSE);
1476
1477   GST_CAT_INFO (GST_CAT_ELEMENT_PADS, "unlinking %s:%s(%p) and %s:%s(%p)",
1478       GST_DEBUG_PAD_NAME (srcpad), srcpad,
1479       GST_DEBUG_PAD_NAME (sinkpad), sinkpad);
1480
1481   GST_OBJECT_LOCK (srcpad);
1482
1483   if (G_UNLIKELY (GST_PAD_DIRECTION (srcpad) != GST_PAD_SRC))
1484     goto not_srcpad;
1485
1486   GST_OBJECT_LOCK (sinkpad);
1487
1488   if (G_UNLIKELY (GST_PAD_DIRECTION (sinkpad) != GST_PAD_SINK))
1489     goto not_sinkpad;
1490
1491   if (G_UNLIKELY (GST_PAD_PEER (srcpad) != sinkpad))
1492     goto not_linked_together;
1493
1494   if (GST_PAD_UNLINKFUNC (srcpad)) {
1495     GST_PAD_UNLINKFUNC (srcpad) (srcpad);
1496   }
1497   if (GST_PAD_UNLINKFUNC (sinkpad)) {
1498     GST_PAD_UNLINKFUNC (sinkpad) (sinkpad);
1499   }
1500
1501   /* first clear peers */
1502   GST_PAD_PEER (srcpad) = NULL;
1503   GST_PAD_PEER (sinkpad) = NULL;
1504
1505   GST_OBJECT_UNLOCK (sinkpad);
1506   GST_OBJECT_UNLOCK (srcpad);
1507
1508   /* fire off a signal to each of the pads telling them
1509    * that they've been unlinked */
1510   g_signal_emit (G_OBJECT (srcpad), gst_pad_signals[PAD_UNLINKED], 0, sinkpad);
1511   g_signal_emit (G_OBJECT (sinkpad), gst_pad_signals[PAD_UNLINKED], 0, srcpad);
1512
1513   GST_CAT_INFO (GST_CAT_ELEMENT_PADS, "unlinked %s:%s and %s:%s",
1514       GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
1515
1516   return TRUE;
1517
1518 not_srcpad:
1519   {
1520     g_critical ("pad %s is not a source pad", GST_PAD_NAME (srcpad));
1521     GST_OBJECT_UNLOCK (srcpad);
1522     return FALSE;
1523   }
1524 not_sinkpad:
1525   {
1526     g_critical ("pad %s is not a sink pad", GST_PAD_NAME (sinkpad));
1527     GST_OBJECT_UNLOCK (sinkpad);
1528     GST_OBJECT_UNLOCK (srcpad);
1529     return FALSE;
1530   }
1531 not_linked_together:
1532   {
1533     /* we do not emit a warning in this case because unlinking cannot
1534      * be made MT safe.*/
1535     GST_OBJECT_UNLOCK (sinkpad);
1536     GST_OBJECT_UNLOCK (srcpad);
1537     return FALSE;
1538   }
1539 }
1540
1541 /**
1542  * gst_pad_is_linked:
1543  * @pad: pad to check
1544  *
1545  * Checks if a @pad is linked to another pad or not.
1546  *
1547  * Returns: TRUE if the pad is linked, FALSE otherwise.
1548  *
1549  * MT safe.
1550  */
1551 gboolean
1552 gst_pad_is_linked (GstPad * pad)
1553 {
1554   gboolean result;
1555
1556   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
1557
1558   GST_OBJECT_LOCK (pad);
1559   result = (GST_PAD_PEER (pad) != NULL);
1560   GST_OBJECT_UNLOCK (pad);
1561
1562   return result;
1563 }
1564
1565 /* get the caps from both pads and see if the intersection
1566  * is not empty.
1567  *
1568  * This function should be called with the pad LOCK on both
1569  * pads
1570  */
1571 static gboolean
1572 gst_pad_link_check_compatible_unlocked (GstPad * src, GstPad * sink)
1573 {
1574   GstCaps *srccaps;
1575   GstCaps *sinkcaps;
1576   GstCaps *icaps;
1577
1578   srccaps = gst_pad_get_caps_unlocked (src);
1579   sinkcaps = gst_pad_get_caps_unlocked (sink);
1580
1581   GST_CAT_DEBUG (GST_CAT_CAPS, "src caps %" GST_PTR_FORMAT, srccaps);
1582   GST_CAT_DEBUG (GST_CAT_CAPS, "sink caps %" GST_PTR_FORMAT, sinkcaps);
1583
1584   /* if we have caps on both pads we can check the intersection. If one
1585    * of the caps is NULL, we return TRUE. */
1586   if (srccaps == NULL || sinkcaps == NULL)
1587     goto done;
1588
1589   icaps = gst_caps_intersect (srccaps, sinkcaps);
1590   gst_caps_unref (srccaps);
1591   gst_caps_unref (sinkcaps);
1592
1593   if (icaps == NULL)
1594     goto was_null;
1595
1596   GST_CAT_DEBUG (GST_CAT_CAPS,
1597       "intersection caps %p %" GST_PTR_FORMAT, icaps, icaps);
1598
1599   if (gst_caps_is_empty (icaps))
1600     goto was_empty;
1601
1602   gst_caps_unref (icaps);
1603
1604 done:
1605   return TRUE;
1606
1607   /* incompatible cases */
1608 was_null:
1609   {
1610     GST_CAT_DEBUG (GST_CAT_CAPS, "intersection gave NULL");
1611     return FALSE;
1612   }
1613 was_empty:
1614   {
1615     GST_CAT_DEBUG (GST_CAT_CAPS, "intersection is EMPTY");
1616     gst_caps_unref (icaps);
1617     return FALSE;
1618   }
1619 }
1620
1621 /* check if the grandparents of both pads are the same.
1622  * This check is required so that we don't try to link
1623  * pads from elements in different bins without ghostpads.
1624  *
1625  * The LOCK should be held on both pads
1626  */
1627 static gboolean
1628 gst_pad_link_check_hierarchy (GstPad * src, GstPad * sink)
1629 {
1630   GstObject *psrc, *psink;
1631   gboolean res = TRUE;
1632
1633   psrc = GST_OBJECT_PARENT (src);
1634   psink = GST_OBJECT_PARENT (sink);
1635
1636   /* if one of the pads has no parent, we allow the link */
1637   if (psrc && psink) {
1638     /* if the parents are the same, we have a loop */
1639     if (psrc == psink) {
1640       GST_CAT_DEBUG (GST_CAT_CAPS, "pads have same parent %" GST_PTR_FORMAT,
1641           psrc);
1642       res = FALSE;
1643       goto done;
1644     }
1645     /* if they both have a parent, we check the grandparents */
1646     psrc = gst_object_get_parent (psrc);
1647     psink = gst_object_get_parent (psink);
1648
1649     if (psrc != psink) {
1650       /* if they have grandparents but they are not the same */
1651       GST_CAT_DEBUG (GST_CAT_CAPS,
1652           "pads have different grandparents %" GST_PTR_FORMAT " and %"
1653           GST_PTR_FORMAT, psrc, psink);
1654       res = FALSE;
1655     }
1656     if (psrc)
1657       gst_object_unref (psrc);
1658     if (psink)
1659       gst_object_unref (psink);
1660   }
1661 done:
1662   return res;
1663 }
1664
1665 /* FIXME leftover from an attempt at refactoring... */
1666 /* call with the two pads unlocked */
1667 static GstPadLinkReturn
1668 gst_pad_link_prepare (GstPad * srcpad, GstPad * sinkpad)
1669 {
1670   /* generic checks */
1671   g_return_val_if_fail (GST_IS_PAD (srcpad), GST_PAD_LINK_REFUSED);
1672   g_return_val_if_fail (GST_IS_PAD (sinkpad), GST_PAD_LINK_REFUSED);
1673
1674   GST_CAT_INFO (GST_CAT_PADS, "trying to link %s:%s and %s:%s",
1675       GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
1676
1677   GST_OBJECT_LOCK (srcpad);
1678
1679   if (G_UNLIKELY (GST_PAD_DIRECTION (srcpad) != GST_PAD_SRC))
1680     goto not_srcpad;
1681
1682   if (G_UNLIKELY (GST_PAD_PEER (srcpad) != NULL))
1683     goto src_was_linked;
1684
1685   GST_OBJECT_LOCK (sinkpad);
1686
1687   if (G_UNLIKELY (GST_PAD_DIRECTION (sinkpad) != GST_PAD_SINK))
1688     goto not_sinkpad;
1689
1690   if (G_UNLIKELY (GST_PAD_PEER (sinkpad) != NULL))
1691     goto sink_was_linked;
1692
1693   /* check hierarchy, pads can only be linked if the grandparents
1694    * are the same. */
1695   if (!gst_pad_link_check_hierarchy (srcpad, sinkpad))
1696     goto wrong_hierarchy;
1697
1698   /* check pad caps for non-empty intersection */
1699   if (!gst_pad_link_check_compatible_unlocked (srcpad, sinkpad))
1700     goto no_format;
1701
1702   /* FIXME check pad scheduling for non-empty intersection */
1703
1704   return GST_PAD_LINK_OK;
1705
1706 not_srcpad:
1707   {
1708     g_critical ("pad %s is not a source pad", GST_PAD_NAME (srcpad));
1709     GST_OBJECT_UNLOCK (srcpad);
1710     return GST_PAD_LINK_WRONG_DIRECTION;
1711   }
1712 src_was_linked:
1713   {
1714     GST_CAT_INFO (GST_CAT_PADS, "src %s:%s was already linked to %s:%s",
1715         GST_DEBUG_PAD_NAME (srcpad),
1716         GST_DEBUG_PAD_NAME (GST_PAD_PEER (srcpad)));
1717     /* we do not emit a warning in this case because unlinking cannot
1718      * be made MT safe.*/
1719     GST_OBJECT_UNLOCK (srcpad);
1720     return GST_PAD_LINK_WAS_LINKED;
1721   }
1722 not_sinkpad:
1723   {
1724     g_critical ("pad %s is not a sink pad", GST_PAD_NAME (sinkpad));
1725     GST_OBJECT_UNLOCK (sinkpad);
1726     GST_OBJECT_UNLOCK (srcpad);
1727     return GST_PAD_LINK_WRONG_DIRECTION;
1728   }
1729 sink_was_linked:
1730   {
1731     GST_CAT_INFO (GST_CAT_PADS, "sink %s:%s was already linked to %s:%s",
1732         GST_DEBUG_PAD_NAME (sinkpad),
1733         GST_DEBUG_PAD_NAME (GST_PAD_PEER (sinkpad)));
1734     /* we do not emit a warning in this case because unlinking cannot
1735      * be made MT safe.*/
1736     GST_OBJECT_UNLOCK (sinkpad);
1737     GST_OBJECT_UNLOCK (srcpad);
1738     return GST_PAD_LINK_WAS_LINKED;
1739   }
1740 wrong_hierarchy:
1741   {
1742     GST_CAT_INFO (GST_CAT_PADS, "pads have wrong hierarchy");
1743     GST_OBJECT_UNLOCK (sinkpad);
1744     GST_OBJECT_UNLOCK (srcpad);
1745     return GST_PAD_LINK_WRONG_HIERARCHY;
1746   }
1747 no_format:
1748   {
1749     GST_CAT_INFO (GST_CAT_PADS, "caps are incompatible");
1750     GST_OBJECT_UNLOCK (sinkpad);
1751     GST_OBJECT_UNLOCK (srcpad);
1752     return GST_PAD_LINK_NOFORMAT;
1753   }
1754 }
1755
1756 /**
1757  * gst_pad_link:
1758  * @srcpad: the source #GstPad to link.
1759  * @sinkpad: the sink #GstPad to link.
1760  *
1761  * Links the source pad and the sink pad.
1762  *
1763  * Returns: A result code indicating if the connection worked or
1764  *          what went wrong.
1765  *
1766  * MT Safe.
1767  */
1768 GstPadLinkReturn
1769 gst_pad_link (GstPad * srcpad, GstPad * sinkpad)
1770 {
1771   GstPadLinkReturn result;
1772
1773   /* prepare will also lock the two pads */
1774   result = gst_pad_link_prepare (srcpad, sinkpad);
1775
1776   if (result != GST_PAD_LINK_OK)
1777     goto prepare_failed;
1778
1779   /* must set peers before calling the link function */
1780   GST_PAD_PEER (srcpad) = sinkpad;
1781   GST_PAD_PEER (sinkpad) = srcpad;
1782
1783   GST_OBJECT_UNLOCK (sinkpad);
1784   GST_OBJECT_UNLOCK (srcpad);
1785
1786   /* FIXME released the locks here, concurrent thread might link
1787    * something else. */
1788   if (GST_PAD_LINKFUNC (srcpad)) {
1789     /* this one will call the peer link function */
1790     result = GST_PAD_LINKFUNC (srcpad) (srcpad, sinkpad);
1791   } else if (GST_PAD_LINKFUNC (sinkpad)) {
1792     /* if no source link function, we need to call the sink link
1793      * function ourselves. */
1794     result = GST_PAD_LINKFUNC (sinkpad) (sinkpad, srcpad);
1795   } else {
1796     result = GST_PAD_LINK_OK;
1797   }
1798
1799   GST_OBJECT_LOCK (srcpad);
1800   GST_OBJECT_LOCK (sinkpad);
1801
1802   if (result == GST_PAD_LINK_OK) {
1803     GST_OBJECT_UNLOCK (sinkpad);
1804     GST_OBJECT_UNLOCK (srcpad);
1805
1806     /* fire off a signal to each of the pads telling them
1807      * that they've been linked */
1808     g_signal_emit (G_OBJECT (srcpad), gst_pad_signals[PAD_LINKED], 0, sinkpad);
1809     g_signal_emit (G_OBJECT (sinkpad), gst_pad_signals[PAD_LINKED], 0, srcpad);
1810
1811     GST_CAT_INFO (GST_CAT_PADS, "linked %s:%s and %s:%s, successful",
1812         GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
1813   } else {
1814     GST_CAT_INFO (GST_CAT_PADS, "link between %s:%s and %s:%s failed",
1815         GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
1816
1817     GST_PAD_PEER (srcpad) = NULL;
1818     GST_PAD_PEER (sinkpad) = NULL;
1819
1820     GST_OBJECT_UNLOCK (sinkpad);
1821     GST_OBJECT_UNLOCK (srcpad);
1822   }
1823   return result;
1824
1825 prepare_failed:
1826   {
1827     return result;
1828   }
1829 }
1830
1831 static void
1832 gst_pad_set_pad_template (GstPad * pad, GstPadTemplate * templ)
1833 {
1834   GstPadTemplate **template_p;
1835
1836   /* this function would need checks if it weren't static */
1837
1838   GST_OBJECT_LOCK (pad);
1839   template_p = &pad->padtemplate;
1840   gst_object_replace ((GstObject **) template_p, (GstObject *) templ);
1841   GST_OBJECT_UNLOCK (pad);
1842
1843   if (templ)
1844     gst_pad_template_pad_created (templ, pad);
1845 }
1846
1847 /**
1848  * gst_pad_get_pad_template:
1849  * @pad: a #GstPad.
1850  *
1851  * Gets the template for @pad.
1852  *
1853  * Returns: the #GstPadTemplate from which this pad was instantiated, or %NULL
1854  * if this pad has no template.
1855  *
1856  * FIXME: currently returns an unrefcounted padtemplate.
1857  */
1858 GstPadTemplate *
1859 gst_pad_get_pad_template (GstPad * pad)
1860 {
1861   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1862
1863   return GST_PAD_PAD_TEMPLATE (pad);
1864 }
1865
1866
1867 /* should be called with the pad LOCK held */
1868 /* refs the caps, so caller is responsible for getting it unreffed */
1869 static GstCaps *
1870 gst_pad_get_caps_unlocked (GstPad * pad)
1871 {
1872   GstCaps *result = NULL;
1873
1874   GST_CAT_DEBUG (GST_CAT_CAPS, "get pad caps of %s:%s (%p)",
1875       GST_DEBUG_PAD_NAME (pad), pad);
1876
1877   if (GST_PAD_GETCAPSFUNC (pad)) {
1878     GST_CAT_DEBUG (GST_CAT_CAPS, "dispatching to pad getcaps function");
1879
1880     GST_OBJECT_FLAG_SET (pad, GST_PAD_IN_GETCAPS);
1881     GST_OBJECT_UNLOCK (pad);
1882     result = GST_PAD_GETCAPSFUNC (pad) (pad);
1883     GST_OBJECT_LOCK (pad);
1884     GST_OBJECT_FLAG_UNSET (pad, GST_PAD_IN_GETCAPS);
1885
1886     if (result == NULL) {
1887       g_critical ("pad %s:%s returned NULL caps from getcaps function",
1888           GST_DEBUG_PAD_NAME (pad));
1889     } else {
1890       GST_CAT_DEBUG (GST_CAT_CAPS,
1891           "pad getcaps %s:%s returned %" GST_PTR_FORMAT,
1892           GST_DEBUG_PAD_NAME (pad), result);
1893 #ifndef G_DISABLE_ASSERT
1894       /* check that the returned caps are a real subset of the template caps */
1895       if (GST_PAD_PAD_TEMPLATE (pad)) {
1896         const GstCaps *templ_caps =
1897             GST_PAD_TEMPLATE_CAPS (GST_PAD_PAD_TEMPLATE (pad));
1898         if (!gst_caps_is_subset (result, templ_caps)) {
1899           GstCaps *temp;
1900
1901           GST_CAT_ERROR_OBJECT (GST_CAT_CAPS, pad,
1902               "pad returned caps %" GST_PTR_FORMAT
1903               " which are not a real subset of its template caps %"
1904               GST_PTR_FORMAT, result, templ_caps);
1905           g_warning
1906               ("pad %s:%s returned caps that are not a real subset of its template caps",
1907               GST_DEBUG_PAD_NAME (pad));
1908           temp = gst_caps_intersect (templ_caps, result);
1909           gst_caps_unref (result);
1910           result = temp;
1911         }
1912       }
1913 #endif
1914       goto done;
1915     }
1916   }
1917   if (GST_PAD_PAD_TEMPLATE (pad)) {
1918     GstPadTemplate *templ = GST_PAD_PAD_TEMPLATE (pad);
1919
1920     result = GST_PAD_TEMPLATE_CAPS (templ);
1921     GST_CAT_DEBUG (GST_CAT_CAPS,
1922         "using pad template %p with caps %p %" GST_PTR_FORMAT, templ, result,
1923         result);
1924
1925     result = gst_caps_ref (result);
1926     goto done;
1927   }
1928   if (GST_PAD_CAPS (pad)) {
1929     result = GST_PAD_CAPS (pad);
1930
1931     GST_CAT_DEBUG (GST_CAT_CAPS,
1932         "using pad caps %p %" GST_PTR_FORMAT, result, result);
1933
1934     result = gst_caps_ref (result);
1935     goto done;
1936   }
1937
1938   GST_CAT_DEBUG (GST_CAT_CAPS, "pad has no caps");
1939   result = gst_caps_new_empty ();
1940
1941 done:
1942   return result;
1943 }
1944
1945 /**
1946  * gst_pad_get_caps:
1947  * @pad: a  #GstPad to get the capabilities of.
1948  *
1949  * Gets the capabilities this pad can produce or consume.
1950  * Note that this method doesn't necessarily return the caps set by
1951  * gst_pad_set_caps() - use #GST_PAD_CAPS for that instead.
1952  * gst_pad_get_caps returns all possible caps a pad can operate with, using
1953  * the pad's get_caps function;
1954  * this returns the pad template caps if not explicitly set.
1955  *
1956  * Returns: a newly allocated copy of the #GstCaps of this pad.
1957  *
1958  * MT safe.
1959  */
1960 GstCaps *
1961 gst_pad_get_caps (GstPad * pad)
1962 {
1963   GstCaps *result = NULL;
1964
1965   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1966
1967   GST_OBJECT_LOCK (pad);
1968
1969   GST_CAT_DEBUG (GST_CAT_CAPS, "get pad caps of %s:%s (%p)",
1970       GST_DEBUG_PAD_NAME (pad), pad);
1971
1972   result = gst_pad_get_caps_unlocked (pad);
1973   GST_OBJECT_UNLOCK (pad);
1974
1975   return result;
1976 }
1977
1978 /**
1979  * gst_pad_peer_get_caps:
1980  * @pad: a  #GstPad to get the peer capabilities of.
1981  *
1982  * Gets the capabilities of the peer connected to this pad.
1983  *
1984  * Returns: the #GstCaps of the peer pad. This function returns a new caps, so use
1985  * gst_caps_unref to get rid of it. this function returns NULL if there is no
1986  * peer pad.
1987  */
1988 GstCaps *
1989 gst_pad_peer_get_caps (GstPad * pad)
1990 {
1991   GstPad *peerpad;
1992   GstCaps *result = NULL;
1993
1994   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1995
1996   GST_OBJECT_LOCK (pad);
1997
1998   GST_CAT_DEBUG (GST_CAT_CAPS, "get peer caps of %s:%s (%p)",
1999       GST_DEBUG_PAD_NAME (pad), pad);
2000
2001   peerpad = GST_PAD_PEER (pad);
2002   if (G_UNLIKELY (peerpad == NULL))
2003     goto no_peer;
2004
2005   gst_object_ref (peerpad);
2006   GST_OBJECT_UNLOCK (pad);
2007
2008   result = gst_pad_get_caps (peerpad);
2009
2010   gst_object_unref (peerpad);
2011
2012   return result;
2013
2014 no_peer:
2015   {
2016     GST_OBJECT_UNLOCK (pad);
2017     return NULL;
2018   }
2019 }
2020
2021 static gboolean
2022 fixate_value (GValue * dest, const GValue * src)
2023 {
2024   if (G_VALUE_TYPE (src) == GST_TYPE_INT_RANGE) {
2025     g_value_init (dest, G_TYPE_INT);
2026     g_value_set_int (dest, gst_value_get_int_range_min (src));
2027   } else if (G_VALUE_TYPE (src) == GST_TYPE_DOUBLE_RANGE) {
2028     g_value_init (dest, G_TYPE_DOUBLE);
2029     g_value_set_double (dest, gst_value_get_double_range_min (src));
2030   } else if (G_VALUE_TYPE (src) == GST_TYPE_FRACTION_RANGE) {
2031     gst_value_init_and_copy (dest, gst_value_get_fraction_range_min (src));
2032   } else if (G_VALUE_TYPE (src) == GST_TYPE_LIST) {
2033     GValue temp = { 0 };
2034
2035     gst_value_init_and_copy (&temp, gst_value_list_get_value (src, 0));
2036     if (!fixate_value (dest, &temp))
2037       gst_value_init_and_copy (dest, &temp);
2038     g_value_unset (&temp);
2039   } else if (G_VALUE_TYPE (src) == GST_TYPE_ARRAY) {
2040     gboolean res = FALSE;
2041     guint n;
2042
2043     g_value_init (dest, GST_TYPE_ARRAY);
2044     for (n = 0; n < gst_value_array_get_size (src); n++) {
2045       GValue kid = { 0 };
2046       const GValue *orig_kid = gst_value_array_get_value (src, n);
2047
2048       if (!fixate_value (&kid, orig_kid))
2049         gst_value_init_and_copy (&kid, orig_kid);
2050       else
2051         res = TRUE;
2052       gst_value_array_append_value (dest, &kid);
2053       g_value_unset (&kid);
2054     }
2055
2056     if (!res)
2057       g_value_unset (dest);
2058
2059     return res;
2060   } else {
2061     return FALSE;
2062   }
2063
2064   return TRUE;
2065 }
2066
2067 static gboolean
2068 gst_pad_default_fixate (GQuark field_id, const GValue * value, gpointer data)
2069 {
2070   GstStructure *s = data;
2071   GValue v = { 0 };
2072
2073   if (fixate_value (&v, value)) {
2074     gst_structure_id_set_value (s, field_id, &v);
2075     g_value_unset (&v);
2076   }
2077
2078   return TRUE;
2079 }
2080
2081 /**
2082  * gst_pad_fixate_caps:
2083  * @pad: a  #GstPad to fixate
2084  * @caps: the  #GstCaps to fixate
2085  *
2086  * Fixate a caps on the given pad. Modifies the caps in place, so you should
2087  * make sure that the caps are actually writable (see gst_caps_make_writable()).
2088  */
2089 void
2090 gst_pad_fixate_caps (GstPad * pad, GstCaps * caps)
2091 {
2092   GstPadFixateCapsFunction fixatefunc;
2093   guint n;
2094
2095   g_return_if_fail (GST_IS_PAD (pad));
2096   g_return_if_fail (caps != NULL);
2097
2098   if (gst_caps_is_fixed (caps))
2099     return;
2100
2101   fixatefunc = GST_PAD_FIXATECAPSFUNC (pad);
2102   if (fixatefunc) {
2103     fixatefunc (pad, caps);
2104   }
2105
2106   /* default fixation */
2107   for (n = 0; n < gst_caps_get_size (caps); n++) {
2108     GstStructure *s = gst_caps_get_structure (caps, n);
2109
2110     gst_structure_foreach (s, gst_pad_default_fixate, s);
2111   }
2112 }
2113
2114 /* Default accept caps implementation just checks against
2115  * against the allowed caps for the pad */
2116 static gboolean
2117 gst_pad_acceptcaps_default (GstPad * pad, GstCaps * caps)
2118 {
2119   /* get the caps and see if it intersects to something
2120    * not empty */
2121   GstCaps *intersect;
2122   GstCaps *allowed;
2123   gboolean result = FALSE;
2124
2125   allowed = gst_pad_get_caps (pad);
2126   if (allowed) {
2127     intersect = gst_caps_intersect (allowed, caps);
2128
2129     result = !gst_caps_is_empty (intersect);
2130
2131     gst_caps_unref (allowed);
2132     gst_caps_unref (intersect);
2133   }
2134
2135   return result;
2136 }
2137
2138 /**
2139  * gst_pad_accept_caps:
2140  * @pad: a #GstPad to check
2141  * @caps: a #GstCaps to check on the pad
2142  *
2143  * Check if the given pad accepts the caps.
2144  *
2145  * Returns: TRUE if the pad can accept the caps.
2146  */
2147 gboolean
2148 gst_pad_accept_caps (GstPad * pad, GstCaps * caps)
2149 {
2150   gboolean result;
2151   GstPadAcceptCapsFunction acceptfunc;
2152   GstCaps *existing = NULL;
2153
2154   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2155
2156   /* any pad can be unnegotiated */
2157   if (caps == NULL)
2158     return TRUE;
2159
2160   GST_OBJECT_LOCK (pad);
2161   acceptfunc = GST_PAD_ACCEPTCAPSFUNC (pad);
2162   if (GST_PAD_CAPS (pad) != NULL)
2163     existing = gst_caps_ref (GST_PAD_CAPS (pad));
2164
2165   GST_CAT_DEBUG (GST_CAT_CAPS, "pad accept caps of %s:%s (%p)",
2166       GST_DEBUG_PAD_NAME (pad), pad);
2167   GST_OBJECT_UNLOCK (pad);
2168
2169   /* The current caps on a pad are trivially acceptable */
2170   if (existing) {
2171     if (caps == existing || gst_caps_is_equal (caps, existing))
2172       goto is_same_caps;
2173     gst_caps_unref (existing);
2174   }
2175
2176   if (G_LIKELY (acceptfunc)) {
2177     /* we can call the function */
2178     result = acceptfunc (pad, caps);
2179   } else {
2180     /* Only null if the element explicitly unset it */
2181     result = gst_pad_acceptcaps_default (pad, caps);
2182   }
2183   return result;
2184
2185 is_same_caps:
2186   gst_caps_unref (existing);
2187   return TRUE;
2188 }
2189
2190 /**
2191  * gst_pad_peer_accept_caps:
2192  * @pad: a  #GstPad to check
2193  * @caps: a #GstCaps to check on the pad
2194  *
2195  * Check if the given pad accepts the caps.
2196  *
2197  * Returns: TRUE if the pad can accept the caps.
2198  */
2199 gboolean
2200 gst_pad_peer_accept_caps (GstPad * pad, GstCaps * caps)
2201 {
2202   GstPad *peerpad;
2203   gboolean result;
2204
2205   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2206
2207   GST_OBJECT_LOCK (pad);
2208
2209   GST_CAT_DEBUG (GST_CAT_CAPS, "peer accept caps of %s:%s (%p)",
2210       GST_DEBUG_PAD_NAME (pad), pad);
2211
2212   peerpad = GST_PAD_PEER (pad);
2213   if (G_UNLIKELY (peerpad == NULL))
2214     goto no_peer;
2215
2216   result = gst_pad_accept_caps (peerpad, caps);
2217   GST_OBJECT_UNLOCK (pad);
2218
2219   return result;
2220
2221 no_peer:
2222   {
2223     GST_OBJECT_UNLOCK (pad);
2224     return TRUE;
2225   }
2226 }
2227
2228 /**
2229  * gst_pad_set_caps:
2230  * @pad: a  #GstPad to set the capabilities of.
2231  * @caps: a #GstCaps to set.
2232  *
2233  * Sets the capabilities of this pad. The caps must be fixed. Any previous
2234  * caps on the pad will be unreffed. This function refs the caps so you should
2235  * unref if as soon as you don't need it anymore.
2236  * It is possible to set NULL caps, which will make the pad unnegotiated
2237  * again.
2238  *
2239  * Returns: TRUE if the caps could be set. FALSE if the caps were not fixed
2240  * or bad parameters were provided to this function.
2241  *
2242  * MT safe.
2243  */
2244 gboolean
2245 gst_pad_set_caps (GstPad * pad, GstCaps * caps)
2246 {
2247   GstPadSetCapsFunction setcaps;
2248   GstCaps *existing;
2249
2250   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2251   g_return_val_if_fail (caps == NULL || gst_caps_is_fixed (caps), FALSE);
2252
2253   GST_OBJECT_LOCK (pad);
2254   setcaps = GST_PAD_SETCAPSFUNC (pad);
2255
2256   existing = GST_PAD_CAPS (pad);
2257   if (existing == caps) {
2258     GST_OBJECT_UNLOCK (pad);
2259     return TRUE;
2260   }
2261
2262   if (gst_caps_is_equal (caps, existing))
2263     goto setting_same_caps;
2264
2265   /* call setcaps function to configure the pad only if the
2266    * caps is not NULL */
2267   if (setcaps != NULL && caps) {
2268     if (!GST_PAD_IS_IN_SETCAPS (pad)) {
2269       GST_OBJECT_FLAG_SET (pad, GST_PAD_IN_SETCAPS);
2270       GST_OBJECT_UNLOCK (pad);
2271       if (!setcaps (pad, caps))
2272         goto could_not_set;
2273       GST_OBJECT_LOCK (pad);
2274       GST_OBJECT_FLAG_UNSET (pad, GST_PAD_IN_SETCAPS);
2275     } else {
2276       GST_CAT_DEBUG (GST_CAT_CAPS, "pad %s:%s was dispatching",
2277           GST_DEBUG_PAD_NAME (pad));
2278     }
2279   }
2280
2281   gst_caps_replace (&GST_PAD_CAPS (pad), caps);
2282   GST_CAT_DEBUG (GST_CAT_CAPS, "%s:%s caps %" GST_PTR_FORMAT,
2283       GST_DEBUG_PAD_NAME (pad), caps);
2284   GST_OBJECT_UNLOCK (pad);
2285
2286   g_object_notify (G_OBJECT (pad), "caps");
2287
2288   return TRUE;
2289
2290 setting_same_caps:
2291   {
2292     gst_caps_replace (&GST_PAD_CAPS (pad), caps);
2293     GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2294         "caps %" GST_PTR_FORMAT " same as existing, updating ptr only", caps);
2295     GST_OBJECT_UNLOCK (pad);
2296
2297     return TRUE;
2298   }
2299 /* errors */
2300 could_not_set:
2301   {
2302     GST_OBJECT_LOCK (pad);
2303     GST_OBJECT_FLAG_UNSET (pad, GST_PAD_IN_SETCAPS);
2304     GST_CAT_DEBUG (GST_CAT_CAPS,
2305         "pad %s:%s, caps %" GST_PTR_FORMAT " could not be set",
2306         GST_DEBUG_PAD_NAME (pad), caps);
2307     GST_OBJECT_UNLOCK (pad);
2308
2309     return FALSE;
2310   }
2311 }
2312
2313 static gboolean
2314 gst_pad_configure_sink (GstPad * pad, GstCaps * caps)
2315 {
2316   GstPadSetCapsFunction setcaps;
2317   gboolean res;
2318
2319   setcaps = GST_PAD_SETCAPSFUNC (pad);
2320
2321   /* See if pad accepts the caps - only needed if
2322    * no setcaps function */
2323   if (setcaps == NULL)
2324     if (!gst_pad_accept_caps (pad, caps))
2325       goto not_accepted;
2326
2327   /* set caps on pad if call succeeds */
2328   res = gst_pad_set_caps (pad, caps);
2329   /* no need to unref the caps here, set_caps takes a ref and
2330    * our ref goes away when we leave this function. */
2331
2332   return res;
2333
2334 not_accepted:
2335   {
2336     GST_CAT_DEBUG (GST_CAT_CAPS, "caps %" GST_PTR_FORMAT " not accepted", caps);
2337     return FALSE;
2338   }
2339 }
2340
2341 /* returns TRUE if the src pad could be configured to accept the given caps */
2342 static gboolean
2343 gst_pad_configure_src (GstPad * pad, GstCaps * caps, gboolean dosetcaps)
2344 {
2345   GstPadSetCapsFunction setcaps;
2346   gboolean res;
2347
2348   setcaps = GST_PAD_SETCAPSFUNC (pad);
2349
2350   /* See if pad accepts the caps - only needed if
2351    * no setcaps function */
2352   if (setcaps == NULL)
2353     if (!gst_pad_accept_caps (pad, caps))
2354       goto not_accepted;
2355
2356   if (dosetcaps)
2357     res = gst_pad_set_caps (pad, caps);
2358   else
2359     res = TRUE;
2360
2361   return res;
2362
2363 not_accepted:
2364   {
2365     GST_CAT_DEBUG (GST_CAT_CAPS, "caps %" GST_PTR_FORMAT " not accepted", caps);
2366     return FALSE;
2367   }
2368 }
2369
2370 /**
2371  * gst_pad_get_pad_template_caps:
2372  * @pad: a #GstPad to get the template capabilities from.
2373  *
2374  * Gets the capabilities for @pad's template.
2375  *
2376  * Returns: the #GstCaps of this pad template. If you intend to keep a reference
2377  * on the caps, make a copy (see gst_caps_copy ()).
2378  */
2379 const GstCaps *
2380 gst_pad_get_pad_template_caps (GstPad * pad)
2381 {
2382   static GstStaticCaps anycaps = GST_STATIC_CAPS ("ANY");
2383
2384   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2385
2386   if (GST_PAD_PAD_TEMPLATE (pad))
2387     return GST_PAD_TEMPLATE_CAPS (GST_PAD_PAD_TEMPLATE (pad));
2388
2389   return gst_static_caps_get (&anycaps);
2390 }
2391
2392
2393 /**
2394  * gst_pad_get_peer:
2395  * @pad: a #GstPad to get the peer of.
2396  *
2397  * Gets the peer of @pad. This function refs the peer pad so
2398  * you need to unref it after use.
2399  *
2400  * Returns: the peer #GstPad. Unref after usage.
2401  *
2402  * MT safe.
2403  */
2404 GstPad *
2405 gst_pad_get_peer (GstPad * pad)
2406 {
2407   GstPad *result;
2408
2409   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2410
2411   GST_OBJECT_LOCK (pad);
2412   result = GST_PAD_PEER (pad);
2413   if (result)
2414     gst_object_ref (result);
2415   GST_OBJECT_UNLOCK (pad);
2416
2417   return result;
2418 }
2419
2420 /**
2421  * gst_pad_get_allowed_caps:
2422  * @srcpad: a #GstPad, it must a a source pad.
2423  *
2424  * Gets the capabilities of the allowed media types that can flow through
2425  * @srcpad and its peer. The pad must be a source pad.
2426  * The caller must free the resulting caps.
2427  *
2428  * Returns: the allowed #GstCaps of the pad link.  Free the caps when
2429  * you no longer need it. This function returns NULL when the @srcpad has no
2430  * peer.
2431  *
2432  * MT safe.
2433  */
2434 GstCaps *
2435 gst_pad_get_allowed_caps (GstPad * srcpad)
2436 {
2437   GstCaps *mycaps;
2438   GstCaps *caps;
2439   GstCaps *peercaps;
2440   GstPad *peer;
2441
2442   g_return_val_if_fail (GST_IS_PAD (srcpad), NULL);
2443   g_return_val_if_fail (GST_PAD_IS_SRC (srcpad), NULL);
2444
2445   GST_OBJECT_LOCK (srcpad);
2446
2447   peer = GST_PAD_PEER (srcpad);
2448   if (G_UNLIKELY (peer == NULL))
2449     goto no_peer;
2450
2451   GST_CAT_DEBUG (GST_CAT_PROPERTIES, "%s:%s: getting allowed caps",
2452       GST_DEBUG_PAD_NAME (srcpad));
2453
2454   gst_object_ref (peer);
2455   GST_OBJECT_UNLOCK (srcpad);
2456   mycaps = gst_pad_get_caps (srcpad);
2457
2458   peercaps = gst_pad_get_caps (peer);
2459   gst_object_unref (peer);
2460
2461   caps = gst_caps_intersect (mycaps, peercaps);
2462   gst_caps_unref (peercaps);
2463   gst_caps_unref (mycaps);
2464
2465   GST_CAT_DEBUG (GST_CAT_CAPS, "allowed caps %" GST_PTR_FORMAT, caps);
2466
2467   return caps;
2468
2469 no_peer:
2470   {
2471     GST_CAT_DEBUG (GST_CAT_PROPERTIES, "%s:%s: no peer",
2472         GST_DEBUG_PAD_NAME (srcpad));
2473     GST_OBJECT_UNLOCK (srcpad);
2474
2475     return NULL;
2476   }
2477 }
2478
2479 /**
2480  * gst_pad_get_negotiated_caps:
2481  * @pad: a #GstPad.
2482  *
2483  * Gets the capabilities of the media type that currently flows through @pad
2484  * and its peer.
2485  *
2486  * This function can be used on both src and sinkpads. Note that srcpads are
2487  * always negotiated before sinkpads so it is possible that the negotiated caps
2488  * on the srcpad do not match the negotiated caps of the peer.
2489  *
2490  * Returns: the negotiated #GstCaps of the pad link.  Free the caps when
2491  * you no longer need it. This function returns NULL when the @pad has no
2492  * peer or is not negotiated yet.
2493  *
2494  * MT safe.
2495  */
2496 GstCaps *
2497 gst_pad_get_negotiated_caps (GstPad * pad)
2498 {
2499   GstCaps *caps;
2500   GstPad *peer;
2501
2502   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2503
2504   GST_OBJECT_LOCK (pad);
2505
2506   if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
2507     goto no_peer;
2508
2509   GST_CAT_DEBUG (GST_CAT_PROPERTIES, "%s:%s: getting negotiated caps",
2510       GST_DEBUG_PAD_NAME (pad));
2511
2512   caps = GST_PAD_CAPS (pad);
2513   if (caps)
2514     gst_caps_ref (caps);
2515   GST_OBJECT_UNLOCK (pad);
2516
2517   GST_CAT_DEBUG (GST_CAT_CAPS, "negotiated caps %" GST_PTR_FORMAT, caps);
2518
2519   return caps;
2520
2521 no_peer:
2522   {
2523     GST_CAT_DEBUG (GST_CAT_PROPERTIES, "%s:%s: no peer",
2524         GST_DEBUG_PAD_NAME (pad));
2525     GST_OBJECT_UNLOCK (pad);
2526
2527     return NULL;
2528   }
2529 }
2530
2531 static GstFlowReturn
2532 gst_pad_alloc_buffer_full (GstPad * pad, guint64 offset, gint size,
2533     GstCaps * caps, GstBuffer ** buf, gboolean setcaps)
2534 {
2535   GstPad *peer;
2536   GstFlowReturn ret;
2537   GstPadBufferAllocFunction bufferallocfunc;
2538   gboolean caps_changed;
2539
2540   g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
2541   g_return_val_if_fail (GST_PAD_IS_SRC (pad), GST_FLOW_ERROR);
2542   g_return_val_if_fail (buf != NULL, GST_FLOW_ERROR);
2543
2544   GST_OBJECT_LOCK (pad);
2545   while (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad)))
2546     if ((ret = handle_pad_block (pad)) != GST_FLOW_OK)
2547       goto flushed;
2548
2549   if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
2550     goto no_peer;
2551
2552   gst_object_ref (peer);
2553   GST_OBJECT_UNLOCK (pad);
2554
2555   if (G_LIKELY ((bufferallocfunc = peer->bufferallocfunc) == NULL))
2556     goto fallback;
2557
2558   GST_OBJECT_LOCK (peer);
2559   /* when the peer is flushing we cannot give a buffer */
2560   if (G_UNLIKELY (GST_PAD_IS_FLUSHING (peer)))
2561     goto flushing;
2562
2563   if (offset == GST_BUFFER_OFFSET_NONE) {
2564     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
2565         "calling bufferallocfunc &%s (@%p) of peer pad %s:%s for size %d offset NONE",
2566         GST_DEBUG_FUNCPTR_NAME (bufferallocfunc),
2567         &bufferallocfunc, GST_DEBUG_PAD_NAME (peer), size);
2568   } else {
2569     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
2570         "calling bufferallocfunc &%s (@%p) of peer pad %s:%s for size %d offset %"
2571         G_GUINT64_FORMAT, GST_DEBUG_FUNCPTR_NAME (bufferallocfunc),
2572         &bufferallocfunc, GST_DEBUG_PAD_NAME (peer), size, offset);
2573   }
2574   GST_OBJECT_UNLOCK (peer);
2575
2576   ret = bufferallocfunc (peer, offset, size, caps, buf);
2577
2578   if (G_UNLIKELY (ret != GST_FLOW_OK))
2579     goto peer_error;
2580   if (G_UNLIKELY (*buf == NULL))
2581     goto fallback;
2582
2583   /* If the buffer alloc function didn't set up the caps like it should,
2584    * do it for it */
2585   if (caps && (GST_BUFFER_CAPS (*buf) == NULL)) {
2586     GST_WARNING ("Buffer allocation function for pad % " GST_PTR_FORMAT
2587         " did not set up caps. Setting", peer);
2588
2589     gst_buffer_set_caps (*buf, caps);
2590   }
2591
2592 do_caps:
2593   gst_object_unref (peer);
2594
2595   /* FIXME, move capnego this into a base class? */
2596   caps = GST_BUFFER_CAPS (*buf);
2597   caps_changed = caps && caps != GST_PAD_CAPS (pad);
2598   /* we got a new datatype on the pad, see if it can handle it */
2599   if (G_UNLIKELY (caps_changed)) {
2600     GST_DEBUG_OBJECT (pad, "caps changed to %" GST_PTR_FORMAT, caps);
2601     if (G_UNLIKELY (!gst_pad_configure_src (pad, caps, setcaps)))
2602       goto not_negotiated;
2603   }
2604   return ret;
2605
2606 flushed:
2607   {
2608     GST_CAT_DEBUG (GST_CAT_PADS, "%s:%s pad block stopped by flush",
2609         GST_DEBUG_PAD_NAME (pad));
2610     GST_OBJECT_UNLOCK (pad);
2611     return ret;
2612   }
2613 no_peer:
2614   {
2615     /* pad has no peer */
2616     GST_CAT_DEBUG (GST_CAT_PADS,
2617         "%s:%s called bufferallocfunc but had no peer",
2618         GST_DEBUG_PAD_NAME (pad));
2619     GST_OBJECT_UNLOCK (pad);
2620     return GST_FLOW_NOT_LINKED;
2621   }
2622 flushing:
2623   {
2624     /* peer was flushing */
2625     GST_OBJECT_UNLOCK (peer);
2626     gst_object_unref (peer);
2627     GST_CAT_DEBUG (GST_CAT_PADS,
2628         "%s:%s called bufferallocfunc but peer was flushing",
2629         GST_DEBUG_PAD_NAME (pad));
2630     return GST_FLOW_WRONG_STATE;
2631   }
2632   /* fallback case, allocate a buffer of our own, add pad caps. */
2633 fallback:
2634   {
2635     GST_CAT_DEBUG (GST_CAT_PADS,
2636         "%s:%s fallback buffer alloc", GST_DEBUG_PAD_NAME (pad));
2637     *buf = gst_buffer_new_and_alloc (size);
2638     GST_BUFFER_OFFSET (*buf) = offset;
2639     gst_buffer_set_caps (*buf, caps);
2640
2641     ret = GST_FLOW_OK;
2642
2643     goto do_caps;
2644   }
2645 not_negotiated:
2646   {
2647     gst_buffer_unref (*buf);
2648     *buf = NULL;
2649     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
2650         "alloc function returned unacceptable buffer");
2651     return GST_FLOW_NOT_NEGOTIATED;
2652   }
2653 peer_error:
2654   {
2655     gst_object_unref (peer);
2656     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
2657         "alloc function returned error %s", gst_flow_get_name (ret));
2658     return ret;
2659   }
2660 }
2661
2662 /**
2663  * gst_pad_alloc_buffer:
2664  * @pad: a source #GstPad
2665  * @offset: the offset of the new buffer in the stream
2666  * @size: the size of the new buffer
2667  * @caps: the caps of the new buffer
2668  * @buf: a newly allocated buffer
2669  *
2670  * Allocates a new, empty buffer optimized to push to pad @pad.  This
2671  * function only works if @pad is a source pad and has a peer.
2672  *
2673  * A new, empty #GstBuffer will be put in the @buf argument.
2674  * You need to check the caps of the buffer after performing this
2675  * function and renegotiate to the format if needed.
2676  *
2677  * Returns: a result code indicating success of the operation. Any
2678  * result code other than #GST_FLOW_OK is an error and @buf should
2679  * not be used.
2680  * An error can occur if the pad is not connected or when the downstream
2681  * peer elements cannot provide an acceptable buffer.
2682  *
2683  * MT safe.
2684  */
2685 GstFlowReturn
2686 gst_pad_alloc_buffer (GstPad * pad, guint64 offset, gint size, GstCaps * caps,
2687     GstBuffer ** buf)
2688 {
2689   return gst_pad_alloc_buffer_full (pad, offset, size, caps, buf, FALSE);
2690 }
2691
2692 /**
2693  * gst_pad_alloc_buffer_and_set_caps:
2694  * @pad: a source #GstPad
2695  * @offset: the offset of the new buffer in the stream
2696  * @size: the size of the new buffer
2697  * @caps: the caps of the new buffer
2698  * @buf: a newly allocated buffer
2699  *
2700  * In addition to the function gst_pad_alloc_buffer(), this function
2701  * automatically calls gst_pad_set_caps() when the caps of the
2702  * newly allocated buffer are different from the @pad caps.
2703  *
2704  * Returns: a result code indicating success of the operation. Any
2705  * result code other than #GST_FLOW_OK is an error and @buf should
2706  * not be used.
2707  * An error can occur if the pad is not connected or when the downstream
2708  * peer elements cannot provide an acceptable buffer.
2709  *
2710  * MT safe.
2711  */
2712 GstFlowReturn
2713 gst_pad_alloc_buffer_and_set_caps (GstPad * pad, guint64 offset, gint size,
2714     GstCaps * caps, GstBuffer ** buf)
2715 {
2716   return gst_pad_alloc_buffer_full (pad, offset, size, caps, buf, TRUE);
2717 }
2718
2719 /**
2720  * gst_pad_get_internal_links_default:
2721  * @pad: the #GstPad to get the internal links of.
2722  *
2723  * Gets a list of pads to which the given pad is linked to
2724  * inside of the parent element.
2725  * This is the default handler, and thus returns a list of all of the
2726  * pads inside the parent element with opposite direction.
2727  * The caller must free this list after use.
2728  *
2729  * Returns: a newly allocated #GList of pads, or NULL if the pad has no parent.
2730  *
2731  * Not MT safe.
2732  */
2733 GList *
2734 gst_pad_get_internal_links_default (GstPad * pad)
2735 {
2736   GList *res = NULL;
2737   GstElement *parent;
2738   GList *parent_pads;
2739   GstPadDirection direction;
2740
2741   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2742
2743   direction = pad->direction;
2744
2745   parent = GST_PAD_PARENT (pad);
2746   if (!parent)
2747     return NULL;
2748
2749   parent_pads = parent->pads;
2750
2751   while (parent_pads) {
2752     GstPad *parent_pad = GST_PAD_CAST (parent_pads->data);
2753
2754     if (parent_pad->direction != direction) {
2755       res = g_list_prepend (res, parent_pad);
2756     }
2757
2758     parent_pads = g_list_next (parent_pads);
2759   }
2760
2761   return res;
2762 }
2763
2764 /**
2765  * gst_pad_get_internal_links:
2766  * @pad: the #GstPad to get the internal links of.
2767  *
2768  * Gets a list of pads to which the given pad is linked to
2769  * inside of the parent element.
2770  * The caller must free this list after use.
2771  *
2772  * Returns: a newly allocated #GList of pads.
2773  *
2774  * Not MT safe.
2775  */
2776 GList *
2777 gst_pad_get_internal_links (GstPad * pad)
2778 {
2779   GList *res = NULL;
2780
2781   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2782
2783   if (GST_PAD_INTLINKFUNC (pad))
2784     res = GST_PAD_INTLINKFUNC (pad) (pad);
2785
2786   return res;
2787 }
2788
2789
2790 static gboolean
2791 gst_pad_event_default_dispatch (GstPad * pad, GstEvent * event)
2792 {
2793   GList *orig, *pads;
2794   gboolean result;
2795
2796   GST_INFO_OBJECT (pad, "Sending event %p to all internally linked pads",
2797       event);
2798
2799   result = (GST_PAD_DIRECTION (pad) == GST_PAD_SINK);
2800
2801   orig = pads = gst_pad_get_internal_links (pad);
2802
2803   while (pads) {
2804     GstPad *eventpad = GST_PAD_CAST (pads->data);
2805
2806     pads = g_list_next (pads);
2807
2808     if (GST_PAD_DIRECTION (eventpad) == GST_PAD_SRC) {
2809       /* for each pad we send to, we should ref the event; it's up
2810        * to downstream to unref again when handled. */
2811       GST_LOG_OBJECT (pad, "Reffing and sending event %p (%s) to %s:%s",
2812           event, GST_EVENT_TYPE_NAME (event), GST_DEBUG_PAD_NAME (eventpad));
2813       gst_event_ref (event);
2814       gst_pad_push_event (eventpad, event);
2815     } else {
2816       /* we only send the event on one pad, multi-sinkpad elements
2817        * should implement a handler */
2818       GST_LOG_OBJECT (pad, "sending event %p (%s) to one sink pad %s:%s",
2819           event, GST_EVENT_TYPE_NAME (event), GST_DEBUG_PAD_NAME (eventpad));
2820       result = gst_pad_push_event (eventpad, event);
2821       goto done;
2822     }
2823   }
2824   /* we handled the incoming event so we unref once */
2825   GST_LOG_OBJECT (pad, "handled event %p, unreffing", event);
2826   gst_event_unref (event);
2827
2828 done:
2829   g_list_free (orig);
2830
2831   return result;
2832 }
2833
2834 /**
2835  * gst_pad_event_default:
2836  * @pad: a #GstPad to call the default event handler on.
2837  * @event: the #GstEvent to handle.
2838  *
2839  * Invokes the default event handler for the given pad. End-of-stream and
2840  * discontinuity events are handled specially, and then the event is sent to all
2841  * pads internally linked to @pad. Note that if there are many possible sink
2842  * pads that are internally linked to @pad, only one will be sent an event.
2843  * Multi-sinkpad elements should implement custom event handlers.
2844  *
2845  * Returns: TRUE if the event was sent succesfully.
2846  */
2847 gboolean
2848 gst_pad_event_default (GstPad * pad, GstEvent * event)
2849 {
2850   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2851   g_return_val_if_fail (event != NULL, FALSE);
2852
2853   switch (GST_EVENT_TYPE (event)) {
2854     case GST_EVENT_EOS:
2855     {
2856       GST_DEBUG_OBJECT (pad, "pausing task because of eos");
2857       gst_pad_pause_task (pad);
2858     }
2859     default:
2860       break;
2861   }
2862
2863   return gst_pad_event_default_dispatch (pad, event);
2864 }
2865
2866 /**
2867  * gst_pad_dispatcher:
2868  * @pad: a #GstPad to dispatch.
2869  * @dispatch: the #GstDispatcherFunction to call.
2870  * @data: gpointer user data passed to the dispatcher function.
2871  *
2872  * Invokes the given dispatcher function on all pads that are
2873  * internally linked to the given pad.
2874  * The GstPadDispatcherFunction should return TRUE when no further pads
2875  * need to be processed.
2876  *
2877  * Returns: TRUE if one of the dispatcher functions returned TRUE.
2878  */
2879 gboolean
2880 gst_pad_dispatcher (GstPad * pad, GstPadDispatcherFunction dispatch,
2881     gpointer data)
2882 {
2883   gboolean res = FALSE;
2884   GList *int_pads, *orig;
2885
2886   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2887   g_return_val_if_fail (dispatch != NULL, FALSE);
2888
2889   orig = int_pads = gst_pad_get_internal_links (pad);
2890
2891   while (int_pads) {
2892     GstPad *int_pad = GST_PAD_CAST (int_pads->data);
2893     GstPad *int_peer = GST_PAD_PEER (int_pad);
2894
2895     if (int_peer) {
2896       res = dispatch (int_peer, data);
2897       if (res)
2898         break;
2899     }
2900     int_pads = g_list_next (int_pads);
2901   }
2902
2903   g_list_free (orig);
2904
2905   return res;
2906 }
2907
2908 /**
2909  * gst_pad_query:
2910  * @pad: a #GstPad to invoke the default query on.
2911  * @query: the #GstQuery to perform.
2912  *
2913  * Dispatches a query to a pad. The query should have been allocated by the
2914  * caller via one of the type-specific allocation functions in gstquery.h. The
2915  * element is responsible for filling the query with an appropriate response,
2916  * which should then be parsed with a type-specific query parsing function.
2917  *
2918  * Again, the caller is responsible for both the allocation and deallocation of
2919  * the query structure.
2920  *
2921  * Returns: TRUE if the query could be performed.
2922  */
2923 gboolean
2924 gst_pad_query (GstPad * pad, GstQuery * query)
2925 {
2926   GstPadQueryFunction func;
2927
2928   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2929   g_return_val_if_fail (GST_IS_QUERY (query), FALSE);
2930
2931   GST_DEBUG ("sending query %p to pad %s:%s", query, GST_DEBUG_PAD_NAME (pad));
2932
2933   if ((func = GST_PAD_QUERYFUNC (pad)) == NULL)
2934     goto no_func;
2935
2936   return func (pad, query);
2937
2938 no_func:
2939   {
2940     GST_DEBUG ("pad had no query function");
2941     return FALSE;
2942   }
2943 }
2944
2945 /**
2946  * gst_pad_query_default:
2947  * @pad: a #GstPad to call the default query handler on.
2948  * @query: the #GstQuery to handle.
2949  *
2950  * Invokes the default query handler for the given pad.
2951  * The query is sent to all pads internally linked to @pad. Note that
2952  * if there are many possible sink pads that are internally linked to
2953  * @pad, only one will be sent the query.
2954  * Multi-sinkpad elements should implement custom query handlers.
2955  *
2956  * Returns: TRUE if the query was performed succesfully.
2957  */
2958 gboolean
2959 gst_pad_query_default (GstPad * pad, GstQuery * query)
2960 {
2961   switch (GST_QUERY_TYPE (query)) {
2962     case GST_QUERY_POSITION:
2963     case GST_QUERY_SEEKING:
2964     case GST_QUERY_FORMATS:
2965     case GST_QUERY_LATENCY:
2966     case GST_QUERY_JITTER:
2967     case GST_QUERY_RATE:
2968     case GST_QUERY_CONVERT:
2969     default:
2970       return gst_pad_dispatcher
2971           (pad, (GstPadDispatcherFunction) gst_pad_query, query);
2972   }
2973 }
2974
2975 #ifndef GST_DISABLE_LOADSAVE
2976 /* FIXME: why isn't this on a GstElement ? */
2977 /**
2978  * gst_pad_load_and_link:
2979  * @self: an #xmlNodePtr to read the description from.
2980  * @parent: the #GstObject element that owns the pad.
2981  *
2982  * Reads the pad definition from the XML node and links the given pad
2983  * in the element to a pad of an element up in the hierarchy.
2984  */
2985 void
2986 gst_pad_load_and_link (xmlNodePtr self, GstObject * parent)
2987 {
2988   xmlNodePtr field = self->xmlChildrenNode;
2989   GstPad *pad = NULL, *targetpad;
2990   gchar *peer = NULL;
2991   gchar **split;
2992   GstElement *target;
2993   GstObject *grandparent;
2994   gchar *name = NULL;
2995
2996   while (field) {
2997     if (!strcmp ((char *) field->name, "name")) {
2998       name = (gchar *) xmlNodeGetContent (field);
2999       pad = gst_element_get_pad (GST_ELEMENT (parent), name);
3000       g_free (name);
3001     } else if (!strcmp ((char *) field->name, "peer")) {
3002       peer = (gchar *) xmlNodeGetContent (field);
3003     }
3004     field = field->next;
3005   }
3006   g_return_if_fail (pad != NULL);
3007
3008   if (peer == NULL)
3009     return;
3010
3011   split = g_strsplit (peer, ".", 2);
3012
3013   if (split[0] == NULL || split[1] == NULL) {
3014     GST_CAT_DEBUG (GST_CAT_XML,
3015         "Could not parse peer '%s' for pad %s:%s, leaving unlinked",
3016         peer, GST_DEBUG_PAD_NAME (pad));
3017
3018     g_free (peer);
3019     return;
3020   }
3021   g_free (peer);
3022
3023   g_return_if_fail (split[0] != NULL);
3024   g_return_if_fail (split[1] != NULL);
3025
3026   grandparent = gst_object_get_parent (parent);
3027
3028   if (grandparent && GST_IS_BIN (grandparent)) {
3029     target = gst_bin_get_by_name_recurse_up (GST_BIN (grandparent), split[0]);
3030   } else
3031     goto cleanup;
3032
3033   if (target == NULL)
3034     goto cleanup;
3035
3036   targetpad = gst_element_get_pad (target, split[1]);
3037
3038   if (targetpad == NULL)
3039     goto cleanup;
3040
3041   gst_pad_link (pad, targetpad);
3042
3043 cleanup:
3044   g_strfreev (split);
3045 }
3046
3047 /**
3048  * gst_pad_save_thyself:
3049  * @pad: a #GstPad to save.
3050  * @parent: the parent #xmlNodePtr to save the description in.
3051  *
3052  * Saves the pad into an xml representation.
3053  *
3054  * Returns: the #xmlNodePtr representation of the pad.
3055  */
3056 static xmlNodePtr
3057 gst_pad_save_thyself (GstObject * object, xmlNodePtr parent)
3058 {
3059   GstPad *pad;
3060   GstPad *peer;
3061
3062   g_return_val_if_fail (GST_IS_PAD (object), NULL);
3063
3064   pad = GST_PAD (object);
3065
3066   xmlNewChild (parent, NULL, (xmlChar *) "name",
3067       (xmlChar *) GST_PAD_NAME (pad));
3068   if (GST_PAD_PEER (pad) != NULL) {
3069     gchar *content;
3070
3071     peer = GST_PAD_PEER (pad);
3072     /* first check to see if the peer's parent's parent is the same */
3073     /* we just save it off */
3074     content = g_strdup_printf ("%s.%s",
3075         GST_OBJECT_NAME (GST_PAD_PARENT (peer)), GST_PAD_NAME (peer));
3076     xmlNewChild (parent, NULL, (xmlChar *) "peer", (xmlChar *) content);
3077     g_free (content);
3078   } else
3079     xmlNewChild (parent, NULL, (xmlChar *) "peer", NULL);
3080
3081   return parent;
3082 }
3083
3084 #if 0
3085 /**
3086  * gst_ghost_pad_save_thyself:
3087  * @pad: a ghost #GstPad to save.
3088  * @parent: the parent #xmlNodePtr to save the description in.
3089  *
3090  * Saves the ghost pad into an xml representation.
3091  *
3092  * Returns: the #xmlNodePtr representation of the pad.
3093  */
3094 xmlNodePtr
3095 gst_ghost_pad_save_thyself (GstPad * pad, xmlNodePtr parent)
3096 {
3097   xmlNodePtr self;
3098
3099   g_return_val_if_fail (GST_IS_GHOST_PAD (pad), NULL);
3100
3101   self = xmlNewChild (parent, NULL, (xmlChar *) "ghostpad", NULL);
3102   xmlNewChild (self, NULL, (xmlChar *) "name", (xmlChar *) GST_PAD_NAME (pad));
3103   xmlNewChild (self, NULL, (xmlChar *) "parent",
3104       (xmlChar *) GST_OBJECT_NAME (GST_PAD_PARENT (pad)));
3105
3106   /* FIXME FIXME FIXME! */
3107
3108   return self;
3109 }
3110 #endif /* 0 */
3111 #endif /* GST_DISABLE_LOADSAVE */
3112
3113 /*
3114  * should be called with pad OBJECT_LOCK and STREAM_LOCK held.
3115  * GST_PAD_IS_BLOCK (pad) == TRUE when this function is
3116  * called.
3117  *
3118  * This function perform the pad blocking when an event, buffer push
3119  * or buffer_alloc is performed on a _SRC_ pad. It blocks the
3120  * streaming thread after informing the pad has been blocked.
3121  *
3122  * An application can with this method wait and block any streaming
3123  * thread and perform operations such as seeking or linking.
3124  *
3125  * Two methods are available for notifying the application of the
3126  * block:
3127  * - the callback method, which happens in the STREAMING thread with
3128  *   the STREAM_LOCK held. With this method, the most usefull way of
3129  *   dealing with the callback is to post a message to the main thread
3130  *   where the pad block can then be handled outside of the streaming
3131  *   thread. With the last method one can perform all operations such
3132  *   as doing a state change, linking, unblocking, seeking etc on the
3133  *   pad.
3134  * - the GCond signal method, which makes any thread unblock when
3135  *   the pad block happens.
3136  *
3137  * MT safe.
3138  */
3139 static GstFlowReturn
3140 handle_pad_block (GstPad * pad)
3141 {
3142   GstPadBlockCallback callback;
3143   gpointer user_data;
3144   GstFlowReturn ret = GST_FLOW_OK;
3145
3146   GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3147       "signal block taken on pad %s:%s", GST_DEBUG_PAD_NAME (pad));
3148
3149   /* flushing, don't bother trying to block and return WRONG_STATE
3150    * right away */
3151   if (GST_PAD_IS_FLUSHING (pad))
3152     goto flushingnonref;
3153
3154   /* we grab an extra ref for the callbacks, this is probably not
3155    * needed (callback code does not have a ref and cannot unref). I
3156    * think this was done to make it possible to unref the element in
3157    * the callback, which is in the end totally impossible as it
3158    * requires grabbing the STREAM_LOCK and OBJECT_LOCK which are
3159    * all taken when calling this function. */
3160   gst_object_ref (pad);
3161
3162   /* we either have a callback installed to notify the block or
3163    * some other thread is doing a GCond wait. */
3164   callback = pad->block_callback;
3165   if (callback) {
3166     /* there is a callback installed, call it. We release the
3167      * lock so that the callback can do something usefull with the
3168      * pad */
3169     user_data = pad->block_data;
3170     GST_OBJECT_UNLOCK (pad);
3171     callback (pad, TRUE, user_data);
3172     GST_OBJECT_LOCK (pad);
3173   } else {
3174     /* no callback, signal the thread that is doing a GCond wait
3175      * if any. */
3176     GST_PAD_BLOCK_SIGNAL (pad);
3177   }
3178
3179   /* OBJECT_LOCK could have been released when we did the callback, which
3180    * then could have made the pad unblock so we need to check the blocking
3181    * condition again.   */
3182   while (GST_PAD_IS_BLOCKED (pad)) {
3183     if (GST_PAD_IS_FLUSHING (pad))
3184       goto flushing;
3185
3186     /* now we block the streaming thread. It can be unlocked when we
3187      * deactivate the pad (which will also set the FLUSHING flag) or
3188      * when the pad is unblocked. A flushing event will also unblock
3189      * the pad after setting the FLUSHING flag. */
3190     GST_PAD_BLOCK_WAIT (pad);
3191
3192     /* see if we got unlocked by a flush or not */
3193     if (GST_PAD_IS_FLUSHING (pad))
3194       goto flushing;
3195   }
3196
3197   GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "got unblocked");
3198
3199   /* when we get here, the pad is unblocked again and we perform
3200    * the needed unblock code. */
3201   callback = pad->block_callback;
3202   if (callback) {
3203     /* we need to call the callback */
3204     user_data = pad->block_data;
3205     GST_OBJECT_UNLOCK (pad);
3206     callback (pad, FALSE, user_data);
3207     GST_OBJECT_LOCK (pad);
3208   } else {
3209     /* we need to signal the thread waiting on the GCond */
3210     GST_PAD_BLOCK_SIGNAL (pad);
3211   }
3212
3213   gst_object_unref (pad);
3214
3215   return ret;
3216
3217 flushingnonref:
3218   {
3219     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3220         "pad %s:%s was flushing", GST_DEBUG_PAD_NAME (pad));
3221     return GST_FLOW_WRONG_STATE;
3222   }
3223 flushing:
3224   {
3225     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3226         "pad %s:%s became flushing", GST_DEBUG_PAD_NAME (pad));
3227     gst_object_unref (pad);
3228     return GST_FLOW_WRONG_STATE;
3229   }
3230 }
3231
3232 /**********************************************************************
3233  * Data passing functions
3234  */
3235
3236 static gboolean
3237 gst_pad_emit_have_data_signal (GstPad * pad, GstMiniObject * obj)
3238 {
3239   GValue ret = { 0 };
3240   GValue args[2] = { {0}, {0} };
3241   gboolean res;
3242   GQuark detail;
3243
3244   /* init */
3245   g_value_init (&ret, G_TYPE_BOOLEAN);
3246   g_value_set_boolean (&ret, TRUE);
3247   g_value_init (&args[0], GST_TYPE_PAD);
3248   g_value_set_object (&args[0], pad);
3249   g_value_init (&args[1], GST_TYPE_MINI_OBJECT);        // G_TYPE_POINTER);
3250   gst_value_set_mini_object (&args[1], obj);
3251
3252   if (GST_IS_EVENT (obj))
3253     detail = event_quark;
3254   else
3255     detail = buffer_quark;
3256
3257   /* actually emit */
3258   g_signal_emitv (args, gst_pad_signals[PAD_HAVE_DATA], detail, &ret);
3259   res = g_value_get_boolean (&ret);
3260
3261   /* clean up */
3262   g_value_unset (&ret);
3263   g_value_unset (&args[0]);
3264   g_value_unset (&args[1]);
3265
3266   return res;
3267 }
3268
3269 /* this is the chain function that does not perform the additional argument
3270  * checking for that little extra speed.
3271  */
3272 static inline GstFlowReturn
3273 gst_pad_chain_unchecked (GstPad * pad, GstBuffer * buffer)
3274 {
3275   GstCaps *caps;
3276   gboolean caps_changed;
3277   GstPadChainFunction chainfunc;
3278   GstFlowReturn ret;
3279   gboolean emit_signal;
3280
3281   GST_PAD_STREAM_LOCK (pad);
3282
3283   GST_OBJECT_LOCK (pad);
3284   if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
3285     goto flushing;
3286
3287   caps = GST_BUFFER_CAPS (buffer);
3288   caps_changed = caps && caps != GST_PAD_CAPS (pad);
3289
3290   emit_signal = GST_PAD_DO_BUFFER_SIGNALS (pad) > 0;
3291   GST_OBJECT_UNLOCK (pad);
3292
3293   /* see if the signal should be emited, we emit before caps nego as
3294    * we might drop the buffer and do capsnego for nothing. */
3295   if (G_UNLIKELY (emit_signal)) {
3296     if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (buffer)))
3297       goto dropping;
3298   }
3299
3300   /* we got a new datatype on the pad, see if it can handle it */
3301   if (G_UNLIKELY (caps_changed)) {
3302     GST_DEBUG_OBJECT (pad, "caps changed to %" GST_PTR_FORMAT, caps);
3303     if (G_UNLIKELY (!gst_pad_configure_sink (pad, caps)))
3304       goto not_negotiated;
3305   }
3306
3307   /* NOTE: we read the chainfunc unlocked.
3308    * we cannot hold the lock for the pad so we might send
3309    * the data to the wrong function. This is not really a
3310    * problem since functions are assigned at creation time
3311    * and don't change that often... */
3312   if (G_UNLIKELY ((chainfunc = GST_PAD_CHAINFUNC (pad)) == NULL))
3313     goto no_function;
3314
3315   GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3316       "calling chainfunction &%s of pad %s:%s",
3317       GST_DEBUG_FUNCPTR_NAME (chainfunc), GST_DEBUG_PAD_NAME (pad));
3318
3319   ret = chainfunc (pad, buffer);
3320
3321   GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3322       "called chainfunction &%s of pad %s:%s, returned %s",
3323       GST_DEBUG_FUNCPTR_NAME (chainfunc), GST_DEBUG_PAD_NAME (pad),
3324       gst_flow_get_name (ret));
3325
3326   GST_PAD_STREAM_UNLOCK (pad);
3327
3328   return ret;
3329
3330   /* ERRORS */
3331 flushing:
3332   {
3333     gst_buffer_unref (buffer);
3334     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3335         "pushing, but pad was flushing");
3336     GST_OBJECT_UNLOCK (pad);
3337     GST_PAD_STREAM_UNLOCK (pad);
3338     return GST_FLOW_WRONG_STATE;
3339   }
3340 dropping:
3341   {
3342     gst_buffer_unref (buffer);
3343     GST_DEBUG_OBJECT (pad, "Dropping buffer due to FALSE probe return");
3344     GST_PAD_STREAM_UNLOCK (pad);
3345     return GST_FLOW_OK;
3346   }
3347 not_negotiated:
3348   {
3349     gst_buffer_unref (buffer);
3350     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3351         "pushing buffer but pad did not accept");
3352     GST_PAD_STREAM_UNLOCK (pad);
3353     return GST_FLOW_NOT_NEGOTIATED;
3354   }
3355 no_function:
3356   {
3357     gst_buffer_unref (buffer);
3358     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3359         "pushing, but not chainhandler");
3360     GST_ELEMENT_ERROR (GST_PAD_PARENT (pad), CORE, PAD, (NULL),
3361         ("push on pad %s:%s but it has no chainfunction",
3362             GST_DEBUG_PAD_NAME (pad)));
3363     GST_PAD_STREAM_UNLOCK (pad);
3364     return GST_FLOW_NOT_SUPPORTED;
3365   }
3366 }
3367
3368 /**
3369  * gst_pad_chain:
3370  * @pad: a sink #GstPad, returns GST_FLOW_ERROR if not.
3371  * @buffer: the #GstBuffer to send, return GST_FLOW_ERROR if not.
3372  *
3373  * Chain a buffer to @pad.
3374  *
3375  * The function returns #GST_FLOW_WRONG_STATE if the pad was flushing.
3376  *
3377  * If the caps on @buffer are different from the current caps on @pad, this
3378  * function will call any setcaps function (see gst_pad_set_setcaps_function())
3379  * installed on @pad. If the new caps are not acceptable for @pad, this function
3380  * returns #GST_FLOW_NOT_NEGOTIATED.
3381  *
3382  * The function proceeds calling the chain function installed on @pad (see
3383  * gst_pad_set_chain_function()) and the return value of that function is
3384  * returned to the caller. #GST_FLOW_NOT_SUPPORTED is returned if @pad has no
3385  * chain function.
3386  *
3387  * In all cases, success or failure, the caller loses its reference to @buffer
3388  * after calling this function.
3389  *
3390  * Returns: a #GstFlowReturn from the pad.
3391  *
3392  * MT safe.
3393  */
3394 GstFlowReturn
3395 gst_pad_chain (GstPad * pad, GstBuffer * buffer)
3396 {
3397   g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
3398   g_return_val_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SINK,
3399       GST_FLOW_ERROR);
3400   g_return_val_if_fail (GST_IS_BUFFER (buffer), GST_FLOW_ERROR);
3401
3402   return gst_pad_chain_unchecked (pad, buffer);
3403 }
3404
3405 /**
3406  * gst_pad_push:
3407  * @pad: a source #GstPad, returns #GST_FLOW_ERROR if not.
3408  * @buffer: the #GstBuffer to push returns GST_FLOW_ERROR if not.
3409  *
3410  * Pushes a buffer to the peer of @pad.
3411  *
3412  * This function will call an installed pad block before triggering any
3413  * installed pad probes.
3414  *
3415  * If the caps on @buffer are different from the currently configured caps on
3416  * @pad, this function will call any installed setcaps function on @pad (see
3417  * gst_pad_set_setcaps_function()). In case of failure to renegotiate the new
3418  * format, this function returns #GST_FLOW_NOT_NEGOTIATED.
3419  *
3420  * The function proceeds calling gst_pad_chain() on the peer pad and returns the
3421  * value from that function. If @pad has no peer, #GST_FLOW_NOT_LINKED will be
3422  * returned.
3423  *
3424  * In all cases, success or failure, the caller loses its reference to @buffer
3425  * after calling this function.
3426  *
3427  * Returns: a #GstFlowReturn from the peer pad.
3428  *
3429  * MT safe.
3430  */
3431 GstFlowReturn
3432 gst_pad_push (GstPad * pad, GstBuffer * buffer)
3433 {
3434   GstPad *peer;
3435   GstFlowReturn ret;
3436
3437   GstCaps *caps;
3438   gboolean caps_changed;
3439
3440   g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
3441   g_return_val_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SRC, GST_FLOW_ERROR);
3442   g_return_val_if_fail (GST_IS_BUFFER (buffer), GST_FLOW_ERROR);
3443
3444   GST_OBJECT_LOCK (pad);
3445
3446   /* FIXME: this check can go away; pad_set_blocked could be implemented with
3447    * probes completely or probes with an extended pad block. */
3448   while (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad)))
3449     if ((ret = handle_pad_block (pad)) != GST_FLOW_OK)
3450       goto flushed;
3451
3452   /* we emit signals on the pad arg, the peer will have a chance to
3453    * emit in the _chain() function */
3454   if (G_UNLIKELY (GST_PAD_DO_BUFFER_SIGNALS (pad) > 0)) {
3455     /* unlock before emitting */
3456     GST_OBJECT_UNLOCK (pad);
3457
3458     /* if the signal handler returned FALSE, it means we should just drop the
3459      * buffer */
3460     if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (buffer)))
3461       goto dropped;
3462
3463     GST_OBJECT_LOCK (pad);
3464   }
3465
3466   if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
3467     goto not_linked;
3468
3469   /* take ref to peer pad before releasing the lock */
3470   gst_object_ref (peer);
3471
3472   /* Before pushing the buffer to the peer pad, ensure that caps
3473    * are set on this pad */
3474   caps = GST_BUFFER_CAPS (buffer);
3475   caps_changed = caps && caps != GST_PAD_CAPS (pad);
3476
3477   GST_OBJECT_UNLOCK (pad);
3478
3479   /* we got a new datatype from the pad, it had better handle it */
3480   if (G_UNLIKELY (caps_changed)) {
3481     GST_DEBUG_OBJECT (pad, "caps changed to %" GST_PTR_FORMAT, caps);
3482     if (G_UNLIKELY (!gst_pad_configure_src (pad, caps, TRUE)))
3483       goto not_negotiated;
3484   }
3485
3486   ret = gst_pad_chain_unchecked (peer, buffer);
3487
3488   gst_object_unref (peer);
3489
3490   return ret;
3491
3492   /* ERROR recovery here */
3493 flushed:
3494   {
3495     gst_buffer_unref (buffer);
3496     GST_DEBUG_OBJECT (pad, "pad block stopped by flush");
3497     GST_OBJECT_UNLOCK (pad);
3498     return ret;
3499   }
3500 dropped:
3501   {
3502     gst_buffer_unref (buffer);
3503     GST_DEBUG_OBJECT (pad, "Dropping buffer due to FALSE probe return");
3504     return GST_FLOW_OK;
3505   }
3506 not_linked:
3507   {
3508     gst_buffer_unref (buffer);
3509     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3510         "pushing, but it was not linked");
3511     GST_OBJECT_UNLOCK (pad);
3512     return GST_FLOW_NOT_LINKED;
3513   }
3514 not_negotiated:
3515   {
3516     gst_buffer_unref (buffer);
3517     gst_object_unref (peer);
3518     GST_CAT_DEBUG_OBJECT (GST_CAT_SCHEDULING, pad,
3519         "element pushed buffer then refused to accept the caps");
3520     return GST_FLOW_NOT_NEGOTIATED;
3521   }
3522 }
3523
3524 /**
3525  * gst_pad_check_pull_range:
3526  * @pad: a sink #GstPad.
3527  *
3528  * Checks if a gst_pad_pull_range() can be performed on the peer
3529  * source pad. This function is used by plugins that want to check
3530  * if they can use random access on the peer source pad.
3531  *
3532  * The peer sourcepad can implement a custom #GstPadCheckGetRangeFunction
3533  * if it needs to perform some logic to determine if pull_range is
3534  * possible.
3535  *
3536  * Returns: a gboolean with the result.
3537  *
3538  * MT safe.
3539  */
3540 gboolean
3541 gst_pad_check_pull_range (GstPad * pad)
3542 {
3543   GstPad *peer;
3544   gboolean ret;
3545   GstPadCheckGetRangeFunction checkgetrangefunc;
3546
3547   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3548
3549   GST_OBJECT_LOCK (pad);
3550   if (GST_PAD_DIRECTION (pad) != GST_PAD_SINK)
3551     goto wrong_direction;
3552
3553   if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
3554     goto not_connected;
3555
3556   gst_object_ref (peer);
3557   GST_OBJECT_UNLOCK (pad);
3558
3559   /* see note in above function */
3560   if (G_LIKELY ((checkgetrangefunc = peer->checkgetrangefunc) == NULL)) {
3561     /* FIXME, kindoff ghetto */
3562     ret = GST_PAD_GETRANGEFUNC (peer) != NULL;
3563   } else {
3564     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3565         "calling checkgetrangefunc %s of peer pad %s:%s",
3566         GST_DEBUG_FUNCPTR_NAME (checkgetrangefunc), GST_DEBUG_PAD_NAME (peer));
3567
3568     ret = checkgetrangefunc (peer);
3569   }
3570
3571   gst_object_unref (peer);
3572
3573   return ret;
3574
3575   /* ERROR recovery here */
3576 wrong_direction:
3577   {
3578     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3579         "checking pull range, but pad must be a sinkpad");
3580     GST_OBJECT_UNLOCK (pad);
3581     return FALSE;
3582   }
3583 not_connected:
3584   {
3585     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3586         "checking pull range, but it was not linked");
3587     GST_OBJECT_UNLOCK (pad);
3588     return FALSE;
3589   }
3590 }
3591
3592 /**
3593  * gst_pad_get_range:
3594  * @pad: a src #GstPad, returns #GST_FLOW_ERROR if not.
3595  * @offset: The start offset of the buffer
3596  * @size: The length of the buffer
3597  * @buffer: a pointer to hold the #GstBuffer, returns #GST_FLOW_ERROR if %NULL.
3598  *
3599  * When @pad is flushing this function returns #GST_FLOW_WRONG_STATE
3600  * immediatly.
3601  *
3602  * Calls the getrange function of @pad, see #GstPadGetRangeFunction for a
3603  * description of a getrange function. If @pad has no getrange function
3604  * installed (see gst_pad_set_getrange_function()) this function returns
3605  * #GST_FLOW_NOT_SUPPORTED.
3606  *
3607  * Returns: a #GstFlowReturn from the pad.
3608  *
3609  * MT safe.
3610  */
3611 GstFlowReturn
3612 gst_pad_get_range (GstPad * pad, guint64 offset, guint size,
3613     GstBuffer ** buffer)
3614 {
3615   GstFlowReturn ret;
3616   GstPadGetRangeFunction getrangefunc;
3617   gboolean emit_signal;
3618
3619   g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
3620   g_return_val_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SRC, GST_FLOW_ERROR);
3621   g_return_val_if_fail (buffer != NULL, GST_FLOW_ERROR);
3622
3623   GST_PAD_STREAM_LOCK (pad);
3624
3625   GST_OBJECT_LOCK (pad);
3626   if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
3627     goto flushing;
3628
3629   emit_signal = GST_PAD_DO_BUFFER_SIGNALS (pad) > 0;
3630   GST_OBJECT_UNLOCK (pad);
3631
3632   if (G_UNLIKELY ((getrangefunc = GST_PAD_GETRANGEFUNC (pad)) == NULL))
3633     goto no_function;
3634
3635   GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3636       "calling getrangefunc %s of peer pad %s:%s, offset %"
3637       G_GUINT64_FORMAT ", size %u",
3638       GST_DEBUG_FUNCPTR_NAME (getrangefunc), GST_DEBUG_PAD_NAME (pad),
3639       offset, size);
3640
3641   ret = getrangefunc (pad, offset, size, buffer);
3642
3643   /* can only fire the signal if we have a valid buffer */
3644   if (G_UNLIKELY (emit_signal) && (ret == GST_FLOW_OK)) {
3645     if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (*buffer)))
3646       goto dropping;
3647   }
3648
3649   GST_PAD_STREAM_UNLOCK (pad);
3650
3651   return ret;
3652
3653   /* ERRORS */
3654 flushing:
3655   {
3656     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3657         "pulling range, but pad was flushing");
3658     GST_OBJECT_UNLOCK (pad);
3659     GST_PAD_STREAM_UNLOCK (pad);
3660     return GST_FLOW_WRONG_STATE;
3661   }
3662 no_function:
3663   {
3664     GST_ELEMENT_ERROR (GST_PAD_PARENT (pad), CORE, PAD, (NULL),
3665         ("pullrange on pad %s:%s but it has no getrangefunction",
3666             GST_DEBUG_PAD_NAME (pad)));
3667     GST_PAD_STREAM_UNLOCK (pad);
3668     return GST_FLOW_NOT_SUPPORTED;
3669   }
3670 dropping:
3671   {
3672     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3673         "Dropping data after FALSE probe return");
3674     GST_PAD_STREAM_UNLOCK (pad);
3675     gst_buffer_unref (*buffer);
3676     *buffer = NULL;
3677     return GST_FLOW_UNEXPECTED;
3678   }
3679 }
3680
3681
3682 /**
3683  * gst_pad_pull_range:
3684  * @pad: a sink #GstPad, returns GST_FLOW_ERROR if not.
3685  * @offset: The start offset of the buffer
3686  * @size: The length of the buffer
3687  * @buffer: a pointer to hold the #GstBuffer, returns GST_FLOW_ERROR if %NULL.
3688  *
3689  * Pulls a buffer from the peer pad.
3690  *
3691  * This function will first trigger the pad block signal if it was
3692  * installed.
3693  *
3694  * When @pad is not linked #GST_FLOW_NOT_LINKED is returned else this
3695  * function returns the result of gst_pad_get_range() on the peer pad.
3696  * See gst_pad_get_range() for a list of return values and for the
3697  * semantics of the arguments of this function.
3698  *
3699  * Returns: a #GstFlowReturn from the peer pad.
3700  * When this function returns #GST_FLOW_OK, @buffer will contain a valid
3701  * #GstBuffer that should be freed with gst_buffer_unref() after usage.
3702  * @buffer may not be used or freed when any other return value than
3703  * #GST_FLOW_OK is returned.
3704  *
3705  * MT safe.
3706  */
3707 GstFlowReturn
3708 gst_pad_pull_range (GstPad * pad, guint64 offset, guint size,
3709     GstBuffer ** buffer)
3710 {
3711   GstPad *peer;
3712   GstFlowReturn ret;
3713   gboolean emit_signal;
3714
3715   g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
3716   g_return_val_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SINK,
3717       GST_FLOW_ERROR);
3718   g_return_val_if_fail (buffer != NULL, GST_FLOW_ERROR);
3719
3720   GST_OBJECT_LOCK (pad);
3721
3722   while (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad)))
3723     handle_pad_block (pad);
3724
3725   if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
3726     goto not_connected;
3727
3728   /* signal emision for the pad, peer has chance to emit when
3729    * we call _get_range() */
3730   emit_signal = GST_PAD_DO_BUFFER_SIGNALS (pad) > 0;
3731
3732   gst_object_ref (peer);
3733   GST_OBJECT_UNLOCK (pad);
3734
3735   ret = gst_pad_get_range (peer, offset, size, buffer);
3736
3737   gst_object_unref (peer);
3738
3739   /* can only fire the signal if we have a valid buffer */
3740   if (G_UNLIKELY (emit_signal) && (ret == GST_FLOW_OK)) {
3741     if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (*buffer)))
3742       goto dropping;
3743   }
3744   return ret;
3745
3746   /* ERROR recovery here */
3747 not_connected:
3748   {
3749     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3750         "pulling range, but it was not linked");
3751     GST_OBJECT_UNLOCK (pad);
3752     return GST_FLOW_NOT_LINKED;
3753   }
3754 dropping:
3755   {
3756     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3757         "Dropping data after FALSE probe return");
3758     gst_buffer_unref (*buffer);
3759     *buffer = NULL;
3760     return GST_FLOW_UNEXPECTED;
3761   }
3762 }
3763
3764 /**
3765  * gst_pad_push_event:
3766  * @pad: a #GstPad to push the event to.
3767  * @event: the #GstEvent to send to the pad.
3768  *
3769  * Sends the event to the peer of the given pad. This function is
3770  * mainly used by elements to send events to their peer
3771  * elements.
3772  *
3773  * This function takes owership of the provided event so you should
3774  * gst_event_ref() it if you want to reuse the event after this call.
3775  *
3776  * Returns: TRUE if the event was handled.
3777  *
3778  * MT safe.
3779  */
3780 gboolean
3781 gst_pad_push_event (GstPad * pad, GstEvent * event)
3782 {
3783   GstPad *peerpad;
3784   gboolean result;
3785
3786   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3787   g_return_val_if_fail (event != NULL, FALSE);
3788   g_return_val_if_fail (GST_IS_EVENT (event), FALSE);
3789
3790   GST_LOG_OBJECT (pad, "event:%s", GST_EVENT_TYPE_NAME (event));
3791
3792   GST_OBJECT_LOCK (pad);
3793
3794   /* Two checks to be made:
3795    * . (un)set the FLUSHING flag for flushing events,
3796    * . handle pad blocking */
3797   switch (GST_EVENT_TYPE (event)) {
3798     case GST_EVENT_FLUSH_START:
3799       GST_PAD_SET_FLUSHING (pad);
3800
3801       if (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad))) {
3802         /* flush start will have set the FLUSHING flag and will then
3803          * unlock all threads doing a GCond wait on the blocked pad. This
3804          * will typically unblock the STREAMING thread blocked on a pad. */
3805         GST_PAD_BLOCK_SIGNAL (pad);
3806         goto flushed;
3807       }
3808       break;
3809     case GST_EVENT_FLUSH_STOP:
3810       GST_PAD_UNSET_FLUSHING (pad);
3811
3812       if (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad)))
3813         goto flushed;
3814       break;
3815     default:
3816       if (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad))) {
3817         if (GST_PAD_IS_FLUSHING (pad))
3818           goto flushed;
3819         while (GST_PAD_IS_BLOCKED (pad))
3820           /* else block the event as long as the pad is blocked */
3821           if (handle_pad_block (pad) != GST_FLOW_OK)
3822             goto flushed;
3823       }
3824       break;
3825   }
3826
3827   if (G_UNLIKELY (GST_PAD_DO_EVENT_SIGNALS (pad) > 0)) {
3828     GST_OBJECT_UNLOCK (pad);
3829
3830     if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (event)))
3831       goto dropping;
3832
3833     GST_OBJECT_LOCK (pad);
3834   }
3835   peerpad = GST_PAD_PEER (pad);
3836   if (peerpad == NULL)
3837     goto not_linked;
3838
3839   GST_LOG_OBJECT (peerpad, "sending event on peerpad");
3840   gst_object_ref (peerpad);
3841   GST_OBJECT_UNLOCK (pad);
3842
3843   result = gst_pad_send_event (peerpad, event);
3844
3845   gst_object_unref (peerpad);
3846   GST_LOG_OBJECT (peerpad, "sent event on peerpad");
3847
3848   return result;
3849
3850   /* ERROR handling */
3851 dropping:
3852   {
3853     GST_DEBUG_OBJECT (pad, "Dropping event after FALSE probe return");
3854     gst_event_unref (event);
3855     return FALSE;
3856   }
3857 not_linked:
3858   {
3859     GST_DEBUG_OBJECT (pad, "Dropping event because pad is not linked");
3860     gst_event_unref (event);
3861     GST_OBJECT_UNLOCK (pad);
3862     return FALSE;
3863   }
3864
3865 flushed:
3866   {
3867     GST_DEBUG_OBJECT (pad,
3868         "Not forwarding event since we're flushing and blocking");
3869     gst_event_unref (event);
3870     GST_OBJECT_UNLOCK (pad);
3871     return TRUE;
3872   }
3873 }
3874
3875 /**
3876  * gst_pad_send_event:
3877  * @pad: a #GstPad to send the event to.
3878  * @event: the #GstEvent to send to the pad.
3879  *
3880  * Sends the event to the pad. This function can be used
3881  * by applications to send events in the pipeline.
3882  *
3883  * If @pad is a source pad, @event should be an upstream event. If @pad is a
3884  * sink pad, @event should be a downstream event. For example, you would not
3885  * send a #GST_EVENT_EOS on a src pad; EOS events only propagate downstream.
3886  * Furthermore, some downstream events have to be serialized with data flow,
3887  * like EOS, while some can travel out-of-band, like #GST_EVENT_FLUSH_START. If
3888  * the event needs to be serialized with data flow, this function will take the
3889  * pad's stream lock while calling its event function.
3890  *
3891  * To find out whether an event type is upstream, downstream, or downstream and
3892  * serialized, see #GstEventTypeFlags, gst_event_type_get_flags(),
3893  * #GST_EVENT_IS_UPSTREAM, #GST_EVENT_IS_DOWNSTREAM, and
3894  * #GST_EVENT_IS_SERIALIZED. Note that in practice that an application or plugin
3895  * doesn't need to bother itself with this information; the core handles all
3896  * necessary locks and checks.
3897  *
3898  * This function takes owership of the provided event so you should
3899  * gst_event_ref() it if you want to reuse the event after this call.
3900  *
3901  * Returns: TRUE if the event was handled.
3902  */
3903 gboolean
3904 gst_pad_send_event (GstPad * pad, GstEvent * event)
3905 {
3906   gboolean result = FALSE;
3907   GstPadEventFunction eventfunc;
3908   gboolean serialized, need_unlock = FALSE;
3909
3910   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3911   g_return_val_if_fail (event != NULL, FALSE);
3912
3913   GST_OBJECT_LOCK (pad);
3914   if (GST_PAD_IS_SINK (pad)) {
3915     if (G_UNLIKELY (!GST_EVENT_IS_DOWNSTREAM (event)))
3916       goto wrong_direction;
3917     serialized = GST_EVENT_IS_SERIALIZED (event);
3918   } else if (GST_PAD_IS_SRC (pad)) {
3919     if (G_UNLIKELY (!GST_EVENT_IS_UPSTREAM (event)))
3920       goto wrong_direction;
3921     /* events on srcpad never are serialized */
3922     serialized = FALSE;
3923   } else
3924     goto unknown_direction;
3925
3926   if (G_UNLIKELY (GST_EVENT_SRC (event) == NULL)) {
3927     GST_LOG_OBJECT (pad, "event had no source, setting pad as event source");
3928     GST_EVENT_SRC (event) = gst_object_ref (pad);
3929   }
3930
3931   /* pad signals */
3932   if (G_UNLIKELY (GST_PAD_DO_EVENT_SIGNALS (pad) > 0)) {
3933     GST_OBJECT_UNLOCK (pad);
3934
3935     if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT_CAST (event)))
3936       goto dropping;
3937
3938     GST_OBJECT_LOCK (pad);
3939   }
3940
3941   switch (GST_EVENT_TYPE (event)) {
3942     case GST_EVENT_FLUSH_START:
3943       GST_CAT_DEBUG (GST_CAT_EVENT,
3944           "have event type %d (FLUSH_START) on pad %s:%s",
3945           GST_EVENT_TYPE (event), GST_DEBUG_PAD_NAME (pad));
3946
3947       /* can't even accept a flush begin event when flushing */
3948       if (GST_PAD_IS_FLUSHING (pad))
3949         goto flushing;
3950       GST_PAD_SET_FLUSHING (pad);
3951       GST_CAT_DEBUG (GST_CAT_EVENT, "set flush flag");
3952       break;
3953     case GST_EVENT_FLUSH_STOP:
3954       GST_PAD_UNSET_FLUSHING (pad);
3955       GST_CAT_DEBUG (GST_CAT_EVENT, "cleared flush flag");
3956       GST_OBJECT_UNLOCK (pad);
3957       /* grab stream lock */
3958       GST_PAD_STREAM_LOCK (pad);
3959       need_unlock = TRUE;
3960       GST_OBJECT_LOCK (pad);
3961       break;
3962     default:
3963       GST_CAT_DEBUG (GST_CAT_EVENT, "have event type %s on pad %s:%s",
3964           GST_EVENT_TYPE_NAME (event), GST_DEBUG_PAD_NAME (pad));
3965
3966       /* make this a little faster, no point in grabbing the lock
3967        * if the pad is allready flushing. */
3968       if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
3969         goto flushing;
3970
3971       if (serialized) {
3972         /* lock order: STREAM_LOCK, LOCK */
3973         GST_OBJECT_UNLOCK (pad);
3974         GST_PAD_STREAM_LOCK (pad);
3975         need_unlock = TRUE;
3976         GST_OBJECT_LOCK (pad);
3977         if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
3978           goto flushing;
3979       }
3980       break;
3981   }
3982   if (G_UNLIKELY ((eventfunc = GST_PAD_EVENTFUNC (pad)) == NULL))
3983     goto no_function;
3984
3985   GST_OBJECT_UNLOCK (pad);
3986
3987   result = eventfunc (pad, event);
3988
3989   if (need_unlock)
3990     GST_PAD_STREAM_UNLOCK (pad);
3991
3992   return result;
3993
3994   /* ERROR handling */
3995 wrong_direction:
3996   {
3997     g_warning ("pad %s:%s sending %s event in wrong direction",
3998         GST_DEBUG_PAD_NAME (pad), GST_EVENT_TYPE_NAME (event));
3999     GST_OBJECT_UNLOCK (pad);
4000     gst_event_unref (event);
4001     return FALSE;
4002   }
4003 unknown_direction:
4004   {
4005     g_warning ("pad %s:%s has invalid direction", GST_DEBUG_PAD_NAME (pad));
4006     GST_OBJECT_UNLOCK (pad);
4007     gst_event_unref (event);
4008     return FALSE;
4009   }
4010 no_function:
4011   {
4012     g_warning ("pad %s:%s has no event handler, file a bug.",
4013         GST_DEBUG_PAD_NAME (pad));
4014     GST_OBJECT_UNLOCK (pad);
4015     gst_event_unref (event);
4016     return FALSE;
4017   }
4018 flushing:
4019   {
4020     GST_OBJECT_UNLOCK (pad);
4021     if (need_unlock)
4022       GST_PAD_STREAM_UNLOCK (pad);
4023     GST_CAT_INFO (GST_CAT_EVENT, "Received event on flushing pad. Discarding");
4024     gst_event_unref (event);
4025     return FALSE;
4026   }
4027 dropping:
4028   {
4029     GST_DEBUG ("Dropping event after FALSE probe return");
4030     gst_event_unref (event);
4031     return FALSE;
4032   }
4033 }
4034
4035 /**
4036  * gst_pad_set_element_private:
4037  * @pad: the #GstPad to set the private data of.
4038  * @priv: The private data to attach to the pad.
4039  *
4040  * Set the given private data gpointer on the pad.
4041  * This function can only be used by the element that owns the pad.
4042  * No locking is performed in this function.
4043  */
4044 void
4045 gst_pad_set_element_private (GstPad * pad, gpointer priv)
4046 {
4047   pad->element_private = priv;
4048 }
4049
4050 /**
4051  * gst_pad_get_element_private:
4052  * @pad: the #GstPad to get the private data of.
4053  *
4054  * Gets the private data of a pad.
4055  * No locking is performed in this function.
4056  *
4057  * Returns: a #gpointer to the private data.
4058  */
4059 gpointer
4060 gst_pad_get_element_private (GstPad * pad)
4061 {
4062   return pad->element_private;
4063 }
4064
4065 /**
4066  * gst_pad_start_task:
4067  * @pad: the #GstPad to start the task of
4068  * @func: the task function to call
4069  * @data: data passed to the task function
4070  *
4071  * Starts a task that repeadedly calls @func with @data. This function
4072  * is nostly used in the pad activation function to start the
4073  * dataflow. This function will automatically acquire the STREAM_LOCK of
4074  * the pad before calling @func.
4075  *
4076  * Returns: a TRUE if the task could be started.
4077  */
4078 gboolean
4079 gst_pad_start_task (GstPad * pad, GstTaskFunction func, gpointer data)
4080 {
4081   GstTask *task;
4082
4083   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
4084   g_return_val_if_fail (func != NULL, FALSE);
4085
4086   GST_OBJECT_LOCK (pad);
4087   task = GST_PAD_TASK (pad);
4088   if (task == NULL) {
4089     task = gst_task_create (func, data);
4090     gst_task_set_lock (task, GST_PAD_GET_STREAM_LOCK (pad));
4091     GST_PAD_TASK (pad) = task;
4092   }
4093   gst_task_start (task);
4094   GST_OBJECT_UNLOCK (pad);
4095
4096   return TRUE;
4097 }
4098
4099 /**
4100  * gst_pad_pause_task:
4101  * @pad: the #GstPad to pause the task of
4102  *
4103  * Pause the task of @pad. This function will also make sure that the
4104  * function executed by the task will effectively stop.
4105  *
4106  * Returns: a TRUE if the task could be paused or FALSE when the pad
4107  * has no task.
4108  */
4109 gboolean
4110 gst_pad_pause_task (GstPad * pad)
4111 {
4112   GstTask *task;
4113
4114   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
4115
4116   GST_OBJECT_LOCK (pad);
4117   task = GST_PAD_TASK (pad);
4118   if (task == NULL)
4119     goto no_task;
4120   gst_task_pause (task);
4121   GST_OBJECT_UNLOCK (pad);
4122
4123   GST_PAD_STREAM_LOCK (pad);
4124   GST_PAD_STREAM_UNLOCK (pad);
4125
4126   return TRUE;
4127
4128 no_task:
4129   {
4130     GST_DEBUG_OBJECT (pad, "pad has no task");
4131     GST_OBJECT_UNLOCK (pad);
4132     return FALSE;
4133   }
4134 }
4135
4136 /**
4137  * gst_pad_stop_task:
4138  * @pad: the #GstPad to stop the task of
4139  *
4140  * Stop the task of @pad. This function will also make sure that the
4141  * function executed by the task will effectively stop if not called
4142  * from the GstTaskFunction.
4143  *
4144  * This function will deadlock if called from the GstTaskFunction of
4145  * the task. Use gst_task_pause() instead.
4146  *
4147  * Regardless of whether the pad has a task, the stream lock is acquired and
4148  * released so as to ensure that streaming through this pad has finished.
4149  *
4150  * Returns: a TRUE if the task could be stopped or FALSE on error.
4151  */
4152 gboolean
4153 gst_pad_stop_task (GstPad * pad)
4154 {
4155   GstTask *task;
4156
4157   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
4158
4159   GST_OBJECT_LOCK (pad);
4160   task = GST_PAD_TASK (pad);
4161   if (task == NULL)
4162     goto no_task;
4163   GST_PAD_TASK (pad) = NULL;
4164   gst_task_stop (task);
4165   GST_OBJECT_UNLOCK (pad);
4166
4167   GST_PAD_STREAM_LOCK (pad);
4168   GST_PAD_STREAM_UNLOCK (pad);
4169
4170   gst_task_join (task);
4171
4172   gst_object_unref (task);
4173
4174   return TRUE;
4175
4176 no_task:
4177   {
4178     GST_OBJECT_UNLOCK (pad);
4179
4180     GST_PAD_STREAM_LOCK (pad);
4181     GST_PAD_STREAM_UNLOCK (pad);
4182
4183     return TRUE;
4184   }
4185 }